@auxx/chat 0.0.1

package/dist/client/client/index.d.ts

@@ -0,0 +1,24 @@
+export interface BootOptions {
+    channelId: string;
+    userJwt?: string;
+    attributes?: Record<string, unknown>;
+    apiBase?: string;
+    widgetBase?: string;
+    theme?: 'light' | 'dark' | 'system';
+}
+declare global {
+    interface Window {
+        AuxxChat?: unknown;
+    }
+}
+declare function boot(options: BootOptions): void;
+declare function update(attributes: Record<string, unknown>): void;
+declare function shutdown(): void;
+declare const Auxx: {
+    boot: typeof boot;
+    update: typeof update;
+    shutdown: typeof shutdown;
+};
+export default Auxx;
+export { boot, update, shutdown };
+//# sourceMappingURL=index.d.ts.map

package/dist/client/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAA;CACpC;AAYD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,QAAQ,CAAC,EAAE,OAAO,CAAA;KACnB;CACF;AA0BD,iBAAS,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CA0DxC;AAED,iBAAS,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAOzD;AAED,iBAAS,QAAQ,IAAI,IAAI,CAYxB;AAED,QAAA,MAAM,IAAI;;;;CAA6B,CAAA;AAEvC,eAAe,IAAI,CAAA;AACnB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA"}

package/dist/client/client/index.js

@@ -0,0 +1,127 @@
+// packages/chat/src/client/index.ts
+/**
+ * Browser bootstrap for `@auxx/chat`.
+ *
+ * Wraps the widget bundle that ships in `./widget-bundle` so customers can
+ * install via npm instead of pasting a `<script data-channel-id>` snippet:
+ *
+ *     import Auxx from '@auxx/chat'
+ *     Auxx.boot({ channelId: 'abc', userJwt, attributes: {...} })
+ *     Auxx.update({ plan: 'pro' })
+ *     Auxx.shutdown()
+ *
+ * Defaults to the hosted bundle at `app.auxx.ai/scripts/chat-widget.js`.
+ * Customers self-hosting can pass `widgetBase` (or set `AUXX_WIDGET_URL` at
+ * build time). `apiBase` is propagated to the bundle via
+ * `window.__AUXX_CONFIG__` *before* the script tag is injected, so the same
+ * override chain applies whether the bundle came from our CDN or from
+ * `node_modules`.
+ *
+ * `userJwt` is accepted here but only stored on the bootstrap state — phase 3
+ * wires it through the actual transport layer.
+ */
+import { API_URL, WIDGET_URL } from '../shared/env';
+let state = null;
+function ensureBrowser() {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        throw new Error('@auxx/chat: boot() can only run in a browser environment');
+    }
+}
+function pushAttributes(attributes) {
+    if (!Object.keys(attributes).length)
+        return;
+    const queue = (window.AuxxChat ??= []);
+    if (Array.isArray(queue)) {
+        queue.push(['identify', attributes]);
+    }
+    else {
+        const handle = queue;
+        handle.push?.(['identify', attributes]);
+    }
+    // Mirror onto __AUXX_CONFIG__ so `buildUserDataEnvelope()` can ship the
+    // non-sensitive bag alongside the JWT for phase-4 resolution.
+    const cfg = (window.__AUXX_CONFIG__ ??= {});
+    cfg.attributes = { ...(cfg.attributes ?? {}), ...attributes };
+}
+function boot(options) {
+    ensureBrowser();
+    if (state) {
+        // Same-channel re-boot is a soft refresh: we don't re-inject the script,
+        // but we do roll forward the userJwt (so the React wrapper's reboot-on-
+        // JWT-change effect actually rotates the token) and push any new
+        // attributes through the identify queue.
+        if (state.channelId === options.channelId) {
+            if (options.userJwt !== undefined) {
+                state.userJwt = options.userJwt;
+                const cfg = (window.__AUXX_CONFIG__ ??= {});
+                if (options.userJwt)
+                    cfg.userJwt = options.userJwt;
+                else
+                    delete cfg.userJwt;
+            }
+            if (options.attributes)
+                pushAttributes(options.attributes);
+            return;
+        }
+        shutdown();
+    }
+    const apiBase = options.apiBase ?? API_URL;
+    const widgetBase = options.widgetBase ?? WIDGET_URL;
+    window.__AUXX_CONFIG__ = {
+        ...(window.__AUXX_CONFIG__ ?? {}),
+        apiBase,
+        ...(options.userJwt ? { userJwt: options.userJwt } : {}),
+    };
+    if (options.attributes)
+        pushAttributes(options.attributes);
+    const next = {
+        channelId: options.channelId,
+        apiBase,
+        widgetBase,
+        userJwt: options.userJwt,
+        attributes: options.attributes,
+    };
+    // Reuse an already-loaded bundle if present.
+    const existing = document.querySelector(`script[data-auxx-chat][data-channel-id="${options.channelId}"]`);
+    if (existing) {
+        next.scriptTag = existing;
+        state = next;
+        return;
+    }
+    const tag = document.createElement('script');
+    tag.async = true;
+    tag.dataset.auxxChat = 'true';
+    tag.dataset.channelId = options.channelId;
+    if (options.theme)
+        tag.dataset.theme = options.theme;
+    tag.src = widgetBase;
+    document.head.appendChild(tag);
+    next.scriptTag = tag;
+    state = next;
+}
+function update(attributes) {
+    ensureBrowser();
+    if (!state) {
+        throw new Error('@auxx/chat: update() called before boot()');
+    }
+    state.attributes = { ...(state.attributes ?? {}), ...attributes };
+    pushAttributes(attributes);
+}
+function shutdown() {
+    if (typeof window === 'undefined')
+        return;
+    if (!state)
+        return;
+    state.scriptTag?.remove();
+    // The widget mounts inside a closed shadow DOM under a host element with
+    // a stable id; remove the host so a subsequent boot() starts cold.
+    document.getElementById('auxx-chat-widget-root')?.remove();
+    delete window.__AUXX_CONFIG__;
+    if (window.AuxxChat && !Array.isArray(window.AuxxChat)) {
+        delete window.AuxxChat;
+    }
+    state = null;
+}
+const Auxx = { boot, update, shutdown };
+export default Auxx;
+export { boot, update, shutdown };

