@belvador/core 0.3.0 → 0.4.0

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", "BLV_MONITOR_INVALID_SLUG", "BLV_MONITOR_INVALID_REASON", "BLV_MONITOR_CONFIG_INVALID", "BLV_CHECK_IN_DROPPED", "BLV_TRACE_TARGET_INVALID"];
+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

@@ -21,6 +21,8 @@ export const DIAGNOSTIC_CODES = [
     "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";
@@ -45,6 +47,8 @@ const MESSAGES = {
     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

@@ -2,6 +2,7 @@ export { SDK_VERSION, ENGINE_VERSION } from "./version.js";
 export { checkDsn, type BelvadorDsn } from "./dsn.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 { MAX_QUEUED_CHECK_INS, SEND_LIMITS, SENT_ITEM_TYPES, filterEnvelope, makeBelvadorTransport, sendWithRetry, type FetchLike, type SendPolicy, type SendState, } from "./transport.js";

package/dist/index.js

@@ -5,6 +5,7 @@ export { SDK_VERSION, ENGINE_VERSION } from "./version.js";
 export { checkDsn } from "./dsn.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 { MAX_QUEUED_CHECK_INS, SEND_LIMITS, SENT_ITEM_TYPES, filterEnvelope, makeBelvadorTransport, sendWithRetry, } from "./transport.js";

package/dist/options.d.ts

@@ -1,5 +1,6 @@
 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;
@@ -39,6 +40,12 @@ export type BelvadorOptions = {
      * (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. */
@@ -86,6 +93,7 @@ export declare function buildEngineOptions(opts: BelvadorOptions, runtime: Runti
     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

@@ -3,6 +3,7 @@ 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";
@@ -116,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,
@@ -140,7 +145,9 @@ export function buildEngineOptions(opts, runtime, send) {
         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]: traceConfigOf(opts.tracePropagation),
+        [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.js

@@ -368,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 —
@@ -390,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/version.d.ts

@@ -1,3 +1,3 @@
-export declare const SDK_VERSION = "0.3.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.3.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.3.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)",