@shipeasy/sdk 6.2.0 → 6.3.1

package/dist/client/index.d.mts

@@ -1,3 +1,7 @@
+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. */
@@ -232,6 +236,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
@@ -468,6 +480,13 @@ interface ShipeasyClientConfig {
     autoCollect?: boolean | (Partial<AutoCollectGroups> & {
         always?: boolean;
     });
+    /**
+     * 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. Telemetry is ON by default — every
      * flag/config/experiment/killswitch read fires one fire-and-forget beacon
@@ -760,4 +779,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AttributesFn, type AutoCollectGroups, type BootstrapPayload, Client, type ConfigureOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, FLAG_REASONS, type FlagDetail, type FlagReason, type GetConfigOptions, type GetExperimentOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetConfigureForTests, _resetShipeasyForTests, attachDevtools, configure, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };
+export { type AttributesFn, type AutoCollectGroups, type BootstrapPayload, Client, type ConfigureOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, FLAG_REASONS, type FlagDetail, type FlagReason, type GetConfigOptions, type GetExperimentOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, LOG_LEVELS, type LabelAttrs, type LogLevel, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetConfigureForTests, _resetShipeasyForTests, attachDevtools, configure, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };

package/dist/client/index.d.ts

@@ -1,3 +1,7 @@
+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. */
@@ -232,6 +236,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
@@ -468,6 +480,13 @@ interface ShipeasyClientConfig {
     autoCollect?: boolean | (Partial<AutoCollectGroups> & {
         always?: boolean;
     });
+    /**
+     * 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. Telemetry is ON by default — every
      * flag/config/experiment/killswitch read fires one fire-and-forget beacon
@@ -760,4 +779,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AttributesFn, type AutoCollectGroups, type BootstrapPayload, Client, type ConfigureOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, FLAG_REASONS, type FlagDetail, type FlagReason, type GetConfigOptions, type GetExperimentOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetConfigureForTests, _resetShipeasyForTests, attachDevtools, configure, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };
+export { type AttributesFn, type AutoCollectGroups, type BootstrapPayload, Client, type ConfigureOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, FLAG_REASONS, type FlagDetail, type FlagReason, type GetConfigOptions, type GetExperimentOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, LOG_LEVELS, type LabelAttrs, type LogLevel, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetConfigureForTests, _resetShipeasyForTests, attachDevtools, configure, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };

package/dist/client/index.js

@@ -27,6 +27,7 @@ __export(client_exports, {
   LABEL_MARKER_RE: () => LABEL_MARKER_RE,
   LABEL_MARKER_SEP: () => LABEL_MARKER_SEP,
   LABEL_MARKER_START: () => LABEL_MARKER_START,
+  LOG_LEVELS: () => LOG_LEVELS,
   _resetConfigureForTests: () => _resetConfigureForTests,
   _resetShipeasyForTests: () => _resetShipeasyForTests,
   attachDevtools: () => attachDevtools,
@@ -109,6 +110,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;
@@ -952,6 +1000,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";
@@ -1086,7 +1135,7 @@ var Engine = class _Engine {
       try {
         l();
       } catch (err) {
-        console.warn("[shipeasy] subscriber threw:", String(err));
+        logger.warn("[shipeasy] subscriber threw:", String(err));
       }
     }
   }
@@ -1163,7 +1212,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;
     }
   }
@@ -1196,7 +1245,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;
     }
   }
@@ -1399,6 +1448,7 @@ function shipeasy(opts) {
   const client = configureShipeasy({
     sdkKey: opts.clientKey,
     baseUrl,
+    logLevel: opts.logLevel,
     autoGuardrails: blanket,
     autoGuardrailGroups: groups,
     autoCollectAlways: acObj?.always === true,
@@ -1411,7 +1461,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 });
@@ -1499,7 +1549,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);
@@ -1512,40 +1562,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 = {
@@ -1553,16 +1609,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
@@ -1574,15 +1632,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();
@@ -1639,7 +1699,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. */
@@ -1647,20 +1707,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
@@ -1669,7 +1742,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.
@@ -1678,12 +1751,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);
@@ -1936,6 +2009,7 @@ var i18n = {
   LABEL_MARKER_RE,
   LABEL_MARKER_SEP,
   LABEL_MARKER_START,
+  LOG_LEVELS,
   _resetConfigureForTests,
   _resetShipeasyForTests,
   attachDevtools,