@helpai/elements 0.21.1 → 0.22.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-C-Sv0e6E.js';
 import 'zod';
 
 /**
@@ -978,6 +978,45 @@ 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;
+}
+/** Post-resolve shape — every field concrete. */
+interface ResolvedTracking {
+    enabled: boolean;
+    endpoint: string;
+    sampleRate: number;
+}
+
 /**
  * The three composing roots: raw input ({@link ChatWidgetOptions}),
  * post-normalisation runtime shape ({@link ResolvedOptions}), and the
@@ -1049,6 +1088,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 +1189,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 +1218,7 @@ interface ServerConfig {
     features?: FeatureFlags;
     forms?: FormsOptions;
     modules?: ModulesOptions;
+    tracking?: TrackingOptions;
     endpoints?: Endpoints;
 }
 

package/index.mjs

@@ -468,6 +468,11 @@ var DEFAULT_FEATURES = {
   humanInLoop: true
 };
 var DEFAULT_FORMS = { list: [], byTrigger: {} };
+var DEFAULT_TRACKING = {
+  enabled: false,
+  endpoint: `https://t.${BRAND.domain}/api/ai-elements/px.gif`,
+  sampleRate: 1
+};
 var DEFAULT_ENDPOINTS = {
   upload: "/ai/agent/upload-file",
   transcribe: "/ai/agent/transcribe-audio",
@@ -562,6 +567,7 @@ function resolveOptions(rawOpts) {
     poweredBy: resolvePoweredBy(footer.poweredBy),
     composer: resolveComposer(opts.composer),
     modules: resolveModules(opts.modules),
+    tracking: resolveTracking(opts.tracking),
     storage: opts.storage ?? defaultStorage,
     onMessage: opts.onMessage,
     onOpen: opts.onOpen,
@@ -594,6 +600,16 @@ function resolveHaptics(overrides) {
     events: overrides?.events
   };
 }
+function resolveTracking(overrides) {
+  const sampleRate = overrides?.sampleRate ?? DEFAULT_TRACKING.sampleRate;
+  return {
+    enabled: overrides?.enabled ?? DEFAULT_TRACKING.enabled,
+    endpoint: overrides?.endpoint ?? DEFAULT_TRACKING.endpoint,
+    // Clamp instead of reject — a malformed rate must never turn a
+    // disabled tracker on or crash resolve (no Zod on the IIFE path).
+    sampleRate: Math.min(1, Math.max(0, Number.isFinite(sampleRate) ? sampleRate : 1))
+  };
+}
 function resolvePoweredBy(overrides) {
   const brandDefault = {
     text: `Powered by ${BRAND.displayName}`,
@@ -736,6 +752,7 @@ var SECTION_KEYS = [
   "i18n",
   "footer",
   "features",
+  "tracking",
   "endpoints"
 ];
 function mergeServerConfig(user, server) {
@@ -5580,10 +5597,10 @@ function createHomeNav(initialTab, tabs, onSwitch) {
       sig.value = { ...sig.value, activeTab: tab };
       onSwitch?.(tab);
     },
-    push(screen) {
+    push(screen2) {
       const s = sig.value;
       const stack = s.stacks[s.activeTab] ?? [];
-      sig.value = { ...s, stacks: { ...s.stacks, [s.activeTab]: [...stack, screen] } };
+      sig.value = { ...s, stacks: { ...s.stacks, [s.activeTab]: [...stack, screen2] } };
     },
     pop() {
       const s = sig.value;
@@ -7242,6 +7259,118 @@ var EventBus = class {
   }
 };
 
+// src/core/tracking.ts
+var PROTOCOL_VERSION = "1";
+var MAX_HITS_PER_MINUTE = 60;
+var MAX_URL_LENGTH = 2e3;
+var TRACKED = {
+  // Panel lifecycle — the owner's "is the widget used at all" funnel.
+  open: () => void 0,
+  close: () => void 0,
+  expand: (on) => ({ on }),
+  fullscreen: (on) => ({ on }),
+  popOut: () => void 0,
+  // Conversation funnel. `send` is the key conversion; text never rides.
+  send: (p33) => ({ attachments: p33.attachmentCount }),
+  message: (p33) => ({ role: p33.role }),
+  stop: () => void 0,
+  clear: () => void 0,
+  suggestion: () => void 0,
+  toggleHistory: (p33) => ({ view: p33.view }),
+  conversationStarted: () => void 0,
+  // Forms + human-in-the-loop — ids and outcomes, never values.
+  formSubmit: (p33) => ({ formId: p33.formId, skipped: p33.skipped }),
+  toolResult: () => void 0,
+  toolDecision: (p33) => ({ approved: p33.approved }),
+  // Composer / attachments / voice.
+  attach: (p33) => ({ count: p33.count, bytes: p33.totalBytes }),
+  voiceStart: () => void 0,
+  voiceStop: (p33) => ({ ms: p33.durationMs }),
+  voiceCancel: () => void 0,
+  // Preferences — how visitors tune the surface.
+  localeChange: (locale) => ({ locale }),
+  themeChange: (theme) => ({ theme }),
+  textSizeChange: (size) => ({ size }),
+  soundToggle: (p33) => ({ muted: p33.muted }),
+  sidebarToggle: (p33) => ({ collapsed: p33.collapsed }),
+  calloutDismiss: () => void 0,
+  // Health signal only — the error object itself never leaves the page.
+  error: () => void 0
+};
+function privacySignalsOff() {
+  const nav = navigator;
+  return nav.globalPrivacyControl === true || nav.doNotTrack === "1";
+}
+function pageUrl() {
+  return location.origin + location.pathname;
+}
+function referrerOrigin() {
+  try {
+    return document.referrer ? new URL(document.referrer).origin : "";
+  } catch {
+    return "";
+  }
+}
+function createTracker(bus, deps) {
+  const sampleRoll = Math.random();
+  let windowStart = 0;
+  let windowHits = 0;
+  const inflight = /* @__PURE__ */ new Set();
+  const hit = (event, dims) => {
+    const { tracking, publicKey, aiAgentDeploymentId, mode, themeMode } = deps.getOptions();
+    if (!tracking.enabled || privacySignalsOff()) return;
+    if (sampleRoll >= tracking.sampleRate) return;
+    const now = performance.now();
+    if (now - windowStart > 6e4) {
+      windowStart = now;
+      windowHits = 0;
+    }
+    if (++windowHits > MAX_HITS_PER_MINUTE) return;
+    const params = new URLSearchParams();
+    params.set("v", PROTOCOL_VERSION);
+    params.set("e", event);
+    if (publicKey) params.set("pk", publicKey);
+    if (aiAgentDeploymentId) params.set("dep", aiAgentDeploymentId);
+    params.set("vid", deps.getVisitorId());
+    const cid = deps.getConversationId();
+    if (cid) params.set("cid", cid);
+    params.set("url", pageUrl());
+    const ref = referrerOrigin();
+    if (ref) params.set("ref", ref);
+    params.set("sw", String(screen.width));
+    params.set("sh", String(screen.height));
+    params.set("vw", String(innerWidth));
+    params.set("vh", String(innerHeight));
+    params.set("dpr", String(devicePixelRatio));
+    params.set("lang", navigator.language);
+    try {
+      params.set("tz", Intl.DateTimeFormat().resolvedOptions().timeZone);
+    } catch {
+    }
+    params.set("m", mode);
+    params.set("th", themeMode);
+    if (dims) {
+      for (const [k, val] of Object.entries(dims)) {
+        if (val !== void 0) params.set(k, String(val));
+      }
+    }
+    params.set("ts", String(Date.now()));
+    const url = `${tracking.endpoint}?${params}`;
+    if (url.length > MAX_URL_LENGTH) return;
+    const img = new Image(1, 1);
+    inflight.add(img);
+    img.onload = img.onerror = () => inflight.delete(img);
+    img.src = url;
+  };
+  const offs = Object.keys(TRACKED).map(
+    (event) => bus.on(event, (payload) => hit(event, TRACKED[event]?.(payload)))
+  );
+  return () => {
+    for (const off of offs) off();
+    inflight.clear();
+  };
+}
+
 // src/core/hooks.ts
 var log19 = logger.scope("hooks");
 var HOOK_WILDCARD = "*";
