@belvador/core 0.2.0 → 0.4.0

package/dist/aborts.d.ts

@@ -8,3 +8,5 @@ export declare function isAbortError(error: unknown): boolean;
 export declare function noteClientAbort(error: unknown, signal: AbortSignal | null | undefined): void;
 /** True for an AbortError or an error thrown while its request's client had gone. */
 export declare function isClientAbort(error: unknown): boolean;
+/** A DOMException (AbortError/InvalidStateError) with a standard View Transition message. */
+export declare function isViewTransitionSkip(error: unknown): boolean;

package/dist/aborts.js

@@ -39,3 +39,36 @@ export function isClientAbort(error) {
         return true;
     return error !== null && typeof error === "object" && clientAborted.has(error);
 }
+/**
+ * Messages browsers give a View Transition that was skipped or aborted on purpose
+ * (observability-1.0 spec 03 §8): the page was hidden, another transition started, the
+ * viewport changed, or `skipTransition()` was called. Exact texts of Chromium, WebKit and
+ * Gecko, matched whole — never a broad pattern.
+ */
+const VIEW_TRANSITION_MESSAGES = [
+    /^Transition was skipped$/,
+    /^Transition was aborted because of invalid state$/,
+    /^Skipped ViewTransition due to (?:document being hidden|another transition starting|hidden document|viewport size change)\.?$/,
+    /^Skipping view transition because (?:document visibility state has become hidden|viewport size changed|the document is hidden|another transition started)\.?$/,
+    /^The (?:previous|old) transition was skipped(?: because a new transition started)?\.?$/,
+    /^View transition was skipped because document visibility state is hidden\.?$/,
+];
+/** A DOMException (AbortError/InvalidStateError) with a standard View Transition message. */
+export function isViewTransitionSkip(error) {
+    try {
+        if (error === null || typeof error !== "object")
+            return false;
+        const name = error.name;
+        const message = error.message;
+        if (name !== "AbortError" && name !== "InvalidStateError")
+            return false;
+        if (typeof message !== "string")
+            return false;
+        if (typeof DOMException !== "undefined" && !(error instanceof DOMException))
+            return false;
+        return VIEW_TRANSITION_MESSAGES.some((re) => re.test(message.trim()));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/diagnostics.d.ts

@@ -1,4 +1,4 @@
-export declare const DIAGNOSTIC_CODES: readonly ["BLV_DSN_MISSING", "BLV_DSN_INVALID", "BLV_INIT_CONFLICT", "BLV_NOT_INITIALIZED", "BLV_SEND_UNAUTHORIZED", "BLV_SEND_RATE_LIMITED", "BLV_SEND_REJECTED", "BLV_SEND_NETWORK", "BLV_SEND_SERVER", "BLV_QUEUE_FULL", "BLV_EVENT_TOO_LARGE", "BLV_HOOK_MISSING", "BLV_DROPPED_BY_APP"];
+export declare const DIAGNOSTIC_CODES: readonly ["BLV_DSN_MISSING", "BLV_DSN_INVALID", "BLV_INIT_CONFLICT", "BLV_NOT_INITIALIZED", "BLV_SEND_UNAUTHORIZED", "BLV_SEND_RATE_LIMITED", "BLV_SEND_REJECTED", "BLV_SEND_NETWORK", "BLV_SEND_SERVER", "BLV_QUEUE_FULL", "BLV_EVENT_TOO_LARGE", "BLV_HOOK_MISSING", "BLV_DROPPED_BY_APP", "BLV_MONITOR_INVALID_SLUG", "BLV_MONITOR_INVALID_REASON", "BLV_MONITOR_CONFIG_INVALID", "BLV_CHECK_IN_DROPPED", "BLV_TRACE_TARGET_INVALID", "BLV_OTEL_INVALID", "BLV_TRACE_OWNER_OTEL"];
 export type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
 /** Public page explaining every code and the verification (one anchor per code). */
 export declare const VERIFY_DOCS_URL = "https://belvador.dev/en/docs/sdk/verify";

package/dist/diagnostics.js

@@ -16,6 +16,13 @@ export const DIAGNOSTIC_CODES = [
     "BLV_EVENT_TOO_LARGE",
     "BLV_HOOK_MISSING",
     "BLV_DROPPED_BY_APP",
+    "BLV_MONITOR_INVALID_SLUG",
+    "BLV_MONITOR_INVALID_REASON",
+    "BLV_MONITOR_CONFIG_INVALID",
+    "BLV_CHECK_IN_DROPPED",
+    "BLV_TRACE_TARGET_INVALID",
+    "BLV_OTEL_INVALID",
+    "BLV_TRACE_OWNER_OTEL",
 ];
 /** Public page explaining every code and the verification (one anchor per code). */
 export const VERIFY_DOCS_URL = "https://belvador.dev/en/docs/sdk/verify";
@@ -35,6 +42,13 @@ const MESSAGES = {
     BLV_EVENT_TOO_LARGE: "an event or attachment is over the size limit — dropped",
     BLV_HOOK_MISSING: "this server code does not run inside Belvador's middleware or wrapper",
     BLV_DROPPED_BY_APP: "the event was dropped before sending (beforeSend, ignoreErrors or sampleRate)",
+    BLV_MONITOR_INVALID_SLUG: "a monitor slug is not valid (lowercase letters, digits, - and _, at most 64) — no check-in was sent",
+    BLV_MONITOR_INVALID_REASON: "a run reason is not a short code (lowercase letters, digits, . - _, at most 64) — it was left out",
+    BLV_MONITOR_CONFIG_INVALID: "a monitor schedule or setting is not valid — the check-in was sent without it",
+    BLV_CHECK_IN_DROPPED: "a check-in was dropped (too many waiting, rate limited or not sent)",
+    BLV_TRACE_TARGET_INVALID: "a tracePropagation target is not a string or RegExp — it was ignored",
+    BLV_OTEL_INVALID: "otel.api is not @opentelemetry/api — ignored",
+    BLV_TRACE_OWNER_OTEL: "otel is set, so tracePropagation is ignored",
 };
 const config = {
     onDiagnostic: undefined,

package/dist/index.d.ts

@@ -1,8 +1,11 @@
 export { SDK_VERSION, ENGINE_VERSION } from "./version.js";
 export { checkDsn, type BelvadorDsn } from "./dsn.js";
-export { isAbortError, isClientAbort, noteClientAbort } from "./aborts.js";
+export { isAbortError, isClientAbort, isViewTransitionSkip, noteClientAbort } from "./aborts.js";
+export { INTERVAL_UNITS, MONITOR_CONFIG_LIMITS, MONITOR_CONTEXT, MONITOR_SLUG_RE, RUN_CONTEXT, RUN_REASON_RE, buildCheckIn, captureCheckIn, heartbeat, monitorConfigOf, runIdOf, withMonitor, type CheckInInput, type IntervalUnit, type MonitorConfigInput, type MonitorSchedule, type RunHandle, type WithMonitorOptions, } from "./monitor.js";
+export { OTEL_OPTION, otelApiOf, otelBridgeIntegration, otelTraceContext, type OtelApiLike, type OtelOptions, } from "./otel.js";
+export { TRACE_OPTION, installTracePropagation, sentryTraceFromTraceparent, traceConfigOf, urlMatches, withIncomingTraceparent, type TraceConfig, type TracePropagationOptions, } from "./trace.js";
 export { FILTERED, SENSITIVE_KEY_PARTS, isSensitiveKey, scrubBreadcrumb, scrubEvent, scrubParams, scrubText, scrubValue, } from "./privacy.js";
-export { SEND_LIMITS, SENT_ITEM_TYPES, filterEnvelope, makeBelvadorTransport, sendWithRetry, type FetchLike, type SendPolicy, type SendState, } from "./transport.js";
+export { MAX_QUEUED_CHECK_INS, SEND_LIMITS, SENT_ITEM_TYPES, filterEnvelope, makeBelvadorTransport, sendWithRetry, type FetchLike, type SendPolicy, type SendState, } from "./transport.js";
 export { BELVADOR_MARKER, DEFAULT_MAX_BREADCRUMBS, MAX_BREADCRUMBS, MAX_VALUE_LENGTH, buildEngineOptions, warnOnce, type BelvadorBreadcrumb, type BelvadorEvent, type BelvadorEventHint, type BelvadorOptions, type EngineOptions, type RuntimeName, } from "./options.js";
 export { addBreadcrumb, captureException, captureMessage, close, flush, getDiagnostics, isActive, lastEventId, setContext, setTag, setTags, setUser, withScope, type Scope, type SeverityLevel, } from "./facade.js";
 export { DIAGNOSTIC_CODES, DIAGNOSTIC_INTERVAL_MS, VERIFY_DOCS_URL, configureDiagnostics, diagnosticDocsUrl, diagnosticMessage, reportDiagnostic, resetDiagnostics, type Diagnostic, type DiagnosticCode, type DiagnosticsSnapshot, } from "./diagnostics.js";

package/dist/index.js

@@ -3,9 +3,12 @@
 // /tanstack-start instead. Importing this module has no side effects.
 export { SDK_VERSION, ENGINE_VERSION } from "./version.js";
 export { checkDsn } from "./dsn.js";
-export { isAbortError, isClientAbort, noteClientAbort } from "./aborts.js";
+export { isAbortError, isClientAbort, isViewTransitionSkip, noteClientAbort } from "./aborts.js";
+export { INTERVAL_UNITS, MONITOR_CONFIG_LIMITS, MONITOR_CONTEXT, MONITOR_SLUG_RE, RUN_CONTEXT, RUN_REASON_RE, buildCheckIn, captureCheckIn, heartbeat, monitorConfigOf, runIdOf, withMonitor, } from "./monitor.js";
+export { OTEL_OPTION, otelApiOf, otelBridgeIntegration, otelTraceContext, } from "./otel.js";
+export { TRACE_OPTION, installTracePropagation, sentryTraceFromTraceparent, traceConfigOf, urlMatches, withIncomingTraceparent, } from "./trace.js";
 export { FILTERED, SENSITIVE_KEY_PARTS, isSensitiveKey, scrubBreadcrumb, scrubEvent, scrubParams, scrubText, scrubValue, } from "./privacy.js";
-export { SEND_LIMITS, SENT_ITEM_TYPES, filterEnvelope, makeBelvadorTransport, sendWithRetry, } from "./transport.js";
+export { MAX_QUEUED_CHECK_INS, SEND_LIMITS, SENT_ITEM_TYPES, filterEnvelope, makeBelvadorTransport, sendWithRetry, } from "./transport.js";
 export { BELVADOR_MARKER, DEFAULT_MAX_BREADCRUMBS, MAX_BREADCRUMBS, MAX_VALUE_LENGTH, buildEngineOptions, warnOnce, } from "./options.js";
 export { addBreadcrumb, captureException, captureMessage, close, flush, getDiagnostics, isActive, lastEventId, setContext, setTag, setTags, setUser, withScope, } from "./facade.js";
 export { DIAGNOSTIC_CODES, DIAGNOSTIC_INTERVAL_MS, VERIFY_DOCS_URL, configureDiagnostics, diagnosticDocsUrl, diagnosticMessage, reportDiagnostic, resetDiagnostics, } from "./diagnostics.js";

package/dist/monitor.d.ts

@@ -0,0 +1,89 @@
+import type { Client, SerializedCheckIn } from "@sentry/core";
+export declare const MONITOR_SLUG_RE: RegExp;
+export declare const RUN_REASON_RE: RegExp;
+export declare const RUN_CONTEXT = "belvador_run";
+export declare const MONITOR_CONTEXT = "monitor";
+export declare const MONITOR_CONFIG_LIMITS: {
+    readonly intervalValueMax: 1000;
+    readonly checkinMarginMax: 1440;
+    readonly maxRuntimeMax: 10080;
+    readonly thresholdMax: 720;
+    readonly environmentMax: 64;
+    readonly attemptMax: 1000;
+};
+export declare const INTERVAL_UNITS: readonly ["minute", "hour", "day", "week", "month", "year"];
+export type IntervalUnit = (typeof INTERVAL_UNITS)[number];
+export type MonitorSchedule = {
+    type: "crontab";
+    value: string;
+} | {
+    type: "interval";
+    value: number;
+    unit: IntervalUnit;
+};
+/** Settings sent as `monitor_config` (creates or updates the monitor from code). */
+export type MonitorConfigInput = {
+    schedule: MonitorSchedule;
+    /** IANA time zone of a crontab, default UTC. */
+    timezone?: string;
+    /** Minutes a check-in may be late before it counts as missed (default 5). */
+    checkinMargin?: number;
+    /** Minutes a run may take before it counts as timed out (default 30). */
+    maxRuntime?: number;
+    /** Failing runs in a row before an incident opens (default 1). */
+    failureIssueThreshold?: number;
+    /** Healthy runs in a row before it closes (default 1). */
+    recoveryThreshold?: number;
+};
+export type WithMonitorOptions = Partial<MonitorConfigInput> & {
+    environment?: string;
+    /** Your id of the logical run (e.g. a queue message id); retries with the same id form one run. */
+    runId?: string;
+    /** 1 for the first try. */
+    attempt?: number;
+    /** True (or a function of the error) when your queue will try again after this error. */
+    willRetry?: boolean | ((error: unknown) => boolean);
+};
+export type RunHandle = {
+    readonly checkInId: string;
+    readonly runId: string;
+    /** The run did nothing on purpose (healthy). `reason` is a short code. */
+    skip(reason: string): void;
+    /** The run ended but its effect is unknown (e.g. a provider timed out after a side effect). */
+    unknown(reason: string): void;
+};
+export type CheckInInput = {
+    monitorSlug: string;
+    status: "in_progress" | "ok" | "error";
+    /** The id of the start check-in this one finishes; omitted = a new attempt. */
+    checkInId?: string;
+    /** Seconds. */
+    duration?: number;
+    environment?: string;
+    runId?: string;
+    attempt?: number;
+    willRetry?: boolean;
+    outcome?: "skipped" | "unknown";
+    reason?: string;
+};
+/** A UUID as 32 lowercase hex; any other id maps to a stable UUID-shaped hash (grouping only). */
+export declare function runIdOf(value: string): string;
+/** Wire `monitor_config`, or null (with a diagnostic) when anything is invalid. */
+export declare function monitorConfigOf(input: Partial<MonitorConfigInput> | undefined): Record<string, unknown> | null;
+/** The check-in item exactly as sent (exported for the golden test). */
+export declare function buildCheckIn(input: CheckInInput, client: Pick<Client, "getOptions">, config: Record<string, unknown> | null, trace: {
+    trace_id: string;
+    span_id: string;
+} | null): SerializedCheckIn & Record<string, unknown>;
+/** Sends one check-in; returns its id ("" when the SDK is off or the slug is invalid). Never throws. */
+export declare function captureCheckIn(checkIn: CheckInInput, monitorConfig?: MonitorConfigInput): string;
+/** A healthy check-in for an interval monitor ("still alive"). */
+export declare function heartbeat(slug: string, options?: {
+    environment?: string;
+}): void;
+/**
+ * Runs `fn` as one monitored attempt: `in_progress` first, then `ok` (or skipped/unknown
+ * via the handle) when it returns, or the error captured as a normal issue and `error`
+ * when it throws — the same value or error goes back to the caller, unchanged.
+ */
+export declare function withMonitor<T>(slug: string, fn: (run: RunHandle) => T, options?: WithMonitorOptions): T;

package/dist/monitor.js

@@ -0,0 +1,330 @@
+// Monitors (build observability-1.0 spec 06 §2–§4, RLY-25): check-ins on Sentry's wire
+// (develop.sentry.dev/sdk/telemetry/check-ins) plus Belvador's versioned run context.
+// `withMonitor` never changes what the app's function returns or throws, never adds an
+// await to a synchronous function, and a failed send never fails the job.
+import { captureException as engineCaptureException, createCheckInEnvelope, getActiveSpan, getClient, getCurrentScope, getTraceContextFromScope, spanToTraceContext, uuid4, withIsolationScope, } from "@sentry/core";
+import { reportDiagnostic } from "./diagnostics.js";
+import { isActive } from "./facade.js";
+// Copies of `src/shared/contracts/monitors.ts` (a root test keeps them equal).
+export const MONITOR_SLUG_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+export const RUN_REASON_RE = /^[a-z0-9][a-z0-9_.-]{0,63}$/;
+export const RUN_CONTEXT = "belvador_run";
+export const MONITOR_CONTEXT = "monitor";
+export const MONITOR_CONFIG_LIMITS = {
+    intervalValueMax: 1000,
+    checkinMarginMax: 1440,
+    maxRuntimeMax: 10080,
+    thresholdMax: 720,
+    environmentMax: 64,
+    attemptMax: 1000,
+};
+export const INTERVAL_UNITS = ["minute", "hour", "day", "week", "month", "year"];
+const HEX32 = /^[0-9a-f]{32}$/;
+const DASHED = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** A UUID as 32 lowercase hex; any other id maps to a stable UUID-shaped hash (grouping only). */
+export function runIdOf(value) {
+    const v = value.trim().toLowerCase();
+    if (HEX32.test(v))
+        return v;
+    if (DASHED.test(v))
+        return v.replace(/-/g, "");
+    // Two 64-bit FNV-1a lanes → 128 bits; not a security boundary, only "same id → same run".
+    let a = 0xcbf29ce484222325n;
+    let b = 0x84222325cbf29ce4n;
+    const prime = 0x100000001b3n;
+    const mask = (1n << 64n) - 1n;
+    for (let i = 0; i < value.length; i++) {
+        const c = BigInt(value.charCodeAt(i));
+        a = ((a ^ c) * prime) & mask;
+        b = ((b ^ (c + 0x9en)) * prime) & mask;
+    }
+    return a.toString(16).padStart(16, "0") + b.toString(16).padStart(16, "0");
+}
+function validTimeZone(tz) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: tz });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function intIn(v, min, max) {
+    return v === undefined || (typeof v === "number" && Number.isInteger(v) && v >= min && v <= max);
+}
+/** Wire `monitor_config`, or null (with a diagnostic) when anything is invalid. */
+export function monitorConfigOf(input) {
+    if (!input || input.schedule === undefined)
+        return null;
+    try {
+        const s = input.schedule;
+        let schedule = null;
+        if (s && s.type === "crontab" && typeof s.value === "string") {
+            const fields = s.value.trim().split(/\s+/);
+            if (s.value.length <= 120 && fields.length === 5 && fields.every((f) => /^[0-9A-Za-z*,/?#LW-]+$/.test(f)))
+                schedule = { type: "crontab", value: fields.join(" ") };
+        }
+        else if (s &&
+            s.type === "interval" &&
+            intIn(s.value, 1, MONITOR_CONFIG_LIMITS.intervalValueMax) &&
+            INTERVAL_UNITS.includes(s.unit)) {
+            schedule = { type: "interval", value: s.value, unit: s.unit };
+        }
+        const tz = input.timezone ?? "UTC";
+        const ok = schedule !== null &&
+            typeof tz === "string" &&
+            tz.length > 0 &&
+            tz.length <= 64 &&
+            validTimeZone(tz) &&
+            intIn(input.checkinMargin, 1, MONITOR_CONFIG_LIMITS.checkinMarginMax) &&
+            // Larger than Sentry's 7-day ceiling is clamped by the node, like Sentry.
+            intIn(input.maxRuntime, 1, Number.MAX_SAFE_INTEGER) &&
+            intIn(input.failureIssueThreshold, 1, MONITOR_CONFIG_LIMITS.thresholdMax) &&
+            intIn(input.recoveryThreshold, 1, MONITOR_CONFIG_LIMITS.thresholdMax);
+        if (!ok) {
+            reportDiagnostic("BLV_MONITOR_CONFIG_INVALID");
+            return null;
+        }
+        const out = { schedule, timezone: tz };
+        if (input.checkinMargin !== undefined)
+            out["checkin_margin"] = input.checkinMargin;
+        if (input.maxRuntime !== undefined)
+            out["max_runtime"] = input.maxRuntime;
+        if (input.failureIssueThreshold !== undefined)
+            out["failure_issue_threshold"] = input.failureIssueThreshold;
+        if (input.recoveryThreshold !== undefined)
+            out["recovery_threshold"] = input.recoveryThreshold;
+        return out;
+    }
+    catch {
+        reportDiagnostic("BLV_MONITOR_CONFIG_INVALID");
+        return null;
+    }
+}
+function cleanReason(reason) {
+    if (reason === undefined)
+        return undefined;
+    if (typeof reason === "string" && RUN_REASON_RE.test(reason))
+        return reason;
+    reportDiagnostic("BLV_MONITOR_INVALID_REASON");
+    return undefined;
+}
+function now() {
+    try {
+        return typeof performance !== "undefined" && typeof performance.now === "function"
+            ? performance.now()
+            : Date.now();
+    }
+    catch {
+        return Date.now();
+    }
+}
+/** The check-in item exactly as sent (exported for the golden test). */
+export function buildCheckIn(input, client, config, trace) {
+    const options = client.getOptions();
+    const id = input.checkInId ? runIdOf(input.checkInId) : uuid4();
+    const env = typeof input.environment === "string" && input.environment.trim() ? input.environment.trim() : options.environment;
+    const run = { v: 1 };
+    if (input.runId)
+        run["run_id"] = runIdOf(input.runId);
+    if (intIn(input.attempt, 1, MONITOR_CONFIG_LIMITS.attemptMax) && input.attempt !== undefined)
+        run["attempt"] = input.attempt;
+    if (input.willRetry === true && input.status === "error")
+        run["will_retry"] = true;
+    if (input.outcome && input.status !== "in_progress")
+        run["outcome"] = input.outcome;
+    const reason = cleanReason(input.reason);
+    if (reason)
+        run["reason"] = reason;
+    const item = {
+        check_in_id: id,
+        monitor_slug: input.monitorSlug,
+        status: input.status,
+    };
+    if (input.status !== "in_progress" && typeof input.duration === "number" && Number.isFinite(input.duration) && input.duration >= 0)
+        item.duration = input.duration;
+    if (options.release)
+        item.release = options.release;
+    if (env)
+        item.environment = String(env).slice(0, MONITOR_CONFIG_LIMITS.environmentMax);
+    if (config)
+        item["monitor_config"] = config;
+    const contexts = {};
+    if (trace)
+        contexts["trace"] = { trace_id: trace.trace_id, span_id: trace.span_id };
+    if (Object.keys(run).length > 1)
+        contexts[RUN_CONTEXT] = run;
+    if (Object.keys(contexts).length)
+        item["contexts"] = contexts;
+    return item;
+}
+function send(item, client) {
+    try {
+        const envelope = createCheckInEnvelope(item, undefined, client.getSdkMetadata(), client.getOptions().tunnel, client.getDsn());
+        Promise.resolve(client.sendEnvelope(envelope)).then(undefined, () => undefined);
+    }
+    catch {
+        reportDiagnostic("BLV_CHECK_IN_DROPPED");
+    }
+}
+/** The trace errors of this scope carry: the active (request) span's, else the scope's. */
+function currentTrace() {
+    try {
+        const span = getActiveSpan();
+        const t = span ? spanToTraceContext(span) : getTraceContextFromScope(getCurrentScope());
+        return t?.trace_id && t.span_id ? { trace_id: t.trace_id, span_id: t.span_id } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Sends one check-in; returns its id ("" when the SDK is off or the slug is invalid). Never throws. */
+export function captureCheckIn(checkIn, monitorConfig) {
+    try {
+        if (!isActive())
+            return "";
+        const client = getClient();
+        if (!client)
+            return "";
+        if (typeof checkIn?.monitorSlug !== "string" || !MONITOR_SLUG_RE.test(checkIn.monitorSlug)) {
+            reportDiagnostic("BLV_MONITOR_INVALID_SLUG");
+            return "";
+        }
+        const item = buildCheckIn(checkIn, client, monitorConfigOf(monitorConfig), currentTrace());
+        send(item, client);
+        return String(item.check_in_id);
+    }
+    catch {
+        return "";
+    }
+}
+/** A healthy check-in for an interval monitor ("still alive"). */
+export function heartbeat(slug, options) {
+    captureCheckIn({ monitorSlug: slug, status: "ok", ...(options?.environment ? { environment: options.environment } : {}) });
+}
+function isThenable(v) {
+    return v !== null && (typeof v === "object" || typeof v === "function") && typeof v.then === "function";
+}
+/**
+ * Runs `fn` as one monitored attempt: `in_progress` first, then `ok` (or skipped/unknown
+ * via the handle) when it returns, or the error captured as a normal issue and `error`
+ * when it throws — the same value or error goes back to the caller, unchanged.
+ */
+export function withMonitor(slug, fn, options) {
+    const inert = { checkInId: "", runId: "", skip: () => undefined, unknown: () => undefined };
+    let ready = false;
+    let client;
+    try {
+        client = isActive() ? getClient() : undefined;
+        if (client && (typeof slug !== "string" || !MONITOR_SLUG_RE.test(slug))) {
+            reportDiagnostic("BLV_MONITOR_INVALID_SLUG");
+            client = undefined;
+        }
+        ready = client !== undefined;
+    }
+    catch {
+        ready = false;
+    }
+    if (!ready || !client)
+        return fn(inert);
+    const c = client;
+    const o = options ?? {};
+    let config = null;
+    try {
+        config = monitorConfigOf(o);
+    }
+    catch {
+        config = null;
+    }
+    const base = {
+        monitorSlug: slug,
+        ...(o.environment !== undefined ? { environment: o.environment } : {}),
+        ...(o.attempt !== undefined ? { attempt: o.attempt } : {}),
+    };
+    return withIsolationScope((scope) => {
+        let checkInId = "";
+        let runId = "";
+        let outcome = null;
+        let finished = false;
+        let started = 0;
+        try {
+            scope.setContext(MONITOR_CONTEXT, { slug });
+            checkInId = uuid4();
+            runId = o.runId ? runIdOf(o.runId) : checkInId;
+            started = now();
+            send(buildCheckIn({ ...base, status: "in_progress", checkInId, runId }, c, config, currentTrace()), c);
+        }
+        catch {
+            /* never stops the job */
+        }
+        const handle = {
+            checkInId,
+            runId,
+            skip: (reason) => {
+                if (!finished)
+                    outcome = { kind: "skipped", reason };
+            },
+            unknown: (reason) => {
+                if (!finished)
+                    outcome = { kind: "unknown", reason };
+            },
+        };
+        const finish = (status, error) => {
+            if (finished)
+                return;
+            finished = true;
+            try {
+                let willRetry = false;
+                if (status === "error") {
+                    try {
+                        willRetry = typeof o.willRetry === "function" ? o.willRetry(error) === true : o.willRetry === true;
+                    }
+                    catch {
+                        willRetry = false;
+                    }
+                }
+                const done = outcome;
+                send(buildCheckIn({
+                    ...base,
+                    status,
+                    checkInId,
+                    runId,
+                    duration: Math.max(0, (now() - started) / 1000),
+                    ...(willRetry ? { willRetry } : {}),
+                    ...(status === "ok" && done ? { outcome: done.kind, reason: done.reason } : {}),
+                }, c, config, currentTrace()), c);
+            }
+            catch {
+                /* never stops the job */
+            }
+        };
+        const failed = (error) => {
+            try {
+                engineCaptureException(error);
+            }
+            catch {
+                /* reported or not, the error goes back unchanged */
+            }
+            finish("error", error);
+        };
+        let result;
+        try {
+            result = fn(handle);
+        }
+        catch (error) {
+            failed(error);
+            throw error;
+        }
+        if (isThenable(result)) {
+            return result.then((value) => {
+                finish("ok");
+                return value;
+            }, (error) => {
+                failed(error);
+                throw error;
+            });
+        }
+        finish("ok");
+        return result;
+    });
+}

package/dist/options.d.ts

@@ -1,5 +1,7 @@
 import type { Breadcrumb, BreadcrumbHint, ErrorEvent, EventHint } from "@sentry/core";
 import { type Diagnostic } from "./diagnostics.js";
+import { type OtelOptions } from "./otel.js";
+import { type TracePropagationOptions } from "./trace.js";
 import { type SendPolicy } from "./transport.js";
 export type BelvadorEvent = ErrorEvent;
 export type BelvadorEventHint = EventHint;
@@ -27,6 +29,23 @@ export type BelvadorOptions = {
      * a cancellation and is always reported.
      */
     captureAborted?: boolean;
+    /**
+     * Browsers: also report a View Transition the browser skipped on purpose (page hidden,
+     * another transition started, `skipTransition()`). Default false — these are expected.
+     */
+    captureViewTransitionSkips?: boolean;
+    /**
+     * Link errors and job check-ins across services with one trace id. Off by default:
+     * requests whose URL matches `targets` get `traceparent` + `sentry-trace` headers
+     * (the receiving API must allow them in CORS). No spans or transactions are sent.
+     */
+    tracePropagation?: TracePropagationOptions;
+    /**
+     * The app already runs OpenTelemetry: pass `{ api }` from `@opentelemetry/api` and errors
+     * captured inside an active span carry that span's trace and span ids. OpenTelemetry then
+     * owns propagation, so `tracePropagation` is ignored. Belvador creates no spans.
+     */
+    otel?: OtelOptions;
     /** Send attachments added with scope.addAttachment (each ≤ 5 MB). Default false. */
     attachments?: boolean;
     /** Runs before Belvador's own scrubbing; return null to drop the event. */
@@ -73,6 +92,8 @@ export declare function buildEngineOptions(opts: BelvadorOptions, runtime: Runti
     defaultIntegrations: false;
     transport: (options: import("@sentry/core").BaseTransportOptions) => import("@sentry/core").Transport;
     _belvador: boolean;
+    _belvadorTrace: import("./trace.js").TraceConfig | null;
+    _belvadorOtel: import("./otel.js").OtelApiLike | null;
     _metadata: {
         sdk: {
             name: string;

package/dist/options.js

@@ -1,8 +1,10 @@
-import { isClientAbort } from "./aborts.js";
+import { isClientAbort, isViewTransitionSkip } from "./aborts.js";
 import { configureDiagnostics, reportDiagnostic } from "./diagnostics.js";
 import { checkDsn } from "./dsn.js";
 import { scrubBreadcrumb, scrubEvent } from "./privacy.js";
 import { VERIFICATION_CONTEXT, VERIFICATION_TAG, noteVerificationOutcome, verificationOf, } from "./verification.js";
+import { OTEL_OPTION, otelApiOf } from "./otel.js";
+import { TRACE_OPTION, traceConfigOf } from "./trace.js";
 import { makeBelvadorTransport } from "./transport.js";
 import { ENGINE_VERSION, SDK_VERSION } from "./version.js";
 /** Engine package behind each runtime (for `sdk.packages`). */
@@ -33,13 +35,18 @@ export function warnOnce(message) {
 function clamp(n, min, max, fallback) {
     return typeof n === "number" && Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : fallback;
 }
-function chainBeforeSend(user, captureAborted) {
+function chainBeforeSend(user, captureAborted, captureViewTransitionSkips) {
     return (event, hint) => {
         // Integration health: a verification error carries its own tag and context; they are
         // set before the app's beforeSend and restored after scrubbing (ids are not user data).
         const v = verificationOf(hint?.originalException);
+        const original = hint?.originalException;
+        // A skipped View Transition is the standard working as designed (spec 03 §8).
+        if (!v && !captureViewTransitionSkips && isViewTransitionSkip(original))
+            return null;
         // Cancelled by the client: expected, dropped before the app's hook (not a diagnostic).
-        if (!v && !captureAborted && isClientAbort(hint?.originalException))
+        // An opted-in View Transition skip is reported even though it is an AbortError.
+        if (!v && !captureAborted && isClientAbort(original) && !(captureViewTransitionSkips && isViewTransitionSkip(original)))
             return null;
         const mark = (e) => {
             if (!v)
@@ -110,6 +117,10 @@ export function buildEngineOptions(opts, runtime, send) {
         return null;
     }
     const attachments = opts.attachments === true;
+    const otel = otelApiOf(opts.otel);
+    // One owner of propagation: with OpenTelemetry present, Belvador adds no headers of its own.
+    if (otel && opts.tracePropagation)
+        reportDiagnostic("BLV_TRACE_OWNER_OTEL");
     return {
         dsn: opts.dsn,
         release: typeof opts.release === "string" && opts.release ? opts.release : undefined,
@@ -127,12 +138,16 @@ export function buildEngineOptions(opts, runtime, send) {
         // Never read SENTRY_TUNNEL / spotlight from the environment; events go only to the DSN.
         tunnel: "",
         spotlight: false,
-        beforeSend: chainBeforeSend(opts.beforeSend, opts.captureAborted === true),
+        beforeSend: chainBeforeSend(opts.beforeSend, opts.captureAborted === true, opts.captureViewTransitionSkips === true),
         beforeBreadcrumb: chainBeforeBreadcrumb(opts.beforeBreadcrumb),
         beforeSendTransaction: () => null,
         defaultIntegrations: false,
         transport: makeBelvadorTransport({ ...send, attachments, debug: opts.debug === true }),
         [BELVADOR_MARKER]: true,
+        // Checked trace propagation of this client (null = off); the engine itself never adds headers.
+        [TRACE_OPTION]: otel ? null : traceConfigOf(opts.tracePropagation),
+        // The checked `@opentelemetry/api` of this client (null = no bridge); runtimes add the integration.
+        [OTEL_OPTION]: otel,
         _metadata: {
             sdk: {
                 name: sdkName,

package/dist/otel.d.ts

@@ -0,0 +1,31 @@
+import type { Integration } from "@sentry/core";
+/** The part of `@opentelemetry/api` the bridge reads (structural, any 1.x version fits). */
+export type OtelApiLike = {
+    trace: {
+        getActiveSpan(): {
+            spanContext(): {
+                traceId: string;
+                spanId: string;
+            };
+        } | undefined;
+    };
+};
+export type OtelOptions = {
+    /** `import * as api from "@opentelemetry/api"` — the same copy your OpenTelemetry SDK uses. */
+    api: OtelApiLike;
+};
+/** Engine-options key carrying the checked API of one client (null = bridge off). */
+export declare const OTEL_OPTION = "_belvadorOtel";
+/** The API when it looks like `@opentelemetry/api`, else null (a wrong value is reported). */
+export declare function otelApiOf(opts: OtelOptions | undefined): OtelApiLike | null;
+/** Ids of the active OpenTelemetry span, or null (none, invalid, all-zero, or the API threw). */
+export declare function otelTraceContext(api: OtelApiLike): {
+    trace_id: string;
+    span_id: string;
+} | null;
+/**
+ * Stamps `contexts.trace` from the active span when the error is captured. `preprocessEvent`
+ * runs synchronously inside the capture call, while the app's span is still current; the
+ * engine keeps an event's own trace context over the scope's.
+ */
+export declare function otelBridgeIntegration(api: OtelApiLike): Integration;

package/dist/otel.js

@@ -0,0 +1,44 @@
+import { reportDiagnostic } from "./diagnostics.js";
+/** Engine-options key carrying the checked API of one client (null = bridge off). */
+export const OTEL_OPTION = "_belvadorOtel";
+/** The API when it looks like `@opentelemetry/api`, else null (a wrong value is reported). */
+export function otelApiOf(opts) {
+    if (!opts)
+        return null;
+    const api = opts.api;
+    if (typeof api?.trace?.getActiveSpan === "function")
+        return api;
+    reportDiagnostic("BLV_OTEL_INVALID");
+    return null;
+}
+// 32 + 16 lowercase hex, neither all zeros (W3C Trace Context invalid ids).
+const IDS = /^(?!0{32})[0-9a-f]{32}-(?!0{16})[0-9a-f]{16}$/;
+/** Ids of the active OpenTelemetry span, or null (none, invalid, all-zero, or the API threw). */
+export function otelTraceContext(api) {
+    try {
+        const c = api.trace.getActiveSpan()?.spanContext();
+        const ids = c ? `${c.traceId}-${c.spanId}`.toLowerCase() : "";
+        return IDS.test(ids) ? { trace_id: ids.slice(0, 32), span_id: ids.slice(33) } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Stamps `contexts.trace` from the active span when the error is captured. `preprocessEvent`
+ * runs synchronously inside the capture call, while the app's span is still current; the
+ * engine keeps an event's own trace context over the scope's.
+ */
+export function otelBridgeIntegration(api) {
+    return {
+        name: "BelvadorOtelBridge",
+        preprocessEvent(event) {
+            const ids = !event.type && otelTraceContext(api); // errors only
+            if (!ids)
+                return;
+            const trace = { ...event.contexts?.trace, ...ids };
+            delete trace.parent_span_id; // the scope's parent is not this span's parent
+            event.contexts = { ...event.contexts, trace };
+        },
+    };
+}

package/dist/privacy.d.ts

@@ -4,7 +4,7 @@ export declare const SENSITIVE_KEY_PARTS: readonly string[];
 export declare function isSensitiveKey(key: string): boolean;
 /** Credentials in URLs and `name=value` text: userinfo removed, sensitive parameter values filtered. */
 export declare function scrubParams(text: string): string;
-/** Every rule for free text: parameters, tokens, card numbers, emails. */
+/** Every rule for free text: assignments, parameters, tokens, card numbers, emails. */
 export declare function scrubText(text: string): string;
 /**
  * Bounded deep copy with every rule applied: sensitive keys → [Filtered],

package/dist/privacy.js

@@ -86,8 +86,15 @@ const EMAIL = /\b[A-Za-z0-9._%+-]{1,64}@([A-Za-z0-9-]{1,63}(?:\.[A-Za-z0-9-]{1,6
 const USERINFO = /\b([a-z][a-z0-9+.-]{1,15}:\/\/)[^\s/?#@]+@/gi;
 /** name=value inside URLs, query strings and log lines. */
 const PARAM = /([A-Za-z0-9_.~%[\]-]{1,128})=([^&#\s"'<>,;]*)/g;
-/** "name": "value" inside JSON-looking text. */
-const JSON_PAIR = /"([^"\\]{1,128})"(\s*:\s*)"(?:[^"\\]|\\.)*"/g;
+/** `Basic <base64>` credentials in headers and log lines. */
+const BASIC_AUTH = /\bBasic\s+[A-Za-z0-9+/]{8,}={0,2}/g;
+/** "name": "value" / 'name': 'value' inside JSON- or dict-looking text (bounded, linear). */
+const QUOTED_ASSIGNMENT = /(["'])([^"'\\\n]{1,128})\1([ \t]{0,8}:[ \t]{0,8})(?:"((?:[^"\\\n]|\\.){0,1024})"|'((?:[^'\\\n]|\\.){0,1024})')/g;
+/**
+ * name=value, name => value and name: value in log lines; the value is one quoted string
+ * or one bare token. The name must not continue a longer word (the leading group).
+ */
+const ASSIGNMENT = /(^|[^A-Za-z0-9_.~%[\]-])([A-Za-z0-9_.~%[\]-]{1,128})([ \t]{0,8}(?:=>|=|:)[ \t]{0,8})("(?:[^"\\]|\\.){0,1024}"|'(?:[^'\\]|\\.){0,1024}'|[^\s&#"'<>,;{}()]{1,1024})/g;
 export function isSensitiveKey(key) {
     const lower = key.toLowerCase();
     for (const part of SENSITIVE_KEY_PARTS)
@@ -122,14 +129,27 @@ function luhn(digits) {
 export function scrubParams(text) {
     return text
         .replace(USERINFO, `$1${FILTERED}@`)
-        .replace(PARAM, (match, name) => isSensitiveKey(decodeName(name)) ? `${name}=${FILTERED}` : match);
+        // An empty value hides nothing (and a quoted value is left to the assignment rule).
+        .replace(PARAM, (match, name, value) => value !== "" && isSensitiveKey(decodeName(name)) ? `${name}=${FILTERED}` : match);
 }
-/** Every rule for free text: parameters, tokens, card numbers, emails. */
+/** Every rule for free text: assignments, parameters, tokens, card numbers, emails. */
 export function scrubText(text) {
     if (text.length === 0)
         return text;
     return scrubParams(text)
-        .replace(JSON_PAIR, (match, name, sep) => isSensitiveKey(name) ? `"${name}"${sep}"${FILTERED}"` : match)
+        .replace(BASIC_AUTH, `Basic ${FILTERED}`)
+        .replace(QUOTED_ASSIGNMENT, (match, q, name, sep, dq) => {
+        if (!isSensitiveKey(name))
+            return match;
+        const vq = dq !== undefined ? '"' : "'";
+        return `${q}${name}${q}${sep}${vq}${FILTERED}${vq}`;
+    })
+        .replace(ASSIGNMENT, (match, lead, name, sep, value) => {
+        if (!isSensitiveKey(decodeName(name)) || value === FILTERED)
+            return match;
+        const q = value[0] === '"' || value[0] === "'" ? value[0] : "";
+        return `${lead}${name}${sep}${q}${FILTERED}${q}`;
+    })
         .replace(BEARER, `Bearer ${FILTERED}`)
         .replace(PROVIDER_KEY, FILTERED)
         .replace(JWT, FILTERED)
@@ -348,6 +368,25 @@ export function scrubBreadcrumb(crumb) {
         return null;
     }
 }
+// W3C trace/span ids are random hex, not personal data; an all-digit span id can look like a
+// card number, so exact-format ids under `contexts.trace` survive (parity with the node).
+const HEX = /^[0-9a-f]+$/;
+function scrubContexts(contexts) {
+    const out = scrubValue(contexts, 0);
+    try {
+        const t = contexts.trace;
+        if (t && out?.trace && typeof out.trace === "object")
+            for (const k of ["trace_id", "span_id", "parent_span_id"]) {
+                const id = t[k];
+                if (typeof id === "string" && id.length === (k === "trace_id" ? 32 : 16) && HEX.test(id))
+                    out.trace[k] = id;
+            }
+    }
+    catch {
+        /* a throwing getter: keep the scrubbed copy */
+    }
+    return out;
+}
 /**
  * Whole-event scrub, run after the app's own `beforeSend` and before any byte
  * leaves the app. Returns a new event, or null (drop) when scrubbing fails —
@@ -370,6 +409,8 @@ export function scrubEvent(event) {
                 next = scrubUser(v);
             else if (key === "exception")
                 next = scrubException(v);
+            else if (key === "contexts")
+                next = scrubContexts(v);
             else if (key === "breadcrumbs")
                 next = Array.isArray(v)
                     ? v.flatMap((b) => {

package/dist/trace.d.ts

@@ -0,0 +1,32 @@
+export type TracePropagationOptions = {
+    /** URLs (substring) or RegExps; relative patterns match same-origin paths in browsers. Empty = off. */
+    targets?: Array<string | RegExp>;
+    /** Also send `baggage` (only the engine's `sentry-*` keys). Default false. */
+    baggage?: boolean;
+};
+export type TraceConfig = {
+    targets: Array<string | RegExp>;
+    baggage: boolean;
+};
+/** Engine-options key carrying the checked config of one client. */
+export declare const TRACE_OPTION = "_belvadorTrace";
+/** Valid targets only (others reported once a minute); null = propagation off. */
+export declare function traceConfigOf(opts: TracePropagationOptions | undefined): TraceConfig | null;
+/** W3C `traceparent` → `sentry-trace` (sampling left to the receiver), or null when invalid. */
+export declare function sentryTraceFromTraceparent(value: string | null | undefined): string | null;
+/**
+ * Server side: a request carrying a valid `traceparent` but no `sentry-trace` gets the
+ * equivalent `sentry-trace`, so the engine continues the same trace. Anything else is
+ * returned unchanged (same object).
+ */
+export declare function withIncomingTraceparent<R extends Request>(request: R): R;
+/** Sentry's rule: the whole URL, or (browsers) the path of a same-origin URL. */
+export declare function urlMatches(url: string, targets: ReadonlyArray<string | RegExp>): boolean;
+/**
+ * The current trace as headers: the active span's ids when there is one (a server request),
+ * else the scope's trace with a fresh span id. Errors-only, so the sampling flag is never set
+ * (`traceparent` flags 00, `sentry-trace` without the third part): the receiver decides.
+ */
+export declare function traceHeaders(baggage: boolean): Record<string, string> | null;
+/** Installs the fetch hook once per process; each client decides with its own config. */
+export declare function installTracePropagation(): void;

package/dist/trace.js

@@ -0,0 +1,184 @@
+// Trace propagation (build observability-1.0 spec 06 §5, SEC-ING-22): off by default.
+// Requests to the app's own targets get `traceparent` (W3C, flags 00 — nothing sampled)
+// and `sentry-trace`; `baggage` only when asked for. Errors-only: no spans, no
+// transactions. Incoming `traceparent` is read on the server so one trace id links
+// the browser error, the server error and the job's check-ins.
+import { addFetchInstrumentationHandler, dynamicSamplingContextToSentryBaggageHeader, generateSpanId, getActiveSpan, getClient, getCurrentScope, getDynamicSamplingContextFromScope, isMatchingPattern, spanToTraceContext, } from "@sentry/core";
+import { reportDiagnostic } from "./diagnostics.js";
+/** Engine-options key carrying the checked config of one client. */
+export const TRACE_OPTION = "_belvadorTrace";
+/** Valid targets only (others reported once a minute); null = propagation off. */
+export function traceConfigOf(opts) {
+    try {
+        if (!opts || !Array.isArray(opts.targets))
+            return null;
+        const targets = [];
+        for (const t of opts.targets) {
+            if ((typeof t === "string" && t.length > 0) || t instanceof RegExp)
+                targets.push(t);
+            else
+                reportDiagnostic("BLV_TRACE_TARGET_INVALID");
+        }
+        return targets.length ? { targets, baggage: opts.baggage === true } : null;
+    }
+    catch {
+        return null;
+    }
+}
+const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/;
+const SENTRY_TRACE = /^[0-9a-f]{32}-[0-9a-f]{16}(-[01])?$/;
+/** W3C `traceparent` → `sentry-trace` (sampling left to the receiver), or null when invalid. */
+export function sentryTraceFromTraceparent(value) {
+    if (typeof value !== "string")
+        return null;
+    const m = TRACEPARENT.exec(value.trim().toLowerCase());
+    if (!m || /^0+$/.test(m[1]) || /^0+$/.test(m[2]))
+        return null;
+    return `${m[1]}-${m[2]}`;
+}
+/**
+ * Server side: a request carrying a valid `traceparent` but no `sentry-trace` gets the
+ * equivalent `sentry-trace`, so the engine continues the same trace. Anything else is
+ * returned unchanged (same object).
+ */
+export function withIncomingTraceparent(request) {
+    try {
+        if (!request || typeof request.headers?.get !== "function")
+            return request;
+        const existing = request.headers.get("sentry-trace");
+        if (existing && SENTRY_TRACE.test(existing.trim()))
+            return request;
+        const converted = sentryTraceFromTraceparent(request.headers.get("traceparent"));
+        if (!converted)
+            return request;
+        const headers = new Headers(request.headers);
+        headers.set("sentry-trace", converted);
+        // Never trust an incoming baggage without its sentry-trace (it would set sampling).
+        headers.delete("baggage");
+        return new Request(request, { headers });
+    }
+    catch {
+        return request;
+    }
+}
+function originOf() {
+    try {
+        const loc = globalThis.location;
+        return typeof loc?.href === "string" ? loc.href : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Sentry's rule: the whole URL, or (browsers) the path of a same-origin URL. */
+export function urlMatches(url, targets) {
+    const test = (s) => targets.some((t) => isMatchingPattern(s, t, false));
+    if (test(url))
+        return true;
+    const base = originOf();
+    if (!base)
+        return false;
+    try {
+        const resolved = new URL(url, base);
+        const page = new URL(base);
+        if (resolved.origin !== page.origin)
+            return false;
+        return test(resolved.href) || test(resolved.pathname);
+    }
+    catch {
+        return false;
+    }
+}
+function clientConfig() {
+    try {
+        const client = getClient();
+        const cfg = client?.getOptions()?.[TRACE_OPTION];
+        if (!client || !cfg)
+            return null;
+        const dsn = client.getDsn();
+        const ingestOrigin = dsn ? `${dsn.protocol}://${dsn.host}${dsn.port ? `:${dsn.port}` : ""}` : "";
+        return { cfg, ingestOrigin };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The current trace as headers: the active span's ids when there is one (a server request),
+ * else the scope's trace with a fresh span id. Errors-only, so the sampling flag is never set
+ * (`traceparent` flags 00, `sentry-trace` without the third part): the receiver decides.
+ */
+export function traceHeaders(baggage) {
+    const scope = getCurrentScope();
+    const span = getActiveSpan();
+    const ctx = span ? spanToTraceContext(span) : null;
+    const pc = scope.getPropagationContext();
+    const traceId = ctx?.trace_id ?? pc.traceId;
+    const spanId = ctx?.span_id ?? pc.propagationSpanId ?? generateSpanId();
+    if (!/^[0-9a-f]{32}$/.test(traceId) || !/^[0-9a-f]{16}$/.test(spanId))
+        return null;
+    const out = {
+        "sentry-trace": `${traceId}-${spanId}`,
+        traceparent: `00-${traceId}-${spanId}-00`,
+    };
+    if (baggage) {
+        const client = getClient();
+        const header = client
+            ? dynamicSamplingContextToSentryBaggageHeader(getDynamicSamplingContextFromScope(client, scope))
+            : undefined;
+        if (header)
+            out["baggage"] = header;
+    }
+    return out;
+}
+function addHeaders(data, cfg) {
+    const trace = traceHeaders(cfg.baggage);
+    const sentryTrace = trace?.["sentry-trace"];
+    if (!trace || !sentryTrace)
+        return;
+    const input = data.args[0];
+    const init = { ...(data.args[1] ?? {}) };
+    const from = init["headers"] ??
+        (typeof Request !== "undefined" && input instanceof Request ? input.headers : undefined);
+    const headers = new Headers(from);
+    if (!headers.has("sentry-trace"))
+        headers.set("sentry-trace", sentryTrace);
+    if (trace["traceparent"] && !headers.has("traceparent"))
+        headers.set("traceparent", trace["traceparent"]);
+    if (cfg.baggage && trace["baggage"] && !headers.has("baggage"))
+        headers.set("baggage", trace["baggage"]);
+    init["headers"] = headers;
+    data.args[1] = init;
+}
+let installed = false;
+/** Installs the fetch hook once per process; each client decides with its own config. */
+export function installTracePropagation() {
+    if (installed)
+        return;
+    installed = true;
+    try {
+        addFetchInstrumentationHandler((data) => {
+            try {
+                const d = data;
+                if (d.endTimestamp || !d.fetchData)
+                    return;
+                const c = clientConfig();
+                if (!c)
+                    return;
+                const url = d.fetchData.url;
+                // Never on the SDK's own sends.
+                if (c.ingestOrigin && url.startsWith(c.ingestOrigin))
+                    return;
+                if (!urlMatches(url, c.cfg.targets))
+                    return;
+                addHeaders(d, c.cfg);
+            }
+            catch {
+                /* a request is never broken by tracing */
+            }
+        });
+    }
+    catch {
+        installed = false;
+    }
+}

package/dist/transport.d.ts

@@ -14,6 +14,8 @@ export declare const SEND_LIMITS: {
 };
 /** Item types the node stores (audit §2); everything else never leaves the app. */
 export declare const SENT_ITEM_TYPES: readonly string[];
+/** Of the 30 queued sends, check-ins take at most this many (spec 06 §4): neither storm starves the other. */
+export declare const MAX_QUEUED_CHECK_INS = 10;
 export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
 export type SendPolicy = {
     attachments: boolean;
@@ -31,6 +33,8 @@ export type SendState = {
     keepaliveCount: number;
     /** Epoch ms until which the edge asked us to wait (429), for diagnostics. */
     rateLimitedUntil?: number;
+    /** Check-in envelopes waiting or in flight (≤ MAX_QUEUED_CHECK_INS). */
+    checkIns?: number;
 };
 /** Integration health spec 02 §2.1: what one HTTP answer means for the app. */
 export declare function diagnosticForStatus(status: number): DiagnosticCode | null;

package/dist/transport.js

@@ -18,7 +18,9 @@ export const SEND_LIMITS = {
     maxRetryAfterMs: 60000,
 };
 /** Item types the node stores (audit §2); everything else never leaves the app. */
-export const SENT_ITEM_TYPES = ["event", "client_report", "attachment"];
+export const SENT_ITEM_TYPES = ["event", "client_report", "attachment", "check_in"];
+/** Of the 30 queued sends, check-ins take at most this many (spec 06 §4): neither storm starves the other. */
+export const MAX_QUEUED_CHECK_INS = 10;
 const RETRY_STATUS = new Set([500, 502, 503, 504]);
 const STOP_STATUS = new Set([401, 403]);
 // Browsers cap keepalive bodies at 64 KiB in flight (fetch spec); stay below it.
@@ -179,6 +181,14 @@ export async function sendWithRetry(fetchImpl, url, init, state, sleep = default
             throw new Error("aborted");
     }
 }
+function isCheckInEnvelope(envelope) {
+    let found = false;
+    forEachEnvelopeItem(envelope, (_item, type) => {
+        if (type === "check_in")
+            found = true;
+    });
+    return found;
+}
 /** Keeps only item types the node stores; reports the rest as dropped. */
 export function filterEnvelope(envelope, policy, record) {
     const kept = [];
@@ -213,6 +223,7 @@ export function makeBelvadorTransport(policy) {
             keepaliveBytes: 0,
             keepaliveCount: 0,
             rateLimitedUntil: 0,
+            checkIns: 0,
         };
         const fetchImpl = policy.fetch ?? globalThis.fetch.bind(globalThis);
         const maxEnvelope = policy.attachments
@@ -297,15 +308,25 @@ export function makeBelvadorTransport(policy) {
                         fail("BLV_EVENT_TOO_LARGE");
                         return Promise.resolve({});
                     }
+                    const checkIn = isCheckInEnvelope(kept);
+                    if (checkIn && (state.checkIns ?? 0) >= MAX_QUEUED_CHECK_INS) {
+                        recordAll(kept, "queue_overflow", options.recordDroppedEvent);
+                        reportDiagnostic("BLV_CHECK_IN_DROPPED");
+                        return Promise.resolve({});
+                    }
                     if (state.queuedBytes + size > maxQueued) {
                         recordAll(kept, "queue_overflow", options.recordDroppedEvent);
-                        reportDiagnostic("BLV_QUEUE_FULL");
+                        reportDiagnostic(checkIn ? "BLV_CHECK_IN_DROPPED" : "BLV_QUEUE_FULL");
                         fail("BLV_QUEUE_FULL");
                         return Promise.resolve({});
                     }
                     state.queuedBytes += size;
+                    if (checkIn)
+                        state.checkIns = (state.checkIns ?? 0) + 1;
                     const release = () => {
                         state.queuedBytes -= size;
+                        if (checkIn)
+                            state.checkIns = Math.max(0, (state.checkIns ?? 1) - 1);
                     };
                     const settle = (r) => {
                         if (verifications.length === 0)
@@ -326,6 +347,9 @@ export function makeBelvadorTransport(policy) {
                     return Promise.resolve(inner.send(kept)).then((r) => {
                         release();
                         settle(r);
+                        // Rate limited (category `monitor`) or lost: the job is fine, the check-in is not.
+                        if (checkIn && (typeof r.statusCode !== "number" || r.statusCode >= 400))
+                            reportDiagnostic("BLV_CHECK_IN_DROPPED");
                         return r;
                     }, () => {
                         release();

package/dist/version.d.ts

@@ -1,3 +1,3 @@
-export declare const SDK_VERSION = "0.2.0";
+export declare const SDK_VERSION = "0.4.0";
 /** The audited engine version every package pins exactly (research/05-decisions.md D3). */
 export declare const ENGINE_VERSION = "10.76.2";

package/dist/version.js

@@ -1,6 +1,6 @@
 // One version for every @belvador/* package (lockstep). Changed only by
 // `bun scripts/set-version.ts`; tests compare it with every package.json and
 // with src/content/sdk-matrix.ts in the web app.
-export const SDK_VERSION = "0.2.0";
+export const SDK_VERSION = "0.4.0";
 /** The audited engine version every package pins exactly (research/05-decisions.md D3). */
 export const ENGINE_VERSION = "10.76.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@belvador/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Internal building blocks of the Belvador SDK (privacy, sending policy). Install @belvador/browser, @belvador/react, @belvador/cloudflare or @belvador/tanstack-start instead.",
   "license": "MIT",
   "author": "Belvador (https://belvador.dev)",