@belvador/core 0.1.0 → 0.2.0

package/dist/aborts.d.ts

@@ -0,0 +1,10 @@
+/** Errors whose own name, or whose direct cause's name, is "AbortError". */
+export declare function isAbortError(error: unknown): boolean;
+/**
+ * Called by Belvador's server middleware and Worker wrapper when a request fails after its
+ * client went away (`request.signal.aborted`): whatever was thrown is then treated as an
+ * abort, even when it is not named AbortError (stream "terminated", "aborted", …).
+ */
+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;

package/dist/aborts.js

@@ -0,0 +1,41 @@
+// Client-cancelled work is expected, not a failure (integration-health 05-decisions,
+// Supaclip finding): a user who closes the tab or navigates away aborts in-flight
+// requests, and the server code serving them throws. These are dropped by default;
+// `captureAborted: true` reports them again. Imports nothing (runs in every runtime).
+/** Errors whose own name, or whose direct cause's name, is "AbortError". */
+export function isAbortError(error) {
+    try {
+        if (nameOf(error) === "AbortError")
+            return true;
+        if (error !== null && typeof error === "object" && "cause" in error)
+            return nameOf(error.cause) === "AbortError";
+    }
+    catch {
+        /* a hostile getter: not an abort */
+    }
+    return false;
+}
+function nameOf(value) {
+    return value !== null && typeof value === "object" ? value.name : undefined;
+}
+const clientAborted = new WeakSet();
+/**
+ * Called by Belvador's server middleware and Worker wrapper when a request fails after its
+ * client went away (`request.signal.aborted`): whatever was thrown is then treated as an
+ * abort, even when it is not named AbortError (stream "terminated", "aborted", …).
+ */
+export function noteClientAbort(error, signal) {
+    try {
+        if (signal?.aborted === true && error !== null && typeof error === "object")
+            clientAborted.add(error);
+    }
+    catch {
+        /* never throws into the app */
+    }
+}
+/** True for an AbortError or an error thrown while its request's client had gone. */
+export function isClientAbort(error) {
+    if (isAbortError(error))
+        return true;
+    return error !== null && typeof error === "object" && clientAborted.has(error);
+}

package/dist/constants.d.ts

@@ -0,0 +1,15 @@
+/** Reserved tag key; its value is the verification id. */
+export declare const VERIFICATION_TAG = "belvador.verification";
+/** Context the SDK adds to a verification event. */
+export declare const VERIFICATION_CONTEXT = "belvador_verification";
+/** Exception type a verification captures or throws. */
+export declare const VERIFICATION_ERROR_TYPE = "BelvadorVerificationError";
+/** `bv1_` + 32 lowercase hex. */
+export declare const VERIFICATION_ID_RE: RegExp;
+export declare const VERIFY_LIMITS: {
+    readonly timeoutDefaultMs: 20000;
+    readonly timeoutMaxMs: 30000;
+    readonly readbackMaxRequests: 10;
+    /** Waits between read-backs; the last value repeats. */
+    readonly readbackDelaysMs: readonly number[];
+};

package/dist/constants.js

@@ -0,0 +1,18 @@
+// Integration-health wire constants (build integration-health-1.0 spec 01/02), a copy
+// of `src/shared/contracts/integration-health.ts` that a root test keeps equal.
+// Imports nothing.
+/** Reserved tag key; its value is the verification id. */
+export const VERIFICATION_TAG = "belvador.verification";
+/** Context the SDK adds to a verification event. */
+export const VERIFICATION_CONTEXT = "belvador_verification";
+/** Exception type a verification captures or throws. */
+export const VERIFICATION_ERROR_TYPE = "BelvadorVerificationError";
+/** `bv1_` + 32 lowercase hex. */
+export const VERIFICATION_ID_RE = /^bv1_[0-9a-f]{32}$/;
+export const VERIFY_LIMITS = {
+    timeoutDefaultMs: 20000,
+    timeoutMaxMs: 30000,
+    readbackMaxRequests: 10,
+    /** Waits between read-backs; the last value repeats. */
+    readbackDelaysMs: [1000, 2000, 3000, 4000, 5000],
+};

package/dist/diagnostics.d.ts

@@ -0,0 +1,60 @@
+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 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";
+/** One callback/console line per code per interval; repeats add to `count`. */
+export declare const DIAGNOSTIC_INTERVAL_MS = 60000;
+export type Diagnostic = {
+    code: DiagnosticCode;
+    /** Epoch ms of this report. */
+    at: number;
+    /** Occurrences since the previous report of this code (≥ 1). */
+    count: number;
+    /** HTTP status of the send, when there was one. */
+    status?: number;
+    /** Seconds the edge asked to wait (429). */
+    retryAfterS?: number;
+};
+export type DiagnosticsSnapshot = {
+    active: boolean;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    /** Host, project and the first 4 characters of the key — never the whole DSN. */
+    dsn: {
+        host: string;
+        project: number;
+        keyHint: string;
+    } | null;
+    lastSend: {
+        status: number | "network";
+        at: number;
+    } | null;
+    counts: Partial<Record<DiagnosticCode, number>>;
+};
+type Config = {
+    onDiagnostic: ((d: Diagnostic) => void) | undefined;
+    debug: boolean;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    dsn: DiagnosticsSnapshot["dsn"];
+};
+/** Anchor on the verification page for one code. */
+export declare function diagnosticDocsUrl(code: DiagnosticCode): string;
+export declare function diagnosticMessage(code: DiagnosticCode): string;
+/** Set by init (and by every Worker invocation). Never throws. */
+export declare function configureDiagnostics(next: Partial<Config>): void;
+/** Records one occurrence; reports at most once per code per minute (NOT_INITIALIZED once). */
+export declare function reportDiagnostic(code: DiagnosticCode, extra?: {
+    status?: number;
+    retryAfterS?: number;
+}, now?: number): void;
+export declare function noteSend(status: number | "network", now?: number): void;
+/** Fixed-size snapshot for support and AI agents; contains no event data. */
+export declare function snapshotDiagnostics(active: boolean): DiagnosticsSnapshot;
+/** Tests only: forget every count and setting. */
+export declare function resetDiagnostics(): void;
+export {};

