@shipeasy/sdk 5.0.0 → 5.2.0

package/dist/server/index.js

@@ -31,9 +31,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var server_exports = {};
 __export(server_exports, {
   ANON_ID_COOKIE: () => ANON_ID_COOKIE,
+  FLAG_REASONS: () => FLAG_REASONS,
   FlagsClient: () => FlagsClient,
+  _murmur3ForTests: () => _murmur3ForTests,
   _resetShipeasyServerForTests: () => _resetShipeasyServerForTests,
   configureShipeasyServer: () => configureShipeasyServer,
+  createInMemoryStickyStore: () => createInMemoryStickyStore,
   fetchLabelsForSSR: () => fetchLabelsForSSR,
   flags: () => flags,
   getBootstrapHtml: () => getBootstrapHtml,
@@ -362,6 +365,9 @@ var SeeLimiter = class {
 var version = "4.0.0";
 var C1 = 3432918353;
 var C2 = 461845907;
+function _murmur3ForTests(key) {
+  return murmur3(key);
+}
 function murmur3(key) {
   const bytes = new TextEncoder().encode(key);
   const len = bytes.length;
@@ -402,6 +408,25 @@ function murmur3(key) {
   h1 ^= h1 >>> 16;
   return h1 >>> 0;
 }
+var FLAG_REASONS = [
+  "CLIENT_NOT_READY",
+  "FLAG_NOT_FOUND",
+  "OFF",
+  "OVERRIDE",
+  "RULE_MATCH",
+  "DEFAULT"
+];
+function createInMemoryStickyStore(seed) {
+  const m = new Map(Object.entries(seed ?? {}));
+  return {
+    get: (unit) => m.get(unit),
+    set: (unit, exp, entry) => {
+      const cur = m.get(unit) ?? {};
+      cur[exp] = entry;
+      m.set(unit, cur);
+    }
+  };
+}
 function isEnabled(v) {
   return v === 1 || v === true;
 }
@@ -454,6 +479,14 @@ var ANON_ID_RX = /^[A-Za-z0-9_-]{1,64}$/;
 function mintAnonId() {
   return typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `anon_${Math.random().toString(36).slice(2)}`;
 }
+function pickIdentifier(user, bucketBy) {
+  if (bucketBy) {
+    const v = user[bucketBy];
+    if (typeof v === "string" && v.length > 0) return v;
+    if (typeof v === "number") return String(v);
+  }
+  return user.user_id ?? user.anonymous_id;
+}
 function evalGateInternal(gate, user) {
   if (isEnabled(gate.killswitch)) return false;
   if (!isEnabled(gate.enabled)) return false;
@@ -509,10 +542,12 @@ function parseOverrides(rawUrl) {
   }
   return { gates, configs, experiments };
 }
-var FlagsClient = class {
+var FlagsClient = class _FlagsClient {
   apiKey;
   baseUrl;
   env;
+  privateAttributes;
+  stickyStore;
   telemetry;
   seeLimiter = new SeeLimiter();
   flagsBlob = null;
@@ -522,47 +557,157 @@ var FlagsClient = class {
   pollInterval = 30;
   timer = null;
   initialized = false;
+  // Test mode: built by `FlagsClient.forTesting()`. When set, init()/initOnce()
+  // never fetch, track() is a no-op, and telemetry is off — the client is a
+  // fully self-contained, network-free seam for unit tests.
+  testMode;
+  // Programmatic overrides (Statsig-style). Set on any client via
+  // overrideFlag/overrideConfig/overrideExperiment; they win over the fetched
+  // blob in getFlag/getConfig/getExperiment. Cleared by clearOverrides().
+  flagOverrides = /* @__PURE__ */ new Map();
+  configOverrides = /* @__PURE__ */ new Map();
+  experimentOverrides = /* @__PURE__ */ new Map();
+  // Change listeners fired after a background poll returns NEW data (200, not
+  // 304). Never fired in testMode/offline (no polling happens there).
+  changeListeners = /* @__PURE__ */ new Set();
   constructor(opts) {
     this.apiKey = opts.apiKey;
     this.baseUrl = (opts.baseUrl ?? "https://cdn.shipeasy.ai").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
+    this.privateAttributes = opts.privateAttributes ?? [];
+    this.stickyStore = opts.stickyStore;
+    this.testMode = opts.testMode === true;
     this.telemetry = new Telemetry({
       endpoint: opts.telemetryUrl ?? DEFAULT_TELEMETRY_URL,
       sdkKey: this.apiKey,
       side: "server",
       env: this.env,
-      disabled: opts.disableTelemetry
+      // Test mode never talks to the network — telemetry off regardless of opt.
+      disabled: this.testMode || opts.disableTelemetry
     });
-    if (opts.initialBlob) {
-      this.flagsBlob = opts.initialBlob;
+    if (opts.initialBlob || this.testMode) {
+      this.flagsBlob = opts.initialBlob ?? { version: "test", plan: "free", gates: {}, configs: {}, killswitches: {} };
+      this.expsBlob = this.expsBlob ?? { version: "test", universes: {}, experiments: {} };
       this.initialized = true;
     }
   }
+  /**
+   * Build a no-network, immediately-usable client for tests (Statsig-style).
+   * init()/initOnce() are no-ops (never fetch), track() is a no-op, telemetry
+   * is disabled, and the client is already "initialized" — seed every entity
+   * with overrideFlag/overrideConfig/overrideExperiment. No SDK key required.
+   *
+   * ```ts
+   * const client = FlagsClient.forTesting();
+   * client.overrideFlag("new_checkout", true);
+   * client.getFlag("new_checkout", { user_id: "u1" }); // true
+   * ```
+   */
+  static forTesting(opts) {
+    return new _FlagsClient({ apiKey: "", ...opts, testMode: true });
+  }
+  /**
+   * Build a fully OFFLINE client from a pre-captured snapshot — no network ever.
+   * Reuses the test-mode plumbing (init()/initOnce()/track() are no-ops,
+   * telemetry off) but, unlike forTesting(), seeds the REAL flags + experiments
+   * blobs so evaluations run the canonical eval against the snapshot. Local
+   * overrides still apply on top.
+   *
+   * Snapshot shape mirrors the wire bodies:
+   * `{ flags: <GET /sdk/flags body>, experiments: <GET /sdk/experiments body> }`.
+   */
+  static fromSnapshot(snapshot) {
+    const client = new _FlagsClient({ apiKey: "", testMode: true });
+    client.flagsBlob = snapshot.flags;
+    client.expsBlob = snapshot.experiments;
+    client.initialized = true;
+    return client;
+  }
+  /**
+   * Build a fully OFFLINE client from a snapshot JSON file on disk (Node only —
+   * not available in the browser entrypoint). The file must contain
+   * `{ "flags": <GET /sdk/flags body>, "experiments": <GET /sdk/experiments body> }`.
+   * See {@link FlagsClient.fromSnapshot}.
+   */
+  static fromFile(path) {
+    const fs = require("fs");
+    const raw = fs.readFileSync(path, "utf8");
+    const snapshot = JSON.parse(raw);
+    return _FlagsClient.fromSnapshot(snapshot);
+  }
   async init() {
+    if (this.testMode) {
+      this.initialized = true;
+      return;
+    }
     await this.fetchAll();
     this.initialized = true;
     this.startPoll();
   }
   async initOnce() {
-    if (this.initialized) return;
+    if (this.testMode || this.initialized) return;
     await this.fetchAll();
     this.initialized = true;
   }
+  // ---- Local overrides (Statsig-style) ----
+  /** Force `getFlag(name, …)` to return `value`, ignoring the fetched gate. */
+  overrideFlag(name, value) {
+    this.flagOverrides.set(name, value);
+  }
+  /** Force `getConfig(name)` to return `value`, ignoring the fetched config. */
+  overrideConfig(name, value) {
+    this.configOverrides.set(name, value);
+  }
+  /**
+   * Force `getExperiment(name, …)` to return `{ inExperiment: true, group, params }`,
+   * ignoring allocation, holdouts, and targeting.
+   */
+  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();
+  }
   destroy() {
     if (this.timer !== null) {
       clearInterval(this.timer);
       this.timer = null;
     }
   }
+  /**
+   * Subscribe to data-change notifications. The listener fires after a
+   * background poll fetch returns NEW data (200, not 304) — i.e. after the
+   * cached blob is updated. Never fires in testMode/offline (no polling).
+   * Returns an unsubscribe function.
+   */
+  onChange(listener) {
+    this.changeListeners.add(listener);
+    return () => {
+      this.changeListeners.delete(listener);
+    };
+  }
+  notifyChange() {
+    for (const l of this.changeListeners) {
+      try {
+        l();
+      } catch (err) {
+        console.warn("[shipeasy] onChange listener threw:", String(err));
+      }
+    }
+  }
   startPoll() {
     this.timer = setInterval(() => {
-      this.fetchAll().catch(
+      this.fetchAll(true).catch(
         (err) => console.warn("[shipeasy] background poll failed:", String(err))
       );
     }, this.pollInterval * 1e3);
   }
-  async fetchAll() {
-    const [interval] = await Promise.all([this.fetchFlags(), this.fetchExps()]);
+  async fetchAll(fromPoll = false) {
+    const [flagsRes, expsChanged] = await Promise.all([this.fetchFlags(), this.fetchExps()]);
+    const { interval, changed: flagsChanged } = flagsRes;
     if (interval !== null && interval !== this.pollInterval) {
       this.pollInterval = interval;
       if (this.timer !== null) {
@@ -570,41 +715,72 @@ var FlagsClient = class {
         this.startPoll();
       }
     }
+    if (fromPoll && (flagsChanged || expsChanged)) this.notifyChange();
   }
   async fetchFlags() {
     const headers = { "X-SDK-Key": this.apiKey };
     if (this.flagsEtag) headers["If-None-Match"] = this.flagsEtag;
     const res = await globalThis.fetch(`${this.baseUrl}/sdk/flags?env=${this.env}`, { headers });
     const interval = Number(res.headers.get("X-Poll-Interval") ?? "30") || 30;
-    if (res.status === 304) return interval;
+    if (res.status === 304) return { interval, changed: false };
     if (!res.ok) throw new Error(`/sdk/flags returned ${res.status}`);
     const etag = res.headers.get("ETag");
     if (etag) this.flagsEtag = etag;
     this.flagsBlob = await res.json();
-    return interval;
+    return { interval, changed: true };
   }
   async fetchExps() {
     const headers = { "X-SDK-Key": this.apiKey };
     if (this.expsEtag) headers["If-None-Match"] = this.expsEtag;
     const res = await globalThis.fetch(`${this.baseUrl}/sdk/experiments`, { headers });
-    if (res.status === 304) return;
+    if (res.status === 304) return false;
     if (!res.ok) throw new Error(`/sdk/experiments returned ${res.status}`);
     const etag = res.headers.get("ETag");
     if (etag) this.expsEtag = etag;
     this.expsBlob = await res.json();
+    return true;
   }
-  getFlag(name, user) {
+  /**
+   * Evaluate a gate and report WHY (LaunchDarkly variationDetail parity). The
+   * reason is computed entirely at this boundary — the canonical eval
+   * (evalGateInternal) is untouched. A local override short-circuits BEFORE
+   * telemetry, exactly like getFlag's override path; otherwise exactly one
+   * "gate" beacon is emitted.
+   */
+  getFlagDetail(name, user) {
+    const ov = this.flagOverrides.get(name);
+    if (ov !== void 0) return { value: ov, reason: "OVERRIDE" };
     this.telemetry.emit("gate", name);
-    const gate = this.flagsBlob?.gates[name];
-    if (!gate) return false;
-    return evalGateInternal(gate, user);
+    if (!this.flagsBlob) return { value: false, reason: "CLIENT_NOT_READY" };
+    const gate = this.flagsBlob.gates[name];
+    if (!gate) return { value: false, reason: "FLAG_NOT_FOUND" };
+    if (isEnabled(gate.killswitch) || !isEnabled(gate.enabled)) {
+      return { value: false, reason: "OFF" };
+    }
+    const value = evalGateInternal(gate, user);
+    return { value, reason: value ? "RULE_MATCH" : "DEFAULT" };
   }
-  getConfig(name, decode) {
+  /**
+   * Read a feature gate. Returns `defaultValue` ONLY when the gate cannot be
+   * evaluated (client not initialized or flag not found) — never for a gate that
+   * legitimately evaluates to false. Plain `getFlag(name, user)` keeps returning
+   * false for a missing flag.
+   */
+  getFlag(name, user, defaultValue = false) {
+    const d = this.getFlagDetail(name, user);
+    if (d.reason === "CLIENT_NOT_READY" || d.reason === "FLAG_NOT_FOUND") return defaultValue;
+    return d.value;
+  }
+  getConfig(name, decodeOrOpts) {
     this.telemetry.emit("config", name);
-    const entry = this.flagsBlob?.configs[name];
-    if (!entry) return void 0;
-    if (!decode) return entry.value;
-    return decode(entry.value);
+    const opts = typeof decodeOrOpts === "function" ? { decode: decodeOrOpts } : decodeOrOpts ?? {};
+    const has = this.configOverrides.has(name);
+    const raw = has ? this.configOverrides.get(name) : this.flagsBlob?.configs[name]?.value;
+    if (raw === void 0 && !has) {
+      return "defaultValue" in opts ? opts.defaultValue : void 0;
+    }
+    if (!opts.decode) return raw;
+    return opts.decode(raw);
   }
   getExperiment(name, user, defaultParams, decode) {
     this.telemetry.emit("experiment", name);
@@ -613,6 +789,16 @@ var FlagsClient = class {
       group: "control",
       params: defaultParams
     };
+    const ov = this.experimentOverrides.get(name);
+    if (ov) {
+      if (!decode) return { inExperiment: true, group: ov.group, params: ov.params };
+      try {
+        return { inExperiment: true, group: ov.group, params: decode(ov.params) };
+      } catch (err) {
+        console.warn(`[shipeasy] getExperiment('${name}') override decode failed:`, String(err));
+        return notIn;
+      }
+    }
     if (!this.flagsBlob || !this.expsBlob) return notIn;
     const exp = this.expsBlob.experiments[name];
     if (!exp || exp.status !== "running") return notIn;
@@ -620,7 +806,7 @@ var FlagsClient = class {
       const gate = this.flagsBlob.gates[exp.targetingGate];
       if (!gate || !evalGateInternal(gate, user)) return notIn;
     }
-    const uid = user.user_id ?? user.anonymous_id;
+    const uid = pickIdentifier(user, exp.bucketBy);
     if (!uid) return notIn;
     const universe = this.expsBlob.universes[exp.universe];
     const holdoutRange = universe?.holdout_range ?? null;
@@ -629,6 +815,23 @@ var FlagsClient = class {
       const [lo, hi] = holdoutRange;
       if (seg >= lo && seg <= hi) return notIn;
     }
+    const asResult = (g) => {
+      if (!decode) return { inExperiment: true, group: g.name, params: g.params };
+      try {
+        return { inExperiment: true, group: g.name, params: decode(g.params) };
+      } catch (err) {
+        console.warn(`[shipeasy] getExperiment('${name}') decode failed:`, String(err));
+        return notIn;
+      }
+    };
+    const salt8 = exp.salt.slice(0, 8);
+    if (this.stickyStore) {
+      const entry = this.stickyStore.get(uid)?.[name];
+      if (entry && entry.s === salt8) {
+        const g = exp.groups.find((x) => x.name === entry.g);
+        if (g) return asResult(g);
+      }
+    }
     if (murmur3(`${exp.salt}:alloc:${uid}`) % 1e4 >= exp.allocationPct) return notIn;
     const groupHash = murmur3(`${exp.salt}:group:${uid}`) % 1e4;
     let cumulative = 0;
@@ -636,20 +839,24 @@ var FlagsClient = class {
       const g = exp.groups[i];
       cumulative += g.weight;
       if (groupHash < cumulative || i === exp.groups.length - 1) {
-        if (!decode) {
-          return { inExperiment: true, group: g.name, params: g.params };
-        }
-        try {
-          return { inExperiment: true, group: g.name, params: decode(g.params) };
-        } catch (err) {
-          console.warn(`[shipeasy] getExperiment('${name}') decode failed:`, String(err));
-          return notIn;
-        }
+        this.stickyStore?.set(uid, name, { g: g.name, s: salt8 });
+        return asResult(g);
       }
     }
     return notIn;
   }
+  /** 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;
+  }
   track(userId, eventName, props) {
+    if (this.testMode) return;
+    const safeProps = this.stripPrivate(props);
     const body = JSON.stringify({
       events: [
         {
@@ -657,7 +864,7 @@ var FlagsClient = class {
           event_name: eventName,
           user_id: userId,
           ts: Date.now(),
-          ...props !== void 0 ? { properties: props } : {}
+          ...safeProps !== void 0 ? { properties: safeProps } : {}
         }
       ]
     });
@@ -667,6 +874,37 @@ var FlagsClient = class {
       body
     }).catch((err) => console.warn("[shipeasy] track failed:", String(err)));
   }
+  /**
+   * Emit an exposure event for an experiment at the server-side decision point
+   * (parity with the browser's auto-exposure). The server is stateless and
+   * never auto-logs, so call this when you actually present the treatment.
+   * Re-evaluates the experiment for `user` (a bare `user_id` string is wrapped
+   * as `{ user_id }`); if the user is enrolled, POSTs a single exposure to
+   * `/collect`. No-op in test mode or when the user isn't enrolled.
+   */
+  logExposure(user, name) {
+    if (this.testMode) return;
+    const u = typeof user === "string" ? { user_id: user } : user;
+    const result = this.getExperiment(name, u, {});
+    if (!result.inExperiment) return;
+    const body = JSON.stringify({
+      events: [
+        {
+          type: "exposure",
+          experiment: name,
+          group: result.group,
+          ...u.user_id !== void 0 ? { user_id: u.user_id } : {},
+          ...u.anonymous_id !== void 0 ? { anonymous_id: u.anonymous_id } : {},
+          ts: Date.now()
+        }
+      ]
+    });
+    globalThis.fetch(`${this.baseUrl}/collect`, {
+      method: "POST",
+      headers: { "X-SDK-Key": this.apiKey, "Content-Type": "text/plain" },
+      body
+    }).catch((err) => console.warn("[shipeasy] logExposure failed:", String(err)));
+  }
   /**
    * Report a structured error into the errors primitive. Fire-and-forget —
    * never blocks or throws into the request path. Spam-guarded by a 30s
@@ -873,7 +1111,11 @@ async function shipeasy(opts) {
     );
   }
   const profile = opts.i18nDefaultProfile ?? "en:prod";
-  flags.configure({ apiKey: serverKey, disableTelemetry: opts.disableTelemetry });
+  flags.configure({
+    apiKey: serverKey,
+    disableTelemetry: opts.disableTelemetry,
+    privateAttributes: opts.privateAttributes
+  });
   let resolvedUrlOverrides = opts.urlOverrides;
   if (!resolvedUrlOverrides) {
     try {
@@ -984,11 +1226,15 @@ var flags = {
   destroy() {
     _server?.destroy();
   },
-  get(name, user) {
-    return _server?.getFlag(name, user) ?? false;
+  get(name, user, defaultValue = false) {
+    return _server?.getFlag(name, user, defaultValue) ?? defaultValue;
   },
-  getConfig(name, decode) {
-    return _server?.getConfig(name, decode);
+  /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
+  getDetail(name, user) {
+    return _server?.getFlagDetail(name, user) ?? { value: false, reason: "CLIENT_NOT_READY" };
+  },
+  getConfig(name, decodeOrOpts) {
+    return _server?.getConfig(name, decodeOrOpts);
   },
   getExperiment(name, user, defaultParams, decode) {
     return _server?.getExperiment(name, user, defaultParams, decode) ?? {
@@ -1008,6 +1254,11 @@ var flags = {
   track(userId, eventName, props) {
     _server?.track(userId, eventName, props);
   },
+  /** Emit an exposure for an enrolled experiment at the decision point. See
+   *  {@link FlagsClient.logExposure}. No-op before configure(). */
+  logExposure(user, name) {
+    _server?.logExposure(user, name);
+  },
   /**
    * Evaluate all flags / configs / experiments for a user against the locally
    * cached blob. Pass the request URL to apply ?se_ks_* / ?se_cf_* / ?se_exp_*
@@ -1039,9 +1290,12 @@ var see = Object.assign(
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ANON_ID_COOKIE,
+  FLAG_REASONS,
   FlagsClient,
+  _murmur3ForTests,
   _resetShipeasyServerForTests,
   configureShipeasyServer,
+  createInMemoryStickyStore,
   fetchLabelsForSSR,
   flags,
   getBootstrapHtml,