@shipeasy/sdk 3.1.0 → 4.2.0

package/dist/server/index.d.mts

@@ -1,4 +1,85 @@
-declare const version = "1.0.0";
+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. */
+interface Consequence {
+    readonly __seConsequence: true;
+    readonly subject: string;
+    readonly outcome: string;
+}
+/**
+ * Non-exception problem, built by `violation(name)`. A plain branded object
+ * (not an Error subclass) so `.message()` can be a builder method without
+ * colliding with `Error.prototype.message`.
+ */
+interface Violation {
+    readonly __seViolation: true;
+    readonly violationName: string;
+    readonly violationMessage?: string;
+    /** Attach free-form detail. Variable data goes HERE (or in extras), never in the name. */
+    message(msg: string): Violation;
+}
+/**
+ * Identity of a problem that see() already reported, carried on the wire as
+ * the `caused_by` of a later occurrence. Holds exactly the fields the worker's
+ * fingerprint function consumes (raw `message`/`stack` — the server normalizes
+ * them) so the backend can recompute the prior issue's fingerprint and link
+ * the two issues. See `findCausedBy` for how the link is discovered.
+ */
+interface SeeCausedBy {
+    error_type: string;
+    message: string;
+    stack?: string;
+    subject: string;
+    outcome: string;
+}
+/** Wire shape — the `type:"error"` RawEvent variant accepted by POST /collect. */
+interface SeeErrorEvent {
+    type: "error";
+    kind: SeeKind;
+    /** Error class/name (e.g. "TypeError") or the violation name. */
+    error_type: string;
+    message: string;
+    stack?: string;
+    /** Consequence: "<error_type> causes the <subject> to <outcome>". */
+    subject: string;
+    outcome: string;
+    extras?: Record<string, string | number | boolean>;
+    url?: string;
+    user_id?: string;
+    anonymous_id?: string;
+    side: "client" | "server";
+    env?: string;
+    sdk_version: string;
+    ts: number;
+    /**
+     * The earlier reported problem this occurrence descends from — present when
+     * the same error was caught + reported at an inner boundary and then
+     * re-thrown (or wrapped via `{ cause }`) and reported again at an outer one.
+     * Lets the backend stitch the two issues into a cause chain instead of
+     * double-counting them as unrelated.
+     */
+    caused_by?: SeeCausedBy;
+}
+interface SeeExtrasTail {
+    /** Attach debugging metadata. Callable repeatedly — keys merge, later wins. */
+    extras(extras: SeeExtras): SeeExtrasTail;
+}
+interface SeeOutcomeStep {
+    /** The user-visible impact: `.causes_the("checkout").to("use cached prices")`. */
+    to(outcome: string): SeeExtrasTail;
+}
+interface SeeChain {
+    /** Start the consequence sentence — the product surface affected. */
+    causes_the(subject: string): SeeOutcomeStep;
+    /** camelCase alias of {@link SeeChain.causes_the}. */
+    causesThe(subject: string): SeeOutcomeStep;
+}
+interface SeeViolationChain extends SeeChain {
+    /** Free-form detail. Variable data goes here (or extras), never in the name. */
+    message(msg: string): SeeViolationChain;
+}
+
+declare const version = "4.0.0";
 interface User {
     user_id?: string;
     anonymous_id?: string;
@@ -68,6 +149,7 @@ declare class FlagsClient {
     private readonly baseUrl;
     private readonly env;
     private readonly telemetry;
+    private readonly seeLimiter;
     private flagsBlob;
     private expsBlob;
     private flagsEtag;
@@ -87,6 +169,12 @@ declare class FlagsClient {
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * Report a structured error into the errors primitive. Fire-and-forget —
+     * never blocks or throws into the request path. Spam-guarded by a 30s
+     * dedup window + per-process cap.
+     */
+    reportError(problem: unknown, consequence: Consequence, extras?: SeeExtras, kind?: SeeKind): void;
     /**
      * Evaluate all flags, configs, and experiments for a user against the locally
      * cached blob (no network call). Applies ?se_ks_* / ?se_cf_* / ?se_exp_*
@@ -229,5 +317,49 @@ declare const flags: {
      */
     evaluate(user: User, rawUrl?: string): BootstrapPayload;
 };
+interface SeeApi {
+    /**
+     * Report a handled problem and its product consequence:
+     *
+     * ```ts
+     * import { see } from "@shipeasy/sdk/server";
+     *
+     * try {
+     *   await chargeCard(order);
+     * } catch (e) {
+     *   see(e).causes_the("payment").to("use the backup processor").extras({ order_id: order.id });
+     *   await chargeViaBackup(order);
+     * }
+     * ```
+     *
+     * The chain dispatches on the next microtask — fire-and-forget into the
+     * errors primitive (grouped by fingerprint, near-real-time timeseries).
+     * If you don't know the consequence of an exception, don't catch it.
+     */
+    (problem: unknown): SeeChain;
+    /**
+     * Report a non-exception problem. Prefer passing a caught Error to `see()`
+     * when one exists. The name is a stable identifier (it participates in the
+     * issue fingerprint) — variable data goes in `.message()` or `.extras()`.
+     *
+     * ```ts
+     * if (results.length > LIMIT) {
+     *   see.Violation("large query").causes_the("search results").to("be trimmed");
+     * }
+     * ```
+     */
+    Violation(name: string): SeeViolationChain;
+    /**
+     * Mark an exception as expected control flow — documents the expectation and
+     * reports nothing. The reason must start with "because".
+     */
+    ControlFlowException(err: unknown, because: string): void;
+}
+/**
+ * Structured error reporter — the whole grammar hangs off this one import.
+ * Safe to import anywhere; a call before `shipeasy({ serverKey })` warns and
+ * drops (never throws).
+ */
+declare const see: SeeApi;
 
-export { type BootstrapHtmlOptions, type BootstrapPayload, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, shipeasy, version };
+export { type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, see, shipeasy, version };

package/dist/server/index.d.ts

@@ -1,4 +1,85 @@
-declare const version = "1.0.0";
+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. */
+interface Consequence {
+    readonly __seConsequence: true;
+    readonly subject: string;
+    readonly outcome: string;
+}
+/**
+ * Non-exception problem, built by `violation(name)`. A plain branded object
+ * (not an Error subclass) so `.message()` can be a builder method without
+ * colliding with `Error.prototype.message`.
+ */
+interface Violation {
+    readonly __seViolation: true;
+    readonly violationName: string;
+    readonly violationMessage?: string;
+    /** Attach free-form detail. Variable data goes HERE (or in extras), never in the name. */
+    message(msg: string): Violation;
+}
+/**
+ * Identity of a problem that see() already reported, carried on the wire as
+ * the `caused_by` of a later occurrence. Holds exactly the fields the worker's
+ * fingerprint function consumes (raw `message`/`stack` — the server normalizes
+ * them) so the backend can recompute the prior issue's fingerprint and link
+ * the two issues. See `findCausedBy` for how the link is discovered.
+ */
+interface SeeCausedBy {
+    error_type: string;
+    message: string;
+    stack?: string;
+    subject: string;
+    outcome: string;
+}
+/** Wire shape — the `type:"error"` RawEvent variant accepted by POST /collect. */
+interface SeeErrorEvent {
+    type: "error";
+    kind: SeeKind;
+    /** Error class/name (e.g. "TypeError") or the violation name. */
+    error_type: string;
+    message: string;
+    stack?: string;
+    /** Consequence: "<error_type> causes the <subject> to <outcome>". */
+    subject: string;
+    outcome: string;
+    extras?: Record<string, string | number | boolean>;
+    url?: string;
+    user_id?: string;
+    anonymous_id?: string;
+    side: "client" | "server";
+    env?: string;
+    sdk_version: string;
+    ts: number;
+    /**
+     * The earlier reported problem this occurrence descends from — present when
+     * the same error was caught + reported at an inner boundary and then
+     * re-thrown (or wrapped via `{ cause }`) and reported again at an outer one.
+     * Lets the backend stitch the two issues into a cause chain instead of
+     * double-counting them as unrelated.
+     */
+    caused_by?: SeeCausedBy;
+}
+interface SeeExtrasTail {
+    /** Attach debugging metadata. Callable repeatedly — keys merge, later wins. */
+    extras(extras: SeeExtras): SeeExtrasTail;
+}
+interface SeeOutcomeStep {
+    /** The user-visible impact: `.causes_the("checkout").to("use cached prices")`. */
+    to(outcome: string): SeeExtrasTail;
+}
+interface SeeChain {
+    /** Start the consequence sentence — the product surface affected. */
+    causes_the(subject: string): SeeOutcomeStep;
+    /** camelCase alias of {@link SeeChain.causes_the}. */
+    causesThe(subject: string): SeeOutcomeStep;
+}
+interface SeeViolationChain extends SeeChain {
+    /** Free-form detail. Variable data goes here (or extras), never in the name. */
+    message(msg: string): SeeViolationChain;
+}
+
+declare const version = "4.0.0";
 interface User {
     user_id?: string;
     anonymous_id?: string;
@@ -68,6 +149,7 @@ declare class FlagsClient {
     private readonly baseUrl;
     private readonly env;
     private readonly telemetry;
+    private readonly seeLimiter;
     private flagsBlob;
     private expsBlob;
     private flagsEtag;
@@ -87,6 +169,12 @@ declare class FlagsClient {
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getExperiment<P extends Record<string, unknown>>(name: string, user: User, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
     track(userId: string, eventName: string, props?: Record<string, unknown>): void;
+    /**
+     * Report a structured error into the errors primitive. Fire-and-forget —
+     * never blocks or throws into the request path. Spam-guarded by a 30s
+     * dedup window + per-process cap.
+     */
+    reportError(problem: unknown, consequence: Consequence, extras?: SeeExtras, kind?: SeeKind): void;
     /**
      * Evaluate all flags, configs, and experiments for a user against the locally
      * cached blob (no network call). Applies ?se_ks_* / ?se_cf_* / ?se_exp_*
@@ -229,5 +317,49 @@ declare const flags: {
      */
     evaluate(user: User, rawUrl?: string): BootstrapPayload;
 };
+interface SeeApi {
+    /**
+     * Report a handled problem and its product consequence:
+     *
+     * ```ts
+     * import { see } from "@shipeasy/sdk/server";
+     *
+     * try {
+     *   await chargeCard(order);
+     * } catch (e) {
+     *   see(e).causes_the("payment").to("use the backup processor").extras({ order_id: order.id });
+     *   await chargeViaBackup(order);
+     * }
+     * ```
+     *
+     * The chain dispatches on the next microtask — fire-and-forget into the
+     * errors primitive (grouped by fingerprint, near-real-time timeseries).
+     * If you don't know the consequence of an exception, don't catch it.
+     */
+    (problem: unknown): SeeChain;
+    /**
+     * Report a non-exception problem. Prefer passing a caught Error to `see()`
+     * when one exists. The name is a stable identifier (it participates in the
+     * issue fingerprint) — variable data goes in `.message()` or `.extras()`.
+     *
+     * ```ts
+     * if (results.length > LIMIT) {
+     *   see.Violation("large query").causes_the("search results").to("be trimmed");
+     * }
+     * ```
+     */
+    Violation(name: string): SeeViolationChain;
+    /**
+     * Mark an exception as expected control flow — documents the expectation and
+     * reports nothing. The reason must start with "because".
+     */
+    ControlFlowException(err: unknown, because: string): void;
+}
+/**
+ * Structured error reporter — the whole grammar hangs off this one import.
+ * Safe to import anywhere; a call before `shipeasy({ serverKey })` warns and
+ * drops (never throws).
+ */
+declare const see: SeeApi;
 
-export { type BootstrapHtmlOptions, type BootstrapPayload, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, shipeasy, version };
+export { type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, see, shipeasy, version };

package/dist/server/index.js

@@ -38,6 +38,7 @@ __export(server_exports, {
   getBootstrapHtml: () => getBootstrapHtml,
   getShipeasyServerClient: () => getShipeasyServerClient,
   i18n: () => i18n,
+  see: () => see,
   shipeasy: () => shipeasy,
   version: () => version
 });
@@ -103,8 +104,247 @@ function send(url) {
   }
 }
 
+// src/see/core.ts
+var SEE_MAX_MESSAGE = 500;
+var SEE_MAX_STACK = 8e3;
+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) {
+      return {
+        __seConsequence: true,
+        subject: truncate(String(subject), SEE_MAX_SUBJECT),
+        outcome: truncate(String(outcome), SEE_MAX_SUBJECT)
+      };
+    }
+  };
+}
+function violation(name) {
+  const make = (msg) => ({
+    __seViolation: true,
+    violationName: String(name),
+    ...msg !== void 0 ? { violationMessage: msg } : {},
+    message(m) {
+      return make(String(m));
+    }
+  });
+  return make();
+}
+function isViolation(p) {
+  return typeof p === "object" && p !== null && p.__seViolation === true;
+}
+var EXPECTED_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-expected");
+function markExpected(err, because) {
+  if (typeof err !== "object" || err === null) return;
+  try {
+    Object.defineProperty(err, EXPECTED_SYM, {
+      value: String(because),
+      enumerable: false,
+      configurable: true
+    });
+  } catch {
+  }
+}
+var REPORTED_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-reported");
+var SEE_MAX_CAUSE_DEPTH = 8;
+function readReportStamp(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const v = err[REPORTED_SYM];
+  return v !== void 0 && v !== null && typeof v === "object" ? v : void 0;
+}
+function findCausedBy(problem) {
+  let cur = problem;
+  const seen = /* @__PURE__ */ new Set();
+  for (let depth = 0; depth < SEE_MAX_CAUSE_DEPTH; depth++) {
+    if (typeof cur !== "object" || cur === null || seen.has(cur)) break;
+    seen.add(cur);
+    const stamp = readReportStamp(cur);
+    if (stamp) return stamp;
+    cur = cur.cause;
+  }
+  return void 0;
+}
+function markReported(problem, ev) {
+  if (!(problem instanceof Error)) return;
+  const stamp = {
+    error_type: ev.error_type,
+    message: ev.message,
+    subject: ev.subject,
+    outcome: ev.outcome
+  };
+  if (ev.stack !== void 0) stamp.stack = ev.stack;
+  try {
+    Object.defineProperty(problem, REPORTED_SYM, {
+      value: Object.freeze(stamp),
+      enumerable: false,
+      configurable: true,
+      writable: true
+    });
+  } catch {
+  }
+}
+function truncate(s, max) {
+  return s.length > max ? s.slice(0, max) : s;
+}
+function sanitizeExtras(extras) {
+  if (!extras || typeof extras !== "object") return void 0;
+  const out = {};
+  let n = 0;
+  for (const [k, v] of Object.entries(extras)) {
+    if (v === null || v === void 0) continue;
+    if (n >= SEE_MAX_EXTRA_KEYS) break;
+    if (typeof v === "string") out[k] = truncate(v, SEE_MAX_EXTRA_VALUE);
+    else if (typeof v === "number" && Number.isFinite(v)) out[k] = v;
+    else if (typeof v === "boolean") out[k] = v;
+    else continue;
+    n += 1;
+  }
+  return n > 0 ? out : void 0;
+}
+function captureCallsiteStack() {
+  const raw = new Error().stack;
+  if (!raw) return void 0;
+  const lines = raw.split("\n");
+  const kept = lines.slice(1).filter((l) => !/@shipeasy[\\/]sdk|see[\\/]core|captureCallsiteStack|\bsee\b\s*\(/.test(l));
+  return kept.length ? kept.join("\n") : void 0;
+}
+function buildSeeEvent(problem, consequence, extras, ctx, kindOverride) {
+  let errorType;
+  let message;
+  let stack;
+  let kind;
+  if (isViolation(problem)) {
+    errorType = problem.violationName;
+    message = problem.violationMessage ?? problem.violationName;
+    stack = captureCallsiteStack();
+    kind = kindOverride ?? "violation";
+  } else if (problem instanceof Error) {
+    errorType = problem.name || "Error";
+    message = problem.message || String(problem);
+    stack = problem.stack ?? void 0;
+    kind = kindOverride ?? "caught";
+  } else {
+    errorType = "Error";
+    message = typeof problem === "string" ? problem : safeString(problem);
+    stack = captureCallsiteStack();
+    kind = kindOverride ?? "caught";
+  }
+  const ev = {
+    type: "error",
+    kind,
+    error_type: truncate(errorType, SEE_MAX_SUBJECT),
+    message: truncate(message, SEE_MAX_MESSAGE),
+    subject: consequence.subject,
+    outcome: consequence.outcome,
+    side: ctx.side,
+    sdk_version: ctx.sdkVersion,
+    ts: Date.now()
+  };
+  if (stack) ev.stack = truncate(stack, SEE_MAX_STACK);
+  const causedBy = findCausedBy(problem);
+  if (causedBy) ev.caused_by = causedBy;
+  const cleanExtras = sanitizeExtras(extras);
+  if (cleanExtras) ev.extras = cleanExtras;
+  if (ctx.url) ev.url = truncate(ctx.url, SEE_MAX_SUBJECT);
+  if (ctx.userId) ev.user_id = ctx.userId;
+  if (ctx.anonId) ev.anonymous_id = ctx.anonId;
+  if (ctx.env) ev.env = ctx.env;
+  markReported(problem, ev);
+  return ev;
+}
+function safeString(v) {
+  try {
+    return typeof v === "object" ? JSON.stringify(v) : String(v);
+  } catch {
+    return String(v);
+  }
+}
+var scheduleMicrotask = typeof queueMicrotask === "function" ? queueMicrotask : (cb) => {
+  void Promise.resolve().then(cb);
+};
+function startSeeChain(getProblem, dispatch) {
+  let subject;
+  let outcome;
+  let collected;
+  let flushed = false;
+  scheduleMicrotask(() => {
+    if (flushed) return;
+    flushed = true;
+    dispatch(
+      getProblem(),
+      // Bare noun phrase — titles render as "… causes the {subject} …", so a
+      // leading article would double up ("causes the the app").
+      causesThe(subject ?? "app").to(outcome ?? "hit an error"),
+      collected
+    );
+  });
+  const tail = {
+    extras(x) {
+      if (x && typeof x === "object") collected = { ...collected, ...x };
+      return tail;
+    }
+  };
+  const step = {
+    to(o) {
+      outcome = String(o);
+      return tail;
+    }
+  };
+  const start = (s) => {
+    subject = String(s);
+    return step;
+  };
+  return { causes_the: start, causesThe: start };
+}
+function startSeeViolationChain(name, dispatch) {
+  let msg;
+  const base = startSeeChain(
+    () => msg !== void 0 ? violation(name).message(msg) : violation(name),
+    dispatch
+  );
+  const chain = {
+    ...base,
+    message(m) {
+      msg = String(m);
+      return chain;
+    }
+  };
+  return chain;
+}
+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/server/index.ts
-var version = "1.0.0";
+var version = "4.0.0";
 var C1 = 3432918353;
 var C2 = 461845907;
 function murmur3(key) {
@@ -254,6 +494,7 @@ var FlagsClient = class {
   baseUrl;
   env;
   telemetry;
+  seeLimiter = new SeeLimiter();
   flagsBlob = null;
   expsBlob = null;
   flagsEtag = null;
@@ -406,6 +647,27 @@ var FlagsClient = class {
       body
     }).catch((err) => console.warn("[shipeasy] track failed:", String(err)));
   }
+  /**
+   * Report a structured error into the errors primitive. Fire-and-forget —
+   * never blocks or throws into the request path. Spam-guarded by a 30s
+   * dedup window + per-process cap.
+   */
+  reportError(problem, consequence, extras, kind) {
+    try {
+      const ev = buildSeeEvent(problem, consequence, extras, {
+        side: "server",
+        sdkVersion: version,
+        env: this.env
+      }, kind);
+      if (!this.seeLimiter.shouldSend(ev)) return;
+      globalThis.fetch(`${this.baseUrl}/collect`, {
+        method: "POST",
+        headers: { "X-SDK-Key": this.apiKey, "Content-Type": "text/plain" },
+        body: JSON.stringify({ events: [ev] })
+      }).catch((err) => console.warn("[shipeasy] see() send failed:", String(err)));
+    } catch {
+    }
+  }
   /**
    * Evaluate all flags, configs, and experiments for a user against the locally
    * cached blob (no network call). Applies ?se_ks_* / ?se_cf_* / ?se_exp_*
@@ -714,6 +976,20 @@ var flags = {
     };
   }
 };
+function dispatchSee(problem, consequence, extras, kind) {
+  if (!_server) {
+    console.warn("[shipeasy] see() called before shipeasy({ serverKey }) \u2014 error dropped");
+    return;
+  }
+  _server.reportError(problem, consequence, extras, kind);
+}
+var see = Object.assign(
+  (problem) => startSeeChain(() => problem, dispatchSee),
+  {
+    Violation: (name) => startSeeViolationChain(name, dispatchSee),
+    ControlFlowException: markExpected
+  }
+);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FlagsClient,
@@ -724,6 +1000,7 @@ var flags = {
   getBootstrapHtml,
   getShipeasyServerClient,
   i18n,
+  see,
   shipeasy,
   version
 });