chat 4.20.0 → 4.20.2

package/docs/api/index.mdx

@@ -20,6 +20,12 @@ import { Chat, root, paragraph, text, Card, Button, emoji } from "chat";
 | [`Message`](/docs/api/message) | Normalized message with text, AST, author, and metadata |
 | [`ScheduledMessage`](/docs/api/thread#scheduledmessage) | Returned by `thread.schedule()` / `channel.schedule()` with `cancel()` |
 
+## Utilities
+
+| Export | Description |
+|--------|-------------|
+| [`toAiMessages`](/docs/streaming#toaimessagesmessages-options) | Convert `Message[]` to AI SDK `{ role, content }[]` format |
+
 ## Message formats
 
 | Export | Description |

package/docs/api/message.mdx

@@ -46,6 +46,10 @@ import { Message } from "chat";
       description: 'File attachments.',
       type: 'Attachment[]',
     },
+    links: {
+      description: 'Links found in the message, with optional preview metadata.',
+      type: 'LinkPreview[]',
+    },
     isMention: {
       description: 'Whether the bot was @-mentioned in this message.',
       type: 'boolean | undefined',
@@ -148,6 +152,50 @@ All adapters return `false` if the bot ID isn't known yet. This is a safe defaul
   }}
 />
 
+## LinkPreview
+
+Links found in incoming messages are extracted and exposed as `LinkPreview` objects. On platforms that support it (currently Slack), links pointing to other chat messages include a `fetchMessage()` callback to retrieve the full linked message.
+
+<TypeTable
+  type={{
+    url: {
+      description: 'The URL.',
+      type: 'string',
+    },
+    title: {
+      description: 'Title from unfurl metadata (if available).',
+      type: 'string | undefined',
+    },
+    description: {
+      description: 'Description from unfurl metadata (if available).',
+      type: 'string | undefined',
+    },
+    imageUrl: {
+      description: 'Preview image URL (if available).',
+      type: 'string | undefined',
+    },
+    siteName: {
+      description: 'Site name, e.g. "Vercel" (if available).',
+      type: 'string | undefined',
+    },
+    'fetchMessage()': {
+      description: 'Fetch the linked chat message. Available when the URL points to a message on the same platform (e.g. a Slack message link).',
+      type: '() => Promise<Message> | undefined',
+    },
+  }}
+/>
+
+<Callout type="info">
+When using [`toAiMessages()`](/docs/streaming#toaimessagesmessages-options), link metadata is automatically appended to the message content. Embedded message links are labeled as `[Embedded message: ...]` so the AI model understands the context.
+</Callout>
+
+### Platform support
+
+| Platform | Link extraction | `fetchMessage()` |
+|----------|----------------|-------------------|
+| Slack | URLs from `rich_text` blocks or `<url>` text patterns | Slack message links (`*.slack.com/archives/...`) |
+| Others | Not yet — `links` is always `[]` | — |
+
 ## Serialization
 
 Messages can be serialized for workflow engines and external systems.

package/docs/handling-events.mdx

@@ -94,18 +94,18 @@ Messages sent by the bot itself do not trigger this handler. You don't need to f
 ### Example: Conversational AI with history
 
 ```typescript title="lib/bot.ts" lineNumbers
+import { toAiMessages } from "chat";
+
 bot.onSubscribedMessage(async (thread, message) => {
   await thread.startTyping();
 
   // Build conversation history from thread messages
-  const history = [];
+  const messages = [];
   for await (const msg of thread.allMessages) {
-    history.push({
-      role: msg.author.isMe ? "assistant" : "user",
-      content: msg.text,
-    });
+    messages.push(msg);
   }
 
+  const history = await toAiMessages(messages);
   const response = await generateAIResponse(history);
   await thread.post(response);
 });

package/docs/streaming.mdx

@@ -183,21 +183,68 @@ await thread.stream(textStream, {
 
 ## Streaming with conversation history
 
-Combine message history with streaming for multi-turn AI conversations:
+Combine message history with streaming for multi-turn AI conversations.
+Use `toAiMessages()` to convert chat messages into the `{ role, content }` format expected by AI SDKs:
 
 ```typescript title="lib/bot.ts" lineNumbers
+import { toAiMessages } from "chat";
+
 bot.onSubscribedMessage(async (thread, message) => {
   // Fetch recent messages for context
   const result = await thread.adapter.fetchMessages(thread.id, { limit: 20 });
 
-  const history = result.messages
-    .filter((msg) => msg.text.trim())
-    .map((msg) => ({
-      role: msg.author.isMe ? "assistant" as const : "user" as const,
-      content: msg.text,
-    }));
+  const history = await toAiMessages(result.messages);
 
   const response = await agent.stream({ prompt: history });
   await thread.post(response.fullStream);
 });
 ```
+
+### `toAiMessages(messages, options?)`
+
+Converts an array of `Message` objects into AI SDK conversation format:
+
+- Maps `author.isMe` to `"assistant"` role, all others to `"user"`
+- Filters out empty messages
+- Sorts chronologically (oldest first)
+- Appends link metadata (URLs, titles, descriptions) when present
+- Labels embedded message links (e.g. shared Slack messages) as `[Embedded message: ...]`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `includeNames` | `boolean` | `false` | Prefix user messages with `[username]: ` for multi-user context |
+| `transformMessage` | `(aiMessage, source) => AiMessage \| Promise<AiMessage \| null> \| null` | — | Transform or filter each message after default processing. Return `null` to skip. |
+| `onUnsupportedAttachment` | `(attachment, message) => void` | `console.warn` | Called when an attachment type is not supported |
+
+### Customizing messages with `transformMessage`
+
+Use `transformMessage` to modify, enrich, or filter messages after default processing:
+
+```typescript title="lib/bot.ts" lineNumbers
+import { toAiMessages } from "chat";
+
+const history = await toAiMessages(result.messages, {
+  transformMessage: (aiMessage, source) => {
+    // Replace bot user IDs with readable names
+    if (typeof aiMessage.content === "string") {
+      return {
+        ...aiMessage,
+        content: aiMessage.content.replace(/<@U123>/g, "@VercelBot"),
+      };
+    }
+    return aiMessage;
+  },
+});
+```
+
+Return `null` to skip a message entirely:
+
+```typescript
+const history = await toAiMessages(result.messages, {
+  transformMessage: (aiMessage, source) => {
+    // Skip messages from a specific user
+    if (source.author.userId === "U_NOISY_BOT") return null;
+    return aiMessage;
+  },
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chat",
-  "version": "4.20.0",
+  "version": "4.20.2",
   "description": "Unified chat abstraction for Slack, Teams, Google Chat, and Discord",
   "type": "module",
   "main": "./dist/index.js",