@brandfine/client 0.13.0 → 0.14.1

package/dist/index.d.ts

@@ -17,12 +17,23 @@ export { BrandfineWebhookEvent, BrandfineWebhookHandlerOptions, BrandfineWebhook
  * who talks through the widget on one page and an inline panel on
  * another continues the same thread.
  */
-type ChatMessageSender = 'VISITOR' | 'AGENT' | 'SYSTEM';
+/**
+ * `BOT` = AI-assistant replies (arriving once a workspace enables the
+ * live-chat AI agent). Render `BOT` on the business/agent side, ideally
+ * with an "AI" label — and treat any FUTURE unknown sender value the
+ * same way (agent-side, generic label) rather than switching
+ * exhaustively: the server may add sender kinds before your copy of
+ * this SDK learns their names.
+ */
+type ChatMessageSender = 'VISITOR' | 'AGENT' | 'SYSTEM' | 'BOT';
 type ChatMessage = {
     id: string;
     body: string;
     sender: ChatMessageSender;
     createdAt: string;
+    /** Monotonic per-conversation sequence — the realtime resume
+     *  cursor. Optional: older APIs don't send it. */
+    eventId?: number;
 };
 type ConversationStatus = 'OPEN' | 'CLOSED';
 type LiveChatSessionState = 'CONNECTING' | 'OPEN' | 'CLOSED' | 'ERROR';
@@ -38,6 +49,10 @@ type LiveChatRuntimeConfig = {
     offlineMessage: string | null;
     theme: Record<string, string> | null;
     online?: boolean;
+    /** Realtime endpoint (wss://…). Absent = poll (older API, or
+     *  the transport is off). The session upgrades automatically
+     *  when present; consumers never touch it. */
+    realtimeUrl?: string;
 };
 type LiveChatSessionSnapshot = {
     messages: ChatMessage[];
@@ -64,10 +79,12 @@ type StartConversationResult = {
 };
 type LiveChatCreateSessionOptions = {
     /** The server-half bootstrap (same object `install()` takes) —
-     *  supplies the publishable key. */
+     *  supplies the publishable key (and, when the API advertises it,
+     *  the realtime endpoint — passed through wholesale). */
     config: {
         enabled: boolean;
         publishableKey?: string;
+        realtimeUrl?: string;
     };
     /** Signed identity — SAME shape and rules as `install()`. A bad
      *  signature downgrades to anonymous server-side; it is never a
@@ -259,6 +276,14 @@ type CreateAppointmentRequestInput = {
     requestedAt: string;
     /** Optional cookie-derived session id from the consumer site. */
     visitorSessionId?: string;
+    /** Signed host-app identity — the SAME payload shape and signature
+     *  Live Chat accepts, so one `liveChat.identityToken(externalId)`
+     *  call signs for both plugins. When present and valid, the booking
+     *  is attributed to the person (verified name/email take precedence
+     *  over the free-text fields above, and the booking links to their
+     *  chat threads via the shared externalId). Invalid or absent →
+     *  the booking proceeds anonymously — it is never rejected. */
+    visitor?: VerifiedVisitor;
 };
 type CreatedAppointmentRequest = {
     id: string;
@@ -266,11 +291,40 @@ type CreatedAppointmentRequest = {
     requestedAt: string;
     durationMinutes: number;
     status: 'PENDING';
+    /** True iff `visitor.identityToken` HMAC-verified — your signal
+     *  that the booking landed attributed rather than anonymous. */
+    identityVerified: boolean;
     /** Visitor's self-cancel token. Embed it in confirmation
      *  emails / on-page UI so the visitor can cancel without an
      *  account. One-time use; revoked once any party acts. */
     cancellationToken: string | null;
 };
+type AppointmentStatus = 'PENDING' | 'CONFIRMED' | 'REJECTED' | 'CANCELLED';
+/** One appointment as the identity-scoped read-back returns it —
+ *  the visitor-safe projection ("where does my request stand?"). */
+type Appointment = {
+    id: string;
+    status: AppointmentStatus;
+    /** UTC ISO 8601 of the requested slot start (reflects the current
+     *  slot after a reschedule). */
+    requestedAt: string;
+    /** The confirmed slot — non-null only once CONFIRMED. */
+    scheduledAt: string | null;
+    durationMinutes: number;
+    /** Workspace's IANA timezone for local rendering. */
+    timezone: string;
+    /** Customer's note — populated only on REJECTED. */
+    declineReason: string | null;
+    rescheduleCount: number;
+    respondedAt: string | null;
+    createdAt: string;
+};
+/** Proof of identity for read-back calls: the same externalId +
+ *  `liveChat.identityToken(externalId)` pair used when booking. */
+type AppointmentIdentity = {
+    externalId: string;
+    identityToken: string;
+};
 type AppointmentsApi = {
     /**
      * Available slots for the workspace's booking window.
@@ -286,12 +340,37 @@ type AppointmentsApi = {
      * the slot is still bookable; if it isn't, throws
      * `BrandfineApiError` with status 404 / 409.
      *
-     * The visitor's browser does not have any other appointment
-     * actions in v1 — post-submission status changes (approve /
-     * decline / reschedule) happen via email, driven by the
-     * customer in the CMS.
+     * Pass `visitor` (signed with `liveChat.identityToken()`) to book
+     * as a known person — that unlocks `list`/`get` read-back below.
+     * Anonymous bookings remain fully supported; their status flow
+     * stays email-driven via the cancellation-token link.
      */
     createRequest: (input: CreateAppointmentRequestInput) => Promise<CreatedAppointmentRequest>;
+    /**
+     * Every appointment belonging to the verified person, newest
+     * first. Requires a valid identity signature — throws
+     * `BrandfineApiError` 401 on a bad one (reads need proof; there
+     * is no anonymous downgrade for reading history). Server-side
+     * only, like `identityToken()` itself.
+     */
+    list: (identity: AppointmentIdentity) => Promise<Appointment[]>;
+    /**
+     * One appointment by id, identity-scoped. 404s when the id does
+     * not exist OR belongs to someone else — indistinguishable by
+     * design.
+     */
+    get: (id: string, identity: AppointmentIdentity) => Promise<Appointment>;
+    /**
+     * Spend the one-time `cancellationToken` from `createRequest` to
+     * cancel a still-PENDING request. The token IS the credential —
+     * no id or API key needed. Throws `BrandfineApiError` 400 when
+     * the request is no longer PENDING, 404 when the token is
+     * unknown/already spent.
+     */
+    cancel: (cancellationToken: string) => Promise<{
+        id: string;
+        status: 'CANCELLED';
+    }>;
 };
 type AnalyticsConfig = {
     enabled: false;
@@ -463,6 +542,12 @@ type LiveChatBootstrap = {
     theme: Record<string, string> | null;
     /** Widget bundle path relative to the API base URL. */
     scriptPath: string;
+    /** Realtime endpoint (wss://…). OPTIONAL by design — this is
+     *  what makes the upgrade non-breaking: an older SDK ignores
+     *  it, a newer SDK against an older API sees it absent and
+     *  polls. Consumers pass `config` through wholesale, so it
+     *  reaches the browser with no change on their side. */
+    realtimeUrl?: string;
 };
 type LiveChatInstallResult = {
     installed: false;
@@ -478,6 +563,13 @@ type LiveChatInstallResult = {
  * the Brandfine API verifies the signature. An invalid or missing
  * token silently downgrades the conversation to anonymous.
  */
+/**
+ * A signed host-app identity payload. Named per-plugin below for
+ * discoverability, but it is ONE shape signed ONE way: a token from
+ * `liveChat.identityToken(externalId)` is accepted by Live Chat AND
+ * Appointments (`createRequest.visitor`, `list`/`get`).
+ */
+type VerifiedVisitor = LiveChatVisitor;
 type LiveChatVisitor = {
     /** Your app's stable id for this person (user id, lead reference…).
      *  Conversations sharing an externalId are the same person across
@@ -588,9 +680,11 @@ type LiveChatApi = {
     }) => Promise<StartConversationResult>;
     sendMessage: (conversationToken: string, input: {
         body: string;
+        clientId?: string;
     }) => Promise<ChatMessage>;
     history: (conversationToken: string, opts?: {
         after?: string;
+        afterEvent?: number;
     }) => Promise<{
         messages: ChatMessage[];
         status: ConversationStatus;
@@ -612,4 +706,4 @@ declare function createBrandfineClient(config: BrandfineClientConfig): Brandfine
  */
 declare const SDK_VERSION: "0.0.0";
 
-export { type AnalyticsConfig, type AnalyticsInstallResult, type AnalyticsOverview, type AnalyticsOverviewRange, BrandfineApiError, BrandfineCategory, type BrandfineClient, type BrandfineClientConfig, BrandfineNavigation, BrandfinePost, BrandfineWorkspace, type ChatMessage, type ChatMessageSender, type ConversationStatus, type CreateSubmissionInput, type InstallOptions, ListCategoriesOptions, ListPostsOptions, type LiveChatBootstrap, type LiveChatCreateSessionOptions, type LiveChatInstallOptions, type LiveChatInstallResult, type LiveChatRuntimeConfig, type LiveChatSession, type LiveChatSessionSnapshot, type LiveChatSessionState, type LiveChatVisitor, SDK_VERSION, type StartConversationResult, type Submission, createBrandfineClient };
+export { type AnalyticsConfig, type AnalyticsInstallResult, type AnalyticsOverview, type AnalyticsOverviewRange, type Appointment, type AppointmentAvailability, type AppointmentIdentity, type AppointmentSlot, type AppointmentStatus, BrandfineApiError, BrandfineCategory, type BrandfineClient, type BrandfineClientConfig, BrandfineNavigation, BrandfinePost, BrandfineWorkspace, type ChatMessage, type ChatMessageSender, type ConversationStatus, type CreateAppointmentRequestInput, type CreateSubmissionInput, type CreatedAppointmentRequest, type InstallOptions, ListCategoriesOptions, ListPostsOptions, type LiveChatBootstrap, type LiveChatCreateSessionOptions, type LiveChatInstallOptions, type LiveChatInstallResult, type LiveChatRuntimeConfig, type LiveChatSession, type LiveChatSessionSnapshot, type LiveChatSessionState, type LiveChatVisitor, SDK_VERSION, type StartConversationResult, type Submission, type VerifiedVisitor, createBrandfineClient };

package/dist/index.js

@@ -60,34 +60,63 @@ async function createLiveChatSession(wire, opts) {
   const listeners = /* @__PURE__ */ new Set();
   const seen = /* @__PURE__ */ new Set();
   let cursor;
+  let lastEventId = 0;
   let token;
   let timer;
   let closed = false;
   let ticking = false;
   const aborter = new AbortController();
+  let realtimeUrl = opts.config.realtimeUrl;
+  let ws;
+  let wsLive = false;
+  let wsFailures = 0;
+  let wsGivenUp = false;
+  let reconnectTimer;
+  let pingTimer;
   function emit(patch) {
     snapshot = { ...snapshot, ...patch };
     for (const listener of listeners) listener(snapshot);
   }
   function appendMessages(incoming) {
     const fresh = incoming.filter((m) => !seen.has(m.id));
-    if (fresh.length === 0) return;
-    for (const m of fresh) seen.add(m.id);
+    if (fresh.length === 0) {
+      for (const m of incoming) {
+        if (typeof m.eventId === "number" && m.eventId > lastEventId) {
+          lastEventId = m.eventId;
+        }
+      }
+      return;
+    }
+    for (const m of fresh) {
+      seen.add(m.id);
+      if (typeof m.eventId === "number" && m.eventId > lastEventId) {
+        lastEventId = m.eventId;
+      }
+    }
     const messages = [...snapshot.messages, ...fresh];
     cursor = messages[messages.length - 1].createdAt;
     emit({ messages });
   }
+  function markClosed() {
+    if (snapshot.status !== "CLOSED") emit({ status: "CLOSED" });
+    stopPolling();
+    teardownRealtime();
+    wsGivenUp = true;
+  }
   async function tick() {
     if (ticking || closed || !token) return;
     ticking = true;
     try {
-      const result = await wire.history(token, { after: cursor });
+      const result = await wire.history(
+        token,
+        // The eventId cursor is exact (no equal-millisecond drop
+        // window); the timestamp cursor remains for old APIs that
+        // never sent eventIds.
+        lastEventId > 0 ? { afterEvent: lastEventId } : { after: cursor }
+      );
       if (closed) return;
       appendMessages(result.messages);
-      if (result.status === "CLOSED" && snapshot.status !== "CLOSED") {
-        emit({ status: "CLOSED" });
-        stopPolling();
-      }
+      if (result.status === "CLOSED") markClosed();
     } catch {
     } finally {
       ticking = false;
@@ -101,6 +130,119 @@ async function createLiveChatSession(wire, opts) {
     if (timer !== void 0) clearInterval(timer);
     timer = void 0;
   }
+  function teardownRealtime() {
+    if (reconnectTimer !== void 0) clearTimeout(reconnectTimer);
+    reconnectTimer = void 0;
+    if (pingTimer !== void 0) clearInterval(pingTimer);
+    pingTimer = void 0;
+    wsLive = false;
+    if (ws) {
+      const socket = ws;
+      ws = void 0;
+      try {
+        socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
+        socket.close();
+      } catch {
+      }
+    }
+  }
+  function scheduleReconnect() {
+    if (closed || wsGivenUp || reconnectTimer !== void 0) return;
+    if (wsFailures >= 5) {
+      wsGivenUp = true;
+      return;
+    }
+    const base = Math.min(3e4, 1e3 * 2 ** wsFailures);
+    const delay = base / 2 + Math.random() * (base / 2);
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = void 0;
+      startRealtime();
+    }, delay);
+  }
+  function handleSocketDown() {
+    teardownRealtime();
+    if (closed || wsGivenUp || snapshot.status === "CLOSED") return;
+    startPolling();
+    wsFailures += 1;
+    scheduleReconnect();
+  }
+  function startRealtime() {
+    if (closed || wsGivenUp || wsLive || ws !== void 0 || !realtimeUrl || !token || !publishableKey || typeof WebSocket === "undefined" || snapshot.status === "CLOSED") {
+      return;
+    }
+    let socket;
+    try {
+      socket = new WebSocket(realtimeUrl);
+    } catch {
+      wsFailures += 1;
+      scheduleReconnect();
+      return;
+    }
+    ws = socket;
+    socket.onopen = () => {
+      try {
+        socket.send(
+          JSON.stringify({
+            type: "auth",
+            publishableKey,
+            conversationToken: token,
+            lastEventId
+          })
+        );
+      } catch {
+        handleSocketDown();
+      }
+    };
+    socket.onmessage = (event) => {
+      let frame;
+      try {
+        frame = JSON.parse(String(event.data));
+      } catch {
+        return;
+      }
+      switch (frame.type) {
+        case "ready": {
+          wsLive = true;
+          wsFailures = 0;
+          stopPolling();
+          if (pingTimer === void 0) {
+            pingTimer = setInterval(() => {
+              try {
+                socket.send(JSON.stringify({ type: "ping" }));
+              } catch {
+              }
+            }, 3e4);
+          }
+          break;
+        }
+        case "message": {
+          const m = frame.message;
+          if (m && typeof m.id === "string") {
+            appendMessages([
+              {
+                ...m,
+                eventId: typeof frame.eventId === "number" ? frame.eventId : m.eventId
+              }
+            ]);
+          }
+          break;
+        }
+        case "status": {
+          if (frame.status === "CLOSED") markClosed();
+          break;
+        }
+        case "error": {
+          wsGivenUp = true;
+          teardownRealtime();
+          if (!closed && snapshot.status !== "CLOSED") startPolling();
+          break;
+        }
+      }
+    };
+    socket.onclose = () => handleSocketDown();
+    socket.onerror = () => {
+    };
+  }
   async function connect(resumeToken) {
     if (!publishableKey) {
       emit({ status: "CLOSED" });
@@ -118,6 +260,7 @@ async function createLiveChatSession(wire, opts) {
         offlineMessage: cfg.offlineMessage,
         online: cfg.online !== false
       });
+      if (cfg.realtimeUrl !== void 0) realtimeUrl = cfg.realtimeUrl;
     } catch (error) {
       if (closed) return;
       emit({ status: "ERROR", error });
@@ -142,7 +285,10 @@ async function createLiveChatSession(wire, opts) {
       if (started.online !== void 0) emit({ online: started.online });
       emit({ status: "OPEN" });
       await tick();
-      if (!closed) startPolling();
+      if (!closed) {
+        startPolling();
+        startRealtime();
+      }
     } catch (error) {
       if (closed) return;
       emit({ status: "ERROR", error });
@@ -169,7 +315,11 @@ async function createLiveChatSession(wire, opts) {
       }
       emit({ sending: true });
       try {
-        const message = await wire.sendMessage(token, { body: trimmed });
+        const clientId = typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID() : `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 12)}`;
+        const message = await wire.sendMessage(token, {
+          body: trimmed,
+          clientId
+        });
         appendMessages([message]);
         return message;
       } finally {
@@ -180,13 +330,18 @@ async function createLiveChatSession(wire, opts) {
       if (closed) return;
       closed = true;
       stopPolling();
+      teardownRealtime();
       aborter.abort();
       listeners.clear();
     },
     async reset() {
+      teardownRealtime();
+      wsFailures = 0;
+      wsGivenUp = false;
       if (publishableKey) writeStoredToken(publishableKey, null);
       token = void 0;
       cursor = void 0;
+      lastEventId = 0;
       seen.clear();
       stopPolling();
       emit({ messages: [], status: "CONNECTING", error: null });
@@ -462,7 +617,7 @@ function createBrandfineClient(config) {
         history: (conversationToken, o = {}) => liveChatWireRequest(
           void 0,
           "GET",
-          `/external/live-chat/conversations/${encodeURIComponent(conversationToken)}/messages${o.after ? `?after=${encodeURIComponent(o.after)}` : ""}`
+          `/external/live-chat/conversations/${encodeURIComponent(conversationToken)}/messages${o.afterEvent !== void 0 ? `?afterEvent=${encodeURIComponent(String(o.afterEvent))}` : o.after ? `?after=${encodeURIComponent(o.after)}` : ""}`
         )
       };
       return createLiveChatSession(wire, opts);
@@ -486,10 +641,11 @@ function createBrandfineClient(config) {
       );
     },
     history(conversationToken, o = {}) {
+      const qs = o.afterEvent !== void 0 ? `?afterEvent=${encodeURIComponent(String(o.afterEvent))}` : o.after ? `?after=${encodeURIComponent(o.after)}` : "";
       return liveChatWireRequest(
         void 0,
         "GET",
-        `/external/live-chat/conversations/${encodeURIComponent(conversationToken)}/messages${o.after ? `?after=${encodeURIComponent(o.after)}` : ""}`
+        `/external/live-chat/conversations/${encodeURIComponent(conversationToken)}/messages${qs}`
       );
     },
     async identityToken(externalId, opts = {}) {
@@ -571,6 +727,35 @@ function createBrandfineClient(config) {
         "/external/appointments/requests",
         input
       );
+    },
+    async list(identity) {
+      const res = await post(
+        "/external/appointments/requests/lookup",
+        identity
+      );
+      return res.appointments;
+    },
+    async get(id, identity) {
+      const res = await post(
+        "/external/appointments/requests/lookup",
+        { ...identity, id }
+      );
+      const row = res.appointments[0];
+      if (!row) {
+        throw new BrandfineApiError({
+          status: 404,
+          statusText: "Not Found",
+          body: "Appointment not found.",
+          url: "/external/appointments/requests/lookup"
+        });
+      }
+      return row;
+    },
+    cancel(cancellationToken) {
+      return post(
+        `/external/appointments/requests/${encodeURIComponent(cancellationToken)}/cancel`,
+        {}
+      );
     }
   };
   return {