@shipeasy/sdk 2.0.1 → 2.0.2

package/dist/client/index.d.mts

@@ -118,6 +118,15 @@ declare function getShipeasyClient(): FlagsClientBrowser | null;
  * Not part of the documented surface; production code should never call this.
  */
 declare function _resetShipeasyForTests(): void;
+interface BootstrapPayload {
+    flags: Record<string, boolean>;
+    configs: Record<string, unknown>;
+    experiments: Record<string, {
+        inExperiment: boolean;
+        group: string;
+        params: Record<string, unknown>;
+    }>;
+}
 /**
  * Universal flags facade. Methods return safe defaults when the singleton
  * hasn't been configured yet (false / undefined / `notIn` experiment), so
@@ -127,8 +136,11 @@ declare const flags: {
     configure(opts: FlagsClientBrowserOptions): void;
     identify(user: User): Promise<void>;
     /**
-     * Read a feature gate. Returns false until FlagsBoundary mounts (SSR-safe).
-     * After mount, URL overrides (?se_ks_*) apply even without a configured client.
+     * Read a feature gate.
+     * Priority: URL override → server bootstrap (window.__SE_BOOTSTRAP) → CDN-fetched (post-mount) → false.
+     * The _mountedAndReady gate still applies for the CDN path to prevent hydration
+     * mismatches on force-static pages; bootstrap data is safe to read immediately
+     * because the server rendered with the same values.
      */
     get(name: string): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
@@ -190,4 +202,4 @@ declare const i18n: {
     onUpdate(cb: () => void): () => void;
 };
 
-export { type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type ShipeasySdkBridge, type User, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, version };
+export { type BootstrapPayload, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type ShipeasySdkBridge, type User, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, version };

package/dist/client/index.d.ts

@@ -118,6 +118,15 @@ declare function getShipeasyClient(): FlagsClientBrowser | null;
  * Not part of the documented surface; production code should never call this.
  */
 declare function _resetShipeasyForTests(): void;
+interface BootstrapPayload {
+    flags: Record<string, boolean>;
+    configs: Record<string, unknown>;
+    experiments: Record<string, {
+        inExperiment: boolean;
+        group: string;
+        params: Record<string, unknown>;
+    }>;
+}
 /**
  * Universal flags facade. Methods return safe defaults when the singleton
  * hasn't been configured yet (false / undefined / `notIn` experiment), so
@@ -127,8 +136,11 @@ declare const flags: {
     configure(opts: FlagsClientBrowserOptions): void;
     identify(user: User): Promise<void>;
     /**
-     * Read a feature gate. Returns false until FlagsBoundary mounts (SSR-safe).
-     * After mount, URL overrides (?se_ks_*) apply even without a configured client.
+     * Read a feature gate.
+     * Priority: URL override → server bootstrap (window.__SE_BOOTSTRAP) → CDN-fetched (post-mount) → false.
+     * The _mountedAndReady gate still applies for the CDN path to prevent hydration
+     * mismatches on force-static pages; bootstrap data is safe to read immediately
+     * because the server rendered with the same values.
      */
     get(name: string): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
@@ -190,4 +202,4 @@ declare const i18n: {
     onUpdate(cb: () => void): () => void;
 };
 
-export { type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type ShipeasySdkBridge, type User, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, version };
+export { type BootstrapPayload, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type ShipeasySdkBridge, type User, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, version };

package/dist/client/index.js

@@ -659,6 +659,10 @@ function _resetShipeasyForTests() {
   _client?.destroy();
   _client = null;
 }
+function getBootstrap() {
+  if (typeof window === "undefined") return null;
+  return window.__SE_BOOTSTRAP ?? null;
+}
 var _mountedAndReady = false;
 var _standaloneListeners = /* @__PURE__ */ new Set();
 var _standaloneOverrideWired = false;
