@helpai/elements 0.21.1 → 0.23.0

package/index.d.ts

@@ -1,4 +1,4 @@
-export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, L as Link, S as ServerConfig, b as SiteConfig, c as StartConversationResponse, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial } from './deployment-B8UxV4b5.js';
+export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, L as Link, S as ServerConfig, b as SiteConfig, c as StartConversationResponse, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial } from './deployment-D7_pjSGq.js';
 import 'zod';
 
 /**
@@ -40,7 +40,7 @@ interface ClientStorage {
  * populated {@link Strings} map. UI components then read `strings.send` as a
  * normal property access — no per-render lookup, no per-render allocation.
  */
-type StringKey = "launcherOpen" | "panelTitle" | "composerPlaceholder" | "send" | "stop" | "attach" | "micStart" | "micStop" | "micUnsupported" | "expand" | "collapse" | "fullscreen" | "exitFullscreen" | "resizeHandle" | "scrollToBottom" | "popOut" | "close" | "moreActions" | "soundOn" | "soundOff" | "language" | "theme" | "themeAuto" | "themeLight" | "themeDark" | "textSize" | "textSizeSmall" | "textSizeNormal" | "textSizeLarge" | "history" | "historyTitle" | "historyEmpty" | "historyLoading" | "historyBack" | "conversationLoading" | "conversationClosed" | "startNewConversation" | "dateToday" | "dateYesterday" | "dateLastWeek" | "dateOlder" | "newConversation" | "dropZone" | "attachmentTooLarge" | "attachmentTooMany" | "attachmentMimeRejected" | "errorRetry" | "errorGeneric" | "errorRateLimited" | "loading" | "thinking" | "thoughts" | "usedTool" | "collapseSidebar" | "expandSidebar" | "formSubmit" | "formSkip" | "formSubmitted" | "formSkipped" | "formRequired" | "formInvalidEmail" | "formInvalidTel" | "formInvalidUrl" | "formInvalidNumber" | "formTooShort" | "formTooLong" | "formNumberTooSmall" | "formNumberTooLarge" | "formPatternMismatch" | "formChooseAtLeast" | "formChooseAtMost" | "formOther" | "formOtherPlaceholder" | "inputRequired" | "inputSubmit" | "inputSkip" | "inputSubmitted" | "approvalRequired" | "approve" | "reject" | "approved" | "rejected" | "approvalReason" | "stepNoLongerActive" | "tabHome" | "tabConversations" | "tabHelp" | "tabNews" | "modulesEmpty" | "moduleBack" | "contentLoading" | "homeGreeting" | "homeGreetingNamed" | "homeGreetingLead" | "homeSearchPlaceholder" | "homeContentTitle" | "helpTitle" | "helpSearchPlaceholder" | "helpEmpty" | "helpLoading" | "helpSearchEmpty" | "newsTitle" | "newsEmpty" | "newsLoading" | "newsBack" | "newsPublishedAt";
+type StringKey = "launcherOpen" | "panelTitle" | "composerPlaceholder" | "send" | "stop" | "attach" | "micStart" | "micStop" | "micUnsupported" | "expand" | "collapse" | "fullscreen" | "exitFullscreen" | "resizeHandle" | "scrollToBottom" | "popOut" | "close" | "moreActions" | "soundOn" | "soundOff" | "language" | "theme" | "themeAuto" | "themeLight" | "themeDark" | "textSize" | "textSizeSmall" | "textSizeNormal" | "textSizeLarge" | "history" | "historyTitle" | "historyEmpty" | "historyLoading" | "historyBack" | "conversationLoading" | "conversationClosed" | "startNewConversation" | "dateToday" | "dateYesterday" | "dateLastWeek" | "dateOlder" | "newConversation" | "dropZone" | "attachmentTooLarge" | "attachmentTooMany" | "attachmentMimeRejected" | "errorRetry" | "errorGeneric" | "errorRateLimited" | "loading" | "thinking" | "thoughts" | "usedTool" | "collapseSidebar" | "expandSidebar" | "formSubmit" | "formSkip" | "formSubmitted" | "formSkipped" | "formFillOut" | "formRequired" | "formInvalidEmail" | "formInvalidTel" | "formInvalidUrl" | "formInvalidNumber" | "formTooShort" | "formTooLong" | "formNumberTooSmall" | "formNumberTooLarge" | "formPatternMismatch" | "formChooseAtLeast" | "formChooseAtMost" | "formOther" | "formOtherPlaceholder" | "inputRequired" | "inputSubmit" | "inputSkip" | "inputSubmitted" | "approvalRequired" | "approve" | "reject" | "approved" | "rejected" | "approvalReason" | "stepNoLongerActive" | "tabHome" | "tabConversations" | "tabHelp" | "tabNews" | "modulesEmpty" | "moduleBack" | "contentLoading" | "homeGreeting" | "homeGreetingNamed" | "homeGreetingLead" | "homeSearchPlaceholder" | "homeContentTitle" | "helpTitle" | "helpSearchPlaceholder" | "helpEmpty" | "helpLoading" | "helpSearchEmpty" | "newsTitle" | "newsEmpty" | "newsLoading" | "newsBack" | "newsPublishedAt";
 /** A partial map for one locale — what overrides look like on the wire. */
 type LocaleStrings = Partial<Record<StringKey, string>>;
 /**
@@ -182,9 +182,8 @@ type WirePart = {
 };
 /**
  * One recorded form submission, returned on `/ai/agent/start-conversation`
- * (alongside `messages`) so the widget can re-place the collapsed
- * "form submitted" marker at its chronological spot in the timeline.
- * Values are NOT echoed back — the marker is pure indication.
+ * (alongside `messages`) so the widget can re-place the "form submitted /
+ * skipped" marker at its chronological spot in the timeline.
  */
 interface FormSubmissionRecord {
     formId: string;
@@ -194,6 +193,13 @@ interface FormSubmissionRecord {
     skipped?: boolean;
     /** ISO-8601 — same format + name as {@link WireMessage.createdAt}. */
     createdAt?: string;
+    /**
+     * The visitor's own answers, echoed back so the submitted marker can offer
+     * a read-only review after a reload. Scoped to the same `visitorId` that
+     * submitted them — this is the visitor seeing their own data, independent
+     * of `submit.toContext` (which governs mirroring into request context).
+     */
+    values?: Record<string, string>;
 }
 /** One-shot bot persona shown in the panel header. */
 interface ConversationAgent {
@@ -978,6 +984,54 @@ interface Endpoints {
     submitForm?: string;
 }
 
+/**
+ * Built-in anonymous usage tracking — utm.gif-style pixel hits that give
+ * the widget OWNER (the site embedding it) insights about how visitors
+ * use the widget: events, pages, devices, locales, funnels.
+ *
+ * Privacy contract (enforced in `src/core/tracking.ts`):
+ *   - never sends message text, form values, or any user content —
+ *     event payloads pass through a static per-event allowlist;
+ *   - the only identifier is the widget's existing anonymous `visitorId`;
+ *   - geo + browser are derived server-side (IP + User-Agent header),
+ *     never collected client-side;
+ *   - `navigator.globalPrivacyControl` / Do-Not-Track force it off
+ *     regardless of config.
+ */
+/** Section: anonymous owner-facing usage tracking. */
+interface TrackingOptions {
+    /**
+     * Master switch. Default `false` — tracking stays off until the
+     * deployment (or the embedding page) explicitly turns it on.
+     */
+    enabled?: boolean;
+    /**
+     * Pixel collector URL. Default: `https://t.<brand domain>/api/ai-elements/px.gif`
+     * (e.g. `https://t.help.ai/api/ai-elements/px.gif`).
+     */
+    endpoint?: string;
+    /**
+     * Per-visitor sampling 0..1. `0.25` tracks ~a quarter of visitors
+     * (decided once per page load, so funnels stay intact). Default `1`.
+     */
+    sampleRate?: number;
+    /**
+     * Anti-forgery token, echoed as `tk=` on every hit. **Server-issued,
+     * never set by hand** — the backend mints it in the
+     * `/start-conversation` response (HMAC over `pk`/`vid`/expiry with a
+     * server-side secret; see `docs/api/tracking-collector.md`) and the
+     * collector verifies it statelessly. Opaque to the client.
+     */
+    token?: string;
+}
+/** Post-resolve shape — every field concrete (token stays optional: absent until the handshake delivers it). */
+interface ResolvedTracking {
+    enabled: boolean;
+    endpoint: string;
+    sampleRate: number;
+    token?: string;
+}
+
 /**
  * The three composing roots: raw input ({@link ChatWidgetOptions}),
  * post-normalisation runtime shape ({@link ResolvedOptions}), and the
@@ -1049,6 +1103,8 @@ interface ChatWidgetOptions {
     forms?: FormsOptions;
     /** Messenger modules (Chat / Home / Messages / Help / News tabs). Server-pushable. */
     modules?: ModulesOptions;
+    /** Anonymous owner-facing usage tracking (pixel hits). Server-pushable. */
+    tracking?: TrackingOptions;
     /**
      * Custom client-side storage adapter. Implements the {@link ClientStorage}
      * interface (`get` / `set` / `remove` / `clear`).
@@ -1148,6 +1204,8 @@ interface ResolvedOptions {
     };
     /** Resolved messenger modules — per-module config + ordered enabled list + default tab. */
     modules: ResolvedModules;
+    /** Resolved anonymous usage tracking. */
+    tracking: ResolvedTracking;
     /** Resolved storage adapter — defaults to `LocalStorageAdapter`. */
     storage: ClientStorage;
     onMessage?: ChatWidgetOptions["onMessage"];
@@ -1175,6 +1233,7 @@ interface ServerConfig {
     features?: FeatureFlags;
     forms?: FormsOptions;
     modules?: ModulesOptions;
+    tracking?: TrackingOptions;
     endpoints?: Endpoints;
 }