chat 4.0.2 → 4.2.0

package/dist/index.d.ts

@@ -46,6 +46,11 @@ interface ChatConfig<TAdapters extends Record<string, Adapter> = Record<string,
      * Pass "silent" to disable all logging.
      */
     logger?: Logger | LogLevel;
+    /**
+     * Update interval for fallback streaming (post + edit) in milliseconds.
+     * Defaults to 500ms. Lower values provide smoother updates but may hit rate limits.
+     */
+    streamingUpdateIntervalMs?: number;
 }
 /**
  * Options for webhook handling.
@@ -84,9 +89,9 @@ interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
     /** Handle incoming webhook request */
     handleWebhook(request: Request, options?: WebhookOptions): Promise<Response>;
     /** Post a message to a thread */
-    postMessage(threadId: string, message: PostableMessage): Promise<RawMessage<TRawMessage>>;
+    postMessage(threadId: string, message: AdapterPostableMessage): Promise<RawMessage<TRawMessage>>;
     /** Edit an existing message */
-    editMessage(threadId: string, messageId: string, message: PostableMessage): Promise<RawMessage<TRawMessage>>;
+    editMessage(threadId: string, messageId: string, message: AdapterPostableMessage): Promise<RawMessage<TRawMessage>>;
     /** Delete a message */
     deleteMessage(threadId: string, messageId: string): Promise<void>;
     /** Add a reaction to a message */
@@ -95,8 +100,39 @@ interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
     removeReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
     /** Show typing indicator */
     startTyping(threadId: string): Promise<void>;
-    /** Fetch messages from a thread */
-    fetchMessages(threadId: string, options?: FetchOptions): Promise<Message<TRawMessage>[]>;
+    /**
+     * Fetch messages from a thread.
+     *
+     * **Direction behavior:**
+     * - `backward` (default): Fetches the most recent messages. Use this for loading
+     *   a chat view. The `nextCursor` points to older messages.
+     * - `forward`: Fetches the oldest messages first. Use this for iterating through
+     *   message history. The `nextCursor` points to newer messages.
+     *
+     * **Message ordering:**
+     * Messages within each page are always returned in chronological order (oldest first),
+     * regardless of direction. This is the natural reading order for chat messages.
+     *
+     * @example
+     * ```typescript
+     * // Load most recent 50 messages for display
+     * const recent = await adapter.fetchMessages(threadId, { limit: 50 });
+     * // recent.messages: [older, ..., newest] in chronological order
+     *
+     * // Paginate backward to load older messages
+     * const older = await adapter.fetchMessages(threadId, {
+     *   limit: 50,
+     *   cursor: recent.nextCursor,
+     * });
+     *
+     * // Iterate through all history from the beginning
+     * const history = await adapter.fetchMessages(threadId, {
+     *   limit: 100,
+     *   direction: 'forward',
+     * });
+     * ```
+     */
+    fetchMessages(threadId: string, options?: FetchOptions): Promise<FetchResult<TRawMessage>>;
     /** Fetch thread metadata */
     fetchThread(threadId: string): Promise<ThreadInfo>;
     /** Encode platform-specific data into a thread ID string */
@@ -133,6 +169,30 @@ interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
      * @returns True if the thread is a DM, false otherwise
      */
     isDM?(threadId: string): boolean;
