claudius-chat-widget 1.6.0 → 1.9.0

package/dist/index.d.cts

@@ -0,0 +1,676 @@
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+
+/** Options for {@link pluginAnalytics}. */
+export declare interface AnalyticsPluginOptions {
+    /**
+     * Sink called once per chat lifecycle event. Wire it to your analytics
+     * provider (Google Analytics, PostHog, Segment, a custom endpoint, ...).
+     */
+    onEvent: (event: ClaudiusAnalyticsEvent) => void;
+    /**
+     * Include message text in `message_sent` / `message_received` events. Set to
+     * `false` to record only the character count and avoid logging user content.
+     * @defaultValue `true`
+     */
+    includeContent?: boolean;
+}
+
+/**
+ * Context for {@link ClaudiusPlugin.onBeforeSend}. Adds the ability to
+ * short-circuit the request before it reaches the network.
+ */
+export declare interface BeforeSendContext extends PluginContext {
+    /**
+     * Skip the network request and render this assistant reply instead. The
+     * (possibly modified) user message is still shown. Stops the hook chain —
+     * later plugins' `onBeforeSend` hooks do not run.
+     */
+    respondWith(reply: string | PluginReply): void;
+    /**
+     * Cancel the send entirely: no request is made and nothing is rendered (the
+     * user message is dropped). Stops the hook chain. Use for client-only
+     * commands the chat should swallow.
+     */
+    abort(reason?: string): void;
+}
+
+/** Names of the built-in themes shipped in {@link builtinThemes}. */
+export declare type BuiltinThemeName = "default" | "minimal" | "playful" | "corporate";
+
+/**
+ * Built-in themes. `default` is intentionally empty: the baked-in token
+ * defaults (see tailwind.config.ts fallbacks and the dark block in
+ * styles.css) ARE the default theme.
+ */
+export declare const builtinThemes: Record<BuiltinThemeName, ClaudiusTheme>;
+
+/** Options for {@link pluginCannedResponses}. */
+export declare interface CannedResponsesOptions {
+    /** Rules evaluated in order; the first match wins. */
+    rules: CannedRule[];
+    /**
+     * Make `string` matchers case-sensitive.
+     * @defaultValue `false`
+     */
+    caseSensitive?: boolean;
+}
+
+/** A single intent-matching rule for {@link pluginCannedResponses}. */
+export declare interface CannedRule {
+    /**
+     * How to match the user's message:
+     * - `string` — case-insensitive substring match (see
+     *   {@link CannedResponsesOptions.caseSensitive}).
+     * - `RegExp` — tested against the message content.
+     * - function — receives the content and returns whether it matches.
+     */
+    match: string | RegExp | ((content: string) => boolean);
+    /** The reply rendered when the rule matches. */
+    reply: string | PluginReply;
+}
+
+/**
+ * Typed client for the Claudius Worker chat API. Handles debouncing,
+ * per-attempt timeouts, and automatic retries with backoff for transient
+ * failures (HTTP 429/503, network errors, timeouts).
+ *
+ * @example
+ * ```ts
+ * const client = new ChatApiClient("https://api.example.com");
+ * const { reply } = await client.sendMessage([
+ *   { id: "1", role: "user", content: "Hello" },
+ * ]);
+ * ```
+ */
+export declare class ChatApiClient {
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly debounceMs;
+    private readonly timeoutMs;
+    private lastSendTime;
+    /**
+     * Create a chat client for the given Worker base URL.
+     *
+     * @param baseUrl - Base URL of the Worker. Requests post to `${baseUrl}/api/chat`.
+     * @param options - Optional retry, debounce, and timeout settings.
+     */
+    constructor(baseUrl: string, options?: ChatApiClientOptions);
+    /**
+     * Send the conversation to the chat endpoint and return the assistant's
+     * reply, retrying transient failures with backoff up to
+     * {@link ChatApiClientOptions.maxRetries} times.
+     *
+     * @param messages - The full conversation so far, oldest message first.
+     * @returns The assistant's reply and any cited sources.
+     * @throws {@link DebounceError} when called within the debounce window.
+         * @throws {@link ChatApiError} when the request fails after all retries.
+             */
+         sendMessage(messages: ChatMessage[]): Promise<ChatResponse>;
+         private fetchWithTimeout;
+         private isRetryable;
+         private getRetryDelay;
+         private delay;
+     }
+
+     /**
+      * Options for {@link ChatApiClient}.
+      */
+     export declare interface ChatApiClientOptions {
+         /**
+          * Maximum retries after the first attempt, for retryable failures (HTTP
+          * 429/503, network errors, timeouts).
+          * @defaultValue `2`
+          */
+         maxRetries?: number;
+         /**
+          * Minimum gap between sends, in milliseconds. A send inside this window
+          * rejects with {@link DebounceError}. Set to 0 to disable.
+          * @defaultValue `300`
+          */
+         debounceMs?: number;
+         /**
+          * Per-attempt request timeout in milliseconds. Aborts the in-flight fetch
+          * via `AbortController` and surfaces a retryable {@link ChatApiError} with
+          * code `"TIMEOUT"`. Set to 0 to disable.
+          * @defaultValue `30000`
+          */
+         timeoutMs?: number;
+     }
+
+     /**
+      * Error thrown by {@link ChatApiClient} when a chat request ultimately fails:
+      * either after exhausting retries, or immediately for a non-retryable status.
+      */
+     export declare class ChatApiError extends Error {
+         /** HTTP status code, or `0` for network and timeout failures. */
+         readonly status: number;
+         /** Machine-readable error code, when available (e.g. `"TIMEOUT"`). */
+         readonly code?: string | undefined;
+         /** Seconds to wait before retrying, parsed from the `Retry-After` header. */
+         readonly retryAfter?: number | undefined;
+         /**
+          * Create a {@link ChatApiError}.
+          *
+          * @param message - Human-readable error message.
+          * @param status - HTTP status code, or `0` for network and timeout failures.
+          * @param code - Optional machine-readable error code (e.g. `"TIMEOUT"`, `"NETWORK_ERROR"`).
+          * @param retryAfter - Seconds to wait before retrying, from the `Retry-After` header.
+          */
+         constructor(message: string, 
+         /** HTTP status code, or `0` for network and timeout failures. */
+         status: number, 
+         /** Machine-readable error code, when available (e.g. `"TIMEOUT"`). */
+         code?: string | undefined, 
+         /** Seconds to wait before retrying, parsed from the `Retry-After` header. */
+         retryAfter?: number | undefined);
+     }
+
+     /**
+      * Error response body returned by the Worker when a chat request fails.
+      */
+     export declare interface ChatErrorResponse {
+         /** Human-readable error message. */
+         error: string;
+         /** Optional machine-readable error code (e.g. `"RATE_LIMITED"`). */
+         code?: string;
+     }
+
+     /**
+      * A single chat message exchanged between the user and the assistant.
+      */
+     export declare interface ChatMessage {
+         /** Stable unique identifier, used as the React list key. */
+         id: string;
+         /** Who authored the message. */
+         role: "user" | "assistant";
+         /** Plain-text message body. */
+         content: string;
+         /** Sources cited by the assistant for this message, when any. */
+         sources?: Source[];
+     }
+
+     /**
+      * Request payload sent to the Worker `POST /api/chat` endpoint.
+      */
+     export declare interface ChatRequest {
+         /** The full conversation so far, oldest message first. */
+         messages: ChatMessage[];
+     }
+
+     /**
+      * Successful response body from `POST /api/chat`.
+      */
+     export declare interface ChatResponse {
+         /** The assistant's reply text. */
+         reply: string;
+         /** Sources the assistant cited, when any. */
+         sources?: Source[];
+     }
+
+     /**
+      * Root Claudius chat widget: a floating toggle button that opens a chat window
+      * backed by the Worker chat API. Render a single instance on the page.
+      *
+      * @param props - See {@link ChatWidgetProps}.
+      * @example
+      * ```tsx
+      * <ChatWidget apiUrl="https://api.example.com" title="Support" />
+      * ```
+      */
+     export declare function ChatWidget({ apiUrl, title, subtitle, welcomeMessage, placeholder, persistMessages, storageKeyPrefix, requestTimeoutMs, theme, accentColor, position, locale, translations: translationOverrides, triggers, plugins, }: ChatWidgetProps): JSX_2.Element;
+
+     /**
+      * Props for the {@link ChatWidget} component.
+      */
+     export declare interface ChatWidgetProps {
+         /** Absolute URL of the Worker chat endpoint (e.g. `https://api.example.com`). */
+         apiUrl: string;
+         /** Header title. Falls back to the active locale's default title. */
+         title?: string;
+         /** Header subtitle shown beneath the title. */
+         subtitle?: string;
+         /** First assistant message shown when the chat opens. */
+         welcomeMessage?: string;
+         /** Placeholder text for the message input. */
+         placeholder?: string;
+         /**
+          * Persist the conversation to storage so it survives reloads.
+          * @defaultValue `false`
+          */
+         persistMessages?: boolean;
+         /** Prefix for the storage key used when {@link ChatWidgetProps.persistMessages} is enabled. */
+         storageKeyPrefix?: string;
+         /** Abort a chat request after this many milliseconds. */
+         requestTimeoutMs?: number;
+         /**
+          * Color-scheme mode ("light" | "dark" | "auto"), a built-in theme name
+          * ("default" | "minimal" | "playful" | "corporate"), an inline
+          * ClaudiusTheme object, or a URL to a theme JSON file.
+          * @defaultValue `"light"`
+          */
+         theme?: ClaudiusThemeInput;
+         /** Accent color override; wins over the theme's accent in both light and dark. */
+         accentColor?: string;
+         /**
+          * Corner of the viewport the widget docks to.
+          * @defaultValue `"bottom-right"`
+          */
+         position?: WidgetPosition;
+         /** BCP-47 locale used to select built-in translations. */
+         locale?: LocaleCode;
+         /** Partial overrides merged over the resolved locale translations. */
+         translations?: Partial<ClaudiusTranslations>;
+         /** Proactive open/greeting rules evaluated against the current page. */
+         triggers?: Trigger[];
+         /**
+          * Middleware run around each message: `onBeforeSend`, `onAfterReceive`, and
+          * `onError`. Hooks run in array order and may modify, replace, or
+          * short-circuit messages. See {@link ClaudiusPlugin}.
+          */
+         plugins?: ClaudiusPlugin[];
+     }
+
+     /** An analytics event emitted by {@link pluginAnalytics}. */
+     export declare type ClaudiusAnalyticsEvent = {
+         /** Event discriminant. */
+         type: "message_sent";
+         /** Always `"user"`. */
+         role: "user";
+         /** Message text, or `""` when `includeContent` is `false`. */
+         content: string;
+         /** Length of the message in characters. */
+         chars: number;
+     } | {
+         /** Event discriminant. */
+         type: "message_received";
+         /** Always `"assistant"`. */
+         role: "assistant";
+         /** Reply text, or `""` when `includeContent` is `false`. */
+         content: string;
+         /** Length of the reply in characters. */
+         chars: number;
+     } | {
+         /** Event discriminant. */
+         type: "chat_error";
+         /** The error message. */
+         message: string;
+         /** Machine-readable error code, when available (e.g. `"TIMEOUT"`). */
+         code?: string;
+     };
+
+     /**
+      * A client-side middleware that runs around the chat message lifecycle. Pass
+      * an array of plugins to {@link ChatWidget} via the `plugins` prop; hooks run
+      * in array order.
+      *
+      * Hooks may be async, and may modify, replace, or short-circuit messages. A
+      * hook that throws is caught and logged — a misbehaving plugin will not break
+      * the chat — so security-sensitive transforms (e.g. PII redaction) should be
+      * written defensively.
+      *
+      * @example
+      * ```ts
+      * const logger: ClaudiusPlugin = {
+      *   name: "logger",
+      *   onBeforeSend: (message) => { console.log("sending", message.content); },
+      *   onAfterReceive: (message) => { console.log("received", message.content); },
+      * };
+      * ```
+      */
+     export declare interface ClaudiusPlugin {
+         /** Stable identifier, used in log messages. */
+         name: string;
+         /**
+          * Runs before the user message is sent. Return a {@link ChatMessage} to
+          * replace it (the returned message is both displayed and sent), return
+          * nothing to leave it unchanged, or call {@link BeforeSendContext.respondWith}
+          * / {@link BeforeSendContext.abort} to short-circuit.
+          */
+         onBeforeSend?(message: ChatMessage, ctx: BeforeSendContext): MaybePromise<ChatMessage | void>;
+         /**
+          * Runs after the assistant reply is received, before it is rendered. Return
+          * a {@link ChatMessage} to replace it, or nothing to leave it unchanged.
+          */
+         onAfterReceive?(message: ChatMessage, ctx: PluginContext): MaybePromise<ChatMessage | void>;
+         /**
+          * Runs when a send fails. Observe the error, or call
+          * {@link ErrorContext.respondWith} to render a fallback reply instead of the
+          * error UI.
+          */
+         onError?(error: Error, ctx: ErrorContext): MaybePromise<void>;
+     }
+
+     /**
+      * A Claudius design-token theme. Every value is a CSS string applied via
+      * --cl-* custom properties. `colors` apply to both light and dark modes
+      * unless `colorsDark` overrides a token for dark mode specifically.
+      *
+      * JSON theme files validate against
+      * https://claudius-docs.pages.dev/schema/theme.v1.json
+      */
+     export declare interface ClaudiusTheme {
+         /** Optional JSON Schema URL, for editor validation and autocomplete. */
+         $schema?: string;
+         /** Human-readable theme name. */
+         name?: string;
+         /** Initial color scheme this theme is designed for. Defaults to "light". */
+         colorScheme?: "light" | "dark" | "auto";
+         /** Color token overrides applied in both light and dark mode. */
+         colors?: Partial<Record<ThemeColorToken, string>>;
+         /** Color token overrides applied only in dark mode, layered over {@link ClaudiusTheme.colors}. */
+         colorsDark?: Partial<Record<ThemeColorToken, string>>;
+         /** Border-radius token overrides. */
+         radii?: Partial<Record<ThemeRadiusToken, string>>;
+         /** Box-shadow token overrides. */
+         shadows?: Partial<Record<ThemeShadowToken, string>>;
+         /** Font-family token overrides. */
+         fonts?: Partial<Record<ThemeFontToken, string>>;
+     }
+
+     /**
+      * Everything the `theme` option accepts: the original color-scheme modes, a
+      * built-in theme name, an inline theme object, or a URL to a theme JSON file.
+      * `(string & {})` keeps literal autocomplete while allowing URLs.
+      */
+     export declare type ClaudiusThemeInput = "light" | "dark" | "auto" | BuiltinThemeName | ClaudiusTheme | (string & {});
+
+     /**
+      * Every user-facing string the widget renders. Pass a {@link ClaudiusTranslations}
+      * (or a partial override) to localize the UI. English is the source of truth;
+      * see {@link defaultTranslations}.
+      */
+     export declare interface ClaudiusTranslations {
+         /** Chat window header title. */
+         title: string;
+         /** Chat window header subtitle. */
+         subtitle: string;
+         /** First assistant message shown when the chat opens. */
+         welcomeMessage: string;
+         /** Accessible label for the close button. */
+         closeChat: string;
+         /** Accessible label for the message list region. */
+         chatMessages: string;
+         /** Accessible label for the typing indicator. */
+         typingIndicator: string;
+         /** Placeholder text for the message input. */
+         placeholder: string;
+         /** Accessible label for the send button. */
+         sendMessage: string;
+         /** Accessible label for the message input field. */
+         typeYourMessage: string;
+         /** Accessible label for the button that opens the chat. */
+         openChat: string;
+         /** Accessible label for dismissing the greeting bubble. */
+         dismissGreeting: string;
+         /** Generic fallback error message. */
+         errorGeneric: string;
+         /** Error shown when the network request fails. */
+         errorConnection: string;
+         /** Error shown when a request times out. */
+         errorTimeout: string;
+         /** Error shown when rate-limited (per-minute limit). */
+         errorRateLimitMinute: string;
+         /** Error shown when rate-limited (per-hour limit). */
+         errorRateLimitHour: string;
+         /** Label for the retry action on a failed message. */
+         errorRetry: string;
+     }
+
+     /**
+      * Build a complete {@link ClaudiusTranslations} from the English defaults,
+      * applying the given overrides.
+      *
+      * @param overrides - Strings to override on top of {@link defaultTranslations}.
+      * @returns A complete translations object.
+      */
+     export declare function createTranslations(overrides?: Partial<ClaudiusTranslations>): ClaudiusTranslations;
+
+     /**
+      * Error thrown by {@link ChatApiClient.sendMessage} when a send is rejected
+      * for arriving within the configured debounce window.
+      */
+     export declare class DebounceError extends Error {
+         /** Creates a `DebounceError` with a fixed message. */
+         constructor();
+     }
+
+     /**
+      * Default PII patterns: email addresses, North-American-style phone numbers,
+      * US Social Security numbers, and 13–16 digit card-like sequences. These are
+      * intentionally conservative starting points — tune {@link RedactPiiOptions.patterns}
+      * for your data.
+      */
+     export declare const DEFAULT_PII_PATTERNS: readonly RegExp[];
+
+     /** The default (English) translations, used when no locale or override applies. */
+     export declare const defaultTranslations: ClaudiusTranslations;
+
+     /**
+      * Detect the best {@link LocaleCode} for the current environment: the document
+      * `lang` attribute first, then the browser language, falling back to `"en"`.
+      *
+      * @returns The detected locale code.
+      */
+     export declare function detectLocale(): LocaleCode;
+
+     /**
+      * Context for {@link ClaudiusPlugin.onError}. Adds the ability to recover from
+      * a failed send by rendering a reply in place of the error UI.
+      */
+     export declare interface ErrorContext extends PluginContext {
+         /**
+          * Recover from the failure by rendering this assistant reply instead of the
+          * error state. Stops the hook chain — later plugins' `onError` hooks do not
+          * run.
+          */
+         respondWith(reply: string | PluginReply): void;
+     }
+
+     /** BCP-47 primary language subtags the widget ships built-in translations for. */
+     export declare type LocaleCode = "en" | "es" | "fr" | "de";
+
+     /** Built-in translations keyed by {@link LocaleCode}. */
+     export declare const locales: Record<LocaleCode, ClaudiusTranslations>;
+
+     /** A value that may be returned synchronously or as a promise. */
+     export declare type MaybePromise<T> = T | Promise<T>;
+
+     /**
+      * Reference plugin that emits a structured analytics event for every message
+      * sent, every reply received, and every error. It never modifies messages.
+      *
+      * @example
+      * ```ts
+      * <ChatWidget
+      *   apiUrl={url}
+      *   plugins={[pluginAnalytics({ onEvent: (e) => gtag("event", e.type, e) })]}
+      * />
+      * ```
+      */
+     export declare function pluginAnalytics(options: AnalyticsPluginOptions): ClaudiusPlugin;
+
+     /**
+      * Reference plugin that answers matching messages locally, without calling the
+      * API. The first rule whose matcher fires short-circuits the send via
+      * `ctx.respondWith`, so the network is never hit for that turn.
+      *
+      * @example
+      * ```ts
+      * <ChatWidget
+      *   apiUrl={url}
+      *   plugins={[pluginCannedResponses({
+      *     rules: [
+      *       { match: "hours", reply: "We're open 9-5, Mon-Fri." },
+      *       { match: /pricing|cost/i, reply: "See https://example.com/pricing." },
+      *     ],
+      *   })]}
+      * />
+      * ```
+      */
+     export declare function pluginCannedResponses(options: CannedResponsesOptions): ClaudiusPlugin;
+
+     /**
+      * Read-only context shared by every plugin hook.
+      *
+      * `messages` is a snapshot of the conversation at the moment the hook runs:
+      * in {@link ClaudiusPlugin.onBeforeSend} it excludes the in-flight user
+      * message; in {@link ClaudiusPlugin.onAfterReceive} and
+      * {@link ClaudiusPlugin.onError} it includes it.
+      */
+     export declare interface PluginContext {
+         /** Conversation snapshot, oldest message first. Treat as immutable. */
+         readonly messages: readonly ChatMessage[];
+         /** The Worker chat endpoint URL the widget posts to. */
+         readonly apiUrl: string;
+     }
+
+     /**
+      * Reference plugin that strips PII from the user's message before it leaves the
+      * browser. The redacted text is what gets displayed and sent, so the user sees
+      * that redaction happened. Optionally redacts assistant replies too.
+      *
+      * @example
+      * ```ts
+      * <ChatWidget apiUrl={url} plugins={[pluginRedactPII()]} />
+      * ```
+      */
+     export declare function pluginRedactPII(options?: RedactPiiOptions): ClaudiusPlugin;
+
+     /**
+      * A synthesized assistant reply, produced by a plugin instead of (or in
+      * recovery from) a network round-trip. Passed to
+      * {@link BeforeSendContext.respondWith} and {@link ErrorContext.respondWith}.
+      */
+     export declare interface PluginReply {
+         /** The assistant reply text to render. */
+         content: string;
+         /** Optional sources to attach to the synthesized reply. */
+         sources?: Source[];
+     }
+
+     /** Options for {@link pluginRedactPII}. */
+     export declare interface RedactPiiOptions {
+         /**
+          * Patterns to redact. Each must carry the global (`g`) flag.
+          * @defaultValue {@link DEFAULT_PII_PATTERNS}
+          */
+         patterns?: readonly RegExp[];
+         /**
+          * Text substituted for each match.
+          * @defaultValue `"[redacted]"`
+          */
+         replacement?: string;
+         /**
+          * Also redact the assistant's replies, not just outgoing user messages.
+          * @defaultValue `false`
+          */
+         redactReplies?: boolean;
+     }
+
+     /** Replace every match of every pattern in `text` with `replacement`. */
+     export declare function redactText(text: string, patterns: readonly RegExp[], replacement: string): string;
+
+     /**
+      * Resolve the final translations for a locale, applying any per-string
+      * overrides on top of the chosen locale's defaults.
+      *
+      * @param options - Locale and override settings.
+      * @returns A complete translations object.
+      */
+     export declare function resolveTranslations(options?: ResolveTranslationsOptions): ClaudiusTranslations;
+
+     /** Options for {@link resolveTranslations}. */
+     export declare interface ResolveTranslationsOptions {
+         /** Locale to use. Defaults to the result of {@link detectLocale}. */
+         locale?: LocaleCode;
+         /** Per-string overrides layered over the chosen locale's translations. */
+         translations?: Partial<ClaudiusTranslations>;
+     }
+
+     /**
+      * A cited source the assistant referenced when answering. Rendered as a link
+      * in the chat and grouped in the sources sidebar.
+      */
+     export declare interface Source {
+         /** Absolute URL of the source. */
+         url: string;
+         /** Human-readable link title shown to the user. */
+         title: string;
+         /** Origin category, used to group and label the source. */
+         type: "blog" | "page" | "external";
+     }
+
+     declare const THEME_COLOR_TOKENS: readonly ["accent", "accentText", "accentSoft", "accentTextMuted", "surface", "surfaceMuted", "text", "textMuted", "border", "userBubble", "userBubbleText", "assistantBubble", "assistantBubbleText", "field", "error", "errorSurface", "errorText", "link", "scrim"];
+
+     declare const THEME_FONT_TOKENS: readonly ["heading", "body"];
+
+     declare const THEME_RADIUS_TOKENS: readonly ["sm", "md", "lg", "full", "tail"];
+
+     declare const THEME_SHADOW_TOKENS: readonly ["elevated", "floating", "floatingHover"];
+
+     /** Names of the color tokens a theme can override (e.g. `accent`, `surface`, `text`). */
+     export declare type ThemeColorToken = (typeof THEME_COLOR_TOKENS)[number];
+
+     /** Names of the font-family tokens a theme can override. */
+     export declare type ThemeFontToken = (typeof THEME_FONT_TOKENS)[number];
+
+     /** Names of the border-radius tokens a theme can override. */
+     export declare type ThemeRadiusToken = (typeof THEME_RADIUS_TOKENS)[number];
+
+     /** Names of the box-shadow tokens a theme can override. */
+     export declare type ThemeShadowToken = (typeof THEME_SHADOW_TOKENS)[number];
+
+     /**
+      * A proactive engagement rule. Each variant fires at most once per page on a
+      * different signal: elapsed time, scroll depth, exit intent, or URL match.
+      */
+     export declare type Trigger = {
+         /** Fire after a fixed dwell time. */
+         on: "time";
+         /** Seconds to wait before firing. */
+         seconds: number;
+         /** Only fire when the current URL matches this pattern. */
+         matchUrl?: UrlPattern;
+         /** Action to run when the trigger fires. */
+         action: TriggerAction;
+     } | {
+         /** Fire once the user scrolls past a depth threshold. */
+         on: "scroll";
+         /** Scroll depth (0-100) that fires the trigger. */
+         percent: number;
+         /** Only fire when the current URL matches this pattern. */
+         matchUrl?: UrlPattern;
+         /** Action to run when the trigger fires. */
+         action: TriggerAction;
+     } | {
+         /** Fire when the pointer leaves the top of the viewport (exit intent). */
+         on: "exit-intent";
+         /** Only fire when the current URL matches this pattern. */
+         matchUrl?: UrlPattern;
+         /** Action to run when the trigger fires. */
+         action: TriggerAction;
+     } | {
+         /** Fire immediately when the current URL matches. */
+         on: "url";
+         /** URL pattern that must match for the trigger to fire. */
+         pattern: UrlPattern;
+         /** Action to run when the trigger fires. */
+         action: TriggerAction;
+     };
+
+     /**
+      * What a {@link Trigger} does when it fires: open the chat, or show a greeting
+      * bubble with the given message.
+      */
+     export declare type TriggerAction = "open" | {
+         /** Greeting bubble message to display. */
+         greeting: string;
+     };
+
+     /** A URL match: a case-insensitive substring, or a regular expression. */
+     export declare type UrlPattern = string | RegExp;
+
+     /** Corner of the viewport the widget docks to. */
+     export declare type WidgetPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+
+     export { }