/platform/docs/CONNECTORS-BATCH2-SPEC.md

# Connectors Batch 2 — Notion, Attio (managed OAuth) + PostHog, Mixpanel, Amplitude, Apollo, Hunter (manual) — with a generic multi-account layer

Status: agreed 2026-07-10 (Rohit + agent). Supersedes nothing; extends M3.6.

## Goals

1. Seven new connectors: **Notion + Attio** with one-click managed OAuth via the
   ocw-connect broker (manual token paste also available, as always), and
   **PostHog, Mixpanel, Amplitude, Apollo, Hunter** as manual API-key connectors.
2. **Multi-account from day one, for all seven.** Users routinely hold multiple
   accounts of the same SaaS (two Notion workspaces, several PostHog projects).
   We already do this bespoke for Slack (workspaces), Gmail/GCal (accounts), and
   HubSpot (portals) — this batch introduces the GENERIC account layer so we
   never write a bespoke module again.
3. Every tool result and approval card names the account it touched.

## Non-goals

- Migrating gmail/gcal/hubspot/slack onto the generic layer (later refactor;
  their shipped behavior must not churn in the same batch that adds 7 connectors).
- Write tools beyond the minimal useful set (this batch is read-heavy).
- Webhooks/relay inbound for any of the seven (outbound/read only).
- Per-account privacy filters (Gmail-style "never show agents") — later if asked.

## 1. Generic account layer — `coworker/connectors/accounts.py`

Same shape as `gcal_accounts.py`, parameterized by connector name:

- Profiles at `<connector>:account:<account_id>`; `<connector>:default` is a
  POINTER ONLY: `{"default_account": <id>}` (plus connector-wide settings like
  `enabled`). Never tokens.
- `list_accounts(secrets, connector) -> [(id, profile)]`
- `default_account(secrets, connector) -> id` (pointer, else sole account)
- `resolve(secrets, connector, account="") -> (profile_key, profile)` — explicit
  account, else default, else the sole account; `{}` when nothing connected.
- `add_account(secrets, connector, account_id, fields)` — used by both manual
  connect and the managed OAuth callback; sets the default pointer if first.
- `set_default`, `disconnect_account` (last disconnect deletes the pointer).
- **Legacy migration**: a token-bearing `<connector>:default` (from any older
  build) is treated as one account and lazily rewritten on first touch —
  mirrors the shipped gmail/gcal migration; no user action.

**Account id per connector** (stable, human-meaningful):

| connector | account_id | shown as |
|---|---|---|
| notion | workspace_id (from OAuth token response) | workspace_name |
| attio | workspace_id (from `GET /v2/self`) | workspace name |
| posthog | project_id | `host · project` |
| mixpanel | project_id | project_id |
| amplitude | api_key last 6 | `key …abc123` |
| apollo | validator identity (account email) | email |
| hunter | validator identity (account email) | email |

Descriptor gains `account_field: str = ""` — the creds field (or `"@identity"`
sentinel = use ValidationResult.identity) that names the account. Non-empty
`account_field` marks the connector as account-patterned everywhere
(connect path, connector_list, server routes, GUI).

## 2. Desktop plumbing

- **Connect (manual)**: for account-patterned connectors, `connect_connector`
  validates, derives the account id, and writes `<name>:account:<id>` via
  `add_account` instead of overwriting `<name>:default`. Re-connecting the same
  id updates it; a different id adds a second account. Managed OAuth callback
  does the same with broker-returned identity.
- **connector_list**: generic branch for account-patterned connectors, same
  shape as gmail/gcal: `accounts: [{account, default, managed}]`,
  `connected = len(accounts) > 0`, `account` = default account (back-compat).
- **Routes** (generic, allowlisted to account-patterned connectors):
  - `POST /v1/connectors/{name}/accounts/{id}/disconnect` (+ best-effort
    cloud_disconnect for managed profiles)
  - `POST /v1/connectors/{name}/accounts/{id}/default`
  (gcal keeps its existing specific routes; no alias churn.)
- **Tools**: every tool gets `account: str = ""`; shared helper
  `_account_profile(secrets, connector, account, *fields)` (resolve →
  `ensure_fresh_connector_token(profile_key=…)` for managed → field check);
  every result passes through `_acct_result(account_id, result)` so approvals
  and transcripts name the account.

## 3. The seven connectors

### Notion (managed + manual)
- OAuth: authorize `https://api.notion.com/v1/oauth/authorize` (`owner=user`),
  token exchange with **HTTP Basic** (client_id:secret). Tokens are long-lived
  (no refresh flow). Token response carries `workspace_id`/`workspace_name` —
  the broker forwards them; desktop stores them on the account profile.
- Manual path: paste an internal-integration token; account id = workspace id
  from `GET /v1/users/me` (bot owner workspace).
- Tools: `notion_search(query, account)` (POST /v1/search),
  `notion_read_page(page_id, account)` (page + block children, text-flattened),
  `notion_query_database(database_id, filter_json, account)`,
  `notion_create_page(parent_id, title, markdown_body, account)` [write].
- Validator: `GET /v1/users/me`.

### Attio (managed + manual)
- OAuth: authorize `https://app.attio.com/authorize`, token
  `https://app.attio.com/oauth/token` (standard code exchange). Long-lived
  access token. Identity: `GET /v2/self` → workspace id + name.
