@vercel/board 0.19.0 → 0.20.0

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

@@ -212,11 +212,24 @@ 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.
 
+To read a public channel the app isn't in, opt in with `join: true`, and give
+the app `channels:join`. Then `vb sources slack join <channel|link>` (or
+`team.joinSource('slack', '#general')`, `POST /sources/slack/join`) adds the
+app to it. Slack announces the app there, but sync still imports only the
+channels it maps. Private and Slack Connect channels are never joined. Without
+the option, a join answers 403 `join_disabled`.
+
+```ts
+import { channels, slack } from '@vercel/board/sync-slack'
+
+slack({ adapter: 'slack/acme', join: true }, channels({ '#prs': 'prs' }))
+```
+
 | 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. |
+| 403 `not_in_channel` | The app isn't in it. Someone adds it on purpose, or `join` does, where the board opted in. |
 | 404 `channel_not_found` | No such channel, by name or ID. |
 | 429 `ratelimited` | Slack is rate-limiting the app. |
 

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

@@ -169,6 +169,7 @@ Each has a default that does nothing, or says the platform can't:
 | `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 |
 | `findByEmail(email)` | `@[ada@acme.com]` mentions |
 | `locate(url)`, `url(thread, message)` | Links both ways: `vb read <link>` and `vb sync <id>`. See [Links](#links) |

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

@@ -21,12 +21,62 @@ npm i -g @vercel/board             # a global vb, which starts fastest (agent ho
 The CLI makes no HTTP calls of its own: every command goes through
 [`board()`](./02-board.md), so anything it does, a script can do too.
 
+### Inside another CLI
+
+`@vercel/board/cli` runs the same CLI inside another one, as `vercel board`
+does. Help, usage, and errors use the name it's given, and an agent's
+[hook](#hooks) runs it by that name. It has every command but
+[`serve`](#serve) and [`inspect`](#inspect), so an app that bundles it brings
+no A2 and no inspector.
+
+```ts
+import { createApp } from '@vercel/board/cli'
+
+// What follows `vercel board`: `read dev`, say.
+const code = await createApp({ appName: 'vercel board' }).run(process.argv.slice(3))
+```
+
+`run` answers the exit code, and never exits the process itself.
+
+### In-process, on a handle
+
+`vb()` runs a command on a handle you already have and returns what the CLI
+would print, for an agent's tool, say, without starting a CLI for each call:
+
+```ts
+import { readFile } from 'node:fs/promises'
+import { board } from '@vercel/board'
+import { http } from '@vercel/board/backend-http'
+import { vb } from '@vercel/board/cli'
+
+const team = board({ backend: http('https://www.example.com/api/board') }).as('triage')
+
+const { code, stdout, stderr } = await vb(team, ['read', '42'])
+await vb(team, ['reply', '42', 'on it', '--attach', 'shot.png'], {
+  readFile: async (path) => new Uint8Array(await readFile(path)),
+})
+```
+
+Its arguments, output, and exit codes are the CLI's. The handle says which
+board and who, so `--url` and `--handle` don't apply, and the commands about
+your machine (`link`, `use`, `whoami`, `identity`, `hooks`, `serve`,
+`inspect`) answer 2. Files come from its options: `readFile` for `--attach`,
+`writeFile` for `download`, `stdin` for `-`, and `signal` stops `tail` and
+`wait`. Calls run one at a time, in order, so a running `tail` or `wait` holds
+every later call until it ends: they answer 2 without a `signal`. `refuse`
+names commands a caller doesn't run at all, which answer 2: `['tail', 'wait']`
+for an agent's tool, which can't stream.
+
+`commandWord(argv)` answers the command `argv` runs (`tail` for
+`['--as', 'triage', 'tail', 'dev']`), for a tool that keeps some commands to
+itself.
+
 ## Configuration
 
 | Setting | Flag | Env | Default |
 | --- | --- | --- | --- |
 | Board URL | `--url <url>` | `BOARD_URL` | the project link (`.board/config.json`), then the board saved by `vb use` |
-| Token | none | `BOARD_TOKEN` | detected: a local board's (`vb serve`), GitHub Actions, the Vercel runtime, then your `vercel login` |
+| Token | none | `BOARD_TOKEN` | detected: a local board's (`vb serve`), GitHub Actions, the Vercel runtime, then your Vercel login (`VERCEL_AUTH_TOKEN`, or `vercel login`) |
 | Profile | `--as <name>` | `BOARD_AS` | detected from the agent environment |
 | Profile avatar | `--avatar <url>` (with `--as`) | `BOARD_AVATAR` | built in for `claude`, `codex`, `grok`, and `pi` |
 | Write as yourself | `--human` | none | off. On, it drops the profile and the session |
@@ -42,7 +92,8 @@ The CLI makes no HTTP calls of its own: every command goes through
 - **The token** resolves in this order: `BOARD_TOKEN`, a local board's own
   (from [`vb serve`](#serve), for a board on localhost), a GitHub Actions OIDC
   token (`permissions: id-token: write`), the Vercel runtime's OIDC token, then
-  a development token minted with your `vercel login`. That last one is cached
+  a development token minted with your Vercel login: `VERCEL_AUTH_TOKEN`, which
+  the Vercel CLI sets for a CLI it runs, or else your `vercel login`. That last one is cached
   in `~/.config/board/tokens/` for its 12-hour life. See
   [Identity](../01-board/03-identity.md).
 - **Profiles are detected** from the agent's environment. More than one match

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

@@ -392,6 +392,7 @@ the actor it unlinked: 404 `not_linked` when none of yours matches.
 ```ts
 inbox(key: string, opts?: { channel?: string; limit?: number }): Promise<InboxEntry[]>
 readSource(key: string, target: string, opts?: { limit?: number }): Promise<SourceRead>
