@sendbird/ai-agent-messenger-react-native 1.6.0 → 1.7.0

package/dist/index.d.ts

@@ -51,16 +51,15 @@ declare interface ActionbookInfo {
  */
 declare interface ActiveChannel {
     url: string;
+    /**
+     * @deprecated Use `conversationStatus` instead. This field always returns 'open' or 'closed' for backward compatibility.
+     * */
+    status: 'open' | 'closed';
     /**
      * @description Conversation status of the active channel.
      * If the conversation is not started, this will be undefined.
      * */
     conversationStatus?: ConversationStatus;
-    /**
-     * @description Status of the active channel. This will be 'closed' if the conversation is closed. otherwise, 'open'.
-     * @deprecated Please use `conversationStatus` field instead.
-     * */
-    status: 'open' | 'closed';
 }
 
 declare interface ActiveChannelUpdatedParams {
@@ -98,6 +97,94 @@ declare interface AgentMessageTemplateInfo {
     };
 }
 
+declare abstract class AIAgentBaseStats {
+    protected timers: Map<string, TimerData> = new Map();
+    protected committed: boolean = false;
+    protected commitCallback: StatsAppendCallback | null = null;
+    protected conversationId: number | null = null;
+    protected channelUrl: string | null = null;
+    protected errorCode: number | null = null;
+    protected errorDescription: string | null = null;
+    protected extraData: Record<string, unknown> = {};
+
+    setCommitCallback(callback: StatsAppendCallback): this {
+        this.commitCallback = callback;
+        return this;
+    }
+
+    setConversationId(id: number): this {
+        this.conversationId = id;
+        return this;
+    }
+
+    setChannelUrl(url: string): this {
+        this.setExtra('channel_url', url);
+        return this;
+    }
+
+    setError(code: number | undefined, description: string): this {
+        this.errorCode = code ?? DEFAULT_ERROR_CODE;
+        this.errorDescription = description;
+        return this;
+    }
+
+    setExtra(key: string, value: unknown): this {
+        if (value !== null && value !== undefined) {
+            this.extraData[key] = value;
+        }
+        return this;
+    }
+
+    startTimer(key: string): this {
+        if (this.committed) return this;
+
+        const existing = this.timers.get(key);
+        if (existing?.startTime !== null && existing?.startTime !== undefined) return this;
+
+        this.timers.set(key, { startTime: Date.now(), endTime: null });
+        return this;
+    }
+
+    stopTimer(key: string): this {
+        if (this.committed) return this;
+
+        const existing = this.timers.get(key);
+        if (!existing || existing.startTime === null || existing.endTime !== null) return this;
+
+        this.timers.set(key, { ...existing, endTime: Date.now() });
+        return this;
+    }
+
+    protected getDuration(key: string): number | null {
+        const timer = this.timers.get(key);
+        if (!timer || timer.startTime === null || timer.endTime === null) return null;
+        return timer.endTime - timer.startTime;
+    }
+
+    isCommitted(): boolean {
+        return this.committed;
+    }
+
+    protected abstract buildPayload(): AIAgentStatPayload | null;
+    protected abstract getMetricKey(): string;
+
+    commit(): boolean {
+        if (this.committed || !this.commitCallback) {
+            return false;
+        }
+
+        const payload = this.buildPayload();
+
+        if (!payload) {
+            return false;
+        }
+
+        this.committed = true;
+        const result = this.commitCallback(AI_AGENT_STAT_TYPE, payload);
+        return result;
+    }
+}
+
 declare interface AIAgentCache {
     template: MessageTemplateCache;
     messenger: MessengerSessionCache;
@@ -152,6 +239,11 @@ declare interface AIAgentConfig {
              * */
             fileEnabled?: boolean;
         };
+        /**
+         * (React only) Whether to play an alert sound when a message is received from the AI agent while the browser is not focused.
+         * @default false
+         * */
+        messageAlertSoundEnabled?: boolean;
         /**
          * (React only) File viewer configuration.
          * */
@@ -284,6 +376,7 @@ declare interface AIAgentMessengerSessionContextValue {
     userSession: null | UserSession;
     aiAgentInfo: null | AIAgentInfo;
     launcherInfo: null | LauncherInfo;
+    presentMethod: PresentMethod;
 
     connectionError?: Error;
 
@@ -298,6 +391,12 @@ declare interface AIAgentMessengerSessionContextValue {
     deauthenticate: () => Promise<void>;
 
     createAttachmentRules: (params: { channel?: GroupChannel; uploadSizeLimit?: number }) => AttachmentRules;
+    /**
+     * @internal
+     */
+    statsTrackers: {
+        initialRender: ConversationInitialRenderStatsTracker;
+    };
 }
 
 declare interface AIAgentMessengerSessionRef {
@@ -389,6 +488,10 @@ queryParams?: AIAgentQueryParams;
 * @description AIAgent global default config.
 * */
 config?: AIAgentConfig;
+/**
+* @internal Used for conversation initial render stat tracking.
+*/
+presentMethod?: PresentMethod;
 } & {
 children?: ReactNode | undefined;
 } & RefAttributes<AIAgentMessengerSessionRef>>;
@@ -404,6 +507,15 @@ declare interface AIAgentSessionHandler extends SessionHandler {
     onExternalAuthTokenExpired?: (data: ExternalAuthTokenExpiredData) => void;
 }
 
+declare interface AIAgentStatPayload {
+    key: string;
+    value?: string;
+    conversation_id?: number;
+    error_code?: number;
+    error_description?: string;
+    extra?: Record<string, unknown>;
+}
+
 /**
  * Common string set interface shared between react and react-native packages
  * These are the base strings that both packages use
@@ -710,6 +822,146 @@ declare interface ConversationHeaderTemplateProps {
     titleAlign?: 'start' | 'center' | 'end';
 }
 
+declare class ConversationInitialRenderStats extends AIAgentBaseStats {
+    private presentMethod: PresentMethod;
+
+    constructor(presentMethod: PresentMethod) {
+        super();
+        this.presentMethod = presentMethod;
+    }
+
+    protected getMetricKey(): string {
+        return METRIC_KEY_CONVERSATION_INITIAL_RENDER;
+    }
+
+    protected buildPayload(): AIAgentStatPayload | null {
+        const authDuration = this.getDuration(DurationKey.AUTH);
+        const getChannelDuration = this.getDuration(DurationKey.GET_CHANNEL);
+        const getMessagesDuration = this.getDuration(DurationKey.GET_MESSAGES);
+        const totalDurationFromCache = this.getDuration(DurationKey.TOTAL_DURATION_FROM_CACHE);
+        const totalDuration = this.getDuration(DurationKey.TOTAL_DURATION);
+
+        const extra: Record<string, unknown> = {
+            ...this.extraData,
+            present_method: this.presentMethod,
+            ...(authDuration !== null && { auth_duration: authDuration }),
+            ...(getChannelDuration !== null && { get_channel_duration: getChannelDuration }),
+            ...(getMessagesDuration !== null && { get_messages_duration: getMessagesDuration }),
+            ...(totalDurationFromCache !== null && { total_duration_from_cache: totalDurationFromCache }),
+        };
+
+        const payload: AIAgentStatPayload = {
+            key: this.getMetricKey(),
+            // Use "0" when totalDuration is null (error case)
+            value: totalDuration !== null ? String(totalDuration) : '0',
+        };
+
+        if (this.conversationId !== null) payload.conversation_id = this.conversationId;
+        if (this.errorCode !== null) payload.error_code = this.errorCode;
+        if (this.errorDescription !== null) payload.error_description = this.errorDescription;
+        if (Object.keys(extra).length > 0) payload.extra = extra;
+
+        return payload;
+    }
+}
+
+/**
+ * Manages ConversationInitialRenderStats lifecycle and encapsulates tracking logic.
+ */
+declare class ConversationInitialRenderStatsTracker {
+    private readonly commitCallback: StatsAppendCallback;
+    private readonly presentMethod: PresentMethod;
+    private stats: ConversationInitialRenderStats | null = null;
+
+    constructor(commitCallback: StatsAppendCallback, presentMethod: PresentMethod) {
+        this.commitCallback = commitCallback;
+        this.presentMethod = presentMethod;
+    }
+
+    private getOrCreateStats(): ConversationInitialRenderStats {
+        if (!this.stats || this.stats.isCommitted()) {
+            this.stats = new ConversationInitialRenderStats(this.presentMethod);
+            this.stats.setCommitCallback(this.commitCallback);
+        }
+        return this.stats;
+    }
+
+    onAuthStart(): void {
+        this.getOrCreateStats()
+        .startTimer(DurationKey.TOTAL_DURATION)
+        .startTimer(DurationKey.TOTAL_DURATION_FROM_CACHE)
+        .startTimer(DurationKey.AUTH);
+    }
+
+    onAuthComplete(): void {
+        this.stats?.stopTimer(DurationKey.AUTH);
+    }
+
+    onAuthError(error: Error): void {
+        if (this.stats && !this.stats.isCommitted()) {
+            this.stats
+            .stopTimer(DurationKey.AUTH)
+            .setError(error instanceof SendbirdError ? error.code : undefined, error.message)
+            .stopTimer(DurationKey.TOTAL_DURATION)
+            .commit();
+        }
+    }
+
+    onGetChannelStart(): void {
+        this.stats?.startTimer(DurationKey.GET_CHANNEL);
+    }
+
+    onGetChannelComplete(conversationId?: number): void {
+        if (this.stats) {
+            this.stats.stopTimer(DurationKey.GET_CHANNEL);
+            if (conversationId !== undefined) {
+                this.stats.setConversationId(conversationId);
+            }
+            this.stats.startTimer(DurationKey.GET_MESSAGES);
+        }
+    }
+
+    onGetChannelError(error: Error): void {
+        if (this.stats && !this.stats.isCommitted()) {
+            this.stats
+            .stopTimer(DurationKey.GET_CHANNEL)
+            .setError(error instanceof SendbirdError ? error.code : undefined, error.message)
+            .stopTimer(DurationKey.TOTAL_DURATION)
+            .commit();
+        }
+    }
+
+    onCacheResult(error: Error | null): void {
+        if (this.stats && !this.stats.isCommitted()) {
+            if (error) {
+                this.stats.setError(error instanceof SendbirdError ? error.code : undefined, error.message);
+            }
+            this.stats.stopTimer(DurationKey.TOTAL_DURATION_FROM_CACHE);
+        }
+    }
+
+    onApiResult(error: Error | null): void {
+        if (this.stats && !this.stats.isCommitted()) {
+            if (error) {
+                this.stats.setError(error instanceof SendbirdError ? error.code : undefined, error.message);
+            }
+            this.stats.stopTimer(DurationKey.TOTAL_DURATION).stopTimer(DurationKey.GET_MESSAGES).commit();
+        }
+    }
+
+    setChannelUrl(url: string): void {
+        this.stats?.setChannelUrl(url);
+    }
+
+    cleanup(): void {
+        this.stats?.commit();
+    }
+
+    clear(): void {
+        this.stats = null;
+    }
+}
+
 export declare const ConversationLayout: {
     (props: PropsWithChildren): ReactNode;
     defaults: {
@@ -2464,6 +2716,8 @@ declare type PositionHorizontal = 'start' | 'end';
 
 declare type PositionVertical = 'top' | 'bottom';
 
+declare type PresentMethod = 'launcher_toggle' | 'direct_present';
+
 declare type RNPermissionsModule = typeof RNPermissions;
 
 export declare type ScrollToBottomButtonProps = {
@@ -2487,6 +2741,8 @@ declare type SingleSelectField = {
     layout: 'default';
 };
 
+declare type StatsAppendCallback = (type: string, data: AIAgentStatPayload) => boolean;
+
 /**
  * Strings type for React Native components
  * Uses nested structure with lowercase keys
@@ -2575,6 +2831,11 @@ declare type TextField = {
     };
 };
 
+declare interface TimerData {
+    startTime: number | null;
+    endTime: number | null;
+}
+
 declare interface TypographyShape {
     h1: TypographyVariant;
     h2: TypographyVariant;