@shipeasy/sdk 3.1.0 → 4.1.0

package/dist/client/index.mjs

@@ -57,8 +57,208 @@ 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 {
+  }
+}
+function isExpected(err) {
+  if (typeof err !== "object" || err === null) return false;
+  return err[EXPECTED_SYM] !== void 0;
+}
+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 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;
+  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(),
+      causesThe(subject ?? "the 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/client/index.ts
-var version = "1.0.0";
+var version = "4.0.0";
 var FLUSH_INTERVAL_MS = 5e3;
 var MAX_BUFFER = 100;
 var ANON_ID_KEY = "__se_anon_id";
@@ -92,6 +292,13 @@ var EventBuffer = class {
       this.timer = null;
     }
   }
+  /** True once this visitor has been exposed to ≥1 experiment (this tab or a
+   *  prior page in the session — the dedup set persists in sessionStorage).
+   *  Gates auto-metric emission: vitals from non-participants are never read
+   *  by the analysis pipeline and would be pure AE write cost (see cost.md). */
+  hasExposures() {
+    return this.exposureSeen.size > 0;
+  }
   pushExposure(experiment, group, userId, anonId) {
     const key = `${userId || anonId}:${experiment}`;
     if (this.exposureSeen.has(key)) return;
@@ -157,16 +364,29 @@ var EventBuffer = class {
   flush(useBeacon = false) {
     if (!this.queue.length) return;
     const batch = this.queue.splice(0);
-    const body = JSON.stringify({ events: batch });
+    this.send(batch, useBeacon);
+  }
+  /**
+   * Bypass the 5s queue and ship events immediately — used by see() error
+   * reporting so occurrences land near-real-time and survive page unload.
+   * Beacon-first (fire-and-forget, unload-safe), keepalive fetch fallback.
+   */
+  sendNow(events) {
+    this.send(events, true);
+  }
+  send(batch, useBeacon) {
     if (useBeacon && typeof navigator !== "undefined" && navigator.sendBeacon) {
       const beaconBody = JSON.stringify({ k: this.sdkKey, events: batch });
-      navigator.sendBeacon(this.collectUrl, new Blob([beaconBody], { type: "text/plain" }));
-      return;
+      try {
+        if (navigator.sendBeacon(this.collectUrl, new Blob([beaconBody], { type: "text/plain" })))
+          return;
+      } catch {
+      }
     }
     fetch(this.collectUrl, {
       method: "POST",
       headers: { "X-SDK-Key": this.sdkKey, "Content-Type": "application/json" },
-      body,
+      body: JSON.stringify({ events: batch }),
       keepalive: true
     }).catch(() => {
     });
@@ -183,14 +403,12 @@ var EventBuffer = class {
     });
   }
 };
