@useago/sdk 1.9.0 → 1.12.0

package/dist/widget.d.ts

@@ -53,6 +53,7 @@ declare class AgoClient {
     private contextRegistry;
     private eventEmitter;
     private activityLedger;
+    private errorWatcher;
     private lastSentPageState;
     private config;
     /** Conversations already warned about an empty reply (one warning each). */
@@ -222,6 +223,26 @@ declare class AgoClient {
      * `SSEHandler.parseToolCall` so persisted and streamed tool calls match.
      */
     private static mapPersistedToolCalls;
+    /**
+     * The tenant's SDK configuration (`GET /api/sdk/v1/config`): per-permission
+     * agents, the ticket form the agent's `ago_ticketing` tool opens, and the
+     * file-attachment flag. The vanilla widget fetches it once, when a ticket
+     * form first appears in a conversation.
+     */
+    getConfig(): Promise<SdkConfig>;
+    /**
+     * The dashboard's home screen content. A starter card shows its
+     * `description` and sends its `initial_message`; one with neither is
+     * unusable and is dropped rather than rendered as an empty card.
+     */
+    private static mapHomePage;
+    private static mapTicketForm;
+    /**
+     * Create a support ticket (`POST /api/sdk/v1/tickets`, multipart). This is
+     * what the ticket form in the conversation does before it completes the
+     * `form` tool call with {@link submitToolCallForm}.
+     */
+    createTicket(input: CreateTicketInput): Promise<CreateTicketResult>;
     /**
      * Get messages for a conversation
      */
@@ -480,6 +501,15 @@ declare class AgoClient {
     /* Excluded from this release type: emitProactiveEvent */
     /* Excluded from this release type: getHttp */
     /* Excluded from this release type: getConfiguredAgent */
+    /**
+     * How the SDK identifies the visitor: the configured `userEmail`, and
+     * whether a `userJwt` is set. The ticket form asks for an email when it has
+     * neither.
+     */
+    getUserIdentity(): {
+        email?: string;
+        hasJwt: boolean;
+    };
     /**
      * Enable automatic capture of the current browser page (URL + title).
      * Injected as a dynamic context entry named `browser-page`.
@@ -502,6 +532,26 @@ declare class AgoClient {
     private addActivity;
     private recordAgentAction;
     private registerActivityContext;
+    /**
+     * Start capturing the page's JavaScript errors (uncaught exceptions,
+     * unhandled rejections, `console.error` calls, {@link reportError}) and send
+     * the recent ones as the `errors:recent` context entry on every message.
+     * Same as setting `errorWatcher` in the config. Calling it again replaces
+     * the watcher (and its options); the captured errors are not kept.
+     */
+    enableErrorWatcher(options?: ErrorWatcherOptions): void;
+    /** Stop capturing errors and drop the `errors:recent` context entry. */
+    disableErrorWatcher(): void;
+    /**
+     * Record an error the app caught itself (React error boundary, Vue
+     * `errorHandler`, Angular `ErrorHandler`, a try/catch) so the agent sees it
+     * like an uncaught one. No-op unless the error watcher is enabled. `context`
+     * is size-clamped before it is stored; keep it small and free of secrets.
+     */
+    reportError(error: unknown, context?: Record<string, unknown>): void;
+    /** Errors the watcher currently holds, oldest first (a copy). Empty when disabled. */
+    getRecentErrors(): CapturedError[];
+    clearErrors(): void;
     /**
      * Subscribe to an event
      */
@@ -696,6 +746,12 @@ declare interface AgoClientEvents {
     };
     /** A user- or agent-action was recorded into the activity ledger. */
     "activity:recorded": ActivityEntry;
+    /**
+     * The error watcher captured a JavaScript error (uncaught exception,
+     * unhandled rejection, `console.error` call, or `reportError`). Fires on
+     * repeats too, with the updated `count`. Requires `errorWatcher` in the config.
+     */
+    "error:captured": CapturedError;
 }
 
 /**
@@ -716,6 +772,8 @@ declare interface AgoConfig {
     userEmail?: string;
     /** JWT token for authenticated users */
     userJwt?: string;
+    /** User metadata sent with messages. Use null to stop sending defaults. Not an authentication credential. */
+    metadata?: Record<string, unknown> | null;
     /** Enable debug logging */
     debug?: boolean;
     /**
@@ -775,6 +833,18 @@ declare interface AgoConfig {
      * default otherwise.
      */
     proactive?: ProactiveOptions;
+    /**
+     * Capture the page's JavaScript errors as agent context. When set, the SDK
+     * listens for uncaught exceptions and unhandled promise rejections, wraps
+     * `console.error` (calling through; restored on `destroy`), and sends the
+     * recent errors (deduplicated, capped, pruned after 10 min) as the
+     * `errors:recent` context entry on every message. `true` uses the defaults;
+     * pass {@link ErrorWatcherOptions} to tune the caps or add a `filter` that
+     * redacts messages. Off by default: error messages can carry PII or internal
+     * URLs, so enabling it is the host's call. Errors also feed the proactive
+     * mode's `jsErrors` signal. See `client.reportError()` for caught errors.
+     */
+    errorWatcher?: boolean | ErrorWatcherOptions;
 }
 
 declare type AgoEventHandler<K extends AgoEventName> = (data: AgoClientEvents[K]) => void;
@@ -988,6 +1058,32 @@ export declare interface AgoWidgetConfig {
     metadata?: Record<string, unknown>;
 }
 
+/** One JavaScript error captured on the page (deduplicated, see `count`). */
+declare interface CapturedError {
+    type: CapturedErrorType;
+    /** Error message, truncated to 500 chars. */
+    message: string;
+    /** Script URL the error came from, without its query string. */
+    source?: string;
+    line?: number;
+    col?: number;
+    /** Leading stack frames, truncated (see `maxStackChars`). */
+    stack?: string;
+    /** Pathname at capture time. */
+    route: string;
+    /** Epoch ms of the first occurrence. */
+    firstAt: number;
+    /** Epoch ms of the most recent occurrence. */
+    lastAt: number;
+    /** How many times this same error (type + message + source + line) fired. */
+    count: number;
+    /** App-provided context, manual reports only (size-clamped). */
+    context?: Record<string, unknown>;
+}
+
+/** How an error reached the watcher. */
+declare type CapturedErrorType = "error" | "unhandledrejection" | "console" | "manual";
+
 /** Handle returned by `mountChatWidget`. */
 export declare interface ChatWidgetHandle {
     /** The AGO client backing the widget. */
@@ -1020,6 +1116,18 @@ export declare interface ChatWidgetHandle {
     readonly threads: Conversation[];
     /** Re-fetch the conversations list and update {@link ChatWidgetHandle.threads}. */
     refreshThreads: () => Promise<Conversation[]>;
+    /** `placement: "bubble"` only. The screen currently shown. */
+    readonly screen?: WidgetScreen;
+    /** `placement: "bubble"` only. Switch to the home, chat, or history screen. */
+    showScreen?: (screen: WidgetScreen) => void;
+    /** `placement: "bubble"` only. Open a conversation by id on the chat screen. */
+    openConversation?: (conversationId: string) => Promise<void>;
+    /**
+     * Forget the current thread and start over, like the header's new-chat
+     * button and the "New conversation" button shown once a ticket exists. The
+     * bubble widget also returns to its home screen.
+     */
+    newConversation: () => void;
     /** Remove listeners, uninstall forms, and clear the DOM. */
     destroy: () => void;
 }
@@ -1114,6 +1222,14 @@ declare interface ClientFunctionSchema {
 /** See {@link AgoConfig.clientFunctionsMode}. */
 declare type ClientFunctionsMode = "placeholder" | "pause";
 
+/**
+ * Translate the embed snippet's `colors` object into {@link WidgetTheme} keys,
+ * so `mountChatWidget({ colors })` skins the bubble widget exactly like
+ * `window.AGO.colors` skins the hosted one. The header text color is derived
+ * for contrast unless the theme sets it.
+ */
+export declare function colorsToTheme(colors: AgoWidgetColors | undefined): WidgetTheme;
+
 /**
  * Build the media query for the compact layout.
  *
@@ -1220,6 +1336,19 @@ export declare interface ConversationSessionOptions {
     ttlMs?: number;
 }
 
+/** A card on the bubble widget's home screen that starts a conversation. */
+export declare interface ConversationStarter {
+    /** Text shown on the card. */
+    label: string;
+    /** Message sent when clicked. Defaults to `label`. */
+    message?: string;
+    /**
+     * Answer this starter with a specific agent (id or slug) instead of the
+     * client's default. Dashboard starters (`loadHomeConfig`) carry their own.
+     */
+    agentId?: string;
+}
+
 export declare interface CreateFormCollectorOptions<V = Record<string, unknown>> {
     /** Short identifier; becomes the `update_<name>` / `submit_<name>` function names. */
     name: string;
@@ -1245,8 +1374,36 @@ export declare interface CreateFormCollectorOptions<V = Record<string, unknown>>
 
 export declare function createSheetController(options?: SheetOptions): SheetController;
 
+/** Input of `AgoClient.createTicket` (`POST /api/sdk/v1/tickets`). */
+declare interface CreateTicketInput {
+    subject: string;
+    body: string;
+    priority?: string;
+    typology?: string;
+    /** Conversation the ticket is filed from. */
+    conversationId?: string;
+    /** Reporter email, for a visitor the SDK does not otherwise identify. */
+    email?: string;
+    customFields?: Array<{
+        id: string;
+        value: string;
+    }>;
+    files?: File[];
+    ticketFormId?: string;
+}
+
+/** Response of `AgoClient.createTicket`. */
+declare interface CreateTicketResult {
+    id: string;
+    url?: string;
+}
+
 export declare const DEFAULT_FEEDBACK_LABELS: FeedbackLabels;
 
+export declare const DEFAULT_TOOL_CALL_FORM_LABELS: ToolCallFormLabels;
+
+export declare const DEFAULT_WIDGET_LABELS: WidgetLabels;
+
 /**
  * A function that returns a fresh context entry on demand.
  * Evaluated every time a message is sent — use it to pull data from stores,
@@ -1261,6 +1418,23 @@ export declare interface ElementProps {
     attrs: Record<string, string | null>;
 }
 
+declare interface ErrorWatcherOptions {
+    /** Max distinct errors kept. Oldest dropped first. Default 10. */
+    maxErrors?: number;
+    /**
+     * Errors older than this are pruned when the buffer is read, so a crash from
+     * an hour ago does not confuse the agent. Default 600 000 (10 min).
+     */
+    maxAgeMs?: number;
+    /** Max chars of stack kept per error. Default 2000. */
+    maxStackChars?: number;
+    /**
+     * Redact or drop an error before it is stored. Return the (possibly edited)
+     * error to keep it, `null` to drop it. Runs on every capture, so keep it cheap.
+     */
+    filter?: (error: CapturedError) => CapturedError | null;
+}
+
 /**
  * Why the user is reporting a message (see `AgoClient.submitFeedback`).
  *
@@ -1550,14 +1724,73 @@ export declare interface MountChatWidgetOptions {
      * closed; the target is only used as the DOM parent (pass `document.body` for
      * a true page overlay). In side mode `height` is ignored and the width comes
      * from {@link MountChatWidgetOptions.width}.
+     *
+     * `"bubble"` reproduces the hosted embed widget without an iframe: a floating
+     * launcher bottom-right, a teaser bubble, and a 550px panel with a home
+     * screen, a conversation screen, and a chat history screen. See the
+     * "Floating bubble" section of `docs/general/widget.md`.
      */
-    placement?: "inline" | "left" | "right";
+    placement?: "inline" | "left" | "right" | "bubble";
     /**
      * Width of the side panel for `placement: "left" | "right"` (number → px).
      * Capped at the viewport width so it never overflows on mobile. Ignored when
-     * `placement` is `"inline"`. Defaults to `400`.
+     * `placement` is `"inline"`. Defaults to `400`; to `550` for `"bubble"`, where
+     * it is clamped between 400px and the viewport width minus 40px.
      */
     width?: string | number;
+    /**
+     * `placement: "bubble"` only. The teaser speech bubble shown above the
+     * launcher one second after mount, inviting the visitor in. Pass `false` to
+     * skip it. Defaults to `"Hello, how can I help you today?"`.
+     */
+    prompt?: string | false;
+    /**
+     * `placement: "bubble"` only. URL of an image (32×32) shown on the launcher
+     * instead of the default chat glyph.
+     */
+    icon?: string;
+    /**
+     * `placement: "bubble"` only. The same `colors` object as the embed snippet's
+     * `window.AGO.colors`, mapped onto {@link WidgetTheme} keys. `theme` wins over
+     * it key by key. The header text color is derived for contrast automatically.
+     */
+    colors?: AgoWidgetColors;
+    /** `placement: "bubble"` only. Hide the Home / Chats bottom bar. Defaults to `false`. */
+    hideFooter?: boolean;
+    /**
+     * `placement: "bubble"` only. Markdown shown under the title on the home
+     * screen.
+     */
+    subtitle?: string;
+    /**
+     * `placement: "bubble"` only. Cards on the home screen that each start a
+     * conversation with a preset message.
+     */
+    conversationStarters?: ConversationStarter[];
+    /**
+     * `placement: "bubble"` only. Take the home screen's title, subtitle and
+     * starter cards from the AGO dashboard (`GET /config`) instead of the
+     * options above, the way the hosted widget does. One request on mount; the
+     * home screen renders immediately with whatever was passed in code and
+     * re-renders when the config lands.
+     *
+     * Each part is replaced only when the dashboard has a value for it, so
+     * anything the dashboard leaves empty keeps what the code set. Off by
+     * default: without it the widget makes no config request on mount.
+     *
+     * The dashboard's *widget starter* (a first message the agent sends by
+     * itself) is honored too, on a fresh visit only.
+     */
+    loadHomeConfig?: boolean;
+    /**
+     * `placement: "bubble"` only. On open, reopen the visitor's most recent
+     * conversation if its last message is under two hours old. Defaults to `true`.
+     */
+    autoResume?: boolean;
+    /** `placement: "bubble"` only. Translate the chrome's strings. */
+    labels?: Partial<Omit<WidgetLabels, "timeAgo">> & {
+        timeAgo?: Partial<WidgetLabels["timeAgo"]>;
+    };
     /**
      * For side placements, render the built-in floating launcher button that opens
      * the panel (plus a close "×" in the header). Set `false` to drive open/close
@@ -1668,6 +1901,11 @@ export declare interface MountChatWidgetOptions {
      * the visitor ignores the panel; the panel then files the detailed report.
      */
     feedback?: boolean | WidgetFeedbackOptions;
+    /**
+     * The ticket form the agent can open in the conversation (labels, success
+     * text, callbacks). See {@link WidgetToolCallFormOptions}.
+     */
+    toolCallForm?: WidgetToolCallFormOptions;
     /**
      * How clicking a suggested follow-up reply behaves. Defaults to sending the
      * reply as a new user message. Pass a handler to override, or `false` to
@@ -1892,12 +2130,29 @@ declare interface ProactiveTriggerWhen {
     pageState?: Partial<Record<string, unknown>>;
     /** Min rage-click bursts on the current route. */
     rageClicks?: number;
+    /**
+     * Min JavaScript errors captured on the current route. Needs the client's
+     * `errorWatcher` enabled; without it the count stays at 0 and the matcher
+     * never passes.
+     */
+    jsErrors?: number;
     /** Min A→B→A→B route oscillations this session. */
     routeBounces?: number;
     /** Per-field minimum error counts (field NAME → min count). */
     fieldErrors?: Record<string, number>;
 }
 
+/**
+ * Pick a legible foreground for a tenant-chosen background, which may be a
+ * solid color or a gradient. A gradient is judged by its least-contrasting
+ * stop, since the text has to survive the whole sweep.
+ *
+ * Deliberately biased toward white: it flips to black only below 3:1, where
+ * white stops being readable at all. Unparseable input (a `var()`, a named
+ * color) keeps white, which is what the default dark header wants.
+ */
+export declare function readableTextColor(background: string | undefined): string;
+
 /**
  * Tiny, dependency-free markdown → DOM renderer for the vanilla chat widget.
  *
@@ -1937,10 +2192,69 @@ declare type ResumeGate = (info: {
     messageId: string;
 }) => Promise<void> | void;
 
+/** Response of `GET /api/sdk/v1/config` (see `AgoClient.getConfig`). */
+declare interface SdkConfig {
+    permissions: SdkPermissionConfig[];
+    proactive: {
+        enabled: boolean;
+    };
+}
+
+/** The dashboard's home screen content (title, subtitle, starter cards). */
+declare interface SdkHomePageConfig {
+    title?: string;
+    /** Markdown. */
+    subtitle?: string;
+    starters: SdkHomeStarter[];
+    widgetStarter?: SdkWidgetStarter;
+}
+
+/**
+ * A conversation starter card configured in the AGO dashboard. `label` is what
+ * the card shows; clicking it sends `message`.
+ */
+declare interface SdkHomeStarter {
+    id: string;
+    /** The card's text (the starter's `description` in the dashboard). */
+    label: string;
+    /** What is sent when the card is clicked. */
+    message: string;
+    /** Answer with this agent instead of the configured default. */
+    agentId?: string;
+}
+
+/** One permission's configuration in {@link SdkConfig}. */
+declare interface SdkPermissionConfig {
+    id?: string;
+    name?: string;
+    displayName?: string;
+    agents: Array<{
+        id: string;
+        name?: string;
+    }>;
+    ticketForm?: TicketForm;
+    /** Home screen content, when the tenant configured one. */
+    homePage?: SdkHomePageConfig;
+    fileAttachmentsEnabled: boolean;
+    voiceEnabled: boolean;
+}
+
+/**
+ * The starter the dashboard sends by itself on a fresh visit, before the
+ * visitor types anything.
+ */
+declare interface SdkWidgetStarter {
+    id: string;
+    message: string;
+    agentId?: string;
+}
+
 /**
  * Options for sending a message
  */
 declare interface SendMessageOptions {
+    /** Replaces config.metadata for this message; null omits metadata for this message. */
+    metadata?: Record<string, unknown> | null;
     /** Existing conversation ID */
     conversationId?: string;
     /** Override default agent */
@@ -2071,6 +2385,12 @@ declare interface SignalsSnapshot {
     idleMs: number;
     /** Rage-click bursts detected on the current route. */
     rageClicks: number;
+    /**
+     * JavaScript errors captured on the current route (count only; the messages
+     * travel in `client_context` under `errors:recent`). Always `0` unless the
+     * client has `errorWatcher` enabled.
+     */
+    jsErrors: number;
     /**
      * A→B→A→B route oscillations detected in the recent route sequence. Rolling
      * session counter (cross-route by nature); trigger cooldowns and dismissal
@@ -2129,6 +2449,13 @@ declare interface SSEChunkData {
     follow_up_replies?: string[];
     satisfaction_feedback?: unknown;
     ask_to_talk_to_human?: boolean;
+    allowed_to_create_ticket?: boolean;
+    ticket?: ToolCallTicketPrefill;
+    mode?: "form" | "embed";
+    ticket_form_id?: string;
+    embed_html?: string;
+    embed_description?: string;
+    display_mode?: "collapsible" | "display" | "both";
     /** Tool call ids still awaiting a client result, sent with the final `WAITING_CLIENT` event. */
     waiting_tool_call_ids?: string[];
 }
@@ -2182,12 +2509,82 @@ declare type SubmitConfig<V = Record<string, unknown>> = string | {
 declare interface SubmitToolCallResult {
     status: string;
     result?: unknown;
+    /** Set when `status` is `"error"`. */
+    error?: string;
+    /** The ticket a ticketing `form` tool call resolved to, when it did. */
+    ticket?: {
+        ticket_id: string;
+        ticket_url?: string;
+        [key: string]: unknown;
+    };
     resume?: {
         message_id: string;
         ready: boolean;
     };
 }
 
+/** A custom field of a ticket form. */
+declare interface TicketField {
+    id: string;
+    /** The key the ticketing backend expects; used as the submit key when set. */
+    externalId?: string;
+    title?: string;
+    /** Field kind, e.g. `"text"`, `"checkbox"`, `"tagger"`. */
+    type?: string;
+    required: boolean;
+    /** Carried in the submission but never shown. */
+    hidden: boolean;
+    active?: boolean;
+    /** Bypass progressive disclosure, while still respecting conditions. */
+    alwaysVisible?: boolean;
+    regexpForValidation?: string;
+    position: number;
+    /** Non-empty turns the field into a select. */
+    options: TicketFieldOption[];
+    /** Show this field only when the parent field holds `conditionalFieldValue`. */
+    conditionalFieldId?: string;
+    /** Legacy comma-separated condition values. */
+    conditionalFieldValue?: string;
+    /** Takes precedence over conditionalFieldValue when non-empty. */
+    conditionalFieldValues?: string[];
+}
+
+/** An option of a ticket form field (`GET /config` → `ticket_form.fields[].options[]`). */
+declare interface TicketFieldOption {
+    id: string;
+    /** Label shown to the user. */
+    name?: string;
+    /** Value submitted. Falls back to `name` when absent. */
+    value?: string;
+    /** Preselected when the form opens. */
+    default: boolean;
+    /** A note shown under the field once this option is picked. */
+    message?: string;
+    messageType: "info" | "warning" | "danger";
+    position?: number;
+    group?: string;
+    noDisplay?: boolean;
+    conditionalFieldId?: string;
+    /** Available when the parent matches any of these values. */
+    conditionalFieldValues?: string[];
+}
+
+/** The ticket form an agent's `ago_ticketing` tool opens in the conversation. */
+declare interface TicketForm {
+    id: string;
+    name?: string;
+    /** `"form"` renders the SDK's own fields; `"embed"` hosts third-party HTML. */
+    mode: "form" | "embed";
+    showSubject: boolean;
+    showBody: boolean;
+    showPriority: boolean;
+    showTypology: boolean;
+    priorityTypologies?: string[];
+    successMessageText?: string;
+    successMessageUrlLabel?: string;
+    fields: TicketField[];
+}
+
 /**
  * Tool call data from SSE stream
  */
@@ -2202,6 +2599,93 @@ declare interface ToolCallData {
     data?: Record<string, unknown>;
     functionName?: string;
     arguments?: Record<string, unknown>;
+    /**
+     * Where the hosted widget shows the call: in the collapsible "reasoning"
+     * section, in the message body, or both. Absent means collapsible only.
+     */
+    displayMode?: "collapsible" | "display" | "both";
+    /** The user asked to talk to a human. */
+    askToTalkToHuman?: boolean;
+    /** `false` when the tenant blocks ticket creation for this visitor. */
+    allowedToCreateTicket?: boolean;
+    /** Fields the agent pre-filled from the conversation. */
+    ticket?: ToolCallTicketPrefill;
+    /** `"embed"` hosts third-party HTML (`embedHtml`); otherwise the SDK's form. */
+    mode?: "form" | "embed";
+    ticketFormId?: string;
+    embedHtml?: string;
+    embedDescription?: string;
+}
+
+/**
+ * Every string the ticket form and its surrounding chrome show, with the
+ * hosted widget's English defaults, so a non-English site can translate them
+ * through `toolCallForm.labels`.
+ */
+export declare interface ToolCallFormLabels {
+    useFormToCreateTicket: string;
+    yourEmail: string;
+    emailPlaceholder: string;
+    emailRequired: string;
+    emailInvalid: string;
+    subject: string;
+    subjectRequired: string;
+    typology: string;
+    selectTypology: string;
+    typologyRequired: string;
+    question: string;
+    task: string;
+    incident: string;
+    priority: string;
+    selectPriority: string;
+    priorityRequired: string;
+    low: string;
+    normal: string;
+    high: string;
+    urgent: string;
+    detailedContext: string;
+    detailedContextRequired: string;
+    /** `{fieldTitle}` is substituted. */
+    fieldRequired: string;
+    fieldFormatInvalid: string;
+    attachments: string;
+    selectFile: string;
+    submit: string;
+    loading: string;
+    maxCharacters: string;
+    ticketSubmitted: string;
+    findTicketHere: string;
+    noTicketForm: string;
+    notAllowed: string;
+    submissionFailed: string;
+    submissionFailedDescription: string;
+    fileTooLarge: string;
+    permissionDenied: string;
+    validationFailed: string;
+    pleaseCheckFields: string;
+    embeddedFormSubmitted: string;
+    noEmbedConfigured: string;
+    embedSubmitTimeout: string;
+    tryAgain: string;
+    contactFormCreated: string;
+    contactFormRejected: string;
+    genericFormComingSoon: string;
+    unknownToolCall: string;
+    formPending: string;
+    ticketCreatedBlocked: string;
+    newConversation: string;
+}
+
+/** The ticket the agent pre-filled on a ticketing `form` tool call. */
+declare interface ToolCallTicketPrefill {
+    subject?: string;
+    body?: string;
+    typology?: string;
+    priority?: string;
+    tag?: string;
+    products?: string[];
+    /** Keyed by the field's external id, or a lowercased, underscored title. */
+    custom_fields?: Record<string, string>;
 }
 
 declare type ToolCallType = "form" | "confirmation_input" | "status_message" | "progress_indicator" | "client_function" | "reasoning" | "mcp_ui_resource";
@@ -2262,6 +2746,57 @@ export declare interface WidgetFeedbackOptions {
     onError?: (error: Error) => void;
 }
 
+/**
+ * Every string the bubble widget's chrome shows (header, footer, home,
+ * history, errors), so a non-English site can translate them. Message-level
+ * strings live in {@link WidgetFeedbackOptions.labels}.
+ */
+export declare interface WidgetLabels {
+    /** Footer tab. */
+    home: string;
+    /** Footer tab. */
+    chats: string;
+    /** Header title on the history screen. */
+    history: string;
+    /** The floating pill on the history screen, and a thread without a title. */
+    newConversation: string;
+    /** Empty history screen. */
+    noHistory: string;
+    /** Composer placeholder on the home screen. */
+    askQuestion: string;
+    /** Accessible name of the header back button. */
+    back: string;
+    /** Accessible name of the header close button. */
+    close: string;
+    /** Accessible name of the header new-chat button. */
+    newChat: string;
+    /** Title of the alert shown on a failed answer. */
+    errorTitle: string;
+    /** Body of the alert shown on a failed answer. */
+    errorDescription: string;
+    /** Accessible name of the scroll-to-bottom button. */
+    scrollToBottom: string;
+    /** Label of the button that hides a file error. */
+    dismiss: string;
+    /** Accessible name of the attach button. */
+    attachFiles: string;
+    /** Composer file errors; `{max}` / `{name}` are substituted. */
+    tooManyFiles: string;
+    invalidFileType: string;
+    fileTooLarge: string;
+    /** Relative time templates on the history screen; `{n}` is the count. */
+    timeAgo: {
+        minutes: string;
+        hours: string;
+        days: string;
+        weeks: string;
+        months: string;
+    };
+}
+
+/** The three screens of the bubble widget (`placement: "bubble"`). */
+export declare type WidgetScreen = "home" | "chat" | "history";
+
 /**
  * Theme overrides for `mountChatWidget`. The keys map to `--ago-*` custom
  * properties (see `THEME_VARS` in `./styles`).
@@ -2296,6 +2831,54 @@ export declare interface WidgetTheme {
     accent?: string;
     /** Background of assistant message bubbles when `agentBubble` is on. Defaults to a light gray. (`--ago-agent-bubble-background`) */
     agentBubbleBg?: string;
+    /** Text color inside assistant messages. Defaults to `text`. (`--ago-agent-bubble-text-color`) */
+    agentBubbleText?: string;
+    /** User message card background. `placement: "bubble"` only; defaults to white there. (`--ago-user-bubble-background`) */
+    userBubbleBg?: string;
+    /** User message text color. `placement: "bubble"` only. (`--ago-user-bubble-text-color`) */
+    userBubbleText?: string;
+    /** Floating launcher circle. `placement: "bubble"` only; defaults to `#007bff`. (`--ago-launcher-background`) */
+    launcherBg?: string;
+    /** Glyph color on the launcher. (`--ago-launcher-text-color`) */
+    launcherText?: string;
+    /** Composer send/stop button. `placement: "bubble"` only; defaults to `brand`. (`--ago-send-button-background`) */
+    sendBg?: string;
+    /** Panel width for `placement: "bubble"`, e.g. `"700px"`. Defaults to `550px`. (`--ago-panel-width`) */
+    panelWidth?: string;
+}
+
+/**
+ * Fine-tuning for the ticket form the agent's `ago_ticketing` tool opens in
+ * the conversation (the `form` tool call). The form is always on: a tool call
+ * the widget ignored would leave the visitor stuck.
+ */
+export declare interface WidgetToolCallFormOptions {
+    /** Translate any of the form's strings. */
+    labels?: Partial<ToolCallFormLabels>;
+    /** Replace the success text once the ticket exists. */
+    successMessage?: string;
+    /** Replace the "You can find it here:" label before the ticket link. */
+    successUrlLabel?: string;
+    /**
+     * Email of the visitor when the SDK has no identity for them (no `userEmail`
+     * or `userJwt` in the client config). When absent, the form asks for it.
+     */
+    userEmail?: string;
+    /** Called once the ticket exists and the tool call is completed. */
+    onSubmitted?: (data: {
+        toolCallId: string;
+        toolName: string;
+        mode: "form" | "embed";
+        ticket?: {
+            id: string;
+            url?: string;
+        };
+        values: Record<string, unknown>;
+    }) => void;
+    /** Called when creating the ticket or completing the tool call failed. */
+    onError?: (error: Error) => void;
+    /** Called when the visitor starts a new conversation from the blocked composer. */
+    onNewConversation?: () => void;
 }
 
 export { }