@paramms/chat-widget 0.1.0 → 1.0.0

package/README.md

@@ -1,23 +1,149 @@
 # @paramms/chat-widget
 
-Embeddable guest chat client. Pure `ChatStore` (state) + `ConnectionManager`
-(ws/reconnect/outbox/cursor) + thin `Renderer`, wired by `mount()`.
+Real-time embeddable chat widget for the Relay platform. Drop into any website with a single script tag — no build step required.
 
-`src/protocol/` is a vendored copy of the wire contract (only what the widget uses).
+## Install
 
-## Run
 ```bash
-npm install
-npm run dev           # Vite demo at http://localhost:5173/ (expects the server on ws://localhost:3000)
-npm run build         # tsc → dist/ (library: importable by the dashboard)
-npm run build:bundle  # vite → standalone browser bundle
-npm test              # vitest (store, connection, jsdom render)
+npm install @paramms/chat-widget
 ```
 
-## Embed
+## Quick start — CDN (no npm, no build)
+
 ```html
+<div id="chat"></div>
 <script type="module">
-  import { mount } from '@paramms/chat-widget'
-  mount({ el: document.getElementById('chat'), url: 'wss://your-host', profileId: 'p_hotel', subjectId: 'room-101' })
+  import { mount } from 'https://relay.paramms.com/index.js'
+  mount({
+    el:        document.getElementById('chat'),
+    url:       'wss://api.paramms.com/ws',
+    profileId: 'YOUR_PROFILE_ID',
+  })
 </script>
 ```
