@shipeasy/sdk 4.2.0 → 4.3.0

package/dist/client/index.d.mts

@@ -51,6 +51,16 @@ 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
@@ -120,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;
@@ -176,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;
@@ -478,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

@@ -51,6 +51,16 @@ 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
@@ -120,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;
@@ -176,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;
@@ -478,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) {
@@ -215,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;
@@ -248,6 +251,7 @@ 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);
@@ -501,8 +505,33 @@ function endpointTemplate(rawUrl) {
     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);
+  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;
@@ -579,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);
@@ -599,7 +633,8 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
           violation("Http5xx").message(`request to ${bareUrl} returned ${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;
@@ -911,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
       );
@@ -923,7 +958,7 @@ 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 enriched = { ...collectSeeEnv(), ...extras };
       const ev = buildSeeEvent(problem, consequence, enriched, {
@@ -933,7 +968,7 @@ var FlagsClientBrowser = class {
         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 {
@@ -1600,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) {
@@ -169,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;
@@ -202,6 +203,7 @@ 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);
@@ -455,8 +457,33 @@ function endpointTemplate(rawUrl) {
     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);
+  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;
@@ -533,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);
@@ -553,7 +585,8 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
           violation("Http5xx").message(`request to ${bareUrl} returned ${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;
@@ -865,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
       );
@@ -877,7 +910,7 @@ 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 enriched = { ...collectSeeEnv(), ...extras };
       const ev = buildSeeEvent(problem, consequence, enriched, {
@@ -887,7 +920,7 @@ var FlagsClientBrowser = class {
         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 {
@@ -1553,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. */
@@ -51,6 +53,16 @@ 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
@@ -60,6 +72,7 @@ interface SeeErrorEvent {
      */
     caused_by?: SeeCausedBy;
 }
+declare function isExpected(err: unknown): boolean;
 interface SeeExtrasTail {
     /** Attach debugging metadata. Callable repeatedly — keys merge, later wins. */
     extras(extras: SeeExtras): SeeExtrasTail;
@@ -187,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;
@@ -362,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. */
@@ -51,6 +53,16 @@ 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
@@ -60,6 +72,7 @@ interface SeeErrorEvent {
      */
     caused_by?: SeeCausedBy;
 }
+declare function isExpected(err: unknown): boolean;
 interface SeeExtrasTail {
     /** Attach debugging metadata. Callable repeatedly — keys merge, later wins. */
     extras(extras: SeeExtras): SeeExtrasTail;
@@ -187,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;
@@ -362,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,10 @@ 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) {
@@ -212,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;
@@ -245,6 +252,7 @@ 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);
@@ -654,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",
@@ -753,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
@@ -1000,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,10 @@ 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) {
@@ -168,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;
@@ -201,6 +206,7 @@ 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);
@@ -610,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",
@@ -709,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
@@ -955,7 +964,9 @@ export {
   getBootstrapHtml,
   getShipeasyServerClient,
   i18n,
+  isExpected,
   see,
+  seeContext,
   shipeasy,
   version
 };

package/package.json

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