@belvador/cloudflare 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Belvador
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This software depends on the Sentry JavaScript SDK (https://github.com/getsentry/sentry-javascript),
+which is distributed under its own MIT License (Copyright (c) Functional Software, Inc. dba Sentry)
+in each of its npm packages. Belvador is not affiliated with or endorsed by Sentry.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# @belvador/cloudflare
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Error tracking for Cloudflare Workers, sending to your [Belvador](https://belvador.dev) node.
+
+```sh
+npm install @belvador/cloudflare
+```
+
+```ts
+import { withBelvador } from "@belvador/cloudflare";
+
+export default withBelvador(
+  (env) => ({ release: env.BELVADOR_RELEASE }),
+  {
+    async fetch(request, env, ctx) {
+      return new Response("ok");
+    },
+  },
+);
+```
+
+Set the DSN as a secret: `wrangler secret put BELVADOR_DSN`. The SDK also reads
+`BELVADOR_RELEASE` (else `CF_VERSION_METADATA.id`), `BELVADOR_ENVIRONMENT` and
+`BELVADOR_DISABLED=1`. It never reads `SENTRY_*` variables.
+
+Requires the `nodejs_compat` compatibility flag so every request gets its own scope (user,
+tags and context never leak between requests). Errors are reported and re-thrown; your
+response (status, headers, streamed body) is returned unchanged and sending finishes in
+`waitUntil` after the response.
+
+## What it sends
+
+Errors only (exceptions, messages, breadcrumbs you turn on, attachments if you enable them).
+No tracing, session replay, logs or profiling — those items are dropped inside your app.
+
+Before anything leaves your app the SDK removes `Authorization`, `Cookie` and `Set-Cookie`
+headers, request bodies and cookies, client IP headers, and masks credentials in URLs, query
+strings, tags, contexts, extra data and breadcrumbs (passwords, tokens, API keys, JWTs, card
+numbers, e-mail addresses). Only `user.id` is kept from `setUser`. Your Belvador node scrubs
+again on its own.
+
+Sending never slows down or breaks your app: at most 30 envelopes / 1 MB wait to be sent,
+each attempt times out after 10 s, failed sends retry at most 5 times, `429` rate limits are
+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`.
+
+Built on the open-source [Sentry JavaScript SDK](https://github.com/getsentry/sentry-javascript)
+(MIT), pinned to one audited version, with Belvador's privacy and sending rules. Events go only
+to your Belvador DSN; no Sentry account is involved. Belvador is not affiliated with Sentry.
+
+License: MIT · https://belvador.dev

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import type { CloudflareOptions as EngineCloudflareOptions } from "@sentry/cloudflare";
+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;
+    /** Breadcrumb sources, off by default. */
+    instrument?: {
+        console?: boolean;
+        fetch?: boolean;
+    };
+};
+/** Bindings the SDK reads (values returned by your options callback win). */
+export type BelvadorEnv = {
+    BELVADOR_DSN?: string;
+    BELVADOR_RELEASE?: string;
+    BELVADOR_ENVIRONMENT?: string;
+    BELVADOR_DISABLED?: string;
+};
+/** Engine options for one Worker invocation (exported for tests and @belvador/tanstack-start). */
+export declare function workerEngineOptions(options: WorkerOptions | undefined, env: unknown, runtime?: "cloudflare" | "tanstack-start"): EngineCloudflareOptions;
+/** Shared with @belvador/tanstack-start so its server events carry its own SDK name. */
+export declare function wrapHandler<Env, H>(optionsCallback: (env: Env) => WorkerOptions | undefined, handler: H, runtime: "cloudflare" | "tanstack-start"): H;
+/**
+ * Wraps a Worker's exported handler (fetch, scheduled, queue, email, tail):
+ * one client per invocation, errors reported and re-thrown, responses
+ * 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

@@ -0,0 +1,175 @@
+// @belvador/cloudflare — errors from Cloudflare Workers to your Belvador node.
+// Built on the open-source Sentry JavaScript SDK (MIT), with Belvador's
+// 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, 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;
+    try {
+        const v = env[name];
+        return typeof v === "string" && v.length > 0 ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function versionId(env) {
+    if (env === null || typeof env !== "object")
+        return undefined;
+    try {
+        const meta = env["CF_VERSION_METADATA"];
+        const id = meta && typeof meta === "object" ? meta["id"] : undefined;
+        return typeof id === "string" && id ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Options for a client that never sends. Every key the engine would otherwise
+ * read from SENTRY_* bindings is set explicitly.
+ */
+const OFF = {
+    dsn: "",
+    enabled: false,
+    tunnel: "",
+    spotlight: false,
+    debug: false,
+    release: undefined,
+    environment: "production",
+    tracesSampleRate: 0,
+    defaultIntegrations: false,
+    integrations: [],
+};
+/** Engine options for one Worker invocation (exported for tests and @belvador/tanstack-start). */
+export function workerEngineOptions(options, env, runtime = "cloudflare") {
+    try {
+        const o = options ?? {};
+        const disabled = o.disabled === true || /^(1|true)$/i.test(binding(env, "BELVADOR_DISABLED") ?? "");
+        const base = buildEngineOptions({
+            ...o,
+            dsn: o.dsn ?? binding(env, "BELVADOR_DSN") ?? "",
+            disabled,
+            release: o.release ?? binding(env, "BELVADOR_RELEASE") ?? versionId(env),
+            environment: o.environment ?? binding(env, "BELVADOR_ENVIRONMENT"),
+        }, runtime === "tanstack-start" ? "tanstack-start" : "cloudflare", { browser: false });
+        if (!base)
+            return OFF;
+        const integrations = [
+            dedupeIntegration(),
+            eventFiltersIntegration(),
+            linkedErrorsIntegration(),
+            // Request URL, method and headers (scrubbed later); never cookies, bodies or IPs.
+            requestDataIntegration({
+                include: {
+                    cookies: false,
+                    data: false,
+                    ip: false,
+                    headers: true,
+                    query_string: true,
+                    url: true,
+                },
+            }),
+        ];
+        if (o.instrument?.console === true)
+            integrations.push(consoleIntegration());
+        if (o.instrument?.fetch === true)
+            integrations.push(fetchIntegration({ breadcrumbs: true }));
+        return {
+            ...base,
+            // 0, not undefined: an undefined value would let SENTRY_TRACES_SAMPLE_RATE turn tracing on.
+            tracesSampleRate: 0,
+            integrations,
+        };
+    }
+    catch {
+        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) => {
+        let options;
+        try {
+            options = optionsCallback(env);
+        }
+        catch {
+            return OFF;
+        }
+        return workerEngineOptions(options, env, runtime);
+    }, marked(handler));
+}
+/**
+ * Wraps a Worker's exported handler (fetch, scheduled, queue, email, tail):
+ * one client per invocation, errors reported and re-thrown, responses
+ * untouched, sending finished in waitUntil after the response.
+ */
+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,45 @@
 {
   "name": "@belvador/cloudflare",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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)",
+  "homepage": "https://belvador.dev",
+  "keywords": [
+    "belvador",
+    "error-tracking",
+    "errors",
+    "monitoring"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@belvador/core": "0.2.0",
+    "@sentry/cloudflare": "10.76.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}