@@ -681,25 +685,44 @@ var flags = {
     return _client.identify(user);
   },
   /**
-   * Read a feature gate. Returns false until FlagsBoundary mounts (SSR-safe).
-   * After mount, URL overrides (?se_ks_*) apply even without a configured client.
+   * Read a feature gate.
+   * Priority: URL override → server bootstrap (window.__SE_BOOTSTRAP) → CDN-fetched (post-mount) → false.
+   * The _mountedAndReady gate still applies for the CDN path to prevent hydration
+   * mismatches on force-static pages; bootstrap data is safe to read immediately
+   * because the server rendered with the same values.
    */
   get(name) {
+    const ov = readGateOverride(name);
+    if (ov !== null) return ov;
+    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;
+    return false;
   },
   getConfig(name, decode) {
-    if (!_mountedAndReady) return void 0;
-    if (_client) return _client.getConfig(name, decode);
     const ov = readConfigOverride(name);
-    if (ov === void 0) return void 0;
-    if (!decode) return ov;
-    try {
-      return decode(ov);
-    } catch {
-      return void 0;
+    if (ov !== void 0) {
+      if (!decode) return ov;
+      try {
+        return decode(ov);
+      } catch {
+        return void 0;
+      }
     }
+    const bs = getBootstrap();
+    if (bs !== null && name in bs.configs) {
+      const raw = bs.configs[name];
+      if (!decode) return raw;
+      try {
+        return decode(raw);
+      } catch {
+        return void 0;
+      }
+    }
+    if (!_mountedAndReady) return void 0;
+    if (_client) return _client.getConfig(name, decode);
+    return void 0;
   },
   getExperiment(name, defaultParams, decode, variants) {
     return _client?.getExperiment(name, defaultParams, decode, variants) ?? {

package/dist/client/index.mjs

@@ -617,6 +617,10 @@ function _resetShipeasyForTests() {
   _client?.destroy();
   _client = null;
 }
+function getBootstrap() {
+  if (typeof window === "undefined") return null;
+  return window.__SE_BOOTSTRAP ?? null;
+}
 var _mountedAndReady = false;
 var _standaloneListeners = /* @__PURE__ */ new Set();
 var _standaloneOverrideWired = false;
@@ -639,25 +643,44 @@ var flags = {
     return _client.identify(user);
   },
   /**
-   * Read a feature gate. Returns false until FlagsBoundary mounts (SSR-safe).
-   * After mount, URL overrides (?se_ks_*) apply even without a configured client.
+   * Read a feature gate.
+   * Priority: URL override → server bootstrap (window.__SE_BOOTSTRAP) → CDN-fetched (post-mount) → false.
+   * The _mountedAndReady gate still applies for the CDN path to prevent hydration
+   * mismatches on force-static pages; bootstrap data is safe to read immediately
+   * because the server rendered with the same values.
    */
   get(name) {
+    const ov = readGateOverride(name);
+    if (ov !== null) return ov;
+    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;
+    return false;
   },
   getConfig(name, decode) {
-    if (!_mountedAndReady) return void 0;
-    if (_client) return _client.getConfig(name, decode);
     const ov = readConfigOverride(name);
-    if (ov === void 0) return void 0;
-    if (!decode) return ov;
-    try {
-      return decode(ov);
-    } catch {
-      return void 0;
+    if (ov !== void 0) {
+      if (!decode) return ov;
+      try {
+        return decode(ov);
+      } catch {
+        return void 0;
+      }
     }
+    const bs = getBootstrap();
+    if (bs !== null && name in bs.configs) {
+      const raw = bs.configs[name];
+      if (!decode) return raw;
+      try {
+        return decode(raw);
+      } catch {
+        return void 0;
+      }
+    }
+    if (!_mountedAndReady) return void 0;
+    if (_client) return _client.getConfig(name, decode);
+    return void 0;
   },
   getExperiment(name, defaultParams, decode, variants) {
     return _client?.getExperiment(name, defaultParams, decode, variants) ?? {

package/dist/server/index.d.mts

@@ -9,6 +9,11 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
+interface BootstrapPayload {
+    flags: Record<string, boolean>;
+    configs: Record<string, unknown>;
+    experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
+}
 type FlagsClientEnv = "dev" | "staging" | "prod";
 interface FlagsClientOptions {
     apiKey: string;
@@ -39,6 +44,16 @@ declare class FlagsClient {
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * Evaluate all flags, configs, and experiments for a user against the locally
+     * cached blob (no network call). Applies ?se_ks_* / ?se_cf_* / ?se_exp_*
+     * overrides from the request URL when provided.
+     *
+     * Intended for SSR: call on the server, inject the result as
+     * `window.__SE_BOOTSTRAP` in the HTML, and the client SDK will read it
+     * synchronously without waiting for identify() to resolve.
+     */
+    evaluate(user: User, rawUrl?: string): BootstrapPayload;
 }
 interface LabelFile {
     v: number;
@@ -72,6 +87,12 @@ declare const flags: {
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * 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_*
+     * overrides. Returns an empty payload when the blob hasn't been fetched yet.
+     */
+    evaluate(user: User, rawUrl?: string): BootstrapPayload;
 };
 
-export { type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type LabelFile, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getShipeasyServerClient, version };
+export { type BootstrapPayload, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type LabelFile, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getShipeasyServerClient, version };

package/dist/server/index.d.ts

@@ -9,6 +9,11 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
+interface BootstrapPayload {
+    flags: Record<string, boolean>;
+    configs: Record<string, unknown>;
+    experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
+}
 type FlagsClientEnv = "dev" | "staging" | "prod";
 interface FlagsClientOptions {
     apiKey: string;
@@ -39,6 +44,16 @@ declare class FlagsClient {
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * Evaluate all flags, configs, and experiments for a user against the locally
+     * cached blob (no network call). Applies ?se_ks_* / ?se_cf_* / ?se_exp_*
+     * overrides from the request URL when provided.
+     *
+     * Intended for SSR: call on the server, inject the result as
+     * `window.__SE_BOOTSTRAP` in the HTML, and the client SDK will read it
+     * synchronously without waiting for identify() to resolve.
+     */
+    evaluate(user: User, rawUrl?: string): BootstrapPayload;
 }
 interface LabelFile {
     v: number;
@@ -72,6 +87,12 @@ declare const flags: {
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * 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_*
+     * overrides. Returns an empty payload when the blob hasn't been fetched yet.
+     */
+    evaluate(user: User, rawUrl?: string): BootstrapPayload;
 };
 
-export { type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type LabelFile, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getShipeasyServerClient, version };
+export { type BootstrapPayload, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type LabelFile, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getShipeasyServerClient, version };

package/dist/server/index.js

@@ -129,6 +129,51 @@ function evalGateInternal(gate, user) {
   if (!uid) return false;
   return murmur3(`${gate.salt}:${uid}`) % 1e4 < gate.rolloutPct;
 }
+var TRUE_RX = /^(true|on|1|yes)$/i;
+var FALSE_RX = /^(false|off|0|no)$/i;
+function parseOverrideBool(raw) {
+  if (TRUE_RX.test(raw)) return true;
+  if (FALSE_RX.test(raw)) return false;
+  return null;
+}
+function decodeOverrideConfigValue(raw) {
+  if (raw.startsWith("b64:")) {
+    try {
+      const json = atob(raw.slice(4).replace(/-/g, "+").replace(/_/g, "/"));
+      return JSON.parse(json);
+    } catch {
+      return raw;
+    }
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+function parseOverrides(rawUrl) {
+  const gates = {};
+  const configs = {};
+  const experiments = {};
+  try {
+    const url = new URL(rawUrl, "http://localhost");
+    for (const [k, v] of url.searchParams) {
+      if (k.startsWith("se_ks_")) {
+        const b = parseOverrideBool(v);
+        if (b !== null) gates[k.slice(6)] = b;
+      } else if (k.startsWith("se_cf_")) {
+        configs[k.slice(6)] = decodeOverrideConfigValue(v);
+      } else if (k.startsWith("se_config_")) {
+        configs[k.slice(10)] = decodeOverrideConfigValue(v);
+      } else if (k.startsWith("se_exp_")) {
+        const name = k.slice(7);
+        if (v && v !== "default" && v !== "none") experiments[name] = v;
+      }
+    }
+  } catch {
+  }
+  return { gates, configs, experiments };
+}
 var FlagsClient = class {
   apiKey;
   baseUrl;
@@ -271,6 +316,38 @@ var FlagsClient = class {
       body
     }).catch((err) => console.warn("[shipeasy] track failed:", String(err)));
   }
+  /**
+   * Evaluate all flags, configs, and experiments for a user against the locally
+   * cached blob (no network call). Applies ?se_ks_* / ?se_cf_* / ?se_exp_*
+   * overrides from the request URL when provided.
+   *
+   * Intended for SSR: call on the server, inject the result as
+   * `window.__SE_BOOTSTRAP` in the HTML, and the client SDK will read it
+   * synchronously without waiting for identify() to resolve.
+   */
+  evaluate(user, rawUrl) {
+    const flags2 = {};
+    const configs = {};
+    const experiments = {};
+    for (const [name, gate] of Object.entries(this.flagsBlob?.gates ?? {})) {
+      flags2[name] = evalGateInternal(gate, user);
+    }
+    for (const [name, entry] of Object.entries(this.flagsBlob?.configs ?? {})) {
+      configs[name] = entry.value;
+    }
+    for (const [name] of Object.entries(this.expsBlob?.experiments ?? {})) {
+      experiments[name] = this.getExperiment(name, user, {});
+    }
+    if (rawUrl) {
+      const ov = parseOverrides(rawUrl);
+      Object.assign(flags2, ov.gates);
+      Object.assign(configs, ov.configs);
+      for (const [name, group] of Object.entries(ov.experiments)) {
+        experiments[name] = { inExperiment: true, group, params: {} };
+      }
+    }
+    return { flags: flags2, configs, experiments };
+  }
 };
 var DEFAULT_I18N_CDN = "https://cdn.i18n.shipeasy.ai";
 async function fetchJson(url, timeoutMs = 2e3) {
@@ -351,6 +428,14 @@ var flags = {
   },
   track(userId, eventName, props) {
     _server?.track(userId, eventName, props);
+  },
+  /**
+   * 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_*
+   * overrides. Returns an empty payload when the blob hasn't been fetched yet.
+   */
+  evaluate(user, rawUrl) {
+    return _server?.evaluate(user, rawUrl) ?? { flags: {}, configs: {}, experiments: {} };
   }
 };
 // Annotate the CommonJS export names for ESM import in node:

package/dist/server/index.mjs

@@ -99,6 +99,51 @@ function evalGateInternal(gate, user) {
   if (!uid) return false;
   return murmur3(`${gate.salt}:${uid}`) % 1e4 < gate.rolloutPct;
 }
+var TRUE_RX = /^(true|on|1|yes)$/i;
+var FALSE_RX = /^(false|off|0|no)$/i;
+function parseOverrideBool(raw) {
+  if (TRUE_RX.test(raw)) return true;
+  if (FALSE_RX.test(raw)) return false;
+  return null;
+}
+function decodeOverrideConfigValue(raw) {
+  if (raw.startsWith("b64:")) {
+    try {
+      const json = atob(raw.slice(4).replace(/-/g, "+").replace(/_/g, "/"));
+      return JSON.parse(json);
+    } catch {
+      return raw;
+    }
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+function parseOverrides(rawUrl) {
+  const gates = {};
+  const configs = {};
+  const experiments = {};
+  try {
+    const url = new URL(rawUrl, "http://localhost");
+    for (const [k, v] of url.searchParams) {
+      if (k.startsWith("se_ks_")) {
+        const b = parseOverrideBool(v);
+        if (b !== null) gates[k.slice(6)] = b;
+      } else if (k.startsWith("se_cf_")) {
+        configs[k.slice(6)] = decodeOverrideConfigValue(v);
+      } else if (k.startsWith("se_config_")) {
+        configs[k.slice(10)] = decodeOverrideConfigValue(v);
+      } else if (k.startsWith("se_exp_")) {
+        const name = k.slice(7);
+        if (v && v !== "default" && v !== "none") experiments[name] = v;
+      }
+    }
+  } catch {
+  }
+  return { gates, configs, experiments };
+}
 var FlagsClient = class {
   apiKey;
   baseUrl;
@@ -241,6 +286,38 @@ var FlagsClient = class {
       body
     }).catch((err) => console.warn("[shipeasy] track failed:", String(err)));
   }
+  /**
+   * Evaluate all flags, configs, and experiments for a user against the locally
+   * cached blob (no network call). Applies ?se_ks_* / ?se_cf_* / ?se_exp_*
+   * overrides from the request URL when provided.
+   *
+   * Intended for SSR: call on the server, inject the result as
+   * `window.__SE_BOOTSTRAP` in the HTML, and the client SDK will read it
+   * synchronously without waiting for identify() to resolve.
+   */
+  evaluate(user, rawUrl) {
+    const flags2 = {};
+    const configs = {};
+    const experiments = {};
+    for (const [name, gate] of Object.entries(this.flagsBlob?.gates ?? {})) {
+      flags2[name] = evalGateInternal(gate, user);
+    }
+    for (const [name, entry] of Object.entries(this.flagsBlob?.configs ?? {})) {
+      configs[name] = entry.value;
+    }
+    for (const [name] of Object.entries(this.expsBlob?.experiments ?? {})) {
+      experiments[name] = this.getExperiment(name, user, {});
+    }
+    if (rawUrl) {
+      const ov = parseOverrides(rawUrl);
+      Object.assign(flags2, ov.gates);
+      Object.assign(configs, ov.configs);
+      for (const [name, group] of Object.entries(ov.experiments)) {
+        experiments[name] = { inExperiment: true, group, params: {} };
+      }
+    }
+    return { flags: flags2, configs, experiments };
+  }
 };
 var DEFAULT_I18N_CDN = "https://cdn.i18n.shipeasy.ai";
 async function fetchJson(url, timeoutMs = 2e3) {
@@ -321,6 +398,14 @@ var flags = {
   },
   track(userId, eventName, props) {
     _server?.track(userId, eventName, props);
+  },
+  /**
+   * 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_*
+   * overrides. Returns an empty payload when the blob hasn't been fetched yet.
+   */
+  evaluate(user, rawUrl) {
+    return _server?.evaluate(user, rawUrl) ?? { flags: {}, configs: {}, experiments: {} };
   }
 };
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/sdk",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Shipeasy SDK — feature gates, runtime configs, experiments, and metrics for the Shipeasy hosted service.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://shipeasy.ai",