@shipeasy/sdk 3.0.0 → 3.1.0

package/dist/client/index.d.mts

@@ -53,6 +53,15 @@ interface FlagsClientBrowserOptions {
     autoGuardrailGroups?: Partial<AutoCollectGroups>;
     /** Which published env to read values from. Defaults to "prod". */
     env?: FlagsClientBrowserEnv;
+    /**
+     * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
+     * getExperiment/getKillswitch call fires one fire-and-forget sendBeacon so
+     * usage is counted by Cloudflare's native per-path analytics. Pass `true` to
+     * disable entirely.
+     */
+    disableTelemetry?: boolean;
+    /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
+    telemetryUrl?: string;
 }
 declare class FlagsClientBrowser {
     private readonly sdkKey;
@@ -64,6 +73,7 @@ declare class FlagsClientBrowser {
     private anonId;
     private userId;
     private buffer;
+    private telemetry;
     private guardrailsInstalled;
     private listeners;
     private overrideListenerInstalled;
@@ -175,6 +185,12 @@ interface ShipeasyClientConfig {
      * ```
      */
     autoCollect?: boolean | Partial<AutoCollectGroups>;
+    /**
+     * Disable per-evaluation usage telemetry. Telemetry is ON by default — every
+     * flag/config/experiment/killswitch read fires one fire-and-forget beacon
+     * counted by Cloudflare's native per-path analytics. Pass `true` to opt out.
+     */
+    disableTelemetry?: boolean;
 }
 /**
  * Initialise the ShipEasy client SDK and wire up lazy devtools.

package/dist/client/index.d.ts

@@ -53,6 +53,15 @@ interface FlagsClientBrowserOptions {
     autoGuardrailGroups?: Partial<AutoCollectGroups>;
     /** Which published env to read values from. Defaults to "prod". */
     env?: FlagsClientBrowserEnv;
+    /**
+     * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
+     * getExperiment/getKillswitch call fires one fire-and-forget sendBeacon so
+     * usage is counted by Cloudflare's native per-path analytics. Pass `true` to
+     * disable entirely.
+     */
+    disableTelemetry?: boolean;
+    /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
+    telemetryUrl?: string;
 }
 declare class FlagsClientBrowser {
     private readonly sdkKey;
@@ -64,6 +73,7 @@ declare class FlagsClientBrowser {
     private anonId;
     private userId;
     private buffer;
+    private telemetry;
     private guardrailsInstalled;
     private listeners;
     private overrideListenerInstalled;
@@ -175,6 +185,12 @@ interface ShipeasyClientConfig {
      * ```
      */
     autoCollect?: boolean | Partial<AutoCollectGroups>;
+    /**
+     * Disable per-evaluation usage telemetry. Telemetry is ON by default — every
+     * flag/config/experiment/killswitch read fires one fire-and-forget beacon
+     * counted by Cloudflare's native per-path analytics. Pass `true` to opt out.
+     */
+    disableTelemetry?: boolean;
 }
 /**
  * Initialise the ShipEasy client SDK and wire up lazy devtools.

package/dist/client/index.js

@@ -42,6 +42,67 @@ __export(client_exports, {
   version: () => version
 });
 module.exports = __toCommonJS(client_exports);
+
+// src/telemetry.ts
+async function sha256Hex(input) {
+  const buf = new TextEncoder().encode(input);
+  const digest = await crypto.subtle.digest("SHA-256", buf);
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var DEFAULT_TELEMETRY_URL = "https://t.shipeasy.ai";
+var Telemetry = class {
+  prefix;
+  disabled;
+  dedupeMs;
+  // Last-emit timestamp per `feature/resource`, for the dedup window. Bounded by
+  // the number of distinct keys the app reads.
+  lastEmit = /* @__PURE__ */ new Map();
+  // Resolved once at construction and reused by every emit(), so the per-eval
+  // cost is a Map-free microtask, not a hash.
+  keyHash;
+  constructor(opts) {
+    const endpoint = (opts.endpoint ?? "").replace(/\/$/, "");
+    this.disabled = opts.disabled === true || !opts.sdkKey || !endpoint;
+    this.dedupeMs = opts.dedupeMs ?? 2e3;
+    this.prefix = `${endpoint}/t`;
+    this.keyHash = this.disabled ? null : sha256Hex(opts.sdkKey).then((h) => `${h}/${opts.side}/${encodeURIComponent(opts.env)}`).catch(() => "");
+  }
+  /**
+   * Emit a single best-effort usage beacon for one evaluation. Never blocks the
+   * caller (the hash is already resolved) and never throws — a failed beacon
+   * must never affect the evaluation it measures.
+   */
+  emit(feature, resource) {
+    if (this.disabled || !this.keyHash) return;
+    if (this.dedupeMs > 0) {
+      const dedupeKey = `${feature}/${resource}`;
+      const now = Date.now();
+      const last = this.lastEmit.get(dedupeKey);
+      if (last !== void 0 && now - last < this.dedupeMs) return;
+      this.lastEmit.set(dedupeKey, now);
+    }
+    void this.keyHash.then((suffix) => {
+      if (!suffix) return;
+      send(`${this.prefix}/${suffix}/${feature}/${encodeURIComponent(resource)}`);
+    });
+  }
+};
+function send(url) {
+  try {
+    if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(url);
+      return;
+    }
+    const f = globalThis.fetch;
+    if (typeof f === "function") {
+      void f(url, { method: "GET", keepalive: true }).catch(() => {
+      });
+    }
+  } catch {
+  }
+}
+
+// src/client/index.ts
 var version = "1.0.0";
 var FLUSH_INTERVAL_MS = 5e3;
 var MAX_BUFFER = 100;
