@helpai/elements 0.21.1 → 0.22.0

package/schema.mjs

@@ -17,7 +17,7 @@ var localeSchema = z.string().min(1).max(35).describe("BCP-47 locale tag (e.g. `
 var uuid7Schema = z.uuidv7().describe("UUID v7 (RFC 9562) \u2014 the single id format for visitor / conversation / message / file / content ids.");
 
 // src/schema/widget.ts
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 
 // src/schema/widget/presentation.ts
 import { z as z3 } from "zod";
@@ -560,11 +560,23 @@ var modulesSchema = z14.array(moduleSchema).max(4).describe(
   ]
 });
 
+// src/schema/widget/tracking.ts
+import { z as z15 } from "zod";
+var trackingSchema = z15.object({
+  enabled: z15.boolean().optional().describe("Master switch. Default `false` \u2014 no hits are sent until the deployment turns tracking on."),
+  endpoint: z15.url().max(2048).optional().describe("Pixel collector URL. Default: `https://t.<brand domain>/api/ai-elements/px.gif`. Must be a full URL."),
+  sampleRate: z15.number().min(0).max(1).optional().describe("Per-visitor sampling 0..1 (decided once per page load, keeping funnels intact). Default `1`.")
+}).loose().describe(
+  "Anonymous usage tracking for the widget owner \u2014 GA-style pixel events (open, send, form submit, \u2026) with page / device / locale dimensions. Never includes message content; visitors are identified only by the widget's anonymous visitorId."
+).meta({
+  examples: [{ enabled: true }, { enabled: true, sampleRate: 0.5 }]
+});
+
 // src/schema/widget.ts
