chat 4.16.0 → 4.17.0

package/dist/{jsx-runtime-Bokk9xw5.d.ts → jsx-runtime-BJENDuXl.d.ts}

@@ -499,12 +499,12 @@ interface CardProps {
 }
 /** Props for Text component in JSX */
 interface TextProps {
-    children?: string | number;
+    children?: string | number | (string | number | undefined)[];
     style?: TextStyle;
 }
 /** Props for Button component in JSX */
 interface ButtonProps {
-    children?: string | number;
+    children?: string | number | (string | number | undefined)[];
     id: string;
     label?: string;
     style?: ButtonStyle;
@@ -512,14 +512,14 @@ interface ButtonProps {
 }
 /** Props for LinkButton component in JSX */
 interface LinkButtonProps {
-    children?: string | number;
+    children?: string | number | (string | number | undefined)[];
     label?: string;
     style?: ButtonStyle;
     url: string;
 }
 /** Props for CardLink component in JSX */
 interface CardLinkProps {
-    children?: string | number;
+    children?: string | number | (string | number | undefined)[];
     label?: string;
     url: string;
 }
@@ -588,7 +588,87 @@ interface CardJSXElement<P extends CardJSXProps = CardJSXProps> {
     props: P;
     type: CardComponentFunction;
 }
-type JSXElement = CardJSXElement;
+/** Union of all element types that can be produced by chat components */
+type ChatElement = CardJSXElement | CardElement | TextElement | ButtonElement | LinkButtonElement | LinkElement | ImageElement | DividerElement | ActionsElement | SectionElement | FieldsElement | FieldElement | ModalElement | TextInputElement | SelectElement | SelectOptionElement | RadioSelectElement;
+interface CardComponent {
+    (options?: CardOptions): CardElement;
+    (props: CardProps): ChatElement;
+}
+interface TextComponent {
+    (content: string, options?: {
+        style?: TextStyle;
+    }): TextElement;
+    (props: TextProps): ChatElement;
+}
+interface ButtonComponent {
+    (options: ButtonOptions): ButtonElement;
+    (props: ButtonProps): ChatElement;
+}
+interface LinkButtonComponent {
+    (options: LinkButtonOptions): LinkButtonElement;
+    (props: LinkButtonProps): ChatElement;
+}
+interface CardLinkComponent {
+    (options: {
+        url: string;
+        label: string;
+    }): LinkElement;
+    (props: CardLinkProps): ChatElement;
+}
+interface ImageComponent {
+    (options: {
+        url: string;
+        alt?: string;
+    }): ImageElement;
+    (props: ImageProps): ChatElement;
+}
+interface FieldComponent {
+    (options: {
+        label: string;
+        value: string;
+    }): FieldElement;
+    (props: FieldProps): ChatElement;
+}
+interface DividerComponent {
+    (): DividerElement;
+    (props: DividerProps): ChatElement;
+}
+interface SectionComponent {
+    (children: CardChild[]): SectionElement;
+    (props: ContainerProps): ChatElement;
+}
+interface ActionsComponent {
+    (children: (ButtonElement | LinkButtonElement | SelectElement | RadioSelectElement)[]): ActionsElement;
+    (props: ContainerProps): ChatElement;
+}
+interface FieldsComponent {
+    (children: FieldElement[]): FieldsElement;
+    (props: ContainerProps): ChatElement;
+}
+interface ModalComponent {
+    (options: ModalOptions): ModalElement;
+    (props: ModalProps): ChatElement;
+}
+interface TextInputComponent {
+    (options: TextInputOptions): TextInputElement;
+    (props: TextInputProps): ChatElement;
+}
+interface SelectComponent {
+    (options: SelectOptions): SelectElement;
+    (props: SelectProps): ChatElement;
+}
+interface SelectOptionComponent {
+    (options: {
+        label: string;
+        value: string;
+        description?: string;
+    }): SelectOptionElement;
+    (props: SelectOptionProps): ChatElement;
+}
+interface RadioSelectComponent {
+    (options: RadioSelectOptions): RadioSelectElement;
+    (props: SelectProps): ChatElement;
+}
 /**
  * Type guard to check if props match CardLinkProps
  */
@@ -627,12 +707,14 @@ declare function toModalElement(jsxElement: unknown): ModalElement | null;
  */
 declare function isJSX(value: unknown): boolean;
 declare namespace JSX {
-    interface Element extends JSXElement {
-    }
+    type Element = ChatElement;
     type IntrinsicElements = {};
+    interface IntrinsicAttributes {
+        key?: string | number;
+    }
     interface ElementChildrenAttribute {
         children: {};
     }
 }
 
-export { type FieldProps as $, Actions as A, Button as B, type CardElement as C, Divider as D, type ImageElement as E, Field as F, type LinkButtonElement as G, type LinkButtonOptions as H, Image as I, type LinkElement as J, type SectionElement as K, LinkButton as L, type ModalElement as M, type TableAlignment as N, type TableElement as O, type TableOptions as P, type TextElement as Q, RadioSelect as R, Section as S, Text as T, type TextStyle as U, type ButtonProps as V, type CardJSXProps as W, type CardLinkProps as X, type CardProps as Y, type ContainerProps as Z, type DividerProps as _, type CardJSXElement as a, type ImageProps as a0, type LinkButtonProps as a1, type TextProps as a2, type ModalChild as a3, type ModalOptions as a4, type RadioSelectElement as a5, type RadioSelectOptions as a6, type SelectElement as a7, type SelectOptionElement as a8, type SelectOptions as a9, type TextInputElement as aa, type TextInputOptions as ab, type ModalProps as ac, type TextInputProps as ad, type SelectProps as ae, type SelectOptionProps as af, isCardLinkProps as ag, jsx as ah, jsxs as ai, jsxDEV as aj, Fragment as ak, JSX as al, type CardChild as b, Card as c, cardChildToFallbackText as d, CardLink as e, Fields as f, fromReactElement as g, isJSX as h, isCardElement as i, Table as j, toModalElement as k, fromReactModalElement as l, isModalElement as m, Modal as n, Select as o, SelectOption as p, TextInput as q, type ActionsElement as r, type ButtonElement as s, toCardElement as t, type ButtonOptions as u, type ButtonStyle as v, type CardOptions as w, type DividerElement as x, type FieldElement as y, type FieldsElement as z };
+export { type DividerProps as $, type ActionsComponent as A, type ButtonComponent as B, type CardElement as C, type DividerComponent as D, type ImageElement as E, type FieldComponent as F, type LinkButtonElement as G, type LinkButtonOptions as H, type ImageComponent as I, type LinkElement as J, type SectionElement as K, type LinkButtonComponent as L, type ModalElement as M, type TableAlignment as N, type TableElement as O, type TableOptions as P, type TextElement as Q, type RadioSelectComponent as R, type SectionComponent as S, type TextComponent as T, type TextStyle as U, type ButtonProps as V, type CardJSXElement as W, type CardJSXProps as X, type CardLinkProps as Y, type CardProps as Z, type ContainerProps as _, type ChatElement as a, type FieldProps as a0, type ImageProps as a1, type LinkButtonProps as a2, type ModalProps as a3, type SelectOptionProps as a4, type SelectProps as a5, type TextInputProps as a6, type TextProps as a7, type ModalChild as a8, type ModalOptions as a9, type RadioSelectElement as aa, type RadioSelectOptions as ab, type SelectElement as ac, type SelectOptionElement as ad, type SelectOptions as ae, type TextInputElement as af, type TextInputOptions as ag, isCardLinkProps as ah, jsx as ai, jsxs as aj, jsxDEV as ak, Fragment as al, JSX as am, type CardChild as b, type CardComponent as c, cardChildToFallbackText as d, type CardLinkComponent as e, type FieldsComponent as f, fromReactElement as g, isJSX as h, isCardElement as i, Table as j, toModalElement as k, fromReactModalElement as l, isModalElement as m, type ModalComponent as n, type SelectComponent as o, type SelectOptionComponent as p, type TextInputComponent as q, type ActionsElement as r, type ButtonElement as s, toCardElement as t, type ButtonOptions as u, type ButtonStyle as v, type CardOptions as w, type DividerElement as x, type FieldElement as y, type FieldsElement as z };

package/dist/jsx-runtime.d.ts

@@ -1 +1 @@
-export { V as ButtonProps, a as CardJSXElement, W as CardJSXProps, X as CardLinkProps, Y as CardProps, Z as ContainerProps, _ as DividerProps, $ as FieldProps, ak as Fragment, a0 as ImageProps, al as JSX, a1 as LinkButtonProps, ac as ModalProps, af as SelectOptionProps, ae as SelectProps, ad as TextInputProps, a2 as TextProps, ag as isCardLinkProps, h as isJSX, ah as jsx, aj as jsxDEV, ai as jsxs, t as toCardElement, k as toModalElement } from './jsx-runtime-Bokk9xw5.js';
+export { A as ActionsComponent, B as ButtonComponent, V as ButtonProps, c as CardComponent, W as CardJSXElement, X as CardJSXProps, e as CardLinkComponent, Y as CardLinkProps, Z as CardProps, a as ChatElement, _ as ContainerProps, D as DividerComponent, $ as DividerProps, F as FieldComponent, a0 as FieldProps, f as FieldsComponent, al as Fragment, I as ImageComponent, a1 as ImageProps, am as JSX, L as LinkButtonComponent, a2 as LinkButtonProps, n as ModalComponent, a3 as ModalProps, R as RadioSelectComponent, S as SectionComponent, o as SelectComponent, p as SelectOptionComponent, a4 as SelectOptionProps, a5 as SelectProps, T as TextComponent, q as TextInputComponent, a6 as TextInputProps, a7 as TextProps, ah as isCardLinkProps, h as isJSX, ai as jsx, ak as jsxDEV, aj as jsxs, t as toCardElement, k as toModalElement } from './jsx-runtime-BJENDuXl.js';

package/dist/jsx-runtime.js

@@ -7,7 +7,7 @@ import {
   jsxs,
   toCardElement,
   toModalElement
-} from "./chunk-7S5DLTN2.js";
+} from "./chunk-Q32GJ2PR.js";
 export {
   Fragment,
   isCardLinkProps,

package/docs/actions.mdx

@@ -46,7 +46,7 @@ The `event` object passed to action handlers:
 | `actionId` | `string` | The `id` from the Button or Select component |
 | `value` | `string` (optional) | The `value` from the Button or selected option |
 | `user` | `Author` | The user who clicked |
-| `thread` | `Thread` | The thread containing the card |
+| `thread` | `Thread \| null` | The thread containing the card (null for view-based actions like home tab buttons) |
 | `messageId` | `string` | The message containing the card |
 | `threadId` | `string` | Thread ID |
 | `adapter` | `Adapter` | The platform adapter |

package/docs/adapters/slack.mdx

@@ -139,6 +139,7 @@ settings:
     request_url: https://your-domain.com/api/webhooks/slack
     bot_events:
       - app_mention
+      - member_joined_channel
       - message.channels
       - message.groups
       - message.im
@@ -219,6 +220,7 @@ SLACK_ENCRYPTION_KEY=...             # Optional, for token encryption
 | Message history | Yes |
 | Assistants API | Yes |
 | App Home tab | Yes |
+| Member joined channel | Yes |
 
 ## Slack Assistants API
 

package/docs/adapters/teams.mdx

@@ -140,12 +140,67 @@ All options are auto-detected from environment variables when not provided.
 | Option | Required | Description |
 |--------|----------|-------------|
 | `appId` | No* | Azure Bot App ID. Auto-detected from `TEAMS_APP_ID` |
-| `appPassword` | No* | Azure Bot App Password. Auto-detected from `TEAMS_APP_PASSWORD` |
+| `appPassword` | No** | Azure Bot App Password. Auto-detected from `TEAMS_APP_PASSWORD` |
+| `certificate` | No** | Certificate-based authentication config |
+| `federated` | No** | Federated (workload identity) authentication config |
 | `appType` | No | `"MultiTenant"` or `"SingleTenant"` (default: `"MultiTenant"`) |
 | `appTenantId` | For SingleTenant | Azure AD Tenant ID. Auto-detected from `TEAMS_APP_TENANT_ID` |
 | `logger` | No | Logger instance (defaults to `ConsoleLogger("info")`) |
 
-*`appId` and `appPassword` are required — either via config or env vars.
+\*`appId` is required — either via config or `TEAMS_APP_ID` env var.
+
+\*\*Exactly one authentication method is required: `appPassword`, `certificate`, or `federated`.
+
+### Authentication methods
+
+The adapter supports three mutually exclusive authentication methods. When no explicit auth is provided, `TEAMS_APP_PASSWORD` is auto-detected from environment variables.
+
+#### Client secret (default)
+
+The simplest option — provide `appPassword` directly or set `TEAMS_APP_PASSWORD`:
+
+```typescript title="lib/bot.ts"
+createTeamsAdapter({
+  appPassword: "your_app_password_here",
+});
+```
+
+#### Certificate
+
+Authenticate with a PEM certificate. Provide either `certificateThumbprint` or `x5c` (public certificate for subject-name validation):
+
+```typescript title="lib/bot.ts"
+createTeamsAdapter({
+  certificate: {
+    certificatePrivateKey: "-----BEGIN RSA PRIVATE KEY-----\n...",
+    certificateThumbprint: "AB1234...", // hex-encoded thumbprint
+  },
+});
+```
+
+Or with subject-name validation:
+
+```typescript title="lib/bot.ts"
+createTeamsAdapter({
+  certificate: {
+    certificatePrivateKey: "-----BEGIN RSA PRIVATE KEY-----\n...",
+    x5c: "-----BEGIN CERTIFICATE-----\n...",
+  },
+});
+```
+
+#### Federated (workload identity)
+
+For environments with managed identities (e.g. Azure Kubernetes Service, GitHub Actions):
+
+```typescript title="lib/bot.ts"
+createTeamsAdapter({
+  federated: {
+    clientId: "your_managed_identity_client_id_here",
+    clientAudience: "api://AzureADTokenExchange", // optional, this is the default
+  },
+});
+```
 
 ## Environment variables
 
@@ -212,7 +267,10 @@ Alternatively, configure the bot in Azure to receive all messages.
 
 ### "Unauthorized" error
 
-- Verify `TEAMS_APP_ID` and `TEAMS_APP_PASSWORD` are correct
+- Verify `TEAMS_APP_ID` and your chosen auth credential are correct
+- For client secret auth, check that `TEAMS_APP_PASSWORD` is valid
+- For certificate auth, ensure the private key and thumbprint/x5c match what's registered in Azure AD
+- For federated auth, verify the managed identity client ID and audience are correct
 - For SingleTenant apps, ensure `TEAMS_APP_TENANT_ID` is set
 - Check that the messaging endpoint URL is correct in Azure
 

package/docs/api/postable-message.mdx

@@ -7,7 +7,7 @@ type: reference
 `PostableMessage` is the union of all message formats accepted by `thread.post()` and `sent.edit()`.
 
 ```typescript
-type PostableMessage = AdapterPostableMessage | AsyncIterable<string>;
+type PostableMessage = AdapterPostableMessage | AsyncIterable<string | StreamChunk | StreamEvent>;
 ```
 
 ## String
@@ -135,15 +135,23 @@ await thread.post({
 
 ## AsyncIterable (streaming)
 
-An async iterable of strings, like the AI SDK's `textStream`. The SDK streams the message in real time using platform-native APIs where available.
+An async iterable of strings, `StreamChunk` objects, or stream events. The SDK streams the message in real time using platform-native APIs where available.
+
+You can yield structured `StreamChunk` objects for rich content like task progress cards on platforms that support it (Slack). See [Streaming](/docs/streaming#structured-streaming-chunks-slack-only) for details.
+
+Both AI SDK stream types are supported:
 
 ```typescript
-import { streamText } from "ai";
+// fullStream (recommended) — preserves step boundaries in multi-step agents
+const result = await agent.stream({ prompt: message.text });
+await thread.post(result.fullStream);
 
-const result = streamText({ model, prompt: message.text });
+// textStream — plain string chunks
 await thread.post(result.textStream);
 ```
 
+When using `fullStream`, the SDK auto-detects `text-delta` and `step-finish` events, extracting text and inserting paragraph breaks between agent steps.
+
 ## FileUpload
 
 Used in the `files` field of any structured message format.

package/docs/api/thread.mdx

@@ -54,8 +54,8 @@ await thread.post({ ast: root([paragraph([text("Hello")])]) });
 // Card
 await thread.post(Card({ title: "Hi", children: [Text("Hello")] }));
 
-// Stream
-await thread.post(result.textStream);
+// Stream (fullStream recommended for multi-step agents)
+await thread.post(result.fullStream);
 ```
 
 **Parameters:** `message: string | PostableMessage | CardJSXElement`

package/docs/handling-events.mdx

@@ -1,6 +1,6 @@
 ---
 title: Handling Events
-description: Register handlers for mentions, messages, reactions, and platform-specific events.
+description: Register handlers for mentions, messages, reactions, member joins, and platform-specific events.
 type: guide
 prerequisites:
   - /docs/getting-started
@@ -373,3 +373,30 @@ The `event` object includes:
 | `userId` | `string` | User who opened the Home tab |
 | `channelId` | `string` | Channel context |
 | `adapter` | `Adapter` | The Slack adapter |
+
+### Handling member joined channel
+
+`onMemberJoinedChannel` fires when a user joins a Slack channel. Use it to post welcome messages or onboard users automatically.
+
+```typescript title="lib/bot.ts" lineNumbers
+bot.onMemberJoinedChannel(async (event) => {
+  // Only post when the bot itself joins
+  if (event.userId !== event.adapter.botUserId) {
+    return;
+  }
+
+  await event.adapter.postMessage(
+    event.channelId,
+    "Hello! I'm now available in this channel. Mention me to get started."
+  );
+});
+```
+
+The `event` object includes:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `adapter` | `Adapter` | The Slack adapter |
+| `channelId` | `string` | The channel that was joined |
+| `userId` | `string` | The user who joined |
+| `inviterId` | `string` (optional) | The user who invited them |

package/docs/posting-messages.mdx

@@ -139,15 +139,18 @@ See the [Cards](/docs/cards) page for the full list of card components.
 
 ## Streaming
 
-Pass an `AsyncIterable<string>` (like the AI SDK's `textStream`) to stream a message in real time. The SDK uses platform-native streaming where available and falls back to post-then-edit on other platforms.
+Pass an AI SDK stream to `thread.post()` to stream a message in real time. The SDK uses platform-native streaming where available and falls back to post-then-edit on other platforms.
 
 ```typescript title="lib/bot.ts" lineNumbers
-import { streamText } from "ai";
+import { ToolLoopAgent } from "ai";
 
-const result = streamText({ model, prompt: message.text });
-await thread.post(result.textStream);
+const agent = new ToolLoopAgent({ model, instructions: "You are a helpful assistant." });
+const result = await agent.stream({ prompt: message.text });
+await thread.post(result.fullStream);
 ```
 
+Both `fullStream` and `textStream` are supported. Use `fullStream` with multi-step agents — it preserves paragraph breaks between steps. Any `AsyncIterable<string>` also works for custom streams.
+
 See the [Streaming](/docs/streaming) page for details on platform behavior and configuration.
 
 ## Attachments and files

package/docs/streaming.mdx

@@ -6,11 +6,11 @@ prerequisites:
   - /docs/usage
 ---
 
-Chat SDK accepts any `AsyncIterable<string>` as a message, enabling real-time streaming of AI responses and other incremental content to chat platforms.
+Chat SDK accepts any `AsyncIterable<string>` as a message, enabling real-time streaming of AI responses and other incremental content to chat platforms. For platforms with native streaming support (Slack), you can also stream structured `StreamChunk` objects for rich content like task progress cards and plan updates.
 
 ## AI SDK integration
 
-Pass an AI SDK `textStream` directly to `thread.post()`:
+Pass an AI SDK `fullStream` or `textStream` directly to `thread.post()`:
 
 ```typescript title="lib/bot.ts" lineNumbers
 import { ToolLoopAgent } from "ai";
@@ -22,10 +22,24 @@ const agent = new ToolLoopAgent({
 
 bot.onNewMention(async (thread, message) => {
   const result = await agent.stream({ prompt: message.text });
-  await thread.post(result.textStream);
+  await thread.post(result.fullStream);
 });
 ```
 
+### Why `fullStream` over `textStream`?
+
+When AI SDK agents make tool calls between text steps, `textStream` concatenates all text without separators — `"hello.how are you?"` instead of `"hello.\n\nhow are you?"`. The `fullStream` contains explicit `step-finish` events that Chat SDK uses to inject paragraph breaks between steps automatically.
+
+Both stream types are auto-detected:
+
+```typescript
+// Recommended: fullStream preserves step boundaries
+await thread.post(result.fullStream);
+
+// Also works: textStream for single-step generation
+await thread.post(result.textStream);
+```
+
 ## Custom streams
 
 Any async iterable works:
@@ -90,6 +104,64 @@ When streaming content that contains GFM tables (e.g. from an LLM), the SDK auto
 
 This happens transparently — no configuration needed.
 
+## Structured streaming chunks (Slack only)
+
+For Slack's native streaming API, you can yield `StreamChunk` objects alongside plain text for rich content:
+
+```typescript title="lib/bot.ts" lineNumbers
+import type { StreamChunk } from "chat";
+
+const stream = (async function* () {
+  yield { type: "markdown_text", text: "Searching..." } satisfies StreamChunk;
+
+  yield {
+    type: "task_update",
+    id: "search-1",
+    title: "Searching documents",
+    status: "in_progress",
+  } satisfies StreamChunk;
+
+  // ... do work ...
+
+  yield {
+    type: "task_update",
+    id: "search-1",
+    title: "Searching documents",
+    status: "complete",
+    output: "Found 3 results",
+  } satisfies StreamChunk;
+
+  yield { type: "markdown_text", text: "Here are your results..." } satisfies StreamChunk;
+})();
+
+await thread.post(stream);
+```
+
+### Chunk types
+
+| Type | Fields | Description |
+|------|--------|-------------|
+| `markdown_text` | `text` | Streamed text content |
+| `task_update` | `id`, `title`, `status`, `output?` | Tool/step progress cards (`pending`, `in_progress`, `complete`, `error`) |
+| `plan_update` | `title` | Plan title updates |
+
+### Task display mode
+
+Control how `task_update` chunks render in Slack by passing `taskDisplayMode` in stream options:
+
+```typescript
+await thread.stream(stream, {
+  taskDisplayMode: "plan", // Group all tasks into a single plan block
+});
+```
+
+| Mode | Description |
+|------|-------------|
+| `"timeline"` | Individual task cards shown inline with text (default) |
+| `"plan"` | All tasks grouped into a single plan block |
+
+Adapters without structured chunk support extract text from `markdown_text` chunks and ignore other types.
+
 ## Stop blocks (Slack only)
 
 When streaming in Slack, you can attach Block Kit elements to the final message using `stopBlocks`. This is useful for adding action buttons after a streamed response completes:
@@ -126,6 +198,6 @@ bot.onSubscribedMessage(async (thread, message) => {
     }));
 
   const response = await agent.stream({ prompt: history });
-  await thread.post(response.textStream);
+  await thread.post(response.fullStream);
 });
 ```

package/package.json

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