# Handoff: koppeling bouwen naar de persoonlijke assistent (inname v1)

Dit document is de handoff voor wie een koppeling bouwt: een script, macro,
app of systeem dat gegevens naar de persoonlijke assistent van Nick stuurt.
Hetzelfde adres doet twee dingen: `GET` geeft deze handoff (altijd de
actuele versie, als Markdown), `POST` levert gegevens af.

```bash
curl -sS https://padump.homeautomation.doingcode.nl/
```

## Doel

Eén adres om alles naar de assistent te sturen: e-mails, gesprekken,
chatberichten, notities, documenten (zoals een projectplan), taken en
afspraken. De assistent bewaart het, deelt het in per werkgebied en maakt er
taken van. Een koppeling hoeft alleen af te leveren; indelen en prioriteren
gebeurt aan de kant van de assistent.

## Wat je nodig hebt

1. **Een kanaal en een token.** Elke koppeling krijgt een eigen kanaal. Vraag
   Nick om er een aan te maken (op de server:
   `./kanaal.sh nieuw <code> "<omschrijving>"`, code in kleine letters,
   bijvoorbeeld `outlook_macro`). Het token wordt één keer getoond.
2. **Het token nooit in de code of in git.** Gebruik de sleutelhanger van het
   systeem (macOS: `security`, Windows: Credential Manager), een
   omgevingsvariabele of een bestand dat alleen de gebruiker kan lezen.
3. **Alleen ingebouwde middelen** als het op een werklaptop draait (curl,
   PowerShell, osascript, launchd, Taakplanner). Niets installeren.

## Regels voor de koppeling

- **`ref` is stabiel**: dezelfde bron geeft altijd dezelfde `ref` (Message-ID,
  ID van de notitie, bestandspad). Daarmee is opnieuw versturen veilig en
  wordt een wijziging een update in plaats van een dubbel item.
- **Bijhouden wat al verstuurd is** mag, hoeft niet: de server herkent
  ongewijzigde items. Houd het wel bij als de bron groot is (stuur alleen wat
  sinds de vorige ronde is gewijzigd) en verhoog die stand pas na een 200.
- **Bundelen**: tot 500 items per verzending, maximaal 5 MB.
- **Fouten**: bij 400 klopt de inhoud niet; lees `fout`, verbeter en stuur
  niet blind opnieuw. Bij 401 is het token fout of ingetrokken: stoppen en
  melden. Bij 5xx of een netwerkfout later opnieuw proberen.
- **Alleen wat mag**: stuur geen gegevens die volgens het beleid van de bron
  het apparaat niet mogen verlaten. Voor CCV, Clover en Fiserv eerst het
  bedrijfsbeleid. Liever een selectie (een map, een label) dan alles.
- **Loggen zonder inhoud**: log aantallen en statuscodes, niet de tekst of
  het token.

## Adres

```
POST https://padump.homeautomation.doingcode.nl/
Authorization: Bearer <token van het kanaal>
Content-Type: application/json
```

## Body

Eén item, of een lijst onder `items` (maximaal 500 per keer):

```json
{
  "versie": 1,
  "items": [
    {
      "soort": "email",
      "ref": "<CAF9x@mail.example.com>",
      "titel": "Prijzen 2027",
      "tekst": "Hoi Nick, kun je voor vrijdag de nieuwe prijzen sturen?",
      "datum": "2026-11-17T09:30:00+01:00",
      "personen": [
        { "naam": "Jan de Vries", "rol": "van", "adres": "jan@example.com" },
        { "naam": "Nick", "rol": "aan" }
      ],
      "context": "prijzen_2027",
      "url": "https://outlook.office.com/mail/id/AAMk...",
      "meta": { "map": "Inbox", "bijlagen": 2 }
    }
  ]
}
```