@@ -7381,6 +7510,11 @@ function mount(opts) {
     applyResolvedHostAttributes();
     renderApp();
   });
+  const unsubscribeTracker = createTracker(bus, {
+    getOptions: () => currentOptions,
+    getVisitorId: () => persistence.getVisitorId(),
+    getConversationId: () => persistence.loadConversationId()
+  });
   const host = mountResult.hostElement;
   let unsubscribeHooks = null;
   const applyUpdate = (patch) => {
@@ -7430,6 +7564,7 @@ function mount(opts) {
     destroy: () => {
       log20.info("destroy", { widgetId });
       unsubscribeHooks?.();
+      unsubscribeTracker();
       bus.clear();
       render(null, mountResult.appRoot);
       mountResult.destroy();

package/package.json

@@ -80,5 +80,5 @@
   ],
   "type": "module",
   "types": "./index.d.ts",
-  "version": "0.21.1"
+  "version": "0.22.0"
 }

package/schema.d.ts

@@ -1,4 +1,4 @@
-export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, E as Endpoints, L as Link, P as PAGE_AREA_SUGGESTIONS, g as PageContext, S as ServerConfig, b as SiteConfig, c as StartConversationResponse, U as UserContext, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial, h as assetSchema, i as blocksConfigSchema, j as connectionConfigPartialSchema, k as connectionConfigSchema, l as cssColorSchema, m as cssLengthSchema, n as endpointsSchema, o as linkSchema, p as localeSchema, q as pageContextSchema, s as serverConfigSchema, r as siteConfigSchema, t as startConversationResponseSchema, u as userContextSchema, v as uuid7Schema, w as widgetConfigPartialSchema, x as widgetConfigSchema, y as widgetSettingsPartialSchema, z as widgetSettingsSchema } from './deployment-B8UxV4b5.js';
+export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, E as Endpoints, L as Link, P as PAGE_AREA_SUGGESTIONS, g as PageContext, S as ServerConfig, b as SiteConfig, c as StartConversationResponse, U as UserContext, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial, h as assetSchema, i as blocksConfigSchema, j as connectionConfigPartialSchema, k as connectionConfigSchema, l as cssColorSchema, m as cssLengthSchema, n as endpointsSchema, o as linkSchema, p as localeSchema, q as pageContextSchema, s as serverConfigSchema, r as siteConfigSchema, t as startConversationResponseSchema, u as userContextSchema, v as uuid7Schema, w as widgetConfigPartialSchema, x as widgetConfigSchema, y as widgetSettingsPartialSchema, z as widgetSettingsSchema } from './deployment-C-Sv0e6E.js';
 import { z } from 'zod';
 
 /**
@@ -840,6 +840,22 @@ declare const modulesSchema: z.ZodArray<z.ZodObject<{
 }, z.core.$loose>>;
 type ModulesOptions = z.infer<typeof modulesSchema>;
 
+/**
+ * Tracking section schema — built-in anonymous usage analytics for the
+ * widget owner (utm.gif-style pixel hits). Off by default; a deployment
+ * turns it on to get event / page / device / locale insights without
+ * wiring its own analytics. No message content or form values ever ride
+ * a hit — payload fields pass a static per-event allowlist in the
+ * runtime tracker.
+ */
+
+declare const trackingSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    endpoint: z.ZodOptional<z.ZodURL>;
+    sampleRate: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+type TrackingSettings = z.infer<typeof trackingSchema>;
+
 /**
  * Per-mode widget-settings projection.
  *
@@ -881,4 +897,4 @@ declare const ALL_MODES: readonly Mode[];
  */
 declare function emitJsonSchema(): unknown;
 
