feat: api v1 routes for calendar lists and notes

2026-07-04 19:03:08 -05:00
parent ea5d1d050c
commit d4304b005c
25 changed files with 1141 additions and 236 deletions
@@ -0,0 +1,69 @@
+# famapp HTTP API (v1)
+
+REST JSON API under `/api/v1/`. Full OpenAPI spec is planned in task 87.3.
+
+## Authentication
+
+Every endpoint accepts **either**:
+
+- Auth.js session cookie (browser login), or
+- `Authorization: Bearer <household-api-token>` header
+
+Unauthorized requests return `401` with `{ "error": "Unauthorized" }`.
+
+Generate bearer tokens in **Settings → API tokens**.
+
+## Endpoints (87.2)
+
+### Calendars
+
+| Method | Path                    | Description                                              |
+| ------ | ----------------------- | -------------------------------------------------------- |
+| GET    | `/api/v1/calendars`     | List visible calendars                                   |
+| POST   | `/api/v1/calendars`     | Create calendar (`name`, optional `color`, `visibility`) |
+| GET    | `/api/v1/calendars/:id` | Get calendar                                             |
+| PATCH  | `/api/v1/calendars/:id` | Update `name`, `visibility`, `color`                     |
+| DELETE | `/api/v1/calendars/:id` | Delete calendar                                          |
+
+### Events
+
+| Method | Path                                    | Description                                                           |
+| ------ | --------------------------------------- | --------------------------------------------------------------------- |
+| GET    | `/api/v1/events?from=&to=&calendarIds=` | List events in range (`calendarIds` = `all` or comma-separated UUIDs) |
+| POST   | `/api/v1/events`                        | Create event                                                          |
+| GET    | `/api/v1/events/:id`                    | Get event                                                             |
+| PATCH  | `/api/v1/events/:id`                    | Update event                                                          |
+| DELETE | `/api/v1/events/:id`                    | Delete event                                                          |
+
+### Lists
+
+| Method | Path                              | Description                                                   |
+| ------ | --------------------------------- | ------------------------------------------------------------- |
+| GET    | `/api/v1/lists?type=`             | List lists (optional `type` filter, e.g. `shopping`, `tasks`) |
+| POST   | `/api/v1/lists`                   | Create list (`type`, `name`)                                  |
+| GET    | `/api/v1/lists/:id`               | Get list with items                                           |
+| PATCH  | `/api/v1/lists/:id`               | Update `name` or `archived`                                   |
+| DELETE | `/api/v1/lists/:id`               | Archive list                                                  |
+| GET    | `/api/v1/lists/:id/items`         | List items                                                    |
+| POST   | `/api/v1/lists/:id/items`         | Add item                                                      |
+| PATCH  | `/api/v1/lists/:id/items/:itemId` | Update or toggle item (`done`)                                |
+| DELETE | `/api/v1/lists/:id/items/:itemId` | Delete item                                                   |
+
+### Notes
+
+| Method | Path                | Description |
+| ------ | ------------------- | ----------- |
+| GET    | `/api/v1/notes`     | List notes  |
+| POST   | `/api/v1/notes`     | Create note |
+| GET    | `/api/v1/notes/:id` | Get note    |
+| PATCH  | `/api/v1/notes/:id` | Update note |
+| DELETE | `/api/v1/notes/:id` | Delete note |
+
+## Bearer token visibility
+
+Bearer tokens see **household-visible calendars only** (private calendars are hidden). Mutations on calendars require ownership (session) or household visibility (bearer). Activity log records `actorId: null` for bearer mutations.
+
+## Planned (87.3)
+
+- Garden, bangs routes
+- OpenAPI specification