@shipeasy/sdk 1.1.0 → 2.0.0

package/dist/client/index.d.mts

@@ -137,14 +137,25 @@ declare const flags: {
     /** True once identify() has completed and flags are available. */
     readonly ready: boolean;
 };
-/**
- * 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 LABEL_MARKER_START = "\uFFF9";
+declare const LABEL_MARKER_SEP = "\uFFFA";
+declare const LABEL_MARKER_END = "\uFFFB";
+declare const LABEL_MARKER_RE: RegExp;
+declare function encodeLabelMarker(key: string, value: string): string;
+interface LabelAttrs {
+    "data-label": string;
+    "data-variables"?: string;
+    "data-label-desc"?: string;
+}
+declare function labelAttrs(key: string, variables?: Record<string, string | number>, desc?: string): LabelAttrs;
 declare const i18n: {
-    t(key: string, variables?: Record<string, string | number>): string;
+    /**
+     * 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;
     /**
      * Translate a key and return a framework element (e.g. React <span>)
      * carrying `data-label` / `data-variables` attributes so the ShipEasy
@@ -157,7 +168,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;
@@ -170,4 +181,4 @@ declare const i18n: {
     onUpdate(cb: () => void): () => void;
 };
 
-export { type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type ShipeasySdkBridge, type User, _resetShipeasyForTests, attachDevtools, configureShipeasy, flags, getShipeasyClient, i18n, isDevtoolsRequested, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, version };
+export { type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type ShipeasySdkBridge, type User, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, version };

package/dist/client/index.d.ts

@@ -137,14 +137,25 @@ declare const flags: {
     /** True once identify() has completed and flags are available. */
     readonly ready: boolean;
 };
