@shipeasy/sdk 2.0.2 → 2.1.0

package/dist/client/index.d.mts

@@ -110,6 +110,20 @@ interface AttachDevtoolsOptions {
  */
 declare function attachDevtools(client: FlagsClientBrowser, opts?: AttachDevtoolsOptions): () => void;
 /** Configure the singleton. Idempotent — re-calling with the same opts is a no-op. */
+interface ShipeasyClientConfig {
+    /** SDK key — same value used on the server via shipeasy(). */
+    apiKey: string;
+    /** Override the ShipEasy CDN/edge base URL. Defaults to https://cdn.shipeasy.ai. */
+    baseUrl?: string;
+    /** Override the admin URL for the devtools overlay (dev use). */
+    adminUrl?: string;
+}
+/**
+ * Initialise the ShipEasy client SDK and wire up lazy devtools.
+ * Call this once at app startup (e.g. in a useEffect in your root layout).
+ * Returns a cleanup function — call it on unmount to remove event listeners.
+ */
+declare function shipeasy(opts: ShipeasyClientConfig): () => void;
 declare function configureShipeasy(opts: FlagsClientBrowserOptions): FlagsClientBrowser;
 /** Returns the configured singleton, or null if configureShipeasy() hasn't run yet. */
 declare function getShipeasyClient(): FlagsClientBrowser | null;
@@ -126,6 +140,9 @@ interface BootstrapPayload {
         group: string;
         params: Record<string, unknown>;
     }>;
+    /** Set by getBootstrapHtml() for auto-init. Not part of evaluate() output. */
+    apiKey?: string;
+    apiUrl?: string;
 }
 /**
  * Universal flags facade. Methods return safe defaults when the singleton
@@ -137,10 +154,10 @@ declare const flags: {
     identify(user: User): Promise<void>;
     /**
      * 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.
+     * Priority: bootstrap → CDN/URL-override (post-mount) → false.
+     * Bootstrap is safe before mount because the server rendered with the same values.
+     * Everything else gates on _mountedAndReady to prevent hydration mismatches on
+     * force-static pages where SSR has no flag data.
      */
     get(name: string): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
@@ -150,7 +167,11 @@ declare const flags: {
     /**
      * 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.
+     * once with real values — URL overrides and CDN-loaded flags.
+     *
+     * Always dispatches even if already mounted: in React hydration-recovery
+     * renders the latch is already true so the early-return guard would swallow
+     * the event, leaving the re-mounted subtree stuck with stale (empty) values.
      */
     notifyMounted(): void;
     /** Subscribe for change notifications (identify/override). Used by framework adapters. */
@@ -202,4 +223,4 @@ declare const i18n: {
     onUpdate(cb: () => void): () => void;
 };
 
-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 };
+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 ShipeasyClientConfig, type ShipeasySdkBridge, type User, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, shipeasy, version };

package/dist/client/index.d.ts

@@ -110,6 +110,20 @@ interface AttachDevtoolsOptions {
  */
 declare function attachDevtools(client: FlagsClientBrowser, opts?: AttachDevtoolsOptions): () => void;
 /** Configure the singleton. Idempotent — re-calling with the same opts is a no-op. */
+interface ShipeasyClientConfig {
+    /** SDK key — same value used on the server via shipeasy(). */
+    apiKey: string;
+    /** Override the ShipEasy CDN/edge base URL. Defaults to https://cdn.shipeasy.ai. */
+    baseUrl?: string;
+    /** Override the admin URL for the devtools overlay (dev use). */
+    adminUrl?: string;
+}
+/**
+ * Initialise the ShipEasy client SDK and wire up lazy devtools.
+ * Call this once at app startup (e.g. in a useEffect in your root layout).
+ * Returns a cleanup function — call it on unmount to remove event listeners.
+ */
+declare function shipeasy(opts: ShipeasyClientConfig): () => void;
 declare function configureShipeasy(opts: FlagsClientBrowserOptions): FlagsClientBrowser;
 /** Returns the configured singleton, or null if configureShipeasy() hasn't run yet. */
 declare function getShipeasyClient(): FlagsClientBrowser | null;
@@ -126,6 +140,9 @@ interface BootstrapPayload {
         group: string;
         params: Record<string, unknown>;
     }>;
+    /** Set by getBootstrapHtml() for auto-init. Not part of evaluate() output. */
+    apiKey?: string;
+    apiUrl?: string;
 }
 /**
  * Universal flags facade. Methods return safe defaults when the singleton
@@ -137,10 +154,10 @@ declare const flags: {
     identify(user: User): Promise<void>;
     /**
      * 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.
+     * Priority: bootstrap → CDN/URL-override (post-mount) → false.
+     * Bootstrap is safe before mount because the server rendered with the same values.
+     * Everything else gates on _mountedAndReady to prevent hydration mismatches on
+     * force-static pages where SSR has no flag data.
      */
     get(name: string): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
