@gamaro.io/widget 0.6.0 → 1.0.1

package/README.md

@@ -5,9 +5,10 @@
 [![types](https://img.shields.io/npm/types/@gamaro.io/widget.svg)](#typescript)
 [![license](https://img.shields.io/badge/license-Commercial%20Source--available-blue.svg)](./LICENSE)
 
-Versiq Widget SDK — embed a conversational conversion agent that answers
-visitors using **your** site's data (catalogue, inventory, CRM, knowledge base),
-not the public-web average a generic LLM assistant returns.
+Gamaro Widget SDK — embed a conversational conversion agent that grounds every
+response in **your** site's own data (catalogue, inventory, CRM, knowledge base)
+instead of the undifferentiated public training data a generic LLM assistant
+would otherwise draw on.
 
 ## Table of Contents
 
@@ -71,7 +72,7 @@ the cost of having to bump it manually on every release.
 ### Programmatic API
 
 The minimal integration is one line — every visual and behavioural aspect
-(theme, position, language, open-state, branding) is configured in the **Versiq
+(theme, position, language, open-state, branding) is configured in the **Gamaro
 admin portal** for your Agent and resolved server-side from the API key.
 
 ```typescript
@@ -93,16 +94,16 @@ widget.destroy();
 Two reasons most platforms fail to convert mobile visitors, and two reasons this
 widget does:
 
-1. **It speaks with your data, not the public-web average.** The agent answers
-   from your catalogue, your stock, your CRM, your knowledge base — what your
-   competitors and generic AI assistants don't have.
+1. **It grounds every answer in your own data, not generic AI training data.**
+   The agent answers from your catalogue, your stock, your CRM, your knowledge
+   base — what your competitors and generic AI assistants don't have.
 2. **It is driven by your thumb, not your keyboard.** The LLM dynamically picks
    the right component at every turn — quick replies, sliders, product cards —
    instead of forcing a form. Visitors qualify their need in a few taps on
    mobile, where 3+ field forms lose 50%+ of users (HubSpot).
 
 The widget rendering layer (`QuickReplies`, `PropertyCard`, `ActionButtons`) is
-the runtime that materialises this. Schemas live in the Versiq backend
+the runtime that materialises this. Schemas live in the Gamaro backend
 repository and are out of scope for the SDK consumer.
 
 ## Configuration
@@ -125,22 +126,22 @@ context (DOM, identity, environment).
 | `userId`    | `string`                | -              | Host-side stable user identifier — must be paired with `userHash`.                                      |
 | `userHash`  | `string`                | -              | HMAC-SHA256 of `email` (or `userId`), signed with the Agent identity secret. See _Identity_.            |
 
-### 2. Server-resolved (configured in the Versiq admin portal)
+### 2. Server-resolved (configured in the Gamaro admin portal)
 
 These are **not** passed by the integration — they are stored in the Agent's
 `widget_config` JSONB row and fetched at bootstrap from the API key. To change
 any of them, edit the Agent in the portal.
 
-| Field             | Configured in admin        | Notes                                                                                                       |
-| ----------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `theme`           | Apparence → palette        | Full palette (`primaryColor`, `backgroundColor`, `textColor`, `borderRadius`, `fontFamily`, `colorScheme`). |
-| `position`        | Apparence → position       | `"bottom-right"`, `"bottom-left"`, or `"inline"`.                                                           |
-| `language`        | Apparence → langue         | ISO 639-1 (e.g. `fr`, `en`). Falls back to browser language when unset.                                     |
-| `showProfile`     | Apparence → panneau profil | Toggles the profile panel in the widget header.                                                             |
-| `open`            | Apparence → état initial   | Default open state on page load. Host can still call `widget.open()` programmatically.                      |
-| `brand.title`     | Branding → titre           | Custom header title (falls back to a vertical-specific default).                                            |
-| `brand.avatarUrl` | Branding → avatar          | Custom avatar URL (must originate from the portal upload — arbitrary URLs are rejected).                    |
-| `vertical`        | Agent creation             | `real-estate`, `b2b-qualification`, … Bound to the API key.                                                 |
+| Field             | Configured in admin        | Notes                                                                                                                                                                 |
+| ----------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `theme`           | Apparence → palette        | Full palette (`primaryColor`, `backgroundColor`, `textColor`, `borderRadius`, `fontFamily`, `colorScheme`).                                                           |
+| `position`        | Apparence → position       | `"bottom-right"`, `"bottom-left"`, or `"inline"`.                                                                                                                     |
+| `language`        | Apparence → langue         | ISO 639-1 (e.g. `fr`, `en`). Falls back to browser language when unset.                                                                                               |
+| `showProfile`     | Apparence → panneau profil | Forces the profile panel visible from the start of the conversation. The panel already shows on its own once the visitor's profile has data, regardless of this flag. |
+| `open`            | Apparence → état initial   | Default open state on page load. Host can still call `widget.open()` programmatically.                                                                                |
+| `brand.title`     | Branding → titre           | Custom header title (falls back to a vertical-specific default).                                                                                                      |
+| `brand.avatarUrl` | Branding → avatar          | Custom avatar URL (must originate from the portal upload — arbitrary URLs are rejected).                                                                              |
+| `vertical`        | Agent creation             | `real-estate`, `b2b-qualification`, … Bound to the API key.                                                                                                           |
 
 ### 3. Client overrides (advanced — rarely needed in production)
 
@@ -199,7 +200,7 @@ const widget = createWidget({
 });
 ```
 
-### VersiqWidget Methods
+### GamaroWidget Methods
 
 | Method                                                | Description                                              |
 | ----------------------------------------------------- | -------------------------------------------------------- |
@@ -215,15 +216,15 @@ const widget = createWidget({
 
 ### Window API (Script Tag)
 
-When using the script tag, the API is available on `window.Versiq`:
+When using the script tag, the API is available on `window.Gamaro`:
 
 ```javascript
-window.Versiq.open();
-window.Versiq.close();
-window.Versiq.setTheme({ primaryColor: "#10B981" });
+window.Gamaro.open();
+window.Gamaro.close();
+window.Gamaro.setTheme({ primaryColor: "#10B981" });
 
 // Wire your own dark-mode toggle to the widget:
-window.Versiq.setColorScheme("dark"); // or "light", or "auto"
+window.Gamaro.setColorScheme("dark"); // or "light", or "auto"
 ```
 
 ## Events
@@ -281,7 +282,7 @@ The package includes full TypeScript support with exported types:
 import type {
   WidgetConfig,
   ThemeConfig,
-  VersiqWidget,
+  GamaroWidget,
   WidgetEventType,
   WidgetProfile,
   WidgetMessage,
@@ -307,7 +308,7 @@ vertical = creating a new Agent + new key.
 ### Real-Estate flow
 
 When the resolved vertical is `real-estate`, the widget runs in qualification
-mode: Versiq qualifies the buyer through conversation and emits the profile — no
+mode: Gamaro qualifies the buyer through conversation and emits the profile — no
 property data is needed from the integrator (data-dependent tools like
 `searchProperties`, `getCityStats`, `estimateProperty` are automatically
 excluded).
@@ -381,10 +382,10 @@ createWidget({
 "use client";
 
 import { useEffect, useRef } from "react";
-import { createWidget, type VersiqWidget } from "@gamaro.io/widget";
+import { createWidget, type GamaroWidget } from "@gamaro.io/widget";
 
 export function ContactWidget() {
-  const widgetRef = useRef<VersiqWidget | null>(null);
+  const widgetRef = useRef<GamaroWidget | null>(null);
   const containerRef = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
@@ -448,7 +449,7 @@ attestation, the host `Permissions-Policy`, and your `Content-Security-Policy`.
 ### Identity verification (HMAC)
 
 By default a visitor is anonymous. If your page already knows who the visitor is
-(a logged-in user), you can attest that identity to Versiq so leads are attached
+(a logged-in user), you can attest that identity to Gamaro so leads are attached
 to the right account — without trusting a client-supplied email blindly.
 
 Pass `email` (or `userId`) **together with** a `userHash`: an HMAC-SHA256 of the
@@ -507,7 +508,7 @@ conversation still works; the visitor just types the city manually.
 Permissions-Policy controls **what the iframe is allowed to do**;
 Content-Security-Policy controls **where scripts / iframes / styles can come
 from**. Both are independent and both are needed in production. The CSP
-directives required for the Versiq widget are documented in the Versiq backend
+directives required for the Gamaro widget are documented in the Gamaro backend
 repo at `docs/B2B_INTEGRATION.md` § "Content-Security-Policy pour intégrateurs".
 
 ## E2E Test Selectors (data-testid)
@@ -516,21 +517,22 @@ For a smoke test that the widget mounted and works on your page, a small core of
 `data-testid` selectors is exposed. These are guaranteed not to change without a
 major version bump.
 
-| Selector                | Element                                                                       | Additional attributes              |
-| ----------------------- | ----------------------------------------------------------------------------- | ---------------------------------- |
-| `widget-root`           | Chat container (open)                                                         | —                                  |
-| `widget-input`          | Message input field                                                           | —                                  |
-| `widget-send`           | Send button                                                                   | —                                  |
-| `widget-message`        | Message bubble                                                                | `data-role="user" \| "assistant"`  |
-| `widget-loading-status` | Running-tool status label beside the typing dots (e.g. "Recherche de biens…") | — (absent until a tool runs)       |
-| `widget-suggestion`     | Quick reply chip                                                              | `data-index="<N>"` (position)      |
-| `widget-cta-button`     | Call-to-action button                                                         | `data-objective="<objectiveType>"` |
-| `widget-avatar`         | Header avatar                                                                 | —                                  |
+| Selector                      | Element                                                                                                                                           | Additional attributes                                     |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `widget-root`                 | Chat container (open)                                                                                                                             | —                                                         |
+| `widget-input`                | Message input field                                                                                                                               | —                                                         |
+| `widget-send`                 | Send button                                                                                                                                       | —                                                         |
+| `widget-message`              | Message bubble                                                                                                                                    | `data-role="user" \| "assistant"`                         |
+| `widget-loading-status`       | Running-tool status label beside the typing dots (e.g. "Recherche de biens…")                                                                     | — (absent until a tool runs)                              |
+| `widget-suggestion`           | Quick reply chip                                                                                                                                  | `data-index="<N>"` (position)                             |
+| `widget-cta-summary-continue` | Pre-CTA recap card "Continue" button (#3028) — precedes `widget-cta-button` when the visitor's profile has display config for the active vertical | — (absent otherwise, `widget-cta-button` mounts directly) |
+| `widget-cta-button`           | Call-to-action button                                                                                                                             | `data-objective="<objectiveType>"`                        |
+| `widget-avatar`               | Header avatar                                                                                                                                     | —                                                         |
 
 > The widget also exposes a large set of vertical-specific selectors
 > (real-estate map, areas-overview, exploration mode, criteria popup, range
-> slider, contact form). They are internal to the Versiq UI and out of scope for
-> SDK consumers — the full contract lives in the Versiq backend repository under
+> slider, contact form). They are internal to the Gamaro UI and out of scope for
+> SDK consumers — the full contract lives in the Gamaro backend repository under
 > `apps/app/src/app/widget/embed/components/`.
 
 ### Example (Playwright)
@@ -612,7 +614,7 @@ Lighthouse manually:
   analytics pipeline (Google Analytics 4, Sentry, etc.) to track field LCP per
   real visitor — Lighthouse alone only measures synthetic loads.
 
-The Versiq widget itself does not emit web-vitals events (out of scope — the SDK
+The Gamaro widget itself does not emit web-vitals events (out of scope — the SDK
 should not impose an analytics dependency on the host). Integrators own the
 measurement pipeline for their own page.
 
@@ -656,7 +658,7 @@ Commercial Source-available — see [LICENSE](./LICENSE).
 This is **not** an open-source release: the source is published so integrators
 can audit what runs in their visitors' browsers, but fork / redistribution /
 competing-SDK use are prohibited without a written agreement. Production use
-against the Versiq backend is governed by the Versiq Commercial Terms of
+against the Gamaro backend is governed by the Gamaro Commercial Terms of
 Service.
 
 For commercial licensing inquiries: admin@dolard.eu

package/dist/iframe-loader.d.ts

@@ -3,10 +3,10 @@
  *
  * Promotes a skeleton placeholder into an operational iframe with a per-attempt
  * timeout and a configurable backoff between retries. Single responsibility —
- * the host (`VersiqWidget`) keeps the application FSM, this module owns the
+ * the host (`GamaroWidget`) keeps the application FSM, this module owns the
  * mechanics of getting the iframe up.
  *
- * Success criterion: iframe `load` event AND a `versiq:ready` postMessage from
+ * Success criterion: iframe `load` event AND a `gamaro:ready` postMessage from
  * the embed React app. The AND is mandatory — a 5xx Next page rendered inside
  * the iframe still fires `load`; relying on that alone would mask deployment
  * failures as silent successes.
@@ -48,7 +48,7 @@ export interface IframeLoaderOptions {
     buildIframe: () => HTMLIFrameElement;
     /** DOM node the iframe will be appended to. */
     container: HTMLElement;
-    /** Allowed origins for the `versiq:ready` ack (passed to `isValidOrigin`). */
+    /** Allowed origins for the `gamaro:ready` ack (passed to `isValidOrigin`). */
     allowedOrigins: string[];
     /** Per-attempt timeout in ms. Defaults to `IFRAME_LOAD_TIMEOUT_MS`. */
     timeoutMs?: number;
@@ -69,10 +69,10 @@ export declare class IframeLoadError extends Error {
  * success; throws `IframeLoadError` (reason + final attempt count) on final
  * failure, or `DOMException("AbortError")` when `opts.signal` aborts.
  *
- * The `versiq:ready` message is observed via a LOCAL listener that is detached
+ * The `gamaro:ready` message is observed via a LOCAL listener that is detached
  * the moment the handshake completes — the caller is expected to attach its
  * own applicative listener AFTER this resolves, and to manually set
  * `isReady = true` + send any post-ready commands, since the embed React app
- * only emits `versiq:ready` once on mount.
+ * only emits `gamaro:ready` once on mount.
  */
 export declare function loadIframeWithRetry(opts: IframeLoaderOptions): Promise<HTMLIFrameElement>;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Versiq Widget SDK
+ * Gamaro Widget SDK
  *
  * Entry point for the widget SDK. Supports both auto-initialization from
  * script tags and programmatic usage.
@@ -34,14 +34,14 @@
  * admin sandbox's live-preview use case (client-wins merge). Partner
  * integrators should configure those fields from the admin portal.
  */
-import { VersiqWidget, createWidget } from "./loader";
+import { GamaroWidget, createWidget } from "./loader";
 import type { WidgetConfig } from "./types";
-export { createWidget, VersiqWidget };
+export { createWidget, GamaroWidget };
 export { parseScriptAttributes as __parseScriptAttributes };
 export { getCurrentScript as __getCurrentScript };
 export { autoInit as __autoInit };
 export { themeConfigSchema, widgetPositionSchema, widgetConfigSchema, b2bProfileSchema, widgetMessageSchema, applicationConfigResponseSchema, } from "./types";
-export type { WidgetConfig, WidgetPosition, ColorScheme, ThemeConfig, B2BProfile, WidgetProfile, WidgetMessage, WidgetEvent, WidgetEventType, WidgetEventHandler, VersiqAPI, ApplicationConfigResponse, } from "./types";
+export type { WidgetConfig, WidgetPosition, ColorScheme, ThemeConfig, B2BProfile, WidgetProfile, WidgetMessage, WidgetEvent, WidgetEventType, WidgetEventHandler, GamaroAPI, ApplicationConfigResponse, } from "./types";
 export { fetchApplicationConfig, ConfigFetchError } from "./config";
 /**
  * Parse script tag data attributes to extract widget config (#726).

package/dist/loader.d.ts

@@ -6,9 +6,9 @@
  * - postMessage communication
  * - Public API exposure
  */
-import type { WidgetConfig, WidgetEventType, WidgetEventHandler, VersiqAPI, ColorScheme, ThemeConfig } from "./types";
+import type { WidgetConfig, WidgetEventType, WidgetEventHandler, GamaroAPI, ColorScheme, ThemeConfig } from "./types";
 export declare function __resetInstanceCounter(): void;
-export declare class VersiqWidget implements VersiqAPI {
+export declare class GamaroWidget implements GamaroAPI {
     readonly version = "0.1.0";
     /**
      * Original config as passed by the caller — preserved separately from
@@ -100,7 +100,7 @@ export declare class VersiqWidget implements VersiqAPI {
     private init;
     /**
      * Strip any path from `baseUrl` so the resulting string matches the
-     * `event.origin` field of a `versiq:ready` postMessage (which is always
+     * `event.origin` field of a `gamaro:ready` postMessage (which is always
      * scheme + host + port, no path). Falls back to the raw value if parsing
      * fails so a malformed config does not silently break the loader gate.
      */
@@ -143,4 +143,4 @@ export declare class VersiqWidget implements VersiqAPI {
 /**
  * Create a new widget instance.
  */
-export declare function createWidget(config: WidgetConfig): VersiqWidget;
+export declare function createWidget(config: WidgetConfig): GamaroWidget;

package/dist/postmessage.d.ts

@@ -15,9 +15,9 @@ import type { WidgetCommand, WidgetEvent } from "./types";
  */
 export declare function isValidOrigin(origin: string, allowedOrigins: string[]): boolean;
 /**
- * Check if an event contains a valid Versiq message.
+ * Check if an event contains a valid Gamaro message.
  */
-export declare function isVersiqMessage(event: MessageEvent): event is MessageEvent<WidgetCommand | WidgetEvent>;
+export declare function isGamaroMessage(event: MessageEvent): event is MessageEvent<WidgetCommand | WidgetEvent>;
 /**
  * Send a command to the widget iframe.
  */

package/dist/types.d.ts

@@ -6,7 +6,7 @@
  * re-exports them so existing consumers (`apps/marketing`,
  * `apps/app/src/components/portal/sandbox`) keep working unchanged. The only
  * types still defined locally are widget-specific SDK surfaces (B2B profile
- * schemas, `VersiqAPI`, `window` augmentation).
+ * schemas, `GamaroAPI`, `window` augmentation).
  */
 import { z } from "zod";
 import type { ColorScheme, ThemeConfig, WidgetEventHandler, WidgetEventType } from "@gamaro.io/core-types";
@@ -145,9 +145,9 @@ export declare const b2bProfileSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type B2BProfile = z.infer<typeof b2bProfileSchema>;
 /**
- * Public API exposed on window.Versiq.
+ * Public API exposed on window.Gamaro.
  */
-export interface VersiqAPI {
+export interface GamaroAPI {
     /** Application ID (available after config resolution) */
     readonly applicationId: string;
     /** Open the widget */
@@ -161,7 +161,7 @@ export interface VersiqAPI {
     /**
      * Update only the color scheme. Sugar over `setTheme({ colorScheme })` so
      * integrators can wire their own dark-mode toggle without rebuilding the
-     * full theme object: `window.Versiq.setColorScheme("dark")`.
+     * full theme object: `window.Gamaro.setColorScheme("dark")`.
      */
     setColorScheme(scheme: ColorScheme): void;
     /** Identify the current user with host-attested HMAC verification */
@@ -179,7 +179,7 @@ export interface VersiqAPI {
 }
 declare global {
     interface Window {
-        Versiq?: VersiqAPI;
-        VersiqApps?: Map<string, VersiqAPI>;
+        Gamaro?: GamaroAPI;
+        GamaroApps?: Map<string, GamaroAPI>;
     }
 }