@customerhero/js 0.0.1 → 1.0.0

package/dist/index.d.cts

@@ -1,5 +1,14 @@
-type TranslationKey = "online" | "typing" | "unable_to_load" | "powered_by" | "new_conversation" | "open_chat" | "close_chat" | "send_message" | "helpful" | "not_helpful" | "menu";
+type TranslationKey = "online" | "typing" | "unable_to_load" | "powered_by" | "new_conversation" | "open_chat" | "close_chat" | "send_message" | "helpful" | "not_helpful" | "menu" | "action_approve" | "action_cancel" | "action_what_will_happen" | "action_already_resolved" | "action_failed" | "status_sending" | "status_sent" | "status_failed" | "screenshot_capture" | "attachment_remove";
+type Translations = Record<TranslationKey, string>;
+
+declare const SUPPORTED_LOCALES: readonly ["en", "es", "pt-BR", "pt-PT", "fr", "de", "it", "nl", "pl", "tr", "ar", "ja", "ko", "zh-CN", "zh-TW"];
+type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
+declare function isRtlLocale(locale: string): boolean;
+declare function resolveLocale(locale: string | undefined): SupportedLocale;
+declare function detectLocale(explicit?: string): SupportedLocale;
+type StringOverrides = Partial<Record<TranslationKey, Partial<Record<string, string>>>>;
 type TranslateFn = (key: TranslationKey) => string;