@@ -427,6 +488,7 @@ var FlagsClientBrowser = class {
   anonId;
   userId = "";
   buffer;
+  telemetry;
   guardrailsInstalled = false;
   listeners = /* @__PURE__ */ new Set();
   overrideListenerInstalled = false;
@@ -450,6 +512,13 @@ var FlagsClientBrowser = class {
     };
     this.anonId = getOrCreateAnonId();
     this.buffer = new EventBuffer(`${this.baseUrl}/collect`, this.sdkKey);
+    this.telemetry = new Telemetry({
+      endpoint: opts.telemetryUrl ?? DEFAULT_TELEMETRY_URL,
+      sdkKey: this.sdkKey,
+      side: "client",
+      env: this.env,
+      disabled: opts.disableTelemetry
+    });
     void this.buffer.flushPendingAlias();
   }
   async identify(user) {
@@ -499,12 +568,14 @@ var FlagsClientBrowser = class {
     this.evalResult = data;
   }
   getFlag(name) {
+    this.telemetry.emit("gate", name);
     if (this.evalResult === null) return false;
     const ov = readGateOverride(name);
     if (ov !== null) return ov;
     return this.evalResult.flags[name] ?? false;
   }
   getConfig(name, decode) {
+    this.telemetry.emit("config", name);
     if (this.evalResult === null) return void 0;
     const ov = readConfigOverride(name);
     const raw = ov !== void 0 ? ov : this.evalResult.configs?.[name];
@@ -518,6 +589,7 @@ var FlagsClientBrowser = class {
     }
   }
   getExperiment(name, defaultParams, decode, variants) {
+    this.telemetry.emit("experiment", name);
     const notIn = {
       inExperiment: false,
       group: "control",
@@ -582,6 +654,7 @@ var FlagsClientBrowser = class {
    * the per-switch state. Returns false for unknown killswitches / switches.
    */
   getKillswitch(name, switchKey) {
+    this.telemetry.emit("ks", name);
     if (this.evalResult === null) return false;
     const ks = this.evalResult.killswitches?.[name];
     if (ks === void 0) return false;
@@ -716,7 +789,8 @@ function shipeasy(opts) {
     sdkKey: opts.clientKey,
     baseUrl,
     autoGuardrails: blanket,
-    autoGuardrailGroups: groups
+    autoGuardrailGroups: groups,
+    disableTelemetry: opts.disableTelemetry
   });
   injectI18nLoader(opts.clientKey, baseUrl, opts.i18nProfile);
   flags.notifyMounted();

package/dist/client/index.mjs

@@ -1,3 +1,62 @@
+// src/telemetry.ts
+async function sha256Hex(input) {
+  const buf = new TextEncoder().encode(input);
+  const digest = await crypto.subtle.digest("SHA-256", buf);
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var DEFAULT_TELEMETRY_URL = "https://t.shipeasy.ai";
+var Telemetry = class {
+  prefix;
+  disabled;
+  dedupeMs;
+  // Last-emit timestamp per `feature/resource`, for the dedup window. Bounded by
+  // the number of distinct keys the app reads.
+  lastEmit = /* @__PURE__ */ new Map();
+  // Resolved once at construction and reused by every emit(), so the per-eval
+  // cost is a Map-free microtask, not a hash.
+  keyHash;
+  constructor(opts) {
+    const endpoint = (opts.endpoint ?? "").replace(/\/$/, "");
+    this.disabled = opts.disabled === true || !opts.sdkKey || !endpoint;
+    this.dedupeMs = opts.dedupeMs ?? 2e3;
+    this.prefix = `${endpoint}/t`;
+    this.keyHash = this.disabled ? null : sha256Hex(opts.sdkKey).then((h) => `${h}/${opts.side}/${encodeURIComponent(opts.env)}`).catch(() => "");
+  }
+  /**
+   * Emit a single best-effort usage beacon for one evaluation. Never blocks the
+   * caller (the hash is already resolved) and never throws — a failed beacon
+   * must never affect the evaluation it measures.
+   */
+  emit(feature, resource) {
+    if (this.disabled || !this.keyHash) return;
+    if (this.dedupeMs > 0) {
+      const dedupeKey = `${feature}/${resource}`;
+      const now = Date.now();
+      const last = this.lastEmit.get(dedupeKey);
+      if (last !== void 0 && now - last < this.dedupeMs) return;
+      this.lastEmit.set(dedupeKey, now);
+    }
+    void this.keyHash.then((suffix) => {
+      if (!suffix) return;
+      send(`${this.prefix}/${suffix}/${feature}/${encodeURIComponent(resource)}`);
+    });
+  }
+};
+function send(url) {
+  try {
+    if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(url);
+      return;
+    }
+    const f = globalThis.fetch;
+    if (typeof f === "function") {
+      void f(url, { method: "GET", keepalive: true }).catch(() => {
+      });
+    }
+  } catch {
+  }
+}
+
 // src/client/index.ts
 var version = "1.0.0";
 var FLUSH_INTERVAL_MS = 5e3;
@@ -384,6 +443,7 @@ var FlagsClientBrowser = class {
   anonId;
   userId = "";
   buffer;
+  telemetry;
   guardrailsInstalled = false;
   listeners = /* @__PURE__ */ new Set();
   overrideListenerInstalled = false;
@@ -407,6 +467,13 @@ var FlagsClientBrowser = class {
     };
     this.anonId = getOrCreateAnonId();
     this.buffer = new EventBuffer(`${this.baseUrl}/collect`, this.sdkKey);
+    this.telemetry = new Telemetry({
+      endpoint: opts.telemetryUrl ?? DEFAULT_TELEMETRY_URL,
+      sdkKey: this.sdkKey,
+      side: "client",
+      env: this.env,
+      disabled: opts.disableTelemetry
+    });
     void this.buffer.flushPendingAlias();
   }
   async identify(user) {
@@ -456,12 +523,14 @@ var FlagsClientBrowser = class {
     this.evalResult = data;
   }
   getFlag(name) {
+    this.telemetry.emit("gate", name);
     if (this.evalResult === null) return false;
     const ov = readGateOverride(name);
     if (ov !== null) return ov;
     return this.evalResult.flags[name] ?? false;
   }
   getConfig(name, decode) {
+    this.telemetry.emit("config", name);
     if (this.evalResult === null) return void 0;
     const ov = readConfigOverride(name);
     const raw = ov !== void 0 ? ov : this.evalResult.configs?.[name];
@@ -475,6 +544,7 @@ var FlagsClientBrowser = class {
     }
   }
   getExperiment(name, defaultParams, decode, variants) {
+    this.telemetry.emit("experiment", name);
     const notIn = {
       inExperiment: false,
       group: "control",
@@ -539,6 +609,7 @@ var FlagsClientBrowser = class {
    * the per-switch state. Returns false for unknown killswitches / switches.
    */
   getKillswitch(name, switchKey) {
+    this.telemetry.emit("ks", name);
     if (this.evalResult === null) return false;
     const ks = this.evalResult.killswitches?.[name];
     if (ks === void 0) return false;
@@ -673,7 +744,8 @@ function shipeasy(opts) {
     sdkKey: opts.clientKey,
     baseUrl,
     autoGuardrails: blanket,
-    autoGuardrailGroups: groups
+    autoGuardrailGroups: groups,
+    disableTelemetry: opts.disableTelemetry
   });
   injectI18nLoader(opts.clientKey, baseUrl, opts.i18nProfile);
   flags.notifyMounted();

package/dist/server/index.d.mts

@@ -51,11 +51,23 @@ interface FlagsClientOptions {
      * for tests; production callers should rely on init()/initOnce().
      */
     initialBlob?: FlagsBlob;
+    /**
+     * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
+     * getExperiment/getKillswitch (and the per-key evaluate() loop) fires one
+     * fire-and-forget beacon counted by Cloudflare's native per-path analytics.
+     * Pass `true` to disable. NOTE: on Cloudflare Workers each beacon is an
+     * outbound subrequest (cap 50 free / 1000 paid per invocation), so disable
+     * this on hot request paths that evaluate many flags per request.
+     */
+    disableTelemetry?: boolean;
+    /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
+    telemetryUrl?: string;
 }
 declare class FlagsClient {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly env;
+    private readonly telemetry;
     private flagsBlob;
     private expsBlob;
     private flagsEtag;
@@ -147,6 +159,12 @@ interface ShipeasyServerConfig {
     user?: User;
     /** i18n profile to load for SSR translations, e.g. "en:prod". Defaults to "en:prod". */
     i18nDefaultProfile?: string;
+    /**
+     * Disable per-evaluation usage telemetry. ON by default. On Cloudflare
+     * Workers each beacon is an outbound subrequest, so disable on hot SSR paths
+     * that evaluate many flags per request. See {@link FlagsClientOptions.disableTelemetry}.
+     */
+    disableTelemetry?: boolean;
 }
 interface ShipeasyServerHandle {
     flags: Record<string, boolean>;

package/dist/server/index.d.ts

@@ -51,11 +51,23 @@ interface FlagsClientOptions {
      * for tests; production callers should rely on init()/initOnce().
      */
     initialBlob?: FlagsBlob;
+    /**
+     * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
+     * getExperiment/getKillswitch (and the per-key evaluate() loop) fires one
+     * fire-and-forget beacon counted by Cloudflare's native per-path analytics.
+     * Pass `true` to disable. NOTE: on Cloudflare Workers each beacon is an
+     * outbound subrequest (cap 50 free / 1000 paid per invocation), so disable
+     * this on hot request paths that evaluate many flags per request.
+     */
+    disableTelemetry?: boolean;
+    /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
+    telemetryUrl?: string;
 }
 declare class FlagsClient {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly env;
+    private readonly telemetry;
     private flagsBlob;
     private expsBlob;
     private flagsEtag;
@@ -147,6 +159,12 @@ interface ShipeasyServerConfig {
     user?: User;
     /** i18n profile to load for SSR translations, e.g. "en:prod". Defaults to "en:prod". */
     i18nDefaultProfile?: string;
+    /**
+     * Disable per-evaluation usage telemetry. ON by default. On Cloudflare
+     * Workers each beacon is an outbound subrequest, so disable on hot SSR paths
+     * that evaluate many flags per request. See {@link FlagsClientOptions.disableTelemetry}.
+     */
+    disableTelemetry?: boolean;
 }
 interface ShipeasyServerHandle {
     flags: Record<string, boolean>;

package/dist/server/index.js

@@ -43,6 +43,67 @@ __export(server_exports, {
 });
 module.exports = __toCommonJS(server_exports);
 var import_node_async_hooks = require("async_hooks");
+
+// src/telemetry.ts
+async function sha256Hex(input) {
+  const buf = new TextEncoder().encode(input);
+  const digest = await crypto.subtle.digest("SHA-256", buf);
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var DEFAULT_TELEMETRY_URL = "https://t.shipeasy.ai";
+var Telemetry = class {
+  prefix;
+  disabled;
+  dedupeMs;
+  // Last-emit timestamp per `feature/resource`, for the dedup window. Bounded by
+  // the number of distinct keys the app reads.
+  lastEmit = /* @__PURE__ */ new Map();
+  // Resolved once at construction and reused by every emit(), so the per-eval
+  // cost is a Map-free microtask, not a hash.
+  keyHash;
+  constructor(opts) {
+    const endpoint = (opts.endpoint ?? "").replace(/\/$/, "");
+    this.disabled = opts.disabled === true || !opts.sdkKey || !endpoint;
+    this.dedupeMs = opts.dedupeMs ?? 2e3;
+    this.prefix = `${endpoint}/t`;
+    this.keyHash = this.disabled ? null : sha256Hex(opts.sdkKey).then((h) => `${h}/${opts.side}/${encodeURIComponent(opts.env)}`).catch(() => "");
+  }
+  /**
+   * Emit a single best-effort usage beacon for one evaluation. Never blocks the
+   * caller (the hash is already resolved) and never throws — a failed beacon
+   * must never affect the evaluation it measures.
+   */
+  emit(feature, resource) {
+    if (this.disabled || !this.keyHash) return;
+    if (this.dedupeMs > 0) {
+      const dedupeKey = `${feature}/${resource}`;
+      const now = Date.now();
+      const last = this.lastEmit.get(dedupeKey);
+      if (last !== void 0 && now - last < this.dedupeMs) return;
+      this.lastEmit.set(dedupeKey, now);
+    }
+    void this.keyHash.then((suffix) => {
+      if (!suffix) return;
+      send(`${this.prefix}/${suffix}/${feature}/${encodeURIComponent(resource)}`);
+    });
+  }
+};
+function send(url) {
+  try {
+    if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(url);
+      return;
+    }
+    const f = globalThis.fetch;
+    if (typeof f === "function") {
+      void f(url, { method: "GET", keepalive: true }).catch(() => {
+      });
+    }
+  } catch {
+  }
+}
+
+// src/server/index.ts
 var version = "1.0.0";
 var C1 = 3432918353;
 var C2 = 461845907;
@@ -192,6 +253,7 @@ var FlagsClient = class {
   apiKey;
   baseUrl;
   env;
+  telemetry;
   flagsBlob = null;
   expsBlob = null;
   flagsEtag = null;
@@ -203,6 +265,13 @@ var FlagsClient = class {
     this.apiKey = opts.apiKey;
     this.baseUrl = (opts.baseUrl ?? "https://cdn.shipeasy.ai").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
+    this.telemetry = new Telemetry({
+      endpoint: opts.telemetryUrl ?? DEFAULT_TELEMETRY_URL,
+      sdkKey: this.apiKey,
+      side: "server",
+      env: this.env,
+      disabled: opts.disableTelemetry
+    });
     if (opts.initialBlob) {
       this.flagsBlob = opts.initialBlob;
       this.initialized = true;
@@ -264,17 +333,20 @@ var FlagsClient = class {
     this.expsBlob = await res.json();
   }
   getFlag(name, user) {
+    this.telemetry.emit("gate", name);
     const gate = this.flagsBlob?.gates[name];
     if (!gate) return false;
     return evalGateInternal(gate, user);
   }
   getConfig(name, decode) {
+    this.telemetry.emit("config", name);
     const entry = this.flagsBlob?.configs[name];
     if (!entry) return void 0;
     if (!decode) return entry.value;
     return decode(entry.value);
   }
   getExperiment(name, user, defaultParams, decode) {
+    this.telemetry.emit("experiment", name);
     const notIn = {
       inExperiment: false,
       group: "control",
@@ -349,15 +421,18 @@ var FlagsClient = class {
     const experiments = {};
     const killswitches = {};
     for (const [name, gate] of Object.entries(this.flagsBlob?.gates ?? {})) {
+      this.telemetry.emit("gate", name);
       flags2[name] = evalGateInternal(gate, user);
     }
     for (const [name, entry] of Object.entries(this.flagsBlob?.configs ?? {})) {
+      this.telemetry.emit("config", name);
       configs[name] = entry.value;
     }
     for (const [name] of Object.entries(this.expsBlob?.experiments ?? {})) {
       experiments[name] = this.getExperiment(name, user, {});
     }
     for (const [name, ks] of Object.entries(this.flagsBlob?.killswitches ?? {})) {
+      this.telemetry.emit("ks", name);
       if (ks.switches && Object.keys(ks.switches).length > 0) {
         const out = {};
         for (const [k, v] of Object.entries(ks.switches)) out[k] = isEnabled(v);
@@ -377,6 +452,7 @@ var FlagsClient = class {
     return { flags: flags2, configs, experiments, killswitches };
   }
   getKillswitch(name, switchKey) {
+    this.telemetry.emit("ks", name);
     const ks = this.flagsBlob?.killswitches?.[name];
     if (!ks) return false;
     if (switchKey === void 0) return isEnabled(ks.killed);
@@ -387,6 +463,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 +509,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);
   },
   /**
@@ -506,7 +588,7 @@ async function shipeasy(opts) {
     );
   }
   const profile = opts.i18nDefaultProfile ?? "en:prod";
-  flags.configure({ apiKey: serverKey });
+  flags.configure({ apiKey: serverKey, disableTelemetry: opts.disableTelemetry });
   let resolvedUrlOverrides = opts.urlOverrides;
   if (!resolvedUrlOverrides) {
     try {

package/dist/server/index.mjs

@@ -1,5 +1,66 @@
 // src/server/index.ts
 import { AsyncLocalStorage } from "async_hooks";
+
+// src/telemetry.ts
+async function sha256Hex(input) {
+  const buf = new TextEncoder().encode(input);
+  const digest = await crypto.subtle.digest("SHA-256", buf);
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var DEFAULT_TELEMETRY_URL = "https://t.shipeasy.ai";
+var Telemetry = class {
+  prefix;
+  disabled;
+  dedupeMs;
+  // Last-emit timestamp per `feature/resource`, for the dedup window. Bounded by
+  // the number of distinct keys the app reads.
+  lastEmit = /* @__PURE__ */ new Map();
+  // Resolved once at construction and reused by every emit(), so the per-eval
+  // cost is a Map-free microtask, not a hash.
+  keyHash;
+  constructor(opts) {
+    const endpoint = (opts.endpoint ?? "").replace(/\/$/, "");
+    this.disabled = opts.disabled === true || !opts.sdkKey || !endpoint;
+    this.dedupeMs = opts.dedupeMs ?? 2e3;
+    this.prefix = `${endpoint}/t`;
+    this.keyHash = this.disabled ? null : sha256Hex(opts.sdkKey).then((h) => `${h}/${opts.side}/${encodeURIComponent(opts.env)}`).catch(() => "");
+  }
+  /**
+   * Emit a single best-effort usage beacon for one evaluation. Never blocks the
+   * caller (the hash is already resolved) and never throws — a failed beacon
+   * must never affect the evaluation it measures.
+   */
+  emit(feature, resource) {
+    if (this.disabled || !this.keyHash) return;
+    if (this.dedupeMs > 0) {
+      const dedupeKey = `${feature}/${resource}`;
+      const now = Date.now();
+      const last = this.lastEmit.get(dedupeKey);
+      if (last !== void 0 && now - last < this.dedupeMs) return;
+      this.lastEmit.set(dedupeKey, now);
+    }
+    void this.keyHash.then((suffix) => {
+      if (!suffix) return;
+      send(`${this.prefix}/${suffix}/${feature}/${encodeURIComponent(resource)}`);
+    });
+  }
+};
+function send(url) {
+  try {
+    if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(url);
+      return;
+    }
+    const f = globalThis.fetch;
+    if (typeof f === "function") {
+      void f(url, { method: "GET", keepalive: true }).catch(() => {
+      });
+    }
+  } catch {
+  }
+}
+
+// src/server/index.ts
 var version = "1.0.0";
 var C1 = 3432918353;
 var C2 = 461845907;
@@ -149,6 +210,7 @@ var FlagsClient = class {
   apiKey;
   baseUrl;
   env;
+  telemetry;
   flagsBlob = null;
   expsBlob = null;
   flagsEtag = null;
@@ -160,6 +222,13 @@ var FlagsClient = class {
     this.apiKey = opts.apiKey;
     this.baseUrl = (opts.baseUrl ?? "https://cdn.shipeasy.ai").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
+    this.telemetry = new Telemetry({
+      endpoint: opts.telemetryUrl ?? DEFAULT_TELEMETRY_URL,
+      sdkKey: this.apiKey,
+      side: "server",
+      env: this.env,
+      disabled: opts.disableTelemetry
+    });
     if (opts.initialBlob) {
       this.flagsBlob = opts.initialBlob;
       this.initialized = true;
@@ -221,17 +290,20 @@ var FlagsClient = class {
     this.expsBlob = await res.json();
   }
   getFlag(name, user) {
+    this.telemetry.emit("gate", name);
     const gate = this.flagsBlob?.gates[name];
     if (!gate) return false;
     return evalGateInternal(gate, user);
   }
   getConfig(name, decode) {
+    this.telemetry.emit("config", name);
     const entry = this.flagsBlob?.configs[name];
     if (!entry) return void 0;
     if (!decode) return entry.value;
     return decode(entry.value);
   }
   getExperiment(name, user, defaultParams, decode) {
+    this.telemetry.emit("experiment", name);
     const notIn = {
       inExperiment: false,
       group: "control",
@@ -306,15 +378,18 @@ var FlagsClient = class {
     const experiments = {};
     const killswitches = {};
     for (const [name, gate] of Object.entries(this.flagsBlob?.gates ?? {})) {
+      this.telemetry.emit("gate", name);
       flags2[name] = evalGateInternal(gate, user);
     }
     for (const [name, entry] of Object.entries(this.flagsBlob?.configs ?? {})) {
+      this.telemetry.emit("config", name);
       configs[name] = entry.value;
     }
     for (const [name] of Object.entries(this.expsBlob?.experiments ?? {})) {
       experiments[name] = this.getExperiment(name, user, {});
     }
     for (const [name, ks] of Object.entries(this.flagsBlob?.killswitches ?? {})) {
+      this.telemetry.emit("ks", name);
       if (ks.switches && Object.keys(ks.switches).length > 0) {
         const out = {};
         for (const [k, v] of Object.entries(ks.switches)) out[k] = isEnabled(v);
@@ -334,6 +409,7 @@ var FlagsClient = class {
     return { flags: flags2, configs, experiments, killswitches };
   }
   getKillswitch(name, switchKey) {
+    this.telemetry.emit("ks", name);
     const ks = this.flagsBlob?.killswitches?.[name];
     if (!ks) return false;
     if (switchKey === void 0) return isEnabled(ks.killed);
@@ -344,6 +420,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 +466,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);
   },
   /**
@@ -463,7 +545,7 @@ async function shipeasy(opts) {
     );
   }
   const profile = opts.i18nDefaultProfile ?? "en:prod";
-  flags.configure({ apiKey: serverKey });
+  flags.configure({ apiKey: serverKey, disableTelemetry: opts.disableTelemetry });
   let resolvedUrlOverrides = opts.urlOverrides;
   if (!resolvedUrlOverrides) {
     try {

package/package.json

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