+    /**
+     * Stream a message using platform-native streaming APIs.
+     *
+     * The adapter consumes the async iterable and handles the entire streaming lifecycle.
+     * Only available on platforms with native streaming support (e.g., Slack).
+     *
+     * @param threadId - The thread to stream to
+     * @param textStream - Async iterable of text chunks (e.g., from AI SDK)
+     * @param options - Platform-specific streaming options
+     * @returns The raw message after streaming completes
+     */
+    stream?(threadId: string, textStream: AsyncIterable<string>, options?: StreamOptions): Promise<RawMessage<TRawMessage>>;
+}
+/**
+ * Options for streaming messages.
+ * Platform-specific options are passed through to the adapter.
+ */
+interface StreamOptions {
+    /** Slack: The user ID to stream to (for AI assistant context) */
+    recipientUserId?: string;
+    /** Slack: The team/workspace ID */
+    recipientTeamId?: string;
+    /** Minimum interval between updates in ms (default: 1000). Used for fallback mode (GChat/Teams). */
+    updateIntervalMs?: number;
 }
 /** Internal interface for Chat instance passed to adapters */
 interface ChatInstance {
@@ -206,7 +266,14 @@ interface Lock {
     token: string;
     expiresAt: number;
 }
-interface Thread<TRawMessage = unknown> {
+/** Default TTL for thread state (30 days in milliseconds) */
+declare const THREAD_STATE_TTL_MS: number;
+/**
+ * Thread interface with support for custom state.
+ * @template TState - Custom state type stored per-thread (default: Record<string, unknown>)
+ * @template TRawMessage - Platform-specific raw message type
+ */
+interface Thread<TState = Record<string, unknown>, TRawMessage = unknown> {
     /** Unique thread ID (format: "adapter:channel:thread") */
     readonly id: string;
     /** The adapter this thread belongs to */
@@ -215,9 +282,45 @@ interface Thread<TRawMessage = unknown> {
     readonly channelId: string;
     /** Whether this is a direct message conversation */
     readonly isDM: boolean;
+    /**
+     * Get the current thread state.
+     * Returns null if no state has been set.
+     *
+     * @example
+     * ```typescript
+     * const state = await thread.state;
+     * if (state?.aiMode) {
+     *   // AI mode is enabled
+     * }
+     * ```
+     */
+    readonly state: Promise<TState | null>;
+    /**
+     * Set the thread state. Merges with existing state by default.
+     * State is persisted for 30 days.
+     *
+     * @param state - Partial state to merge, or full state if replace is true
+     * @param options - Options for setting state
+     *
+     * @example
+     * ```typescript
+     * // Merge with existing state
+     * await thread.setState({ aiMode: true });
+     *
+     * // Replace entire state
+     * await thread.setState({ aiMode: true }, { replace: true });
+     * ```
+     */
+    setState(state: Partial<TState>, options?: {
+        replace?: boolean;
+    }): Promise<void>;
     /** Recently fetched messages (cached) */
     recentMessages: Message<TRawMessage>[];
-    /** Async iterator for all messages in the thread */
+    /**
+     * Async iterator for all messages in the thread.
+     * Messages are yielded in chronological order (oldest first).
+     * Automatically handles pagination.
+     */
     allMessages: AsyncIterable<Message<TRawMessage>>;
     /**
      * Check if this thread is currently subscribed.
@@ -252,7 +355,11 @@ interface Thread<TRawMessage = unknown> {
     /**
      * Post a message to this thread.
      *
-     * @param message - String, PostableMessage, or JSX Card element to send
+     * Supports text, markdown, cards, and streaming from async iterables.
+     * When posting a stream (e.g., from AI SDK), uses platform-native streaming
+     * APIs when available (Slack), or falls back to post + edit with throttling.
+     *
+     * @param message - String, PostableMessage, JSX Card, or AsyncIterable<string>
      * @returns A SentMessage with methods to edit, delete, or add reactions
      *
      * @example
@@ -266,12 +373,16 @@ interface Thread<TRawMessage = unknown> {
      * // With emoji
      * await thread.post(`${emoji.thumbs_up} Great job!`);
      *
-     * // JSX Card (with @jsxImportSource chat-sdk)
+     * // JSX Card (with @jsxImportSource chat)
      * await thread.post(
      *   <Card title="Welcome!">
      *     <Text>Hello world</Text>
      *   </Card>
      * );
+     *
+     * // Stream from AI SDK
+     * const result = await agent.stream({ prompt: message.text });
+     * await thread.post(result.textStream);
      * ```
      */
     post(message: string | PostableMessage | CardJSXElement): Promise<SentMessage<TRawMessage>>;
@@ -304,13 +415,77 @@ interface ThreadInfo {
     /** Platform-specific metadata */
     metadata: Record<string, unknown>;
 }
+/**
+ * Direction for fetching messages.
+ *
+ * - `backward`: Fetch most recent messages first. Pagination moves toward older messages.
+ *   This is the default, suitable for loading a chat view (show latest messages first).
+ *
+ * - `forward`: Fetch oldest messages first. Pagination moves toward newer messages.
+ *   Suitable for iterating through message history from the beginning.
+ *
+ * In both directions, messages within each page are returned in chronological order
+ * (oldest first), which is the natural reading order for chat messages.
+ *
+ * @example
+ * ```typescript
+ * // Load most recent 50 messages (default)
+ * const recent = await adapter.fetchMessages(threadId, { limit: 50 });
+ * // recent.messages: [older, ..., newest] (chronological within page)
+ * // recent.nextCursor: points to older messages
+ *
+ * // Iterate through all history from beginning
+ * const history = await adapter.fetchMessages(threadId, {
+ *   limit: 50,
+ *   direction: 'forward',
+ * });
+ * // history.messages: [oldest, ..., newer] (chronological within page)
+ * // history.nextCursor: points to even newer messages
+ * ```
+ */
+type FetchDirection = "forward" | "backward";
+/**
+ * Options for fetching messages from a thread.
+ */
 interface FetchOptions {
-    /** Maximum number of messages to fetch */
+    /** Maximum number of messages to fetch. Default varies by adapter (50-100). */
     limit?: number;
-    /** Fetch messages before this message ID */
-    before?: string;
-    /** Fetch messages after this message ID */
-    after?: string;
+    /**
+     * Pagination cursor for fetching the next page of messages.
+     * Pass the `nextCursor` from a previous `FetchResult`.
+     */
+    cursor?: string;
+    /**
+     * Direction to fetch messages.
+     *
+     * - `backward` (default): Fetch most recent messages. Cursor moves to older messages.
+     * - `forward`: Fetch oldest messages. Cursor moves to newer messages.
+     *
+     * Messages within each page are always returned in chronological order (oldest first).
+     */
+    direction?: FetchDirection;
+}
+/**
+ * Result of fetching messages from a thread.
+ */
+interface FetchResult<TRawMessage = unknown> {
+    /**
+     * Messages in chronological order (oldest first within this page).
+     *
+     * For `direction: 'backward'` (default): These are the N most recent messages.
+     * For `direction: 'forward'`: These are the N oldest messages (or next N after cursor).
+     */
+    messages: Message<TRawMessage>[];
+    /**
+     * Cursor for fetching the next page.
+     * Pass this as `cursor` in the next `fetchMessages` call.
+     *
+     * - For `direction: 'backward'`: Points to older messages.
+     * - For `direction: 'forward'`: Points to newer messages.
+     *
+     * Undefined if there are no more messages in that direction.
+     */
+    nextCursor?: string;
 }
 /**
  * Formatted content using mdast AST.
@@ -392,6 +567,11 @@ interface SentMessage<TRawMessage = unknown> extends Message<TRawMessage> {
     /** Remove a reaction from this message */
     removeReaction(emoji: EmojiValue | string): Promise<void>;
 }
+/**
+ * Input type for adapter postMessage/editMessage methods.
+ * This excludes streams since adapters handle content synchronously.
+ */
+type AdapterPostableMessage = string | PostableRaw | PostableMarkdown | PostableAst | PostableCard | CardElement;
 /**
  * A message that can be posted to a thread.
  *
@@ -401,8 +581,9 @@ interface SentMessage<TRawMessage = unknown> extends Message<TRawMessage> {
  * - `{ ast: Root }` - mdast AST, converted to platform format
  * - `{ card: CardElement }` - Rich card with buttons (Block Kit / Adaptive Cards / GChat Cards)
  * - `CardElement` - Direct card element
+ * - `AsyncIterable<string>` - Streaming text (e.g., from AI SDK's textStream)
  */
-type PostableMessage = string | PostableRaw | PostableMarkdown | PostableAst | PostableCard | CardElement;
+type PostableMessage = AdapterPostableMessage | AsyncIterable<string>;
 interface PostableRaw {
     /** Raw text passed through as-is to the platform */
     raw: string;
@@ -496,14 +677,14 @@ interface FileUpload {
  * });
  * ```
  */
-type MentionHandler = (thread: Thread, message: Message) => Promise<void>;
+type MentionHandler<TState = Record<string, unknown>> = (thread: Thread<TState>, message: Message) => Promise<void>;
 /**
  * Handler for messages matching a regex pattern.
  *
  * Registered via `chat.onNewMessage(pattern, handler)`. Called when a message
  * matches the pattern in an unsubscribed thread.
  */
-type MessageHandler = (thread: Thread, message: Message) => Promise<void>;
+type MessageHandler<TState = Record<string, unknown>> = (thread: Thread<TState>, message: Message) => Promise<void>;
 /**
  * Handler for messages in subscribed threads.
  *
@@ -527,7 +708,7 @@ type MessageHandler = (thread: Thread, message: Message) => Promise<void>;
  * });
  * ```
  */
-type SubscribedMessageHandler = (thread: Thread, message: Message) => Promise<void>;
+type SubscribedMessageHandler<TState = Record<string, unknown>> = (thread: Thread<TState>, message: Message) => Promise<void>;
 /**
  * Well-known emoji that work across platforms (Slack and Google Chat).
  * These are normalized to a common format regardless of platform.
@@ -728,10 +909,19 @@ type Webhooks<TAdapters extends Record<string, Adapter>> = {
     [K in keyof TAdapters]: WebhookHandler;
 };
 /**
- * Main Chat class with type-safe adapter inference.
+ * Main Chat class with type-safe adapter inference and custom thread state.
+ *
+ * @template TAdapters - Map of adapter names to Adapter instances
+ * @template TState - Custom state type stored per-thread (default: Record<string, unknown>)
  *
  * @example
- * const chat = new Chat({
+ * // Define custom thread state type
+ * interface MyThreadState {
+ *   aiMode?: boolean;
+ *   userName?: string;
+ * }
+ *
+ * const chat = new Chat<typeof adapters, MyThreadState>({
  *   userName: "mybot",
  *   adapters: {
  *     slack: createSlackAdapter({ ... }),
@@ -740,14 +930,18 @@ type Webhooks<TAdapters extends Record<string, Adapter>> = {
  *   state: createMemoryState(),
  * });
  *
- * // Type-safe: only 'slack' and 'teams' are valid
- * chat.webhooks.slack(request, { waitUntil });
+ * // Type-safe thread state
+ * chat.onNewMention(async (thread, message) => {
+ *   await thread.setState({ aiMode: true });
+ *   const state = await thread.state; // Type: MyThreadState | null
+ * });
  */
-declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Adapter>> implements ChatInstance {
+declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Adapter>, TState = Record<string, unknown>> implements ChatInstance {
     private adapters;
-    private state;
+    private _stateAdapter;
     private userName;
     private logger;
+    private _streamingUpdateIntervalMs;
     private mentionHandlers;
     private messagePatterns;
     private subscribedMessageHandlers;
@@ -804,7 +998,7 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
      * });
      * ```
      */
-    onNewMention(handler: MentionHandler): void;
+    onNewMention(handler: MentionHandler<TState>): void;
     /**
      * Register a handler for messages matching a regex pattern.
      *
@@ -819,7 +1013,7 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
      * });
      * ```
      */
-    onNewMessage(pattern: RegExp, handler: MessageHandler): void;
+    onNewMessage(pattern: RegExp, handler: MessageHandler<TState>): void;
     /**
      * Register a handler for messages in subscribed threads.
      *
@@ -843,7 +1037,7 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
      * });
      * ```
      */
-    onSubscribedMessage(handler: SubscribedMessageHandler): void;
+    onSubscribedMessage(handler: SubscribedMessageHandler<TState>): void;
     /**
      * Register a handler for reaction events.
      *
@@ -959,7 +1153,7 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
      * });
      * ```
      */
-    openDM(user: string | Author): Promise<Thread>;
+    openDM(user: string | Author): Promise<Thread<TState>>;
     /**
      * Infer which adapter to use based on the userId format.
      */
@@ -985,6 +1179,71 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
     private runHandlers;
 }
 
+interface ThreadImplConfig {
+    id: string;
+    adapter: Adapter;
+    channelId: string;
+    stateAdapter: StateAdapter;
+    initialMessage?: Message;
+    /** If true, thread is known to be subscribed (for short-circuit optimization) */
+    isSubscribedContext?: boolean;
+    /** Whether this is a direct message conversation */
+    isDM?: boolean;
+    /** Current message context for streaming (provides userId/teamId) */
+    currentMessage?: Message;
+    /** Update interval for fallback streaming in milliseconds. Defaults to 500ms. */
+    streamingUpdateIntervalMs?: number;
+}
+declare class ThreadImpl<TState = Record<string, unknown>> implements Thread<TState> {
+    readonly id: string;
+    readonly adapter: Adapter;
+    readonly channelId: string;
+    readonly isDM: boolean;
+    private _stateAdapter;
+    private _recentMessages;
+    private _isSubscribedContext;
+    /** Current message context for streaming - provides userId/teamId */
+    private _currentMessage?;
+    /** Update interval for fallback streaming */
+    private _streamingUpdateIntervalMs;
+    constructor(config: ThreadImplConfig);
+    get recentMessages(): Message[];
+    set recentMessages(messages: Message[]);
+    /**
+     * Get the current thread state.
+     * Returns null if no state has been set.
+     */
+    get state(): Promise<TState | null>;
+    /**
+     * Set the thread state. Merges with existing state by default.
+     * State is persisted for 30 days.
+     */
+    setState(newState: Partial<TState>, options?: {
+        replace?: boolean;
+    }): Promise<void>;
+    get allMessages(): AsyncIterable<Message>;
+    isSubscribed(): Promise<boolean>;
+    subscribe(): Promise<void>;
+    unsubscribe(): Promise<void>;
+    post(message: string | PostableMessage | CardJSXElement): Promise<SentMessage>;
+    /**
+     * Handle streaming from an AsyncIterable.
+     * Uses adapter's native streaming if available, otherwise falls back to post+edit.
+     */
+    private handleStream;
+    startTyping(): Promise<void>;
+    /**
+     * Fallback streaming implementation using post + edit.
+     * Used when adapter doesn't support native streaming.
+     * Uses recursive setTimeout to send updates every intervalMs (default 500ms).
+     * Schedules next update only after current edit completes to avoid overwhelming slow services.
+     */
+    private fallbackStream;
+    refresh(): Promise<void>;
+    mentionUser(userId: string): string;
+    private createSentMessage;
+}
+
 /**
  * Get or create an immutable singleton EmojiValue.
  *
@@ -1150,6 +1409,8 @@ declare const emoji: ExtendedEmojiHelper;
  * Markdown parsing and conversion utilities using unified/remark.
  */
 
+type PostableMessageInput = AdapterPostableMessage;
+
 /**
  * Parse markdown string into an AST.
  * Supports GFM (GitHub Flavored Markdown) for strikethrough, tables, etc.
@@ -1281,19 +1542,6 @@ declare abstract class BaseFormatConverter implements FormatConverter {
      */
     protected cardChildToFallbackText(child: CardChild): string | null;
 }
-/**
- * Type for PostableMessage input (for rendering to text)
- */
-type PostableMessageInput = string | {
-    raw: string;
-} | {
-    markdown: string;
-} | {
-    ast: Root;
-} | {
-    card: CardElement;
-    fallbackText?: string;
-} | CardElement;
 
 declare const Actions: typeof Actions$1;
 declare const Button: typeof Button$1;
@@ -1309,4 +1557,4 @@ declare const isJSX: typeof isJSX$1;
 declare const Section: typeof Section$1;
 declare const toCardElement: typeof toCardElement$1;
 
-export { type ActionEvent, type ActionHandler, Actions, type Adapter, type Attachment, type Author, BaseFormatConverter, Button, Card, CardChild, CardElement, CardJSXElement, CardText, Chat, type ChatConfig, ChatError, type ChatInstance, ConsoleLogger, type CustomEmojiMap, DEFAULT_EMOJI_MAP, Divider, type Emoji, type EmojiFormats, type EmojiMapConfig, EmojiResolver, type EmojiValue, type FetchOptions, Field, Fields, type FileUpload, type FormatConverter, type FormattedContent, Image, type Lock, LockError, type LogLevel, type Logger, type MarkdownConverter, type MentionHandler, type Message, type MessageHandler, type MessageMetadata, NotImplementedError, type PostableAst, type PostableCard, type PostableMarkdown, type PostableMessage, type PostableRaw, RateLimitError, type RawMessage, type ReactionEvent, type ReactionHandler, Section, type SentMessage, type StateAdapter, type SubscribedMessageHandler, type Thread, type ThreadInfo, type WebhookOptions, type WellKnownEmoji, blockquote, codeBlock, convertEmojiPlaceholders, createEmoji, defaultEmojiResolver, emoji, emphasis, fromReactElement, getEmoji, inlineCode, isCardElement, isJSX, link, markdownToPlainText, paragraph, parseMarkdown, root, strikethrough, stringifyMarkdown, strong, text, toCardElement, toPlainText, walkAst };
+export { type ActionEvent, type ActionHandler, Actions, type Adapter, type AdapterPostableMessage, type Attachment, type Author, BaseFormatConverter, Button, Card, CardChild, CardElement, CardJSXElement, CardText, Chat, type ChatConfig, ChatError, type ChatInstance, ConsoleLogger, type CustomEmojiMap, DEFAULT_EMOJI_MAP, Divider, type Emoji, type EmojiFormats, type EmojiMapConfig, EmojiResolver, type EmojiValue, type FetchDirection, type FetchOptions, type FetchResult, Field, Fields, type FileUpload, type FormatConverter, type FormattedContent, Image, type Lock, LockError, type LogLevel, type Logger, type MarkdownConverter, type MentionHandler, type Message, type MessageHandler, type MessageMetadata, NotImplementedError, type PostableAst, type PostableCard, type PostableMarkdown, type PostableMessage, type PostableRaw, RateLimitError, type RawMessage, type ReactionEvent, type ReactionHandler, Section, type SentMessage, type StateAdapter, type StreamOptions, type SubscribedMessageHandler, THREAD_STATE_TTL_MS, type Thread, ThreadImpl, type ThreadInfo, type WebhookOptions, type WellKnownEmoji, blockquote, codeBlock, convertEmojiPlaceholders, createEmoji, defaultEmojiResolver, emoji, emphasis, fromReactElement, getEmoji, inlineCode, isCardElement, isJSX, link, markdownToPlainText, paragraph, parseMarkdown, root, strikethrough, stringifyMarkdown, strong, text, toCardElement, toPlainText, walkAst };