@onedeskpro/chatbot-core 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,29 +1,36 @@
 import { ApiError } from '@onedeskpro/chatbot-types';
 import { ApiResponse } from '@onedeskpro/chatbot-types';
+import { ChatAttachment } from '@onedeskpro/chatbot-types';
 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 { ChatMessageKind } 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 { UploadAttachmentResponseData } from '@onedeskpro/chatbot-types';
 import { VisitorVerifyResponse } from '@onedeskpro/chatbot-types';
+import { VoiceRecording } from '@onedeskpro/chatbot-types';
 
 export declare class ApiClient {
     private baseUrl;
     private apiKey;
     private timeoutMs;
+    private uploadTimeoutMs;
     constructor(options: ApiClientOptions);
     private fail;
     private request;
     identify(payload: IdentifyRequest): Promise<IdentifyResponseData>;
     verifyVisitor(visitorToken: string): Promise<VisitorVerifyResponse>;
     sendMessage(payload: ChatRequest): Promise<ChatResponseData>;
+    /** Uploads one file for a media message; the result goes into `ChatRequest.attachments`. */
+    uploadAttachment(file: File, visitorToken: string): Promise<UploadAttachmentResponseData>;
     fetchConfig(): Promise<SdkConfigResponse>;
     requestHuman(visitorToken: string): Promise<TicketStatusData>;
     fetchTicketStatus(visitorToken: string): Promise<TicketStatusData>;
@@ -34,12 +41,16 @@ declare interface ApiClientOptions {
     apiKey: string;
     /** Abort a request that has not responded within this many milliseconds. */
     timeoutMs?: number;
+    /** Abort a file upload that has not completed within this many milliseconds. */
+    uploadTimeoutMs?: number;
 }
 
 export { ApiError }
 
 export { ApiResponse }
 
+export { ChatAttachment }
+
 export { ChatbotBlockReason }
 
 export declare class ChatbotCore {
@@ -57,6 +68,8 @@ export declare class ChatbotCore {
      * 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;
     /**
@@ -79,8 +92,19 @@ export declare class ChatbotCore {
     private syncWidgetMode;
     init(options: ChatbotInitOptions): Promise<void>;
     /**
-     * Maps `/sdk/config` failures: missing Connected Channels becomes `no-agent`,
-     * other 403s show the API message, and 401/network stay as `state.error`.
+     * 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;
@@ -106,7 +130,42 @@ export declare class ChatbotCore {
      * Escalate the open AI ticket to Unassigned. No-op unless the widget is in `ai` mode.
      */
     requestHuman(): Promise<void>;
+    /** The visitor token every send needs; throws when the visitor has not identified. */
+    private requireVisitorToken;
+    /** Adds the visitor's own message optimistically and marks a send in flight. */
+    private pushLocalMessage;
+    private replaceMessage;
+    private removeMessage;
     sendMessage(text: string): Promise<void>;
+    /** Records a send that never left the browser: `state.error`, the composer, and `error`. */
+    private rejectSend;
+    /**
+     * Sends `files` as one media message, with `text` as its caption. The bubble
+     * appears at once with local previews, uploads each file through the API, then
+     * posts the chat message the same way `sendMessage` does. Rejects when the visitor
+     * has not identified; a file that breaks the size or count limit is reported as
+     * `state.error` (and an `error` event) without sending anything.
+     */
+    sendAttachments(files: File[], text?: string): Promise<void>;
+    /**
+     * Sends a recorded voice note (from `VoiceRecorder` or your own recorder). The
+     * recording is re-encoded as mono WAV with a waveform where Web Audio allows,
+     * uploaded, and posted as a `voice` message so the inbox shows its voice player.
+     * Rejects when the visitor has not identified; an unusable or oversized recording is
+     * reported as `state.error` (and an `error` event) without sending anything.
+     */
+    sendVoice(recording: VoiceRecording): Promise<void>;
+    /**
+     * Shared tail of every file send: an optimistic `pending` bubble with local previews,
+     * one upload per file, then `deliver`. A failed upload removes the bubble; a failed
+     * chat post keeps it (the files are already stored) and records the error.
+     */
+    private uploadThenDeliver;
+    /**
+     * Posts `payload` to `/sdk/chat` and applies the outcome: the ticket now exists,
+     * the mode may have moved, and in `ai` mode the reply becomes a bubble.
+     */
+    private deliver;
     on<K extends keyof ChatbotEventMap>(event: K, listener: Listener<K>): () => void;
     resetSession(): void;
     open(): void;
@@ -138,6 +197,8 @@ export { ChatbotTicketMode }
 
 export { ChatMessage }
 
+export { ChatMessageKind }
+
 export { ChatRequest }
 
 export { ChatResponseData }
@@ -176,6 +237,12 @@ export declare const OnedeskProChatbot: {
  */
 export declare function resolveSdkSocketUrl(baseUrl: string): string;
 
+/** Most attachments one chat message may carry. */
+export declare const SDK_CHAT_MAX_ATTACHMENTS = 10;
+
+/** Largest file `POST /sdk/upload` accepts, in bytes (10 MB). */
+export declare const SDK_UPLOAD_MAX_BYTES: number;
+
 export { SdkConfigResponse }
 
 /**
@@ -217,6 +284,62 @@ export declare class SessionManager {
 
 export { TicketStatusData }
 
+export { UploadAttachmentResponseData }
+
 export { VisitorVerifyResponse }
 
+/** Longest voice note the widget records before stopping on its own. */
+export declare const VOICE_MAX_DURATION_SECONDS = 300;
+
+/**
+ * Records a voice note with `MediaRecorder`. Framework-independent: the widget uses it,
+ * and custom UIs built on `ChatbotCore` can too. `destroy()` releases the microphone,
+ * timers and audio context; nothing is left running once it returns.
+ */
+export declare class VoiceRecorder {
+    private readonly onChange;
+    private readonly maxDurationSeconds;
+    private recorder;
+    private stream;
+    private chunks;
+    private mimeType;
+    private startedAt;
+    private tickTimer;
+    private levelTimer;
+    private maxTimer;
+    private audioContext;
+    private analyser;
+    private snapshot;
+    constructor(onChange: (snapshot: VoiceRecorderSnapshot) => void, maxDurationSeconds?: number);
+    static isSupported(): boolean;
+    getSnapshot(): VoiceRecorderSnapshot;
+    /** Asks for the microphone and starts recording. Rejects with a visitor-facing message. */
+    start(): Promise<void>;
+    /** Stops recording and moves to `preview`. Resolves with the recording, or null if none. */
+    stop(): Promise<VoiceRecording | null>;
+    /** Discards the recording (or the one in preview) and returns to `idle`. */
+    cancel(): void;
+    destroy(): void;
+    private update;
+    private elapsedMs;
+    private startLevelMeter;
+    private clearTimers;
+    private releaseMedia;
+    private release;
+}
+
+export declare interface VoiceRecorderSnapshot {
+    state: VoiceRecorderState;
+    /** Whole seconds recorded so far (or the final length in `preview`). */
+    elapsedSeconds: number;
+    /** Microphone loudness 0–1 while recording, 0 otherwise. */
+    level: number;
+    /** The finished recording while in `preview`. */
+    result: VoiceRecording | null;
+}
+
+export declare type VoiceRecorderState = 'idle' | 'recording' | 'preview';
+
+export { VoiceRecording }
+
 export { }

package/dist/index.d.ts

@@ -1,29 +1,36 @@
 import { ApiError } from '@onedeskpro/chatbot-types';
 import { ApiResponse } from '@onedeskpro/chatbot-types';
+import { ChatAttachment } from '@onedeskpro/chatbot-types';
 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 { ChatMessageKind } 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 { UploadAttachmentResponseData } from '@onedeskpro/chatbot-types';
 import { VisitorVerifyResponse } from '@onedeskpro/chatbot-types';
+import { VoiceRecording } from '@onedeskpro/chatbot-types';
 
 export declare class ApiClient {
     private baseUrl;
     private apiKey;
     private timeoutMs;
+    private uploadTimeoutMs;
     constructor(options: ApiClientOptions);
     private fail;
     private request;
     identify(payload: IdentifyRequest): Promise<IdentifyResponseData>;
     verifyVisitor(visitorToken: string): Promise<VisitorVerifyResponse>;
     sendMessage(payload: ChatRequest): Promise<ChatResponseData>;
+    /** Uploads one file for a media message; the result goes into `ChatRequest.attachments`. */
+    uploadAttachment(file: File, visitorToken: string): Promise<UploadAttachmentResponseData>;
     fetchConfig(): Promise<SdkConfigResponse>;
     requestHuman(visitorToken: string): Promise<TicketStatusData>;
     fetchTicketStatus(visitorToken: string): Promise<TicketStatusData>;
@@ -34,12 +41,16 @@ declare interface ApiClientOptions {
     apiKey: string;
     /** Abort a request that has not responded within this many milliseconds. */
     timeoutMs?: number;
+    /** Abort a file upload that has not completed within this many milliseconds. */
+    uploadTimeoutMs?: number;
 }
 
 export { ApiError }
 
 export { ApiResponse }
 
+export { ChatAttachment }
+
 export { ChatbotBlockReason }
 
 export declare class ChatbotCore {
@@ -57,6 +68,8 @@ export declare class ChatbotCore {
      * 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;
     /**
@@ -79,8 +92,19 @@ export declare class ChatbotCore {
     private syncWidgetMode;
     init(options: ChatbotInitOptions): Promise<void>;
     /**
-     * Maps `/sdk/config` failures: missing Connected Channels becomes `no-agent`,
-     * other 403s show the API message, and 401/network stay as `state.error`.
+     * 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;
@@ -106,7 +130,42 @@ export declare class ChatbotCore {
      * Escalate the open AI ticket to Unassigned. No-op unless the widget is in `ai` mode.
      */
     requestHuman(): Promise<void>;
+    /** The visitor token every send needs; throws when the visitor has not identified. */
+    private requireVisitorToken;
+    /** Adds the visitor's own message optimistically and marks a send in flight. */
+    private pushLocalMessage;
+    private replaceMessage;
+    private removeMessage;
     sendMessage(text: string): Promise<void>;
+    /** Records a send that never left the browser: `state.error`, the composer, and `error`. */
+    private rejectSend;
+    /**
+     * Sends `files` as one media message, with `text` as its caption. The bubble
+     * appears at once with local previews, uploads each file through the API, then
+     * posts the chat message the same way `sendMessage` does. Rejects when the visitor
+     * has not identified; a file that breaks the size or count limit is reported as
+     * `state.error` (and an `error` event) without sending anything.
+     */
+    sendAttachments(files: File[], text?: string): Promise<void>;
+    /**
+     * Sends a recorded voice note (from `VoiceRecorder` or your own recorder). The
+     * recording is re-encoded as mono WAV with a waveform where Web Audio allows,
+     * uploaded, and posted as a `voice` message so the inbox shows its voice player.
+     * Rejects when the visitor has not identified; an unusable or oversized recording is
+     * reported as `state.error` (and an `error` event) without sending anything.
+     */
+    sendVoice(recording: VoiceRecording): Promise<void>;
+    /**
+     * Shared tail of every file send: an optimistic `pending` bubble with local previews,
+     * one upload per file, then `deliver`. A failed upload removes the bubble; a failed
+     * chat post keeps it (the files are already stored) and records the error.
+     */
+    private uploadThenDeliver;
+    /**
+     * Posts `payload` to `/sdk/chat` and applies the outcome: the ticket now exists,
+     * the mode may have moved, and in `ai` mode the reply becomes a bubble.
+     */
+    private deliver;
     on<K extends keyof ChatbotEventMap>(event: K, listener: Listener<K>): () => void;
     resetSession(): void;
     open(): void;
@@ -138,6 +197,8 @@ export { ChatbotTicketMode }
 
 export { ChatMessage }
 
+export { ChatMessageKind }
+
 export { ChatRequest }
 
 export { ChatResponseData }
@@ -176,6 +237,12 @@ export declare const OnedeskProChatbot: {
  */
 export declare function resolveSdkSocketUrl(baseUrl: string): string;
 
+/** Most attachments one chat message may carry. */
+export declare const SDK_CHAT_MAX_ATTACHMENTS = 10;
+
+/** Largest file `POST /sdk/upload` accepts, in bytes (10 MB). */
+export declare const SDK_UPLOAD_MAX_BYTES: number;
+
 export { SdkConfigResponse }
 
 /**
@@ -217,6 +284,62 @@ export declare class SessionManager {
 
 export { TicketStatusData }
 
+export { UploadAttachmentResponseData }
+
 export { VisitorVerifyResponse }
 
+/** Longest voice note the widget records before stopping on its own. */
+export declare const VOICE_MAX_DURATION_SECONDS = 300;
+
+/**
+ * Records a voice note with `MediaRecorder`. Framework-independent: the widget uses it,
+ * and custom UIs built on `ChatbotCore` can too. `destroy()` releases the microphone,
+ * timers and audio context; nothing is left running once it returns.
+ */
+export declare class VoiceRecorder {
+    private readonly onChange;
+    private readonly maxDurationSeconds;
+    private recorder;
+    private stream;
+    private chunks;
+    private mimeType;
+    private startedAt;
+    private tickTimer;
+    private levelTimer;
+    private maxTimer;
+    private audioContext;
+    private analyser;
+    private snapshot;
+    constructor(onChange: (snapshot: VoiceRecorderSnapshot) => void, maxDurationSeconds?: number);
+    static isSupported(): boolean;
+    getSnapshot(): VoiceRecorderSnapshot;
+    /** Asks for the microphone and starts recording. Rejects with a visitor-facing message. */
+    start(): Promise<void>;
+    /** Stops recording and moves to `preview`. Resolves with the recording, or null if none. */
+    stop(): Promise<VoiceRecording | null>;
+    /** Discards the recording (or the one in preview) and returns to `idle`. */
+    cancel(): void;
+    destroy(): void;
+    private update;
+    private elapsedMs;
+    private startLevelMeter;
+    private clearTimers;
+    private releaseMedia;
+    private release;
+}
+
+export declare interface VoiceRecorderSnapshot {
+    state: VoiceRecorderState;
+    /** Whole seconds recorded so far (or the final length in `preview`). */
+    elapsedSeconds: number;
+    /** Microphone loudness 0–1 while recording, 0 otherwise. */
+    level: number;
+    /** The finished recording while in `preview`. */
+    result: VoiceRecording | null;
+}
+
+export declare type VoiceRecorderState = 'idle' | 'recording' | 'preview';
+
+export { VoiceRecording }
+
 export { }