@paramms/chat-widget 0.1.0 → 1.0.0

package/dist/outbox.d.ts

@@ -0,0 +1,20 @@
+import type { MessageContent } from './protocol/index.js';
+export interface OutboxItem {
+    clientMsgId: string;
+    content: MessageContent;
+    ts: number;
+}
+/** Persists not-yet-acknowledged outgoing messages to localStorage, keyed by
+ *  guest token, so a page reload during a connectivity drop doesn't silently
+ *  lose what the user typed (the "WhatsApp" guarantee: your message is queued
+ *  until it's confirmed sent, even across app restarts). */
+export declare class PersistentOutbox {
+    private readonly key;
+    constructor(token: string);
+    /** All pending items, oldest first, with stale (>7d) entries dropped. */
+    load(): OutboxItem[];
+    add(item: OutboxItem): void;
+    /** Remove an item once it's been acknowledged by the server. */
+    remove(clientMsgId: string): void;
+    private save;
+}

package/dist/protocol/actions.d.ts

@@ -0,0 +1,98 @@
+import type { ActionId, ProfileId, TenantId } from './ids.js';
+export type ActionAudience = 'guest' | 'agent' | 'both';
+export type ActionSurface = 'toolbar' | 'inline' | 'quick_reply';
+export interface ActionInputField {
+    name: string;
+    label: string;
+    type: 'text' | 'number' | 'date' | 'select';
+    required?: boolean;
+    options?: string[];
+}
+export type TerminalEffect = {
+    type: 'webhook';
+    url: string;
+} | {
+    type: 'state_transition';
+    target: 'conversation' | 'subject';
+    toState: string;
+} | {
+    type: 'bot';
+} | {
+    type: 'builtin';
+    name: string;
+};
+export type ActionEffect = TerminalEffect | {
+    type: 'form';
+    fields: ActionInputField[];
+    then: TerminalEffect;
+};
+export type ActionResult = {
+    kind: 'system_message';
+    template?: string;
+} | {
+    kind: 'card';
+} | {
+    kind: 'state_badge';
+} | {
+    kind: 'none';
+};
+export interface ActionDef {
+    id: ActionId;
+    label: string;
+    icon?: string;
+    confirm?: boolean;
+    audience: ActionAudience;
+    surface: ActionSurface;
+    availableInStates?: string[];
+    effect: ActionEffect;
+    result: ActionResult;
+}
+export interface ManifestAction {
+    id: ActionId;
+    label: string;
+    icon?: string;
+    confirm?: boolean;
+    audience: ActionAudience;
+    surface: ActionSurface;
+    availableInStates?: string[];
+    input?: ActionInputField[];
+}
+/** Project an internal action to its client-safe manifest form. */
+export declare function toManifestAction(a: ActionDef): ManifestAction;
+/** Operating hours slot: 0=Sun … 6=Sat, times in "HH:MM" 24h local. */
+export interface OperatingHoursSlot {
+    day: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    open: string;
+    close: string;
+}
+export interface BehaviorProfile {
+    id: ProfileId;
+    tenantId: TenantId;
+    name: string;
+    actions: ActionDef[];
+    defaults: {
+        greeting?: string;
+        theme?: {
+            accent: string;
+        };
+        e2e?: boolean;
+        persona?: string;
+        /** Paid-tier flag: when true, hides the "Powered by Relay" footer in the widget. */
+        whiteLabel?: boolean;
+        /** White-label: serve/embed the widget from this hostname (e.g.
+         *  "chat.acmeco.com"). Allowed automatically as a CORS origin for the
+         *  control-plane API so the widget works from the custom domain. */
+        customDomain?: string;
+    };
+    states: string[];
+    initialState: string;
+    version: number;
+    welcomeMessage?: string;
+    operatingHours?: OperatingHoursSlot[];
+    offlineMessage?: string;
+    /** Base64-encoded ECDSA P-256 SPKI public key. When set, guest tokens must be
+     *  signed JWTs — unsigned opaque tokens are rejected. */
+    guestPublicKey?: string;
+    createdAt: number;
+    updatedAt: number;
+}

package/dist/protocol/codec.d.ts

