@shipeasy/sdk 1.2.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. */
@@ -168,7 +177,7 @@ declare const i18n: {
      * Falls back to a plain translated string if `createElement` was not
      * configured (e.g. server-side or in non-JSX contexts).
      */
-    tEl(key: string, variables?: Record<string, string | number>, desc?: string): any;
+    tEl(key: string, fallback: string, variables?: Record<string, string | number>, desc?: string): any;
     /** Wire up the element creator once at app startup (call before any tEl use). */
     configure(opts: {
         createElement: (tag: string, props: object, children: string) => any;

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. */
@@ -168,7 +177,7 @@ declare const i18n: {
      * Falls back to a plain translated string if `createElement` was not
      * configured (e.g. server-side or in non-JSX contexts).
      */
-    tEl(key: string, variables?: Record<string, string | number>, desc?: string): any;
+    tEl(key: string, fallback: string, variables?: Record<string, string | number>, desc?: string): any;
     /** Wire up the element creator once at app startup (call before any tEl use). */
     configure(opts: {
         createElement: (tag: string, props: object, children: string) => any;

package/dist/client/index.js

@@ -659,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);
@@ -670,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) ?? {
@@ -690,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() {
@@ -732,9 +769,8 @@ var i18n = {
    * Falls back to a plain translated string if `createElement` was not
    * configured (e.g. server-side or in non-JSX contexts).
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  tEl(key, variables, desc) {
-    const text = this.t(key, variables);
+  tEl(key, fallback, variables, desc) {
+    const text = this.t(key, variables) || fallback;
     if (!_createElement) return text;
     return _createElement("span", labelAttrs(key, variables, desc), text);
   },

package/dist/client/index.mjs

@@ -617,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);
@@ -628,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) ?? {
@@ -648,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() {
@@ -690,9 +727,8 @@ var i18n = {
    * Falls back to a plain translated string if `createElement` was not
    * configured (e.g. server-side or in non-JSX contexts).
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  tEl(key, variables, desc) {
-    const text = this.t(key, variables);
+  tEl(key, fallback, variables, desc) {
+    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": "1.2.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",