@sendbird/ai-agent-messenger-react 1.37.0 → 1.39.0

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import { ComponentType } from 'react';
 import { Context } from 'react';
 import type { Conversation as Conversation_2 } from '@sendbird/chat/aiAgent';
 import type { ConversationStatus } from '@sendbird/chat/aiAgent';
+import type { CPAAuthorizationErrorCode } from '@sendbird/chat/aiAgent';
 import { CSSProperties } from 'react';
 import type { DeskChannelFilter } from '@sendbird/chat/aiAgent';
 import type { FileMessage } from '@sendbird/chat/message';
@@ -226,6 +227,11 @@ countryCode?: string;
 context?: Record<string, string>;
 /**
 * @public
+* @description Customer-provided authorization codes to submit after the messenger session connects.
+* */
+cpaAuthorizationCodes?: CPAAuthorizationCode[];
+/**
+* @public
 * @description AIAgent global default query parameters.
 * */
 queryParams?: AIAgentQueryParams;
@@ -421,8 +427,8 @@ declare interface AIAgentClientHandlers {
     onClickLink?: (params: { url: string }) => void;
     /**
      * Called whenever the SDK emits a live metric — connection, conversation lifecycle,
-     * handoff, and message events. Use for real-time analytics. Implementations should be
-     * efficient and non-blocking, as this may be called frequently.
+     * handoff, message, and memory dialog events. Use for real-time analytics. Implementations
+     * should be efficient and non-blocking, as this may be called frequently.
      */
     onLiveMetric?: (metric: LiveMetric) => void;
 }