package/dist/diagnostics.js

@@ -0,0 +1,129 @@
+// Local diagnostics (build integration-health-1.0 spec 02 §2): what went wrong in
+// this app, said once per minute per code, never sent anywhere. The code list is a
+// copy of `src/shared/contracts/integration-health.ts`; a root test keeps them equal.
+// Imports nothing.
+export const DIAGNOSTIC_CODES = [
+    "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",
+];
+/** Public page explaining every code and the verification (one anchor per code). */
+export const VERIFY_DOCS_URL = "https://belvador.dev/en/docs/sdk/verify";
+/** One callback/console line per code per interval; repeats add to `count`. */
+export const DIAGNOSTIC_INTERVAL_MS = 60000;
+const MESSAGES = {
+    BLV_DSN_MISSING: "no DSN — the SDK is off",
+    BLV_DSN_INVALID: "the DSN is not valid — the SDK is off",
+    BLV_INIT_CONFLICT: "another error-tracking client is already running — init skipped",
+    BLV_NOT_INITIALIZED: "capture called while the SDK is not running",
+    BLV_SEND_UNAUTHORIZED: "the DSN key was refused (revoked or wrong project) — sending stopped",
+    BLV_SEND_RATE_LIMITED: "rate limited by Belvador — events are dropped until the wait ends",
+    BLV_SEND_REJECTED: "an event was rejected (too large or not accepted)",
+    BLV_SEND_NETWORK: "Belvador could not be reached after retries (network, CSP or ad blocker)",
+    BLV_SEND_SERVER: "Belvador answered with a server error after retries",
+    BLV_QUEUE_FULL: "the send queue is full — an event was dropped",
+    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)",
+};
+const config = {
+    onDiagnostic: undefined,
+    debug: false,
+    sdk: { name: "", version: "" },
+    dsn: null,
+};
+const perCode = new Map();
+let lastSend = null;
+/** Anchor on the verification page for one code. */
+export function diagnosticDocsUrl(code) {
+    return `${VERIFY_DOCS_URL}#${code.toLowerCase().replace(/_/g, "-")}`;
+}
+export function diagnosticMessage(code) {
+    return MESSAGES[code];
+}
+/** Set by init (and by every Worker invocation). Never throws. */
+export function configureDiagnostics(next) {
+    try {
+        Object.assign(config, next);
+    }
+    catch {
+        /* frozen input */
+    }
+}
+function emit(d) {
+    const cb = config.onDiagnostic;
+    if (cb) {
+        try {
+            cb({ ...d });
+        }
+        catch {
+            /* a failing callback never reaches the app or the SDK */
+        }
+    }
+    if (config.debug) {
+        try {
+            console.warn(`[belvador] ${d.code}: ${MESSAGES[d.code]} — ${diagnosticDocsUrl(d.code)}`);
+        }
+        catch {
+            /* no console */
+        }
+    }
+}
+/** Records one occurrence; reports at most once per code per minute (NOT_INITIALIZED once). */
+export function reportDiagnostic(code, extra = {}, now = Date.now()) {
+    try {
+        const s = perCode.get(code) ?? { last: -Infinity, pending: 0, total: 0 };
+        s.total++;
+        s.pending++;
+        perCode.set(code, s);
+        const once = code === "BLV_NOT_INITIALIZED";
+        if (once ? s.total > 1 : now - s.last < DIAGNOSTIC_INTERVAL_MS)
+            return;
+        const d = { code, at: now, count: s.pending };
+        if (extra.status !== undefined)
+            d.status = extra.status;
+        if (extra.retryAfterS !== undefined)
+            d.retryAfterS = extra.retryAfterS;
+        s.last = now;
+        s.pending = 0;
+        emit(d);
+    }
+    catch {
+        /* never throws */
+    }
+}
+export function noteSend(status, now = Date.now()) {
+    lastSend = { status, at: now };
+}
+/** Fixed-size snapshot for support and AI agents; contains no event data. */
+export function snapshotDiagnostics(active) {
+    const counts = {};
+    for (const [code, s] of perCode)
+        counts[code] = s.total;
+    return {
+        active,
+        sdk: { ...config.sdk },
+        dsn: config.dsn ? { ...config.dsn } : null,
+        lastSend: lastSend ? { ...lastSend } : null,
+        counts,
+    };
+}
+/** Tests only: forget every count and setting. */
+export function resetDiagnostics() {
+    perCode.clear();
+    lastSend = null;
+    config.onDiagnostic = undefined;
+    config.debug = false;
+    config.sdk = { name: "", version: "" };
+    config.dsn = null;
+}

package/dist/facade.d.ts

@@ -1,7 +1,10 @@
 import type { Breadcrumb, ExclusiveEventHintOrCaptureContext, Scope, SeverityLevel } from "@sentry/core";
