@belvador/core 0.1.0 → 0.3.0

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.3.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.3.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.3.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)",