claudius-chat-widget 1.8.2 → 1.9.0

package/dist/index.d.cts

@@ -1,5 +1,39 @@
 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";
 
@@ -10,6 +44,31 @@ export declare type BuiltinThemeName = "default" | "minimal" | "playful" | "corp
  */
 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
@@ -158,7 +217,7 @@ export declare class ChatApiClient {
       * <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, }: ChatWidgetProps): JSX_2.Element;
+     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.
@@ -203,6 +262,82 @@ export declare class ChatApiClient {
          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>;
      }
 
      /**
@@ -299,6 +434,14 @@ export declare class ChatApiClient {
          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;
 
@@ -310,12 +453,123 @@ export declare class ChatApiClient {
       */
      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.

package/dist/index.d.ts

@@ -1,5 +1,39 @@
 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";
 
@@ -10,6 +44,31 @@ export declare type BuiltinThemeName = "default" | "minimal" | "playful" | "corp
  */
 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
@@ -158,7 +217,7 @@ export declare class ChatApiClient {
       * <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, }: ChatWidgetProps): JSX_2.Element;
+     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.
@@ -203,6 +262,82 @@ export declare class ChatApiClient {
          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>;
      }
 
      /**
@@ -299,6 +434,14 @@ export declare class ChatApiClient {
          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;
 
@@ -310,12 +453,123 @@ export declare class ChatApiClient {
       */
      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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudius-chat-widget",
-  "version": "1.8.2",
+  "version": "1.9.0",
   "type": "module",
   "description": "Embeddable AI chat widget powered by Claude. Drop-in React component or standalone script embed, backed by a Cloudflare Worker.",
   "keywords": [
@@ -63,7 +63,7 @@
     "test:coverage": "vitest run --coverage",
     "e2e": "playwright test",
     "e2e:ui": "playwright test --ui",
-    "e2e:install": "playwright install chromium",
+    "e2e:install": "playwright install chromium webkit",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "format": "prettier --write \"src/**/*.{ts,tsx,css}\"",