@shipeasy/sdk 2.5.2 → 3.0.1

package/dist/client/index.d.mts

@@ -137,12 +137,23 @@ 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;
+    /**
+     * Public client key — the ONLY key the browser entrypoint accepts. Authenticates
+     * /sdk/evaluate, /collect and the runtime i18n loader (/sdk/i18n/strings). Safe to
+     * expose (e.g. NEXT_PUBLIC_ env vars). This is a different key from the server key
+     * passed to `shipeasy({ serverKey })` in @shipeasy/sdk/server — never use the
+     * server key here.
+     */
+    clientKey: 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;
+    /**
+     * i18n profile for the runtime string loader, e.g. "en:prod". Defaults to the
+     * profile the server recorded in window.__SE_BOOTSTRAP, then "en:prod".
+     */
+    i18nProfile?: string;
     /**
      * Skip the lazy auto-identify({}) at boot. Defaults to true (auto-identify on).
      * Turn off when the host has its own identify orchestration and wants to
@@ -158,9 +169,9 @@ interface ShipeasyClientConfig {
      * Pass `false` to disable everything, or a per-group object to narrow:
      *
      * ```ts
-     * shipeasy({ apiKey, autoCollect: false });                  // off
-     * shipeasy({ apiKey, autoCollect: { errors: false } });      // vitals + engagement only
-     * shipeasy({ apiKey });                                      // all groups on
+     * shipeasy({ clientKey, autoCollect: false });               // off
+     * shipeasy({ clientKey, autoCollect: { errors: false } });   // vitals + engagement only
+     * shipeasy({ clientKey });                                   // all groups on
      * ```
      */
     autoCollect?: boolean | Partial<AutoCollectGroups>;
