@shipeasy/sdk 4.1.0 → 4.3.0

package/dist/client/index.d.mts

@@ -18,6 +18,20 @@ interface Violation {
     /** 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";
@@ -37,6 +51,24 @@ interface SeeErrorEvent {
     env?: string;
     sdk_version: string;
     ts: number;
+    /**
+     * Per-request correlation token. The client mints one per same-origin fetch
+     * and ships it on both the request header (`X-SE-Correlation`) and any 5xx
+     * occurrence it reports; the server safety net reports the matching uncaught
+     * error under the same token. The backend joins the two issues by it —
+     * populating `caused_by` across the network boundary, where the in-process
+     * `.cause`-chain stamp (see `findCausedBy`) cannot reach. Join-only metadata,
+     * never persisted as an issue field.
+     */
+    correlation_id?: string;
+    /**
+     * 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. */
@@ -98,6 +130,15 @@ interface AutoCollectGroups {
     errors: boolean;
     engagement: boolean;
 }
+/** True when `rawUrl` resolves to the page's own origin (relative URLs included). */
+declare function sameOrigin(rawUrl: string): boolean;
+/**
+ * Return a new `fetch` args tuple with `X-SE-Correlation` added, preserving any
+ * existing headers across all three arg shapes (string / URL / Request). Never
+ * mutates the caller's objects. Best-effort: on any failure the original args
+ * pass through unchanged (correlation is optional, never breaks the fetch).
+ */
+declare function injectCorrelationHeader(args: Parameters<typeof fetch>, corr: string): Parameters<typeof fetch>;
 type FlagsClientBrowserEnv = "dev" | "staging" | "prod";
 interface FlagsClientBrowserOptions {
     sdkKey: string;
@@ -154,7 +195,7 @@ declare class FlagsClientBrowser {
      * (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: unknown, consequence: Consequence, extras?: SeeExtras, kind?: SeeKind): void;
+    reportError(problem: unknown, consequence: Consequence, extras?: SeeExtras, kind?: SeeKind, correlationId?: string): void;
     get ready(): boolean;
     private notify;
     initFromBootstrap(data: EvalResponse): void;
@@ -456,4 +497,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, 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 SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, see, shipeasy, version };
+export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, 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 SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };

package/dist/client/index.d.ts

@@ -18,6 +18,20 @@ interface Violation {
     /** 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";
@@ -37,6 +51,24 @@ interface SeeErrorEvent {
     env?: string;
     sdk_version: string;
     ts: number;
+    /**
+     * Per-request correlation token. The client mints one per same-origin fetch
+     * and ships it on both the request header (`X-SE-Correlation`) and any 5xx
+     * occurrence it reports; the server safety net reports the matching uncaught
+     * error under the same token. The backend joins the two issues by it —
+     * populating `caused_by` across the network boundary, where the in-process
+     * `.cause`-chain stamp (see `findCausedBy`) cannot reach. Join-only metadata,
+     * never persisted as an issue field.
+     */
+    correlation_id?: string;
+    /**
+     * 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. */
@@ -98,6 +130,15 @@ interface AutoCollectGroups {
     errors: boolean;
     engagement: boolean;
 }
+/** True when `rawUrl` resolves to the page's own origin (relative URLs included). */
+declare function sameOrigin(rawUrl: string): boolean;
+/**
+ * Return a new `fetch` args tuple with `X-SE-Correlation` added, preserving any
+ * existing headers across all three arg shapes (string / URL / Request). Never
+ * mutates the caller's objects. Best-effort: on any failure the original args
+ * pass through unchanged (correlation is optional, never breaks the fetch).
+ */
+declare function injectCorrelationHeader(args: Parameters<typeof fetch>, corr: string): Parameters<typeof fetch>;
 type FlagsClientBrowserEnv = "dev" | "staging" | "prod";
 interface FlagsClientBrowserOptions {
     sdkKey: string;
@@ -154,7 +195,7 @@ declare class FlagsClientBrowser {
      * (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: unknown, consequence: Consequence, extras?: SeeExtras, kind?: SeeKind): void;
+    reportError(problem: unknown, consequence: Consequence, extras?: SeeExtras, kind?: SeeKind, correlationId?: string): void;
     get ready(): boolean;
     private notify;
     initFromBootstrap(data: EvalResponse): void;
@@ -456,4 +497,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, 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 SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, see, shipeasy, version };
+export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, 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 SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };

package/dist/client/index.js

@@ -32,12 +32,14 @@ __export(client_exports, {
   flags: () => flags,
   getShipeasyClient: () => getShipeasyClient,
   i18n: () => i18n,
+  injectCorrelationHeader: () => injectCorrelationHeader,
   isDevtoolsRequested: () => isDevtoolsRequested,
   labelAttrs: () => labelAttrs,
   loadDevtools: () => loadDevtools,
   readConfigOverride: () => readConfigOverride,
   readExpOverride: () => readExpOverride,
   readGateOverride: () => readGateOverride,
+  sameOrigin: () => sameOrigin,
   see: () => see,
   shipeasy: () => shipeasy,
   version: () => version
@@ -109,6 +111,7 @@ var SEE_MAX_STACK = 8e3;
 var SEE_MAX_SUBJECT = 200;
 var SEE_MAX_EXTRA_VALUE = 200;
 var SEE_MAX_EXTRA_KEYS = 20;
+var SEE_MAX_CORRELATION = 64;
 var SEE_DEDUP_WINDOW_MS = 3e4;
 var SEE_MAX_PER_SESSION = 25;
 function causesThe(subject) {
@@ -152,6 +155,44 @@ function isExpected(err) {
   if (typeof err !== "object" || err === null) return false;
   return err[EXPECTED_SYM] !== void 0;
 }
+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;
 }
@@ -177,7 +218,7 @@ function captureCallsiteStack() {
   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) {
+function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlationId) {
   let errorType;
   let message;
   let stack;
@@ -210,12 +251,16 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride) {
     ts: Date.now()
   };
   if (stack) ev.stack = truncate(stack, SEE_MAX_STACK);
+  if (correlationId) ev.correlation_id = truncate(String(correlationId), SEE_MAX_CORRELATION);
+  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) {
@@ -238,7 +283,9 @@ function startSeeChain(getProblem, dispatch) {
     flushed = true;
     dispatch(
       getProblem(),
-      causesThe(subject ?? "the app").to(outcome ?? "hit an error"),
+      // 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
     );
   });
@@ -449,6 +496,43 @@ var EventBuffer = class {
     });
   }
 };
