chat 4.18.0 → 4.19.0

package/README.md

@@ -40,6 +40,8 @@ bot.onSubscribedMessage(async (thread, message) => {
 });
 ```
 
+> **Tip:** PostgreSQL and ioredis adapters are also available for production. See [State Adapters](https://chat-sdk.dev/docs/state) for all options.
+
 ## Configuration
 
 | Option | Type | Default | Description |

package/dist/index.d.ts

@@ -77,6 +77,18 @@ interface ChatConfig<TAdapters extends Record<string, Adapter> = Record<string,
      * Pass "silent" to disable all logging.
      */
     logger?: Logger | LogLevel;
+    /**
+     * 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
+     * - callback — custom logic receiving `(threadId, message)`, return `'force'` or `'drop'`
+     *
+     * When `'force'` is used, the previous handler continues executing — only the lock
+     * is released, not the handler itself. This means two handlers may run concurrently
+     * on the same thread. The old handler's `releaseLock()` call becomes a no-op since
+     * the token no longer matches.
+     */
+    onLockConflict?: "force" | "drop" | ((threadId: string, message: Message) => "force" | "drop" | Promise<"force" | "drop">);
     /** State adapter for subscriptions and locking */
     state: StateAdapter;
     /**
@@ -122,7 +134,7 @@ interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
      * Default fallback: first two colon-separated parts (e.g., "slack:C123").
      * Adapters with different structures should override this.
      */
-    channelIdFromThreadId?(threadId: string): string;
+    channelIdFromThreadId(threadId: string): string;
     /** Decode thread ID string back to platform-specific data */
     decodeThreadId(threadId: string): TThreadId;
     /** Delete a message */
@@ -248,13 +260,27 @@ interface Adapter<TThreadId = unknown, TRawMessage = unknown> {
      * @param message - The message content
      * @returns EphemeralMessage with usedFallback: false
      */
-    postEphemeral?(threadId: string, userId: string, message: AdapterPostableMessage): Promise<EphemeralMessage>;
+    postEphemeral?(threadId: string, userId: string, message: AdapterPostableMessage): Promise<EphemeralMessage<TRawMessage>>;
     /** Post a message to a thread */
     postMessage(threadId: string, message: AdapterPostableMessage): Promise<RawMessage<TRawMessage>>;
     /** Remove a reaction from a message */
     removeReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
     /** Render formatted content to platform-specific string */
     renderFormatted(content: FormattedContent): string;
+    /**
+     * Schedule a message for future delivery.
+     *
+     * Optional — only supported by adapters with native scheduling APIs (e.g., Slack).
+     * Thread.schedule() will throw NotImplementedError if this method is absent.
+     *
+     * @param threadId - The thread to post in
+     * @param message - The message content
+     * @param options - Scheduling options including the target delivery time
+     * @returns A ScheduledMessage with cancel() capability
+     */
+    scheduleMessage?(threadId: string, message: AdapterPostableMessage, options: {
+        postAt: Date;
+    }): Promise<ScheduledMessage<TRawMessage>>;
     /** Show typing indicator */
     startTyping(threadId: string, status?: string): Promise<void>;
     /**
@@ -406,6 +432,12 @@ interface StateAdapter {
     disconnect(): Promise<void>;
     /** Extend a lock's TTL */
     extendLock(lock: Lock, ttlMs: number): Promise<boolean>;
+    /**
+     * Force-release a lock on a thread, regardless of ownership token.
+     * The previous lock holder's handler continues running — only the lock is released.
+     * The old handler's `releaseLock()` becomes a no-op (token mismatch).
+     */
+    forceReleaseLock(threadId: string): Promise<void>;
     /** Get a cached value by key */
     get<T = unknown>(key: string): Promise<T | null>;
     /** Check if subscribed to a thread */
@@ -456,7 +488,30 @@ interface Postable<TState = Record<string, unknown>, TRawMessage = unknown> {
     /**
      * Post an ephemeral message visible only to a specific user.
      */
-    postEphemeral(user: string | Author, message: AdapterPostableMessage | ChatElement, options: PostEphemeralOptions): Promise<EphemeralMessage | null>;
+    postEphemeral(user: string | Author, message: AdapterPostableMessage | ChatElement, options: PostEphemeralOptions): Promise<EphemeralMessage<TRawMessage> | null>;
+    /**
+     * Schedule a message for future delivery.
+     *
+     * Currently only supported by the Slack adapter. Other adapters
+     * will throw NotImplementedError.
+     *
+     * @param message - The message content (streaming not supported)
+     * @param options - Scheduling options including the target delivery time
+     * @returns A ScheduledMessage with cancel() capability
+     *
+     * @example
+     * ```typescript
+     * const scheduled = await thread.schedule("Reminder: standup!", {
+     *   postAt: new Date("2026-03-09T09:00:00Z"),
+     * });
+     *
+     * // Cancel before it's sent
+     * await scheduled.cancel();
+     * ```
+     */
+    schedule(message: AdapterPostableMessage | ChatElement, options: {
+        postAt: Date;
+    }): Promise<ScheduledMessage<TRawMessage>>;
     /**
      * Set the state. Merges with existing state by default.
      */
@@ -630,7 +685,7 @@ interface Thread<TState = Record<string, unknown>, TRawMessage = unknown> extend
      * }
      * ```
      */
