@belvador/tanstack-start 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,81 @@
-# Temporary Holding Version
+# @belvador/tanstack-start
 
-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 [TanStack Start](https://tanstack.com/start) apps on Cloudflare Workers
+(including apps built with Lovable), sending to your [Belvador](https://belvador.dev) node.
+
+```sh
+npm install @belvador/tanstack-start
+```
+
+**Browser** — `src/router.tsx`:
+
+```ts
+import { belvadorOnCatch, init } from "@belvador/tanstack-start/client";
+
+if (typeof window !== "undefined") {
+  init({ dsn: "https://<key>@ingest.belvador.dev/<project>", release: import.meta.env.VITE_APP_VERSION });
+}
+// createRouter({ ..., defaultOnCatch: belvadorOnCatch })
+```
+
+**Server** — `src/server.ts` (set `tanstackStart: { server: { entry: "server" } }` in `vite.config.ts`):
+
+```ts
+import handler from "@tanstack/react-start/server-entry";
+import { withBelvador } from "@belvador/tanstack-start/server";
+
+export default withBelvador((env) => ({ release: env.BELVADOR_RELEASE }), {
+  fetch: (request, env, ctx) => handler.fetch(request, env, ctx),
+});
+```
+
+**Middleware** — `src/start.ts`, last in each list (closest to the handler):
+
+```ts
+import { createStart } from "@tanstack/react-start";
+import { belvadorFunctionMiddleware, belvadorRequestMiddleware } from "@belvador/tanstack-start";
+
+export const startInstance = createStart(() => ({
+  requestMiddleware: [/* your middleware */ belvadorRequestMiddleware],
+  functionMiddleware: [/* your middleware */ belvadorFunctionMiddleware],
+}));
+```
+
+Server functions and server routes are reported with their server stack; redirects,
+`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.
+
+## 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.
+
+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.
+
+## 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/client.d.ts

@@ -0,0 +1,5 @@
+import 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

@@ -0,0 +1,7 @@
+import { initReact } from "@belvador/react/internal";
+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) {
+    return initReact(options, "tanstack-start");
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export { SDK_VERSION } from "@belvador/core";
+/**
+ * Control flow, not failures: redirects, not-found, thrown Responses and
+ * 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;
+/**
+ * Request middleware: reports errors thrown by server routes and SSR, then
+ * re-throws so your own error handling runs unchanged. Put it LAST in
+ * `requestMiddleware` (closest to the handler) so it sees errors before an
+ * error-page middleware turns them into a response.
+ */
+export declare const belvadorRequestMiddleware: import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, undefined>;
+/** Server-function middleware: same contract, put it LAST in `functionMiddleware`. */
+export declare const belvadorFunctionMiddleware: import("@tanstack/react-start").FunctionMiddlewareAfterServer<{}, unknown, undefined, undefined, undefined, undefined, undefined>;
+/** For `createRouter({ defaultOnCatch: belvadorOnCatch })`: errors shown by a route's error boundary. */
+export declare function belvadorOnCatch(error: Error, errorInfo?: {
+    componentStack?: string | null;
+}): void;

package/dist/index.js

@@ -0,0 +1,76 @@
+// @belvador/tanstack-start — shared (client + server) pieces: middleware for
+// src/start.ts and the router's defaultOnCatch. Safe to import from both
+// bundles: it only calls the runtime-neutral capture API.
+import { isNotFound, isRedirect } from "@tanstack/react-router";
+import { createMiddleware } from "@tanstack/react-start";
+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 (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 {
+        if (typeof Response !== "undefined" && error instanceof Response)
+            return error.status < 500;
+        if (isRedirect(error) || isNotFound(error))
+            return true;
+        if (error !== null && typeof error === "object") {
+            const e = error;
+            const status = typeof e.statusCode === "number" ? e.statusCode : e.status;
+            if (typeof status === "number" && status < 500)
+                return true;
+        }
+    }
+    catch {
+        /* fall through: report it */
+    }
+    return false;
+}
+function report(error, kind) {
+    if (isExpectedError(error))
+        return;
+    captureException(error, {
+        mechanism: { type: `auto.belvador.tanstack_start.${kind}`, handled: false },
+    });
+}
+/**
+ * Request middleware: reports errors thrown by server routes and SSR, then
+ * re-throws so your own error handling runs unchanged. Put it LAST in
+ * `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, 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, signal }) => {
+    markHooked("middleware");
+    try {
+        return await next();
+    }
+    catch (error) {
+        noteClientAbort(error, signal);
+        report(error, "server_function");
+        throw error;
+    }
+});
+/** For `createRouter({ defaultOnCatch: belvadorOnCatch })`: errors shown by a route's error boundary. */
+export function belvadorOnCatch(error, errorInfo) {
+    if (isExpectedError(error))
+        return;
+    captureException(error, {
+        mechanism: { type: "auto.belvador.tanstack_start.route", handled: true },
+        ...(errorInfo?.componentStack ? { data: { componentStack: errorInfo.componentStack } } : {}),
+    });
+}

package/dist/server.d.ts

@@ -0,0 +1,16 @@
+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 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

@@ -0,0 +1,21 @@
+// @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";
+import { currentHooks, runVerification, } from "@belvador/core";
+export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, flush, 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.
+ */
+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,61 @@
 {
   "name": "@belvador/tanstack-start",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Belvador error tracking for TanStack Start on Cloudflare Workers: client, server entry and middleware.",
+  "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"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "default": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@belvador/cloudflare": "0.2.0",
+    "@belvador/core": "0.2.0",
+    "@belvador/react": "0.2.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "@tanstack/react-router": "^1.168.0",
+    "@tanstack/react-start": "^1.168.0",
+    "react": "^18.0.0 || ^19.0.0"
+  }
+}