Merge remote-tracking branch 'origin/main' into fix/gchat-endpoint-url-audience

Author: bensabic

.agents/skills/add-adapter/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: add-adapter
+description: Add a vendor-official or community adapter to the Chat SDK catalog and docs — adapters.json registry, chat/adapters catalog entry, the docs MDX page, meta.json, integration-test lists, and a changeset. Use when a developer wants to add, list, register, or submit a third-party (vendor-official or community) adapter to this repo, add an adapter to the catalog, or create or edit an adapter docs page under apps/docs/content/adapters/vendor-official or apps/docs/content/adapters/community.
+---
+
+# Add a catalog adapter (vendor-official or community)
+
+Use this to list a **third-party** adapter in the Chat SDK catalog and docs. It is not for building a first-party `packages/adapter-*` package.
+
+## Gather the source — never invent details
+
+Ask the user for:
+
+1. Their adapter's **GitHub repository URL**.
+2. Their **docs or README**.
+
+Read both. Everything you write into the catalog and docs must come **directly** from those sources or from the user. Do not assume or guess any information:
+
+- **`packageName`** — read it from the repo's `package.json`, verbatim.
+- **Factory export** (e.g. `createFooAdapter`) — read it from the package's exports/source. Do not guess it from the display name.
+- **`type`** (`platform` or `state`), **env vars**, and the **feature matrix** — base these on what the code and README actually document.
+- **Install and usage snippets** — take them from the README; do not write example code the adapter may not support.
+
+If the repo or README does not make something clear, **stop and ask the user** rather than filling it in. When in doubt, ask.
+
+Choose the `slug` (kebab-case) and confirm it is not already taken: `ls apps/docs/content/adapters/*/`.
+
+## Pick the tier
+
+- **community** — listed in the docs only. No `chat/adapters` catalog entry, no changeset.
+- **vendor-official** — a maintained/blessed adapter. Everything community has, plus a `chat/adapters` catalog entry, a matching `create-chat-sdk` scaffold-spec entry, and a changeset. Frontmatter adds `vendorOfficial: true` and `author`.
+
+## Files to change
+
+`<tier>` is `vendor-official` or `community`.
+
+1. **`apps/docs/content/adapters/<tier>/<slug>.mdx`** — the docs page. Start from [assets/adapter.mdx](assets/adapter.mdx). The filename basename must equal the `slug` frontmatter field, and the page must render `<FeatureSupport />`.
+2. **`apps/docs/content/adapters/<tier>/meta.json`** — add `"<slug>"` to the `pages` array.
+3. **`apps/docs/adapters.json`** — add a registry entry: `name`, `slug`, `type`, `community: true`, `description`, `packageName`, `author`, `readme` (the GitHub URL). Add `vendorOfficial: true` for vendor-official.
+4. **`packages/integration-tests/src/docs-adapters.test.ts`** — add `"<slug>"` to the hardcoded expected list for its tier.
+5. **`packages/integration-tests/src/documentation-test-utils.ts`** — add the `packageName` to `VALID_DOC_PACKAGES`, plus every import specifier used in the MDX code blocks (subpaths count separately).
+
+**Vendor-official also:**
+
+6. **`packages/chat/src/adapters/index.ts`** — add an `ADAPTERS` entry with `group: "vendor-official"`. Reuse the `env`/`secretEnv`/`urlEnv` helpers; use `env: { notes: "…" }` when there are no env vars. See `packages/chat/src/adapters/AGENTS.md`.
+7. **`packages/create-chat-sdk/src/catalog/scaffold-spec.ts`** — add a matching `"<slug>": { invocation: … }` entry, modeled on a similar adapter. This is a required registration step, not a behavior change: the object is `satisfies Record<AdapterSlug, …>`, so every catalog slug must have one or `create-chat-sdk` fails to type-check.
+8. **`.changeset/<slug>-adapter.md`** — `"chat": patch` + `"create-chat-sdk": patch`, one line describing the addition.
+
+## Invariants the tests enforce
+
+- **Registry ↔ catalog parity.** `Object.keys(ADAPTERS)` must equal the adapters.json slugs where `!community || vendorOfficial`. So vendor-official **must** be in `chat/adapters`; community-only **must not** be. This is why community adapters skip steps 6–8.
+- **peerDeps ↔ PackageInstall.** The catalog entry's `peerDeps` (sorted) must exactly equal the extra packages in the MDX `<PackageInstall package="…" />`, after removing the adapter's own `packageName`, `chat`, and any `@chat-adapter/state-*`. Easiest: `peerDeps: []`, install only `<packageName> chat` (plus a state adapter) in `PackageInstall`, and keep any other imports in fenced code blocks.
+- **Fields match.** `packageName`, `type`, `community`, and `vendorOfficial` must match between the MDX frontmatter and the adapters.json entry.
+- **Required frontmatter:** `title`, `description`, `packageName`, `slug`, `tagline`, `type` (`platform` | `state`), `mdxBody: true`, `community: true` (plus `vendorOfficial: true` and `author` for vendor-official).
+- **Imports.** Every import in an MDX code block must be listed in `VALID_DOC_PACKAGES`.
+
+## Validate
+
+```bash
+pnpm --filter chat build            # regenerate the catalog the tests import
+pnpm --filter @chat-adapter/integration-tests test
+pnpm --filter chat typecheck
+pnpm --filter create-chat-sdk typecheck   # vendor-official only
+pnpm check && pnpm konsistent
+```
+
+## Resources
+
+- MDX template: [assets/adapter.mdx](assets/adapter.mdx)
+- Catalog conventions: `packages/chat/src/adapters/AGENTS.md`
+- Examples to copy: `apps/docs/content/adapters/vendor-official/` and `apps/docs/content/adapters/community/`

