Add Teams subpath exports for custom runtimes, including Bot Connector
API helpers, Graph reads, parse-only webhooks, format helpers, Adaptive
Cards, and Task Module primitives.
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
Stacked on top of #603 (`create-chat-sdk`).
Refreshes the chat-sdk.dev homepage styling:
- Adds Geist typography utilities (`text-heading-*`, `text-copy-*`) and
applies them to the hero, section headings, and copy.
- Adds a grid-based layout (`home-grid.css`) with consistent guide lines
for the stats, supported-platforms, code, and integrations sections.
- Adds a tabbed code showcase for the Chat SDK Core section, with window
chrome, a Geist syntax theme, and
`bot.ts`/handlers/cards/streaming/tools/state/multi-platform snippets.
- Scopes inline-code styling and sets the dark-mode
`--ds-background-100`/`--ds-background-200` tokens so `background-100`
is the elevated surface.
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
Adds `create-chat-sdk`, a CLI that scaffolds a Next.js Chat SDK bot
project:
```bash
npm create chat-sdk@latest my-bot
# non-interactive
npm create chat-sdk@latest -- my-bot --adapter slack redis -y
```
The user picks platform and state adapters interactively or via
`--adapter`, and the CLI generates a webhook-only project with
`src/lib/bot.ts`, `.env.example`, `next.config.ts`, `package.json`, and
a README, then optionally runs `git init` and installs dependencies.
There are no pages or client UI in the template.
Adapter choices come straight from the `chat/adapters` catalog, so the
CLI has no adapter registry of its own. When a coding agent such as
Cursor or Claude Code runs the CLI, it uses non-interactive defaults and
requires an explicit platform adapter. `--interactive` forces prompts.
## also in this pr
- `google-chat` is renamed to `gchat` everywhere, including docs pages,
the OG image, and adapter catalog. Old URLs redirect permanently,
including language-prefixed and `/og` paths
- a new docs page is available at `chat-sdk.dev/docs/create-chat-sdk`,
and the CLI is promoted on the homepage, package READMEs, and agent
skill
- `create-chat-sdk` releases independently with a minor changeset for
its initial `0.1.0` release
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
Co-authored-by: dancer <josh@afterima.ge>
## summary
adds native rich message support for Telegram Bot API 10.1
explicit markdown and AST messages now use `sendRichMessage`, edits use
rich message payloads, and private chat streams use
`sendRichMessageDraft` before persisting the completed response
preserves existing behavior for plain strings, raw messages, cards,
media captions, and older or custom Bot API servers through automatic
fallback
adds typed inbound rich message parsing, rich message limits, regression
coverage, and updated adapter documentation
## summary
adds `webClientOptions` to `SlackAdapterConfig` so users can configure
the underlying Slack `WebClient` instances
the options apply to both the default client and per-token clients used
for multi-workspace requests, including settings such as `retryConfig`,
per-request `timeout`, custom headers, and `rejectRateLimitedCalls`
`slackApiUrl` is intentionally excluded from `webClientOptions` because
the existing `apiUrl` option remains the single configuration path for
overriding the Slack Web API base URL
custom headers are cloned for each client because the Slack SDK adds
authorization to the provided headers object, preventing credentials
from leaking between token-bound clients
---------
Co-authored-by: dancer <josh@afterima.ge>
Adds a safeguard in `NavigationMenuTrigger` to skip `preventDefault`
when the click is on a nested link, so the logo navigates home without
interfering with the chevron dropdown, matching the AI SDK website
interaction model.
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
## Summary
Adds Telegram bot command support for Chat SDK slash command handlers.
- Routes Telegram `/command` and `/command@botusername` messages to
`bot.onSlashCommand`
- Ignores commands addressed to another bot
- Keeps non-command messages on the existing normal message path
## Test plan
- `pnpm validate`
- Tested locally against a real Telegram bot
## Checklist
- [x] All commits are signed and verified
- [x] `pnpm validate` passes
- [x] Changeset added
- [x] Documentation updated
---------
Co-authored-by: dancer <josh@afterima.ge>
Adapter Catalog:
- Adds a zero-dependency `chat/adapters` subpath for official and
vendor-official adapter metadata.
- Includes typed catalog entries, env specs, peer dependency metadata,
and helper APIs for setup and onboarding flows.
- Wires the subpath into the `chat` package export map and build config.
Code Coverage:
- Adds unit coverage for catalog integrity, registry sync, helper
behavior, official env declarations, and peer dependency derivation.
- Extends docs integration coverage for `chat/adapters` imports and
vendor-official package install metadata.
Documentation:
- Documents the new catalog on the adapter overview page.
- Splits platform-specific adapter guidance into a new
`/docs/platform-adapters` page.
- Renames `/docs/state` to `/docs/state-adapters` and adds a redirect
for the old slug.
Agent Guidance:
- Updates repo-local and public agent guidance so agents know when and
how to use `chat/adapters`.
- Adds focused `AGENTS.md` guidance inside `packages/chat/src/adapters`
for future catalog maintenance.
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
Adds official platform adapter branding across the docs site, npm
READMEs, and social previews.
- **Homepage**: add Twilio to the supported-platforms logo grid
- **OG images**: add custom artwork for all 11 official platform
adapters under content/adapters/official/og/; serve static-first from
the existing /adapters/official/{slug}/og route with dynamic fallback
for state adapters
- **READMEs**: add linked hero banners to every official platform
adapter package README, using the live OG URL as the single image source
- **Tests**: integration-test guardrails for OG image coverage, README
banner discoverability, and knip-clean helpers
- **Changeset**: empty changeset for CI
<img width="2400" height="1256" alt="Chat SDK - Slack"
src="https://github.com/user-attachments/assets/4d186a1c-5651-44b8-8698-091ee23b44da"
/>
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
## Summary
- Add the QQ Bot community platform adapter to `apps/docs/adapters.json`
- Point the listing at the published npm package
`@youglin/adapter-qq-bot`
- Pin the rendered README to the adapter repository commit
`46e76e8e6965d5dc1ee1446bbea76feb23cf7733`
## Verification
- Parsed `apps/docs/adapters.json` and checked unique `slug` /
`packageName` values
- Verified the `readme` field is pinned to a 40-character commit SHA
- Verified GitHub API can fetch `README.md` at the pinned adapter commit
Improves Chat SDK discoverability across npm, READMEs, and the docs site
for search engines and AI coding agents.
- **npm metadata**: point every published package `homepage` at
chat-sdk.dev deep links; expand `chat` keywords/description; fix
`repository.directory` (`packages/chat-sdk` → `packages/chat`); align
state adapter keywords
- **READMEs**: add npm callouts, Documentation/Guides links, and AI
Coding Agents sections (skill install, optional Vercel Plugin,
`llms.txt` / `llms-full.txt`) across all published packages and the repo
root
- **docs JSON-LD**: `HowTo` / `TechArticle` on getting-started,
streaming, and cards; `CollectionPage` + official-only `ItemList` on
`/adapters` (with split human vs JSON-LD descriptions)
- **UTMs**: add `chat-sdk_site` / `chat-sdk_repo` tracking params to
Resources links in selected MDX pages and adapter READMEs (discord,
github, slack, liveblocks, getting-started, ai index)
- **contract tests**: integration-tests guardrails for npm metadata and
README discoverability so future package additions don't drift
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
Moves the Sendblue adapter from community to vendor-official in the docs
site now that Sendblue maintains `chat-adapter-sendblue`.
- package: `chat-adapter-sendblue`
- repo: https://github.com/sendblue-api/chat-adapter-sendblue
- docs: https://docs.sendblue.com/guides/chat-sdk-adapter/
Updates the adapter registry and hand-authored detail page (iMessage,
SMS, RCS, `sb-signing-secret` webhook verification, official Sendblue
guide links). Reorders vendor-official adapters so Liveblocks, Resend,
Sendblue, and Zernio appear first. Adds a permanent redirect from
`/adapters/community/sendblue`.
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
## summary
clarifies that `author.isMe` means the message was sent by the current
bot runtime and should be filtered from handler dispatch
documents that adapters backed by user-owned accounts should not map
platform fields like `fromMe` directly to `isMe`
recommends tracking message ids returned by `postMessage` so webhook
echoes can be identified without filtering legitimate user-authored
messages
Adds Schema.org JSON-LD to every adapter detail page (official,
community, vendor-official):
- `SoftwareSourceCode` describing the package — name (package),
description (tagline), repository, `programmingLanguage: TypeScript`,
`runtimePlatform: Node.js`, and author (Vercel for official adapters,
the vendor/community author otherwise). License is only emitted for
official adapters; no fabricated ratings/offers.
- `BreadcrumbList` for the `Chat SDK › Adapters › <name>` hierarchy.
Built from existing frontmatter + `adapters.json` via a shared
`getAdapterJsonLd` helper, injected with the same `<script
type="application/ld+json">` pattern already used on the home page.
Primarily a classic-SEO/rich-result and entity-linking improvement,
complementing the markdown/llms.txt AEO work.
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
## summary
adds Velt as a vendor-official adapter in the docs directory
`@veltdev/chat-sdk-adapter` connects a Chat SDK bot to Velt comment
threads on documents, text editors, and canvases. it maps Velt documents
to channels, comment annotations to threads, and comments to messages so
the rest of the Chat SDK API works unchanged
- package: `@veltdev/chat-sdk-adapter`
- repo: https://github.com/velt-js/velt-chat-sdk-adapter
- docs: https://velt.dev/docs/ai/chat-sdk-adapter
this updates the adapter registry, adds the Velt vendor-official detail
page, and includes the `velt` slug in the vendor-official adapter
metadata
SEO/AEO improvements for the docs site:
- Append `| Chat SDK` to every page's `<title>` and `og:title` (home
stays `Chat SDK`).
- Expose a plain-markdown version of every docs and adapter page via an
`sr-only` AI/LLM hint link and a `text/markdown` alternate; adapter
pages get a new `/adapters/<group>/<slug>.md` endpoint.
- Turn `llms.txt` into a sitemap-style index linking to each page's
markdown, and move the full-text concatenation to `llms-full.txt`. A
`<link rel="llms-txt">` is added to every page.
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
## Summary
- Updates Teams setup docs to install `@microsoft/teams.cli` instead of
the old `@preview` tag.
## Why
- Teams CLI is stable now, so the docs should point folks at the stable
package. Nice and tidy.
## Interesting bits
- This touches both the public docs page and the adapter README so they
don't disagree.
## Test plan
- Not run; docs-only change.
## Summary
Adds typing indicator support for WhatsApp and also bumps the API
version to the latest v25.0.
> Good to know: There is a limitation with typing indicator API: it has
a 25-second cooldown and rqeuires a recent incoming message. This means
if you try to display the typing indicator before the cooldown period
has passed, it won’t show up, but the message will still be marked with
a red check mark.
## Test plan
Verified end-to-end on a real WhatsApp Business profile
---------
Co-authored-by: dancer <josh@afterima.ge>
## Summary
Adds
[`@larksuite/vercel-chat-adapter`](https://www.npmjs.com/package/@larksuite/vercel-chat-adapter),
the Lark / Feishu adapter for Chat SDK, as a **vendor-official community
adapter**.
- **Package**: `@larksuite/vercel-chat-adapter` — published on npm under
the official `larksuite` scope
- **Built on**:
[`@larksuiteoapi/node-sdk`](https://www.npmjs.com/package/@larksuiteoapi/node-sdk)'s
`LarkChannel`, the official Lark Node SDK
- **Docs source**: external README referenced by `adapters.json` lives
in
[`larksuite/node-sdk`](https://github.com/larksuite/node-sdk/tree/cbc4adf13cbcb93b389db01faf428e3b3cef053c/docs/vercel-chat-adapter)
(the official Lark vendor-owned GitHub org, pinned at commit
`cbc4adf1`); the in-tree MDX in this PR is the rendered detail page
(`mdxBody: true`)
- **Capabilities**: native cardkit typewriter streaming, interactive
cards, reactions, edit / delete, message history (via SDK
`normalize()`), DM detection, mention handling, and scan-to-create app
onboarding through `registerLarkApp`
## Changes
| File | Change |
|---|---|
| `apps/docs/adapters.json` | Add Lark / Feishu entry (`community:
true`, `vendorOfficial: true`) |
| `apps/docs/content/adapters/vendor-official/lark.mdx` | New
hand-authored MDX detail page (frontmatter with full features matrix,
install / quick start / configuration / transport / streaming / ID
encoding / history / safety / limitations / FeatureSupport) |
| `apps/docs/content/adapters/vendor-official/meta.json` | Append
`"lark"` to the sidebar `pages` array |
| `packages/integration-tests/src/docs-adapters.test.ts` | Append
`"lark"` to the hardcoded vendor-official slug list asserted by
`Vendor-Official adapter MDX › contains exactly the expected adapters` |
No icon registered in `adapters.json` / `iconMap` / `adapterLogos` —
matches the existing pattern for vendor-official adapters (Beeper,
Resend, Liveblocks, Zernio, Photon).
## Vendor Official tier
Per `docs/contributing/building.mdx` (Qualifications for vendor official
tier):
- ✅ **Commitment for continued maintenance** — owned by the Lark /
Feishu team
- ✅ **GitHub hosting in official vendor-owned org** — adapter README
lives in [`larksuite/node-sdk`](https://github.com/larksuite/node-sdk),
the official Lark org
- ✅ **Documentation in primary vendor docs** — will be cross-linked from
the official Lark Open Platform developer documentation
- ✅ **Announcement** — will be announced through Lark developer
changelog / channels
## A note on source visibility
The adapter source is not currently open-sourced due to internal
release-process requirements. What is public:
- The npm package itself (consumable by any user)
- The README, hosted in `larksuite/node-sdk` (official Lark org)
- The underlying
[`@larksuiteoapi/node-sdk`](https://github.com/larksuite/node-sdk) on
which it is built — this *is* fully open-source
## Test plan
- [x] `pnpm --filter docs build` — docs app builds cleanly;
`/en/adapters/vendor-official/lark` and
`/en/adapters/vendor-official/lark/og` routes are generated
- [x] `pnpm typecheck` — passes (33 tasks)
- [x] `pnpm check` (Ultracite / Biome) — 438 files, no fixes
- [x] `pnpm --filter @chat-adapter/integration-tests test docs-adapters`
— 232 tests pass (frontmatter, vendor-official roster, adapters.json ↔
MDX sync)
- [x] Manual: `/adapters` lists the Lark / Feishu card in the **Vendor
Official** section; `/adapters/vendor-official/lark` renders the MDX
detail page with the FeatureSupport matrix
Broad SEO/AEO pass across the docs site, adapter READMEs and AGENTS.md
files, and npm package metadata so Chat SDK content shows up better in
search engines, in LLM-driven package recommendations, and in
IDE/coding-agent context.
**Docs site**
- Adds a `## Resources` section to the Getting Started and AI overview
pages and to the Slack, Discord, GitHub, Liveblocks, and Sendblue
adapter pages, each linking to applicable guides/templates with
descriptions sourced from `resources-edge-config.json` and a cross-link
back to the central `/resources` hub.
**Adapter packages**
- Mirrors the same Resources sections into the Slack, Discord, and
GitHub READMEs (so they surface on npm) and into their AGENTS.md files
(so coding agents see them alongside the API notes).
- Expands `keywords` on every published adapter and state package — adds
`chat-sdk`, `chatbot`, `ai-agent`, `ai-sdk`, `vercel`, plus
platform-specific terms like `slack-bot`, `block-kit`, `slash-commands`,
`github-app`, `whatsapp-business`, `state-adapter`.
**Resources registry**
- Registers four new entries in `resources-edge-config.json`
(Human-in-the-Loop guide, Liveblocks AI agent guide, Slack + Vercel Blob
guide, Durable iMessage Agent template) and runs `pnpm sync-resources`
so the bundled `chat` package guides, `templates.json`, and
`skills/chat/SKILL.md` all pick them up.
- Fixes the synced Slack AI agent guide to import `toAiMessages` from
`chat/ai` instead of the deprecated `chat` re-export path (the upstream
KB source has also been updated, so future syncs will preserve this).
**Drive-by fixes**
- Resend adapter doc quick start: corrects `MemoryStateAdapter` class
import to the `createMemoryState()` factory (matching every other
adapter doc).
- Zalo adapter doc: drops the "community adapter" callout that
duplicated frontmatter.
**Tooling / CI**
- Adds `tsx` as a root devDependency so `pnpm sync-resources` works out
of the box (it previously relied on `npx tsx`, which hung when not
pre-cached).
- Loosens the CI changeset gate to also skip `packages/chat/resources/`
(generated data), matching the existing `*.md` carve-out.
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
## summary
adds lower-level Slack helpers for custom runtimes that already own
routing, state, sessions, or workflow execution
this expands the existing Slack subpaths with typed inbound files,
richer interaction payload fields, thread reply fetching, modal opening,
and generic input request Block Kit helpers
it keeps the helpers on the existing `@chat-adapter/slack` package and
preserves the runtime-light import boundary for `webhook`, `api`, and
`blocks`
## summary
adds a first-class Twilio adapter for SMS and MMS bots, plus low-level
voice helpers for custom Twilio voice routes
this includes webhook parsing and signature verification, outbound
Messages API helpers, phone-number and Messaging Service sending,
inbound MMS attachments with authenticated `fetchData`, plain text card
fallback rendering, markdown conversion, and runtime-light `api`,
`webhook`, `voice`, and `format` subpaths
the adapter intentionally avoids the `twilio` npm runtime dependency so
apps can use the low-level helpers without pulling in the full SDK
## summary
documents the low-level Slack subpaths for custom runtimes that own
routing, state, sessions, or workflow execution
covers `@chat-adapter/slack/webhook`, `@chat-adapter/slack/format`,
`@chat-adapter/slack/api`, and `@chat-adapter/slack/blocks`, including
when to use them instead of the full `createSlackAdapter` runtime
also links the new guide from the Slack adapter page
## Summary
Introduces a dedicated `chat/ai` subpath as the home for every Vercel AI
SDK helper that ships with Chat SDK. Importing from this subpath keeps
the optional `ai` and `zod` peer dependencies out of bundles that don't
use them.
### What's new
- **`createChatTools`** — exposes Chat SDK operations as ready-to-use AI
SDK tools so an agent can read, post, react, edit, delete, and manage
thread subscriptions across every adapter the supplied `Chat` instance
has registered.
- Write operations require user approval by default (`requireApproval:
true`); toggle globally or per-tool.
- Three presets — `reader`, `messenger`, `moderator` — scope the
toolset.
- Individual tools can also be cherry-picked (`import { postMessage,
addReaction } from "chat/ai"`).
- **`toAiMessages`** (and the `Ai*` / `ToAiMessagesOptions` types) now
live alongside the tools at `chat/ai`. The previous `chat` re-exports
continue to work, but are flagged `@deprecated` with an editor hint
pointing to the new home — migration is a one-line import change.
- **Docs** — new `/docs/ai` section between Usage and Adapters in the
sidebar:
- `/docs/ai` — Overview
- `/docs/ai/ai-sdk-tools` — `createChatTools` guide
- `/docs/ai/to-ai-messages` — `toAiMessages` reference
- `/docs/ai/types` — Reference for every type exported from `chat/ai`
- **Example app** — `examples/nextjs-chat` now demos the new surface via
a "Run Agent Demo" button on the welcome card and a free-form `/agent
<prompt>` slash command (streaming, with a placeholder so users get
immediate feedback in channel contexts where Slack's typing-status API
is a no-op).
### Future plans
`createChatTools` currently exposes the cross-adapter Chat SDK surface
only. A natural follow-up is to also support **platform-specific tools**
— e.g. expose Slack-only `pin`/`unpin`, Discord-only thread archiving,
GitHub-only issue commenting, etc., so users can further extend what
their agent can do without dropping back to raw adapter calls. The shape
would likely be additional opt-in factories under `chat/ai` (or
per-adapter subpaths like `@chat-adapter/slack/ai`) that return tools
layered on top of the platform-specific adapter clients, while keeping
the cross-platform `createChatTools` API as the lowest common
denominator.
### Coverage
- `createChatTools` orchestrator: 100% statements / 94.7% branches.
- Every tool factory's `execute()` is exercised end-to-end (29 tests in
`index.test.ts`).
- `toAiMessages` keeps its existing 35-test suite covering role mapping,
attachment handling, links, transforms, and unsupported-attachment
fallbacks.
- Tools folder overall: 99.0% statements / 86.1% branches / 97.4%
functions / 98.9% lines.
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
Co-authored-by: dancer <josh@afterima.ge>
## summary
adds an opt-in `burst` concurrency strategy for #414
when a thread is idle, the first message waits for `debounceMs`,
messages that arrive during that window are queued, and the handler runs
once with the latest message plus earlier burst messages in
`context.skipped`
after the handler finishes, messages that arrived while it was running
are drained like `queue`, so the latest queued message is processed with
earlier queued messages in `context.skipped`
keeps existing `drop`, `queue`, `debounce`, and `concurrent` behavior
unchanged
updates docs to cover `burst`, explain when to choose it over
`debounce`, and document the related `MessageContext` behavior
## Summary
<!-- What does this PR do? -->
## Test plan
<!-- How did you verify the changes? -->
## Checklist
- [ ] All commits are signed and verified
- [ ] `pnpm validate` passes
- [ ] Changeset added (or N/A — see
[CONTRIBUTING.md](./CONTRIBUTING.md))
- [ ] Documentation updated (or N/A)
---------
Co-authored-by: dancer <josh@afterima.ge>
## Summary
Rename the public native client getter on the GitHub, Linear, and Slack
adapters so it matches the underlying SDK class instead of the generic
`.client`. The previous `.client` getter is preserved as a `@deprecated`
alias on all three adapters, so existing code keeps working without
changes.
- `bot.getAdapter("github").client` is now
`bot.getAdapter("github").octokit` (returns `Octokit`)
- `bot.getAdapter("linear").client` is now
`bot.getAdapter("linear").linearClient` (returns `LinearClient` from
`@linear/sdk`)
- `bot.getAdapter("slack").client` is now
`bot.getAdapter("slack").webClient` (returns `WebClient` from
`@slack/web-api`)
Each new getter has TSDoc covering single- vs multi-tenant resolution
rules and when calling outside a webhook handler throws. Focused unit
tests assert that the new getter returns the underlying SDK instance,
that single-tenant calls return the same instance, that the deprecated
`.client` alias points at the new getter, that multi-tenant mode without
webhook context throws on both getters, and that inside a webhook
context the getter resolves to the per-tenant client.
Commits are split for review:
1. `feat(adapter-github): rename adapter.client to adapter.octokit`
2. `feat(adapter-linear): rename adapter.client to adapter.linearClient`
3. `docs: use .octokit / .linearClient in chat-sdk.dev examples`
4. `chore: changeset for adapter native client getter rename`
5. `fix: hoist regex literals in new client-getter tests to module
scope`
6. `feat(adapter-slack): rename adapter.client to adapter.webClient`
7. `docs: include slack .webClient in chat-sdk.dev examples`
8. `chore: include adapter-slack in native client getter rename
changeset`
9. `test(adapter-github,adapter-linear): cover with-context resolution
on the new client getters`
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
## Summary
Refreshes the adapter docs end-to-end so every adapter — official,
vendor-official, and community — now ships hand-authored MDX, lives
under a clean URL structure, and renders on a polished
sidebar/right-rail layout dedicated to `/adapters` (the shared `/docs`
chrome is untouched).
```mermaid
flowchart LR
subgraph Before
direction TB
OB[official] --> CB[community<br/>incl. 5 vendor pages]
end
subgraph After
direction TB
OA[official] --> VA[vendor-official<br/>5 pages] --> CA[community]
end
Before -.-> After
```
### Content & routing
- **New `/adapters/vendor-official/<slug>` route** for vendor-maintained
adapters (Beeper Matrix, Photon iMessage, Liveblocks, Resend, Zernio).
Sidebar gets a third labelled group ("Vendor-Official Adapters") between
Official and Community, with a top divider matching the existing
Community treatment.
- **All 13 vendor-official + community adapters migrated** from runtime
README fetching to hand-authored MDX with rich `features:` matrices and
full body content (install, quick start, configuration, auth,
gateway/streaming, troubleshooting). README fetch stays as a fallback
for any future community adapter that hasn't been migrated yet, gated by
a new `mdxBody: true` frontmatter flag.
- **Messenger filter pages removed** (`/adapters/for/<messenger>` + the
"Browse by messenger" chip row on `/adapters`). Existing URLs
308-redirect to `/adapters`.
- **Permanent redirects** from
`/adapters/community/{matrix,imessage,resend,zernio,liveblocks}` to
their new `/adapters/vendor-official/...` paths.
- **Fixed** `/docs/adapters` and `/docs/state` so the bare pages are
accessible again — the previous catch-all redirect (`:slug*`) was
swallowing them. Switched to `:slug+` so subpath URLs still 308 while
the bare pages render.
### Visual polish
- **Adapter-only sidebar variant** (`AdaptersDocsLayout` +
`AdaptersSidebar`) with uppercase eyebrow separators, tighter rows, and
a thin themed scrollbar utility class. The shared `/docs` sidebar is
untouched.
- **Restyled `AdapterHero`**: drops the badges row + packageName, sits
the title inline with the logo, larger 17 px tagline, horizontal divider
beneath the block.
- **Restyled `PackageInstall`** as a tabbed dark single-line snippet
with a `$` prompt prefix and a copy button — replaces the previous
multi-line `CodeBlock` layout.
- **New "Deploy your chat app on Vercel" upsell card** (`<Upsell />`)
replaces the old `EditSource / ScrollTop / Feedback / CopyPage` footer
cluster on every adapter detail page.
- **Listing & messenger pages**: align the H1 to a tighter `text-4xl
sm:text-[44px]`, and the section headers to `text-base font-medium
tracking-tight` with a one-line muted lede.
### Tooling & tests
- Added `mdxBody: true` opt-in to the adapter frontmatter schema
(`source.config.ts`), and updated both detail-page handlers
(`community/[slug]` and the new `vendor-official/[slug]`) to render the
MDX body when present, falling back to README fetch otherwise.
- Refactored both detail-page handlers to flatten the body-render
branches into a `renderBody()` helper, removing the nested ternaries
that were tripping `lint/style/noNestedTernary`.
- New test file
[`packages/integration-tests/src/docs-adapters.test.ts`](https://github.com/vercel/chat/blob/docs/refresh-adapters/packages/integration-tests/src/docs-adapters.test.ts)
— **220 new assertions** covering:
- Adapter MDX frontmatter completeness, slug ↔ filename consistency, and
`type ∈ {platform, state}`.
- Vendor-official invariants: exactly the expected slugs,
`vendorOfficial: true`, `community: true`, `author`, `mdxBody: true`,
`<FeatureSupport />` rendered.
- Community invariants: `community: true` (never vendor-official),
`mdxBody: true`, `<FeatureSupport />`.
- Official invariants: never flagged, `packageName` always under
`@chat-adapter/*`.
- `adapters.json` ↔ MDX sync on `packageName` / `type` / `community` /
`vendorOfficial`.
- Extended `VALID_DOC_PACKAGES` so `docs-content.test.ts` accepts the
new vendor-official + community packages, plus `@chat-adapter/web`,
`@chat-adapter/web/react`, and `@chat-adapter/messenger`.
### Per-package AGENTS.md
- Added `AGENTS.md` to every official adapter and state adapter (14
packages), each tailored to that adapter's surface — overview, directory
layout, build/test commands, public exports, thread ID format, webhook
flow, authentication, format conversion, cards/streaming, platform
quirks, testing approach, coding conventions, and release rules.
- Added a one-line `CLAUDE.md` (`@AGENTS.md`) beside each so Claude Code
picks up the same instructions through its built-in resolver — same
convention as the root.
### Web adapter copy
- Cleaned up the Web adapter tagline (removed inline backticks) and
dropped the now-redundant "v1 scope" section from the body.
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
## summary
clarifies that registered `onDirectMessage` handlers take precedence for
incoming DM messages before subscribed-message, mention, and pattern
routing
updates the direct messages, event handling, thread subscription, and
API docs so they match the current runtime behavior
adds `onDirectMessage` to the Chat API docs
fixes#432
* chore: changed class function access to protected
* chore: format
* chore: added changeset
* chore(changeset): drop unchanged shared package, expand description
* refactor(adapters): keep internal state private, only protected for extension surface
Narrow scope of #475: caches, polling/runtime state, and one-shot warning
flags stay private. Methods and shared helpers (logger, formatConverter,
chat, config) remain protected as the documented extension surface.
Also fixes a typecheck failure where gchat's oauth2Client (now private)
no longer requires a portable type for the emitted .d.ts.
* test(adapters): add subclass extensibility tests
Each adapter now has a compile-time test that subclasses can access the
documented protected surface. If any of these members revert to private,
the test file fails to type-check.
* style: apply ultracite formatting to subclass tests
* style(slack): mark static cache TTL constants as readonly
These three protected static cache TTLs are configuration constants, not
mutable state. Marking them readonly prevents subclasses (the new extension
surface from this PR) from mutating values shared across every instance
in-process.
* test(adapters): document intent of subclass extensibility tests
Mirrors the inline comment from the Telegram subclass test across the other
nine adapter tests so future readers immediately understand these blocks are
type-only sentinels — they fail at typecheck (not vitest) if a member reverts
to private.
* docs(adapters): document subclassing for adapter customization
Adds a "Customizing an adapter via subclassing" section to the Adapters page
that walks through extending an official adapter to override a protected hook
(using the issue #433 Telegram processUpdate scenario as the canonical
example) and clarifies that private members are intentionally off-limits.
* refactor(linear): expose accessTokenExpiry to subclasses
The surrounding refreshClientCredentialsToken and ensureValidToken methods
are now protected, but accessTokenExpiry was kept private — meaning a
subclass overriding either method couldn't read or update the expiry without
calling super. Flipping it to protected lets subclasses fully reimplement
the token-refresh flow.
* chore(changeset): bump adapters from patch to minor
This PR adds a new, additive capability — subclassing official adapters to
override protected hooks. Per CONTRIBUTING.md, additive backward-compatible
features warrant a minor bump rather than a patch.
* docs(adapters): clarify subclassing surface stability
Correct the parenthetical describing what stays `private` (credentials are
now `protected`) and add a callout warning that the `protected` extension
surface is intentionally broader than the public API but not yet fully
stable, so subclass authors know to pin versions and prefer overriding
the smallest hook.
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
* chore: Add Messenger logo to homepage
* chore: Use Messenger brand colour for logo
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
* Revert "feat(slack): expose direct WebClient access via adapter.client (#471)"
This reverts commit 8366b8b0fb.
* Fix: The `createSlackAdapter()` helper function silently drops the `apiUrl` config field, so custom Slack API URLs (e.g., for GovSlack) are ignored when using the helper.
This commit fixes the issue reported at packages/adapter-slack/src/index.ts:5055
**Bug explanation:**
The `SlackAdapterConfig` interface defines an `apiUrl` field (line 166) that allows users to override the Slack Web API base URL — useful for GovSlack or self-hosted gateways. The `SlackAdapter` constructor reads this field at line 622:
```typescript
const slackApiUrl = config.apiUrl ?? process.env.SLACK_API_URL;
```
However, the `createSlackAdapter()` helper function (around line 5055) constructs a `resolved` config object that includes many fields from the user's config but omits `apiUrl`. This means when a user writes:
```typescript
createSlackAdapter({ apiUrl: "https://slack-gov.com/api/" })
```
The `apiUrl` is silently dropped and the `WebClient` is created without the custom URL. The `SLACK_API_URL` environment variable fallback still works (since it's checked in the constructor), but explicit config via the helper is lost.
This is clearly a bug — all other config fields are forwarded through the `resolved` object, and `apiUrl` was simply forgotten.
**Fix explanation:**
Added `apiUrl: config?.apiUrl,` to the `resolved` config object in `createSlackAdapter()`. This ensures the `apiUrl` value from user config is properly forwarded to the `SlackAdapter` constructor, matching the pattern used for all other optional config fields.
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
Co-authored-by: visyat <vishal.yathish@gmail.com>
---------
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
* feat(slack): expose direct WebClient access via adapter.client
Mirror the Linear and GitHub adapter pattern by exposing the underlying
@slack/web-api WebClient as `adapter.client` for any Web API call not
covered by the SDK's high-level methods.
Resolution order:
1. Token from the current request context (multi-workspace webhooks,
`withBotToken()`).
2. The default `botToken` when configured as a static string or a
synchronous resolver function.
Throws AuthenticationError outside of any context in multi-workspace
mode, or when `botToken` is configured as an async resolver. For both,
bind the token explicitly with `adapter.withBotToken(token, () => ...)`.
Internally, the existing private `client` field is renamed to `_client`
so the public getter can return per-token cached `WebClient` instances.
All internal API calls continue to route through `_client.foo(await
this.withToken(...))` unchanged. Also fixes `createSlackAdapter()`
silently dropping the `apiUrl` config field, surfaced by the new
apiUrl-propagation test.
* docs(slack): document direct WebClient access
Add Slack to the "Direct client access" section of the chat-sdk.dev
docs (api/chat.mdx, usage.mdx) alongside Linear and GitHub. Update the
multi-tenant Callout to spell out both Slack constraints — request
context required in multi-workspace mode, and `withBotToken()` required
when `botToken` is an async resolver.
Add a parallel "Direct WebClient access" section to the Slack adapter
README with a usage example, the token resolution order, and the
async-resolver workaround.
* feat(example): add Channel Info button using slack.client
Demonstrate the new direct WebClient access pattern in the nextjs-chat
demo with a "Channel Info (Slack)" button. The handler resolves the
Slack adapter from the action event, reaches into
`adapter.client.conversations.info` (channels:read scope, already in
the example manifest), and renders the result as a Card with channel
name, member count, topic, purpose, and the standard flags. Falls back
to a friendly message on non-Slack platforms.
* feat(example): add Pin Message button using slack.client.pins.add
Pin the welcome card itself via `adapter.client.pins.add({ channel,
timestamp: event.messageId })` to demonstrate calling a Slack Web API
endpoint not wrapped by the SDK. Adds the required `pins:write` scope
to the example Slack manifest.
* chore(example): render channel info as a table and include num_members
Replace the Fields/Section layout in the Channel Info card with a
two-column Table for a tidier presentation, and pass
`include_num_members: true` so the Members row is actually populated
(Slack's `conversations.info` omits it by default).
* test(slack): expand coverage for adapter.client
Adds three tests:
- Cache differentiation: distinct tokens produce distinct WebClient
instances so per-workspace credentials never bleed across calls.
- apiUrl env var resolution: SLACK_API_URL is honored by the WebClient
the new getter returns (covers GovSlack-style deployments).
- End-to-end multi-workspace token routing: a real block_actions
webhook drives `processAction`, and the handler-side
`event.adapter.client.token` matches the installation's bot token —
proving the request-context-bound client works inside webhook
dispatch.
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
* feat(tests): add @chat-adapter/tests test kit
New package providing Vitest factories, custom matchers, and a setup file for
people building Chat SDK adapters and bots.
Factories: createMockAdapter, createMockChatInstance, createMockState (with
working in-memory subscriptions/locks/KV/queues), createTestMessage,
mockLogger / createMockLogger.
Matchers: toHavePosted(threadId, textPattern?), toHaveDispatched(handler),
toBeSubscribedTo(threadId). Auto-register via the
'@chat-adapter/tests/setup' subpath in vitest setupFiles.
chat and vitest are peer dependencies. Adapter-specific helpers (e.g. signed
Slack webhook builders) belong in each adapter's own /testing subpath, not
in this kit.
* test(integration-tests): allow @chat-adapter/tests imports in README check
* docs: add Testing page covering @chat-adapter/tests
New content/docs/testing.mdx walks bot authors and custom-adapter authors
through the kit's factories, custom matchers, and setup file. Added under
the Usage section in the sidebar, after error-handling.
Cross-link from contributing/testing.mdx clarifying that the hand-rolled
patterns there are for repo contributors building first-party adapters,
while consumers of Chat SDK should use @chat-adapter/tests.
* test(integration-tests): allow @chat-adapter/tests imports in docs check
* fix(tests): match real Adapter.postMessage signature in toHavePosted
Adapter.postMessage is (threadId: string, message: AdapterPostableMessage)
— previously the matcher read args[0] as { id: string } and args[1] as
{ text: string }, neither of which match the actual SDK shape. The matcher's
own tests fed the same wrong shape into the mock so they passed locally
while the matcher silently failed against any real bot or adapter.
Now compares args[0] as a string threadId, and extracts a comparable string
from AdapterPostableMessage's union — strings directly, PostableMarkdown
.markdown, PostableRaw.raw, and PostableCard.fallbackText. PostableAst and
fallback-less cards aren't text-matchable; documented in the JSDoc.
Tests updated to call postMessage with the real signature and to cover
each comparable AdapterPostableMessage shape.
* test(tests): add smoke tests driving matchers against a real Chat
Construct a real `Chat` with a `createMockAdapter` + `createMockState` and
exercise `Chat.thread().post()` and `.subscribe()` end-to-end. The matchers
(toHavePosted, toBeSubscribedTo) then assert against the actual call shape
the SDK uses, so a future signature drift breaks here instead of silently
agreeing with whatever wrong shape lives in the unit tests.
This is the regression guard for the postMessage-shape bug fixed in the
prior commit: each new matcher in subsequent PRs should be paired with a
smoke case here.
* feat(tests): round out adapter mutation matchers
Adds toHaveEdited, toHaveDeleted, toHaveReactedWith, toHaveStartedTyping,
and toHavePostedToChannel — covering the common Adapter mutation surface
that bot authors assert on. Each matcher's signature was checked against
packages/chat/src/types.ts, and each is paired with a smoke case that
drives a real Chat through the corresponding Thread/Channel API so
signature drift breaks the smoke test instead of silently agreeing with
the unit tests.
Emoji matching accepts both plain strings and EmojiValue ({ name }).
Text matching reuses the same extraction rules as toHavePosted —
strings, PostableMarkdown.markdown, PostableRaw.raw, and
PostableCard.fallbackText. Documented in matcher JSDoc, README, and
the Testing docs page.
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
* [messenger] add messenger (meta) platform adapter to chat sdk
- Webhook handling with HMAC-SHA256 signature verification
- Generic and Button template support for cards
- Postback, reaction, delivery/read confirmation handling
- Message caching for fetchMessages (Messenger has no history API)
- Replay tests and ~98% code coverage
Co-authored-by: Dimitar K. Nikolov <mitkodkn@users.noreply.github.com>
Co-authored-by: Ben Sabic <27636870+bensabic@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
* Fix: The `@chat-adapter/messenger` package version is `4.15.0` while all other packages in the Changesets fixed version group are at `4.27.0`, breaking the fixed versioning contract.
This commit fixes the issue reported at packages/adapter-messenger/package.json:3
**Bug explanation:**
The repository uses Changesets with a `"fixed"` configuration: `[["chat", "@chat-adapter/*"]]`. This means all packages matching these patterns must always share the same version number. Every package in the group (`chat`, `@chat-adapter/discord`, `@chat-adapter/gchat`, `@chat-adapter/github`, `@chat-adapter/linear`, `@chat-adapter/shared`, `@chat-adapter/slack`, `@chat-adapter/teams`, `@chat-adapter/telegram`, `@chat-adapter/web`, `@chat-adapter/whatsapp`, and the state packages) is at version `4.27.0`, except `@chat-adapter/messenger` which is at `4.15.0`.
This is likely because the messenger adapter was newly added to the monorepo (copied from a template or created fresh) and its version was never aligned with the rest of the fixed group. This mismatch will cause problems with the Changesets release workflow — when Changesets tries to bump versions for the fixed group, it may produce inconsistent or errored releases because one package is 12 minor versions behind the others.
**Fix explanation:**
Changed `"version": "4.15.0"` to `"version": "4.27.0"` in `packages/adapter-messenger/package.json` to align it with all other packages in the fixed version group.
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
Co-authored-by: visyat <vishal.yathish@gmail.com>
* Fix: Messenger adapter env var guard only checks `FACEBOOK_APP_SECRET` but `createMessengerAdapter` requires all three env vars, causing a `ValidationError` crash at Next.js build time when only `FACEBOOK_APP_SECRET` is set.
This commit fixes the issue reported at examples/nextjs-chat/src/lib/adapters.ts:154
**Bug Analysis:**
The build failure is confirmed in the Vercel build log with:
```
Error [ValidationError]: pageAccessToken is required. Set FACEBOOK_PAGE_ACCESS_TOKEN or provide it in config.
```
The root cause is in `examples/nextjs-chat/src/lib/adapters.ts` at line ~154. The messenger adapter guard only checks for `FACEBOOK_APP_SECRET`:
```typescript
if (process.env.FACEBOOK_APP_SECRET) {
```
However, `createMessengerAdapter` (in `packages/adapter-messenger/src/index.ts`) validates and throws `ValidationError` for each of three required env vars: `FACEBOOK_APP_SECRET`, `FACEBOOK_PAGE_ACCESS_TOKEN`, and `FACEBOOK_VERIFY_TOKEN`. When only `FACEBOOK_APP_SECRET` is set in the Vercel project environment, the guard passes, `createMessengerAdapter` is called, and it throws a `ValidationError` for the missing `FACEBOOK_PAGE_ACCESS_TOKEN`. Since this code runs at module evaluation time during the Next.js build's "Collecting page data" phase, the uncaught error crashes the entire build.
This is inconsistent with other adapters in the same file. For example, the WhatsApp adapter checks both `WHATSAPP_ACCESS_TOKEN` and `WHATSAPP_PHONE_NUMBER_ID`, and the gchat/github/linear/whatsapp adapters all wrap creation in try-catch blocks.
**Fix:**
1. Updated the env var guard to check all three required environment variables (`FACEBOOK_APP_SECRET`, `FACEBOOK_PAGE_ACCESS_TOKEN`, and `FACEBOOK_VERIFY_TOKEN`) before attempting to create the adapter.
2. Wrapped the `createMessengerAdapter` call in a try-catch block (matching the pattern used by gchat, github, linear, and whatsapp adapters) so that any unexpected validation errors are caught and logged as warnings instead of crashing the build.
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
Co-authored-by: visyat <vishal.yathish@gmail.com>
---------
Co-authored-by: Dimitar K. Nikolov <mitkodkn@users.noreply.github.com>
Co-authored-by: Ben Sabic <27636870+bensabic@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
* 1
* w
* 3f
* x
* ln
* gh
* sl
* t1
* u
* t2
* t3
* t4
* t5
* d
* d2
* cs
* fx
* cl
* docs: clean up subject + .client docs and restructure nav
- subject.mdx: simplify prose, drop redundant platform lists, link to MessageSubject API and getAdapter
- api/message.mdx: add MessageSubject TypeTable
- api/chat.mdx: expand getAdapter with Direct client access content
- adapters.mdx: add Parent subject and Native client rows to feature matrix
- usage.mdx: mention .client under Accessing adapters
- adapter-github/-linear READMEs: add Direct API client section
- meta.json: split Features into Messaging + Interactivity, move error-handling to Usage
- title case across messaging-cluster page titles
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
OSS Polar Bear