@dolard.eu/versiq-core-types 0.1.0

package/LICENSE

@@ -0,0 +1,48 @@
+Versiq Core Types — Commercial Source-available License
+========================================================
+
+Copyright (c) 2024-2026 Sébastien Dolard
+
+This package ships TypeScript type contracts and Zod schemas consumed by the
+Versiq Widget SDK. It is published under the same license as the widget
+bundle so that TypeScript integrators get a working type tree when they
+install `@dolard.eu/versiq-widget`.
+
+1. Permitted use
+   You may, without separate written agreement:
+   (a) Install this package as a transitive dependency of
+       `@dolard.eu/versiq-widget` via standard package managers.
+   (b) Import the exported types and Zod schemas in client-side or
+       server-side code that interoperates with the Versiq backend API.
+
+2. Prohibited without prior written agreement
+   You may not, in whole or in part:
+   (a) Modify, fork, or create derivative works for redistribution under
+       any name.
+   (b) Redistribute the package, or any derivative, under a different
+       package name, namespace, or scope.
+   (c) Use these contracts to design or implement a competing widget SDK,
+       qualification backend, or conversation orchestration product.
+   (d) Remove, alter, or obscure copyright notices, attribution, or this
+       license file from any copy.
+
+3. Production use
+   Use of the corresponding Versiq backend in production is subject to the
+   Versiq Commercial Terms of Service. The license granted here is for the
+   type contracts only; it does not authorize backend access.
+
+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/dist/application-config.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Application bootstrap config returned by `GET /api/application/config`.
+ *
+ * The app (`apps/app`) produces this response through a stricter server-side
+ * whitelist schema (`publicApplicationConfigSchema` in the route), and the
+ * widget (`@dolard.eu/versiq-widget`) consumes it here. Keeping the widget-side Zod
+ * schema as the canonical shape prevents drift — the server schema MUST remain
+ * a compatible subset (it may be stricter, never more permissive).
+ */
+import { z } from "zod";
+export declare const applicationConfigResponseSchema: z.ZodObject<{
+    applicationId: z.ZodString;
+    applicationSlug: z.ZodString;
+    applicationName: z.ZodString;
+    vertical: z.ZodString;
+    theme: z.ZodNullable<z.ZodObject<{
+        primaryColor: z.ZodOptional<z.ZodString>;
+        backgroundColor: z.ZodOptional<z.ZodString>;
+        textColor: z.ZodOptional<z.ZodString>;
+        borderRadius: z.ZodOptional<z.ZodNumber>;
+        fontFamily: z.ZodOptional<z.ZodString>;
+        colorScheme: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+            auto: "auto";
+        }>>;
+    }, z.core.$strip>>;
+    allowedOrigins: z.ZodArray<z.ZodString>;
+    monitoring: z.ZodBoolean;
+    primaryObjective: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        label: z.ZodString;
+        ctaLabel: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    identityVerificationRequired: z.ZodBoolean;
+    widget: z.ZodNullable<z.ZodObject<{
+        theme: z.ZodOptional<z.ZodObject<{
+            primaryColor: z.ZodOptional<z.ZodString>;
+            backgroundColor: z.ZodOptional<z.ZodString>;
+            textColor: z.ZodOptional<z.ZodString>;
+            borderRadius: z.ZodOptional<z.ZodNumber>;
+            fontFamily: z.ZodOptional<z.ZodString>;
+            colorScheme: z.ZodOptional<z.ZodEnum<{
+                light: "light";
+                dark: "dark";
+                auto: "auto";
+            }>>;
+        }, z.core.$strip>>;
+        position: z.ZodOptional<z.ZodEnum<{
+            "bottom-right": "bottom-right";
+            "bottom-left": "bottom-left";
+            inline: "inline";
+        }>>;
+        language: z.ZodOptional<z.ZodString>;
+        showProfile: z.ZodOptional<z.ZodBoolean>;
+        open: z.ZodOptional<z.ZodBoolean>;
+        brand: z.ZodOptional<z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            avatarUrl: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+export type ApplicationConfigResponse = z.infer<typeof applicationConfigResponseSchema>;

package/dist/application-config.js

@@ -0,0 +1,45 @@
+/**
+ * Application bootstrap config returned by `GET /api/application/config`.
+ *
+ * The app (`apps/app`) produces this response through a stricter server-side
+ * whitelist schema (`publicApplicationConfigSchema` in the route), and the
+ * widget (`@dolard.eu/versiq-widget`) consumes it here. Keeping the widget-side Zod
+ * schema as the canonical shape prevents drift — the server schema MUST remain
+ * a compatible subset (it may be stricter, never more permissive).
+ */
+import { z } from "zod";
+import { themeConfigSchema } from "./theme";
+import { widgetRuntimeConfigSchema } from "./widget-runtime-config";
+export const applicationConfigResponseSchema = z.object({
+    applicationId: z.string().uuid().describe("Application UUID"),
+    applicationSlug: z
+        .string()
+        .max(100)
+        .describe("Application slug (kebab-case)"),
+    applicationName: z.string().max(200).describe("Application display name"),
+    vertical: z
+        .string()
+        .max(50)
+        .describe("Vertical resolved from Application config"),
+    theme: themeConfigSchema.nullable().describe("Application theme"),
+    allowedOrigins: z
+        .array(z.string().max(200))
+        .max(50)
+        .describe("Allowed origins for this application"),
+    monitoring: z.boolean().describe("Monitoring enabled flag"),
+    primaryObjective: z
+        .object({
+        id: z.string().uuid(),
+        type: z.string(),
+        label: z.string(),
+        ctaLabel: z.string().nullable(),
+    })
+        .nullable()
+        .describe("Primary conversion objective"),
+    identityVerificationRequired: z
+        .boolean()
+        .describe("Whether HMAC identity verification is required"),
+    widget: widgetRuntimeConfigSchema
+        .nullable()
+        .describe("Admin-configured widget runtime config (theme, position, language, showProfile, open). Null when the application has not yet persisted a widget_config JSONB."),
+});

package/dist/geo.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Geographic cross-boundary type contracts.
+ *
+ * Cross-boundary contract shared by the geo package (`@versiq/geo`) and the
+ * app host (`apps/app`). Previously co-located in `apps/app/src/lib/ai/schemas/`
+ * by historical happenstance — directions cardinales are not AI-specific, they
+ * are pure geographic primitives.
+ */
+import { z } from "zod";
+/**
+ * Cardinal directions for directional zone search (e.g., "nord de Lyon").
+ * Uses English keys for LLM consistency, mapped to French for display.
+ */
+export declare const cardinalDirectionEnum: z.ZodEnum<{
+    north: "north";
+    northeast: "northeast";
+    east: "east";
+    southeast: "southeast";
+    south: "south";
+    southwest: "southwest";
+    west: "west";
+    northwest: "northwest";
+}>;
+export type CardinalDirection = z.infer<typeof cardinalDirectionEnum>;

package/dist/geo.js

@@ -0,0 +1,25 @@
+/**
+ * Geographic cross-boundary type contracts.
+ *
+ * Cross-boundary contract shared by the geo package (`@versiq/geo`) and the
+ * app host (`apps/app`). Previously co-located in `apps/app/src/lib/ai/schemas/`
+ * by historical happenstance — directions cardinales are not AI-specific, they
+ * are pure geographic primitives.
+ */
+import { z } from "zod";
+/**
+ * Cardinal directions for directional zone search (e.g., "nord de Lyon").
+ * Uses English keys for LLM consistency, mapped to French for display.
+ */
+export const cardinalDirectionEnum = z
+    .enum([
+    "north",
+    "northeast",
+    "east",
+    "southeast",
+    "south",
+    "southwest",
+    "west",
+    "northwest",
+])
+    .describe("Direction cardinale (north/south/east/west + combinaisons)");

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @dolard.eu/versiq-core-types
+ *
+ * Cross-workspace type contracts shared by `apps/app`, `apps/marketing` and
+ * `packages/widget`. Scope is intentionally narrow (ADR-006): only types that
+ * cross a workspace boundary live here. Do NOT dump domain-specific schemas
+ * in this package — keep them in the consumer that owns the domain.
+ *
+ * See `docs/adr/ADR-006-monorepo-package-strategy.md`.
+ */
+export * from "./theme";
+export * from "./theme-resolver";
+export * from "./viewport";
+export * from "./widget-config";
+export * from "./widget-runtime-config";
+export * from "./application-config";
+export * from "./postmessage";
+export * from "./geo";

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @dolard.eu/versiq-core-types
+ *
+ * Cross-workspace type contracts shared by `apps/app`, `apps/marketing` and
+ * `packages/widget`. Scope is intentionally narrow (ADR-006): only types that
+ * cross a workspace boundary live here. Do NOT dump domain-specific schemas
+ * in this package — keep them in the consumer that owns the domain.
+ *
+ * See `docs/adr/ADR-006-monorepo-package-strategy.md`.
+ */
+export * from "./theme";
+export * from "./theme-resolver";
+export * from "./viewport";
+export * from "./widget-config";
+export * from "./widget-runtime-config";
+export * from "./application-config";
+export * from "./postmessage";
+export * from "./geo";

package/dist/postmessage.d.ts

@@ -0,0 +1,137 @@
+/**
+ * postMessage protocol between the widget iframe and its host page.
+ *
+ * Two directions share the `versiq:*` prefix:
+ *   - `WidgetCommand` — parent page → iframe (commands)
+ *   - `WidgetEvent`   — iframe → parent page (events)
+ *
+ * The `MESSAGE_TYPES` const aggregates every message type string across both
+ * directions. Consumers that treat the protocol opaquely (e.g. origin
+ * validation helpers) can rely on it to check `type.startsWith("versiq:")`
+ * without enumerating every member.
+ */
+import { z } from "zod";
+import { themeConfigSchema, type ThemeConfig } from "./theme";
+import { viewportModeSchema, type ViewportMode } from "./viewport";
+import { widgetConfigSchema, type WidgetConfig } from "./widget-config";
+export declare const messageRoleSchema: z.ZodEnum<{
+    user: "user";
+    assistant: "assistant";
+}>;
+export type MessageRole = z.infer<typeof messageRoleSchema>;
+export declare const widgetMessageSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        user: "user";
+        assistant: "assistant";
+    }>;
+    content: z.ZodString;
+}, z.core.$strip>;
+export type WidgetMessage = z.infer<typeof widgetMessageSchema>;
+/**
+ * Generic widget profile emitted across postMessage boundaries.
+ * The concrete shape depends on the vertical (`BuyerProfile` for real-estate,
+ * `B2BProfile` for b2b-qualification, etc.) — we intentionally keep the
+ * cross-boundary contract structural so verticals can evolve independently.
+ */
+export type WidgetProfile = Record<string, unknown>;
+/**
+ * Exhaustive catalogue of every `versiq:*` message type used in either
+ * direction. Kept as a single const so a new event or command is declared in
+ * one place.
+ */
+export declare const MESSAGE_TYPES: {
+    readonly INIT: "versiq:init";
+    readonly OPEN: "versiq:open";
+    readonly CLOSE: "versiq:close";
+    readonly RESET: "versiq:reset";
+    readonly SET_THEME: "versiq:setTheme";
+    readonly VIEWPORT: "versiq:viewport";
+    readonly IDENTIFY: "versiq:identify";
+    readonly READY: "versiq:ready";
+    readonly PROFILE_UPDATE: "versiq:profile-update";
+    readonly MESSAGE: "versiq:message";
+    readonly QUALIFIED: "versiq:qualified";
+    readonly ERROR: "versiq:error";
+    readonly QUOTA_WARNING: "versiq:quota-warning";
+    readonly QUOTA_EXCEEDED: "versiq:quota-exceeded";
+    readonly FUNNEL_STAGE_CHANGE: "versiq:funnel-stage-change";
+    readonly CTA_SHOWN: "versiq:cta-shown";
+    readonly CTA_CLICKED: "versiq:cta-clicked";
+    readonly LEAD_CAPTURED: "versiq:lead-captured";
+    readonly IDENTITY_VERIFIED: "versiq:identity-verified";
+};
+export type MessageType = (typeof MESSAGE_TYPES)[keyof typeof MESSAGE_TYPES];
+export type WidgetCommand = {
+    type: typeof MESSAGE_TYPES.INIT;
+    config: WidgetConfig;
+} | {
+    type: typeof MESSAGE_TYPES.OPEN;
+} | {
+    type: typeof MESSAGE_TYPES.CLOSE;
+} | {
+    type: typeof MESSAGE_TYPES.RESET;
+} | {
+    type: typeof MESSAGE_TYPES.SET_THEME;
+    theme: ThemeConfig;
+} | {
+    type: typeof MESSAGE_TYPES.VIEWPORT;
+    mode: ViewportMode;
+} | {
+    type: typeof MESSAGE_TYPES.IDENTIFY;
+    email: string;
+    userId?: string;
+    userHash: string;
+};
+export type WidgetEvent = {
+    type: typeof MESSAGE_TYPES.READY;
+} | {
+    type: typeof MESSAGE_TYPES.PROFILE_UPDATE;
+    profile: WidgetProfile;
+} | {
+    type: typeof MESSAGE_TYPES.MESSAGE;
+    message: WidgetMessage;
+} | {
+    type: typeof MESSAGE_TYPES.QUALIFIED;
+    profile: WidgetProfile;
+    score: number;
+} | {
+    type: typeof MESSAGE_TYPES.ERROR;
+    code: string;
+    message: string;
+} | {
+    type: typeof MESSAGE_TYPES.OPEN;
+} | {
+    type: typeof MESSAGE_TYPES.CLOSE;
+} | {
+    type: typeof MESSAGE_TYPES.QUOTA_WARNING;
+    remaining: number;
+    limit: number;
+} | {
+    type: typeof MESSAGE_TYPES.QUOTA_EXCEEDED;
+} | {
+    type: typeof MESSAGE_TYPES.FUNNEL_STAGE_CHANGE;
+    stage: string;
+    previousStage: string | null;
+} | {
+    type: typeof MESSAGE_TYPES.CTA_SHOWN;
+    ctaType: string;
+    objectiveId?: string;
+} | {
+    type: typeof MESSAGE_TYPES.CTA_CLICKED;
+    ctaType: string;
+    objectiveId?: string;
+} | {
+    type: typeof MESSAGE_TYPES.LEAD_CAPTURED;
+    hasEmail: boolean;
+    hasPhone: boolean;
+} | {
+    type: typeof MESSAGE_TYPES.IDENTITY_VERIFIED;
+    email: string;
+    userId?: string;
+};
+/**
+ * Short keys (no `versiq:` prefix) used by the widget public API (on/off).
+ */
+export type WidgetEventType = "ready" | "profile-update" | "message" | "qualified" | "error" | "open" | "close" | "quota-warning" | "quota-exceeded" | "funnel-stage-change" | "cta-shown" | "cta-clicked" | "lead-captured" | "identity-verified";
+export type WidgetEventHandler<T = unknown> = (data: T) => void;
+export { themeConfigSchema, viewportModeSchema, widgetConfigSchema };

