chat 4.21.0 → 4.22.0

package/dist/index.d.ts

@@ -336,6 +336,20 @@ declare class NotImplementedError extends ChatError {
 interface ChatConfig<TAdapters extends Record<string, Adapter> = Record<string, Adapter>> {
     /** Map of adapter name to adapter instance */
     adapters: TAdapters;
+    /**
+     * How to handle messages that arrive while a handler is already
+     * processing on the same thread.
+     *
+     * - `'drop'` (default) — discard the message (throw `LockError`)
+     * - `'queue'` — queue the message; when the current handler finishes,
+     *   process only the latest queued message with `context.skipped` containing
+     *   all intermediate messages
+     * - `'debounce'` — all messages start/reset a debounce timer; only the
+     *   final message in a burst is processed
+     * - `'concurrent'` — no locking; all messages processed in parallel
+     * - `ConcurrencyConfig` — fine-grained control over strategy and parameters
+     */
+    concurrency?: ConcurrencyStrategy | ConcurrencyConfig;
     /**
      * TTL for message deduplication entries in milliseconds.
      * Defaults to 300000 (5 minutes). Increase if your webhook cold starts
@@ -350,6 +364,17 @@ interface ChatConfig<TAdapters extends Record<string, Adapter> = Record<string,
      * wait until some real text has been streamed before creating the message.
      */
     fallbackStreamingPlaceholderText?: string | null;
+    /**
+     * Lock scope determines which messages contend for the same lock.
+     *
+     * - `'thread'`: lock per threadId (default for most adapters)
+     * - `'channel'`: lock per channelId (default for WhatsApp, Telegram)
+     * - function: resolve scope dynamically per message (async supported)
+     *
+     * When not set, falls back to the adapter's `lockScope` property,
+     * then to `'thread'`.
+     */
+    lockScope?: LockScope | ((context: LockScopeContext) => LockScope | Promise<LockScope>);
     /**
      * Logger instance or log level.
      * Pass "silent" to disable all logging.
@@ -366,6 +391,8 @@ interface ChatConfig<TAdapters extends Record<string, Adapter> = Record<string,
         ttlMs?: number;
     };
     /**
+     * @deprecated Use `concurrency` instead.
+     *
      * Behavior when a thread lock cannot be acquired (another handler is processing).
      * - `'drop'` (default) — throw `LockError`, preserving current behavior
      * - `'force'` — force-release the existing lock and re-acquire
@@ -501,6 +528,14 @@ interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
      * List threads in a channel.
      */
     listThreads?(channelId: string, options?: ListThreadsOptions): Promise<ListThreadsResult<TRawMessage>>;
+    /**
+     * Default lock scope for this adapter.
+     * - `'thread'` (default): lock per threadId
+     * - `'channel'`: lock per channelId (for channel-based platforms like WhatsApp, Telegram)
+     *
+     * Can be overridden by `ChatConfig.lockScope`.
+     */
+    readonly lockScope?: LockScope;
     /** Unique name for this adapter (e.g., "slack", "teams") */
     readonly name: string;
     /**
@@ -716,6 +751,57 @@ interface ChatInstance {
         channelId: string;
     }, options?: WebhookOptions): void;
 }
+/** Lock scope determines which messages contend for the same lock. */
+type LockScope = "thread" | "channel";
+/** Context provided to the lockScope resolver function. */
+interface LockScopeContext {
+    adapter: Adapter;
+    channelId: string;
+    isDM: boolean;
+    threadId: string;
+}
+/** Concurrency strategy for overlapping messages on the same thread. */
+type ConcurrencyStrategy = "drop" | "queue" | "debounce" | "concurrent";
+/** Fine-grained concurrency configuration. */
+interface ConcurrencyConfig {
+    /** Debounce window in milliseconds (debounce strategy). Default: 1500. */
+    debounceMs?: number;
+    /** Max concurrent handlers per thread (concurrent strategy). Default: Infinity. */
+    maxConcurrent?: number;
+    /** Max queued messages per thread (queue/debounce strategy). Default: 10. */
+    maxQueueSize?: number;
+    /** What to do when queue is full. Default: 'drop-oldest'. */
+    onQueueFull?: "drop-oldest" | "drop-newest";
+    /** TTL for queued entries in milliseconds. Default: 90000 (90s). */
+    queueEntryTtlMs?: number;
+    /** The concurrency strategy to use. */
+    strategy: ConcurrencyStrategy;
+}
+/**
+ * An entry in the per-thread message queue.
+ * Used by the `queue` and `debounce` concurrency strategies.
+ */
+interface QueueEntry {
+    /** When this entry was enqueued (Unix ms). */
+    enqueuedAt: number;
+    /** When this entry expires (Unix ms). Stale entries are discarded on dequeue. */
+    expiresAt: number;
+    /** The queued message. */
+    message: Message;
+}
+/**
+ * Context provided to message handlers when messages were queued
+ * while a previous handler was running.
+ */
+interface MessageContext {
+    /**
+     * Messages that arrived while the previous handler was running,
+     * in chronological order, excluding the current message (which is the latest).
+     */
+    skipped: Message[];
+    /** Total messages received since last handler ran (skipped.length + 1). */
+    totalSinceLastHandler: number;
+}
 interface StateAdapter {
     /** Acquire a lock on a thread (returns null if already locked) */
     acquireLock(threadId: string, ttlMs: number): Promise<Lock | null>;
@@ -728,8 +814,12 @@ interface StateAdapter {
     connect(): Promise<void>;
     /** Delete a cached value */
     delete(key: string): Promise<void>;
+    /** Pop the next message from the thread's queue. Returns null if empty. */
+    dequeue(threadId: string): Promise<QueueEntry | null>;
     /** Disconnect from the state backend */
     disconnect(): Promise<void>;
+    /** Atomically append a message to the thread's pending queue. Returns new queue depth. */
+    enqueue(threadId: string, entry: QueueEntry, maxSize: number): Promise<number>;
     /** Extend a lock's TTL */
     extendLock(lock: Lock, ttlMs: number): Promise<boolean>;
     /**
@@ -744,6 +834,8 @@ interface StateAdapter {
     getList<T = unknown>(key: string): Promise<T[]>;
     /** Check if subscribed to a thread */
     isSubscribed(threadId: string): Promise<boolean>;
+    /** Get the current queue depth for a thread. */
+    queueDepth(threadId: string): Promise<number>;
     /** Release a lock */
     releaseLock(lock: Lock): Promise<void>;
     /** Set a cached value with optional TTL in milliseconds */
@@ -1349,7 +1441,7 @@ interface FileUpload {
  * });
  * ```
  */
-type MentionHandler<TState = Record<string, unknown>> = (thread: Thread<TState>, message: Message) => void | Promise<void>;
+type MentionHandler<TState = Record<string, unknown>> = (thread: Thread<TState>, message: Message, context?: MessageContext) => void | Promise<void>;
 /**
  * Handler for direct messages (1:1 conversations with the bot).
  *
@@ -1358,14 +1450,14 @@ type MentionHandler<TState = Record<string, unknown>> = (thread: Thread<TState>,
  * handlers are registered, DMs fall through to `onNewMention` for backward
  * compatibility.
  */
-type DirectMessageHandler<TState = Record<string, unknown>> = (thread: Thread<TState>, message: Message, channel: Channel<TState>) => void | Promise<void>;
+type DirectMessageHandler<TState = Record<string, unknown>> = (thread: Thread<TState>, message: Message, channel: Channel<TState>, context?: MessageContext) => void | 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<TState = Record<string, unknown>> = (thread: Thread<TState>, message: Message) => void | Promise<void>;
+type MessageHandler<TState = Record<string, unknown>> = (thread: Thread<TState>, message: Message, context?: MessageContext) => void | Promise<void>;
 /**
  * Handler for messages in subscribed threads.
  *
@@ -1389,7 +1481,7 @@ type MessageHandler<TState = Record<string, unknown>> = (thread: Thread<TState>,
  * });
  * ```
  */
-type SubscribedMessageHandler<TState = Record<string, unknown>> = (thread: Thread<TState>, message: Message) => void | Promise<void>;
+type SubscribedMessageHandler<TState = Record<string, unknown>> = (thread: Thread<TState>, message: Message, context?: MessageContext) => void | Promise<void>;
 /**
  * Well-known emoji that work across platforms (Slack and Google Chat).
  * These are normalized to a common format regardless of platform.
@@ -2101,6 +2193,9 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
     private readonly _dedupeTtlMs;
     private readonly _onLockConflict;
     private readonly _messageHistory;
+    private readonly _concurrencyStrategy;
+    private readonly _concurrencyConfig;
+    private readonly _lockScope;
     private readonly mentionHandlers;
     private readonly directMessageHandlers;
     private readonly messagePatterns;
@@ -2470,6 +2565,12 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
      * Infer which adapter to use based on the userId format.
      */
     private inferAdapterFromUserId;
+    /**
+     * Resolve the lock key for a message based on lock scope.
+     * With 'thread' scope, returns threadId. With 'channel' scope,
+     * returns channelId (derived via adapter.channelIdFromThreadId).
+     */
+    private getLockKey;
     /**
      * Handle an incoming message from an adapter.
      * This is called by adapters when they receive a webhook.
@@ -2478,9 +2579,36 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
      * - 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
+     * - Concurrency: Controlled by `concurrency` config (drop, queue, debounce, concurrent)
      */
     handleIncomingMessage(adapter: Adapter, threadId: string, message: Message): Promise<void>;
+    /**
+     * Drop strategy: acquire lock or fail. Original behavior.
+     */
+    private handleDrop;
+    /**
+     * Queue/Debounce strategy: enqueue if lock is busy, drain after processing.
+     */
+    private handleQueueOrDebounce;
+    /**
+     * Debounce loop: wait for debounceMs, check if newer message arrived,
+     * repeat until no new messages, then process the final message.
+     */
+    private debounceLoop;
+    /**
+     * Drain queue: collect all pending messages, dispatch the latest with
+     * skipped context, then check for more.
+     */
+    private drainQueue;
+    /**
+     * Concurrent strategy: no locking, process immediately.
+     */
+    private handleConcurrent;
+    /**
+     * Dispatch a message to the appropriate handler chain based on
+     * subscription status, mention detection, and pattern matching.
+     */
+    private dispatchToHandlers;
     private createThread;
     /**
      * Detect if the bot was mentioned in the message.
@@ -2488,6 +2616,13 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
      */
     private detectMention;
     private escapeRegex;
+    /**
+     * Reconstruct a proper Message instance from a dequeued entry.
+     * After JSON roundtrip through the state adapter, the message is a plain
+     * object (not a Message instance). This restores class invariants like
+     * `links` defaulting to `[]` and `metadata.dateSent` being a Date.
+     */
+    private rehydrateMessage;
     private runHandlers;
 }
 
@@ -3001,4 +3136,4 @@ declare const Select: SelectComponent;
 declare const SelectOption: SelectOptionComponent;
 declare const TextInput: TextInputComponent;
 
-export { type ActionEvent, type ActionHandler, Actions, ActionsComponent, type Adapter, type AdapterPostableMessage, type AiAssistantMessage, type AiFilePart, type AiImagePart, type AiMessage, type AiMessagePart, type AiTextPart, type AiUserMessage, type AppHomeOpenedEvent, type AppHomeOpenedHandler, type AssistantContextChangedEvent, type AssistantContextChangedHandler, type AssistantThreadStartedEvent, type AssistantThreadStartedHandler, type Attachment, type Author, BaseFormatConverter, Button, ButtonComponent, Card, CardChild, CardComponent, CardElement, CardLink, CardLinkComponent, CardText, type Channel, ChannelImpl, type ChannelInfo, Chat, type ChatConfig, ChatElement, ChatError, type ChatInstance, ConsoleLogger, type CustomEmojiMap, DEFAULT_EMOJI_MAP, type DirectMessageHandler, Divider, DividerComponent, type Emoji, type EmojiFormats, type EmojiMapConfig, EmojiResolver, type EmojiValue, type EphemeralMessage, type FetchDirection, type FetchOptions, type FetchResult, Field, FieldComponent, Fields, FieldsComponent, type FileUpload, type FormatConverter, type FormattedContent, Image, ImageComponent, LinkButton, LinkButtonComponent, type LinkPreview, type ListThreadsOptions, type ListThreadsResult, type Lock, LockError, type LogLevel, type Logger, type MarkdownConverter, type MarkdownTextChunk, type MemberJoinedChannelEvent, type MemberJoinedChannelHandler, type MentionHandler, Message, type MessageData, type MessageHandler, MessageHistoryCache, type MessageHistoryConfig, type MessageMetadata, Modal, type ModalCloseEvent, type ModalCloseHandler, type ModalCloseResponse, ModalComponent, ModalElement, type ModalErrorsResponse, type ModalPushResponse, type ModalResponse, type ModalSubmitEvent, type ModalSubmitHandler, type ModalUpdateResponse, NotImplementedError, type PlanUpdateChunk, type PostEphemeralOptions, type Postable, type PostableAst, type PostableCard, type PostableMarkdown, type PostableMessage, type PostableRaw, RadioSelect, RadioSelectComponent, RateLimitError, type RawMessage, type ReactionEvent, type ReactionHandler, type ScheduledMessage, Section, SectionComponent, Select, SelectComponent, SelectOption, SelectOptionComponent, type SentMessage, type SerializedChannel, type SerializedMessage, type SerializedThread, type SlashCommandEvent, type SlashCommandHandler, type StateAdapter, type StreamChunk, type StreamEvent, type StreamOptions, StreamingMarkdownRenderer, type SubscribedMessageHandler, THREAD_STATE_TTL_MS, Table, type TaskUpdateChunk, TextComponent, TextInput, TextInputComponent, type Thread, ThreadImpl, type ThreadInfo, type ThreadSummary, type WebhookOptions, type WellKnownEmoji, blockquote, cardChildToFallbackText, codeBlock, convertEmojiPlaceholders, createEmoji, defaultEmojiResolver, deriveChannelId, emoji, emphasis, fromFullStream, fromReactElement, fromReactModalElement, getEmoji, getNodeChildren, getNodeValue, inlineCode, isBlockquoteNode, isCardElement, isCodeNode, isDeleteNode, isEmphasisNode, isInlineCodeNode, isJSX, isLinkNode, isListItemNode, isListNode, isModalElement, isParagraphNode, isStrongNode, isTableCellNode, isTableNode, isTableRowNode, isTextNode, link, markdownToPlainText, paragraph, parseMarkdown, root, strikethrough, stringifyMarkdown, strong, tableElementToAscii, tableToAscii, text, toAiMessages, toCardElement, toModalElement, toPlainText, walkAst };
+export { type ActionEvent, type ActionHandler, Actions, ActionsComponent, type Adapter, type AdapterPostableMessage, type AiAssistantMessage, type AiFilePart, type AiImagePart, type AiMessage, type AiMessagePart, type AiTextPart, type AiUserMessage, type AppHomeOpenedEvent, type AppHomeOpenedHandler, type AssistantContextChangedEvent, type AssistantContextChangedHandler, type AssistantThreadStartedEvent, type AssistantThreadStartedHandler, type Attachment, type Author, BaseFormatConverter, Button, ButtonComponent, Card, CardChild, CardComponent, CardElement, CardLink, CardLinkComponent, CardText, type Channel, ChannelImpl, type ChannelInfo, Chat, type ChatConfig, ChatElement, ChatError, type ChatInstance, type ConcurrencyConfig, type ConcurrencyStrategy, ConsoleLogger, type CustomEmojiMap, DEFAULT_EMOJI_MAP, type DirectMessageHandler, Divider, DividerComponent, type Emoji, type EmojiFormats, type EmojiMapConfig, EmojiResolver, type EmojiValue, type EphemeralMessage, type FetchDirection, type FetchOptions, type FetchResult, Field, FieldComponent, Fields, FieldsComponent, type FileUpload, type FormatConverter, type FormattedContent, Image, ImageComponent, LinkButton, LinkButtonComponent, type LinkPreview, type ListThreadsOptions, type ListThreadsResult, type Lock, LockError, type LockScope, type LockScopeContext, type LogLevel, type Logger, type MarkdownConverter, type MarkdownTextChunk, type MemberJoinedChannelEvent, type MemberJoinedChannelHandler, type MentionHandler, Message, type MessageContext, type MessageData, type MessageHandler, MessageHistoryCache, type MessageHistoryConfig, type MessageMetadata, Modal, type ModalCloseEvent, type ModalCloseHandler, type ModalCloseResponse, ModalComponent, ModalElement, type ModalErrorsResponse, type ModalPushResponse, type ModalResponse, type ModalSubmitEvent, type ModalSubmitHandler, type ModalUpdateResponse, NotImplementedError, type PlanUpdateChunk, type PostEphemeralOptions, type Postable, type PostableAst, type PostableCard, type PostableMarkdown, type PostableMessage, type PostableRaw, type QueueEntry, RadioSelect, RadioSelectComponent, RateLimitError, type RawMessage, type ReactionEvent, type ReactionHandler, type ScheduledMessage, Section, SectionComponent, Select, SelectComponent, SelectOption, SelectOptionComponent, type SentMessage, type SerializedChannel, type SerializedMessage, type SerializedThread, type SlashCommandEvent, type SlashCommandHandler, type StateAdapter, type StreamChunk, type StreamEvent, type StreamOptions, StreamingMarkdownRenderer, type SubscribedMessageHandler, THREAD_STATE_TTL_MS, Table, type TaskUpdateChunk, TextComponent, TextInput, TextInputComponent, type Thread, ThreadImpl, type ThreadInfo, type ThreadSummary, type WebhookOptions, type WellKnownEmoji, blockquote, cardChildToFallbackText, codeBlock, convertEmojiPlaceholders, createEmoji, defaultEmojiResolver, deriveChannelId, emoji, emphasis, fromFullStream, fromReactElement, fromReactModalElement, getEmoji, getNodeChildren, getNodeValue, inlineCode, isBlockquoteNode, isCardElement, isCodeNode, isDeleteNode, isEmphasisNode, isInlineCodeNode, isJSX, isLinkNode, isListItemNode, isListNode, isModalElement, isParagraphNode, isStrongNode, isTableCellNode, isTableNode, isTableRowNode, isTextNode, link, markdownToPlainText, paragraph, parseMarkdown, root, strikethrough, stringifyMarkdown, strong, tableElementToAscii, tableToAscii, text, toAiMessages, toCardElement, toModalElement, toPlainText, walkAst };