+
+## React / Next.js
+
+```tsx
+'use client'
+import { ChatWidget } from '@paramms/chat-widget/react'
+
+export default function SupportChat() {
+  return (
+    <ChatWidget
+      url="wss://api.paramms.com/ws"
+      profileId="YOUR_PROFILE_ID"
+    />
+  )
+}
+```
+
+## Identified users (no separate login needed)
+
+Pass your own user's ID as the token and their details via `user`. Anonymous users work without any configuration.
+
+```tsx
+<ChatWidget
+  url="wss://api.paramms.com/ws"
+  profileId="YOUR_PROFILE_ID"
+  token={currentUser.id}          // your own stable user ID — ties history across devices
+  user={{
+    name:   currentUser.name,     // shown to agents instead of opaque ID
+    email:  currentUser.email,    // agents can follow up even after disconnect
+    avatar: currentUser.avatarUrl,
+    meta: {
+      plan:      currentUser.plan,
+      accountId: currentUser.id,
+    },
+  }}
+/>
+```
+
+## Cryptographically verified identity (Tier 4)
+
+For marketplaces and financial services — the guest's identity is verified against your ECDSA key so it cannot be spoofed.
+
+```tsx
+// 1. Generate a key pair (once, server-side)
+//    openssl ecparam -genkey -name prime256v1 -noout | openssl pkcs8 -topk8 -nocrypt -out private.pem
+//    openssl ec -in private.pem -pubout | base64 -w0  → paste in Dashboard → Domain → Guest identity linking
+
+// 2. Sign a token per user (your backend)
+import { createSign } from 'node:crypto'
+const hdr = Buffer.from(JSON.stringify({ alg: 'ES256', typ: 'JWT' })).toString('base64url')
+const pay = Buffer.from(JSON.stringify({ sub: userId, iat: Math.floor(Date.now() / 1000), exp: Math.floor(Date.now() / 1000) + 3600 })).toString('base64url')
+const sig = createSign('SHA256').update(`${hdr}.${pay}`).sign(privateKey, 'base64url')
+const signedToken = `${hdr}.${pay}.${sig}`
+
+// 3. Pass to widget — server verifies the signature automatically
+<ChatWidget url="..." profileId="..." token={signedToken} />
+```
+
+## Marketplace / multi-item (one thread per listing)
+
+```tsx
+<ChatWidget
+  url="wss://api.paramms.com/ws"
+  profileId="YOUR_PROFILE_ID"
+  subjectId={`car_${listing.id}`}   // one conversation per item
+  showChatList={true}                // guest can switch between their threads
+/>
+```
+
+## Launcher (floating button)
+
+```tsx
+<ChatWidget
+  url="wss://api.paramms.com/ws"
+  profileId="YOUR_PROFILE_ID"
+  launcher={true}
+  position="bottom-right"
+  accent="#4F63F5"
+/>
+```
+
+## Internationalisation
+
+```tsx
+<ChatWidget
+  url="wss://api.paramms.com/ws"
+  profileId="YOUR_PROFILE_ID"
+  i18n={{
+    placeholder: 'Écrivez un message…',
+    send:        'Envoyer',
+    offline:     'Nous sommes hors ligne pour l\'instant',
+    poweredBy:   '',   // empty string hides the footer
+  }}
+/>
+```
+
+RTL is detected automatically for Arabic, Hebrew, Persian and Urdu browsers.
+
+## All options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `el` | `HTMLElement` | required | Mount target |
+| `url` | `string` | required | WebSocket URL (`wss://...`) |
+| `profileId` | `string` | required | Domain profile ID |
+| `token` | `string` | auto-generated | Guest identity token — pass your user's stable ID to tie history across devices |
+| `user` | `UserInfo` | — | Name, email, avatar, custom metadata — shown to agents |
+| `subjectId` | `string` | — | Item ID for marketplace mode |
+| `showChatList` | `boolean` | `false` | Show conversation switcher in header |
+| `accent` | `string` | `#f5713c` | Brand colour (hex) |
+| `launcher` | `boolean` | `false` | Render as floating button |
+| `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Launcher position |
+| `translateLang` | `string` | — | Auto-translate incoming messages (ISO language code) |
+| `quickReplies` | `string[]` | — | Pre-set reply chips shown above input |
+| `i18n` | `I18nStrings` | English | UI string overrides |
+
+## Development
+
+```bash
+npm install
+npm run dev          # Vite preview at http://localhost:5174/
+npm run build        # tsc → dist/
+npm run build:bundle # Vite → standalone CDN bundle
+npm test             # 75 tests via vitest
+npm run typecheck
+```

package/dist/connection.d.ts

@@ -0,0 +1,48 @@
+import { type ClientFrame, type ServerFrame } from './protocol/index.js';
+export interface SocketLike {
+    binaryType: string;
+    send(data: Uint8Array): void;
+    close(): void;
+    onopen: (() => void) | null;
+    onclose: (() => void) | null;
+    onerror: (() => void) | null;
+    onmessage: ((ev: {
+        data: ArrayBuffer;
+    }) => void) | null;
+}
+export type SocketFactory = (url: string) => SocketLike;
+export interface ConnectionOptions {
+    url: string;
+    token: string;
+    open: Extract<ClientFrame, {
+        type: 'open';
+    }>;
+    onFrame: (frame: ServerFrame) => void;
+    getCursor: () => number;
+    onStatusChange?: (status: 'connecting' | 'open' | 'reconnecting') => void;
+    socketFactory?: SocketFactory;
+    backoffBaseMs?: number;
+    backoffMaxMs?: number;
+    maxOutbox?: number;
+}
+export declare class ConnectionManager {
+    private readonly opts;
+    private socket;
+    private state;
+    private authed;
+    private attempt;
+    private outbox;
+    private stopped;
+    private timer;
+    constructor(opts: ConnectionOptions);
+    connect(): void;
+    /** Queue a frame; sent immediately if open, else flushed on (re)connect.
+     *  The outbox is bounded so a prolonged outage can't grow memory without limit
+     *  — oldest queued frames are dropped past the cap. */
+    send(frame: ClientFrame): void;
+    close(): void;
+    private handle;
+    private flush;
+    private raw;
+    private onClosed;
+}

package/dist/crypto.d.ts

@@ -0,0 +1,69 @@
+/**
+ * End-to-end encryption primitives (Web Crypto): ECDH P-256 for key agreement
+ * + AES-GCM for message content. The server only ever relays public keys and
+ * stores ciphertext — it cannot read messages.
+ *
+ * Scope/limitations (honest): this secures a *live 1:1* session — the guest and
+ * one agent exchange public keys while both are connected, then messages between
+ * them are encrypted. True asynchronous E2E (encrypting to an offline party)
+ * needs a prekey/X3DH scheme, which is out of scope here. When E2E is on, the
+ * AI assistant cannot read the room (by design).
+ */
+export interface KeyPair {
+    publicKey: CryptoKey;
+    privateKey: CryptoKey;
+}
+export declare function generateKeyPair(): Promise<KeyPair>;
+/** Export a public key to a compact base64 string (raw, 65 bytes for P-256). */
+export declare function exportPublicKey(key: CryptoKey): Promise<string>;
+/** Derive the shared AES-GCM key from our private key + the peer's public key. */
+export declare function deriveSharedKey(privateKey: CryptoKey, peerPublicKeyB64: string): Promise<CryptoKey>;
+export interface Ciphertext {
+    ct: string;
+    iv: string;
+}
+export declare function encrypt(key: CryptoKey, plaintext: string): Promise<Ciphertext>;
+export declare function decrypt(key: CryptoKey, ct: string, iv: string): Promise<string>;
+/** Persist/restore our keypair across reloads (so prior ciphertext stays readable). */
+export declare function loadOrCreateKeyPair(storageKey: string): Promise<KeyPair>;
+/** Sign a prekey public key bytes using ECDSA P-256 SHA-256.
+ *  The signingKey must be an ECDSA P-256 private key (not ECDH).
+ *  In the full X3DH setup the identity key pair contains both an ECDH key
+ *  (for DH) and an ECDSA key (for signing). We keep them separate here. */
+export declare function signPrekey(signingPrivateKey: CryptoKey, spkPublicKey: CryptoKey): Promise<string>;
+/** Verify an SPK signature. verifyPublicKey must be an ECDSA P-256 public key. */
+export declare function verifyPrekeySignature(verifyPublicKeyB64: string, spkPublicKeyB64: string, signatureB64: string): Promise<boolean>;
+/** A full identity keypair for X3DH: ECDH key for DH computations + ECDSA key
+ *  for signing prekeys. The two key objects share the same P-256 curve but have
+ *  different usages, so Web Crypto treats them separately. */
+export interface IdentityKeyPair {
+    ecdhKP: KeyPair;
+    ecdsaKP: {
+        publicKey: CryptoKey;
+        privateKey: CryptoKey;
+    };
+    /** The ECDH public key exported as base64 — used as the X3DH identity key. */
+    publicKeyB64: string;
+    /** The ECDSA public key exported as base64 — used for SPK signature verification. */
+    sigPublicKeyB64: string;
+}
+/** Generate a full X3DH identity keypair (ECDH + ECDSA on the same P-256 curve). */
+export declare function generateIdentityKeyPair(): Promise<IdentityKeyPair>;
+/** Load or generate an identity keypair, persisting both components. */
+export declare function loadOrCreateIdentityKeyPair(storageKey: string): Promise<IdentityKeyPair>;
+export interface X3DHBundle {
+    identityKey: string;
+    signedPrekey: string;
+    signedPrekeyId: string;
+    signature: string;
+    oneTimePrekey?: string;
+}
+/** X3DH sender side: derive a shared key from the recipient's prekey bundle.
+ *  Returns the shared AES-GCM key and the ephemeral public key to transmit. */
+export declare function x3dhSend(senderIK: KeyPair, recipientBundle: X3DHBundle): Promise<{
+    sharedKey: CryptoKey;
+    ephemeralPublicKey: string;
+}>;
+/** X3DH recipient side: rederive the shared key from an init message.
+ *  Returns the shared AES-GCM key. */
+export declare function x3dhReceive(recipientIK: KeyPair, recipientSPK: KeyPair, senderIKb64: string, ephemeralKeyB64: string, recipientOPK?: KeyPair): Promise<CryptoKey>;

package/dist/e2e.d.ts

@@ -0,0 +1,75 @@
+import type { MessageContent, UserId } from './protocol/index.js';
+import type { ServerFrame } from './protocol/index.js';
+import { type X3DHBundle } from './crypto.js';
+/**
+ * Per-user E2E session. Supports two modes:
+ *
+ * LIVE (original): Both parties are online. ECDH P-256 key exchange via the
+ * `pubkey`/`peerkey` frames. Instant but requires both parties to be connected.
+ *
+ * ASYNC (X3DH): The sender encrypts to the recipient's prekey bundle while the
+ * recipient is offline. Uses X3DH (Extended Triple DH) with identity keys,
+ * signed prekeys, and one-time prekeys. The recipient derives the same shared
+ * key from the init message when they come online.
+ *
+ * Both modes produce an AES-GCM 256 shared key for message encryption.
+ */
+export declare class E2ESession {
+    private readonly storageKey;
+    private kp?;
+    private shared?;
+    private identityKP;
+    private signedPreKP;
+    private signedPrekeyId;
+    private readonly otpKeys;
+    private x3dhShared?;
+    private pendingX3DH;
+    constructor(storageKey: string);
+    get ready(): boolean;
+    /** Live ECDH mode: Generate/restore our keypair and return our public key to publish. */
+    begin(): Promise<string>;
+    /** Live ECDH mode: A peer published their key — derive the shared secret. */
+    onPeerKey(peerKeyB64: string): Promise<void>;
+    /** X3DH: Generate identity key, signed prekey, and OTP prekeys.
+     *  Returns the upload frame payload the caller should send to the server. */
+    initX3DH(): Promise<{
+        identityKey: string;
+        signedPrekey: string;
+        signedPrekeyId: string;
+        signature: string;
+        oneTimePrekeys: string[];
+    }>;
+    /** X3DH sender: given a recipient's prekey bundle, derive the shared key and
+     *  return the init message fields to embed in the first encrypted message. */
+    x3dhSendTo(bundle: X3DHBundle): Promise<{
+        ephemeralKey: string;
+        spkId: string;
+        usedOTP: boolean;
+        senderIK: string;
+    }>;
+    /** X3DH recipient: given an init message's sender IK + EK + SPK ID, derive the shared key. */
+    x3dhReceiveFrom(senderIKb64: string, ephemeralKeyB64: string, spkId: string): Promise<void>;
+    /** Flush pending X3DH derivation after initX3DH() completes. */
+    flushPendingX3DH(): Promise<void>;
+    /** Encrypt outgoing text into a wire content object. For X3DH init messages,
+     *  the caller should pass x3dhInit fields to embed in the content. */
+    sealText(text: string, x3dhInit?: {
+        ephemeralKey: string;
+        spkId: string;
+        senderIK: string;
+    }): Promise<MessageContent>;
+    /** Decrypt one content object if it is encrypted (otherwise pass through). */
+    private openContent;
+    /** Decrypt any encrypted message content carried by an incoming frame, in place. */
+    openFrame(frame: ServerFrame): Promise<void>;
+}
+/** X3DH init fields embedded in a text MessageContent (as extra properties).
+ *  Present only on the very first message from a sender to an offline peer. */
+export interface X3DHInitFields {
+    x3dhEK: string;
+    x3dhSPK: string;
+    x3dhIK: string;
+}
+export declare function extractX3DHInit(content: MessageContent): X3DHInitFields | null;
+export { type X3DHBundle } from './crypto.js';
+export { type UserId };

package/dist/history.d.ts

@@ -0,0 +1,14 @@
+import type { ChatStore } from './store.js';
+import type { ConversationId } from './protocol/index.js';
+import type { Renderer } from './renderer.js';
+/** Derive the HTTP(S) base origin from a ws(s):// URL. */
+export declare function httpBaseFromWsUrl(wsUrl: string): string;
+/** Initial history restore on conversation open.
+ *
+ *  Fetches the latest PAGE messages and sets up scroll-triggered loading for
+ *  older messages via IntersectionObserver on a sentinel at the top of the
+ *  scroll container. No buttons — scrolling up loads more automatically.
+ *
+ *  Returns a cleanup function — call it when the conversation is closed to
+ *  disconnect the observer and prevent stale updates. */
+export declare function restoreHistory(wsUrl: string, token: string, conversationId: ConversationId, store: ChatStore, renderer: Renderer): Promise<void>;

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+import { asConversationId } from './protocol/index.js';
+import { type WidgetConfig } from './renderer.js';
+export interface UserInfo {
+    /** Display name shown in the conversation (e.g. "Sarah Chen"). */
+    name?: string;
+    /** Email address — passed as conversation metadata for agent context. */
+    email?: string;
+    /** Avatar URL — shown as the guest's avatar in both widget and dashboard. */
+    avatar?: string;
+    /** Any custom key/value metadata to attach to the conversation
+     *  (e.g. plan tier, account ID, page URL). Shown to agents in the sidebar. */
+    meta?: Record<string, string>;
+}
+export interface MountOptions {
+    el: HTMLElement;
+    url: string;
+    profileId: string;
+    subjectId?: string;
+    token?: string;
+    subject?: WidgetConfig['subject'];
+    quickReplies?: string[];
+    accent?: string;
+    /** If set, shows a 🌐 translate button on incoming messages that translates
+     *  them into this language (ISO code or language name) via the server's
+     *  /translate endpoint. Omit to disable the feature. */
+    translateLang?: string;
+    /** If true, mount as a floating launcher button that opens/closes the chat */
+    launcher?: boolean;
+    /** Position of the launcher button: default 'bottom-right' */
+    position?: 'bottom-right' | 'bottom-left';
+    /** If true, shows a 💬 button in the header that opens a list of the
+     *  guest's other conversations (e.g. a marketplace where each item gets
+     *  its own subjectId/thread) and lets them switch between them.
+     *  Off by default — single-conversation embeds don't need this. */
+    showChatList?: boolean;
+    /** Optional user info for identified users. When provided, the name/email/
+     *  avatar are shown to agents in the dashboard instead of the anonymous ID.
+     *  The token still controls identity — this is display metadata only.
+     *  Anonymous users (no token, no user) remain fully anonymous. */
+    user?: UserInfo;
+    /** i18n: override UI strings. All keys are optional — omitted keys fall
+     *  back to English defaults. */
+    i18n?: {
+        placeholder?: string;
+        send?: string;
+        offline?: string;
+        poweredBy?: string;
+    };
+}
+export interface WidgetHandle {
+    close(): void;
+}
+export declare function mount(opts: MountOptions): WidgetHandle;
+export { ChatStore } from './store.js';
+export { ConnectionManager } from './connection.js';
+export { Renderer, type ChatListEntry } from './renderer.js';
+export { asConversationId };
+export { E2ESession, extractX3DHInit, type X3DHBundle } from './e2e.js';
+export { PersistentOutbox, type OutboxItem } from './outbox.js';
+export { restoreHistory, httpBaseFromWsUrl } from './history.js';