.agents/skills/add-adapter/assets/adapter.mdx

@@ -0,0 +1,104 @@
+---
+title: Foo
+description: One-to-two sentence summary of what the Foo adapter connects to and its headline capabilities. Shown in search and listings.
+packageName: "@foo/chat-sdk-adapter"
+slug: foo
+type: platform
+tagline: One-line pitch shown on the adapter card — what it does and for whom.
+community: true
+# vendor-official only — delete both lines for a community adapter:
+vendorOfficial: true
+author: Foo
+mdxBody: true
+# Feature matrix. Use `yes` / `no`, or `{ status: partial|yes, label: "…" }`.
+# PLATFORM adapters use these keys:
+features:
+  postMessage: yes
+  editMessage: no
+  deleteMessage: no
+  fileUploads: no
+  streaming: no
+  scheduledMessages: no
+  cardFormat: no
+  buttons: no
+  linkButtons: no
+  selectMenus: no
+  tables: no
+  fields: no
+  imagesInCards: no
+  modals: no
+  slashCommands: no
+  mentions: no
+  addReactions: no
+  removeReactions: no
+  typingIndicator: no
+  directMessages: yes
+  ephemeralMessages: no
+  userLookup: no
+  customApiEndpoint: no
+  fetchMessages: no
+  fetchSingleMessage: no
+  fetchThreadInfo: no
+  fetchChannelMessages: no
+  listThreads: no
+  fetchChannelInfo: no
+  postChannelMessage: no
+# STATE adapters (type: state) use these keys instead of the platform set above:
+#   persistence, multiInstance, subscriptions, distributedLocking, keyValueCache,
+#   lists, queues, automaticReconnect, cluster, sentinel, keyPrefix
+---
+
+## Install
+
+{/* Only the adapter package + chat (+ optional state adapter). Extra imports
+    used below go in code blocks, NOT here — see the peerDeps invariant. */}
+<PackageInstall package="@foo/chat-sdk-adapter chat @chat-adapter/state-memory" />
+
+## Quick start
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createMemoryState } from "@chat-adapter/state-memory";
+import { createFooAdapter } from "@foo/chat-sdk-adapter";
+
+export const bot = new Chat({
+  userName: "mybot",
+  state: createMemoryState(),
+  adapters: {
+    foo: createFooAdapter({
+      apiKey: process.env.FOO_API_KEY,
+      webhookSecret: process.env.FOO_WEBHOOK_SECRET,
+    }),
+  },
+});
+
+bot.onDirectMessage(async (thread, message) => {
+  await thread.post(`You said: ${message.text}`);
+});
+```
+
+## Configuration
+
+<TypeTable
+  type={{
+    apiKey: { type: "string", description: "Foo API key. Falls back to `FOO_API_KEY`." },
+    webhookSecret: { type: "string", description: "Signing secret for inbound webhook verification. Falls back to `FOO_WEBHOOK_SECRET`." },
+  }}
+/>
+
+## Webhooks
+
+```typescript title="app/api/webhooks/foo/route.ts" lineNumbers
+import { bot } from "@/lib/bot";
+
+export async function POST(request: Request): Promise<Response> {
+  return bot.webhooks.foo(request);
+}
+```
+
+{/* Add the sections that apply: sending, reactions, attachments, thread IDs,
+    limitations, links. Keep it faithful to the adapter's real behavior. */}
+
+## Feature support
+
+<FeatureSupport />

.changeset/add-tests-package.md

@@ -0,0 +1,5 @@
+---
+"@chat-adapter/teams": patch
+---
+
+Fall back to Microsoft Graph's user principal name when a Teams user has no mail address.

.changeset/calm-users-email.md

@@ -7,9 +7,8 @@
   "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
-  "ignore": [
-    "example-nextjs-chat",
-    "example-telegram-chat",
-    "@chat-adapter/integration-tests"
-  ]
+  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
+    "onlyUpdatePeerDependentsWhenOutOfRange": true
+  },
+  "ignore": ["example-*", "@chat-adapter/integration-tests"]
 }