@belvador/cloudflare 0.1.0 → 0.2.0

package/README.md

@@ -44,6 +44,14 @@ each attempt times out after 10 s, failed sends retry at most 5 times, `429` rat
 respected, and a revoked key (`401`/`403`) stops sending for the life of the page or isolate.
 Every public function catches its own errors.
 
+## Check the connection
+
+"No errors" is not proof that errors arrive. Call `verifyIntegration()` from `@belvador/cloudflare` inside a request handled by `withBelvador`:
+it sends one marked test error (never an issue), reads it back and resolves to
+`{ outcome: "verified" | "problem" | "unconfirmed", checks, docsUrl, … }`. It never throws.
+Requests the visitor cancelled (`AbortError`) are not reported unless you set `captureAborted: true`.
+See https://belvador.dev/docs/sdk/verify
+
 ## Status
 
 `0.x` — used by Belvador's own apps first. The API may still change before `1.0`.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { CloudflareOptions as EngineCloudflareOptions } from "@sentry/cloudflare";
-import { type BelvadorOptions } from "@belvador/core";
-export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, lastEventId, setContext, setTag, setTags, setUser, withScope, type BelvadorBreadcrumb, type BelvadorEvent, type BelvadorEventHint, type Scope, type SeverityLevel, } from "@belvador/core";
+import { type BelvadorOptions, type VerificationResult, type VerifyOptions } from "@belvador/core";
+export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, getDiagnostics, lastEventId, setContext, setTag, setTags, setUser, withScope, type BelvadorBreadcrumb, type BelvadorEvent, type BelvadorEventHint, type Diagnostic, type DiagnosticCode, type DiagnosticsSnapshot, type Scope, type SeverityLevel, type VerificationResult, type VerifyOptions, } from "@belvador/core";
 export type WorkerOptions = Omit<BelvadorOptions, "dsn"> & {
     /** Defaults to the BELVADOR_DSN binding. */
     dsn?: string;
@@ -27,3 +27,9 @@ export declare function wrapHandler<Env, H>(optionsCallback: (env: Env) => Worke
  * untouched, sending finished in waitUntil after the response.
  */
 export declare function withBelvador<Env, H>(optionsCallback: (env: Env) => WorkerOptions | undefined, handler: H): H;
+/**
+ * Proves this Worker reports to Belvador. Call it inside a request handled by
+ * withBelvador (for example a temporary `/verify-belvador` path): it checks the wrapper,
+ * sends one verification error and reads it back. Never automatic; always resolves.
+ */
+export declare function verifyIntegration(options?: VerifyOptions): Promise<VerificationResult>;

package/dist/index.js

@@ -3,8 +3,8 @@
 // privacy and sending rules. Needs the `nodejs_compat` (or `nodejs_als`)
 // compatibility flag so every request gets its own scope.
 import { consoleIntegration, dedupeIntegration, eventFiltersIntegration, fetchIntegration, linkedErrorsIntegration, requestDataIntegration, withSentry, } from "@sentry/cloudflare";
-import { buildEngineOptions } from "@belvador/core";
-export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, lastEventId, setContext, setTag, setTags, setUser, withScope, } from "@belvador/core";
+import { buildEngineOptions, currentHooks, markHooked, noteClientAbort, runVerification, } from "@belvador/core";
+export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, getDiagnostics, lastEventId, setContext, setTag, setTags, setUser, withScope, } from "@belvador/core";
 function binding(env, name) {
     if (env === null || typeof env !== "object")
         return undefined;
@@ -89,6 +89,55 @@ export function workerEngineOptions(options, env, runtime = "cloudflare") {
         return OFF;
     }
 }
+const HANDLER_METHODS = ["fetch", "scheduled", "queue", "email", "tail"];
+/**
+ * Marks each invocation of an object handler as running inside the wrapper (integration
+ * health: `verifyIntegration` can tell), and notes a fetch that failed after its client
+ * disconnected so the error counts as a cancellation. Class handlers pass through unchanged.
+ */
+function marked(handler) {
+    if (handler === null || typeof handler !== "object")
+        return handler;
+    const out = { ...handler };
+    for (const name of HANDLER_METHODS) {
+        const fn = handler[name];
+        if (typeof fn !== "function")
+            continue;
+        out[name] = function (...args) {
+            markHooked("wrapper");
+            const signal = name === "fetch" ? signalOf(args[0]) : undefined;
+            if (!signal)
+                return fn.apply(handler, args);
+            const failed = (error) => {
+                noteClientAbort(error, signal);
+                throw error;
+            };
+            let result;
+            try {
+                result = fn.apply(handler, args);
+            }
+            catch (error) {
+                return failed(error);
+            }
+            return isThenable(result) ? Promise.resolve(result).then(undefined, failed) : result;
+        };
+    }
+    return out;
+}
+function signalOf(request) {
+    try {
+        const signal = request?.signal;
+        return typeof AbortSignal !== "undefined" && signal instanceof AbortSignal ? signal : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isThenable(value) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value.then === "function");
+}
 /** Shared with @belvador/tanstack-start so its server events carry its own SDK name. */
 export function wrapHandler(optionsCallback, handler, runtime) {
     return withSentry((env) => {
@@ -100,7 +149,7 @@ export function wrapHandler(optionsCallback, handler, runtime) {
             return OFF;
         }
         return workerEngineOptions(options, env, runtime);
-    }, handler);
+    }, marked(handler));
 }
 /**
  * Wraps a Worker's exported handler (fetch, scheduled, queue, email, tail):
@@ -110,3 +159,17 @@ export function wrapHandler(optionsCallback, handler, runtime) {
 export function withBelvador(optionsCallback, handler) {
     return wrapHandler(optionsCallback, handler, "cloudflare");
 }
+/**
+ * Proves this Worker reports to Belvador. Call it inside a request handled by
+ * withBelvador (for example a temporary `/verify-belvador` path): it checks the wrapper,
+ * sends one verification error and reads it back. Never automatic; always resolves.
+ */
+export function verifyIntegration(options) {
+    return runVerification({
+        surface: "server",
+        hook: () => {
+            const hooks = currentHooks();
+            return { ok: hooks.has("wrapper") || hooks.has("middleware") };
+        },
+    }, options);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@belvador/cloudflare",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Belvador error tracking for Cloudflare Workers: per-request scope, errors only, private by default.",
   "license": "MIT",
   "author": "Belvador (https://belvador.dev)",
@@ -32,7 +32,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@belvador/core": "0.1.0",
+    "@belvador/core": "0.2.0",
     "@sentry/cloudflare": "10.76.2"
   },
   "publishConfig": {