+function endpointTemplate(rawUrl) {
+  const isIdSegment = (seg) => /^\d+$/.test(seg) || /^0x[0-9a-f]+$/i.test(seg) || /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(seg) || /^[0-9a-f]{8,}$/i.test(seg) || seg.length >= 12 && /\d/.test(seg) && /[a-z]/i.test(seg);
+  let u;
+  try {
+    u = new URL(rawUrl, typeof location !== "undefined" ? location.href : void 0);
+  } catch {
+    return (rawUrl.split(/[?#]/)[0] ?? "").slice(0, 120);
+  }
+  const path = u.pathname.split("/").map((seg) => seg && isIdSegment(seg) ? ":id" : seg).join("/");
+  const sameOrigin2 = typeof location !== "undefined" && u.origin === location.origin;
+  return ((sameOrigin2 ? "" : u.host) + path).slice(0, 120);
+}
+function sameOrigin(rawUrl) {
+  if (typeof location === "undefined") return false;
+  try {
+    return new URL(rawUrl, location.href).origin === location.origin;
+  } catch {
+    return false;
+  }
+}
+function injectCorrelationHeader(args, corr) {
+  try {
+    const input = args[0];
+    if (typeof Request !== "undefined" && input instanceof Request) {
+      const headers2 = new Headers(input.headers);
+      headers2.set("X-SE-Correlation", corr);
+      return [new Request(input, { headers: headers2 }), ...args.slice(1)];
+    }
+    const init = { ...args[1] ?? {} };
+    const headers = new Headers(init.headers ?? void 0);
+    headers.set("X-SE-Correlation", corr);
+    init.headers = headers;
+    return [input, init];
+  } catch {
+    return args;
+  }
+}
 function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignoreUrlPrefixes, always = false) {
   if (typeof window === "undefined" || typeof PerformanceObserver === "undefined") return;
   const shouldEmit = () => always || buffer.hasExposures();
@@ -497,7 +581,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
         const problem = err ?? (typeof msg === "string" && msg ? msg : "Unknown error");
         reportSee(
           problem,
-          causesThe("the page").to("hit an unhandled error"),
+          causesThe("page").to("hit an unhandled error"),
           {
             source: typeof source === "string" ? source : void 0,
             line: lineno ?? void 0
@@ -513,7 +597,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
       if (isExpected(reason)) return;
       reportSee(
         reason ?? "Unhandled promise rejection",
-        causesThe("the page").to("hit an unhandled promise rejection"),
+        causesThe("page").to("hit an unhandled promise rejection"),
         void 0,
         "unhandled_rejection"
       );
@@ -524,6 +608,11 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
       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 corr;
+      if (!ignored && sameOrigin(url) && typeof crypto !== "undefined" && crypto.randomUUID) {
+        corr = crypto.randomUUID();
+        args = injectCorrelationHeader(args, corr);
+      }
       let res;
       try {
         res = await origFetch.apply(this, args);
@@ -531,7 +620,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
         if (!ignored && !isExpected(err)) {
           reportSee(
             violation("NetworkError").message(`request to ${bareUrl} failed`),
-            causesThe("a network request").to("fail without a response"),
+            causesThe(`request to ${endpointTemplate(url)}`).to("get no response"),
             { status: 0, url: url.slice(0, 200) },
             "network"
           );
@@ -542,9 +631,10 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
         const elapsed = typeof performance !== "undefined" ? performance.now() - startedAt : 0;
         reportSee(
           violation("Http5xx").message(`request to ${bareUrl} returned ${res.status}`),
-          causesThe("a network request").to(`fail with HTTP ${res.status}`),
+          causesThe(`request to ${endpointTemplate(url)}`).to("fail with a server error"),
           { status: res.status, url: url.slice(0, 200), duration_ms: Math.round(elapsed) },
-          "network"
+          "network",
+          corr
         );
       }
       return res;
@@ -687,6 +777,83 @@ function collectBrowserAttrs() {
   }
   return attrs;
 }
+function collectSeeEnv() {
+  const out = {};
+  if (typeof navigator === "undefined") return out;
+  const nav = navigator;
+  const ua = typeof nav.userAgent === "string" ? nav.userAgent : "";
+  const browser = parseUaBrowser(ua);
+  if (browser) out["env.browser"] = browser;
+  const os = parseUaOs(ua) ?? nav.userAgentData?.platform;
+  if (os) out["env.os"] = os;
+  out["env.device"] = typeof nav.userAgentData?.mobile === "boolean" ? nav.userAgentData.mobile ? "mobile" : "desktop" : /iPad|Tablet/.test(ua) ? "tablet" : /Mobi|iPhone|Android.*Mobile/.test(ua) ? "mobile" : "desktop";
+  try {
+    if (nav.language) out["env.lang"] = nav.language;
+  } catch {
+  }
+  try {
+    if (typeof nav.onLine === "boolean") out["env.online"] = nav.onLine;
+  } catch {
+  }
+  try {
+    if (typeof nav.hardwareConcurrency === "number") out["env.cores"] = nav.hardwareConcurrency;
+  } catch {
+  }
+  try {
+    if (typeof nav.deviceMemory === "number") out["env.memory_gb"] = nav.deviceMemory;
+  } catch {
+  }
+  try {
+    const et = nav.connection?.effectiveType;
+    if (et) out["env.connection"] = et;
+  } catch {
+  }
+  try {
+    if (typeof window !== "undefined" && window.innerWidth && window.innerHeight) {
+      out["env.viewport"] = `${window.innerWidth}\xD7${window.innerHeight}`;
+    }
+    if (typeof window !== "undefined" && typeof window.devicePixelRatio === "number") {
+      out["env.dpr"] = window.devicePixelRatio;
+    }
+    if (typeof screen !== "undefined" && screen.width && screen.height) {
+      out["env.screen"] = `${screen.width}\xD7${screen.height}`;
+    }
+  } catch {
+  }
+  try {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    if (tz) out["env.tz"] = tz;
+  } catch {
+  }
+  return out;
+}
+function parseUaBrowser(ua) {
+  const tests = [
+    [/Edg(?:A|iOS)?\/(\d+)/, "Edge"],
+    [/(?:OPR|Opera)\/(\d+)/, "Opera"],
+    [/(?:Firefox|FxiOS)\/(\d+)/, "Firefox"],
+    [/(?:Chrome|CriOS)\/(\d+)/, "Chrome"],
+    [/Version\/(\d+)[.\d]* (?:Mobile.*)?Safari/, "Safari"]
+  ];
+  for (const [re, name] of tests) {
+    const m = re.exec(ua);
+    if (m) return `${name} ${m[1]}`;
+  }
+  return void 0;
+}
+function parseUaOs(ua) {
+  if (/Windows NT 10/.test(ua)) return "Windows 10/11";
+  if (/Windows NT/.test(ua)) return "Windows";
+  let m = /Mac OS X (\d+)[._](\d+)/.exec(ua);
+  if (m) return `macOS ${m[1]}.${m[2]}`;
+  if (/Macintosh/.test(ua)) return "macOS";
+  m = /Android (\d+)/.exec(ua);
+  if (m) return `Android ${m[1]}`;
+  m = /(?:iPhone|iPad)[^)]* OS (\d+)/.exec(ua);
+  if (m) return `iOS ${m[1]}`;
+  if (/Linux/.test(ua)) return "Linux";
+  return void 0;
+}
 function readExperimentOverridesFromUrl() {
   if (typeof window === "undefined") return {};
   const out = {};
@@ -779,7 +946,7 @@ var FlagsClientBrowser = class {
         this.userId,
         this.anonId,
         this.autoGuardrailGroups,
-        (problem, consequence, extras, kind) => this.reportError(problem, consequence, extras, kind),
+        (problem, consequence, extras, kind, correlationId) => this.reportError(problem, consequence, extras, kind, correlationId),
         [`${this.baseUrl}/`, DEFAULT_TELEMETRY_URL],
         this.autoCollectAlways
       );
@@ -791,16 +958,17 @@ var FlagsClientBrowser = class {
    * (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) {
+  reportError(problem, consequence, extras, kind, correlationId) {
     try {
-      const ev = buildSeeEvent(problem, consequence, extras, {
+      const enriched = { ...collectSeeEnv(), ...extras };
+      const ev = buildSeeEvent(problem, consequence, enriched, {
         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);
+      }, kind, correlationId);
       if (!this.seeLimiter.shouldSend(ev)) return;
       this.buffer.sendNow([ev]);
     } catch {
@@ -1467,12 +1635,14 @@ var i18n = {
   flags,
   getShipeasyClient,
   i18n,
+  injectCorrelationHeader,
   isDevtoolsRequested,
   labelAttrs,
   loadDevtools,
   readConfigOverride,
   readExpOverride,
   readGateOverride,
+  sameOrigin,
   see,
   shipeasy,
   version

package/dist/client/index.mjs

@@ -63,6 +63,7 @@ var SEE_MAX_STACK = 8e3;
 var SEE_MAX_SUBJECT = 200;
 var SEE_MAX_EXTRA_VALUE = 200;
 var SEE_MAX_EXTRA_KEYS = 20;
+var SEE_MAX_CORRELATION = 64;
 var SEE_DEDUP_WINDOW_MS = 3e4;
 var SEE_MAX_PER_SESSION = 25;
 function causesThe(subject) {
@@ -106,6 +107,44 @@ function isExpected(err) {
   if (typeof err !== "object" || err === null) return false;
   return err[EXPECTED_SYM] !== void 0;
 }
+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;
 }
@@ -131,7 +170,7 @@ function captureCallsiteStack() {
   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) {
+function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlationId) {
   let errorType;
   let message;
   let stack;
@@ -164,12 +203,16 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride) {
     ts: Date.now()
   };
   if (stack) ev.stack = truncate(stack, SEE_MAX_STACK);
+  if (correlationId) ev.correlation_id = truncate(String(correlationId), SEE_MAX_CORRELATION);
+  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) {
@@ -192,7 +235,9 @@ function startSeeChain(getProblem, dispatch) {
     flushed = true;
     dispatch(
       getProblem(),
-      causesThe(subject ?? "the app").to(outcome ?? "hit an error"),
+      // 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
     );
   });
@@ -403,6 +448,43 @@ var EventBuffer = class {
     });
   }
 };
+function endpointTemplate(rawUrl) {
+  const isIdSegment = (seg) => /^\d+$/.test(seg) || /^0x[0-9a-f]+$/i.test(seg) || /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(seg) || /^[0-9a-f]{8,}$/i.test(seg) || seg.length >= 12 && /\d/.test(seg) && /[a-z]/i.test(seg);
+  let u;
+  try {
+    u = new URL(rawUrl, typeof location !== "undefined" ? location.href : void 0);
+  } catch {
+    return (rawUrl.split(/[?#]/)[0] ?? "").slice(0, 120);
+  }
+  const path = u.pathname.split("/").map((seg) => seg && isIdSegment(seg) ? ":id" : seg).join("/");
+  const sameOrigin2 = typeof location !== "undefined" && u.origin === location.origin;
+  return ((sameOrigin2 ? "" : u.host) + path).slice(0, 120);
+}
+function sameOrigin(rawUrl) {
+  if (typeof location === "undefined") return false;
+  try {
+    return new URL(rawUrl, location.href).origin === location.origin;
+  } catch {
+    return false;
+  }
+}
+function injectCorrelationHeader(args, corr) {
+  try {
+    const input = args[0];
+    if (typeof Request !== "undefined" && input instanceof Request) {
+      const headers2 = new Headers(input.headers);
+      headers2.set("X-SE-Correlation", corr);
+      return [new Request(input, { headers: headers2 }), ...args.slice(1)];
+    }
+    const init = { ...args[1] ?? {} };
+    const headers = new Headers(init.headers ?? void 0);
+    headers.set("X-SE-Correlation", corr);
+    init.headers = headers;
+    return [input, init];
+  } catch {
+    return args;
+  }
+}
 function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignoreUrlPrefixes, always = false) {
   if (typeof window === "undefined" || typeof PerformanceObserver === "undefined") return;
   const shouldEmit = () => always || buffer.hasExposures();
@@ -451,7 +533,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
         const problem = err ?? (typeof msg === "string" && msg ? msg : "Unknown error");
         reportSee(
           problem,
-          causesThe("the page").to("hit an unhandled error"),
+          causesThe("page").to("hit an unhandled error"),
           {
             source: typeof source === "string" ? source : void 0,
             line: lineno ?? void 0
@@ -467,7 +549,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
       if (isExpected(reason)) return;
       reportSee(
         reason ?? "Unhandled promise rejection",
-        causesThe("the page").to("hit an unhandled promise rejection"),
+        causesThe("page").to("hit an unhandled promise rejection"),
         void 0,
         "unhandled_rejection"
       );
@@ -478,6 +560,11 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
       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 corr;
+      if (!ignored && sameOrigin(url) && typeof crypto !== "undefined" && crypto.randomUUID) {
+        corr = crypto.randomUUID();
+        args = injectCorrelationHeader(args, corr);
+      }
       let res;
       try {
         res = await origFetch.apply(this, args);
@@ -485,7 +572,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
         if (!ignored && !isExpected(err)) {
           reportSee(
             violation("NetworkError").message(`request to ${bareUrl} failed`),
-            causesThe("a network request").to("fail without a response"),
+            causesThe(`request to ${endpointTemplate(url)}`).to("get no response"),
             { status: 0, url: url.slice(0, 200) },
             "network"
           );
@@ -496,9 +583,10 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
         const elapsed = typeof performance !== "undefined" ? performance.now() - startedAt : 0;
         reportSee(
           violation("Http5xx").message(`request to ${bareUrl} returned ${res.status}`),
-          causesThe("a network request").to(`fail with HTTP ${res.status}`),
+          causesThe(`request to ${endpointTemplate(url)}`).to("fail with a server error"),
           { status: res.status, url: url.slice(0, 200), duration_ms: Math.round(elapsed) },
-          "network"
+          "network",
+          corr
         );
       }
       return res;
@@ -641,6 +729,83 @@ function collectBrowserAttrs() {
   }
   return attrs;
 }
+function collectSeeEnv() {
+  const out = {};
+  if (typeof navigator === "undefined") return out;
+  const nav = navigator;
+  const ua = typeof nav.userAgent === "string" ? nav.userAgent : "";
+  const browser = parseUaBrowser(ua);
+  if (browser) out["env.browser"] = browser;
+  const os = parseUaOs(ua) ?? nav.userAgentData?.platform;
+  if (os) out["env.os"] = os;
+  out["env.device"] = typeof nav.userAgentData?.mobile === "boolean" ? nav.userAgentData.mobile ? "mobile" : "desktop" : /iPad|Tablet/.test(ua) ? "tablet" : /Mobi|iPhone|Android.*Mobile/.test(ua) ? "mobile" : "desktop";
+  try {
+    if (nav.language) out["env.lang"] = nav.language;
+  } catch {
+  }
+  try {
+    if (typeof nav.onLine === "boolean") out["env.online"] = nav.onLine;
+  } catch {
+  }
+  try {
+    if (typeof nav.hardwareConcurrency === "number") out["env.cores"] = nav.hardwareConcurrency;
+  } catch {
+  }
+  try {
+    if (typeof nav.deviceMemory === "number") out["env.memory_gb"] = nav.deviceMemory;
+  } catch {
+  }
+  try {
+    const et = nav.connection?.effectiveType;
+    if (et) out["env.connection"] = et;
+  } catch {
+  }
+  try {
+    if (typeof window !== "undefined" && window.innerWidth && window.innerHeight) {
+      out["env.viewport"] = `${window.innerWidth}\xD7${window.innerHeight}`;
+    }
+    if (typeof window !== "undefined" && typeof window.devicePixelRatio === "number") {
+      out["env.dpr"] = window.devicePixelRatio;
+    }
+    if (typeof screen !== "undefined" && screen.width && screen.height) {
+      out["env.screen"] = `${screen.width}\xD7${screen.height}`;
+    }
+  } catch {
+  }
+  try {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    if (tz) out["env.tz"] = tz;
+  } catch {
+  }
+  return out;
+}
+function parseUaBrowser(ua) {
+  const tests = [
+    [/Edg(?:A|iOS)?\/(\d+)/, "Edge"],
+    [/(?:OPR|Opera)\/(\d+)/, "Opera"],
+    [/(?:Firefox|FxiOS)\/(\d+)/, "Firefox"],
+    [/(?:Chrome|CriOS)\/(\d+)/, "Chrome"],
+    [/Version\/(\d+)[.\d]* (?:Mobile.*)?Safari/, "Safari"]
+  ];
+  for (const [re, name] of tests) {
+    const m = re.exec(ua);
+    if (m) return `${name} ${m[1]}`;
+  }
+  return void 0;
+}
+function parseUaOs(ua) {
+  if (/Windows NT 10/.test(ua)) return "Windows 10/11";
+  if (/Windows NT/.test(ua)) return "Windows";
+  let m = /Mac OS X (\d+)[._](\d+)/.exec(ua);
+  if (m) return `macOS ${m[1]}.${m[2]}`;
+  if (/Macintosh/.test(ua)) return "macOS";
+  m = /Android (\d+)/.exec(ua);
+  if (m) return `Android ${m[1]}`;
+  m = /(?:iPhone|iPad)[^)]* OS (\d+)/.exec(ua);
+  if (m) return `iOS ${m[1]}`;
+  if (/Linux/.test(ua)) return "Linux";
+  return void 0;
+}
 function readExperimentOverridesFromUrl() {
   if (typeof window === "undefined") return {};
   const out = {};
@@ -733,7 +898,7 @@ var FlagsClientBrowser = class {
         this.userId,
         this.anonId,
         this.autoGuardrailGroups,
-        (problem, consequence, extras, kind) => this.reportError(problem, consequence, extras, kind),
+        (problem, consequence, extras, kind, correlationId) => this.reportError(problem, consequence, extras, kind, correlationId),
         [`${this.baseUrl}/`, DEFAULT_TELEMETRY_URL],
         this.autoCollectAlways
       );
@@ -745,16 +910,17 @@ var FlagsClientBrowser = class {
    * (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) {
+  reportError(problem, consequence, extras, kind, correlationId) {
     try {
-      const ev = buildSeeEvent(problem, consequence, extras, {
+      const enriched = { ...collectSeeEnv(), ...extras };
+      const ev = buildSeeEvent(problem, consequence, enriched, {
         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);
+      }, kind, correlationId);
       if (!this.seeLimiter.shouldSend(ev)) return;
       this.buffer.sendNow([ev]);
     } catch {
@@ -1420,12 +1586,14 @@ export {
   flags,
   getShipeasyClient,
   i18n,
+  injectCorrelationHeader,
   isDevtoolsRequested,
   labelAttrs,
   loadDevtools,
   readConfigOverride,
   readExpOverride,
   readGateOverride,
+  sameOrigin,
   see,
   shipeasy,
   version

package/dist/server/index.d.mts

@@ -1,3 +1,5 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
 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,20 @@ interface Violation {
     /** 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";
@@ -37,7 +53,26 @@ interface SeeErrorEvent {
     env?: string;
     sdk_version: string;
     ts: number;
+    /**
+     * Per-request correlation token. The client mints one per same-origin fetch
+     * and ships it on both the request header (`X-SE-Correlation`) and any 5xx
+     * occurrence it reports; the server safety net reports the matching uncaught
+     * error under the same token. The backend joins the two issues by it —
+     * populating `caused_by` across the network boundary, where the in-process
+     * `.cause`-chain stamp (see `findCausedBy`) cannot reach. Join-only metadata,
+     * never persisted as an issue field.
+     */
+    correlation_id?: string;
+    /**
+     * 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;
 }
+declare function isExpected(err: unknown): boolean;
 interface SeeExtrasTail {
     /** Attach debugging metadata. Callable repeatedly — keys merge, later wins. */
     extras(extras: SeeExtras): SeeExtrasTail;
@@ -165,6 +200,11 @@ declare class FlagsClient {
     evaluate(user: User, rawUrl?: string): BootstrapPayload;
     getKillswitch(name: string, switchKey?: string): boolean;
 }
+interface SeeCorrelationStore {
+    correlationId?: string;
+}
+declare const seeContext: AsyncLocalStorage<SeeCorrelationStore>;
+
 interface I18nForRequest {
     strings: Record<string, string>;
     locale: string;
@@ -340,4 +380,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-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 };
+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, isExpected, see, seeContext, shipeasy, version };

package/dist/server/index.d.ts

@@ -1,3 +1,5 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
 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,20 @@ interface Violation {
     /** 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";
@@ -37,7 +53,26 @@ interface SeeErrorEvent {
     env?: string;
     sdk_version: string;
     ts: number;
+    /**
+     * Per-request correlation token. The client mints one per same-origin fetch
+     * and ships it on both the request header (`X-SE-Correlation`) and any 5xx
+     * occurrence it reports; the server safety net reports the matching uncaught
+     * error under the same token. The backend joins the two issues by it —
+     * populating `caused_by` across the network boundary, where the in-process
+     * `.cause`-chain stamp (see `findCausedBy`) cannot reach. Join-only metadata,
+     * never persisted as an issue field.
+     */
+    correlation_id?: string;
+    /**
+     * 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;
 }
+declare function isExpected(err: unknown): boolean;
 interface SeeExtrasTail {
     /** Attach debugging metadata. Callable repeatedly — keys merge, later wins. */
     extras(extras: SeeExtras): SeeExtrasTail;
@@ -165,6 +200,11 @@ declare class FlagsClient {
     evaluate(user: User, rawUrl?: string): BootstrapPayload;
     getKillswitch(name: string, switchKey?: string): boolean;
 }
+interface SeeCorrelationStore {
+    correlationId?: string;
+}
+declare const seeContext: AsyncLocalStorage<SeeCorrelationStore>;
+
 interface I18nForRequest {
     strings: Record<string, string>;
     locale: string;
@@ -340,4 +380,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-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 };
+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, isExpected, see, seeContext, shipeasy, version };

package/dist/server/index.js

@@ -38,7 +38,9 @@ __export(server_exports, {
   getBootstrapHtml: () => getBootstrapHtml,
   getShipeasyServerClient: () => getShipeasyServerClient,
   i18n: () => i18n,
+  isExpected: () => isExpected,
   see: () => see,
+  seeContext: () => seeContext,
   shipeasy: () => shipeasy,
   version: () => version
 });
@@ -110,6 +112,7 @@ var SEE_MAX_STACK = 8e3;
 var SEE_MAX_SUBJECT = 200;
 var SEE_MAX_EXTRA_VALUE = 200;
 var SEE_MAX_EXTRA_KEYS = 20;
+var SEE_MAX_CORRELATION = 64;
 var SEE_DEDUP_WINDOW_MS = 3e4;
 var SEE_MAX_PER_SESSION = 25;
 function causesThe(subject) {
@@ -149,6 +152,48 @@ function markExpected(err, because) {
   } catch {
   }
 }
+function isExpected(err) {
+  if (typeof err !== "object" || err === null) return false;
+  return err[EXPECTED_SYM] !== void 0;
+}
+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;
 }
@@ -174,7 +219,7 @@ function captureCallsiteStack() {
   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) {
+function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlationId) {
   let errorType;
   let message;
   let stack;
@@ -207,12 +252,16 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride) {
     ts: Date.now()
   };
   if (stack) ev.stack = truncate(stack, SEE_MAX_STACK);
+  if (correlationId) ev.correlation_id = truncate(String(correlationId), SEE_MAX_CORRELATION);
+  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) {
@@ -235,7 +284,9 @@ function startSeeChain(getProblem, dispatch) {
     flushed = true;
     dispatch(
       getProblem(),
-      causesThe(subject ?? "the app").to(outcome ?? "hit an error"),
+      // 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
     );
   });
@@ -611,11 +662,12 @@ var FlagsClient = class {
    */
   reportError(problem, consequence, extras, kind) {
     try {
+      const correlationId = seeContext.getStore()?.correlationId;
       const ev = buildSeeEvent(problem, consequence, extras, {
         side: "server",
         sdkVersion: version,
         env: this.env
-      }, kind);
+      }, kind, correlationId);
       if (!this.seeLimiter.shouldSend(ev)) return;
       globalThis.fetch(`${this.baseUrl}/collect`, {
         method: "POST",
@@ -710,6 +762,8 @@ Object.defineProperty(globalThis, _EDIT_MODE_SSR_SYM, {
   },
   configurable: true
 });
+var _SEE_CORR_ALS_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-correlation-als");
+var seeContext = globalThis[_SEE_CORR_ALS_SYM] ?? (globalThis[_SEE_CORR_ALS_SYM] = new import_node_async_hooks.AsyncLocalStorage());
 var i18n = {
   /**
    * Fetch translation labels for the current request and store them in an
@@ -957,7 +1011,9 @@ var see = Object.assign(
   getBootstrapHtml,
   getShipeasyServerClient,
   i18n,
+  isExpected,
   see,
+  seeContext,
   shipeasy,
   version
 });

package/dist/server/index.mjs

@@ -66,6 +66,7 @@ var SEE_MAX_STACK = 8e3;
 var SEE_MAX_SUBJECT = 200;
 var SEE_MAX_EXTRA_VALUE = 200;
 var SEE_MAX_EXTRA_KEYS = 20;
+var SEE_MAX_CORRELATION = 64;
 var SEE_DEDUP_WINDOW_MS = 3e4;
 var SEE_MAX_PER_SESSION = 25;
 function causesThe(subject) {
@@ -105,6 +106,48 @@ function markExpected(err, because) {
   } catch {
   }
 }
+function isExpected(err) {
+  if (typeof err !== "object" || err === null) return false;
+  return err[EXPECTED_SYM] !== void 0;
+}
+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;
 }
@@ -130,7 +173,7 @@ function captureCallsiteStack() {
   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) {
+function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlationId) {
   let errorType;
   let message;
   let stack;
@@ -163,12 +206,16 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride) {
     ts: Date.now()
   };
   if (stack) ev.stack = truncate(stack, SEE_MAX_STACK);
+  if (correlationId) ev.correlation_id = truncate(String(correlationId), SEE_MAX_CORRELATION);
+  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) {
@@ -191,7 +238,9 @@ function startSeeChain(getProblem, dispatch) {
     flushed = true;
     dispatch(
       getProblem(),
-      causesThe(subject ?? "the app").to(outcome ?? "hit an error"),
+      // 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
     );
   });
@@ -567,11 +616,12 @@ var FlagsClient = class {
    */
   reportError(problem, consequence, extras, kind) {
     try {
+      const correlationId = seeContext.getStore()?.correlationId;
       const ev = buildSeeEvent(problem, consequence, extras, {
         side: "server",
         sdkVersion: version,
         env: this.env
-      }, kind);
+      }, kind, correlationId);
       if (!this.seeLimiter.shouldSend(ev)) return;
       globalThis.fetch(`${this.baseUrl}/collect`, {
         method: "POST",
@@ -666,6 +716,8 @@ Object.defineProperty(globalThis, _EDIT_MODE_SSR_SYM, {
   },
   configurable: true
 });
+var _SEE_CORR_ALS_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-correlation-als");
+var seeContext = globalThis[_SEE_CORR_ALS_SYM] ?? (globalThis[_SEE_CORR_ALS_SYM] = new AsyncLocalStorage());
 var i18n = {
   /**
    * Fetch translation labels for the current request and store them in an
@@ -912,7 +964,9 @@ export {
   getBootstrapHtml,
   getShipeasyServerClient,
   i18n,
+  isExpected,
   see,
+  seeContext,
   shipeasy,
   version
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/sdk",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "Shipeasy SDK — feature gates, runtime configs, experiments, and metrics for the Shipeasy hosted service.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://shipeasy.ai",