flowgrid-sdk 1.6.3 → 1.6.5

package/dist/lib/helpers/identity.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * @fileoverview Drop-in identity helpers.
+ * @module helpers/identity
+ *
+ * @description
+ * Stable, SSR-safe IDs that most apps need to wire up tracking, exposed as
+ * plain functions so you never have to re-implement the localStorage /
+ * sessionStorage boilerplate yourself.
+ *
+ * ```ts
+ * import { getOrCreateAnonId, getOrCreateCartId } from "flowgrid-sdk";
+ *
+ * fg.products.view(product, { userId: getOrCreateAnonId() });
+ * fg.cart.add(product, 1, getOrCreateCartId());
+ * ```
+ *
+ * Both helpers degrade gracefully: during SSR or when storage is blocked
+ * (private mode, strict cookie settings) they return a safe fallback instead
+ * of throwing, so they're safe to call anywhere.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOrCreateAnonId = getOrCreateAnonId;
+exports.getOrCreateCartId = getOrCreateCartId;
+exports.resetCartId = resetCartId;
+/** localStorage key for the anonymous visitor ID. Shared with the experiment engine. */
+const ANON_ID_KEY = "fg_anon_id";
+/** sessionStorage key for the per-session cart ID. */
+const CART_ID_KEY = "fg_cart_id";
+/**
+ * UUID v4 with a non-crypto fallback for ancient/locked-down runtimes.
+ * `crypto.randomUUID()` is preferred when available.
+ */
+function uuid() {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+        return crypto.randomUUID();
+    }
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        return (c === "x" ? r : (r & 0x3) | 0x8).toString(16);
+    });
+}
+/**
+ * Returns a stable anonymous visitor ID, generating and persisting one in
+ * `localStorage` on first call. The same value is reused across page loads so
+ * a returning visitor is recognised as the same person.
+ *
+ * Uses the same `fg_anon_id` key as the experiment engine, so the IDs line up
+ * across tracking calls and A/B test assignments.
+ *
+ * @returns The persisted anonymous ID, or `"anon"` when storage is unavailable.
+ */
+function getOrCreateAnonId() {
+    if (typeof localStorage === "undefined")
+        return "anon";
+    try {
+        const existing = localStorage.getItem(ANON_ID_KEY);
+        if (existing)
+            return existing;
+        const id = uuid();
+        localStorage.setItem(ANON_ID_KEY, id);
+        return id;
+    }
+    catch {
+        return "anon";
+    }
+}
+/**
+ * Returns a stable cart ID for the lifetime of the browser session, generating
+ * and persisting one in `sessionStorage` on first call. Pair this with cart and
+ * checkout events so every line item shares the same `cartId`.
+ *
+ * @returns The persisted cart ID (prefixed `cart_`), or `"cart_anon"` when
+ *          storage is unavailable.
+ */
+function getOrCreateCartId() {
+    if (typeof sessionStorage === "undefined")
+        return "cart_anon";
+    try {
+        const existing = sessionStorage.getItem(CART_ID_KEY);
+        if (existing)
+            return existing;
+        const id = `cart_${uuid()}`;
+        sessionStorage.setItem(CART_ID_KEY, id);
+        return id;
+    }
+    catch {
+        return "cart_anon";
+    }
+}
+/**
+ * Clears the persisted cart ID so the next {@link getOrCreateCartId} call starts
+ * a fresh cart. Call this after a completed purchase.
+ */
+function resetCartId() {
+    try {
+        if (typeof sessionStorage !== "undefined")
+            sessionStorage.removeItem(CART_ID_KEY);
+    }
+    catch {
+        /* SSR or privacy mode */
+    }
+}
+//# sourceMappingURL=identity.js.map

package/dist/lib/helpers/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../../src/lib/helpers/identity.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;AAgCH,8CAWC;AAUD,8CAWC;AAMD,kCAMC;AA1ED,wFAAwF;AACxF,MAAM,WAAW,GAAG,YAAY,CAAC;AAEjC,sDAAsD;AACtD,MAAM,WAAW,GAAG,YAAY,CAAC;AAEjC;;;GAGG;AACH,SAAS,IAAI;IACX,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QAC7E,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC;IAC7B,CAAC;IACD,OAAO,sCAAsC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;QACnE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,iBAAiB;IAC/B,IAAI,OAAO,YAAY,KAAK,WAAW;QAAE,OAAO,MAAM,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC;QAClB,YAAY,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QACtC,OAAO,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,iBAAiB;IAC/B,IAAI,OAAO,cAAc,KAAK,WAAW;QAAE,OAAO,WAAW,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QACrD,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,MAAM,EAAE,GAAG,QAAQ,IAAI,EAAE,EAAE,CAAC;QAC5B,cAAc,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QACxC,OAAO,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAgB,WAAW;IACzB,IAAI,CAAC;QACH,IAAI,OAAO,cAAc,KAAK,WAAW;YAAE,cAAc,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IACpF,CAAC;IAAC,MAAM,CAAC;QACP,yBAAyB;IAC3B,CAAC;AACH,CAAC"}

