chat 4.4.0 → 4.5.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { C as CardElement, a as CardJSXElement, M as ModalElement, b as CardChild, A as Actions$1, B as Button$1, c as Card$1, T as Text$1, D as Divider$1, F as Field$1, d as Fields$1, f as fromReactElement$1, I as Image$1, i as isCardElement$1, e as isJSX$1, S as Section$1, t as toCardElement$1, g as toModalElement$1, h as fromReactModalElement$1, j as isModalElement$1, k as Modal$1, l as Select$1, m as SelectOption$1, n as TextInput$1 } from './jsx-runtime-CFK57xOl.js';
 export { x as ActionsElement, y as ButtonElement, z as ButtonOptions, o as ButtonProps, E as ButtonStyle, p as CardJSXProps, G as CardOptions, q as CardProps, r as ContainerProps, H as DividerElement, s as DividerProps, J as FieldElement, u as FieldProps, K as FieldsElement, L as ImageElement, v as ImageProps, Q as ModalChild, R as ModalOptions, N as SectionElement, U as SelectElement, V as SelectOptionElement, W as SelectOptions, O as TextElement, X as TextInputElement, Y as TextInputOptions, w as TextProps, P as TextStyle } from './jsx-runtime-CFK57xOl.js';
+import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
 import { Root, Content, Blockquote, Code, Emphasis, InlineCode, Delete, Link, ListItem, List, Paragraph, Strong, Text } from 'mdast';
 export { Blockquote, Code, Content, Delete, Emphasis, InlineCode, Link, List, ListItem, Paragraph, Root, Strong, Text } from 'mdast';
 
@@ -182,6 +183,18 @@ interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
      * ```
      */
     openDM?(userId: string): Promise<string>;
+    /**
+     * Post an ephemeral message visible only to a specific user.
+     *
+     * This is optional - if not implemented, Thread.postEphemeral will
+     * fall back to openDM + postMessage when fallbackToDM is true.
+     *
+     * @param threadId - The thread to post in
+     * @param userId - The user who should see the message
+     * @param message - The message content
+     * @returns EphemeralMessage with usedFallback: false
+     */
+    postEphemeral?(threadId: string, userId: string, message: AdapterPostableMessage): Promise<EphemeralMessage>;
     /**
      * Check if a thread is a direct message conversation.
      *
@@ -418,6 +431,35 @@ interface Thread<TState = Record<string, unknown>, TRawMessage = unknown> {
      * ```
      */
     post(message: string | PostableMessage | CardJSXElement): Promise<SentMessage<TRawMessage>>;
+    /**
+     * Post an ephemeral message visible only to a specific user.
+     *
+     * **Platform Behavior:**
+     * - **Slack**: Native ephemeral (session-dependent, disappears on reload)
+     * - **Google Chat**: Native private message (persists, only target user sees it)
+     * - **Discord**: No native support - requires fallbackToDM: true
+     * - **Teams**: No native support - requires fallbackToDM: true
+     *
+     * @param user - User ID string or Author object (from message.author or event.user)
+     * @param message - Message content (string, markdown, card, etc.). Streaming is not supported.
+     * @param options.fallbackToDM - Required. If true, falls back to DM when native
+     *   ephemeral is not supported. If false, returns null when unsupported.
+     * @returns EphemeralMessage with `usedFallback: true` if DM was used, or null
+     *   if native ephemeral not supported and fallbackToDM is false
+     *
+     * @example
+     * ```typescript
+     * // Always send (DM fallback on Discord/Teams)
+     * await thread.postEphemeral(user, 'Only you can see this!', { fallbackToDM: true })
+     *
+     * // Only send if native ephemeral supported (Slack/GChat)
+     * const result = await thread.postEphemeral(user, 'Secret!', { fallbackToDM: false })
+     * if (!result) {
+     *   // Platform doesn't support native ephemeral - handle accordingly
+     * }
+     * ```
+     */
+    postEphemeral(user: string | Author, message: AdapterPostableMessage | CardJSXElement, options: PostEphemeralOptions): Promise<EphemeralMessage | null>;
     /**
      * Show typing indicator in the thread.
      *
@@ -524,45 +566,6 @@ interface FetchResult<TRawMessage = unknown> {
  * This is the canonical representation of message formatting.
  */
 type FormattedContent = Root;