package/dist/postmessage.js

@@ -0,0 +1,63 @@
+/**
+ * postMessage protocol between the widget iframe and its host page.
+ *
+ * Two directions share the `versiq:*` prefix:
+ *   - `WidgetCommand` — parent page → iframe (commands)
+ *   - `WidgetEvent`   — iframe → parent page (events)
+ *
+ * The `MESSAGE_TYPES` const aggregates every message type string across both
+ * directions. Consumers that treat the protocol opaquely (e.g. origin
+ * validation helpers) can rely on it to check `type.startsWith("versiq:")`
+ * without enumerating every member.
+ */
+import { z } from "zod";
+import { themeConfigSchema } from "./theme";
+import { viewportModeSchema } from "./viewport";
+import { widgetConfigSchema } from "./widget-config";
+// ============================================================================
+// Message primitives
+// ============================================================================
+export const messageRoleSchema = z
+    .enum(["user", "assistant"])
+    .describe("Message sender role");
+export const widgetMessageSchema = z.object({
+    role: messageRoleSchema.describe("Message sender role"),
+    content: z
+        .string()
+        .max(10000)
+        .describe("Message content (max 10000 characters)"),
+});
+// ============================================================================
+// Message type catalogue
+// ============================================================================
+/**
+ * Exhaustive catalogue of every `versiq:*` message type used in either
+ * direction. Kept as a single const so a new event or command is declared in
+ * one place.
+ */
+export const MESSAGE_TYPES = {
+    // Parent → iframe (commands)
+    INIT: "versiq:init",
+    OPEN: "versiq:open",
+    CLOSE: "versiq:close",
+    RESET: "versiq:reset",
+    SET_THEME: "versiq:setTheme",
+    VIEWPORT: "versiq:viewport",
+    IDENTIFY: "versiq:identify",
+    // iframe → parent (events)
+    READY: "versiq:ready",
+    PROFILE_UPDATE: "versiq:profile-update",
+    MESSAGE: "versiq:message",
+    QUALIFIED: "versiq:qualified",
+    ERROR: "versiq:error",
+    QUOTA_WARNING: "versiq:quota-warning",
+    QUOTA_EXCEEDED: "versiq:quota-exceeded",
+    FUNNEL_STAGE_CHANGE: "versiq:funnel-stage-change",
+    CTA_SHOWN: "versiq:cta-shown",
+    CTA_CLICKED: "versiq:cta-clicked",
+    LEAD_CAPTURED: "versiq:lead-captured",
+    IDENTITY_VERIFIED: "versiq:identity-verified",
+};
+// Re-export schemas that participate in the protocol for consumers that want
+// runtime validation (e.g. widget bootstrap parsing a `WidgetConfig`).
+export { themeConfigSchema, viewportModeSchema, widgetConfigSchema };