@@ -0,0 +1,12 @@
+import type { ClientFrame, ServerFrame } from './frames.js';
+export type AnyFrame = ClientFrame | ServerFrame;
+/** True if a decoded frame is one a client is allowed to send. The server uses
+ *  this to reject server-only frame types before dispatch, so a malicious or
+ *  buggy client can't reach an unexpected handler path. */
+export declare function isClientFrame(frame: AnyFrame): frame is ClientFrame;
+/** Encode a frame to a binary msgpack payload for the wire. */
+export declare function encodeFrame(frame: AnyFrame): Uint8Array;
+/** Decode a binary payload into a frame. Returns null on any malformed input or
+ *  anything lacking a string `type`, so a bad frame can never crash the handler
+ *  — the boundary validates `type` before trusting the rest. */
+export declare function decodeFrame(bytes: Uint8Array): AnyFrame | null;

package/dist/protocol/entities.d.ts

@@ -0,0 +1,109 @@
+import type { ConversationId, MessageId, ProfileId, SubjectId, TenantId, UserId } from './ids.js';
+import type { ActionId } from './ids.js';
+export interface CardField {
+    label: string;
+    value: string;
+}
+/** A reference to an action a card/quick-reply can invoke. */
+export interface InlineActionRef {
+    actionId: ActionId;
+    label: string;
+}
+export type MessageContent = {
+    kind: 'text';
+    text: string;
+    enc?: boolean;
+    iv?: string;
+} | {
+    kind: 'attachment';
+    url: string;
+    mime: string;
+    name?: string;
+    size?: number;
+} | {
+    kind: 'card';
+    title?: string;
+    body?: string;
+    fields?: CardField[];
+    actions?: InlineActionRef[];
+} | {
+    kind: 'form';
+    prompt: string;
+    actionId: ActionId;
+} | {
+    kind: 'system';
+    event: string;
+    data?: Record<string, string | number | boolean>;
+} | {
+    kind: 'appointment';
+    title: string;
+    startIso: string;
+    endIso: string;
+    location?: string;
+    description?: string;
+    googleUrl: string;
+    icalUrl: string;
+    confirmed?: boolean;
+};
+export type SenderRole = 'guest' | 'agent' | 'system' | 'bot';
+export interface Message {
+    id: MessageId;
+    conversationId: ConversationId;
+    seq: number;
+    senderId: UserId;
+    senderRole: SenderRole;
+    content: MessageContent;
+    ts: number;
+    replyToId?: MessageId;
+    editedAt?: number;
+    deletedAt?: number;
+    reactions?: Record<string, UserId[]>;
+    internal?: boolean;
+}
+export interface Conversation {
+    id: ConversationId;
+    tenantId: TenantId;
+    profileId: ProfileId;
+    subjectId?: SubjectId;
+    guestId: UserId;
+    participants: UserId[];
+    assignedAgentId?: UserId;
+    aiActive?: boolean;
+    state: string;
+    firstResponseAt?: number;
+    csat?: number;
+    lastSeq: number;
+    tags?: string[];
+    /** Live sentiment of the guest's most recent message (best-effort, async). */
+    sentiment?: 'positive' | 'neutral' | 'frustrated';
+    /** -1 (very frustrated) .. +1 (very positive); paired with `sentiment`. */
+    sentimentScore?: number;
+    /** Set once an SLA-breach escalation macro has fired, so it only fires once. */
+    slaEscalatedAt?: number;
+    /** Page URL where the widget was open when the conversation started. */
+    pageUrl?: string;
+    /** Browser tab title at conversation start — gives agents context. */
+    pageTitle?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface AnnotationPoint {
+    x: number;
+    y: number;
+}
+export interface AnnotationStroke {
+    id: string;
+    points: AnnotationPoint[];
+    color: string;
+    width: number;
+    by: UserId;
+}
+export interface Subject {
+    id: SubjectId;
+    tenantId: TenantId;
+    title: string;
+    state: string;
+    fields: Record<string, string | number | boolean>;
+    createdAt: number;
+    updatedAt: number;
+}

package/dist/protocol/frames.d.ts

@@ -0,0 +1,248 @@
+import type { ConnectionId, ConversationId, MessageId, ProfileId, SubjectId, UserId } from './ids.js';
+import type { Conversation, Message, MessageContent, Subject, AnnotationStroke } from './entities.js';
+import type { ManifestAction } from './actions.js';
+export type ErrorCode = 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'BAD_REQUEST' | 'RATE_LIMITED' | 'PAYLOAD_TOO_LARGE' | 'CONFLICT' | 'INTERNAL';
+export type ClientFrame = {
+    type: 'auth';
+    token: string;
+} | {
+    type: 'open';
+    conversationId?: ConversationId;
+    subjectId?: SubjectId;
+    profileId?: ProfileId;
+    pageUrl?: string;
+    pageTitle?: string;
+} | {
+    type: 'send';
+    conversationId: ConversationId;
+    clientMsgId: string;
+    content: MessageContent;
+    replyToId?: MessageId;
+} | {
+    type: 'sync';
+    conversationId: ConversationId;
+    sinceSeq: number;
+} | {
+    type: 'history';
+    conversationId: ConversationId;
+    beforeSeq: number;
+    limit?: number;
+} | {
+    type: 'read';
+    conversationId: ConversationId;
+    seq: number;
+} | {
+    type: 'typing';
+    conversationId: ConversationId;
+    isTyping: boolean;
+} | {
+    type: 'react';
+    conversationId: ConversationId;
+    messageId: MessageId;
+    emoji: string;
+    remove?: boolean;
+} | {
+    type: 'edit';
+    conversationId: ConversationId;
+    messageId: MessageId;
+    content: MessageContent;
+} | {
+    type: 'delete';
+    conversationId: ConversationId;
+    messageId: MessageId;
+} | {
+    type: 'invoke';
+    conversationId: ConversationId;
+    actionId: string;
+    clientInvokeId: string;
+    inputs?: Record<string, unknown>;
+} | {
+    type: 'assign';
+    conversationId: ConversationId;
+    agentId: UserId | null;
+} | {
+    type: 'tag';
+    conversationId: ConversationId;
+    tag: string;
+    remove?: boolean;
+} | {
+    type: 'note';
+    conversationId: ConversationId;
+    clientMsgId: string;
+    text: string;
+} | {
+    type: 'agent_status';
+    status: 'online' | 'away' | 'offline';
+} | {
+    type: 'annotate';
+    conversationId: ConversationId;
+    stroke: Omit<AnnotationStroke, 'by'>;
+} | {
+    type: 'annotate_clear';
+    conversationId: ConversationId;
+} | {
+    type: 'pubkey';
+    conversationId: ConversationId;
+    key: string;
+} | {
+    type: 'uploadPrekeys';
+    identityKey: string;
+    signedPrekey: string;
+    signedPrekeyId: string;
+    signature: string;
+    oneTimePrekeys: string[];
+} | {
+    type: 'fetchPrekey';
+    targetUserId: UserId;
+} | {
+    type: 'ping';
+};
+export type ServerFrame = {
+    type: 'authed';
+    userId: UserId;
+    connectionId: ConnectionId;
+} | {
+    type: 'opened';
+    conversation: Conversation;
+    subject?: Subject;
+    annotations?: AnnotationStroke[];
+} | {
+    type: 'manifest';
+    conversationId: ConversationId;
+    actions: ManifestAction[];
+    version: number;
+    name?: string;
+    theme?: {
+        accent: string;
+    };
+    e2e?: boolean;
+    offline?: boolean;
+    offlineMessage?: string;
+    whiteLabel?: boolean;
+} | {
+    type: 'message';
+    message: Message;
+} | {
+    type: 'ack';
+    clientMsgId: string;
+    messageId: MessageId;
+    seq: number;
+    ts: number;
+} | {
+    type: 'delivered';
+    conversationId: ConversationId;
+    seq: number;
+    to: UserId;
+} | {
+    type: 'read';
+    conversationId: ConversationId;
+    seq: number;
+    by: UserId;
+} | {
+    type: 'sync';
+    conversationId: ConversationId;
+    messages: Message[];
+} | {
+    type: 'history';
+    conversationId: ConversationId;
+    messages: Message[];
+    hasMore: boolean;
+} | {
+    type: 'typing';
+    conversationId: ConversationId;
+    userId: UserId;
+    isTyping: boolean;
+} | {
+    type: 'reaction';
+    conversationId: ConversationId;
+    messageId: MessageId;
+    emoji: string;
+    by: UserId;
+    removed: boolean;
+} | {
+    type: 'edited';
+    conversationId: ConversationId;
+    messageId: MessageId;
+    content: MessageContent;
+    editedAt: number;
+} | {
+    type: 'deleted';
+    conversationId: ConversationId;
+    messageId: MessageId;
+    ts: number;
+} | {
+    type: 'state';
+    conversationId: ConversationId;
+    state: string;
+} | {
+    type: 'assigned';
+    conversationId: ConversationId;
+    agentId: UserId | null;
+} | {
+    type: 'tagged';
+    conversationId: ConversationId;
+    tag: string;
+    removed: boolean;
+} | {
+    type: 'visitor_count';
+    count: number;
+} | {
+    type: 'agent_status_changed';
+    agentId: UserId;
+    status: 'online' | 'away' | 'offline';
+} | {
+    type: 'sentiment';
+    conversationId: ConversationId;
+    label: 'positive' | 'neutral' | 'frustrated';
+    score: number;
+} | {
+    type: 'annotation';
+    conversationId: ConversationId;
+    stroke: AnnotationStroke;
+} | {
+    type: 'annotation_clear';
+    conversationId: ConversationId;
+    by: UserId;
+} | {
+    type: 'subjectState';
+    subjectId: SubjectId;
+    state: string;
+} | {
+    type: 'presence';
+    conversationId: ConversationId;
+    userId: UserId;
+    status: 'online' | 'offline';
+    lastSeen?: number;
+} | {
+    type: 'invoked';
+    clientInvokeId: string;
+    ok: boolean;
+    error?: string;
+} | {
+    type: 'error';
+    code: ErrorCode;
+    message: string;
+} | {
+    type: 'peerkey';
+    conversationId: ConversationId;
+    userId: UserId;
+    key: string;
+} | {
+    type: 'prekeyBundle';
+    targetUserId: UserId;
+    bundle: {
+        identityKey: string;
+        signedPrekey: string;
+        signedPrekeyId: string;
+        signature: string;
+        oneTimePrekey?: string;
+    } | null;
+} | {
+    type: 'pong';
+};
+/** Limits referenced by both ends so validation stays consistent. */
+export declare const LIMITS: {
+    readonly MAX_TEXT_LEN: 8000;
+    readonly MAX_HISTORY_LIMIT: 100;
+    readonly DEFAULT_HISTORY: 50;
+};

package/dist/protocol/ids.d.ts

@@ -0,0 +1,22 @@
+export type Brand<T, B extends string> = T & {
+    readonly __brand: B;
+};
+export type TenantId = Brand<string, 'TenantId'>;
+export type UserId = Brand<string, 'UserId'>;
+export type ConversationId = Brand<string, 'ConversationId'>;
+export type SubjectId = Brand<string, 'SubjectId'>;
+export type MessageId = Brand<string, 'MessageId'>;
+export type ActionId = Brand<string, 'ActionId'>;
+export type ProfileId = Brand<string, 'ProfileId'>;
+export type ConnectionId = Brand<string, 'ConnectionId'>;
+export declare const asTenantId: (s: string) => TenantId;
+export declare const asUserId: (s: string) => UserId;
+export declare const asConversationId: (s: string) => ConversationId;
+export declare const asSubjectId: (s: string) => SubjectId;
+export declare const asMessageId: (s: string) => MessageId;
+export declare const asActionId: (s: string) => ActionId;
+export declare const asProfileId: (s: string) => ProfileId;
+export declare const asConnectionId: (s: string) => ConnectionId;
+/** Anonymous guests live under this tenant; they bypass cross-tenant scoping but
+ *  are still gated by conversation membership. */
+export declare const ANONYMOUS_TENANT: TenantId;

package/dist/protocol/index.d.ts

@@ -0,0 +1,5 @@
+export * from './ids.js';
+export * from './entities.js';
+export * from './actions.js';
+export * from './frames.js';
+export * from './codec.js';

package/dist/react.d.ts

@@ -0,0 +1,109 @@
+import { type MountOptions } from './index.js';
+interface BaseProps {
+    /** Relay WebSocket URL — set as NEXT_PUBLIC_RELAY_WS_URL in .env — required */
+    url: string;
+    /** Your Relay profile ID — set as NEXT_PUBLIC_RELAY_PROFILE_ID in .env — required */
+    profileId: string;
+    /** Your logged-in user's stable ID. When omitted the widget automatically
+     *  assigns a persistent anonymous ID from localStorage — no login required. */
+    userId?: string;
+    /** Shown to agents instead of the raw user ID */
+    userName?: string;
+    /** Shown to agents so they can follow up by email */
+    userEmail?: string;
+    /** Avatar URL shown in the widget header and dashboard */
+    userAvatar?: string;
+    /** Brand colour hex, e.g. "#1a56db". Defaults to the profile theme colour. */
+    accent?: string;
+    /** Render as a floating launcher button instead of inline */
+    launcher?: boolean;
+    /** Launcher position — default 'bottom-right' */
+    position?: 'bottom-right' | 'bottom-left';
+    /** Pre-set reply chips shown above the input */
+    quickReplies?: string[];
+    /** Container height when rendered inline. Default: '100%' */
+    height?: string;
+    /** i18n string overrides for non-English sites */
+    i18n?: MountOptions['i18n'];
+    /** ISO language code for auto-translating incoming messages */
+    translateLang?: string;
+}
+export interface ChatWidgetProps extends BaseProps {
+    /** Optional context card shown at the top of the chat
+     *  (e.g. the support ticket, booking, or order being discussed) */
+    contextTitle?: string;
+    contextSubtitle?: string;
+    contextStatus?: string;
+    /** Show the WhatsApp-style thread list as the home screen.
+     *  Use when users can have more than one thread on this profile
+     *  (e.g. one thread per support ticket, one per booking). */
+    showChatList?: boolean;
+    /** Stable item ID — pins this conversation to a specific item/thread.
+     *  When showChatList is also true, the widget opens this thread immediately
+     *  but the user can navigate back to the full list. */
+    subjectId?: string;
+}
+/**
+ * General-purpose support chat widget. Only `url` and `profileId` are required.
+ * All other props are optional — anonymous guests work without any configuration.
+ *
+ * @example Basic support chat
+ * ```tsx
+ * <ChatWidget
+ *   url={process.env.NEXT_PUBLIC_RELAY_WS_URL}
+ *   profileId={process.env.NEXT_PUBLIC_RELAY_PROFILE_ID}
+ *   userId={session?.user.id}
+ *   userName={session?.user.name}
+ *   userEmail={session?.user.email}
+ * />
+ * ```
+ *
+ * @example Multi-thread (tickets, bookings, orders)
+ * ```tsx
+ * <ChatWidget
+ *   url={...} profileId={...}
+ *   showChatList
+ *   subjectId={`ticket_${ticket.id}`}
+ *   contextTitle={ticket.title}
+ *   contextStatus={ticket.status}
+ *   userId={session?.user.id}
+ * />
+ * ```
+ */
+export declare function ChatWidget({ url, profileId, userId, userName, userEmail, userAvatar, contextTitle, contextSubtitle, contextStatus, showChatList, subjectId, accent, launcher, position, quickReplies, height, i18n, translateLang, }: ChatWidgetProps): JSX.Element;
+export interface MarketplaceChatProps extends BaseProps {
+    /** Unique ID for this listing — each listing gets its own thread.
+     *  Omit for a general (non-item-specific) conversation. */
+    listingId?: string;
+    /** Shown at the top of the chat — e.g. "2019 Toyota Camry SE" */
+    listingTitle?: string;
+    /** One-line detail — e.g. "45,000 km · Automatic" */
+    listingMeta?: string;
+    /** Price shown as a tag — e.g. 12500 → "$12,500" */
+    listingPrice?: number;
+    /** Status badge — e.g. "Available", "Sold", "Pending" */
+    listingStatus?: string;
+}
+/**
+ * Marketplace chat — one thread per listing, guests can switch between all
+ * their active threads via a WhatsApp-style list. Only `url` and `profileId`
+ * are required. All other props are optional.
+ *
+ * @example Used car listing
+ * ```tsx
+ * <MarketplaceChat
+ *   url={process.env.NEXT_PUBLIC_RELAY_WS_URL}
+ *   profileId={process.env.NEXT_PUBLIC_RELAY_PROFILE_ID}
+ *   listingId={car.id}
+ *   listingTitle={car.title}
+ *   listingPrice={car.price}
+ *   listingMeta={`${car.mileage.toLocaleString()} km · ${car.transmission}`}
+ *   listingStatus="Available"
+ *   userId={session?.user.id}
+ *   userName={session?.user.name}
+ *   userEmail={session?.user.email}
+ * />
+ * ```
+ */
+export declare function MarketplaceChat({ url, profileId, listingId, listingTitle, listingMeta, listingPrice, listingStatus, userId, userName, userEmail, userAvatar, accent, launcher, position, quickReplies, height, i18n, translateLang, }: MarketplaceChatProps): JSX.Element;
+export {};