@shipeasy/sdk 6.2.0 → 6.3.1

package/dist/client/index.mjs

@@ -57,6 +57,53 @@ function send(url) {
   }
 }
 
+// src/logger.ts
+var LOG_LEVELS = ["silent", "error", "warn", "info", "debug"];
+var RANK = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4
+};
+var currentLevel = "warn";
+function setLogLevel(level) {
+  if (typeof level === "string" && Object.prototype.hasOwnProperty.call(RANK, level)) {
+    currentLevel = level;
+  }
+}
+function write(method, args) {
+  try {
+    const c = globalThis.console;
+    if (!c) return;
+    const fn = c[method] ?? c.log;
+    if (typeof fn === "function") fn.call(c, ...args);
+  } catch {
+  }
+}
+var logger = {
+  error(...args) {
+    if (RANK[currentLevel] >= RANK.error) write("error", args);
+  },
+  warn(...args) {
+    if (RANK[currentLevel] >= RANK.warn) write("warn", args);
+  },
+  info(...args) {
+    if (RANK[currentLevel] >= RANK.info) write("info", args);
+  },
+  debug(...args) {
+    if (RANK[currentLevel] >= RANK.debug) write("debug", args);
+  }
+};
+function safeRun(label, fallback, fn) {
+  try {
+    return fn();
+  } catch (err) {
+    logger.error(`[shipeasy] ${label} failed \u2014 returning safe default:`, String(err));
+    return fallback;
+  }
+}
+
 // src/see/core.ts
 var SEE_MAX_MESSAGE = 500;
 var SEE_MAX_STACK = 8e3;
@@ -900,6 +947,7 @@ var Engine = class _Engine {
     this.notify();
   };
   constructor(opts) {
+    setLogLevel(opts.logLevel);
     this.sdkKey = opts.sdkKey;
     this.baseUrl = (opts.baseUrl ?? "https://edge.shipeasy.dev").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
@@ -1034,7 +1082,7 @@ var Engine = class _Engine {
       try {
         l();
       } catch (err) {
-        console.warn("[shipeasy] subscriber threw:", String(err));
+        logger.warn("[shipeasy] subscriber threw:", String(err));
       }
     }
   }
@@ -1111,7 +1159,7 @@ var Engine = class _Engine {
     try {
       return opts.decode(raw);
     } catch (err) {
-      console.warn(`[shipeasy] getConfig('${name}') decode failed:`, String(err));
+      logger.warn(`[shipeasy] getConfig('${name}') decode failed:`, String(err));
       return void 0;
     }
   }
@@ -1144,7 +1192,7 @@ var Engine = class _Engine {
     try {
       return { inExperiment: true, group: entry.group, params: decode(entry.params) };
     } catch (err) {
-      console.warn(`[shipeasy] getExperiment('${name}') decode failed:`, String(err));
+      logger.warn(`[shipeasy] getExperiment('${name}') decode failed:`, String(err));
       return notIn;
     }
   }