package/dist/theme-resolver.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Theme resolver — single source of truth for `ThemeConfig` → CSS-ready values.
+ *
+ * Pure function consumed by:
+ *  - `apps/app/src/app/widget/embed/EmbedChat.tsx` (iframe runtime)
+ *  - `apps/app/src/components/portal/sandbox/WidgetMockPreview.tsx` (admin preview)
+ *
+ * Before this module existed, the same resolution rules were duplicated across
+ * the two call sites (cf. audit `tmp/widget-customization-review.md` § 3.4 —
+ * fuite n° 3 of the verdict "abstraction qui ne tient pas sa promesse"). Any
+ * evolution had to be mirrored by hand, with no compiler check. The function
+ * here is the contract; both callers MUST consume it.
+ *
+ * Dark-mode policy:
+ *   `backgroundColor` and `textColor` admin-side hex overrides apply in
+ *   LIGHT MODE ONLY. The widget's `colorScheme: "dark"` token flips surface
+ *   tokens via the `.dark` CSS class on the iframe root — forcing a saved
+ *   "#FFFFFF" through dark mode would defeat the toggle and yield a
+ *   white-on-white outcome on the visitor's site. When `isDark` is true,
+ *   those two fields fall back to the resolver's `defaults` (typically CSS
+ *   variables that respond to `.dark`).
+ *
+ *   `primaryColor` is brand-side and applies in both schemes: the assistant
+ *   bubble and the launcher button must stay the brand colour even on a
+ *   dark surface.
+ */
+import type { ThemeConfig } from "./theme";
+/**
+ * Caller-supplied fallback palette. Each consumer (runtime, preview) passes
+ * the same constant — that is what guarantees alignment by construction. The
+ * test contract (`theme-resolver.test.ts`) asserts identical output for
+ * identical input across callers.
+ */
+export interface ThemeDefaults {
+    /** Brand colour applied to launcher + user bubble. Used in BOTH schemes. */
+    primaryColor: string;
+    /** Background applied to the widget surface. Used only when `isDark === false`. */
+    backgroundColor: string;
+    /** Foreground text colour. Used only when `isDark === false`. */
+    textColor: string;
+    /** Default radius (in pixels) used when `theme.borderRadius == null`. */
+    borderRadiusPx: number;
+    /** Default font stack used when `theme.fontFamily == null`. */
+    fontFamily: string;
+}
+export interface ResolvedTheme {
+    primaryColor: string;
+    backgroundColor: string;
+    textColor: string;
+    /** CSS string ready to apply (e.g. `"16px"`). */
+    borderRadius: string;
+    fontFamily: string;
+}
+export declare function resolveTheme(theme: ThemeConfig | null | undefined, isDark: boolean, defaults: ThemeDefaults): ResolvedTheme;

