@interfere/types 9.0.0 → 9.0.3-canary.0

package/dist/sdk/envelope.mjs

@@ -1,114 +1,2 @@
-import { z } from "zod";
-import { sessionIdSchema } from "#data/session";
-import { browserContextSchema } from "#sdk/plugins/context/browser";
-import { edgeContextSchema } from "#sdk/plugins/context/edge";
-import { nextjsContextSchema } from "#sdk/plugins/context/next";
-import { errorEnvelopePayloadSchema } from "#sdk/plugins/payload/errors";
-import { pageleavePayloadSchema, pageviewPayloadSchema, uiEventPayloadSchema } from "#sdk/plugins/payload/page-events";
-import { rageClickPayloadSchema } from "#sdk/plugins/payload/rage-click";
-import { replayChunkPayloadSchema } from "#sdk/plugins/payload/replay";
-import { envSchema, runtimeSchema } from "#sdk/runtime";
-//#region src/sdk/envelope.ts
-/**
-* Indicates how the sessionId was resolved on the server.
-*
-* - "header": Extracted from x-interfere-request header (ideal case)
-* - "async_context": Retrieved from AsyncLocalStorage context
-* - "fallback": Generated as server-side fallback (breaks session continuity)
-* - "client": Session ID was set on the client (browser SDK)
-*/
-const sessionSourceSchema = z.enum([
-	"header",
-	"async_context",
-	"fallback",
-	"client"
-]).optional().meta({
-	id: "SessionSource",
-	title: "SessionSource",
-	description: "How the server resolved the sessionId for this envelope."
-});
-const envelopeContextSchema = z.discriminatedUnion("runtime", [
-	browserContextSchema,
-	nextjsContextSchema,
-	edgeContextSchema
-]).meta({
-	id: "EnvelopeContext",
-	title: "EnvelopeContext",
-	description: "Runtime-specific request context attached to every envelope."
-});
-const envelopeHeadersShape = {
-	buildId: z.string(),
-	clientTs: z.int(),
-	context: envelopeContextSchema.optional(),
-	environment: envSchema,
-	producerVersion: z.string().optional(),
-	releaseId: z.string().nullable(),
-	runtime: runtimeSchema,
-	sdkStack: z.array(z.string()).optional(),
-	sessionId: sessionIdSchema.nullable(),
-	sessionSource: sessionSourceSchema,
-	uuid: z.uuidv7(),
-	v: z.literal(0)
-};
-const errorEnvelopeSchema = z.object({
-	...envelopeHeadersShape,
-	type: z.literal("error"),
-	payload: errorEnvelopePayloadSchema
-}).meta({
-	id: "ErrorEnvelope",
-	title: "ErrorEnvelope"
-});
-const pageviewEnvelopeSchema = z.object({
-	...envelopeHeadersShape,
-	type: z.literal("pageview"),
-	payload: pageviewPayloadSchema
-}).meta({
-	id: "PageviewEnvelope",
-	title: "PageviewEnvelope"
-});
-const pageleaveEnvelopeSchema = z.object({
-	...envelopeHeadersShape,
-	type: z.literal("pageleave"),
-	payload: pageleavePayloadSchema
-}).meta({
-	id: "PageleaveEnvelope",
-	title: "PageleaveEnvelope"
-});
-const uiEventEnvelopeSchema = z.object({
-	...envelopeHeadersShape,
-	type: z.literal("ui_event"),
-	payload: uiEventPayloadSchema
-}).meta({
-	id: "UiEventEnvelope",
-	title: "UiEventEnvelope"
-});
-const replayChunkEnvelopeSchema = z.object({
-	...envelopeHeadersShape,
-	type: z.literal("replay_chunk"),
-	payload: replayChunkPayloadSchema
-}).meta({
-	id: "ReplayChunkEnvelope",
-	title: "ReplayChunkEnvelope"
-});
-const rageClickEnvelopeSchema = z.object({
-	...envelopeHeadersShape,
-	type: z.literal("rage_click"),
-	payload: rageClickPayloadSchema
-}).meta({
-	id: "RageClickEnvelope",
-	title: "RageClickEnvelope"
-});
-const envelopeSchema = z.discriminatedUnion("type", [
-	errorEnvelopeSchema,
-	pageviewEnvelopeSchema,
-	pageleaveEnvelopeSchema,
-	uiEventEnvelopeSchema,
-	replayChunkEnvelopeSchema,
-	rageClickEnvelopeSchema
-]).meta({
-	id: "Envelope",
-	title: "Envelope",
-	description: "A single event envelope accepted by the collector."
-});
-//#endregion
-export { envelopeContextSchema, envelopeSchema, errorEnvelopeSchema, pageleaveEnvelopeSchema, pageviewEnvelopeSchema, rageClickEnvelopeSchema, replayChunkEnvelopeSchema, sessionSourceSchema, uiEventEnvelopeSchema };
+import{z}from"zod";import{sessionIdSchema}from"#data/session";import{browserContextSchema}from"#sdk/plugins/context/browser";import{edgeContextSchema}from"#sdk/plugins/context/edge";import{nextjsContextSchema}from"#sdk/plugins/context/next";import{nodeContextSchema}from"#sdk/plugins/context/node";import{errorEnvelopePayloadSchema}from"#sdk/plugins/payload/errors";import{pageleavePayloadSchema,pageviewPayloadSchema,uiEventPayloadSchema}from"#sdk/plugins/payload/page-events";import{rageClickPayloadSchema}from"#sdk/plugins/payload/rage-click";import{replayChunkPayloadSchema}from"#sdk/plugins/payload/replay";import{envSchema,runtimeSchema}from"#sdk/runtime";const sessionSourceSchema=z.enum([`header`,`async_context`,`fallback`,`client`]).optional().meta({id:`SessionSource`,title:`SessionSource`,description:`How the server resolved the sessionId for this envelope.`}),envelopeContextSchema=z.discriminatedUnion(`runtime`,[browserContextSchema,nextjsContextSchema,edgeContextSchema,nodeContextSchema]).meta({id:`EnvelopeContext`,title:`EnvelopeContext`,description:`Runtime-specific request context attached to every envelope.`}),envelopeHeadersShape={buildId:z.string(),clientTs:z.int(),context:envelopeContextSchema.optional(),environment:envSchema,producerVersion:z.string().optional(),releaseId:z.string().nullable(),runtime:runtimeSchema,sdkStack:z.array(z.string()).optional(),sessionId:sessionIdSchema.nullable(),sessionSource:sessionSourceSchema,uuid:z.uuidv7(),v:z.literal(0)},errorEnvelopeSchema=z.object({...envelopeHeadersShape,type:z.literal(`error`),payload:errorEnvelopePayloadSchema}).meta({id:`ErrorEnvelope`,title:`ErrorEnvelope`}),pageviewEnvelopeSchema=z.object({...envelopeHeadersShape,type:z.literal(`pageview`),payload:pageviewPayloadSchema}).meta({id:`PageviewEnvelope`,title:`PageviewEnvelope`}),pageleaveEnvelopeSchema=z.object({...envelopeHeadersShape,type:z.literal(`pageleave`),payload:pageleavePayloadSchema}).meta({id:`PageleaveEnvelope`,title:`PageleaveEnvelope`}),uiEventEnvelopeSchema=z.object({...envelopeHeadersShape,type:z.literal(`ui_event`),payload:uiEventPayloadSchema}).meta({id:`UiEventEnvelope`,title:`UiEventEnvelope`}),replayChunkEnvelopeSchema=z.object({...envelopeHeadersShape,type:z.literal(`replay_chunk`),payload:replayChunkPayloadSchema}).meta({id:`ReplayChunkEnvelope`,title:`ReplayChunkEnvelope`}),rageClickEnvelopeSchema=z.object({...envelopeHeadersShape,type:z.literal(`rage_click`),payload:rageClickPayloadSchema}).meta({id:`RageClickEnvelope`,title:`RageClickEnvelope`}),envelopeSchema=z.discriminatedUnion(`type`,[errorEnvelopeSchema,pageviewEnvelopeSchema,pageleaveEnvelopeSchema,uiEventEnvelopeSchema,replayChunkEnvelopeSchema,rageClickEnvelopeSchema]).meta({id:`Envelope`,title:`Envelope`,description:`A single event envelope accepted by the collector.`});export{envelopeContextSchema,envelopeSchema,errorEnvelopeSchema,pageleaveEnvelopeSchema,pageviewEnvelopeSchema,rageClickEnvelopeSchema,replayChunkEnvelopeSchema,sessionSourceSchema,uiEventEnvelopeSchema};
+//# sourceMappingURL=envelope.mjs.map

