chat 3.0.0 → 4.0.0

package/dist/index.d.ts

@@ -0,0 +1,1312 @@
+import { C as CardElement, a as CardJSXElement, 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 } from './jsx-runtime-D7zHSnXe.js';
+export { g as ActionsElement, h as ButtonElement, j as ButtonOptions, k as ButtonStyle, l as CardOptions, m as DividerElement, n as FieldElement, o as FieldsElement, p as ImageElement, q as SectionElement, r as TextElement, s as TextStyle } from './jsx-runtime-D7zHSnXe.js';
+import { Root, Content, Blockquote, Code, Emphasis, InlineCode, Link, Paragraph, Delete, Strong, Text } from 'mdast';
+export { Blockquote, Code, Content, Delete, Emphasis, InlineCode, Link, List, ListItem, Paragraph, Root, Strong, Text } from 'mdast';
+
+/**
+ * Core types for chat-sdk
+ */
+
+type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    /** Create a sub-logger with a prefix */
+    child(prefix: string): Logger;
+}
+/**
+ * Default console logger implementation.
+ */
+declare class ConsoleLogger implements Logger {
+    private level;
+    private prefix;
+    constructor(level?: LogLevel, prefix?: string);
+    private shouldLog;
+    child(prefix: string): Logger;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Chat configuration with type-safe adapter inference.
+ * @template TAdapters - Record of adapter name to adapter instance
+ */
+interface ChatConfig<TAdapters extends Record<string, Adapter> = Record<string, Adapter>> {
+    /** Default bot username across all adapters */
+    userName: string;
+    /** Map of adapter name to adapter instance */
+    adapters: TAdapters;
+    /** State adapter for subscriptions and locking */
+    state: StateAdapter;
+    /**
+     * Logger instance or log level. Defaults to "info".
+     * Pass "silent" to disable all logging.
+     */
+    logger?: Logger | LogLevel;
+}
+/**
+ * Options for webhook handling.
+ */
+interface WebhookOptions {
+    /**
+     * Function to run message handling in the background.
+     * Use this to ensure fast webhook responses while processing continues.
+     *
+     * @example
+     * // Next.js App Router
+     * import { after } from "next/server";
+     * chat.webhooks.slack(request, { waitUntil: (p) => after(() => p) });
+     *
+     * @example
+     * // Vercel Functions
+     * import { waitUntil } from "@vercel/functions";
+     * chat.webhooks.slack(request, { waitUntil });
+     */
+    waitUntil?: (task: Promise<unknown>) => void;
+}
+/**
+ * Adapter interface with generics for platform-specific types.
+ * @template TThreadId - Platform-specific thread ID data type
+ * @template TRawMessage - Platform-specific raw message type
+ */
+interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
+    /** Unique name for this adapter (e.g., "slack", "teams") */
+    readonly name: string;
+    /** Bot username (can override global userName) */
+    readonly userName: string;
+    /** Bot user ID for platforms that use IDs in mentions (e.g., Slack's <@U123>) */
+    readonly botUserId?: string;
+    /** Called when Chat instance is created (internal use) */
+    initialize(chat: ChatInstance): Promise<void>;
+    /** 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>>;
+    /** Edit an existing message */
+    editMessage(threadId: string, messageId: string, message: PostableMessage): Promise<RawMessage<TRawMessage>>;
+    /** Delete a message */
+    deleteMessage(threadId: string, messageId: string): Promise<void>;
+    /** Add a reaction to a message */
+    addReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
+    /** Remove a reaction from a message */
+    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 thread metadata */
+    fetchThread(threadId: string): Promise<ThreadInfo>;
+    /** Encode platform-specific data into a thread ID string */
+    encodeThreadId(platformData: TThreadId): string;
+    /** Decode thread ID string back to platform-specific data */
+    decodeThreadId(threadId: string): TThreadId;
+    /** Parse platform message format to normalized format */
+    parseMessage(raw: TRawMessage): Message<TRawMessage>;
+    /** Render formatted content to platform-specific string */
+    renderFormatted(content: FormattedContent): string;
+    /**
+     * Optional hook called when a thread is subscribed to.
+     * Adapters can use this to set up platform-specific subscriptions
+     * (e.g., Google Chat Workspace Events).
+     */
+    onThreadSubscribe?(threadId: string): Promise<void>;
+    /**
+     * Open a direct message conversation with a user.
+     *
+     * @param userId - The platform-specific user ID
+     * @returns The thread ID for the DM conversation
+     *
+     * @example
+     * ```typescript
+     * const dmThreadId = await adapter.openDM("U123456");
+     * await adapter.postMessage(dmThreadId, "Hello!");
+     * ```
+     */
+    openDM?(userId: string): Promise<string>;
+    /**
+     * Check if a thread is a direct message conversation.
+     *
+     * @param threadId - The thread ID to check
+     * @returns True if the thread is a DM, false otherwise
+     */
+    isDM?(threadId: string): boolean;
+}
+/** Internal interface for Chat instance passed to adapters */
+interface ChatInstance {
+    /**
+     * Process an incoming message from an adapter.
+     * Handles waitUntil registration and error catching internally.
+     *
+     * @param adapter - The adapter that received the message
+     * @param threadId - The thread ID
+     * @param message - Either a parsed message, or a factory function for lazy async parsing
+     * @param options - Webhook options including waitUntil
+     */
+    processMessage(adapter: Adapter, threadId: string, message: Message | (() => Promise<Message>), options?: WebhookOptions): void;
+    /**
+     * @deprecated Use processMessage instead. This method is for internal use.
+     */
+    handleIncomingMessage(adapter: Adapter, threadId: string, message: Message): Promise<void>;
+    /**
+     * Process an incoming reaction event from an adapter.
+     * Handles waitUntil registration and error catching internally.
+     *
+     * @param event - The reaction event (without adapter field, will be added)
+     * @param options - Webhook options including waitUntil
+     */
+    processReaction(event: Omit<ReactionEvent, "adapter" | "thread"> & {
+        adapter?: Adapter;
+    }, options?: WebhookOptions): void;
+    /**
+     * Process an incoming action event (button click) from an adapter.
+     * Handles waitUntil registration and error catching internally.
+     *
+     * @param event - The action event (without thread field, will be added)
+     * @param options - Webhook options including waitUntil
+     */
+    processAction(event: Omit<ActionEvent, "thread"> & {
+        adapter: Adapter;
+    }, options?: WebhookOptions): void;
+    getState(): StateAdapter;
+    getUserName(): string;
+    /** Get the configured logger, optionally with a child prefix */
+    getLogger(prefix?: string): Logger;
+}
+interface StateAdapter {
+    /** Connect to the state backend */
+    connect(): Promise<void>;
+    /** Disconnect from the state backend */
+    disconnect(): Promise<void>;
+    /** Subscribe to a thread (persists across restarts) */
+    subscribe(threadId: string): Promise<void>;
+    /** Unsubscribe from a thread */
+    unsubscribe(threadId: string): Promise<void>;
+    /** Check if subscribed to a thread */
+    isSubscribed(threadId: string): Promise<boolean>;
+    /** List all subscriptions, optionally filtered by adapter */
+    listSubscriptions(adapterName?: string): AsyncIterable<string>;
+    /** Acquire a lock on a thread (returns null if already locked) */
+    acquireLock(threadId: string, ttlMs: number): Promise<Lock | null>;
+    /** Release a lock */
+    releaseLock(lock: Lock): Promise<void>;
+    /** Extend a lock's TTL */
+    extendLock(lock: Lock, ttlMs: number): Promise<boolean>;
+    /** Get a cached value by key */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /** Set a cached value with optional TTL in milliseconds */
+    set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void>;
+    /** Delete a cached value */
+    delete(key: string): Promise<void>;
+}
+interface Lock {
+    threadId: string;
+    token: string;
+    expiresAt: number;
+}
+interface Thread<TRawMessage = unknown> {
+    /** Unique thread ID (format: "adapter:channel:thread") */
+    readonly id: string;
+    /** The adapter this thread belongs to */
+    readonly adapter: Adapter;
+    /** Channel/conversation ID */
+    readonly channelId: string;
+    /** Whether this is a direct message conversation */
+    readonly isDM: boolean;
+    /** Recently fetched messages (cached) */
+    recentMessages: Message<TRawMessage>[];
+    /** Async iterator for all messages in the thread */
+    allMessages: AsyncIterable<Message<TRawMessage>>;
+    /**
+     * Check if this thread is currently subscribed.
+     *
+     * In subscribed message handlers, this is optimized to return true immediately
+     * without a state lookup, since we already know we're in a subscribed context.
+     *
+     * @returns Promise resolving to true if subscribed, false otherwise
+     */
+    isSubscribed(): Promise<boolean>;
+    /**
+     * Subscribe to future messages in this thread.
+     *
+     * Once subscribed, all messages in this thread will trigger `onSubscribedMessage` handlers.
+     * The initial message that triggered subscription will NOT fire the handler.
+     *
+     * @example
+     * ```typescript
+     * chat.onNewMention(async (thread, message) => {
+     *   await thread.subscribe();  // Subscribe to follow-up messages
+     *   await thread.post("I'm now watching this thread!");
+     * });
+     * ```
+     */
+    subscribe(): Promise<void>;
+    /**
+     * Unsubscribe from this thread.
+     *
+     * Future messages will no longer trigger `onSubscribedMessage` handlers.
+     */
+    unsubscribe(): Promise<void>;
+    /**
+     * Post a message to this thread.
+     *
+     * @param message - String, PostableMessage, or JSX Card element to send
+     * @returns A SentMessage with methods to edit, delete, or add reactions
+     *
+     * @example
+     * ```typescript
+     * // Simple string
+     * await thread.post("Hello!");
+     *
+     * // Markdown
+     * await thread.post({ markdown: "**Bold** and _italic_" });
+     *
+     * // With emoji
+     * await thread.post(`${emoji.thumbs_up} Great job!`);
+     *
+     * // JSX Card (with @jsxImportSource chat-sdk)
+     * await thread.post(
+     *   <Card title="Welcome!">
+     *     <Text>Hello world</Text>
+     *   </Card>
+     * );
+     * ```
+     */
+    post(message: string | PostableMessage | CardJSXElement): Promise<SentMessage<TRawMessage>>;
+    /**
+     * Show typing indicator in the thread.
+     *
+     * Some platforms support persistent typing indicators, others just send once.
+     */
+    startTyping(): Promise<void>;
+    /**
+     * Refresh `recentMessages` from the API.
+     *
+     * Fetches the latest 50 messages and updates `recentMessages`.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Get a platform-specific mention string for a user.
+     * Use this to @-mention a user in a message.
+     * @example
+     * await thread.post(`Hey ${thread.mentionUser(userId)}, check this out!`);
+     */
+    mentionUser(userId: string): string;
+}
+interface ThreadInfo {
+    id: string;
+    channelId: string;
+    channelName?: string;
+    /** Whether this is a direct message conversation */
+    isDM?: boolean;
+    /** Platform-specific metadata */
+    metadata: Record<string, unknown>;
+}
+interface FetchOptions {
+    /** Maximum number of messages to fetch */
+    limit?: number;
+    /** Fetch messages before this message ID */
+    before?: string;
+    /** Fetch messages after this message ID */
+    after?: string;
+}
+/**
+ * Formatted content using mdast AST.
+ * 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;
+    threadId: string;
+    raw: TRawMessage;
+}
+interface Author {
+    /** Unique user ID */
+    userId: string;
+    /** Username/handle for @-mentions */
+    userName: string;
+    /** Display name */
+    fullName: string;
+    /** Whether the author is a bot */
+    isBot: boolean | "unknown";
+    /** Whether the author is this bot */
+    isMe: boolean;
+}
+interface MessageMetadata {
+    /** When the message was sent */
+    dateSent: Date;
+    /** Whether the message has been edited */
+    edited: boolean;
+    /** When the message was last edited */
+    editedAt?: Date;
+}
+interface SentMessage<TRawMessage = unknown> extends Message<TRawMessage> {
+    /** Edit this message with text, a PostableMessage, or a JSX Card element */
+    edit(newContent: string | PostableMessage | CardJSXElement): Promise<SentMessage<TRawMessage>>;
+    /** Delete this message */
+    delete(): Promise<void>;
+    /** Add a reaction to this message */
+    addReaction(emoji: EmojiValue | string): Promise<void>;
+    /** Remove a reaction from this message */
+    removeReaction(emoji: EmojiValue | string): Promise<void>;
+}
+/**
+ * A message that can be posted to a thread.
+ *
+ * - `string` - Raw text, passed through as-is to the platform
+ * - `{ raw: string }` - Explicit raw text, passed through as-is
+ * - `{ markdown: string }` - Markdown text, converted to platform format
+ * - `{ ast: Root }` - mdast AST, converted to platform format
+ * - `{ card: CardElement }` - Rich card with buttons (Block Kit / Adaptive Cards / GChat Cards)
+ * - `CardElement` - Direct card element
+ */
+type PostableMessage = string | PostableRaw | PostableMarkdown | PostableAst | PostableCard | CardElement;
+interface PostableRaw {
+    /** Raw text passed through as-is to the platform */
+    raw: string;
+    /** File/image attachments */
+    attachments?: Attachment[];
+    /** Files to upload */
+    files?: FileUpload[];
+}
+interface PostableMarkdown {
+    /** Markdown text, converted to platform format */
+    markdown: string;
+    /** File/image attachments */
+    attachments?: Attachment[];
+    /** Files to upload */
+    files?: FileUpload[];
+}
+interface PostableAst {
+    /** mdast AST, converted to platform format */
+    ast: Root;
+    /** File/image attachments */
+    attachments?: Attachment[];
+    /** Files to upload */
+    files?: FileUpload[];
+}
+interface PostableCard {
+    /** Rich card element */
+    card: CardElement;
+    /** Fallback text for platforms/clients that can't render cards */
+    fallbackText?: string;
+    /** Files to upload */
+    files?: FileUpload[];
+}
+interface Attachment {
+    /** Type of attachment */
+    type: "image" | "file" | "video" | "audio";
+    /** URL to the file (for linking/downloading) */
+    url?: string;
+    /** Binary data (for uploading or if already fetched) */
+    data?: Buffer | Blob;
+    /** Filename */
+    name?: string;
+    /** MIME type */
+    mimeType?: string;
+    /** File size in bytes */
+    size?: number;
+    /** Image/video width (if applicable) */
+    width?: number;
+    /** Image/video height (if applicable) */
+    height?: number;
+    /**
+     * Fetch the attachment data.
+     * For platforms that require authentication (like Slack private URLs),
+     * this method handles the auth automatically.
+     */
+    fetchData?: () => Promise<Buffer>;
+}
+/**
+ * File to upload with a message.
+ */
+interface FileUpload {
+    /** Binary data */
+    data: Buffer | Blob | ArrayBuffer;
+    /** Filename */
+    filename: string;
+    /** MIME type (optional, will be inferred from filename if not provided) */
+    mimeType?: string;
+}
+/**
+ * Handler for new @-mentions of the bot.
+ *
+ * **Important**: This handler is ONLY called for mentions in **unsubscribed** threads.
+ * Once a thread is subscribed (via `thread.subscribe()`), subsequent messages
+ * including @-mentions go to `onSubscribedMessage` handlers instead.
+ *
+ * To detect mentions in subscribed threads, check `message.isMention`:
+ *
+ * @example
+ * ```typescript
+ * // Handle new mentions (unsubscribed threads only)
+ * chat.onNewMention(async (thread, message) => {
+ *   await thread.subscribe();  // Subscribe to follow-up messages
+ *   await thread.post("Hello! I'll be watching this thread.");
+ * });
+ *
+ * // Handle all messages in subscribed threads
+ * chat.onSubscribedMessage(async (thread, message) => {
+ *   if (message.isMention) {
+ *     // User @-mentioned us in a thread we're already watching
+ *     await thread.post("You mentioned me again!");
+ *   }
+ * });
+ * ```
+ */
+type MentionHandler = (thread: Thread, 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>;
+/**
+ * Handler for messages in subscribed threads.
+ *
+ * Called for all messages in threads that have been subscribed via `thread.subscribe()`.
+ * This includes:
+ * - Follow-up messages from users
+ * - Messages that @-mention the bot (check `message.isMention`)
+ *
+ * Does NOT fire for:
+ * - The message that triggered the subscription (e.g., the initial @mention)
+ * - Messages sent by the bot itself
+ *
+ * @example
+ * ```typescript
+ * chat.onSubscribedMessage(async (thread, message) => {
+ *   // Handle all follow-up messages
+ *   if (message.isMention) {
+ *     // User @-mentioned us in a subscribed thread
+ *   }
+ *   await thread.post(`Got your message: ${message.text}`);
+ * });
+ * ```
+ */
+type SubscribedMessageHandler = (thread: Thread, 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.
+ */
+type WellKnownEmoji = "thumbs_up" | "thumbs_down" | "clap" | "wave" | "pray" | "muscle" | "ok_hand" | "point_up" | "point_down" | "point_left" | "point_right" | "raised_hands" | "shrug" | "facepalm" | "heart" | "smile" | "laugh" | "thinking" | "sad" | "cry" | "angry" | "love_eyes" | "cool" | "wink" | "surprised" | "worried" | "confused" | "neutral" | "sleeping" | "sick" | "mind_blown" | "relieved" | "grimace" | "rolling_eyes" | "hug" | "zany" | "check" | "x" | "question" | "exclamation" | "warning" | "stop" | "info" | "100" | "fire" | "star" | "sparkles" | "lightning" | "boom" | "eyes" | "green_circle" | "yellow_circle" | "red_circle" | "blue_circle" | "white_circle" | "black_circle" | "rocket" | "party" | "confetti" | "balloon" | "gift" | "trophy" | "medal" | "lightbulb" | "gear" | "wrench" | "hammer" | "bug" | "link" | "lock" | "unlock" | "key" | "pin" | "memo" | "clipboard" | "calendar" | "clock" | "hourglass" | "bell" | "megaphone" | "speech_bubble" | "email" | "inbox" | "outbox" | "package" | "folder" | "file" | "chart_up" | "chart_down" | "coffee" | "pizza" | "beer" | "arrow_up" | "arrow_down" | "arrow_left" | "arrow_right" | "refresh" | "sun" | "cloud" | "rain" | "snow" | "rainbow";
+/**
+ * Platform-specific emoji formats for a single emoji.
+ */
+interface EmojiFormats {
+    /** Slack emoji name (without colons), e.g., "+1", "heart" */
+    slack: string | string[];
+    /** Google Chat unicode emoji, e.g., "👍", "❤️" */
+    gchat: string | string[];
+}
+/**
+ * Emoji map type - can be extended by users to add custom emoji.
+ *
+ * @example
+ * ```typescript
+ * // Extend with custom emoji
+ * declare module "chat" {
+ *   interface CustomEmojiMap {
+ *     "custom_emoji": EmojiFormats;
+ *   }
+ * }
+ *
+ * const myEmojiMap: EmojiMapConfig = {
+ *   custom_emoji: { slack: "custom", gchat: "🎯" },
+ * };
+ * ```
+ */
+interface CustomEmojiMap {
+}
+/**
+ * Full emoji type including well-known and custom emoji.
+ */
+type Emoji = WellKnownEmoji | keyof CustomEmojiMap;
+/**
+ * Configuration for emoji mapping.
+ */
+type EmojiMapConfig = Partial<Record<Emoji, EmojiFormats>>;
+/**
+ * Immutable emoji value object with object identity.
+ *
+ * These objects are singletons - the same emoji name always returns
+ * the same frozen object instance, enabling `===` comparison.
+ *
+ * @example
+ * ```typescript
+ * // Object identity comparison works
+ * if (event.emoji === emoji.thumbs_up) {
+ *   console.log("User gave a thumbs up!");
+ * }
+ *
+ * // Works in template strings via toString()
+ * await thread.post(`${emoji.thumbs_up} Great job!`);
+ * ```
+ */
+interface EmojiValue {
+    /** The normalized emoji name (e.g., "thumbs_up") */
+    readonly name: string;
+    /** Returns the placeholder string for message formatting */
+    toString(): string;
+    /** Returns the placeholder string (for JSON.stringify) */
+    toJSON(): string;
+}
+/**
+ * Reaction event fired when a user adds or removes a reaction.
+ */
+interface ReactionEvent<TRawMessage = unknown> {
+    /** The normalized emoji as an EmojiValue singleton (enables `===` comparison) */
+    emoji: EmojiValue;
+    /** The raw platform-specific emoji (e.g., "+1" for Slack, "👍" for GChat) */
+    rawEmoji: string;
+    /** Whether the reaction was added (true) or removed (false) */
+    added: boolean;
+    /** The user who added/removed the reaction */
+    user: Author;
+    /** The message that was reacted to (if available) */
+    message?: Message<TRawMessage>;
+    /** The message ID that was reacted to */
+    messageId: string;
+    /** The thread ID */
+    threadId: string;
+    /**
+     * The thread where the reaction occurred.
+     * Use this to post replies or check subscription status.
+     *
+     * @example
+     * ```typescript
+     * chat.onReaction([emoji.thumbs_up], async (event) => {
+     *   await event.thread.post(`Thanks for the ${event.emoji}!`);
+     * });
+     * ```
+     */
+    thread: Thread<TRawMessage>;
+    /** The adapter that received the event */
+    adapter: Adapter;
+    /** Platform-specific raw event data */
+    raw: unknown;
+}
+/**
+ * Handler for reaction events.
+ *
+ * @example
+ * ```typescript
+ * // Handle specific emoji
+ * chat.onReaction(["thumbs_up", "heart"], async (event) => {
+ *   console.log(`${event.user.userName} ${event.added ? "added" : "removed"} ${event.emoji}`);
+ * });
+ *
+ * // Handle all reactions
+ * chat.onReaction(async (event) => {
+ *   // ...
+ * });
+ * ```
+ */
+type ReactionHandler = (event: ReactionEvent) => Promise<void>;
+/**
+ * Action event fired when a user clicks a button in a card.
+ *
+ * @example
+ * ```typescript
+ * chat.onAction("approve", async (event) => {
+ *   await event.thread.post(`Order ${event.value} approved by ${event.user.userName}`);
+ * });
+ * ```
+ */
+interface ActionEvent<TRawMessage = unknown> {
+    /** The action ID from the button (matches Button's `id` prop) */
+    actionId: string;
+    /** Optional value/payload from the button */
+    value?: string;
+    /** User who clicked the button */
+    user: Author;
+    /** The thread where the action occurred */
+    thread: Thread<TRawMessage>;
+    /** The message ID containing the card */
+    messageId: string;
+    /** The thread ID */
+    threadId: string;
+    /** The adapter that received the event */
+    adapter: Adapter;
+    /** Platform-specific raw event data */
+    raw: unknown;
+}
+/**
+ * Handler for action events (button clicks in cards).
+ *
+ * @example
+ * ```typescript
+ * // Handle specific action
+ * chat.onAction("approve", async (event) => {
+ *   await event.thread.post("Approved!");
+ * });
+ *
+ * // Handle multiple actions
+ * chat.onAction(["approve", "reject"], async (event) => {
+ *   if (event.actionId === "approve") {
+ *     // ...
+ *   }
+ * });
+ *
+ * // Handle all actions (catch-all)
+ * chat.onAction(async (event) => {
+ *   console.log(`Action: ${event.actionId}`);
+ * });
+ * ```
+ */
+type ActionHandler = (event: ActionEvent) => Promise<void>;
+declare class ChatError extends Error {
+    readonly code: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: string, cause?: unknown | undefined);
+}
+declare class RateLimitError extends ChatError {
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, retryAfterMs?: number | undefined, cause?: unknown);
+}
+declare class LockError extends ChatError {
+    constructor(message: string, cause?: unknown);
+}
+declare class NotImplementedError extends ChatError {
+    readonly feature?: string | undefined;
+    constructor(message: string, feature?: string | undefined, cause?: unknown);
+}
+
+/** Filter can be EmojiValue objects, emoji names, or raw emoji formats */
+type EmojiFilter = EmojiValue | string;
+/**
+ * Type-safe webhook handler that is available for each adapter.
+ */
+type WebhookHandler = (request: Request, options?: WebhookOptions) => Promise<Response>;
+/**
+ * Creates a type-safe webhooks object based on the adapter names.
+ */
+type Webhooks<TAdapters extends Record<string, Adapter>> = {
+    [K in keyof TAdapters]: WebhookHandler;
+};
+/**
+ * Main Chat class with type-safe adapter inference.
+ *
+ * @example
+ * const chat = new Chat({
+ *   userName: "mybot",
+ *   adapters: {
+ *     slack: createSlackAdapter({ ... }),
+ *     teams: createTeamsAdapter({ ... }),
+ *   },
+ *   state: createMemoryState(),
+ * });
+ *
+ * // Type-safe: only 'slack' and 'teams' are valid
+ * chat.webhooks.slack(request, { waitUntil });
+ */
+declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Adapter>> implements ChatInstance {
+    private adapters;
+    private state;
+    private userName;
+    private logger;
+    private mentionHandlers;
+    private messagePatterns;
+    private subscribedMessageHandlers;
+    private reactionHandlers;
+    private actionHandlers;
+    /** Initialization state */
+    private initPromise;
+    private initialized;
+    /**
+     * Type-safe webhook handlers keyed by adapter name.
+     * @example
+     * chat.webhooks.slack(request, { backgroundTask: waitUntil });
+     */
+    readonly webhooks: Webhooks<TAdapters>;
+    constructor(config: ChatConfig<TAdapters>);
+    /**
+     * Handle a webhook request for a specific adapter.
+     * Automatically initializes adapters on first call.
+     */
+    private handleWebhook;
+    /**
+     * Ensure the chat instance is initialized.
+     * This is called automatically before handling webhooks.
+     */
+    private ensureInitialized;
+    private doInitialize;
+    /**
+     * Gracefully shut down the chat instance.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Register a handler for new @-mentions of the bot.
+     *
+     * **Important**: This handler is ONLY called for mentions in **unsubscribed** threads.
+     * Once a thread is subscribed (via `thread.subscribe()`), subsequent messages
+     * including @-mentions go to `onSubscribedMessage` handlers instead.
+     *
+     * To detect mentions in subscribed threads, check `message.isMention`:
+     *
+     * @example
+     * ```typescript
+     * // Handle new mentions (unsubscribed threads only)
+     * chat.onNewMention(async (thread, message) => {
+     *   await thread.subscribe();  // Subscribe to follow-up messages
+     *   await thread.post("Hello! I'll be watching this thread.");
+     * });
+     *
+     * // Handle all messages in subscribed threads
+     * chat.onSubscribedMessage(async (thread, message) => {
+     *   if (message.isMention) {
+     *     // User @-mentioned us in a thread we're already watching
+     *     await thread.post("You mentioned me again!");
+     *   }
+     * });
+     * ```
+     */
+    onNewMention(handler: MentionHandler): void;
+    /**
+     * Register a handler for messages matching a regex pattern.
+     *
+     * @param pattern - Regular expression to match against message text
+     * @param handler - Handler called when pattern matches
+     *
+     * @example
+     * ```typescript
+     * // Match messages starting with "!help"
+     * chat.onNewMessage(/^!help/, async (thread, message) => {
+     *   await thread.post("Available commands: !help, !status, !ping");
+     * });
+     * ```
+     */
+    onNewMessage(pattern: RegExp, handler: MessageHandler): void;
+    /**
+     * Register a handler for messages in subscribed threads.
+     *
+     * Called for all messages in threads that have been subscribed via `thread.subscribe()`.
+     * This includes:
+     * - Follow-up messages from users
+     * - Messages that @-mention the bot (check `message.isMention`)
+     *
+     * Does NOT fire for:
+     * - The message that triggered the subscription (e.g., the initial @mention)
+     * - Messages sent by the bot itself
+     *
+     * @example
+     * ```typescript
+     * chat.onSubscribedMessage(async (thread, message) => {
+     *   // Handle all follow-up messages
+     *   if (message.isMention) {
+     *     // User @-mentioned us in a subscribed thread
+     *   }
+     *   await thread.post(`Got your message: ${message.text}`);
+     * });
+     * ```
+     */
+    onSubscribedMessage(handler: SubscribedMessageHandler): void;
+    /**
+     * Register a handler for reaction events.
+     *
+     * @example
+     * ```typescript
+     * // Handle specific emoji using EmojiValue objects (recommended)
+     * chat.onReaction([emoji.thumbs_up, emoji.heart], async (event) => {
+     *   if (event.emoji === emoji.thumbs_up) {
+     *     console.log("Thumbs up!");
+     *   }
+     * });
+     *
+     * // Handle all reactions
+     * chat.onReaction(async (event) => {
+     *   console.log(`${event.added ? "Added" : "Removed"} ${event.emoji.name}`);
+     * });
+     * ```
+     *
+     * @param emojiOrHandler - Either an array of emoji to filter (EmojiValue or string), or the handler
+     * @param handler - The handler (if emoji filter is provided)
+     */
+    onReaction(handler: ReactionHandler): void;
+    onReaction(emoji: EmojiFilter[], handler: ReactionHandler): void;
+    /**
+     * Register a handler for action events (button clicks in cards).
+     *
+     * @example
+     * ```typescript
+     * // Handle specific action
+     * chat.onAction("approve", async (event) => {
+     *   await event.thread.post("Approved!");
+     * });
+     *
+     * // Handle multiple actions
+     * chat.onAction(["approve", "reject"], async (event) => {
+     *   if (event.actionId === "approve") {
+     *     await event.thread.post("Approved!");
+     *   } else {
+     *     await event.thread.post("Rejected!");
+     *   }
+     * });
+     *
+     * // Handle all actions (catch-all)
+     * chat.onAction(async (event) => {
+     *   console.log(`Action: ${event.actionId}`);
+     * });
+     * ```
+     *
+     * @param actionIdOrHandler - Either an action ID, array of action IDs, or the handler
+     * @param handler - The handler (if action ID filter is provided)
+     */
+    onAction(handler: ActionHandler): void;
+    onAction(actionId: string, handler: ActionHandler): void;
+    onAction(actionIds: string[], handler: ActionHandler): void;
+    /**
+     * Get an adapter by name with type safety.
+     */
+    getAdapter<K extends keyof TAdapters>(name: K): TAdapters[K];
+    /**
+     * Process an incoming message from an adapter.
+     * Handles waitUntil registration and error catching internally.
+     * Adapters should call this instead of handleIncomingMessage directly.
+     */
+    processMessage(adapter: Adapter, threadId: string, messageOrFactory: Message | (() => Promise<Message>), options?: WebhookOptions): void;
+    /**
+     * Process an incoming reaction event from an adapter.
+     * Handles waitUntil registration and error catching internally.
+     */
+    processReaction(event: Omit<ReactionEvent, "adapter" | "thread"> & {
+        adapter?: Adapter;
+    }, options?: WebhookOptions): void;
+    /**
+     * Process an incoming action event (button click) from an adapter.
+     * Handles waitUntil registration and error catching internally.
+     */
+    processAction(event: Omit<ActionEvent, "thread"> & {
+        adapter: Adapter;
+    }, options?: WebhookOptions): void;
+    /**
+     * Handle an action event internally.
+     */
+    private handleActionEvent;
+    /**
+     * Handle a reaction event internally.
+     */
+    private handleReactionEvent;
+    getState(): StateAdapter;
+    getUserName(): string;
+    getLogger(prefix?: string): Logger;
+    /**
+     * Open a direct message conversation with a user.
+     *
+     * Accepts either a user ID string or an Author object (from message.author or event.user).
+     *
+     * The adapter is automatically inferred from the userId format:
+     * - Slack: `U...` (e.g., "U03STHCA1JM")
+     * - Teams: `29:...` (e.g., "29:198PbJuw...")
+     * - Google Chat: `users/...` (e.g., "users/117994873354375860089")
+     *
+     * @param user - Platform-specific user ID string, or an Author object
+     * @returns A Thread that can be used to post messages
+     *
+     * @example
+     * ```ts
+     * // Using user ID directly
+     * const dmThread = await chat.openDM("U123456");
+     * await dmThread.post("Hello via DM!");
+     *
+     * // Using Author object from a message
+     * chat.onSubscribedMessage(async (thread, message) => {
+     *   const dmThread = await chat.openDM(message.author);
+     *   await dmThread.post("Hello via DM!");
+     * });
+     * ```
+     */
+    openDM(user: string | Author): Promise<Thread>;
+    /**
+     * Infer which adapter to use based on the userId format.
+     */
+    private inferAdapterFromUserId;
+    /**
+     * Handle an incoming message from an adapter.
+     * This is called by adapters when they receive a webhook.
+     *
+     * The Chat class handles common concerns centrally:
+     * - Deduplication: Same message may arrive multiple times (e.g., Slack sends
+     *   both `message` and `app_mention` events, GChat sends direct webhook + Pub/Sub)
+     * - Bot filtering: Messages from the bot itself are skipped
+     * - Locking: Only one instance processes a thread at a time
+     */
+    handleIncomingMessage(adapter: Adapter, threadId: string, message: Message): Promise<void>;
+    private createThread;
+    /**
+     * Detect if the bot was mentioned in the message.
+     * All adapters normalize mentions to @name format, so we just check for @username.
+     */
+    private detectMention;
+    private escapeRegex;
+    private runHandlers;
+}
+
+/**
+ * Get or create an immutable singleton EmojiValue.
+ *
+ * Always returns the same frozen object for the same name,
+ * enabling `===` comparison for emoji identity.
+ *
+ * @example
+ * ```typescript
+ * const e1 = getEmoji("thumbs_up");
+ * const e2 = getEmoji("thumbs_up");
+ * console.log(e1 === e2); // true - same object
+ * ```
+ */
+declare function getEmoji(name: string): EmojiValue;
+/**
+ * Default emoji map for well-known emoji.
+ * Maps normalized emoji names to platform-specific formats.
+ */
+declare const DEFAULT_EMOJI_MAP: Record<string, EmojiFormats>;
+/**
+ * Emoji resolver that handles conversion between platform formats and normalized names.
+ */
+declare class EmojiResolver {
+    private emojiMap;
+    private slackToNormalized;
+    private gchatToNormalized;
+    constructor(customMap?: EmojiMapConfig);
+    private buildReverseMaps;
+    /**
+     * Convert a Slack emoji name to normalized EmojiValue.
+     * Returns an EmojiValue for the raw emoji if no mapping exists.
+     */
+    fromSlack(slackEmoji: string): EmojiValue;
+    /**
+     * Convert a Google Chat unicode emoji to normalized EmojiValue.
+     * Returns an EmojiValue for the raw emoji if no mapping exists.
+     */
+    fromGChat(gchatEmoji: string): EmojiValue;
+    /**
+     * Convert a Teams reaction type to normalized EmojiValue.
+     * Teams uses specific names: like, heart, laugh, surprised, sad, angry
+     * Returns an EmojiValue for the raw reaction if no mapping exists.
+     */
+    fromTeams(teamsReaction: string): EmojiValue;
+    /**
+     * Convert a normalized emoji (or EmojiValue) to Slack format.
+     * Returns the first Slack format if multiple exist.
+     */
+    toSlack(emoji: EmojiValue | string): string;
+    /**
+     * Convert a normalized emoji (or EmojiValue) to Google Chat format.
+     * Returns the first GChat format if multiple exist.
+     */
+    toGChat(emoji: EmojiValue | string): string;
+    /**
+     * Check if an emoji (in any format) matches a normalized emoji name or EmojiValue.
+     */
+    matches(rawEmoji: string, normalized: EmojiValue | string): boolean;
+    /**
+     * Add or override emoji mappings.
+     */
+    extend(customMap: EmojiMapConfig): void;
+}
+/**
+ * Default emoji resolver instance.
+ */
+declare const defaultEmojiResolver: EmojiResolver;
+/**
+ * Convert emoji placeholders in text to platform-specific format.
+ *
+ * @example
+ * ```typescript
+ * convertEmojiPlaceholders("Thanks! {{emoji:thumbs_up}}", "slack");
+ * // Returns: "Thanks! :+1:"
+ *
+ * convertEmojiPlaceholders("Thanks! {{emoji:thumbs_up}}", "gchat");
+ * // Returns: "Thanks! 👍"
+ * ```
+ */
+declare function convertEmojiPlaceholders(text: string, platform: "slack" | "gchat" | "teams", resolver?: EmojiResolver): string;
+/** Base emoji object with well-known emoji as EmojiValue singletons */
+type BaseEmojiHelper = {
+    [K in WellKnownEmoji]: EmojiValue;
+} & {
+    /** Create an EmojiValue for a custom emoji name */
+    custom: (name: string) => EmojiValue;
+};
+/** Extended emoji object including custom emoji from module augmentation */
+type ExtendedEmojiHelper = BaseEmojiHelper & {
+    [K in keyof CustomEmojiMap]: EmojiValue;
+};
+/**
+ * Create a type-safe emoji helper with custom emoji.
+ *
+ * Returns immutable singleton EmojiValue objects that support:
+ * - Object identity comparison (`event.emoji === emoji.thumbs_up`)
+ * - Template string interpolation (`${emoji.thumbs_up}` → "{{emoji:thumbs_up}}")
+ *
+ * Custom emoji are automatically registered with the default resolver,
+ * so placeholders will convert correctly in messages.
+ *
+ * @example
+ * ```typescript
+ * // First, extend the CustomEmojiMap type (usually in a .d.ts file)
+ * declare module "chat" {
+ *   interface CustomEmojiMap {
+ *     unicorn: EmojiFormats;
+ *     company_logo: EmojiFormats;
+ *   }
+ * }
+ *
+ * // Then create the emoji helper with your custom emoji
+ * const emoji = createEmoji({
+ *   unicorn: { slack: "unicorn_face", gchat: "🦄" },
+ *   company_logo: { slack: "company", gchat: "🏢" },
+ * });
+ *
+ * // Object identity works for comparisons
+ * if (event.emoji === emoji.unicorn) { ... }
+ *
+ * // Template strings work for messages
+ * await thread.post(`${emoji.unicorn} Magic!`);
+ * // Slack: ":unicorn_face: Magic!"
+ * // GChat: "🦄 Magic!"
+ * ```
+ */
+declare function createEmoji<T extends Record<string, {
+    slack: string | string[];
+    gchat: string | string[];
+}>>(customEmoji?: T): BaseEmojiHelper & {
+    [K in keyof T]: EmojiValue;
+};
+/**
+ * Type-safe emoji helper for embedding emoji in messages.
+ *
+ * @example
+ * ```typescript
+ * import { emoji } from "chat";
+ *
+ * await thread.post(`Great job! ${emoji.thumbs_up} ${emoji.fire}`);
+ * // Slack: "Great job! :+1: :fire:"
+ * // GChat: "Great job! 👍 🔥"
+ * ```
+ *
+ * For custom emoji, use `createEmoji()` with module augmentation:
+ * @example
+ * ```typescript
+ * // types.d.ts
+ * declare module "chat" {
+ *   interface CustomEmojiMap {
+ *     unicorn: EmojiFormats;
+ *   }
+ * }
+ *
+ * // bot.ts
+ * const emoji = createEmoji({ unicorn: { slack: "unicorn", gchat: "🦄" } });
+ * await thread.post(`${emoji.unicorn} Magic!`);
+ * ```
+ */
+declare const emoji: ExtendedEmojiHelper;
+
+/**
+ * Markdown parsing and conversion utilities using unified/remark.
+ */
+
+/**
+ * Parse markdown string into an AST.
+ * Supports GFM (GitHub Flavored Markdown) for strikethrough, tables, etc.
+ */
+declare function parseMarkdown(markdown: string): Root;
+/**
+ * Stringify an AST back to markdown.
+ */
+declare function stringifyMarkdown(ast: Root): string;
+/**
+ * Extract plain text from an AST (strips all formatting).
+ */
+declare function toPlainText(ast: Root): string;
+/**
+ * Extract plain text from a markdown string.
+ */
+declare function markdownToPlainText(markdown: string): string;
+/**
+ * Walk the AST and transform nodes.
+ */
+declare function walkAst<T extends Content | Root>(node: T, visitor: (node: Content) => Content | null): T;
+/**
+ * Create a text node.
+ */
+declare function text(value: string): Text;
+/**
+ * Create a strong (bold) node.
+ */
+declare function strong(children: Content[]): Strong;
+/**
+ * Create an emphasis (italic) node.
+ */
+declare function emphasis(children: Content[]): Emphasis;
+/**
+ * Create a delete (strikethrough) node.
+ */
+declare function strikethrough(children: Content[]): Delete;
+/**
+ * Create an inline code node.
+ */
+declare function inlineCode(value: string): InlineCode;
+/**
+ * Create a code block node.
+ */
+declare function codeBlock(value: string, lang?: string): Code;
+/**
+ * Create a link node.
+ */
+declare function link(url: string, children: Content[], title?: string): Link;
+/**
+ * Create a blockquote node.
+ */
+declare function blockquote(children: Content[]): Blockquote;
+/**
+ * Create a paragraph node.
+ */
+declare function paragraph(children: Content[]): Paragraph;
+/**
+ * Create a root node (top-level AST container).
+ */
+declare function root(children: Content[]): Root;
+/**
+ * Interface for platform-specific format converters.
+ *
+ * The AST (mdast Root) is the canonical representation.
+ * All conversions go through the AST:
+ *
+ *   Platform Format <-> AST <-> Markdown String
+ *
+ * Adapters implement this interface to convert between
+ * their platform-specific format and the standard AST.
+ */
+interface FormatConverter {
+    /**
+     * Render an AST to the platform's native format.
+     * This is the primary method used when sending messages.
+     */
+    fromAst(ast: Root): string;
+    /**
+     * Parse platform's native format into an AST.
+     * This is the primary method used when receiving messages.
+     */
+    toAst(platformText: string): Root;
+    /**
+     * Extract plain text from platform format.
+     * Convenience method - default implementation uses toAst + toPlainText.
+     */
+    extractPlainText(platformText: string): string;
+}
+/**
+ * @deprecated Use FormatConverter instead
+ */
+interface MarkdownConverter extends FormatConverter {
+    fromMarkdown(markdown: string): string;
+    toMarkdown(platformText: string): string;
+    toPlainText(platformText: string): string;
+}
+/**
+ * Base class for format converters with default implementations.
+ */
+declare abstract class BaseFormatConverter implements FormatConverter {
+    abstract fromAst(ast: Root): string;
+    abstract toAst(platformText: string): Root;
+    extractPlainText(platformText: string): string;
+    fromMarkdown(markdown: string): string;
+    toMarkdown(platformText: string): string;
+    /** @deprecated Use extractPlainText instead */
+    toPlainText(platformText: string): string;
+    /**
+     * Convert a PostableMessage to platform format (text only).
+     * - string: passed through as raw text (no conversion)
+     * - { raw: string }: passed through as raw text (no conversion)
+     * - { markdown: string }: converted from markdown to platform format
+     * - { ast: Root }: converted from AST to platform format
+     * - { card: CardElement }: returns fallback text (cards should be handled by adapter)
+     * - CardElement: returns fallback text (cards should be handled by adapter)
+     *
+     * Note: For cards, adapters should check for card content first and render
+     * them using platform-specific card APIs, using this method only for fallback.
+     */
+    renderPostable(message: PostableMessageInput): string;
+    /**
+     * Generate fallback text from a card element.
+     * Override in subclasses for platform-specific formatting.
+     */
+    protected cardToFallbackText(card: CardElement): string;
+    /**
+     * Convert card child element to fallback text.
+     */
+    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;
+declare const Card: typeof Card$1;
+declare const CardText: typeof Text$1;
+declare const Divider: typeof Divider$1;
+declare const Field: typeof Field$1;
+declare const Fields: typeof Fields$1;
+declare const fromReactElement: typeof fromReactElement$1;
+declare const Image: typeof Image$1;
+declare const isCardElement: typeof isCardElement$1;
+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 };