-interface Message<TRawMessage = unknown> {
-    /** Unique message ID */
-    readonly id: string;
-    /** Thread this message belongs to */
-    readonly threadId: string;
-    /** Plain text content (all formatting stripped) */
-    text: string;
-    /**
-     * Structured formatting as an AST (mdast Root).
-     * This is the canonical representation - use this for processing.
-     * Use `stringifyMarkdown(message.formatted)` to get markdown string.
-     */
-    formatted: FormattedContent;
-    /** Platform-specific raw payload (escape hatch) */
-    raw: TRawMessage;
-    /** Message author */
-    author: Author;
-    /** Message metadata */
-    metadata: MessageMetadata;
-    /** Attachments */
-    attachments: Attachment[];
-    /**
-     * Whether the bot is @-mentioned in this message.
-     *
-     * This is set by the Chat SDK before passing the message to handlers.
-     * It checks for `@username` in the message text using the adapter's
-     * configured `userName` and optional `botUserId`.
-     *
-     * @example
-     * ```typescript
-     * chat.onSubscribedMessage(async (thread, message) => {
-     *   if (message.isMention) {
-     *     await thread.post("You mentioned me!");
-     *   }
-     * });
-     * ```
-     */
-    isMention?: boolean;
-}
 /** Raw message returned from adapter (before wrapping as SentMessage) */
 interface RawMessage<TRawMessage = unknown> {
     id: string;
@@ -599,6 +602,34 @@ interface SentMessage<TRawMessage = unknown> extends Message<TRawMessage> {
     /** Remove a reaction from this message */
     removeReaction(emoji: EmojiValue | string): Promise<void>;
 }
+/**
+ * Result of posting an ephemeral message.
+ *
+ * Ephemeral messages are visible only to a specific user and typically
+ * cannot be edited or deleted (platform-dependent).
+ */
+interface EphemeralMessage {
+    /** Message ID (may be empty for some platforms) */
+    id: string;
+    /** Thread ID where message was sent (or DM thread if fallback was used) */
+    threadId: string;
+    /** Whether this used native ephemeral or fell back to DM */
+    usedFallback: boolean;
+    /** Platform-specific raw response */
+    raw: unknown;
+}
+/**
+ * Options for posting ephemeral messages.
+ */
+interface PostEphemeralOptions {
+    /**
+     * Controls behavior when native ephemeral is not supported by the platform.
+     *
+     * - `true`: Falls back to sending a DM to the user
+     * - `false`: Returns `null` if native ephemeral is not supported
+     */
+    fallbackToDM: boolean;
+}
 /**
  * Input type for adapter postMessage/editMessage methods.
  * This excludes streams since adapters handle content synchronously.
@@ -934,6 +965,7 @@ interface ModalSubmitEvent {
 interface ModalCloseEvent {
     callbackId: string;
     viewId: string;
+    privateMetadata?: string;
     user: Author;
     adapter: Adapter;
     raw: unknown;
@@ -957,6 +989,153 @@ type ModalResponse = ModalCloseResponse | ModalErrorsResponse | ModalUpdateRespo
 type ModalSubmitHandler = (event: ModalSubmitEvent) => Promise<ModalResponse | undefined>;
 type ModalCloseHandler = (event: ModalCloseEvent) => Promise<void>;
 
+/**
+ * Message class with serialization support for workflow engines.
+ */
+
+/**
+ * Input data for creating a Message instance.
+ * Use this interface when constructing Message objects.
+ */
+interface MessageData<TRawMessage = unknown> {
+    /** Unique message ID */
+    id: string;
+    /** Thread this message belongs to */
+    threadId: string;
+    /** Plain text content (all formatting stripped) */
+    text: string;
+    /** Structured formatting as an AST (mdast Root) */
+    formatted: FormattedContent;
+    /** Platform-specific raw payload (escape hatch) */
+    raw: TRawMessage;
+    /** Message author */
+    author: Author;
+    /** Message metadata */
+    metadata: MessageMetadata;
+    /** Attachments */
+    attachments: Attachment[];
+    /** Whether the bot is @-mentioned in this message */
+    isMention?: boolean;
+}
+/**
+ * Serialized message data for passing to external systems (e.g., workflow engines).
+ * Dates are converted to ISO strings, and non-serializable fields are omitted.
+ */
+interface SerializedMessage {
+    _type: "chat:Message";
+    id: string;
+    threadId: string;
+    text: string;
+    formatted: Root;
+    raw: unknown;
+    author: {
+        userId: string;
+        userName: string;
+        fullName: string;
+        isBot: boolean | "unknown";
+        isMe: boolean;
+    };
+    metadata: {
+        dateSent: string;
+        edited: boolean;
+        editedAt?: string;
+    };
+    attachments: Array<{
+        type: "image" | "file" | "video" | "audio";
+        url?: string;
+        name?: string;
+        mimeType?: string;
+        size?: number;
+        width?: number;
+        height?: number;
+    }>;
+    isMention?: boolean;
+}
+/**
+ * A chat message with serialization support for workflow engines.
+ *
+ * @example
+ * ```typescript
+ * // Create a message
+ * const message = new Message({
+ *   id: "msg-1",
+ *   threadId: "slack:C123:1234.5678",
+ *   text: "Hello world",
+ *   formatted: parseMarkdown("Hello world"),
+ *   raw: {},
+ *   author: { userId: "U123", userName: "user", fullName: "User", isBot: false, isMe: false },
+ *   metadata: { dateSent: new Date(), edited: false },
+ *   attachments: [],
+ * });
+ *
+ * // Serialize for workflow
+ * const serialized = message.toJSON();
+ * ```
+ */
+declare class Message<TRawMessage = unknown> {
+    /** Unique message ID */
+    readonly id: string;
+    /** Thread this message belongs to */
+    readonly threadId: string;
+    /** Plain text content (all formatting stripped) */
+    text: string;
+    /**
+     * Structured formatting as an AST (mdast Root).
+     * This is the canonical representation - use this for processing.
+     * Use `stringifyMarkdown(message.formatted)` to get markdown string.
+     */
+    formatted: FormattedContent;
+    /** Platform-specific raw payload (escape hatch) */
+    raw: TRawMessage;
+    /** Message author */
+    author: Author;
+    /** Message metadata */
+    metadata: MessageMetadata;
+    /** Attachments */
+    attachments: Attachment[];
+    /**
+     * Whether the bot is @-mentioned in this message.
+     *
+     * This is set by the Chat SDK before passing the message to handlers.
+     * It checks for `@username` in the message text using the adapter's
+     * configured `userName` and optional `botUserId`.
+     *
+     * @example
+     * ```typescript
+     * chat.onSubscribedMessage(async (thread, message) => {
+     *   if (message.isMention) {
+     *     await thread.post("You mentioned me!");
+     *   }
+     * });
+     * ```
+     */
+    isMention?: boolean;
+    constructor(data: MessageData<TRawMessage>);
+    /**
+     * Serialize the message to a plain JSON object.
+     * Use this to pass message data to external systems like workflow engines.
+     *
+     * Note: Attachment `data` (Buffer) and `fetchData` (function) are omitted
+     * as they're not serializable.
+     */
+    toJSON(): SerializedMessage;
+    /**
+     * Reconstruct a Message from serialized JSON data.
+     * Converts ISO date strings back to Date objects.
+     */
+    static fromJSON<TRawMessage = unknown>(json: SerializedMessage): Message<TRawMessage>;
+    /**
+     * Serialize a Message instance for @workflow/serde.
+     * This static method is automatically called by workflow serialization.
+     */
+    static [WORKFLOW_SERIALIZE](instance: Message): SerializedMessage;
+    /**
+     * Deserialize a Message from @workflow/serde.
+     * This static method is automatically called by workflow deserialization.
+     */
+    static [WORKFLOW_DESERIALIZE](data: SerializedMessage): Message;
+}
+
 /** Filter can be EmojiValue objects, emoji names, or raw emoji formats */
 type EmojiFilter = EmojiValue | string;
 /**
@@ -998,6 +1177,29 @@ type Webhooks<TAdapters extends Record<string, Adapter>> = {
  * });
  */
 declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Adapter>, TState = Record<string, unknown>> implements ChatInstance {
+    /**
+     * Register this Chat instance as the global singleton.
+     * Required for Thread deserialization via @workflow/serde.
+     *
+     * @example
+     * ```typescript
+     * const chat = new Chat({ ... });
+     * chat.registerSingleton();
+     *
+     * // Now threads can be deserialized without passing chat explicitly
+     * const thread = ThreadImpl.fromJSON(serializedThread);
+     * ```
+     */
+    registerSingleton(): this;
+    /**
+     * Get the registered singleton Chat instance.
+     * Throws if no singleton has been registered.
+     */
+    static getSingleton(): Chat;
+    /**
+     * Check if a singleton has been registered.
+     */
+    static hasSingleton(): boolean;
     private adapters;
     private _stateAdapter;
     private userName;
@@ -1171,6 +1373,26 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
      * Get an adapter by name with type safety.
      */
     getAdapter<K extends keyof TAdapters>(name: K): TAdapters[K];
+    /**
+     * Get a JSON.parse reviver function that automatically deserializes
+     * chat:Thread and chat:Message objects.
+     *
+     * Use this when parsing JSON that contains serialized Thread or Message objects
+     * (e.g., from workflow engine payloads).
+     *
+     * @returns A reviver function for JSON.parse
+     *
+     * @example
+     * ```typescript
+     * // Parse workflow payload with automatic deserialization
+     * const data = JSON.parse(payload, chat.reviver());
+     *
+     * // data.thread is now a ThreadImpl instance
+     * // data.message is now a Message object with Date fields restored
+     * await data.thread.post("Hello from workflow!");
+     * ```
+     */
+    reviver(): (key: string, value: unknown) => unknown;
     /**
      * Process an incoming message from an adapter.
      * Handles waitUntil registration and error catching internally.
@@ -1257,27 +1479,55 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
     private runHandlers;
 }
 
-interface ThreadImplConfig {
+/**
+ * Serialized thread data for passing to external systems (e.g., workflow engines).
+ */
+interface SerializedThread {
+    _type: "chat:Thread";
+    id: string;
+    channelId: string;
+    isDM: boolean;
+    adapterName: string;
+}
+/**
+ * Config for creating a ThreadImpl with explicit adapter/state instances.
+ */
+interface ThreadImplConfigWithAdapter {
     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;
 }
+/**
+ * Config for creating a ThreadImpl with lazy adapter resolution.
+ * The adapter will be looked up from the Chat singleton on first access.
+ */
+interface ThreadImplConfigLazy {
+    id: string;
+    adapterName: string;
+    channelId: string;
+    initialMessage?: Message;
+    isSubscribedContext?: boolean;
+    isDM?: boolean;
+    currentMessage?: Message;
+    streamingUpdateIntervalMs?: number;
+}
+type ThreadImplConfig = ThreadImplConfigWithAdapter | ThreadImplConfigLazy;
 declare class ThreadImpl<TState = Record<string, unknown>> implements Thread<TState> {
     readonly id: string;
-    readonly adapter: Adapter;
     readonly channelId: string;
     readonly isDM: boolean;
-    private _stateAdapter;
+    /** Direct adapter instance (if provided) */
+    private _adapter?;
+    /** Adapter name for lazy resolution */
+    private _adapterName?;
+    /** Direct state adapter instance (if provided) */
+    private _stateAdapterInstance?;
     private _recentMessages;
     private _isSubscribedContext;
     /** Current message context for streaming - provides userId/teamId */
@@ -1285,6 +1535,16 @@ declare class ThreadImpl<TState = Record<string, unknown>> implements Thread<TSt
     /** Update interval for fallback streaming */
     private _streamingUpdateIntervalMs;
     constructor(config: ThreadImplConfig);
+    /**
+     * Get the adapter for this thread.
+     * If created with lazy config, resolves from Chat singleton on first access.
+     */
+    get adapter(): Adapter;
+    /**
+     * Get the state adapter for this thread.
+     * If created with lazy config, resolves from Chat singleton on first access.
+     */
+    private get _stateAdapter();
     get recentMessages(): Message[];
     set recentMessages(messages: Message[]);
     /**
@@ -1304,6 +1564,7 @@ declare class ThreadImpl<TState = Record<string, unknown>> implements Thread<TSt
     subscribe(): Promise<void>;
     unsubscribe(): Promise<void>;
     post(message: string | PostableMessage | CardJSXElement): Promise<SentMessage>;
+    postEphemeral(user: string | Author, message: AdapterPostableMessage | CardJSXElement, options: PostEphemeralOptions): Promise<EphemeralMessage | null>;
     /**
      * Handle streaming from an AsyncIterable.
      * Uses adapter's native streaming if available, otherwise falls back to post+edit.
@@ -1319,6 +1580,46 @@ declare class ThreadImpl<TState = Record<string, unknown>> implements Thread<TSt
     private fallbackStream;
     refresh(): Promise<void>;
     mentionUser(userId: string): string;
+    /**
+     * Serialize the thread to a plain JSON object.
+     * Use this to pass thread data to external systems like workflow engines.
+     *
+     * @example
+     * ```typescript
+     * // Pass to a workflow
+     * await workflow.start("my-workflow", {
+     *   thread: thread.toJSON(),
+     *   message: serializeMessage(message),
+     * });
+     * ```
+     */
+    toJSON(): SerializedThread;
+    /**
+     * Reconstruct a Thread from serialized JSON data.
+     *
+     * Reconstructs a ThreadImpl from serialized data.
+     * Uses lazy resolution from Chat.getSingleton() for adapter and state.
+     *
+     * @param json - Serialized thread data
+     * @requires Call `chat.registerSingleton()` before deserializing threads
+     *
+     * @example
+     * ```typescript
+     * const thread = ThreadImpl.fromJSON(serializedThread);
+     * ```
+     */
+    static fromJSON<TState = Record<string, unknown>>(json: SerializedThread): ThreadImpl<TState>;
+    /**
+     * Serialize a ThreadImpl instance for @workflow/serde.
+     * This static method is automatically called by workflow serialization.
+     */
+    static [WORKFLOW_SERIALIZE](instance: ThreadImpl): SerializedThread;
+    /**
+     * Deserialize a ThreadImpl from @workflow/serde.
+     * Uses lazy adapter resolution from Chat.getSingleton().
+     * Requires chat.registerSingleton() to have been called.
+     */
+    static [WORKFLOW_DESERIALIZE](data: SerializedThread): ThreadImpl;
     private createSentMessage;
 }
 
@@ -1713,4 +2014,4 @@ declare const Select: typeof Select$1;
 declare const SelectOption: typeof SelectOption$1;
 declare const TextInput: typeof TextInput$1;
 
-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, Modal, type ModalCloseEvent, type ModalCloseHandler, type ModalCloseResponse, ModalElement, type ModalErrorsResponse, type ModalPushResponse, type ModalResponse, type ModalSubmitEvent, type ModalSubmitHandler, type ModalUpdateResponse, NotImplementedError, type PostableAst, type PostableCard, type PostableMarkdown, type PostableMessage, type PostableRaw, RateLimitError, type RawMessage, type ReactionEvent, type ReactionHandler, Section, Select, SelectOption, type SentMessage, type StateAdapter, type StreamOptions, type SubscribedMessageHandler, THREAD_STATE_TTL_MS, TextInput, type Thread, ThreadImpl, type ThreadInfo, type WebhookOptions, type WellKnownEmoji, blockquote, codeBlock, convertEmojiPlaceholders, createEmoji, defaultEmojiResolver, emoji, emphasis, fromReactElement, fromReactModalElement, getEmoji, getNodeChildren, getNodeValue, inlineCode, isBlockquoteNode, isCardElement, isCodeNode, isDeleteNode, isEmphasisNode, isInlineCodeNode, isJSX, isLinkNode, isListItemNode, isListNode, isModalElement, isParagraphNode, isStrongNode, isTextNode, link, markdownToPlainText, paragraph, parseMarkdown, root, strikethrough, stringifyMarkdown, strong, text, toCardElement, toModalElement, 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 EphemeralMessage, 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, Message, type MessageData, type MessageHandler, type MessageMetadata, Modal, type ModalCloseEvent, type ModalCloseHandler, type ModalCloseResponse, ModalElement, type ModalErrorsResponse, type ModalPushResponse, type ModalResponse, type ModalSubmitEvent, type ModalSubmitHandler, type ModalUpdateResponse, NotImplementedError, type PostEphemeralOptions, type PostableAst, type PostableCard, type PostableMarkdown, type PostableMessage, type PostableRaw, RateLimitError, type RawMessage, type ReactionEvent, type ReactionHandler, Section, Select, SelectOption, type SentMessage, type SerializedMessage, type SerializedThread, type StateAdapter, type StreamOptions, type SubscribedMessageHandler, THREAD_STATE_TTL_MS, TextInput, type Thread, ThreadImpl, type ThreadInfo, type WebhookOptions, type WellKnownEmoji, blockquote, codeBlock, convertEmojiPlaceholders, createEmoji, defaultEmojiResolver, emoji, emphasis, fromReactElement, fromReactModalElement, getEmoji, getNodeChildren, getNodeValue, inlineCode, isBlockquoteNode, isCardElement, isCodeNode, isDeleteNode, isEmphasisNode, isInlineCodeNode, isJSX, isLinkNode, isListItemNode, isListNode, isModalElement, isParagraphNode, isStrongNode, isTextNode, link, markdownToPlainText, paragraph, parseMarkdown, root, strikethrough, stringifyMarkdown, strong, text, toCardElement, toModalElement, toPlainText, walkAst };