@vercel/board 0.30.0 → 0.31.0

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

@@ -28,6 +28,30 @@ with them. It writes to one channel, `conformance` (`--channel`, or
 `{ channel }`), with every post kept on the board, labeled with the run's own
 `conformance=<id>`, and deletes what it posted when it's done.
 
+To check that a token does only what its `can` says, it calls the board with
+one it mints, through `withToken(secret)`: the same board, with that secret as
+the credential, as `BOARD_TOKEN` sends it. `vb conformance` passes it; from
+code, pass your own, or that check is skipped:
+
+```ts scripts/conformance.ts
+import { board } from '@vercel/board'
+import { http } from '@vercel/board/backend-http'
+import { conformance } from '@vercel/board/conformance'
+
+const url = 'https://board.example.com/api/board'
+const withToken = (secret: string) =>
+  board({
+    backend: http(url, {
+      fetch: (input, init) => {
+        const headers = new Headers(init?.headers)
+        headers.set('authorization', `Bearer ${secret}`)
+        return fetch(input, { ...init, headers })
+      },
+    }),
+  })
+const report = await conformance(board({ backend: http(url) }), { withToken })
+```
+
 ## What it checks
 
 The whole protocol, on every board:
@@ -55,6 +79,9 @@ The whole protocol, on every board:
   until the next one.
 - **A delete leaves a tombstone.**
 - **Channels and actors** list the channel it posted in, and you.
+- **Creating a channel** a post made answers `created: false`, and a path
+  that isn't one is 400. It creates none of its own, since a board keeps every
+  channel.
 - **Errors:** an ID that names nothing is 404 `message_not_found`, and a
   request that doesn't validate is 400 `invalid_request`.
 
@@ -63,15 +90,17 @@ Then the rest, a group each in the report:
 | Group | Check |
 | --- | --- |
 | `schedules` | schedules a reply a day out, lists it, and cancels it; and keeps a schedule's `noSync`, so its sends stay off every platform |
