@helpai/elements 0.21.1 → 0.23.0

package/configurator.mjs

@@ -20,7 +20,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";
@@ -563,11 +563,26 @@ 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`."),
+  token: z15.string().max(512).optional().describe(
+    "Anti-forgery token, echoed as `tk=` on every hit. Server-issued in the `/start-conversation` response \u2014 never set by hand (see `docs/api/tracking-collector.md`)."
+  )
+}).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({
@@ -577,14 +592,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" }]
@@ -600,31 +615,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(
@@ -644,7 +659,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`)."),
@@ -656,9 +671,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" },
@@ -676,10 +692,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({
@@ -702,49 +718,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
@@ -754,26 +770,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(),
   /**
@@ -782,11 +798,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()
@@ -796,7 +812,7 @@ var startConversationResponseSchema = z16.object({
 import "zod";
 
 // src/schema/json-schema.ts
-import { z as z18 } from "zod";
+import { z as z19 } from "zod";
 
 // src/configurator/field-help.tsx
 import { createPortal } from "preact/compat";