-export { ALL_MODES, type ActionName, type AttachmentLimits, type Behavior, type CalloutPosition, type CalloutShape, type ComposerOptions, type FeatureFlags, type FeedbackEvent, type FeedbackOptions, type FieldOption, type FieldType, type FieldValidation, type FooterOptions, type FormCondition, type FormDef, type FormField, type Forms, type HapticsOptions, type HeaderActions, type HeaderOptions, type I18nOptions, type LauncherCallout, type LauncherOptions, type LauncherSize, type LauncherVariant, type Mode, type ModuleLayout, type ModuleOptions, type ModulesOptions, type Position, type PoweredBy, type Presentation, type ResizeOptions, type ResponseMode, type SendButtonOptions, type SizeOptions, type SoundOptions, type StringsOverride, type ThemeOverrides, type ThemePreference, type VoiceMode, actionNameSchema, attachmentLimitsSchema, behaviorSchema, calloutPositionSchema, calloutShapeSchema, composerOptionsSchema, emitJsonSchema, featureFlagsSchema, feedbackEventSchema, feedbackSchema, fieldOptionSchema, fieldTypeSchema, fieldValidationSchema, footerSchema, formConditionSchema, formDefSchema, formFieldSchema, formTriggerSchema, formsSchema, hapticsOptionsSchema, headerActionsSchema, headerSchema, i18nSchema, initialSizeSchema, launcherCalloutSchema, launcherOptionsSchema, launcherSizeSchema, launcherVariantSchema, modeSchema, moduleLayoutSchema, moduleSchema, modulesSchema, positionSchema, poweredBySchema, presentationSchema, resizeOptionsSchema, responseModeSchema, sendButtonIconSchema, sendButtonOptionsSchema, sendButtonShapeSchema, sendButtonVariantSchema, sizeOptionsSchema, soundOptionsSchema, stringsOverrideSchema, themeFieldSchema, themeOverridesSchema, themePreferenceSchema, toolRefSchema, voiceModeSchema, widgetSettingsSchemaForMode };
+export { ALL_MODES, type ActionName, type AttachmentLimits, type Behavior, type CalloutPosition, type CalloutShape, type ComposerOptions, type FeatureFlags, type FeedbackEvent, type FeedbackOptions, type FieldOption, type FieldType, type FieldValidation, type FooterOptions, type FormCondition, type FormDef, type FormField, type Forms, type HapticsOptions, type HeaderActions, type HeaderOptions, type I18nOptions, type LauncherCallout, type LauncherOptions, type LauncherSize, type LauncherVariant, type Mode, type ModuleLayout, type ModuleOptions, type ModulesOptions, type Position, type PoweredBy, type Presentation, type ResizeOptions, type ResponseMode, type SendButtonOptions, type SizeOptions, type SoundOptions, type StringsOverride, type ThemeOverrides, type ThemePreference, type TrackingSettings, type VoiceMode, actionNameSchema, attachmentLimitsSchema, behaviorSchema, calloutPositionSchema, calloutShapeSchema, composerOptionsSchema, emitJsonSchema, featureFlagsSchema, feedbackEventSchema, feedbackSchema, fieldOptionSchema, fieldTypeSchema, fieldValidationSchema, footerSchema, formConditionSchema, formDefSchema, formFieldSchema, formTriggerSchema, formsSchema, hapticsOptionsSchema, headerActionsSchema, headerSchema, i18nSchema, initialSizeSchema, launcherCalloutSchema, launcherOptionsSchema, launcherSizeSchema, launcherVariantSchema, modeSchema, moduleLayoutSchema, moduleSchema, modulesSchema, positionSchema, poweredBySchema, presentationSchema, resizeOptionsSchema, responseModeSchema, sendButtonIconSchema, sendButtonOptionsSchema, sendButtonShapeSchema, sendButtonVariantSchema, sizeOptionsSchema, soundOptionsSchema, stringsOverrideSchema, themeFieldSchema, themeOverridesSchema, themePreferenceSchema, toolRefSchema, trackingSchema, voiceModeSchema, widgetSettingsSchemaForMode };

