@vercel/board 0.16.0 → 0.18.0

package/docs/02-sync/07-linear.md

@@ -0,0 +1,129 @@
+---
+title: Linear
+description: Turn each Linear issue into a board thread, with its comments as replies and its state as a label.
+---
+
+## Configure it
+
+```package-install
+npm i chat @chat-adapter/linear @vercel/connect
+```
+
+`linear(app, sync)` takes a [Vercel Connect](./01-overview.md#set-up-webhooks)
+connector and a [sync function](./02-functions.md). `teams` makes one from a map
+of Linear team keys 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'
+import { a2 } from '@vercel/board/backend-a2'
+import { vercelQueues } from '@vercel/board/backend-a2/scheduler-vercel'
+import { postgres } from '@vercel/board/backend-a2/store-postgres'
+import { linear, teams } from '@vercel/board/sync-linear'
+
+const backend = a2({
+  store: postgres({ connectionString: process.env.DATABASE_URL! }),
+  scheduler: vercelQueues({ topic: 'board' }),
+})
+
+const team = board({
+  backend,
+  sync: {
+    linear: linear('linear/acme', teams({
+      ENG: 'dev',        // ENG-123 and the rest of the team's issues, both ways
+      SUP: 'support',
+    })),
+  },
+})
+export const GET = team.fetch, POST = team.fetch
+export const { scheduler } = backend
+```
+
+A key is a team's key, the prefix of its issue IDs (`ENG` in `ENG-123`). A value is
+a board channel to mirror, or a [function](./02-functions.md). A team that isn't
+in the map stays off the board, except threads someone syncs by hand.
+
+## An issue's life in one thread
+
+1. **An issue opens.** The board creates a root in the team's channel,
+   `ENG-123: <title>` with its link, labeled `issue=ENG-123` and `state` with its
+   workflow state's type.
+2. **Comments** arrive as replies. A reply to a comment stays in that comment's
+   thread on Linear, and a board reply to one goes back into it. Edits and
+   deletes sync too.
+3. **Moving the issue** to another state updates `state`. A new title edits a
+   root that Linear opened to say it.
+4. **A root posted on the board** in a mirrored channel opens an issue in that
+   team. Its first line is the title, and the whole message is the description.
+   Editing the root edits the description. Deleting it on the board leaves the
+   issue open on Linear, and a new title on Linear leaves the root as written.
+
+| Thing | ID |
+| --- | --- |
+| A team, the channel | `linear:ENG` |
+| An issue | `linear:ENG:<issueId>` |
+| A comment thread, grouped under its issue | `linear:ENG:<issueId>:c:<commentId>` |
+
+`<issueId>` is the issue's UUID, which stays the same when the issue is renamed.
+To sync a thread by hand, name the issue by its identifier, its UUID, or its ID:
+`vb sync 812 linear:ENG-123`. A comment thread isn't a sync target: sync its
+issue.
+
+An issue that moves to another team starts a new thread in that team's channel,
+with a root fetched from Linear: the team is part of the ID, so what's said on
+the board follows the team it's in now. The old thread stays as it was.
+
+## Events
+
+| Event | What the mirror does |
+| --- | --- |
+| `issue.created` | A root labeled `issue=ENG-123` and `state=<type>` |
+| `issue.updated` | A new state sets `state`; a new title edits a root Linear opened. Other changes write nothing |
+| `comment` | A reply. Edits and deletes sync too |
+
+`state` is the workflow state's type: `triage`, `backlog`, `unstarted`,
+`started`, `completed`, or `canceled`, the same whatever a team names its states.
+
+```bash
+# in a terminal:
+vb read dev --label state=started           # what's in progress
+vb wait dev --label state=completed --timeout 1h
+```
+
+A comment on an issue that opened before you mapped its team still lands: the
+board fetches the issue through Linear's API, creates its root, then posts the
+comment as a reply.
+
+## Reactions
+
+A reaction on the board goes to its comment on Linear, while it's added: Linear
+reacts to comments, not issues, and the adapter can't take one back. Reactions
+on Linear stay there, since Linear's reaction webhooks don't say which issue
+they're on.
+
+## Setup
+
+1. Create a Linear app (**Settings > API > Applications**), through Vercel
+   Connect or by hand, with the `read`, `write`, `comments:create`, and
+   `issues:create` scopes, installed as the app (`actor=app`).
+2. Subscribe its webhook to **Issues** and **Comments**, for the teams you map.
+3. Point the webhook at `https://<host>/api/board/webhooks/linear`: Connect's
+   trigger path, or the app's webhook URL with its signing secret.
+
+Without Connect, pass your own adapter, in its default `comments` mode, with the
+app's own credentials:
+
+```ts
+// in board({ sync: { … } }):
+// import { createLinearAdapter } from '@chat-adapter/linear'
+linear({
+  adapter: createLinearAdapter({
+    clientCredentials: { clientId: process.env.LINEAR_CLIENT_ID!, clientSecret: process.env.LINEAR_CLIENT_SECRET! },
+    webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
+  }),
+}, teams({ ENG: 'dev' })),
+```
+
+> [!WARNING]
+> The adapter takes the token's user for itself and skips what they write. With a
+> personal API key, that's you: your own comments never reach the board.

package/docs/03-guides/04-triage.md

@@ -114,7 +114,7 @@ const backend = a2({
 
 const team = board({
   backend,
-  // sync: { slack: slack({ … }) }, mirroring Slack's #firehose into `firehose`
+  // sync: { slack: slack('slack/acme', channels({ '#firehose': 'firehose' })) },
   watch: {
     triage: {
       tail: 'firehose --from slack',

package/docs/04-reference/01-cli.md

@@ -95,7 +95,8 @@ $ vb read 812
 | Command | One line per |
 | --- | --- |
 | `read <channel>`, `read [filters]` | thread: `{ message, replies, last }`, the root, its reply count, and its latest reply or `null` |
-| `read <id>` | message: `{ id, channel, text, re, labels, reactions, by, author, createdAt, … }`, where `re` is the root's ID or `null` for a root |
+| `read <id>`, `read <link>` | message: `{ id, channel, text, re, labels, reactions, by, author, createdAt, … }`, where `re` is the root's ID or `null` for a root |
+| `sync <id>` | target: `{ target, key, thread, message, url, undelivered }`, the message's copy there and the platform's link to it |
 | `tail`, `wait` | event: `{ cursor, type, createdAt, payload, message, actor }` |
 | `post`, `reply` | the new message |
 
@@ -288,6 +289,7 @@ linked account, whose it is (`→ @jb`).
 ```text
 vb read [channel] [filters] [--after <id>] [--limit N]
 vb read <id>
+vb read <link>
 ```
 
 - **`read <channel>`** prints one summary per thread, like a Slack channel:
@@ -299,6 +301,11 @@ vb read <id>
 - **`read <id>`** prints one whole thread: the root and every reply, plus the
   thread's pending schedules. Any message in the thread works. With filters,
   it prints the root and only the replies that match: `vb read 812 --by ada`.
+- **`read <link>`** reads the thread a platform link names: a Slack permalink,
+  a GitHub PR, issue, or comment. The board answers from what its sync
+  recorded and never asks the platform, so a link it didn't sync, or one in a
+  channel you can't read, is the same error, exit 1:
+  `error: no message on this board for that link`.
 - **A channel that doesn't exist** is an error, exit 1:
   `error: no channel <name>: board channels lists them`.
 - `--limit` is 50 by default, at most 500. `--after <id>` reads forward from a
@@ -456,13 +463,26 @@ WhatsApp marks the latest inbound message read. Nothing is written to the log.
 ### sync
 
 ```text
+vb sync <id>
 vb sync <id> <target>
 ```
 
-Attaches the message's thread to an external target and backfills it in
-order. A channel target (`slack:#incidents`) starts a thread there; a thread
-target (`github:owner/repo:12`) joins it. Attaching twice prints `already
-synced with …`. See [Sync](../02-sync/01-overview.md).
+With no target, it prints where the message's thread is synced: a row a
+target, with its sync key, where it is, and the platform's link to this
+message's copy there, or why it didn't reach it. A thread on no platform
+prints `not synced anywhere`.
+
+```text
+$ vb sync 812
+slack   C0C8XN8SQRG     https://vercel.slack.com/archives/C0C8XN8SQRG/p1792780353701549
+github  vercel/v0:4021  https://github.com/vercel/v0/pull/4021#issuecomment-3301
+```
+
+With a target, it attaches the thread there and backfills it in order. A
+channel target (`slack:#incidents`) starts a thread there; a thread target
+(`github:owner/repo:12`) joins it. Either way the thread stays synced both
+ways. Attaching twice prints `already synced with …`. See
+[Sync](../02-sync/01-overview.md).
 
 ### sources
 
@@ -515,7 +535,7 @@ watchers
   passed   matches a registered tail, hands the match to a pull, and takes its ack
 
 sync
-  passed   keeps sync's records: an import as a platform author, its lookups by platform ID, and a receipt
+  passed   keeps sync's records: an import as a platform author, its lookups by platform ID, a receipt, and where it's synced
 
 18 passed
 ```

package/docs/04-reference/02-board.md

@@ -240,12 +240,25 @@ This handle's own post with `id`, as posting it answered, or a 404
 ### sync
 
 ```ts
+sync(id: string): Promise<SyncedView>
 sync(id: string, target: string): Promise<{ target: string; attached: boolean }>
+linked(url: string): Promise<ThreadView>
 ```
 
-Attaches the message's thread to an external target and backfills it.
-`target` is the normalized target; `attached` is false when the thread was
-already synced there. See [Sync](../02-sync/01-overview.md).
+With a target, `sync` attaches the message's thread to an external target and
+backfills it. `target` is the normalized target; `attached` is false when the
+thread was already synced there.
+
+With no target, it says where the thread is synced: `{ targets }`, each
+`{ target, key, thread, message, url, undelivered }`, with this message's copy
+there by the platform's ID and the platform's link to it. It needs `read` where
+the message is.
+
+`linked(url)` is the thread a platform link names (a Slack permalink, a GitHub
+PR, issue, or comment), as `thread(id)` answers it. The board looks it up in
+what its sync recorded and never asks the platform: a link it didn't sync, or
+to a message you can't read, is 404 `message_not_found`. See
+[Sync](../02-sync/01-overview.md).
 
 ### typing
 
@@ -574,6 +587,6 @@ export async function POST(request: Request) {
   calls `http()`'s methods, which call that board, whose middleware sees its
   writes.
 
-Sync callbacks get a client of their own, acting as the platform user who
+Sync functions get a client of their own, acting as the platform user who
 triggered the event. See [Mounting](../01-board/01-mounting.md),
-[Watchers](../01-board/06-watchers.md), and [Callbacks](../02-sync/02-callbacks.md).
+[Watchers](../01-board/06-watchers.md), and [Sync functions](../02-sync/02-functions.md).

package/docs/04-reference/03-http.md

@@ -109,6 +109,8 @@ a refused write it can read answers 403. `GET /me` returns the caller's
 | POST | `/messages/:id/reactions` | `{ emoji, remove? }`. `emoji` is a short name: `eyes`, `thumbs_up` |
 | POST | `/messages/:id/labels` | `{ set?, unset? }`, at least one |
 | POST | `/messages/:id/sync` | `{ target }`: attach the thread to an external target and backfill it. Answers `{ target, attached }` |
+| GET | `/messages/:id/sync` | Where the thread is synced: `{ targets }`, each `{ target, key, thread, message, url, undelivered }`, with this message's copy there and the platform's link to it. Needs `read` where it is |
+| GET | `/links` | The thread a platform link names, as `GET /messages/:id` answers it. Query: `url`. From sync's records alone; a link the board didn't sync, or to a message the caller can't read, is 404 `message_not_found` |
 | POST | `/messages/:id/typing` | `{ status? }`: show typing in the thread's synced platform threads. Answers `{ targets }`. Writes nothing to the log |
 | POST | `/attachments` | Upload one file. Answers 201 `{ attachment: { id, name, type, size } }`. See [Attachments](#attachments) |
 | GET | `/attachments/:id` | The file |
@@ -139,8 +141,9 @@ Every board that keeps its own log answers every route here. The sync routes
 a person calls (`/webhooks/:key`, `/messages/:id/sync`, `/identity/sign-in`,
 `/identity/signed-in`, and `/identity/unlink`) are `board()`'s, and work on any
 backend: the ones that need a sync entry answer 404 on a board that doesn't
-run it. `/sources/:key/read` and `/messages/:id/typing` are the backend's
-methods, which `a2()` answers through the sync `board()` runs beside it. A
+run it. `/sources/:key/read`, `/messages/:id/typing`, `GET /messages/:id/sync`,
+and `/links` are the backend's methods, which `a2()` answers through the sync
+`board()` runs beside it. A
 board on `http()` answers only wake-ups, webhooks, and its sync's sign-ins,
 unless it has an `access` of its own: then it serves its callers as its
 project on the board it uses (see [A board on `http()`](../01-board/09-access.md#a-board-on-http)). There are no

package/docs/04-reference/05-conformance.md

@@ -56,7 +56,7 @@ Then the rest, a group each in the report:
 | `schedules` | schedules a reply a day out, lists it, and cancels it |
 | `attachments` | uploads a file, posts it, and downloads it |
 | `watchers` | registers a tail, pulls the match for a post, and acks it. Skipped when the token already has watchers or a sync registered there, since registering replaces them |
-| `sync` | imports a message as a platform user of its own (`conformance:user:<id>`), finds it by its platform IDs, imports it again to the same message, refuses a second root from the same platform thread, records a receipt and reads the copy back, and deletes it. Skipped when the token can't register a sync or `sync` in the channel, or already has watchers or a sync registered |
+| `sync` | imports a message as a platform user of its own (`conformance:user:<id>`), finds it by its platform IDs, imports it again to the same message, refuses a second root from the same platform thread, records a receipt and reads the copy back, lists where the thread is synced with it, answers 404 for a link no sync there knows, and deletes it. Skipped when the token can't register a sync or `sync` in the channel, or already has watchers or a sync registered |
 
 Every board answers all of them: see
 [the whole protocol](./03-http.md#the-whole-protocol). A board may keep no

package/docs/index.md

@@ -51,8 +51,8 @@ import { board } from '@vercel/board'
 import { a2 } from '@vercel/board/backend-a2'
 import { vercelQueues } from '@vercel/board/backend-a2/scheduler-vercel'
 import { postgres } from '@vercel/board/backend-a2/store-postgres'
-import { slack } from '@vercel/board/sync-slack'
-import { github } from '@vercel/board/sync-github'
+import { channels, slack } from '@vercel/board/sync-slack'
+import { github, repos } from '@vercel/board/sync-github'
 
 const backend = a2({
   store: postgres({ connectionString: process.env.DATABASE_URL! }),
@@ -62,14 +62,9 @@ const backend = a2({
 const team = board({
   backend,
   sync: {
-    slack: slack({
-      adapter: 'slack/acme', // a Vercel Connect connector
-      channels: { '#errors-www': 'errors-www', '#prs': 'prs' },
-    }),
-    github: github({
-      adapter: 'github/acme',
-      repos: { 'acme/www': 'prs' },
-    }),
+    // A Vercel Connect connector, and what each event does.
+    slack: slack('slack/acme', channels({ '#errors-www': 'errors-www', '#prs': 'prs' })),
+    github: github('github/acme', repos({ 'acme/www': 'prs' })),
   },
 })
 export const GET = team.fetch, POST = team.fetch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/board",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "A message board you mount in one route: one durable log, verified authors, live tail, and two-way sync.",
   "license": "MIT",
   "type": "module",
@@ -100,27 +100,34 @@
       "types": "./dist/sync-kapso.d.mts",
       "default": "./dist/sync-kapso.mjs"
     },
+    "./sync-linear": {
+      "types": "./dist/sync-linear.d.mts",
+      "default": "./dist/sync-linear.mjs"
+    },
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@chat-adapter/github": "^4.41.1",
-    "@chat-adapter/slack": "^4.41.1",
-    "@vercel/connect": "^2.3.4",
     "@vercel/oidc": "^3.8.9",
-    "chat": "^4.41.1",
-    "experimental-a2": "0.22.0",
     "jose": "^6.2.12",
     "zod": "^4.6.5"
   },
   "peerDependencies": {
+    "@chat-adapter/github": "^4.41.1",
+    "@chat-adapter/linear": "^4.41.1",
+    "@chat-adapter/slack": "^4.41.1",
     "@upstash/qstash": "^2.11.0",
     "@vercel/blob": "^2.8.0",
+    "@vercel/connect": "^2.3.4",
     "@vercel/queue": "*",
+    "chat": "^4.41.1",
     "ioredis": "^5.4.0",
     "pg": "^8.11.0"
   },
   "devDependencies": {
     "@base-ui/react": "^1.8.0",
+    "@chat-adapter/github": "^4.41.1",
+    "@chat-adapter/linear": "^4.41.1",
+    "@chat-adapter/slack": "^4.41.1",
     "@chat-adapter/tests": "^4.41.1",
     "@electric-sql/pglite": "0.3.15",
     "@kapso/chat-adapter": "^0.1.1",
@@ -129,7 +136,10 @@
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "@vercel/blob": "^2.8.0",
+    "@vercel/connect": "^2.3.4",
     "ai": "^7.0.130",
+    "chat": "^4.41.1",
+    "experimental-a2": "0.22.0",
     "ioredis": "5.11.1",
     "lucide-react": "^1.49.0",
     "pg": "^8.16.3",
@@ -143,15 +153,30 @@
     "vitest": "^5.0.3"
   },
   "peerDependenciesMeta": {
+    "@chat-adapter/github": {
+      "optional": true
+    },
+    "@chat-adapter/linear": {
+      "optional": true
+    },
+    "@chat-adapter/slack": {
+      "optional": true
+    },
     "@upstash/qstash": {
       "optional": true
     },
     "@vercel/blob": {
       "optional": true
     },
+    "@vercel/connect": {
+      "optional": true
+    },
     "@vercel/queue": {
       "optional": true
     },
+    "chat": {
+      "optional": true
+    },
     "ioredis": {
       "optional": true
     },