- Manual path: workspace API key (same header).
- Tools: `attio_list_objects(account)` (GET /v2/objects),
  `attio_search_records(object, query, account)` (POST
  /v2/objects/{object}/records/query), `attio_get_record(object, record_id,
  account)`, `attio_create_note(parent_object, parent_record_id, title,
  content, account)` [write].
- Validator: `GET /v2/self`.

### PostHog (manual)
- Fields: `base_url` (default `https://us.posthog.com`), `api_key` (personal),
  `project_id`. Bearer auth.
- Tools: `posthog_query(hogql, account)` (POST /api/projects/{pid}/query,
  HogQLQuery kind), `posthog_list_insights(query, max_results, account)`.
- Validator: `GET /api/users/@me/` → email.

### Mixpanel (manual)
- Fields: service account `username` + `secret`, `project_id`. HTTP Basic.
- Tools: `mixpanel_segmentation(event, from_date, to_date, unit, where,
  account)` (GET mixpanel.com/api/query/segmentation),
  `mixpanel_top_events(max_results, account)` (GET /api/query/events/top).
- Validator: `GET https://mixpanel.com/api/app/me`.

### Amplitude (manual)
- Fields: `api_key`, `secret_key`. HTTP Basic. Dashboard REST API.
- Tools: `amplitude_active_users(start, end, metric, account)` (GET
  amplitude.com/api/2/users), `amplitude_event_totals(event_type, start, end,
  account)` (GET /api/2/events/segmentation).
- Validator: `GET /api/2/annotations`.

### Apollo (manual)
- Field: `api_key` (X-Api-Key header).
- Tools: `apollo_enrich_person(email, name, company_domain, account)` (POST
  /api/v1/people/match), `apollo_enrich_company(domain, account)` (GET
  /api/v1/organizations/enrich), `apollo_search_people(query, max_results,
  account)` (POST /api/v1/mixed_people/search).
- Validator: `GET /api/v1/auth/health`.

### Hunter (manual)
- Field: `api_key` (query param).
- Tools: `hunter_domain_search(domain, max_results, account)`,
  `hunter_find_email(domain, first_name, last_name, account)`,
  `hunter_verify_email(email, account)`.
- Validator: `GET /v2/account` → email.

All tools approval-gated (house default); `caps=[<connector>, "read"|"write"]`.
Writes in batch: `notion_create_page`, `attio_create_note` only.

## 4. Broker (ocw-connect)

- Two `Provider` entries: `notion` (Basic-auth token exchange, no refresh,
  forward `workspace_id`/`workspace_name`/`bot_id` in the callback result) and
  `attio` (standard exchange). No scope sets (both fix scopes at app level).
- Redirect URIs: `https://api.opencoworker.app/v1/oauth/{notion,attio}/callback`.
- Stateless as ever: tokens go to the desktop, nothing at rest.
- **Prereqs (Rohit)**: register the Notion public integration + Attio app,
  add client ids/secrets to the `ocw-connect/oauth-providers` secret
  (key names only in any transcript), approve terraform apply.

## 5. GUI

- **AccountsDetail** (generic detail page, registered for all seven): accounts
  group with Default badge / set-default / × disconnect-account, "＋ Add
  account" (managed → `connectManaged`; manual → the connector's field form),
  Tools disclosure, footer Disconnect-all. Modeled on CalendarDetail; replaces
  GenericDetail for account-patterned connectors.
- ConnectorsList row status shows `N accounts` when >1.
- Add-connection modal: Notion/Attio get One click | Manual pills (≥2 modes);
  the five manual ones keep the plain field form.
- Visual review in the dev app before PR (house rule).

## 6. Tests

- `tests/test_accounts.py`: generic layer — add/list/resolve/default/disconnect
  /legacy-migration, per connector-name isolation.
- `test_connectors.py`: routing tests for all new tools (fake `_request`),
  not-connected errors, account param → profile resolution, `_acct_result`
  stamping, write tools approval-pinned.
- `test_setup.py`-style: connector_list accounts branch; connect twice with
  different ids → two accounts, default stable.
- Server route tests: generic disconnect/default (allowlist rejects
  non-account connectors).
- Broker: provider config tests (authorize URL shape, Basic-auth exchange for
  notion), callback forwarding of workspace fields.
- e2e: accounts page spec (fixtures with two Notion accounts), add-account
  modal, default switch; connectors-list count row.
- Live drills (with ledger entries for anything caught): two Notion
  workspaces one-click; Attio workspace; each manual key validated; account
  disambiguation in approvals; dual-account tool calls.

## 7. Build order (each step lands green + committed)

- **Step 0** — accounts.py + descriptor `account_field` + connect-path +
  connector_list branch + generic routes + tests.
- **Step 1** — the five manual connectors on the pattern (descriptors,
  validators, tools, tool_defs) + tests.               [task #27]
- **Step 2** — broker notion/attio providers + tests; deploy after prereqs +
  explicit approval.                                    [task #28]
- **Step 3** — desktop notion/attio (descriptors managed=True, callback
  branches, tools) + tests.                             [task #29]
- **Step 4** — GUI AccountsDetail + modal pills + e2e; visual review.
- **Step 5** — live drills, ledger, then DMG rebuild (full build_dmg.sh,
  signed).                                              [task #30]

## Open questions (defaulted, flag to change)

- Attio/Notion write tools kept minimal (create page / note). More on ask.
- PostHog EU cloud → covered by `base_url`; self-hosted too.
- Amplitude EU residency zone (analytics.eu.amplitude.com) — not in v1.