@chatcops/widget 0.5.0 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # @chatcops/widget
 
-Embeddable AI chatbot widget. Zero dependencies, Shadow DOM isolated, ~50KB gzipped.
+Embeddable AI chatbot widget. Zero dependencies, Shadow DOM isolated, ~13KB gzipped.
 
 ## Install
 
@@ -95,7 +95,8 @@ ChatCops.init({
   placeholder: 'Type a message...',
 
   // Behavior
-  persistHistory: true,                 // localStorage, default: true
+  persistence: 'local',                 // 'local' | 'session' | 'none', default: 'local'
+  historyTtlDays: 30,                   // drop saved chats older than this
   maxMessages: 50,                      // max persisted messages
   pageContext: true,                     // send page URL/title to API
   autoOpen: 5000,                       // auto-open after ms (popup only)
@@ -157,7 +158,7 @@ All configuration can be set via `data-*` attributes:
 - **Conversation Persistence** - localStorage for history, sessionStorage for session ID
 - **Theming** - CSS custom properties, auto-derived surface colors from `bgColor`
 - **Mobile Responsive** - Full-screen panel on screens below 768px
-- **i18n** - Built-in locale strings with custom override support
+- **i18n** - Ships in English with custom override support for any language
 - **Accessible** - ARIA labels, semantic HTML, keyboard navigation
 
 ## License

package/dist/api/client.d.ts

@@ -1,8 +1,15 @@
+import { type KeyStore } from '../storage.js';
 import type { WidgetChatRequest, WidgetChatChunk } from './types.js';
 export interface ChatClientOptions {
     apiUrl: string;
     /** Inactivity timeout in milliseconds. Defaults to 30000. */
     timeout?: number;
+    /** Cloudflare Turnstile site key, when the server checks Turnstile before issuing a session. */
+    turnstileSiteKey?: string;
+    /** The host site's signed token for a signed-in visitor, sent when asking for a session. */
+    userToken?: string;
+    /** Where the session token is kept. Defaults to localStorage; the widget passes its own store. */
+    store?: KeyStore;
 }
 export interface SendMessageOptions {
     signal?: AbortSignal;
@@ -12,7 +19,21 @@ export interface SendMessageOptions {
 export declare class ChatClient {
     private apiUrl;
     private timeout;
+    private sessionKey;
+    /** The last token, kept across page loads so the server can resume the conversation. Read on first use. */
+    private saved?;
+    private store;
+    private turnstileSiteKey?;
+    private userToken?;
     constructor(options: ChatClientOptions);
+    /**
+     * The signed-in visitor's identity token for the next session, or none.
+     * The session token from before is dropped, so the next message gets one
+     * for the new identity (the server starts a new conversation for a
+     * different user).
+     */
+    setUserToken(token: string | undefined): void;
+    get identity(): string | undefined;
     sendMessage(request: WidgetChatRequest, options?: SendMessageOptions): AsyncGenerator<WidgetChatChunk>;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAErE,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,EAAE,iBAAiB;IAK/B,WAAW,CAChB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,kBAAuB,GAC/B,cAAc,CAAC,eAAe,CAAC;CAmHnC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAErE,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gGAAgG;IAChG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kGAAkG;IAClG,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAS;IAC3B,2GAA2G;IAC3G,OAAO,CAAC,KAAK,CAAC,CAAmB;IACjC,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,gBAAgB,CAAC,CAAS;IAClC,OAAO,CAAC,SAAS,CAAC,CAAS;gBAEf,OAAO,EAAE,iBAAiB;IAStC;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAO7C,IAAI,QAAQ,IAAI,MAAM,GAAG,SAAS,CAEjC;IAEM,WAAW,CAChB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,kBAAuB,GAC/B,cAAc,CAAC,eAAe,CAAC;CA8KnC"}

package/dist/api/protocol.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The protocol v1 parts the widget reads, copied from `@chatcops/core`
+ * (`packages/core/src/protocol/v1.ts`) so the widget's types don't depend on
+ * core. `tests/protocol.test-d.ts` fails if core changes them.
+ */
+export type WirePart = {
+    type: 'start';
+    protocol: 1;
+    conversationId: string;
+    messageId: string;
+} | {
+    type: 'text-delta';
+    id: string;
+    delta: string;
+} | {
+    type: 'lead-captured';
+    lead: Record<string, unknown>;
+} | {
+    type: 'error';
+    code: string;
+    message?: string;
+    retryable: boolean;
+    retryAfterMs?: number;
+    scope?: string;
+} | {
+    type: 'finish';
+    reason: string;
+} | {
+    type: 'source';
+    sourceId: string;
+    url: string;
+    title?: string;
+    snippet?: string;
+}
+/** Parts the widget doesn't use yet. */
+ | {
+    type: 'text-start' | 'text-end' | 'tool-call' | 'tool-result' | 'handoff' | 'agent-message' | 'suggestions';
+};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/api/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/api/protocol.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,CAAC,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACzE;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5G;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE;AACrF,wCAAwC;GACtC;IAAE,IAAI,EAAE,YAAY,GAAG,UAAU,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,GAAG,eAAe,GAAG,aAAa,CAAA;CAAE,CAAC"}

package/dist/api/turnstile.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A Cloudflare Turnstile token, for the server to check before it issues a
+ * session. Cloudflare's script loads only when this first runs, and the
+ * challenge renders in the page itself (not the widget's shadow root), in a
+ * box that stays empty unless the visitor has to click.
+ */
+export declare function turnstileToken(siteKey: string): Promise<string>;
+//# sourceMappingURL=turnstile.d.ts.map

package/dist/api/turnstile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turnstile.d.ts","sourceRoot":"","sources":["../../src/api/turnstile.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBrE"}

package/dist/api/types.d.ts

@@ -2,22 +2,38 @@ export interface WidgetChatRequest {
     conversationId: string;
     message: string;
     messageId?: string;
-    regenerate?: boolean;
+    /** `{ assistantMessageId }` only once the server speaks protocol v1; 0.5 servers take `true`. */
+    regenerate?: boolean | {
+        assistantMessageId: string;
+    };
     pageContext?: {
         url: string;
         title: string;
         description?: string;
         contentSnippet?: string;
+        /** What the site added with setContext(). */
+        data?: Record<string, string>;
     };
     locale?: string;
     userData?: Record<string, string>;
 }
 export interface WidgetChatChunk {
+    /** The server gave this conversation a new id along with its session token. */
+    conversationId?: string;
+    /** The id the server saves the reply under (protocol v1). */
+    messageId?: string;
     content?: string;
     done?: boolean;
     error?: string;
+    /** How long to wait before trying again, with a `rate_limit` error. */
+    retryAfterMs?: number;
     leadCaptured?: boolean;
     leadData?: Record<string, unknown>;
     suggestedActions?: string[];
+    /** A page the reply cited (protocol v1 `source` part). */
+    source?: {
+        url: string;
+        title?: string;
+    };
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/api/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iGAAiG;IACjG,UAAU,CAAC,EAAE,OAAO,GAAG;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,WAAW,CAAC,EAAE;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,6CAA6C;QAC7C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAC/B,CAAC;IACF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,0DAA0D;IAC1D,MAAM,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1C"}