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/dist/index.d.ts CHANGED Viewed

@@ -3,6 +3,101 @@ export { e as BrandfineNavItem, f as BrandfineNavItemType, g as BrandfineNavPost
 export { Cache, CacheOptions, KeyedCache, KeyedCacheOptions, createCache, createKeyedCache } from './cache/index.js';
 export { BrandfineWebhookEvent, BrandfineWebhookHandlerOptions, BrandfineWebhookPayload, createBrandfineWebhookHandler, parseWebhookPayload, verifyWebhookSecret } from './webhook/index.js';
+/**
+ * Headless Live Chat session — the conversation WITHOUT the widget.
+ *
+ * `bf.liveChat.createSession()` gives a consumer everything needed to
+ * render chat inline in their own design system: transcript state, a
+ * send method, and a subscribe API shaped for
+ * `useSyncExternalStore` / Svelte stores / Vue refs. Brandfine keeps
+ * owning transport, identity, threading and storage; the consumer
+ * owns pixels.
+ *
+ * Storage keys are IDENTICAL to the floating widget's, so a visitor
+ * who talks through the widget on one page and an inline panel on
+ * another continues the same thread.
+ */
+type ChatMessageSender = 'VISITOR' | 'AGENT' | 'SYSTEM';
+type ChatMessage = {
+    id: string;
+    body: string;
+    sender: ChatMessageSender;
+    createdAt: string;
+};
+type ConversationStatus = 'OPEN' | 'CLOSED';
+type LiveChatSessionState = 'CONNECTING' | 'OPEN' | 'CLOSED' | 'ERROR';
+/** The `/external/live-chat/config` shape — the RUNTIME config the
+ *  widget fetches per page load. Distinct from the server-side
+ *  `LiveChatBootstrap` (which additionally carries the publishable
+ *  key + script path). */
+type LiveChatRuntimeConfig = {
+    enabled: false;
+} | {
+    enabled: true;
+    greeting: string | null;
+    offlineMessage: string | null;
+    theme: Record<string, string> | null;
+    online?: boolean;
+};
+type LiveChatSessionSnapshot = {
+    messages: ChatMessage[];
+    status: LiveChatSessionState;
+    /** Agents available right now (business-hours based today; agent
+     *  presence once the realtime transport lands). */
+    online: boolean;
+    /** Localized via the session's `locale`. */
+    greeting: string | null;
+    offlineMessage: string | null;
+    /** An outbound `send()` is in flight. */
+    sending: boolean;
+    error: Error | null;
+};
+type StartConversationResult = {
+    enabled: false;
+} | {
+    enabled: true;
+    conversationId: string;
+    conversationToken: string;
+    greeting: string | null;
+    resumed: boolean;
+    online?: boolean;
+};
+type LiveChatCreateSessionOptions = {
+    /** The server-half bootstrap (same object `install()` takes) —
+     *  supplies the publishable key. */
+    config: {
+        enabled: boolean;
+        publishableKey?: string;
+    };
+    /** Signed identity — SAME shape and rules as `install()`. A bad
+     *  signature downgrades to anonymous server-side; it is never a
+     *  second identity path. */
+    visitor?: Record<string, unknown>;
+    /** BCP-47 tag for greeting/away localization. Defaults to
+     *  `<html lang>` then browser language, like the widget. */
+    locale?: string;
+    /** Defaults to `location.href`. */
+    pageUrl?: string;
+    referrer?: string;
+    /** Transcript refresh cadence. Polling is the transport today; a
+     *  realtime upgrade will keep this as the fallback. */
+    pollIntervalMs?: number;
+};
+type LiveChatSession = {
+    /** Current transcript (same array identity as the latest snapshot). */
+    readonly messages: readonly ChatMessage[];
+    readonly state: LiveChatSessionState;
+    send(body: string): Promise<ChatMessage>;
+    /** Listener fires on every snapshot change. Returns unsubscribe. */
+    subscribe(listener: (s: LiveChatSessionSnapshot) => void): () => void;
+    getSnapshot(): LiveChatSessionSnapshot;
+    /** Stop polling, abort in-flight work, drop listeners. Idempotent. */
+    close(): void;
+    /** Drop the stored conversation token and start a fresh thread —
+     *  identity switch on a shared browser. */
+    reset(): Promise<void>;
+};
 /**
  * `createBrandfineClient` — the SDK's entry point.
  *
@@ -19,9 +114,12 @@ export { BrandfineWebhookEvent, BrandfineWebhookHandlerOptions, BrandfineWebhook
  */
 type BrandfineClientConfig = {
-    /** Base URL of the Brandfine API. No trailing slash — the client
-     *  trims one if you pass it anyway. e.g. `https://api.brandfine.co` */
-    baseUrl: string;
+    /** Base URL of the Brandfine API. OPTIONAL — defaults to the
+     *  production API (`https://api.brandfine.co`); on the server the
+     *  `BRANDFINE_API_URL` env var overrides the default (set it for
+     *  local dev / staging). Explicit option wins over both. No
+     *  trailing slash — the client trims one if you pass it anyway. */
+    baseUrl?: string;
     /** Workspace-scoped API key. Generated from the cms's Workspace
      *  settings; identifies which workspace the client talks to. */
     apiKey: string;
@@ -412,6 +510,14 @@ type LiveChatInstallOptions = {
      * onto the widget host, it performs no crypto.
      */
     visitor?: LiveChatVisitor;
+    /**
+     * Locale for the widget's visitor-facing strings (greeting, away
+     * message), e.g. your i18n router's active locale. Optional — the
+     * widget falls back to the page's `<html lang>` and then the
+     * browser language. Resolved server-side against the workspace's
+     * configured translations; unknown locales get the default text.
+     */
+    locale?: string;
 };
 type LiveChatApi = {
     /**
@@ -436,18 +542,59 @@ type LiveChatApi = {
     install: (opts: LiveChatInstallOptions) => Promise<LiveChatInstallResult>;
     /**
      * Computes the visitor identity token:
-     * hex(HMAC_SHA256(identitySecret, externalId)). SERVER-ONLY — it
-     * throws in a browser context and throws when no secret is
-     * provided (explicitly or via BRANDFINE_LIVE_CHAT_IDENTITY_SECRET),
-     * rather than ever emitting an unsigned/mis-signed payload.
+     * hex(HMAC_SHA256(signingSecret, externalId)). SERVER-ONLY — it
+     * throws in a browser context rather than ever computing next to
+     * the DOM.
      *
-     * Get the secret from the CMS: Plugins → Live Chat → Manage
-     * settings → Integrate → Identity secret. Keep it in server env;
-     * shipping it to a browser lets anyone impersonate any visitor.
+     * Signing secret, in order: `{ secret }` option →
+     * `BRANDFINE_LIVE_CHAT_IDENTITY_SECRET` env → **derived from the
+     * client's API key** (HMAC with a fixed domain-separation
+     * constant; the Brandfine API derives the same value from its
+     * stored copy). The derived path needs ZERO extra configuration —
+     * an explicit secret is only for signers that shouldn't hold the
+     * broad key, or legacy workspaces without a revealable key
+     * (generate one in the CMS: Plugins → Live Chat → Integrate).
      */
     identityToken: (externalId: string, opts?: {
         secret?: string;
     }) => Promise<string>;
+    /**
+     * Headless session — the conversation without the widget, for
+     * building your own inline chat UI. Browser-only. Takes the same
+     * `config` and signed `visitor` as `install()` (identical identity
+     * rules and thread continuity — it IS the same conversation the
+     * widget would join, sharing its storage keys). Transport today is
+     * polling (`pollIntervalMs`, default 5000); a realtime upgrade
+     * will keep this API and the poll as fallback.
+     */
+    createSession: (opts: LiveChatCreateSessionOptions) => Promise<LiveChatSession>;
+    /**
+     * Raw, stateless wire methods for full control. NOTE on auth: the
+     * config + start endpoints authenticate with this client's
+     * `apiKey` header — in a browser, construct the client with the
+     * PUBLISHABLE key (`createBrandfineClient({ apiKey: config.publishableKey })`),
+     * never the broad key. Message endpoints authenticate with the
+     * conversation token alone — treat it as a bearer credential:
+     * don't log it, don't put it in URLs you share.
+     */
+    runtimeConfig: (locale?: string) => Promise<LiveChatRuntimeConfig>;
+    startConversation: (input: {
+        visitorSessionId: string;
+        conversationToken?: string;
+        pageUrl?: string;
+        referrer?: string;
+        locale?: string;
+        visitor?: Record<string, unknown>;
+    }) => Promise<StartConversationResult>;
+    sendMessage: (conversationToken: string, input: {
+        body: string;
+    }) => Promise<ChatMessage>;
+    history: (conversationToken: string, opts?: {
+        after?: string;
+    }) => Promise<{
+        messages: ChatMessage[];
+        status: ConversationStatus;
+    }>;
 };
 declare function createBrandfineClient(config: BrandfineClientConfig): BrandfineClient;
@@ -465,4 +612,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 CreateSubmissionInput, type InstallOptions, ListCategoriesOptions, ListPostsOptions, SDK_VERSION, type Submission, createBrandfineClient };
+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 };

package/dist/index.js CHANGED Viewed

@@ -2,6 +2,201 @@ export { createCache, createKeyedCache } from './chunk-DHQHUIFO.js';
 export { isLocale, localizePath, pickLocale, resolveNavigation, stripLocalePrefix } from './chunk-U6VJX7PP.js';
 export { createBrandfineWebhookHandler, parseWebhookPayload, verifyWebhookSecret } from './chunk-QQLAYITF.js';
+// 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";
@@ -21,6 +216,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;
@@ -42,12 +254,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;
@@ -162,6 +380,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");
@@ -186,6 +426,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-")) {
@@ -201,35 +444,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 = {