@dolard.eu/versiq-widget 0.1.0

package/LICENSE

@@ -0,0 +1,55 @@
+Versiq Widget SDK — Commercial Source-available License
+========================================================
+
+Copyright (c) 2024-2026 Sébastien Dolard
+
+This software is made available for inspection. Source code is published only
+so integrators can verify what runs on their visitors' browsers. Publication
+is NOT an open-source release and does NOT grant rights normally associated
+with such releases.
+
+1. Permitted use
+   You may, without separate written agreement:
+   (a) Include `dist/widget.umd.js` or `dist/widget.es.js` on websites you
+       operate, for the sole purpose of consuming the Versiq backend API
+       using a publishable key you have legitimately obtained.
+   (b) Hot-link the bundle from public CDNs that mirror npm (e.g. unpkg,
+       jsDelivr), provided you do not strip or alter the file.
+   (c) Configure the widget at runtime via the public TypeScript surface
+       (theme, position, lifecycle handlers, identity hooks, etc.) as
+       documented in the README.
+
+2. Prohibited without prior written agreement
+   You may not, in whole or in part:
+   (a) Modify, fork, or create derivative works of the source or bundle for
+       redistribution under any name.
+   (b) Reverse-engineer, decompile, or de-obfuscate the bundle, in whole or
+       in part, for the purpose of creating a competing SDK, widget, or
+       backend.
+   (c) Redistribute the bundle, or any derivative, under a different package
+       name, namespace, or scope.
+   (d) Remove, alter, or obscure copyright notices, attribution, or this
+       license file from any copy.
+
+3. Production use
+   Use of this software against the Versiq backend in production is subject
+   to the Versiq Commercial Terms of Service. The license granted here does
+   not by itself authorize production use; a valid commercial agreement
+   (typically reflected by an issued publishable key bound to an
+   Application) is required.
+
+4. No warranty
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+   OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+   IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+   CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+   TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+   SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+5. Termination
+   Any breach of section 2 terminates your rights under section 1
+   immediately, without notice, and you must cease all use of the software
+   and destroy all copies in your possession or control.
+
+For commercial licensing or written-agreement inquiries: admin@dolard.eu

package/README.md