package/dist/client/shared/env.d.ts

@@ -0,0 +1,4 @@
+export declare const IS_PROD: boolean;
+export declare const API_URL: string;
+export declare const WIDGET_URL: string;
+//# sourceMappingURL=env.d.ts.map

package/dist/client/shared/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../src/shared/env.ts"],"names":[],"mappings":"AAwBA,eAAO,MAAM,OAAO,SAAuC,CAAA;AAE3D,eAAO,MAAM,OAAO,QACoE,CAAA;AAExF,eAAO,MAAM,UAAU,QAI8B,CAAA"}

package/dist/client/shared/env.js

@@ -0,0 +1,29 @@
+// packages/chat/src/shared/env.ts
+/**
+ * Build-time / runtime defaults for the npm entry points (`client`, `server`,
+ * `react`). The widget *bundle* itself does not consult this file — it reads
+ * `window.__AUXX_CONFIG__` via `shared/runtime-config.ts` and falls back to
+ * the Vite-`define`d `__AUXX_API_BASE_URL__` constant.
+ *
+ * Override priority for hosts using the npm shims:
+ *   1. Explicit `Auxx.boot({ apiBase, widgetBase })` — runtime args win.
+ *   2. Build-time `process.env.AUXX_*` — customer bundler replaces at build.
+ *   3. Built-in defaults below, gated by `AUXX_ENV`.
+ *
+ * Mirrors `packages/sdk/src/env.ts`.
+ */
+function readEnv(key) {
+    if (typeof process === 'undefined' || !process.env)
+        return undefined;
+    const value = process.env[key];
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+export const IS_PROD = readEnv('AUXX_ENV') === 'production';
+export const API_URL = readEnv('AUXX_API_URL') ?? (IS_PROD ? 'https://api.auxx.ai' : 'http://localhost:3007');
+export const WIDGET_URL = readEnv('AUXX_WIDGET_URL') ??
+    (IS_PROD
+        ? 'https://app.auxx.ai/scripts/chat-widget.js'
+        : 'http://localhost:3000/scripts/chat-widget.js');

package/dist/react/client/index.d.ts

@@ -0,0 +1,24 @@
+export interface BootOptions {
+    channelId: string;
+    userJwt?: string;
+    attributes?: Record<string, unknown>;
+    apiBase?: string;
+    widgetBase?: string;
+    theme?: 'light' | 'dark' | 'system';
+}
+declare global {
+    interface Window {
+        AuxxChat?: unknown;
+    }
+}
+declare function boot(options: BootOptions): void;
+declare function update(attributes: Record<string, unknown>): void;
+declare function shutdown(): void;
+declare const Auxx: {
+    boot: typeof boot;
+    update: typeof update;
+    shutdown: typeof shutdown;
+};
+export default Auxx;
+export { boot, update, shutdown };
+//# sourceMappingURL=index.d.ts.map

package/dist/react/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAA;CACpC;AAYD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,QAAQ,CAAC,EAAE,OAAO,CAAA;KACnB;CACF;AA0BD,iBAAS,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CA0DxC;AAED,iBAAS,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAOzD;AAED,iBAAS,QAAQ,IAAI,IAAI,CAYxB;AAED,QAAA,MAAM,IAAI;;;;CAA6B,CAAA;AAEvC,eAAe,IAAI,CAAA;AACnB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA"}

package/dist/react/client/index.js

@@ -0,0 +1,127 @@
+// packages/chat/src/client/index.ts
+/**
+ * Browser bootstrap for `@auxx/chat`.
+ *
+ * Wraps the widget bundle that ships in `./widget-bundle` so customers can
+ * install via npm instead of pasting a `<script data-channel-id>` snippet:
+ *
+ *     import Auxx from '@auxx/chat'
+ *     Auxx.boot({ channelId: 'abc', userJwt, attributes: {...} })
+ *     Auxx.update({ plan: 'pro' })
+ *     Auxx.shutdown()
+ *
+ * Defaults to the hosted bundle at `app.auxx.ai/scripts/chat-widget.js`.
+ * Customers self-hosting can pass `widgetBase` (or set `AUXX_WIDGET_URL` at
+ * build time). `apiBase` is propagated to the bundle via
+ * `window.__AUXX_CONFIG__` *before* the script tag is injected, so the same
+ * override chain applies whether the bundle came from our CDN or from
+ * `node_modules`.
+ *
+ * `userJwt` is accepted here but only stored on the bootstrap state — phase 3
+ * wires it through the actual transport layer.
+ */
+import { API_URL, WIDGET_URL } from '../shared/env';
+let state = null;
+function ensureBrowser() {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        throw new Error('@auxx/chat: boot() can only run in a browser environment');
+    }
+}
+function pushAttributes(attributes) {
+    if (!Object.keys(attributes).length)
+        return;
+    const queue = (window.AuxxChat ??= []);
+    if (Array.isArray(queue)) {
+        queue.push(['identify', attributes]);
+    }
+    else {
+        const handle = queue;
+        handle.push?.(['identify', attributes]);
+    }
+    // Mirror onto __AUXX_CONFIG__ so `buildUserDataEnvelope()` can ship the
+    // non-sensitive bag alongside the JWT for phase-4 resolution.
+    const cfg = (window.__AUXX_CONFIG__ ??= {});
+    cfg.attributes = { ...(cfg.attributes ?? {}), ...attributes };
+}
+function boot(options) {
+    ensureBrowser();
+    if (state) {
+        // Same-channel re-boot is a soft refresh: we don't re-inject the script,
+        // but we do roll forward the userJwt (so the React wrapper's reboot-on-
+        // JWT-change effect actually rotates the token) and push any new
+        // attributes through the identify queue.
+        if (state.channelId === options.channelId) {
+            if (options.userJwt !== undefined) {
+                state.userJwt = options.userJwt;
+                const cfg = (window.__AUXX_CONFIG__ ??= {});
+                if (options.userJwt)
+                    cfg.userJwt = options.userJwt;
+                else
+                    delete cfg.userJwt;
+            }
+            if (options.attributes)
+                pushAttributes(options.attributes);
+            return;
+        }
+        shutdown();
+    }
+    const apiBase = options.apiBase ?? API_URL;
+    const widgetBase = options.widgetBase ?? WIDGET_URL;
+    window.__AUXX_CONFIG__ = {
+        ...(window.__AUXX_CONFIG__ ?? {}),
+        apiBase,
+        ...(options.userJwt ? { userJwt: options.userJwt } : {}),
+    };
+    if (options.attributes)
+        pushAttributes(options.attributes);
+    const next = {
+        channelId: options.channelId,
+        apiBase,
+        widgetBase,
+        userJwt: options.userJwt,
+        attributes: options.attributes,
+    };
+    // Reuse an already-loaded bundle if present.
+    const existing = document.querySelector(`script[data-auxx-chat][data-channel-id="${options.channelId}"]`);
+    if (existing) {
+        next.scriptTag = existing;
+        state = next;
+        return;
+    }
+    const tag = document.createElement('script');
+    tag.async = true;
+    tag.dataset.auxxChat = 'true';
+    tag.dataset.channelId = options.channelId;
+    if (options.theme)
+        tag.dataset.theme = options.theme;
+    tag.src = widgetBase;
+    document.head.appendChild(tag);
+    next.scriptTag = tag;
+    state = next;
+}
+function update(attributes) {
+    ensureBrowser();
+    if (!state) {
+        throw new Error('@auxx/chat: update() called before boot()');
+    }
+    state.attributes = { ...(state.attributes ?? {}), ...attributes };
+    pushAttributes(attributes);
+}
+function shutdown() {
+    if (typeof window === 'undefined')
+        return;
+    if (!state)
+        return;
+    state.scriptTag?.remove();
+    // The widget mounts inside a closed shadow DOM under a host element with
+    // a stable id; remove the host so a subsequent boot() starts cold.
+    document.getElementById('auxx-chat-widget-root')?.remove();
+    delete window.__AUXX_CONFIG__;
+    if (window.AuxxChat && !Array.isArray(window.AuxxChat)) {
+        delete window.AuxxChat;
+    }
+    state = null;
+}
+const Auxx = { boot, update, shutdown };
+export default Auxx;
+export { boot, update, shutdown };

