# gsdplan.com Calendar API

## Overview
This is a family calendar API. You can insert events for family members using the endpoint below.

## Authentication
All data-writing requests require a Bearer token in the Authorization header:
`Authorization: Bearer <PIN>`

The user will provide the PIN/code when asking you to insert entries.

## Endpoints

### GET /api/ai
This endpoint (the one you're reading now). No authentication required.

### POST /api/entries
Insert one or more calendar entries. Requires authentication.

**Request Body (JSON):**
```json
{
  "entries": [
    {
      "name": "ben",
      "date": "2026-06-15",
      "text": "Flight QF401 SYD→MEL 7:00am"
    },
    {
      "name": "ben",
      "date": "2026-06-18",
      "text": "Flight QF402 MEL→SYD 5:30pm"
    }
  ]
}
```

### Valid Column Names (the "name" field)
Use one of these exact values (case-insensitive matching is done server-side):
- `general` — General events (NSW public holidays, etc.)
- `franca` — Franca's events
- `ben` — Ben's events
- `maddie` — Maddie's events
- `milly` — Milly's events
- `notes` — General notes
- `collingwood` — Collingwood-related events

### Date Format
- Must be `YYYY-MM-DD` format
- Year must be `2026`
- Example: `2026-07-15` for July 15th, 2026

### Important Rules
1. **Always append**: If a cell already has content, new text is APPENDED on a new line. Existing data is never overwritten.
2. **Multi-line text**: Use \n for line breaks within a single entry's text.
3. **URLs**: Include full URLs (https://...) in text — they auto-render as clickable links in the calendar.
4. **Multiple entries per day**: Send separate entries for the same date if needed. They will be appended.
5. **Person mapping**: Map the person's name from the user's request to the correct column name (e.g., "Ben" → "ben", "Franca" → "franca").

### Success Response
```json
{
  "success": true,
  "inserted": 2,
  "details": [
    { "date": "2026-06-15", "name": "ben", "status": "appended" },
    { "date": "2026-06-18", "name": "ben", "status": "created" }
  ]
}
```

### Error Response
```json
{
  "success": false,
  "error": "Invalid column name: john. Valid names: general, franca, ben, maddie, milly, notes, collingwood"
}
```

## Example cURL
```
curl -X POST https://gsdplan.com/api/entries \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PIN_HERE" \
  -d '{"entries":[{"name":"ben","date":"2026-07-01","text":"Meeting at 9am"}]}'
```

## Workflow for AI Agents
1. The user will say something like: "Put this for Ben in gsdplan.com code c9419"
2. Parse the content (email, image, text) to extract dates and event descriptions
3. Map the person's name to a valid column name
4. Format dates as YYYY-MM-DD
5. POST to /api/entries with the PIN as Bearer token
6. Report the result back to the user