@paramms/chat-widget 0.1.0

package/src/protocol/actions.ts

@@ -0,0 +1,114 @@
+import type { ActionId, ProfileId, TenantId } from './ids.js'
+
+// ── Actions: the product primitive ────────────────────────────────────────────
+// An action is data an admin authors in the dashboard; the runtime stays generic
+// and only knows how to execute a small, fixed set of EFFECTS. Adding "make
+// offer" or "schedule meeting" is a config row, not a code deploy.
+
+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[]            // for type: 'select'
+}
+
+// A terminal effect produces a result and ends the action. Actions are
+// single-shot: structured multi-step lives in the conversation state machine,
+// and conversational multi-step is the `bot` effect — not an action workflow.
+export type TerminalEffect =
+  | { type: 'webhook';          url: string }                                  // signed POST to tenant system
+  | { type: 'state_transition'; target: 'conversation' | 'subject'; toState: string }
+  | { type: 'bot' }                                                            // route to the AI resolver
+  | { type: 'builtin';          name: string }                                 // e.g. 'handoff'
+
+// The ONLY composition allowed is "collect a form, then run one terminal
+// effect" — exactly one level deep. This covers input-gathering (e.g. an offer
+// amount) without becoming a workflow engine.
+export type ActionEffect =
+  | TerminalEffect
+  | { type: 'form'; fields: ActionInputField[]; then: TerminalEffect }
+
+export type ActionResult =
+  | { kind: 'system_message'; template?: string }   // post a system line into the chat
+  | { kind: 'card' }                                 // render the effect's response as a card
+  | { kind: 'state_badge' }                          // reflect a state change
+  | { kind: 'none' }
+
+export interface ActionDef {
+  id:                ActionId
+  label:             string
+  icon?:             string
+  confirm?:          boolean
+  audience:          ActionAudience
+  surface:           ActionSurface
+  availableInStates?: string[]    // conversation/subject states; omit = always available
+  effect:            ActionEffect
+  result:            ActionResult
+}
+
+// Client-safe projection of an action: enough for the widget to render it and
+// collect inputs, but NONE of the effect internals (webhook URLs, transition
+// targets) — those stay server-side and execute on `invoke`. The client filters
+// by `availableInStates` locally against the current conversation state, so a
+// state change needs no manifest round-trip; the server re-validates on invoke.
+export interface ManifestAction {
+  id:                ActionId
+  label:             string
+  icon?:             string
+  confirm?:          boolean
+  audience:          ActionAudience
+  surface:           ActionSurface
+  availableInStates?: string[]
+  input?:            ActionInputField[]   // present when the action collects input (form effect)
+}
+
+/** Project an internal action to its client-safe manifest form. */
+export function toManifestAction(a: ActionDef): ManifestAction {
+  const input = a.effect.type === 'form' ? a.effect.fields : undefined
+  return {
+    id: a.id, label: a.label, audience: a.audience, surface: a.surface,
+    ...(a.icon ? { icon: a.icon } : {}),
+    ...(a.confirm ? { confirm: a.confirm } : {}),
+    ...(a.availableInStates ? { availableInStates: a.availableInStates } : {}),
+    ...(input ? { input } : {}),
+  }
+}
+
+// ── Behavior profile (what "domain" becomes) ──────────────────────────────────
+// A reusable, admin-composed bundle of actions + defaults + state machine. Not a
+// built-in taxonomy — the 7 old templates become starter presets of this shape.
+// `version` lets an in-flight invocation validate against a consistent snapshot.
+
+/** 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               // first message guests see when opening the widget
+  operatingHours?:  OperatingHoursSlot[] // empty/absent = always open
+  offlineMessage?:  string               // shown outside operating hours instead of chat
+  createdAt:    number
+  updatedAt:    number
+}

package/src/protocol/codec.ts

@@ -0,0 +1,35 @@
+import { encode as mpEncode, decode as mpDecode } from '@msgpack/msgpack'
+import type { ClientFrame, ServerFrame } from './frames.js'
+
+export type AnyFrame = ClientFrame | ServerFrame
+
+const CLIENT_FRAME_TYPES: ReadonlySet<ClientFrame['type']> = new Set([
+  'auth', 'open', 'send', 'sync', 'history', 'read', 'typing', 'react', 'edit', 'delete', 'invoke', 'pubkey', 'ping', 'annotate', 'annotate_clear',
+])
+
+/** 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 function isClientFrame(frame: AnyFrame): frame is ClientFrame {
+  return CLIENT_FRAME_TYPES.has(frame.type as ClientFrame['type'])
+}
+
+/** Encode a frame to a binary msgpack payload for the wire. */
+export function encodeFrame(frame: AnyFrame): Uint8Array {
+  return mpEncode(frame)
+}
+
+/** 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 function decodeFrame(bytes: Uint8Array): AnyFrame | null {
+  let value: unknown
+  try {
+    value = mpDecode(bytes)
+  } catch {
+    return null
+  }
+  if (typeof value !== 'object' || value === null) return null
+  if (typeof (value as { type?: unknown }).type !== 'string') return null
+  return value as AnyFrame
+}

package/src/protocol/entities.ts

@@ -0,0 +1,104 @@
+import type {
+  ConversationId, MessageId, ProfileId, SubjectId, TenantId, UserId,
+} from './ids.js'
+import type { ActionId } from './ids.js'
+
+// ── Message content (discriminated union) ─────────────────────────────────────
+// The runtime stays generic by never hard-coding business content: a message is
+// one of a small, fixed set of shapes. `card`/`form`/`system` are how action
+// results and structured prompts render — they subsume most "rich messaging"
+// features without a per-feature content zoo.
+
+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'
+
+// ── Message ───────────────────────────────────────────────────────────────────
+// Ordering is by `seq` (server-assigned, monotonic per conversation), never by
+// `ts`. `ts` is wall-clock for display only. This kills the reorder/duplicate/
+// lost-on-reconnect class of bugs that millisecond-timestamp ordering caused.
+
+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   // true = internal note, only visible to agents
+}
+
+// ── Conversation (the room; messages partition by conversationId) ─────────────
+// The room is the conversation, NOT the subject. Two guests discussing the same
+// subject get two conversations. `subjectId` is a nullable reference, never part
+// of the room identity — so "one thread per (guest, subject)" is enforced as
+// app logic at open-time, and many-threads-per-subject stays possible for free.
+
+export interface Conversation {
+  id:              ConversationId
+  tenantId:        TenantId
+  profileId:       ProfileId            // behavior profile → which actions this room has
+  subjectId?:      SubjectId            // optional: the thing it's about
+  guestId:         UserId               // the end-user
+  participants:    UserId[]             // guest + any assigned agents (membership = authz)
+  assignedAgentId?: UserId              // routing/ownership
+  aiActive?:       boolean              // staff assigned the AI to answer this room
+  state:           string               // conversation state-machine state
+  firstResponseAt?: number              // first agent reply ts (SLA)
+  csat?:           number               // satisfaction score 1–5 (set on resolution)
+  lastSeq:         number               // highest seq assigned in this conversation
+  tags?:           string[]             // macro/manual tags (e.g. "refund", "vip")
+  /** 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
+  createdAt:       number
+  updatedAt:       number
+}
+
+// ── Co-browsing / shared annotation ────────────────────────────────────────---
+// A lightweight shared whiteboard layered over a conversation: agent and guest
+// can draw freehand strokes that both sides see live. Strokes are relayed
+// (not stored as messages) and kept per-conversation so late joiners can catch
+// up via the `opened` frame's `annotations` field.
+
+export interface AnnotationPoint { x: number; y: number }
+export interface AnnotationStroke {
+  id:     string
+  points: AnnotationPoint[]
+  color:  string
+  width:  number
+  by:     UserId
+}
+
+// ── Subject (the referenced entity — Intercom "custom object") ────────────────
+// Carries shared state (available → reserved → sold) and fields (price, vin…)
+// that actions read/write. Many conversations reference one subject. Never a room.
+
+export interface Subject {
+  id:        SubjectId
+  tenantId:  TenantId
+  title:     string
+  state:     string
+  fields:    Record<string, string | number | boolean>
+  createdAt: number
+  updatedAt: number
+}

package/src/protocol/frames.ts

@@ -0,0 +1,86 @@
+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'
+
+// ── Wire protocol ─────────────────────────────────────────────────────────────
+// One shared contract, imported by server + widget + dashboard. A change here is
+// a compile error in every consumer — which is the whole reason this lives in a
+// shared package instead of being hand-copied three times.
+
+export type ErrorCode =
+  | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'BAD_REQUEST'
+  | 'RATE_LIMITED' | 'PAYLOAD_TOO_LARGE' | 'CONFLICT' | 'INTERNAL'
+
+export type ClientFrame =
+  | { type: 'auth';    token: string }
+  // Open an existing conversation, or find-or-create one. Find-or-create keys on
+  // (guest, subject) when subjectId is given; otherwise a fresh conversation.
+  | { type: 'open';    conversationId?: ConversationId; subjectId?: SubjectId; profileId?: ProfileId }
+  | { type: 'send';    conversationId: ConversationId; clientMsgId: string; content: MessageContent; replyToId?: MessageId }
+  | { type: 'sync';    conversationId: ConversationId; sinceSeq: number }          // catch-up after cursor
+  | { type: 'history'; conversationId: ConversationId; beforeSeq: number; limit?: number }  // load older
+  | { type: 'read';    conversationId: ConversationId; seq: number }               // read up to seq
+  | { 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 }   // null = unassign
+  | { type: 'tag';     conversationId: ConversationId; tag: string; remove?: boolean }
+  | { type: 'note';    conversationId: ConversationId; clientMsgId: string; text: string }   // internal note
+  | { type: 'agent_status'; status: 'online' | 'away' | 'offline' }   // agent sets their availability
+  // Co-browsing: a freehand stroke (or "clear") on the shared annotation canvas
+  // for a subject-anchored conversation. Relayed live to the other participant.
+  | { type: 'annotate';       conversationId: ConversationId; stroke: Omit<AnnotationStroke, 'by'> }
+  | { type: 'annotate_clear'; conversationId: ConversationId }
+  | { type: 'pubkey'; conversationId: ConversationId; key: string }
+  // X3DH async E2E: a client uploads a batch of one-time prekeys so peers can
+  // encrypt to them while they are offline. The server stores them opaquely and
+  // vends one on demand — it never derives or uses the keys.
+  | { 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 }   // broadcast to agents: guests currently connected
+  | { type: 'agent_status_changed'; agentId: UserId; status: 'online' | 'away' | 'offline' }
+  // Live sentiment of a guest's most recent message — relayed to agents only so
+  // the inbox can flag frustrated conversations as they happen.
+  | { type: 'sentiment';    conversationId: ConversationId; label: 'positive' | 'neutral' | 'frustrated'; score: number }
+  // Co-browsing: relay of an annotation stroke / clear to everyone in the room.
+  | { 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 }
+  // X3DH bundle vended to a requesting client so they can encrypt to an offline peer.
+  // Contains null when the target user has no registered prekeys.
+  | { 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 const LIMITS = {
+  MAX_TEXT_LEN:       8_000,
+  MAX_HISTORY_LIMIT:  100,
+  DEFAULT_HISTORY:    50,
+} as const

package/src/protocol/ids.ts

@@ -0,0 +1,27 @@
+// Branded identifier types. A plain string can't be passed where a TenantId is
+// expected (and vice-versa), so id-confusion bugs — the kind that caused the
+// `t-1` vs `dev-tenant` mismatch in the previous system — become compile errors.
+
+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 const asTenantId       = (s: string): TenantId       => s as TenantId
+export const asUserId         = (s: string): UserId         => s as UserId
+export const asConversationId = (s: string): ConversationId => s as ConversationId
+export const asSubjectId      = (s: string): SubjectId      => s as SubjectId
+export const asMessageId      = (s: string): MessageId      => s as MessageId
+export const asActionId       = (s: string): ActionId       => s as ActionId
+export const asProfileId      = (s: string): ProfileId      => s as ProfileId
+export const asConnectionId   = (s: string): ConnectionId   => s as ConnectionId
+
+/** Anonymous guests live under this tenant; they bypass cross-tenant scoping but
+ *  are still gated by conversation membership. */
+export const ANONYMOUS_TENANT = asTenantId('anonymous')

