@brandfine/client 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @brandfine/client
 
+## 0.14.0
+
+### Minor Changes
+
+- 966879a: Appointments grows the authenticated half it was missing — book as a known person, read your own status back, and cancel, mirroring Live Chat's identity model:
+  - **Verified visitor identity on `createRequest`** — optional `visitor: { externalId, name?, email?, attributes?, identityToken }`, signed with the SAME `liveChat.identityToken(externalId)` you already use for chat (one signature, both plugins). Valid → the booking is attributed (verified name/email take precedence, `identityVerified: true` in the response, and the booking links to the person's chat threads via the shared `externalId`). Invalid or absent → the booking proceeds anonymously; it is never rejected.
+  - **Identity-scoped read-back** — `appointments.list({ externalId, identityToken })` returns the verified person's appointments (status, requestedAt, `scheduledAt` once confirmed, `declineReason` on rejection, timezone), newest first; `appointments.get(id, identity)` fetches one, 404ing identically for missing and foreign ids. POST under the hood so the identityToken never lands in URLs or logs. Bad signature → hard 401 (reads require proof).
+  - **`appointments.cancel(cancellationToken)`** — spends the one-time token `createRequest` already returned; no more hand-rolled HTTP call.
+  - **Publishable-key availability** — the workspace's scoped `brandfine_pk_…` key (minted/upgraded on Appointments activation, shown in the config) can now call `getAvailability` read-only, so fully-static sites render slots without a proxy. Booking, read-back and cancel stay on the broad workspace key.
+  - **Export fix** — `AppointmentAvailability`, `AppointmentSlot`, `CreateAppointmentRequestInput`, `CreatedAppointmentRequest` (plus the new `Appointment`, `AppointmentStatus`, `AppointmentIdentity`, `VerifiedVisitor`) are now exported from the package root; previously they were declared but unexported.
+
+- 966879a: Live Chat gets a realtime transport — messages arrive in ~ms instead of on the 5-second tick, with **zero consumer code changes**:
+  - `createSession()` upgrades itself to a WebSocket when the API advertises `realtimeUrl` (new optional field on `LiveChatBootstrap` and the runtime config — older SDKs ignore it; this SDK against an older API simply polls). Same `subscribe`/`getSnapshot`/`send`/`reset`/`close` surface; a consumer never has to ask which transport is live.
+  - **Polling is the automatic, invisible fallback**: no `realtimeUrl`, no `WebSocket` in the runtime, a socket that won't open, or 5 consecutive reconnect failures → the session polls exactly as before. During reconnect backoff (1s→30s with jitter) polling covers the gap from the first millisecond.
+  - **Resume by `eventId`**: every message now carries a monotonic per-conversation `eventId`; reconnects replay everything after the last one seen — a laptop waking from sleep gets the missed replies, no gaps and no duplicates (also fixes a rare equal-millisecond drop window in the polling cursor via the new `afterEvent` history param).
+  - **Idempotent sends**: `send()` attaches a generated `clientId`; a retry after a dropped response returns the original message instead of duplicating.
+  - Socket auth mirrors REST exactly (publishable key + conversation token, sent in the first frame — never in the URL) and grants nothing REST wouldn't. `reset()` tears the socket down before switching threads (shared-browser guarantee); unknown frame types are ignored by both ends so typing/presence/read receipts can ship later without a breaking change.
+  - Workspaces can optionally restrict socket origins via the new `allowedOrigins` Live Chat setting (unset = any origin, matching the REST posture).
+
 ## 0.13.0
 
 ### Minor Changes

package/README.md

@@ -62,6 +62,17 @@ await bf.appointments.createRequest({
   visitorName: 'Alex',
   visitorEmail: 'alex@example.com',
   requestedAt: slots[0].start,
+  // Optional: book as a KNOWN person — same signature Live Chat
+  // uses, so one identityToken serves both plugins. Unlocks
+  // list()/get() read-back for that person.
+  visitor: {
+    externalId: 'user:42',
+    identityToken: await bf.liveChat.identityToken('user:42'),
+  },
+})
+const mine = await bf.appointments.list({
+  externalId: 'user:42',
+  identityToken: await bf.liveChat.identityToken('user:42'),
 })
 ```
 

package/dist/index.cjs

@@ -62,34 +62,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;
@@ -103,6 +132,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" });
@@ -120,6 +262,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 });
@@ -144,7 +287,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 });
@@ -171,7 +317,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 {
@@ -182,13 +332,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 });
@@ -464,7 +619,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);
@@ -488,10 +643,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 = {}) {
@@ -573,6 +729,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 {