package/dist/theme-resolver.js

@@ -0,0 +1,40 @@
+/**
+ * Theme resolver — single source of truth for `ThemeConfig` → CSS-ready values.
+ *
+ * Pure function consumed by:
+ *  - `apps/app/src/app/widget/embed/EmbedChat.tsx` (iframe runtime)
+ *  - `apps/app/src/components/portal/sandbox/WidgetMockPreview.tsx` (admin preview)
+ *
+ * Before this module existed, the same resolution rules were duplicated across
+ * the two call sites (cf. audit `tmp/widget-customization-review.md` § 3.4 —
+ * fuite n° 3 of the verdict "abstraction qui ne tient pas sa promesse"). Any
+ * evolution had to be mirrored by hand, with no compiler check. The function
+ * here is the contract; both callers MUST consume it.
+ *
+ * Dark-mode policy:
+ *   `backgroundColor` and `textColor` admin-side hex overrides apply in
+ *   LIGHT MODE ONLY. The widget's `colorScheme: "dark"` token flips surface
+ *   tokens via the `.dark` CSS class on the iframe root — forcing a saved
+ *   "#FFFFFF" through dark mode would defeat the toggle and yield a
+ *   white-on-white outcome on the visitor's site. When `isDark` is true,
+ *   those two fields fall back to the resolver's `defaults` (typically CSS
+ *   variables that respond to `.dark`).
+ *
+ *   `primaryColor` is brand-side and applies in both schemes: the assistant
+ *   bubble and the launcher button must stay the brand colour even on a
+ *   dark surface.
+ */
+export function resolveTheme(theme, isDark, defaults) {
+    const primaryColor = theme?.primaryColor ?? defaults.primaryColor;
+    const backgroundColor = isDark
+        ? defaults.backgroundColor
+        : (theme?.backgroundColor ?? defaults.backgroundColor);
+    const textColor = isDark
+        ? defaults.textColor
+        : (theme?.textColor ?? defaults.textColor);
+    const borderRadius = theme?.borderRadius != null
+        ? `${theme.borderRadius}px`
+        : `${defaults.borderRadiusPx}px`;
+    const fontFamily = theme?.fontFamily ?? defaults.fontFamily;
+    return { primaryColor, backgroundColor, textColor, borderRadius, fontFamily };
+}

