# integrations

Third-party connectors and the token vault.

## Connector interface

```ts
interface Connector {
  id: string                                // e.g. "todoist"
  scopes: string[]                          // human-readable list shown in consent UI
  beginOAuth(user): Promise<{ redirectUrl, state }>
  finishOAuth(code, state): Promise<StoredCredential>
  fetchSignals(user, since?): AsyncIterable<NormalizedEvent>
  // incremental-sync cursor (Todoist sync_token, webhook timestamps, etc.)
  // stored in Credential.meta; the connector owns its shape.
  act?(user, action): Promise<void>          // optional write-back (complete task, etc.)
  revoke(user): Promise<void>                // REQUIRED: provider-side token revocation on disconnect
}
```

## Token vault

- Credentials encrypted at rest (libsodium sealed box); key from env/KMS.
- Refresh handled transparently; consumers never see raw tokens.
- One row per `(user, provider)` with provider-specific `meta`.

## Roadmap

- Phase 0: **Todoist** (OAuth2, read tasks, complete task).
- Phase 2: Google Calendar, Apple Health (web import), generic webhook ingress.
- Phase 5: public SDK so third parties can ship connectors.