package/schema.json

@@ -1839,6 +1839,38 @@
             ]
           ]
         },
+        "tracking": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "description": "Master switch. Default `false` — no hits are sent until the deployment turns tracking on.",
+              "type": "boolean"
+            },
+            "endpoint": {
+              "description": "Pixel collector URL. Default: `https://t.<brand domain>/api/ai-elements/px.gif`. Must be a full URL.",
+              "type": "string",
+              "maxLength": 2048,
+              "format": "uri"
+            },
+            "sampleRate": {
+              "description": "Per-visitor sampling 0..1 (decided once per page load, keeping funnels intact). Default `1`.",
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            }
+          },
+          "additionalProperties": {},
+          "description": "Anonymous usage tracking for the widget owner — GA-style pixel events (open, send, form submit, …) with page / device / locale dimensions. Never includes message content; visitors are identified only by the widget's anonymous visitorId.",
+          "examples": [
+            {
+              "enabled": true
+            },
+            {
+              "enabled": true,
+              "sampleRate": 0.5
+            }
+          ]
+        },
         "site": {
           "description": "Site config — applies in `mode: \"page\"`. Comes from the start-conversation response, not user-edited."
         },
@@ -3556,6 +3588,38 @@
                   }
                 ]
               ]
+            },
+            "tracking": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "description": "Master switch. Default `false` — no hits are sent until the deployment turns tracking on.",
+                  "type": "boolean"
+                },
+                "endpoint": {
+                  "description": "Pixel collector URL. Default: `https://t.<brand domain>/api/ai-elements/px.gif`. Must be a full URL.",
+                  "type": "string",
+                  "maxLength": 2048,
+                  "format": "uri"
+                },
+                "sampleRate": {
+                  "description": "Per-visitor sampling 0..1 (decided once per page load, keeping funnels intact). Default `1`.",
+                  "type": "number",
+                  "minimum": 0,
+                  "maximum": 1
+                }
+              },
+              "additionalProperties": {},
+              "description": "Anonymous usage tracking for the widget owner — GA-style pixel events (open, send, form submit, …) with page / device / locale dimensions. Never includes message content; visitors are identified only by the widget's anonymous visitorId.",
+              "examples": [
+                {
+                  "enabled": true
+                },
+                {
+                  "enabled": true,
+                  "sampleRate": 0.5
+                }
+              ]
             }
           },
           "additionalProperties": {}