@@ -579,6 +585,7 @@ declare interface AIAgentContextValue {
     language: string;
     countryCode?: string;
     context?: Record<string, string>;
+    cpaAuthorizationCodes?: CPAAuthorizationCode[];
 
     logger: Loggable;
     dispatcher: Dispatcher;
@@ -623,11 +630,7 @@ declare interface AIAgentConversationContextValue {
     };
 
     state: {
-        streamAnimation: {
-            isAnimating: boolean;
-            start: (id: string | number) => void;
-            stop: (id: string | number) => void;
-        };
+        streamAnimation: StreamAnimation;
         input: InputState;
     };
 
@@ -745,6 +748,8 @@ declare interface AIAgentInterface {
     countryCode?: string;
     /** The context object for AI Agent */
     context?: Record<string, string>;
+    /** Customer-provided authorization codes to submit after authentication connects */
+    cpaAuthorizationCodes?: CPAAuthorizationCode[];
 
     /** @internal Agent version for conversation initialization */
     agentVersion?: number;
@@ -778,6 +783,8 @@ declare interface AIAgentInterface {
     getContextObject: (channelUrl: string) => Promise<ContextObject>;
     /** Requests a nudge message to be shown above the launcher. Fire-and-forget: the result is only broadcast to onNudgeMessageReceived subscribers */
     requestNudgeMessage: (params: RequestNudgeMessageParams) => Promise<void>;
+    /** Submits customer-provided authorization codes for the current user */
+    submitCPAAuthorizationCodes: (authCodes: CPAAuthorizationCode[]) => Promise<SubmitCPAAuthorizationCodesResponse>;
     /** Clears memories saved for the current user */
     clearUserMemories: (params?: ClearUserMemoriesParams) => Promise<void>;
 
@@ -836,6 +843,7 @@ declare interface AIAgentMessengerSessionContextValue {
     createConversation: (params: ConversationCreateParams) => Promise<string>;
     searchConversation: (params: SearchConversationParams) => Promise<string[]>;
     refreshActiveChannel: () => Promise<string>;
+    submitCPAAuthorizationCodes: (authCodes: CPAAuthorizationCode[]) => Promise<SubmitCPAAuthorizationCodesResponse>;
 
     authenticate: () => Promise<MessengerSettingsResponse>;
     deauthenticate: () => Promise<void>;
@@ -848,6 +856,7 @@ declare interface AIAgentMessengerSessionRef {
     chatSDK: AIAgentContextValue['chatSDK'];
     authenticate: () => Promise<MessengerSettingsResponse>;
     deauthenticate: () => Promise<void>;
+    submitCPAAuthorizationCodes: (authCodes: CPAAuthorizationCode[]) => Promise<SubmitCPAAuthorizationCodesResponse>;
     getContextObject: () => Promise<ContextObject>;
     updateContext: {
         /** Updates the context of the active conversation initialized at session start. */
@@ -963,6 +972,11 @@ export declare type AIAgentProps = PropsWithChildren<{
      * @description Context object for the AI agent client. This is injected when the messenger is first loaded and can provide additional context that may influence how the AI responds to user conversations.
      * */
     context?: Record<string, string>;
+    /**
+     * @public
+     * @description Customer-provided authorization codes to submit after the messenger session connects.
+     * */
+    cpaAuthorizationCodes?: CPAAuthorizationCode[];
     /**
      * @public
      * @description AIAgent global default query parameters.
@@ -1469,6 +1483,8 @@ declare type ChatSDKConversation = Conversation_2;
 
 declare type ChatSDKConversationStatus = ConversationStatus;
 
+declare type ChatSDKCPAAuthorizationErrorCode = CPAAuthorizationErrorCode;
+
 declare type ChatSDKDeskChannelFilter = DeskChannelFilter;
 
 declare type ChatSDKFileMessage = FileMessage;
@@ -1691,7 +1707,7 @@ export declare const ConversationHeaderLayout: {
             TitleArea: () => ReactNode;
             EndArea: () => ReactNode;
             MenuButton: () => ReactNode;
-            Title: () => ReactNode;
+            Title: (props: HeaderTitleProps) => ReactNode;
             MemoryIndicator: () => ReactNode;
             HandoffButton: () => ReactNode;
             ConversationCloseButton: () => ReactNode;
@@ -1708,7 +1724,7 @@ export declare const ConversationHeaderLayout: {
     TitleArea: () => ReactNode;
     EndArea: () => ReactNode;
     MenuButton: () => ReactNode;
-    Title: () => ReactNode;
+    Title: (props: HeaderTitleProps) => ReactNode;
     MemoryIndicator: () => ReactNode;
     HandoffButton: () => ReactNode;
     ConversationCloseButton: () => ReactNode;
@@ -1720,7 +1736,7 @@ export declare const ConversationHeaderLayout: {
     TitleArea: () => ReactNode;
     EndArea: () => ReactNode;
     MenuButton: () => ReactNode;
-    Title: () => ReactNode;
+    Title: (props: HeaderTitleProps) => ReactNode;
     MemoryIndicator: () => ReactNode;
     HandoffButton: () => ReactNode;
     ConversationCloseButton: () => ReactNode;
@@ -1741,7 +1757,7 @@ export declare const ConversationHeaderLayout: {
         component: () => ReactNode;
     }) => null;
     Title: (props: {
-        component: () => ReactNode;
+        component: (props: HeaderTitleProps) => ReactNode;
     }) => null;
     MemoryIndicator: (props: {
         component: () => ReactNode;
@@ -2794,6 +2810,19 @@ declare interface ConversationScrollContextValue {
 
 declare type ConversationScrollMode = 'auto' | 'fixed';
 
+declare interface CPAAuthorizationCode {
+    key: string;
+    code: string;
+    redirectURI?: string;
+}
+
+declare interface CPAAuthorizationResult {
+    key: string;
+    status: 'ok' | 'error';
+    errorCode?: ChatSDKCPAAuthorizationErrorCode;
+    errorMessage?: string;
+}
+
 declare type CSATSubmitParams = {
     csatType: string;
     csat?: number;
@@ -3035,6 +3064,7 @@ export declare interface ExtendedMessagePayload {
 declare type ExternalAuthTokenExpiredData = {
     channelUrl: string;
     aiAgentId: string;
+    cpaKey: string;
 };
 
 export declare interface FeedbackInfo {
@@ -3133,6 +3163,11 @@ export declare interface GroundednessInfo {
     preview_title: string;
 }
 
+declare interface HeaderTitleProps {
+    /** Overrides the default title, which is derived from the channel (AI agent nickname or channel name). */
+    title?: string;
+}
+
 /**
  * Hex color string type. Enforces '#' prefix at compile time.
  * Only validates the prefix — does not guarantee valid hex digits or length.
@@ -3185,6 +3220,12 @@ BaseMessageProps<{
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
     onStreamAnimationComplete?: () => void;
+    /**
+     * Fired (layout effect) when this row starts/stops holding its text — the stream animation is
+     * running but nothing is visible yet. The row renders nothing while holding, so the list draws its
+     * single typing row on the row's behalf and keeps the held row out of the accessibility tree.
+     */
+    onStreamAnimationHoldChange?: (holding: boolean) => void;
 
     // fallbacks
     messageTemplateErrorFallback?: ReactNode;
@@ -3275,6 +3316,7 @@ export declare const IncomingMessageLayout: {
                 onStreamAnimationStart?: () => void;
                 onStreamAnimationProgress?: () => void;
                 onStreamAnimationComplete?: () => void;
+                onStreamAnimationHoldChange?: (holding: boolean) => void;
                 messageTemplateErrorFallback?: ReactNode;
                 messageTemplateLoadingFallback?: ReactNode;
             } & {
@@ -3353,6 +3395,7 @@ export declare const IncomingMessageLayout: {
                 onStreamAnimationStart?: () => void;
                 onStreamAnimationProgress?: () => void;
                 onStreamAnimationComplete?: () => void;
+                onStreamAnimationHoldChange?: (holding: boolean) => void;
                 messageTemplateErrorFallback?: ReactNode;
                 messageTemplateLoadingFallback?: ReactNode;
             } & {
@@ -3431,6 +3474,7 @@ export declare const IncomingMessageLayout: {
                 onStreamAnimationStart?: () => void;
                 onStreamAnimationProgress?: () => void;
                 onStreamAnimationComplete?: () => void;
+                onStreamAnimationHoldChange?: (holding: boolean) => void;
                 messageTemplateErrorFallback?: ReactNode;
                 messageTemplateLoadingFallback?: ReactNode;
             } & {
@@ -3505,6 +3549,7 @@ export declare const IncomingMessageLayout: {
                 onStreamAnimationStart?: () => void;
                 onStreamAnimationProgress?: () => void;
                 onStreamAnimationComplete?: () => void;
+                onStreamAnimationHoldChange?: (holding: boolean) => void;
                 messageTemplateErrorFallback?: ReactNode;
                 messageTemplateLoadingFallback?: ReactNode;
             } & {
@@ -3583,6 +3628,7 @@ export declare const IncomingMessageLayout: {
                 onStreamAnimationStart?: () => void;
                 onStreamAnimationProgress?: () => void;
                 onStreamAnimationComplete?: () => void;
+                onStreamAnimationHoldChange?: (holding: boolean) => void;
                 messageTemplateErrorFallback?: ReactNode;
                 messageTemplateLoadingFallback?: ReactNode;
             } & {
@@ -3661,6 +3707,7 @@ export declare const IncomingMessageLayout: {
                 onStreamAnimationStart?: () => void;
                 onStreamAnimationProgress?: () => void;
                 onStreamAnimationComplete?: () => void;
+                onStreamAnimationHoldChange?: (holding: boolean) => void;
                 messageTemplateErrorFallback?: ReactNode;
                 messageTemplateLoadingFallback?: ReactNode;
             } & {
@@ -3767,6 +3814,7 @@ export declare const IncomingMessageLayout: {
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
     onStreamAnimationComplete?: () => void;
+    onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
     } & {
@@ -3845,6 +3893,7 @@ export declare const IncomingMessageLayout: {
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
     onStreamAnimationComplete?: () => void;
+    onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
     } & {
@@ -3923,6 +3972,7 @@ export declare const IncomingMessageLayout: {
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
     onStreamAnimationComplete?: () => void;
+    onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
     } & {
@@ -3997,6 +4047,7 @@ export declare const IncomingMessageLayout: {
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
     onStreamAnimationComplete?: () => void;
+    onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
     } & {
@@ -4075,6 +4126,7 @@ export declare const IncomingMessageLayout: {
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
     onStreamAnimationComplete?: () => void;
+    onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
     } & {
@@ -4153,6 +4205,7 @@ export declare const IncomingMessageLayout: {
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
     onStreamAnimationComplete?: () => void;
+    onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
     } & {
@@ -4254,6 +4307,7 @@ export declare const IncomingMessageLayout: {
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
     onStreamAnimationComplete?: () => void;
+    onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
     } & {
@@ -4332,6 +4386,7 @@ export declare const IncomingMessageLayout: {
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
     onStreamAnimationComplete?: () => void;
+    onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
     } & {
@@ -4410,6 +4465,7 @@ export declare const IncomingMessageLayout: {
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
     onStreamAnimationComplete?: () => void;
+    onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
     } & {
@@ -4484,6 +4540,7 @@ export declare const IncomingMessageLayout: {
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
     onStreamAnimationComplete?: () => void;
+    onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
     } & {
@@ -4562,6 +4619,7 @@ export declare const IncomingMessageLayout: {
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
     onStreamAnimationComplete?: () => void;
+    onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
     } & {
@@ -4640,6 +4698,7 @@ export declare const IncomingMessageLayout: {
     onStreamAnimationStart?: () => void;
     onStreamAnimationProgress?: () => void;
     onStreamAnimationComplete?: () => void;
+    onStreamAnimationHoldChange?: (holding: boolean) => void;
     messageTemplateErrorFallback?: ReactNode;
     messageTemplateLoadingFallback?: ReactNode;
     } & {
@@ -4764,6 +4823,7 @@ export declare const IncomingMessageLayout: {
             onStreamAnimationStart?: () => void;
             onStreamAnimationProgress?: () => void;
             onStreamAnimationComplete?: () => void;
+            onStreamAnimationHoldChange?: (holding: boolean) => void;
             messageTemplateErrorFallback?: ReactNode;
             messageTemplateLoadingFallback?: ReactNode;
         } & {
@@ -4842,6 +4902,7 @@ export declare const IncomingMessageLayout: {
             onStreamAnimationStart?: () => void;
             onStreamAnimationProgress?: () => void;
             onStreamAnimationComplete?: () => void;
+            onStreamAnimationHoldChange?: (holding: boolean) => void;
             messageTemplateErrorFallback?: ReactNode;
             messageTemplateLoadingFallback?: ReactNode;
         } & {
@@ -4920,6 +4981,7 @@ export declare const IncomingMessageLayout: {
             onStreamAnimationStart?: () => void;
             onStreamAnimationProgress?: () => void;
             onStreamAnimationComplete?: () => void;
+            onStreamAnimationHoldChange?: (holding: boolean) => void;
             messageTemplateErrorFallback?: ReactNode;
             messageTemplateLoadingFallback?: ReactNode;
         } & {
@@ -4996,6 +5058,7 @@ export declare const IncomingMessageLayout: {
             onStreamAnimationStart?: () => void;
             onStreamAnimationProgress?: () => void;
             onStreamAnimationComplete?: () => void;
+            onStreamAnimationHoldChange?: (holding: boolean) => void;
             messageTemplateErrorFallback?: ReactNode;
             messageTemplateLoadingFallback?: ReactNode;
         } & {
@@ -5074,6 +5137,7 @@ export declare const IncomingMessageLayout: {
             onStreamAnimationStart?: () => void;
             onStreamAnimationProgress?: () => void;
             onStreamAnimationComplete?: () => void;
+            onStreamAnimationHoldChange?: (holding: boolean) => void;
             messageTemplateErrorFallback?: ReactNode;
             messageTemplateLoadingFallback?: ReactNode;
         } & {
@@ -5152,6 +5216,7 @@ export declare const IncomingMessageLayout: {
             onStreamAnimationStart?: () => void;
             onStreamAnimationProgress?: () => void;
             onStreamAnimationComplete?: () => void;
+            onStreamAnimationHoldChange?: (holding: boolean) => void;
             messageTemplateErrorFallback?: ReactNode;
             messageTemplateLoadingFallback?: ReactNode;
         } & {
@@ -5330,8 +5395,9 @@ declare interface LiveMetricEmitter<S extends MetricSource = MetricSource> {
  *
  * Registers Sendbird SDK handlers, wraps raw callbacks into {@link MetricSource}s,
  * routes each source to its category emitter, and lets emitters dispatch public
- * metrics through the settable {@link LiveMetricManager.dispatch} sink. Outgoing message
- * and explicit conversation-initialized sources are injected via {@link LiveMetricManager.track}.
+ * metrics through the settable {@link LiveMetricManager.dispatch} sink. Outgoing message,
+ * explicit conversation-initialized, and memory dialog sources are injected via
+ * {@link LiveMetricManager.track}.
  */
 declare class LiveMetricManager {
     private readonly id = 'aiagent_livemetric';
@@ -5354,6 +5420,7 @@ declare class LiveMetricManager {
             handoff: new HandoffMetricEmitter(this.emit),
             incomingMessage: new IncomingMessageMetricEmitter(this.emit, getCurrentUserId),
             outgoingMessage: new OutgoingMessageMetricEmitter(this.emit, getCurrentUserId),
+            memory: new MemoryMetricEmitter(this.emit, getCurrentUserId),
         };
     }
 
@@ -5388,7 +5455,7 @@ declare class LiveMetricManager {
 
     /**
      * Routes a source to its emitter. Also the entry point for externally injected
-     * sources (outgoing message status, explicit conversation-initialized).
+     * sources (outgoing message status, explicit conversation-initialized, memory dialog).
      */
     track(source: MetricSource): void {
         try {
@@ -5448,6 +5515,14 @@ declare interface ManualSessionInfoParams {
     sessionHandler: AIAgentSessionHandler;
 }
 
+/**
+ * What happened on the memory dialog: it became visible, the user chose one of its two buttons,
+ * or the user closed it without choosing (backdrop, Escape, Android back).
+ */
+declare type MemoryDialogAction = 'shown' | 'confirm' | 'cancel' | 'dismiss';
+
+declare type MemoryDialogVariant = 'consent' | 'on' | 'off' | 'readonly';
+
 declare interface MemoryInfo {
     enabled: boolean;
     showIndicator: boolean;
@@ -5633,6 +5708,9 @@ declare class MessagePendingStuckStatsTracker extends MultiStatsTrackerBase<Mess
     }
 }
 
+/** How a message's sender is drawn: the typing row's user and every message row's sender share this. */
+declare type MessageSenderInfo = { userId: string; nickname: string; profileUrl?: string };
+
 declare interface MessageTemplateCache {
     set(key: string, value: string): void;
     get(key: string): string | null;
@@ -5822,7 +5900,7 @@ declare type MessengerSettingsUpdatedParams =
 | { settings: MessengerSettingsResponse; source: 'server' }
 | { settings: CachedMessengerSettings; source: 'cache' };
 
-declare type MetricCategory = 'handoff' | 'conversation' | 'message' | 'connection';
+declare type MetricCategory = 'handoff' | 'conversation' | 'message' | 'connection' | 'memory';
 
 /**
  * An event + action represented as a single value. Input to the emitters.
@@ -5832,7 +5910,8 @@ declare type MetricSource =
 | { type: 'handoff'; channel: ChatSDKGroupChannel }
 | { type: 'conversation'; channel: ChatSDKGroupChannel }
 | { type: 'incomingMessage'; channel: ChatSDKGroupChannel; message: ChatSDKBaseMessage }
-| { type: 'outgoingMessage'; channel: ChatSDKGroupChannel; message: ChatSDKBaseMessage };
+| { type: 'outgoingMessage'; channel: ChatSDKGroupChannel; message: ChatSDKBaseMessage }
+| { type: 'memory'; variant: MemoryDialogVariant; action: MemoryDialogAction; deleteOnOff: boolean };
 
 declare type MultiSelectField = {
     key: string;
@@ -6636,6 +6715,25 @@ declare enum StewardTaskStatus {
     CANCELED = 'CANCELED',
 }
 
+declare type StreamAnimation = {
+    isAnimating: boolean;
+    start: (id: string | number) => void;
+    stop: (id: string | number) => void;
+    isHolding: (id: string | number) => boolean;
+    /**
+     * Set while a row holds its streamed text. The list draws a single typing row, so it falls back to
+     * this when nobody is typing — a live typing signal always wins.
+     *
+     * Never carries a thinking message, deliberately: a row enters the hold only after its reply started
+     * streaming, so the agent's thinking phase is over by then — the frame is held back by our own start
+     * gate, not by the agent still thinking. Relaying the last thinking text here would report a state it
+     * has already left, so the typing row falls back to dots for this window.
+     */
+    heldTypingInfo?: TypingRowInfo;
+    holdStart: (id: string | number, info: TypingRowInfo) => void;
+    holdStop: (id: string | number) => void;
+};
+
 declare type StreamMeasure = {
     channelUrl?: string;
     deliveryTimer: TimeoutId | null;
@@ -7166,6 +7264,10 @@ export declare type StringSet = {
     CHANNEL_FROZEN: string;
 };
 
+declare interface SubmitCPAAuthorizationCodesResponse {
+    cpaAuthorizations: CPAAuthorizationResult[];
+}
+
 declare type SystemBaseMessageProps<T> = T & BaseMessageProps<{}>;
 
 declare type SystemCSATMessageProps = SystemMessageProps & {
@@ -7513,6 +7615,16 @@ declare type TypingMeasure = {
     userMessageId?: number;
 };
 
+/**
+ * What the list's single typing row renders, whoever it is drawn for. `user.userId` identifies the row
+ * it stands in for, which is how the typing bridge tells the awaited reply from anyone else's.
+ */
+declare type TypingRowInfo = {
+    user: MessageSenderInfo;
+    isBot: boolean;
+    thinkingMessage?: string;
+};
+
 declare type TypingTurnEntry = {
     requestId: string;
     record: StatsRecord<TypingIndicatorAbsentTimeoutStats, TypingMeasure>;