@shipeasy/sdk 4.1.0 → 4.2.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,14 @@ interface SeeErrorEvent {
     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. */

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,14 @@ interface SeeErrorEvent {
     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. */

package/dist/client/index.js

@@ -152,6 +152,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;
 }
@@ -210,12 +248,15 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride) {
     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) {
@@ -238,7 +279,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 +492,18 @@ 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 sameOrigin = typeof location !== "undefined" && u.origin === location.origin;
+  return ((sameOrigin ? "" : u.host) + path).slice(0, 120);
+}
 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 +552,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 +568,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"
       );
@@ -531,7 +586,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,7 +597,7 @@ 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"
         );
@@ -687,6 +742,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 = {};
@@ -793,7 +925,8 @@ var FlagsClientBrowser = class {
    */
   reportError(problem, consequence, extras, kind) {
     try {
-      const ev = buildSeeEvent(problem, consequence, extras, {
+      const enriched = { ...collectSeeEnv(), ...extras };
+      const ev = buildSeeEvent(problem, consequence, enriched, {
         side: "client",
         sdkVersion: version,
         env: this.env,

package/dist/client/index.mjs

@@ -106,6 +106,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;
 }
@@ -164,12 +202,15 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride) {
     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) {
@@ -192,7 +233,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 +446,18 @@ 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 sameOrigin = typeof location !== "undefined" && u.origin === location.origin;
+  return ((sameOrigin ? "" : u.host) + path).slice(0, 120);
+}
 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 +506,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 +522,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"
       );
@@ -485,7 +540,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,7 +551,7 @@ 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"
         );
@@ -641,6 +696,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 = {};
@@ -747,7 +879,8 @@ var FlagsClientBrowser = class {
    */
   reportError(problem, consequence, extras, kind) {
     try {
-      const ev = buildSeeEvent(problem, consequence, extras, {
+      const enriched = { ...collectSeeEnv(), ...extras };
+      const ev = buildSeeEvent(problem, consequence, enriched, {
         side: "client",
         sdkVersion: version,
         env: this.env,

package/dist/server/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,14 @@ interface SeeErrorEvent {
     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. */

package/dist/server/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,14 @@ interface SeeErrorEvent {
     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. */

package/dist/server/index.js

@@ -149,6 +149,44 @@ function markExpected(err, because) {
   } 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;
 }
@@ -207,12 +245,15 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride) {
     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) {
@@ -235,7 +276,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
     );
   });

package/dist/server/index.mjs

@@ -105,6 +105,44 @@ function markExpected(err, because) {
   } 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;
 }
@@ -163,12 +201,15 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride) {
     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) {
@@ -191,7 +232,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
     );
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/sdk",
-  "version": "4.1.0",
+  "version": "4.2.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",