@shipeasy/sdk 6.2.0 → 7.0.0

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. */
@@ -18,6 +20,10 @@ interface ExperimentResult<P> {
     inExperiment: boolean;
     group: string;
     params: P;
+    /** The universe this experiment belongs to. Carried in the SSR bootstrap +
+     *  `/sdk/evaluate` so the client can resolve `universe(name).assign()` by
+     *  finding the enrolled experiment in a universe. */
+    universe?: string;
 }
 /**
  * Why a flag evaluated the way it did (LaunchDarkly variationDetail parity).
@@ -63,13 +69,46 @@ interface ExperimentGroup {
 interface Experiment {
     universe: string;
     targetingGate?: string | null;
+    /**
+     * Per-experiment holdout flag (a `type='holdout'` gate). When set and the flag
+     * passes for a unit, that unit is *held out* of THIS experiment — never
+     * assigned, sees the universe defaults. Checked after the universe holdout,
+     * before allocation. Mirrors @shipeasy/core §B3.
+     */
+    holdoutGate?: string | null;
     allocationPct: number;
+    /**
+     * Contiguous half-open slice `[poolOffsetBp, poolOffsetBp + poolSizeBp)` of the
+     * *universe* hash space this experiment claims. Used only when `hashVersion >= 2`
+     * (pooled assignment / real mutual exclusion, §B4): the unit's universe segment
+     * must fall in this range to be in the experiment. Null ⇒ fall back to the
+     * legacy independent-salt `allocationPct` gate.
+     */
+    poolOffsetBp?: number | null;
+    poolSizeBp?: number | null;
+    /**
+     * A tail of the group split kept empty (basis points) so a new variant can be
+     * appended into it while running without reshuffling enrolled units. Group
+     * weights sum to `10000 − reservedHeadroomBp`; a unit hashing into the reserved
+     * tail is treated as not-assigned (sees universe defaults). §B5.
+     */
+    reservedHeadroomBp?: number | null;
     salt: string;
     groups: ExperimentGroup[];
     status: "draft" | "running" | "stopped" | "archived";
+    /** Bucketing scheme version. `>= 2` unlocks pooled (mutually-exclusive) assignment. */
+    hashVersion?: number;
     /** Attribute to bucket on (e.g. company_id); defaults to user_id/anonymous_id. */
     bucketBy?: string | null;
 }
