chat 4.0.2 → 4.1.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 */
@@ -133,6 +138,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 +235,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,6 +251,38 @@ 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 */
@@ -252,7 +320,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 +338,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>>;
@@ -392,6 +468,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 +482,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 +578,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 +609,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 +810,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 +831,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 +899,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 +914,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 +938,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 +1054,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.
      */
@@ -1150,6 +1245,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 +1378,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 +1393,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 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 StreamOptions, type SubscribedMessageHandler, THREAD_STATE_TTL_MS, 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 };