package/dist/theme.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Theme configuration schema for customizing widget appearance.
+ *
+ * Cross-boundary contract shared by the widget SDK (`@dolard.eu/versiq-widget`) and the
+ * app host (`apps/app`). Both workspaces historically redefined the same
+ * fields — this module is the single source of truth.
+ */
+import { z } from "zod";
+export declare const themeConfigSchema: z.ZodObject<{
+    primaryColor: z.ZodOptional<z.ZodString>;
+    backgroundColor: z.ZodOptional<z.ZodString>;
+    textColor: z.ZodOptional<z.ZodString>;
+    borderRadius: z.ZodOptional<z.ZodNumber>;
+    fontFamily: z.ZodOptional<z.ZodString>;
+    colorScheme: z.ZodOptional<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+        auto: "auto";
+    }>>;
+}, z.core.$strip>;
+export type ThemeConfig = z.infer<typeof themeConfigSchema>;
+export type ColorScheme = NonNullable<ThemeConfig["colorScheme"]>;

package/dist/theme.js

@@ -0,0 +1,39 @@
+/**
+ * Theme configuration schema for customizing widget appearance.
+ *
+ * Cross-boundary contract shared by the widget SDK (`@dolard.eu/versiq-widget`) and the
+ * app host (`apps/app`). Both workspaces historically redefined the same
+ * fields — this module is the single source of truth.
+ */
+import { z } from "zod";
+// 6-digit hex color (e.g. "#3B82F6"). Lower or upper case accepted.
+// `max(20)` is kept on top of the regex as a belt-and-braces guard against
+// pre-validation length attacks even if the regex were ever loosened.
+const HEX_COLOR_REGEX = /^#[0-9a-fA-F]{6}$/;
+const HEX_COLOR_MESSAGE = "Color must be a 6-digit hex code (e.g. '#3B82F6'). Short hex, rgb(), and named colors are not supported.";
+export const themeConfigSchema = z.object({
+    primaryColor: z
+        .string()
+        .max(20)
+        .regex(HEX_COLOR_REGEX, HEX_COLOR_MESSAGE)
+        .describe("Primary brand color (hex format, e.g., '#3B82F6')")
+        .optional(),
+    backgroundColor: z
+        .string()
+        .max(20)
+        .regex(HEX_COLOR_REGEX, HEX_COLOR_MESSAGE)
+        .describe("Background color for the widget container")
+        .optional(),
+    textColor: z
+        .string()
+        .max(20)
+        .regex(HEX_COLOR_REGEX, HEX_COLOR_MESSAGE)
+        .describe("Text color")
+        .optional(),
+    borderRadius: z.number().describe("Border radius in pixels").optional(),
+    fontFamily: z.string().max(100).describe("Font family").optional(),
+    colorScheme: z
+        .enum(["light", "dark", "auto"])
+        .describe("Widget color scheme: 'light' (default), 'dark', or 'auto' (follows the visitor's prefers-color-scheme).")
+        .optional(),
+});