@@ -198,8 +209,8 @@ interface BootstrapPayload {
      * the killswitch is not whole-killed and the map carries per-switch state.
      */
     killswitches?: Record<string, boolean | Record<string, boolean>>;
-    /** Set by getBootstrapHtml() for auto-init. Not part of evaluate() output. */
-    apiKey?: string;
+    /** i18n profile the server rendered with, so the client loader matches. No key is embedded. */
+    i18nProfile?: string;
     apiUrl?: string;
     /** When true, tEl() returns marker-wrapped strings for devtools label editing. */
     editLabels?: boolean;

package/dist/client/index.d.ts

@@ -137,12 +137,23 @@ 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;
+    /**
+     * Public client key — the ONLY key the browser entrypoint accepts. Authenticates
+     * /sdk/evaluate, /collect and the runtime i18n loader (/sdk/i18n/strings). Safe to
+     * expose (e.g. NEXT_PUBLIC_ env vars). This is a different key from the server key
+     * passed to `shipeasy({ serverKey })` in @shipeasy/sdk/server — never use the
+     * server key here.
+     */
+    clientKey: 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;
+    /**
+     * i18n profile for the runtime string loader, e.g. "en:prod". Defaults to the
+     * profile the server recorded in window.__SE_BOOTSTRAP, then "en:prod".
+     */
+    i18nProfile?: string;
     /**
      * Skip the lazy auto-identify({}) at boot. Defaults to true (auto-identify on).
      * Turn off when the host has its own identify orchestration and wants to
@@ -158,9 +169,9 @@ interface ShipeasyClientConfig {
      * Pass `false` to disable everything, or a per-group object to narrow:
      *
      * ```ts
-     * shipeasy({ apiKey, autoCollect: false });                  // off
-     * shipeasy({ apiKey, autoCollect: { errors: false } });      // vitals + engagement only
-     * shipeasy({ apiKey });                                      // all groups on
+     * shipeasy({ clientKey, autoCollect: false });               // off
+     * shipeasy({ clientKey, autoCollect: { errors: false } });   // vitals + engagement only
+     * shipeasy({ clientKey });                                   // all groups on
      * ```
      */
     autoCollect?: boolean | Partial<AutoCollectGroups>;
@@ -198,8 +209,8 @@ interface BootstrapPayload {
      * the killswitch is not whole-killed and the map carries per-switch state.
      */
     killswitches?: Record<string, boolean | Record<string, boolean>>;
-    /** Set by getBootstrapHtml() for auto-init. Not part of evaluate() output. */
-    apiKey?: string;
+    /** i18n profile the server rendered with, so the client loader matches. No key is embedded. */
+    i18nProfile?: string;
     apiUrl?: string;
     /** When true, tEl() returns marker-wrapped strings for devtools label editing. */
     editLabels?: boolean;

package/dist/client/index.js

@@ -711,12 +711,14 @@ function shipeasy(opts) {
   const ac = opts.autoCollect;
   const blanket = ac === false ? false : true;
   const groups = ac && typeof ac === "object" ? ac : void 0;
+  const baseUrl = opts.baseUrl ?? "https://cdn.shipeasy.ai";
   const client = configureShipeasy({
-    sdkKey: opts.apiKey,
-    baseUrl: opts.baseUrl ?? "https://cdn.shipeasy.ai",
+    sdkKey: opts.clientKey,
+    baseUrl,
     autoGuardrails: blanket,
     autoGuardrailGroups: groups
   });
+  injectI18nLoader(opts.clientKey, baseUrl, opts.i18nProfile);
   flags.notifyMounted();
   if (opts.autoIdentify !== false) {
     void client.identify({}).catch((err) => {
@@ -736,6 +738,23 @@ function getShipeasyClient() {
 function _resetShipeasyForTests() {
   _client?.destroy();
   _client = null;
+  _i18nLoaderInjected = false;
+}
+var _i18nLoaderInjected = false;
+function injectI18nLoader(clientKey, baseUrl, profileOpt) {
+  if (_i18nLoaderInjected || typeof document === "undefined") return;
+  if (!clientKey || typeof document.createElement !== "function" || !document.head) return;
+  _i18nLoaderInjected = true;
+  try {
+    const bs = getBootstrap();
+    const profile = profileOpt ?? bs?.i18nProfile ?? "en:prod";
+    const s = document.createElement("script");
+    s.src = `${baseUrl}/sdk/i18n/loader.js`;
+    s.setAttribute("data-key", clientKey);
+    s.setAttribute("data-profile", profile);
+    document.head.appendChild(s);
+  } catch {
+  }
 }
 function getBootstrap() {
   if (typeof window === "undefined") return null;
@@ -1090,12 +1109,6 @@ 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,

package/dist/client/index.mjs

@@ -668,12 +668,14 @@ function shipeasy(opts) {
   const ac = opts.autoCollect;
   const blanket = ac === false ? false : true;
   const groups = ac && typeof ac === "object" ? ac : void 0;
+  const baseUrl = opts.baseUrl ?? "https://cdn.shipeasy.ai";
   const client = configureShipeasy({
-    sdkKey: opts.apiKey,
-    baseUrl: opts.baseUrl ?? "https://cdn.shipeasy.ai",
+    sdkKey: opts.clientKey,
+    baseUrl,
     autoGuardrails: blanket,
     autoGuardrailGroups: groups
   });
+  injectI18nLoader(opts.clientKey, baseUrl, opts.i18nProfile);
   flags.notifyMounted();
   if (opts.autoIdentify !== false) {
     void client.identify({}).catch((err) => {
@@ -693,6 +695,23 @@ function getShipeasyClient() {
 function _resetShipeasyForTests() {
   _client?.destroy();
   _client = null;
+  _i18nLoaderInjected = false;
+}
+var _i18nLoaderInjected = false;
+function injectI18nLoader(clientKey, baseUrl, profileOpt) {
+  if (_i18nLoaderInjected || typeof document === "undefined") return;
+  if (!clientKey || typeof document.createElement !== "function" || !document.head) return;
+  _i18nLoaderInjected = true;
+  try {
+    const bs = getBootstrap();
+    const profile = profileOpt ?? bs?.i18nProfile ?? "en:prod";
+    const s = document.createElement("script");
+    s.src = `${baseUrl}/sdk/i18n/loader.js`;
+    s.setAttribute("data-key", clientKey);
+    s.setAttribute("data-profile", profile);
+    document.head.appendChild(s);
+  } catch {
+  }
 }
 function getBootstrap() {
   if (typeof window === "undefined") return null;
@@ -1047,12 +1066,6 @@ 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,

package/dist/server/index.d.mts

@@ -132,20 +132,15 @@ declare function getShipeasyServerClient(): FlagsClient | null;
 declare function _resetShipeasyServerForTests(): void;
 interface ShipeasyServerConfig {
     /**
-     * Server-side API key — authenticates flag/experiment fetches from the edge
-     * (requireKey("server")). Never embedded in browser output. If omitted, flag
-     * and experiment evaluation is skipped and an error is logged — it is NOT
-     * substituted with clientKey (a client key 401s against /sdk/flags).
+     * Server key — the ONLY key the server entrypoint accepts. Authenticates
+     * flag/experiment fetches (requireKey("server")) AND SSR i18n string fetches
+     * (the /sdk/i18n/strings route accepts the server key for server-side use).
+     * Never embedded in browser output. The browser uses its own client key via
+     * `shipeasy({ clientKey })` from `@shipeasy/sdk/client` — the server never
+     * sees or forwards the client key. If omitted, flag/experiment/i18n loading
+     * is skipped and an error is logged.
      */
-    apiKey?: string;
-    /**
-     * Public client key — embedded in window.__SE_BOOTSTRAP and used by the
-     * browser SDK, and authenticates i18n string fetches (requireKey("client")).
-     * Safe to expose (e.g. NEXT_PUBLIC_ env vars). If omitted, i18n loading is
-     * skipped and an error is logged — it is NOT substituted with apiKey (a
-     * server key 401s against /sdk/i18n/strings).
-     */
-    clientKey?: string;
+    serverKey?: string;
     /** Raw URL or query string for applying ?se_ks_* / ?se_cf_* / ?se_exp_* overrides. */
     urlOverrides?: string;
     /** User attributes for flag and experiment evaluation. */
@@ -168,23 +163,24 @@ interface ShipeasyServerHandle {
  */
 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". */
+    /** i18n profile recorded in the bootstrap so the client loader matches SSR. Defaults to "en:prod". */
     i18nProfile?: string;
     /** When true, tEl() embeds label markers so the devtools can highlight them. */
     editLabels?: boolean;
 }
 /**
- * Returns a vanilla-JS script string for a single <script> tag.
- * Handles everything the client needs at startup:
+ * Returns a vanilla-JS string for a single inline <script> tag. Handles
+ * everything the client needs at startup EXCEPT the key — no SDK key is ever
+ * embedded here (the server only knows the server key, which must stay
+ * server-side). The browser supplies its own client key via
+ * `shipeasy({ clientKey })` from @shipeasy/sdk/client, which also injects the
+ * runtime i18n loader. This script emits:
  *   - 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
+ *   - window.__SE_BOOTSTRAP (flags + configs + experiments + i18n DATA + i18nProfile, NO key)
+ *   - window.i18n shim from SSR strings (prevents hydration mismatches / FOUC)
+ *   - devtools overlay loader when ?se / ?se_devtools is present
  *
  * 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: {

package/dist/server/index.d.ts

@@ -132,20 +132,15 @@ declare function getShipeasyServerClient(): FlagsClient | null;
 declare function _resetShipeasyServerForTests(): void;
 interface ShipeasyServerConfig {
     /**
-     * Server-side API key — authenticates flag/experiment fetches from the edge
-     * (requireKey("server")). Never embedded in browser output. If omitted, flag
-     * and experiment evaluation is skipped and an error is logged — it is NOT
-     * substituted with clientKey (a client key 401s against /sdk/flags).
+     * Server key — the ONLY key the server entrypoint accepts. Authenticates
+     * flag/experiment fetches (requireKey("server")) AND SSR i18n string fetches
+     * (the /sdk/i18n/strings route accepts the server key for server-side use).
+     * Never embedded in browser output. The browser uses its own client key via
+     * `shipeasy({ clientKey })` from `@shipeasy/sdk/client` — the server never
+     * sees or forwards the client key. If omitted, flag/experiment/i18n loading
+     * is skipped and an error is logged.
      */
-    apiKey?: string;
-    /**
-     * Public client key — embedded in window.__SE_BOOTSTRAP and used by the
-     * browser SDK, and authenticates i18n string fetches (requireKey("client")).
-     * Safe to expose (e.g. NEXT_PUBLIC_ env vars). If omitted, i18n loading is
-     * skipped and an error is logged — it is NOT substituted with apiKey (a
-     * server key 401s against /sdk/i18n/strings).
-     */
-    clientKey?: string;
+    serverKey?: string;
     /** Raw URL or query string for applying ?se_ks_* / ?se_cf_* / ?se_exp_* overrides. */
     urlOverrides?: string;
     /** User attributes for flag and experiment evaluation. */
@@ -168,23 +163,24 @@ interface ShipeasyServerHandle {
  */
 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". */
+    /** i18n profile recorded in the bootstrap so the client loader matches SSR. Defaults to "en:prod". */
     i18nProfile?: string;
     /** When true, tEl() embeds label markers so the devtools can highlight them. */
     editLabels?: boolean;
 }
 /**
- * Returns a vanilla-JS script string for a single <script> tag.
- * Handles everything the client needs at startup:
+ * Returns a vanilla-JS string for a single inline <script> tag. Handles
+ * everything the client needs at startup EXCEPT the key — no SDK key is ever
+ * embedded here (the server only knows the server key, which must stay
+ * server-side). The browser supplies its own client key via
+ * `shipeasy({ clientKey })` from @shipeasy/sdk/client, which also injects the
+ * runtime i18n loader. This script emits:
  *   - 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
+ *   - window.__SE_BOOTSTRAP (flags + configs + experiments + i18n DATA + i18nProfile, NO key)
+ *   - window.i18n shim from SSR strings (prevents hydration mismatches / FOUC)
+ *   - devtools overlay loader when ?se / ?se_devtools is present
  *
  * 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: {

package/dist/server/index.js

@@ -387,6 +387,7 @@ var _I18N_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n");
 var _EDIT_MODE_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-edit-mode");
 var _i18nALS = new import_node_async_hooks.AsyncLocalStorage();
 var _I18N_CACHE_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n-cache");
+var I18N_CACHE_TTL_MS = 6e4;
 var _i18nCache = globalThis[_I18N_CACHE_SYM] ?? (globalThis[_I18N_CACHE_SYM] = /* @__PURE__ */ new Map());
 globalThis[_I18N_SSR_SYM] = () => {
   const fromALS = _i18nALS.getStore();
@@ -432,14 +433,19 @@ var i18n = {
     const existingALS = _i18nALS.getStore();
     if (existingALS && Object.keys(existingALS.strings).length > 0) return;
     const cached = _i18nCache.get(profile);
-    if (cached && Object.keys(cached.strings).length > 0) {
+    if (cached && Object.keys(cached.strings).length > 0 && Date.now() - cached.fetchedAt < I18N_CACHE_TTL_MS) {
       _i18nALS.enterWith(cached);
       return;
     }
     const labels = await fetchLabelsForSSR({ key, profile, cdnBaseUrl }).catch(() => null);
     const locale = profile.split(":")[0] || "en";
     const store = { strings: labels?.strings ?? {}, locale };
-    if (Object.keys(store.strings).length > 0) _i18nCache.set(profile, store);
+    if (Object.keys(store.strings).length > 0) {
+      _i18nCache.set(profile, { ...store, fetchedAt: Date.now() });
+    } else if (cached && Object.keys(cached.strings).length > 0) {
+      _i18nALS.enterWith(cached);
+      return;
+    }
     _i18nALS.enterWith(store);
   },
   /**
@@ -486,7 +492,6 @@ async function fetchLabelsForSSR(opts) {
   }
 }
 var _server = null;
-var _rememberedClientKey = null;
 function configureShipeasyServer(opts) {
   if (_server) return _server;
   _server = new FlagsClient(opts);
@@ -500,21 +505,14 @@ function _resetShipeasyServerForTests() {
   _server = null;
 }
 async function shipeasy(opts) {
-  const apiKey = opts.apiKey ?? "";
-  const clientKey = opts.clientKey ?? _rememberedClientKey ?? "";
-  if (opts.clientKey && !_rememberedClientKey) _rememberedClientKey = opts.clientKey;
-  if (!apiKey) {
-    console.error(
-      "[shipeasy] No server key \u2014 flags & experiments skipped. Pass `apiKey` to shipeasy() with your server key (SHIPEASY_SERVER_KEY). Set it as a Worker secret with `wrangler secret put SHIPEASY_SERVER_KEY` (or add it to .env for local dev). Do not pass a client key here \u2014 /sdk/flags requires a server key and will 401."
-    );
-  }
-  if (!clientKey) {
+  const serverKey = opts.serverKey ?? "";
+  if (!serverKey) {
     console.error(
-      "[shipeasy] No client key \u2014 i18n strings skipped, falling back to hardcoded text. Pass `clientKey` to shipeasy() with your public client key (NEXT_PUBLIC_SHIPEASY_CLIENT_KEY). Do not pass a server key here \u2014 /sdk/i18n/strings requires a client key and will 401."
+      "[shipeasy] No server key \u2014 flags, experiments and SSR i18n skipped. Pass `serverKey` to shipeasy() from @shipeasy/sdk/server with your server key (SHIPEASY_SERVER_KEY). Set it as a Worker secret with `wrangler secret put SHIPEASY_SERVER_KEY` (or add it to .env for local dev). Do not pass a client key here \u2014 the server entrypoint only accepts the server key."
     );
   }
   const profile = opts.i18nDefaultProfile ?? "en:prod";
-  flags.configure({ apiKey });
+  flags.configure({ apiKey: serverKey });
   let resolvedUrlOverrides = opts.urlOverrides;
   if (!resolvedUrlOverrides) {
     try {
@@ -535,8 +533,8 @@ async function shipeasy(opts) {
   const editLabels = resolvedUrlOverrides ? new URLSearchParams(resolvedUrlOverrides).has("se_edit_labels") : false;
   globalThis[_EDIT_MODE_SSR_SYM] = editLabels;
   await Promise.allSettled([
-    apiKey ? flags.initOnce() : Promise.resolve(),
-    clientKey ? i18n.init(clientKey, profile) : Promise.resolve()
+    serverKey ? flags.initOnce() : Promise.resolve(),
+    serverKey ? i18n.init(serverKey, profile) : Promise.resolve()
   ]);
   const bootstrap = flags.evaluate(opts.user ?? {}, resolvedUrlOverrides);
   const i18nData = i18n.getForRequest();
@@ -546,7 +544,6 @@ async function shipeasy(opts) {
     experiments: bootstrap.experiments,
     getBootstrapHtml() {
       return getBootstrapHtml(bootstrap, i18nData, {
-        apiKey: clientKey,
         editLabels,
         i18nProfile: profile
       });
@@ -561,7 +558,9 @@ function getBootstrapHtml(bootstrap, i18nData, opts) {
     flags: bootstrap?.flags ?? {},
     configs: bootstrap?.configs ?? {},
     experiments: bootstrap?.experiments ?? {},
-    apiKey: opts.apiKey,
+    // No key here — the server only knows the server key, which must never reach
+    // the browser. The client supplies its own client key via shipeasy({ clientKey }).
+    i18nProfile: profile,
     apiUrl
   };
   if (i18nData) payload.i18n = i18nData;
@@ -575,9 +574,6 @@ function getBootstrapHtml(bootstrap, i18nData, opts) {
       `(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);})();`
-  );
   parts.push(
     `(function(){var p=new URLSearchParams(location.search);if(p.has('se')||p.has('se_devtools')){var d=document.createElement('script');d.src='https://shipeasy.ai/se-devtools.js';document.head.appendChild(d);}})();`
   );

package/dist/server/index.mjs

@@ -344,6 +344,7 @@ var _I18N_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n");
 var _EDIT_MODE_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-edit-mode");
 var _i18nALS = new AsyncLocalStorage();
 var _I18N_CACHE_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n-cache");
+var I18N_CACHE_TTL_MS = 6e4;
 var _i18nCache = globalThis[_I18N_CACHE_SYM] ?? (globalThis[_I18N_CACHE_SYM] = /* @__PURE__ */ new Map());
 globalThis[_I18N_SSR_SYM] = () => {
   const fromALS = _i18nALS.getStore();
@@ -389,14 +390,19 @@ var i18n = {
     const existingALS = _i18nALS.getStore();
     if (existingALS && Object.keys(existingALS.strings).length > 0) return;
     const cached = _i18nCache.get(profile);
-    if (cached && Object.keys(cached.strings).length > 0) {
+    if (cached && Object.keys(cached.strings).length > 0 && Date.now() - cached.fetchedAt < I18N_CACHE_TTL_MS) {
       _i18nALS.enterWith(cached);
       return;
     }
     const labels = await fetchLabelsForSSR({ key, profile, cdnBaseUrl }).catch(() => null);
     const locale = profile.split(":")[0] || "en";
     const store = { strings: labels?.strings ?? {}, locale };
-    if (Object.keys(store.strings).length > 0) _i18nCache.set(profile, store);
+    if (Object.keys(store.strings).length > 0) {
+      _i18nCache.set(profile, { ...store, fetchedAt: Date.now() });
+    } else if (cached && Object.keys(cached.strings).length > 0) {
+      _i18nALS.enterWith(cached);
+      return;
+    }
     _i18nALS.enterWith(store);
   },
   /**
@@ -443,7 +449,6 @@ async function fetchLabelsForSSR(opts) {
   }
 }
 var _server = null;
-var _rememberedClientKey = null;
 function configureShipeasyServer(opts) {
   if (_server) return _server;
   _server = new FlagsClient(opts);
@@ -457,21 +462,14 @@ function _resetShipeasyServerForTests() {
   _server = null;
 }
 async function shipeasy(opts) {
-  const apiKey = opts.apiKey ?? "";
-  const clientKey = opts.clientKey ?? _rememberedClientKey ?? "";
-  if (opts.clientKey && !_rememberedClientKey) _rememberedClientKey = opts.clientKey;
-  if (!apiKey) {
-    console.error(
-      "[shipeasy] No server key \u2014 flags & experiments skipped. Pass `apiKey` to shipeasy() with your server key (SHIPEASY_SERVER_KEY). Set it as a Worker secret with `wrangler secret put SHIPEASY_SERVER_KEY` (or add it to .env for local dev). Do not pass a client key here \u2014 /sdk/flags requires a server key and will 401."
-    );
-  }
-  if (!clientKey) {
+  const serverKey = opts.serverKey ?? "";
+  if (!serverKey) {
     console.error(
-      "[shipeasy] No client key \u2014 i18n strings skipped, falling back to hardcoded text. Pass `clientKey` to shipeasy() with your public client key (NEXT_PUBLIC_SHIPEASY_CLIENT_KEY). Do not pass a server key here \u2014 /sdk/i18n/strings requires a client key and will 401."
+      "[shipeasy] No server key \u2014 flags, experiments and SSR i18n skipped. Pass `serverKey` to shipeasy() from @shipeasy/sdk/server with your server key (SHIPEASY_SERVER_KEY). Set it as a Worker secret with `wrangler secret put SHIPEASY_SERVER_KEY` (or add it to .env for local dev). Do not pass a client key here \u2014 the server entrypoint only accepts the server key."
     );
   }
   const profile = opts.i18nDefaultProfile ?? "en:prod";
-  flags.configure({ apiKey });
+  flags.configure({ apiKey: serverKey });
   let resolvedUrlOverrides = opts.urlOverrides;
   if (!resolvedUrlOverrides) {
     try {
@@ -492,8 +490,8 @@ async function shipeasy(opts) {
   const editLabels = resolvedUrlOverrides ? new URLSearchParams(resolvedUrlOverrides).has("se_edit_labels") : false;
   globalThis[_EDIT_MODE_SSR_SYM] = editLabels;
   await Promise.allSettled([
-    apiKey ? flags.initOnce() : Promise.resolve(),
-    clientKey ? i18n.init(clientKey, profile) : Promise.resolve()
+    serverKey ? flags.initOnce() : Promise.resolve(),
+    serverKey ? i18n.init(serverKey, profile) : Promise.resolve()
   ]);
   const bootstrap = flags.evaluate(opts.user ?? {}, resolvedUrlOverrides);
   const i18nData = i18n.getForRequest();
@@ -503,7 +501,6 @@ async function shipeasy(opts) {
     experiments: bootstrap.experiments,
     getBootstrapHtml() {
       return getBootstrapHtml(bootstrap, i18nData, {
-        apiKey: clientKey,
         editLabels,
         i18nProfile: profile
       });
@@ -518,7 +515,9 @@ function getBootstrapHtml(bootstrap, i18nData, opts) {
     flags: bootstrap?.flags ?? {},
     configs: bootstrap?.configs ?? {},
     experiments: bootstrap?.experiments ?? {},
-    apiKey: opts.apiKey,
+    // No key here — the server only knows the server key, which must never reach
+    // the browser. The client supplies its own client key via shipeasy({ clientKey }).
+    i18nProfile: profile,
     apiUrl
   };
   if (i18nData) payload.i18n = i18nData;
@@ -532,9 +531,6 @@ function getBootstrapHtml(bootstrap, i18nData, opts) {
       `(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);})();`
-  );
   parts.push(
     `(function(){var p=new URLSearchParams(location.search);if(p.has('se')||p.has('se_devtools')){var d=document.createElement('script');d.src='https://shipeasy.ai/se-devtools.js';document.head.appendChild(d);}})();`
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/sdk",
-  "version": "2.5.2",
+  "version": "3.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",