@belvador/tanstack-start 0.1.0 → 0.3.0

package/README.md

@@ -42,13 +42,69 @@ export const startInstance = createStart(() => ({
 ```
 
 Server functions and server routes are reported with their server stack; redirects,
-`notFound()` and errors with a status below 500 are not. Needs `nodejs_compat` and the
-`BELVADOR_DSN` secret on the server.
+`notFound()`, errors with a status below 500 and requests the visitor cancelled (`AbortError`,
+or a failure after the client disconnected — `captureAborted: true` reports them) are not.
+Needs `nodejs_compat` and the `BELVADOR_DSN` secret on the server.
+
+## Monitor background work
+
+Errors alone cannot tell you that a job never ran. Wrap scheduled and queued work in
+`withMonitor` (Sentry-compatible check-ins): Belvador sees each run start and finish, and
+opens an incident when a run fails, times out or never happens.
+
+```ts
+// src/routes/api/jobs/nightly-invoices.ts — called by your scheduler
+import { createFileRoute } from "@tanstack/react-router";
+import { withMonitor } from "@belvador/tanstack-start/server";
+
+export const Route = createFileRoute("/api/jobs/nightly-invoices")({
+  server: {
+    handlers: {
+      POST: async () => {
+        const sent = await withMonitor(
+          "nightly-invoices",
+          async (run) => {
+            const due = await loadDueInvoices();
+            if (due.length === 0) run.skip("nothing_due");
+            return sendInvoices(due);
+          },
+          { schedule: { type: "crontab", value: "0 2 * * *" }, timezone: "Europe/Berlin" },
+        );
+        return Response.json({ sent });
+      },
+    },
+  },
+});
+```
+
+Your function's result and errors come back unchanged (a synchronous function stays
+synchronous); an error is also reported as a normal issue with the monitor's slug. For queue
+consumers pass `runId` (your message id), `attempt` and `willRetry` so retries count as one
+run. `captureCheckIn()` and `heartbeat()` cover manual start/finish and "still alive" checks.
+Check-ins are sent only from server code. See https://belvador.dev/docs/monitors/setup
+
+## Link requests with one trace
+
+Off by default. `tracePropagation: { targets: [/^\/api\//, "https://api.example.com"] }` (in
+`init` and in the `withBelvador` options) adds `traceparent` and `sentry-trace` headers to
+`fetch` calls to those URLs, so the browser error, the server error and the job's check-ins
+behind one request share a trace id. An incoming
+`traceparent` (or `sentry-trace`) is continued. No spans or transactions are sent; `baggage`
+only with `baggage: true`. See https://belvador.dev/docs/sdk/tracing
+
+## Check the connection
+
+"No errors" is not proof that errors arrive. Call `verifyIntegration()` once from the browser
+(`@belvador/tanstack-start/client`) and once from a server route (`@belvador/tanstack-start/server`):
+each sends one marked test error (never an issue), reads it back and resolves to
+`{ outcome: "verified" | "problem" | "unconfirmed", checks, docsUrl, … }`. It never throws. See
+https://belvador.dev/docs/sdk/verify
 
 ## 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.
+Errors (exceptions, messages, breadcrumbs you turn on, attachments if you enable them) and
+the job check-ins you send with `withMonitor`. No spans, 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

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { ReactOptions } from "@belvador/react";
-export { ErrorBoundary, SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, lastEventId, reactErrorHandler, setContext, setTag, setTags, setUser, withErrorBoundary, withScope, type ErrorBoundaryProps, type ReactOptions, } from "@belvador/react";
+export { ErrorBoundary, SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, getDiagnostics, lastEventId, reactErrorHandler, setContext, setTag, setTags, setUser, withErrorBoundary, withScope, verifyIntegration, type Diagnostic, type DiagnosticCode, type DiagnosticsSnapshot, type ErrorBoundaryProps, type ReactOptions, type VerificationResult, type VerifyOptions, } from "@belvador/react";
 export { belvadorOnCatch } from "./index.js";
 /** Starts error tracking in the browser; returns whether it is running. Never throws. */
 export declare function init(options: ReactOptions): boolean;

package/dist/client.js

@@ -1,5 +1,5 @@
 import { initReact } from "@belvador/react/internal";
-export { ErrorBoundary, SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, lastEventId, reactErrorHandler, setContext, setTag, setTags, setUser, withErrorBoundary, withScope, } from "@belvador/react";
+export { ErrorBoundary, SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, getDiagnostics, lastEventId, reactErrorHandler, setContext, setTag, setTags, setUser, withErrorBoundary, withScope, verifyIntegration, } from "@belvador/react";
 export { belvadorOnCatch } from "./index.js";
 /** Starts error tracking in the browser; returns whether it is running. Never throws. */
 export function init(options) {

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export { SDK_VERSION } from "@belvador/core";
 /**
  * Control flow, not failures: redirects, not-found, thrown Responses and
- * anything carrying an HTTP status below 500 are never reported.
+ * anything carrying an HTTP status below 500 (499 "client closed" included) are
+ * never reported. Client cancellations (AbortError, or a failure after the visitor
+ * disconnected) are dropped by the SDK itself unless `captureAborted` is on.
  */
 export declare function isExpectedError(error: unknown): boolean;
 /**

package/dist/index.js

@@ -3,11 +3,13 @@
 // bundles: it only calls the runtime-neutral capture API.
 import { isNotFound, isRedirect } from "@tanstack/react-router";
 import { createMiddleware } from "@tanstack/react-start";
-import { captureException } from "@belvador/core";
+import { captureException, markHooked, noteClientAbort } from "@belvador/core";
 export { SDK_VERSION } from "@belvador/core";
 /**
  * Control flow, not failures: redirects, not-found, thrown Responses and
- * anything carrying an HTTP status below 500 are never reported.
+ * anything carrying an HTTP status below 500 (499 "client closed" included) are
+ * never reported. Client cancellations (AbortError, or a failure after the visitor
+ * disconnected) are dropped by the SDK itself unless `captureAborted` is on.
  */
 export function isExpectedError(error) {
     try {
@@ -40,21 +42,25 @@ function report(error, kind) {
  * `requestMiddleware` (closest to the handler) so it sees errors before an
  * error-page middleware turns them into a response.
  */
-export const belvadorRequestMiddleware = createMiddleware().server(async ({ next }) => {
+export const belvadorRequestMiddleware = createMiddleware().server(async ({ next, request }) => {
+    markHooked("middleware");
     try {
         return await next();
     }
     catch (error) {
+        noteClientAbort(error, request?.signal);
         report(error, "request");
         throw error;
     }
 });
 /** Server-function middleware: same contract, put it LAST in `functionMiddleware`. */
-export const belvadorFunctionMiddleware = createMiddleware({ type: "function" }).server(async ({ next }) => {
+export const belvadorFunctionMiddleware = createMiddleware({ type: "function" }).server(async ({ next, signal }) => {
+    markHooked("middleware");
     try {
         return await next();
     }
     catch (error) {
+        noteClientAbort(error, signal);
         report(error, "server_function");
         throw error;
     }

package/dist/server.d.ts

@@ -1,7 +1,16 @@
 import { type WorkerOptions } from "@belvador/cloudflare";
-export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, flush, setContext, setTag, setTags, setUser, withScope, type BelvadorEnv, type WorkerOptions, } from "@belvador/cloudflare";
+import { type VerificationResult, type VerifyOptions } from "@belvador/core";
+export { SDK_VERSION, addBreadcrumb, captureCheckIn, captureException, captureMessage, flush, heartbeat, withMonitor, getDiagnostics, setContext, setTag, setTags, setUser, withScope, type BelvadorEnv, type Diagnostic, type DiagnosticCode, type DiagnosticsSnapshot, type CheckInInput, type MonitorConfigInput, type MonitorSchedule, type RunHandle, type TracePropagationOptions, type WithMonitorOptions, type WorkerOptions, } from "@belvador/cloudflare";
+export type { VerificationResult, VerifyOptions } from "@belvador/core";
 /**
  * `export default withBelvador((env) => ({ release: env.BELVADOR_RELEASE }), { fetch })`:
  * one client per request, errors reported and re-thrown, the response untouched.
  */
 export declare function withBelvador<Env, H>(optionsCallback: (env: Env) => WorkerOptions | undefined, handler: H): H;
+/**
+ * Proves the server reports to Belvador. Call it inside a server function or server
+ * route (for example a temporary `/api/verify-belvador` route): it checks that the call
+ * runs inside belvadorRequestMiddleware/belvadorFunctionMiddleware, sends one
+ * verification error and reads it back. Never automatic; always resolves.
+ */
+export declare function verifyIntegration(options?: VerifyOptions): Promise<VerificationResult>;

package/dist/server.js

@@ -1,7 +1,8 @@
 // @belvador/tanstack-start/server — Workers side. Wrap the default export of
 // src/server.ts; add the middleware from "@belvador/tanstack-start" to src/start.ts.
 import { wrapHandler } from "@belvador/cloudflare";
-export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, flush, setContext, setTag, setTags, setUser, withScope, } from "@belvador/cloudflare";
+import { currentHooks, runVerification, } from "@belvador/core";
+export { SDK_VERSION, addBreadcrumb, captureCheckIn, captureException, captureMessage, flush, heartbeat, withMonitor, getDiagnostics, setContext, setTag, setTags, setUser, withScope, } from "@belvador/cloudflare";
 /**
  * `export default withBelvador((env) => ({ release: env.BELVADOR_RELEASE }), { fetch })`:
  * one client per request, errors reported and re-thrown, the response untouched.
@@ -9,3 +10,12 @@ export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, flush, se
 export function withBelvador(optionsCallback, handler) {
     return wrapHandler(optionsCallback, handler, "tanstack-start");
 }
+/**
+ * Proves the server reports to Belvador. Call it inside a server function or server
+ * route (for example a temporary `/api/verify-belvador` route): it checks that the call
+ * runs inside belvadorRequestMiddleware/belvadorFunctionMiddleware, sends one
+ * verification error and reads it back. Never automatic; always resolves.
+ */
+export function verifyIntegration(options) {
+    return runVerification({ surface: "server", hook: () => ({ ok: currentHooks().has("middleware") }) }, options);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@belvador/tanstack-start",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Belvador error tracking for TanStack Start on Cloudflare Workers: client, server entry and middleware.",
   "license": "MIT",
   "author": "Belvador (https://belvador.dev)",
@@ -42,9 +42,9 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@belvador/cloudflare": "0.1.0",
-    "@belvador/core": "0.1.0",
-    "@belvador/react": "0.1.0"
+    "@belvador/cloudflare": "0.3.0",
+    "@belvador/core": "0.3.0",
+    "@belvador/react": "0.3.0"
   },
   "publishConfig": {
     "access": "public",