@cloudflare/ai-search-snippet 0.0.38 → 0.0.39

package/dist/main.d.ts

@@ -9,6 +9,13 @@ export declare class AISearchClient {
     search(query: string, options?: Omit<SearchOptions, 'query'>): Promise<SearchResult[]>;
     searchStream(query: string, options?: Omit<SearchOptions, 'query'>): AsyncGenerator<SearchResult | SearchError, void, undefined>;
     chat(query: string, options?: ChatOptions): AsyncGenerator<ChatTypes, void, undefined>;
+    /**
+     * Consume an SSE stream from the chat/completions endpoint and yield one
+     * ChatTextResponse per non-empty content delta. Discards `event: chunks`
+     * (RAG sources) and the `[DONE]` sentinel; tolerates malformed individual
+     * frames without aborting the whole stream.
+     */
+    private parseChatStream;
     /**
      * Cancels an active request by ID
      */
@@ -41,6 +48,23 @@ export declare interface ApiError {
     details?: Record<string, unknown>;
 }
 
+/**
+ * Stats Client
+ *
+ * Sends search analytics events to the `/stats` endpoint as fire-and-forget
+ * POST requests. Events are buffered and flushed in batches to reduce request
+ * count, and any remaining events are flushed via `navigator.sendBeacon` (or a
+ * keepalive `fetch` fallback) when the page is unloaded.
+ */
+/**
+ * Shared fields across every analytics event.
+ */
+declare interface BaseStatsEvent {
+    inputQuery: string;
+    snippetVersion: string;
+    totalResult: number;
+}
+
 export declare class ChatBubbleSnippet extends HTMLElement {
     private shadow;
     private client;
@@ -50,11 +74,12 @@ export declare class ChatBubbleSnippet extends HTMLElement {
     private isMinimized;
     private translationsOverride;
     private resolvedTranslations;
+    private chatQueryRewriteOverride;
     private handleBubbleClick;
     private handleCloseClick;
     private handleMinimizeClick;
     private handleClearClick;
-    static get observedAttributes(): readonly ["api-url", "placeholder", "theme", "hide-branding", "translations"];
+    static get observedAttributes(): readonly ["api-url", "placeholder", "theme", "hide-branding", "translations", "chat-query-rewrite"];
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -63,6 +88,12 @@ export declare class ChatBubbleSnippet extends HTMLElement {
      * Get the current translations object.
      */
     get translations(): Translations | null;
+    /**
+     * Override AI Search query rewriting on subsequent chat turns. Setting
+     * `null` falls back to parsing the `chat-query-rewrite` attribute.
+     */
+    get chatQueryRewrite(): SearchSnippetProps['chatQueryRewrite'] | null;
+    set chatQueryRewrite(value: SearchSnippetProps['chatQueryRewrite'] | null | undefined);
     /**
      * Override any user-facing string. Omitted keys fall back to English defaults.
      */
@@ -70,6 +101,7 @@ export declare class ChatBubbleSnippet extends HTMLElement {
     private syncTranslationsFromAttribute;
     private rerenderAfterTranslationsChange;
     private getProps;
+    private resolveChatQueryRewrite;
     private initializeClient;
     private render;
     private getBubbleStyles;
@@ -92,12 +124,31 @@ declare type ChatError = {
     message: string;
 };
 
+/**
+ * A single chat message in the conversation history.
+ */
+declare interface ChatMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+
 /**
  * Chat options
  */
 export declare interface ChatOptions {
     stream?: boolean;
     signal?: AbortSignal;
+    /** Prior conversation turns to send before the new user query. */
+    history?: ChatMessage[];
+    /**
+     * Enable AI Search query rewriting. Pass `true` to use built-in defaults,
+     * an object to override the model and/or rewrite prompt, or omit / pass
+     * `false` to disable.
+     */
+    queryRewrite?: boolean | {
+        model?: string;
+        rewritePrompt?: string;
+    };
 }
 
 export declare class ChatPageSnippet extends HTMLElement {
@@ -110,12 +161,13 @@ export declare class ChatPageSnippet extends HTMLElement {
     private sidebarCollapsed;
     private translationsOverride;
     private resolvedTranslations;
+    private chatQueryRewriteOverride;
     private handleClearClick;
     private handleNewChatClick;
     private handleToggleSidebarClick;
     private handleChatListClick;
     private handleMessageEvent;
-    static get observedAttributes(): readonly ["api-url", "placeholder", "theme", "hide-branding", "translations"];
+    static get observedAttributes(): readonly ["api-url", "placeholder", "theme", "hide-branding", "translations", "chat-query-rewrite"];
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -124,6 +176,12 @@ export declare class ChatPageSnippet extends HTMLElement {
      * Get the current translations object.
      */
     get translations(): Translations | null;
+    /**
+     * Override AI Search query rewriting on subsequent chat turns. Setting
+     * `null` falls back to parsing the `chat-query-rewrite` attribute.
+     */
+    get chatQueryRewrite(): SearchSnippetProps['chatQueryRewrite'] | null;
+    set chatQueryRewrite(value: SearchSnippetProps['chatQueryRewrite'] | null | undefined);
     /**
      * Override any user-facing string. Omitted keys fall back to English defaults.
      */
@@ -137,6 +195,7 @@ export declare class ChatPageSnippet extends HTMLElement {
     private refreshDefaultSessionTitles;
     private rerenderAfterTranslationsChange;
     private getProps;
+    private resolveChatQueryRewrite;
     private initializeClient;
     private render;
     private getPageStyles;
@@ -200,6 +259,15 @@ declare type ChatTextResponse = {
 
 declare type ChatTypes = ChatResult | ChatTextResponse | ChatError;
 
+/**
+ * Fired when a user clicks a specific result in the list.
+ */
+export declare interface ClickStatsEvent extends BaseStatsEvent {
+    clickedResultId: string;
+    clickPosition: number;
+    clickViewMore: false;
+}
+
 export declare const DEFAULT_TRANSLATIONS: Required<Translations>;
 
 /**
@@ -230,6 +298,7 @@ declare interface RequestState {
 declare class SearchBarSnippet extends HTMLElement {
     private shadow;
     private client;
+    private stats;
     private container;
     private inputElement;
     private resultsContainer;
@@ -240,11 +309,15 @@ declare class SearchBarSnippet extends HTMLElement {
     private loadingMessageIndex;
     private translationsOverride;
     private resolvedTranslations;
+    private lastSearchQuery;
+    private lastSearchTotal;
     private handleInputChange;
     private handleInputKeydownEnter;
     private handleInputKeydownEscape;
     private handleSearchButtonClick;
-    static get observedAttributes(): readonly ["api-url", "placeholder", "max-results", "max-render-results", "debounce-ms", "theme", "hide-branding", "show-url", "show-date", "hide-thumbnails", "see-more", "request-options", "translations"];
+    private handleResultClick;
+    private handleSeeMoreClick;
+    static get observedAttributes(): readonly ["api-url", "placeholder", "max-results", "max-render-results", "debounce-ms", "theme", "hide-branding", "show-url", "show-date", "hide-thumbnails", "see-more", "disable-analytics", "request-options", "translations"];
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -266,6 +339,7 @@ declare class SearchBarSnippet extends HTMLElement {
     private getProps;
     private getRequestOptions;
     private initializeClient;
+    private destroyStatsClient;
     private render;
     private attachEventListeners;
     private performSearch;
@@ -273,6 +347,7 @@ declare class SearchBarSnippet extends HTMLElement {
     private renderResult;
     private renderResultImage;
     private attachResultHandlers;
+    private detachResultTrackingHandlers;
     private showLoadingState;
     private startLoadingInterval;
     private clearLoadingInterval;
@@ -298,6 +373,7 @@ declare interface SearchError {
 export declare class SearchModalSnippet extends HTMLElement {
     private shadow;
     private client;
+    private stats;
     private backdrop;
     private modal;
     private inputElement;
@@ -312,13 +388,16 @@ export declare class SearchModalSnippet extends HTMLElement {
     private loadingMessageIndex;
     private translationsOverride;
     private resolvedTranslations;
+    private lastSearchQuery;
+    private lastSearchTotal;
     private handleGlobalKeydown;
     private handleInputChange;
     private handleInputKeydown;
     private handleBackdropClick;
+    private handleResultsContainerClick;
     private savedBodyStyles;
     private savedHtmlOverflow;
-    static get observedAttributes(): readonly ["api-url", "placeholder", "max-results", "max-render-results", "theme", "shortcut", "use-meta-key", "debounce-ms", "hide-branding", "show-url", "show-date", "hide-thumbnails", "see-more", "request-options", "translations"];
+    static get observedAttributes(): readonly ["api-url", "placeholder", "max-results", "max-render-results", "theme", "shortcut", "use-meta-key", "debounce-ms", "hide-branding", "show-url", "show-date", "hide-thumbnails", "see-more", "disable-analytics", "request-options", "translations"];
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -342,6 +421,7 @@ export declare class SearchModalSnippet extends HTMLElement {
     private getProps;
     private getRequestOptions;
     private initializeClient;
+    private destroyStatsClient;
     private render;
     private attachGlobalKeyboardShortcut;
     private attachEventListeners;
@@ -353,6 +433,7 @@ export declare class SearchModalSnippet extends HTMLElement {
     private renderResult;
     private renderResultImage;
     private attachResultHandlers;
+    private detachResultsContainerClick;
     private renderEmptyState;
     private showEmptyState;
     private showLoadingState;
@@ -456,6 +537,11 @@ export declare interface SearchSnippetProps {
     hideThumbnails?: boolean;
     /** URL template for "See more" link. The search query is appended URL-encoded. Example: "https://example.com/search?q=" */
     seeMore?: string;
+    /**
+     * Disable sending search / click / view-more analytics events to the
+     * `/stats` endpoint. Defaults to `false` (analytics enabled).
+     */
+    disableAnalytics?: boolean;
     /**
      * Override any user-facing string. Omitted keys fall back to English defaults.
      *
@@ -465,8 +551,97 @@ export declare interface SearchSnippetProps {
      * ```
      */
     translations?: Translations;
+    /**
+     * Customize AI Search query rewriting on subsequent chat turns.
+     *
+     * Query rewriting is automatically enabled from the second user message
+     * onward (the first message has no history to rewrite from). Use this to
+     * override the model, the rewrite prompt, or to disable the feature.
+     *
+     * @example
+     * ```ts
+     * element.chatQueryRewrite = { enabled: false };
+     * element.chatQueryRewrite = { model: 'openai/gpt-5-mini' };
+     * element.chatQueryRewrite = { rewritePrompt: 'Rewrite the latest user message...' };
+     * ```
+     */
+    chatQueryRewrite?: {
+        /** Override the auto-enable behavior. Defaults to true on subsequent turns. */
+        enabled?: boolean;
+        /** Override the rewriter model. Defaults to '@cf/meta/llama-3.3-70b-instruct-fp8-fast'. */
+        model?: string;
+        /** Override the system prompt sent as `rewrite_prompt`. Defaults to a built-in prompt. */
+        rewritePrompt?: string;
+    };
+}
+
+/**
+ * Fired after a search completes successfully (or returns zero results).
+ * Click-related fields are intentionally omitted.
+ */
+export declare type SearchStatsEvent = BaseStatsEvent;
+
+export declare class StatsClient {
+    private readonly baseUrl;
+    private readonly endpoint;
+    private readonly snippetVersion;
+    private readonly flushIntervalMs;
+    private readonly maxBufferSize;
+    private buffer;
+    private flushTimer;
+    private destroyed;
+    private readonly boundUnloadHandler;
+    private readonly boundVisibilityHandler;
+    constructor(baseUrl: string, options?: StatsClientOptions);
+    /**
+     * Record a completed search (no click).
+     */
+    trackSearch(inputQuery: string, totalResult: number): void;
+    /**
+     * Record a click on a specific result.
+     */
+    trackClick(inputQuery: string, totalResult: number, clickedResultId: string, clickPosition: number): void;
+    /**
+     * Record a click on the "See more" link.
+     */
+    trackViewMore(inputQuery: string, totalResult: number): void;
+    /**
+     * Buffer a pre-built event. Higher-level `track*` helpers call this.
+     */
+    track(event: StatsEvent): void;
+    /**
+     * Force an immediate flush using `fetch` with `keepalive: true`.
+     * Returns synchronously; network errors are swallowed.
+     */
+    flush(): void;
+    /**
+     * Flush path optimized for page-unload. Prefers `navigator.sendBeacon`
+     * when available; falls back to `fetch({ keepalive: true })`.
+     */
+    private flushBeacon;
+    /**
+     * Remove unload listeners, clear timers, and flush anything still buffered.
+     * Call from the host component's `disconnectedCallback`.
+     */
+    destroy(): void;
+    private scheduleFlush;
+    private drainBuffer;
+    private buildUrl;
 }
 
+export declare interface StatsClientOptions {
+    /** Overrides the library version placed on each event. Defaults to the built-in `SNIPPET_VERSION`. */
+    snippetVersion?: string;
+    /** Milliseconds to wait before auto-flushing a non-empty buffer. Defaults to 1500ms. */
+    flushIntervalMs?: number;
+    /** Buffer size that triggers an immediate flush. Defaults to 20. */
+    maxBufferSize?: number;
+    /** Path appended to `baseUrl`. Defaults to `/stats`. */
+    endpoint?: string;
+}
+
+export declare type StatsEvent = SearchStatsEvent | ClickStatsEvent | ViewMoreStatsEvent;
+
 export declare type Theme = 'light' | 'dark' | 'auto';
 
 /**
@@ -603,4 +778,11 @@ export declare interface Translations {
     loadingMessages?: string[];
 }
 
+/**
+ * Fired when a user clicks the "See more" affordance beneath the results.
+ */
+export declare interface ViewMoreStatsEvent extends BaseStatsEvent {
+    clickViewMore: true;
+}
+
 export { }