@shipeasy/sdk 2.0.0 → 2.0.1

package/dist/client/index.d.mts

@@ -126,12 +126,21 @@ 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. Returns false until FlagsBoundary mounts (SSR-safe).
+     * After mount, URL overrides (?se_ks_*) apply even without a configured client.
+     */
     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 +157,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

package/dist/client/index.d.ts

@@ -126,12 +126,21 @@ 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. Returns false until FlagsBoundary mounts (SSR-safe).
+     * After mount, URL overrides (?se_ks_*) apply even without a configured client.
+     */
     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 +157,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

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,16 @@ function _resetShipeasyForTests() {
   _client?.destroy();
   _client = 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 +680,26 @@ var flags = {
     }
     return _client.identify(user);
   },
-  /** Read a feature gate. Returns false until identify() resolves. */
+  /**
+   * Read a feature gate. Returns false until FlagsBoundary mounts (SSR-safe).
+   * After mount, URL overrides (?se_ks_*) apply even without a configured client.
+   */
   get(name) {
-    return _client?.getFlag(name) ?? false;
+    if (!_mountedAndReady) return false;
+    if (_client) return _client.getFlag(name);
+    return readGateOverride(name) ?? false;
   },
   getConfig(name, decode) {
-    return _client?.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;
+    }
   },
   getExperiment(name, defaultParams, decode, variants) {
     return _client?.getExperiment(name, defaultParams, decode, variants) ?? {
@@ -692,11 +714,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 +752,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 +770,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,16 @@ function _resetShipeasyForTests() {
   _client?.destroy();
   _client = 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 +638,26 @@ var flags = {
     }
     return _client.identify(user);
   },
-  /** Read a feature gate. Returns false until identify() resolves. */
+  /**
+   * Read a feature gate. Returns false until FlagsBoundary mounts (SSR-safe).
+   * After mount, URL overrides (?se_ks_*) apply even without a configured client.
+   */
   get(name) {
-    return _client?.getFlag(name) ?? false;
+    if (!_mountedAndReady) return false;
+    if (_client) return _client.getFlag(name);
+    return readGateOverride(name) ?? false;
   },
   getConfig(name, decode) {
-    return _client?.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;
+    }
   },
   getExperiment(name, defaultParams, decode, variants) {
     return _client?.getExperiment(name, defaultParams, decode, variants) ?? {
@@ -650,11 +672,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 +710,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 +728,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/package.json

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