chat 4.13.0 → 4.13.2

package/docs/adapters/teams.mdx

@@ -0,0 +1,225 @@
+---
+title: Microsoft Teams
+description: Configure the Microsoft Teams adapter with Azure Bot Service.
+type: integration
+prerequisites:
+  - /docs/getting-started
+---
+
+## Installation
+
+```sh title="Terminal"
+pnpm add @chat-adapter/teams
+```
+
+## Usage
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createTeamsAdapter } from "@chat-adapter/teams";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    teams: createTeamsAdapter({
+      appId: process.env.TEAMS_APP_ID!,
+      appPassword: process.env.TEAMS_APP_PASSWORD!,
+      appType: "SingleTenant",
+      appTenantId: process.env.TEAMS_APP_TENANT_ID!,
+    }),
+  },
+});
+
+bot.onNewMention(async (thread, message) => {
+  await thread.post("Hello from Teams!");
+});
+```
+
+## Azure Bot setup
+
+### 1. Create Azure Bot resource
+
+1. Go to [portal.azure.com](https://portal.azure.com)
+2. Click **Create a resource**
+3. Search for **Azure Bot** and select it
+4. Click **Create** and fill in:
+   - **Bot handle**: Unique identifier for your bot
+   - **Subscription**: Your Azure subscription
+   - **Resource group**: Create new or use existing
+   - **Pricing tier**: F0 (free) for testing
+   - **Type of App**: **Single Tenant** (recommended for enterprise)
+   - **Creation type**: **Create new Microsoft App ID**
+5. Click **Review + create** then **Create**
+
+### 2. Get app credentials
+
+1. Go to your Bot resource then **Configuration**
+2. Copy **Microsoft App ID** as `TEAMS_APP_ID`
+3. Click **Manage Password** (next to Microsoft App ID)
+4. In the App Registration page, go to **Certificates & secrets**
+5. Click **New client secret**, add description, select expiry, click **Add**
+6. Copy the **Value** immediately (shown only once) as `TEAMS_APP_PASSWORD`
+7. Go to **Overview** and copy **Directory (tenant) ID** as `TEAMS_APP_TENANT_ID`
+
+### 3. Configure messaging endpoint
+
+1. In your Azure Bot resource, go to **Configuration**
+2. Set **Messaging endpoint** to `https://your-domain.com/api/webhooks/teams`
+3. Click **Apply**
+
+### 4. Enable Teams channel
+
+1. In your Azure Bot resource, go to **Channels**
+2. Click **Microsoft Teams**
+3. Accept the terms of service
+4. Click **Apply**
+
+### 5. Create Teams app package
+
+Create a `manifest.json` file:
+
+```json title="manifest.json" lineNumbers
+{
+  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
+  "manifestVersion": "1.16",
+  "version": "1.0.0",
+  "id": "your_app_id_here",
+  "packageName": "com.yourcompany.chatbot",
+  "developer": {
+    "name": "Your Company",
+    "websiteUrl": "https://your-domain.com",
+    "privacyUrl": "https://your-domain.com/privacy",
+    "termsOfUseUrl": "https://your-domain.com/terms"
+  },
+  "name": {
+    "short": "Chat Bot",
+    "full": "Chat SDK Demo Bot"
+  },
+  "description": {
+    "short": "A chat bot powered by Chat SDK",
+    "full": "A chat bot powered by Chat SDK that responds to messages and commands."
+  },
+  "icons": {
+    "outline": "outline.png",
+    "color": "color.png"
+  },
+  "accentColor": "#FFFFFF",
+  "bots": [
+    {
+      "botId": "your_app_id_here",
+      "scopes": ["personal", "team", "groupchat"],
+      "supportsFiles": false,
+      "isNotificationOnly": false
+    }
+  ],
+  "permissions": ["identity", "messageTeamMembers"],
+  "validDomains": ["your-domain.com"]
+}
+```
+
+Create icon files (32x32 `outline.png` and 192x192 `color.png`), then zip all three files together.
+
+### 6. Upload app to Teams
+
+**For testing (sideloading):**
+
+1. In Teams, click **Apps** in the sidebar
+2. Click **Manage your apps** then **Upload an app**
+3. Click **Upload a custom app** and select your zip file
+
+**For organization-wide deployment:**
+
+1. Go to [Teams Admin Center](https://admin.teams.microsoft.com)
+2. Go to **Teams apps** then **Manage apps**
+3. Click **Upload new app** and select your zip file
+4. Go to **Setup policies** to control who can use the app
+
+## Configuration
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `appId` | Yes | Azure Bot App ID |
+| `appPassword` | Yes | Azure Bot App Password |
+| `appType` | No | `"MultiTenant"` or `"SingleTenant"` (default: `"MultiTenant"`) |
+| `appTenantId` | For SingleTenant | Azure AD Tenant ID |
+
+## Environment variables
+
+```bash title=".env.local"
+TEAMS_APP_ID=...
+TEAMS_APP_PASSWORD=...
+TEAMS_APP_TENANT_ID=...  # Required for SingleTenant
+```
+
+## Features
+
+| Feature | Supported |
+|---------|-----------|
+| Mentions | Yes |
+| Reactions (add/remove) | Read-only |
+| Cards (Adaptive Cards) | Yes |
+| Modals | No |
+| Streaming | Post+Edit fallback |
+| DMs | Yes |
+| Ephemeral messages | No (DM fallback) |
+| File uploads | Yes |
+| Typing indicator | No |
+| Message history | No |
+
+## Limitations
+
+- **Adding reactions**: Teams Bot Framework doesn't support bots adding reactions. Calling `addReaction()` or `removeReaction()` throws a `NotImplementedError`. The bot can still receive reaction events via `onReaction()`.
+- **Typing indicators**: Not available via Bot Framework. `startTyping()` is a no-op.
+
+### Message history (`fetchMessages`)
+
+Fetching message history requires the Microsoft Graph API with client credentials flow. To enable it:
+
+1. Set `appTenantId` in the adapter config
+2. Grant one of these Azure AD app permissions:
+   - `ChatMessage.Read.Chat`
+   - `Chat.Read.All`
+   - `Chat.Read.WhereInstalled`
+
+Without these permissions, `fetchMessages` will not be able to retrieve channel history.
+
+### Receiving all messages
+
+By default, Teams bots only receive messages when directly @-mentioned. To receive all messages in a channel or group chat, add Resource-Specific Consent (RSC) permissions to your Teams app manifest:
+
+```json title="manifest.json"
+{
+  "authorization": {
+    "permissions": {
+      "resourceSpecific": [
+        {
+          "name": "ChannelMessage.Read.Group",
+          "type": "Application"
+        }
+      ]
+    }
+  }
+}
+```
+
+Alternatively, configure the bot in Azure to receive all messages.
+
+## Troubleshooting
+
+### "Unauthorized" error
+
+- Verify `TEAMS_APP_ID` and `TEAMS_APP_PASSWORD` are correct
+- For SingleTenant apps, ensure `TEAMS_APP_TENANT_ID` is set
+- Check that the messaging endpoint URL is correct in Azure
+
+### Bot not appearing in Teams
+
+- Verify the Teams channel is enabled in Azure Bot
+- Check that the app manifest is correctly configured
+- Ensure the app is installed in the workspace/team
+
+### Messages not received
+
+- Verify the messaging endpoint URL is correct
+- Check that your server is accessible from the internet
+- Review Azure Bot logs for errors

package/docs/api/cards.mdx

@@ -0,0 +1,217 @@
+---
+title: Cards
+description: Rich card components for cross-platform interactive messages.
+type: reference
+---
+
+Card components render natively on each platform — Block Kit on Slack, Adaptive Cards on Teams, Embeds on Discord, and Google Chat Cards.
+
+```typescript
+import { Card, Text, Button, Actions, Section, Fields, Field, Divider, Image, LinkButton } from "chat";
+```
+
+All components support both function-call and JSX syntax. Function-call syntax is recommended for better type inference.
+
+## Card
+
+Top-level container for a rich message.
+
+```typescript
+Card({
+  title: "Order #1234",
+  subtitle: "Pending approval",
+  children: [Text("Total: $50.00")],
+})
+```
+
+<TypeTable
+  type={{
+    title: {
+      description: 'Card title.',
+      type: 'string',
+    },
+    subtitle: {
+      description: 'Card subtitle.',
+      type: 'string',
+    },
+    imageUrl: {
+      description: 'Header image URL.',
+      type: 'string',
+    },
+    children: {
+      description: 'Card content elements.',
+      type: 'CardChild[]',
+    },
+  }}
+/>
+
+## Text
+
+Text content element. Use `CardText` instead of `Text` in JSX to avoid conflicts with React's built-in types.
+
+```typescript
+Text("Hello, world!")
+Text("Important", { style: "bold" })
+Text("Subtle note", { style: "muted" })
+```
+
+<TypeTable
+  type={{
+    content: {
+      description: 'Text content (first argument).',
+      type: 'string',
+    },
+    'options.style': {
+      description: 'Text style.',
+      type: '"plain" | "bold" | "muted"',
+    },
+  }}
+/>
+
+## Button
+
+Interactive button that triggers an `onAction` handler.
+
+```typescript
+Button({ id: "approve", label: "Approve", style: "primary" })
+Button({ id: "delete", label: "Delete", style: "danger", value: "item-123" })
+```
+
+<TypeTable
+  type={{
+    id: {
+      description: 'Unique action ID for callback routing.',
+      type: 'string',
+    },
+    label: {
+      description: 'Button label text.',
+      type: 'string',
+    },
+    style: {
+      description: 'Visual style.',
+      type: '"primary" | "danger" | "default"',
+    },
+    value: {
+      description: 'Optional payload sent with the action callback.',
+      type: 'string',
+    },
+  }}
+/>
+
+## LinkButton
+
+Button that opens a URL. No `onAction` handler needed.
+
+```typescript
+LinkButton({ url: "https://example.com", label: "View Docs" })
+```
+
+<TypeTable
+  type={{
+    url: {
+      description: 'URL to open when clicked.',
+      type: 'string',
+    },
+    label: {
+      description: 'Button label text.',
+      type: 'string',
+    },
+    style: {
+      description: 'Visual style.',
+      type: '"primary" | "danger" | "default"',
+    },
+  }}
+/>
+
+## Actions
+
+Container for buttons and interactive elements. Required wrapper around `Button`, `LinkButton`, `Select`, and `RadioSelect`.
+
+```typescript
+Actions([
+  Button({ id: "approve", label: "Approve", style: "primary" }),
+  Button({ id: "reject", label: "Reject", style: "danger" }),
+  LinkButton({ url: "https://example.com", label: "View" }),
+])
+```
+
+## Section
+
+Groups related content together.
+
+```typescript
+Section([
+  Text("Grouped content"),
+  Image({ url: "https://example.com/photo.png" }),
+])
+```
+
+## Fields
+
+Renders key-value pairs in a compact, multi-column layout.
+
+```typescript
+Fields([
+  Field({ label: "Name", value: "Jane Smith" }),
+  Field({ label: "Role", value: "Engineer" }),
+])
+```
+
+## Field
+
+A single key-value pair. Must be used inside `Fields`.
+
+<TypeTable
+  type={{
+    label: {
+      description: 'Field label.',
+      type: 'string',
+    },
+    value: {
+      description: 'Field value.',
+      type: 'string',
+    },
+  }}
+/>
+
+## Image
+
+Embeds an image in the card.
+
+```typescript
+Image({ url: "https://example.com/screenshot.png", alt: "Screenshot" })
+```
+
+<TypeTable
+  type={{
+    url: {
+      description: 'Image URL.',
+      type: 'string',
+    },
+    alt: {
+      description: 'Alt text for accessibility.',
+      type: 'string',
+    },
+  }}
+/>
+
+## Divider
+
+A visual separator between sections.
+
+```typescript
+Divider()
+```
+
+## CardChild types
+
+The `children` array in `Card` and `Section` accepts these element types:
+
+| Type | Created by |
+|------|-----------|
+| `TextElement` | `Text()` |
+| `ImageElement` | `Image()` |
+| `DividerElement` | `Divider()` |
+| `ActionsElement` | `Actions()` |
+| `SectionElement` | `Section()` |
+| `FieldsElement` | `Fields()` |

package/docs/api/channel.mdx

@@ -0,0 +1,176 @@
+---
+title: Channel
+description: Channel container that holds threads, with methods for listing, posting, and iteration.
+type: reference
+---
+
+A `Channel` represents a channel or conversation container that holds threads. Both `Thread` and `Channel` extend the shared `Postable` interface, so they share common methods like `post()`, `state`, and `messages`.
+
+Get a channel via `thread.channel` or `chat.channel()`:
+
+```typescript
+// Navigate from a thread
+const channel = thread.channel;
+
+// Get directly by ID
+const channel = chat.channel("slack:C123ABC");
+```
+
+## Properties
+
+<TypeTable
+  type={{
+    id: {
+      description: 'Channel ID (e.g., "slack:C123ABC", "gchat:spaces/ABC123").',
+      type: 'string',
+    },
+    name: {
+      description: 'Channel name (e.g., "#general"). Null until fetchMetadata() is called.',
+      type: 'string | null',
+    },
+    adapter: {
+      description: 'The platform adapter this channel belongs to.',
+      type: 'Adapter',
+    },
+    isDM: {
+      description: 'Whether this is a direct message conversation.',
+      type: 'boolean',
+    },
+  }}
+/>
+
+## Channel ID format
+
+Channel IDs are derived from thread IDs by dropping the thread-specific part. By default, this is the first two colon-separated segments:
+
+| Platform | Thread ID | Channel ID |
+|----------|-----------|------------|
+| Slack | `slack:C123ABC:1234567890.123456` | `slack:C123ABC` |
+| Teams | `teams:{base64}:{base64}` | `teams:{base64}` |
+| Google Chat | `gchat:spaces/ABC123:{base64}` | `gchat:spaces/ABC123` |
+| Discord | `discord:{guildId}:{channelId}/{messageId}` | `discord:{guildId}` |
+
+## messages
+
+Iterate channel-level messages (top-level, not thread replies) newest first. Auto-paginates lazily.
+
+```typescript
+for await (const msg of channel.messages) {
+  console.log(msg.text);
+}
+```
+
+## threads
+
+Iterate threads in the channel, most recently active first. Returns lightweight `ThreadSummary` objects.
+
+```typescript
+for await (const thread of channel.threads()) {
+  console.log(thread.rootMessage.text, thread.replyCount);
+}
+```
+
+### ThreadSummary
+
+<TypeTable
+  type={{
+    id: {
+      description: 'Full thread ID.',
+      type: 'string',
+    },
+    rootMessage: {
+      description: 'The first message of the thread.',
+      type: 'Message',
+    },
+    replyCount: {
+      description: 'Number of replies (if available).',
+      type: 'number | undefined',
+    },
+    lastReplyAt: {
+      description: 'Timestamp of most recent reply.',
+      type: 'Date | undefined',
+    },
+  }}
+/>
+
+## post
+
+Post a message to the channel top-level (not in a thread).
+
+```typescript
+await channel.post("Hello channel!");
+await channel.post({ markdown: "**Announcement**: New release!" });
+```
+
+Accepts the same message formats as `thread.post()` — see [PostableMessage](/docs/api/postable-message).
+
+## fetchMetadata
+
+Fetch channel metadata from the platform.
+
+```typescript
+const info = await channel.fetchMetadata();
+console.log(info.name, info.memberCount);
+```
+
+### ChannelInfo
+
+<TypeTable
+  type={{
+    id: {
+      description: 'Channel ID.',
+      type: 'string',
+    },
+    name: {
+      description: 'Channel name.',
+      type: 'string | undefined',
+    },
+    isDM: {
+      description: 'Whether this is a direct message.',
+      type: 'boolean | undefined',
+    },
+    memberCount: {
+      description: 'Number of members in the channel.',
+      type: 'number | undefined',
+    },
+    metadata: {
+      description: 'Platform-specific metadata.',
+      type: 'Record<string, unknown>',
+    },
+  }}
+/>
+
+## state
+
+Store typed, per-channel state. Works the same as thread state with a 30-day TTL.
+
+```typescript
+const state = await channel.state;
+await channel.setState({ lastAnnouncement: new Date().toISOString() });
+```
+
+## postEphemeral
+
+Post a message visible only to a specific user.
+
+```typescript
+await channel.postEphemeral(userId, "Only you can see this", {
+  fallbackToDM: true,
+});
+```
+
+## startTyping
+
+Show a typing indicator. No-op on platforms that don't support it.
+
+```typescript
+await channel.startTyping();
+```
+
+## mentionUser
+
+Get a platform-specific @-mention string.
+
+```typescript
+await channel.post(`Hey ${channel.mentionUser(userId)}, check this out!`);
+```