-var endpointsSchema = z15.object({
-  upload: z15.string().min(1).max(2048).default("/ai/agent/upload-file"),
-  transcribe: z15.string().min(1).max(2048).default("/ai/agent/transcribe-audio"),
-  submitForm: z15.string().min(1).max(2048).default("/ai/agent/submit-form").describe(
+var endpointsSchema = z16.object({
+  upload: z16.string().min(1).max(2048).default("/ai/agent/upload-file"),
+  transcribe: z16.string().min(1).max(2048).default("/ai/agent/transcribe-audio"),
+  submitForm: z16.string().min(1).max(2048).default("/ai/agent/submit-form").describe(
     "Form submission endpoint. The widget POSTs each completed form's values here (fire-and-forget), keyed by the same visitorId + conversationId as the conversation; the payload carries `formId` + `trigger` so the backend can route. Optional \u2014 a 404 is ignored."
   )
 }).loose().describe("HTTP endpoint overrides. Paths are appended to baseUrl; absolute URLs are accepted too.").meta({
@@ -574,14 +586,14 @@ var endpointsSchema = z15.object({
     { submitForm: "https://crm.acme.com/leads" }
   ]
 });
-var userContextSchema = z15.object({
-  id: z15.string().min(1).max(200).optional().describe("Host's stable id for the user \u2014 informational context the agent/backend can key on (not auth)."),
-  email: z15.string().min(1).max(320).optional().describe("User email \u2014 surfaced to the agent for context (optional)."),
-  name: z15.string().min(1).max(200).optional().describe("Display name \u2014 shown in the Home greeting (`{name}`) and conversation transcripts (optional)."),
-  plan: z15.string().min(1).max(120).optional().describe("Subscription / pricing tier, e.g. `pro` (optional)."),
-  role: z15.string().min(1).max(120).optional().describe("The user's role on the host site, e.g. `admin` (optional)."),
-  phone: z15.string().min(1).max(40).optional().describe("Phone number (optional).")
-}).catchall(z15.union([z15.string(), z15.number(), z15.boolean()])).describe(
+var userContextSchema = z16.object({
+  id: z16.string().min(1).max(200).optional().describe("Host's stable id for the user \u2014 informational context the agent/backend can key on (not auth)."),
+  email: z16.string().min(1).max(320).optional().describe("User email \u2014 surfaced to the agent for context (optional)."),
+  name: z16.string().min(1).max(200).optional().describe("Display name \u2014 shown in the Home greeting (`{name}`) and conversation transcripts (optional)."),
+  plan: z16.string().min(1).max(120).optional().describe("Subscription / pricing tier, e.g. `pro` (optional)."),
+  role: z16.string().min(1).max(120).optional().describe("The user's role on the host site, e.g. `admin` (optional)."),
+  phone: z16.string().min(1).max(40).optional().describe("Phone number (optional).")
+}).catchall(z16.union([z16.string(), z16.number(), z16.boolean()])).describe(
   "Host-asserted end-user context (informational, untrusted \u2014 not authentication). Recognised `id` / `email` / `name` / `plan` / `role` / `phone` plus any extra custom scalar fields forwarded to the agent."
 ).meta({
   examples: [{ id: "u_123" }, { id: "u_123", email: "alex@acme.com", name: "Alex Lee", plan: "pro" }]
@@ -597,31 +609,31 @@ var PAGE_AREA_SUGGESTIONS = [
   "account",
   "blog"
 ];
-var pageContextSchema = z15.object({
-  area: z15.string().min(1).max(64).optional().describe(`Host-defined surface the visitor is on. Free-form; suggested: ${PAGE_AREA_SUGGESTIONS.join(" | ")}.`),
-  url: z15.string().min(1).max(2048).optional().describe("Full page URL. Auto-filled from the host page when omitted."),
-  path: z15.string().min(1).max(2048).optional().describe("Page path, e.g. `/pricing/enterprise`."),
-  title: z15.string().min(1).max(300).optional().describe("Human-readable page title.")
-}).catchall(z15.union([z15.string(), z15.number(), z15.boolean()])).describe(
+var pageContextSchema = z16.object({
+  area: z16.string().min(1).max(64).optional().describe(`Host-defined surface the visitor is on. Free-form; suggested: ${PAGE_AREA_SUGGESTIONS.join(" | ")}.`),
+  url: z16.string().min(1).max(2048).optional().describe("Full page URL. Auto-filled from the host page when omitted."),
+  path: z16.string().min(1).max(2048).optional().describe("Page path, e.g. `/pricing/enterprise`."),
+  title: z16.string().min(1).max(300).optional().describe("Human-readable page title.")
+}).catchall(z16.union([z16.string(), z16.number(), z16.boolean()])).describe(
   "Host-asserted page/visit context (informational, untrusted). Where the visitor is + the surface (`area`) they're using, plus any custom scalar fields, forwarded to the agent."
 ).meta({ examples: [{ area: "pricing", path: "/pricing" }, { area: "help-desk" }] });
-var connectionConfigSchema = z15.object({
-  widgetId: z15.string().min(1).max(80).default("default").describe(
+var connectionConfigSchema = z16.object({
+  widgetId: z16.string().min(1).max(80).default("default").describe(
     "Stable per-instance id used to namespace localStorage keys. Set this when mounting more than one widget on the same page so their conversation state doesn't collide."
   ),
-  publicKey: z15.string().min(1).max(200).optional().describe(
+  publicKey: z16.string().min(1).max(200).optional().describe(
     "Workspace-scoped public key (`agent_pk_\u2026`) issued from the dashboard. Sent on every API call as the `x-public-key` header."
   ),
-  aiAgentDeploymentId: z15.string().min(1).max(200).optional().describe(
+  aiAgentDeploymentId: z16.string().min(1).max(200).optional().describe(
     "Deployment UUID from the dashboard. Picks which agent / settings bundle answers this mount. Sent as `x-ai-agent-deployment-id`."
   ),
-  baseUrl: z15.string().min(1).max(2048).optional().describe(
+  baseUrl: z16.string().min(1).max(2048).optional().describe(
     "Full backend origin (e.g. `https://help.ai/api`). Set this to point at your staging / self-hosted / custom backend. Default: the brand's `defaultBaseUrl` baked at build time."
   ),
   userContext: userContextSchema.optional(),
   pageContext: pageContextSchema.optional(),
   endpoints: endpointsSchema.optional(),
-  debug: z15.union([z15.boolean(), z15.enum(["off", "error", "warn", "info", "debug", "trace"])]).optional().describe(
+  debug: z16.union([z16.boolean(), z16.enum(["off", "error", "warn", "info", "debug", "trace"])]).optional().describe(
     'Console log verbosity. `false` / `"off"` silences everything (default in production). `true` \u2192 `"debug"`. Levels `error` / `warn` / `info` / `debug` / `trace` gate output additively. Use `"trace"` to capture per-chunk SSE frames + every state transition. Also toggleable at runtime via `chat.setDebug(level)` or `?<brand>-debug=trace` in the page URL \u2014 the URL beats this option, this option beats the persisted `localStorage` value.'
   )
 }).loose().describe(
@@ -641,7 +653,7 @@ var connectionConfigSchema = z15.object({
     }
   ]
 });
-var widgetSettingsSchema = z15.object({
+var widgetSettingsSchema = z16.object({
   presentation: presentationSchema.optional(),
   behavior: behaviorSchema.optional(),
   theme: themeFieldSchema.default("auto").describe("Theme preference (`auto` follows OS) or a tokens override object (`accent`, `radius`, `fontFamily`)."),
@@ -653,9 +665,10 @@ var widgetSettingsSchema = z15.object({
   footer: footerSchema.optional(),
   features: featureFlagsSchema.optional(),
   forms: formsSchema.optional(),
-  modules: modulesSchema.optional()
+  modules: modulesSchema.optional(),
+  tracking: trackingSchema.optional()
 }).loose().describe(
-  "Portal-configurable widget settings \u2014 thirteen sections, one per dashboard tab. The backend pushes this same shape on `/ai/agent/start-conversation` under `config`."
+  "Portal-configurable widget settings \u2014 fourteen sections, one per dashboard tab. The backend pushes this same shape on `/ai/agent/start-conversation` under `config`."
 ).meta({
   examples: [
     { presentation: { mode: "floating", position: "bottom-right" }, theme: "auto" },
@@ -673,10 +686,10 @@ var widgetSettingsSchema = z15.object({
 });
 var widgetConfigSchema = connectionConfigSchema.extend({
   ...widgetSettingsSchema.shape,
-  site: z15.unknown().optional().describe(
+  site: z16.unknown().optional().describe(
     'Site config \u2014 applies in `mode: "page"`. Comes from the start-conversation response, not user-edited.'
   ),
-  blocks: z15.unknown().optional().describe('Blocks (nav + link cards) \u2014 applies in `mode: "page"`. Comes from the start-conversation response.')
+  blocks: z16.unknown().optional().describe('Blocks (nav + link cards) \u2014 applies in `mode: "page"`. Comes from the start-conversation response.')
 }).describe(
   "Full client widget config \u2014 connection (where + auth) + widget settings (look + behaviour) + page-mode extras. This is what the runtime parses on `mount()` / `init()`. Mode-specific constraints (e.g. `position` only meaningful in `floating`) are NOT enforced here \u2014 the runtime silently ignores irrelevant fields rather than rejecting them so the same object can flow across mode changes."
 ).meta({
@@ -699,49 +712,49 @@ var widgetSettingsPartialSchema = widgetSettingsSchema.partial();
 var connectionConfigPartialSchema = connectionConfigSchema.partial();
 
 // src/schema/deployment.ts
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 var serverConfigSchema = widgetSettingsSchema.partial();
-var siteConfigSchema = z16.object({
-  title: z16.string().min(1).max(120).optional().describe("Brand / site name. Used as the logo's alt-text fallback."),
+var siteConfigSchema = z17.object({
+  title: z17.string().min(1).max(120).optional().describe("Brand / site name. Used as the logo's alt-text fallback."),
   logo: assetSchema.optional().describe("Brand logo shown at the top of the page-mode sidebar."),
   logoDark: assetSchema.optional().describe(
     "Optional dark-theme logo variant. Falls back to `logo` when the active theme is light or `logoDark` is unset."
   )
 }).loose();
-var blocksConfigSchema = z16.object({
-  navigation: z16.array(linkSchema).max(100).optional().describe("Sidebar navigation links (vertical list, primary nav)."),
-  linkCards: z16.array(linkSchema).max(100).optional().describe("Sidebar link cards (richer entries with optional `description`).")
+var blocksConfigSchema = z17.object({
+  navigation: z17.array(linkSchema).max(100).optional().describe("Sidebar navigation links (vertical list, primary nav)."),
+  linkCards: z17.array(linkSchema).max(100).optional().describe("Sidebar link cards (richer entries with optional `description`).")
 }).loose();
-var handshakeWelcomeMessageSchema = z16.object({
-  id: z16.string(),
-  role: z16.enum(["assistant", "system"]),
-  text: z16.string()
+var handshakeWelcomeMessageSchema = z17.object({
+  id: z17.string(),
+  role: z17.enum(["assistant", "system"]),
+  text: z17.string()
 }).loose();
-var handshakeWelcomeSuggestionSchema = z16.object({
-  id: z16.string(),
-  label: z16.string(),
-  text: z16.string().optional()
+var handshakeWelcomeSuggestionSchema = z17.object({
+  id: z17.string(),
+  label: z17.string(),
+  text: z17.string().optional()
 }).loose();
-var rebindReasonSchema = z16.enum(["conflict", "expired", "invalid"]);
-var startConversationResponseSchema = z16.object({
-  deployment: z16.object({
-    id: z16.string(),
-    name: z16.string(),
+var rebindReasonSchema = z17.enum(["conflict", "expired", "invalid"]);
+var startConversationResponseSchema = z17.object({
+  deployment: z17.object({
+    id: z17.string(),
+    name: z17.string(),
     // Page URL identifier — present on every deployment; unique per host.
     // Used to mount page deployments via `?slug=…`.
-    slug: z16.string().optional(),
-    publicKey: z16.string().optional()
+    slug: z17.string().optional(),
+    publicKey: z17.string().optional()
     // Deliberately no `type` / `channel` here. Deployment-level
     // taxonomy is a backend categorization concern — the widget's
     // rendering choice flows from `widget.presentation.mode`, not
     // the deployment record's category. `.loose()` lets any such
     // backend field pass through without typing.
   }).loose(),
-  agent: z16.object({
-    id: z16.string(),
-    name: z16.string(),
-    title: z16.string().optional(),
-    status: z16.enum(["online", "away", "offline"]).optional()
+  agent: z17.object({
+    id: z17.string(),
+    name: z17.string(),
+    title: z17.string().optional(),
+    status: z17.enum(["online", "away", "offline"]).optional()
   }).loose(),
   /**
    * Deployment-wide widget configuration the dashboard admin saved
@@ -751,26 +764,26 @@ var startConversationResponseSchema = z16.object({
   config: serverConfigSchema.optional(),
   site: siteConfigSchema.optional(),
   blocks: blocksConfigSchema.optional(),
-  welcome: z16.object({
-    messages: z16.array(handshakeWelcomeMessageSchema).optional(),
-    suggestions: z16.array(handshakeWelcomeSuggestionSchema).optional()
+  welcome: z17.object({
+    messages: z17.array(handshakeWelcomeMessageSchema).optional(),
+    suggestions: z17.array(handshakeWelcomeSuggestionSchema).optional()
   }).loose().optional(),
-  visitorId: z16.string(),
-  conversationId: z16.string(),
-  canContinue: z16.boolean(),
-  messages: z16.array(z16.unknown()),
+  visitorId: z17.string(),
+  conversationId: z17.string(),
+  canContinue: z17.boolean(),
+  messages: z17.array(z17.unknown()),
   /**
    * Form submissions recorded for this conversation — echoed like
    * `messages` so the widget reconstructs the collapsed "form submitted"
    * timeline markers on resume. `createdAt` is ISO-8601 (a serialized
    * Mongo ISODate — same format as message `createdAt`).
    */
-  formSubmissions: z16.array(
-    z16.object({
-      formId: z16.string(),
-      trigger: z16.string(),
-      skipped: z16.boolean().optional(),
-      createdAt: z16.iso.datetime().optional()
+  formSubmissions: z17.array(
+    z17.object({
+      formId: z17.string(),
+      trigger: z17.string(),
+      skipped: z17.boolean().optional(),
+      createdAt: z17.iso.datetime().optional()
     }).loose()
   ).optional(),
   /**
@@ -779,11 +792,11 @@ var startConversationResponseSchema = z16.object({
    * what THIS visitor toggled inside the widget, not the
    * deployment's admin-set defaults.
    */
-  userPrefs: z16.record(z16.string(), z16.unknown()).optional(),
+  userPrefs: z17.record(z17.string(), z17.unknown()).optional(),
   // Present only when the server rotated the request `visitorId` /
   // `conversationId`. Purely advisory — client must adopt the response ids
   // verbatim regardless of whether this block is present.
-  rebind: z16.object({
+  rebind: z17.object({
     visitorId: rebindReasonSchema.optional(),
     conversationId: rebindReasonSchema.optional()
   }).loose().optional()
@@ -798,7 +811,8 @@ var COMMON_SECTIONS = [
   "footer",
   "i18n",
   "features",
-  "feedback"
+  "feedback",
+  "tracking"
 ];
 var MODE_EXTRAS = {
   floating: ["presentation", "behavior", "modules", "launcher"],
@@ -819,15 +833,15 @@ function widgetSettingsSchemaForMode(mode) {
 var ALL_MODES = ["floating", "inline", "standalone", "page", "modal", "drawer"];
 
 // src/schema/json-schema.ts
-import { z as z18 } from "zod";
+import { z as z19 } from "zod";
 function emitJsonSchema() {
   return {
     $schema: "https://json-schema.org/draft/2020-12/schema",
     title: "@helpai/elements config",
     description: "Canonical config schemas for the embeddable AI agent elements widget.",
     definitions: {
-      WidgetConfig: z18.toJSONSchema(widgetConfigSchema),
-      StartConversationResponse: z18.toJSONSchema(startConversationResponseSchema)
+      WidgetConfig: z19.toJSONSchema(widgetConfigSchema),
+      StartConversationResponse: z19.toJSONSchema(startConversationResponseSchema)
     }
   };
 }
@@ -895,6 +909,7 @@ export {
   themeOverridesSchema,
   themePreferenceSchema,
   toolRefSchema,
+  trackingSchema,
   userContextSchema,
   uuid7Schema,
   voiceModeSchema,

package/web-component.mjs

@@ -453,6 +453,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",
@@ -547,6 +552,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,
@@ -579,6 +585,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}`,
@@ -721,6 +737,7 @@ var SECTION_KEYS = [
   "i18n",
   "footer",
   "features",
+  "tracking",
   "endpoints"
 ];
 function mergeServerConfig(user, server) {
@@ -5635,10 +5652,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;