slack-term 1.47.0 → 1.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slack-term",
-  "version": "1.47.0",
+  "version": "1.48.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/snomiao/slack-term.git"
@@ -25,6 +25,10 @@
   "bin": {
     "slack": "./ts/cli.ts"
   },
+  "exports": {
+    "./worker": "./worker/src/index.ts",
+    "./package.json": "./package.json"
+  },
   "description": "Slack CLI — read activity/news/mentions, search, send messages with a confirm-hash safety gate.",
   "engines": {
     "node": ">=18"
@@ -32,6 +36,7 @@
   "files": [
     "ts/",
     "dist/",
+    "worker/src/",
     "README.md",
     "SKILL.md",
     "LICENSE"
@@ -75,5 +80,13 @@
   "type": "module",
   "dependencies": {
     "yargs": "^18.0.0"
+  },
+  "peerDependencies": {
+    "@cloudflare/workers-types": "^4"
+  },
+  "peerDependenciesMeta": {
+    "@cloudflare/workers-types": {
+      "optional": true
+    }
   }
 }

package/ts/cli.ts

@@ -15,6 +15,7 @@ import { cmdAuthLogin, cmdAuthLoginChrome, cmdAuthChrome, cmdAuthFirefox, cmdAut
 import { cmdTail, parseSince as parseDuration } from "./tail.ts";
 import { runStream, webClient } from "./stream.ts";
 import { relaySubscriber, relayTransport } from "./relay.ts";
+import { DEFAULT_DIR, initRelay, initReport, relayHealth } from "./relayInit.ts";
 import { agentCommands } from "./agent.ts";
 
 import {
@@ -5558,8 +5559,9 @@ async function main(): Promise<void> {
     .option("workspace", { alias: "w", type: "string", describe: "Workspace name" })
     .middleware(async (argv) => {
       const cmd = String((argv._ ?? [])[0] ?? "");
-      // `sent` reads only the local log — no token, no network.
-      if (!cmd || cmd === "auth" || cmd === "login" || cmd === "agent" || cmd === "sent") return;
+      // `sent` reads only the local log — no token, no network. `relay` writes
+      // local files (init) or talks to the user's own relay (health): no Slack token.
+      if (!cmd || cmd === "auth" || cmd === "login" || cmd === "agent" || cmd === "sent" || cmd === "relay") return;
       try {
         const active = resolveToken((argv as W).workspace);
         const bot = resolveBotToken();
@@ -7638,6 +7640,46 @@ async function main(): Promise<void> {
         )
         .command("$0", false as unknown as string, () => {}, () => { y.showHelp(); process.exit(0); }),
     )
+    .command(
+      "relay",
+      "Set up / check the real-time relay for `slack stream` (a Cloudflare Worker)",
+      (y) => y
+        .command(
+          "init [dir]",
+          "Scaffold a deployable relay Worker folder (local files only; prints a fresh RELAY_TOKEN and the next steps)",
+          (y2) => y2
+            .positional("dir", { type: "string", default: DEFAULT_DIR, describe: "Folder to create" })
+            .option("name", { type: "string", describe: "Worker name (default: the folder's name)" })
+            .option("force", { type: "boolean", default: false, describe: "Overwrite files that already exist" })
+            .option("slack-term", { type: "string", describe: "slack-term dependency spec (default: this CLI's version), e.g. latest or file:../slack-term" }),
+          (argv) => {
+            const r = initRelay(argv.dir, {
+              force: argv.force,
+              ...(argv.name !== undefined ? { name: argv.name } : {}),
+              ...(argv["slack-term"] !== undefined ? { slackTerm: argv["slack-term"] } : {}),
+            });
+            if (!r.ok) {
+              console.error(`slack relay init: ${r.error}`);
+              for (const f of r.existing ?? []) console.error(`  exists: ${f}`);
+              process.exit(2);
+            }
+            console.log(initReport(r));
+          },
+        )
+        .command(
+          "health",
+          "GET /health on the relay (SLACK_RELAY_URL / SLACK_RELAY_TOKEN); exit 0 = ok",
+          (y2) => y2
+            .option("url", { type: "string", describe: "Relay URL (default: $SLACK_RELAY_URL)" })
+            .option("token", { type: "string", describe: "Relay token (default: $SLACK_RELAY_TOKEN)" }),
+          async (argv) => {
+            const r = await relayHealth(argv.url ?? process.env.SLACK_RELAY_URL, argv.token ?? process.env.SLACK_RELAY_TOKEN);
+            (r.code === 0 ? console.log : console.error)(r.out);
+            process.exit(r.code);
+          },
+        )
+        .demandCommand(1, "Specify a relay subcommand (init, health)"),
+    )
     .command(
       "stream",
       "Print every new message matching --grep, across all channels the identity is in (threads included); resumable",
@@ -7655,7 +7697,7 @@ async function main(): Promise<void> {
         .option("calls-per-min", { type: "number", default: 40, describe: "Polling: pace conversations.history/replies to this many calls per minute (0 = unpaced)" })
         .option("state", { type: "string", describe: "Cursor file (default: one per identity+grep+channels under $XDG_STATE_HOME/slack-term/stream/)" })
         .option("as-user", { type: "boolean", default: false, describe: "Stream as the user identity (sees the user's DMs) instead of the bot" })
-        .option("relay", { type: "boolean", default: true, describe: "Use the doorbell relay (worker/) when SLACK_RELAY_URL and SLACK_RELAY_TOKEN are set; --no-relay polls only" })
+        .option("relay", { type: "boolean", default: true, describe: "Use the doorbell relay (`slack relay init`) when SLACK_RELAY_URL and SLACK_RELAY_TOKEN are set; --no-relay polls only" })
         .option("reconcile", { type: "string", default: "5m", describe: "While the relay is connected, poll this rarely as a safety net" }),
       async (argv) => {
         let re: RegExp;

package/ts/relayInit.ts

@@ -0,0 +1,209 @@
+// `slack relay init` / `slack relay health`: set up and check the doorbell
+// relay without cloning this repo.
+//
+// The relay's code ships in the npm package as `slack-term/worker`
+// (worker/src/), so a deployable Worker is a two-line re-export plus a
+// wrangler.jsonc. `init` writes that folder — local files only, no network,
+// nothing that touches Slack — and prints a fresh RELAY_TOKEN with the next
+// steps. The token is deliberately NOT written into the folder: it is a secret,
+// and the folder is meant to be committed.
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+import pkg from "../package.json" with { type: "json" };
+
+/** The wrangler the repo deploys worker/ with (worker/package.json). */
+export const WRANGLER_VERSION = "4.105.0";
+/** worker/wrangler.jsonc's compatibility_date. */
+export const COMPATIBILITY_DATE = "2026-07-01";
+export const DEFAULT_DIR = "slack-term-relay";
+export const RELAY_DOCS_URL = "https://github.com/snomiao/slack-term/blob/main/worker/README.md";
+
+/** A Workers script name: lowercase letters, digits and dashes, 1–63 chars,
+ *  no leading or trailing dash. */
+export function validWorkerName(name: string): boolean {
+  return /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(name);
+}
+
+/** A directory name turned into a valid Worker name. */
+export function workerNameFrom(dir: string): string {
+  const n = basename(resolve(dir)).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63).replace(/-+$/, "");
+  return n || DEFAULT_DIR;
+}
+
+export type ScaffoldOptions = {
+  /** Worker name; default: the directory's basename. */
+  name?: string;
+  /** The `slack-term` dependency spec; default: `^` this CLI's version (a source
+   *  checkout carries a stale placeholder version; the range still resolves). */
+  slackTerm?: string;
+};
+
+/** The scaffold's files, relative path → content. */
+export function relayFiles(name: string, opts: { slackTerm?: string } = {}): Record<string, string> {
+  const packageJson = {
+    name,
+    private: true,
+    type: "module",
+    scripts: { deploy: "wrangler deploy", dev: "wrangler dev --local" },
+    dependencies: { "slack-term": opts.slackTerm ?? `^${pkg.version}` },
+    devDependencies: { wrangler: WRANGLER_VERSION },
+    engines: { node: ">=22" },
+  };
+  return {
+    "package.json": `${JSON.stringify(packageJson, null, 2)}\n`,
+    "wrangler.jsonc": `// slack-term relay: Slack Events API -> doorbells for \`slack stream\`.
+// Secrets (not in this file): wrangler secret put SLACK_SIGNING_SECRET / RELAY_TOKEN / SLACK_TEAM_ID (optional)
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": ${JSON.stringify(name)},
+  "main": "src/index.ts",
+  "compatibility_date": "${COMPATIBILITY_DATE}",
+  "durable_objects": {
+    "bindings": [{ "name": "RELAY", "class_name": "Relay" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Relay"] }],
+  // Request bodies are message events from possibly customer-facing channels:
+  // keep Workers Logs off so nothing about them is persisted by the platform.
+  "observability": { "enabled": false }
+}
+`,
+    "src/index.ts": `// The relay lives in the slack-term package. Relay (the Durable Object class)
+// must be exported from this main module for the RELAY binding to find it.
+export { default, Relay } from "slack-term/worker";
+`,
+    ".gitignore": "node_modules/\n.wrangler/\n.dev.vars*\n.env*\n",
+    "README.md": readme(name),
+  };
+}
+
+/** The steps after `init`, shared by the README and the printed output.
+ *  `token` is only ever printed, never written to a file. */
+export function nextSteps(name: string, token?: string): string {
+  const tok = token ?? "<RELAY_TOKEN>";
+  return `1. Node >= 22 (wrangler 4 needs it), then install:
+     npm install
+2. Log in to Cloudflare:
+     npx wrangler login
+   or set CLOUDFLARE_API_TOKEN (Workers Scripts: Edit) and CLOUDFLARE_ACCOUNT_ID.
+3. Deploy, then set the secrets:
+     npx wrangler deploy
+     npx wrangler secret put SLACK_SIGNING_SECRET   # Slack app -> Basic Information -> Signing Secret
+     npx wrangler secret put RELAY_TOKEN            # paste: ${tok}
+     npx wrangler secret put SLACK_TEAM_ID          # optional: accept one workspace only (T...)
+4. In the Slack app -> Event Subscriptions: Enable Events, Request URL
+     https://${name}.<your-subdomain>.workers.dev/slack/events
+   and subscribe to bot events: message.channels, message.groups, message.im,
+   app_mention (and message.mpim if the bot has mpim:history). Save; reinstall if asked.
+5. Where \`slack stream\` runs:
+     export SLACK_RELAY_URL=https://${name}.<your-subdomain>.workers.dev
+     export SLACK_RELAY_TOKEN=${tok}
+6. Check it:
+     slack relay health        # or: curl -H "Authorization: Bearer $SLACK_RELAY_TOKEN" $SLACK_RELAY_URL/health
+     slack stream -e .         # stderr says: relay connected (websocket)
+`;
+}
+
+function readme(name: string): string {
+  return `# ${name}
+
+A [slack-term](https://github.com/snomiao/slack-term) relay: a Cloudflare Worker
+that turns Slack's Events API into a resumable doorbell stream for
+\`slack stream\`. The code is the \`slack-term/worker\` export; this folder only
+configures and deploys it. Created by \`slack relay init\`.
+
+## Set up
+
+${nextSteps(name)}
+\`RELAY_TOKEN\` is any long random string (\`openssl rand -hex 32\`); \`slack relay init\`
+printed one. Keep it out of this folder: anyone holding it can watch when and
+where messages are posted.
+
+## Update
+
+Bump \`slack-term\` in package.json, \`npm install\`, \`npx wrangler deploy\`.
+Storage survives redeploys; clients reconnect and resume.
+
+Details (endpoints, privacy, protocol): ${RELAY_DOCS_URL}
+`;
+}
+
+export type InitResult =
+  | { ok: true; dir: string; name: string; written: string[]; token: string }
+  | { ok: false; error: string; existing?: string[] };
+
+/** Write the scaffold into `dir`. Refuses to overwrite any existing file
+ *  unless `force`. Returns the generated RELAY_TOKEN for the caller to print. */
+export function initRelay(
+  dir: string,
+  opts: ScaffoldOptions & { force?: boolean } = {},
+  rand: (n: number) => Buffer = randomBytes,
+): InitResult {
+  const name = opts.name ?? workerNameFrom(dir);
+  if (!validWorkerName(name)) {
+    return { ok: false, error: `invalid worker name "${name}": use lowercase letters, digits and dashes (1-63 chars, no leading/trailing dash)` };
+  }
+  const files = relayFiles(name, opts.slackTerm !== undefined ? { slackTerm: opts.slackTerm } : {});
+  const root = resolve(dir);
+  const existing = Object.keys(files).filter((f) => existsSync(join(root, f)));
+  if (existing.length && !opts.force) {
+    return { ok: false, error: `refusing to overwrite existing files in ${root} (pass --force to replace them)`, existing };
+  }
+  for (const [rel, content] of Object.entries(files)) {
+    const p = join(root, rel);
+    mkdirSync(join(p, ".."), { recursive: true });
+    writeFileSync(p, content);
+  }
+  return { ok: true, dir: root, name, written: Object.keys(files), token: rand(32).toString("hex") };
+}
+
+/** What `slack relay init` prints on success. */
+export function initReport(r: Extract<InitResult, { ok: true }>, cwd: string = process.cwd()): string {
+  const rel = r.dir.startsWith(`${cwd}/`) ? r.dir.slice(cwd.length + 1) : r.dir;
+  return [
+    `Created ${r.dir} (worker "${r.name}"):`,
+    ...r.written.map((f) => `  ${f}`),
+    "",
+    `RELAY_TOKEN (generated now, not saved anywhere — copy it):`,
+    `  ${r.token}`,
+    "",
+    "Next steps:",
+    `0. cd ${rel}`,
+    nextSteps(r.name, r.token),
+  ].join("\n");
+}
+
+export type HealthResult = { code: 0 | 1 | 2; out: string };
+
+/** GET /health on the relay (read-only). 0 = ok, 1 = unhealthy/unreachable,
+ *  2 = not configured. */
+export async function relayHealth(
+  url: string | undefined,
+  token: string | undefined,
+  fetchImpl: typeof fetch = fetch,
+  timeoutMs = 10_000,
+): Promise<HealthResult> {
+  if (!url || !token) {
+    return { code: 2, out: "slack relay health: set SLACK_RELAY_URL and SLACK_RELAY_TOKEN (or pass --url / --token)" };
+  }
+  const target = `${url.replace(/\/+$/, "")}/health`;
+  try {
+    const res = await fetchImpl(target, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const body = await res.text();
+    if (res.status === 401) return { code: 1, out: `slack relay health: 401 unauthorized — SLACK_RELAY_TOKEN does not match the relay's RELAY_TOKEN secret` };
+    if (!res.ok) return { code: 1, out: `slack relay health: HTTP ${res.status} from ${target}${body ? `: ${body.slice(0, 200)}` : ""}` };
+    let json: { ok?: unknown };
+    try {
+      json = JSON.parse(body) as typeof json;
+    } catch {
+      return { code: 1, out: `slack relay health: not a slack-term relay (non-JSON reply from ${target})` };
+    }
+    return { code: json.ok === true ? 0 : 1, out: JSON.stringify(json, null, 2) };
+  } catch (e) {
+    return { code: 1, out: `slack relay health: cannot reach ${target}: ${e instanceof Error ? e.message : String(e)}` };
+  }
+}

package/ts/stream.ts

@@ -643,7 +643,7 @@ export async function runStream(client: StreamClient, opts: StreamOpts): Promise
       `slack stream: WARNING: polling mode (${opts.pollReason ?? "no relay configured"}) — this is the fallback, ` +
       `not the intended setup: matches arrive up to ${Math.round(opts.intervalMs / 1000)}s late (replies under older ` +
       `parents up to ${Math.round(Math.max(opts.threadScanSec ?? 180, opts.intervalMs / 1000))}s) and every cycle spends ` +
-      `Slack API calls. For real time, deploy the relay and set SLACK_RELAY_URL + SLACK_RELAY_TOKEN: ${RELAY_DOCS}`,
+      `Slack API calls. For real time, set up the relay (slack relay init) and set SLACK_RELAY_URL + SLACK_RELAY_TOKEN: ${RELAY_DOCS}`,
     );
   }
   client = paced(client, opts.callsPerMin ?? 40, opts.signal);

package/worker/README.md

@@ -0,0 +1,216 @@
+# slack-term relay
+
+A Cloudflare Worker that turns Slack's **Events API** into a resumable stream of
+*doorbells* for `slack stream`. Slack posts each event to the Worker; the Worker
+keeps only `{channel, ts, thread_ts}` and pushes it over a WebSocket (or, for
+older clients, Server-Sent Events) to authenticated clients. Each client then
+reads the message itself, with its own token.
+
+```
+Slack ──POST /slack/events──▶ Worker ──▶ Relay Durable Object (SQLite)
+                                              │ seq  {channel, ts, thread_ts}
+slack stream ◀──GET /ws (WebSocket, hibernating)┤
+older clients ◀──GET /stream (SSE, Bearer)──────┘
+```
+
+## Cost: why WebSocket
+
+A Durable Object is billed for **duration** while it is in memory, and an open
+SSE response keeps it there for as long as a client is connected — all day,
+for a stream that is idle most of the time. `/ws` instead uses the Durable
+Object [WebSocket Hibernation API](https://developers.cloudflare.com/durable-objects/best-practices/websockets/):
+
+- sockets are accepted with `ctx.acceptWebSocket()`, so between bells the object
+  is evicted and not billed, while the connections stay open;
+- the client's keepalive (`"ping"` every 25 s) is answered `"pong"` by the
+  runtime (`setWebSocketAutoResponse`) **without waking the object**;
+- all per-client state (resume position, acked position, replay/live, stall
+  clock) lives in the socket's attachment (`serializeAttachment`), so it
+  survives hibernation, and nothing waits on a timer.
+
+The object wakes only for a Slack event, a client connecting, a client's ack
+(sent within ~100 ms of the bells it acknowledges, while the object is still
+awake from the event), or the hourly TTL alarm.
+
+**SSE is kept for one release** so `slack stream` clients from before `/ws`
+keep working against a redeployed relay. Each connected SSE client keeps the
+object awake as before; `/health` shows `sse_clients` so you can see when none
+are left, after which `/stream` can be removed. New clients try `/ws` first and
+fall back to `/stream` for a connection only if the socket cannot be opened at
+all (an older relay, a proxy that strips upgrades, a runtime without
+`WebSocket`); `SLACK_RELAY_TRANSPORT=websocket|sse` pins one.
+
+## Endpoints
+
+| Path | Auth | What |
+|---|---|---|
+| `POST /slack/events` | Slack signing secret (`X-Slack-Signature`, ±5 min) | Answers `url_verification`; stores one bell per `message` / `app_mention` event. Acks with a single SQLite insert, well inside Slack's 3 s. Retries collapse on `(channel, ts)`. |
+| `GET /ws?after=<seq>&epoch=<e>` | Subprotocols `slack-term-relay.v1` **and** `bearer.<base64url($RELAY_TOKEN)>` (or `Authorization: Bearer`) | WebSocket (below). Rejected with 401 before the upgrade is accepted. |
+| `GET /stream?after=<seq>` | `Authorization: Bearer $RELAY_TOKEN` | SSE (kept for older clients). First an `event: hello` frame `{seq, gap, retention_sec}`, then the backlog after `seq`, then live `event: bell` frames (`id:` = seq). A keepalive comment goes out every 25 s. `Last-Event-ID` works as well as `?after`. Pass `&epoch=` from the last hello: the epoch names the relay's storage, so a client resuming against a reset relay is told `gap: true` and gets everything kept, even once the new numbers have passed its old seq. If `after` is omitted, the stream starts from now. `gap: true` means some bells after `after` are gone (expired, or the relay was reset): everything still kept is replayed, and the client should also catch up by polling. |
+| `GET /health` | Bearer | `{epoch, latest, oldest, clients, websocket_clients, sse_clients, retention_sec}` |
+
+At most 16 clients (both kinds) at once; more get 503.
+
+### The WebSocket protocol (`/ws`)
+
+**Auth.** The token is never put in the URL (query strings end up in logs).
+Node's built-in `WebSocket` cannot send an `Authorization` header, so the client
+offers two subprotocols — `Sec-WebSocket-Protocol: slack-term-relay.v1,
+bearer.<base64url(token)>` (base64url because subprotocols must be HTTP tokens;
+the same scheme Kubernetes uses) — and the Worker compares the bearer one in
+constant time before the request reaches the Durable Object. The server
+selects only `slack-term-relay.v1`, never echoing the token.
+
+**Messages** are JSON text, one per frame:
+
+- server → client: `{"type":"hello","seq","gap","retention_sec","epoch"}` first
+  (same resume rules as SSE: `after`, `epoch`, `gap`); then
+  `{"type":"bell","seq":n,"bell":{channel,ts,thread_ts?,self?}}` — the backlog
+  after `seq`, then live bells; and `"pong"` (from the runtime).
+- client → server: `"ping"` every 25 s; `{"type":"ack","seq":n}` for the highest
+  bell received — at once after 32 unacked bells, else within 100 ms.
+
+**Flow control** replaces SSE's write backpressure, which a WebSocket send
+does not give: the backlog is replayed 100 bells at a time, each batch only
+after the previous one is acked, and the switch to live happens right after a
+storage read comes back empty (synchronously, so no bell falls in between). A
+client is closed — and resumes from storage with `?after` — when it has 64 live
+bells unacked (`4008 overflow`), makes no ack progress for 30 s while owing one
+(`4009 stalled`), or neither pings nor acks for 90 s (`4010 silent`). These
+checks run whenever the object is awake (an event, a connect, the alarm), since
+a hibernating object runs no timers.
+
+## Privacy
+
+- **No message content is stored or served:** no text, no sender, no attachments.
+  A bell holds a channel id and two timestamps — plus, on posts by **this app's own
+  bot** only, `self`: that bot's user id. A client streaming as the bot never prints
+  its own posts, so it skips the Web API read such a bell would cost (and, for
+  `--replies-to`, learns from it that the bot is in the thread). No other sender
+  is ever recorded.
+- **Bells are deleted 1 hour after arrival** (`RETENTION_SEC`, enforced by a
+  Durable Object alarm). That window exists only so a client can resume.
+  Anything older is covered by the client's catch-up poll, except replies
+  under a thread parent older than the client's `--thread-window`: the poll
+  cannot find those, so a bell that expired before the client read it is lost.
+- **Nothing logs a request body**, and Workers Logs are off (`observability`).
+- **Token holders see activity metadata.** Anyone with `RELAY_TOKEN` can watch
+  *when* and *where* messages are posted — channel ids, timestamps and thread
+  structure, for every conversation the bot is in, **including DMs** with it —
+  even though they never see text or senders. Treat the token like read access
+  to that timing data: give it only to consumers you trust, and rotate it
+  (`wrangler secret put RELAY_TOKEN`) when one should lose access.
+- **A forged bell costs a few Web API reads at most:** one
+  `conversations.replies` call, a few pages if needed, and up to 8 retries
+  if the message is not found. The client applies its own filter to what
+  Slack returns, so a forged bell never prints anything.
+
+## Deploy
+
+### Without cloning (recommended)
+
+The relay ships in the npm package as `slack-term/worker`. Scaffold a Worker
+folder with the CLI:
+
+```sh
+slack relay init my-relay        # or: npx slack-term relay init my-relay
+cd my-relay && npm install
+npx wrangler login               # or CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID (below)
+npx wrangler deploy
+```
+
+`init` writes `package.json` (slack-term as `^` the CLI's version, wrangler
+pinned), `wrangler.jsonc` (the same config as this folder's, with `--name` or
+the folder's name), `src/index.ts`, `.gitignore` and a `README.md`. It makes no
+network calls and refuses to overwrite existing files unless `--force`. It
+prints a freshly generated `RELAY_TOKEN` — not saved anywhere — and the
+remaining steps: the secrets, the Slack app settings and the client env, all
+as described below (run them from the new folder, with `npx wrangler`).
+
+Already have a Worker project? `src/index.ts` is just
+
+```ts
+export { default, Relay } from "slack-term/worker";
+```
+
+with a `RELAY` Durable Object binding to class `Relay` and a
+`new_sqlite_classes: ["Relay"]` migration — copy them from
+[`wrangler.jsonc`](wrangler.jsonc). `Env` is exported too, for typing.
+`@cloudflare/workers-types` is an optional peer dependency of slack-term.
+
+To update, bump `slack-term` in the folder's package.json and redeploy.
+
+### From a clone of this repo (contributors)
+
+Wrangler 4 needs **Node ≥ 22**.
+
+Cloudflare credentials, in the environment:
+
+- `CLOUDFLARE_API_TOKEN` — a token with the **Workers Scripts: Edit** permission
+  (the "Edit Cloudflare Workers" template).
+- `CLOUDFLARE_ACCOUNT_ID` — from the dashboard sidebar.
+
+```sh
+cd worker
+npx --yes wrangler@4.105.0 deploy
+npx --yes wrangler@4.105.0 secret put SLACK_SIGNING_SECRET   # Slack app → Basic Information → Signing Secret
+npx --yes wrangler@4.105.0 secret put RELAY_TOKEN            # long random string, shared with consumers (e.g. openssl rand -hex 32)
+npx --yes wrangler@4.105.0 secret put SLACK_TEAM_ID          # optional: accept one workspace only (T…)
+```
+
+Redeploying an existing relay keeps its storage (and epoch): no migration is
+needed, the Durable Object class is unchanged. A deploy restarts the object,
+which drops every connection; clients reconnect and resume from their last seq.
+
+### Then, either way
+
+Check it (expects `{"ok":true,…}`):
+
+```sh
+curl -H "Authorization: Bearer $RELAY_TOKEN" https://<worker>/health
+# or, with SLACK_RELAY_URL / SLACK_RELAY_TOKEN set:
+slack relay health
+```
+
+Then, in the Slack app:
+
+1. Go to **Event Subscriptions** and turn on **Enable Events**.
+2. Set the **Request URL** to `https://<worker>/slack/events`. It should verify at once.
+3. Under **Subscribe to bot events**, add:
+   - `message.channels`
+   - `message.groups`
+   - `message.im`
+   - `app_mention`
+   - `message.mpim`, only if the bot has `mpim:history`.
+   Each needs its bot scope (`channels:history`, `groups:history`, `im:history`,
+   `app_mentions:read`); Slack offers to add them.
+4. Click **Save**, then reinstall the app if Slack asks.
+
+The secrets must be in place first: Slack's URL verification is signed.
+
+Consumers set `SLACK_RELAY_URL=https://<worker>` and `SLACK_RELAY_TOKEN=…`
+(the same value as the `RELAY_TOKEN` secret). `slack stream` then uses the relay
+automatically and says so on stderr: `relay connected (websocket)` — or
+`(sse)` if it fell back. Optional: `SLACK_RELAY_TRANSPORT=websocket` or `sse`.
+
+## Develop
+
+```sh
+cd worker && bun install && bun run typecheck
+# or, from the repo root (what CI runs):
+bun run typecheck:worker
+```
+
+The signature and event parsing live in `src/slack.ts`, and the WebSocket
+session logic (replay, acks, flow control, auth) in `src/hub.ts`; neither has
+Cloudflare types, and the CLI suite tests both (`tests/relay.test.ts`,
+`tests/relay-hub.test.ts`, `tests/relay-ws.test.ts`).
+
+To run the Worker locally (Node ≥ 22; on an older Node,
+`npx -y -p node@22 -- …` works):
+
+```sh
+cd worker
+printf 'SLACK_SIGNING_SECRET=dev\nRELAY_TOKEN=dev\n' > .dev.vars   # git-ignored
+npx --yes wrangler@4.105.0 dev --local
+```