package/dist/viewport.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Viewport, breakpoints, responsive and position contracts for the widget.
+ *
+ * Cross-boundary contract shared by `@dolard.eu/versiq-widget` (runtime enforcement) and
+ * `apps/app` (sandbox preview, embed layout).
+ */
+import { z } from "zod";
+export declare const viewportModeSchema: z.ZodEnum<{
+    mobile: "mobile";
+    tablet: "tablet";
+    desktop: "desktop";
+}>;
+export type ViewportMode = z.infer<typeof viewportModeSchema>;
+export declare const widgetPositionSchema: z.ZodEnum<{
+    "bottom-right": "bottom-right";
+    "bottom-left": "bottom-left";
+    inline: "inline";
+}>;
+export type WidgetPosition = z.infer<typeof widgetPositionSchema>;
+export declare const breakpointsConfigSchema: z.ZodObject<{
+    mobile: z.ZodOptional<z.ZodNumber>;
+    tablet: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type BreakpointsConfig = z.infer<typeof breakpointsConfigSchema>;
+export declare const responsiveConfigSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    breakpoints: z.ZodOptional<z.ZodObject<{
+        mobile: z.ZodOptional<z.ZodNumber>;
+        tablet: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ResponsiveConfig = z.infer<typeof responsiveConfigSchema>;

package/dist/viewport.js

@@ -0,0 +1,36 @@
+/**
+ * Viewport, breakpoints, responsive and position contracts for the widget.
+ *
+ * Cross-boundary contract shared by `@dolard.eu/versiq-widget` (runtime enforcement) and
+ * `apps/app` (sandbox preview, embed layout).
+ */
+import { z } from "zod";
+export const viewportModeSchema = z
+    .enum(["mobile", "tablet", "desktop"])
+    .describe("Viewport mode: mobile (<480px), tablet (480-768px), desktop (>768px)");
+export const widgetPositionSchema = z
+    .enum(["bottom-right", "bottom-left", "inline"])
+    .describe("Widget position on the page");
+export const breakpointsConfigSchema = z.object({
+    mobile: z
+        .number()
+        .min(0)
+        .max(1000)
+        .describe("Max width for mobile viewport (default: 480)")
+        .optional(),
+    tablet: z
+        .number()
+        .min(0)
+        .max(2000)
+        .describe("Max width for tablet viewport (default: 768)")
+        .optional(),
+});
+export const responsiveConfigSchema = z.object({
+    enabled: z
+        .boolean()
+        .describe("Enable responsive behavior (default: true)")
+        .optional(),
+    breakpoints: breakpointsConfigSchema
+        .describe("Custom breakpoint values")
+        .optional(),
+});

package/dist/widget-config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Full widget configuration contract.
+ *
+ * Consumed by `@dolard.eu/versiq-widget` (config parsing and iframe bootstrap) and by
+ * `apps/app` sandbox/preview components via `@dolard.eu/versiq-widget`'s re-export.
+ */
+import { z } from "zod";
+export declare const widgetConfigSchema: z.ZodObject<{
+    theme: z.ZodOptional<z.ZodObject<{
+        primaryColor: z.ZodOptional<z.ZodString>;
+        backgroundColor: z.ZodOptional<z.ZodString>;
+        textColor: z.ZodOptional<z.ZodString>;
+        borderRadius: z.ZodOptional<z.ZodNumber>;
+        fontFamily: z.ZodOptional<z.ZodString>;
+        colorScheme: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+            auto: "auto";
+        }>>;
+    }, z.core.$strip>>;
+    position: z.ZodOptional<z.ZodEnum<{
+        "bottom-right": "bottom-right";
+        "bottom-left": "bottom-left";
+        inline: "inline";
+    }>>;
+    open: z.ZodOptional<z.ZodBoolean>;
+    container: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<HTMLElement, HTMLElement>, z.ZodString]>>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    debug: z.ZodOptional<z.ZodBoolean>;
+    responsive: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        breakpoints: z.ZodOptional<z.ZodObject<{
+            mobile: z.ZodOptional<z.ZodNumber>;
+            tablet: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    showProfile: z.ZodOptional<z.ZodBoolean>;
+    language: z.ZodOptional<z.ZodString>;
+    apiKey: z.ZodString;
+    email: z.ZodOptional<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+    userHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WidgetConfig = z.infer<typeof widgetConfigSchema>;

package/dist/widget-config.js

@@ -0,0 +1,62 @@
+/**
+ * Full widget configuration contract.
+ *
+ * Consumed by `@dolard.eu/versiq-widget` (config parsing and iframe bootstrap) and by
+ * `apps/app` sandbox/preview components via `@dolard.eu/versiq-widget`'s re-export.
+ */
+import { z } from "zod";
+import { themeConfigSchema } from "./theme";
+import { responsiveConfigSchema, widgetPositionSchema } from "./viewport";
+export const widgetConfigSchema = z.object({
+    theme: themeConfigSchema.describe("Custom theme configuration").optional(),
+    position: widgetPositionSchema
+        .describe("Widget position (default: 'bottom-right')")
+        .optional(),
+    open: z.boolean().describe("Initial open state (default: false)").optional(),
+    container: z
+        .union([
+        z.custom((val) => val instanceof HTMLElement),
+        z.string().max(200),
+    ])
+        .describe("Container element for inline mode")
+        .optional(),
+    baseUrl: z
+        .string()
+        .url()
+        .max(200)
+        .describe("Base URL for the widget embed (default: production URL)")
+        .optional(),
+    debug: z.boolean().describe("Enable debug logging").optional(),
+    responsive: responsiveConfigSchema
+        .describe("Responsive behavior configuration")
+        .optional(),
+    showProfile: z
+        .boolean()
+        .describe("Show profile panel in widget header (default: false)")
+        .optional(),
+    language: z
+        .string()
+        .max(10)
+        .describe("Language for UI labels (e.g., 'fr', 'en'). Defaults to browser language.")
+        .optional(),
+    apiKey: z
+        .string()
+        .max(100)
+        .describe("Publishable API key (pk_*) for application authentication"),
+    email: z
+        .string()
+        .email()
+        .max(255)
+        .describe("Pre-identified user email (host-attested identity)")
+        .optional(),
+    userId: z
+        .string()
+        .max(255)
+        .describe("Host-side unique user identifier")
+        .optional(),
+    userHash: z
+        .string()
+        .max(128)
+        .describe("HMAC-SHA256 of email (or userId), signed with identity secret")
+        .optional(),
+});

package/dist/widget-runtime-config.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Widget runtime config — server-authoritative, admin-editable.
+ *
+ * This schema defines what the admin portal can edit for a given Application
+ * and what the widget SDK receives at bootstrap via `GET /api/application/config`.
+ * It is deliberately disjoint from `widgetConfigSchema` (which contains the
+ * host-context attributes `apiKey`/`container`/`baseUrl`/`debug`/identity
+ * fields that can only live on the integrator's page).
+ *
+ * Single source of truth consumed by:
+ *  - `apps/app` admin route handlers (Zod second-gate on response + PUT body)
+ *  - `apps/app` portal widget editor (form schema)
+ *  - `packages/widget` config resolver (server-wins merge policy)
+ *
+ * Storage: `applications.widget_config` JSONB column. Cache-invalidated on
+ * update via `invalidateKeyCacheForApplication`.
+ *
+ * Part of #726 — unifying widget config so the integration reduces to
+ * `<script data-api-key="pk_live_…"></script>`.
+ */
+import { z } from "zod";
+export declare const widgetRuntimeConfigSchema: z.ZodObject<{
+    theme: z.ZodOptional<z.ZodObject<{
+        primaryColor: z.ZodOptional<z.ZodString>;
+        backgroundColor: z.ZodOptional<z.ZodString>;
+        textColor: z.ZodOptional<z.ZodString>;
+        borderRadius: z.ZodOptional<z.ZodNumber>;
+        fontFamily: z.ZodOptional<z.ZodString>;
+        colorScheme: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+            auto: "auto";
+        }>>;
+    }, z.core.$strip>>;
+    position: z.ZodOptional<z.ZodEnum<{
+        "bottom-right": "bottom-right";
+        "bottom-left": "bottom-left";
+        inline: "inline";
+    }>>;
+    language: z.ZodOptional<z.ZodString>;
+    showProfile: z.ZodOptional<z.ZodBoolean>;
+    open: z.ZodOptional<z.ZodBoolean>;
+    brand: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        avatarUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type WidgetRuntimeConfig = z.infer<typeof widgetRuntimeConfigSchema>;

package/dist/widget-runtime-config.js

@@ -0,0 +1,63 @@
+/**
+ * Widget runtime config — server-authoritative, admin-editable.
+ *
+ * This schema defines what the admin portal can edit for a given Application
+ * and what the widget SDK receives at bootstrap via `GET /api/application/config`.
+ * It is deliberately disjoint from `widgetConfigSchema` (which contains the
+ * host-context attributes `apiKey`/`container`/`baseUrl`/`debug`/identity
+ * fields that can only live on the integrator's page).
+ *
+ * Single source of truth consumed by:
+ *  - `apps/app` admin route handlers (Zod second-gate on response + PUT body)
+ *  - `apps/app` portal widget editor (form schema)
+ *  - `packages/widget` config resolver (server-wins merge policy)
+ *
+ * Storage: `applications.widget_config` JSONB column. Cache-invalidated on
+ * update via `invalidateKeyCacheForApplication`.
+ *
+ * Part of #726 — unifying widget config so the integration reduces to
+ * `<script data-api-key="pk_live_…"></script>`.
+ */
+import { z } from "zod";
+import { themeConfigSchema } from "./theme";
+import { widgetPositionSchema } from "./viewport";
+export const widgetRuntimeConfigSchema = z
+    .object({
+    theme: themeConfigSchema
+        .describe("Full visual theme palette applied by the widget. Admin-configured, no client-side override.")
+        .optional(),
+    position: widgetPositionSchema
+        .describe("Default launcher position. `inline` only applies when integrator supplies `data-container`.")
+        .optional(),
+    language: z
+        .string()
+        .max(10)
+        .describe("Locale forced for widget UI labels (ISO 639-1). Falls back to browser language when null.")
+        .optional(),
+    showProfile: z
+        .boolean()
+        .describe("Whether the widget header exposes the profile panel to end-users.")
+        .optional(),
+    open: z
+        .boolean()
+        .describe("Default open state on load. Host can still call `window.Versiq.open()` programmatically.")
+        .optional(),
+    brand: z
+        .object({
+        title: z
+            .string()
+            .max(60)
+            .describe("Custom widget header title. Falls back to a vertical-specific default (e.g. 'Versiq Chat' for B2B) when unset.")
+            .optional(),
+        avatarUrl: z
+            .string()
+            .url()
+            .max(2048)
+            .describe("Public URL of the custom widget avatar (PNG or JPEG). MUST originate from the branding-upload endpoint — arbitrary external URLs are rejected at the API boundary.")
+            .optional(),
+    })
+        .strict()
+        .describe("White-label branding overrides (issue #1083 Piste 5). Both fields are optional.")
+        .optional(),
+})
+    .strict();

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@dolard.eu/versiq-core-types",
+  "version": "0.1.0",
+  "description": "Cross-workspace TypeScript contracts and Zod schemas consumed by @dolard.eu/versiq-widget. Intended as a peer of the widget SDK.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Sébastien Dolard <admin@dolard.eu>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sdolard/Toize.git",
+    "directory": "packages/core-types"
+  },
+  "homepage": "https://github.com/sdolard/Toize/tree/main/packages/core-types#readme",
+  "bugs": {
+    "url": "https://github.com/sdolard/Toize/issues"
+  },
+  "keywords": [
+    "versiq",
+    "widget",
+    "types",
+    "zod",
+    "schemas",
+    "sdk"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "pnpm clean && tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit",
+    "typecheck:ci": "pnpm typecheck"
+  }
+}