@@ -0,0 +1,401 @@
+# @dolard.eu/versiq-widget
+
+Versiq Widget SDK - Embed conversational qualification into your website.
+
+## Installation
+
+```bash
+npm install @dolard.eu/versiq-widget
+# or
+pnpm add @dolard.eu/versiq-widget
+```
+
+## Quick Start
+
+### Script Tag (CDN)
+
+Hot-link from any public npm CDN, pinned to a version:
+
+```html
+<script
+  src="https://unpkg.com/@dolard.eu/versiq-widget@0.1.0/dist/widget.umd.js"
+  data-api-key="pk_your_key"
+  data-theme='{"primaryColor":"#3B82F6"}'
+></script>
+```
+
+Equivalent via jsDelivr:
+
+```html
+<script
+  src="https://cdn.jsdelivr.net/npm/@dolard.eu/versiq-widget@0.1.0/dist/widget.umd.js"
+  data-api-key="pk_your_key"
+></script>
+```
+
+Pinning a version avoids breaking changes from later releases. To always follow
+the latest, drop `@0.1.0`.
+
+### Programmatic API
+
+```typescript
+import { createWidget, type VersiqWidget } from "@dolard.eu/versiq-widget";
+
+const widget = createWidget({
+  apiKey: "pk_your_key",
+  position: "bottom-right",
+  theme: { primaryColor: "#3B82F6" },
+});
+
+// Control the widget
+widget.open();
+widget.close();
+widget.reset();
+
+// Cleanup
+widget.destroy();
+```
+
+## Configuration
+
+### WidgetConfig
+
+| Option      | Type                                          | Default          | Description                                  |
+| ----------- | --------------------------------------------- | ---------------- | -------------------------------------------- |
+| `apiKey`    | `string`                                      | **required**     | Publishable API key (`pk_*`) for the app     |
+| `position`  | `"bottom-right" \| "bottom-left" \| "inline"` | `"bottom-right"` | Widget position on the page                  |
+| `open`      | `boolean`                                     | `false`          | Initial open state                           |
+| `container` | `HTMLElement \| string`                       | -                | Container element for inline mode            |
+| `baseUrl`   | `string`                                      | Production URL   | Base URL for the widget embed                |
+| `theme`     | `ThemeConfig`                                 | -                | Custom theme (merged with server-side theme) |
+| `debug`     | `boolean`                                     | `false`          | Enable debug logging                         |
+| `email`     | `string`                                      | -                | Pre-identified user email (HMAC)             |
+| `userId`    | `string`                                      | -                | Host-side user identifier (HMAC)             |
+| `userHash`  | `string`                                      | -                | HMAC-SHA256 of email/userId                  |
+
+### ThemeConfig
+
+| Option            | Type                          | Description                                                                                    |
+| ----------------- | ----------------------------- | ---------------------------------------------------------------------------------------------- |
+| `primaryColor`    | `string`                      | Primary brand color (hex, e.g., `#3B82F6`)                                                     |
+| `backgroundColor` | `string`                      | Background color for the widget container                                                      |
+| `textColor`       | `string`                      | Text color                                                                                     |
+| `borderRadius`    | `number`                      | Border radius in pixels                                                                        |
+| `fontFamily`      | `string`                      | Font family                                                                                    |
+| `colorScheme`     | `"light" \| "dark" \| "auto"` | Widget color scheme. `"auto"` follows the visitor's `prefers-color-scheme`. Defaults to light. |
+
+## API Reference
+
+### createWidget(config)
+
+Creates a new widget instance.
+
+```typescript
+const widget = createWidget({
+  apiKey: "pk_your_key",
+  position: "inline",
+  container: document.getElementById("widget-container"),
+  open: true,
+});
+```
+
+### VersiqWidget Methods
+
+| Method                                                | Description                                              |
+| ----------------------------------------------------- | -------------------------------------------------------- |
+| `open()`                                              | Open the widget                                          |
+| `close()`                                             | Close the widget                                         |
+| `reset()`                                             | Reset the conversation                                   |
+| `setTheme(theme: ThemeConfig)`                        | Update theme dynamically                                 |
+| `setColorScheme(scheme: "light" \| "dark" \| "auto")` | Sugar over `setTheme({ colorScheme })` for dark-mode UIs |
+| `identify(params)`                                    | Set host-attested identity (HMAC)                        |
+| `destroy()`                                           | Remove widget and cleanup                                |
+| `on(event, handler)`                                  | Subscribe to events                                      |
+| `off(event, handler)`                                 | Unsubscribe from events                                  |
+
+### Window API (Script Tag)
+
+When using the script tag, the API is available on `window.Versiq`:
+
+```javascript
+window.Versiq.open();
+window.Versiq.close();
+window.Versiq.setTheme({ primaryColor: "#10B981" });
+
+// Wire your own dark-mode toggle to the widget:
+window.Versiq.setColorScheme("dark"); // or "light", or "auto"
+```
+
+## Events
+
+Subscribe to widget events to react to user interactions.
+
+```typescript
+widget.on("ready", () => {
+  console.log("Widget is ready");
+});
+
+widget.on("profile-update", (data) => {
+  console.log("Profile updated:", data.profile);
+});
+
+widget.on("qualified", (data) => {
+  console.log("Lead qualified:", data.profile, "Score:", data.score);
+});
+
+widget.on("message", (data) => {
+  console.log("New message:", data.message);
+});
+
+widget.on("error", (data) => {
+  console.error("Widget error:", data.code, data.message);
+});
+```
+
+### Event Types
+
+| Event               | Payload                                     | Description                   |
+| ------------------- | ------------------------------------------- | ----------------------------- |
+| `ready`             | -                                           | Widget is loaded and ready    |
+| `open`              | -                                           | Widget was opened             |
+| `close`             | -                                           | Widget was closed             |
+| `message`           | `{ message: WidgetMessage }`                | New chat message              |
+| `profile-update`    | `{ profile: WidgetProfile }`                | Profile data was updated      |
+| `qualified`         | `{ profile: WidgetProfile, score: number }` | Lead qualification complete   |
+| `error`             | `{ code: string, message: string }`         | An error occurred             |
+| `quota-warning`     | `{ remaining: number, limit: number }`      | Lead quota running low        |
+| `quota-exceeded`    | -                                           | Lead quota exceeded           |
+| `identity-verified` | `{ email: string, userId?: string }`        | Host identity verified (HMAC) |
+
+## TypeScript
+
+The package includes full TypeScript support with exported types:
+
+```typescript
+import type {
+  WidgetConfig,
+  ThemeConfig,
+  VersiqWidget,
+  WidgetEventType,
+  WidgetProfile,
+  WidgetMessage,
+  B2BProfile, // B2B-specific (backward compat)
+} from "@dolard.eu/versiq-widget";
+```
+
+### Profile Types
+
+- **`WidgetProfile`** (`Record<string, unknown>`) — Generic profile used in
+  events. Shape depends on the vertical (`BuyerProfile` for real-estate,
+  `B2BProfile` for b2b-qualification).
+- **`B2BProfile`** — Typed B2B qualification profile (sector, companySize,
+  etc.). Kept for backward compatibility.
+
+## Widget Mode (Real-Estate)
+
+When using `vertical: "real-estate"`, the widget runs in **qualification mode**:
+Versiq qualifies the buyer through conversation and transmits the profile — no
+property data is needed from the integrator.
+
+### Flow
+
+1. Versiq detects the user type (buyer, seller, etc.)
+2. Collects criteria: location, budget, property type, surface...
+3. Emits `profile-update` at each turn with the current profile
+4. When qualification is complete, emits `versiq:qualified` with the full
+   profile
+
+### Integration Example
+
+```typescript
+const widget = createWidget({
+  apiKey: "pk_your_real_estate_key",
+  position: "inline",
+  container: "#chat",
+  open: true,
+});
+
+// Track profile updates in real-time
+widget.on("profile-update", (data) => {
+  console.log("Criteria so far:", data.profile);
+  // data.profile: { userType, location, budget, propertyType, ... }
+});
+
+// Lead is fully qualified — trigger your own search/CRM
+widget.on("qualified", (data) => {
+  console.log("Qualified lead:", data.profile);
+  // data.score: 1 (V1: binary — 1 = qualified)
+  triggerPropertySearch(data.profile);
+});
+```
+
+### Data Tools
+
+In widget mode, data-dependent tools (searchProperties, getCityStats,
+estimateProperty, etc.) are **automatically excluded**. The integrator's
+platform provides the data; Versiq handles qualification only.
+
+## Display Modes
+
+### Floating (Default)
+
+Widget appears as a floating button in the corner of the page.
+
+```typescript
+createWidget({
+  apiKey: "pk_your_key",
+  position: "bottom-right", // or "bottom-left"
+});
+```
+
+### Inline
+
+Widget is embedded directly into a container element.
+
+```typescript
+createWidget({
+  apiKey: "pk_your_key",
+  position: "inline",
+  container: document.getElementById("chat-container"),
+  open: true,
+});
+```
+
+## React Integration
+
+```tsx
+"use client";
+
+import { useEffect, useRef } from "react";
+import { createWidget, type VersiqWidget } from "@dolard.eu/versiq-widget";
+
+export function ContactWidget() {
+  const widgetRef = useRef<VersiqWidget | null>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!containerRef.current || widgetRef.current) return;
+
+    const widget = createWidget({
+      apiKey: "pk_your_key",
+      position: "inline",
+      container: containerRef.current,
+      open: true,
+      theme: { primaryColor: "#3B82F6" },
+    });
+
+    widgetRef.current = widget;
+
+    return () => {
+      widgetRef.current?.destroy();
+      widgetRef.current = null;
+    };
+  }, []);
+
+  return <div ref={containerRef} className="h-[600px]" />;
+}
+```
+
+## Data Attributes (Script Tag)
+
+| Attribute        | Maps to    | Example                                 |
+| ---------------- | ---------- | --------------------------------------- |
+| `data-api-key`   | `apiKey`   | `data-api-key="pk_live_abc123"`         |
+| `data-position`  | `position` | `data-position="bottom-left"`           |
+| `data-open`      | `open`     | `data-open="true"`                      |
+| `data-theme`     | `theme`    | `data-theme='{"primaryColor":"#F00"}'`  |
+| `data-base-url`  | `baseUrl`  | `data-base-url="https://app.versiq.io"` |
+| `data-debug`     | `debug`    | `data-debug="true"`                     |
+| `data-email`     | `email`    | `data-email="user@example.com"`         |
+| `data-user-id`   | `userId`   | `data-user-id="usr_123"`                |
+| `data-user-hash` | `userHash` | `data-user-hash="<hmac>"`               |
+
+## E2E Test Selectors (data-testid)
+
+The widget exposes a **stable contract** of `data-testid` attributes for
+end-to-end testing (Playwright, Cypress, etc.). These selectors 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-suggestion` | Quick reply chip      | `data-index="<N>"` (position)      |
+| `widget-cta-button` | Call-to-action button | `data-objective="<objectiveType>"` |
+| `widget-avatar`     | Header avatar         | —                                  |
+
+> Contract source: `apps/app/src/app/widget/embed/components/`. Property card
+> selectors (`widget-property-card`) are not yet exposed (pending #727).
+
+### Example (Playwright)
+
+```ts
+await page.getByTestId("widget-input").fill("Looking for a 2-bedroom in Lyon");
+await page.getByTestId("widget-send").click();
+await expect(
+  page.getByTestId("widget-message").filter({ hasText: "Lyon" }),
+).toBeVisible();
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Development build with watch
+pnpm dev
+
+# Production build
+pnpm build
+
+# Run tests
+pnpm test
+
+# Local testing (serves test.html via HTTP - required for iframe CSP)
+pnpm serve
+# Then open http://localhost:5500/test.html
+```
+
+## Performance
+
+### Bundle Size
+
+| Format | Size (minified) | Size (gzipped) | Limit |
+| ------ | --------------- | -------------- | ----- |
+| UMD    | ~63 KB          | ~16 KB         | 50 KB |
+| ESM    | ~89 KB          | ~19 KB         | -     |
+
+CI enforces the 50 KB gzipped limit via `size-limit`.
+
+### Largest Contentful Paint (LCP)
+
+**Target**: < 1.5s
+
+The widget loads as an iframe, so LCP depends on:
+
+1. SDK download (~16 KB gzipped) - typically < 100ms
+2. Iframe creation - instant
+3. Embed page load - varies by network
+
+**Measured baseline**: 0.14s (localhost, no throttling)
+
+### Integration Time
+
+**Target**: < 15 minutes from docs to working widget
+
+The Quick Start section provides copy-paste integration in under 5 minutes.
+
+## License
+
+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
+Service.
+
+For commercial licensing inquiries: admin@dolard.eu

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+import { type ApplicationConfigResponse } from "./types";
+export declare class ConfigFetchError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare function fetchApplicationConfig(apiKey: string, baseUrl: string, externalSignal?: AbortSignal): Promise<ApplicationConfigResponse>;

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Versiq Widget SDK
+ *
+ * Entry point for the widget SDK. Supports both auto-initialization from
+ * script tags and programmatic usage.
+ *
+ * Auto-init usage (canonical integrator surface — #726):
+ * ```html
+ * <script
+ *   src="https://cdn.versiq.io/widget.js"
+ *   data-api-key="pk_live_xxx">
+ * </script>
+ * ```
+ *
+ * The integrator's HTML carries only the publishable key (plus optional
+ * host-context attributes like `data-container` / `data-debug` / identity
+ * fields). Theme, position, language, showProfile, and the default open
+ * state are configured from the admin portal (`/portal/widget`) and
+ * resolved at load time via the publishable key — editing them from
+ * HTML is no longer supported. The legacy `data-theme` / `data-position` /
+ * `data-language` / `data-show-profile` / `data-open` attributes are
+ * silently ignored.
+ *
+ * Programmatic usage (internal dev surface — admin preview, marketing
+ * demo — not recommended for partner integrations):
+ * ```javascript
+ * import { createWidget } from '@dolard.eu/versiq-widget';
+ *
+ * const widget = createWidget({ apiKey: 'pk_live_xxx' });
+ * widget.on('qualified', (data) => sendToAnalytics(data));
+ * ```
+ *
+ * Programmatic `theme` / `position` / ... overrides are preserved for the
+ * 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 type { WidgetConfig } from "./types";
+export { createWidget, VersiqWidget };
+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 { fetchApplicationConfig, ConfigFetchError } from "./config";
+/**
+ * Parse script tag data attributes to extract widget config (#726).
+ *
+ * Only host-context attributes are read here — fields that cannot live
+ * server-side because they are tied to the integrator's page (DOM
+ * selectors, dev flags, HMAC-verified identity). Theme, position,
+ * language, showProfile, and the default open state are resolved from
+ * the admin portal via `fetchApplicationConfig` in `loader.ts`.
+ */
+declare function parseScriptAttributes(script: HTMLScriptElement): WidgetConfig | null;
+/**
+ * Find the current script tag.
+ */
+declare function getCurrentScript(): HTMLScriptElement | null;
+/**
+ * Initialize widgets from script tags with data-api-key attributes.
+ * Supports multiple widgets on the same page (multi-instance).
+ */
+declare function autoInit(): void;

package/dist/loader.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Widget Loader
+ *
+ * Creates and manages the widget iframe, handling:
+ * - iFrame injection and positioning
+ * - postMessage communication
+ * - Public API exposure
+ */
+import type { WidgetConfig, WidgetEventType, WidgetEventHandler, VersiqAPI, ColorScheme, ThemeConfig } from "./types";
+export declare function __resetInstanceCounter(): void;
+export declare class VersiqWidget implements VersiqAPI {
+    readonly version = "0.1.0";
+    /**
+     * Original config as passed by the caller — preserved separately from
+     * `this.config` (which has defaults merged on top) so the server-config
+     * merge in `resolveConfig()` can tell "field not set by the caller,
+     * use the server value" from "caller explicitly passed a default".
+     */
+    private originalConfig;
+    private config;
+    private iframe;
+    private container;
+    private skeletonButton;
+    private isOpen;
+    private isReady;
+    private isInitialized;
+    private isDestroyed;
+    private fetchAbortController;
+    private _applicationId;
+    private vertical;
+    private instanceId;
+    private pendingCommands;
+    private eventHandlers;
+    private cleanupListener;
+    private debugLog;
+    private currentViewportMode;
+    private mobileMediaQuery;
+    private tabletMediaQuery;
+    private debounceTimer;
+    private viewportChangeHandler;
+    get applicationId(): string;
+    constructor(config: WidgetConfig);
+    /**
+     * Minimal placeholder launcher rendered synchronously before the server
+     * config arrives. Uses the default position (bottom-right) unless the
+     * caller explicitly provided one. Replaced by the real iframe in
+     * `init()` after `resolveConfig()` succeeds.
+     */
+    private renderSkeleton;
+    /**
+     * Resolve the widget runtime config from the server (#726). Retries once
+     * with a 1s backoff on *transient* failures (network, timeout, 5xx) —
+     * 4xx and parse errors are permanent config/setup problems that a
+     * retry cannot fix, so we surface them immediately. If both attempts
+     * fail, the skeleton stays visible and the widget emits `error` —
+     * visible degraded mode rather than a silently absent widget.
+     */
+    private resolveConfig;
+    private isTransientFetchError;
+    /**
+     * Merge the server-resolved application config into the widget state
+     * and promote the skeleton to a fully-initialised iframe.
+     *
+     * Merge semantics (#726):
+     *  1. Fields explicitly passed to `createWidget(...)` win (`originalConfig`).
+     *     This keeps the admin sandbox's live preview working: unsaved edits
+     *     stay visible on the preview widget.
+     *  2. Otherwise the server's `widget` block (from the publishable key
+     *     lookup) provides theme/position/language/showProfile/open.
+     *  3. Legacy `server.theme` is still merged underneath `server.widget.theme`
+     *     for backward compatibility with pre-#726 data shapes — it will
+     *     be removed once all consumers land the new contract.
+     */
+    private applyServerConfig;
+    private flushPendingCommands;
+    private init;
+    private createContainer;
+    private createIframe;
+    private buildIframeUrl;
+    private setupViewportListener;
+    private handleViewportChange;
+    private getViewportMode;
+    private updateContainerForViewport;
+    private handleMessage;
+    private sendConfig;
+    private updateVisibility;
+    private emit;
+    open(): void;
+    close(): void;
+    reset(): void;
+    identify(params: {
+        email: string;
+        userId?: string;
+        userHash: string;
+    }): void;
+    setTheme(theme: ThemeConfig): void;
+    setColorScheme(scheme: ColorScheme): void;
+    on<T = unknown>(event: WidgetEventType, handler: WidgetEventHandler<T>): void;
+    off<T = unknown>(event: WidgetEventType, handler: WidgetEventHandler<T>): void;
+    destroy(): void;
+    private log;
+}
+/**
+ * Create a new widget instance.
+ */
+export declare function createWidget(config: WidgetConfig): VersiqWidget;

package/dist/logger.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Widget Logger
+ *
+ * Lightweight logger for the widget SDK with consistent prefix.
+ * Provides a centralized logging interface for debug, info, warn, and error levels.
+ */
+/**
+ * Log an error message.
+ */
+export declare function logError(msg: string, ...args: unknown[]): void;
+/**
+ * Log a warning message.
+ */
+export declare function logWarn(msg: string, ...args: unknown[]): void;
+/**
+ * Log an info message.
+ */
+export declare function logInfo(msg: string, ...args: unknown[]): void;
+/**
+ * Log a debug message.
+ */
+export declare function logDebug(msg: string, ...args: unknown[]): void;
+/**
+ * Create a conditional debug logger based on debug flag.
+ */
+export declare function createDebugLogger(enabled: boolean): typeof logDebug;