# Integrations internals

How connections are stored, how write-back and Linear's comments run, and how the one-time tracker import works, for
people changing that code. The user guides are [Integrations](https://andon-docs.pages.dev/guide/integrations.md) and
[Import from a tracker](https://andon-docs.pages.dev/guide/import-from-a-tracker.md).

## Connections

`integrations` holds the workspace's connections (`is_default`, `name`; `secret_name` is the Vault entry the token is
kept under, or the server's keyring). `team_connections` holds each team's pick, with a `mapping` of
`key_prefixes` and `writeback` that overrides the connection's. `private.integration_for` resolves a team's connection
(its own pick, a parent's, else the default) and `private.integration_config_for` its settings, so imports, link
resolving and write-back all follow the pick. Migration `20261110064100_workspace_connections`.

Tokens go through `integration-secrets`, which checks each with the provider before keeping it and never returns it.
The write-back switches are each provider's `events` in `apps/board/src/lib/integrations.ts`.

## Asana sign-in

**Connect with Asana** sends the browser to Asana's consent page with a `state` signed for this org and person with
the client secret (valid 10 minutes). Asana returns to `/settings/integrations/asana?code=…&state=…`, and the page
passes both to `integration-secrets` (`oauth_finish`), which checks the state, swaps the code for an access and a
refresh token, and keeps them together; `config.auth` records `pat` or `oauth`. `asanaToken`
(`apps/server/src/functions/shared/asana.ts`) refreshes an OAuth token within five minutes of expiry; a refused refresh sets
the connection's `last_error`. Rotating the client secret only restarts consents in flight.

The app's scopes, when it uses granular ones, must cover what the import, the sync and write-back do: users,
workspaces, teams, projects and tasks read, stories and attachments read, webhooks create and delete, and tasks and
stories write.

## Write-back

Asana write-back runs in `apps/server/src/functions/shared/asana-writeback.ts`, through `links-writeback`. Each attempt is a
`writeback` event on the card's latest run and stays on its outbox row for a week. The outbox has no client access;
the Sync health panel calls `tracker-import {action: 'asana_health'}`, which checks the caller's role, then reads the outbox and the import list.

## Linear comments

`import_issue_comments` (service role only, migration `20261112143225_linear_comments`) copies up to 500 comments when a
card is made from an issue, keyed by `<issue id>/<comment id>` in `card_comments.external_ref`, so a second import adds
no copies. Comments the write-back posted are skipped. In a run's `{{comments}}` they are marked *from Linear*.

## The tracker import

The `tracker-import` function (`/api/fn/tracker-import` and the `tracker-import` job) runs
`apps/server/src/functions/shared/tracker-import-job.ts`.

- **Readers and the dry run** are pure: `packages/shared/src/tracker-parse.ts` and `tracker-import.ts`, which the
  job imports from `@andon/shared`. `parseTrello` reads both Trello's export and its API pages; `parseAsana` reads Asana's REST pages.
- **Slices.** The job works in slices with a lease (`import_job_claim`) and queues the next itself (`import_job_kick`
  → `private.call_function`). Where the database can't call functions, the open Settings page drives it.
- **Writes**: `import_job_prepare` (team, statuses, projects, cycles, milestones, fields,
  former members), `import_job_card` (a card with its comments and links), `import_job_relations`,
  `import_job_templates` and `import_job_apply_templates`, `import_job_finish`.
- **Idempotence.** A card is found again by `card_links (org, provider, external_id)`; a comment, status, cycle or field
  by `private.import_refs`; a project or milestone by its tracker id; a file by `card_attachments.source_ref`.
- **Rate limits.** One request at a time per tracker: Trello 120 ms apart, Asana 400 ms. A 429 waits as asked, up to a
  minute.
- **Trello's API.** The key and token are one secret (`<key>:<token>`, `apps/server/src/functions/shared/trello.ts`), sent in
  the `Authorization: OAuth …` header, never a URL. The board is read in the export's shape, then the comment and
  create actions are paged past the first 1,000.
- **Asana reading** (`apps/server/src/functions/shared/asana-import.ts`, `asanaReadSlice`): workspace, team, users and
  projects; each project's sections and task pages (100 a page); subtasks at any depth; then each task's stories and
  attachments. The bundle grows in the job until it's all read. A file's signed `download_url` is fetched fresh
  (`GET /attachments/{gid}`) when it is copied, and the token never goes with the download.
- **Asana sync.** Each synced project is an `asana_webhooks` row. The handshake's `X-Hook-Secret` is kept like a token
  and answered only for a subscription made in the last ten minutes. A delivery must carry a valid
  `X-Hook-Signature` (HMAC-SHA256 of the body) or gets 401; an unknown subscription gets 410. Deliveries queue task ids
  (`asana_sync_enqueue`); `asana_sync_kick` runs `tracker-import {action: 'sync'}`, which rereads them in batches.
  `asana_sync_claim` keeps a sync and a re-run apart. Deliveries arrive at `asana-webhook`
  (`/functions/v1/asana-webhook` on the server).
- **Former members.** `former_members` rows; `cards.former_assignee_id` and `card_comments.former_author_id` point at
  them. The email is in `private.former_member_emails`. `invite_former_member` calls `create_invite` from the private
  address, and `link_former_member` sets `former_members.user_id`. Migration `20261108192317_tracker_import`.

## Not covered yet

- `fixtures/asana/move-team.json` and `fixtures/trello/board-export.json` are built from the providers' API references,
  not captured from real workspaces.
- A Jira XML export's components and affected versions aren't read.