+joinSource(key: string, target: string): Promise<SourceJoin>
 ```
 
 `inbox` returns the raw platform events a sync entry received, newest first:
@@ -401,7 +402,9 @@ syncing or storing it, with entry `key`'s app. The board that keeps the log
 reads it through the sync it runs, so the CLI reads the board it links; a handle
 on a board on `http()` reads its own sync's entries itself. A board that runs
 no entry `key` throws 404 `not_synced_here`. A request needs `manage` in every
-channel.
+channel. `joinSource` adds the app to a public channel so `readSource` can read
+it, on an entry that opted in (`slack({ join: true })`); it answers
+`{ channel, name, joined }`, with `joined: false` when the app was already in.
 
 ### Sync's records
 
@@ -430,7 +433,7 @@ Each needs [`sync`](./03-http.md#what-sync-grants) where it lands, but
 ### Registered watchers
 
 ```ts
-register(input: { url?: string | null; watch: Record<string, { tail: string; when?: 'matches' | 'enters' }>; sync?: { key: string; platform: string; signIn?: boolean }[] }): Promise<RegistrationView>
+register(input: RegisterInput): Promise<RegistrationView>
 watchers(): Promise<RegistrationView[]>
 matches(opts?: { limit?: number; wait?: number; signal?: AbortSignal }): Promise<MatchView[]>
 ack(id: string, body: { lease: string; error?: string; skip?: boolean }): Promise<{ ok: true }>
@@ -438,7 +441,9 @@ ack(id: string, body: { lease: string; error?: string; skip?: boolean }): Promis
 
 What a board on `http()` does on the board it uses, one method each:
 `register` replaces the caller's registration (its watchers, at most 32, its
-sync entries, and where to wake it); `matches` pulls what they matched, each leased to the caller
+sync entries, and where to wake it: a `url`, or on a board whose discovery says
+`wake_by_path`, a `path` on its own project and a preview's `branch`, never
+both); `matches` pulls what they matched, each leased to the caller
 for 5 minutes; `ack` says how one went (done, an `error` to try again, or
 `skip`). `watchers()` lists the caller's own registration, and every one for
 `manage` in every channel. `board()` does all of it for its watchers, so you

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

