@vercel/board 0.0.0-stage → 0.15.0

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

@@ -0,0 +1,265 @@
+---
+title: Callbacks
+description: Decide what each inbound platform event becomes, and how board messages look on each platform.
+---
+
+## A function per mapping
+
+A string mapping imports every event into one channel. A function receives every
+inbound event for its external channel, connected threads included, and decides:
+
+```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 { github, GitHubPayload } from '@vercel/board/sync-github'
+
+const backend = a2({
+  store: postgres({ connectionString: process.env.DATABASE_URL! }),
+  scheduler: vercelQueues({ topic: 'board' }),
+})
+
+const team = board({
+  backend,
+  sync: {
+    github: github({
+      adapter: 'github/acme',
+      repos: {
+        'acme/www': async ({ event, board }) => {
+          const channel = event.subject.type === 'pull_request' ? 'prs' : 'issues'
+          await board.sync(channel, event, {
+            labels: { area: 'www' },
+            root: ({ raw }) => {
+              const payload = GitHubPayload.parse(raw)
+              const item = payload.pull_request ?? payload.issue
+              return { text: [item?.title, item?.body, item?.html_url].filter(Boolean).join('\n\n') }
+            },
+          })
+        },
+      },
+    }),
+  },
+})
+export const GET = team.fetch, POST = team.fetch
+export const { scheduler } = backend
+```
+
+`board.sync(channel, event)` applies the default import: the same thing a string
+mapping does, with the same provenance, files, links, state labels, and retries.
+Call it once, await it, and the event lands on the board. Don't call it, and the
+event is skipped; the thread stays connected, so later events still reach you.
+
+For an event in a thread that's already synced, the channel is ignored: the event
+lands in that thread. The channel only places new roots.
+
+The function's other writes through `board` (a reply, a label, a reaction, an
+edit or delete of the user's own message) are the platform user's, with the
+same provenance as the import, and go through the
+[middleware](../01-board/08-middleware.md) like it. Its reads, and anything
+else it does, are sync's own. It works the same on any backend, a board on
+`http()` included: there the writes land on the board it uses as imports.
+
+## The event
+
+Every event is an envelope, validated and frozen before your function sees 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. |
+| `channel`, `thread` | External IDs with the key prefix: `slack:C0123ABC`, `slack:C0123ABC:1727000000.123456`. `thread` is what `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`. |
+| `raw` | The platform's payload. |
+
+Then, by kind:
+
+- **`message`:** `message` (the platform's ID), `text` (markdown), `author`
+  (`{ id, handle, name, avatar, isBot }`), `isRoot`, `context` (a GitHub review
+  comment's `path:line`), and `files` and `links` when it has them.
+- **`edited`:** `message`, `text`, `author`, `links`.
+- **`deleted`:** `message`.
+- **`reaction`:** `message`, `emoji`, `added`, `author`.
+- **`lifecycle`:** `type`, `title`, `url`, `labels`, `reply`, and `author`. Only
+  GitHub sends these: see the [events table](./04-github.md#events).
+
+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`, and `WhatsAppEvent` from `@vercel/board/sync-kapso`.
+
+## Permalinks
+
+Every callback also gets `permalink()`, the platform's own link to the event's
+message. It's fetched on the first call and reused after, so callbacks that never
+ask don't cost an API request:
+
+```ts
+// in slack({ channels: { … } }): copy a report elsewhere, with a link back
+'#reports': async ({ event, board, permalink }) => {
+  if (event.kind === 'message' && event.isRoot)
+    await board.post('triage', `${event.text}\n\n${await permalink()}`)
+},
+```
+
+On Slack it calls `chat.getPermalink` with the provider's client, so the URL has
+the workspace's own host (Enterprise Grid included) and a reply's `thread_ts`. It
+only reads the URL: the thread isn't synced and no channel is joined. It returns
+`null` for a lifecycle event or a deleted message, and on platforms without
+links, and throws when Slack refuses, so the callback is retried.
+
+## Overrides
+
+The third argument changes the default import:
+
+| Override | Effect |
+| --- | --- |
+| `text` | Replaces the imported message's text. For a lifecycle event that creates a root and a reply, it replaces the reply; for one that only creates a root, it's the root's final text. |
+| `labels` | Merged into the thread root's labels. |
+| `unset` | Label keys removed from the root, applied last. |
+| `root` | A synchronous function that shapes a new root. It receives the default draft (`text`, `labels`, `author`, `raw`) and returns `{ text?, labels? }`. |
+| `noSync` | Keeps the imported reply on the board, like `vb reply --no-sync`: no other platform the thread syncs to gets it, now or in a backfill. A root it creates still syncs. |
+
+`root` runs whenever an import creates a root: a PR opening, or a comment on a PR
+the board hasn't seen, which recovers the root first. Its labels merge into the
+draft, then `labels` takes precedence, then `unset` removes keys. It can't change
+the author or other provenance.
+
+`noSync` keeps a GitHub PR's inline review threads out of its Slack thread, while
+top-level comments and reviews still go through:
+
+```ts
+// in github({ repos: { … } }):
+'acme/www': {
+  channel: 'prs',
+  run: async ({ event, board }) => {
+    await board.sync('prs', event, { noSync: event.subthread !== null })
+  },
+},
+```
+
+Platform reconciliation still applies on later events: GitHub's next event
+rewrites `state`, `review`, `tag.*`, and `assignee.*` unless you override them
+again.
+
+## The result
+
+`board.sync` returns `{ root, message }`, the board IDs it touched:
+
+- `root` is the thread's root.
+- `message` is the imported message, the message an edit, delete, or reaction
+  changed, or a lifecycle event's reply. A lifecycle event that only creates a root
+  returns the root; one that only changes labels returns `null`.
+- An event that can't apply (a reaction on a message the board never had) returns
+  `null` where no board message exists.
+
+Retried after it succeeded, it returns the same IDs.
+
+## More than an import
+
+`board` is a client of the board in this process, through `board()`, with the
+[handle's](../04-reference/02-board.md) methods, so a function can also reply,
+react, label, or attach:
+
+```ts
+// in slack({ channels: { … } }):
+'#support': async ({ event, board }) => {
+  const { root } = await board.sync('support', event)
+  if (event.kind === 'message' && event.isRoot && root !== null)
+    await board.label(root, { set: { status: 'new' } })
+},
+```
+
+Its writes are authored by the platform actor who triggered the event, like
+`slack:user:U0456`. It holds no token: `board()` makes its calls.
+
+## Reverse routing
+
+A bare function chooses a channel when an event arrives, so the board can't know
+which external channel a board root in `support` belongs to. Declare it:
+
+```ts
+// in slack({ channels: { … } }):
+'#support': {
+  channel: 'support',
+  run: async ({ event, board }) => {
+    await board.sync('support', event)
+  },
+},
+```
+
+Inbound events still go through `run`. A root posted in `support` on the board
+now starts a thread in `#support`, and replies flow both ways through the
+connection. Outgoing delivery never runs your function.
+
+## Retries and idempotency
+
+A function that throws is retried. Writes made through `board` take IDs derived
+from the inbox event and the order of calls, so a retry that writes in the same
+order doesn't post twice, and a default import that already succeeded returns its
+existing message. Two rules follow:
+
+- Writes made in parallel (`Promise.all`) need explicit `id`s.
+- Your own side effects aren't covered. Key them on `event.id`:
+
+```ts
+// in a callback, your side effect:
+// await createTicket(event, { idempotencyKey: event.id })
+```
+
+On `a2()`, a function that keeps throwing dead-letters after 10 tries. That
+holds up only its thread's lane in that channel's inbox; other threads and the
+board keep flowing. A board on `http()` gives the event up after 5. Calling
+`board.sync` after the function returns, twice, or with an event other than the
+one it received throws.
+
+## Render
+
+Every provider takes `render`, which decides the body of each board message it
+posts. It receives immutable copies of the message, as clients see it (its IDs
+are strings), and its author, the default label, and the resolved destination,
+and returns markdown:
+
+```ts
+// in kapso({ … }): post the text alone, without the author label
+render: ({ message }) => message.text,
+```
+
+The default is `**${label}**: ${message.text}`, where the label is the author's
+name: `claude via julian` for an agent profile, `ada (slack)` for a message that
+came from a platform. board still adds a line per attachment the platform
+didn't take, and converts mentions to the platform's own form after your
+function runs.
+
+A renderer can read labels. When a label change changes what a delivered copy
+renders to, board edits that copy, so a PR's root in Slack can show its state:
+
+```ts
+// in slack({ … }):
+render: ({ message, label }) =>
+  message.re === null && message.labels.state === 'merged'
+    ? `:pr-merged: ${message.text}`
+    : `**${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
+the author's name, so nobody gets pinged unless a renderer asks:
+
+```ts
+// in slack({ … }): a PR's root mentions its owner, or its author
+render: ({ message, label, mentionOf }) => {
+  const who = (message.labels.owner && mentionOf(message.labels.owner)) ?? mentionOf(message.by.actor)
+  return message.re === null && message.labels.pr && who
+    ? `${message.text} · ${who}`
+    : `**${label}**: ${message.text}`
+},
+```
+
+The default renderer reads no labels, so labels alone never edit a copy. Rendering
+applies to roots, replies, backfills, and edits; changing it affects future
+deliveries, not copies already sent. A subclass can override `render(input)`
+instead; see [custom providers](./06-providers.md).

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

@@ -0,0 +1,248 @@
+---
+title: Slack
+description: Mirror Slack channels into board channels, with threads, reactions, files, and agents posting under their own names.
+---
+
+## Configure it
+
+`slack({ adapter, channels })` takes a [Vercel Connect](./01-overview.md#set-up-webhooks)
+connector and a map of Slack channels, by name (`'#prs'`) or ID (`'C0123ABC'`), to
+[mappings](./01-overview.md#mappings):
+
+```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 { slack } from '@vercel/board/sync-slack'
+
+const backend = a2({
+  store: postgres({ connectionString: process.env.DATABASE_URL! }),
+  scheduler: vercelQueues({ topic: 'board' }),
+})
+
+const team = board({
+  backend,
+  sync: {
+    slack: slack({
+      adapter: 'slack/acme',
+      channels: {
+        '#errors-www': 'errors-www',
+        C0123ABC: 'dev',
+      },
+    }),
+  },
+})
+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.
+
+| Thing | ID |
+| --- | --- |
+| A channel | `slack:C0123ABC` |
+| A thread, named by its root's `ts` | `slack:C0123ABC:1727000000.123456` |
+
+The prefix is the entry's key, so a second workspace keyed `acme` reads
+`acme:C0999XYZ:1727000000.123456`.
+
+### Your own adapter
+
+Without Connect, pass a Chat SDK Slack adapter with the app's own secrets
+(`npm i chat @chat-adapter/slack`):
+
+```ts app/api/board/[[...path]]/route.ts
+import { createSlackAdapter } from '@chat-adapter/slack'
+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'
+
+const backend = a2({
+  store: postgres({ connectionString: process.env.DATABASE_URL! }),
+  scheduler: vercelQueues({ topic: 'board' }),
+})
+
+const team = board({
+  backend,
+  sync: {
+    slack: slack({
+      adapter: createSlackAdapter({
+        botToken: process.env.SLACK_BOT_TOKEN!,
+        signingSecret: process.env.SLACK_SIGNING_SECRET!,
+      }),
+      channels: { '#prs': 'prs' },
+    }),
+  },
+})
+export const GET = team.fetch, POST = team.fetch
+export const { scheduler } = backend
+```
+
+An adapter whose `botToken` is a function (minted per call) also needs a `client`
+resolver that returns the adapter's web client with a fresh token, or setup fails.
+A static-token adapter can leave it out; board uses the adapter's own web client.
+
+## Channels
+
+Slack only sends a channel's events to apps in it. When a mapped channel resolves,
+the app joins it if it's public. A private channel needs someone to `/invite` the
+app, and the log names each one that does.
+
+Name lookups list channels once and cache the result. Private channels show up by
+name only with `groups:read`; Vercel Connect's Slack app doesn't request it, so map
+a private channel by its ID. A name that doesn't resolve is skipped and retried at
+most once a minute, while the other channels sync.
+
+## What syncs
+
+- **Messages, replies, edits, deletes, and reactions,** both ways. Slack's mrkdwn
+  arrives as markdown, and the board's markdown posts back as Slack formatting.
+- **Mentions** round-trip. `<@U0456>` resolves to `slack:user:U0456` on the way
+  in, and a board mention of a Slack user posts as `<@U0456>`. A board message can
+  mention someone by email, `@[ada@acme.com]`, and Slack looks them up (it needs
+  `users:read.email`). See [mentions](../01-board/03-identity.md#mentions).
+- **Other bots' messages,** from Sentry or Vercel alerts, sync like anyone's. Only
+  the board's own posts are skipped.
+- **Typing:** `team.typing('812', 'running tests…')`, or
+  `vb typing 812 running tests…`, sets the thread's status in Slack, under the
+  thread, until the app posts or about two minutes pass. The status is at most
+  100 characters; without one, Slack shows "Typing…".
+
+## Agents post under their own names
+
+A message from an agent profile goes to Slack with the agent as its sender
+(`claude via julian`), and the `**name**: ` label it would open with is left out.
+Its avatar is the agent's own picture when it's an https image Slack can show.
+An agent with the board's built-in avatar (an SVG, which Slack won't show) takes
+the Vercel avatar of the person it works for, so `claude via julian` shows
+Julian: the picture their CLI sent when they posted as themselves, or else one
+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.
+An edit leaves the label out only where Slack shows the message under the
+agent's name.
+
+## Files
+
+**From Slack:** a file posted in a synced thread becomes a board attachment. When
+the message lands, board fetches each file through the adapter (it needs
+`files:read`) and stores it in the board's blob store. A file that can't come
+over gets a line in the text instead, and the message still lands:
+
+```text
+📎 run.mov (50.0 MB) didn't come over: over 25 MB
+```
+
+That covers files over 25 MB (sync fetches a file on the server, so it isn't held to
+the 4 MB an upload is) and a fetch that fails three times. A board
+[without a blob store](../01-board/01-mounting.md#without-a-blob-store) keeps no
+files, so each one is a line that links it where it lives in Slack, for people
+who can see it there:
+
+```text
+📎 [shot.png](https://files.slack.com/…) (7 B) didn't come over: this board keeps no files
+```
+
+**To Slack:** the text posts first, then the files upload into the same thread as a
+message of their own (it needs `files:write`). A failed upload retries alone, and
+deleting the message on the board deletes the files in Slack. If Slack refuses
+files, the text is edited to add a line per file:
+
+```text
+📎 after.png (17 KB, on the board: #812)
+```
+
+Slack picks a file's type from its extension and offers any it doesn't know
+(`.log`, `.ndjson`) as a binary download. So a text file with such a name uploads
+with `.txt` appended (`deepsec.log.txt`), which Slack previews; the board keeps
+the file's own name.
+
+## Message links
+
+A Slack permalink in a message becomes one of the message's links; its text stays
+as written. `vb read` and `vb inspect` quote each one under the message.
+
+- A link to a message the board has (it was synced, either way) in the same
+  board channel is that board message, `#812`, with a snapshot of it. One in
+  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.
+- 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.
+- A forwarded message links the message it shares, with a snapshot of it. A
+  forward with no text of its own imports as the shared message, quoted, with
+  its link: `> **Ada**: deploys are down`.
+
+Snapshots are what the message said when the link arrived. Files in them are
+linked, not copied.
+
+## Read on demand
+
+The board that runs a Slack entry can read a channel it doesn't sync, for
+research or a reference, without syncing it. Only that board has the app to
+read with, so ask it: its own code, through its handle, `vb sources slack read`
+on the board you link, or a request to its `GET /sources/slack/read?target=…`.
+A board that doesn't run the entry answers 404 `not_synced_here`.
+
+```ts
+// in the route that mounts the board with `sync: { slack }`:
+const recent = await team.readSource('slack', '#general')                          // newest 50, oldest first
+await team.readSource('slack', 'C0123ABC', { limit: 20 })
+await team.readSource('slack', 'C0123ABC:1727000000.123456')                       // a thread; a reply's ts reads its whole thread
+await team.readSource('slack', 'https://acme.slack.com/archives/C0123ABC/p1727000000123456')
+```
+
+It reads only public channels the app is already in, and never joins one. Nothing
+is stored, and reading a channel doesn't make the board listen to it. A request
+needs `manage` in every channel, since the app's token reads more than the
+caller might.
+
+| Answer | Why |
+| --- | --- |
+| 403 `private_channel` | A private channel or DM. |
+| 403 `shared_channel` | A Slack Connect channel, shared with another organization. |
+| 403 `not_in_channel` | The app isn't in it. Someone adds it on purpose. |
+| 404 `channel_not_found` | No such channel, by name or ID. |
+| 429 `ratelimited` | Slack is rate-limiting the app. |
+
+## Setup
+
+With Vercel Connect, create a Slack connector and attach its trigger to
+`/api/board/webhooks/slack` (see [webhooks](./01-overview.md#set-up-webhooks)).
+To create the app yourself:
+
+1. Create a Slack app.
+2. Set its Event Subscriptions request URL to
+   `https://<host>/api/board/webhooks/slack`.
+3. Subscribe to the bot events `message.channels`, `message.groups`,
+   `reaction_added`, and `reaction_removed`.
+4. Add the scopes below, install the app, and set `SLACK_BOT_TOKEN` and
+   `SLACK_SIGNING_SECRET`.
+
+| Scope | For |
+| --- | --- |
+| `channels:history`, `groups:history` | Reading messages, links, and threads |
+| `channels:read` | Looking up channels by name |
+| `groups:read` | Looking up private channels by name |
+| `channels:join` | Joining mapped public channels |
+| `chat:write` | Posting |
+| `chat:write.customize` | Agents posting under their own names |
+| `reactions:read`, `reactions:write` | Reactions both ways |
+| `users:read` | Names and avatars |
+| `users:read.email` | Mentions by email |
+| `files:read`, `files:write` | Files both ways |
+
+## Limits
+
+Slack's `chat.postMessage` takes no idempotency key. If the function dies after
+Slack accepts a post but before the board records it, the retry can post a
+duplicate.