+| `grants` | grants a project that doesn't exist, lists it, takes the same issuer and claims again as one grant, revokes it twice, and changes a grant's `can` by creating it again. Grants a GitHub repository's workflows and another team's project, and keeps two environments of one project as two grants. Skipped when the token can't change the board's grants |
+| `tokens` | mints a token for an hour that reads the channel, checks its `can` and its expiry, lists it without its secret, and revokes it twice. Then, with another one's secret: `/me` names its minter and only what it may read, it reads the channel and can't post there, and once it's revoked, it's refused with a 401 |
 | `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, lists where the thread is synced with it, answers 404 for a link no sync there knows, and deletes it. Pushes two events on one platform thread to the sync's inbox, and the first again, then leases them one at a time and in order, each once the one before is acked. Pulls the sync's `@sync` match for a post. Each of these is skipped when the token can't register a sync or `sync` in the channel, or already has watchers or a sync registered. Then, registering nothing: reads a post's and a reply's `noSync` back, and finds no one linked to a platform account nobody linked |
+| `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. Pushes two events on one platform thread to the sync's inbox, and the first again, then leases them one at a time and in order, each once the one before is acked. Pulls the sync's `@sync` match for a post. Each of these is skipped when the token can't register a sync or `sync` in the channel, or already has watchers or a sync registered. Then, registering nothing: reads a post's and a reply's `noSync` back |
 
 Every board answers all of them: see
 [the whole protocol](./03-http.md#the-whole-protocol). A board may keep no
-schedules or no files, and say so: one that answers the schedules or
-attachments check with a 501 has it skipped, `not kept here`, with what the
-board said. A board on `a2()` without a `scheduler` answers 501
+schedules, grants, or files, or issue no tokens, and say so: one that answers
+one of those groups' checks with a 501 has it skipped, `not kept here`, with
+what the board said. A board that's meant to keep them and doesn't yet answers otherwise, and fails: Vercel's boards fail both groups until Vercel's API keeps grants and tokens. A board on `a2()` without a `scheduler` answers 501
 `no_scheduler`, and without a `blob` 501 `no_files`: see
 [Mounting](../01-board/01-mounting.md#without-a-scheduler). `vb serve` keeps
 both, so it passes every check.
@@ -89,7 +118,7 @@ attachments
   skipped  takes a file, posts it, and gives it back
            not kept here: this board keeps no files: pass `blob` to `a2()`
 …
-21 passed, 3 skipped
+26 passed, 3 skipped
 ```
 
 ## The report
@@ -97,7 +126,7 @@ attachments
 ```ts
 type ConformanceReport = {
   url: string
-  checks: { group: 'core' | 'schedules' | 'attachments' | 'watchers' | 'sync'; name: string; status: 'passed' | 'failed' | 'skipped'; detail?: string }[]
+  checks: { group: 'core' | 'schedules' | 'grants' | 'tokens' | 'attachments' | 'watchers' | 'sync'; name: string; status: 'passed' | 'failed' | 'skipped'; detail?: string }[]
   ok: boolean // nothing failed
 }
 ```

package/docs/index.md

@@ -1,6 +1,6 @@
 ---
 title: Introduction
-description: 'A message board you mount in one route: one durable log, verified authors, a live tail, and two-way sync with Slack, GitHub, and WhatsApp.'
+description: 'A message board you mount in one route: one durable log, verified authors, a live tail, and two-way sync with Slack, GitHub, Linear, and any platform with a Chat SDK adapter.'
 ---
 
 ```bash
@@ -72,7 +72,7 @@ export const { scheduler } = backend
 
 [Vercel Connect](./02-sync/01-overview.md#set-up-webhooks) holds the Slack
 and GitHub credentials, so the board keeps no platform secrets. board builds
-the adapters from the connector names, and people who sign in post as themselves. A Slack reply,
+the adapters from the connector names. A Slack reply,
 a PR review comment, and `vb reply` land in the same thread, and each one
 reaches the others. A PR's root carries its state as labels
 (`state=open`, `review=approved`), so an agent can wait on GitHub without

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/board",
-  "version": "0.30.0",
+  "version": "0.31.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",
@@ -97,9 +97,9 @@
       "types": "./dist/sync.d.mts",
       "default": "./dist/sync.mjs"
     },
-    "./sync/chat": {
-      "types": "./dist/sync.chat.d.mts",
-      "default": "./dist/sync.chat.mjs"
+    "./sync-chat-sdk": {
+      "types": "./dist/sync-chat-sdk.d.mts",
+      "default": "./dist/sync-chat-sdk.mjs"
     },
     "./sync-slack": {
       "types": "./dist/sync-slack.d.mts",
@@ -109,10 +109,6 @@
       "types": "./dist/sync-github.d.mts",
       "default": "./dist/sync-github.mjs"
     },
-    "./sync-kapso": {
-      "types": "./dist/sync-kapso.d.mts",
-      "default": "./dist/sync-kapso.mjs"
-    },
     "./sync-linear": {
       "types": "./dist/sync-linear.d.mts",
       "default": "./dist/sync-linear.mjs"
@@ -138,12 +134,13 @@
   },
   "devDependencies": {
     "@base-ui/react": "^1.8.0",
+    "@chat-adapter/discord": "4.41.1",
     "@chat-adapter/github": "^4.41.1",
     "@chat-adapter/linear": "^4.41.1",
     "@chat-adapter/slack": "^4.41.1",
+    "@chat-adapter/telegram": "4.41.1",
     "@chat-adapter/tests": "^4.41.1",
     "@electric-sql/pglite": "0.3.15",
-    "@kapso/chat-adapter": "^0.1.1",
     "@types/node": "^26.6.3",
     "@types/pg": "8.15.5",
     "@types/react": "^19.3.0",

package/sql/postgres/board.sql

@@ -74,7 +74,7 @@ create table if not exists board_external_messages (
   message_id bigint not null
 );
 --> statement-breakpoint
-create index if not exists board_messages_recent on board_messages (by_principal, created_at) where re is null;
+drop index if exists board_messages_recent;
 --> statement-breakpoint
 drop function if exists board_apply(text, bigint, boolean, jsonb, jsonb, jsonb);
 --> statement-breakpoint

package/sql/postgres/schema.sql

@@ -380,7 +380,7 @@ create table if not exists board_external_messages (
   message_id bigint not null
 );
 --> statement-breakpoint
-create index if not exists board_messages_recent on board_messages (by_principal, created_at) where re is null;
+drop index if exists board_messages_recent;
 --> statement-breakpoint
 drop function if exists board_apply(text, bigint, boolean, jsonb, jsonb, jsonb);
 --> statement-breakpoint

package/dist/events-qf5XG5VQ.mjs

@@ -1,75 +0,0 @@
-import { d as LabelKey, p as Labels } from "./schemas-DBmUO6pr.mjs";
-import { n as ExternalEvent, r as ExternalLocation } from "./external-D3p5T57R.mjs";
-import { z } from "zod";
-//#region src/sync/events.ts
-const EventBase = z.object({
-	id: z.string().min(1),
-	platform: z.string().min(1),
-	key: z.string().min(1),
-	...ExternalLocation.shape,
-	raw: z.unknown()
-});
-const eventTypes = {
-	message: "message",
-	edited: "message.edited",
-	deleted: "message.deleted",
-	reaction: "reaction.added",
-	lifecycle: "lifecycle"
-};
-function envelope(platform, key, event, raw, id) {
-	return {
-		...event,
-		...EventBase.parse({
-			id,
-			platform,
-			key,
-			channel: event.channel,
-			thread: event.thread,
-			subthread: "subthread" in event ? event.subthread : null,
-			raw
-		}),
-		type: event.kind === "lifecycle" ? event.type : event.kind === "reaction" && !event.added ? "reaction.removed" : eventTypes[event.kind]
-	};
-}
-function eventSchema(platform, messageType) {
-	const [message, edited, deleted, reaction, lifecycle] = ExternalEvent.options;
-	const common = {
-		...EventBase.shape,
-		platform: z.literal(platform)
-	};
-	return z.discriminatedUnion("kind", [
-		message.extend({
-			...common,
-			type: z.literal(messageType)
-		}),
-		edited.extend({
-			...common,
-			type: z.literal("message.edited")
-		}),
-		deleted.extend({
-			...common,
-			type: z.literal("message.deleted")
-		}),
-		reaction.extend({
-			...common,
-			type: z.enum(["reaction.added", "reaction.removed"])
-		}),
-		lifecycle.extend(common)
-	]);
-}
-const SyncOverrides = z.object({
-	root: z.custom((value) => typeof value === "function").optional(),
-	text: z.string().optional(),
-	labels: Labels.optional(),
-	unset: z.array(LabelKey).optional(),
-	noSync: z.boolean().optional()
-}).strict();
-function immutable(value) {
-	if (value && typeof value === "object") {
-		for (const item of Object.values(value)) immutable(item);
-		Object.freeze(value);
-	}
-	return value;
-}
-//#endregion
-export { immutable as a, eventSchema as i, SyncOverrides as n, envelope as r, EventBase as t };

package/dist/exports-CrGA5_yN.d.mts

@@ -1,5 +0,0 @@
-import "./auth-CU56Q2Xh.mjs";
-import "./folds-8wRRXjAt.mjs";
-import "./client-CjAatpV4.mjs";
-import "./backend-n3hajfrD.mjs";
-import "./errors-87TVtXeb.mjs";

package/dist/sync-kapso.mjs

@@ -1,89 +0,0 @@
-import { s as channels } from "./provider-BaVmi4Hi.mjs";
-import { i as eventSchema, r as envelope } from "./events-qf5XG5VQ.mjs";
-import { r as markdownOf, t as ChatSyncProvider } from "./chat-provider-COtsU5jB.mjs";
-import { z } from "zod";
-//#region src/sync/kapso.ts
-const decode = (id) => id.split(":").map((part) => Buffer.from(part, "base64url").toString("utf8")).join(":");
-const encode = (id) => id.split(":").map((part) => Buffer.from(part, "utf8").toString("base64url")).join(":");
-const WhatsAppEvent = eventSchema("whatsapp", "message");
-/**
-* Syncs WhatsApp numbers on Kapso with the board: `sync` is what each event
-* does, both ways, like `numbers({ '16315558151': 'support' })`. Each Kapso
-* conversation is a thread. WhatsApp has no threads in a number, so a board
-* thread never starts one: a board root in a mirrored channel stays on the board.
-*/
-function kapso(options, sync) {
-	return new KapsoProvider(options, sync);
-}
-/**
-* Routes each event by its WhatsApp number. Keys are phone number IDs (`'16315558151'`), not
-* the numbers; values are a board channel to `mirror`, or a sync function.
-*/
-const numbers = (map) => channels(map);
-var KapsoProvider = class extends ChatSyncProvider {
-	constructor(options, sync) {
-		if (typeof options.markRead !== "function") throw new Error("kapso requires a public markRead operation for cross-instance read and typing");
-		const fileIds = (raw) => (raw?.responses ?? []).flatMap((response) => response.messages?.[0]?.id ?? []);
-		super({
-			fileIds,
-			platform: "whatsapp",
-			adapter: options.adapter,
-			canStartThreads: false,
-			async uploadFiles(thread, files) {
-				const sent = await options.adapter.postMessage(thread, {
-					markdown: "",
-					files
-				});
-				return {
-					message: sent.id,
-					files: fileIds(sent.raw)
-				};
-			},
-			refusesFiles: (error) => error?.code === "VALIDATION_ERROR",
-			async resolveChannel(key) {
-				if (!/^\d+$/.test(key)) throw new Error(`${key} isn't a phone number ID; use the number's ID from Kapso, not the number`);
-				return key;
-			},
-			fromChatId: decode,
-			toChatId: encode,
-			singleReaction: true,
-			async startTyping(thread, latest) {
-				if (!latest) return options.adapter.startTyping(thread);
-				const [phoneNumberId] = decode(thread.slice(thread.indexOf(":") + 1)).split(":");
-				await options.markRead({
-					phoneNumberId,
-					messageId: latest,
-					typingIndicator: { type: "text" }
-				});
-			},
-			groupThread: (thread) => thread,
-			isRoot: () => false,
-			context: () => null,
-			markdown(message) {
-				const text = markdownOf(message);
-				const transcript = message.raw?.kapso?.transcript?.text;
-				return [text, typeof transcript === "string" && transcript.trim() && transcript !== text ? `> ${transcript.trim()}` : null].filter(Boolean).join("\n\n");
-			},
-			async resolveTarget(target) {
-				const parts = target.split(":");
-				if (!/^\d+$/.test(parts[0]) || parts.length !== 1 && parts.length !== 3) throw new Error(`invalid Kapso target: ${target}`);
-				return {
-					target,
-					channel: parts[0],
-					kind: parts.length === 1 ? "channel" : "thread"
-				};
-			}
-		}, sync);
-	}
-	eventId(key, input) {
-		if (input.kind !== "reaction") return super.eventId(key, input);
-		const reaction = input.reaction;
-		const stamp = z.looseObject({ id: z.string().min(1) }).parse(reaction.raw).id;
-		return `reaction:${key}:${this.toNative(reaction.threadId)}|${reaction.messageId}|${reaction.rawEmoji}|${reaction.user.userId}|${reaction.added}|${stamp}`;
-	}
-	event(context) {
-		return WhatsAppEvent.parse(envelope(this.platform, context.key, context.event, context.raw, context.id));
-	}
-};
-//#endregion
-export { KapsoProvider, WhatsAppEvent, kapso, numbers };

package/dist/sync.chat.d.mts

@@ -1,2 +0,0 @@
-import { i as externalAuthor, n as ChatSyncProvider, r as ChatTransport, t as ChatInput } from "./chat-provider-D6jVT4wS.mjs";
-export { ChatInput, ChatSyncProvider, ChatTransport, externalAuthor };

package/dist/sync.chat.mjs

@@ -1,2 +0,0 @@
-import { n as externalAuthor, t as ChatSyncProvider } from "./chat-provider-COtsU5jB.mjs";
-export { ChatSyncProvider, externalAuthor };

package/dist/users-yryHKFMo.mjs

@@ -1,42 +0,0 @@
-//#region src/sync/users.ts
-const USER_TOKENS = Symbol.for("board.userTokens");
-/**
-* Gives an adapter people's tokens, for your own OAuth: `slack({ adapter:
-* withUserTokens(createSlackAdapter(...), { authorize, token }) }, sync)`. A
-* Connect connector name (`slack('slack/acme', sync)`) does this for you.
-*/
-function withUserTokens(adapter, tokens) {
-	Object.defineProperty(adapter, USER_TOKENS, {
-		value: tokens,
-		enumerable: false,
-		configurable: true
-	});
-	return adapter;
-}
-const userTokensOf = (adapter) => adapter[USER_TOKENS] ?? null;
-/** Vercel Connect's user tokens for `connector`: the subject is the board's principal, so Connect binds the account to it. */
-function connectUserTokens(connector) {
-	const subject = (principal) => ({ subject: {
-		type: "user",
-		id: principal
-	} });
-	return {
-		async authorize(principal, options = {}) {
-			const { startAuthorization } = await import("@vercel/connect");
-			return (options.callback ? await startAuthorization(connector, subject(principal), { callbackUrl: options.callback }) : await startAuthorization(connector, subject(principal))).url;
-		},
-		async token(principal) {
-			const { getToken, NoValidTokenError, UserAuthorizationRequiredError } = await import("@vercel/connect");
-			try {
-				return await getToken(connector, subject(principal));
-			} catch (error) {
-				if (error instanceof UserAuthorizationRequiredError || error instanceof NoValidTokenError) return null;
-				const code = error.code;
-				if (code === "user_authorization_required" || code === "no_token") return null;
-				throw error;
-			}
-		}
-	};
-}
-//#endregion
-export { userTokensOf as n, withUserTokens as r, connectUserTokens as t };

package/docs/02-sync/05-whatsapp.md

@@ -1,152 +0,0 @@
----
-title: WhatsApp
-description: Sync WhatsApp conversations on a business number with board threads, through Kapso.
----
-
-## Configure it
-
-```package-install
-npm i chat @kapso/chat-adapter @kapso/whatsapp-cloud-api
-```
-
-`kapso({ adapter, markRead }, sync)` takes
-[Kapso's Chat SDK adapter](https://chat-sdk.dev/adapters/vendor-official/kapso),
-a read operation, and a [sync function](./02-functions.md). `numbers` makes one
-from a map of WhatsApp phone number IDs to board channels (two-way mirrors) or
-functions of your own:
-
-```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 { kapso, numbers } from '@vercel/board/sync-kapso'
-import { createKapsoAdapter } from '@kapso/chat-adapter'
-import { WhatsAppClient } from '@kapso/whatsapp-cloud-api'
-
-const client = new WhatsAppClient({
-  baseUrl: 'https://api.kapso.ai/meta/whatsapp',
-  kapsoApiKey: process.env.KAPSO_API_KEY!,
-})
-
-const backend = a2({
-  store: postgres({ connectionString: process.env.DATABASE_URL! }),
-  scheduler: vercelQueues({ topic: 'board' }),
-})
-
-const team = board({
-  backend,
-  sync: {
-    kapso: kapso(
-      {
-        adapter: createKapsoAdapter({ client }),
-        markRead: (input) => client.messages.markRead(input),
-      },
-      numbers({ '16315558151': 'support' }),
-    ),
-  },
-})
-export const GET = team.fetch, POST = team.fetch
-export const { scheduler } = backend
-```
-
-Keys are phone number IDs as Kapso shows them, not the phone numbers themselves.
-A key that isn't one is skipped with a warning that says so.
-
-`markRead` is required at setup. The adapter only remembers messages whose webhook
-reached its own instance, so typing and read receipts go through this operation
-instead, which works from any serverless instance.
-
-| Thing | ID |
-| --- | --- |
-| A business number, the channel | `kapso:16315558151` |
-| A Kapso conversation, a thread | `kapso:16315558151:<WhatsApp ID>:<conversation ID>` |
-
-Kapso's adapter encodes each part of its IDs; the board writes them decoded, so
-targets and `vb inbox` read as above.
-
-## Conversations are threads
-
-WhatsApp has no threads, so a contact's messages group into Kapso's conversations.
-One starts when they write, and ends after a day of quiet or when someone closes it
-in Kapso. Writing again after that starts a new board thread.
-
-- **Authors** are `whatsapp:user:<WhatsApp ID>`, named by their WhatsApp profile
-  name.
-- **The board never starts a conversation.** A number has no threads to start, so
-  a root posted in a mirrored channel stays on the board.
-- **Board messages post from the business number,** with the author's name in bold
-  (`*julian*: refunded`). To post the text alone, wrap the function in
-  `render(({ message }) => message.text, …)`; see [render](./02-functions.md#render).
-
-## Reply within the window
-
-WhatsApp takes free-form messages only within 24 hours of the contact's last one.
-A board reply after that fails, and is recorded as `message.sync_failed`, which
-`vb read` shows under it:
-
-```text
-✗ didn't reach kapso:16315558151:51987654321:conv_123: <WhatsApp's error>
-```
-
-Templates aren't synced; send them with `@kapso/whatsapp-cloud-api`.
-
-## Reactions
-
-WhatsApp keeps one reaction per person per message. A contact's new reaction
-replaces their old one on the board, and removing it clears it. The business number
-has one too: the board's reactions on a WhatsApp message show there as the latest
-one added, and removing any of them clears it.
-
-## Media
-
-An image, video, voice note, or document becomes an attachment on the board,
-fetched through Kapso, with its caption as the text. A voice note's transcript is
-quoted under it when Kapso has one. A board without a blob store keeps no files:
-each is a line in the text instead, as on [Slack](./03-slack.md#files).
-
-A board message's files follow its text to WhatsApp, each as its own message.
-WhatsApp can't delete them, so they stay when the board message is deleted.
-
-## Typing
-
-```ts
-// in the route that mounts the board with its `sync`:
-await team.typing('812')
-```
-
-Shows "typing…" to the contact and marks their latest message read (blue ticks).
-WhatsApp shows no status text, so a status is ignored.
-
-## Route by function
-
-A function for a number receives every event for it, both ways. Importing a
-message into a channel connects its conversation, and delivering sends board
-replies in that thread to the contact:
-
-```ts
-// in kapso({ … }, numbers({ … })):
-'16315558151': async (sync) => {
-  if (sync.direction === 'out') return sync.deliver()
-  if (sync.event.kind !== 'message') return
-  await sync.import('leads', { text: `${sync.event.author.name}: ${sync.event.text}` })
-},
-```
-
-See [sync functions](./02-functions.md) for the event and the overrides.
-
-## What doesn't sync
-
-- Edits and deletes, which WhatsApp can't do for recipients.
-- Button and list replies.
-
-## Setup
-
-1. In Kapso, create an API key and copy the number's phone number ID.
-2. Add a webhook with the URL `https://<host>/api/board/webhooks/kapso`, a secret
-   key, and the `whatsapp.message.received` event.
-3. Set `KAPSO_API_KEY` and `KAPSO_WEBHOOK_SECRET`, or pass `webhookSecret` to
-   `createKapsoAdapter`. Without the secret, the adapter rejects every webhook.
-
-The webhook path ends in the entry's key, so an entry keyed `kapso` listens at
-`/webhooks/kapso`.