claudius-chat-widget 1.17.0 → 1.18.0

package/dist/index.d.cts

@@ -116,6 +116,7 @@ export declare class ChatApiClient {
     private readonly maxRetries;
     private readonly debounceMs;
     private readonly timeoutMs;
+    private readonly citations;
     private lastSendTime;
     /**
      * Create a chat client for the given Worker base URL.
@@ -198,6 +199,12 @@ export declare class ChatApiClient {
                * @defaultValue `30000`
                */
               timeoutMs?: number;
+              /**
+               * Send `citations: true` with every request, asking the worker to number
+               * its retrieved excerpts and have the model cite them as `[n]`.
+               * @defaultValue `false`
+               */
+              citations?: boolean;
           }
 
           /**
@@ -295,6 +302,11 @@ export declare class ChatApiClient {
           export declare interface ChatRequest {
               /** The full conversation so far, oldest message first. */
               messages: ChatMessage[];
+              /**
+               * Ask the worker to number its retrieved excerpts to match `sources` and
+               * to have the model cite them as `[n]`. Sent by widgets with citations on.
+               */
+              citations?: boolean;
           }
 
           /**
@@ -327,6 +339,12 @@ export declare class ChatApiClient {
                * show a "used tool" affordance before the reply completes.
                */
               onToolUse?: (toolUse: ToolUse, allToolUses: ToolUse[]) => void;
+              /**
+               * Called when the worker announces the reply's sources ahead of the text,
+               * so citation chips can render while the reply streams. The `done` event
+               * carries the final list.
+               */
+              onSources?: (sources: Source[]) => void;
               /**
                * Cancels the stream when aborted. Cancellation is not an error: the
                * promise resolves with the partial reply and `aborted: true`.
@@ -352,7 +370,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, plugins, streaming, attachments, voice, conversationExport, }: ChatWidgetProps): JSX_2.Element;
+          export declare function ChatWidget({ apiUrl, title, subtitle, welcomeMessage, placeholder, persistMessages, storageKeyPrefix, requestTimeoutMs, theme, accentColor, position, locale, translations: translationOverrides, triggers, plugins, streaming, attachments, voice, conversationExport, citations, }: ChatWidgetProps): JSX_2.Element;
 
           /**
            * Props for the {@link ChatWidget} component.
@@ -438,6 +456,36 @@ export declare class ChatApiClient {
                * @defaultValue `false`
                */
               conversationExport?: boolean;
+              /**
+               * Render `[n]` citations in grounded replies as numbered chips, with a
+               * collapsible footer of source cards under the reply. `true` enables the
+               * defaults (five cards before "Show all", favicons on); pass a
+               * {@link CitationsOptions} to tune them. The widget also asks the worker to
+               * number its retrieved excerpts, so this needs a worker from 1.18.0 or
+               * later with RAG on to have any effect. Only `true` or an object enables
+               * it. See the Inline citations guide.
+               * @defaultValue `false`
+               */
+              citations?: boolean | CitationsOptions;
+          }
+
+          /**
+           * Inline citations. Pass to {@link ChatWidget} via the `citations` prop (or
+           * `true` for the defaults). `[n]` markers in a grounded reply become chips
+           * and its sources become a footer of cards.
+           */
+          export declare interface CitationsOptions {
+              /**
+               * Source cards shown before the "Show all" control. Positive integer.
+               * @defaultValue `5`
+               */
+              maxSources?: number;
+              /**
+               * Show each source's favicon, fetched from `/favicon.ico` on the source's
+               * own origin with no referrer. Set to `false` to make no such requests.
+               * @defaultValue `true`
+               */
+              favicons?: boolean;
           }
 
           /** An analytics event emitted by {@link pluginAnalytics}. */
