@ada-cx/messaging-sdk 1.0.0-setup.0

package/dist/client/client-types.d.ts

@@ -0,0 +1,231 @@
+export type MetaFieldValue = string | number | boolean | null;
+export interface AdaSdkEventContext {
+    eventKey: string;
+}
+export type AdaSdkEventCallback = (event: unknown, context: AdaSdkEventContext) => void;
+export type BeforeSend = (message: {
+    text: string;
+}) => {
+    text: string;
+} | false | Promise<{
+    text: string;
+} | false>;
+export interface Delegate {
+    beforeSend?: BeforeSend;
+}
+export interface PublicAgentInfo {
+    id: string;
+    name: string;
+    avatarUrl?: string;
+}
+export interface AdaReadyCallbackParams {
+    isRolledOut: boolean;
+}
+export interface AdaMessagingSettings {
+    /** Full base URL for the Ada API; overrides all default derivation. */
+    endpoint?: string;
+    /**
+     * Ada base-domain segment (e.g. "ada", "ada-dev2"), combined with `handle`
+     * and any regional `cluster` into the API host
+     * `https://<handle>.[<cluster>.]<domain>.support`. For a full URL override,
+     * use `endpoint` instead.
+     */
+    domain?: string;
+    /**
+     * Ada cluster: either a full base domain (e.g. "ada-dev2.support",
+     * "eu.ada.support", "localhost") used as-is, or a regional segment (e.g.
+     * "eu") combined with `domain`.
+     */
+    cluster?: string | null;
+    /** Language code (e.g. "en", "fr") */
+    language?: string;
+    /** Answer response id to trigger as the initial greeting (legacy CDN parity). */
+    greeting?: string;
+    /** Short-lived identity token returned by the Platform API auth-token endpoint. */
+    identityToken?: string;
+    /**
+     * URL of a customer-hosted app frame to mount in place of Ada's default
+     * conversation UI. Must be an absolute `https:` URL (or `http:` on a
+     * loopback host for local development); any other value is
+     * ignored with a warning. Ada enables custom apps per handle by
+     * allowlisting your app's origin server-side — ask your Ada team to add
+     * it; a URL whose origin is not allowlisted is dropped with a console
+     * warning and Ada's default app mounts instead. The custom frame keeps its
+     * own origin (sandboxed with `allow-same-origin`) and receives
+     * conversation state through `@ada-cx/messaging-bridge`, never through URL
+     * query params. When the custom frame fails to load or complete its bridge
+     * handshake, Messaging falls back to Ada's default app unless
+     * `appUrlFallback` is `false`.
+     */
+    appUrl?: string;
+    /**
+     * When `false`, a failing custom `appUrl` frame is NOT replaced with Ada's
+     * default app; activation fails instead. Defaults to true. Only meaningful
+     * together with `appUrl`.
+     */
+    appUrlFallback?: boolean;
+    /** Metafield key/value pairs passed to the bot */
+    metaFields?: Record<string, MetaFieldValue>;
+    /**
+     * When true, `reset({ metaFields })` may apply caller-supplied metaFields.
+     * Defaults to false so an end user cannot inject or override metaFields by
+     * calling `reset()` (e.g. from the browser console). The value is locked on
+     * the first config and cannot be changed at runtime. (MES-542)
+     */
+    allowMetaFieldsInReset?: boolean;
+    /**
+     * When true, unlocks the programmatic-control surface — `sendMessage()`,
+     * `setComposerText()`, `setDelegate()`, `getMessages()`, `getConversation()`,
+     * and the `ada:message:sent` / `ada:message:received` events. Defaults to
+     * false for security; the value is locked on the first config and cannot be
+     * changed at runtime. (MES-981)
+     */
+    enableProgrammaticControl?: boolean;
+    /** Custom style overrides (tintColor, surfaceColor, etc.) */
+    styles?: Record<string, string>;
+    /** Button and chat drawer alignment: "right" (default), "left", or "auto" */
+    align?: "right" | "left" | "auto";
+    /** Defer SDK initialization until start() is explicitly called */
+    lazy?: boolean;
+    /**
+     * Where to mount the chat when the floating drawer is not desired.
+     * Accepts an `HTMLElement` or an element id string.
+     */
+    parentElement?: string | HTMLElement;
+    /**
+     * Hide the widget's built-in ChatHeader, for hosts that render their own
+     * header chrome around the widget. Defaults to false, so parentElement
+     * consumers (mobile webview, React Native) keep their header.
+     *
+     * Currently unused and undocumented — no caller sets it. Removing it spans
+     * core/bridge/sdk/app, so it is left in place as its own cleanup.
+     */
+    hideDefaultHeader?: boolean;
+    /** Prevent cross-session history from being loaded */
+    privateMode?: boolean;
+    /** Mark chatter as a test user (not counted in analytics) */
+    testMode?: boolean;
+    /** Hide the overlay mask behind the chat drawer */
+    hideMask?: boolean;
+    /**
+     * Run the SDK without rendering the default launcher button, intro popup, or
+     * chat drawer. Intended for hosts that render their own UI and drive the
+     * conversation through the programmatic API.
+     */
+    headless?: boolean;
+    /**
+     * When true (default), show a self-contained fallback document in the chat
+     * frame if chat activation exceeds the timeout budget and no
+     * `ada:chat_frame_timeout` subscriber has taken over handling.
+     */
+    showFallbackOnTimeout?: boolean;
+    /** Sensitive metafield key/value pairs passed through secure storage transport. */
+    sensitiveMetaFields?: Record<string, MetaFieldValue>;
+    /** Event callbacks to eagerly register before the first startup event fires */
+    eventCallbacks?: Record<string, AdaSdkEventCallback>;
+    /**
+     * Override the rollout fraction for this session (0–1).
+     * For testing and QA purposes only.
+     */
+    rolloutOverride?: number;
+    /** Persist eligible live-chat window state across refreshes and tabs. Defaults to true. */
+    crossWindowPersistence?: boolean;
+    /**
+     * Color scheme for the chat widget: `"light"`, `"dark"`, or `"auto"`.
+     * When set to `"auto"` (default), the widget follows the user's OS preference
+     * via `prefers-color-scheme`. This overrides the server-configured theme.
+     */
+    theme?: "light" | "dark" | "auto";
+    /** Legacy callback fired when chat has finished setting up. */
+    adaReadyCallback?: (params: AdaReadyCallbackParams) => void;
+    /** Legacy callback fired when a chatter token becomes available. */
+    chatterTokenCallback?: (chatterToken: string) => void;
+    /** Legacy callback fired when the conversation ends. */
+    conversationEndCallback?: (event?: Record<string, unknown>) => void;
+    /** Legacy callback fired when the drawer opens or closes. */
+    toggleCallback?: (isDrawerOpen: boolean) => void;
+    /**
+     * Called once the public embed interface is ready to be used.
+     * Useful for early event subscriptions.
+     */
+    onAdaEmbedLoaded?: () => void;
+    /** Legacy Zendesk chat auth callback. */
+    zdChatterAuthCallback?: (callback: (token: string) => void) => void;
+}
+/** Parameters for resetting the session with optional new config */
+export interface ResetParams {
+    /** Legacy Answer response id to trigger after reset. */
+    greeting?: string | null;
+    /** Response id to trigger after reset */
+    greetingResponseId?: string | null;
+    /** Language code to apply after reset */
+    language?: string;
+    /** Metafield key/value pairs to apply after reset */
+    metaFields?: Record<string, MetaFieldValue>;
+    /** Sensitive metafield key/value pairs to apply after reset */
+    sensitiveMetaFields?: Record<string, MetaFieldValue>;
+    /** Short-lived identity token to exchange before the next boot sequence. */
+    identityToken?: string;
+    /** When false, preserve conversation history on reset */
+    resetChatHistory?: boolean;
+}
+/** Current client state returned by getInfo() */
+export interface WindowInfo {
+    /** Whether chat is currently visible to the user */
+    isChatOpen: boolean;
+    /** Whether the drawer UI is currently open (always false in parentElement mode) */
+    isDrawerOpen: boolean;
+    /** Whether an active chatter exists in the current session */
+    hasActiveChatter: boolean;
+    /** Whether the chatter has previously closed a chat */
+    hasClosedChat: boolean;
+}
+/** Conversation + live-agent handoff state returned by getConversation(). */
+export interface ConversationInfo {
+    /** The active conversation id, or null if none has started. */
+    id: string | null;
+    handoff: {
+        /** Whether the conversation is currently in a live-agent handoff. */
+        inLiveChat: boolean;
+        /** Basic connected-agent identity when Messaging has it. */
+        agent?: PublicAgentInfo;
+    };
+}
+/**
+ * A single message in the transcript returned by getMessages(). The base shape
+ * matches legacy Embed2; Messaging may include safe type-specific data when
+ * that data is already visible in the rendered conversation.
+ */
+export interface PublicMessage {
+    id: string;
+    /** The message author. */
+    role: "user" | "bot" | "agent";
+    /** The message kind (e.g. "text", "quick_replies", "picture"). */
+    type: string;
+    /** The message body text, when the message type has a text body. */
+    body?: string;
+    /** Unix-epoch seconds when the message was created. */
+    createdAt: number;
+    /** Present whenever the transport message carries agent identity (legacy parity). */
+    agent?: PublicAgentInfo;
+    data?: Record<string, unknown>;
+    /** "programmatic" for SDK-originated sends; absent otherwise (legacy parity). */
+    origin?: "programmatic";
+}
+/** Result returned by sendMessage() once Messaging accepts the user message. */
+export interface SendMessageResult {
+    id: string;
+}
+/**
+ * Event keys for subscribeEvent().
+ * Extends string so custom keys are also accepted.
+ */
+export type AdaSdkEventKey = "ada:ready" | "ada:campaigns:shown" | "ada:campaigns:opened" | "ada:campaigns:engaged" | "ada:campaigns:dismissed" | "ada:end_conversation" | "ada:agent:joined" | "ada:agent:left" | "ada:typing:start" | "ada:typing:stop" | "ada:connection:change" | "ada:conversation:change" | "ada:minimize_chat" | "ada:close_chat" | "ada:csat_submitted" | "ada:conversation:message" | "ada:message:sent" | "ada:message:received" | "ada:chat_frame_timeout" | "ada:chatter_token" | "ada:identity_token:error" | "ada:identity_token:expired" | "ada:analytics" | "ada:toggle" | "ada:embed_loaded" | "ada:web_notification:click" | string;
+export interface AdaMessagingClientConfig extends AdaMessagingSettings {
+    /** Bot handle identifier */
+    handle: string;
+}
+export interface AdaMessagingStartOptions extends AdaMessagingSettings {
+    /** Bot handle identifier. Required unless it was already provided elsewhere. */
+    handle?: string;
+}