* [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>
* feat(chat): expose awaitable Promise from processMessage
Return the inner task as Promise<void> instead of void so streaming
adapters can await full handler completion and surface user-handler
rejections at the wire level. waitUntil semantics for existing webhook
adapters are unchanged — the SDK still tracks the work with errors
swallowed (and logged) so platforms don't retry on handler bugs.
Required by @chat-adapter/web, whose response body is the user
handler's stream.
* feat(adapter-web): add @chat-adapter/web package
A new platform adapter that lets a chat-sdk bot serve a browser chat
UI alongside Slack/Teams/Discord/etc. without writing any client-side
glue. Speaks the AI SDK UI message stream protocol, so @ai-sdk/react's
useChat and the ai-elements component library work out of the box.
- `@chat-adapter/web` — server: createWebAdapter({ userName, getUser })
- `@chat-adapter/web/react` — client: useChat() preconfigured with
DefaultChatTransport against /api/chat (override via `api`)
Defaults that matter for v1:
- `isDM: true` — every web message routes through onDirectMessage
- `persistMessageHistory: true` — chat-sdk caches each turn in the
configured state adapter so handlers can read prior context via
thread.messages / channel.messages (no platform history API exists)
- channelId === threadId — web has no separate channel concept; this
prevents cross-conversation bleed when a single user has multiple
useChat sessions
- Native `adapter.stream` implementation pumps text-deltas straight
onto the SSE response — no post+edit fallback
Out of scope for v1: cards/JSX rendering, reactions, modals, file
uploads, edit/delete, multi-tab proactive push.
* feat(example-nextjs-chat): wire up web adapter and add /chat page
- Register the web adapter in lib/adapters.ts with a demo getUser
(single shared identity — replace with NextAuth/Clerk/cookie auth
in production)
- Expose POST /api/chat backed by bot.webhooks.web (using next/after
for waitUntil)
- Add a minimal /chat page using @chat-adapter/web/react's useChat —
same bot.onDirectMessage handler that powers Slack now powers the
browser too
Bumps `ai` to ^6.0.174 to align with @ai-sdk/react@^3 (avoids dual
provider-utils versions in the workspace).
* docs: list @chat-adapter/web in registry
- Add an entry to adapters.json so the package shows up on /adapters
- Add a globe SVG to lib/logos.tsx and wire it into the icon map
- Mention the new adapter in docs/adapters.mdx
* feat(adapter-web): tighten request handling and message construction
- Reject user ids containing ':' with HTTP 400 — the character would
corrupt the thread-id round-trip through decodeThreadId
- Skip emitting text-start/text-end in postMessage when the resolved
text is empty so useChat doesn't render blank assistant bubbles
- Derive the parseMessage author from raw.role so rehydrated assistant
messages report the bot identity instead of "unknown"
- Drop the duplicate handler-error log; chat.processMessage already
logs at ERROR level
- Document the actual persistMessageHistory default (true) and the
state-cache rationale; promote the fetchMessages no-op rationale
into its JSDoc
* test(adapter-web): add direct coverage for stream()
- Aborting request.signal mid-stream short-circuits the iterator and
still writes text-end via the finally block
- Non-text StreamChunks (task_update, plan_update) are dropped without
emitting any delta
- The SentMessage returned from thread.post matches the id used in
text-start / text-end events
* docs(adapter-web): expand README into the full adapter docs page
The docs site renders each adapter's README, so flesh out
@chat-adapter/web to match the depth of @chat-adapter/slack:
authentication boundary, threading semantics, streaming,
persistence, React hook reference, configuration table,
feature matrix, and troubleshooting.
* docs(adapter-web): drop unsupported provider import from streaming example
* fix(adapter-web): validate conversationId for reserved colon character
* fix(example): show error state in web chat demo
* fix(example): add thinking indicator to web chat demo
* feat(example): redesign web chat demo with tailwind
* chore: remove redundant changeset
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
Co-authored-by: dancer <josh@afterima.ge>
* feat(chat): add Transcripts API and rename per-thread cache to threadHistory
Introduce `bot.transcripts` for cross-platform per-user message persistence.
When `ChatConfig.transcripts` and `ChatConfig.identity` are configured, every
inbound message has its `userKey` resolved during dispatch and the API exposes
`append` / `list` / `count` / `delete` keyed by that user. Backed by the
existing `StateAdapter.appendToList` primitive — every built-in state adapter
supports it with no contract changes.
Rename the existing per-thread history cache from `messageHistory` to
`threadHistory` (with backwards compat for `ChatConfig.messageHistory` and
`Adapter.persistMessageHistory`) so the two persistence layers don't share a
"messages" name. The state-adapter storage key prefix is unchanged so existing
data isn't orphaned.
`delete()` writes a tombstone via `appendToList(key, _, { maxLength: 1 })`
rather than `state.delete(key)`, because `state.delete` only addresses the
k/v namespace on every non-memory state adapter — `list()` and `count()`
filter the tombstone out so the API contract is preserved.
* docs(chat): cover Transcripts API and Conversation history
Add a Features-style "Conversation history" guide (`/docs/conversation-history`)
walking through identity resolution, the LLM-context append/list pattern,
filtering, and per-user deletion for DSR flows.
Add an API reference page at `/docs/api/transcripts` with `<TypeTable>` blocks
for `ChatConfig.transcripts`, `ChatConfig.identity`, every method on
`bot.transcripts`, and the `TranscriptEntry` shape.
Wire both into the corresponding `meta.json` files.
* example(nextjs-chat): wire Transcripts API into the AI mode handler
Replace the brittle `threadState.history` shim with `bot.transcripts.list({ ..., threadId, limit })` as the fallback context source for platforms without
`fetchMessages` (Telegram, WhatsApp). Drop the `history` field from
`ThreadState` accordingly.
Add a hardcoded `TEST_USER_KEY = "test-user"` so the API can be exercised
without juggling real user identities, plus "Show Transcripts" and
"Clear Transcripts" buttons in the welcome card so the store can be
inspected and reset from chat.
* fix(chat): tighten Transcripts API public surface and wiring
Polish on top of the Transcripts API + threadHistory rename, addressing
review concerns before merge.
Public surface (`types.ts`, `index.ts`):
- Expose `transcripts` on the `ChatInstance` interface so callers typed
against the public interface can reach `bot.transcripts`.
- Promote the `count` argument to a named `CountQuery` interface,
matching `DeleteTarget` / `ListQuery`. Exported from `index.ts`.
- Document on `TranscriptsApi.list()` that pagination is intentionally
out-of-scope — the store keeps at most `maxPerUser` entries per user.
- Reconcile the `TranscriptEntry.id` JSDoc with the implementation:
UUID assigned at append time, returned in append order, not
lexicographically sortable; use `timestamp` for cross-store ordering.
Wiring (`chat.ts`):
- Include `threadId` in the identity-resolver failure log context so
operators can correlate failures with the source thread.
Stale-reference sweep:
- Replace lingering "Messages API" / `chat.messages` /
`messages.storeFormatted` strings in shipped JSDoc with the new
`transcripts` names (these ride into `.d.ts` and are user-visible).
- Fix the dead `[Messages API](./messages.ts)` link in the existing
thread-history-rename changeset.
* test(chat): cover dual-read precedence, resolver edges, concurrent ops
Fill gaps in the Transcripts API + threadHistory rename test suite:
`chat.test.ts` (persistThreadHistory block):
- top-level `config.messageHistory` (deprecated alias) flows through
to the per-thread cache when `threadHistory` is unset
- `threadHistory` takes precedence over `messageHistory` when both are
set — pinned by asserting `appendToList` receives the new config's
`maxLength` / `ttlMs`
- both `persistThreadHistory` and `persistMessageHistory` set on the
adapter still triggers persistence
`transcripts-wiring.test.ts`:
- sync resolver returning a plain string populates `message.userKey`
- resolver returning `""` is treated as no userKey (truthy check at
the dispatch hook would silently flip if a future change moved to
`!== undefined`)
`transcripts.test.ts`:
- concurrent append/delete/append interleave preserves invariants:
`count()` and `list()` agree (no tombstone leak), no pre-delete
entry survives, and the post-delete result is bounded by the two
concurrent appends
* docs(chat): use named types in Transcripts API reference
- `formatted` rows in the AppendInput / TranscriptEntry TypeTables
now render `FormattedContent | undefined` (the alias actually
exported from `chat`), instead of `Root | undefined` which would
force readers to pull the type from `mdast` directly.
- `count` signature uses the new `CountQuery` named type, with a
one-liner describing its single field.
* example(nextjs-chat): fix stale comment on transcripts demo handler
The action handler was relabelled to `transcripts` when it was wired
to `bot.transcripts.list`, but the leading comment still read
"Demonstrate fetchMessages and allMessages" from the previous
iteration. Update it to describe the transcripts demo.
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
* feat(slack): use native markdown_text field for outgoing messages
Slack now natively renders markdown via the `markdown_text` parameter on
chat.postMessage / postEphemeral / update / scheduleMessage and via
response_url payloads. The adapter passes markdown through directly instead
of converting to mrkdwn.
- Tables, headings, code fences, blockquotes, and nested lists render
natively in Slack instead of falling back to ASCII / mrkdwn.
- `string` and `{ raw }` messages still go to `text` (preserves literal `*`).
- `{ markdown }` and `{ ast }` messages go to `markdown_text` (12k char limit).
- `renderWithTableBlocks`, `toBlocksWithTable`, `mdastTableToSlackBlock`,
and the AST→mrkdwn renderer (`fromAst` / `nodeToMrkdwn`) are removed.
- `SlackMarkdownConverter` alias is removed; use `SlackFormatConverter`.
- `renderFormatted(ast)` now returns standard markdown (was mrkdwn).
- Incoming `message` events still arrive as mrkdwn and are parsed unchanged.
Net -473 lines across markdown.ts and the five sender call sites.
* fix(slack): use mrkdwn fallback for response_url edits
* docs: cover gchat verification, linear token encryption, shared crypto helpers
The adapter hardening pass in #441 made gchat JWT verification required,
added optional at-rest encryption for Linear OAuth tokens, and promoted
the AES-256-GCM helpers into @chat-adapter/shared. Update the affected
package READMEs and the adapter-authoring guide to match.
* docs(adapter-shared): correct EncryptedTokenData field names
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
* fix(slack): enrich link previews with unfurl metadata from attachments
* fix(slack): add trailing slash normalization for unfurl URL matching
* fix(slack): store unfurl metadata from message_changed and enrich subsequent messages
* fix(slack): poll for unfurls so link metadata survives the message_changed race
* [chat] fix Slack streaming team ID for interactive payloads
* chore: downgrade changeset to patch
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
* feat(adapter-teams): use native Teams SDK streaming for DMs
Use ctx.stream.emit() from the Teams SDK for DM streaming instead of
manual post+edit. This sends proper typing activities with streamType
channelData, giving the native streaming UI in Teams.
- Capture IStreamer from activity context in handleMessageActivity
- Block handler with deferred promise so stream stays alive during processing
- streamViaEmit() for DMs: uses stream.emit() with incremental text deltas
- Group chats: accumulate full response and post as single message (no flicker)
- Handle StreamCancelledError and stream.canceled for graceful cancellation
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(tests): update Teams streaming assertions for accumulate-and-post
Group chats now accumulate streamed chunks and post as a single message
instead of post+edit, so assertions should check sentActivities not
updatedActivities.
* style: format replay-streaming test
* chore: add changeset for teams native streaming
---------
* docs(adapter-teams): simplify bot setup using Teams CLI
Replace manual 6-step Azure portal walkthrough with Teams CLI commands.
`teams app create` handles AAD registration, secret generation, bot
registration, and channel setup in a single command. Also updates RSC
permission and troubleshooting sections to reference CLI equivalents.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(adapter-teams): remove bot migration section
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(adapter-teams): clarify message history permissions by context
RSC permissions cover channels and group chats (no admin consent).
Azure AD Chat.Read.All is only needed for DM history. Add permission
table and az CLI commands for DM setup.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(adapter-teams): simplify bot setup using Teams CLI
Replace manual 6-step Azure portal walkthrough with Teams CLI commands.
Correct message history permissions: RSC for channels/group chats,
Azure AD only for DM history. Add local dev tunnel tip.
* docs(adapter-teams): add teams status step after login
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add chat.getUser() for cross-platform user lookups
Add UserInfo type and optional getUser() method to the Adapter interface.
Implement on Slack (extends existing lookupUser with email/avatar),
Discord, Google Chat, GitHub, Linear, and Telegram adapters.
Add "Who Am I" button to the example app demonstrating the feature.
Update docs with getUser API reference and usage examples.
* fix(chat): improve getUser across slack and gchat adapters
- slack: return null from lookupUser on failure instead of fallback
object, removing the isBot === undefined sentinel in getUser
- slack: use image_192 instead of image_72 for better avatar quality
- gchat: cache avatarUrl from webhook sender payload
- gchat: return avatarUrl in getUser response
- gchat: fix tests to use current cache format with isBot field
- docs: document null return, fix example to use message.author
* chore: fix lint
* docs(chat): include Microsoft Teams in getUser supported adapters list
* feat(adapter-teams): add getUser() support (#404)
* feat(adapter-teams): add getUser() via Microsoft Graph API
- Cache aadObjectId from activity.from during webhook handling
- Implement getUser() using Graph GET /users/{user-id} endpoint
- Requires User.Read.All application permission
- Returns null gracefully when user hasn't interacted or Graph call fails
* docs: add getUser() section to Teams adapter README
* chore: apply ultracite formatting to adapter-teams getUser
* fix(chat): cover all 7 adapters in getUser inference and document per-platform constraints
---------
Co-authored-by: dancer <josh@afterima.ge>
* feat(chat): add initialOption and option_groups to ExternalSelect
* docs(modals): document ExternalSelect initialOption and option_groups, truncate group label to 75 chars
* docs(state-pg): disclose chat_state_lists and chat_state_queues tables
The Data model section in the @chat-adapter/state-pg README listed only
three tables, but ensureSchema() also creates chat_state_lists and
chat_state_queues. Add them so the docs accurately describe what the
adapter writes to the database.
Closes#428
* docs(state-pg): document expired row cleanup for lists and queues
Extend the "Expired row cleanup" section to cover chat_state_lists and
chat_state_queues — both have expires_at columns. Note that queue
entries are purged opportunistically per-thread on enqueue/dequeue, and
list entries are filtered on read but never deleted, then add both
tables to the suggested periodic cleanup SQL.
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
* ci(release): pin changesets/action and enable npm provenance
Pin changesets/action to the v1.7.0 commit SHA, switch to GitHub-API
commit mode (signed commits via the API), set the version PR commit
and title to a conventional "chore(release): version packages", and
enable npm provenance attestations on publish via NPM_CONFIG_PROVENANCE.
* chore: add CODEOWNERS
Default ownership goes to @vercel/chat-sdk; release-plumbing paths
(release workflow, changeset config, CODEOWNERS itself) stay locked
to @cramforce since the publish workflow is bound to npm Trusted
Publisher by filename.
* docs: add SUPPORT.md and tidy issue contact links
Add a SUPPORT.md pointing users to docs, the issue chooser, and the
security advisory flow. Also update .github/config.yml: point the
Documentation contact link at chat-sdk.dev/docs (was a github.com
README anchor) and remove the GitHub Discussions entry, which 404s
because Discussions isn't enabled on the repo.
* chore: add docs issue and adapter request templates
Two new issue templates so reports come in pre-shaped:
- Documentation Issue — page/section, type (typo, outdated, missing,
broken link, etc.), description, suggested fix.
- Adapter Request — platform name, adapter type (platform/state), API
docs link, use case, existing community work, willingness to help
maintain.
* docs(contributing): point contributors at issue templates and SUPPORT.md
Add a "Reporting issues" section at the top of CONTRIBUTING.md that
links to the issue chooser (now covering bugs, features, docs issues,
and adapter requests) and to SUPPORT.md for general questions, with
the SECURITY.md private-disclosure path called out separately.
* chore: add pre-merge checklist to PR template
Adds four self-attestation boxes contributors can tick before
requesting review, surfacing requirements that already live in
CONTRIBUTING.md so they're not forgotten:
- Signed and verified commits (CONTRIBUTING explicitly bounces PRs
with unsigned commits).
- `pnpm validate` passes (lint, typecheck, tests, build in one go).
- Changeset added when a package's behavior changes.
- Docs updated for user-facing changes.
The "or N/A" wording on the last two avoids forcing a yes for
internal-only or docs-only PRs.
* chore: add Telegram and WhatsApp to bug report platform dropdown
The bug report platform dropdown was missing Telegram and WhatsApp,
which both have official adapters (@chat-adapter/telegram and
@chat-adapter/whatsapp). Reporters had to fall back to "Other" for
bugs in those adapters, losing the platform signal.
* docs(readme): fix CONTRIBUTING link path and add Support section
The Contributing section linked to ./CONTRIBUTING.md, but the file
actually lives at .github/CONTRIBUTING.md, so the link 404'd on
github.com. Repoint it.
Also add a Support section linking SUPPORT.md (general help) and
SECURITY.md (private vulnerability reporting) so those community
health files are reachable from the repo entry point instead of
only via GitHub's auto-surfacing.
* docs(contributing): add adapter authoring, commit conventions, and docs sections
Three additions to CONTRIBUTING.md to round out the file alongside
the recently added issue templates and PR checklist:
- "Building your own adapter" — points contributors who hit the
Adapter Request template at the existing community-adapter guide
on chat-sdk.dev rather than leaving them to discover it.
- "Commit messages" — codifies the Conventional Commits style the
repo already uses; the release workflow now relies on the
"chore(release): version packages" convention for its auto-PR,
so consistency in new commits keeps changelogs predictable.
- "Updating documentation" — names the apps/docs/content/docs/
source path, links the live site, and shows the local preview
command so the PR-template "Documentation updated" checkbox is
actionable.
* docs: trim agent docs, rename CLAUDE.md to AGENTS.md, add CLAUDE.md pointer
Move the agent guidance to AGENTS.md (the cross-tool convention) and
leave CLAUDE.md as a one-line "@AGENTS.md" pointer so Claude Code
keeps auto-loading the same content.
While renaming, trim and update the file:
- "packages/chat-sdk" was wrong — directory is "packages/chat", npm
name is "chat".
- Updated the package list to include adapter-{discord,telegram,
github,linear,zoom,shared}, state-{ioredis,pg}, integration-tests,
and the apps/docs and examples/nextjs-chat trees.
- Replaced the verbose recording-and-replay jq walkthrough with a
one-line pointer to the integration-tests README.
- Dropped the duplicated Changesets walkthrough — full guidance now
lives in CONTRIBUTING.md.
- Condensed ~120 lines of generic Ultracite/Biome rules to a short
list of non-obvious gotchas (Biome enforces the rest automatically).
- Added Conventional Commits (load-bearing for the release workflow's
auto-PR), the apps/docs/content/docs/ docs path with the "pnpm
--filter docs dev" preview command, a pointer to the community
health files, and POSTGRES_URL/DATABASE_URL for the new state-pg
adapter.
Net: 344 → ~125 lines.
* docs(nav): rename "Source" link to "GitHub"
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
- Add scripts/sync-resources.ts (run via pnpm sync-resources) that reads apps/docs/resources-edge-config.json, fetches each guide's .md version over https with a timeout and size cap, writes templates.json, and regenerates the Available resources block in skills/chat/SKILL.md
- Migrate the Slack Next.js, Discord Nuxt, and Hono code-review guides from on-site MDX to Vercel KB and register them in the resources edge-config JSON alongside the existing external guides
- Remove /docs/guides MDX content, sidebar entries, top-level Guides nav entry, getting-started cards, and the dead /guides/ branch in the sitemap route now that all guides live externally and are surfaced on /resources
- Replace the homepage Guides/Templates section and the standalone Adapters pill section with a single two-column Resources + Adapters section (icons, headings, descriptions, outline buttons, divider), and drop the URL footer from ResourceCard on the Resources page
- Update skills/chat/SKILL.md to point at resources/guides and resources/templates.json and list the available guides and templates between marker comments that sync-resources rewrites
- Add tsx to knip's ignoreBinaries so npx tsx in the new script does not fail lint
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
Co-authored-by: dancer <josh@afterima.ge>
* feat(slack): dynamic botToken resolver and custom webhookVerifier
Allow `botToken` to be a function returning `string | Promise<string>`
so apps can rotate or lazily fetch tokens; the resolver is invoked per
API call. Add `webhookVerifier: (request) => string | Promise<string>`
as an alternative to `signingSecret` for custom request verification —
returns the verified body text or throws to produce a 401.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* change verifier signature to make it compatible with function
* make scheduleMessage cancel() rotation-safe and honor verifier body
- scheduleMessage cancel(): re-resolve token in single-workspace mode so
rotation works. Slack rotated tokens have a 12h TTL and scheduled messages
can outlive their schedule-time token, leaving cancel() with stale auth.
Multi-workspace still snapshots ctx.token since cancel() runs outside
the AsyncLocalStorage frame.
- webhookVerifier: when it returns a string, use it as the verified body
for downstream parsing. JSDoc previously implied this contract; the code
only checked truthiness.
- webhookVerifier JSDoc: explicit SECURITY note that timestamp/replay
protection is the implementer's responsibility when bypassing signingSecret.
- Tests: cover Attachment.fetchData snapshot semantics — multi-workspace
uses the ctx token captured at attachment creation; single-workspace
re-resolves the default provider per fetch (rotation-safe).
* docs(slack): document botToken resolver and webhookVerifier in README
* opt out of SLACK_SIGNING_SECRET env fallback when webhookVerifier is set
A webhookVerifier passed in config was being silently shadowed by
SLACK_SIGNING_SECRET in the env (read by both createSlackAdapter and the
SlackAdapter constructor). An explicit verifier now opts out of that
fallback in both code paths. Added a regression test that stubs the env
var via vi.stubEnv.
* register handleReactionEvent's outer promise via waitUntil
handleReactionEvent does async work (conversations.replies, users.info)
before delegating to chat.processReaction, which is the only point that
registers a waitUntil task. The outer prep work was untracked, so callers
that drained waitUntil tasks could complete before the reaction handler
finished — flaky in CI under tight microtask scheduling. Track the outer
promise too so the full handler is awaited.
* fix(integration-tests): drain waitUntil cascade in test tracker
---------
Co-authored-by: dancer <josh@afterima.ge>
Restructures the docs homepage around the AI SDK section flow: hero
with command prompt + interactive demo, OSS stats grid, supported
platforms with feature pillars, Chat SDK Core code showcase, "Scale
with confidence" Vercel ecosystem integrations, and a closing
get-started section with three guides.
- New: oss-stats-section, supported-platforms, code-section,
integrations-section, get-started-section.
- Removed unused layout helpers: adapters-section, centered-section,
cta, one-two-section, text-grid-section, templates (folded into
get-started-section).
- Hero loses the badge and embeds the existing Demo as the
hero-interactive piece.
- Three guide cards link to the Slack agent guide, Knowledge Agent
template, and GitHub code review bot guide.
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
- Detect when files under packages/** have changed and skip the check otherwise
- Exclude markdown-only changes from triggering the check
- Run pnpm changeset status against the PR base branch to fail when a changeset is missing
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
Closes#417.
- handleConcurrent now acquires a per-thread semaphore slot when
maxConcurrent is finite; fast path preserved for the default Infinity.
- Constructor throws on maxConcurrent < 1 (would deadlock) and warns
when maxConcurrent is paired with a non-concurrent strategy (was
previously ignored silently).
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
* Bump Teams SDK to 2.0.8 and switch to User-Agent header
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(teams): remove unused ts-expect-error after SDK 2.0.8 upgrade
---------
Co-authored-by: dancer <josh@afterima.ge>
* fix(telegram): switch parse_mode from legacy Markdown to MarkdownV2
The Telegram adapter hardcoded `parse_mode: "Markdown"` (legacy) but
rendered messages via the SDK's generic `stringifyMarkdown()`, which
emits standard markdown. Two incompatible dialects glued together:
- Standard markdown uses `**bold**`, Telegram legacy uses `*bold*`
- Legacy Markdown has no escape rules — any message with `.`, `!`,
`(`, `)`, `-`, `_` in unexpected positions was rejected with
`can't parse entities`, which is virtually every LLM-generated
response
- Legacy Markdown is deprecated by Telegram and lacks support for
underline, strikethrough, spoiler, and blockquote
This commit:
- Switches TELEGRAM_MARKDOWN_PARSE_MODE to "MarkdownV2"
- Replaces fromAst() with a proper AST → MarkdownV2 renderer:
- Single `*bold*`, `_italic_`, `~strike~` markers
- Context-aware escaping: 20-char matrix for normal text, only
`` ` `` and `\` inside code blocks, only `)` and `\` inside link
URLs
- Headings rendered as bold (MarkdownV2 has no heading syntax)
- Ordered/unordered lists with escaped dashes and periods
- Blockquotes with per-line `>` prefix
- Tables pre-empted and rendered as ASCII code blocks
- Explicit handlers for reference-style links, images, HTML, and
definitions so nothing is silently dropped
- Routes card fallback text through `fromMarkdown` (not raw escape)
with `boldFormat: "**"` — @chat-adapter/shared's cardToFallbackText
defaults `boldFormat` to "*" (Slack mrkdwn), which would render as
italic on Telegram. Explicit "**" keeps the card title rendered as
real MarkdownV2 bold.
- Fixes resolveParseMode so every message routed through the format
converter (`{markdown}`, `{ast}`, cards, JSX) gets
`parse_mode: "MarkdownV2"`. Previously only `{markdown}` and cards
were covered, so `{ast}` messages shipped without parse_mode and
rendered asterisks literally.
- Documents inbound vs outbound dialects on applyTelegramEntities /
escapeMarkdownInEntity (inbound entities → standard markdown)
versus the new outbound MarkdownV2 renderer, so future
contributors don't confuse the two.
Tests: full 20-char MarkdownV2 escape matrix, context-escape tests
for code blocks and link URLs, nested-formatting tests, edge cases
(empty, whitespace-only, raw HTML), and an end-to-end LLM-output
corpus test that asserts MarkdownV2 validity (no unescaped special
chars outside entities or code blocks). Regression guards added in
index.test.ts for the AST / plain-string / raw parse_mode paths and
for card-title MarkdownV2 bold rendering.
Fixes#226
* feat(examples): add telegram-chat reference bot
Polling-mode Telegram bot that exercises the adapter end-to-end:
MarkdownV2 rendering, interactive cards with inline keyboards,
reactions, file uploads, and streaming edits. Runs with a single
`pnpm --filter example-telegram-chat start`; no webhook, no public
URL, no external API keys.
Menu structure — three categorized sub-menus reached from any DM text:
- Text & Markdown: plain, inline emphasis, code block, links, list+table,
20-char torture string, LLM-style corpus, streaming editMessage loop
- Cards & Actions: interactive approval card (edits in-place on press),
callback_data size probe demonstrating the 64-byte limit, LinkButton
- Media & Reactions: on-demand reaction one-shot (briefly subscribes),
generated 1×1 PNG upload, generated minimal PDF upload
Zero new runtime deps. PNG/PDF are hand-rolled in memory
(lib/png.ts, lib/pdf.ts) rather than pulled from a binary-processing
library. Failure handling is consistent: every demo runner is
try/catch-wrapped and posts an inline ❌ line with the error message.
Excluded from npm release via .changeset/config.json.
* fix(telegram): produce valid MarkdownV2 when truncating long messages
The MarkdownV2 migration widened a latent truncation bug into a reliable
400. The previous truncator sliced at 4096/1024 chars and appended
literal "..." — but in MarkdownV2 `.` is a reserved character, the slice
can leave an orphan trailing `\`, and it can cut through a paired
entity (`*bold*`, `` `code` ``) leaving it unclosed.
Unify the two truncate methods into one `truncateForTelegram(text,
limit, parseMode)` that appends `\.\.\.` for MarkdownV2 and walks back
past unbalanced entity delimiters or orphan backslashes. Plain text
keeps literal `...`. Adds 8 length-limit tests.
Related cleanup:
- Move MarkdownV2 string utilities and Bot API limits to markdown.ts.
- Type renderMarkdownV2 exhaustively on mdast's `Nodes` union with a
`never` assertion so new node kinds fail the build. Replaces the
hand-rolled `AstNode` interface. Adds explicit cases for table /
tableRow / tableCell (throw — preprocessed by fromAst),
footnoteDefinition, footnoteReference, yaml.
- Introduce `TelegramParseMode = "MarkdownV2" | "plain"` replacing
`string | undefined`. `toBotApiParseMode` handles the wire mapping.
- Re-export `Nodes` from the chat package; re-export
`TelegramReactionType` from the adapter entry.
* feat(examples): add length-limit demos to telegram-chat reference bot
Three new menu entries exercise the MarkdownV2 truncation path that the
prior commit fixed:
- Long (5000 plain) — basic truncation, verifies escaped `\.\.\.` ellipsis
- Long (bold crosses 4096) — entity-balancing heuristic for unclosed `*`
- Long (code crosses 4096) — entity-balancing heuristic for unclosed `` ` ``
Each button posts a message whose rendered length exceeds Telegram's
4096-char limit and would have produced `can't parse entities` 400s
against the previous truncator. Serves as an interactive smoke test
alongside the unit tests in packages/adapter-telegram.
* test(telegram): add unit tests for truncation helpers and MarkdownV2 boundary trimming
* docs(telegram): update README to reflect MarkdownV2 parse mode
* chore: unexport trimToMarkdownV2SafeBoundary to fix knip
---------
Co-authored-by: dancer <josh@afterima.ge>
* fix(adapter-teams): resolve DM conversation IDs for Graph API fetchMessages
DM conversation IDs from Bot Framework are opaque and don't work with
Graph's /chats/{chat-id}/messages endpoint. Cache the user's AAD object
ID from incoming activities and construct the correct Graph chat ID
(19:{aadId}_{botId}@unq.gbl.spaces) via a new TeamsGraphContext union.
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(adapter-teams): simplify graph context branching
Remove redundant type checks — DMs never have threadMessageId so the
channel guard doesn't need an explicit DM exclusion.
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
* Add slack/socket mode dependency
* Update config types and SlackAdapter class
* Add socket mode methods, extract interactive dispatch
* Update createSlackAdapter factory function
* Write tests for socket mode
* Create slack-socket-mode.md
* Run fix
* Fix polynomial regex issues
* Fix: Floating promises in `routeSocketEvent` for slash commands and interactive payloads can cause unhandled promise rejections that crash the Node.js process.
This commit fixes the issue reported at packages/adapter-slack/src/index.ts:1152
**Bug Analysis:**
In `routeSocketEvent` (line 1150), which is a synchronous `void` method, two async operations produce floating promises:
1. `this.handleSlashCommand(params)` (line 1165) - `handleSlashCommand` is `async` and always returns a `Promise<Response>`. It calls `await this.lookupUser(userId)` which internally calls `await this.chat.getState().get()` (before the try/catch around the API call), and `this.chat.processSlashCommand()`. Any of these could throw.
2. `this.dispatchInteractivePayload(payload)` (line 1172) - Returns `Response | Promise<Response>`. When the payload type is `view_submission`, it delegates to `async handleViewSubmission()`, which calls `await this.chat.processModalSubmit()` and accesses `payload.view.state.values` (which could throw on malformed payloads).
Since `routeSocketEvent` is synchronous (`void` return type) and called from a sync context within the socket mode event handler (after `await ack()` has already completed), these returned promises are fire-and-forget. If any reject, it triggers an unhandled promise rejection, which in Node.js 15+ terminates the process by default.
In contrast, in the webhook code path (`handleWebhook`), these same methods are always `return`-ed from async functions, so their promises are properly chained to the caller.
**Fix:**
Added `.catch()` handlers to both floating promises:
1. For `handleSlashCommand`: Added `.catch()` that logs the error via `this.logger.error`.
2. For `dispatchInteractivePayload`: Since it returns `Response | Promise<Response>` (only a Promise for `view_submission`), used `instanceof Promise` to conditionally attach a `.catch()` handler only when the result is a Promise.
This approach was chosen over making `routeSocketEvent` async because: (a) it doesn't change the method signature, (b) the caller doesn't need to await it (the ack has already been sent), and (c) errors are logged rather than silently swallowed.
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
Co-authored-by: haydenbleasel <hello@haydenbleasel.com>
* Add socket mode forwarding support to Slack adapter
- Export SlackForwardedSocketEvent type
- Add x-slack-socket-token check at top of handleWebhook() for forwarded events
- Update routeSocketEvent() to accept WebhookOptions and use waitUntil
- Add startSocketModeListener(), runSocketModeListener(), forwardSocketEvent()
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Add tests for socket mode forwarding
- Forwarded event accepted/rejected based on appToken
- Bypasses signature verification for forwarded events
- Options passthrough to handlers
- startSocketModeListener returns 200/500 appropriately
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Add socket mode cron route and vercel config
- New /api/slack/socket-mode route using createPersistentListener
- Mirrors Discord gateway pattern (CRON_SECRET auth, Redis coordination)
- Cron runs every 9 min, listener duration 10 min
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Fix signingSecret defaulting to empty string in socket mode
Make signingSecret optional (string | undefined) instead of falling
back to "". verifySignature now returns false when no secret is
configured, preventing HMAC with an empty key from silently passing.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Wrap event_callback in try-catch in routeSocketEvent
Sync errors from processEventPayload were silently dropped in
socket mode. Wrap with try-catch for parity with slash_commands
and interactive cases.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Use dedicated socketForwardingSecret for forwarding auth
Stop using the Slack app-level token (xapp-...) as the bearer token
for HTTP forwarding. Adds socketForwardingSecret config option
(auto-detected from SLACK_SOCKET_FORWARDING_SECRET) with fallback
to appToken for backwards compatibility.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Replace double cast with type guard for socket event body
Validate body.event exists and construct a properly typed
SlackWebhookPayload instead of using `as unknown as`.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Internalize SlackForwardedSocketEvent type
Remove export — only used internally by the forwarding mechanism.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Fix formatting in socketForwardingSecret check
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Add socket mode documentation to Slack adapter README
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(slack): use SDK envelope type for socket mode event routing
* fix(slack): pass interactive response through ack in socket mode
* feat(chat): add clear modal response action to close entire view stack
* chore: update changeset for clear modal action
---------
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: dancer <josh@afterima.ge>
github-actions[bot]