@@ -150,7 +167,11 @@ declare const flags: {
     /**
      * 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.
+     * once with real values — URL overrides and CDN-loaded flags.
+     *
+     * Always dispatches even if already mounted: in React hydration-recovery
+     * renders the latch is already true so the early-return guard would swallow
+     * the event, leaving the re-mounted subtree stuck with stale (empty) values.
      */
     notifyMounted(): void;
     /** Subscribe for change notifications (identify/override). Used by framework adapters. */
@@ -202,4 +223,4 @@ declare const i18n: {
     onUpdate(cb: () => void): () => void;
 };
 
-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 };
+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 ShipeasyClientConfig, type ShipeasySdkBridge, type User, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, shipeasy, version };

package/dist/client/index.js

@@ -38,6 +38,7 @@ __export(client_exports, {
   readConfigOverride: () => readConfigOverride,
   readExpOverride: () => readExpOverride,
   readGateOverride: () => readGateOverride,
+  shipeasy: () => shipeasy,
   version: () => version
 });
 module.exports = __toCommonJS(client_exports);
@@ -647,6 +648,14 @@ function attachDevtools(client, opts = {}) {
   };
 }
 var _client = null;
+function shipeasy(opts) {
+  const client = configureShipeasy({
+    sdkKey: opts.apiKey,
+    baseUrl: opts.baseUrl ?? "https://cdn.shipeasy.ai"
+  });
+  flags.notifyMounted();
+  return attachDevtools(client, { adminUrl: opts.adminUrl });
+}
 function configureShipeasy(opts) {
   if (_client) return _client;
   _client = new FlagsClientBrowser(opts);
@@ -686,30 +695,19 @@ var flags = {
   },
   /**
    * 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.
+   * Priority: bootstrap → CDN/URL-override (post-mount) → false.
+   * Bootstrap is safe before mount because the server rendered with the same values.
+   * Everything else gates on _mountedAndReady to prevent hydration mismatches on
+   * force-static pages where SSR has no flag data.
    */
   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 false;
+    return readGateOverride(name) ?? false;
   },
   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];
@@ -722,7 +720,14 @@ var flags = {
     }
     if (!_mountedAndReady) return void 0;
     if (_client) return _client.getConfig(name, decode);
