Add OpenAPI docs, frontend, migrations, and API updates
- OpenAPI: add missing endpoints (add-from-url, subscriptions, public availability) - OpenAPI: CalendarSubscription schema, Subscriptions tag - Frontend app - Migrations: count_for_availability, subscriptions_sync, user_preferences, calendar_settings - Config, rate limit, auth, calendar, booking, ICS, availability, user service updates Made-with: Cursor
This commit is contained in:
Michilis
@@ -1,5 +1,73 @@
|
||||
{
|
||||
"paths": {
|
||||
"/availability/aggregate": {
|
||||
"get": {
|
||||
"tags": ["Availability"],
|
||||
"summary": "Get aggregate availability (public)",
|
||||
"description": "Returns merged busy time blocks across multiple calendars by their public tokens. No authentication required.",
|
||||
"operationId": "getAvailabilityAggregate",
|
||||
"parameters": [
|
||||
{ "name": "tokens", "in": "query", "required": true, "schema": { "type": "string", "description": "Comma-separated calendar tokens from ical_url" }, "description": "Calendar tokens" },
|
||||
{ "name": "start", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Range start (RFC3339)" },
|
||||
{ "name": "end", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Range end (RFC3339)" }
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Aggregate busy blocks",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": ["range_start", "range_end", "busy"],
|
||||
"properties": {
|
||||
"range_start": { "type": "string", "format": "date-time" },
|
||||
"range_end": { "type": "string", "format": "date-time" },
|
||||
"busy": { "type": "array", "items": { "$ref": "#/components/schemas/BusyBlock" } }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
||||
},
|
||||
"security": []
|
||||
}
|
||||
},
|
||||
"/availability/{token}": {
|
||||
"get": {
|
||||
"tags": ["Availability"],
|
||||
"summary": "Get availability by token (public)",
|
||||
"description": "Returns busy time blocks for a calendar by its public token. No authentication required.",
|
||||
"operationId": "getAvailabilityByToken",
|
||||
"parameters": [
|
||||
{ "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Calendar token from ical_url" },
|
||||
{ "name": "start", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Range start (RFC3339)" },
|
||||
{ "name": "end", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Range end (RFC3339)" }
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Busy blocks for the calendar",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": ["calendar_id", "range_start", "range_end", "busy"],
|
||||
"properties": {
|
||||
"calendar_id": { "type": "string", "format": "uuid" },
|
||||
"range_start": { "type": "string", "format": "date-time" },
|
||||
"range_end": { "type": "string", "format": "date-time" },
|
||||
"busy": { "type": "array", "items": { "$ref": "#/components/schemas/BusyBlock" } }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
||||
"404": { "description": "Calendar not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
||||
},
|
||||
"security": []
|
||||
}
|
||||
},
|
||||
"/availability": {
|
||||
"get": {
|
||||
"tags": ["Availability"],
|
||||
|
||||
@@ -32,7 +32,8 @@
|
||||
{ "name": "Contacts", "description": "Contact management" },
|
||||
{ "name": "Availability", "description": "Calendar availability queries" },
|
||||
{ "name": "Booking", "description": "Public booking links and reservations" },
|
||||
{ "name": "ICS", "description": "ICS calendar import and export" }
|
||||
{ "name": "ICS", "description": "ICS calendar import and export" },
|
||||
{ "name": "Subscriptions", "description": "Calendar subscriptions (external iCal feeds)" }
|
||||
],
|
||||
"security": [
|
||||
{ "BearerAuth": [] },
|
||||
|
||||
@@ -1,5 +1,51 @@
|
||||
{
|
||||
"paths": {
|
||||
"/calendars/add-from-url": {
|
||||
"post": {
|
||||
"tags": ["ICS"],
|
||||
"summary": "Add calendar from iCal URL",
|
||||
"description": "Creates a new calendar, fetches the iCal feed from the given URL, imports all events, and creates a subscription for future syncs. One-step flow for adding external calendars. Requires calendars:write scope.",
|
||||
"operationId": "addCalendarFromURL",
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": ["url"],
|
||||
"properties": {
|
||||
"url": { "type": "string", "format": "uri", "description": "iCal feed URL (http, https, or webcal)", "example": "https://example.com/calendar.ics" },
|
||||
"name": { "type": "string", "description": "Optional calendar name", "example": "Work" },
|
||||
"color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "example": "#3B82F6" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Calendar created and events imported",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": ["ok", "calendar", "imported", "source"],
|
||||
"properties": {
|
||||
"ok": { "type": "boolean", "example": true },
|
||||
"calendar": { "$ref": "#/components/schemas/Calendar" },
|
||||
"imported": { "type": "object", "properties": { "events": { "type": "integer", "example": 12 } } },
|
||||
"source": { "type": "string", "format": "uri", "description": "The URL that was imported" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": { "description": "Validation error, unreachable URL, or invalid ICS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
||||
"401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
||||
"403": { "description": "Insufficient scope or permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
||||
}
|
||||
}
|
||||
},
|
||||
"/calendars/{id}/export.ics": {
|
||||
"get": {
|
||||
"tags": ["ICS"],
|
||||
@@ -130,16 +176,16 @@
|
||||
"/cal/{token}/feed.ics": {
|
||||
"get": {
|
||||
"tags": ["ICS"],
|
||||
"summary": "Public iCal feed",
|
||||
"description": "Returns a public iCal feed for a calendar that has been marked as public. No authentication required. This URL can be used to subscribe to the calendar in Google Calendar, Apple Calendar, Outlook, etc. The `ical_url` is returned in the Calendar object when `is_public` is true.",
|
||||
"operationId": "publicCalendarFeed",
|
||||
"summary": "iCal feed",
|
||||
"description": "Returns an iCal feed for a calendar. Works for both public and private calendars. No authentication required. Public calendars use a shorter base64url token; private calendars use a 64-character SHA256 hex token. The `ical_url` is returned in the Calendar object. Subscribe in Google Calendar, Apple Calendar, Outlook, etc.",
|
||||
"operationId": "calendarFeed",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "token",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string" },
|
||||
"description": "Public calendar token (from the calendar's ical_url)"
|
||||
"description": "Calendar token from ical_url (public or private)"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
@@ -151,7 +197,7 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": { "description": "Calendar not found or not public", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
||||
"404": { "description": "Calendar not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
||||
},
|
||||
"security": []
|
||||
}
|
||||
|
||||
@@ -58,7 +58,7 @@
|
||||
"name": { "type": "string", "minLength": 1, "maxLength": 80 },
|
||||
"color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "example": "#22C55E" },
|
||||
"is_public": { "type": "boolean" },
|
||||
"ical_url": { "type": "string", "format": "uri", "description": "Public iCal feed URL (only present when is_public is true)" },
|
||||
"ical_url": { "type": "string", "format": "uri", "description": "iCal feed URL. Present for both public and private calendars. Public calendars use a shorter token; private calendars use a 64-character SHA256 hex token for additional security." },
|
||||
"role": { "type": "string", "enum": ["owner", "editor", "viewer"], "description": "Current user's role on this calendar" },
|
||||
"created_at": { "type": "string", "format": "date-time" },
|
||||
"updated_at": { "type": "string", "format": "date-time" }
|
||||
@@ -152,6 +152,18 @@
|
||||
"role": { "type": "string", "enum": ["owner", "editor", "viewer"] }
|
||||
}
|
||||
},
|
||||
"CalendarSubscription": {
|
||||
"type": "object",
|
||||
"required": ["id", "calendar_id", "source_url", "created_at"],
|
||||
"properties": {
|
||||
"id": { "type": "string", "format": "uuid" },
|
||||
"calendar_id": { "type": "string", "format": "uuid" },
|
||||
"source_url": { "type": "string", "format": "uri", "description": "iCal feed URL" },
|
||||
"last_synced_at": { "type": "string", "format": "date-time", "nullable": true },
|
||||
"sync_interval_minutes": { "type": "integer", "nullable": true },
|
||||
"created_at": { "type": "string", "format": "date-time" }
|
||||
}
|
||||
},
|
||||
"BusyBlock": {
|
||||
"type": "object",
|
||||
"required": ["start", "end", "event_id"],
|
||||
|
||||
146
internal/api/openapi/specs/subscriptions.json
Normal file
146
internal/api/openapi/specs/subscriptions.json
Normal file
@@ -0,0 +1,146 @@
|
||||
{
|
||||
"paths": {
|
||||
"/calendars/{id}/subscriptions": {
|
||||
"get": {
|
||||
"tags": ["Subscriptions"],
|
||||
"summary": "List calendar subscriptions",
|
||||
"description": "Returns all iCal feed subscriptions for a calendar. Requires `calendars:read` scope.",
|
||||
"operationId": "listCalendarSubscriptions",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "format": "uuid" },
|
||||
"description": "Calendar ID"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "List of subscriptions",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": ["items", "page"],
|
||||
"properties": {
|
||||
"items": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/components/schemas/CalendarSubscription" }
|
||||
},
|
||||
"page": { "$ref": "#/components/schemas/PageInfo" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
||||
"403": { "description": "Insufficient scope or permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
||||
"404": { "description": "Calendar not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
||||
}
|
||||
},
|
||||
"post": {
|
||||
"tags": ["Subscriptions"],
|
||||
"summary": "Add a subscription",
|
||||
"description": "Adds an iCal feed subscription to a calendar. Fetches the feed, imports events, and creates a subscription for future syncs. Owner or editor only. Requires `calendars:write` scope.",
|
||||
"operationId": "addCalendarSubscription",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "format": "uuid" },
|
||||
"description": "Calendar ID"
|
||||
}
|
||||
],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": ["url"],
|
||||
"properties": {
|
||||
"url": { "type": "string", "format": "uri", "description": "iCal feed URL (http, https, or webcal)", "example": "https://example.com/calendar.ics" },
|
||||
"sync_interval_minutes": { "type": "integer", "nullable": true, "description": "Optional sync interval in minutes" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Subscription added and events imported",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": ["ok", "imported", "source"],
|
||||
"properties": {
|
||||
"ok": { "type": "boolean", "example": true },
|
||||
"imported": { "type": "object", "properties": { "events": { "type": "integer", "example": 12 } } },
|
||||
"source": { "type": "string", "format": "uri", "description": "The URL that was imported" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": { "description": "Validation error, unreachable URL, or invalid ICS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
||||
"401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
||||
"403": { "description": "Insufficient scope or permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
||||
"404": { "description": "Calendar not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
||||
}
|
||||
}
|
||||
},
|
||||
"/calendars/{id}/subscriptions/{subId}": {
|
||||
"delete": {
|
||||
"tags": ["Subscriptions"],
|
||||
"summary": "Delete a subscription",
|
||||
"description": "Removes an iCal feed subscription from a calendar. Owner or editor only. Requires `calendars:write` scope.",
|
||||
"operationId": "deleteCalendarSubscription",
|
||||
"parameters": [
|
||||
{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Calendar ID" },
|
||||
{ "name": "subId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription ID" }
|
||||
],
|
||||
"responses": {
|
||||
"200": { "description": "Subscription deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } },
|
||||
"401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
||||
"403": { "description": "Insufficient scope or permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
||||
"404": { "description": "Calendar or subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
||||
}
|
||||
}
|
||||
},
|
||||
"/calendars/{id}/subscriptions/{subId}/sync": {
|
||||
"post": {
|
||||
"tags": ["Subscriptions"],
|
||||
"summary": "Sync a subscription",
|
||||
"description": "Triggers an immediate sync of an iCal feed subscription. Fetches the feed and imports/updates events. Owner or editor only. Requires `calendars:write` scope.",
|
||||
"operationId": "syncCalendarSubscription",
|
||||
"parameters": [
|
||||
{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Calendar ID" },
|
||||
{ "name": "subId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription ID" }
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Sync completed",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": ["ok", "imported"],
|
||||
"properties": {
|
||||
"ok": { "type": "boolean", "example": true },
|
||||
"imported": { "type": "object", "properties": { "events": { "type": "integer", "example": 5 } } }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
||||
"403": { "description": "Insufficient scope or permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
|
||||
"404": { "description": "Calendar or subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user