package/dist/react/react/index.d.ts

@@ -0,0 +1,6 @@
+import { type BootOptions } from '../client';
+export interface AuxxChatProps extends BootOptions {
+}
+export declare function AuxxChat(props: AuxxChatProps): null;
+export default AuxxChat;
+//# sourceMappingURL=index.d.ts.map

package/dist/react/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/index.tsx"],"names":[],"mappings":"AAcA,OAAa,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAElD,MAAM,WAAW,aAAc,SAAQ,WAAW;CAAG;AAErD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CA2BnD;AAED,eAAe,QAAQ,CAAA"}

package/dist/react/react/index.js

@@ -0,0 +1,39 @@
+// packages/chat/src/react/index.tsx
+/**
+ * React wrapper for `@auxx/chat`. Renders nothing — runs `Auxx.boot` in an
+ * effect, calls `Auxx.update` when serialized attributes change, and
+ * `Auxx.shutdown` on unmount.
+ *
+ *     <AuxxChat channelId="..." userJwt={token} attributes={{ plan: 'pro' }} />
+ *
+ * Kept on a sub-path import (`@auxx/chat/react`) so React is not pulled into
+ * the non-React bundle.
+ */
+import { useEffect, useRef } from 'react';
+import Auxx, {} from '../client';
+export function AuxxChat(props) {
+    const { channelId, userJwt, attributes, apiBase, widgetBase, theme } = props;
+    // Track whether boot() has run so attribute changes route through update().
+    const bootedRef = useRef(false);
+    useEffect(() => {
+        Auxx.boot({ channelId, userJwt, attributes, apiBase, widgetBase, theme });
+        bootedRef.current = true;
+        return () => {
+            Auxx.shutdown();
+            bootedRef.current = false;
+        };
+        // Reboot whenever the channel / JWT / hosting URLs change. Attribute
+        // changes are handled by the second effect via `update()`.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [channelId, userJwt, apiBase, widgetBase, theme]);
+    // Serialize attributes so reference-only changes don't fire spurious updates.
+    const attributesKey = attributes ? JSON.stringify(attributes) : '';
+    useEffect(() => {
+        if (!bootedRef.current || !attributes)
+            return;
+        Auxx.update(attributes);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [attributesKey]);
+    return null;
+}
+export default AuxxChat;

package/dist/react/shared/env.d.ts

@@ -0,0 +1,4 @@
+export declare const IS_PROD: boolean;
+export declare const API_URL: string;
+export declare const WIDGET_URL: string;
+//# sourceMappingURL=env.d.ts.map

package/dist/react/shared/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../src/shared/env.ts"],"names":[],"mappings":"AAwBA,eAAO,MAAM,OAAO,SAAuC,CAAA;AAE3D,eAAO,MAAM,OAAO,QACoE,CAAA;AAExF,eAAO,MAAM,UAAU,QAI8B,CAAA"}

package/dist/react/shared/env.js

@@ -0,0 +1,29 @@
+// packages/chat/src/shared/env.ts
+/**
+ * Build-time / runtime defaults for the npm entry points (`client`, `server`,
+ * `react`). The widget *bundle* itself does not consult this file — it reads
+ * `window.__AUXX_CONFIG__` via `shared/runtime-config.ts` and falls back to
+ * the Vite-`define`d `__AUXX_API_BASE_URL__` constant.
+ *
+ * Override priority for hosts using the npm shims:
+ *   1. Explicit `Auxx.boot({ apiBase, widgetBase })` — runtime args win.
+ *   2. Build-time `process.env.AUXX_*` — customer bundler replaces at build.
+ *   3. Built-in defaults below, gated by `AUXX_ENV`.
+ *
+ * Mirrors `packages/sdk/src/env.ts`.
+ */
+function readEnv(key) {
+    if (typeof process === 'undefined' || !process.env)
+        return undefined;
+    const value = process.env[key];
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+export const IS_PROD = readEnv('AUXX_ENV') === 'production';
+export const API_URL = readEnv('AUXX_API_URL') ?? (IS_PROD ? 'https://api.auxx.ai' : 'http://localhost:3007');
+export const WIDGET_URL = readEnv('AUXX_WIDGET_URL') ??
+    (IS_PROD
+        ? 'https://app.auxx.ai/scripts/chat-widget.js'
+        : 'http://localhost:3000/scripts/chat-widget.js');

package/dist/server/server/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Node-side helper for signing the user JWT that `@auxx/chat`'s browser
+ * bootstrap accepts via `Auxx.boot({ userJwt })`.
+ *
+ * Customers sign HS256 tokens on their own server using a per-channel secret
+ * stored in our `ApiKey` table (`type='chat'`, `referenceId=channelId`). The
+ * widget forwards the token with every request to `/api/chat/*`; phase 3
+ * wires verification on the server side.
+ *
+ * Default expiry is 1h. Tokens are short-lived; per-request re-verification
+ * catches expiry — no denylist.
+ */
+import { type SignOptions } from 'jsonwebtoken';
+export interface SignUserJwtPayload {
+    /** Stable customer-side user id. Required. */
+    user_id: string;
+    /** Optional identifying attributes — passed through to the contact merge. */
+    email?: string;
+    name?: string;
+    /** Any additional sensitive claims the customer wants protected by JWT. */
+    [key: string]: unknown;
+}
+export interface SignUserJwtOptions {
+    /** JWT lifetime. Accepts seconds (number) or a vercel-ms string. Default `'1h'`. */
+    expiresIn?: SignOptions['expiresIn'];
+}
+export declare function signUserJwt(payload: SignUserJwtPayload, secret: string, options?: SignUserJwtOptions): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/server/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,OAAY,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAEpD,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAA;IACf,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,oFAAoF;IACpF,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CAAA;CACrC;AAED,wBAAgB,WAAW,CACzB,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAWR"}

package/dist/server/server/index.js

@@ -0,0 +1,26 @@
+// packages/chat/src/server/index.ts
+/**
+ * Node-side helper for signing the user JWT that `@auxx/chat`'s browser
+ * bootstrap accepts via `Auxx.boot({ userJwt })`.
+ *
+ * Customers sign HS256 tokens on their own server using a per-channel secret
+ * stored in our `ApiKey` table (`type='chat'`, `referenceId=channelId`). The
+ * widget forwards the token with every request to `/api/chat/*`; phase 3
+ * wires verification on the server side.
+ *
+ * Default expiry is 1h. Tokens are short-lived; per-request re-verification
+ * catches expiry — no denylist.
+ */
+import jwt, {} from 'jsonwebtoken';
+export function signUserJwt(payload, secret, options = {}) {
+    if (!payload || typeof payload.user_id !== 'string' || payload.user_id.length === 0) {
+        throw new Error('signUserJwt: payload.user_id is required');
+    }
+    if (typeof secret !== 'string' || secret.length === 0) {
+        throw new Error('signUserJwt: secret is required');
+    }
+    return jwt.sign(payload, secret, {
+        algorithm: 'HS256',
+        expiresIn: options.expiresIn ?? '1h',
+    });
+}