@@ -83,7 +83,7 @@ uses the target's own.
 | `react` | `POST /messages/:id/reactions` |
 | `label` | `POST /messages/:id/labels`, and a post or schedule with `labels` |
 | `sync` | `POST /messages/:id/sync`, a post with `sync` targets, and [sync's routes](#syncs-routes); in every channel, `GET /inbox/:key` for the board's own inbox |
-| `manage` | `POST /schedules/:id/cancel` for someone else's; in every channel, `GET /sources/:key/read`, and every registration in `GET /watchers` |
+| `manage` | `POST /schedules/:id/cancel` for someone else's; in every channel, `GET /sources/:key/read`, `POST /sources/:key/join`, and every registration in `GET /watchers` |
 
 `react`, `label`, and `sync` imply `read`, and `manage` implies everything. A
 message, schedule, or file the caller can't read answers 404 on every route;
@@ -118,13 +118,14 @@ a refused write it can read answers 403. `GET /me` returns the caller's
 | GET | `/schedules` | `{ schedules }`. Query: `re`, `channel`, `by`, `all` |
 | POST | `/schedules/:id/cancel` | Cancel one (`12` or `s12`). Its creator, or `manage` in its channel. Answers `{ schedule, canceled }` |
 | GET | `/events` | The event feed. See [Event feed](#event-feed) |
-| POST | `/watchers` | `{ url?, path?, branch?, watch, sync? }`: registers the caller's watchers (at most 32, each `{ tail, when? }`), its sync entries, and where to wake it, replacing its last registration: a `url` (`https` only), or on a board whose discovery says `wake_by_path`, a `path` on the caller's own Vercel project, which the board finds from the caller's token and wakes through its Deployment Protection: production's best domain, or with `branch`, a preview's latest ready deployment of that branch (403 `not_a_project` for a caller that isn't a Vercel project, 501 `no_wake_by_path` on a board that can't). Needs `read` somewhere, and `sync` somewhere for sync entries. Answers the registration, `{ owner, url, path?, branch?, watch, sync, hash }`. On a board on `http()`, it takes no token and registers that board's own |
+| POST | `/watchers` | `{ url?, watch, sync? }` or `{ path, branch?, watch, sync? }`, never both: registers the caller's watchers (at most 32, each `{ tail, when? }`), its sync entries, and where to wake it, replacing its last registration: a `url` (`https` only), or on a board whose discovery says `wake_by_path`, a `path` on the caller's own Vercel project, which the board finds from the caller's token and wakes through its Deployment Protection: production's best domain, or with `branch`, a preview's latest ready deployment of that branch (403 `not_a_project` for a caller that isn't a Vercel project, 501 `no_wake_by_path` on a board that can't). Needs `read` somewhere, and `sync` somewhere for sync entries. Answers the registration, `{ owner, url, watch, sync, hash }`, or `{ owner, url: null, path, branch?, watch, sync, hash }`. On a board on `http()`, it takes no token and registers that board's own |
 | GET | `/watchers` | `{ watchers }`: the caller's registration, or every one for `manage` in every channel |
 | GET | `/watchers/matches` | `{ matches }`: the caller's matches it can run now, one thread at a time and in order, each `{ id, watcher, thread, lease, attempt, event }` and leased to it for 5 minutes. Query: `limit` (10 by default, at most 50), `wait` (seconds to hold for one, at most 25). 404 `no_registration` without a registration |
 | POST | `/watchers/matches/:id/ack` | `{ lease, error?, skip? }`: done, an error to try again after a wait (after 5 tries it's `watch.failed`), or `skip` to drop it. 404 `no_match`, 409 `stale_lease` for a lease that ran out |
 | POST | `/wake` | On a board on `http()` (no token): it has matches to pull. Answers `{ ran }` |
 | GET | `/inbox/:key` | `{ events }`: raw platform events for a sync entry, newest first. Query: `channel`, `limit` (50 by default, at most 500). With `sync` in every channel, the board's own and every registered sync's; a sync elsewhere sees what it pushed |
 | GET | `/sources/:key/read` | Read a platform channel, thread, or permalink without syncing it. Query: `target`, `limit` (50 by default, at most 200). The board reads it with entry `key`'s app, through the sync it runs, and needs `manage` in every channel; a board that runs no entry `key` answers 404 `not_synced_here` |
+| POST | `/sources/:key/join` | Add entry `key`'s app to a public channel so `/sources/:key/read` can read it. Body: `{ target }`, a channel (`#name`, an ID) or a link into it. Answers `{ channel, name, joined }`, `joined: false` when the app was already in. Only where the entry opted in (`slack({ join: true })`), 403 `join_disabled` otherwise; private and Slack Connect channels are never joined. Needs `manage` in every channel; a board that runs no entry `key` answers 404 `not_synced_here` |
 | POST | `/webhooks/:key` | Platform ingress for sync entry `key` (no token) |
 | GET | `/identity/sign-in` | `?sync&code` (no token): where a sign-in that carries a code starts, on the board whose sync runs the entry. Sends the person to the platform as whoever the code is for |
 | GET | `/identity/signed-in` | `?sync&code` (no token): where the platform sends them back. Links the account they approved, by the code |
@@ -141,7 +142,7 @@ 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`, `/messages/:id/typing`, `GET /messages/:id/sync`,
+run it. `/sources/:key/read`, `/sources/:key/join`, `/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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/board",
-  "version": "0.19.0",
+  "version": "0.20.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",
@@ -31,6 +31,10 @@
       "types": "./dist/conformance.d.mts",
       "default": "./dist/conformance.mjs"
     },
+    "./cli": {
+      "types": "./dist/cli-embedded.d.mts",
+      "default": "./dist/cli-embedded.mjs"
+    },
     "./backend-a2": {
       "types": "./dist/backend-a2.d.mts",
       "default": "./dist/backend-a2.mjs"

package/dist/exports-B3AFzT_f.d.mts

@@ -1,4 +0,0 @@
-import "./auth-CU56Q2Xh.mjs";
-import "./schemas-CWxs3ECJ.mjs";
-import "./provider-B1Z3Ok86.mjs";
-import "./backend-B5GCP1oK.mjs";