+import { type DiagnosticsSnapshot } from "./diagnostics.js";
 export type { Scope, SeverityLevel };
 /** True when the current scope's client was set up by a Belvador `init`. */
 export declare function isActive(): boolean;
+/** Local diagnostics snapshot (integration-health spec 02 §2.2); no event data. */
+export declare function getDiagnostics(): DiagnosticsSnapshot;
 /** Returns the event id (not a delivery receipt); "" when the SDK is off. */
 export declare function captureException(error: unknown, context?: ExclusiveEventHintOrCaptureContext): string;
 export declare function captureMessage(message: string, level?: SeverityLevel): string;

package/dist/facade.js

@@ -2,6 +2,7 @@
 // function is a no-op returning a neutral value when no Belvador client is
 // active, and never throws into the app.
 import { addBreadcrumb as engineAddBreadcrumb, captureException as engineCaptureException, captureMessage as engineCaptureMessage, close as engineClose, flush as engineFlush, getClient, lastEventId as engineLastEventId, setContext as engineSetContext, setTag as engineSetTag, setTags as engineSetTags, setUser as engineSetUser, withScope as engineWithScope, } from "@sentry/core";
+import { reportDiagnostic, snapshotDiagnostics } from "./diagnostics.js";
 import { BELVADOR_MARKER } from "./options.js";
 /** True when the current scope's client was set up by a Belvador `init`. */
 export function isActive() {
@@ -13,6 +14,10 @@ export function isActive() {
         return false;
     }
 }
