@sendbird/ai-agent-messenger-react 1.33.0 → 1.34.1

package/dist/index.d.ts

@@ -396,6 +396,12 @@ declare interface AIAgentClientHandlers {
      * `Linking.openURL` on React Native.
      */
     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.
+     */
+    onLiveMetric?: (metric: LiveMetric) => void;
 }
 
 declare type AIAgentCommonIconName =
@@ -755,6 +761,12 @@ declare interface AIAgentInterface {
     /** @internal Initializes a conversation on the channel if needed (AI Agent channel without conversation). */
     initConversationIfNeeded: (channel: ChatSDKGroupChannel) => Promise<void>;
 
+    /** @internal Live metric handler; bridged from {@link AIAgentClientHandlers.onLiveMetric}. */
+    onLiveMetric?: LiveMetricDispatch;
+
+    /** @internal Live metric manager owned by this SDK instance. */
+    readonly liveMetricManager: LiveMetricManager;
+
     /** Disposes all resources held by this instance (WebSocket, desk auth, event handlers). */
     dispose: () => void;
 
@@ -1565,6 +1577,13 @@ export declare const ConnectionDelayLayout: {
     }) => null;
 };
 
+declare type ConnectionEventDetail =
+| 'connected'
+| 'reconnectStarted'
+| 'reconnectSucceeded'
+| 'reconnectFailed'
+| 'disconnected';
+
 declare interface ContextObject {
     language?: string;
     country?: string;
@@ -2635,6 +2654,10 @@ declare type ErrorLike = StatsPayloadError;
  */
 export declare interface ExtendedMessagePayload {
     is_thinking: boolean;
+    // Whether this message is the last bubble in a multi-bubble turn.
+    // Sent as `true` only on the last bubble; omitted (undefined) on non-last bubbles.
+    // Only reliable once the server stream has completed (data.stream = false).
+    is_last_in_turn?: boolean;
     cta_button: {
         label: string;
         url: string;
@@ -2909,7 +2932,7 @@ export declare const IncomingMessageLayout: {
                 };
             }) => ReactNode;
             SuggestedReplies: ({ extendedMessagePayload, onClickSuggestedReply, suggestedRepliesDirection, }: IncomingMessageProps) => ReactNode;
-            MessageTemplate: (props: Pick<IncomingMessageProps, "onGetCachedMessageTemplate" | "onRequestMessageTemplate" | "onHandleTemplateInternalAction" | "messageTemplateErrorFallback" | "messageTemplateLoadingFallback" | "extendedMessagePayload"> & {
+            MessageTemplate: (props: Pick<IncomingMessageProps, "onClickLink" | "onGetCachedMessageTemplate" | "onRequestMessageTemplate" | "onHandleTemplateInternalAction" | "messageTemplateErrorFallback" | "messageTemplateLoadingFallback" | "extendedMessagePayload"> & {
                 statsCallbacks?: Pick<IncomingMessageStatsCallbacks, "onMessageTemplateError">;
             }) => ReactNode;
             CustomMessageTemplate: (_: ({
@@ -3401,7 +3424,7 @@ export declare const IncomingMessageLayout: {
     };
     }) => ReactNode;
     SuggestedReplies: ({ extendedMessagePayload, onClickSuggestedReply, suggestedRepliesDirection, }: IncomingMessageProps) => ReactNode;
-    MessageTemplate: (props: Pick<IncomingMessageProps, "onGetCachedMessageTemplate" | "onRequestMessageTemplate" | "onHandleTemplateInternalAction" | "messageTemplateErrorFallback" | "messageTemplateLoadingFallback" | "extendedMessagePayload"> & {
+    MessageTemplate: (props: Pick<IncomingMessageProps, "onClickLink" | "onGetCachedMessageTemplate" | "onRequestMessageTemplate" | "onHandleTemplateInternalAction" | "messageTemplateErrorFallback" | "messageTemplateLoadingFallback" | "extendedMessagePayload"> & {
     statsCallbacks?: Pick<IncomingMessageStatsCallbacks, "onMessageTemplateError">;
     }) => ReactNode;
     CustomMessageTemplate: (_: ({
@@ -3888,7 +3911,7 @@ export declare const IncomingMessageLayout: {
     };
     }) => ReactNode;
     SuggestedReplies: ({ extendedMessagePayload, onClickSuggestedReply, suggestedRepliesDirection, }: IncomingMessageProps) => ReactNode;
-    MessageTemplate: (props: Pick<IncomingMessageProps, "onGetCachedMessageTemplate" | "onRequestMessageTemplate" | "onHandleTemplateInternalAction" | "messageTemplateErrorFallback" | "messageTemplateLoadingFallback" | "extendedMessagePayload"> & {
+    MessageTemplate: (props: Pick<IncomingMessageProps, "onClickLink" | "onGetCachedMessageTemplate" | "onRequestMessageTemplate" | "onHandleTemplateInternalAction" | "messageTemplateErrorFallback" | "messageTemplateLoadingFallback" | "extendedMessagePayload"> & {
     statsCallbacks?: Pick<IncomingMessageStatsCallbacks, "onMessageTemplateError">;
     }) => ReactNode;
     CustomMessageTemplate: (_: ({
@@ -4361,7 +4384,7 @@ export declare const IncomingMessageLayout: {
     }>;
 } & {
     MessageTemplate: (props: {
-        component: (props: Pick<IncomingMessageProps, "onGetCachedMessageTemplate" | "onRequestMessageTemplate" | "onHandleTemplateInternalAction" | "messageTemplateErrorFallback" | "messageTemplateLoadingFallback" | "extendedMessagePayload"> & {
+        component: (props: Pick<IncomingMessageProps, "onClickLink" | "onGetCachedMessageTemplate" | "onRequestMessageTemplate" | "onHandleTemplateInternalAction" | "messageTemplateErrorFallback" | "messageTemplateLoadingFallback" | "extendedMessagePayload"> & {
             statsCallbacks?: Pick<IncomingMessageStatsCallbacks, "onMessageTemplateError">;
         }) => ReactNode;
     }) => null;
@@ -4986,6 +5009,110 @@ declare interface LayoutContextValue<Props, Components extends Record<string, Co
     updateComponent: <K extends keyof Components>(key: K, component: Components[K]) => void;
 }
 
+/**
+ * Base contract for every metric emitted by the Live Metric module.
+ * The injected `dispatch` boundary receives values of this type.
+ */
+export declare interface LiveMetric {
+    readonly category: MetricCategory;
+    readonly metricKey: string;
+    readonly data: Record<string, string>;
+}
+
+/** Outward boundary: emitters dispatch built metrics through this callback. */
+declare type LiveMetricDispatch = (metric: LiveMetric) => void;
+
+/**
+ * Category emitter contract. Each emitter accepts its own source variant,
+ * decides whether to emit based on its state cache, and dispatches metrics.
+ */
+declare interface LiveMetricEmitter<S extends MetricSource = MetricSource> {
+    handleEvent(source: S): void;
+}
+
+/**
+ * Central manager for the Live Metric module.
+ *
+ * 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}.
+ */
+declare class LiveMetricManager {
+    private readonly id = 'aiagent_livemetric';
+
+    /** Sink for emitted metrics. Set by the owner; metrics are dropped while unset. */
+    dispatch?: LiveMetricDispatch;
+
+    // Project to the plain public shape: drops internal fields and resolves the
+    // non-enumerable `data` getter so the payload survives JSON.stringify/spread.
+    private readonly emit: LiveMetricDispatch = ({ category, metricKey, data }) => {
+        this.dispatch?.({ category, metricKey, data });
+    };
+    private readonly emitters: Record<MetricSource['type'], LiveMetricEmitter>;
+
+    constructor(private readonly chatSDK: ChatSDKType) {
+        const getCurrentUserId = () => this.chatSDK.currentUser?.userId;
+        this.emitters = {
+            connection: new ConnectionMetricEmitter(this.emit),
+            conversation: new ConversationMetricEmitter(this.emit),
+            handoff: new HandoffMetricEmitter(this.emit),
+            incomingMessage: new IncomingMessageMetricEmitter(this.emit, getCurrentUserId),
+            outgoingMessage: new OutgoingMessageMetricEmitter(this.emit, getCurrentUserId),
+        };
+    }
+
+    start(): void {
+        const connectionHandler = new ConnectionHandler({
+            onConnected: (userId) => this.trackConnection('connected', userId),
+            onDisconnected: (userId) => this.trackConnection('disconnected', userId),
+            onReconnectStarted: () => this.trackConnection('reconnectStarted'),
+            onReconnectSucceeded: () => this.trackConnection('reconnectSucceeded'),
+            onReconnectFailed: () => this.trackConnection('reconnectFailed'),
+        });
+
+        const channelHandler = new GroupChannelHandler({
+            onMessageReceived: (channel, message) => {
+                if (!channel.isGroupChannel()) return;
+                this.track({ type: 'incomingMessage', channel, message });
+            },
+            onChannelChanged: (channel) => {
+                if (!channel.isGroupChannel()) return;
+
+                // Note: onChannelChanged can be triggered by various events (message received, user joined/left, etc.)
+                this.track({ type: 'handoff', channel });
+                this.track({ type: 'conversation', channel });
+            },
+            onUserJoined: (channel) => this.track({ type: 'handoff', channel }),
+            onUserLeft: (channel) => this.track({ type: 'handoff', channel }),
+        });
+
+        this.chatSDK.addConnectionHandler(this.id, connectionHandler);
+        this.chatSDK.groupChannel.addGroupChannelHandler(this.id, channelHandler);
+    }
+
+    /**
+     * Routes a source to its emitter. Also the entry point for externally injected
+     * sources (outgoing message status, explicit conversation-initialized).
+     */
+    track(source: MetricSource): void {
+        try {
+            this.emitters[source.type].handleEvent(source);
+        } catch {
+            // no-op
+        }
+    }
+
+    dispose(): void {
+        this.chatSDK.removeConnectionHandler(this.id);
+        this.chatSDK.groupChannel.removeGroupChannelHandler(this.id);
+    }
+
+    private trackConnection(detail: ConnectionEventDetail, userId = this.chatSDK.currentUser?.userId): void {
+        if (userId) this.track({ type: 'connection', detail, userId });
+    }
+}
+
 declare interface LocalizationContextValue extends LanguageSet {
     format: typeof format;
     defaultStringSet: StringSet;
@@ -5353,6 +5480,18 @@ declare type MessengerSettingsUpdatedParams =
 | { settings: MessengerSettingsResponse; source: 'server' }
 | { settings: CachedMessengerSettings; source: 'cache' };
 
+declare type MetricCategory = 'handoff' | 'conversation' | 'message' | 'connection';
+
+/**
+ * An event + action represented as a single value. Input to the emitters.
+ */
+declare type MetricSource =
+| { type: 'connection'; detail: ConnectionEventDetail; userId: string }
+| { type: 'handoff'; channel: ChatSDKGroupChannel }
+| { type: 'conversation'; channel: ChatSDKGroupChannel }
+| { type: 'incomingMessage'; channel: ChatSDKGroupChannel; message: ChatSDKBaseMessage }
+| { type: 'outgoingMessage'; channel: ChatSDKGroupChannel; message: ChatSDKBaseMessage };
+
 declare type MultiSelectField = {
     key: string;
     type: 'multi-select';