chat 4.15.0 → 4.16.0

package/docs/contributing/documenting.mdx

@@ -0,0 +1,218 @@
+---
+title: Documenting your adapter
+description: Write a README, configuration reference, and usage examples for your community adapter.
+type: guide
+prerequisites:
+  - /docs/contributing/building
+  - /docs/contributing/testing
+related:
+  - /docs/contributing/publishing
+  - /docs/adapters
+---
+
+## Why documentation matters
+
+Your adapter's README is the first thing developers see on npm and GitHub. Clear documentation reduces support questions, builds trust, and encourages adoption.
+
+All Vercel-maintained adapters follow a consistent structure. Community adapters should aim for the same bar.
+
+## README structure
+
+Your `README.md` should include these sections in order:
+
+### Title and badges
+
+Start with the package name as an H1, followed by npm badges and a one-line description.
+
+````markdown title="README.md"
+# chat-adapter-matrix
+
+[![npm version](https://img.shields.io/npm/v/chat-adapter-matrix)](https://www.npmjs.com/package/chat-adapter-matrix)
+[![npm downloads](https://img.shields.io/npm/dm/chat-adapter-matrix)](https://www.npmjs.com/package/chat-adapter-matrix)
+
+Matrix adapter for [Chat SDK](https://chat-sdk.dev/docs).
+````
+
+### Installation
+
+Show the install command with `chat` as a co-dependency.
+
+````markdown title="README.md"
+## Installation
+
+```bash
+npm install chat chat-adapter-matrix
+```
+````
+
+### Quick start
+
+A minimal working example that developers can copy-paste. Include the factory function with explicit config so readers understand what credentials are needed.
+
+````markdown title="README.md"
+## Usage
+
+```typescript
+import { Chat } from "chat";
+import { createMatrixAdapter } from "chat-adapter-matrix";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    matrix: createMatrixAdapter({
+      homeserverUrl: process.env.MATRIX_HOMESERVER_URL!,
+      accessToken: process.env.MATRIX_ACCESS_TOKEN!,
+    }),
+  },
+});
+
+bot.onNewMention(async (thread, message) => {
+  await thread.post("Hello from Matrix!");
+});
+```
+````
+
+### Environment variables
+
+List every environment variable your adapter reads, with a description and example value.
+
+````markdown title="README.md"
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MATRIX_HOMESERVER_URL` | Yes | Matrix homeserver URL (e.g., `https://matrix.example.com`) |
+| `MATRIX_ACCESS_TOKEN` | Yes | Bot account access token |
+| `MATRIX_BOT_USERNAME` | No | Override the bot display name |
+````
+
+### Configuration reference
+
+Document every field in your config interface, including defaults.
+
+````markdown title="README.md"
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `homeserverUrl` | `string` | `MATRIX_HOMESERVER_URL` | Matrix homeserver URL |
+| `accessToken` | `string` | `MATRIX_ACCESS_TOKEN` | Bot account access token |
+| `userName` | `string` | `"matrix-bot"` | Bot display name |
+| `logger` | `Logger` | `ConsoleLogger` | Custom logger instance |
+````
+
+### Platform setup
+
+Walk through creating the bot account on the platform. Use numbered steps, link to the platform's developer portal, and call out where to find each credential.
+
+````markdown title="README.md"
+## Platform setup
+
+1. Create a bot account on your Matrix homeserver
+2. Generate an access token for the bot
+3. Set the webhook URL to `https://your-domain.com/api/webhooks/matrix`
+````
+
+### Features
+
+List what your adapter supports. Use a feature table if it helps. Call out any limitations.
+
+````markdown title="README.md"
+## Features
+
+- Mentions and DMs
+- Rich text (bold, italic, code, links)
+- Reactions (add and remove)
+- File uploads
+- Typing indicators
+- Thread support
+````
+
+### License
+
+````markdown title="README.md"
+## License
+
+MIT
+````
+
+## Code-level documentation
+
+### Exported types
+
+Export your config and thread ID interfaces so consumers can use them in their own type annotations. TypeScript declarations generated by `tsup` serve as the primary API reference — keep your interface fields descriptive enough that hover-over docs in an editor are useful.
+
+```typescript title="src/types.ts" lineNumbers
+/** Configuration for the Matrix adapter */
+export interface MatrixAdapterConfig {
+  /** Matrix homeserver URL (e.g., "https://matrix.example.com") */
+  homeserverUrl: string;
+  /** Access token for the bot account */
+  accessToken: string;
+  /** Override the bot display name (default: "matrix-bot") */
+  userName?: string;
+}
+```
+
+<Callout type="info">
+  TSDoc comments on exported interfaces and functions appear in IDE tooltips and generated `.d.ts` files. Keep them concise and factual.
+</Callout>
+
+### What not to document
+
+- Internal/private methods — they're implementation details
+- Re-exported types from `chat` or `@chat-adapter/shared` — link to the upstream docs instead
+- Obvious behavior — `postMessage` posts a message, no need to elaborate
+
+## Sample messages file
+
+Include a `sample-messages.md` file in your package root with real webhook payloads from the platform. This is invaluable for other contributors debugging edge cases.
+
+````markdown title="sample-messages.md"
+# Matrix sample messages
+
+## Text message
+
+```json
+{
+  "type": "m.room.message",
+  "room_id": "!abc123:matrix.org",
+  "event_id": "$evt456",
+  "sender": "@alice:matrix.org",
+  "content": {
+    "msgtype": "m.text",
+    "body": "Hello world"
+  },
+  "origin_server_ts": 1700000000000
+}
+```
+
+## Bot mention
+
+```json
+{
+  "type": "m.room.message",
+  "room_id": "!abc123:matrix.org",
+  "event_id": "$evt789",
+  "sender": "@alice:matrix.org",
+  "content": {
+    "msgtype": "m.text",
+    "body": "@bot help me",
+    "format": "org.matrix.custom.html",
+    "formatted_body": "<a href=\"https://matrix.to/#/@bot:matrix.org\">bot</a> help me"
+  },
+  "origin_server_ts": 1700000001000
+}
+```
+````
+
+Existing Vercel-maintained adapters include `sample-messages.md` files in their package roots — check those for format reference.
+
+## Checklist
+
+Before publishing, verify your documentation covers:
+
+- [ ] README with badges, install, quick start, env vars, config reference, platform setup
+- [ ] TSDoc comments on all exported interfaces and factory functions
+- [ ] `sample-messages.md` with real platform webhook payloads
+- [ ] Links to Chat SDK docs (`chat-sdk.dev`) where relevant

package/docs/contributing/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Contributing",
+  "pages": ["building", "testing", "documenting", "publishing"]
+}

package/docs/contributing/publishing.mdx

@@ -0,0 +1,161 @@
+---
+title: Publishing your adapter
+description: Package, version, and publish your community Chat SDK adapter to npm.
+type: guide
+prerequisites:
+  - /docs/contributing/building
+  - /docs/contributing/testing
+  - /docs/contributing/documenting
+related:
+  - /docs/adapters
+---
+
+## Package checklist
+
+Before publishing, verify your `package.json` meets these requirements:
+
+```json title="package.json" lineNumbers
+{
+  "name": "chat-adapter-matrix",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "peerDependencies": {
+    "chat": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["chat-sdk", "chat-adapter", "matrix"],
+  "license": "MIT"
+}
+```
+
+| Field | Why it matters |
+|-------|---------------|
+| `"type": "module"` | ESM-only — matches the Chat SDK ecosystem |
+| `"files": ["dist"]` | Only publish compiled output, keeping the package lean |
+| `"exports"` | Explicit entry points for bundlers and Node.js |
+| `"peerDependencies"` | Consumers provide their own `chat` instance |
+| `"publishConfig"` | Required for scoped packages (`@your-scope/chat-adapter-*`) |
+| `"keywords"` | Include `chat-sdk` and `chat-adapter` for npm discoverability |
+
+## Naming conventions
+
+| Convention | Example | When to use |
+|------------|---------|-------------|
+| Unscoped | `chat-adapter-matrix` | Most community adapters |
+| Scoped | `@your-org/chat-adapter-matrix` | Optional — if you prefer publishing under your org's scope |
+
+<Callout type="warn">
+  The `@chat-adapter/` npm scope is reserved for Vercel-maintained adapters. Do not publish under this scope.
+</Callout>
+
+## Build and verify
+
+Run a full build and verify everything compiles before publishing.
+
+```sh title="Terminal"
+# Build
+npm run build
+
+# Type-check
+npm run typecheck
+
+# Run tests
+npm test
+```
+
+Inspect the package contents to make sure only `dist/` is included:
+
+```sh title="Terminal"
+npm pack --dry-run
+```
+
+You should see output like:
+
+```
+dist/index.js
+dist/index.d.ts
+dist/index.js.map
+package.json
+README.md
+LICENSE
+```
+
+If you see `src/`, `node_modules/`, or test files in the output, update your `"files"` field or add a `.npmignore`.
+
+## Versioning
+
+Follow [semver](https://semver.org):
+
+| Change | Bump | Example |
+|--------|------|---------|
+| Bug fix, internal refactor | `patch` | `1.0.0` → `1.0.1` |
+| New feature, new export, new config option | `minor` | `1.0.0` → `1.1.0` |
+| Breaking change (removed export, changed signature) | `major` | `1.0.0` → `2.0.0` |
+
+When the Chat SDK releases a new major version, you'll need a major bump too if your adapter's peer dependency range changes.
+
+## Publish to npm
+
+```sh title="Terminal"
+npm publish
+```
+
+For scoped packages published for the first time:
+
+```sh title="Terminal"
+npm publish --access public
+```
+
+## Peer dependency compatibility
+
+Your adapter should declare `chat` as a peer dependency with a caret range:
+
+```json
+{
+  "peerDependencies": {
+    "chat": "^4.0.0"
+  }
+}
+```
+
+This means your adapter works with any `4.x` release. When the Chat SDK ships a new major version:
+
+1. Test your adapter against the new version
+2. Update the peer dependency range
+3. Publish a new major version of your adapter
+
+## Post-publish verification
+
+After publishing, verify the package works for consumers:
+
+```sh title="Terminal"
+# Create a temp directory
+mkdir /tmp/test-adapter && cd /tmp/test-adapter
+npm init -y
+
+# Install your adapter
+npm install chat chat-adapter-matrix
+
+# Verify the import works
+node -e "import('chat-adapter-matrix').then(m => console.log(Object.keys(m)))"
+```
+
+You should see your exported symbols (`createMatrixAdapter`, `MatrixAdapter`, etc.).
+
+## Keeping your adapter up to date
+
+- Watch the [Chat SDK changelog](https://github.com/vercel/chat/releases) for new features and breaking changes
+- Run your test suite against new Chat SDK releases before they ship to catch compatibility issues early
+- When the `Adapter` interface adds new optional methods, consider implementing them to keep your adapter feature-complete