@shipeasy/sdk 2.0.0 → 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
@@ -126,12 +135,24 @@ declare function _resetShipeasyForTests(): void;
 declare const flags: {
     configure(opts: FlagsClientBrowserOptions): void;
     identify(user: User): Promise<void>;
-    /** Read a feature gate. Returns false until identify() resolves. */
+    /**
+     * 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;
     getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
     track(eventName: string, props?: Record<string, unknown>): void;
     flush(): Promise<void>;
+    /**
+     * Called by FlagsBoundary after React hydration to unlock flag reads.
+     * Dispatches se:override:change so subscribers (FlagsBoundary) re-render
+     * once with real values — URL overrides and server-evaluated flags.
+     */
+    notifyMounted(): void;
     /** Subscribe for change notifications (identify/override). Used by framework adapters. */
     subscribe(listener: () => void): () => void;
     /** True once identify() has completed and flags are available. */
@@ -148,14 +169,14 @@ interface LabelAttrs {
     "data-label-desc"?: string;
 }
 declare function labelAttrs(key: string, variables?: Record<string, string | number>, desc?: string): LabelAttrs;
+/**
+ * Universal i18n facade. Backed by the `window.i18n` global the loader
+ * script installs. Returns the key itself when the loader hasn't run
+ * (SSR, missing script tag, before profile fetch completes), so call
+ * sites never need to null-check.
+ */
 declare const i18n: {
-    /**
-     * Look up `key` in the active translation profile. When the profile
-     * hasn't been fetched yet (SSR, CDN downtime, missing key), interpolate
-     * `fallback` instead — `fallback` is the source-of-truth English copy
-     * and is mandatory so the page never renders a raw key.
-     */
-    t(key: string, fallback: string, variables?: Record<string, string | number>): string;
+    t(key: string, variables?: Record<string, string | number>): string;
     /**
      * Translate a key and return a framework element (e.g. React <span>)
      * carrying `data-label` / `data-variables` attributes so the ShipEasy
@@ -181,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
@@ -126,12 +135,24 @@ declare function _resetShipeasyForTests(): void;
 declare const flags: {
     configure(opts: FlagsClientBrowserOptions): void;
     identify(user: User): Promise<void>;
-    /** Read a feature gate. Returns false until identify() resolves. */
+    /**
+     * 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;
     getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
     track(eventName: string, props?: Record<string, unknown>): void;
     flush(): Promise<void>;
+    /**
+     * Called by FlagsBoundary after React hydration to unlock flag reads.
+     * Dispatches se:override:change so subscribers (FlagsBoundary) re-render
+     * once with real values — URL overrides and server-evaluated flags.
+     */
+    notifyMounted(): void;
     /** Subscribe for change notifications (identify/override). Used by framework adapters. */
     subscribe(listener: () => void): () => void;
     /** True once identify() has completed and flags are available. */
@@ -148,14 +169,14 @@ interface LabelAttrs {
     "data-label-desc"?: string;
 }
 declare function labelAttrs(key: string, variables?: Record<string, string | number>, desc?: string): LabelAttrs;
+/**
+ * Universal i18n facade. Backed by the `window.i18n` global the loader
+ * script installs. Returns the key itself when the loader hasn't run
+ * (SSR, missing script tag, before profile fetch completes), so call
+ * sites never need to null-check.
+ */
 declare const i18n: {
-    /**
-     * Look up `key` in the active translation profile. When the profile
-     * hasn't been fetched yet (SSR, CDN downtime, missing key), interpolate
-     * `fallback` instead — `fallback` is the source-of-truth English copy
-     * and is mandatory so the page never renders a raw key.
-     */
-    t(key: string, fallback: string, variables?: Record<string, string | number>): string;
+    t(key: string, variables?: Record<string, string | number>): string;
     /**
      * Translate a key and return a framework element (e.g. React <span>)
      * carrying `data-label` / `data-variables` attributes so the ShipEasy
@@ -181,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

@@ -454,15 +454,13 @@ var FlagsClientBrowser = class {
     this.evalResult = data;
   }
   getFlag(name) {
-    if (this.evalResult === null) return false;
     const ov = readGateOverride(name);
     if (ov !== null) return ov;
-    return this.evalResult.flags[name] ?? false;
+    return this.evalResult?.flags[name] ?? false;
   }
   getConfig(name, decode) {
-    if (this.evalResult === null) return void 0;
     const ov = readConfigOverride(name);
-    const raw = ov !== void 0 ? ov : this.evalResult.configs?.[name];
+    const raw = ov !== void 0 ? ov : this.evalResult?.configs?.[name];
     if (raw === void 0) return void 0;
     if (!decode) return raw;
     try {
@@ -661,6 +659,20 @@ 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;
+function wireStandaloneOverride() {
+  if (_standaloneOverrideWired || typeof window === "undefined") return;
+  _standaloneOverrideWired = true;
+  window.addEventListener("se:override:change", () => {
+    for (const cb of _standaloneListeners) cb();
+  });
+}
 var flags = {
   configure(opts) {
     configureShipeasy(opts);
@@ -672,12 +684,45 @@ var flags = {
     }
     return _client.identify(user);
   },
-  /** Read a feature gate. Returns false until identify() resolves. */
+  /**
+   * 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) {
-    return _client?.getFlag(name) ?? false;
+    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 false;
   },
   getConfig(name, decode) {
-    return _client?.getConfig(name, decode);
+    const ov = readConfigOverride(name);
+    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) ?? {
@@ -692,11 +737,24 @@ var flags = {
   flush() {
     return _client?.flush() ?? Promise.resolve();
   },
+  /**
+   * Called by FlagsBoundary after React hydration to unlock flag reads.
+   * Dispatches se:override:change so subscribers (FlagsBoundary) re-render
+   * once with real values — URL overrides and server-evaluated flags.
+   */
+  notifyMounted() {
+    if (_mountedAndReady) return;
+    _mountedAndReady = true;
+    if (typeof window !== "undefined") {
+      window.dispatchEvent(new CustomEvent("se:override:change"));
+    }
+  },
   /** Subscribe for change notifications (identify/override). Used by framework adapters. */
   subscribe(listener) {
-    if (!_client) return () => {
-    };
-    return _client.subscribe(listener);
+    if (_client) return _client.subscribe(listener);
+    _standaloneListeners.add(listener);
+    wireStandaloneOverride();
+    return () => _standaloneListeners.delete(listener);
   },
   /** True once identify() has completed and flags are available. */
   get ready() {
@@ -717,27 +775,10 @@ function labelAttrs(key, variables, desc) {
   return attrs;
 }
 var _createElement = null;
-function interpolate(template, variables) {
-  if (!variables) return template;
-  let out = template;
-  for (const name of Object.keys(variables)) {
-    out = out.replace(new RegExp(`\\{\\{${name}\\}\\}`, "g"), String(variables[name]));
-  }
-  return out;
-}
 var i18n = {
-  /**
-   * Look up `key` in the active translation profile. When the profile
-   * hasn't been fetched yet (SSR, CDN downtime, missing key), interpolate
-   * `fallback` instead — `fallback` is the source-of-truth English copy
-   * and is mandatory so the page never renders a raw key.
-   */
-  t(key, fallback, variables) {
-    if (typeof window !== "undefined" && window.i18n) {
-      const v = window.i18n.t(key, variables);
-      if (v !== key) return v;
-    }
-    return interpolate(fallback, variables);
+  t(key, variables) {
+    if (typeof window !== "undefined" && window.i18n) return window.i18n.t(key, variables);
+    return key;
   },
   /**
    * Translate a key and return a framework element (e.g. React <span>)
@@ -752,7 +793,7 @@ var i18n = {
    * configured (e.g. server-side or in non-JSX contexts).
    */
   tEl(key, fallback, variables, desc) {
-    const text = this.t(key, fallback, variables);
+    const text = this.t(key, variables) || fallback;
     if (!_createElement) return text;
     return _createElement("span", labelAttrs(key, variables, desc), text);
   },

package/dist/client/index.mjs

@@ -412,15 +412,13 @@ var FlagsClientBrowser = class {
     this.evalResult = data;
   }
   getFlag(name) {
-    if (this.evalResult === null) return false;
     const ov = readGateOverride(name);
     if (ov !== null) return ov;
-    return this.evalResult.flags[name] ?? false;
+    return this.evalResult?.flags[name] ?? false;
   }
   getConfig(name, decode) {
-    if (this.evalResult === null) return void 0;
     const ov = readConfigOverride(name);
-    const raw = ov !== void 0 ? ov : this.evalResult.configs?.[name];
+    const raw = ov !== void 0 ? ov : this.evalResult?.configs?.[name];
     if (raw === void 0) return void 0;
     if (!decode) return raw;
     try {
@@ -619,6 +617,20 @@ 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;
+function wireStandaloneOverride() {
+  if (_standaloneOverrideWired || typeof window === "undefined") return;
+  _standaloneOverrideWired = true;
+  window.addEventListener("se:override:change", () => {
+    for (const cb of _standaloneListeners) cb();
+  });
+}
 var flags = {
   configure(opts) {
     configureShipeasy(opts);
@@ -630,12 +642,45 @@ var flags = {
     }
     return _client.identify(user);
   },
-  /** Read a feature gate. Returns false until identify() resolves. */
+  /**
+   * 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) {
-    return _client?.getFlag(name) ?? false;
+    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 false;
   },
   getConfig(name, decode) {
-    return _client?.getConfig(name, decode);
+    const ov = readConfigOverride(name);
+    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) ?? {
@@ -650,11 +695,24 @@ var flags = {
   flush() {
     return _client?.flush() ?? Promise.resolve();
   },
+  /**
+   * Called by FlagsBoundary after React hydration to unlock flag reads.
+   * Dispatches se:override:change so subscribers (FlagsBoundary) re-render
+   * once with real values — URL overrides and server-evaluated flags.
+   */
+  notifyMounted() {
+    if (_mountedAndReady) return;
+    _mountedAndReady = true;
+    if (typeof window !== "undefined") {
+      window.dispatchEvent(new CustomEvent("se:override:change"));
+    }
+  },
   /** Subscribe for change notifications (identify/override). Used by framework adapters. */
   subscribe(listener) {
-    if (!_client) return () => {
-    };
-    return _client.subscribe(listener);
+    if (_client) return _client.subscribe(listener);
+    _standaloneListeners.add(listener);
+    wireStandaloneOverride();
+    return () => _standaloneListeners.delete(listener);
   },
   /** True once identify() has completed and flags are available. */
   get ready() {
@@ -675,27 +733,10 @@ function labelAttrs(key, variables, desc) {
   return attrs;
 }
 var _createElement = null;
-function interpolate(template, variables) {
-  if (!variables) return template;
-  let out = template;
-  for (const name of Object.keys(variables)) {
-    out = out.replace(new RegExp(`\\{\\{${name}\\}\\}`, "g"), String(variables[name]));
-  }
-  return out;
-}
 var i18n = {
-  /**
-   * Look up `key` in the active translation profile. When the profile
-   * hasn't been fetched yet (SSR, CDN downtime, missing key), interpolate
-   * `fallback` instead — `fallback` is the source-of-truth English copy
-   * and is mandatory so the page never renders a raw key.
-   */
-  t(key, fallback, variables) {
-    if (typeof window !== "undefined" && window.i18n) {
-      const v = window.i18n.t(key, variables);
-      if (v !== key) return v;
-    }
-    return interpolate(fallback, variables);
+  t(key, variables) {
+    if (typeof window !== "undefined" && window.i18n) return window.i18n.t(key, variables);
+    return key;
   },
   /**
    * Translate a key and return a framework element (e.g. React <span>)
@@ -710,7 +751,7 @@ var i18n = {
    * configured (e.g. server-side or in non-JSX contexts).
    */
   tEl(key, fallback, variables, desc) {
-    const text = this.t(key, fallback, variables);
+    const text = this.t(key, variables) || fallback;
     if (!_createElement) return text;
     return _createElement("span", labelAttrs(key, variables, desc), text);
   },

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.0",
+  "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",