# famapp HTTP API (v1)

REST JSON API under `/api/v1/`. Full specification: [`openapi.yaml`](openapi.yaml).

## Authentication

Every endpoint accepts **either**:

- Auth.js session cookie (browser login), or
- `Authorization: Bearer <household-api-token>` header (recommended for external clients)

Unauthorized requests return `401` with `{ "error": "Unauthorized" }`.

Generate bearer tokens in **Settings → API tokens**. Example:

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" https://fam.ginnoir.com/api/v1/calendars
```

## OpenAPI

See [`openapi.yaml`](openapi.yaml) for paths, request/response schemas, and the `bearerAuth` security scheme. Import into Swagger UI, Postman, or your HTTP client of choice.

## Endpoints

### 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 |

### Garden

| Method | Path                            | Description                            |
| ------ | ------------------------------- | -------------------------------------- |
| GET    | `/api/v1/garden/containers`     | List containers                        |
| POST   | `/api/v1/garden/containers`     | Create container                       |
| GET    | `/api/v1/garden/containers/:id` | Get container with plants              |
| PATCH  | `/api/v1/garden/containers/:id` | Update container                       |
| DELETE | `/api/v1/garden/containers/:id` | Delete container                       |
| GET    | `/api/v1/garden/plants`         | List plants (optional `?containerId=`) |
| POST   | `/api/v1/garden/plants`         | Create plant                           |
| GET    | `/api/v1/garden/plants/:id`     | Get plant detail                       |
| PATCH  | `/api/v1/garden/plants/:id`     | Update plant                           |
| DELETE | `/api/v1/garden/plants/:id`     | Delete plant                           |

### Bangs

| Method | Path                | Description                                      |
| ------ | ------------------- | ------------------------------------------------ |
| GET    | `/api/v1/bangs`     | Stats: `total` + `recent` (optional `?limit=10`) |
| POST   | `/api/v1/bangs`     | Record bang (optional `occurredOn` YYYY-MM-DD)   |
| PATCH  | `/api/v1/bangs/:id` | Update `occurredOn`                              |
| DELETE | `/api/v1/bangs/:id` | Delete bang                                      |

## 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.