@paramms/chat-widget 0.1.0 → 1.0.0

package/src/protocol/actions.ts

@@ -1,114 +0,0 @@
-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

@@ -1,35 +0,0 @@
-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

@@ -1,104 +0,0 @@
-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

@@ -1,86 +0,0 @@
-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

@@ -1,27 +0,0 @@
-// 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

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

package/src/react.tsx

@@ -1,37 +0,0 @@
-// 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%' }} />
-}