-    postEphemeral(user: string | Author, message: AdapterPostableMessage | ChatElement, options: PostEphemeralOptions): Promise<EphemeralMessage | null>;
+    postEphemeral(user: string | Author, message: AdapterPostableMessage | ChatElement, options: PostEphemeralOptions): Promise<EphemeralMessage<TRawMessage> | null>;
     /** Recently fetched messages (cached) */
     recentMessages: Message<TRawMessage>[];
     /**
@@ -796,11 +851,11 @@ interface SentMessage<TRawMessage = unknown> extends Message<TRawMessage> {
  * Ephemeral messages are visible only to a specific user and typically
  * cannot be edited or deleted (platform-dependent).
  */
-interface EphemeralMessage {
+interface EphemeralMessage<TRawMessage = unknown> {
     /** Message ID (may be empty for some platforms) */
     id: string;
     /** Platform-specific raw response */
-    raw: unknown;
+    raw: TRawMessage;
     /** 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 */
@@ -818,6 +873,24 @@ interface PostEphemeralOptions {
      */
     fallbackToDM: boolean;
 }
+/**
+ * Result of scheduling a message for future delivery.
+ *
+ * Currently only supported by the Slack adapter via `chat.scheduleMessage`.
+ * Other adapters will throw `NotImplementedError` when `schedule()` is called.
+ */
+interface ScheduledMessage<TRawMessage = unknown> {
+    /** Cancel the scheduled message before it's sent */
+    cancel(): Promise<void>;
+    /** Channel ID where the message will be posted */
+    channelId: string;
+    /** When the message will be sent */
+    postAt: Date;
+    /** Platform-specific raw response */
+    raw: TRawMessage;
+    /** Platform-specific scheduled message ID */
+    scheduledMessageId: string;
+}
 /**
  * Input type for adapter postMessage/editMessage methods.
  * This excludes streams since adapters handle content synchronously.
@@ -1576,6 +1649,9 @@ declare class ChannelImpl<TState = Record<string, unknown>> implements Channel<T
     post(message: string | PostableMessage | ChatElement): Promise<SentMessage>;
     private postSingleMessage;
     postEphemeral(user: string | Author, message: AdapterPostableMessage | ChatElement, options: PostEphemeralOptions): Promise<EphemeralMessage | null>;
+    schedule(message: AdapterPostableMessage | ChatElement, options: {
+        postAt: Date;
+    }): Promise<ScheduledMessage>;
     startTyping(status?: string): Promise<void>;
     mentionUser(userId: string): string;
     toJSON(): SerializedChannel;
@@ -1586,8 +1662,6 @@ declare class ChannelImpl<TState = Record<string, unknown>> implements Channel<T
 }
 /**
  * Derive the channel ID from a thread ID.
- * Uses adapter.channelIdFromThreadId if available, otherwise defaults to
- * first two colon-separated parts.
  */
 declare function deriveChannelId(adapter: Adapter, threadId: string): string;
 
@@ -1662,6 +1736,7 @@ declare class Chat<TAdapters extends Record<string, Adapter> = Record<string, Ad
     private readonly _streamingUpdateIntervalMs;
     private readonly _fallbackStreamingPlaceholderText;
     private readonly _dedupeTtlMs;
+    private readonly _onLockConflict;
     private readonly mentionHandlers;
     private readonly messagePatterns;
     private readonly subscribedMessageHandlers;
@@ -2203,6 +2278,9 @@ declare class ThreadImpl<TState = Record<string, unknown>> implements Thread<TSt
     unsubscribe(): Promise<void>;
     post(message: string | PostableMessage | ChatElement): Promise<SentMessage>;
     postEphemeral(user: string | Author, message: AdapterPostableMessage | ChatElement, options: PostEphemeralOptions): Promise<EphemeralMessage | null>;
+    schedule(message: AdapterPostableMessage | ChatElement, options: {
+        postAt: Date;
+    }): Promise<ScheduledMessage>;
     /**
      * Handle streaming from an AsyncIterable.
      * Normalizes the stream (supports both textStream and fullStream from AI SDK),
@@ -2697,4 +2775,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 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, 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 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, 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, 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, toCardElement, toModalElement, toPlainText, walkAst };
+export { type ActionEvent, type ActionHandler, Actions, ActionsComponent, type Adapter, type AdapterPostableMessage, 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, 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 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, 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, toCardElement, toModalElement, toPlainText, walkAst };

package/dist/index.js

@@ -472,6 +472,25 @@ var ChannelImpl = class _ChannelImpl {
     }
     return null;
   }
+  async schedule(message, options) {
+    let postable;
+    if (isJSX(message)) {
+      const card = toCardElement(message);
+      if (!card) {
+        throw new Error("Invalid JSX element: must be a Card element");
+      }
+      postable = card;
+    } else {
+      postable = message;
+    }
+    if (!this.adapter.scheduleMessage) {
+      throw new NotImplementedError(
+        "Scheduled messages are not supported by this adapter",
+        "scheduling"
+      );
+    }
+    return this.adapter.scheduleMessage(this.id, postable, options);
+  }
   async startTyping(status) {
     await this.adapter.startTyping(this.id, status);
   }
@@ -555,11 +574,7 @@ var ChannelImpl = class _ChannelImpl {
   }
 };
 function deriveChannelId(adapter, threadId) {
-  if (adapter.channelIdFromThreadId) {
-    return adapter.channelIdFromThreadId(threadId);
-  }
-  const parts = threadId.split(":");
-  return parts.slice(0, 2).join(":");
+  return adapter.channelIdFromThreadId(threadId);
 }
 function extractMessageContent(message) {
   if (typeof message === "string") {
@@ -1114,6 +1129,25 @@ var ThreadImpl = class _ThreadImpl {
     }
     return null;
   }
+  async schedule(message, options) {
+    let postable;
+    if (isJSX(message)) {
+      const card = toCardElement(message);
+      if (!card) {
+        throw new Error("Invalid JSX element: must be a Card element");
+      }
+      postable = card;
+    } else {
+      postable = message;
+    }
+    if (!this.adapter.scheduleMessage) {
+      throw new NotImplementedError(
+        "Scheduled messages are not supported by this adapter",
+        "scheduling"
+      );
+    }
+    return this.adapter.scheduleMessage(this.id, postable, options);
+  }
   /**
    * Handle streaming from an AsyncIterable.
    * Normalizes the stream (supports both textStream and fullStream from AI SDK),
@@ -1529,6 +1563,7 @@ var Chat = class {
   _streamingUpdateIntervalMs;
   _fallbackStreamingPlaceholderText;
   _dedupeTtlMs;
+  _onLockConflict;
   mentionHandlers = [];
   messagePatterns = [];
   subscribedMessageHandlers = [];
@@ -1557,6 +1592,7 @@ var Chat = class {
     this._streamingUpdateIntervalMs = config.streamingUpdateIntervalMs ?? 500;
     this._fallbackStreamingPlaceholderText = config.fallbackStreamingPlaceholderText !== void 0 ? config.fallbackStreamingPlaceholderText : "...";
     this._dedupeTtlMs = config.dedupeTtlMs ?? DEDUPE_TTL_MS;
+    this._onLockConflict = config.onLockConflict;
     if (typeof config.logger === "string") {
       this.logger = new ConsoleLogger(config.logger);
     } else {
@@ -2489,15 +2525,26 @@ var Chat = class {
       });
       return;
     }
-    const lock = await this._stateAdapter.acquireLock(
+    let lock = await this._stateAdapter.acquireLock(
       threadId,
       DEFAULT_LOCK_TTL_MS
     );
     if (!lock) {
-      this.logger.warn("Could not acquire lock on thread", { threadId });
-      throw new LockError(
-        `Could not acquire lock on thread ${threadId}. Another instance may be processing.`
-      );
+      const resolution = typeof this._onLockConflict === "function" ? await this._onLockConflict(threadId, message) : this._onLockConflict ?? "drop";
+      if (resolution === "force") {
+        this.logger.info("Force-releasing lock on thread", { threadId });
+        await this._stateAdapter.forceReleaseLock(threadId);
+        lock = await this._stateAdapter.acquireLock(
+          threadId,
+          DEFAULT_LOCK_TTL_MS
+        );
+      }
+      if (!lock) {
+        this.logger.warn("Could not acquire lock on thread", { threadId });
+        throw new LockError(
+          `Could not acquire lock on thread ${threadId}. Another instance may be processing.`
+        );
+      }
     }
     this.logger.debug("Lock acquired", { threadId, token: lock.token });
     try {