@@ -641,6 +689,16 @@ export declare class ChatApiClient {
               transcriptAttachments: string;
               /** Transcript label above a message's citation list, including its colon. */
               transcriptSources: string;
+              /** Label of the sources footer under a cited reply, and of its list. */
+              sources: string;
+              /** Button that reveals the remaining source cards; supports `{count}`. */
+              showAllSources: string;
+              /** Button that hides the extra source cards again. */
+              showFewerSources: string;
+              /** Accessible name of a citation chip; supports `{n}` and `{title}`. */
+              citation: string;
+              /** Visually hidden hint appended to links that open a new tab. */
+              opensInNewTab: string;
               /** Generic fallback error message. */
               errorGeneric: string;
               /** Error shown when the network request fails. */
@@ -680,6 +738,9 @@ export declare class ChatApiClient {
           /** Defaults applied when attachments are enabled with `true` or a partial config. */
           export declare const DEFAULT_ATTACHMENT_OPTIONS: ResolvedAttachmentsConfig;
 
+          /** Defaults applied when citations are enabled with `true` or a partial config. */
+          export declare const DEFAULT_CITATIONS_OPTIONS: ResolvedCitationsConfig;
+
           /**
            * Default PII patterns: email addresses, North-American-style phone numbers,
            * US Social Security numbers, and 13–16 digit card-like sequences. These are
@@ -819,6 +880,9 @@ export declare class ChatApiClient {
           /** {@link AttachmentsOptions} with every field filled in. */
           export declare type ResolvedAttachmentsConfig = Required<AttachmentsOptions>;
 
+          /** {@link CitationsOptions} with every field filled in. */
+          export declare type ResolvedCitationsConfig = Required<CitationsOptions>;
+
           /** {@link VoiceOptions} with every field filled in. */
           export declare type ResolvedVoiceConfig = Required<VoiceOptions>;
 
@@ -850,6 +914,11 @@ export declare class ChatApiClient {
               title: string;
               /** Origin category, used to group and label the source. */
               type: "blog" | "page" | "external";
+              /**
+               * Short plain-text excerpt of the page, shown on its source card. About
+               * 200 characters. Absent from workers that predate citations.
+               */
+              snippet?: string;
           }
 
           /**

package/dist/index.d.ts

@@ -116,6 +116,7 @@ export declare class ChatApiClient {
     private readonly maxRetries;
     private readonly debounceMs;
     private readonly timeoutMs;
+    private readonly citations;
     private lastSendTime;
     /**
      * Create a chat client for the given Worker base URL.
@@ -198,6 +199,12 @@ export declare class ChatApiClient {
                * @defaultValue `30000`
                */
               timeoutMs?: number;
+              /**
+               * Send `citations: true` with every request, asking the worker to number
+               * its retrieved excerpts and have the model cite them as `[n]`.
+               * @defaultValue `false`
+               */
+              citations?: boolean;
           }
 
           /**
@@ -295,6 +302,11 @@ export declare class ChatApiClient {
           export declare interface ChatRequest {
               /** The full conversation so far, oldest message first. */
               messages: ChatMessage[];
+              /**
+               * Ask the worker to number its retrieved excerpts to match `sources` and
+               * to have the model cite them as `[n]`. Sent by widgets with citations on.
+               */
+              citations?: boolean;
           }
 
           /**
@@ -327,6 +339,12 @@ export declare class ChatApiClient {
                * show a "used tool" affordance before the reply completes.
                */
               onToolUse?: (toolUse: ToolUse, allToolUses: ToolUse[]) => void;
+              /**
+               * Called when the worker announces the reply's sources ahead of the text,
+               * so citation chips can render while the reply streams. The `done` event
+               * carries the final list.
+               */
+              onSources?: (sources: Source[]) => void;
               /**
                * Cancels the stream when aborted. Cancellation is not an error: the
                * promise resolves with the partial reply and `aborted: true`.
@@ -352,7 +370,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, plugins, streaming, attachments, voice, conversationExport, }: ChatWidgetProps): JSX_2.Element;
+          export declare function ChatWidget({ apiUrl, title, subtitle, welcomeMessage, placeholder, persistMessages, storageKeyPrefix, requestTimeoutMs, theme, accentColor, position, locale, translations: translationOverrides, triggers, plugins, streaming, attachments, voice, conversationExport, citations, }: ChatWidgetProps): JSX_2.Element;
 
           /**
            * Props for the {@link ChatWidget} component.
@@ -438,6 +456,36 @@ export declare class ChatApiClient {
                * @defaultValue `false`
                */
               conversationExport?: boolean;