-    return void 0;
+    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) ?? {
@@ -740,10 +745,13 @@ var flags = {
   /**
    * 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.
+   * once with real values — URL overrides and CDN-loaded flags.
+   *
+   * Always dispatches even if already mounted: in React hydration-recovery
+   * renders the latch is already true so the early-return guard would swallow
+   * the event, leaving the re-mounted subtree stuck with stale (empty) values.
    */
   notifyMounted() {
-    if (_mountedAndReady) return;
     _mountedAndReady = true;
     if (typeof window !== "undefined") {
       window.dispatchEvent(new CustomEvent("se:override:change"));
@@ -775,9 +783,19 @@ function labelAttrs(key, variables, desc) {
   return attrs;
 }
 var _createElement = null;
+var _I18N_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n");
+function getSSRI18nStore() {
+  return globalThis[_I18N_SSR_SYM]?.() ?? null;
+}
+function interpolate(raw, variables) {
+  if (!variables) return raw;
+  return raw.replace(/\{\{(\w+)\}\}/g, (_, k) => String(variables[k] ?? `{{${k}}}`));
+}
 var i18n = {
   t(key, variables) {
     if (typeof window !== "undefined" && window.i18n) return window.i18n.t(key, variables);
+    const store = getSSRI18nStore();
+    if (store?.strings[key]) return interpolate(store.strings[key], variables);
     return key;
   },
   /**
@@ -793,7 +811,8 @@ var i18n = {
    * configured (e.g. server-side or in non-JSX contexts).
    */
   tEl(key, fallback, variables, desc) {
-    const text = this.t(key, variables) || fallback;
+    const hasTranslation = typeof window !== "undefined" && Boolean(window.i18n) || Boolean(getSSRI18nStore()?.strings[key]);
+    const text = hasTranslation ? this.t(key, variables) || fallback : fallback;
     if (!_createElement) return text;
     return _createElement("span", labelAttrs(key, variables, desc), text);
   },
@@ -836,6 +855,12 @@ var i18n = {
     };
   }
 };
+if (typeof window !== "undefined") {
+  const _initBs = window.__SE_BOOTSTRAP;
+  if (_initBs?.apiKey && !_client) {
+    shipeasy({ apiKey: _initBs.apiKey, baseUrl: _initBs.apiUrl });
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FlagsClientBrowser,
@@ -856,5 +881,6 @@ var i18n = {
   readConfigOverride,
   readExpOverride,
   readGateOverride,
+  shipeasy,
   version
 });

package/dist/client/index.mjs

@@ -605,6 +605,14 @@ function attachDevtools(client, opts = {}) {
   };
 }
 var _client = null;
+function shipeasy(opts) {
+  const client = configureShipeasy({
+    sdkKey: opts.apiKey,
+    baseUrl: opts.baseUrl ?? "https://cdn.shipeasy.ai"
+  });
+  flags.notifyMounted();
+  return attachDevtools(client, { adminUrl: opts.adminUrl });
+}
 function configureShipeasy(opts) {
   if (_client) return _client;
   _client = new FlagsClientBrowser(opts);
@@ -644,30 +652,19 @@ var flags = {
   },
   /**
    * 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.
+   * Priority: bootstrap → CDN/URL-override (post-mount) → false.
+   * Bootstrap is safe before mount because the server rendered with the same values.
+   * Everything else gates on _mountedAndReady to prevent hydration mismatches on
+   * force-static pages where SSR has no flag data.
    */
   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 false;
+    return readGateOverride(name) ?? false;
   },
   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];
@@ -680,7 +677,14 @@ var flags = {
     }
     if (!_mountedAndReady) return void 0;
     if (_client) return _client.getConfig(name, decode);
-    return void 0;
+    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) ?? {
@@ -698,10 +702,13 @@ var flags = {
   /**
    * 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.
+   * once with real values — URL overrides and CDN-loaded flags.
+   *
+   * Always dispatches even if already mounted: in React hydration-recovery
+   * renders the latch is already true so the early-return guard would swallow
+   * the event, leaving the re-mounted subtree stuck with stale (empty) values.
    */
   notifyMounted() {
-    if (_mountedAndReady) return;
     _mountedAndReady = true;
     if (typeof window !== "undefined") {
       window.dispatchEvent(new CustomEvent("se:override:change"));
@@ -733,9 +740,19 @@ function labelAttrs(key, variables, desc) {
   return attrs;
 }
 var _createElement = null;
+var _I18N_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n");
+function getSSRI18nStore() {
+  return globalThis[_I18N_SSR_SYM]?.() ?? null;
+}
+function interpolate(raw, variables) {
+  if (!variables) return raw;
+  return raw.replace(/\{\{(\w+)\}\}/g, (_, k) => String(variables[k] ?? `{{${k}}}`));
+}
 var i18n = {
   t(key, variables) {
     if (typeof window !== "undefined" && window.i18n) return window.i18n.t(key, variables);
+    const store = getSSRI18nStore();
+    if (store?.strings[key]) return interpolate(store.strings[key], variables);
     return key;
   },
   /**
@@ -751,7 +768,8 @@ var i18n = {
    * configured (e.g. server-side or in non-JSX contexts).
    */
   tEl(key, fallback, variables, desc) {
-    const text = this.t(key, variables) || fallback;
+    const hasTranslation = typeof window !== "undefined" && Boolean(window.i18n) || Boolean(getSSRI18nStore()?.strings[key]);
+    const text = hasTranslation ? this.t(key, variables) || fallback : fallback;
     if (!_createElement) return text;
     return _createElement("span", labelAttrs(key, variables, desc), text);
   },
@@ -794,6 +812,12 @@ var i18n = {
     };
   }
 };
+if (typeof window !== "undefined") {
+  const _initBs = window.__SE_BOOTSTRAP;
+  if (_initBs?.apiKey && !_client) {
+    shipeasy({ apiKey: _initBs.apiKey, baseUrl: _initBs.apiUrl });
+  }
+}
 export {
   FlagsClientBrowser,
   LABEL_MARKER_END,
@@ -813,5 +837,6 @@ export {
   readConfigOverride,
   readExpOverride,
   readGateOverride,
+  shipeasy,
   version
 };

package/dist/server/index.d.mts

@@ -55,6 +55,32 @@ declare class FlagsClient {
      */
     evaluate(user: User, rawUrl?: string): BootstrapPayload;
 }
+interface I18nForRequest {
+    strings: Record<string, string>;
+    locale: string;
+}
+declare const i18n: {
+    /**
+     * Fetch translation labels for the current request and store them in an
+     * async-local context so `i18n.t()` / `i18n.tEl()` in SSR'd client
+     * components return the real translated strings instead of the key.
+     *
+     * Call once per request in the root layout (or page). Failure is silent —
+     * `i18n.t()` falls back to the hardcoded fallback arg when no labels are
+     * loaded.
+     *
+     * @param key     SDK client key (NEXT_PUBLIC_SHIPEASY_CLIENT_KEY)
+     * @param profile i18n profile identifier, e.g. "en:prod"
+     * @param cdnBaseUrl Optional override for the i18n CDN (default: cdn.i18n.shipeasy.ai)
+     */
+    init(key: string, profile: string, cdnBaseUrl?: string): Promise<void>;
+    /**
+     * Return the translation strings loaded for the current request.
+     * Use this to include i18n data in the SSR bootstrap payload so the
+     * client doesn't need an extra network round-trip.
+     */
+    getForRequest(): I18nForRequest;
+};
 interface LabelFile {
     v: number;
     profile: string;
@@ -72,6 +98,57 @@ declare function fetchLabelsForSSR(opts: FetchLabelsOptions): Promise<LabelFile
 declare function configureShipeasyServer(opts: FlagsClientOptions): FlagsClient;
 declare function getShipeasyServerClient(): FlagsClient | null;
 declare function _resetShipeasyServerForTests(): void;
+interface ShipeasyServerConfig {
+    /**
+     * Server-side API key — authenticates flag/experiment fetches from the edge.
+     * Never embedded in browser output. A warning is logged if omitted.
+     */
+    apiKey?: string;
+    /**
+     * Public client key — embedded in window.__SE_BOOTSTRAP and used by the
+     * browser SDK. Safe to expose (e.g. NEXT_PUBLIC_ env vars).
+     * Defaults to apiKey for single-key setups.
+     */
+    clientKey?: string;
+    /** Raw URL or query string for applying ?se_ks_* / ?se_cf_* / ?se_exp_* overrides. */
+    urlOverrides?: string;
+    /** User attributes for flag and experiment evaluation. */
+    user?: User;
+    /** i18n profile to load for SSR translations, e.g. "en:prod". Defaults to "en:prod". */
+    i18nDefaultProfile?: string;
+}
+interface ShipeasyServerHandle {
+    flags: Record<string, boolean>;
+    configs: Record<string, unknown>;
+    experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
+    /** Returns a vanilla-JS string for a single inline <script> tag. */
+    getBootstrapHtml(): string;
+}
+/**
+ * Initialise the ShipEasy server SDK, evaluate flags for this request, and
+ * return a handle. Call once per request in your root layout (or page for
+ * URL-override support). Failure is non-fatal — evaluation returns empty
+ * payloads and i18n falls back to hardcoded strings.
+ */
+declare function shipeasy(opts: ShipeasyServerConfig): Promise<ShipeasyServerHandle>;
+interface BootstrapHtmlOptions {
+    /** SDK client key */
+    apiKey: string;
+    /** i18n profile fed to the loader script. Defaults to "en:prod". */
+    i18nProfile?: string;
+}
+/**
+ * Returns a vanilla-JS script string for a single <script> tag.
+ * Handles everything the client needs at startup:
+ *   - window.__se_devtools_config (when devtoolsAdminUrl is set)
+ *   - window.__SE_BOOTSTRAP (flags + configs + experiments + i18n + apiKey for auto-init)
+ *   - window.i18n shim from SSR strings (prevents hydration mismatches)
+ *   - dynamic <script> injection for the i18n loader
+ *
+ * Framework-agnostic: set innerHTML on a <script> element, nothing else required.
+ * Pass null for bootstrap on pages without flag evaluation — client still auto-inits.
+ */
+declare function getBootstrapHtml(bootstrap: BootstrapPayload | null, i18nData: I18nForRequest | null, opts: BootstrapHtmlOptions): string;
 declare const flags: {
     configure(opts: FlagsClientOptions): void;
     /**
@@ -95,4 +172,4 @@ declare const flags: {
     evaluate(user: User, rawUrl?: string): BootstrapPayload;
 };
 
-export { type BootstrapPayload, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type LabelFile, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getShipeasyServerClient, version };
+export { type BootstrapHtmlOptions, type BootstrapPayload, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, shipeasy, version };

package/dist/server/index.d.ts

@@ -55,6 +55,32 @@ declare class FlagsClient {
      */
     evaluate(user: User, rawUrl?: string): BootstrapPayload;
 }
+interface I18nForRequest {
+    strings: Record<string, string>;
+    locale: string;
+}
+declare const i18n: {
+    /**
+     * Fetch translation labels for the current request and store them in an
+     * async-local context so `i18n.t()` / `i18n.tEl()` in SSR'd client
+     * components return the real translated strings instead of the key.
+     *
+     * Call once per request in the root layout (or page). Failure is silent —
+     * `i18n.t()` falls back to the hardcoded fallback arg when no labels are
+     * loaded.
+     *
+     * @param key     SDK client key (NEXT_PUBLIC_SHIPEASY_CLIENT_KEY)
+     * @param profile i18n profile identifier, e.g. "en:prod"
+     * @param cdnBaseUrl Optional override for the i18n CDN (default: cdn.i18n.shipeasy.ai)
+     */
+    init(key: string, profile: string, cdnBaseUrl?: string): Promise<void>;
+    /**
+     * Return the translation strings loaded for the current request.
+     * Use this to include i18n data in the SSR bootstrap payload so the
+     * client doesn't need an extra network round-trip.
+     */
+    getForRequest(): I18nForRequest;
+};
 interface LabelFile {
     v: number;
     profile: string;
@@ -72,6 +98,57 @@ declare function fetchLabelsForSSR(opts: FetchLabelsOptions): Promise<LabelFile
 declare function configureShipeasyServer(opts: FlagsClientOptions): FlagsClient;
 declare function getShipeasyServerClient(): FlagsClient | null;
 declare function _resetShipeasyServerForTests(): void;
+interface ShipeasyServerConfig {
+    /**
+     * Server-side API key — authenticates flag/experiment fetches from the edge.
+     * Never embedded in browser output. A warning is logged if omitted.
+     */
+    apiKey?: string;
+    /**
+     * Public client key — embedded in window.__SE_BOOTSTRAP and used by the
+     * browser SDK. Safe to expose (e.g. NEXT_PUBLIC_ env vars).
+     * Defaults to apiKey for single-key setups.
+     */
+    clientKey?: string;
+    /** Raw URL or query string for applying ?se_ks_* / ?se_cf_* / ?se_exp_* overrides. */
+    urlOverrides?: string;
+    /** User attributes for flag and experiment evaluation. */
+    user?: User;
+    /** i18n profile to load for SSR translations, e.g. "en:prod". Defaults to "en:prod". */
+    i18nDefaultProfile?: string;
+}
+interface ShipeasyServerHandle {
+    flags: Record<string, boolean>;
+    configs: Record<string, unknown>;
+    experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
+    /** Returns a vanilla-JS string for a single inline <script> tag. */
+    getBootstrapHtml(): string;
+}
+/**
+ * Initialise the ShipEasy server SDK, evaluate flags for this request, and
+ * return a handle. Call once per request in your root layout (or page for
+ * URL-override support). Failure is non-fatal — evaluation returns empty
+ * payloads and i18n falls back to hardcoded strings.
+ */
+declare function shipeasy(opts: ShipeasyServerConfig): Promise<ShipeasyServerHandle>;
+interface BootstrapHtmlOptions {
+    /** SDK client key */
+    apiKey: string;
+    /** i18n profile fed to the loader script. Defaults to "en:prod". */
+    i18nProfile?: string;
+}
+/**
+ * Returns a vanilla-JS script string for a single <script> tag.
+ * Handles everything the client needs at startup:
+ *   - window.__se_devtools_config (when devtoolsAdminUrl is set)
+ *   - window.__SE_BOOTSTRAP (flags + configs + experiments + i18n + apiKey for auto-init)
+ *   - window.i18n shim from SSR strings (prevents hydration mismatches)
+ *   - dynamic <script> injection for the i18n loader
+ *
+ * Framework-agnostic: set innerHTML on a <script> element, nothing else required.
+ * Pass null for bootstrap on pages without flag evaluation — client still auto-inits.
+ */
+declare function getBootstrapHtml(bootstrap: BootstrapPayload | null, i18nData: I18nForRequest | null, opts: BootstrapHtmlOptions): string;
 declare const flags: {
     configure(opts: FlagsClientOptions): void;
     /**
@@ -95,4 +172,4 @@ declare const flags: {
     evaluate(user: User, rawUrl?: string): BootstrapPayload;
 };
 
-export { type BootstrapPayload, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type LabelFile, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getShipeasyServerClient, version };
+export { type BootstrapHtmlOptions, type BootstrapPayload, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, shipeasy, version };

package/dist/server/index.js

@@ -25,7 +25,10 @@ __export(server_exports, {
   configureShipeasyServer: () => configureShipeasyServer,
   fetchLabelsForSSR: () => fetchLabelsForSSR,
   flags: () => flags,
+  getBootstrapHtml: () => getBootstrapHtml,
   getShipeasyServerClient: () => getShipeasyServerClient,
+  i18n: () => i18n,
+  shipeasy: () => shipeasy,
   version: () => version
 });
 module.exports = __toCommonJS(server_exports);
@@ -349,6 +352,39 @@ var FlagsClient = class {
     return { flags: flags2, configs, experiments };
   }
 };
+var { AsyncLocalStorage } = require("async_hooks");
+var _I18N_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n");
+var _i18nALS = new AsyncLocalStorage();
+globalThis[_I18N_SSR_SYM] = () => _i18nALS.getStore() ?? null;
+var i18n = {
+  /**
+   * Fetch translation labels for the current request and store them in an
+   * async-local context so `i18n.t()` / `i18n.tEl()` in SSR'd client
+   * components return the real translated strings instead of the key.
+   *
+   * Call once per request in the root layout (or page). Failure is silent —
+   * `i18n.t()` falls back to the hardcoded fallback arg when no labels are
+   * loaded.
+   *
+   * @param key     SDK client key (NEXT_PUBLIC_SHIPEASY_CLIENT_KEY)
+   * @param profile i18n profile identifier, e.g. "en:prod"
+   * @param cdnBaseUrl Optional override for the i18n CDN (default: cdn.i18n.shipeasy.ai)
+   */
+  async init(key, profile, cdnBaseUrl) {
+    if (_i18nALS.getStore() !== void 0) return;
+    const labels = await fetchLabelsForSSR({ key, profile, cdnBaseUrl }).catch(() => null);
+    const locale = profile.split(":")[0] || "en";
+    _i18nALS.enterWith({ strings: labels?.strings ?? {}, locale });
+  },
+  /**
+   * Return the translation strings loaded for the current request.
+   * Use this to include i18n data in the SSR bootstrap payload so the
+   * client doesn't need an extra network round-trip.
+   */
+  getForRequest() {
+    return _i18nALS.getStore() ?? { strings: {}, locale: "en" };
+  }
+};
 var DEFAULT_I18N_CDN = "https://cdn.i18n.shipeasy.ai";
 async function fetchJson(url, timeoutMs = 2e3) {
   const controller = new AbortController();
@@ -392,6 +428,51 @@ function _resetShipeasyServerForTests() {
   _server?.destroy();
   _server = null;
 }
+async function shipeasy(opts) {
+  if (!opts.apiKey && !opts.clientKey) {
+    console.warn("[shipeasy] apiKey is required \u2014 flag evaluation and i18n will not load.");
+  } else if (!opts.apiKey) {
+    console.warn("[shipeasy] apiKey not set \u2014 falling back to clientKey for server requests.");
+  }
+  const apiKey = opts.apiKey ?? opts.clientKey ?? "";
+  const clientKey = opts.clientKey ?? opts.apiKey ?? "";
+  const profile = opts.i18nDefaultProfile ?? "en:prod";
+  flags.configure({ apiKey });
+  await Promise.allSettled([flags.initOnce(), i18n.init(apiKey, profile)]);
+  const bootstrap = flags.evaluate(opts.user ?? {}, opts.urlOverrides);
+  const i18nData = i18n.getForRequest();
+  return {
+    flags: bootstrap.flags,
+    configs: bootstrap.configs,
+    experiments: bootstrap.experiments,
+    getBootstrapHtml() {
+      return getBootstrapHtml(bootstrap, i18nData, { apiKey: clientKey });
+    }
+  };
+}
+function getBootstrapHtml(bootstrap, i18nData, opts) {
+  const parts = [];
+  const apiUrl = "https://cdn.shipeasy.ai";
+  const profile = opts.i18nProfile ?? "en:prod";
+  const payload = {
+    flags: bootstrap?.flags ?? {},
+    configs: bootstrap?.configs ?? {},
+    experiments: bootstrap?.experiments ?? {},
+    apiKey: opts.apiKey,
+    apiUrl
+  };
+  if (i18nData) payload.i18n = i18nData;
+  parts.push(`window.__SE_BOOTSTRAP=${JSON.stringify(payload)};`);
+  if (i18nData?.strings && Object.keys(i18nData.strings).length > 0) {
+    parts.push(
+      `(function(){var d=window.__SE_BOOTSTRAP.i18n;if(!d)return;window.i18n={locale:d.locale,t:function(k,v){var r=d.strings[k];if(!r)return k;return v?r.replace(/\\{\\{(\\w+)\\}\\}/g,function(_,p){return v[p]!==undefined?String(v[p]):'{{'+p+'}}'}):r;},on:function(){return function(){};}};})();`
+    );
+  }
+  parts.push(
+    `(function(){var s=document.createElement('script');s.src=${JSON.stringify(`${apiUrl}/sdk/i18n/loader.js`)};s.setAttribute('data-key',${JSON.stringify(opts.apiKey)});s.setAttribute('data-profile',${JSON.stringify(profile)});document.head.appendChild(s);})();`
+  );
+  return parts.join("");
+}
 var flags = {
   configure(opts) {
     configureShipeasyServer(opts);
@@ -445,6 +526,9 @@ var flags = {
   configureShipeasyServer,
   fetchLabelsForSSR,
   flags,
+  getBootstrapHtml,
   getShipeasyServerClient,
+  i18n,
+  shipeasy,
   version
 });

package/dist/server/index.mjs

@@ -1,3 +1,10 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
 // src/server/index.ts
 var version = "1.0.0";
 var C1 = 3432918353;
@@ -319,6 +326,39 @@ var FlagsClient = class {
     return { flags: flags2, configs, experiments };
   }
 };
+var { AsyncLocalStorage } = __require("async_hooks");
+var _I18N_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n");
+var _i18nALS = new AsyncLocalStorage();
+globalThis[_I18N_SSR_SYM] = () => _i18nALS.getStore() ?? null;
+var i18n = {
+  /**
+   * Fetch translation labels for the current request and store them in an
+   * async-local context so `i18n.t()` / `i18n.tEl()` in SSR'd client
+   * components return the real translated strings instead of the key.
+   *
+   * Call once per request in the root layout (or page). Failure is silent —
+   * `i18n.t()` falls back to the hardcoded fallback arg when no labels are
+   * loaded.
+   *
+   * @param key     SDK client key (NEXT_PUBLIC_SHIPEASY_CLIENT_KEY)
+   * @param profile i18n profile identifier, e.g. "en:prod"
+   * @param cdnBaseUrl Optional override for the i18n CDN (default: cdn.i18n.shipeasy.ai)
+   */
+  async init(key, profile, cdnBaseUrl) {
+    if (_i18nALS.getStore() !== void 0) return;
+    const labels = await fetchLabelsForSSR({ key, profile, cdnBaseUrl }).catch(() => null);
+    const locale = profile.split(":")[0] || "en";
+    _i18nALS.enterWith({ strings: labels?.strings ?? {}, locale });
+  },
+  /**
+   * Return the translation strings loaded for the current request.
+   * Use this to include i18n data in the SSR bootstrap payload so the
+   * client doesn't need an extra network round-trip.
+   */
+  getForRequest() {
+    return _i18nALS.getStore() ?? { strings: {}, locale: "en" };
+  }
+};
 var DEFAULT_I18N_CDN = "https://cdn.i18n.shipeasy.ai";
 async function fetchJson(url, timeoutMs = 2e3) {
   const controller = new AbortController();
@@ -362,6 +402,51 @@ function _resetShipeasyServerForTests() {
   _server?.destroy();
   _server = null;
 }
+async function shipeasy(opts) {
+  if (!opts.apiKey && !opts.clientKey) {
+    console.warn("[shipeasy] apiKey is required \u2014 flag evaluation and i18n will not load.");
+  } else if (!opts.apiKey) {
+    console.warn("[shipeasy] apiKey not set \u2014 falling back to clientKey for server requests.");
+  }
+  const apiKey = opts.apiKey ?? opts.clientKey ?? "";
+  const clientKey = opts.clientKey ?? opts.apiKey ?? "";
+  const profile = opts.i18nDefaultProfile ?? "en:prod";
+  flags.configure({ apiKey });
+  await Promise.allSettled([flags.initOnce(), i18n.init(apiKey, profile)]);
+  const bootstrap = flags.evaluate(opts.user ?? {}, opts.urlOverrides);
+  const i18nData = i18n.getForRequest();
+  return {
+    flags: bootstrap.flags,
+    configs: bootstrap.configs,
+    experiments: bootstrap.experiments,
+    getBootstrapHtml() {
+      return getBootstrapHtml(bootstrap, i18nData, { apiKey: clientKey });
+    }
+  };
+}
+function getBootstrapHtml(bootstrap, i18nData, opts) {
+  const parts = [];
+  const apiUrl = "https://cdn.shipeasy.ai";
+  const profile = opts.i18nProfile ?? "en:prod";
+  const payload = {
+    flags: bootstrap?.flags ?? {},
+    configs: bootstrap?.configs ?? {},
+    experiments: bootstrap?.experiments ?? {},
+    apiKey: opts.apiKey,
+    apiUrl
+  };
+  if (i18nData) payload.i18n = i18nData;
+  parts.push(`window.__SE_BOOTSTRAP=${JSON.stringify(payload)};`);
+  if (i18nData?.strings && Object.keys(i18nData.strings).length > 0) {
+    parts.push(
+      `(function(){var d=window.__SE_BOOTSTRAP.i18n;if(!d)return;window.i18n={locale:d.locale,t:function(k,v){var r=d.strings[k];if(!r)return k;return v?r.replace(/\\{\\{(\\w+)\\}\\}/g,function(_,p){return v[p]!==undefined?String(v[p]):'{{'+p+'}}'}):r;},on:function(){return function(){};}};})();`
+    );
+  }
+  parts.push(
+    `(function(){var s=document.createElement('script');s.src=${JSON.stringify(`${apiUrl}/sdk/i18n/loader.js`)};s.setAttribute('data-key',${JSON.stringify(opts.apiKey)});s.setAttribute('data-profile',${JSON.stringify(profile)});document.head.appendChild(s);})();`
+  );
+  return parts.join("");
+}
 var flags = {
   configure(opts) {
     configureShipeasyServer(opts);
@@ -414,6 +499,9 @@ export {
   configureShipeasyServer,
   fetchLabelsForSSR,
   flags,
+  getBootstrapHtml,
   getShipeasyServerClient,
+  i18n,
+  shipeasy,
   version
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/sdk",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "Shipeasy SDK — feature gates, runtime configs, experiments, and metrics for the Shipeasy hosted service.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://shipeasy.ai",
@@ -48,13 +48,6 @@
     "LICENSE",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsup",
-    "type-check": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "publish-loader": "wrangler r2 object put shipeasy-sdk/loader-v$npm_package_version.js --file=dist/loader/loader.global.js --content-type 'application/javascript; charset=utf-8' --cache-control 'public, max-age=31536000, immutable' --remote && wrangler r2 object put shipeasy-sdk/loader.js --file=dist/loader/loader.global.js --content-type 'application/javascript; charset=utf-8' --cache-control 'public, max-age=300' --remote"
-  },
   "dependencies": {
     "murmurhash-js": "^1.0.0"
   },
@@ -78,5 +71,12 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "publish-loader": "wrangler r2 object put shipeasy-sdk/loader-v$npm_package_version.js --file=dist/loader/loader.global.js --content-type 'application/javascript; charset=utf-8' --cache-control 'public, max-age=31536000, immutable' --remote && wrangler r2 object put shipeasy-sdk/loader.js --file=dist/loader/loader.global.js --content-type 'application/javascript; charset=utf-8' --cache-control 'public, max-age=300' --remote"
   }
-}
+}