@shipeasy/sdk 7.0.0 → 7.1.0

package/dist/client/index.d.mts

@@ -280,10 +280,26 @@ interface EngineOptions {
     /** Which published env to read values from. Defaults to "prod". */
     env?: EngineEnv;
     /**
-     * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
+     * Master network switch — when `false`, the browser SDK makes NO outbound
+     * requests at all: identify()/init never call /sdk/evaluate (getters read code
+     * defaults / overrides), track() and exposure logging are no-ops, usage
+     * telemetry is off, and SDK-internal error self-monitoring is off.
+     *
+     * DEFAULT is environment-derived (see {@link isProductionEnv}): ON in
+     * production, OFF everywhere else. In the browser there is usually no native
+     * `NODE_ENV`, so production is taken from the `env` option above (default
+     * `"prod"`) — meaning it defaults ON. Pass `false` (or set `env: "dev"`) to
+     * keep a local build quiet.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Per-evaluation usage telemetry ("tracking") — 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.
+     * usage is counted by Cloudflare's native per-path analytics.
+     *
+     * DEFAULT is environment-derived: ON in production, OFF everywhere else (same
+     * inference as {@link isNetworkEnabled}). Pass `true` to force it off, `false`
+     * to force it on. Forced off whenever `isNetworkEnabled` is false.
      */
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
@@ -365,6 +381,8 @@ declare class Engine {
     private overrideListenerInstalled;
     private identifySeq;
     private readonly testMode;
+    private readonly networkEnabled;
+    private readonly offline;
     private readonly flagOverrides;
     private readonly configOverrides;
     private readonly experimentOverrides;
@@ -517,6 +535,12 @@ interface ShipeasyClientConfig {
     clientKey: string;
     /** Override the ShipEasy CDN/edge base URL. Defaults to https://cdn.shipeasy.ai. */
     baseUrl?: string;
+    /**
+     * Which published env to read values from — also the fallback signal for the
+     * environment-derived egress defaults (see {@link isNetworkEnabled}) when the
+     * browser exposes no native `NODE_ENV`. Defaults to `"prod"`.
+     */
+    env?: EngineEnv;
     /** Override the admin URL for the devtools overlay (dev use). */
     adminUrl?: string;
     /**
@@ -569,9 +593,18 @@ interface ShipeasyClientConfig {
      */
     logLevel?: LogLevel;
     /**
-     * Disable per-evaluation usage telemetry. Telemetry is ON by default — every
+     * Master network switch — `false` puts the browser SDK fully offline (no
+     * /sdk/evaluate, no /collect, no telemetry, no error self-monitoring).
+     * Defaults to environment-derived: ON in production, OFF everywhere else
+     * (in the browser, "production" comes from `env`, default `"prod"`). See
+     * {@link EngineOptions.isNetworkEnabled}.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Disable per-evaluation usage telemetry ("tracking"). Defaults to
+     * environment-derived: ON in production, OFF everywhere else. 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.
+     * counted by Cloudflare's native per-path analytics. Pass `true` to force off.
      */
     disableTelemetry?: boolean;
     /**

package/dist/client/index.d.ts

@@ -280,10 +280,26 @@ interface EngineOptions {
     /** Which published env to read values from. Defaults to "prod". */
     env?: EngineEnv;
     /**
-     * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
+     * Master network switch — when `false`, the browser SDK makes NO outbound
+     * requests at all: identify()/init never call /sdk/evaluate (getters read code
+     * defaults / overrides), track() and exposure logging are no-ops, usage
+     * telemetry is off, and SDK-internal error self-monitoring is off.
+     *
+     * DEFAULT is environment-derived (see {@link isProductionEnv}): ON in
+     * production, OFF everywhere else. In the browser there is usually no native
+     * `NODE_ENV`, so production is taken from the `env` option above (default
+     * `"prod"`) — meaning it defaults ON. Pass `false` (or set `env: "dev"`) to
+     * keep a local build quiet.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Per-evaluation usage telemetry ("tracking") — 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.
+     * usage is counted by Cloudflare's native per-path analytics.
+     *
+     * DEFAULT is environment-derived: ON in production, OFF everywhere else (same
+     * inference as {@link isNetworkEnabled}). Pass `true` to force it off, `false`
+     * to force it on. Forced off whenever `isNetworkEnabled` is false.
      */
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
@@ -365,6 +381,8 @@ declare class Engine {
     private overrideListenerInstalled;
     private identifySeq;
     private readonly testMode;
+    private readonly networkEnabled;
+    private readonly offline;
     private readonly flagOverrides;
     private readonly configOverrides;
     private readonly experimentOverrides;
@@ -517,6 +535,12 @@ interface ShipeasyClientConfig {
     clientKey: string;
     /** Override the ShipEasy CDN/edge base URL. Defaults to https://cdn.shipeasy.ai. */
     baseUrl?: string;
+    /**
+     * Which published env to read values from — also the fallback signal for the
+     * environment-derived egress defaults (see {@link isNetworkEnabled}) when the
+     * browser exposes no native `NODE_ENV`. Defaults to `"prod"`.
+     */
+    env?: EngineEnv;
     /** Override the admin URL for the devtools overlay (dev use). */
     adminUrl?: string;
     /**
@@ -569,9 +593,18 @@ interface ShipeasyClientConfig {
      */
     logLevel?: LogLevel;
     /**
-     * Disable per-evaluation usage telemetry. Telemetry is ON by default — every
+     * Master network switch — `false` puts the browser SDK fully offline (no
+     * /sdk/evaluate, no /collect, no telemetry, no error self-monitoring).
+     * Defaults to environment-derived: ON in production, OFF everywhere else
+     * (in the browser, "production" comes from `env`, default `"prod"`). See
+     * {@link EngineOptions.isNetworkEnabled}.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Disable per-evaluation usage telemetry ("tracking"). Defaults to
+     * environment-derived: ON in production, OFF everywhere else. 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.
+     * counted by Cloudflare's native per-path analytics. Pass `true` to force off.
      */
     disableTelemetry?: boolean;
     /**

package/dist/client/index.js

@@ -110,6 +110,24 @@ function send(url) {
   }
 }
 
+// src/env.ts
+function isProductionEnv(configuredEnv) {
+  const native = readNativeEnv();
+  if (native !== null) return native === "production" || native === "prod";
+  return (configuredEnv ?? "prod").toLowerCase() === "prod";
+}
+function readNativeEnv() {
+  try {
+    const proc = globalThis.process;
+    const raw = proc?.env?.SHIPEASY_ENV ?? proc?.env?.NODE_ENV;
+    if (typeof raw !== "string") return null;
+    const v = raw.trim().toLowerCase();
+    return v.length ? v : null;
+  } catch {
+    return null;
+  }
+}
+
 // src/see/core.ts
 var SEE_MAX_MESSAGE = 500;
 var SEE_MAX_STACK = 8e3;
@@ -1072,6 +1090,12 @@ var Engine = class _Engine {
   // never fetches, track() is a no-op, telemetry is off, and the client is
   // already ready with an empty eval result.
   testMode;
+  // Master network gate — false ⇒ the SDK never touches the network. Defaults to
+  // environment-derived (prod-on), forced false by testMode.
+  networkEnabled;
+  // Convenience inverse of networkEnabled — the "no network at all" state every
+  // /sdk/evaluate, /collect and telemetry gate keys on. testMode implies offline.
+  offline;
   // Programmatic overrides (Statsig-style). Set on any client via
   // overrideFlag/overrideConfig/overrideExperiment; they win over BOTH the URL
   // overrides and the fetched eval result. Cleared by clearOverrides().
@@ -1088,10 +1112,13 @@ var Engine = class _Engine {
     this.baseUrl = (opts.baseUrl ?? "https://api.shipeasy.ai").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
     this.testMode = opts.testMode === true;
+    const prod = isProductionEnv(this.env);
+    this.networkEnabled = this.testMode ? false : opts.isNetworkEnabled ?? prod;
+    this.offline = !this.networkEnabled;
     setInternalReportContext({
       side: "client",
       sdkVersion: version,
-      enabled: !this.testMode && opts.disableInternalErrorReporting !== true
+      enabled: this.networkEnabled && opts.disableInternalErrorReporting !== true
     });
     this.autoGuardrails = opts.autoGuardrails !== false;
     this.autoCollectAlways = opts.autoCollectAlways === true;
@@ -1105,7 +1132,7 @@ var Engine = class _Engine {
       engagement: g.engagement ?? this.autoGuardrails
     };
     this.anonId = getOrCreateAnonId();
-    if (opts.anonymousStore && !this.testMode) {
+    if (opts.anonymousStore && !this.offline) {
       this.anonReady = this.hydrateAnonFromStore(opts.anonymousStore);
     }
     this.buffer = new EventBuffer(`${this.baseUrl}/collect`, this.sdkKey);
@@ -1114,10 +1141,11 @@ var Engine = class _Engine {
       sdkKey: this.sdkKey,
       side: "client",
       env: this.env,
-      // Test mode never talks to the network — telemetry off regardless of opt.
-      disabled: this.testMode || opts.disableTelemetry
+      // Off when the network is disabled; otherwise honour an explicit
+      // disableTelemetry, else default to prod-on (off outside production).
+      disabled: this.offline || (opts.disableTelemetry ?? !prod)
     });
-    if (this.testMode) {
+    if (this.offline) {
       this.evalResult = { flags: {}, configs: {}, experiments: {}, killswitches: {} };
     } else {
       void this.buffer.flushPendingAlias();
@@ -1162,7 +1190,7 @@ var Engine = class _Engine {
     });
   }
   async identify(user) {
-    if (this.testMode) {
+    if (this.offline) {
       if (user.user_id !== void 0) this.userId = user.user_id;
       this.notify();
       return;
@@ -1224,6 +1252,7 @@ var Engine = class _Engine {
    * the 5s metric batch. Spam-guarded by a 30s dedup window + per-session cap.
    */
   reportError(problem, consequence, extras, kind, correlationId) {
+    if (this.offline) return;
     try {
       const enriched = { ...collectSeeEnv(), ...extras };
       const ev = buildSeeEvent(problem, consequence, enriched, {
@@ -1396,7 +1425,7 @@ var Engine = class _Engine {
     return bridge;
   }
   track(eventName, props) {
-    if (this.testMode) return;
+    if (this.offline) return;
     this.buffer.pushMetric(eventName, this.userId, this.anonId, this.stripPrivate(props));
   }
   /** Drop caller-marked private attributes from an outbound props bag. */
@@ -1549,10 +1578,12 @@ function shipeasy(opts) {
   const client = configureShipeasy({
     sdkKey: opts.clientKey,
     baseUrl,
+    env: opts.env,
     logLevel: opts.logLevel,
     autoGuardrails: blanket,
     autoGuardrailGroups: groups,
     autoCollectAlways: acObj?.always === true,
+    isNetworkEnabled: opts.isNetworkEnabled,
     disableTelemetry: opts.disableTelemetry,
     disableInternalErrorReporting: opts.disableInternalErrorReporting,
     disableAutoExposure: opts.disableAutoExposure,

package/dist/client/index.mjs

@@ -57,6 +57,24 @@ function send(url) {
   }
 }
 
+// src/env.ts
+function isProductionEnv(configuredEnv) {
+  const native = readNativeEnv();
+  if (native !== null) return native === "production" || native === "prod";
+  return (configuredEnv ?? "prod").toLowerCase() === "prod";
+}
+function readNativeEnv() {
+  try {
+    const proc = globalThis.process;
+    const raw = proc?.env?.SHIPEASY_ENV ?? proc?.env?.NODE_ENV;
+    if (typeof raw !== "string") return null;
+    const v = raw.trim().toLowerCase();
+    return v.length ? v : null;
+  } catch {
+    return null;
+  }
+}
+
 // src/see/core.ts
 var SEE_MAX_MESSAGE = 500;
 var SEE_MAX_STACK = 8e3;
@@ -1019,6 +1037,12 @@ var Engine = class _Engine {
   // never fetches, track() is a no-op, telemetry is off, and the client is
   // already ready with an empty eval result.
   testMode;
+  // Master network gate — false ⇒ the SDK never touches the network. Defaults to
+  // environment-derived (prod-on), forced false by testMode.
+  networkEnabled;
+  // Convenience inverse of networkEnabled — the "no network at all" state every
+  // /sdk/evaluate, /collect and telemetry gate keys on. testMode implies offline.
+  offline;
   // Programmatic overrides (Statsig-style). Set on any client via
   // overrideFlag/overrideConfig/overrideExperiment; they win over BOTH the URL
   // overrides and the fetched eval result. Cleared by clearOverrides().
@@ -1035,10 +1059,13 @@ var Engine = class _Engine {
     this.baseUrl = (opts.baseUrl ?? "https://api.shipeasy.ai").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
     this.testMode = opts.testMode === true;
+    const prod = isProductionEnv(this.env);
+    this.networkEnabled = this.testMode ? false : opts.isNetworkEnabled ?? prod;
+    this.offline = !this.networkEnabled;
     setInternalReportContext({
       side: "client",
       sdkVersion: version,
-      enabled: !this.testMode && opts.disableInternalErrorReporting !== true
+      enabled: this.networkEnabled && opts.disableInternalErrorReporting !== true
     });
     this.autoGuardrails = opts.autoGuardrails !== false;
     this.autoCollectAlways = opts.autoCollectAlways === true;
@@ -1052,7 +1079,7 @@ var Engine = class _Engine {
       engagement: g.engagement ?? this.autoGuardrails
     };
     this.anonId = getOrCreateAnonId();
-    if (opts.anonymousStore && !this.testMode) {
+    if (opts.anonymousStore && !this.offline) {
       this.anonReady = this.hydrateAnonFromStore(opts.anonymousStore);
     }
     this.buffer = new EventBuffer(`${this.baseUrl}/collect`, this.sdkKey);
@@ -1061,10 +1088,11 @@ var Engine = class _Engine {
       sdkKey: this.sdkKey,
       side: "client",
       env: this.env,
-      // Test mode never talks to the network — telemetry off regardless of opt.
-      disabled: this.testMode || opts.disableTelemetry
+      // Off when the network is disabled; otherwise honour an explicit
+      // disableTelemetry, else default to prod-on (off outside production).
+      disabled: this.offline || (opts.disableTelemetry ?? !prod)
     });
-    if (this.testMode) {
+    if (this.offline) {
       this.evalResult = { flags: {}, configs: {}, experiments: {}, killswitches: {} };
     } else {
       void this.buffer.flushPendingAlias();
@@ -1109,7 +1137,7 @@ var Engine = class _Engine {
     });
   }
   async identify(user) {
-    if (this.testMode) {
+    if (this.offline) {
       if (user.user_id !== void 0) this.userId = user.user_id;
       this.notify();
       return;
@@ -1171,6 +1199,7 @@ var Engine = class _Engine {
    * the 5s metric batch. Spam-guarded by a 30s dedup window + per-session cap.
    */
   reportError(problem, consequence, extras, kind, correlationId) {
+    if (this.offline) return;
     try {
       const enriched = { ...collectSeeEnv(), ...extras };
       const ev = buildSeeEvent(problem, consequence, enriched, {
@@ -1343,7 +1372,7 @@ var Engine = class _Engine {
     return bridge;
   }
   track(eventName, props) {
-    if (this.testMode) return;
+    if (this.offline) return;
     this.buffer.pushMetric(eventName, this.userId, this.anonId, this.stripPrivate(props));
   }
   /** Drop caller-marked private attributes from an outbound props bag. */
@@ -1496,10 +1525,12 @@ function shipeasy(opts) {
   const client = configureShipeasy({
     sdkKey: opts.clientKey,
     baseUrl,
+    env: opts.env,
     logLevel: opts.logLevel,
     autoGuardrails: blanket,
     autoGuardrailGroups: groups,
     autoCollectAlways: acObj?.always === true,
+    isNetworkEnabled: opts.isNetworkEnabled,
     disableTelemetry: opts.disableTelemetry,
     disableInternalErrorReporting: opts.disableInternalErrorReporting,
     disableAutoExposure: opts.disableAutoExposure,

package/dist/openfeature-server/index.d.mts

@@ -201,12 +201,31 @@ interface EngineOptions {
      */
     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.
+     * Master network switch — when `false`, the SDK makes NO outbound requests at
+     * all: init()/initOnce() never fetch (getters read code defaults / overrides),
+     * track() and exposure logging are no-ops, usage telemetry is off, and
+     * SDK-internal error self-monitoring is off. Think of it as a production-safe
+     * offline mode.
+     *
+     * DEFAULT is environment-derived (see {@link isProductionEnv}): ON in
+     * production, OFF everywhere else — so a local/dev/CI run never phones home
+     * unless you opt in. Production is inferred from `SHIPEASY_ENV`/`NODE_ENV`, or
+     * (when neither is set, e.g. on Cloudflare Workers) from the `env` option
+     * above, which defaults to `"prod"`. Pass an explicit value to override.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Per-evaluation usage telemetry ("tracking"/outside logging). 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.
+     *
+     * DEFAULT is environment-derived: ON in production, OFF everywhere else (same
+     * inference as {@link isNetworkEnabled}). Pass `true` to force it off, `false`
+     * to force it on. 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. Forced off whenever
+     * `isNetworkEnabled` is false.
      */
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
@@ -258,6 +277,8 @@ declare class Engine {
     private readonly env;
     private readonly privateAttributes;
     private readonly stickyStore;
+    private readonly networkEnabled;
+    private readonly offline;
     private readonly telemetry;
     private readonly seeLimiter;
     private flagsBlob;
@@ -388,8 +409,8 @@ declare class Engine {
     /**
      * POST a single exposure for an enrolled `(user, experiment, group)`. Deduped
      * per process (bounded set) so repeated `assign()` calls in one server don't
-     * spam `/collect`. Fire-and-forget; no-op in test mode. This is how
-     * `assignUniverse` auto-logs — the browser's auto-exposure parity for SSR.
+     * spam `/collect`. Fire-and-forget; no-op when the network is disabled. This
+     * is how `assignUniverse` auto-logs — the browser's auto-exposure parity for SSR.
      */
     private postExposure;
     /**

package/dist/openfeature-server/index.d.ts

@@ -201,12 +201,31 @@ interface EngineOptions {
      */
     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.
+     * Master network switch — when `false`, the SDK makes NO outbound requests at
+     * all: init()/initOnce() never fetch (getters read code defaults / overrides),
+     * track() and exposure logging are no-ops, usage telemetry is off, and
+     * SDK-internal error self-monitoring is off. Think of it as a production-safe
+     * offline mode.
+     *
+     * DEFAULT is environment-derived (see {@link isProductionEnv}): ON in
+     * production, OFF everywhere else — so a local/dev/CI run never phones home
+     * unless you opt in. Production is inferred from `SHIPEASY_ENV`/`NODE_ENV`, or
+     * (when neither is set, e.g. on Cloudflare Workers) from the `env` option
+     * above, which defaults to `"prod"`. Pass an explicit value to override.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Per-evaluation usage telemetry ("tracking"/outside logging). 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.
+     *
+     * DEFAULT is environment-derived: ON in production, OFF everywhere else (same
+     * inference as {@link isNetworkEnabled}). Pass `true` to force it off, `false`
+     * to force it on. 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. Forced off whenever
+     * `isNetworkEnabled` is false.
      */
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
@@ -258,6 +277,8 @@ declare class Engine {
     private readonly env;
     private readonly privateAttributes;
     private readonly stickyStore;
+    private readonly networkEnabled;
+    private readonly offline;
     private readonly telemetry;
     private readonly seeLimiter;
     private flagsBlob;
@@ -388,8 +409,8 @@ declare class Engine {
     /**
      * POST a single exposure for an enrolled `(user, experiment, group)`. Deduped
      * per process (bounded set) so repeated `assign()` calls in one server don't
-     * spam `/collect`. Fire-and-forget; no-op in test mode. This is how
-     * `assignUniverse` auto-logs — the browser's auto-exposure parity for SSR.
+     * spam `/collect`. Fire-and-forget; no-op when the network is disabled. This
+     * is how `assignUniverse` auto-logs — the browser's auto-exposure parity for SSR.
      */
     private postExposure;
     /**

package/dist/openfeature-web/index.d.mts

@@ -158,10 +158,26 @@ interface EngineOptions {
     /** Which published env to read values from. Defaults to "prod". */
     env?: EngineEnv;
     /**
-     * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
+     * Master network switch — when `false`, the browser SDK makes NO outbound
+     * requests at all: identify()/init never call /sdk/evaluate (getters read code
+     * defaults / overrides), track() and exposure logging are no-ops, usage
+     * telemetry is off, and SDK-internal error self-monitoring is off.
+     *
+     * DEFAULT is environment-derived (see {@link isProductionEnv}): ON in
+     * production, OFF everywhere else. In the browser there is usually no native
+     * `NODE_ENV`, so production is taken from the `env` option above (default
+     * `"prod"`) — meaning it defaults ON. Pass `false` (or set `env: "dev"`) to
+     * keep a local build quiet.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Per-evaluation usage telemetry ("tracking") — 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.
+     * usage is counted by Cloudflare's native per-path analytics.
+     *
+     * DEFAULT is environment-derived: ON in production, OFF everywhere else (same
+     * inference as {@link isNetworkEnabled}). Pass `true` to force it off, `false`
+     * to force it on. Forced off whenever `isNetworkEnabled` is false.
      */
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
@@ -243,6 +259,8 @@ declare class Engine {
     private overrideListenerInstalled;
     private identifySeq;
     private readonly testMode;
+    private readonly networkEnabled;
+    private readonly offline;
     private readonly flagOverrides;
     private readonly configOverrides;
     private readonly experimentOverrides;

package/dist/openfeature-web/index.d.ts

@@ -158,10 +158,26 @@ interface EngineOptions {
     /** Which published env to read values from. Defaults to "prod". */
     env?: EngineEnv;
     /**
-     * Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
+     * Master network switch — when `false`, the browser SDK makes NO outbound
+     * requests at all: identify()/init never call /sdk/evaluate (getters read code
+     * defaults / overrides), track() and exposure logging are no-ops, usage
+     * telemetry is off, and SDK-internal error self-monitoring is off.
+     *
+     * DEFAULT is environment-derived (see {@link isProductionEnv}): ON in
+     * production, OFF everywhere else. In the browser there is usually no native
+     * `NODE_ENV`, so production is taken from the `env` option above (default
+     * `"prod"`) — meaning it defaults ON. Pass `false` (or set `env: "dev"`) to
+     * keep a local build quiet.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Per-evaluation usage telemetry ("tracking") — 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.
+     * usage is counted by Cloudflare's native per-path analytics.
+     *
+     * DEFAULT is environment-derived: ON in production, OFF everywhere else (same
+     * inference as {@link isNetworkEnabled}). Pass `true` to force it off, `false`
+     * to force it on. Forced off whenever `isNetworkEnabled` is false.
      */
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
@@ -243,6 +259,8 @@ declare class Engine {
     private overrideListenerInstalled;
     private identifySeq;
     private readonly testMode;
+    private readonly networkEnabled;
+    private readonly offline;
     private readonly flagOverrides;
     private readonly configOverrides;
     private readonly experimentOverrides;

package/dist/server/index.d.mts

@@ -309,12 +309,31 @@ interface EngineOptions {
      */
     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.
+     * Master network switch — when `false`, the SDK makes NO outbound requests at
+     * all: init()/initOnce() never fetch (getters read code defaults / overrides),
+     * track() and exposure logging are no-ops, usage telemetry is off, and
+     * SDK-internal error self-monitoring is off. Think of it as a production-safe
+     * offline mode.
+     *
+     * DEFAULT is environment-derived (see {@link isProductionEnv}): ON in
+     * production, OFF everywhere else — so a local/dev/CI run never phones home
+     * unless you opt in. Production is inferred from `SHIPEASY_ENV`/`NODE_ENV`, or
+     * (when neither is set, e.g. on Cloudflare Workers) from the `env` option
+     * above, which defaults to `"prod"`. Pass an explicit value to override.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Per-evaluation usage telemetry ("tracking"/outside logging). 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.
+     *
+     * DEFAULT is environment-derived: ON in production, OFF everywhere else (same
+     * inference as {@link isNetworkEnabled}). Pass `true` to force it off, `false`
+     * to force it on. 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. Forced off whenever
+     * `isNetworkEnabled` is false.
      */
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
@@ -366,6 +385,8 @@ declare class Engine {
     private readonly env;
     private readonly privateAttributes;
     private readonly stickyStore;
+    private readonly networkEnabled;
+    private readonly offline;
     private readonly telemetry;
     private readonly seeLimiter;
     private flagsBlob;
@@ -496,8 +517,8 @@ declare class Engine {
     /**
      * POST a single exposure for an enrolled `(user, experiment, group)`. Deduped
      * per process (bounded set) so repeated `assign()` calls in one server don't
-     * spam `/collect`. Fire-and-forget; no-op in test mode. This is how
-     * `assignUniverse` auto-logs — the browser's auto-exposure parity for SSR.
+     * spam `/collect`. Fire-and-forget; no-op when the network is disabled. This
+     * is how `assignUniverse` auto-logs — the browser's auto-exposure parity for SSR.
      */
     private postExposure;
     /**
@@ -591,7 +612,15 @@ interface ShipeasyServerConfig {
      */
     logLevel?: LogLevel;
     /**
-     * Disable per-evaluation usage telemetry. ON by default. On Cloudflare
+     * Master network switch — `false` puts the SDK fully offline (no fetch, no
+     * track, no telemetry, no error self-monitoring). Defaults to
+     * environment-derived: ON in production, OFF everywhere else. See
+     * {@link EngineOptions.isNetworkEnabled}.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Disable per-evaluation usage telemetry ("tracking"). Defaults to
+     * environment-derived: ON in production, OFF everywhere else. On Cloudflare
      * Workers each beacon is an outbound subrequest, so disable on hot SSR paths
      * that evaluate many flags per request. See {@link EngineOptions.disableTelemetry}.
      */

package/dist/server/index.d.ts

@@ -309,12 +309,31 @@ interface EngineOptions {
      */
     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.
+     * Master network switch — when `false`, the SDK makes NO outbound requests at
+     * all: init()/initOnce() never fetch (getters read code defaults / overrides),
+     * track() and exposure logging are no-ops, usage telemetry is off, and
+     * SDK-internal error self-monitoring is off. Think of it as a production-safe
+     * offline mode.
+     *
+     * DEFAULT is environment-derived (see {@link isProductionEnv}): ON in
+     * production, OFF everywhere else — so a local/dev/CI run never phones home
+     * unless you opt in. Production is inferred from `SHIPEASY_ENV`/`NODE_ENV`, or
+     * (when neither is set, e.g. on Cloudflare Workers) from the `env` option
+     * above, which defaults to `"prod"`. Pass an explicit value to override.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Per-evaluation usage telemetry ("tracking"/outside logging). 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.
+     *
+     * DEFAULT is environment-derived: ON in production, OFF everywhere else (same
+     * inference as {@link isNetworkEnabled}). Pass `true` to force it off, `false`
+     * to force it on. 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. Forced off whenever
+     * `isNetworkEnabled` is false.
      */
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
@@ -366,6 +385,8 @@ declare class Engine {
     private readonly env;
     private readonly privateAttributes;
     private readonly stickyStore;
+    private readonly networkEnabled;
+    private readonly offline;
     private readonly telemetry;
     private readonly seeLimiter;
     private flagsBlob;
@@ -496,8 +517,8 @@ declare class Engine {
     /**
      * POST a single exposure for an enrolled `(user, experiment, group)`. Deduped
      * per process (bounded set) so repeated `assign()` calls in one server don't
-     * spam `/collect`. Fire-and-forget; no-op in test mode. This is how
-     * `assignUniverse` auto-logs — the browser's auto-exposure parity for SSR.
+     * spam `/collect`. Fire-and-forget; no-op when the network is disabled. This
+     * is how `assignUniverse` auto-logs — the browser's auto-exposure parity for SSR.
      */
     private postExposure;
     /**
@@ -591,7 +612,15 @@ interface ShipeasyServerConfig {
      */
     logLevel?: LogLevel;
     /**
-     * Disable per-evaluation usage telemetry. ON by default. On Cloudflare
+     * Master network switch — `false` puts the SDK fully offline (no fetch, no
+     * track, no telemetry, no error self-monitoring). Defaults to
+     * environment-derived: ON in production, OFF everywhere else. See
+     * {@link EngineOptions.isNetworkEnabled}.
+     */
+    isNetworkEnabled?: boolean;
+    /**
+     * Disable per-evaluation usage telemetry ("tracking"). Defaults to
+     * environment-derived: ON in production, OFF everywhere else. On Cloudflare
      * Workers each beacon is an outbound subrequest, so disable on hot SSR paths
      * that evaluate many flags per request. See {@link EngineOptions.disableTelemetry}.
      */

package/dist/server/index.js

@@ -122,6 +122,24 @@ function send(url) {
   }
 }
 
+// src/env.ts
+function isProductionEnv(configuredEnv) {
+  const native = readNativeEnv();
+  if (native !== null) return native === "production" || native === "prod";
+  return (configuredEnv ?? "prod").toLowerCase() === "prod";
+}
+function readNativeEnv() {
+  try {
+    const proc = globalThis.process;
+    const raw = proc?.env?.SHIPEASY_ENV ?? proc?.env?.NODE_ENV;
+    if (typeof raw !== "string") return null;
+    const v = raw.trim().toLowerCase();
+    return v.length ? v : null;
+  } catch {
+    return null;
+  }
+}
+
 // src/see/core.ts
 var SEE_MAX_MESSAGE = 500;
 var SEE_MAX_STACK = 8e3;
@@ -724,6 +742,13 @@ var Engine = class _Engine {
   env;
   privateAttributes;
   stickyStore;
+  // Master network gate — false ⇒ the SDK never touches the network (no fetch,
+  // no track, no telemetry, no internal error reports). Defaults to
+  // environment-derived (prod-on), forced false by testMode.
+  networkEnabled;
+  // Convenience inverse of networkEnabled — the "no network at all" state that
+  // every fetch/track/init gate keys on. `testMode` implies offline.
+  offline;
   telemetry;
   seeLimiter = new SeeLimiter();
   flagsBlob = null;
@@ -757,20 +782,24 @@ var Engine = class _Engine {
     this.privateAttributes = opts.privateAttributes ?? [];
     this.stickyStore = opts.stickyStore;
     this.testMode = opts.testMode === true;
+    const prod = isProductionEnv(this.env);
+    this.networkEnabled = this.testMode ? false : opts.isNetworkEnabled ?? prod;
+    this.offline = !this.networkEnabled;
     setInternalReportContext({
       side: "server",
       sdkVersion: version,
-      enabled: !this.testMode && opts.disableInternalErrorReporting !== true
+      enabled: this.networkEnabled && opts.disableInternalErrorReporting !== true
     });
     this.telemetry = new Telemetry({
       endpoint: opts.telemetryUrl ?? DEFAULT_TELEMETRY_URL,
       sdkKey: this.apiKey,
       side: "server",
       env: this.env,
-      // Test mode never talks to the network — telemetry off regardless of opt.
-      disabled: this.testMode || opts.disableTelemetry
+      // Off when the network is disabled; otherwise honour an explicit
+      // disableTelemetry, else default to prod-on (off outside production).
+      disabled: this.offline || (opts.disableTelemetry ?? !prod)
     });
-    if (opts.initialBlob || this.testMode) {
+    if (opts.initialBlob || this.offline) {
       this.flagsBlob = opts.initialBlob ?? { version: "test", plan: "free", gates: {}, configs: {}, killswitches: {} };
       this.expsBlob = this.expsBlob ?? { version: "test", universes: {}, experiments: {} };
       this.initialized = true;
@@ -821,7 +850,7 @@ var Engine = class _Engine {
     return _Engine.fromSnapshot(snapshot);
   }
   async init() {
-    if (this.testMode) {
+    if (this.offline) {
       this.initialized = true;
       return;
     }
@@ -830,7 +859,7 @@ var Engine = class _Engine {
     this.startPoll();
   }
   async initOnce() {
-    if (this.testMode || this.initialized) return;
+    if (this.offline || this.initialized) return;
     await this.fetchAll();
     this.initialized = true;
   }
@@ -1054,7 +1083,7 @@ var Engine = class _Engine {
     return out;
   }
   track(userId, eventName, props) {
-    if (this.testMode) return;
+    if (this.offline) return;
     const safeProps = this.stripPrivate(props);
     const body = JSON.stringify({
       events: [
@@ -1076,11 +1105,11 @@ var Engine = class _Engine {
   /**
    * POST a single exposure for an enrolled `(user, experiment, group)`. Deduped
    * per process (bounded set) so repeated `assign()` calls in one server don't
-   * spam `/collect`. Fire-and-forget; no-op in test mode. This is how
-   * `assignUniverse` auto-logs — the browser's auto-exposure parity for SSR.
+   * spam `/collect`. Fire-and-forget; no-op when the network is disabled. This
+   * is how `assignUniverse` auto-logs — the browser's auto-exposure parity for SSR.
    */
   postExposure(user, experiment, group) {
-    if (this.testMode) return;
+    if (this.offline) return;
     const uid = user.user_id ?? user.anonymous_id;
     const dedupKey = `${uid ?? ""}:${experiment}:${group}`;
     if (this.exposureSeen.has(dedupKey)) return;
@@ -1110,6 +1139,7 @@ var Engine = class _Engine {
    * dedup window + per-process cap.
    */
   reportError(problem, consequence, extras, kind) {
+    if (this.offline) return;
     try {
       const correlationId = seeContext.getStore()?.correlationId;
       const ev = buildSeeEvent(problem, consequence, extras, {
@@ -1326,6 +1356,7 @@ async function shipeasy(opts) {
   const profile = opts.i18nDefaultProfile ?? "en:prod";
   flags.configure({
     apiKey: serverKey,
+    isNetworkEnabled: opts.isNetworkEnabled,
     disableTelemetry: opts.disableTelemetry,
     disableInternalErrorReporting: opts.disableInternalErrorReporting,
     privateAttributes: opts.privateAttributes,

package/dist/server/index.mjs

@@ -67,6 +67,24 @@ function send(url) {
   }
 }
 
+// src/env.ts
+function isProductionEnv(configuredEnv) {
+  const native = readNativeEnv();
+  if (native !== null) return native === "production" || native === "prod";
+  return (configuredEnv ?? "prod").toLowerCase() === "prod";
+}
+function readNativeEnv() {
+  try {
+    const proc = globalThis.process;
+    const raw = proc?.env?.SHIPEASY_ENV ?? proc?.env?.NODE_ENV;
+    if (typeof raw !== "string") return null;
+    const v = raw.trim().toLowerCase();
+    return v.length ? v : null;
+  } catch {
+    return null;
+  }
+}
+
 // src/see/core.ts
 var SEE_MAX_MESSAGE = 500;
 var SEE_MAX_STACK = 8e3;
@@ -669,6 +687,13 @@ var Engine = class _Engine {
   env;
   privateAttributes;
   stickyStore;
+  // Master network gate — false ⇒ the SDK never touches the network (no fetch,
+  // no track, no telemetry, no internal error reports). Defaults to
+  // environment-derived (prod-on), forced false by testMode.
+  networkEnabled;
+  // Convenience inverse of networkEnabled — the "no network at all" state that
+  // every fetch/track/init gate keys on. `testMode` implies offline.
+  offline;
   telemetry;
   seeLimiter = new SeeLimiter();
   flagsBlob = null;
@@ -702,20 +727,24 @@ var Engine = class _Engine {
     this.privateAttributes = opts.privateAttributes ?? [];
     this.stickyStore = opts.stickyStore;
     this.testMode = opts.testMode === true;
+    const prod = isProductionEnv(this.env);
+    this.networkEnabled = this.testMode ? false : opts.isNetworkEnabled ?? prod;
+    this.offline = !this.networkEnabled;
     setInternalReportContext({
       side: "server",
       sdkVersion: version,
-      enabled: !this.testMode && opts.disableInternalErrorReporting !== true
+      enabled: this.networkEnabled && opts.disableInternalErrorReporting !== true
     });
     this.telemetry = new Telemetry({
       endpoint: opts.telemetryUrl ?? DEFAULT_TELEMETRY_URL,
       sdkKey: this.apiKey,
       side: "server",
       env: this.env,
-      // Test mode never talks to the network — telemetry off regardless of opt.
-      disabled: this.testMode || opts.disableTelemetry
+      // Off when the network is disabled; otherwise honour an explicit
+      // disableTelemetry, else default to prod-on (off outside production).
+      disabled: this.offline || (opts.disableTelemetry ?? !prod)
     });
-    if (opts.initialBlob || this.testMode) {
+    if (opts.initialBlob || this.offline) {
       this.flagsBlob = opts.initialBlob ?? { version: "test", plan: "free", gates: {}, configs: {}, killswitches: {} };
       this.expsBlob = this.expsBlob ?? { version: "test", universes: {}, experiments: {} };
       this.initialized = true;
@@ -766,7 +795,7 @@ var Engine = class _Engine {
     return _Engine.fromSnapshot(snapshot);
   }
   async init() {
-    if (this.testMode) {
+    if (this.offline) {
       this.initialized = true;
       return;
     }
@@ -775,7 +804,7 @@ var Engine = class _Engine {
     this.startPoll();
   }
   async initOnce() {
-    if (this.testMode || this.initialized) return;
+    if (this.offline || this.initialized) return;
     await this.fetchAll();
     this.initialized = true;
   }
@@ -999,7 +1028,7 @@ var Engine = class _Engine {
     return out;
   }
   track(userId, eventName, props) {
-    if (this.testMode) return;
+    if (this.offline) return;
     const safeProps = this.stripPrivate(props);
     const body = JSON.stringify({
       events: [
@@ -1021,11 +1050,11 @@ var Engine = class _Engine {
   /**
    * POST a single exposure for an enrolled `(user, experiment, group)`. Deduped
    * per process (bounded set) so repeated `assign()` calls in one server don't
-   * spam `/collect`. Fire-and-forget; no-op in test mode. This is how
-   * `assignUniverse` auto-logs — the browser's auto-exposure parity for SSR.
+   * spam `/collect`. Fire-and-forget; no-op when the network is disabled. This
+   * is how `assignUniverse` auto-logs — the browser's auto-exposure parity for SSR.
    */
   postExposure(user, experiment, group) {
-    if (this.testMode) return;
+    if (this.offline) return;
     const uid = user.user_id ?? user.anonymous_id;
     const dedupKey = `${uid ?? ""}:${experiment}:${group}`;
     if (this.exposureSeen.has(dedupKey)) return;
@@ -1055,6 +1084,7 @@ var Engine = class _Engine {
    * dedup window + per-process cap.
    */
   reportError(problem, consequence, extras, kind) {
+    if (this.offline) return;
     try {
       const correlationId = seeContext.getStore()?.correlationId;
       const ev = buildSeeEvent(problem, consequence, extras, {
@@ -1271,6 +1301,7 @@ async function shipeasy(opts) {
   const profile = opts.i18nDefaultProfile ?? "en:prod";
   flags.configure({
     apiKey: serverKey,
+    isNetworkEnabled: opts.isNetworkEnabled,
     disableTelemetry: opts.disableTelemetry,
     disableInternalErrorReporting: opts.disableInternalErrorReporting,
     privateAttributes: opts.privateAttributes,

package/docs/skill/SKILL.md

@@ -42,6 +42,12 @@ flags.getFlagDetail("new_checkout");                   // { value, reason }
 `configure()` is first-config-wins and owns the fetch lifecycle (one-shot by
 default; `poll: true` for a background refresh). Construct `new Client(user)` once
 per user/request — it binds the user, so no method takes a user argument.
+
+Egress is **environment-derived**: network + usage telemetry default ON in
+production and OFF otherwise (prod is read from `SHIPEASY_ENV`/`NODE_ENV`, else
+the `env` option, default `"prod"`), so the SDK never phones home from dev/CI.
+Override with `isNetworkEnabled: false` (fully offline) or `disableTelemetry: true`
+(keep fetching, no usage beacons).
 Full reference: <https://shipeasy-ai.github.io/sdk-ts/pages/configuration.md> ·
 <https://shipeasy-ai.github.io/sdk-ts/pages/flags.md> ·
 snippets <https://shipeasy-ai.github.io/sdk-ts/snippets/release/flags.md> ·

package/package.json

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