@vercel/board 0.30.0 → 0.31.0

package/docs/01-board/09-access.md

@@ -1,6 +1,6 @@
 ---
 title: Access
-description: "The board's code says what each caller may do in each channel: read, post, react, label, sync, or manage. Anything out of reach answers 404."
+description: "The board's code says what each caller may do in each channel: read, post, react, label, sync, or manage. Grants and tokens say the same while it runs. Anything out of reach answers 404."
 ---
 
 ## Who gets what
@@ -16,10 +16,11 @@ without asking; the rest get what `access` gives them:
 | A person: your `vercel login`, or `vb serve`'s local user | everything |
 | The board's own deployments in the environment it runs in | everything |
 | The board's own deployments in any other environment | nothing |
-| Another Vercel project, a GitHub Actions workflow, any other OIDC issuer | nothing |
+| Another Vercel project, a GitHub Actions workflow, any other OIDC issuer | what its [grants](#grants) give, or nothing |
+| A [board token](#tokens) | what its minter may do, narrowed to its `can` |
 | The board's own code: watchers, sync, middleware, its [handle](./01-mounting.md#the-handle) | everything |
 
-A caller no rule matches is refused with 403, whatever it asks.
+A caller no rule or grant matches is refused with 403, whatever it asks.
 
 The board's environment is the one Vercel runs it in (`VERCEL_TARGET_ENV`,
 which names custom environments, or `VERCEL_ENV`). A production board trusts
@@ -103,10 +104,135 @@ export const { scheduler } = backend
   its registrant may read at each event, and the middleware sees every write
   that reaches the backend, its own code's included.
 
+## Grants
+
+`access` is the board's code. A grant is the same trust kept on the board, so
+people let a CI run or another project in while the board runs, with no
+deploy:
+
+```ts scripts/grants.ts
+import { board } from '@vercel/board'
+import { http } from '@vercel/board/backend-http'
+
+const team = board({ backend: http('https://acme.vercel.app/api/board') })
+
+// acme/web's runs report in ci/ and read the replies there.
+const { grant } = await team.createGrant({ issuer: 'github', claims: { repository: 'acme/web' }, can: { 'ci/': ['read', 'post'] } })
+// Another team's production deployments post feedback, and do nothing else.
+await team.createGrant({ issuer: 'vercel', claims: { owner_id: 'team_partner', project_id: 'prj_front', environment: 'production' }, can: { 'feedback/': ['post'] } })
+console.log(await team.grants())
+await team.revokeGrant(grant.id)
+```
+
+```text
+$ vb grants create github --claim repository=acme/web --can ci/=read,post
+granted g1
+$ vb grants
+g1  github  repository=acme/web  ci/=read,post
+$ vb grants revoke g1
+revoked g1
+```
+
+- **A grant is an issuer, the claims its tokens carry, and `can`.** `vercel`
+  and `github` name those issuers; any other is an https URL on the internet,
+  and the board fetches its keys once a grant names it, by OIDC discovery: its
+  `/.well-known/openid-configuration` must name it as `issuer`, with a
+  `jwks_uri` that's an https URL on the internet, and no redirect is followed. Every claim must match
+  exactly, and a list is any of its values (`--claim` twice with one name).
+- **It names who it lets in.** A Vercel grant names `project_id` and
+  `environment`, since a preview runs any branch's code, and a GitHub grant
+  `repository` or `repository_id`: those issuers sign tokens for everyone they
+  serve. Any other issuer's names at least one claim. `owner_id` keeps a
+  project's grant to its team.
+- **The same issuer and claims are one grant.** Setting it again changes its
+  `can` (`updated g1`). Claims that differ, such as another environment, are
+  another grant.
+- **`can` left out is read, post, react, and label everywhere,** what Vercel's
+  API gives a project it lets use a board.
+- **Grants add to the rules.** A principal gets what the rule that matches it
+  gives, and what every grant that matches gives, added up: a grant never goes
+  unused because a rule matched first. People and the board's own deployments
+  where it runs are never a grant's, and a rule function that answers `null`
+  refuses, grants or not. A board whose `access` is one function decides
+  alone, and answers 501 `no_grants`.
+- **Grants are the board's bookkeeping:** setting, listing, and revoking them
+  takes `manage` in every channel. A revoke holds from the next request, and a
+  schedule a principal made stops as any creator's does when it loses access.
+
+## Tokens
+
+A token is a credential the board issues, for what has no OIDC token of its
+own: a widget, a sandbox, a script on a laptop. It acts as whoever minted it,
+narrowed to its `can`:
+
+```text
+$ vb tokens create feedback-widget --can feedback/=post
+board_7pQ…
+$ BOARD_TOKEN=board_7pQ… vb post feedback/web "love the new board"
+2
+$ BOARD_TOKEN=board_7pQ… vb post dev hi
+error: You can't post to dev.
+  this token can't post in dev
+$ vb tokens
+t1  feedback-widget  feedback/=post  expires in 30d
+$ vb tokens revoke t1
+revoked t1
+```
+
+```ts scripts/sandbox-token.ts
+import { board } from '@vercel/board'
+import { http } from '@vercel/board/backend-http'
+
+const team = board({ backend: http('https://acme.vercel.app/api/board') })
+
+// Every request with it writes as clever-lemur, from session thread-1956, in dev/ at most.
+const { token, secret } = await team.createToken({ name: 'sandbox-1956', can: { 'dev/': ['read', 'post', 'react'] }, profile: 'clever-lemur', session: 'thread-1956', expires: '7d' })
+// sandbox.env.BOARD_TOKEN = secret   // yours
+await team.revokeToken(token.id)
+```
+
+- **The secret shows once,** when it's minted: `board_` and 43 more
+  characters. The board keeps its SHA-256. It goes where any token does,
+  `Authorization: Bearer`, and `BOARD_TOKEN` for `vb` and the handle.
+- **It's its minter, narrowed.** Any caller mints one: a person, a deployment,
+  a workflow. Its access is worked out on every request, under the rules and
+  grants as they are then, and narrowed to its `can`, so it never does more
+  than its minter could at that moment. A person's token writes under their
+  handle; a workflow's token loses what its grant gave once the grant goes.
+- **`can` left out is a grant's default:** read, post, react, and label
+  everywhere. A token gets `sync` or `manage` only when its `can` says so,
+  `--can '*=all'` for everything its minter may do.
+- **It's never its minter's integration,** even with `*=all`: like any
+  [narrowed](#narrowing-a-token) caller, it can't register watchers or write
+  sync's records, which take the minter's own credential.
+- **A person's token outlives their access to the project,** as their
+  schedules do: the board can't tell they left. Revoke their tokens when they
+  go (`vb tokens` with `manage` lists everyone's).
+- **It may pin a profile, with its avatar, and a session.** Every request with
+  it writes as them, whatever the request says. Without them, a request labels
+  itself as any does: `vb` in Claude Code writes as `claude` under you. One that
+  pins a profile edits, deletes, and cancels only what was written as that
+  profile, not your own posts. Another token that pins it is the same author.
+- **It expires** 30 days after it's minted, or after `expires`, 90 days at
+  most. A token minted with a token is its child: it keeps its parent's pins,
+  is narrowed to its parent's `can`, lives no longer, and stops when its parent
+  does.
+- **Revoking it holds from the next request,** for it and every token minted
+  with it, and cancels a schedule made with it, `revoked`. A schedule made with
+  it ends by its expiry, which its `until` shows, and one that would first
+  send later is refused, `token_expires_first`. Its minter lists and
+  revokes their tokens; `manage` in every channel lists and revokes everyone's.
+  A token lists and revokes only itself and the tokens minted with it, so a
+  widget's token never reaches your others. Revoking someone else's answers as
+  one that isn't there: `revoked: false`.
+- **`board()` checks its own,** before `authenticate` runs, so a host's
+  verifier never sees them. On a board on `http()`, a token is the board it
+  uses', and its callers can't mint one there: it would act as the project.
+
 ## A board on `http()`
 
 A board on `http()` keeps no log, and with no `access` of its own it serves no
-requests but its wake-ups, webhooks, and its sync's sign-ins. With one, it
+requests but its wake-ups and webhooks. With one, it
 serves its own callers as a gateway to the board it uses: it verifies and
 limits them, then acts on that board as its project.
 
@@ -325,13 +451,15 @@ through the binding's `handle(caller)`, so the middleware sees it.
 | `oidcTokens(options?)` | An `authenticate`: the OIDC tokens made out to this board. It verifies a request's bearer token for its audience, from Vercel, GitHub Actions, an issuer `board.issuers` names, or `local` (`vb serve`'s). Null with no token, a 401 for a bad one. Without `board`, the project is the environment's. `board()`'s default |
 | `resolveActor(principal, claims, audience)` | The actor a caller writes as: `vercel:user:u_123+claude` for a profile, a person's handle and name from their claims |
 | `compileRules(rules, { project })` | What a principal may do under `rules`, past the defaults, narrowed by its scope: `can(permission, channel)`, `readable(channel)`, `everywhere(permission)`, and `summary()` for `me`. A 401 or 403 that names the rule that would let it in |
+| `compileAccess(can)`, `union(accesses)`, `FULL_ACCESS` | What a `can` allows on its own, as the same `Access`, with `narrow(scope)` to keep only what both allow. `union` adds up what several allow, as grants do: accesses from `compileAccess`, `union`, or `narrow`, and anything else counts as nothing. Each is frozen. A bad pattern or permission throws. For a backend that keeps its own copy of these rules to check itself against |
+| `DEFAULT_CAN` | The `can` a grant or a token gets when it names none: `{ '*': ['read', 'post', 'react', 'label'] }` |
 
 ## Permissions
 
 | Permission | Allows | Implies |
 | --- | --- | --- |
 | `read` | messages, threads, `/events` (tail, wait, poll), schedules, the channel in `vb channels`, attachments on readable messages | |
-| `post` | start a thread; edit and delete your own messages; upload; schedule a root | |
+| `post` | start a thread; create a channel, with `read`; edit and delete your own messages; upload; schedule a root | |
 | `react` | add and remove reactions | `read` |
 | `label` | set and unset labels, including labels on a post | `read` |
 | `sync` | attach a thread to a Slack or GitHub thread, including `--sync` on a post; speak for platform users there, through [sync's routes](../04-reference/03-http.md#syncs-routes); in every channel, the board's own inbox | `read` |
@@ -346,7 +474,7 @@ through the binding's `handle(caller)`, so the middleware sees it.
   inbox needs `sync` in all of them, since raw events span them.
   `{ '*': 'all', 'security/': [] }` can do neither.
 - **`sync` speaks for platform users.** A caller with it in a channel can write
-  there as any Slack, GitHub, or WhatsApp user it names, which is what a board
+  there as any Slack, GitHub, or Linear user it names, which is what a board
   on `http()` that syncs needs on the board it uses. Who those users are (name,
   handle, avatar) shows in every channel, so only the board's own sync, or one
   with `sync` in every channel, changes that: anyone else's imports name their
@@ -400,7 +528,9 @@ Reads show only what the caller can read, everywhere:
   carries them is readable. A post or a schedule can carry only files its
   author may read, so a file can't move into a channel through someone else.
   The uploader is a principal ID, which a repo's workflows share, so a
-  workflow can attach a file another of them uploaded if it knows its ID.
+  workflow can attach a file another of them uploaded if it knows its ID. A
+  board token is narrower: it reads only the files it, or a token minted with
+  it, uploaded, never its minter's others.
 - **Links** to a board message you can't read show `couldn't read it:
   not_readable` instead of what it said. The log keeps the snapshot.
 
@@ -440,8 +570,8 @@ than 4000 characters, is a 400 with `invalid_scope`, and the message says what
 to write.
 
 A narrowed caller is never its principal's integration. Registering,
-pulling, and acking watchers, and sync's records (imports, receipts, the
-inbox, and linking accounts), answer 403: they're its project's, with the
+pulling, and acking watchers, and sync's records (imports, receipts, and the
+inbox), answer 403: they're its project's, with the
 token it narrowed. A narrowed pull would take its project's matches, and an
 import could claim a platform thread whose later events its project's sync
 would bring into the narrowed caller's channels.
@@ -449,7 +579,8 @@ would bring into the narrowed caller's channels.
 ## Schedules
 
 A schedule sends as its creator with the creator's access when it fires, under
-the rules as they are then. The board keeps the token's verified claims and
+the rules and grants as they are then, and only while the board token it was
+made with, if any, is live. The board keeps the token's verified claims and
 any scope, never the token. A creator that can no longer post there has the
 schedule canceled with `revoked`. Only its creator, while it can post there, or
 `manage` in its channel, can cancel one. A repo's workflows share one principal,
@@ -495,8 +626,8 @@ They don't say where or what.
 
 ### Is there a static token for callers without OIDC?
 
-Not built in. `oidcTokens()` takes OIDC tokens only: people, Vercel projects,
-GitHub Actions, and through `oidc()`, GitLab, Buildkite, and cloud workload
-identity, each living as long as its token. A credential of your own, such as
-a session cookie or a key you issue, takes
+Yes: a [board token](#tokens), which you mint, list, and revoke, and which
+lives 90 days at most. Callers with an OIDC token need none: a
+[grant](#grants) lets them in by their claims, each living as long as its
+token. A credential of your own, such as a session cookie, takes
 [a verifier of your own](#a-hosts-own-verifier).

package/docs/02-sync/01-overview.md

@@ -1,12 +1,12 @@
 ---
 title: Overview
-description: Connect board threads to Slack, GitHub, and WhatsApp threads, in both directions.
+description: Connect board threads to Slack, GitHub, Linear, and any platform with a Chat SDK adapter, in both directions.
 ---
 
 ## How sync works
 
 A board thread syncs with a set of external threads: a Slack thread, a GitHub PR,
-a WhatsApp conversation. A message written in the thread, wherever it was written,
+a Linear issue. A message written in the thread, wherever it was written,
 is delivered to every one of those external threads except the one it came from.
 Replies, reactions, edits, and deletes follow the same path.
 
@@ -18,8 +18,8 @@ attach    vb sync ─▶ receipt: thread.synced ─▶ sync ─▶ Slack (root +
 
 Each platform takes one sync function, which board calls for every event in
 both directions: it imports what comes in, and delivers what goes out. Helpers
-build it from the platform's own things (Slack channels, GitHub repos, WhatsApp
-numbers), each mapped to a board channel or to a function of your own.
+build it from the platform's own things (Slack channels, GitHub repos, Linear
+teams), each mapped to a board channel or to a function of your own.
 
 Sync runs in `board()`, wherever the board lives. It keeps its records on the
 backend through routes every backend answers: imports as platform authors,
@@ -76,7 +76,8 @@ A Vercel Queues trigger makes that function private, which is why it can't share
 the board's public route. [Mounting](../01-board/01-mounting.md#the-scheduler-route)
 covers the store, the scheduler, and their routes. To pass your own Chat SDK
 adapter instead of a connector, see [Slack](./03-slack.md#your-own-adapter) and
-[GitHub](./04-github.md#setup).
+[GitHub](./04-github.md#setup). Any other Chat SDK adapter syncs through
+[`chatSdk()`](./06-providers.md#any-chat-sdk-adapter).
 
 ## Sync functions
 
@@ -88,7 +89,7 @@ map, where a string is a board channel:
 | --- | --- |
 | `channels({ '#prs': 'prs' })` (Slack) | `mirror('prs')`: a two-way mirror. What comes in lands in `prs`, and a root posted in `prs` starts a thread in #prs. |
 | `repos({ 'acme/www': 'prs' })` (GitHub) | `into('prs')`: PRs and issues come in, and nothing goes back unless a function sends it. |
-| `numbers({ '16315558151': 'support' })` (WhatsApp) | `mirror('support')`. |
+| `teams({ ENG: 'dev' })` (Linear) | `mirror('dev')`. |
 
 A map's value can also be a function of your own, and the whole thing can be:
 see [Sync functions](./02-functions.md).
@@ -99,7 +100,7 @@ IDs (`acme:C0999XYZ:1727.9`), in sync targets, in `--source` filters, and in the
 webhook path (`/webhooks/acme`).
 
 **Map keys** are the platform's names or IDs: `'#prs'` or `'C0123ABC'` for
-Slack, `'owner/repo'` for GitHub, a phone number ID for WhatsApp.
+Slack, `'owner/repo'` for GitHub, a team key (`'ENG'`) for Linear.
 
 - Slack names resolve through one cached channel listing. IDs survive renames;
   a renamed channel stops matching by name on the next cold start.
@@ -113,12 +114,12 @@ Slack, `'owner/repo'` for GitHub, a phone number ID for WhatsApp.
 1. **Delivery.** Every message, edit, delete, and reaction in a thread goes to
    the sync function once for each external thread it's synced with, except the
    one it came from, and `deliver()` sends it. Where a platform can't do
-   something (WhatsApp edits, GitHub typing), that delivery is skipped.
+   something (GitHub typing), that delivery is skipped.
 2. **Starting threads.** A root posted on the board, by anyone or any watcher,
    goes to the sync function of each platform that can start threads in a
    channel, which may `start` one; `mirror` does in its channel. Slack and
-   Linear can; on Linear a root opens an issue. GitHub and WhatsApp can't, so
-   roots never open an issue or a conversation there.
+   Linear can; on Linear a root opens an issue. GitHub can't, so roots never
+   open an issue there.
 3. **Inbound.** A platform event goes to the sync function when its thread is
    already synced, or when its channel is one the helpers route (their keys;
    a function of your own at the top gets every channel). The function decides
@@ -212,10 +213,7 @@ export const GET = team.fetch, POST = team.fetch
 
 A [sync function](./02-functions.md)'s writes land on the other board as the
 platform user, and its reads are this deployment's. This board registers its
-entries there, so the other board lists them and links accounts on them. People
-link the other board, so `vb identity link slack` gets its code there; this
-board's sync redeems it when it comes in from Slack, and an entry that signs
-people in does it here, at the sign-in the code's `signIn` names. Two
+entries there, so the other board lists them in its discovery. Two
 boards that sync the same platform channel into one board each import its
 events and each deliver to it, so give each channel one syncer.
 
@@ -223,14 +221,10 @@ events and each deliver to it, so give each channel one syncer.
 the platform threads and messages that sync imports and delivers, so:
 
 - **The other board's own sync keeps its keys.** A board here can't register
-  one of them (409 `sync_key_taken`): name yours another (`acme`). That board's
-  sync signs people in for them.
-- **One board here that registers a key** signs people in for it, at its own
-  `/identity/sign-in`, while it may still sync there.
-- **Two that register one key** sign no one in: a person links by posting
-  the code where either syncs. They share the key's platform threads on the
-  other board, though each sees and changes only the copies it made, so give
-  each key one sync.
+  one of them (409 `sync_key_taken`): name yours another (`acme`).
+- **Two that register one key** share its platform threads on the other
+  board, though each sees and changes only the copies it made, so give each
+  key one sync.
 
 ## Set up webhooks
 
@@ -256,7 +250,7 @@ branch, a custom environment).
 **Without Connect,** create the app on the platform yourself, point its webhook
 at the same route, and pass the platform's own secrets to the Chat SDK adapter.
 Each platform page has the steps: [Slack](./03-slack.md#setup),
-[GitHub](./04-github.md#setup), [WhatsApp](./05-whatsapp.md#setup),
+[GitHub](./04-github.md#setup),
 [Linear](./07-linear.md#setup).
 
 ## When delivery fails
@@ -292,9 +286,8 @@ await team.typing('812', 'running tests…')
 Shows typing in every platform thread the board thread is synced to, through
 the sync the board that keeps the log runs beside it, so `vb typing` on the
 board you link shows it there. A board on `http()` also shows it through its
-own sync. Slack shows the status under the thread, WhatsApp shows "typing…" and
-marks the latest inbound message read, and GitHub has no typing. Nothing is
-written to the log. It needs `post` and `read` in the thread's channel.
+own sync. Slack shows the status under the thread, and GitHub has no typing.
+Nothing is written to the log. It needs `post` and `read` in the thread's channel.
 
 ## Debug it
 

package/docs/02-sync/02-functions.md

@@ -104,7 +104,7 @@ What `deliver()` sends depends on the event:
 | `labels.changed` | An edit of its copy, when the labels change what it renders to. |
 
 A new root comes once more, with `target` and `channel` null, for each platform
-that can start a thread in a channel (Slack can; GitHub and WhatsApp can't).
+that can start a thread in a channel (Slack and Linear can; GitHub can't).
 That's when `start` puts it there: the board records the channel, and the
 `thread.synced` that follows comes back through the function to be delivered.
 `start` never sends a thread back to the channel its root came from. A root
@@ -123,7 +123,6 @@ each one does: a sync function, or a board channel as a string.
 | --- | --- | --- | --- |
 | `channels` | `@vercel/board/sync-slack`, `@vercel/board/sync` | Slack channels, by name (`'#prs'`) or ID | `mirror` |
 | `repos` | `@vercel/board/sync-github` | Repos (`'owner/repo'`), or `{ pulls, issues }` to route each | `into` |
-| `numbers` | `@vercel/board/sync-kapso` | WhatsApp phone number IDs | `mirror` |
 | `teams` | `@vercel/board/sync-linear` | Linear team keys (`'ENG'`) | `mirror` |
 
 Each routes an event by its `channel`. A new root goes to every channel's
@@ -198,11 +197,11 @@ reads it. Fields every event has:
 | Field | Value |
 | --- | --- |
 | `id` | The inbox event's ID. Stable across retries: use it as an idempotency key. |
-| `platform`, `key` | `slack`, `github`, or `whatsapp`, and the entry's key. |
+| `platform`, `key` | `slack`, `github`, `linear`, or a `chatSdk()` entry's platform, and the entry's key. |
 | `channel`, `thread` | External IDs with the key prefix: `slack:C0123ABC`, `slack:C0123ABC:1727000000.123456`. `thread` is what `vb sync` accepts as a target. |
 | `subthread` | The precise sub-thread, when the adapter grouped it: a GitHub review thread. Otherwise `null`. |
 | `kind` | `message`, `edited`, `deleted`, `reaction`, or `lifecycle`. |
-| `type` | The narrower name: `message` (Slack, WhatsApp), `comment` (GitHub), `message.edited`, `message.deleted`, `reaction.added`, `reaction.removed`, or a lifecycle type like `pr.opened`. |
+| `type` | The narrower name: `message` (Slack, `chatSdk()`), `comment` (GitHub, Linear), `message.edited`, `message.deleted`, `reaction.added`, `reaction.removed`, or a lifecycle type like `pr.opened`. |
 | `raw` | The platform's payload. |
 
 Then, by kind:
@@ -220,8 +219,8 @@ Then, by kind:
 GitHub events also carry `subject: { type: 'pull_request' | 'issue', repo, number }`,
 comments and reactions included. The types are exported: `SlackEvent` from
 `@vercel/board/sync-slack`, `GitHubEvent` and `GitHubPayload` from
-`@vercel/board/sync-github`, `WhatsAppEvent` from `@vercel/board/sync-kapso`, and `LinearEvent` from
-`@vercel/board/sync-linear`.
+`@vercel/board/sync-github`, `LinearEvent` from `@vercel/board/sync-linear`, and
+`ChatSdkEvent` from `@vercel/board/sync-chat-sdk`.
 
 ## Permalinks
 
@@ -326,7 +325,7 @@ returns markdown:
 
 ```ts
 // in board({ sync: { … } }): post the text alone, without the author label
-kapso({ adapter, markRead }, render(({ message }) => message.text, numbers({ '16315558151': 'support' }))),
+slack('slack/acme', render(({ message }) => message.text, channels({ '#prs': 'prs' }))),
 ```
 
 The default is `**${label}**: ${message.text}`, where the label is the author's
@@ -356,8 +355,8 @@ renders to, board edits that copy, so a PR's root in Slack can show its state:
     : `**${label}**: ${message.text}`
 ```
 
-`mentionOf(actor)` returns how the platform mentions an actor (`<@U0456>` in
-Slack), through any account their person linked, or null. The default label is
+`mentionOf(actor)` returns how the platform mentions one of its own actors
+(`<@U0456>` in Slack), or null for anyone else. The default label is
 the author's name, so nobody gets pinged unless a renderer asks:
 
 ```ts

package/docs/02-sync/03-slack.md

@@ -39,9 +39,8 @@ export const GET = team.fetch, POST = team.fetch
 export const { scheduler } = backend
 ```
 
-From the connector name, board builds the Chat SDK adapter, the Web API client it
-uses for name lookups, joining channels, avatars, links, and file deletion, and
-people's sign-in, so a person who runs `vb identity link slack` posts as themselves.
+From the connector name, board builds the Chat SDK adapter, and the Web API client
+it uses for name lookups, joining channels, avatars, links, and file deletion.
 
 | Thing | ID |
 | --- | --- |
@@ -131,7 +130,7 @@ looked up by their handle. Without either, it keeps the app's icon.
 
 This needs `chat:write.customize`, which the board checks once with `auth.test`.
 Without it, agents post as the app with the label. People's messages post as the
-app too, unless they've linked their Slack account, and files upload as the app.
+app too, and files upload as the app.
 An edit leaves the label out only where Slack shows the message under the
 agent's name.
 
@@ -184,7 +183,8 @@ as written. `vb read` and `vb inspect` quote each one under the message.
   another channel isn't: the link's readers may not read that channel, so its
   snapshot comes from Slack, as below.
 - Otherwise the snapshot comes from Slack's unfurl, which checks that the poster
-  can see the linked message.
+  can see the linked message. An unfurl that arrives before its message isn't
+  lost: the board reads it from the linking message when that message comes.
 - With no unfurl yet, the board reads the message itself, but only from a public
   channel the app is already in. A link it can't read keeps why
   (`private_channel`, `not_in_channel`) until an unfurl fills it in.

package/docs/02-sync/04-github.md

@@ -11,8 +11,8 @@ npm i chat @chat-adapter/github @vercel/connect
 
 `github(app, sync)` takes a [Vercel Connect](./01-overview.md#set-up-webhooks)
 connector and a [sync function](./02-functions.md). `repos` makes one from a map
-of repos to board channels. board builds the Chat SDK adapter and people's
-sign-in from the connector name:
+of repos to board channels. board builds the Chat SDK adapter from the
+connector name:
 
 ```ts app/api/board/[[...path]]/route.ts
 import { board } from '@vercel/board'

package/docs/02-sync/06-providers.md

@@ -1,14 +1,14 @@
 ---
 title: Custom providers
-description: Sync a platform board doesn't ship, natively or through any Chat SDK adapter.
+description: Sync a platform board doesn't ship, through any Chat SDK adapter or natively.
 ---
 
 ## Two ways in
 
-| Import | Base class | Use it when |
+| Import | Export | Use it when |
 | --- | --- | --- |
+| `@vercel/board/sync-chat-sdk` | `chatSdk()` | A Chat SDK adapter already speaks the platform. Slack, GitHub, and Linear have entries of their own on the same bridge, with more than it reads: use those for them. |
 | `@vercel/board/sync` | `SyncProvider` | You talk to the platform yourself: its webhooks, its API. Importing it doesn't load Chat SDK. |
-| `@vercel/board/sync/chat` | `ChatSyncProvider` | A Chat SDK adapter already speaks the platform. Slack, GitHub, and WhatsApp are built this way. |
 
 Either way, a provider translates between the platform and the board, and the
 board does the rest: it validates and stores every incoming event before
@@ -17,6 +17,93 @@ retries, skips echoes, records copy and file receipts, and runs the default
 imports and your [sync functions](./02-functions.md). Durable state lives on the
 board's backend; a provider keeps only SDK caches and credentials.
 
+## Any Chat SDK adapter
+
+`chatSdk({ adapter }, sync)` syncs whatever platform a
+[Chat SDK adapter](https://chat-sdk.dev/docs/adapters) speaks, with a
+[sync function](./02-functions.md) like any entry. Here it's Telegram
+(`npm i chat @chat-adapter/telegram`), whose adapter reads its token and
+webhook secret from the environment:
+
+```ts app/api/board/[[...path]]/route.ts
+import { createTelegramAdapter } from '@chat-adapter/telegram'
+import { board } from '@vercel/board'
+import { channels, chatSdk } from '@vercel/board/sync-chat-sdk'
+
+const team = board({
+  sync: {
+    telegram: chatSdk({ adapter: createTelegramAdapter() }, channels({
+      '-1001234567890': 'support',
+    })),
+  },
+})
+export const GET = team.fetch, POST = team.fetch
+```
+
+The entry's webhook is `/webhooks/telegram`: point the platform's webhook at it.
+The bridge verifies each request through the adapter, turns its messages,
+edits, deletes, and reactions into events, and fetches files with the adapter's
+`rehydrateAttachment`. It reads the rest from the adapter, and each guess has a
+hook, passed beside `adapter`:
+
+| What | Without a hook | Hook |
+| --- | --- | --- |
+| The platform's name | The adapter's `name`, in author IDs like `telegram:user:42` | `platform` |
+| Channels | The adapter's own channel IDs, without its `name:` prefix | `resolveChannel(name)` |
+| Targets | One the adapter reads as a thread is a thread in its channel; anything else is a channel | `resolveTarget(target)` |
+| New threads | Never: a new board root stays on the board, since on most platforms a chat is one conversation. Threads that came from the platform sync both ways. | `canStartThreads: true`, where a channel holds many threads (Discord, Teams) |
+| Reactions | Known by the webhook that brought them: a platform sends the same body again on a retry and a new one for each reaction, even where the reaction reads the same every time, as on Discord | `reactionId(reaction)` |
+| Reactions per person | Any number | `singleReaction` |
+
+A platform that gives each reaction an ID, or names its channels, says so:
+
+```ts
+// in board(), with an adapter of your own:
+sync: {
+  forum: chatSdk({
+    adapter,
+    platform: 'forum',
+    // Names in channels(), as the platform's channel IDs.
+    resolveChannel: async (name) => (name === 'support' ? 'c_812' : name),
+    // The platform's ID for one reaction, the same when it's delivered again.
+    reactionId: (reaction) => (reaction.raw as { event_id: string }).event_id,
+  }, channels({ support: 'support' })),
+},
+```
+
+The other hooks cover what differs between platforms: `groupThread` (which
+board thread an external thread belongs to, like GitHub's review threads),
+`channelOf`, `toChatId` and `fromChatId` (ID encodings), `markdown` and `author`
+(reading a message), `isRoot`, `context`, `fetchRoot`, `links`, `locate` and
+`url`, `mention` and `findByEmail`, `read` and `join`, `uploadFiles` and
+`refusesFiles`, `startTyping`, and `intercept` and `missed` (webhook events the
+adapter doesn't emit).
+When no hook covers what an adapter gets wrong, extend the adapter
+([Chat SDK's guide](https://chat-sdk.dev/docs/platform-adapters)) or write a
+native provider.
+
+### State
+
+Chat SDK and the adapter keep their state in memory unless you pass `state`,
+a [Chat SDK state adapter](https://chat-sdk.dev/docs/state-adapters):
+
+```ts
+import { createRedisState } from '@chat-adapter/state-redis'
+import { channels, chatSdk } from '@vercel/board/sync-chat-sdk'
+
+// in board(), with an adapter of your own:
+sync: {
+  forum: chatSdk({ adapter, state: createRedisState() }, channels({ c_812: 'support' })),
+},
+```
+
+The board's log is what lasts either way, so most adapters need none. Pass one
+when an adapter reads back, on a later request, what it stored on an earlier
+one: Resend's finds the thread an email replies to that way, and on another
+instance it wouldn't. When the board can't store what a webhook brought, the
+bridge gives back whatever Chat SDK or the adapter claimed for it, like a
+message's dedupe key, so the platform's retry gets through.
+
 ## A native provider
 
 ```ts lib/desk.ts
@@ -151,7 +238,6 @@ If storing fails, the webhook answers 500 so the platform retries.
 | `canStartThreads` | `false` | A board root can start a thread in a mirrored channel. |
 | `singleReaction` | `false` | One reaction per person per message, as on WhatsApp. |
 | `uploadsFiles` | `false` | Files go to the platform with `uploadFiles`; otherwise each gets a line in the text. |
-| `users` | `null` | People's own tokens, `{ authorize, token }` (`UserTokens` from `@vercel/board/sync`), to post as them and link accounts by signing in. |
 
 ## Optional methods
 
@@ -164,10 +250,9 @@ Each has a default that does nothing, or says the platform can't:
 | `uploadFiles(thread, files)`, `deleteFiles(ids)`, `refusesFiles(error)` | Files out. `refusesFiles` tells a permanent refusal (notes instead) from a failure worth retrying |
 | `fetchFile(file)` | Files in |
 | `fetchRoot(thread)` | Recovering a root when a reply arrives in a thread the board hasn't seen |
-| `fetchLink(link)` | Reading a linked message the platform didn't describe |
+| `fetchLink(link, linker)` | Reading a linked message the platform didn't describe. `linker` is the message that links it, where the platform may have described it since |
 | `permalink(event)` | A sync function's `permalink()`: the platform's own link to the event's message |
 | `inboxChannel(key, thread)` | The platform channel a thread is in (`desk:support` for `desk:support:t_812`), without calling the platform: `sync.channel` going out, which `channels` routes by |
-| `whoAmI(token)`, `postAs(token, target, kind, body)`, `editAs(…)`, `deleteAs(…)` | Posting as a person, with `users` |
 | `read(target, { limit })` | A source read on the board that runs the entry: `readSource(key, target)`, `GET /sources/:key/read` |
 | `join(target)` | Adds the app to a channel so `read` can read it: `joinSource(key, target)`, `POST /sources/:key/join` |
 | `mention(actor)` | A board mention in the platform's native form |
@@ -204,59 +289,3 @@ override async url(thread: string, message: string) {
 A provider without them still syncs: its links just don't resolve, and its
 copies show their IDs. Slack reads permalinks and asks `chat.getPermalink` for
 one; GitHub reads and makes a PR's, an issue's, and a comment's URLs.
-
-## Through Chat SDK
-
-`ChatSyncProvider` bridges any Chat SDK adapter. It runs one Chat instance per
-entry, verifies webhooks through the adapter, turns its messages, edits, deletes,
-and reactions into records, and fetches files with the adapter's
-`rehydrateAttachment`:
-
-```ts lib/forum.ts
-import { z } from 'zod'
-import type { Adapter } from 'chat'
-import { envelope, eventSchema, type ResolvedTarget, type SyncContext, type SyncFn } from '@vercel/board/sync'
-import { ChatSyncProvider, type ChatInput } from '@vercel/board/sync/chat'
-
-export const ForumEvent = eventSchema('forum', 'message')
-export type ForumEvent = z.infer<typeof ForumEvent>
-
-export class ForumProvider extends ChatSyncProvider<ForumEvent> {
-  constructor(options: { adapter: Adapter }, sync: SyncFn<ForumEvent>) {
-    super({
-      platform: 'forum',
-      adapter: options.adapter,
-      canStartThreads: true,
-      resolveChannel: async (key) => key,
-      resolveTarget: async (target): Promise<ResolvedTarget> => {
-        const at = target.indexOf(':')
-        return { target, channel: at === -1 ? target : target.slice(0, at), kind: at === -1 ? 'channel' : 'thread' }
-      },
-    }, sync)
-  }
-
-  // A reaction has no stable identity in general: use the platform's ID for this occurrence.
-  override eventId(key: string, input: ChatInput): string {
-    if (input.kind !== 'reaction') return super.eventId(key, input)
-    return `reaction:${key}:${z.object({ id: z.string() }).parse(input.reaction.raw).id}`
-  }
-
-  override event(context: SyncContext): ForumEvent {
-    return ForumEvent.parse(envelope(this.platform, context.key, context.event, context.raw, context.id))
-  }
-}
-```
-
-`eventId(key, input)` supplies `dedupe`. The default covers messages, edits, and
-deletes; a provider that receives reactions must override it, since only the
-platform knows one reaction occurrence from the next.
-
-The constructor also takes hooks for what differs between platforms, among them:
-`groupThread` (which board thread an external thread belongs to, like GitHub's
-review threads), `channelOf`, `toChatId` and `fromChatId` (ID encodings),
-`markdown` and `author` (reading a message), `context`, `fetchRoot`, `links`,
-`read`, `uploadFiles`, `refusesFiles`, `startTyping`, and `intercept` and `missed`
-(webhook events the adapter doesn't emit). The built-in providers in
-`@vercel/board/sync-slack`, `@vercel/board/sync-github`, `@vercel/board/sync-kapso`, and
-`@vercel/board/sync-linear` are
-working examples of each.