package/src/protocol/index.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/src/react.tsx

@@ -0,0 +1,37 @@
+// react.tsx — React wrapper around mount(). Optional: only needed if you're
+// using React/Next.js. Plain HTML/vanilla JS sites should use mount() directly.
+//
+// Usage:
+//   import { ChatWidget } from '@paramms/chat-widget/react'
+//   <ChatWidget url="wss://api.paramms.com/ws" profileId="p_xxx" />
+//
+// Next.js (App Router): this component uses browser APIs (WebSocket, DOM) and
+// MUST be rendered client-side. Add the 'use client' directive to whichever
+// file renders it, e.g.:
+//   'use client'
+//   import { ChatWidget } from '@paramms/chat-widget/react'
+import { useEffect, useRef } from 'react'
+import { mount, type MountOptions, type WidgetHandle } from './index.js'
+
+export type ChatWidgetProps = Omit<MountOptions, 'el'>
+
+/** Drop-in React component for the chat widget. Mounts on the client only —
+ *  safe to use in Next.js as long as the host file/component is marked
+ *  'use client' (the widget needs WebSocket + DOM, which don't exist during
+ *  server-side rendering). */
+export function ChatWidget(props: ChatWidgetProps): JSX.Element {
+  const ref = useRef<HTMLDivElement>(null)
+  const handleRef = useRef<WidgetHandle | null>(null)
+
+  useEffect(() => {
+    if (!ref.current) return
+    handleRef.current = mount({ ...props, el: ref.current })
+    return () => { handleRef.current?.close(); handleRef.current = null }
+    // Re-mount if the connection target or profile changes; most other props
+    // (theme, quick replies) are read once at mount time by design, matching
+    // how the vanilla mount() API works.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [props.url, props.profileId, props.subjectId, props.token])
+
+  return <div ref={ref} style={{ width: '100%', height: '100%' }} />
+}