@shipeasy/sdk 5.0.0 → 5.2.0

package/dist/client/index.mjs

@@ -310,6 +310,14 @@ var SeeLimiter = class {
 
 // src/client/index.ts
 var version = "4.0.0";
+var FLAG_REASONS = [
+  "CLIENT_NOT_READY",
+  "FLAG_NOT_FOUND",
+  "OFF",
+  "OVERRIDE",
+  "RULE_MATCH",
+  "DEFAULT"
+];
 var FLUSH_INTERVAL_MS = 5e3;
 var MAX_BUFFER = 100;
 var ANON_ID_KEY = "__se_anon_id";
@@ -674,6 +682,40 @@ function writeAnonCookie(id) {
   } catch {
   }
 }
+var STICKY_COOKIE = "__se_sticky";
+var STICKY_MAX_BYTES = 3800;
+function readStickyCookie() {
+  try {
+    const m = ("; " + document.cookie).match(/; __se_sticky=([^;]+)/);
+    if (!m) return {};
+    const parsed = JSON.parse(decodeURIComponent(m[1]));
+    if (!parsed || typeof parsed !== "object") return {};
+    const out = {};
+    for (const [k, v] of Object.entries(parsed)) {
+      if (v && typeof v === "object" && typeof v.g === "string") {
+        out[k] = { g: v.g, s: String(v.s ?? "") };
+      }
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+function writeStickyCookie(map) {
+  try {
+    let json = JSON.stringify(map);
+    if (json.length > STICKY_MAX_BYTES) {
+      const entries = Object.entries(map);
+      while (entries.length > 0 && JSON.stringify(Object.fromEntries(entries)).length > STICKY_MAX_BYTES) {
+        entries.shift();
+      }
+      json = JSON.stringify(Object.fromEntries(entries));
+    }
+    const secure = location.protocol === "https:" ? ";secure" : "";
+    document.cookie = `${STICKY_COOKIE}=${encodeURIComponent(json)};path=/;max-age=31536000;samesite=lax${secure}`;
+  } catch {
+  }
+}
 function getOrCreateAnonId() {
   let id = readAnonCookie();
   if (!id && typeof window !== "undefined") {
@@ -821,12 +863,15 @@ function readExperimentOverridesFromUrl() {
   }
   return out;
 }
-var FlagsClientBrowser = class {
+var FlagsClientBrowser = class _FlagsClientBrowser {
   sdkKey;
   baseUrl;
   autoGuardrails;
   autoGuardrailGroups;
   autoCollectAlways;
+  disableAutoExposure;
+  privateAttributes;
+  stickyBucketing;
   env;
   evalResult = null;
   anonId;
@@ -840,6 +885,16 @@ var FlagsClientBrowser = class {
   // Monotonic counter so a later identify() always wins even if its /sdk/evaluate
   // response races and lands before an earlier in-flight call's response.
   identifySeq = 0;
+  // Test mode: built by `FlagsClientBrowser.forTesting()`. When set, identify()
+  // never fetches, track() is a no-op, telemetry is off, and the client is
+  // already ready with an empty eval result.
+  testMode;
+  // Programmatic overrides (Statsig-style). Set on any client via
+  // overrideFlag/overrideConfig/overrideExperiment; they win over BOTH the URL
+  // overrides and the fetched eval result. Cleared by clearOverrides().
+  flagOverrides = /* @__PURE__ */ new Map();
+  configOverrides = /* @__PURE__ */ new Map();
+  experimentOverrides = /* @__PURE__ */ new Map();
   onOverrideChange = () => {
     this.installBridge();
     this.notify();
@@ -848,8 +903,12 @@ var FlagsClientBrowser = class {
     this.sdkKey = opts.sdkKey;
     this.baseUrl = (opts.baseUrl ?? "https://edge.shipeasy.dev").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
+    this.testMode = opts.testMode === true;
     this.autoGuardrails = opts.autoGuardrails !== false;
     this.autoCollectAlways = opts.autoCollectAlways === true;
+    this.disableAutoExposure = opts.disableAutoExposure === true;
+    this.privateAttributes = opts.privateAttributes ?? [];
+    this.stickyBucketing = opts.stickyBucketing !== false;
     const g = opts.autoGuardrailGroups ?? {};
     this.autoGuardrailGroups = {
       vitals: g.vitals ?? this.autoGuardrails,
@@ -863,11 +922,42 @@ var FlagsClientBrowser = class {
       sdkKey: this.sdkKey,
       side: "client",
       env: this.env,
-      disabled: opts.disableTelemetry
+      // Test mode never talks to the network — telemetry off regardless of opt.
+      disabled: this.testMode || opts.disableTelemetry
+    });
+    if (this.testMode) {
+      this.evalResult = { flags: {}, configs: {}, experiments: {}, killswitches: {} };
+    } else {
+      void this.buffer.flushPendingAlias();
+    }
+  }
+  /**
+   * Build a no-network, immediately-usable browser client for tests
+   * (Statsig-style). identify() is a no-op (never calls /sdk/evaluate), track()
+   * is a no-op, telemetry is disabled, and the client is already ready — seed
+   * every entity with overrideFlag/overrideConfig/overrideExperiment. No SDK
+   * key required.
+   *
+   * ```ts
+   * const client = FlagsClientBrowser.forTesting();
+   * client.overrideFlag("new_checkout", true);
+   * client.getFlag("new_checkout"); // true
+   * ```
+   */
+  static forTesting(opts) {
+    return new _FlagsClientBrowser({
+      sdkKey: "",
+      autoGuardrails: false,
+      ...opts,
+      testMode: true
     });
-    void this.buffer.flushPendingAlias();
   }
   async identify(user) {
+    if (this.testMode) {
+      if (user.user_id !== void 0) this.userId = user.user_id;
+      this.notify();
+      return;
+    }
     const seq = ++this.identifySeq;
     const prevUserId = this.userId;
     if (user.user_id !== void 0) this.userId = user.user_id;
@@ -884,13 +974,22 @@ var FlagsClientBrowser = class {
       headers: { "X-SDK-Key": this.sdkKey, "Content-Type": "application/json" },
       body: JSON.stringify({
         user: userPayload,
-        experiment_overrides: readExperimentOverridesFromUrl()
+        experiment_overrides: readExperimentOverridesFromUrl(),
+        // Private attributes still reach the edge for evaluation (unavoidable —
+        // the edge evaluates), but the worker never persists them. See doc 20 §5.
+        ...this.privateAttributes.length > 0 ? { private_attributes: [...this.privateAttributes] } : {},
+        // Sticky state round-trip: send the current cookie map; the worker
+        // applies the sticky short-circuit and returns any new assignments.
+        ...this.stickyBucketing ? { sticky: readStickyCookie() } : {}
       })
     });
     if (!res.ok) throw new Error(`/sdk/evaluate returned ${res.status}`);
     const data = await res.json();
     if (seq !== this.identifySeq) return;
     this.evalResult = data;
+    if (this.stickyBucketing && data.sticky && Object.keys(data.sticky).length > 0) {
+      writeStickyCookie({ ...readStickyCookie(), ...data.sticky });
+    }
     const anyGroupOn = this.autoGuardrailGroups.vitals || this.autoGuardrailGroups.errors || this.autoGuardrailGroups.engagement;
     if (anyGroupOn && !this.guardrailsInstalled) {
       this.guardrailsInstalled = true;
@@ -942,34 +1041,95 @@ var FlagsClientBrowser = class {
   initFromBootstrap(data) {
     this.evalResult = data;
   }
-  getFlag(name) {
+  // ---- Local overrides (Statsig-style) ----
+  //
+  // Precedence (highest first): programmatic override (these methods) > URL
+  // override (?se_gate_/?se_config_/?se_exp_) > fetched eval result. A
+  // programmatic override is an explicit in-code decision, so it wins over the
+  // ad-hoc URL/devtools overrides as well as the server's evaluation.
+  /** Force `getFlag(name)` to return `value`, ignoring URL overrides + eval. */
+  overrideFlag(name, value) {
+    this.flagOverrides.set(name, value);
+  }
+  /** Force `getConfig(name)` to return `value`, ignoring URL overrides + eval. */
+  overrideConfig(name, value) {
+    this.configOverrides.set(name, value);
+  }
+  /**
+   * Force `getExperiment(name, …)` to return `{ inExperiment: true, group, params }`,
+   * ignoring URL overrides, the eval result, and exposure logging.
+   */
+  overrideExperiment(name, group, params) {
+    this.experimentOverrides.set(name, { group, params });
+  }
+  /** Remove every programmatic override set via the override* methods. */
+  clearOverrides() {
+    this.flagOverrides.clear();
+    this.configOverrides.clear();
+    this.experimentOverrides.clear();
+  }
+  /**
+   * Evaluate a gate and report WHY (LaunchDarkly variationDetail parity). A
+   * local override OR a ?se_gate_/?se_ks_ URL override short-circuits BEFORE
+   * telemetry; otherwise exactly one "gate" beacon is emitted. The server
+   * pre-evaluates a gate's enabled/killed state into a plain boolean, so OFF
+   * folds into DEFAULT here (the browser can't tell "disabled" from "rule
+   * denied").
+   */
+  getFlagDetail(name) {
+    const pov = this.flagOverrides.get(name);
+    if (pov !== void 0) return { value: pov, reason: "OVERRIDE" };
+    const urlOv = readGateOverride(name);
+    if (urlOv !== null) return { value: urlOv, reason: "OVERRIDE" };
     this.telemetry.emit("gate", name);
-    if (this.evalResult === null) return false;
-    const ov = readGateOverride(name);
-    if (ov !== null) return ov;
-    return this.evalResult.flags[name] ?? false;
+    if (this.evalResult === null) return { value: false, reason: "CLIENT_NOT_READY" };
+    if (!(name in this.evalResult.flags)) return { value: false, reason: "FLAG_NOT_FOUND" };
+    const value = this.evalResult.flags[name] ?? false;
+    return { value, reason: value ? "RULE_MATCH" : "DEFAULT" };
   }
-  getConfig(name, decode) {
+  /**
+   * Read a feature gate. Returns `defaultValue` ONLY when the gate cannot be
+   * evaluated (not ready or flag not found) — never for a gate that legitimately
+   * evaluates to false. Plain `getFlag(name)` keeps returning false for a
+   * missing flag.
+   */
+  getFlag(name, defaultValue = false) {
+    const d = this.getFlagDetail(name);
+    if (d.reason === "CLIENT_NOT_READY" || d.reason === "FLAG_NOT_FOUND") return defaultValue;
+    return d.value;
+  }
+  getConfig(name, decodeOrOpts) {
     this.telemetry.emit("config", name);
-    if (this.evalResult === null) return void 0;
-    const ov = readConfigOverride(name);
-    const raw = ov !== void 0 ? ov : this.evalResult.configs?.[name];
-    if (raw === void 0) return void 0;
-    if (!decode) return raw;
+    const opts = typeof decodeOrOpts === "function" ? { decode: decodeOrOpts } : decodeOrOpts ?? {};
+    const fallback = "defaultValue" in opts ? opts.defaultValue : void 0;
+    const hasProgrammatic = this.configOverrides.has(name);
+    if (!hasProgrammatic && this.evalResult === null) return fallback;
+    const urlOv = hasProgrammatic ? void 0 : readConfigOverride(name);
+    const raw = hasProgrammatic ? this.configOverrides.get(name) : urlOv !== void 0 ? urlOv : this.evalResult?.configs?.[name];
+    if (raw === void 0) return fallback;
+    if (!opts.decode) return raw;
     try {
-      return decode(raw);
+      return opts.decode(raw);
     } catch (err) {
       console.warn(`[shipeasy] getConfig('${name}') decode failed:`, String(err));
       return void 0;
     }
   }
-  getExperiment(name, defaultParams, decode, variants) {
+  getExperiment(name, defaultParams, decodeOrOpts, variantsArg) {
+    const opts = typeof decodeOrOpts === "function" ? { decode: decodeOrOpts, variants: variantsArg } : decodeOrOpts ?? {};
+    const { decode, variants } = opts;
     this.telemetry.emit("experiment", name);
     const notIn = {
       inExperiment: false,
       group: "control",
       params: defaultParams
     };
+    const pov = this.experimentOverrides.get(name);
+    if (pov) {
+      const variantParams = variants?.[pov.group];
+      const params = { ...defaultParams, ...pov.params, ...variantParams ?? {} };
+      return { inExperiment: true, group: pov.group, params };
+    }
     const ov = readExpOverride(name);
     if (ov !== null) {
       const variantParams = variants?.[ov];
@@ -978,7 +1138,8 @@ var FlagsClientBrowser = class {
     }
     const entry = this.evalResult?.experiments[name];
     if (!entry || !entry.inExperiment) return notIn;
-    this.buffer.pushExposure(name, entry.group, this.userId, this.anonId);
+    const shouldLog = opts.logExposure ?? !this.disableAutoExposure;
+    if (shouldLog) this.buffer.pushExposure(name, entry.group, this.userId, this.anonId);
     if (!decode) return { inExperiment: true, group: entry.group, params: entry.params };
     try {
       return { inExperiment: true, group: entry.group, params: decode(entry.params) };
@@ -987,6 +1148,18 @@ var FlagsClientBrowser = class {
       return notIn;
     }
   }
+  /**
+   * Manually log an exposure for an enrolled experiment (Statsig's
+   * `manuallyLogExposure`). Reads the cached eval result; if the visitor is in
+   * the experiment, pushes the session-deduped exposure. Pair this with the
+   * render of the treatment when reading with `{ logExposure: false }` (or
+   * `disableAutoExposure: true`). No-op if the visitor isn't enrolled.
+   */
+  logExposure(name) {
+    const entry = this.evalResult?.experiments[name];
+    if (!entry || !entry.inExperiment) return;
+    this.buffer.pushExposure(name, entry.group, this.userId, this.anonId);
+  }
   /**
    * Subscribe to state changes — fires after identify() completes and on
    * `se:override:change` events from the devtools overlay. Returns an
@@ -1021,7 +1194,17 @@ var FlagsClientBrowser = class {
     return bridge;
   }
   track(eventName, props) {
-    this.buffer.pushMetric(eventName, this.userId, this.anonId, props);
+    if (this.testMode) return;
+    this.buffer.pushMetric(eventName, this.userId, this.anonId, this.stripPrivate(props));
+  }
+  /** Drop caller-marked private attributes from an outbound props bag. */
+  stripPrivate(props) {
+    if (!props || this.privateAttributes.length === 0) return props;
+    const out = {};
+    for (const [k, v] of Object.entries(props)) {
+      if (!this.privateAttributes.includes(k)) out[k] = v;
+    }
+    return out;
   }
   /**
    * Read a killswitch from the server's evaluated state. Without `switchKey`,
@@ -1167,7 +1350,10 @@ function shipeasy(opts) {
     autoGuardrails: blanket,
     autoGuardrailGroups: groups,
     autoCollectAlways: acObj?.always === true,
-    disableTelemetry: opts.disableTelemetry
+    disableTelemetry: opts.disableTelemetry,
+    disableAutoExposure: opts.disableAutoExposure,
+    privateAttributes: opts.privateAttributes,
+    stickyBucketing: opts.stickyBucketing
   });
   injectI18nLoader(opts.clientKey, baseUrl, opts.i18nProfile);
   flags.notifyMounted();
@@ -1239,12 +1425,19 @@ var flags = {
    * Everything else gates on _mountedAndReady to prevent hydration mismatches on
    * force-static pages where SSR has no flag data.
    */
-  get(name) {
+  get(name, defaultValue = false) {
     const bs = getBootstrap();
     if (bs !== null && name in bs.flags) return bs.flags[name];
-    if (!_mountedAndReady) return false;
-    if (_client) return _client.getFlag(name);
-    return readGateOverride(name) ?? false;
+    if (!_mountedAndReady) return defaultValue;
+    if (_client) return _client.getFlag(name, defaultValue);
+    return readGateOverride(name) ?? defaultValue;
+  },
+  /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
+  getDetail(name) {
+    if (_client) return _client.getFlagDetail(name);
+    const ov = readGateOverride(name);
+    if (ov !== null) return { value: ov, reason: "OVERRIDE" };
+    return { value: false, reason: "CLIENT_NOT_READY" };
   },
   getConfig(name, decode) {
     const bs = getBootstrap();
@@ -1268,12 +1461,19 @@ var flags = {
       return void 0;
     }
   },
-  getExperiment(name, defaultParams, decode, variants) {
-    return _client?.getExperiment(name, defaultParams, decode, variants) ?? {
+  getExperiment(name, defaultParams, decodeOrOpts, variants) {
+    const fallback = {
       inExperiment: false,
       group: "control",
       params: defaultParams
     };
+    if (!_client) return fallback;
+    return typeof decodeOrOpts === "function" ? _client.getExperiment(name, defaultParams, decodeOrOpts, variants) : _client.getExperiment(name, defaultParams, decodeOrOpts ?? {});
+  },
+  /** Manually log an exposure for an enrolled experiment. See
+   *  {@link FlagsClientBrowser.logExposure}. No-op before configure(). */
+  logExposure(name) {
+    _client?.logExposure(name);
   },
   track(eventName, props) {
     _client?.track(eventName, props);
@@ -1575,6 +1775,7 @@ var i18n = {
   }
 };
 export {
+  FLAG_REASONS,
   FlagsClientBrowser,
   LABEL_MARKER_END,
   LABEL_MARKER_RE,