@helpai/elements 0.14.0 → 0.14.2

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-session validation, 3rd-party tooling |
+| `schema.json`                     | JSON Schema | Dashboard config UIs, backend start-conversation 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,9 +323,9 @@ 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-session time — colors, launcher
+Help AI workspace at start-conversation time — colors, launcher
 chrome, strings, action layout, model defaults, history visibility
-all flow through `StartSessionResponse.settings`. You don't recompile
+all flow through `StartConversationResponse.settings`. You don't recompile
 per-customer.
 
 A handful of options live in the install snippet itself:

package/configurator.mjs

@@ -17,7 +17,7 @@ var linkSchema = z.object({
 var cssLengthSchema = z.string().min(1).max(120).describe("Any CSS length \u2014 `640px`, `80vh`, `calc(100vh - 64px)`, etc. Validated only for size, not syntax.");
 var cssColorSchema = z.string().min(1).max(120).describe("Any CSS colour \u2014 hex, `rgb()`, `hsl()`, `oklch()`, a named colour, or a `var(--token)`.");
 var localeSchema = z.string().min(1).max(35).describe("BCP-47 locale tag (e.g. `en`, `fr-CA`, `zh-Hant-HK`).");
-var uuid7Schema = z.uuidv7().describe("UUID v7 (RFC 9562) \u2014 the single id format for visitor / session / message / file / content ids.");
+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 z16 } from "zod";
@@ -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 `?chat=<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-session.widget.behavior.popOutUrl`."
+    "URL the `popOut` action opens in a new tab (carries `?chat=<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`."
   )
 }).loose().describe("Lifecycle + streaming behaviour. Doesn't affect visual presentation.").meta({
   examples: [
@@ -439,23 +439,21 @@ var formDefSchema = z13.object({
   title: z13.string().max(120).optional(),
   description: z13.string().max(500).optional(),
   submitLabel: z13.string().max(60).optional(),
-  skippable: z13.boolean().default(false).describe("Show a Skip control."),
-  blocking: z13.boolean().default(false).describe("Gate the composer (honored only for `pre-chat` / `after-messages`); otherwise renders inline."),
-  frequency: z13.enum(["once", "session", "always"]).default("once").describe("`once` (persisted per-device), `session`, or `always`."),
+  skippable: z13.boolean().default(false).describe("Show a Skip control so the visitor can dismiss the form."),
+  frequency: z13.enum(["once", "conversation", "always"]).default("once").describe("`once` (per device, persisted), `conversation` (re-eligible each new conversation), or `always`."),
   mirrorToContext: z13.boolean().default(true).describe(
     "Mirror the answers into `userContext` so they ride every request. Set `false` for PII (DOB, policy #, symptoms) \u2014 those then go only to the submit endpoint."
   )
 }).loose();
 var formsSchema = z13.array(formDefSchema).max(20).describe(
-  "Event-driven forms \u2014 an ordered list (order = priority). Each binds to trigger event(s), shows blocking or inline, dedupes by frequency, and records via `endpoints.forms`. Generic across verticals."
+  "Event-driven forms \u2014 an ordered list (order = priority). Each binds to trigger event(s), gates the chat until submit/skip, dedupes by frequency, and records via `endpoints.submitForm`. Generic across verticals."
 ).meta({
   examples: [
-    [{ id: "intake", on: "pre-chat", blocking: true, fields: [{ name: "email", label: "Email", type: "email" }] }],
+    [{ id: "intake", on: "pre-chat", fields: [{ name: "email", label: "Email", type: "email" }] }],
     [
       {
         id: "lead",
         on: "pre-chat",
-        blocking: true,
         title: "Before we start",
         fields: [
           { name: "name", label: "Your name", type: "text" },
@@ -581,7 +579,7 @@ 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 + sessionId as the conversation; the payload carries `formId` + `trigger` so the backend can route. Optional \u2014 a 404 is ignored."
+    "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({
   examples: [
@@ -672,7 +670,7 @@ var widgetSettingsSchema = z16.object({
   forms: formsSchema.optional(),
   modules: modulesSchema.optional()
 }).loose().describe(
-  "Portal-configurable widget settings \u2014 thirteen sections, one per dashboard tab. The backend pushes this same shape on `/ai/agent/start-session` under `config`."
+  "Portal-configurable widget settings \u2014 thirteen 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" },
@@ -690,8 +688,10 @@ 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-session response, not user-edited.'),
-  blocks: z16.unknown().optional().describe('Blocks (nav + link cards) \u2014 applies in `mode: "page"`. Comes from the start-session response.')
+  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.')
 }).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({
@@ -738,7 +738,7 @@ var handshakeWelcomeSuggestionSchema = z17.object({
   text: z17.string().optional()
 }).loose();
 var rebindReasonSchema = z17.enum(["conflict", "expired", "invalid"]);
-var startSessionResponseSchema = z17.object({
+var startConversationResponseSchema = z17.object({
   deployment: z17.object({
     id: z17.string(),
     name: z17.string(),
@@ -771,7 +771,7 @@ var startSessionResponseSchema = z17.object({
     suggestions: z17.array(handshakeWelcomeSuggestionSchema).optional()
   }).loose().optional(),
   visitorId: z17.string(),
-  sessionId: z17.string(),
+  conversationId: z17.string(),
   canContinue: z17.boolean(),
   messages: z17.array(z17.unknown()),
   /**
@@ -782,11 +782,11 @@ var startSessionResponseSchema = z17.object({
    */
   userPrefs: z17.record(z17.string(), z17.unknown()).optional(),
   // Present only when the server rotated the request `visitorId` /
-  // `sessionId`. Purely advisory — client must adopt the response ids
+  // `conversationId`. Purely advisory — client must adopt the response ids
   // verbatim regardless of whether this block is present.
   rebind: z17.object({
     visitorId: rebindReasonSchema.optional(),
-    sessionId: rebindReasonSchema.optional()
+    conversationId: rebindReasonSchema.optional()
   }).loose().optional()
 }).loose();