+/** One param the universe owns: a name, a type, and the default a variant
+ *  inherits when it doesn't override the value (§A/§B2). */
+interface UniverseParam {
+    name: string;
+    type: "bool" | "int" | "number" | "string";
+    default: unknown;
+}
+type UniverseParamSchema = UniverseParam[];
 /** One persisted sticky assignment: group + 8-char salt prefix (reshuffle key). */
 interface StickyEntry {
     g: string;
@@ -88,6 +127,13 @@ interface StickyBucketStore {
 }
 interface Universe {
     holdout_range: [number, number] | null;
+    /**
+     * The universe's config schema — the single source of truth for param names,
+     * types, and defaults (§A). The `assign()` merge layers these defaults *under*
+     * an assigned variant's overrides so an unset param still returns the universe
+     * default. Null/absent ⇒ no defaults (legacy: variant params returned verbatim).
+     */
+    param_schema?: UniverseParamSchema | null;
 }
 interface Killswitch {
     killed: 0 | 1 | boolean;
@@ -114,6 +160,34 @@ interface BootstrapPayload {
     configs: Record<string, unknown>;
     experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
     killswitches: Record<string, boolean | Record<string, boolean>>;
+    /** Per-universe param defaults (name → default map) so the client can resolve
+     *  `universe(name).get(field)` to the universe default even when the unit is
+     *  not enrolled in any experiment there. Only universes with running
+     *  experiments are included. */
+    universes?: Record<string, {
+        defaults: Record<string, unknown>;
+    }>;
+}
+/**
+ * The result of `universe(name).assign(user)` — a user's standing in a universe.
+ * A universe is a mutual-exclusion pool, so a unit lands in **at most one**
+ * experiment. Never throws: an un-enrolled unit still resolves `get()` to the
+ * universe defaults (or your fallback). Reading is side-effect free — the single
+ * exposure is logged once by `assign()` when the unit is enrolled.
+ */
+interface Assignment {
+    /** The experiment the unit landed in, or `null` when not enrolled. */
+    readonly name: string | null;
+    /** The assigned variant/group name, or `null` when not enrolled. */
+    readonly group: string | null;
+    /** True iff the unit is enrolled in an experiment in this universe. */
+    readonly enrolled: boolean;
+    /**
+     * Read a resolved param: the assigned variant's override, else the universe
+     * default, else `fallback`. Works even when not enrolled (variant layer is
+     * absent, so you get `universeDefault ?? fallback`).
+     */
+    get<T = unknown>(field: string, fallback?: T): T | undefined;
 }
 type EngineEnv = "dev" | "staging" | "prod";
 interface EngineOptions {
@@ -137,6 +211,24 @@ 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;
+    /**
+     * Opt out of SDK-internal error self-monitoring. When one of the SDK's own
+     * last-resort guards catches an internal failure (an "on our end" bug), the
+     * SDK reports it to Shipeasy's own project so we can track SDK bugs across
+     * apps — never to your project. ON by default; forced off in test mode. Pass
+     * `true` to disable.
+     */
+    disableInternalErrorReporting?: boolean;
     /**
      * Attribute names usable for targeting but never persisted in analytics
      * (LD/Statsig `privateAttributes`). The server evaluates locally so private
@@ -179,6 +271,7 @@ declare class Engine {
     private readonly flagOverrides;
     private readonly configOverrides;
     private readonly experimentOverrides;
+    private readonly exposureSeen;
     private readonly changeListeners;
     constructor(opts: EngineOptions);
     /**
@@ -258,19 +351,47 @@ declare class Engine {
     getFlag(name: string, user: User, defaultValue?: boolean): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getConfig<T = unknown>(name: string, opts: GetConfigOptions<T>): T;
-    getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
+    /**
+     * Bind the per-experiment sticky seam over the configured {@link StickyBucketStore}
+     * for one (unit, experiment). Absent store ⇒ deterministic (no sticky).
+     */
+    private bindSticky;
+    /**
+     * Evaluate one experiment by name for `user` — override → full classify
+     * pipeline (targeting → universe holdout → holdout gate → sticky → allocation
+     * → group), merging the universe defaults under the assigned variant (§B2).
+     * Internal: the public surface is `universe(name).assign(user)`. Reused by the
+     * SSR `evaluate()` bootstrap (keyed by experiment name) and by `assignUniverse`.
+     */
+    private evalExperiment;
+    /**
+     * Assign `user` within `universeName`. A universe is a mutual-exclusion pool,
+     * so a unit lands in **at most one** experiment; the returned {@link Assignment}
+     * exposes the variant + resolved params and auto-logs a single exposure when
+     * enrolled. An un-enrolled unit still resolves `get()` to the universe defaults.
+     * Never throws. This is the sole experiment read path (there is no
+     * `getExperiment` — a caller asks a universe, not an experiment).
+     */
+    assignUniverse(universeName: string, user: User): Assignment;
+    /**
+     * The universe-first experiment read entry point:
+     * `engine.universe("checkout").assign(user)`. Returns a reusable handle bound
+     * to one universe; `assign(user)` picks the ≤1 experiment the unit is pooled
+     * into and auto-logs a single exposure. See {@link assignUniverse}.
+     */
+    universe(name: string): {
+        assign(user: User): Assignment;
+    };
     /** Drop caller-marked private attributes from an outbound props bag. */
     private stripPrivate;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
     /**
-     * Emit an exposure event for an experiment at the server-side decision point
-     * (parity with the browser's auto-exposure). The server is stateless and
-     * never auto-logs, so call this when you actually present the treatment.
-     * Re-evaluates the experiment for `user` (a bare `user_id` string is wrapped
-     * as `{ user_id }`); if the user is enrolled, POSTs a single exposure to
-     * `/collect`. No-op in test mode or when the user isn't enrolled.
+     * 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.
      */
-    logExposure(user: string | User, name: string): void;
+    private postExposure;
     /**
      * Report a structured error into the errors primitive. Fire-and-forget —
      * never blocks or throws into the request path. Spam-guarded by a 30s

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. */
@@ -18,6 +20,10 @@ interface ExperimentResult<P> {
     inExperiment: boolean;
     group: string;
     params: P;
+    /** The universe this experiment belongs to. Carried in the SSR bootstrap +
+     *  `/sdk/evaluate` so the client can resolve `universe(name).assign()` by
+     *  finding the enrolled experiment in a universe. */
+    universe?: string;
 }
 /**
  * Why a flag evaluated the way it did (LaunchDarkly variationDetail parity).
@@ -63,13 +69,46 @@ interface ExperimentGroup {
 interface Experiment {
     universe: string;
     targetingGate?: string | null;
+    /**
+     * Per-experiment holdout flag (a `type='holdout'` gate). When set and the flag
+     * passes for a unit, that unit is *held out* of THIS experiment — never
+     * assigned, sees the universe defaults. Checked after the universe holdout,
+     * before allocation. Mirrors @shipeasy/core §B3.
+     */
+    holdoutGate?: string | null;
     allocationPct: number;
+    /**
+     * Contiguous half-open slice `[poolOffsetBp, poolOffsetBp + poolSizeBp)` of the
+     * *universe* hash space this experiment claims. Used only when `hashVersion >= 2`
+     * (pooled assignment / real mutual exclusion, §B4): the unit's universe segment
+     * must fall in this range to be in the experiment. Null ⇒ fall back to the
+     * legacy independent-salt `allocationPct` gate.
+     */
+    poolOffsetBp?: number | null;
+    poolSizeBp?: number | null;
+    /**
+     * A tail of the group split kept empty (basis points) so a new variant can be
+     * appended into it while running without reshuffling enrolled units. Group
+     * weights sum to `10000 − reservedHeadroomBp`; a unit hashing into the reserved
+     * tail is treated as not-assigned (sees universe defaults). §B5.
+     */
+    reservedHeadroomBp?: number | null;
     salt: string;
     groups: ExperimentGroup[];
     status: "draft" | "running" | "stopped" | "archived";
+    /** Bucketing scheme version. `>= 2` unlocks pooled (mutually-exclusive) assignment. */
+    hashVersion?: number;
     /** Attribute to bucket on (e.g. company_id); defaults to user_id/anonymous_id. */
     bucketBy?: string | null;
 }
+/** One param the universe owns: a name, a type, and the default a variant
+ *  inherits when it doesn't override the value (§A/§B2). */
+interface UniverseParam {
+    name: string;
+    type: "bool" | "int" | "number" | "string";
+    default: unknown;
+}
+type UniverseParamSchema = UniverseParam[];
 /** One persisted sticky assignment: group + 8-char salt prefix (reshuffle key). */
 interface StickyEntry {
     g: string;
@@ -88,6 +127,13 @@ interface StickyBucketStore {
 }
 interface Universe {
     holdout_range: [number, number] | null;
+    /**
+     * The universe's config schema — the single source of truth for param names,
+     * types, and defaults (§A). The `assign()` merge layers these defaults *under*
+     * an assigned variant's overrides so an unset param still returns the universe
+     * default. Null/absent ⇒ no defaults (legacy: variant params returned verbatim).
+     */
+    param_schema?: UniverseParamSchema | null;
 }
 interface Killswitch {
     killed: 0 | 1 | boolean;
@@ -114,6 +160,34 @@ interface BootstrapPayload {
     configs: Record<string, unknown>;
     experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
     killswitches: Record<string, boolean | Record<string, boolean>>;
+    /** Per-universe param defaults (name → default map) so the client can resolve
+     *  `universe(name).get(field)` to the universe default even when the unit is
+     *  not enrolled in any experiment there. Only universes with running
+     *  experiments are included. */
+    universes?: Record<string, {
+        defaults: Record<string, unknown>;
+    }>;
+}
+/**
+ * The result of `universe(name).assign(user)` — a user's standing in a universe.
+ * A universe is a mutual-exclusion pool, so a unit lands in **at most one**
+ * experiment. Never throws: an un-enrolled unit still resolves `get()` to the
+ * universe defaults (or your fallback). Reading is side-effect free — the single
+ * exposure is logged once by `assign()` when the unit is enrolled.
+ */
+interface Assignment {
+    /** The experiment the unit landed in, or `null` when not enrolled. */
+    readonly name: string | null;
+    /** The assigned variant/group name, or `null` when not enrolled. */
+    readonly group: string | null;
+    /** True iff the unit is enrolled in an experiment in this universe. */
+    readonly enrolled: boolean;
+    /**
+     * Read a resolved param: the assigned variant's override, else the universe
+     * default, else `fallback`. Works even when not enrolled (variant layer is
+     * absent, so you get `universeDefault ?? fallback`).
+     */
+    get<T = unknown>(field: string, fallback?: T): T | undefined;
 }
 type EngineEnv = "dev" | "staging" | "prod";
 interface EngineOptions {
@@ -137,6 +211,24 @@ 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;
+    /**
+     * Opt out of SDK-internal error self-monitoring. When one of the SDK's own
+     * last-resort guards catches an internal failure (an "on our end" bug), the
+     * SDK reports it to Shipeasy's own project so we can track SDK bugs across
+     * apps — never to your project. ON by default; forced off in test mode. Pass
+     * `true` to disable.
+     */
+    disableInternalErrorReporting?: boolean;
     /**
      * Attribute names usable for targeting but never persisted in analytics
      * (LD/Statsig `privateAttributes`). The server evaluates locally so private
@@ -179,6 +271,7 @@ declare class Engine {
     private readonly flagOverrides;
     private readonly configOverrides;
     private readonly experimentOverrides;
+    private readonly exposureSeen;
     private readonly changeListeners;
     constructor(opts: EngineOptions);
     /**
@@ -258,19 +351,47 @@ declare class Engine {
     getFlag(name: string, user: User, defaultValue?: boolean): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getConfig<T = unknown>(name: string, opts: GetConfigOptions<T>): T;
-    getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
+    /**
+     * Bind the per-experiment sticky seam over the configured {@link StickyBucketStore}
+     * for one (unit, experiment). Absent store ⇒ deterministic (no sticky).
+     */
+    private bindSticky;
+    /**
+     * Evaluate one experiment by name for `user` — override → full classify
+     * pipeline (targeting → universe holdout → holdout gate → sticky → allocation
+     * → group), merging the universe defaults under the assigned variant (§B2).
+     * Internal: the public surface is `universe(name).assign(user)`. Reused by the
+     * SSR `evaluate()` bootstrap (keyed by experiment name) and by `assignUniverse`.
+     */
+    private evalExperiment;
+    /**
+     * Assign `user` within `universeName`. A universe is a mutual-exclusion pool,
+     * so a unit lands in **at most one** experiment; the returned {@link Assignment}
+     * exposes the variant + resolved params and auto-logs a single exposure when
+     * enrolled. An un-enrolled unit still resolves `get()` to the universe defaults.
+     * Never throws. This is the sole experiment read path (there is no
+     * `getExperiment` — a caller asks a universe, not an experiment).
+     */
+    assignUniverse(universeName: string, user: User): Assignment;
+    /**
+     * The universe-first experiment read entry point:
+     * `engine.universe("checkout").assign(user)`. Returns a reusable handle bound
+     * to one universe; `assign(user)` picks the ≤1 experiment the unit is pooled
+     * into and auto-logs a single exposure. See {@link assignUniverse}.
+     */
+    universe(name: string): {
+        assign(user: User): Assignment;
+    };
     /** Drop caller-marked private attributes from an outbound props bag. */
     private stripPrivate;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
     /**
-     * Emit an exposure event for an experiment at the server-side decision point
-     * (parity with the browser's auto-exposure). The server is stateless and
-     * never auto-logs, so call this when you actually present the treatment.
-     * Re-evaluates the experiment for `user` (a bare `user_id` string is wrapped
-     * as `{ user_id }`); if the user is enrolled, POSTs a single exposure to
-     * `/collect`. No-op in test mode or when the user isn't enrolled.
+     * 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.
      */
-    logExposure(user: string | User, name: string): void;
+    private postExposure;
     /**
      * Report a structured error into the errors primitive. Fire-and-forget —
      * never blocks or throws into the request path. Spam-guarded by a 30s

package/dist/openfeature-server/index.js

@@ -32,6 +32,8 @@ var import_node_async_hooks = require("async_hooks");
 var SEE_MAX_SUBJECT = 200;
 var SEE_MAX_EXTRA_VALUE = 200;
 var SEE_MAX_EXTRA_KEYS = 20;
+var SEE_DEDUP_WINDOW_MS = 3e4;
+var SEE_MAX_PER_SESSION = 25;
 function causesThe(subject) {
   return {
     to(outcome) {
@@ -142,6 +144,69 @@ function startControlFlowChain(err) {
     }
   };
 }
+function topStackLine(stack) {
+  if (!stack) return "";
+  for (const line of stack.split("\n")) {
+    if (/^\s*at |@|:\d+:\d+/.test(line)) return line.trim().slice(0, 200);
+  }
+  return "";
+}
+var SeeLimiter = class {
+  constructor(maxPerSession = SEE_MAX_PER_SESSION, dedupWindowMs = SEE_DEDUP_WINDOW_MS) {
+    this.maxPerSession = maxPerSession;
+    this.dedupWindowMs = dedupWindowMs;
+  }
+  maxPerSession;
+  dedupWindowMs;
+  lastSent = /* @__PURE__ */ new Map();
+  sent = 0;
+  shouldSend(ev) {
+    if (this.sent >= this.maxPerSession) return false;
+    const key = `${ev.kind}|${ev.error_type}|${ev.message.slice(0, 200)}|${topStackLine(ev.stack)}`;
+    const now = Date.now();
+    const prev = this.lastSent.get(key);
+    if (prev !== void 0 && now - prev < this.dedupWindowMs) return false;
+    this.lastSent.set(key, now);
+    this.sent += 1;
+    return true;
+  }
+};
+
+// src/internal-report.ts
+var limiter = new SeeLimiter();
+
+// 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/server/index.ts
 var _I18N_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n");
@@ -183,7 +248,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

@@ -8,6 +8,8 @@ import { AsyncLocalStorage } from "async_hooks";
 var SEE_MAX_SUBJECT = 200;
 var SEE_MAX_EXTRA_VALUE = 200;
 var SEE_MAX_EXTRA_KEYS = 20;
+var SEE_DEDUP_WINDOW_MS = 3e4;
+var SEE_MAX_PER_SESSION = 25;
 function causesThe(subject) {
   return {
     to(outcome) {
@@ -118,6 +120,69 @@ function startControlFlowChain(err) {
     }
   };
 }
+function topStackLine(stack) {
+  if (!stack) return "";
+  for (const line of stack.split("\n")) {
+    if (/^\s*at |@|:\d+:\d+/.test(line)) return line.trim().slice(0, 200);
+  }
+  return "";
+}
+var SeeLimiter = class {
+  constructor(maxPerSession = SEE_MAX_PER_SESSION, dedupWindowMs = SEE_DEDUP_WINDOW_MS) {
+    this.maxPerSession = maxPerSession;
+    this.dedupWindowMs = dedupWindowMs;
+  }
+  maxPerSession;
+  dedupWindowMs;
+  lastSent = /* @__PURE__ */ new Map();
+  sent = 0;
+  shouldSend(ev) {
+    if (this.sent >= this.maxPerSession) return false;
+    const key = `${ev.kind}|${ev.error_type}|${ev.message.slice(0, 200)}|${topStackLine(ev.stack)}`;
+    const now = Date.now();
+    const prev = this.lastSent.get(key);
+    if (prev !== void 0 && now - prev < this.dedupWindowMs) return false;
+    this.lastSent.set(key, now);
+    this.sent += 1;
+    return true;
+  }
+};
+
+// src/internal-report.ts
+var limiter = new SeeLimiter();
+
+// 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/server/index.ts
 var _I18N_SSR_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:ssr-i18n");
@@ -159,7 +224,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);