@helpai/elements 0.25.0 → 0.27.0

package/README.md

@@ -85,7 +85,7 @@ re-resolves at runtime.
 | `index.mjs` / `web-component.mjs` | ESM    | Bundlers (Vite, webpack, esbuild) — bare imports kept       |
 | `elements.cjs.js`                 | CJS    | `require()` from Node / legacy tooling         |
 | `style.css`                       | CSS    | `<link rel="stylesheet">`                      |
-| `schema.json`                     | JSON Schema | Dashboard config UIs, backend start-conversation validation, 3rd-party tooling |
+| `schema.json`                     | JSON Schema | Dashboard config UIs, backend handshake validation, 3rd-party tooling |
 | `schema.mjs`                      | ESM    | Zod runtime schemas: `import { widgetConfigSchema } from "@helpai/elements/schema"` |
 
 Every bundle exposes the same surface (`mount`, `init`, `hook`, types).
@@ -323,7 +323,7 @@ attribute. See [https://help.ai/docs/elements/modes](https://help.ai/docs/elemen
 ## Configuration
 
 The element reads its per-deployment configuration from your
-Help AI workspace at start-conversation time — colors, launcher
+Help AI workspace at handshake time — colors, launcher
 chrome, strings, action layout, model defaults, history visibility
 all flow through `StartConversationResponse.settings`. You don't recompile
 per-customer.

package/configurator.mjs

@@ -132,7 +132,7 @@ var behaviorSchema = z4.object({
     "Show tool/function calls the model makes (e.g. search) as inline chips in the transcript. `false` (default) hides them."
   ),
   popOutUrl: z4.string().min(1).max(2048).optional().describe(
-    "URL the `popOut` action opens in a new tab (carries `?conversation=<id>&widgetId=<id>` query params). Falls back to the brand's build-time default. Set this to point at your own dedicated chat page (e.g. `https://app.acme.com/chat`). Server-pushable on `/start-conversation.widget.behavior.popOutUrl`."
+    "URL the `popOut` action opens in a new tab (carries `?conversation=<id>&widgetId=<id>` query params). Falls back to the brand's build-time default. Set this to point at your own dedicated chat page (e.g. `https://app.acme.com/chat`). Server-pushable on `/handshake.widget.behavior.popOutUrl`."
   )
 }).loose().describe("Lifecycle + streaming behaviour. Doesn't affect visual presentation.").meta({
   examples: [
@@ -572,13 +572,15 @@ 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."),
+  enabled: z15.boolean().optional().describe(
+    "Master switch. Default `true` \u2014 the widget always fires; the data module gates ingestion per deployment server-side. Set `false` to silence the client entirely."
+  ),
   endpoint: z15.url().max(2048).optional().describe(
-    "Pixel collector URL. Default: `${dataBaseUrl}/elements/px.gif` (e.g. `https://help.ai/api/data/elements/px.gif`). Must be a full URL."
+    "Pixel collector URL. Default: `${dataBaseUrl}/pai/elements-px.gif` (e.g. `https://help.ai/api/data/pai/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`)."
+    "Anti-forgery token, echoed as `tk=` on every hit. Server-issued in the `/handshake` 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."
@@ -588,16 +590,16 @@ var trackingSchema = z15.object({
 
 // src/schema/widget.ts
 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("/submit-form").describe(
+  upload: z16.string().min(1).max(2048).default("/pai/upload-file"),
+  transcribe: z16.string().min(1).max(2048).default("/pai/transcribe-audio"),
+  submitForm: z16.string().min(1).max(2048).default("/pai/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. `upload` / `transcribe` paths are appended to the agent base (`${baseUrl}/api/agent`), `submitForm` to the data base (`dataBaseUrl`); absolute URLs are accepted too."
 ).meta({
   examples: [
-    { upload: "/ai/agent/upload-file", transcribe: "/ai/agent/transcribe-audio" },
+    { upload: "/pai/upload-file", transcribe: "/pai/transcribe-audio" },
     { upload: "https://help.ai/uploads/presign" },
     { submitForm: "https://crm.acme.com/leads" }
   ]
@@ -646,8 +648,11 @@ var connectionConfigSchema = z16.object({
   baseUrl: z16.string().min(1).max(2048).optional().describe(
     "MAIN site origin (e.g. `https://help.ai`) \u2014 the API modules derive from it: agent API at `${baseUrl}/api/agent`, data API at `${baseUrl}/api/data`. Set this to point at your staging / self-hosted / custom backend. Default: the brand's `defaultBaseUrl` baked at build time."
   ),
+  agentBaseUrl: z16.string().min(1).max(2048).optional().describe(
+    "Full agent-API base \u2014 set it to reach a STANDALONE `module-help-ai-agent-api` directly (local module on its own port, e.g. `http://localhost:3087`; routes attach as-is: `/pai/handshake`). Precedence: this option > derived from the main origin (`${baseUrl}/api/agent`). Not server-pushable."
+  ),
   dataBaseUrl: z16.string().min(1).max(2048).optional().describe(
-    "Full data-API base (e.g. `https://help.ai/api/data`) \u2014 the service serving content, form definitions (`GET /forms`), and form submissions at root-level paths. Precedence: this option > server-pushed `config.dataBaseUrl` > derived from the main origin (`${baseUrl}/api/data`)."
+    "Full data-API base (e.g. `https://help.ai/api/data`, or a standalone local module like `http://localhost:3106`) \u2014 the service serving content, form definitions (`GET /forms`), and form submissions at root-level paths. Precedence: this option > server-pushed `config.dataBaseUrl` > derived from the main origin (`${baseUrl}/api/data`)."
   ),
   userContext: userContextSchema.optional(),
   pageContext: pageContextSchema.optional(),
@@ -687,7 +692,7 @@ var widgetSettingsSchema = z16.object({
   modules: modulesSchema.optional(),
   tracking: trackingSchema.optional()
 }).loose().describe(
-  "Portal-configurable widget settings \u2014 fourteen 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 `/pai/handshake` under `config`."
 ).meta({
   examples: [
     { presentation: { mode: "floating", position: "bottom-right" }, theme: "auto" },
@@ -705,10 +710,8 @@ var widgetSettingsSchema = z16.object({
 });
 var widgetConfigSchema = connectionConfigSchema.extend({
   ...widgetSettingsSchema.shape,
-  site: z16.unknown().optional().describe(
-    'Site config \u2014 applies in `mode: "page"`. Comes from the start-conversation response, not user-edited.'
-  ),
-  blocks: z16.unknown().optional().describe('Blocks (nav + link cards) \u2014 applies in `mode: "page"`. Comes from the start-conversation response.')
+  site: z16.unknown().optional().describe('Site config \u2014 applies in `mode: "page"`. Comes from the handshake response, not user-edited.'),
+  blocks: z16.unknown().optional().describe('Blocks (nav + link cards) \u2014 applies in `mode: "page"`. Comes from the handshake 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({
@@ -757,7 +760,7 @@ var handshakeWelcomeSuggestionSchema = z17.object({
   text: z17.string().optional()
 }).loose();
 var rebindReasonSchema = z17.enum(["conflict", "expired", "invalid"]);
-var startConversationResponseSchema = z17.object({
+var handshakeResponseSchema = z17.object({
   deployment: z17.object({
     id: z17.string(),
     name: z17.string(),
@@ -791,8 +794,6 @@ var startConversationResponseSchema = z17.object({
   }).loose().optional(),
   visitorId: z17.string(),
   conversationId: z17.string(),
-  canContinue: z17.boolean(),
-  messages: z17.array(z17.unknown()),
   /**
    * Per-visitor preferences (locale picker, theme picker, sound
    * mute, dragged panel size). Distinct from `config` — this is