-/**
- * 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 LABEL_MARKER_START = "\uFFF9";
+declare const LABEL_MARKER_SEP = "\uFFFA";
+declare const LABEL_MARKER_END = "\uFFFB";
+declare const LABEL_MARKER_RE: RegExp;
+declare function encodeLabelMarker(key: string, value: string): string;
+interface LabelAttrs {
+    "data-label": string;
+    "data-variables"?: string;
+    "data-label-desc"?: string;
+}
+declare function labelAttrs(key: string, variables?: Record<string, string | number>, desc?: string): LabelAttrs;
 declare const i18n: {
-    t(key: string, variables?: Record<string, string | number>): string;
+    /**
+     * 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;
     /**
      * Translate a key and return a framework element (e.g. React <span>)
      * carrying `data-label` / `data-variables` attributes so the ShipEasy
@@ -157,7 +168,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;
@@ -170,4 +181,4 @@ declare const i18n: {
     onUpdate(cb: () => void): () => void;
 };
 
-export { type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type ShipeasySdkBridge, type User, _resetShipeasyForTests, attachDevtools, configureShipeasy, flags, getShipeasyClient, i18n, isDevtoolsRequested, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, version };
+export { type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type ShipeasySdkBridge, type User, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, version };

package/dist/client/index.js

@@ -21,13 +21,19 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var client_exports = {};
 __export(client_exports, {
   FlagsClientBrowser: () => FlagsClientBrowser,
+  LABEL_MARKER_END: () => LABEL_MARKER_END,
+  LABEL_MARKER_RE: () => LABEL_MARKER_RE,
+  LABEL_MARKER_SEP: () => LABEL_MARKER_SEP,
+  LABEL_MARKER_START: () => LABEL_MARKER_START,
   _resetShipeasyForTests: () => _resetShipeasyForTests,
   attachDevtools: () => attachDevtools,
   configureShipeasy: () => configureShipeasy,
+  encodeLabelMarker: () => encodeLabelMarker,
   flags: () => flags,
   getShipeasyClient: () => getShipeasyClient,
   i18n: () => i18n,
   isDevtoolsRequested: () => isDevtoolsRequested,
+  labelAttrs: () => labelAttrs,
   loadDevtools: () => loadDevtools,
   readConfigOverride: () => readConfigOverride,
   readExpOverride: () => readExpOverride,
@@ -448,13 +454,15 @@ 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 {
@@ -695,11 +703,41 @@ var flags = {
     return _client?.ready ?? false;
   }
 };
+var LABEL_MARKER_START = "\uFFF9";
+var LABEL_MARKER_SEP = "\uFFFA";
+var LABEL_MARKER_END = "\uFFFB";
+var LABEL_MARKER_RE = /([^]+)([^]*)/g;
+function encodeLabelMarker(key, value) {
+  return `${LABEL_MARKER_START}${key}${LABEL_MARKER_SEP}${value}${LABEL_MARKER_END}`;
+}
+function labelAttrs(key, variables, desc) {
+  const attrs = { "data-label": key };
+  if (variables) attrs["data-variables"] = JSON.stringify(variables);
+  if (desc) attrs["data-label-desc"] = 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 = {
-  t(key, variables) {
-    if (typeof window !== "undefined" && window.i18n) return window.i18n.t(key, variables);
-    return key;
+  /**
+   * 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);
   },
   /**
    * Translate a key and return a framework element (e.g. React <span>)
@@ -713,14 +751,10 @@ 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, fallback, variables);
     if (!_createElement) return text;
-    const props = { "data-label": key };
-    if (variables) props["data-variables"] = JSON.stringify(variables);
-    if (desc) props["data-label-desc"] = desc;
-    return _createElement("span", props, text);
+    return _createElement("span", labelAttrs(key, variables, desc), text);
   },
   /** Wire up the element creator once at app startup (call before any tEl use). */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -764,13 +798,19 @@ var i18n = {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FlagsClientBrowser,
+  LABEL_MARKER_END,
+  LABEL_MARKER_RE,
+  LABEL_MARKER_SEP,
+  LABEL_MARKER_START,
   _resetShipeasyForTests,
   attachDevtools,
   configureShipeasy,
+  encodeLabelMarker,
   flags,
   getShipeasyClient,
   i18n,
   isDevtoolsRequested,
+  labelAttrs,
   loadDevtools,
   readConfigOverride,
   readExpOverride,

package/dist/client/index.mjs

@@ -412,13 +412,15 @@ 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 {
@@ -659,11 +661,41 @@ var flags = {
     return _client?.ready ?? false;
   }
 };
+var LABEL_MARKER_START = "\uFFF9";
+var LABEL_MARKER_SEP = "\uFFFA";
+var LABEL_MARKER_END = "\uFFFB";
+var LABEL_MARKER_RE = /([^]+)([^]*)/g;
+function encodeLabelMarker(key, value) {
+  return `${LABEL_MARKER_START}${key}${LABEL_MARKER_SEP}${value}${LABEL_MARKER_END}`;
+}
+function labelAttrs(key, variables, desc) {
+  const attrs = { "data-label": key };
+  if (variables) attrs["data-variables"] = JSON.stringify(variables);
+  if (desc) attrs["data-label-desc"] = 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 = {
-  t(key, variables) {
-    if (typeof window !== "undefined" && window.i18n) return window.i18n.t(key, variables);
-    return key;
+  /**
+   * 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);
   },
   /**
    * Translate a key and return a framework element (e.g. React <span>)
@@ -677,14 +709,10 @@ 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, fallback, variables);
     if (!_createElement) return text;
-    const props = { "data-label": key };
-    if (variables) props["data-variables"] = JSON.stringify(variables);
-    if (desc) props["data-label-desc"] = desc;
-    return _createElement("span", props, text);
+    return _createElement("span", labelAttrs(key, variables, desc), text);
   },
   /** Wire up the element creator once at app startup (call before any tEl use). */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -727,13 +755,19 @@ var i18n = {
 };
 export {
   FlagsClientBrowser,
+  LABEL_MARKER_END,
+  LABEL_MARKER_RE,
+  LABEL_MARKER_SEP,
+  LABEL_MARKER_START,
   _resetShipeasyForTests,
   attachDevtools,
   configureShipeasy,
+  encodeLabelMarker,
   flags,
   getShipeasyClient,
   i18n,
   isDevtoolsRequested,
+  labelAttrs,
   loadDevtools,
   readConfigOverride,
   readExpOverride,

package/dist/server/index.d.mts

@@ -40,6 +40,20 @@ declare class FlagsClient {
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
 }
+interface LabelFile {
+    v: number;
+    profile: string;
+    chunk: string;
+    strings: Record<string, string>;
+}
+interface FetchLabelsOptions {
+    key: string;
+    profile: string;
+    chunk?: string;
+    cdnBaseUrl?: string;
+    timeoutMs?: number;
+}
+declare function fetchLabelsForSSR(opts: FetchLabelsOptions): Promise<LabelFile | null>;
 declare function configureShipeasyServer(opts: FlagsClientOptions): FlagsClient;
 declare function getShipeasyServerClient(): FlagsClient | null;
 declare function _resetShipeasyServerForTests(): void;
@@ -60,4 +74,4 @@ declare const flags: {
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
 };
 
-export { type ExperimentResult, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type User, _resetShipeasyServerForTests, configureShipeasyServer, flags, getShipeasyServerClient, version };
+export { type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type LabelFile, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getShipeasyServerClient, version };

package/dist/server/index.d.ts

@@ -40,6 +40,20 @@ declare class FlagsClient {
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
 }
+interface LabelFile {
+    v: number;
+    profile: string;
+    chunk: string;
+    strings: Record<string, string>;
+}
+interface FetchLabelsOptions {
+    key: string;
+    profile: string;
+    chunk?: string;
+    cdnBaseUrl?: string;
+    timeoutMs?: number;
+}
+declare function fetchLabelsForSSR(opts: FetchLabelsOptions): Promise<LabelFile | null>;
 declare function configureShipeasyServer(opts: FlagsClientOptions): FlagsClient;
 declare function getShipeasyServerClient(): FlagsClient | null;
 declare function _resetShipeasyServerForTests(): void;
@@ -60,4 +74,4 @@ declare const flags: {
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
 };
 
-export { type ExperimentResult, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type User, _resetShipeasyServerForTests, configureShipeasyServer, flags, getShipeasyServerClient, version };
+export { type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type LabelFile, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getShipeasyServerClient, version };

package/dist/server/index.js

@@ -23,6 +23,7 @@ __export(server_exports, {
   FlagsClient: () => FlagsClient,
   _resetShipeasyServerForTests: () => _resetShipeasyServerForTests,
   configureShipeasyServer: () => configureShipeasyServer,
+  fetchLabelsForSSR: () => fetchLabelsForSSR,
   flags: () => flags,
   getShipeasyServerClient: () => getShipeasyServerClient,
   version: () => version
@@ -271,6 +272,36 @@ var FlagsClient = class {
     }).catch((err) => console.warn("[shipeasy] track failed:", String(err)));
   }
 };
+var DEFAULT_I18N_CDN = "https://cdn.i18n.shipeasy.ai";
+async function fetchJson(url, timeoutMs = 2e3) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      signal: controller.signal,
+      next: { revalidate: 60 }
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`);
+    return res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function fetchLabelsForSSR(opts) {
+  const cdn = opts.cdnBaseUrl ?? DEFAULT_I18N_CDN;
+  const chunk = opts.chunk ?? "index";
+  try {
+    const manifest = await fetchJson(
+      `${cdn}/labels/${opts.key}/${opts.profile}/manifest.json`,
+      opts.timeoutMs
+    );
+    const fileUrl = manifest[chunk];
+    if (!fileUrl) return null;
+    return await fetchJson(fileUrl, opts.timeoutMs);
+  } catch {
+    return null;
+  }
+}
 var _server = null;
 function configureShipeasyServer(opts) {
   if (_server) return _server;
@@ -327,6 +358,7 @@ var flags = {
   FlagsClient,
   _resetShipeasyServerForTests,
   configureShipeasyServer,
+  fetchLabelsForSSR,
   flags,
   getShipeasyServerClient,
   version

package/dist/server/index.mjs

@@ -242,6 +242,36 @@ var FlagsClient = class {
     }).catch((err) => console.warn("[shipeasy] track failed:", String(err)));
   }
 };
+var DEFAULT_I18N_CDN = "https://cdn.i18n.shipeasy.ai";
+async function fetchJson(url, timeoutMs = 2e3) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      signal: controller.signal,
+      next: { revalidate: 60 }
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`);
+    return res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function fetchLabelsForSSR(opts) {
+  const cdn = opts.cdnBaseUrl ?? DEFAULT_I18N_CDN;
+  const chunk = opts.chunk ?? "index";
+  try {
+    const manifest = await fetchJson(
+      `${cdn}/labels/${opts.key}/${opts.profile}/manifest.json`,
+      opts.timeoutMs
+    );
+    const fileUrl = manifest[chunk];
+    if (!fileUrl) return null;
+    return await fetchJson(fileUrl, opts.timeoutMs);
+  } catch {
+    return null;
+  }
+}
 var _server = null;
 function configureShipeasyServer(opts) {
   if (_server) return _server;
@@ -297,6 +327,7 @@ export {
   FlagsClient,
   _resetShipeasyServerForTests,
   configureShipeasyServer,
+  fetchLabelsForSSR,
   flags,
   getShipeasyServerClient,
   version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/sdk",
-  "version": "1.1.0",
+  "version": "2.0.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",
@@ -16,8 +16,12 @@
   "browser": "./dist/client/index.js",
   "typesVersions": {
     "*": {
-      "client": ["./dist/client/index.d.ts"],
-      "server": ["./dist/server/index.d.ts"]
+      "client": [
+        "./dist/client/index.d.ts"
+      ],
+      "server": [
+        "./dist/server/index.d.ts"
+      ]
     }
   },
   "exports": {