-var MAX_ERRORS_PER_SESSION = 5;
-function installAutoGuardrails(buffer, userId, anonId, groups) {
+function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignoreUrlPrefixes, always = false) {
   if (typeof window === "undefined" || typeof PerformanceObserver === "undefined") return;
+  const shouldEmit = () => always || buffer.hasExposures();
   let lcp = null;
   let inp = null;
   let clsBad = false;
-  let jsErrorCount = 0;
-  let netErrorCount = 0;
   let navTimingFlushed = false;
   if (groups.vitals) {
     try {
@@ -229,68 +447,71 @@ function installAutoGuardrails(buffer, userId, anonId, groups) {
   if (groups.errors) {
     const origOnError = window.onerror;
     window.onerror = (msg, source, lineno, _colno, err) => {
-      if (jsErrorCount < MAX_ERRORS_PER_SESSION) {
-        jsErrorCount += 1;
-        buffer.pushMetric("__auto_js_error", userId, anonId, {
-          value: 1,
-          kind: "exception",
-          message: typeof msg === "string" ? msg.slice(0, 200) : String(err ?? "").slice(0, 200),
-          source: typeof source === "string" ? source.slice(0, 200) : "",
-          line: lineno ?? 0
-        });
+      if (!isExpected(err)) {
+        const problem = err ?? (typeof msg === "string" && msg ? msg : "Unknown error");
+        reportSee(
+          problem,
+          causesThe("the page").to("hit an unhandled error"),
+          {
+            source: typeof source === "string" ? source : void 0,
+            line: lineno ?? void 0
+          },
+          "uncaught"
+        );
       }
       if (typeof origOnError === "function") return origOnError(msg, source, lineno, _colno, err);
       return false;
     };
     window.addEventListener("unhandledrejection", (e) => {
-      if (jsErrorCount < MAX_ERRORS_PER_SESSION) {
-        jsErrorCount += 1;
-        const reason = e.reason;
-        const message = reason instanceof Error ? reason.message : typeof reason === "string" ? reason : String(reason);
-        buffer.pushMetric("__auto_js_error", userId, anonId, {
-          value: 1,
-          kind: "unhandled_rejection",
-          message: message.slice(0, 200)
-        });
-      }
+      const reason = e.reason;
+      if (isExpected(reason)) return;
+      reportSee(
+        reason ?? "Unhandled promise rejection",
+        causesThe("the page").to("hit an unhandled promise rejection"),
+        void 0,
+        "unhandled_rejection"
+      );
     });
     const origFetch = window.fetch;
     window.fetch = async function(...args) {
       const startedAt = typeof performance !== "undefined" ? performance.now() : 0;
       const url = typeof args[0] === "string" ? args[0] : args[0].toString();
+      const ignored = ignoreUrlPrefixes.some((p) => p && url.startsWith(p));
+      const bareUrl = url.split("?")[0].slice(0, 200);
       let res;
       try {
         res = await origFetch.apply(this, args);
       } catch (err) {
-        if (netErrorCount < MAX_ERRORS_PER_SESSION) {
-          netErrorCount += 1;
-          buffer.pushMetric("__auto_network_error", userId, anonId, {
-            value: 1,
-            kind: "network",
-            status: 0,
-            url: url.slice(0, 200)
-          });
+        if (!ignored && !isExpected(err)) {
+          reportSee(
+            violation("NetworkError").message(`request to ${bareUrl} failed`),
+            causesThe("a network request").to("fail without a response"),
+            { status: 0, url: url.slice(0, 200) },
+            "network"
+          );
         }
         throw err;
       }
-      if (res.status >= 500 && netErrorCount < MAX_ERRORS_PER_SESSION) {
-        netErrorCount += 1;
+      if (!ignored && res.status >= 500) {
         const elapsed = typeof performance !== "undefined" ? performance.now() - startedAt : 0;
-        buffer.pushMetric("__auto_network_error", userId, anonId, {
-          value: 1,
-          kind: "5xx",
-          status: res.status,
-          url: url.slice(0, 200),
-          duration_ms: Math.round(elapsed)
-        });
+        reportSee(
+          violation("Http5xx").message(`request to ${bareUrl} returned ${res.status}`),
+          causesThe("a network request").to(`fail with HTTP ${res.status}`),
+          { status: res.status, url: url.slice(0, 200), duration_ms: Math.round(elapsed) },
+          "network"
+        );
       }
       return res;
     };
   }
   const flushNavTiming = () => {
     if (navTimingFlushed) return;
+    if (!groups.vitals) {
+      navTimingFlushed = true;
+      return;
+    }
+    if (!shouldEmit()) return;
     navTimingFlushed = true;
-    if (!groups.vitals) return;
     try {
       const navList = performance.getEntriesByType("navigation");
       const nav = navList[0];
@@ -325,7 +546,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups) {
   };
   if (groups.engagement) {
     try {
-      buffer.pushMetric("__auto_session_active", userId, anonId, { value: 1 });
+      if (shouldEmit()) buffer.pushMetric("__auto_session_active", userId, anonId, { value: 1 });
     } catch {
     }
     let lastEmit = Date.now();
@@ -333,6 +554,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups) {
     document.addEventListener("visibilitychange", () => {
       if (document.visibilityState !== "visible") return;
       if (Date.now() - lastEmit < SESSION_GAP_MS) return;
+      if (!shouldEmit()) return;
       try {
         buffer.pushMetric("__auto_session_active", userId, anonId, { value: 1 });
         lastEmit = Date.now();
@@ -355,7 +577,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups) {
     }
     const flushOnHide = () => {
       flushNavTiming();
-      if (groups.vitals) {
+      if (groups.vitals && shouldEmit()) {
         if (lcp !== null) buffer.pushMetric("__auto_lcp", userId, anonId, { value: lcp });
         if (inp !== null) buffer.pushMetric("__auto_inp", userId, anonId, { value: inp });
         if (clsBad) buffer.pushMetric("__auto_cls_binary", userId, anonId, { value: 1 });
@@ -438,12 +660,14 @@ var FlagsClientBrowser = class {
   baseUrl;
   autoGuardrails;
   autoGuardrailGroups;
+  autoCollectAlways;
   env;
   evalResult = null;
   anonId;
   userId = "";
   buffer;
   telemetry;
+  seeLimiter = new SeeLimiter();
   guardrailsInstalled = false;
   listeners = /* @__PURE__ */ new Set();
   overrideListenerInstalled = false;
@@ -459,6 +683,7 @@ var FlagsClientBrowser = class {
     this.baseUrl = (opts.baseUrl ?? "https://edge.shipeasy.dev").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
     this.autoGuardrails = opts.autoGuardrails !== false;
+    this.autoCollectAlways = opts.autoCollectAlways === true;
     const g = opts.autoGuardrailGroups ?? {};
     this.autoGuardrailGroups = {
       vitals: g.vitals ?? this.autoGuardrails,
@@ -503,10 +728,38 @@ var FlagsClientBrowser = class {
     const anyGroupOn = this.autoGuardrailGroups.vitals || this.autoGuardrailGroups.errors || this.autoGuardrailGroups.engagement;
     if (anyGroupOn && !this.guardrailsInstalled) {
       this.guardrailsInstalled = true;
-      installAutoGuardrails(this.buffer, this.userId, this.anonId, this.autoGuardrailGroups);
+      installAutoGuardrails(
+        this.buffer,
+        this.userId,
+        this.anonId,
+        this.autoGuardrailGroups,
+        (problem, consequence, extras, kind) => this.reportError(problem, consequence, extras, kind),
+        [`${this.baseUrl}/`, DEFAULT_TELEMETRY_URL],
+        this.autoCollectAlways
+      );
     }
     this.notify();
   }
+  /**
+   * Report a structured error into the errors primitive. Flushes immediately
+   * (beacon-first) — error occurrences are near-real-time, never queued behind
+   * the 5s metric batch. Spam-guarded by a 30s dedup window + per-session cap.
+   */
+  reportError(problem, consequence, extras, kind) {
+    try {
+      const ev = buildSeeEvent(problem, consequence, extras, {
+        side: "client",
+        sdkVersion: version,
+        env: this.env,
+        url: typeof window !== "undefined" && window.location ? window.location.href : void 0,
+        userId: this.userId || void 0,
+        anonId: this.anonId
+      }, kind);
+      if (!this.seeLimiter.shouldSend(ev)) return;
+      this.buffer.sendNow([ev]);
+    } catch {
+    }
+  }
   get ready() {
     return this.evalResult !== null;
   }
@@ -738,13 +991,15 @@ var _client = null;
 function shipeasy(opts) {
   const ac = opts.autoCollect;
   const blanket = ac === false ? false : true;
-  const groups = ac && typeof ac === "object" ? ac : void 0;
+  const acObj = ac && typeof ac === "object" ? ac : void 0;
+  const groups = acObj ? { vitals: acObj.vitals, errors: acObj.errors, engagement: acObj.engagement } : void 0;
   const baseUrl = opts.baseUrl ?? "https://cdn.shipeasy.ai";
   const client = configureShipeasy({
     sdkKey: opts.clientKey,
     baseUrl,
     autoGuardrails: blanket,
     autoGuardrailGroups: groups,
+    autoCollectAlways: acObj?.always === true,
     disableTelemetry: opts.disableTelemetry
   });
   injectI18nLoader(opts.clientKey, baseUrl, opts.i18nProfile);
@@ -906,6 +1161,20 @@ var flags = {
     return _client?.ready ?? false;
   }
 };
+function dispatchSee(problem, consequence, extras, kind) {
+  if (!_client) {
+    console.warn("[shipeasy] see() called before shipeasy({ clientKey }) \u2014 error dropped");
+    return;
+  }
+  _client.reportError(problem, consequence, extras, kind);
+}
+var see = Object.assign(
+  (problem) => startSeeChain(() => problem, dispatchSee),
+  {
+    Violation: (name) => startSeeViolationChain(name, dispatchSee),
+    ControlFlowException: markExpected
+  }
+);
 var LABEL_MARKER_START = "\uFFF9";
 var LABEL_MARKER_SEP = "\uFFFA";
 var LABEL_MARKER_END = "\uFFFB";
@@ -1157,6 +1426,7 @@ export {
   readConfigOverride,
   readExpOverride,
   readGateOverride,
+  see,
   shipeasy,
   version
 };

package/dist/server/index.d.mts

@@ -1,4 +1,63 @@
-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;
+}
+/** 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;
+}
+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 +127,7 @@ declare class FlagsClient {
     private readonly baseUrl;
     private readonly env;
     private readonly telemetry;
+    private readonly seeLimiter;
     private flagsBlob;
     private expsBlob;
     private flagsEtag;
@@ -87,6 +147,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 +295,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 };