+              /**
+               * Render `[n]` citations in grounded replies as numbered chips, with a
+               * collapsible footer of source cards under the reply. `true` enables the
+               * defaults (five cards before "Show all", favicons on); pass a
+               * {@link CitationsOptions} to tune them. The widget also asks the worker to
+               * number its retrieved excerpts, so this needs a worker from 1.18.0 or
+               * later with RAG on to have any effect. Only `true` or an object enables
+               * it. See the Inline citations guide.
+               * @defaultValue `false`
+               */
+              citations?: boolean | CitationsOptions;
+          }
+
+          /**
+           * Inline citations. Pass to {@link ChatWidget} via the `citations` prop (or
+           * `true` for the defaults). `[n]` markers in a grounded reply become chips
+           * and its sources become a footer of cards.
+           */
+          export declare interface CitationsOptions {
+              /**
+               * Source cards shown before the "Show all" control. Positive integer.
+               * @defaultValue `5`
+               */
+              maxSources?: number;
+              /**
+               * Show each source's favicon, fetched from `/favicon.ico` on the source's
+               * own origin with no referrer. Set to `false` to make no such requests.
+               * @defaultValue `true`
+               */
+              favicons?: boolean;
           }
 
           /** An analytics event emitted by {@link pluginAnalytics}. */
@@ -641,6 +689,16 @@ export declare class ChatApiClient {
               transcriptAttachments: string;
               /** Transcript label above a message's citation list, including its colon. */
               transcriptSources: string;
+              /** Label of the sources footer under a cited reply, and of its list. */
+              sources: string;
+              /** Button that reveals the remaining source cards; supports `{count}`. */
+              showAllSources: string;
+              /** Button that hides the extra source cards again. */
+              showFewerSources: string;
+              /** Accessible name of a citation chip; supports `{n}` and `{title}`. */
+              citation: string;
+              /** Visually hidden hint appended to links that open a new tab. */
+              opensInNewTab: string;
               /** Generic fallback error message. */
               errorGeneric: string;
               /** Error shown when the network request fails. */
@@ -680,6 +738,9 @@ export declare class ChatApiClient {
           /** Defaults applied when attachments are enabled with `true` or a partial config. */
           export declare const DEFAULT_ATTACHMENT_OPTIONS: ResolvedAttachmentsConfig;
 
+          /** Defaults applied when citations are enabled with `true` or a partial config. */
+          export declare const DEFAULT_CITATIONS_OPTIONS: ResolvedCitationsConfig;
+
           /**
            * Default PII patterns: email addresses, North-American-style phone numbers,
            * US Social Security numbers, and 13–16 digit card-like sequences. These are
@@ -819,6 +880,9 @@ export declare class ChatApiClient {
           /** {@link AttachmentsOptions} with every field filled in. */
           export declare type ResolvedAttachmentsConfig = Required<AttachmentsOptions>;
 
+          /** {@link CitationsOptions} with every field filled in. */
+          export declare type ResolvedCitationsConfig = Required<CitationsOptions>;
+
           /** {@link VoiceOptions} with every field filled in. */
           export declare type ResolvedVoiceConfig = Required<VoiceOptions>;
 
@@ -850,6 +914,11 @@ export declare class ChatApiClient {
               title: string;
               /** Origin category, used to group and label the source. */
               type: "blog" | "page" | "external";
+              /**
+               * Short plain-text excerpt of the page, shown on its source card. About
+               * 200 characters. Absent from workers that predate citations.
+               */
+              snippet?: string;
           }
 
           /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudius-chat-widget",
-  "version": "1.17.0",
+  "version": "1.18.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": [