npm - @brandfine/client - Versions diffs - 0.10.0 → 0.13.0 - Mend

@brandfine/client 0.10.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,30 @@
 # @brandfine/client
+## 0.13.0
+### Minor Changes
+- 6c8f190: Headless Live Chat — build your own chat UI:
+  - `liveChat.createSession({ config, visitor, locale, pollIntervalMs })` exposes the conversation as typed, subscribable state (`messages`, `status`, `online`, localized `greeting`/`offlineMessage`, `sending`, `error`) with `send()`, `subscribe()` (shaped for `useSyncExternalStore`), `close()` and `reset()`. Shares the floating widget's storage, threading and identity semantics — same conversation everywhere; the widget remains unchanged.
+  - Raw wire methods for full control: `liveChat.runtimeConfig()`, `startConversation()`, `sendMessage()`, `history()`. In browsers, construct the client with the publishable key.
+  - New root exports: `ChatMessage`, `ChatMessageSender`, `ConversationStatus`, `LiveChatSession`, `LiveChatSessionSnapshot`, `LiveChatSessionState`, `LiveChatCreateSessionOptions`, `LiveChatRuntimeConfig`, `StartConversationResult` — with a root-export test so gaps can't regress again.
+  - Transport is polling (default 5000 ms, `pollIntervalMs` option); a future realtime upgrade keeps this API with polling as fallback.
+## 0.12.0
+### Minor Changes
+- 0e6c7c9: Live Chat localization + zero-config identity signing (code already on main, changeset restored after a merge dropped it):
+  - `liveChat.install({ config, locale })` pins the widget's language (falls back to the page's `<html lang>`, then the browser). Greeting/away-message translations are configured per locale in the CMS and resolved server-side; the visitor's page language is stored on the conversation.
+  - `liveChat.identityToken()` no longer requires a configured secret: by default it derives the signing secret from the client's API key (domain-separated HMAC; the API verifies against the same derivation). `{ secret }` / `BRANDFINE_LIVE_CHAT_IDENTITY_SECRET` still override for decoupled signers and legacy workspaces. The missing-secret throw is gone — only the in-browser guard remains.
+## 0.11.0
+### Minor Changes
+- 59bb2ab: - `baseUrl` is now optional: resolution is explicit option → `BRANDFINE_API_URL` env (server-side) → `https://api.brandfine.co`. Consumers only configure a URL for local dev or staging; existing explicit `baseUrl` callers are unaffected.
+  - Export the Live Chat types from the root entry: `LiveChatBootstrap`, `LiveChatInstallOptions`, `LiveChatInstallResult`, `LiveChatVisitor`. They were declared in 0.9.0/0.10.0 but missing from the root export list, forcing consumers to re-derive them structurally.
 ## 0.10.0
 ### Minor Changes

package/README.md CHANGED Viewed

@@ -34,8 +34,9 @@ Pick the import path that scopes to what you actually use — tree-shaking does
 ```ts
 const bf = createBrandfineClient({
-  baseUrl: 'https://api.brandfine.co',
   apiKey: process.env.BRANDFINE_API_KEY!,
+  // baseUrl is optional — defaults to https://api.brandfine.co.
+  // For local dev, set BRANDFINE_API_URL or pass it explicitly.
 })
 // Content reads
@@ -105,16 +106,13 @@ bf.liveChat.install({ config })
 ### Verified visitors
-On signed-in pages, tell the inbox **who** is chatting. Sign the
-identity on your server with the workspace's identity secret (CMS:
-Plugins → Live Chat → Manage settings → Integrate), then pass it to
-`install()`:
+On signed-in pages, tell the inbox **who** is chatting. Signing
+needs **no extra configuration** — `identityToken()` derives the
+signing secret from the API key the client already holds:
 ```ts
 // Server — never in a browser:
-const identityToken = await bf.liveChat.identityToken(user.id, {
-  secret: process.env.BRANDFINE_LIVE_CHAT_IDENTITY_SECRET,
-})
+const identityToken = await bf.liveChat.identityToken(user.id)
 const visitor = {
   externalId: user.id,
   name: user.name,
@@ -132,11 +130,13 @@ the Brandfine inbox and continue across devices/sessions (same
 `externalId` = same person). An invalid or missing token silently
 downgrades to anonymous chat — never a blocked visitor.
-> **Security:** never ship the identity secret to a browser and
-> never compute the HMAC client-side — either would let anyone
-> impersonate any visitor. `identityToken()` enforces this: it
-> throws in browser contexts and when the secret is missing. Rotate
-> the secret in the CMS if it ever leaks.
+> **Security:** never compute the HMAC client-side — the signing
+> secret (derived from your API key, or an explicit one) must never
+> reach a browser, or anyone could impersonate any visitor.
+> `identityToken()` enforces this by throwing in browser contexts.
+> An explicit secret (`{ secret }` / `BRANDFINE_LIVE_CHAT_IDENTITY_SECRET`)
+> overrides the derived default — only needed when the signer
+> shouldn't hold the broad API key.
 Full reference: [docs.brandfine.co/docs/sdk/live-chat](https://docs.brandfine.co/docs/sdk/live-chat).

package/dist/index.cjs CHANGED Viewed

@@ -4,6 +4,201 @@ var chunkXJFKL2HU_cjs = require('./chunk-XJFKL2HU.cjs');
 var chunkFCK7QJBC_cjs = require('./chunk-FCK7QJBC.cjs');
 var chunkKHHMR2NX_cjs = require('./chunk-KHHMR2NX.cjs');
+// src/live-chat-session.ts
+var SESSION_STORAGE_KEY = "bf-live-chat-session";
+function tokenStorageKey(publishableKey) {
+  return `bf-live-chat-token:${publishableKey.slice(-12)}`;
+}
+function getVisitorSessionId() {
+  try {
+    const existing = localStorage.getItem(SESSION_STORAGE_KEY);
+    if (existing) return existing;
+    const generated = typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID().replace(/-/g, "") : `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 12)}`;
+    localStorage.setItem(SESSION_STORAGE_KEY, generated);
+    return generated;
+  } catch {
+    return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 12)}`;
+  }
+}
+function readStoredToken(publishableKey) {
+  try {
+    return localStorage.getItem(tokenStorageKey(publishableKey)) ?? void 0;
+  } catch {
+    return void 0;
+  }
+}
+function writeStoredToken(publishableKey, token) {
+  try {
+    if (token === null) localStorage.removeItem(tokenStorageKey(publishableKey));
+    else localStorage.setItem(tokenStorageKey(publishableKey), token);
+  } catch {
+  }
+}
+function resolvePageLocale(explicit) {
+  if (explicit) return explicit;
+  if (typeof document === "undefined") return void 0;
+  const htmlLang = document.documentElement.lang?.trim();
+  if (htmlLang) return htmlLang;
+  return typeof navigator !== "undefined" ? navigator.language || void 0 : void 0;
+}
+async function createLiveChatSession(wire, opts) {
+  if (typeof window === "undefined") {
+    throw new Error(
+      "liveChat.createSession() is browser-only \u2014 build the transcript UI client-side; fetch the bootstrap with getConfig() on the server."
+    );
+  }
+  const publishableKey = opts.config.enabled ? opts.config.publishableKey : void 0;
+  const locale = resolvePageLocale(opts.locale);
+  const pollMs = Math.max(1e3, opts.pollIntervalMs ?? 5e3);
+  let snapshot = {
+    messages: [],
+    status: "CONNECTING",
+    online: false,
+    greeting: null,
+    offlineMessage: null,
+    sending: false,
+    error: null
+  };
+  const listeners = /* @__PURE__ */ new Set();
+  const seen = /* @__PURE__ */ new Set();
+  let cursor;
+  let token;
+  let timer;
+  let closed = false;
+  let ticking = false;
+  const aborter = new AbortController();
+  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);
+    const messages = [...snapshot.messages, ...fresh];
+    cursor = messages[messages.length - 1].createdAt;
+    emit({ messages });
+  }
+  async function tick() {
+    if (ticking || closed || !token) return;
+    ticking = true;
+    try {
+      const result = await wire.history(token, { after: cursor });
+      if (closed) return;
+      appendMessages(result.messages);
+      if (result.status === "CLOSED" && snapshot.status !== "CLOSED") {
+        emit({ status: "CLOSED" });
+        stopPolling();
+      }
+    } catch {
+    } finally {
+      ticking = false;
+    }
+  }
+  function startPolling() {
+    stopPolling();
+    timer = setInterval(() => void tick(), pollMs);
+  }
+  function stopPolling() {
+    if (timer !== void 0) clearInterval(timer);
+    timer = void 0;
+  }
+  async function connect(resumeToken) {
+    if (!publishableKey) {
+      emit({ status: "CLOSED" });
+      return;
+    }
+    try {
+      const cfg = await wire.runtimeConfig(locale);
+      if (closed) return;
+      if (!cfg.enabled) {
+        emit({ status: "CLOSED" });
+        return;
+      }
+      emit({
+        greeting: cfg.greeting,
+        offlineMessage: cfg.offlineMessage,
+        online: cfg.online !== false
+      });
+    } catch (error) {
+      if (closed) return;
+      emit({ status: "ERROR", error });
+      return;
+    }
+    try {
+      const started = await wire.startConversation({
+        visitorSessionId: getVisitorSessionId(),
+        conversationToken: resumeToken,
+        pageUrl: opts.pageUrl ?? (typeof location !== "undefined" ? location.href.slice(0, 2048) : void 0),
+        referrer: opts.referrer,
+        locale,
+        visitor: opts.visitor
+      });
+      if (closed) return;
+      if (!started.enabled) {
+        emit({ status: "CLOSED" });
+        return;
+      }
+      token = started.conversationToken;
+      writeStoredToken(publishableKey, token);
+      if (started.online !== void 0) emit({ online: started.online });
+      emit({ status: "OPEN" });
+      await tick();
+      if (!closed) startPolling();
+    } catch (error) {
+      if (closed) return;
+      emit({ status: "ERROR", error });
+    }
+  }
+  const session = {
+    get messages() {
+      return snapshot.messages;
+    },
+    get state() {
+      return snapshot.status;
+    },
+    getSnapshot: () => snapshot,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    async send(body) {
+      const trimmed = body.trim();
+      if (!trimmed) throw new Error("send(): message body is empty");
+      if (!token) throw new Error("send(): session is not connected");
+      if (snapshot.status === "CLOSED") {
+        throw new Error("send(): conversation is closed \u2014 call reset()");
+      }
+      emit({ sending: true });
+      try {
+        const message = await wire.sendMessage(token, { body: trimmed });
+        appendMessages([message]);
+        return message;
+      } finally {
+        emit({ sending: false });
+      }
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      stopPolling();
+      aborter.abort();
+      listeners.clear();
+    },
+    async reset() {
+      if (publishableKey) writeStoredToken(publishableKey, null);
+      token = void 0;
+      cursor = void 0;
+      seen.clear();
+      stopPolling();
+      emit({ messages: [], status: "CONNECTING", error: null });
+      await connect(void 0);
+    }
+  };
+  await connect(publishableKey ? readStoredToken(publishableKey) : void 0);
+  return session;
+}
 // src/client.ts
 var BrandfineApiError = class extends Error {
   name = "BrandfineApiError";
@@ -23,6 +218,23 @@ var BrandfineApiError = class extends Error {
 };
 var INSTALLED_MARKER = "data-brandfine-analytics";
 var LIVE_CHAT_MARKER = "data-brandfine-live-chat";
+var LIVE_CHAT_IDENTITY_CONTEXT = "brandfine:live-chat:identity:v1";
+async function hmacHex(key, message) {
+  const enc = new TextEncoder();
+  const cryptoKey = await globalThis.crypto.subtle.importKey(
+    "raw",
+    enc.encode(key),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await globalThis.crypto.subtle.sign(
+    "HMAC",
+    cryptoKey,
+    enc.encode(message)
+  );
+  return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
 var GTAG_MARKER = "data-brandfine-gtag";
 function injectGoogleTag(measurementId) {
   if (typeof document === "undefined") return;
@@ -44,12 +256,18 @@ function injectGoogleTag(measurementId) {
   gtag("config", measurementId);
 }
 var DEFAULT_USER_AGENT = "@brandfine/client";
+var DEFAULT_BASE_URL = "https://api.brandfine.co";
+function resolveBaseUrl(explicit) {
+  if (explicit) return explicit;
+  if (typeof process !== "undefined" && process.env?.BRANDFINE_API_URL) {
+    return process.env.BRANDFINE_API_URL;
+  }
+  return DEFAULT_BASE_URL;
+}
 function createBrandfineClient(config) {
-  if (!config.baseUrl)
-    throw new Error("createBrandfineClient: `baseUrl` is required");
   if (!config.apiKey)
     throw new Error("createBrandfineClient: `apiKey` is required");
-  const baseUrl = config.baseUrl.replace(/\/$/, "");
+  const baseUrl = resolveBaseUrl(config.baseUrl).replace(/\/$/, "");
   const apiKey = config.apiKey;
   const fetchImpl = config.fetch ?? globalThis.fetch;
   const userAgent = config.userAgent ?? DEFAULT_USER_AGENT;
@@ -164,6 +382,28 @@ function createBrandfineClient(config) {
       return { installed: true, websiteId: cfg.websiteId };
     }
   };
+  async function liveChatWireRequest(key, method, path, body) {
+    const url = `${baseUrl}${path}`;
+    const res = await fetchImpl(url, {
+      method,
+      headers: {
+        Accept: "application/json",
+        ...body !== void 0 ? { "Content-Type": "application/json" } : {},
+        ...key ? { "X-Api-Key": key } : {}
+      },
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new BrandfineApiError({
+        status: res.status,
+        statusText: res.statusText,
+        body: text,
+        url
+      });
+    }
+    return await res.json();
+  }
   const liveChat = {
     getConfig() {
       return get("/external/live-chat/bootstrap");
@@ -188,6 +428,9 @@ function createBrandfineClient(config) {
       if (opts.visitor?.externalId && opts.visitor.identityToken) {
         host.setAttribute("data-visitor", JSON.stringify(opts.visitor));
       }
+      if (opts.locale) {
+        host.setAttribute("data-locale", opts.locale);
+      }
       if (cfg.theme) {
         for (const [key, value] of Object.entries(cfg.theme)) {
           if (key.startsWith("--bf-chat-")) {
@@ -203,35 +446,66 @@ function createBrandfineClient(config) {
       document.head.appendChild(script);
       return { installed: true };
     },
+    createSession(opts) {
+      const pk = opts.config.enabled ? opts.config.publishableKey : void 0;
+      const wire = {
+        runtimeConfig: (locale) => liveChatWireRequest(
+          pk,
+          "GET",
+          `/external/live-chat/config${locale ? `?locale=${encodeURIComponent(locale)}` : ""}`
+        ),
+        startConversation: (input) => liveChatWireRequest(pk, "POST", "/external/live-chat/conversations", input),
+        sendMessage: (conversationToken, input) => liveChatWireRequest(
+          void 0,
+          "POST",
+          `/external/live-chat/conversations/${encodeURIComponent(conversationToken)}/messages`,
+          input
+        ),
+        history: (conversationToken, o = {}) => liveChatWireRequest(
+          void 0,
+          "GET",
+          `/external/live-chat/conversations/${encodeURIComponent(conversationToken)}/messages${o.after ? `?after=${encodeURIComponent(o.after)}` : ""}`
+        )
+      };
+      return createLiveChatSession(wire, opts);
+    },
+    runtimeConfig(locale) {
+      return liveChatWireRequest(
+        apiKey,
+        "GET",
+        `/external/live-chat/config${locale ? `?locale=${encodeURIComponent(locale)}` : ""}`
+      );
+    },
+    startConversation(input) {
+      return liveChatWireRequest(apiKey, "POST", "/external/live-chat/conversations", input);
+    },
+    sendMessage(conversationToken, input) {
+      return liveChatWireRequest(
+        void 0,
+        "POST",
+        `/external/live-chat/conversations/${encodeURIComponent(conversationToken)}/messages`,
+        input
+      );
+    },
+    history(conversationToken, o = {}) {
+      return liveChatWireRequest(
+        void 0,
+        "GET",
+        `/external/live-chat/conversations/${encodeURIComponent(conversationToken)}/messages${o.after ? `?after=${encodeURIComponent(o.after)}` : ""}`
+      );
+    },
     async identityToken(externalId, opts = {}) {
       if (typeof document !== "undefined" || typeof window !== "undefined") {
         throw new Error(
           "liveChat.identityToken() is server-only \u2014 never compute identity tokens in a browser. Sign the visitor on your server and pass the result to install({ visitor })."
         );
       }
-      const secret = opts.secret ?? (typeof process !== "undefined" ? process.env.BRANDFINE_LIVE_CHAT_IDENTITY_SECRET : void 0);
-      if (!secret) {
-        throw new Error(
-          "liveChat.identityToken(): identity secret missing. Pass { secret } or set BRANDFINE_LIVE_CHAT_IDENTITY_SECRET. Generate one in the CMS: Plugins \u2192 Live Chat \u2192 Integrate."
-        );
-      }
       if (!externalId) {
         throw new Error("liveChat.identityToken(): externalId is required.");
       }
-      const enc = new TextEncoder();
-      const key = await globalThis.crypto.subtle.importKey(
-        "raw",
-        enc.encode(secret),
-        { name: "HMAC", hash: "SHA-256" },
-        false,
-        ["sign"]
-      );
-      const sig = await globalThis.crypto.subtle.sign(
-        "HMAC",
-        key,
-        enc.encode(externalId)
-      );
-      return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+      const explicit = opts.secret ?? (typeof process !== "undefined" ? process.env.BRANDFINE_LIVE_CHAT_IDENTITY_SECRET : void 0);
+      const secret = explicit ?? await hmacHex(apiKey, LIVE_CHAT_IDENTITY_CONTEXT);
+      return hmacHex(secret, externalId);
     }
   };
   const submissions = {