package/dist/sdk/errors.cjs

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const MECHANISM_TYPE={browser:{onerror:`auto.browser.global_handlers.onerror`,onunhandledrejection:`auto.browser.global_handlers.onunhandledrejection`,consoleError:`auto.browser.console.error`},react:{errorBoundary:`auto.function.react.error_boundary`,captureBoundary:`auto.function.react.capture_boundary`,caughtError:`auto.function.react.caught_error`,uncaughtError:`auto.function.react.uncaught_error`,recoverableError:`auto.function.react.recoverable_error`},nextjs:{onRequestError:`auto.function.nextjs.on_request_error`,captureError:`auto.function.nextjs.capture_error`},node:{captureError:`auto.function.node.capture_error`,uncaughtException:`auto.node.global_handlers.uncaught_exception`,unhandledRejection:`auto.node.global_handlers.unhandled_rejection`},manual:{capture:`manual.api.capture`}},EXTENSION_URL_RE=/\b(?:chrome|moz|safari-web|safari|ms-browser|webkit-masked)-(?:extension|url):\/\//;function shouldDropBrowserExtensionNoise(stacks){return stacks.some(stack=>EXTENSION_URL_RE.test(stack))}const HAS_SOURCE_LOCATION_RE=/(?:https?|file|blob|webpack-internal):\/\/|\sat\s+[\w$.<>]+\s+\([^)]+:\d/;function shouldDropUnresolvableStack(stacks){if(stacks.length===0)return!1;for(let stack of stacks)if(HAS_SOURCE_LOCATION_RE.test(stack))return!1;return!0}const COMPONENT_STACK_RE=/^(?:in|at)\s+([^\s(]+)(?:\s+\(([^\s:)]+):(\d+)(?::(\d+))?\))?/;function parseReactComponentStack(componentStack){let frames=[];for(let rawLine of componentStack.split(`
+`)){let line=rawLine.trim();if(!line)continue;let match=COMPONENT_STACK_RE.exec(line);if(!match)continue;let[,name,fileName,lineStr,colStr]=match;if(!name)continue;let frame={id:`react-${frames.length}`,fn:name};fileName&&(frame.file=fileName),lineStr&&(frame.line=Number(lineStr)),colStr&&(frame.column=Number(colStr)),frames.push(frame)}return frames}function toError(error){return error instanceof Error?error:typeof error==`string`?Error(error):typeof error==`object`&&error?tryUnwrapNestedError(error)||tagAsNonError(safeJson(error)??String(error)):tagAsNonError(String(error))}function tryUnwrapNestedError(record){if(record.cause instanceof Error)return record.cause;for(let value of Object.values(record))if(value instanceof Error)return value}function tagAsNonError(message){let e=Error(message);return e.name=`NonError`,e}function safeJson(value){try{return JSON.stringify(value)}catch{return null}}function classify(value){if(value===null)return`null`;let t=typeof value;if(t!==`object`)return t;let tag=Object.prototype.toString.call(value).slice(8,-1);return tag===`Object`?`PlainObject`:tag}function describe(value){if(value==null)return`Non-Error captured: ${String(value)}`;if(typeof value==`object`){let keys=Object.keys(value).sort();return keys.length===0?`Non-Error captured: empty object`:`Non-Error captured with keys: ${keys.join(`, `)}`}return`Non-Error captured: ${String(value)}`}function serializeBoundedDepth(value,maxDepth){let seen=new WeakSet,walk=(current,depth)=>{if(current===null)return null;let t=typeof current;if(t===`string`||t===`number`||t===`boolean`)return current;if(t===`undefined`)return;if(t===`function`||t===`symbol`||t===`bigint`)return String(current);if(depth>maxDepth)return`[depth-limit]`;if(seen.has(current))return`[circular]`;if(seen.add(current),Array.isArray(current))return current.map(item=>walk(item,depth+1));let out={};for(let[k,v]of Object.entries(current))out[k]=walk(v,depth+1);return out};return walk(value,0)}function toException(value){if(value instanceof Error)return value;if(typeof value==`string`)return Error(value);if(typeof value==`object`&&value){let nested=tryUnwrapNestedError(value);if(nested)return nested}return{kind:`non-error`,type:classify(value),value:describe(value),serialized:serializeBoundedDepth(value,4)}}function isNonErrorException(value){return typeof value==`object`&&!!value&&value.kind===`non-error`}function toExceptions(value,mechanism){if(isNonErrorException(value))return[{kind:`non-error`,type:value.type,value:value.value,mechanism,serialized:value.serialized}];let exceptions=[],current=value;for(let depth=0;current&&depth<5;depth+=1)exceptions.push({kind:`error`,type:current.name,value:current.message,mechanism:depth===0?mechanism:void 0,stack:current.stack??``}),current=current.cause instanceof Error?current.cause:void 0;return exceptions}exports.MECHANISM_TYPE=MECHANISM_TYPE,exports.isNonErrorException=isNonErrorException,exports.parseReactComponentStack=parseReactComponentStack,exports.shouldDropBrowserExtensionNoise=shouldDropBrowserExtensionNoise,exports.shouldDropUnresolvableStack=shouldDropUnresolvableStack,exports.toError=toError,exports.toException=toException,exports.toExceptions=toExceptions;

package/dist/sdk/errors.d.cts

@@ -0,0 +1,154 @@
+import { IngestedFrame } from "#data/frame";
+import { ErrorMechanism, ExceptionValue } from "#sdk/plugins/payload/errors";
+
+//#region src/sdk/errors.d.ts
+/**
+ * Structured taxonomy of capture sources, tagged onto each
+ * `ErrorMechanism.type`. Follows the `auto.<surface>.<library>.<method>`
+ * convention Sentry also uses, so downstream analytics / classification can
+ * group on common prefixes:
+ *
+ *   `auto.browser.*`   — captured by SDK global handlers in the browser
+ *   `auto.function.*`  — captured by SDK functions (boundaries, callbacks,
+ *                        server wrappers)
+ *
+ * Leaves (`.onerror`, `.error_boundary`, `.on_request_error`, …) identify
+ * the specific capture site, which lets the agent's skill classifier reason
+ * about what "kind" of event this is without string-matching loose names.
+ */
+declare const MECHANISM_TYPE: {
+  readonly browser: {
+    readonly onerror: "auto.browser.global_handlers.onerror";
+    readonly onunhandledrejection: "auto.browser.global_handlers.onunhandledrejection";
+    readonly consoleError: "auto.browser.console.error";
+  };
+  readonly react: {
+    readonly errorBoundary: "auto.function.react.error_boundary";
+    readonly captureBoundary: "auto.function.react.capture_boundary";
+    readonly caughtError: "auto.function.react.caught_error";
+    readonly uncaughtError: "auto.function.react.uncaught_error";
+    readonly recoverableError: "auto.function.react.recoverable_error";
+  };
+  readonly nextjs: {
+    readonly onRequestError: "auto.function.nextjs.on_request_error";
+    readonly captureError: "auto.function.nextjs.capture_error";
+  };
+  readonly node: {
+    readonly captureError: "auto.function.node.capture_error";
+    readonly uncaughtException: "auto.node.global_handlers.uncaught_exception";
+    readonly unhandledRejection: "auto.node.global_handlers.unhandled_rejection";
+  };
+  readonly manual: {
+    /** Customer called `capture(error)` from `@interfere/react/api`. */readonly capture: "manual.api.capture";
+  };
+};
+/**
+ * True when the raw stack mentions any browser-extension URL scheme
+ * anywhere. Catches extension-only stacks, extension interceptors
+ * (extension frames above app), and app errors whose stack still
+ * includes extension code (e.g. extension hydration). Cause-chain
+ * variants are caught by passing the chain entries' stacks to this
+ * check separately.
+ *
+ * Server-side parsing has full structured fidelity, but the noise
+ * filter runs at capture time before a parsed stack exists — regex
+ * over the raw string is sufficient and avoids pulling a parser into
+ * the customer bundle.
+ */
+declare function shouldDropBrowserExtensionNoise(stacks: readonly string[]): boolean;
+/**
+ * True when **none** of the supplied stacks (head + cause chain entries)
+ * carries any source-location anchor. Non-Error rejections (no stack at
+ * all) are exempt at the call site — they ship structured payloads the
+ * agent can reason over without frames.
+ */
+declare function shouldDropUnresolvableStack(stacks: readonly string[]): boolean;
+/**
+ * Parses a React `errorInfo.componentStack` string into synthetic frames.
+ * Server-side stack parsing handles JS frames; component-stack frames are
+ * supplementary context React emits separately and have a different shape,
+ * so they're parsed at capture time and shipped via `appendFrames`.
+ *
+ * React produces different formats across versions:
+ *   - React 16–18 legacy:    `    in ComponentName`
+ *                            `    in ComponentName (created by Parent)`
+ *   - React 19 owner stacks: `    at ComponentName`
+ *                            `    at ComponentName (file.tsx:10:5)`
+ */
+declare function parseReactComponentStack(componentStack: string): IngestedFrame[];
+/**
+ * Coerces any thrown value into an `Error` instance, preferring a nested
+ * `Error` inside a plain-object rejection over a stringified fallback.
+ *
+ * Motivated by the common `Promise.reject({ error: realErr })` pattern
+ * (tRPC, GraphQL clients, some fetch wrappers). Without this, the captured
+ * exception would be `new Error("[object Object]")` and the nested Error's
+ * stack/message would be lost entirely.
+ *
+ * When multiple candidate Error values exist on the object, the first one
+ * found (in declaration order) wins. `cause` is preferred if present, since
+ * it's the documented ES2022 convention.
+ */
+declare function toError(error: unknown): Error;
+/**
+ * Capture-side variant for thrown values that aren't Errors and don't
+ * carry a nested Error (e.g. `Promise.reject({ code: 401, body: "..." })`,
+ * `Promise.reject(42)`). The structured payload rides on `serialized`
+ * so downstream consumers can render the original shape instead of
+ * parsing JSON back out of an Error's message string.
+ *
+ * Strings are *not* represented here — `Promise.reject("boom")` maps
+ * cleanly to `new Error("boom")` without lying about the shape, so it
+ * goes through `toException`'s Error branch.
+ */
+interface NonErrorException {
+  readonly kind: "non-error";
+  /**
+   * Original payload, depth-bounded and circular-safe. Anything beyond
+   * `MAX_NON_ERROR_DEPTH` is collapsed to `"[depth-limit]"`; circular
+   * back-edges become `"[circular]"`. Primitives pass through unchanged.
+   */
+  readonly serialized: unknown;
+  /**
+   * Stable label for grouping. `"PlainObject"` / `"Array"` / `"number"`
+   * etc. — derived from the value's structural class, not its content,
+   * so two `Promise.reject({ code: 401 })` calls land in the same group
+   * regardless of which keys the object carries.
+   */
+  readonly type: string;
+  /**
+   * Best-effort one-liner. For objects: a sorted list of keys. For
+   * primitives: `String(value)`. The dashboard shows this; the
+   * `serialized` field carries the actual payload.
+   */
+  readonly value: string;
+}
+/**
+ * Coerces any thrown value into either an `Error` (when one is
+ * recoverable — direct Error, or nested Error inside an object via
+ * `cause` / first-Error-valued property — or a string, which maps
+ * cleanly to `new Error(str)`) or a structured `NonErrorException`
+ * carrying the original payload.
+ *
+ * Replaces `toError` for capture sites that handle both branches
+ * (today: `unhandledrejection`). `toError` is kept for callers that
+ * specifically need an `Error` (`<ErrorBoundary>` interop, browser
+ * APIs that take Error-typed args).
+ */
+declare function toException(value: unknown): Error | NonErrorException;
+declare function isNonErrorException(value: unknown): value is NonErrorException;
+/**
+ * Walks `Error.cause` to flatten the chain into the wire shape the
+ * collector expects. Each entry carries `type` / `value` / `mechanism?`
+ * plus the raw `stack` string — the SDK ships **no parsed frames**.
+ * Server-side ingest parses `stack` into structured `IngestedFrame[]`
+ * via the collector's stack parser (see
+ * `src/services/collector/src/lib/stack-parser.ts`).
+ *
+ * Non-Error rejections short-circuit to a single `kind: "non-error"`
+ * entry with the structured payload on `serialized`.
+ */
+declare function toExceptions(value: Error | NonErrorException, mechanism: ErrorMechanism): ExceptionValue[];
+//#endregion
+export { MECHANISM_TYPE, NonErrorException, isNonErrorException, parseReactComponentStack, shouldDropBrowserExtensionNoise, shouldDropUnresolvableStack, toError, toException, toExceptions };
+//# sourceMappingURL=errors.d.cts.map

package/dist/sdk/errors.d.mts

@@ -33,47 +33,47 @@ declare const MECHANISM_TYPE: {
     readonly onRequestError: "auto.function.nextjs.on_request_error";
     readonly captureError: "auto.function.nextjs.capture_error";
   };
+  readonly node: {
+    readonly captureError: "auto.function.node.capture_error";
+    readonly uncaughtException: "auto.node.global_handlers.uncaught_exception";
+    readonly unhandledRejection: "auto.node.global_handlers.unhandled_rejection";
+  };
+  readonly manual: {
+    /** Customer called `capture(error)` from `@interfere/react/api`. */readonly capture: "manual.api.capture";
+  };
 };
 /**
- * True when any exception in the cause chain has at least one stack frame
- * whose `fileName` is a browser-extension script URL. Covers extension-only
- * stacks, extension interceptors (extension frames above app), app errors
- * whose stack still includes extension code (e.g. hydration), and errors
- * whose outer throw is app code but whose inner `.cause` originated in an
- * extension. Stacks with no filenames are unchanged (returns false).
- */
-declare function shouldDropBrowserExtensionNoise(exceptions: readonly ExceptionValue[]): boolean;
-/**
- * True when no frame across the full cause chain carries any `fileName`.
+ * True when the raw stack mentions any browser-extension URL scheme
+ * anywhere. Catches extension-only stacks, extension interceptors
+ * (extension frames above app), and app errors whose stack still
+ * includes extension code (e.g. extension hydration). Cause-chain
+ * variants are caught by passing the chain entries' stacks to this
+ * check separately.
  *
- * Such stacks are structurally uninvestigatable: they come from inline
- * `<script>` blocks (`at <anonymous>:N:M`), `eval()` / `new Function()`,
- * CORS-masked cross-origin scripts (`"Script error."`), or browser-internal
- * code with no URL. No source map can resolve them, no repo lookup can find
- * them, and the agent has nothing to reason over. Dropping at capture time
- * prevents them from dominating ingest volume.
+ * Server-side parsing has full structured fidelity, but the noise
+ * filter runs at capture time before a parsed stack exists — regex
+ * over the raw string is sufficient and avoids pulling a parser into
+ * the customer bundle.
  */
-declare function shouldDropUnresolvableStack(exceptions: readonly ExceptionValue[]): boolean;
+declare function shouldDropBrowserExtensionNoise(stacks: readonly string[]): boolean;
 /**
- * Normalizes an `Error.stack` string before feeding it to the stack parser.
- *
- * - Truncates each line to {@link MAX_STACK_LINE_LENGTH} to prevent ReDoS on
- *   pathological inputs (a single frame with a 100 KiB URL can stall the
- *   main thread for seconds in a regex-based parser).
- * - Strips the trailing `(error: *)` suffix some webpack builds emit.
+ * True when **none** of the supplied stacks (head + cause chain entries)
+ * carries any source-location anchor. Non-Error rejections (no stack at
+ * all) are exempt at the call site — they ship structured payloads the
+ * agent can reason over without frames.
  */
-declare function preprocessStack(stack: string): string;
+declare function shouldDropUnresolvableStack(stacks: readonly string[]): boolean;
 /**
  * Parses a React `errorInfo.componentStack` string into synthetic frames.
+ * Server-side stack parsing handles JS frames; component-stack frames are
+ * supplementary context React emits separately and have a different shape,
+ * so they're parsed at capture time and shipped via `appendFrames`.
  *
  * React produces different formats across versions:
  *   - React 16–18 legacy:    `    in ComponentName`
  *                            `    in ComponentName (created by Parent)`
  *   - React 19 owner stacks: `    at ComponentName`
  *                            `    at ComponentName (file.tsx:10:5)`
- *
- * Each line becomes one frame with the component as `functionName`. When file
- * positions are present (React 19), they're preserved.
  */
 declare function parseReactComponentStack(componentStack: string): IngestedFrame[];
 /**
@@ -90,7 +90,65 @@ declare function parseReactComponentStack(componentStack: string): IngestedFrame
  * it's the documented ES2022 convention.
  */
 declare function toError(error: unknown): Error;
-declare function toExceptions(error: Error, mechanism: ErrorMechanism): ExceptionValue[];
-declare function extractFilenameFromStack(stack: string): string | null;
+/**
+ * Capture-side variant for thrown values that aren't Errors and don't
+ * carry a nested Error (e.g. `Promise.reject({ code: 401, body: "..." })`,
+ * `Promise.reject(42)`). The structured payload rides on `serialized`
+ * so downstream consumers can render the original shape instead of
+ * parsing JSON back out of an Error's message string.
+ *
+ * Strings are *not* represented here — `Promise.reject("boom")` maps
+ * cleanly to `new Error("boom")` without lying about the shape, so it
+ * goes through `toException`'s Error branch.
+ */
+interface NonErrorException {
+  readonly kind: "non-error";
+  /**
+   * Original payload, depth-bounded and circular-safe. Anything beyond
+   * `MAX_NON_ERROR_DEPTH` is collapsed to `"[depth-limit]"`; circular
+   * back-edges become `"[circular]"`. Primitives pass through unchanged.
+   */
+  readonly serialized: unknown;
+  /**
+   * Stable label for grouping. `"PlainObject"` / `"Array"` / `"number"`
+   * etc. — derived from the value's structural class, not its content,
+   * so two `Promise.reject({ code: 401 })` calls land in the same group
+   * regardless of which keys the object carries.
+   */
+  readonly type: string;
+  /**
+   * Best-effort one-liner. For objects: a sorted list of keys. For
+   * primitives: `String(value)`. The dashboard shows this; the
+   * `serialized` field carries the actual payload.
+   */
+  readonly value: string;
+}
+/**
+ * Coerces any thrown value into either an `Error` (when one is
+ * recoverable — direct Error, or nested Error inside an object via
+ * `cause` / first-Error-valued property — or a string, which maps
+ * cleanly to `new Error(str)`) or a structured `NonErrorException`
+ * carrying the original payload.
+ *
+ * Replaces `toError` for capture sites that handle both branches
+ * (today: `unhandledrejection`). `toError` is kept for callers that
+ * specifically need an `Error` (`<ErrorBoundary>` interop, browser
+ * APIs that take Error-typed args).
+ */
+declare function toException(value: unknown): Error | NonErrorException;
+declare function isNonErrorException(value: unknown): value is NonErrorException;
+/**
+ * Walks `Error.cause` to flatten the chain into the wire shape the
+ * collector expects. Each entry carries `type` / `value` / `mechanism?`
+ * plus the raw `stack` string — the SDK ships **no parsed frames**.
+ * Server-side ingest parses `stack` into structured `IngestedFrame[]`
+ * via the collector's stack parser (see
+ * `src/services/collector/src/lib/stack-parser.ts`).
+ *
+ * Non-Error rejections short-circuit to a single `kind: "non-error"`
+ * entry with the structured payload on `serialized`.
+ */
+declare function toExceptions(value: Error | NonErrorException, mechanism: ErrorMechanism): ExceptionValue[];
 //#endregion
-export { MECHANISM_TYPE, extractFilenameFromStack, parseReactComponentStack, preprocessStack, shouldDropBrowserExtensionNoise, shouldDropUnresolvableStack, toError, toExceptions };
+export { MECHANISM_TYPE, NonErrorException, isNonErrorException, parseReactComponentStack, shouldDropBrowserExtensionNoise, shouldDropUnresolvableStack, toError, toException, toExceptions };
+//# sourceMappingURL=errors.d.mts.map