@braze/web-sdk 6.12.1 → 6.13.0

package/index.d.ts

@@ -1,5 +1,5 @@
 /*
-* Type definitions for @braze/web-sdk v6.12.1
+* Type definitions for @braze/web-sdk v6.13.0
 * Project: https://github.com/braze-inc/braze-web-sdk
 * (c) Braze, Inc. 2026 - http://braze.com
 * License available at https://github.com/braze-inc/braze-web-sdk/blob/master/LICENSE
@@ -2590,7 +2590,7 @@ export function logout(
  * - Create a `service-worker.js` file with the content below and place it in the root directory of your website:
  *
  * ```
- * self.importScripts('https://js.appboycdn.com/web-sdk/6.12/service-worker.js');
+ * self.importScripts('https://js.appboycdn.com/web-sdk/6.13/service-worker.js');
  * ```
  *
  * For more details, see [Our Product Documentation](https://www.braze.com/docs/developer_guide/platform_integration_guides/web/push_notifications/integration).
@@ -2937,6 +2937,237 @@ export function subscribeToBannersUpdates(
 
 
 
+/*
+ * Conversational Chat
+ *
+ * On npm these are available like any other method and are tree-shaken out if unused. On the CDN,
+ * the headless chat APIs and SDK-managed widget ship only in braze.conversational.min.js.
+ */
+
+/**
+ * A paragraph block item: a snippet of HTML to render inline.
+ */
+export interface ChatParagraphItem {
+  html: string;
+}
+
+/**
+ * An unordered-list block item: a snippet of HTML (often an anchor) to render as a list entry.
+ */
+export interface ChatListItem {
+  html: string;
+}
+
+
+export type ChatMessageBlockType = "paragraph" | "unorderedList";
+
+/**
+ * A single block of agent content. `items` are HTML snippets for paragraph/unorderedList blocks.
+ *   The SDK passes these through verbatim — it never parses, sanitizes, or markdown-converts them;
+ *   rendering (and any sanitization) is the consumer's responsibility.
+ */
+export interface ChatMessageBlock {
+  type: ChatMessageBlockType;
+  items: Array<ChatParagraphItem | ChatListItem>;
+}
+
+/**
+ * A directive the agent attaches to a turn. The set of actions depends on what the customer
+ *   configures, so `type` is open and `data` optional; the SDK passes every action through to
+ *   subscribers untouched (and acts on the few it recognizes, like ending the conversation).
+ */
+export interface ChatAction {
+  type: string;
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Action types the Braze SDK recognizes. Directives with unrecognized types are ignored.
+ */
+export type BrazeChatActionType = "error" | "end_conversation" | "user_action";
+
+/**
+ * Properties attached to a sent message. Use `completedActions` to report actions the app already
+ *   performed (named in past tense, e.g. `added_to_cart`), with supporting detail in `data`.
+ */
+export interface ChatMessageProperties {
+  completedActions?: Array<{ name: string; data?: Record<string, unknown> }>;
+}
+
+/**
+ * Event dispatched to `subscribeToChatAction` subscribers when the agent attaches a recognized
+ *   action to a turn, or when the user clicks an action button whose Braze Action URI triggers
+ *   a `user_action`.
+ */
+export type ChatActionEvent =
+  | { type: "user_action"; name: string; data?: Record<string, unknown> }
+  | { type: "end_conversation"; data?: Record<string, unknown> }
+  | { type: "error"; data?: Record<string, unknown> };
+
+/**
+ * The agent's message object for a turn. `content` is always present — the list of blocks a consumer
+ *   renders. The SDK otherwise treats this as an opaque pass-through, so additional fields the backend
+ *   may add (e.g. an id or timestamp) flow through untouched.
+ */
+export interface ChatMessageContent {
+  content: ChatMessageBlock[];
+  [key: string]: unknown;
+}
+
+/**
+ * Who sent a turn: the end user, or the conversational agent.
+ */
+export type ChatRole = "user" | "assistant";
+
+/**
+ * A single turn in the conversation. Agent turns are delivered to
+ *   `subscribeToChatMessageReceived` subscribers as they arrive; `getChatMessages` returns
+ *   the full transcript (both user and agent turns) for rendering history on reload. Use `role` to
+ *   tell them apart: `"assistant"` turns carry `message`, `"user"` turns carry `userMessage`.
+ */
+export class ChatMessage {
+  /** Who sent this turn. */
+  role: ChatRole;
+
+  /** The conversation session this turn belongs to. */
+  sessionId: string;
+
+  /** Server-assigned identifier for this message. */
+  messageId: string;
+
+  /** The directives the agent attached to this turn, e.g. ending the conversation (assistant turns only). */
+  actions: ChatAction[];
+
+  /** The agent's content for this turn (assistant turns only). */
+  message?: ChatMessageContent;
+
+  /** The event type of this turn (assistant turns only). */
+  eventType?: string;
+
+  /** The text the user sent (user turns only). */
+  userMessage?: string;
+}
+
+/**
+ * Requests the conversational chat opening message for the current user. The opening message is not
+ *   returned synchronously — it is delivered asynchronously and surfaced through
+ *   `subscribeToChatMessageReceived`, like any other agent turn.
+ *
+ * @param successCallback - Called when the request is accepted.
+ * @param errorCallback - Called on failure, including when the SDK or conversational chat is disabled.
+ */
+export function retrieveChatConfig(
+  successCallback?: () => void,
+  errorCallback?: () => void,
+): void;
+
+/**
+ * Sends a user message to the conversational agent. The agent's reply is delivered asynchronously
+ *   (see `subscribeToChatMessageReceived`).
+ *
+ * @param message - The user's message. Must be a non-empty string.
+ * @param messageProperties - Optional properties attached to the message (see `ChatMessageProperties`).
+ * @param successCallback - Called when the message is accepted.
+ * @param errorCallback - Called on failure.
+ *
+ * @returns false if the message is invalid, the SDK is disabled, a turn is already in progress, the
+ *    agent has ended the conversation, or the request was rate limited; true once the send is initiated.
+ */
+export function sendChatMessage(
+  message: string,
+  messageProperties?: ChatMessageProperties,
+  successCallback?: () => void,
+  errorCallback?: () => void,
+): boolean;
+
+/**
+ * Registers a callback invoked with each agent turn as it arrives. Every turn is delivered, including
+ *   ones carrying an `error` or `end_conversation` action, so the host can inspect `actions`.
+ *
+ * @param subscriber - The callback function to handle each received `ChatMessage`.
+ *
+ * @returns The identifier of the subscription created. This can be passed to `removeSubscription`
+ *    to cancel the subscription. Returns undefined if the SDK has not been initialized, null if the
+ *    subscriber is not a function.
+ */
+export function subscribeToChatMessageReceived(
+  subscriber: (message: ChatMessage) => void,
+): string | null | undefined;
+
+/**
+ * Registers a callback invoked (with no arguments) when the conversation state changes — a new
+ *   message, a cross-tab write, a user switch (`changeUser`), a data wipe (`wipeData`), or a
+ *   reset. Use it to refresh — re-read `getChatMessages`, `isChatTurnInProgress`,
+ *   `isChatConversationEnded`, and `isChatTurnErrored` — and re-render.
+ *
+ * @param subscriber - The callback function, invoked when conversation state changes.
+ *
+ * @returns The identifier of the subscription created. This can be passed to `removeSubscription`
+ *    to cancel the subscription. Returns undefined if the SDK has not been initialized, null if the
+ *    subscriber is not a function.
+ */
+export function subscribeToChatUpdates(
+  subscriber: () => void,
+): string | null | undefined;
+
+/**
+ * Registers a callback invoked when the agent or an action button fires an action. Use this
+ *   to react to agent directives (e.g. `end_conversation`) or user-triggered front-end actions
+ *   (e.g. `user_action` with `name: "add_to_cart"`).
+ *
+ * @param subscriber - The callback function to handle each `ChatActionEvent`.
+ *
+ * @returns The identifier of the subscription created. This can be passed to `removeSubscription`
+ *    to cancel the subscription. Returns undefined if the SDK has not been initialized, null if the
+ *    subscriber is not a function.
+ */
+export function subscribeToChatAction(
+  subscriber: (action: ChatActionEvent) => void,
+): string | null | undefined;
+
+/**
+ * Returns the conversation's turns so far so a host can render existing history on load; new turns
+ *   then arrive through `subscribeToChatMessageReceived`. Returns null if conversational chat is not
+ *   enabled for this user, or undefined if the SDK has not been initialized.
+ */
+export function getChatMessages(): ChatMessage[] | null | undefined;
+
+/**
+ * Resets the current conversation (session, transcript, in-flight turn, ended state, error state) so
+ *   the user can restart from scratch; call `retrieveChatConfig` afterward to fetch a new opening
+ *   message.
+ */
+export function resetChatConversation(): void;
+
+/**
+ * Whether a chat turn (the opening message or a sent message) is awaiting its reply. Returns null if
+ *   conversational chat is not enabled for this user, or undefined if the SDK has not been initialized.
+ */
+export function isChatTurnInProgress(): boolean | null | undefined;
+
+/**
+ * Whether the agent has ended the current conversation. While ended, `sendChatMessage` is rejected
+ *   until `resetChatConversation` is called. Returns null if conversational chat is not enabled for
+ *   this user, or undefined if the SDK has not been initialized.
+ */
+export function isChatConversationEnded(): boolean | null | undefined;
+
+/**
+ * Whether the last chat turn resulted in an error (agent error or send failure). Tracked separately from
+ *   the conversation's ended state, so an error never reopens an ended conversation and never blocks a
+ *   send on its own. Cleared when the next turn starts, when a reply arrives, or on conversation reset.
+ *   Returns null if conversational chat is not enabled for this user, or undefined if the SDK has not
+ *   been initialized.
+ */
+export function isChatTurnErrored(): boolean | null | undefined;
+
+/**
+ * Opt into SDK-managed conversational chat: mounts and manages the chat widget when conversational chat
+ *   is enabled. Call once after `initialize`. No-op if the SDK is disabled. On the CDN this method
+ *   ships only in `braze.conversational.min.js`.
+ */
+export function automaticallyManageChat(): void;
+
 /**
  * Getter method to determine if the Braze SDK has been initialized.
  */
@@ -2985,6 +3216,12 @@ export type InitializationOptions = {
    *   `use.fontawesome.com` to your Content Security Policy allowlist or by using the `doNotLoadFontAwesome` option and loading it manually.
    */
   contentSecurityNonce?: string;
+  /**
+   * By default, the conversational chat widget is shown with a z-index of one less than the in-app message backdrop:
+   *   `inAppMessageZIndex - 1` when that option is set, otherwise 9000. Provide a value for this option to override that
+   *   default, for example to layer the widget relative to other overlay content on your site.
+   */
+  conversationalChatZIndex?: number;
   /**
    * By default, the Braze SDK automatically detects and collects all device properties in `DeviceProperties`. To override
    *   this behavior, provide an array of `DeviceProperties`. To disable all properties being sent to Braze servers, provide
@@ -3036,7 +3273,7 @@ export type InitializationOptions = {
    *   lifecycle of, set this option to true and the Braze SDK will not register or unregister a service worker. If you set this
    *   option to true, in order for push to function correctly you must register the service worker yourself BEFORE calling
    *   `requestPushPermission`, and ensure that it contains Braze's service worker code, either with
-   *   `self.importScripts('https://js.appboycdn.com/web-sdk/6.12/service-worker.js');` or by including the content
+   *   `self.importScripts('https://js.appboycdn.com/web-sdk/6.13/service-worker.js');` or by including the content
    *   of that file directly. When this option is true, the `serviceWorkerLocation` option is irrelevant and is ignored.
    */
   manageServiceWorkerExternally?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@braze/web-sdk",
-  "version": "6.12.1",
+  "version": "6.13.0",
   "description": "Braze SDK for web sites and other JS platforms.",
   "main": "src/index.js",
   "scripts": {

package/shared-lib/event-types.js

@@ -1,35 +1,35 @@
 const p = {
     CustomEvent: "ce",
-    Pr: "p",
-    $c: "pc",
-    Fc: "ca",
-    vl: "i",
-    _a: "ie",
+    qr: "p",
+    km: "pc",
+    ev: "ca",
+    Sc: "i",
+    Zl: "ie",
     vs: "cci",
     ws: "ccic",
     us: "ccc",
     gs: "ccd",
-    wm: "ss",
+    Sm: "ss",
     hm: "se",
-    On: "si",
-    Hn: "sc",
-    Jn: "sbc",
-    Lc: "sfe",
+    ua: "si",
+    pa: "sc",
+    ha: "sbc",
+    tv: "sfe",
     om: "iec",
-    Dc: "lr",
-    Ac: "uae",
-    Mc: "lcaa",
-    Cc: "lcar",
-    Na: "inc",
+    bm: "lr",
+    vm: "uae",
+    Dm: "lcaa",
+    Am: "lcar",
+    Ya: "inc",
     Xu: "add",
     Zu: "rem",
     Vu: "set",
     Qu: "ncam",
-    Tc: "sgu",
+    $m: "sgu",
     xo: "ffi",
     ro: "bi",
     Nt: "bc",
     Rt: "bd",
   },
-  Ee = { Gc: "content_cards_displayed" };
-export { p as EventTypes, Ee as InternalEventTypes };
+  Me = { nv: "content_cards_displayed" };
+export { p as EventTypes, Me as InternalEventTypes };

package/shared-lib/indexed-db-adapter.js

@@ -1,21 +1,21 @@
 export default class et {
   constructor(t, e) {
     (this.database = t),
-      (this.Bd = e),
+      (this.df = e),
       (this.parent = "undefined" == typeof window ? self : window),
       (this.database = t),
-      (this.Bd = e);
+      (this.df = e);
   }
-  Ud() {
+  vf() {
     if ("indexedDB" in this.parent) return this.parent.indexedDB;
   }
   isSupported() {
     var t;
     try {
-      if (null == this.Ud()) return !1;
+      if (null == this.vf()) return !1;
       {
         const e =
-          null === (t = this.Ud()) || void 0 === t
+          null === (t = this.vf()) || void 0 === t
             ? void 0
             : t.open("Braze IndexedDB Support Test");
         if (
@@ -25,10 +25,10 @@ export default class et {
           "undefined" != typeof window)
         ) {
           const t = window,
-            e = t.chrome || t.browser || t.Od;
+            e = t.chrome || t.browser || t.Df;
           if (e && e.runtime && e.runtime.id)
             return (
-              this.Bd.info(
+              this.df.info(
                 "Not using IndexedDB for storage because we are running inside an extension",
               ),
               !1
@@ -38,27 +38,27 @@ export default class et {
       }
     } catch (t) {
       return (
-        this.Bd.info(
+        this.df.info(
           "Not using IndexedDB for storage due to following error: " + t,
         ),
         !1
       );
     }
   }
-  kd(t, e) {
+  Bf(t, e) {
     var n;
     const o =
-      null === (n = this.Ud()) || void 0 === n
+      null === (n = this.vf()) || void 0 === n
         ? void 0
-        : n.open(this.database.Kd, this.database.VERSION);
+        : n.open(this.database.Sf, this.database.VERSION);
     if (null == o) return "function" == typeof e && e(), !1;
     const i = this;
     return (
       (o.onupgradeneeded = (t) => {
         var e;
-        i.Bd.info(
+        i.df.info(
           "Upgrading indexedDB " +
-            i.database.Kd +
+            i.database.Sf +
             " to v" +
             i.database.VERSION +
             "...",
@@ -77,7 +77,7 @@ export default class et {
         (r.onversionchange = () => {
           r.close(),
             "function" == typeof e && e(),
-            i.Bd.error(
+            i.df.error(
               "Needed to close the database unexpectedly because of an upgrade in another tab",
             );
         }),
@@ -87,9 +87,9 @@ export default class et {
         var n;
         const o = t;
         return (
-          i.Bd.info(
+          i.df.info(
             "Could not open indexedDB " +
-              i.database.Kd +
+              i.database.Sf +
               " v" +
               i.database.VERSION +
               ": " +
@@ -105,16 +105,16 @@ export default class et {
   setItem(t, e, n, o, i) {
     if (!this.isSupported()) return "function" == typeof i && i(), !1;
     const r = this;
-    return this.kd((d) => {
+    return this.Bf((d) => {
       if (!d.objectStoreNames.contains(t))
         return (
-          r.Bd.error(
+          r.df.error(
             "Could not store object " +
               e +
               " in " +
               t +
               " on indexedDB " +
-              r.database.Kd +
+              r.database.Sf +
               " - " +
               t +
               " is not a valid objectStore",
@@ -126,13 +126,13 @@ export default class et {
       s.oncomplete = () => d.close();
       const u = s.objectStore(t).put(n, e);
       (u.onerror = () => {
-        r.Bd.error(
+        r.df.error(
           "Could not store object " +
             e +
             " in " +
             t +
             " on indexedDB " +
-            r.database.Kd,
+            r.database.Sf,
         ),
           "function" == typeof i && i();
       }),
@@ -144,16 +144,16 @@ export default class et {
   getItem(t, e, n) {
     if (!this.isSupported()) return !1;
     const o = this;
-    return this.kd((i) => {
+    return this.Bf((i) => {
       if (!i.objectStoreNames.contains(t))
         return (
-          o.Bd.error(
+          o.df.error(
             "Could not retrieve object " +
               e +
               " in " +
               t +
               " on indexedDB " +
-              o.database.Kd +
+              o.database.Sf +
               " - " +
               t +
               " is not a valid objectStore",
@@ -164,13 +164,13 @@ export default class et {
       r.oncomplete = () => i.close();
       const d = r.objectStore(t).get(e);
       (d.onerror = () => {
-        o.Bd.error(
+        o.df.error(
           "Could not retrieve object " +
             e +
             " in " +
             t +
             " on indexedDB " +
-            o.database.Kd,
+            o.database.Sf,
         );
       }),
         (d.onsuccess = (t) => {
@@ -183,14 +183,14 @@ export default class et {
   kr(t, e, n) {
     if (!this.isSupported()) return "function" == typeof n && n(), !1;
     const o = this;
-    return this.kd((i) => {
+    return this.Bf((i) => {
       if (!i.objectStoreNames.contains(t))
         return (
-          o.Bd.error(
+          o.df.error(
             "Could not retrieve last record from " +
               t +
               " on indexedDB " +
-              o.database.Kd +
+              o.database.Sf +
               " - " +
               t +
               " is not a valid objectStore",
@@ -202,8 +202,8 @@ export default class et {
       r.oncomplete = () => i.close();
       const d = r.objectStore(t).openCursor(null, "prev");
       (d.onerror = () => {
-        o.Bd.error(
-          "Could not open cursor for " + t + " on indexedDB " + o.database.Kd,
+        o.df.error(
+          "Could not open cursor for " + t + " on indexedDB " + o.database.Sf,
         ),
           "function" == typeof n && n();
       }),
@@ -216,19 +216,19 @@ export default class et {
         });
     }, n);
   }
-  ge(t, e) {
+  Ae(t, e) {
     if (!this.isSupported()) return !1;
     const n = this;
-    return this.kd((o) => {
+    return this.Bf((o) => {
       if (!o.objectStoreNames.contains(t))
         return (
-          n.Bd.error(
+          n.df.error(
             "Could not delete record " +
               e +
               " from " +
               t +
               " on indexedDB " +
-              n.database.Kd +
+              n.database.Sf +
               " - " +
               t +
               " is not a valid objectStore",
@@ -238,13 +238,13 @@ export default class et {
       const i = o.transaction([t], "readwrite");
       i.oncomplete = () => o.close();
       i.objectStore(t).delete(e).onerror = () => {
-        n.Bd.error(
+        n.df.error(
           "Could not delete record " +
             e +
             " from " +
             t +
             " on indexedDB " +
-            n.database.Kd,
+            n.database.Sf,
         );
       };
     });
@@ -252,14 +252,14 @@ export default class et {
   Qs(t, e) {
     if (!this.isSupported()) return !1;
     const n = this;
-    return this.kd((o) => {
+    return this.Bf((o) => {
       if (!o.objectStoreNames.contains(t))
         return (
-          n.Bd.error(
+          n.df.error(
             "Could not retrieve objects from " +
               t +
               " on indexedDB " +
-              n.database.Kd +
+              n.database.Sf +
               " - " +
               t +
               " is not a valid objectStore",
@@ -273,18 +273,18 @@ export default class et {
         s = [];
       (d.onerror = () => {
         s.length > 0
-          ? (n.Bd.info(
+          ? (n.df.info(
               "Cursor closed midway through for " +
                 t +
                 " on indexedDB " +
-                n.database.Kd,
+                n.database.Sf,
             ),
             e(s))
-          : n.Bd.error(
+          : n.df.error(
               "Could not open cursor for " +
                 t +
                 " on indexedDB " +
-                n.database.Kd,
+                n.database.Sf,
             );
       }),
         (d.onsuccess = (t) => {
@@ -307,27 +307,27 @@ export default class et {
     for (const e in this.database.Ws) {
       const n = e;
       this.database.Ws.hasOwnProperty(e) &&
-        this.database.Ws[n] !== this.database.Ws.pe &&
+        this.database.Ws[n] !== this.database.Ws.ke &&
         t.push(this.database.Ws[n]);
     }
     const e = this;
-    return this.kd(function (n) {
+    return this.Bf(function (n) {
       const o = n.transaction(t, "readwrite");
       o.oncomplete = () => n.close();
       for (let n = 0; n < t.length; n++) {
         const i = t[n];
         o.objectStore(i).clear().onerror = function () {
-          e.Bd.error(
+          e.df.error(
             "Could not clear " +
               this.source.name +
               " on indexedDB " +
-              e.database.Kd,
+              e.database.Sf,
           );
         };
       }
       o.onerror = function () {
-        e.Bd.error(
-          "Could not clear object stores on indexedDB " + e.database.Kd,
+        e.df.error(
+          "Could not clear object stores on indexedDB " + e.database.Sf,
         );
       };
     });
@@ -335,18 +335,18 @@ export default class et {
 }
 et._s = {
   Xs: {
-    Kd: "AppboyServiceWorkerAsyncStorage",
+    Sf: "AppboyServiceWorkerAsyncStorage",
     VERSION: 6,
     Ws: {
-      Cn: "data",
-      yr: "pushClicks",
+      Jh: "data",
+      Fr: "pushClicks",
       Gu: "pushSubscribed",
-      Gd: "fallbackDevice",
+      Cf: "fallbackDevice",
       Vs: "cardUpdates",
-      pe: "optOut",
-      Br: "pendingData",
-      wh: "sdkAuthenticationSignature",
+      ke: "optOut",
+      Dr: "pendingData",
+      ac: "sdkAuthenticationSignature",
     },
-    be: 1,
+    ze: 1,
   },
 };