package/dist/lib/helpers/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Drop-in helpers.
+ * @module helpers
+ *
+ * @description
+ * Small, framework-agnostic convenience functions for the things almost every
+ * integration needs — stable IDs and consent wiring — so you can import them
+ * directly instead of re-implementing the boilerplate in every app.
+ *
+ * ```ts
+ * import {
+ *   getOrCreateAnonId,
+ *   getOrCreateCartId,
+ *   setupConsent,
+ *   attachConsentBanner,
+ * } from "flowgrid-sdk";
+ * ```
+ */
+export { getOrCreateAnonId, getOrCreateCartId, resetCartId } from "./identity";
+export { setupConsent, attachConsentBanner } from "./consent";
+export type { ConsentBannerOptions, ConsentBannerHandle } from "./consent";

package/dist/lib/helpers/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * @fileoverview Drop-in helpers.
+ * @module helpers
+ *
+ * @description
+ * Small, framework-agnostic convenience functions for the things almost every
+ * integration needs — stable IDs and consent wiring — so you can import them
+ * directly instead of re-implementing the boilerplate in every app.
+ *
+ * ```ts
+ * import {
+ *   getOrCreateAnonId,
+ *   getOrCreateCartId,
+ *   setupConsent,
+ *   attachConsentBanner,
+ * } from "flowgrid-sdk";
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachConsentBanner = exports.setupConsent = exports.resetCartId = exports.getOrCreateCartId = exports.getOrCreateAnonId = void 0;
+var identity_1 = require("./identity");
+Object.defineProperty(exports, "getOrCreateAnonId", { enumerable: true, get: function () { return identity_1.getOrCreateAnonId; } });
+Object.defineProperty(exports, "getOrCreateCartId", { enumerable: true, get: function () { return identity_1.getOrCreateCartId; } });
+Object.defineProperty(exports, "resetCartId", { enumerable: true, get: function () { return identity_1.resetCartId; } });
+var consent_1 = require("./consent");
+Object.defineProperty(exports, "setupConsent", { enumerable: true, get: function () { return consent_1.setupConsent; } });
+Object.defineProperty(exports, "attachConsentBanner", { enumerable: true, get: function () { return consent_1.attachConsentBanner; } });
+//# sourceMappingURL=index.js.map

package/dist/lib/helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/helpers/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAEH,uCAA+E;AAAtE,6GAAA,iBAAiB,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AAAE,uGAAA,WAAW,OAAA;AAC1D,qCAA8D;AAArD,uGAAA,YAAY,OAAA;AAAE,8GAAA,mBAAmB,OAAA"}

package/dist/lib/tracking/core/experiment.d.ts

@@ -62,6 +62,18 @@ export declare class ExperimentTracker {
      * Call this when the variant is rendered.
      */
     exposure(experimentId: string, userId: string, variantId: string): Promise<import("../../..").ExperimentResponse>;
+    /**
+     * Browser-side exposure for the locally-assigned variant — resolves both the
+     * variant and the user id for you. Call this right after rendering the
+     * variant; no-op if the visitor has no assignment yet.
+     *
+     * @example
+     * ```ts
+     * await fg.experiments.init([{ id: "checkout_v2", variants: [...] }]);
+     * await fg.experiments.exposureAuto("checkout_v2");
+     * ```
+     */
+    exposureAuto(experimentId: string): Promise<void>;
     /**
      * Record a conversion against a specific user's variant (server-side).
      *

package/dist/lib/tracking/core/experiment.js

@@ -63,6 +63,20 @@ class ExperimentTracker {
     exposure(experimentId, userId, variantId) {
         return this.client.trackExposure(experimentId, userId, variantId);
     }
+    /**
+     * Browser-side exposure for the locally-assigned variant — resolves both the
+     * variant and the user id for you. Call this right after rendering the
+     * variant; no-op if the visitor has no assignment yet.
+     *
+     * @example
+     * ```ts
+     * await fg.experiments.init([{ id: "checkout_v2", variants: [...] }]);
+     * await fg.experiments.exposureAuto("checkout_v2");
+     * ```
+     */
+    exposureAuto(experimentId) {
+        return this.client.trackLocalExposure(experimentId);
+    }
     /**
      * Record a conversion against a specific user's variant (server-side).
      *

package/dist/lib/tracking/core/experiment.js.map

@@ -1 +1 @@
-{"version":3,"file":"experiment.js","sourceRoot":"","sources":["../../../../src/lib/tracking/core/experiment.ts"],"names":[],"mappings":";;;AA2BA,MAAa,iBAAiB;IAC5B,YAA4B,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAElD,8EAA8E;IAC9E,QAAQ;IACR,8EAA8E;IAE9E;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,UAAgC;QACrC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,WAAmC;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;IAClD,CAAC;IAED,8EAA8E;IAC9E,aAAa;IACb,8EAA8E;IAE9E;;;OAGG;IACH,OAAO,CAAC,YAAoB;QAC1B,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;IACnD,CAAC;IAED;;;OAGG;IACH,MAAM,CACJ,YAAoB,EACpB,MAAc,EACd,SAAiB,EACjB,SAA6C,UAAU;QAEvD,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,8EAA8E;IAC9E,wBAAwB;IACxB,8EAA8E;IAE9E;;;OAGG;IACH,QAAQ,CAAC,YAAoB,EAAE,MAAc,EAAE,SAAiB;QAC9D,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;OAOG;IACH,UAAU,CACR,YAAoB,EACpB,MAAc,EACd,SAAiB,EACjB,UAAkB,EAClB,QAAgB,CAAC;QAEjB,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC;YACjC,YAAY;YACZ,MAAM;YACN,SAAS;YACT,UAAU;YACV,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,YAAoB,EAAE,aAAqB,YAAY,EAAE,QAAgB,CAAC;QACxF,OAAO,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,YAAY,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IAC3E,CAAC;IAED,8EAA8E;IAC9E,yBAAyB;IACzB,EAAE;IACF,sEAAsE;IACtE,wEAAwE;IACxE,uEAAuE;IACvE,8EAA8E;IAE9E;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,MAA0B;QAC3C,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,uBAAuB,CAAC,YAAuC;QAC7D,IAAI,CAAC,MAAM,CAAC,uBAAuB,CAAC,YAAY,CAAC,CAAC;IACpD,CAAC;IAED;;;OAGG;IACH,iBAAiB,CAAC,WAAmC;QACnD,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;IACtC,CAAC;IAED;;;;;;;;OAQG;IACH,yBAAyB;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC,yBAAyB,EAAE,CAAC;IACjD,CAAC;IAED,mEAAmE;IACnE,gBAAgB;QACd,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;IACjC,CAAC;CACF;AA9KD,8CA8KC"}
+{"version":3,"file":"experiment.js","sourceRoot":"","sources":["../../../../src/lib/tracking/core/experiment.ts"],"names":[],"mappings":";;;AA2BA,MAAa,iBAAiB;IAC5B,YAA4B,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAElD,8EAA8E;IAC9E,QAAQ;IACR,8EAA8E;IAE9E;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,UAAgC;QACrC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,WAAmC;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;IAClD,CAAC;IAED,8EAA8E;IAC9E,aAAa;IACb,8EAA8E;IAE9E;;;OAGG;IACH,OAAO,CAAC,YAAoB;QAC1B,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;IACnD,CAAC;IAED;;;OAGG;IACH,MAAM,CACJ,YAAoB,EACpB,MAAc,EACd,SAAiB,EACjB,SAA6C,UAAU;QAEvD,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,8EAA8E;IAC9E,wBAAwB;IACxB,8EAA8E;IAE9E;;;OAGG;IACH,QAAQ,CAAC,YAAoB,EAAE,MAAc,EAAE,SAAiB;QAC9D,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;;;;OAUG;IACH,YAAY,CAAC,YAAoB;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAC;IACtD,CAAC;IAED;;;;;;;OAOG;IACH,UAAU,CACR,YAAoB,EACpB,MAAc,EACd,SAAiB,EACjB,UAAkB,EAClB,QAAgB,CAAC;QAEjB,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC;YACjC,YAAY;YACZ,MAAM;YACN,SAAS;YACT,UAAU;YACV,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,YAAoB,EAAE,aAAqB,YAAY,EAAE,QAAgB,CAAC;QACxF,OAAO,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,YAAY,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IAC3E,CAAC;IAED,8EAA8E;IAC9E,yBAAyB;IACzB,EAAE;IACF,sEAAsE;IACtE,wEAAwE;IACxE,uEAAuE;IACvE,8EAA8E;IAE9E;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,MAA0B;QAC3C,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,uBAAuB,CAAC,YAAuC;QAC7D,IAAI,CAAC,MAAM,CAAC,uBAAuB,CAAC,YAAY,CAAC,CAAC;IACpD,CAAC;IAED;;;OAGG;IACH,iBAAiB,CAAC,WAAmC;QACnD,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;IACtC,CAAC;IAED;;;;;;;;OAQG;IACH,yBAAyB;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC,yBAAyB,EAAE,CAAC;IACjD,CAAC;IAED,mEAAmE;IACnE,gBAAgB;QACd,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;IACjC,CAAC;CACF;AA7LD,8CA6LC"}