@onedeskpro/chatbot-core 0.1.0 → 0.2.1

package/dist/index.d.cts

@@ -4,10 +4,15 @@ import { ChatbotBlockReason } from '@onedeskpro/chatbot-types';
 import { ChatbotEventMap } from '@onedeskpro/chatbot-types';
 import { ChatbotInitOptions } from '@onedeskpro/chatbot-types';
 import { ChatbotState } from '@onedeskpro/chatbot-types';
+import { ChatbotTicketMode } from '@onedeskpro/chatbot-types';
 import { ChatMessage } from '@onedeskpro/chatbot-types';
 import { ChatRequest } from '@onedeskpro/chatbot-types';
 import { ChatResponseData } from '@onedeskpro/chatbot-types';
+import { IdentifyRequest } from '@onedeskpro/chatbot-types';
+import { IdentifyResponseData } from '@onedeskpro/chatbot-types';
 import { SdkConfigResponse } from '@onedeskpro/chatbot-types';
+import { TicketStatusData } from '@onedeskpro/chatbot-types';
+import { VisitorVerifyResponse } from '@onedeskpro/chatbot-types';
 
 export declare class ApiClient {
     private baseUrl;
@@ -16,9 +21,12 @@ export declare class ApiClient {
     constructor(options: ApiClientOptions);
     private fail;
     private request;
+    identify(payload: IdentifyRequest): Promise<IdentifyResponseData>;
+    verifyVisitor(visitorToken: string): Promise<VisitorVerifyResponse>;
     sendMessage(payload: ChatRequest): Promise<ChatResponseData>;
-    fetchHistory(sessionId: string): Promise<ChatMessage[]>;
     fetchConfig(): Promise<SdkConfigResponse>;
+    requestHuman(visitorToken: string): Promise<TicketStatusData>;
+    fetchTicketStatus(visitorToken: string): Promise<TicketStatusData>;
 }
 
 declare interface ApiClientOptions {
@@ -37,10 +45,22 @@ export { ChatbotBlockReason }
 export declare class ChatbotCore {
     private apiClient;
     private emitter;
-    private session;
+    private visitorTokens;
     private widget;
+    private sdkSocket;
     private options;
     private callerSetName;
+    /**
+     * True once this session has an open (or recently closed) ticket episode —
+     * from ticket-status `conversationId`, a non-ai mode, or a successful chat
+     * round-trip. Gates the request-human control so visitors cannot escalate
+     * before a ticket exists.
+     */
+    private hasActiveTicket;
+    /** Pending readiness re-check while the server is unreachable. */
+    private retryTimer;
+    /** Server id of the last `message:receive` push rendered as an agent bubble. */
+    private lastPushId;
     /**
      * Bumped by every init() and by destroy(). An async init compares the token it
      * started with against this before touching anything, so a superseded run — a
@@ -55,11 +75,51 @@ export declare class ChatbotCore {
      * everything — not just the transitions that have a dedicated event.
      */
     private setState;
+    private applyMode;
+    /** Derive ticket existence from status restore / socket pushes. */
+    private syncHasActiveTicket;
+    private syncWidgetMode;
     init(options: ChatbotInitOptions): Promise<void>;
-    /** Returns null on failure — a network blip must not block the user from trying. */
-    private fetchConfig;
+    /**
+     * Asks `/sdk/config` whether the server is up and the agent can reply, and
+     * shows the widget only when both hold. An unreachable server is retried on
+     * READINESS_RETRY_DELAYS_MS; a configuration problem is final for this page.
+     * `ready` fires once the outcome is settled either way.
+     */
+    private checkReadiness;
+    /** Creates the widget hidden; checkReadiness reveals it once every check passed. */
+    private mountWidget;
+    private clearRetry;
+    /**
+     * Maps `/sdk/config` rejections other than an unreachable server: missing
+     * Connected Channels becomes `no-agent`; anything else (an invalid key, a
+     * disallowed origin) is recorded as `state.error`.
+     */
+    private handleConfigError;
+    private resolveVisitorGate;
+    private enterChat;
+    private connectSdkSocket;
+    private disconnectSdkSocket;
+    /** Restore episode mode after identify / verify — never hydrates messages. */
+    private restoreTicketStatus;
+    private handleTicketStatus;
+    /**
+     * Live human (agent) pushes from `/sdk` `message:receive`.
+     *
+     * Choice: ignore while `mode === 'ai'`. Website outbound (including AI
+     * replies) is fanned out to the visitor room; AI text already arrives via
+     * `POST /sdk/chat` REST and would double-render as an `agent` bubble. Accept
+     * pushes in `waiting` / `human` / `closed` (late agent messages after close).
+     * Also dedupe against the last bubble: an `ai` bubble by content, an `agent`
+     * bubble by server id, so an agent can send the same text twice.
+     */
+    private handleMessageReceive;
+    submitIdentify(payload: IdentifyRequest): Promise<void>;
+    /**
+     * Escalate the open AI ticket to Unassigned. No-op unless the widget is in `ai` mode.
+     */
+    requestHuman(): Promise<void>;
     sendMessage(text: string): Promise<void>;
-    private loadHistory;
     on<K extends keyof ChatbotEventMap>(event: K, listener: Listener<K>): () => void;
     resetSession(): void;
     open(): void;
@@ -87,6 +147,8 @@ export declare interface ChatbotRequestError extends Error {
 
 export { ChatbotState }
 
+export { ChatbotTicketMode }
+
 export { ChatMessage }
 
 export { ChatRequest }
@@ -106,6 +168,12 @@ export declare class EventEmitter {
     removeAllListeners(): void;
 }
 
+export { IdentifyRequest }
+
+export { IdentifyResponseData }
+
+export declare function isChatbotRequestError(error: unknown): error is ChatbotRequestError;
+
 declare type Listener<K extends keyof ChatbotEventMap> = ChatbotEventMap[K] extends void ? () => void : (payload: ChatbotEventMap[K]) => void;
 
 declare type Listener_2<T> = T extends void ? () => void : (payload: T) => void;
@@ -115,15 +183,53 @@ export declare const OnedeskProChatbot: {
     getInstance(): ChatbotCore | null;
 };
 
+/**
+ * Strip any path/query/hash from an API base URL so Socket.IO connects to the
+ * server origin + `/sdk` namespace (not `/v1/sdk` if the REST client uses a path prefix).
+ */
+export declare function resolveSdkSocketUrl(baseUrl: string): string;
+
 export { SdkConfigResponse }
 
+/**
+ * Visitor Socket.IO helper for the dedicated `/sdk` namespace.
+ * Auth is handshake-only (`apiKey` + `visitorToken`); no BetterAuth session.
+ */
+export declare class SdkSocket {
+    private socket;
+    get connected(): boolean;
+    connect(opts: SdkSocketConnectOptions): void;
+    disconnect(): void;
+}
+
+export declare interface SdkSocketConnectOptions {
+    /** API base URL (may include a path prefix); origin is used for the `/sdk` namespace. */
+    baseUrl: string;
+    apiKey: string;
+    visitorToken: string;
+    onTicketStatus?: (payload: TicketStatusData) => void;
+    /** Raw inbox-shaped payload from `message:receive` (mapped in ChatbotCore later). */
+    onMessageReceive?: (payload: unknown) => void;
+    /**
+     * Fired on socket.io `connect` after the first successful connection
+     * (i.e. reconnect). Callers should re-fetch ticket status — no history backfill.
+     */
+    onReconnect?: () => void;
+    onConnectError?: (error: Error) => void;
+}
+
 export declare class SessionManager {
-    private sessionId;
-    init(providedSessionId?: string): string;
+    private token;
+    private storageKey;
+    /** Scope the token to an agent so multiple widgets on one origin stay isolated. */
+    setScope(agentId: string | null | undefined): void;
     get(): string | null;
-    reset(): string;
-    private persist;
-    private generateId;
+    set(token: string): void;
+    clear(): void;
 }
 
+export { TicketStatusData }
+
+export { VisitorVerifyResponse }
+
 export { }

package/dist/index.d.ts

@@ -4,10 +4,15 @@ import { ChatbotBlockReason } from '@onedeskpro/chatbot-types';
 import { ChatbotEventMap } from '@onedeskpro/chatbot-types';
 import { ChatbotInitOptions } from '@onedeskpro/chatbot-types';
 import { ChatbotState } from '@onedeskpro/chatbot-types';
+import { ChatbotTicketMode } from '@onedeskpro/chatbot-types';
 import { ChatMessage } from '@onedeskpro/chatbot-types';
 import { ChatRequest } from '@onedeskpro/chatbot-types';
 import { ChatResponseData } from '@onedeskpro/chatbot-types';
+import { IdentifyRequest } from '@onedeskpro/chatbot-types';
+import { IdentifyResponseData } from '@onedeskpro/chatbot-types';
 import { SdkConfigResponse } from '@onedeskpro/chatbot-types';
+import { TicketStatusData } from '@onedeskpro/chatbot-types';
+import { VisitorVerifyResponse } from '@onedeskpro/chatbot-types';
 
 export declare class ApiClient {
     private baseUrl;
@@ -16,9 +21,12 @@ export declare class ApiClient {
     constructor(options: ApiClientOptions);
     private fail;
     private request;
+    identify(payload: IdentifyRequest): Promise<IdentifyResponseData>;
+    verifyVisitor(visitorToken: string): Promise<VisitorVerifyResponse>;
     sendMessage(payload: ChatRequest): Promise<ChatResponseData>;
-    fetchHistory(sessionId: string): Promise<ChatMessage[]>;
     fetchConfig(): Promise<SdkConfigResponse>;
+    requestHuman(visitorToken: string): Promise<TicketStatusData>;
+    fetchTicketStatus(visitorToken: string): Promise<TicketStatusData>;
 }
 
 declare interface ApiClientOptions {
@@ -37,10 +45,22 @@ export { ChatbotBlockReason }
 export declare class ChatbotCore {
     private apiClient;
     private emitter;
-    private session;
+    private visitorTokens;
     private widget;
+    private sdkSocket;
     private options;
     private callerSetName;
+    /**
+     * True once this session has an open (or recently closed) ticket episode —
+     * from ticket-status `conversationId`, a non-ai mode, or a successful chat
+     * round-trip. Gates the request-human control so visitors cannot escalate
+     * before a ticket exists.
+     */
+    private hasActiveTicket;
+    /** Pending readiness re-check while the server is unreachable. */
+    private retryTimer;
+    /** Server id of the last `message:receive` push rendered as an agent bubble. */
+    private lastPushId;
     /**
      * Bumped by every init() and by destroy(). An async init compares the token it
      * started with against this before touching anything, so a superseded run — a
@@ -55,11 +75,51 @@ export declare class ChatbotCore {
      * everything — not just the transitions that have a dedicated event.
      */
     private setState;
+    private applyMode;
+    /** Derive ticket existence from status restore / socket pushes. */
+    private syncHasActiveTicket;
+    private syncWidgetMode;
     init(options: ChatbotInitOptions): Promise<void>;
-    /** Returns null on failure — a network blip must not block the user from trying. */
-    private fetchConfig;
+    /**
+     * Asks `/sdk/config` whether the server is up and the agent can reply, and
+     * shows the widget only when both hold. An unreachable server is retried on
+     * READINESS_RETRY_DELAYS_MS; a configuration problem is final for this page.
+     * `ready` fires once the outcome is settled either way.
+     */
+    private checkReadiness;
+    /** Creates the widget hidden; checkReadiness reveals it once every check passed. */
+    private mountWidget;
+    private clearRetry;
+    /**
+     * Maps `/sdk/config` rejections other than an unreachable server: missing
+     * Connected Channels becomes `no-agent`; anything else (an invalid key, a
+     * disallowed origin) is recorded as `state.error`.
+     */
+    private handleConfigError;
+    private resolveVisitorGate;
+    private enterChat;
+    private connectSdkSocket;
+    private disconnectSdkSocket;
+    /** Restore episode mode after identify / verify — never hydrates messages. */
+    private restoreTicketStatus;
+    private handleTicketStatus;
+    /**
+     * Live human (agent) pushes from `/sdk` `message:receive`.
+     *
+     * Choice: ignore while `mode === 'ai'`. Website outbound (including AI
+     * replies) is fanned out to the visitor room; AI text already arrives via
+     * `POST /sdk/chat` REST and would double-render as an `agent` bubble. Accept
+     * pushes in `waiting` / `human` / `closed` (late agent messages after close).
+     * Also dedupe against the last bubble: an `ai` bubble by content, an `agent`
+     * bubble by server id, so an agent can send the same text twice.
+     */
+    private handleMessageReceive;
+    submitIdentify(payload: IdentifyRequest): Promise<void>;
+    /**
+     * Escalate the open AI ticket to Unassigned. No-op unless the widget is in `ai` mode.
+     */
+    requestHuman(): Promise<void>;
     sendMessage(text: string): Promise<void>;
-    private loadHistory;
     on<K extends keyof ChatbotEventMap>(event: K, listener: Listener<K>): () => void;
     resetSession(): void;
     open(): void;
@@ -87,6 +147,8 @@ export declare interface ChatbotRequestError extends Error {
 
 export { ChatbotState }
 
+export { ChatbotTicketMode }
+
 export { ChatMessage }
 
 export { ChatRequest }
@@ -106,6 +168,12 @@ export declare class EventEmitter {
     removeAllListeners(): void;
 }
 
+export { IdentifyRequest }
+
+export { IdentifyResponseData }
+
+export declare function isChatbotRequestError(error: unknown): error is ChatbotRequestError;
+
 declare type Listener<K extends keyof ChatbotEventMap> = ChatbotEventMap[K] extends void ? () => void : (payload: ChatbotEventMap[K]) => void;
 
 declare type Listener_2<T> = T extends void ? () => void : (payload: T) => void;
@@ -115,15 +183,53 @@ export declare const OnedeskProChatbot: {
     getInstance(): ChatbotCore | null;
 };
 
+/**
+ * Strip any path/query/hash from an API base URL so Socket.IO connects to the
+ * server origin + `/sdk` namespace (not `/v1/sdk` if the REST client uses a path prefix).
+ */
+export declare function resolveSdkSocketUrl(baseUrl: string): string;
+
 export { SdkConfigResponse }
 
+/**
+ * Visitor Socket.IO helper for the dedicated `/sdk` namespace.
+ * Auth is handshake-only (`apiKey` + `visitorToken`); no BetterAuth session.
+ */
+export declare class SdkSocket {
+    private socket;
+    get connected(): boolean;
+    connect(opts: SdkSocketConnectOptions): void;
+    disconnect(): void;
+}
+
+export declare interface SdkSocketConnectOptions {
+    /** API base URL (may include a path prefix); origin is used for the `/sdk` namespace. */
+    baseUrl: string;
+    apiKey: string;
+    visitorToken: string;
+    onTicketStatus?: (payload: TicketStatusData) => void;
+    /** Raw inbox-shaped payload from `message:receive` (mapped in ChatbotCore later). */
+    onMessageReceive?: (payload: unknown) => void;
+    /**
+     * Fired on socket.io `connect` after the first successful connection
+     * (i.e. reconnect). Callers should re-fetch ticket status — no history backfill.
+     */
+    onReconnect?: () => void;
+    onConnectError?: (error: Error) => void;
+}
+
 export declare class SessionManager {
-    private sessionId;
-    init(providedSessionId?: string): string;
+    private token;
+    private storageKey;
+    /** Scope the token to an agent so multiple widgets on one origin stay isolated. */
+    setScope(agentId: string | null | undefined): void;
     get(): string | null;
-    reset(): string;
-    private persist;
-    private generateId;
+    set(token: string): void;
+    clear(): void;
 }
 
+export { TicketStatusData }
+
+export { VisitorVerifyResponse }
+
 export { }