+/** Local diagnostics snapshot (integration-health spec 02 §2.2); no event data. */
+export function getDiagnostics() {
+    return snapshotDiagnostics(isActive());
+}
 function guard(fallback, fn) {
     if (!isActive())
         return fallback;
@@ -25,9 +30,13 @@ function guard(fallback, fn) {
 }
 /** Returns the event id (not a delivery receipt); "" when the SDK is off. */
 export function captureException(error, context) {
+    if (!isActive())
+        reportDiagnostic("BLV_NOT_INITIALIZED");
     return guard("", () => engineCaptureException(error, context));
 }
 export function captureMessage(message, level) {
+    if (!isActive())
+        reportDiagnostic("BLV_NOT_INITIALIZED");
     return guard("", () => engineCaptureMessage(String(message), level));
 }
 export function addBreadcrumb(crumb) {

package/dist/index.d.ts

@@ -1,6 +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 { 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 { 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, isActive, lastEventId, setContext, setTag, setTags, setUser, withScope, type Scope, type SeverityLevel, } from "./facade.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";
+export { BelvadorVerificationError, VERIFICATION_CONTEXT, VERIFICATION_ERROR_TYPE, VERIFICATION_ID_RE, VERIFICATION_TAG, currentHooks, markHooked, newVerificationId, verificationOf, type HookKind, type VerificationContext, type VerificationSurface, } from "./verification.js";
+export { VERIFY_LIMITS, runVerification, type CheckName, type CheckStatus, type VerificationResult, type VerifyOptions, type VerifyRuntime, } from "./verify.js";
+export { diagnosticForStatus } from "./transport.js";

package/dist/index.js

@@ -3,7 +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 { 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 { BELVADOR_MARKER, DEFAULT_MAX_BREADCRUMBS, MAX_BREADCRUMBS, MAX_VALUE_LENGTH, buildEngineOptions, warnOnce, } from "./options.js";
-export { addBreadcrumb, captureException, captureMessage, close, flush, isActive, lastEventId, setContext, setTag, setTags, setUser, withScope, } from "./facade.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";
+export { BelvadorVerificationError, VERIFICATION_CONTEXT, VERIFICATION_ERROR_TYPE, VERIFICATION_ID_RE, VERIFICATION_TAG, currentHooks, markHooked, newVerificationId, verificationOf, } from "./verification.js";
+export { VERIFY_LIMITS, runVerification, } from "./verify.js";
+export { diagnosticForStatus } from "./transport.js";

package/dist/options.d.ts

@@ -1,4 +1,5 @@
 import type { Breadcrumb, BreadcrumbHint, ErrorEvent, EventHint } from "@sentry/core";
+import { type Diagnostic } from "./diagnostics.js";
 import { type SendPolicy } from "./transport.js";
 export type BelvadorEvent = ErrorEvent;
 export type BelvadorEventHint = EventHint;
@@ -19,12 +20,24 @@ export type BelvadorOptions = {
     /** Default 50, at most 100. */
     maxBreadcrumbs?: number;
     ignoreErrors?: Array<string | RegExp>;
+    /**
+     * Also report errors from work the client cancelled: an `AbortError` (fetch or stream
+     * aborted), or a server error thrown after the visitor closed the connection. Default
+     * false — cancellations are expected and never become issues. A `TimeoutError` is not
+     * a cancellation and is always reported.
+     */
+    captureAborted?: boolean;
     /** 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. */
     beforeSend?: (event: BelvadorEvent, hint: BelvadorEventHint) => BelvadorEvent | null | PromiseLike<BelvadorEvent | null>;
     /** Runs before Belvador's own scrubbing; return null to drop the breadcrumb. */
     beforeBreadcrumb?: (crumb: BelvadorBreadcrumb, hint?: BreadcrumbHint) => BelvadorBreadcrumb | null;
+    /**
+     * Local diagnostics (missing DSN, refused key, failed sends, …): at most once a
+     * minute per code, never sent anywhere. Errors thrown here are ignored.
+     */
+    onDiagnostic?: (diagnostic: Diagnostic) => void;
 };
 export type RuntimeName = "browser" | "react" | "cloudflare" | "tanstack-start";
 export declare const DEFAULT_MAX_BREADCRUMBS = 50;

package/dist/options.js

@@ -1,5 +1,8 @@
+import { isClientAbort } 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 { makeBelvadorTransport } from "./transport.js";
 import { ENGINE_VERSION, SDK_VERSION } from "./version.js";
 /** Engine package behind each runtime (for `sdk.packages`). */
@@ -30,19 +33,44 @@ 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) {
+function chainBeforeSend(user, captureAborted) {
     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);
+        // Cancelled by the client: expected, dropped before the app's hook (not a diagnostic).
+        if (!v && !captureAborted && isClientAbort(hint?.originalException))
+            return null;
+        const mark = (e) => {
+            if (!v)
+                return e;
+            e.tags = { ...(e.tags ?? {}), [VERIFICATION_TAG]: v.id };
+            e.contexts = { ...(e.contexts ?? {}), [VERIFICATION_CONTEXT]: { ...v.context } };
+            return e;
+        };
+        const finish = (e) => {
+            if (!e) {
+                if (v) {
+                    noteVerificationOutcome(v.id, v.context.check, { kind: "dropped" });
+                    reportDiagnostic("BLV_DROPPED_BY_APP");
+                }
+                return null;
+            }
+            // A scrubber failure drops the event (never sends it unscrubbed).
+            const clean = scrubEvent(e);
+            return clean ? mark(clean) : null;
+        };
         let out;
         try {
-            out = user ? user(event, hint) : event;
+            out = user ? user(mark(event), hint) : mark(event);
         }
         catch {
-            return null;
+            return finish(null);
         }
         if (out && typeof out.then === "function") {
-            return Promise.resolve(out).then((e) => (e ? scrubEvent(e) : null), () => null);
+            return Promise.resolve(out).then(finish, () => finish(null));
         }
-        return out ? scrubEvent(out) : null;
+        return finish(out);
     };
 }
 function chainBeforeBreadcrumb(user) {
@@ -63,9 +91,22 @@ function chainBeforeBreadcrumb(user) {
 export function buildEngineOptions(opts, runtime, send) {
     if (!opts || opts.disabled === true)
         return null;
+    const sdkName = `belvador.javascript.${runtime}`;
     const dsn = checkDsn(opts.dsn);
+    configureDiagnostics({
+        onDiagnostic: typeof opts.onDiagnostic === "function" ? opts.onDiagnostic : undefined,
+        debug: opts.debug === true,
+        sdk: { name: sdkName, version: SDK_VERSION },
+        dsn: dsn
+            ? { host: dsn.host, project: dsn.projectId, keyHint: dsn.publicKey.slice(0, 4) }
+            : null,
+    });
     if (!dsn) {
-        warnOnce("invalid DSN — the SDK is off. Copy the DSN from your Belvador project settings.");
+        const missing = typeof opts.dsn !== "string" || opts.dsn.trim() === "";
+        reportDiagnostic(missing ? "BLV_DSN_MISSING" : "BLV_DSN_INVALID");
+        warnOnce(missing
+            ? "no DSN — the SDK is off. Copy the DSN from your Belvador project settings."
+            : "invalid DSN — the SDK is off. Copy the DSN from your Belvador project settings.");
         return null;
     }
     const attachments = opts.attachments === true;
@@ -86,7 +127,7 @@ 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),
+        beforeSend: chainBeforeSend(opts.beforeSend, opts.captureAborted === true),
         beforeBreadcrumb: chainBeforeBreadcrumb(opts.beforeBreadcrumb),
         beforeSendTransaction: () => null,
         defaultIntegrations: false,
@@ -94,7 +135,7 @@ export function buildEngineOptions(opts, runtime, send) {
         [BELVADOR_MARKER]: true,
         _metadata: {
             sdk: {
-                name: `belvador.javascript.${runtime}`,
+                name: sdkName,
                 version: SDK_VERSION,
                 packages: [
                     { name: `npm:@belvador/${runtime}`, version: SDK_VERSION },

package/dist/transport.d.ts

@@ -1,4 +1,5 @@
 import type { BaseTransportOptions, Envelope, Transport } from "@sentry/core";
+import { type DiagnosticCode } from "./diagnostics.js";
 /** The numbers of `docs/build-sdk-1.0/rules.md` §2. */
 export declare const SEND_LIMITS: {
     readonly maxQueue: 30;
@@ -28,7 +29,11 @@ export type SendState = {
     queuedBytes: number;
     keepaliveBytes: number;
     keepaliveCount: number;
+    /** Epoch ms until which the edge asked us to wait (429), for diagnostics. */
+    rateLimitedUntil?: number;
 };
+/** Integration health spec 02 §2.1: what one HTTP answer means for the app. */
+export declare function diagnosticForStatus(status: number): DiagnosticCode | null;
 /**
  * One request with the retry policy: network errors and 500/502/503/504 are
  * retried up to 5 attempts (1/2/4/8 s; a 503 Retry-After ≤ 60 s is honoured),

package/dist/transport.js

@@ -3,6 +3,8 @@
 // One transport for every runtime, built on the engine's `createTransport`
 // (rate limits per category, client reports) with our own request executor.
 import { createEnvelope, createTransport, envelopeItemTypeToDataCategory, forEachEnvelopeItem, makePromiseBuffer, serializeEnvelope, suppressTracing, } from "@sentry/core";
+import { noteSend, reportDiagnostic } from "./diagnostics.js";
+import { noteVerificationOutcome, verificationOfEvent } from "./verification.js";
 /** The numbers of `docs/build-sdk-1.0/rules.md` §2. */
 export const SEND_LIMITS = {
     maxQueue: 30,
@@ -22,6 +24,31 @@ const STOP_STATUS = new Set([401, 403]);
 // Browsers cap keepalive bodies at 64 KiB in flight (fetch spec); stay below it.
 const KEEPALIVE_MAX_BYTES = 60000;
 const KEEPALIVE_MAX_COUNT = 15;
+/** Integration health spec 02 §2.1: what one HTTP answer means for the app. */
+export function diagnosticForStatus(status) {
+    if (status >= 200 && status < 300)
+        return null;
+    if (status === 401 || status === 403)
+        return "BLV_SEND_UNAUTHORIZED";
+    if (status === 429)
+        return "BLV_SEND_RATE_LIMITED";
+    if (status >= 500)
+        return "BLV_SEND_SERVER";
+    return "BLV_SEND_REJECTED";
+}
+/** Verification events in an envelope (id + check), read from tags and context. */
+function verificationsIn(envelope) {
+    const out = [];
+    forEachEnvelopeItem(envelope, (item, type) => {
+        if (type !== "event")
+            return;
+        const payload = item[1];
+        const v = payload && typeof payload === "object" ? verificationOfEvent(payload) : null;
+        if (v)
+            out.push(v);
+    });
+    return out;
+}
 function utf8Length(s) {
     let n = 0;
     for (let i = 0; i < s.length; i++) {
@@ -185,6 +212,7 @@ export function makeBelvadorTransport(policy) {
             queuedBytes: 0,
             keepaliveBytes: 0,
             keepaliveCount: 0,
+            rateLimitedUntil: 0,
         };
         const fetchImpl = policy.fetch ?? globalThis.fetch.bind(globalThis);
         const maxEnvelope = policy.attachments
@@ -209,11 +237,29 @@ export function makeBelvadorTransport(policy) {
                     ...(options.headers ? { headers: options.headers } : {}),
                     ...(policy.browser ? { referrerPolicy: "strict-origin", keepalive } : {}),
                 };
-                const res = await suppressTracing(() => sendWithRetry(fetchImpl, options.url, init, state, policy.sleep));
+                let res;
+                try {
+                    res = await suppressTracing(() => sendWithRetry(fetchImpl, options.url, init, state, policy.sleep));
+                }
+                catch (e) {
+                    noteSend("network");
+                    reportDiagnostic("BLV_SEND_NETWORK");
+                    throw e;
+                }
                 const headers = {
                     "x-sentry-rate-limits": res.headers.get("X-Sentry-Rate-Limits"),
                     "retry-after": res.headers.get("Retry-After"),
                 };
+                noteSend(res.status);
+                const code = diagnosticForStatus(res.status);
+                if (code === "BLV_SEND_RATE_LIMITED") {
+                    const after = retryAfterMs(res);
+                    const seconds = Math.round((after ?? 60000) / 1000);
+                    state.rateLimitedUntil = Date.now() + seconds * 1000;
+                    reportDiagnostic(code, { status: res.status, retryAfterS: seconds });
+                }
+                else if (code)
+                    reportDiagnostic(code, { status: res.status });
                 await discard(res);
                 return { statusCode: res.status, headers };
             }
@@ -228,29 +274,62 @@ export function makeBelvadorTransport(policy) {
         return {
             send(envelope) {
                 try {
-                    if (state.stopped)
+                    const verifications = verificationsIn(envelope);
+                    const fail = (code, status) => {
+                        for (const v of verifications)
+                            noteVerificationOutcome(v.id, v.check, {
+                                kind: "failed",
+                                code,
+                                ...(status !== undefined ? { status } : {}),
+                            });
+                    };
+                    if (state.stopped) {
+                        fail("BLV_SEND_UNAUTHORIZED");
                         return Promise.resolve({});
+                    }
                     const kept = filterEnvelope(envelope, policy, options.recordDroppedEvent);
                     if (!kept)
                         return Promise.resolve({});
                     const size = byteLength(serializeEnvelope(kept));
                     if (size > maxEnvelope) {
                         recordAll(kept, "send_error", options.recordDroppedEvent);
+                        reportDiagnostic("BLV_EVENT_TOO_LARGE");
+                        fail("BLV_EVENT_TOO_LARGE");
                         return Promise.resolve({});
                     }
                     if (state.queuedBytes + size > maxQueued) {
                         recordAll(kept, "queue_overflow", options.recordDroppedEvent);
+                        reportDiagnostic("BLV_QUEUE_FULL");
+                        fail("BLV_QUEUE_FULL");
                         return Promise.resolve({});
                     }
                     state.queuedBytes += size;
                     const release = () => {
                         state.queuedBytes -= size;
                     };
+                    const settle = (r) => {
+                        if (verifications.length === 0)
+                            return;
+                        const status = r.statusCode;
+                        if (typeof status !== "number") {
+                            // Dropped by the engine's rate limiter or lost on the network.
+                            fail(Date.now() < (state.rateLimitedUntil ?? 0) ? "BLV_SEND_RATE_LIMITED" : "BLV_SEND_NETWORK");
+                            return;
+                        }
+                        const code = diagnosticForStatus(status);
+                        if (code)
+                            fail(code, status);
+                        else
+                            for (const v of verifications)
+                                noteVerificationOutcome(v.id, v.check, { kind: "sent", status });
+                    };
                     return Promise.resolve(inner.send(kept)).then((r) => {
                         release();
+                        settle(r);
                         return r;
                     }, () => {
                         release();
+                        settle({});
                         return {};
                     });
                 }

package/dist/verification.d.ts

@@ -0,0 +1,51 @@
+import { VERIFICATION_CONTEXT, VERIFICATION_ERROR_TYPE, VERIFICATION_ID_RE, VERIFICATION_TAG } from "./constants.js";
+export { VERIFICATION_CONTEXT, VERIFICATION_ERROR_TYPE, VERIFICATION_ID_RE, VERIFICATION_TAG };
+export type VerificationSurface = "browser" | "server";
+export type VerificationCheck = "delivery" | "uncaught";
+export type VerificationContext = {
+    v: 1;
+    surface: VerificationSurface;
+    check: VerificationCheck;
+    hook?: "ok" | "missing" | "unknown";
+    uncaught_expected?: boolean;
+};
+declare const MARK = "__belvadorVerification";
+/** The error a verification captures or throws; carries its id and context. */
+export declare class BelvadorVerificationError extends Error {
+    readonly [MARK]: {
+        id: string;
+        context: VerificationContext;
+    };
+    constructor(id: string, context: VerificationContext);
+}
+export declare function newVerificationId(): string;
+/** The marker of a verification error, if `value` is one. */
+export declare function verificationOf(value: unknown): {
+    id: string;
+    context: VerificationContext;
+} | null;
+export type SendOutcome = {
+    kind: "sent";
+    status: number;
+} | {
+    kind: "failed";
+    code: string;
+    status?: number;
+} | {
+    kind: "dropped";
+};
+export declare function noteVerificationOutcome(id: string, check: string, outcome: SendOutcome): void;
+export declare function verificationOutcome(id: string, check: string): SendOutcome | undefined;
+/** The verification id/check of an event, read from its tags and Belvador context. */
+export declare function verificationOfEvent(event: {
+    tags?: Record<string, unknown>;
+    contexts?: Record<string, unknown>;
+}): {
+    id: string;
+    check: string;
+} | null;
+export type HookKind = "middleware" | "wrapper";
+/** Called by Belvador's request/function middleware and Worker wrapper. Never throws. */
+export declare function markHooked(kind: HookKind): void;
+/** Hooks around the code running now (the current request). */
+export declare function currentHooks(): ReadonlySet<HookKind>;

package/dist/verification.js

@@ -0,0 +1,87 @@
+// Verification marker and per-request hook marks (build integration-health-1.0
+// spec 02 §3). A verification is an ordinary error event with a reserved tag; the
+// SDK attaches the tag and context in beforeSend from the thrown error itself, so
+// captured and uncaught verifications take the same path as real errors.
+import { getIsolationScope } from "@sentry/core";
+import { VERIFICATION_CONTEXT, VERIFICATION_ERROR_TYPE, VERIFICATION_ID_RE, VERIFICATION_TAG, } from "./constants.js";
+export { VERIFICATION_CONTEXT, VERIFICATION_ERROR_TYPE, VERIFICATION_ID_RE, VERIFICATION_TAG };
+const MARK = "__belvadorVerification";
+/** The error a verification captures or throws; carries its id and context. */
+export class BelvadorVerificationError extends Error {
+    constructor(id, context) {
+        super(context.check === "uncaught"
+            ? "Belvador verification (uncaught, expected) — safe to ignore"
+            : "Belvador verification (delivery) — safe to ignore");
+        this.name = VERIFICATION_ERROR_TYPE;
+        this[MARK] = { id, context };
+    }
+}
+export function newVerificationId() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    let hex = "";
+    for (const b of bytes)
+        hex += b.toString(16).padStart(2, "0");
+    return `bv1_${hex}`;
+}
+/** The marker of a verification error, if `value` is one. */
+export function verificationOf(value) {
+    try {
+        if (value === null || typeof value !== "object")
+            return null;
+        const m = value[MARK];
+        if (!m || typeof m.id !== "string" || !VERIFICATION_ID_RE.test(m.id))
+            return null;
+        if (!m.context || typeof m.context !== "object")
+            return null;
+        return m;
+    }
+    catch {
+        return null;
+    }
+}
+const outcomes = new Map();
+const key = (id, check) => `${id}:${check}`;
+export function noteVerificationOutcome(id, check, outcome) {
+    if (outcomes.size > 50)
+        outcomes.clear();
+    outcomes.set(key(id, check), outcome);
+}
+export function verificationOutcome(id, check) {
+    return outcomes.get(key(id, check));
+}
+/** The verification id/check of an event, read from its tags and Belvador context. */
+export function verificationOfEvent(event) {
+    try {
+        const id = event.tags?.[VERIFICATION_TAG];
+        const ctx = event.contexts?.[VERIFICATION_CONTEXT];
+        if (typeof id !== "string" || !VERIFICATION_ID_RE.test(id))
+            return null;
+        return { id, check: typeof ctx?.check === "string" ? ctx.check : "delivery" };
+    }
+    catch {
+        return null;
+    }
+}
+const hooked = new WeakMap();
+/** Called by Belvador's request/function middleware and Worker wrapper. Never throws. */
+export function markHooked(kind) {
+    try {
+        const scope = getIsolationScope();
+        const set = hooked.get(scope) ?? new Set();
+        set.add(kind);
+        hooked.set(scope, set);
+    }
+    catch {
+        /* no scope */
+    }
+}
+/** Hooks around the code running now (the current request). */
+export function currentHooks() {
+    try {
+        return hooked.get(getIsolationScope()) ?? new Set();
+    }
+    catch {
+        return new Set();
+    }
+}

package/dist/verify.d.ts

@@ -0,0 +1,47 @@
+import { VERIFY_LIMITS } from "./constants.js";
+import { type HookKind, type VerificationSurface } from "./verification.js";
+export { VERIFY_LIMITS };
+export type VerifyOptions = {
+    /** Whole run, default 20 000 ms, at most 30 000. */
+    timeoutMs?: number;
+    /** Browser: also prove that uncaught errors are reported (default true). */
+    uncaught?: boolean;
+    /** Ask Belvador whether the events arrived (default true). */
+    readback?: boolean;
+};
+export type CheckName = "init" | "hook" | "delivery" | "uncaught";
+export type CheckStatus = "confirmed" | "accepted" | "missing" | "failed" | "skipped";
+export type VerificationResult = {
+    verificationId: string;
+    surface: VerificationSurface;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    /** Project id from the DSN, or null when there is none. */
+    project: number | null;
+    checks: Array<{
+        check: CheckName;
+        status: CheckStatus;
+        code?: string;
+    }>;
+    outcome: "verified" | "problem" | "unconfirmed";
+    node?: "connected" | "offline";
+    docsUrl: string;
+};
+/** What a runtime package tells the runner. */
+export type VerifyRuntime = {
+    surface: VerificationSurface;
+    /** Browser: global handlers installed. Server: hooks around the current request. */
+    hook: () => {
+        ok: boolean;
+    };
+    /** Server: which hook kinds count (TanStack Start: middleware; Workers: wrapper or middleware). */
+    serverHooks?: readonly HookKind[];
+    /** Test seams. */
+    fetch?: (url: string, init: RequestInit) => Promise<Response>;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+};
+/** Runs the verification for one runtime. Concurrent calls share one run. */
+export declare function runVerification(runtime: VerifyRuntime, options?: VerifyOptions): Promise<VerificationResult>;

package/dist/verify.js

@@ -0,0 +1,180 @@
+// verifyIntegration (build integration-health-1.0 spec 02 §3): proves that one
+// runtime of this app reaches the right Belvador project. Only runs when the app
+// calls it; ≤ 2 events and ≤ 10 read-backs per call; always resolves, never throws.
+import { captureException as engineCaptureException, flush as engineFlush, getClient } from "@sentry/core";
+import { VERIFY_DOCS_URL, diagnosticDocsUrl, reportDiagnostic, } from "./diagnostics.js";
+import { VERIFY_LIMITS } from "./constants.js";
+import { checkDsn } from "./dsn.js";
+import { getDiagnostics, isActive } from "./facade.js";
+import { BelvadorVerificationError, newVerificationId, verificationOutcome, } from "./verification.js";
+export { VERIFY_LIMITS };
+const running = new Map();
+function clampTimeout(ms) {
+    return typeof ms === "number" && Number.isFinite(ms)
+        ? Math.min(VERIFY_LIMITS.timeoutMaxMs, Math.max(1000, ms))
+        : VERIFY_LIMITS.timeoutDefaultMs;
+}
+function line(r) {
+    const parts = r.checks
+        .filter((c) => c.check !== "init" || c.status !== "confirmed")
+        .map((c) => `${c.check} ${c.status}${c.code ? ` (${c.code})` : ""}`);
+    return `[belvador] verify ${r.surface}: ${r.outcome} — ${parts.join(", ")} — ${r.verificationId} — ${r.docsUrl}`;
+}
+function print(r) {
+    try {
+        (r.outcome === "verified" ? console.info : console.warn)(line(r));
+    }
+    catch {
+        /* no console */
+    }
+}
+/** Runs the verification for one runtime. Concurrent calls share one run. */
+export function runVerification(runtime, options = {}) {
+    const current = running.get(runtime.surface);
+    if (current)
+        return current;
+    const p = execute(runtime, options)
+        .catch(() => fallback(runtime.surface))
+        .then((r) => {
+        print(r);
+        return r;
+    })
+        .finally(() => running.delete(runtime.surface));
+    running.set(runtime.surface, p);
+    return p;
+}
+function fallback(surface) {
+    return {
+        verificationId: "",
+        surface,
+        sdk: getDiagnostics().sdk,
+        project: null,
+        checks: [{ check: "init", status: "failed", code: "BLV_NOT_INITIALIZED" }],
+        outcome: "problem",
+        docsUrl: VERIFY_DOCS_URL,
+    };
+}
+async function execute(runtime, options) {
+    const now = runtime.now ?? Date.now;
+    const started = now();
+    const deadline = started + clampTimeout(options.timeoutMs);
+    const sleep = runtime.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const id = newVerificationId();
+    const snapshot = getDiagnostics();
+    const dsnValue = getClient()?.getOptions()?.dsn;
+    const dsn = checkDsn(dsnValue);
+    const result = {
+        verificationId: id,
+        surface: runtime.surface,
+        sdk: snapshot.sdk,
+        project: dsn?.projectId ?? snapshot.dsn?.project ?? null,
+        checks: [],
+        outcome: "problem",
+        docsUrl: VERIFY_DOCS_URL,
+    };
+    // 1. init
+    if (!isActive() || !dsn) {
+        const code = ["BLV_DSN_MISSING", "BLV_DSN_INVALID", "BLV_INIT_CONFLICT"].find((c) => (snapshot.counts[c] ?? 0) > 0);
+        result.checks.push({ check: "init", status: "failed", code: code ?? "BLV_NOT_INITIALIZED" });
+        result.docsUrl = diagnosticDocsUrl(code ?? "BLV_NOT_INITIALIZED");
+        return result;
+    }
+    result.checks.push({ check: "init", status: "confirmed" });
+    // 2. hook
+    const hookOk = runtime.hook().ok;
+    if (!hookOk)
+        reportDiagnostic("BLV_HOOK_MISSING");
+    result.checks.push(hookOk ? { check: "hook", status: "confirmed" } : { check: "hook", status: "missing", code: "BLV_HOOK_MISSING" });
+    // 3. delivery (+ 4. uncaught in the browser)
+    const wantUncaught = runtime.surface === "browser" && options.uncaught !== false;
+    engineCaptureException(new BelvadorVerificationError(id, {
+        v: 1,
+        surface: runtime.surface,
+        check: "delivery",
+        ...(runtime.surface === "server"
+            ? { hook: hookOk ? "ok" : "missing" }
+            : { uncaught_expected: wantUncaught }),
+    }), { level: "info" });
+    if (wantUncaught) {
+        // The page's own timer, so the throw reaches window.onerror like any app error.
+        const w = globalThis.window;
+        const schedule = w?.setTimeout ? w.setTimeout.bind(w) : setTimeout;
+        schedule(() => {
+            throw new BelvadorVerificationError(id, { v: 1, surface: "browser", check: "uncaught" });
+        }, 0);
+        // Let the global handler see it before flushing.
+        await sleep(50);
+    }
+    await engineFlush(Math.max(1000, Math.min(5000, deadline - now()))).catch(() => false);
+    const local = (check) => {
+        const o = verificationOutcome(id, check);
+        if (!o)
+            return { status: "failed", code: "BLV_DROPPED_BY_APP" };
+        if (o.kind === "dropped")
+            return { status: "failed", code: "BLV_DROPPED_BY_APP" };
+        if (o.kind === "failed")
+            return { status: "failed", code: o.code };
+        return { status: "accepted" };
+    };
+    const delivery = local("delivery");
+    const uncaught = wantUncaught ? local("uncaught") : { status: "skipped" };
+    // 5. read back
+    let readback = null;
+    const sendsOk = delivery.status === "accepted";
+    if (options.readback !== false && sendsOk) {
+        const doFetch = runtime.fetch ?? ((u, i) => globalThis.fetch(u, i));
+        const url = `${dsn.protocol}//${dsn.host}/api/${dsn.projectId}/verification/${id}/?sentry_key=${dsn.publicKey}`;
+        for (let i = 0; i < VERIFY_LIMITS.readbackMaxRequests; i++) {
+            const wait = VERIFY_LIMITS.readbackDelaysMs[Math.min(i, VERIFY_LIMITS.readbackDelaysMs.length - 1)];
+            if (now() + wait > deadline)
+                break;
+            await sleep(wait);
+            try {
+                const res = await doFetch(url, { method: "GET", credentials: "omit" });
+                if (res.status === 200) {
+                    const body = (await res.json());
+                    readback = { node: body.node === "offline" ? "offline" : "connected", checks: Array.isArray(body.checks) ? body.checks : [] };
+                    const has = (c) => readback.checks.some((x) => x.surface === runtime.surface && x.check === c);
+                    if (has("delivery") && (!wantUncaught || has("uncaught") || uncaught.status !== "accepted"))
+                        break;
+                    if (readback.node === "offline")
+                        break;
+                }
+                else if (res.status === 429 || res.status === 401 || res.status === 403) {
+                    break;
+                }
+            }
+            catch {
+                /* retry within the deadline */
+            }
+        }
+    }
+    const confirmed = (check) => readback?.checks.some((x) => x.surface === runtime.surface && x.check === check) ?? false;
+    const finalize = (check, s) => {
+        if (s.status !== "accepted")
+            return s;
+        if (confirmed(check))
+            return { status: "confirmed" };
+        // Read back worked and the node is up, yet nothing arrived: the event is missing.
+        if (readback && readback.node === "connected")
+            return { status: "missing" };
+        return s;
+    };
+    const d = finalize("delivery", delivery);
+    result.checks.push({ check: "delivery", ...d });
+    if (runtime.surface === "browser")
+        result.checks.push({ check: "uncaught", ...finalize("uncaught", uncaught) });
+    if (readback)
+        result.node = readback.node;
+    const all = result.checks.filter((c) => c.status !== "skipped");
+    if (all.some((c) => c.status === "failed" || c.status === "missing"))
+        result.outcome = "problem";
+    else if (all.every((c) => c.status === "confirmed") && !result.checks.some((c) => c.status === "skipped"))
+        result.outcome = "verified";
+    else
+        result.outcome = "unconfirmed";
+    const first = result.checks.find((c) => c.code);
+    if (first?.code)
+        result.docsUrl = diagnosticDocsUrl(first.code);
+    return result;
+}

package/dist/version.d.ts

@@ -1,3 +1,3 @@
-export declare const SDK_VERSION = "0.1.0";
+export declare const SDK_VERSION = "0.2.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.1.0";
+export const SDK_VERSION = "0.2.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.1.0",
+  "version": "0.2.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)",