@belvador/tanstack-start 0.2.0 → 0.4.0

package/README.md

@@ -46,6 +46,52 @@ Server functions and server routes are reported with their server stack; redirec
 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
@@ -56,8 +102,9 @@ 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/server.d.ts

@@ -1,6 +1,6 @@
 import { type WorkerOptions } from "@belvador/cloudflare";
 import { type VerificationResult, type VerifyOptions } from "@belvador/core";
-export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, flush, getDiagnostics, setContext, setTag, setTags, setUser, withScope, type BelvadorEnv, type Diagnostic, type DiagnosticCode, type DiagnosticsSnapshot, type WorkerOptions, } from "@belvador/cloudflare";
+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 })`:

package/dist/server.js

@@ -2,7 +2,7 @@
 // src/server.ts; add the middleware from "@belvador/tanstack-start" to src/start.ts.
 import { wrapHandler } from "@belvador/cloudflare";
 import { currentHooks, runVerification, } from "@belvador/core";
-export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, flush, getDiagnostics, setContext, setTag, setTags, setUser, withScope, } from "@belvador/cloudflare";
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@belvador/tanstack-start",
-  "version": "0.2.0",
+  "version": "0.4.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.2.0",
-    "@belvador/core": "0.2.0",
-    "@belvador/react": "0.2.0"
+    "@belvador/cloudflare": "0.4.0",
+    "@belvador/core": "0.4.0",
+    "@belvador/react": "0.4.0"
   },
   "publishConfig": {
     "access": "public",