| Veld | Verplicht | Inhoud |
| --- | --- | --- |
| `versie` | nee | `1`. Een andere versie wordt geweigerd. |
| `soort` | ja | `email`, `gesprek`, `chat`, `notitie`, `document`, `taak`, `agenda` of `overig` |
| `ref` | ja | vaste ID van het origineel binnen dit kanaal, maximaal 500 tekens: Message-ID van een mail, ID van een notitie, bestandspad. **Zelfde `soort` en `ref` opnieuw sturen = bijwerken**, geen dubbel item. |
| `tekst` | ja | de inhoud als platte tekst of Markdown, maximaal 200.000 tekens. Een gesprek: het transcript. |
| `titel` | nee | onderwerp of titel, maximaal 500 tekens |
| `datum` | nee | moment van het origineel (verzonden, gesprek, laatst gewijzigd), ISO 8601 met tijdzone |
| `personen` | nee | lijst van maximaal 50; per persoon een naam als tekst of `{naam, rol, adres}`. `rol` is vrij: `van`, `aan`, `cc`, `spreker`, `eigenaar`, ... |
| `context` | nee | werkgebied als hint: `team`, `ccv`, `clover`, `operatie`, `vacatures`, `prijzen_2027`, `overig`. De indeling mag ervan afwijken. |
| `url` | nee | link naar het origineel (`http://` of `https://`) |
| `meta` | nee | vrij object voor de rest (map, labels, duur van een gesprek), maximaal 20.000 tekens als JSON |

Velden die niet in de lijst staan, worden genegeerd. Bijlagen en audio gaan
(nog) niet via dit adres: stuur de tekst, of het transcript van een gesprek.

## Antwoord

| Status | Body | Betekenis |
| --- | --- | --- |
| 200 | `{"ok":true,"kanaal":"iphone","ontvangen":3,"nieuw":1,"bijgewerkt":1,"ongewijzigd":1}` | opgeslagen |
| 400 | `{"ok":false,"fout":"item 2: tekst is leeg"}` | vorm klopt niet; **niets** opgeslagen |
| 401 | `{"ok":false,"fout":"token onbekend of ingetrokken"}` | token klopt niet; niets opgeslagen |
| 403 | HTML | alleen `GET /` (deze handoff) en `POST /` zijn open |

Een verzending is alles of niets: bij een fout in één item wordt niets
opgeslagen. Opnieuw versturen is altijd veilig.

Wat binnenkomt staat in `items` met `verwerkt = false`; de indeling door
Claude (werkgebied, taken, scores) loopt daarna apart.

## Voorbeelden

```bash
TOKEN=pa_...
URL=https://padump.homeautomation.doingcode.nl/

# Notitie
curl -sS "$URL" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"soort":"notitie","ref":"2026-11-17-overleg","tekst":"Overleg met Jan: prijzen voor vrijdag"}'

# Projectplan uit een Markdown-bestand (ref = bestandsnaam)
jq -n --rawfile t plan.md '{soort:"document", ref:"plan.md", titel:"Projectplan Clover", tekst:$t, context:"clover"}' |
  curl -sS "$URL" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' --data-binary @-

# Chatbericht
curl -sS "$URL" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"soort":"chat","ref":"teams-19:abc-1731834000","tekst":"Kun jij de release van morgen goedkeuren?","personen":[{"naam":"Piet","rol":"van"}],"datum":"2026-11-17T10:00:00+01:00"}'
```

PowerShell (werklaptop zonder curl of jq):

```powershell
$body = @{ soort = 'gesprek'; ref = 'overleg-2026-11-17'; tekst = (Get-Content transcript.txt -Raw) } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri 'https://padump.homeautomation.doingcode.nl/' `
  -Headers @{ Authorization = "Bearer $env:PA_TOKEN" } -ContentType 'application/json; charset=utf-8' -Body $body
```

## Kanalen

Op de server, in `/opt/personal_assistant`:

```bash
./kanaal.sh nieuw outlook_script "VBA-macro in Outlook"   # toont het token eenmalig
./kanaal.sh lijst                                          # code, status, laatst gebruikt
./kanaal.sh vernieuw outlook_script                        # nieuw token, oude werkt niet meer
./kanaal.sh intrekken outlook_script                       # uit; items blijven staan
```

De code van het kanaal wordt de `bron` van elk item. Eén token per apparaat
of systeem: lekt er een uit, dan trek je alleen die in.

## Privacy

- Geslaagde uitvoeringen bewaart n8n niet (anders zouden de tekst en het
  token 14 dagen in n8n staan). Mislukte wel, om fouten te kunnen zoeken.
- Het token staat alleen als SHA-256 in de database.
- Stuur geen gegevens waarvoor dat niet mag. Voor werkbronnen van CCV,
  Clover en Fiserv geldt eerst het bedrijfsbeleid.