+declare function createTranslator(locale: SupportedLocale, overrides?: StringOverrides): TranslateFn;
 
 interface CustomerHeroChatConfig {
     /** The chatbot ID to connect to */
@@ -27,6 +36,7 @@ interface CustomerHeroChatConfig {
     /** Predefined quick-reply options shown before the user sends a message */
     suggestedMessages?: string[];
 }
+
 interface ResolvedConfig {
     chatbotId: string;
     apiBase: string;
@@ -39,12 +49,53 @@ interface ResolvedConfig {
     title: string;
     avatarUrl?: string;
     suggestedMessages: string[];
+    /** Per-chatbot overrides for any translation key, optionally per-locale. */
+    stringOverrides?: StringOverrides;
 }
+interface MessageSource {
+    index: number;
+    title: string;
+    url?: string;
+    dataSourceId: string;
+    heading?: string;
+}
+type QuickRepliesBlock = {
+    type: "quick_replies";
+    options: string[];
+};
+type ActionConfirmationBlock = {
+    type: "action_confirmation";
+    pendingToolCallId: string;
+    actionName: string;
+    title: string;
+    summary: string;
+    approveHref: string;
+    cancelHref: string;
+};
+type MessageBlock = QuickRepliesBlock | ActionConfirmationBlock;
+type MessageStatus = "sending" | "sent" | "failed";
 interface ChatMessage {
     /** Message ID from the API (only present for bot messages) */
     id?: string;
     role: "user" | "bot";
     content: string;
+    /** Source citations referenced inline with `[n]` markers. Bot only. */
+    sources?: MessageSource[];
+    /** Structured blocks (quick-reply chips, etc.) rendered with the bubble. */
+    blocks?: MessageBlock[];
+    /**
+     * Follow-up questions the customer might plausibly ask next. Rendered as
+     * tappable chips under the most recent bot message only.
+     */
+    suggestions?: string[];
+    /** True while this message is still receiving streaming tokens. */
+    streaming?: boolean;
+    /**
+     * Local-only delivery status. User messages only — `sending` until the
+     * SSE `metadata` event lands, then `sent`. `failed` if the POST never
+     * reached the server. Bot messages use `streaming` instead.
+     */
+    status?: MessageStatus;
 }
 type MessageRating = "positive" | "negative";
 interface IdentifyPayload {
@@ -82,6 +133,10 @@ interface ChatState {
     configError: string | null;
     error: string | null;
     identity: IdentityData | null;
+    /** Active locale (one of `SUPPORTED_LOCALES`). */
+    locale: SupportedLocale;
+    /** True when the active locale is right-to-left. */
+    isRtl: boolean;
 }
 
 type Listener = (state: ChatState) => void;
@@ -91,15 +146,34 @@ declare class CustomerHeroChat {
     private storage;
     private userConfig;
     private identityData;
-    readonly t: TranslateFn;
+    t: TranslateFn;
     constructor(config: CustomerHeroChatConfig);
+    setLocale(tag: string): void;
+    private rebuildTranslator;
     subscribe(listener: Listener): () => void;
     getState(): ChatState;
     private setState;
+    private patchLastMessage;
     private notifyListeners;
     fetchConfig(): Promise<void>;
     private loadHistory;
-    sendMessage(message: string): Promise<void>;
+    sendMessage(message: string, options?: {
+        attachmentTokens?: string[];
+    }): Promise<void>;
+    uploadAttachment(blob: Blob, options?: {
+        filename?: string;
+    }): Promise<{
+        attachmentToken: string;
+        previewUrl: string;
+        expiresAt: string;
+    }>;
+    approveAction(pendingId: string): Promise<void>;
+    cancelAction(pendingId: string): Promise<void>;
+    private sendDecision;
+    private findActionConfirmationMessageIndex;
+    private patchMessageAt;
+    private appendToMessageAt;
+    private appendBlockToMessageAt;
     rateMessage(messageId: string, rating: MessageRating): Promise<void>;
     toggle(): void;
     open(): void;
@@ -119,4 +193,13 @@ declare const DEFAULTS: {
     title: string;
 };
 
-export { type ChatMessage, type ChatState, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type MessageRating, type ResolvedConfig, type TranslateFn, type TranslationKey };
+declare class ScreenshotCancelled extends Error {
+    constructor(message?: string);
+}
+declare class ScreenshotUnavailable extends Error {
+    constructor(message?: string);
+}
+declare function canCaptureScreenshot(): boolean;
+declare function captureScreenshot(): Promise<Blob>;
+
+export { type ActionConfirmationBlock, type ChatMessage, type ChatState, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type MessageBlock, type MessageRating, type MessageSource, type MessageStatus, type QuickRepliesBlock, type ResolvedConfig, SUPPORTED_LOCALES, ScreenshotCancelled, ScreenshotUnavailable, type StringOverrides, type SupportedLocale, type TranslateFn, type TranslationKey, type Translations, canCaptureScreenshot, captureScreenshot, createTranslator, detectLocale, isRtlLocale, resolveLocale };

package/dist/index.d.ts

@@ -1,5 +1,14 @@
-type TranslationKey = "online" | "typing" | "unable_to_load" | "powered_by" | "new_conversation" | "open_chat" | "close_chat" | "send_message" | "helpful" | "not_helpful" | "menu";
+type TranslationKey = "online" | "typing" | "unable_to_load" | "powered_by" | "new_conversation" | "open_chat" | "close_chat" | "send_message" | "helpful" | "not_helpful" | "menu" | "action_approve" | "action_cancel" | "action_what_will_happen" | "action_already_resolved" | "action_failed" | "status_sending" | "status_sent" | "status_failed" | "screenshot_capture" | "attachment_remove";
+type Translations = Record<TranslationKey, string>;
+
+declare const SUPPORTED_LOCALES: readonly ["en", "es", "pt-BR", "pt-PT", "fr", "de", "it", "nl", "pl", "tr", "ar", "ja", "ko", "zh-CN", "zh-TW"];
+type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
+declare function isRtlLocale(locale: string): boolean;
+declare function resolveLocale(locale: string | undefined): SupportedLocale;
+declare function detectLocale(explicit?: string): SupportedLocale;
+type StringOverrides = Partial<Record<TranslationKey, Partial<Record<string, string>>>>;
 type TranslateFn = (key: TranslationKey) => string;
+declare function createTranslator(locale: SupportedLocale, overrides?: StringOverrides): TranslateFn;
 
 interface CustomerHeroChatConfig {
     /** The chatbot ID to connect to */
@@ -27,6 +36,7 @@ interface CustomerHeroChatConfig {
     /** Predefined quick-reply options shown before the user sends a message */
     suggestedMessages?: string[];
 }
+
 interface ResolvedConfig {
     chatbotId: string;
     apiBase: string;
@@ -39,12 +49,53 @@ interface ResolvedConfig {
     title: string;
     avatarUrl?: string;
     suggestedMessages: string[];
+    /** Per-chatbot overrides for any translation key, optionally per-locale. */
+    stringOverrides?: StringOverrides;
 }
+interface MessageSource {
+    index: number;
+    title: string;
+    url?: string;
+    dataSourceId: string;
+    heading?: string;
+}
+type QuickRepliesBlock = {
+    type: "quick_replies";
+    options: string[];
+};
+type ActionConfirmationBlock = {
+    type: "action_confirmation";
+    pendingToolCallId: string;
+    actionName: string;
+    title: string;
+    summary: string;
+    approveHref: string;
+    cancelHref: string;
+};
+type MessageBlock = QuickRepliesBlock | ActionConfirmationBlock;
+type MessageStatus = "sending" | "sent" | "failed";
 interface ChatMessage {
     /** Message ID from the API (only present for bot messages) */
     id?: string;
     role: "user" | "bot";
     content: string;
+    /** Source citations referenced inline with `[n]` markers. Bot only. */
+    sources?: MessageSource[];
+    /** Structured blocks (quick-reply chips, etc.) rendered with the bubble. */
+    blocks?: MessageBlock[];
+    /**
+     * Follow-up questions the customer might plausibly ask next. Rendered as
+     * tappable chips under the most recent bot message only.
+     */
+    suggestions?: string[];
+    /** True while this message is still receiving streaming tokens. */
+    streaming?: boolean;
+    /**
+     * Local-only delivery status. User messages only — `sending` until the
+     * SSE `metadata` event lands, then `sent`. `failed` if the POST never
+     * reached the server. Bot messages use `streaming` instead.
+     */
+    status?: MessageStatus;
 }
 type MessageRating = "positive" | "negative";
 interface IdentifyPayload {
@@ -82,6 +133,10 @@ interface ChatState {
     configError: string | null;
     error: string | null;
     identity: IdentityData | null;
+    /** Active locale (one of `SUPPORTED_LOCALES`). */
+    locale: SupportedLocale;
+    /** True when the active locale is right-to-left. */
+    isRtl: boolean;
 }
 
 type Listener = (state: ChatState) => void;
@@ -91,15 +146,34 @@ declare class CustomerHeroChat {
     private storage;
     private userConfig;
     private identityData;
-    readonly t: TranslateFn;
+    t: TranslateFn;
     constructor(config: CustomerHeroChatConfig);
+    setLocale(tag: string): void;
+    private rebuildTranslator;
     subscribe(listener: Listener): () => void;
     getState(): ChatState;
     private setState;
+    private patchLastMessage;
     private notifyListeners;
     fetchConfig(): Promise<void>;
     private loadHistory;
-    sendMessage(message: string): Promise<void>;
+    sendMessage(message: string, options?: {
+        attachmentTokens?: string[];
+    }): Promise<void>;
+    uploadAttachment(blob: Blob, options?: {
+        filename?: string;
+    }): Promise<{
+        attachmentToken: string;
+        previewUrl: string;
+        expiresAt: string;
+    }>;
+    approveAction(pendingId: string): Promise<void>;
+    cancelAction(pendingId: string): Promise<void>;
+    private sendDecision;
+    private findActionConfirmationMessageIndex;
+    private patchMessageAt;
+    private appendToMessageAt;
+    private appendBlockToMessageAt;
     rateMessage(messageId: string, rating: MessageRating): Promise<void>;
     toggle(): void;
     open(): void;
@@ -119,4 +193,13 @@ declare const DEFAULTS: {
     title: string;
 };
 
-export { type ChatMessage, type ChatState, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type MessageRating, type ResolvedConfig, type TranslateFn, type TranslationKey };
+declare class ScreenshotCancelled extends Error {
+    constructor(message?: string);
+}
+declare class ScreenshotUnavailable extends Error {
+    constructor(message?: string);
+}
+declare function canCaptureScreenshot(): boolean;
+declare function captureScreenshot(): Promise<Blob>;
+
+export { type ActionConfirmationBlock, type ChatMessage, type ChatState, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type MessageBlock, type MessageRating, type MessageSource, type MessageStatus, type QuickRepliesBlock, type ResolvedConfig, SUPPORTED_LOCALES, ScreenshotCancelled, ScreenshotUnavailable, type StringOverrides, type SupportedLocale, type TranslateFn, type TranslationKey, type Translations, canCaptureScreenshot, captureScreenshot, createTranslator, detectLocale, isRtlLocale, resolveLocale };