@csntgao/ai-employee-client 0.15.6 → 0.16.0

package/dist/index.d.ts

@@ -466,6 +466,12 @@ declare class CustomerSupportClient {
 
 type NotificationReadStatus = 'unread' | 'read';
 type NotificationContentType = 'text' | 'markdown';
+type ConversationNotificationChannel = 'ai_employee' | 'customer_support';
+interface NotificationConversationReference {
+    channel: ConversationNotificationChannel;
+    messageId: string;
+    messageSequence?: string;
+}
 interface NotificationSource {
     type: string;
     code: string;
@@ -488,6 +494,8 @@ interface NotificationAttachment {
 }
 interface NotificationDto {
     id: string;
+    /** Authoritative application that owns and can open this notification. */
+    applicationName: string;
     type: string;
     typeName: string;
     title: string;
@@ -496,6 +504,8 @@ interface NotificationDto {
     contentType: NotificationContentType;
     priority: string;
     source: NotificationSource | null;
+    /** Valid conversation_message or customer_support_message payload with a matching channel. */
+    conversation?: NotificationConversationReference;
     resources: readonly NotificationResource[];
     attachments: readonly NotificationAttachment[];
     readStatus: NotificationReadStatus;
@@ -548,6 +558,9 @@ type NotificationRealtimeChange = {
 };
 interface NotificationCenterTransport {
     listInbox(query: NotificationInboxQuery): Promise<NotificationInboxResult>;
+    getNotification(params: {
+        notificationId: string;
+    }): Promise<NotificationDto>;
     getUnreadCount(params: {
         applicationName: string;
     }): Promise<{
@@ -581,7 +594,7 @@ interface NotificationCenterClientOptions {
     readStatus?: 'all' | 'unread' | 'read';
     preferredTypeOrder?: readonly string[];
 }
-type NotificationCenterErrorCode = 'INVALID_CONFIGURATION' | 'INBOX_LOAD_FAILED' | 'MARK_READ_FAILED' | 'DOWNLOAD_FAILED' | 'CLIENT_DESTROYED';
+type NotificationCenterErrorCode = 'INVALID_CONFIGURATION' | 'NAVIGATION_NOT_CONFIGURED' | 'INBOX_LOAD_FAILED' | 'MARK_READ_FAILED' | 'DOWNLOAD_FAILED' | 'CLIENT_DESTROYED' | 'NOTIFICATION_FRAGMENT_INVALID' | 'NOTIFICATION_NOT_FOUND' | 'NOTIFICATION_APPLICATION_MISSING' | 'NOTIFICATION_APPLICATION_MISMATCH' | 'NOTIFICATION_APPLICATION_UNAVAILABLE' | 'NOTIFICATION_HANDLER_UNAVAILABLE' | 'NOTIFICATION_RESOURCE_INVALID' | 'NOTIFICATION_LAUNCH_BLOCKED' | 'NOTIFICATION_LAUNCH_FAILED' | 'NOTIFICATION_OPEN_FAILED';
 interface NotificationCenterErrorDetail {
     code: NotificationCenterErrorCode;
     message: string;
@@ -672,6 +685,7 @@ declare class NotificationCenterClient {
     private setAvailableTypes;
     private refreshUnreadCount;
     private applyRealtimeChange;
+    private resyncUnreadInbox;
     private syncRealtimeUnreadCount;
     private applyRead;
     private refreshFromRealtime;
@@ -682,6 +696,159 @@ declare class NotificationCenterClient {
     private assertUsable;
 }
 
+type UserRealtimeConnectionState = 'idle' | 'connecting' | 'authenticating' | 'connected' | 'reconnecting' | 'stopped' | 'destroyed';
+interface UserRealtimeReconnectOptions {
+    initialDelayMs: number;
+    maximumDelayMs: number;
+    factor: number;
+    jitter: number;
+}
+interface UserRealtimeCursorStore {
+    load(channel: string): string | null | undefined | Promise<string | null | undefined>;
+    save(channel: string, cursor: string): void | Promise<void>;
+    clear(channel: string): void | Promise<void>;
+}
+type UserRealtimeWebSocketFactory = (url: string) => WebSocket;
+interface UserRealtimeClientOptions {
+    realtimeUrl: string;
+    getAccessToken(): string | Promise<string>;
+    requestedChannels: readonly string[];
+    cursorStore?: UserRealtimeCursorStore | null;
+    reconnect?: Partial<UserRealtimeReconnectOptions>;
+    webSocketFactory?: UserRealtimeWebSocketFactory;
+    /** Primarily useful for deterministic tests. Production heartbeats are never faster than 5s. */
+    minimumHeartbeatMs?: number;
+    /** Per-channel in-memory event ID bound. */
+    maximumSeenEventIds?: number;
+}
+type UserRealtimeErrorCode = 'INVALID_CONFIGURATION' | 'TOKEN_UNAVAILABLE' | 'WEBSOCKET_UNAVAILABLE' | 'WEBSOCKET_ERROR' | 'AUTHENTICATION_FAILED' | 'REALTIME_UNAVAILABLE' | 'CHANNEL_UNAVAILABLE' | 'PROTOCOL_ERROR' | 'CURSOR_STORE_FAILED' | 'EVENT_HANDLER_FAILED' | 'CLIENT_DESTROYED';
+interface UserRealtimeErrorDetail {
+    code: UserRealtimeErrorCode;
+    message: string;
+    recoverable: boolean;
+    channel?: string;
+}
+interface UserRealtimeChannelEventDetail {
+    channel: string;
+    /** Raw `realtime_event.event` payload. The client does not parse business DTOs. */
+    event: unknown;
+    eventId: string;
+    cursor: string;
+    /** Monotonically increases for every newly delivered event within this channel. */
+    sequence: number;
+}
+interface UserRealtimeResyncRequiredDetail {
+    channel: string;
+    reason: string;
+    latestEventId: string;
+    /** Channel event sequence observed when the resync signal arrived. */
+    sequence: number;
+    /** Per-channel generation used to reject stale resync acknowledgements. */
+    generation: number;
+}
+interface UserRealtimeClientEventMap {
+    ready: {
+        channels: readonly string[];
+    };
+    'channel-event': UserRealtimeChannelEventDetail;
+    'resync-required': UserRealtimeResyncRequiredDetail;
+    'state-change': {
+        previous: UserRealtimeConnectionState;
+        current: UserRealtimeConnectionState;
+    };
+    error: UserRealtimeErrorDetail;
+}
+type UserRealtimeClientListener<K extends keyof UserRealtimeClientEventMap> = (detail: UserRealtimeClientEventMap[K]) => void;
+interface UserRealtimeRestartOptions {
+    clearCursors?: boolean;
+}
+
+declare class UserRealtimeClientError extends Error {
+    readonly code: UserRealtimeErrorCode;
+    constructor(code: UserRealtimeErrorCode, message: string);
+}
+/**
+ * Framework-independent owner of one authenticated `/api/user-realtime/ws` connection.
+ *
+ * Business payloads remain opaque. Hosts decide which components or stores receive each
+ * channel event and own all HTTP resynchronization work.
+ */
+declare class UserRealtimeClient {
+    readonly requestedChannels: readonly string[];
+    private readonly realtimeUrl;
+    private readonly getAccessToken;
+    private readonly cursorStore;
+    private readonly reconnectOptions;
+    private readonly webSocketFactory;
+    private readonly minimumHeartbeatMs;
+    private readonly maximumSeenEventIds;
+    private readonly listeners;
+    private readonly cursors;
+    private readonly cursorWriteChains;
+    private readonly seenEventIds;
+    private readonly channelSequences;
+    private readonly pendingResyncs;
+    private readonly resyncGenerations;
+    private socket;
+    private messageChain;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private startPromise;
+    private currentState;
+    private socketGeneration;
+    private lifecycleGeneration;
+    private reconnectAttempt;
+    private deliverySequence;
+    private shouldReconnect;
+    private destroyed;
+    private socketAuthenticationFailure;
+    constructor(options: UserRealtimeClientOptions);
+    get connectionState(): UserRealtimeConnectionState;
+    get eventSequence(): number;
+    get isDestroyed(): boolean;
+    on<K extends keyof UserRealtimeClientEventMap>(type: K, listener: UserRealtimeClientListener<K>): () => void;
+    start(): Promise<void>;
+    stop(): void;
+    restart(options?: UserRealtimeRestartOptions): Promise<void>;
+    clearCursors(): Promise<void>;
+    /**
+     * Confirm that Host HTTP state was restored for a previously emitted resync signal.
+     * Stale confirmations never overwrite a cursor advanced by a newer realtime event.
+     */
+    confirmResync(detail: UserRealtimeResyncRequiredDetail): Promise<boolean>;
+    destroy(): void;
+    private loadCursors;
+    private openSocket;
+    private authenticate;
+    private handleSocketData;
+    private handleServerMessage;
+    private handleReady;
+    private handleRealtimeEvent;
+    private handleResyncRequired;
+    private handleChannelError;
+    private handleAuthenticationError;
+    private startHeartbeat;
+    private handleSocketClose;
+    private scheduleReconnect;
+    private rememberEventId;
+    private hasSeenEvent;
+    private rememberCursor;
+    private flushCursorWrite;
+    private clearStoredCursor;
+    private stopConnection;
+    private closeCurrentSocket;
+    private clearReconnectTimer;
+    private clearHeartbeatTimer;
+    private clearDeliveryState;
+    private isCurrentSocket;
+    private isCurrentLifecycle;
+    private setState;
+    private emitError;
+    private emit;
+    private emitSafely;
+    private assertUsable;
+}
+
 type JsonRecord = Record<string, unknown>;
 interface AuthenticateFrame {
     type: 'authenticate';
@@ -738,4 +905,4 @@ declare function parseJsonRecord(raw: string): JsonRecord | null;
 declare function parseAiEmployeeEvent(raw: unknown): ParsedAiEmployeeEvent;
 declare function hashText(value: string): string;
 
-export { type AiEmployeeAssistantAction, type AiEmployeeAttachmentReference, AiEmployeeClient, AiEmployeeClientError, type AiEmployeeClientErrorDetail, type AiEmployeeClientEventMap, type AiEmployeeClientListener, type AiEmployeeClientOptions, type AiEmployeeClientStartResult, type AiEmployeeConnectionState, type AiEmployeeErrorCode, type AiEmployeeFirstMessageOptions, type AiEmployeeFirstMessageRequest, type AiEmployeeFirstMessageRequestState, type AiEmployeeFirstMessageRequestStore, type AiEmployeeFirstMessageResult, type AiEmployeeMessage, type AiEmployeeMessageRole, type AiEmployeeReconnectOptions, type AiEmployeeSessionSummary, type AiEmployeeTransport, AiEmployeeTransportError, type AiEmployeeTransportErrorCode, type AiEmployeeWebSocketFactory, type AuthenticateFrame, type CustomerSupportAgent, type CustomerSupportAttachment, type CustomerSupportAttachmentDownloadRequest, CustomerSupportClient, CustomerSupportClientError, type CustomerSupportClientEventMap, type CustomerSupportClientListener, type CustomerSupportClientOptions, type CustomerSupportCreateSessionRequest, type CustomerSupportCreateSessionResult, type CustomerSupportErrorCode, type CustomerSupportErrorDetail, type CustomerSupportHandoffRequest, type CustomerSupportHandoffResult, type CustomerSupportMessage, type CustomerSupportMessagePage, type CustomerSupportSenderType, type CustomerSupportSession, type CustomerSupportSessionStatus, type CustomerSupportTransport, type NotificationAttachment, NotificationCenterClient, NotificationCenterClientError, type NotificationCenterClientEventMap, type NotificationCenterClientListener, type NotificationCenterClientOptions, type NotificationCenterErrorCode, type NotificationCenterErrorDetail, type NotificationCenterTransport, type NotificationContentType, type NotificationDto, type NotificationInboxQuery, type NotificationInboxResult, type NotificationMarkAllReadResult, type NotificationMarkReadResult, type NotificationReadStatus, type NotificationRealtimeChange, type NotificationResource, type NotificationSource, type NotificationTypeSummary, type OpenCustomerSupportAssistantAction, type OpenFileAssistantAction, type ParsedAiEmployeeAssistantContent, type ParsedAiEmployeeEvent, type ParsedAssistantMessageStreamReference, type ParsedAssistantStreamEvent, type ParsedSessionMessage, type PingFrame, type SessionSubscriptionFrame, createAuthenticateFrame, createPingFrame, createSubscriptionFrame, hashText, isUuidV4, parseAiEmployeeAssistantContent, parseAiEmployeeEvent, parseJsonRecord };
+export { type AiEmployeeAssistantAction, type AiEmployeeAttachmentReference, AiEmployeeClient, AiEmployeeClientError, type AiEmployeeClientErrorDetail, type AiEmployeeClientEventMap, type AiEmployeeClientListener, type AiEmployeeClientOptions, type AiEmployeeClientStartResult, type AiEmployeeConnectionState, type AiEmployeeErrorCode, type AiEmployeeFirstMessageOptions, type AiEmployeeFirstMessageRequest, type AiEmployeeFirstMessageRequestState, type AiEmployeeFirstMessageRequestStore, type AiEmployeeFirstMessageResult, type AiEmployeeMessage, type AiEmployeeMessageRole, type AiEmployeeReconnectOptions, type AiEmployeeSessionSummary, type AiEmployeeTransport, AiEmployeeTransportError, type AiEmployeeTransportErrorCode, type AiEmployeeWebSocketFactory, type AuthenticateFrame, type ConversationNotificationChannel, type CustomerSupportAgent, type CustomerSupportAttachment, type CustomerSupportAttachmentDownloadRequest, CustomerSupportClient, CustomerSupportClientError, type CustomerSupportClientEventMap, type CustomerSupportClientListener, type CustomerSupportClientOptions, type CustomerSupportCreateSessionRequest, type CustomerSupportCreateSessionResult, type CustomerSupportErrorCode, type CustomerSupportErrorDetail, type CustomerSupportHandoffRequest, type CustomerSupportHandoffResult, type CustomerSupportMessage, type CustomerSupportMessagePage, type CustomerSupportSenderType, type CustomerSupportSession, type CustomerSupportSessionStatus, type CustomerSupportTransport, type NotificationAttachment, NotificationCenterClient, NotificationCenterClientError, type NotificationCenterClientEventMap, type NotificationCenterClientListener, type NotificationCenterClientOptions, type NotificationCenterErrorCode, type NotificationCenterErrorDetail, type NotificationCenterTransport, type NotificationContentType, type NotificationConversationReference, type NotificationDto, type NotificationInboxQuery, type NotificationInboxResult, type NotificationMarkAllReadResult, type NotificationMarkReadResult, type NotificationReadStatus, type NotificationRealtimeChange, type NotificationResource, type NotificationSource, type NotificationTypeSummary, type OpenCustomerSupportAssistantAction, type OpenFileAssistantAction, type ParsedAiEmployeeAssistantContent, type ParsedAiEmployeeEvent, type ParsedAssistantMessageStreamReference, type ParsedAssistantStreamEvent, type ParsedSessionMessage, type PingFrame, type SessionSubscriptionFrame, type UserRealtimeChannelEventDetail, UserRealtimeClient, UserRealtimeClientError, type UserRealtimeClientEventMap, type UserRealtimeClientListener, type UserRealtimeClientOptions, type UserRealtimeConnectionState, type UserRealtimeCursorStore, type UserRealtimeErrorCode, type UserRealtimeErrorDetail, type UserRealtimeReconnectOptions, type UserRealtimeRestartOptions, type UserRealtimeResyncRequiredDetail, type UserRealtimeWebSocketFactory, createAuthenticateFrame, createPingFrame, createSubscriptionFrame, hashText, isUuidV4, parseAiEmployeeAssistantContent, parseAiEmployeeEvent, parseJsonRecord };