@@ -1347,6 +1395,7 @@ function shipeasy(opts) {
   const client = configureShipeasy({
     sdkKey: opts.clientKey,
     baseUrl,
+    logLevel: opts.logLevel,
     autoGuardrails: blanket,
     autoGuardrailGroups: groups,
     autoCollectAlways: acObj?.always === true,
@@ -1359,7 +1408,7 @@ function shipeasy(opts) {
   flags.notifyMounted();
   if (opts.autoIdentify !== false) {
     void client.identify({}).catch((err) => {
-      console.warn("[shipeasy] auto-identify failed:", String(err));
+      logger.warn("[shipeasy] auto-identify failed:", String(err));
     });
   }
   return attachDevtools(client, { adminUrl: opts.adminUrl });
@@ -1447,7 +1496,7 @@ var flags = {
   },
   identify(user) {
     if (!_client) {
-      console.warn("[shipeasy] flags.identify called before configureShipeasy()");
+      logger.warn("[shipeasy] flags.identify called before configureShipeasy()");
       return Promise.resolve();
     }
     return _client.identify(user);
@@ -1460,40 +1509,46 @@ var flags = {
    * force-static pages where SSR has no flag data.
    */
   get(name, defaultValue = false) {
-    const bs = getBootstrap();
-    if (bs !== null && name in bs.flags) return bs.flags[name];
-    if (!_mountedAndReady) return defaultValue;
-    if (_client) return _client.getFlag(name, defaultValue);
-    return readGateOverride(name) ?? defaultValue;
+    return safeRun("flags.get", defaultValue, () => {
+      const bs = getBootstrap();
+      if (bs !== null && name in bs.flags) return bs.flags[name];
+      if (!_mountedAndReady) return defaultValue;
+      if (_client) return _client.getFlag(name, defaultValue);
+      return readGateOverride(name) ?? defaultValue;
+    });
   },
   /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
   getDetail(name) {
-    if (_client) return _client.getFlagDetail(name);
-    const ov = readGateOverride(name);
-    if (ov !== null) return { value: ov, reason: "OVERRIDE" };
-    return { value: false, reason: "CLIENT_NOT_READY" };
+    return safeRun("flags.getDetail", { value: false, reason: "CLIENT_NOT_READY" }, () => {
+      if (_client) return _client.getFlagDetail(name);
+      const ov = readGateOverride(name);
+      if (ov !== null) return { value: ov, reason: "OVERRIDE" };
+      return { value: false, reason: "CLIENT_NOT_READY" };
+    });
   },
   getConfig(name, decode) {
-    const bs = getBootstrap();
-    if (bs !== null && name in bs.configs) {
-      const raw = bs.configs[name];
-      if (!decode) return raw;
+    return safeRun("flags.getConfig", void 0, () => {
+      const bs = getBootstrap();
+      if (bs !== null && name in bs.configs) {
+        const raw = bs.configs[name];
+        if (!decode) return raw;
+        try {
+          return decode(raw);
+        } catch {
+          return void 0;
+        }
+      }
+      if (!_mountedAndReady) return void 0;
+      if (_client) return _client.getConfig(name, decode);
+      const ov = readConfigOverride(name);
+      if (ov === void 0) return void 0;
+      if (!decode) return ov;
       try {
-        return decode(raw);
+        return decode(ov);
       } catch {
         return void 0;
       }
-    }
-    if (!_mountedAndReady) return void 0;
-    if (_client) return _client.getConfig(name, decode);
-    const ov = readConfigOverride(name);
-    if (ov === void 0) return void 0;
-    if (!decode) return ov;
-    try {
-      return decode(ov);
-    } catch {
-      return void 0;
-    }
+    });
   },
   getExperiment(name, defaultParams, decodeOrOpts, variants) {
     const fallback = {
@@ -1501,16 +1556,18 @@ var flags = {
       group: "control",
       params: defaultParams
     };
-    if (!_client) return fallback;
-    return typeof decodeOrOpts === "function" ? _client.getExperiment(name, defaultParams, decodeOrOpts, variants) : _client.getExperiment(name, defaultParams, decodeOrOpts ?? {});
+    return safeRun("flags.getExperiment", fallback, () => {
+      if (!_client) return fallback;
+      return typeof decodeOrOpts === "function" ? _client.getExperiment(name, defaultParams, decodeOrOpts, variants) : _client.getExperiment(name, defaultParams, decodeOrOpts ?? {});
+    });
   },
   /** Manually log an exposure for an enrolled experiment. See
    *  {@link Engine.logExposure}. No-op before configure(). */
   logExposure(name) {
-    _client?.logExposure(name);
+    safeRun("flags.logExposure", void 0, () => _client?.logExposure(name));
   },
   track(eventName, props) {
-    _client?.track(eventName, props);
+    safeRun("flags.track", void 0, () => _client?.track(eventName, props));
   },
   /**
    * Read a killswitch. Without `switchKey`, returns true when the killswitch is
@@ -1522,15 +1579,17 @@ var flags = {
    * available synchronously on first render.
    */
   ks(name, switchKey) {
-    const bs = getBootstrap();
-    if (bs !== null && bs.killswitches && name in bs.killswitches) {
-      const ks = bs.killswitches[name];
-      if (typeof ks === "boolean") return switchKey === void 0 ? ks : false;
-      if (switchKey === void 0) return false;
-      return ks[switchKey] === true;
-    }
-    if (!_mountedAndReady) return false;
-    return _client?.getKillswitch(name, switchKey) ?? false;
+    return safeRun("flags.ks", false, () => {
+      const bs = getBootstrap();
+      if (bs !== null && bs.killswitches && name in bs.killswitches) {
+        const ks = bs.killswitches[name];
+        if (typeof ks === "boolean") return switchKey === void 0 ? ks : false;
+        if (switchKey === void 0) return false;
+        return ks[switchKey] === true;
+      }
+      if (!_mountedAndReady) return false;
+      return _client?.getKillswitch(name, switchKey) ?? false;
+    });
   },
   flush() {
     return _client?.flush() ?? Promise.resolve();
@@ -1587,7 +1646,7 @@ var Client = class {
     this.engine = engine;
     this.attributes = _attributes(user);
     this._identify = this.engine.identify(this.attributes).catch((err) => {
-      console.warn("[shipeasy] Client identify failed:", String(err));
+      logger.warn("[shipeasy] Client identify failed:", String(err));
     });
   }
   /** Resolves once the engine's identify() for this user has completed. */
@@ -1595,20 +1654,33 @@ var Client = class {
     return this._identify;
   }
   getFlag(name, defaultValue = false) {
-    return this.engine.getFlag(name, defaultValue);
+    return safeRun("Client.getFlag", defaultValue, () => this.engine.getFlag(name, defaultValue));
   }
   getFlagDetail(name) {
-    return this.engine.getFlagDetail(name);
+    return safeRun(
+      "Client.getFlagDetail",
+      { value: false, reason: "CLIENT_NOT_READY" },
+      () => this.engine.getFlagDetail(name)
+    );
   }
   getConfig(name, decodeOrOpts) {
-    return this.engine.getConfig(name, decodeOrOpts);
+    return safeRun(
+      "Client.getConfig",
+      void 0,
+      () => this.engine.getConfig(name, decodeOrOpts)
+    );
   }
   getExperiment(name, defaultParams, decode) {
-    return this.engine.getExperiment(name, defaultParams, decode);
+    const notIn = { inExperiment: false, group: "control", params: defaultParams };
+    return safeRun(
+      "Client.getExperiment",
+      notIn,
+      () => this.engine.getExperiment(name, defaultParams, decode)
+    );
   }
   /** Read a killswitch (not user-bound; mirrors {@link Engine.getKillswitch}). */
   getKillswitch(name, switchKey) {
-    return this.engine.getKillswitch(name, switchKey);
+    return safeRun("Client.getKillswitch", false, () => this.engine.getKillswitch(name, switchKey));
   }
   /**
    * Record a conversion/metric event for the bound (identified) user. Delegates
@@ -1617,7 +1689,7 @@ var Client = class {
    * test mode.
    */
   track(eventName, props) {
-    this.engine.track(eventName, props);
+    safeRun("Client.track", void 0, () => this.engine.track(eventName, props));
   }
   /**
    * Log an exposure for `name` at the treatment's render for the bound user.
@@ -1626,12 +1698,12 @@ var Client = class {
    * `disableAutoExposure` to log exposure exactly when you render.
    */
   logExposure(name) {
-    this.engine.logExposure(name);
+    safeRun("Client.logExposure", void 0, () => this.engine.logExposure(name));
   }
 };
 function dispatchSee(problem, consequence, extras, kind) {
   if (!_client) {
-    console.warn("[shipeasy] see() called before shipeasy({ clientKey }) \u2014 error dropped");
+    logger.warn("[shipeasy] see() called before shipeasy({ clientKey }) \u2014 error dropped");
     return;
   }
   _client.reportError(problem, consequence, extras, kind);
@@ -1883,6 +1955,7 @@ export {
   LABEL_MARKER_RE,
   LABEL_MARKER_SEP,
   LABEL_MARKER_START,
+  LOG_LEVELS,
   _resetConfigureForTests,
   _resetShipeasyForTests,
   attachDevtools,

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

@@ -1,5 +1,7 @@
 import { Provider, EvaluationContext, Logger, ResolutionDetails, JsonValue } from '@openfeature/server-sdk';
 
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+
 type SeeExtras = Record<string, string | number | boolean | null | undefined>;
 type SeeKind = "caught" | "uncaught" | "unhandled_rejection" | "network" | "violation";
 /** Built by `causesThe(subject).to(outcome)` — never constructed by hand. */
@@ -137,6 +139,16 @@ interface EngineOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * How chatty the SDK is on `console` when it catches an error internally.
+     * Every public runtime method (getFlag/getConfig/getExperiment/getKillswitch/
+     * track/logExposure/see) fails silently — it returns a safe default rather
+     * than throwing — and surfaces the swallowed error through this level so you
+     * still find out. Ordering: `silent` < `error` < `warn` < `info` < `debug`.
+     * Defaults to `"warn"` (prints `error` + `warn`). Pass `"silent"` to mute the
+     * SDK entirely. See {@link LogLevel}.
+     */
+    logLevel?: LogLevel;
     /**
      * Attribute names usable for targeting but never persisted in analytics
      * (LD/Statsig `privateAttributes`). The server evaluates locally so private

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

@@ -1,5 +1,7 @@
 import { Provider, EvaluationContext, Logger, ResolutionDetails, JsonValue } from '@openfeature/server-sdk';
 
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+
 type SeeExtras = Record<string, string | number | boolean | null | undefined>;
 type SeeKind = "caught" | "uncaught" | "unhandled_rejection" | "network" | "violation";
 /** Built by `causesThe(subject).to(outcome)` — never constructed by hand. */
@@ -137,6 +139,16 @@ interface EngineOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * How chatty the SDK is on `console` when it catches an error internally.
+     * Every public runtime method (getFlag/getConfig/getExperiment/getKillswitch/
+     * track/logExposure/see) fails silently — it returns a safe default rather
+     * than throwing — and surfaces the swallowed error through this level so you
+     * still find out. Ordering: `silent` < `error` < `warn` < `info` < `debug`.
+     * Defaults to `"warn"` (prints `error` + `warn`). Pass `"silent"` to mute the
+     * SDK entirely. See {@link LogLevel}.
+     */
+    logLevel?: LogLevel;
     /**
      * Attribute names usable for targeting but never persisted in analytics
      * (LD/Statsig `privateAttributes`). The server evaluates locally so private

package/dist/openfeature-server/index.js

@@ -28,6 +28,39 @@ var import_server_sdk = require("@openfeature/server-sdk");
 // src/server/index.ts
 var import_node_async_hooks = require("async_hooks");
 
+// src/logger.ts
+var RANK = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4
+};
+var currentLevel = "warn";
+function write(method, args) {
+  try {
+    const c = globalThis.console;
+    if (!c) return;
+    const fn = c[method] ?? c.log;
+    if (typeof fn === "function") fn.call(c, ...args);
+  } catch {
+  }
+}
+var logger = {
+  error(...args) {
+    if (RANK[currentLevel] >= RANK.error) write("error", args);
+  },
+  warn(...args) {
+    if (RANK[currentLevel] >= RANK.warn) write("warn", args);
+  },
+  info(...args) {
+    if (RANK[currentLevel] >= RANK.info) write("info", args);
+  },
+  debug(...args) {
+    if (RANK[currentLevel] >= RANK.debug) write("debug", args);
+  }
+};
+
 // src/see/core.ts
 var SEE_MAX_SUBJECT = 200;
 var SEE_MAX_EXTRA_VALUE = 200;
@@ -183,7 +216,7 @@ function getShipeasyServerClient() {
 }
 function dispatchSee(problem, consequence, extras, kind) {
   if (!_server) {
-    console.warn("[shipeasy] see() called before shipeasy({ serverKey }) \u2014 error dropped");
+    logger.warn("[shipeasy] see() called before shipeasy({ serverKey }) \u2014 error dropped");
     return;
   }
   _server.reportError(problem, consequence, extras, kind);

package/dist/openfeature-server/index.mjs

@@ -4,6 +4,39 @@ import { ErrorCode } from "@openfeature/server-sdk";
 // src/server/index.ts
 import { AsyncLocalStorage } from "async_hooks";
 
+// src/logger.ts
+var RANK = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4
+};
+var currentLevel = "warn";
+function write(method, args) {
+  try {
+    const c = globalThis.console;
+    if (!c) return;
+    const fn = c[method] ?? c.log;
+    if (typeof fn === "function") fn.call(c, ...args);
+  } catch {
+  }
+}
+var logger = {
+  error(...args) {
+    if (RANK[currentLevel] >= RANK.error) write("error", args);
+  },
+  warn(...args) {
+    if (RANK[currentLevel] >= RANK.warn) write("warn", args);
+  },
+  info(...args) {
+    if (RANK[currentLevel] >= RANK.info) write("info", args);
+  },
+  debug(...args) {
+    if (RANK[currentLevel] >= RANK.debug) write("debug", args);
+  }
+};
+
 // src/see/core.ts
 var SEE_MAX_SUBJECT = 200;
 var SEE_MAX_EXTRA_VALUE = 200;
@@ -159,7 +192,7 @@ function getShipeasyServerClient() {
 }
 function dispatchSee(problem, consequence, extras, kind) {
   if (!_server) {
-    console.warn("[shipeasy] see() called before shipeasy({ serverKey }) \u2014 error dropped");
+    logger.warn("[shipeasy] see() called before shipeasy({ serverKey }) \u2014 error dropped");
     return;
   }
   _server.reportError(problem, consequence, extras, kind);

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

@@ -1,5 +1,7 @@
 import { Provider, EvaluationContext, Logger, ResolutionDetails, JsonValue } from '@openfeature/web-sdk';
 
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+
 type SeeExtras = Record<string, string | number | boolean | null | undefined>;
 type SeeKind = "caught" | "uncaught" | "unhandled_rejection" | "network" | "violation";
 /** Built by `causesThe(subject).to(outcome)` — never constructed by hand. */
@@ -131,6 +133,14 @@ interface EngineOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * How chatty the SDK is on `console` when it catches an error internally.
+     * Every public runtime method (getFlag/getConfig/getExperiment/getKillswitch/
+     * track/logExposure/see) fails silently — returning a safe default instead of
+     * throwing — and surfaces the swallowed error through this level. Ordering:
+     * `silent` < `error` < `warn` < `info` < `debug`. Defaults to `"warn"`.
+     */
+    logLevel?: LogLevel;
     /**
      * Suppress automatic exposure logging in `getExperiment` (Statsig's
      * `disableExposureLogging`). Default false — reading an enrolled variant

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

@@ -1,5 +1,7 @@
 import { Provider, EvaluationContext, Logger, ResolutionDetails, JsonValue } from '@openfeature/web-sdk';
 
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+
 type SeeExtras = Record<string, string | number | boolean | null | undefined>;
 type SeeKind = "caught" | "uncaught" | "unhandled_rejection" | "network" | "violation";
 /** Built by `causesThe(subject).to(outcome)` — never constructed by hand. */
@@ -131,6 +133,14 @@ interface EngineOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * How chatty the SDK is on `console` when it catches an error internally.
+     * Every public runtime method (getFlag/getConfig/getExperiment/getKillswitch/
+     * track/logExposure/see) fails silently — returning a safe default instead of
+     * throwing — and surfaces the swallowed error through this level. Ordering:
+     * `silent` < `error` < `warn` < `info` < `debug`. Defaults to `"warn"`.
+     */
+    logLevel?: LogLevel;
     /**
      * Suppress automatic exposure logging in `getExperiment` (Statsig's
      * `disableExposureLogging`). Default false — reading an enrolled variant

package/dist/server/index.d.mts

@@ -1,5 +1,9 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+/** All accepted {@link LogLevel} values, in increasing verbosity. */
+declare const LOG_LEVELS: readonly LogLevel[];
+
 type SeeExtras = Record<string, string | number | boolean | null | undefined>;
 type SeeKind = "caught" | "uncaught" | "unhandled_rejection" | "network" | "violation";
 /** Built by `causesThe(subject).to(outcome)` — never constructed by hand. */
@@ -243,6 +247,16 @@ interface EngineOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * How chatty the SDK is on `console` when it catches an error internally.
+     * Every public runtime method (getFlag/getConfig/getExperiment/getKillswitch/
+     * track/logExposure/see) fails silently — it returns a safe default rather
+     * than throwing — and surfaces the swallowed error through this level so you
+     * still find out. Ordering: `silent` < `error` < `warn` < `info` < `debug`.
+     * Defaults to `"warn"` (prints `error` + `warn`). Pass `"silent"` to mute the
+     * SDK entirely. See {@link LogLevel}.
+     */
+    logLevel?: LogLevel;
     /**
      * Attribute names usable for targeting but never persisted in analytics
      * (LD/Statsig `privateAttributes`). The server evaluates locally so private
@@ -460,6 +474,13 @@ interface ShipeasyServerConfig {
     user?: User;
     /** i18n profile to load for SSR translations, e.g. "en:prod". Defaults to "en:prod". */
     i18nDefaultProfile?: string;
+    /**
+     * How chatty the SDK is on `console` when it swallows an internal error.
+     * `silent` < `error` < `warn` < `info` < `debug`; defaults to `"warn"`. Every
+     * runtime read/track/see call fails silently to a safe default and reports the
+     * cause at this level. See {@link EngineOptions.logLevel}.
+     */
+    logLevel?: LogLevel;
     /**
      * Disable per-evaluation usage telemetry. ON by default. On Cloudflare
      * Workers each beacon is an outbound subrequest, so disable on hot SSR paths
@@ -789,4 +810,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-export { ANON_ID_COOKIE, type AttributesFn, type BootstrapData, type BootstrapEmitOptions, type BootstrapPayload, Client, type ConfigureOfflineOptions, type ConfigureOptions, type ConfigureTestOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, type ExpsBlob, FLAG_REASONS, type FetchLabelsOptions, type FlagDetail, type FlagReason, type FlagsBlob, type GetConfigOptions, type I18nForRequest, type LabelFile, type ScriptTagSpec, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type StickyBucketStore, type StickyEntry, type User, type Violation, _murmur3ForTests, _resetConfigureForTests, _resetShipeasyServerForTests, clearOverrides, configure, configureForOffline, configureForTesting, configureShipeasyServer, createInMemoryStickyStore, fetchLabelsForSSR, flags, getBootstrapData, getBootstrapTags, getShipeasyServerClient, i18n, isExpected, onChange, overrideConfig, overrideExperiment, overrideFlag, see, seeContext, shipeasy, version };
+export { ANON_ID_COOKIE, type AttributesFn, type BootstrapData, type BootstrapEmitOptions, type BootstrapPayload, Client, type ConfigureOfflineOptions, type ConfigureOptions, type ConfigureTestOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, type ExpsBlob, FLAG_REASONS, type FetchLabelsOptions, type FlagDetail, type FlagReason, type FlagsBlob, type GetConfigOptions, type I18nForRequest, LOG_LEVELS, type LabelFile, type LogLevel, type ScriptTagSpec, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type StickyBucketStore, type StickyEntry, type User, type Violation, _murmur3ForTests, _resetConfigureForTests, _resetShipeasyServerForTests, clearOverrides, configure, configureForOffline, configureForTesting, configureShipeasyServer, createInMemoryStickyStore, fetchLabelsForSSR, flags, getBootstrapData, getBootstrapTags, getShipeasyServerClient, i18n, isExpected, onChange, overrideConfig, overrideExperiment, overrideFlag, see, seeContext, shipeasy, version };

package/dist/server/index.d.ts

@@ -1,5 +1,9 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+/** All accepted {@link LogLevel} values, in increasing verbosity. */
+declare const LOG_LEVELS: readonly LogLevel[];
+
 type SeeExtras = Record<string, string | number | boolean | null | undefined>;
 type SeeKind = "caught" | "uncaught" | "unhandled_rejection" | "network" | "violation";
 /** Built by `causesThe(subject).to(outcome)` — never constructed by hand. */
@@ -243,6 +247,16 @@ interface EngineOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * How chatty the SDK is on `console` when it catches an error internally.
+     * Every public runtime method (getFlag/getConfig/getExperiment/getKillswitch/
+     * track/logExposure/see) fails silently — it returns a safe default rather
+     * than throwing — and surfaces the swallowed error through this level so you
+     * still find out. Ordering: `silent` < `error` < `warn` < `info` < `debug`.
+     * Defaults to `"warn"` (prints `error` + `warn`). Pass `"silent"` to mute the
+     * SDK entirely. See {@link LogLevel}.
+     */
+    logLevel?: LogLevel;
     /**
      * Attribute names usable for targeting but never persisted in analytics
      * (LD/Statsig `privateAttributes`). The server evaluates locally so private
@@ -460,6 +474,13 @@ interface ShipeasyServerConfig {
     user?: User;
     /** i18n profile to load for SSR translations, e.g. "en:prod". Defaults to "en:prod". */
     i18nDefaultProfile?: string;
+    /**
+     * How chatty the SDK is on `console` when it swallows an internal error.
+     * `silent` < `error` < `warn` < `info` < `debug`; defaults to `"warn"`. Every
+     * runtime read/track/see call fails silently to a safe default and reports the
+     * cause at this level. See {@link EngineOptions.logLevel}.
+     */
+    logLevel?: LogLevel;
     /**
      * Disable per-evaluation usage telemetry. ON by default. On Cloudflare
      * Workers each beacon is an outbound subrequest, so disable on hot SSR paths
@@ -789,4 +810,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-export { ANON_ID_COOKIE, type AttributesFn, type BootstrapData, type BootstrapEmitOptions, type BootstrapPayload, Client, type ConfigureOfflineOptions, type ConfigureOptions, type ConfigureTestOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, type ExpsBlob, FLAG_REASONS, type FetchLabelsOptions, type FlagDetail, type FlagReason, type FlagsBlob, type GetConfigOptions, type I18nForRequest, type LabelFile, type ScriptTagSpec, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type StickyBucketStore, type StickyEntry, type User, type Violation, _murmur3ForTests, _resetConfigureForTests, _resetShipeasyServerForTests, clearOverrides, configure, configureForOffline, configureForTesting, configureShipeasyServer, createInMemoryStickyStore, fetchLabelsForSSR, flags, getBootstrapData, getBootstrapTags, getShipeasyServerClient, i18n, isExpected, onChange, overrideConfig, overrideExperiment, overrideFlag, see, seeContext, shipeasy, version };
+export { ANON_ID_COOKIE, type AttributesFn, type BootstrapData, type BootstrapEmitOptions, type BootstrapPayload, Client, type ConfigureOfflineOptions, type ConfigureOptions, type ConfigureTestOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, type ExpsBlob, FLAG_REASONS, type FetchLabelsOptions, type FlagDetail, type FlagReason, type FlagsBlob, type GetConfigOptions, type I18nForRequest, LOG_LEVELS, type LabelFile, type LogLevel, type ScriptTagSpec, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type StickyBucketStore, type StickyEntry, type User, type Violation, _murmur3ForTests, _resetConfigureForTests, _resetShipeasyServerForTests, clearOverrides, configure, configureForOffline, configureForTesting, configureShipeasyServer, createInMemoryStickyStore, fetchLabelsForSSR, flags, getBootstrapData, getBootstrapTags, getShipeasyServerClient, i18n, isExpected, onChange, overrideConfig, overrideExperiment, overrideFlag, see, seeContext, shipeasy, version };