@developer.notchatbot/webchat 1.6.0 → 2.0.0

package/README.md

@@ -1,5 +1,7 @@
 # 🔷 WebChat - Embedded Chat
 
+Webchat 2.0.0 uses origin-bound visitor credentials and requires the matching NotChatbot backend and Cloudflare presence service. See [the rollout guide](../next/apps/next/docs/webchat-v2-rollout.md) before upgrading an existing install.
+
 ## 📦 Quick Start
 
 ### 1. Add the widget to your website
@@ -44,6 +46,8 @@ interface WebChatConfig {
     active?: boolean;                   // Enable or disable the button (default: true)
     color?: string;                     // Customize the internal WhatsApp button color
   };
+  apiBaseUrl?: string;                  // Backend override (see "Targeting a non-production backend")
+  realtimeUrl?: string;                 // Convex deployment override (same section)
 }
 
 interface WebChatPositionConfig {
@@ -85,6 +89,33 @@ WebChat.initialize({
 });
 ```
 
+## 🎯 Targeting a non-production backend
+
+By default the widget picks its backend from the hostname of the page it runs
+on: `localhost` → `http://localhost:3000`, anything else → production
+(`https://next.notchatbot.com`). That default is right for a merchant's
+storefront, but wrong wherever the page itself is a non-production deployment —
+a Vercel preview, `dev.notchatbot.com`, or a local dev server on a port other
+than 3000. Without an override, a message typed on a preview lands in the
+**production** inbox.
+
+`apiBaseUrl` and `realtimeUrl` override that detection:
+
+```js
+WebChat.initialize({
+    apiKey: "your-chatbot-uid",
+    apiBaseUrl: window.location.origin,          // HTTP: /api/webchat, /upload, /rate
+    realtimeUrl: "https://<deployment>.convex.cloud" // Convex realtime subscriptions
+});
+```
+
+- Both must be `https://` (or `http://localhost` / `http://127.0.0.1`); anything
+  else is ignored with a console warning and the defaults are kept.
+- **Set them as a pair.** `apiBaseUrl` alone writes to one deployment while the
+  widget keeps listening on the default Convex, so agent replies never arrive.
+- Omitting them keeps the previous behaviour exactly — existing embeds are
+  unaffected, and each `initialize()` clears any override from a prior call.
+
 # 💬 WhatsApp Button
 
 If you simply want a floating WhatsApp action button with no WebChat, you can use `WhatsAppButtonAPI`, which isolates itself in the Shadow DOM to avoid CSS conflicts.

package/dist/components/ChatBot.d.ts

@@ -1,6 +1,5 @@
-import { default as React } from 'react';
 import { ChatBotProps } from '../types';
-declare const ChatBot: React.FC<ChatBotProps & {
-    exposeControl?: (api: any) => void;
-}>;
+declare const ChatBot: ({ config, exposeControl }: ChatBotProps & {
+    exposeControl?: (api: Record<string, unknown>) => void;
+}) => import("react/jsx-runtime").JSX.Element | null;
 export default ChatBot;

package/dist/components/ContactCapture.d.ts

@@ -0,0 +1,7 @@
+interface Props {
+    uid: string;
+    conversationId?: string;
+}
+/** Save intentional contact edits after a pause; passive identity hints never authorize follow-up. */
+export declare function ContactCapture({ uid, conversationId }: Props): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/MessageActions.d.ts

@@ -0,0 +1,8 @@
+export default function MessageActions({ anchor, selectionMode, reaction, onReact, onReply, onClose }: {
+    selectionMode?: boolean;
+    anchor: HTMLElement;
+    reaction?: string | null;
+    onReact?: (emoji: string | null) => void;
+    onReply?: () => void;
+    onClose: () => void;
+}): import('react').ReactPortal;

package/dist/components/MessageAlertSettings.d.ts

@@ -0,0 +1,5 @@
+import { MessageAlertControls } from '../hooks/useMessageAlerts';
+/** Customer-controlled alert preferences. Opening this menu never requests browser permission. */
+export default function MessageAlertSettings({ controls }: {
+    controls: MessageAlertControls;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/MessageSelectionActions.d.ts

@@ -0,0 +1,4 @@
+export default function MessageSelectionActions({ onReply, onCancel }: {
+    onReply: () => void;
+    onCancel: () => void;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/ReplyQuote.d.ts

@@ -0,0 +1,8 @@
+import { Message } from '../types';
+export declare const quoteName: (message: Message) => string;
+export declare const quoteText: (message: Pick<Message, "type" | "text">) => string;
+export default function ReplyQuote({ message, onClick, textColor }: {
+    message: Message;
+    onClick?: () => void;
+    textColor?: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/UnreadMessagePreview.d.ts

@@ -0,0 +1,15 @@
+import { Message } from '../types';
+interface Props {
+    messages: Message[];
+    isStaffTyping?: boolean;
+    staffTypingAuthor?: Message["author"];
+    title: string;
+    avatar?: string;
+    position: 'bottom-left' | 'bottom-right';
+    marginBottom: number;
+    marginSide: number;
+    onOpen: () => void;
+}
+/** Real unread replies in transcript order. Previewing or dismissing never sends viewed receipts. */
+export default function UnreadMessagePreview({ messages, isStaffTyping, staffTypingAuthor, title, avatar, position, marginBottom, marginSide, onOpen }: Props): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/embedchat/EmbedChat.d.ts

@@ -1,4 +1,8 @@
-import { default as React } from 'react';
 import { EmbedChatProps } from '../../types';
-declare const EmbedChat: React.FC<EmbedChatProps>;
+declare const EmbedChat: ({ config, exposeControl }: EmbedChatProps & {
+    exposeControl?: (api: {
+        restart: () => void;
+        identify: (hint: import('../../utils/storefront-identity').CustomerHint) => void;
+    }) => void;
+}) => import("react/jsx-runtime").JSX.Element | null;
 export default EmbedChat;

package/dist/config/endpoints.d.ts

@@ -2,9 +2,17 @@ export interface EndpointConfig {
     baseUrl: string;
     chatEndpoint: string;
     uploadEndpoint: string;
-    rateEndpoint: string;
     realtimeUrl: string;
 }
+/**
+ * Replaces the endpoint overrides. Called on every `initialize()`, so a config
+ * without these keys clears any previous override. Invalid URLs are ignored
+ * with a warning and the environment defaults are kept.
+ */
+export declare function setEndpointOverrides(overrides: {
+    apiBaseUrl?: string;
+    realtimeUrl?: string;
+}): void;
 /**
  * Detecta si estamos en ambiente de desarrollo
  */
@@ -21,10 +29,6 @@ export declare function getChatEndpoint(): string;
  * Obtiene el endpoint de upload
  */
 export declare function getUploadEndpoint(): string;
-/**
- * Obtiene el endpoint de rating
- */
-export declare function getRateEndpoint(): string;
 /**
  * Obtiene la URL base según el ambiente
  */

package/dist/hooks/useMessageAlerts.d.ts

@@ -0,0 +1,11 @@
+import { Message } from '../types';
+export interface MessageAlertControls {
+    soundEnabled: boolean;
+    toggleSound: () => void;
+    notificationsEnabled: boolean;
+    notificationsSupported: boolean;
+    permission: NotificationPermission | 'unsupported';
+    toggleNotifications: () => Promise<void>;
+}
+/** Alerts use the existing unread feed; old history, typing and duplicate snapshots remain silent. */
+export declare function useMessageAlerts(uid: string, conversationId: string | undefined, messages: Message[], unreadCount: number, isOpen: boolean, title: string, onOpen: () => void): MessageAlertControls;

package/dist/hooks/useMessageGesture.d.ts

@@ -0,0 +1,14 @@
+import { default as React } from 'react';
+export declare function useMessageGesture(enabled: boolean, onReply: () => void, onHold: (touch: boolean) => void): {
+    offset: number;
+    gestures: {
+        onPointerDown: (event: React.PointerEvent<HTMLDivElement>) => void;
+        onPointerMove: (event: React.PointerEvent) => void;
+        onPointerUp: (event: React.PointerEvent) => void;
+        onPointerCancel: () => void;
+        onLostPointerCapture: () => void;
+        onClickCapture: (event: React.MouseEvent) => void;
+        onKeyDown: (event: React.KeyboardEvent) => void;
+        onContextMenu: (event: React.MouseEvent) => void;
+    };
+};

package/dist/hooks/useTeamAvailability.d.ts

@@ -0,0 +1,2 @@
+/** Before engagement, an open widget reads only a cached anonymous edge boolean. */
+export declare function useTeamAvailability(uid: string, open: boolean, engaged: boolean, liveOnline: boolean): boolean;

package/dist/hooks/useVisitorChat.d.ts

@@ -0,0 +1,48 @@
+import { VisitorSession } from '../utils/visitor-session';
+import { Transcript } from '../utils/transcript';
+import { FileWithBlobUrl, Message, WebChatConfig } from '../types';
+import { CustomerHint } from '../utils/storefront-identity';
+interface PendingSend {
+    createdAt?: string;
+    requestId: string;
+    conversationId: string;
+    chatbotUid: string;
+    newMessages: Array<{
+        id: string;
+        role: 'user';
+        content: string;
+        type: string;
+        metaContent?: string;
+        replyToId?: string;
+    }>;
+    currentUrl: string;
+}
+/** Owns the visitor lifecycle shared by floating and embedded chat surfaces. */
+export declare function useVisitorChat(config: WebChatConfig, isOpen: boolean): {
+    react: (messageId: string, emoji: string | null) => Promise<boolean>;
+    teamOnline: boolean;
+    staffTypingAuthor: {
+        name: string;
+        avatarUrl?: string;
+    } | undefined;
+    staffTyping: boolean;
+    unreadMessages: Message[];
+    unreadMessage: Message;
+    session: VisitorSession | null;
+    draftRevision: number;
+    messages: Message[];
+    sending: boolean;
+    error: string;
+    unread: boolean;
+    unreadCount: number;
+    state: Partial<Transcript>;
+    connected: boolean;
+    pending: PendingSend;
+    send: (text: string, files?: FileWithBlobUrl[], replyTo?: Message) => false | Promise<boolean | undefined>;
+    restart: (forgetContact?: boolean) => void;
+    viewed: (ids: string[]) => void;
+    typing: (active: boolean) => void | undefined;
+    identify: (hint: CustomerHint) => void;
+    retry: () => void;
+};
+export {};

package/dist/types.d.ts

@@ -5,6 +5,10 @@ export interface WebChatPositionConfig {
     showPopup?: boolean;
 }
 export interface WebChatConfig {
+    active?: boolean;
+    quickReplies?: string[];
+    contactCapture?: boolean;
+    identityEndpoint?: string;
     elementId: string;
     title?: string;
     placeholder?: string;
@@ -25,6 +29,22 @@ export interface WebChatConfig {
     whatsapp?: Omit<WhatsAppConfig, 'position' | 'marginBottom' | 'marginSide' | 'mobile' | 'desktop'> & {
         active?: boolean;
     };
+    /**
+     * Optional backend base URL override (e.g. a Vercel preview deployment or
+     * dev.notchatbot.com). `/api/webchat`, `/api/webchat/upload` and
+     * `/api/webchat/conversation/rate` are derived from it. Must be https://
+     * (or http://localhost). Omitted or invalid → the environment defaults.
+     */
+    apiBaseUrl?: string;
+    /**
+     * Optional Convex deployment URL override for the realtime subscriptions
+     * (agent replies, history, activation). Must be https:// (or
+     * http://localhost). Omitted or invalid → the environment default.
+     *
+     * Pair it with `apiBaseUrl`: pointing HTTP at one deployment and realtime at
+     * another means the widget writes to one database and listens on another.
+     */
+    realtimeUrl?: string;
     /**
      * Optional GTM/GA event name overrides for dataLayer pushes.
      * If omitted, defaults are used.
@@ -42,6 +62,11 @@ export interface EmbedChatInputConfig {
     iconColor?: string;
 }
 export interface EmbedChatConfig {
+    apiBaseUrl?: string;
+    realtimeUrl?: string;
+    contactCapture?: boolean;
+    quickReplies?: string[];
+    identityEndpoint?: string;
     elementId: string;
     title?: string;
     placeholder?: string;
@@ -79,14 +104,28 @@ export interface EmbedChatProps {
     config: EmbedChatConfig;
 }
 export interface EmbedChatWindowProps {
+    onReact?: (messageId: string, emoji: string | null) => Promise<boolean>;
+    alertSettings?: React.ReactNode;
+    onTyping?: (active: boolean) => void;
+    contactMessage?: React.ReactNode;
+    children?: React.ReactNode;
+    onViewed?: (ids: string[]) => void;
+    sending?: boolean;
+    draftRevision?: number;
     config: EmbedChatConfig;
     messages: Message[];
-    onSendMessage: (message: string, files?: FileWithBlobUrl[]) => void;
+    onSendMessage: (message: string, files?: FileWithBlobUrl[], replyTo?: Message) => void | boolean | Promise<void | boolean>;
     isLoading?: boolean;
     isAiTyping?: boolean;
+    teamOnline?: boolean;
+    isStaffTyping?: boolean;
+    staffTypingAuthor?: Message["author"];
     chatbotActivated?: boolean;
 }
 export interface EmbedChatHeaderProps {
+    selectionActions?: React.ReactNode;
+    teamOnline?: boolean;
+    alertSettings?: React.ReactNode;
     title: string;
     primaryColor?: string;
     avatar?: string;
@@ -97,12 +136,29 @@ export interface EmbedChatFooterProps {
     footerColor?: string;
 }
 export interface EmbedChatInstance {
+    logout?: () => void;
+    setCart: (cart: Omit<import('./utils/cart-model').WebchatCart, 'itemCount' | 'truncated'> | null) => void;
+    identify?: (hint: import('./utils/storefront-identity').CustomerHint) => void;
     destroy: () => void;
     updateConfig?: (newConfig: Partial<EmbedChatConfig>) => void;
     injectCSS?: (css: string) => void;
     removeCustomCSS?: () => void;
 }
 export interface Message {
+    reaction?: string;
+    replyToId?: string;
+    replyTo?: {
+        id: string;
+        content: string;
+        role: string;
+        type: string;
+    };
+    author?: {
+        name: string;
+        avatarUrl?: string;
+    };
+    contactPromptAfter?: boolean;
+    delivery?: 'sending' | 'accepted' | 'failed';
     id: string;
     text: string;
     sender: 'user' | 'bot';
@@ -122,37 +178,44 @@ export interface ChatButtonProps {
     marginBottom?: number;
     marginSide?: number;
     hasNewMessages?: boolean;
+    unreadCount?: number;
     isMobile?: boolean;
     isMenuOpen?: boolean;
     hasWhatsAppMenu?: boolean;
 }
 export interface ChatWindowProps {
+    onReact?: (messageId: string, emoji: string | null) => Promise<boolean>;
+    alertSettings?: React.ReactNode;
+    onTyping?: (active: boolean) => void;
+    draftRevision?: number;
+    onViewed?: (ids: string[]) => void;
+    sendError?: string;
+    onRetry?: () => void;
+    sending?: boolean;
+    contactCaptured?: boolean;
+    handoffRequested?: boolean;
+    engaged?: boolean;
     isOpen: boolean;
     onClose: () => void;
     config: WebChatConfig;
     messages: Message[];
-    onSendMessage: (message: string, files?: FileWithBlobUrl[]) => void;
+    onSendMessage: (message: string, files?: FileWithBlobUrl[], replyTo?: Message) => void | boolean | Promise<void | boolean>;
     isLoading?: boolean;
     isAiTyping?: boolean;
+    teamOnline?: boolean;
+    isStaffTyping?: boolean;
+    staffTypingAuthor?: Message["author"];
     position?: 'bottom-right' | 'bottom-left';
     marginBottom?: number;
     marginSide?: number;
     isMobile?: boolean;
     chatbotActivated?: boolean;
-    isRated?: boolean;
-    onRatingChange?: (isRated: boolean) => void;
     conversationId?: string;
-    /** Configurable auto-survey threshold from the backend; undefined = legacy default (2). */
-    surveyAfterUserMessages?: number;
-    /** Timestamp of the last manual survey request from Livechat; undefined = never requested. */
-    webchatSurveyRequestedAt?: number;
-}
-/** Survey-related conversation state forwarded from the Convex realtime subscription. */
-export interface ConversationSurveyState {
-    surveyAfterUserMessages?: number;
-    webchatSurveyRequestedAt?: number;
 }
 export interface ChatHeaderProps {
+    selectionActions?: React.ReactNode;
+    teamOnline?: boolean;
+    alertSettings?: React.ReactNode;
     title: string;
     onClose: () => void;
     primaryColor?: string;
@@ -162,21 +225,40 @@ export interface ChatHeaderProps {
     closeButtonCustomIcon?: string;
 }
 export interface MessageListProps {
+    selectedMessageId?: string;
+    onSelectMessage?: (message: Message | undefined) => void;
+    onReact?: (messageId: string, emoji: string | null) => Promise<boolean>;
+    onReply?: (message: Message) => void;
+    contactMessage?: React.ReactNode;
+    onViewed?: (ids: string[]) => void;
     messages: Message[];
     isTyping: boolean;
+    teamOnline?: boolean;
+    isStaffTyping?: boolean;
+    staffTypingAuthor?: Message["author"];
     avatar?: string;
     textColor?: string;
     bubbleUserColor?: string;
     chatbotActivated?: boolean;
 }
 export interface MessageProps {
+    selectedMessageId?: string;
+    onSelectMessage?: (message: Message | undefined) => void;
+    onReact?: (messageId: string, emoji: string | null) => Promise<boolean>;
+    onReply?: (message: Message) => void;
+    referencedMessage?: Message;
+    onJump?: (id: string) => void;
     message: Message;
     avatar?: string;
     textColor?: string;
     bubbleUserColor?: string;
 }
 export interface MessageInputProps {
-    onSendMessage: (message: string, files?: FileWithBlobUrl[]) => void;
+    replyTo?: Message;
+    onCancelReply?: () => void;
+    onTyping?: (active: boolean) => void;
+    draftScope?: string;
+    onSendMessage: (message: string, files?: FileWithBlobUrl[], replyTo?: Message) => void | boolean | Promise<void | boolean>;
     placeholder?: string;
     primaryColor?: string;
     disabled?: boolean;
@@ -185,6 +267,9 @@ export interface MessageInputProps {
 }
 export interface TypingIndicatorProps {
     avatar?: string;
+    author?: Message["author"];
+    human?: boolean;
+    compact?: boolean;
 }
 export interface ChatBubblePopoverProps {
     initialMessage?: string;
@@ -198,14 +283,25 @@ export interface ChatBubblePopoverProps {
     onPopoverClick: () => void;
 }
 export interface WebChatInstance {
+    logout?: () => void;
+    setCart: (cart: Omit<import('./utils/cart-model').WebchatCart, 'itemCount' | 'truncated'> | null) => void;
+    identify?: (hint: import('./utils/storefront-identity').CustomerHint) => void;
     root: any;
     destroy: () => void;
     getConversationId: () => string | null;
     setIsOpen?: (open: boolean) => void;
     updateConfig?: (newConfig: Partial<WebChatConfig>) => void;
     setPosition?: (pos: Partial<WebChatConfig>) => void;
+    getIsOpen?: () => boolean;
     hide?: () => void;
     show?: () => void;
+    /**
+     * Starts a new conversation in place: new conversation id, empty transcript,
+     * fresh visitor session, realtime subscriptions reopened. Unlike calling
+     * `initialize()` again it does not destroy and rebuild the widget, so the
+     * panel does not blink out while the new thread is prepared.
+     */
+    restartConversation?: () => void;
     injectCSS?: (css: string) => void;
     removeCustomCSS?: () => void;
 }

package/dist/utils/cart-model.d.ts

@@ -0,0 +1,23 @@
+/** Cart amounts are integer minor currency units. Storefront hints never authorize orders or prices. */
+export interface WebchatCartItem {
+    id: string;
+    title: string;
+    quantity: number;
+    unitPrice: number;
+    variant?: string;
+    imageUrl?: string;
+    url?: string;
+}
+export interface WebchatCart {
+    currency: string;
+    total: number;
+    itemCount: number;
+    items: WebchatCartItem[];
+    truncated: boolean;
+}
+export interface WebchatCartSnapshot {
+    cart: WebchatCart | null;
+    updatedAt: number;
+}
+/** Allowlist and bound storefront context before sending it to staff or edge storage. */
+export declare function sanitizeWebchatCart(value: unknown, origin: string): WebchatCart | null;

package/dist/utils/contact-link.d.ts

@@ -0,0 +1,2 @@
+/** Remove the bearer credential before widget analytics or presence can use the URL. */
+export declare function takeContactLink(chatbotUid: string): string | null;

package/dist/utils/convex.d.ts

@@ -1,5 +1,5 @@
 import { ConvexReactClient } from 'convex/react';
-import { ConversationSurveyState, Message } from '../types';
+import { Message } from '../types';
 export interface ConvexConnectionData {
     client: ConvexReactClient;
     unsubscribe: (() => void) | null;
@@ -11,10 +11,9 @@ export interface ConvexConnectionData {
  * @param conversationId Conversation ID
  * @param onMessage Callback for new messages
  * @param onChatbotToggle Callback for chatbot activation changes
- * @param onSurveyStateChange Callback for survey state changes (threshold + manual trigger)
  * @returns Promise that resolves to Convex connection data
  */
-export declare const initializeConvexConnection: (realtimeEndpoint: string, _chatbotUid: string, conversationId: string, onMessage: (message: Message) => void, onChatbotToggle?: (chatbotActivated: boolean) => void, onSurveyStateChange?: (surveyState: ConversationSurveyState) => void) => Promise<ConvexConnectionData>;
+export declare const initializeConvexConnection: (realtimeEndpoint: string, _chatbotUid: string, conversationId: string, onMessage: (message: Message) => void, onChatbotToggle?: (chatbotActivated: boolean) => void) => Promise<ConvexConnectionData>;
 /**
  * Fetches initial conversation data with messages from Convex
  * @param realtimeEndpoint Realtime service deployment URL

package/dist/utils/markdown.d.ts

@@ -0,0 +1,2 @@
+/** Both visitor and assistant text are untrusted, including raw HTML inside Markdown. */
+export declare function renderMessageMarkdown(text: string): string;

package/dist/utils/message-alerts.d.ts

@@ -0,0 +1,15 @@
+/** Keep notification counters out of the page metadata sent to Livechat. */
+export declare const getStorefrontTitle: () => string;
+/** Preserve storefront title changes, including client-side navigation, while showing unread replies. */
+export declare function createUnreadTitle(): {
+    update(next: number): void;
+    close(): void;
+};
+/** Share a bounded receipt ledger between storefront tabs; Web Locks prevent simultaneous alerts. */
+export declare function claimMessageAlert(uid: string, conversationId: string, ids: string[]): Promise<any>;
+/** Unlock audio only on customer interaction; unsupported/autoplay-blocked browsers remain silent. */
+export declare function createMessageSound(): {
+    unlock: () => void;
+    play(): void;
+    close(): void;
+};

package/dist/utils/message-colors.d.ts

@@ -0,0 +1,3 @@
+/** Store theme colors are opaque hex colors; keep a custom text color only when legible. */
+export declare function messageTextColor(background: string, preferred?: string): string;
+export declare function messageMetaColor(background: string, foreground: string): string;

package/dist/utils/message-id.d.ts

@@ -0,0 +1,2 @@
+/** Mirrors the API's conversation/request/index ID, so optimistic bubbles reconcile before HTTP completes. */
+export declare function webchatMessageId(conversationId: string, requestId: string, index: number): Promise<string>;

package/dist/utils/phone.d.ts

@@ -0,0 +1,16 @@
+import { getCountryCallingCode, CountryCode } from 'libphonenumber-js/min';
+export { getCountryCallingCode, type CountryCode };
+export declare const phoneCountries: CountryCode[];
+export declare const isPhoneCountry: (value: unknown) => value is CountryCode;
+export declare const countryFlag: (country: CountryCode) => string;
+/** Browser hints are a convenience, not geolocation. No request or permission prompt is needed. */
+export declare function suggestPhoneCountry(languages: readonly string[], timeZone: string): CountryCode;
+/** Split pasted/saved international numbers without duplicating their country calling code. */
+export declare function splitPhone(value: string, fallback: CountryCode): {
+    value: string;
+    country: CountryCode;
+};
+/** Normalize national input (including trunk prefixes) for the existing E.164 contact endpoint. */
+export declare function normalizePhone(value: string, country: CountryCode): string | null;
+export declare const countryName: (country: CountryCode) => string;
+export declare const sortedPhoneCountries: CountryCode[];

package/dist/utils/storefront-cart.d.ts

@@ -0,0 +1,6 @@
+import { WebchatCart } from './cart-model';
+export type { WebchatCart } from './cart-model';
+/** Commerce adapters call this on initial load and cart changes. No network until chat engagement. */
+export declare function setStorefrontCart(uid: string, input: unknown): void;
+export declare const getStorefrontCart: (uid: string) => WebchatCart | null | undefined;
+export declare function subscribeStorefrontCart(uid: string, listener: () => void): () => void;

package/dist/utils/storefront-identity.d.ts

@@ -0,0 +1,23 @@
+import { VisitorSession } from './visitor-session';
+export interface CustomerHint {
+    platform?: 'tiendanube' | 'shopify' | 'vtex' | 'custom';
+    subject?: string;
+    email?: string;
+    name?: string;
+    phone?: string;
+}
+interface VerifiedIdentity extends CustomerHint {
+    verified: boolean;
+    expiresAt: number;
+}
+/** Hints only prefill the form; they do not authenticate or link customer records. */
+export declare function saveCustomerHint(uid: string, hint: CustomerHint): void;
+/** The configured same-origin merchant route must validate its own login before signing. */
+export declare function refreshStorefrontIdentity(session: VisitorSession, endpoint: string): Promise<{
+    changed: boolean;
+    identity: null;
+} | {
+    changed: boolean;
+    identity: VerifiedIdentity;
+}>;
+export {};

package/dist/utils/transcript.d.ts

@@ -0,0 +1,23 @@
+import { VisitorSession } from './visitor-session';
+import { Message } from '../types';
+export interface Transcript {
+    messages: Array<{
+        reaction?: string;
+        replyToId?: string;
+        replyTo?: Message["replyTo"];
+        id: string;
+        role: string;
+        content: string;
+        createdAt: string;
+        type?: string;
+        metaContent?: string;
+        contactPromptAfter?: boolean;
+        author?: Message['author'];
+    }>;
+    chatbotActivated: boolean;
+    contactCaptured?: boolean;
+    handoffRequested?: boolean;
+}
+export declare const transcriptMessages: (data: Transcript) => Message[];
+/** One bounded subscription supplies both initial history and live replies, avoiding snapshot races. */
+export declare function subscribeTranscript(session: VisitorSession, onData: (data: Transcript) => void, onError: () => void): () => void;

package/dist/utils/visitor-presence.d.ts

@@ -0,0 +1,30 @@
+import { VisitorSession } from './visitor-session';
+export interface EdgeReply {
+    id: string;
+    at: number;
+    receipt: 'available' | 'delivered' | 'viewed';
+}
+export interface EdgeState {
+    staffTyping?: {
+        name: string;
+        avatarUrl?: string;
+    } | null;
+    staffTypingUntil?: number;
+    typingUntil?: number;
+    page?: {
+        url: string;
+        title: string;
+    } | null;
+    type: 'state';
+    presence: string;
+    replies: EdgeReply[];
+    observedAt: number;
+}
+/** Reconnectable metadata channel. Transcript content is only loaded while the chat is open. */
+export declare function connectVisitorPresence(session: VisitorSession, onState: (state: EdgeState) => void, onConnection: (connected: boolean) => void, onTeamAvailability?: (online: boolean) => void): {
+    setTyping: (active: boolean) => void;
+    setOpen(value: boolean): void;
+    delivered(ids: string[]): void;
+    viewed(ids: string[]): void;
+    close(): void;
+};