@bigbertha/sdk 0.0.0-stage → 0.1.0

package/dist/generated/ingest.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Answer to `POST /ingest/v1/deploys`.
+ */
+export type DeployRecorded = {
+    releaseId: string;
+};
+/**
+ * `POST /ingest/v1/events`, gzip or plain JSON, `Authorization: Bearer <ingest key>`.
+ */
+export type IngestBatch = {
+    sdk: IngestSdk;
+    events: Array<IngestEvent>;
+};
+export type IngestBreadcrumb = {
+    timestamp: string;
+    category: string;
+    level?: string;
+    message: string;
+};
+export type IngestCommit = {
+    sha: string;
+    message: string;
+    author: string;
+};
+export type IngestContext = {
+    browser?: string;
+    os?: string;
+    runtime?: string;
+    userAgent?: string;
+};
+/**
+ * `POST /ingest/v1/deploys`, from CI after a deploy.
+ */
+export type IngestDeploy = {
+    release: string;
+    environment?: string;
+    commit?: IngestCommit;
+    /**
+     * Defaults to now.
+     */
+    deployedAt?: string;
+};
+/**
+ * Errors from ingest endpoints: `{ error: "…" }` with a 4xx status.
+ */
+export type IngestError = {
+    error: string;
+};
+export type IngestEvent = {
+    /**
+     * Client-generated id; repeats are dropped, so retries are safe.
+     */
+    id?: string;
+    /**
+     * When it happened, ISO 8601. Clamped to the last 7 days and now.
+     */
+    timestamp: string;
+    level?: IngestLevel;
+    /**
+     * Free text; mapped to production, staging or development.
+     */
+    environment?: string;
+    release?: string;
+    /**
+     * The error, with its `cause` chain.
+     */
+    exception?: IngestException;
+    /**
+     * For reports without an error object (`captureMessage`).
+     */
+    message?: string;
+    /**
+     * Oldest first.
+     */
+    breadcrumbs?: Array<IngestBreadcrumb>;
+    request?: IngestRequest;
+    user?: IngestUser;
+    context?: IngestContext;
+    tags?: {
+        [key in string]: string;
+    };
+    /**
+     * Overrides grouping: events with the same fingerprint are one issue.
+     */
+    fingerprint?: Array<string>;
+    /**
+     * Bundle file URL → debug id, for source maps.
+     */
+    debugIds?: {
+        [key in string]: string;
+    };
+};
+export type IngestException = {
+    type: string;
+    message: string;
+    /**
+     * Innermost (where it was thrown) first.
+     */
+    frames: Array<IngestFrame>;
+    cause?: IngestException;
+};
+export type IngestFrame = {
+    file: string;
+    function?: string;
+    line?: number;
+    column?: number;
+    /**
+     * The SDK's guess; the server decides from the file path when absent.
+     */
+    inApp?: boolean;
+};
+/**
+ * `POST /ingest/v1/heartbeat`: a long-running process saying it is alive, so
+ * bertha can tell "no errors" (0) from "no data" (a gap) in charts.
+ */
+export type IngestHeartbeat = {
+    environment?: string;
+    release?: string;
+};
+export type IngestLevel = "fatal" | "error" | "warning";
+export type IngestRequest = {
+    method: string;
+    url: string;
+    status?: number;
+};
+export type IngestResponse = {
+    accepted: number;
+    rejected: number;
+    /**
+     * Seconds to wait before sending again, when throttled.
+     */
+    retryAfter?: number;
+};
+export type IngestSdk = {
+    name: string;
+    version: string;
+};
+export type IngestUser = {
+    id?: string;
+    email?: string;
+    /**
+     * `"auto"` = use the address the report came from.
+     */
+    ip?: string;
+};
+/**
+ * Answer to `POST /ingest/v1/sourcemaps?debugId=…&file=…&release=…`
+ * (body: the raw map, gzip or plain).
+ */
+export type SourceMapUploaded = {
+    debugId: string;
+    sources: number;
+};

package/dist/generated/ingest.js

@@ -0,0 +1,2 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+export {};

package/dist/next/client.d.ts

@@ -0,0 +1,2 @@
+export { captureException, captureMessage, setTag, setUser } from "../core/hub.ts";
+export declare function onRouterTransitionStart(url: string, navigationType: "push" | "replace" | "traverse"): void;

package/dist/next/client.js

@@ -0,0 +1,34 @@
+// @bigbertha/sdk/next/client, for instrumentation-client.ts:
+//   export { onRouterTransitionStart } from "@bigbertha/sdk/next/client"
+// Importing it starts reporting. Next inlines the NEXT_PUBLIC_ variables below.
+import { init } from "../browser/index.js";
+import { addBreadcrumb } from "../core/hub.js";
+export { captureException, captureMessage, setTag, setUser } from "../core/hub.js";
+function read(f) {
+    try {
+        return f() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Written out in full so Next's compiler can replace each one.
+const key = read(() => process.env.NEXT_PUBLIC_BERTHA_KEY);
+const url = read(() => process.env.NEXT_PUBLIC_BERTHA_URL);
+if (typeof window === "undefined") {
+    // Prerendering on the server: instrumentation.ts covers that side.
+}
+else if (key && url) {
+    init({
+        key,
+        url,
+        release: read(() => process.env.BERTHA_RELEASE),
+        environment: read(() => process.env.NODE_ENV),
+    });
+}
+else {
+    console.warn("[bertha] Set NEXT_PUBLIC_BERTHA_KEY and NEXT_PUBLIC_BERTHA_URL. Nothing will be sent.");
+}
+export function onRouterTransitionStart(url, navigationType) {
+    addBreadcrumb({ category: "navigation", message: `${navigationType} ${url}` });
+}

package/dist/next/config.d.ts

@@ -0,0 +1,8 @@
+export interface BerthaNextOptions {
+    release?: string;
+    /** Keep .map files in `.next` after uploading. Default false. */
+    keepMaps?: boolean;
+    /** Skip the post-build step entirely (the release is still stamped). */
+    disableUpload?: boolean;
+}
+export declare function withBertha<C extends object>(config?: C, options?: BerthaNextOptions): C;

package/dist/next/config.js

@@ -0,0 +1,36 @@
+// @bigbertha/sdk/next/config, for next.config.ts:
+//   export default withBertha(nextConfig)
+// Turns on source maps for production builds, stamps the release, and after each
+// build gives bundles debug ids, uploads the maps and removes them from `.next`.
+import { join } from "node:path";
+import { detectRelease, processDirectory } from "../build/index.js";
+import { firstEnv } from "../core/env.js";
+export function withBertha(config = {}, options = {}) {
+    const c = config;
+    const release = options.release ?? detectRelease();
+    const previous = c.compiler?.runAfterProductionCompile;
+    const next = {
+        ...c,
+        productionBrowserSourceMaps: true,
+        env: { ...c.env, ...(release ? { BERTHA_RELEASE: release } : {}) },
+        experimental: { ...c.experimental, serverSourceMaps: true },
+        compiler: {
+            ...c.compiler,
+            async runAfterProductionCompile(meta) {
+                await previous?.(meta);
+                if (options.disableUpload)
+                    return;
+                await processDirectory({
+                    dir: meta.distDir ?? join(meta.projectDir, ".next"),
+                    release,
+                    url: firstEnv("BERTHA_URL", "NEXT_PUBLIC_BERTHA_URL"),
+                    uploadKey: firstEnv("BERTHA_UPLOAD_KEY"),
+                    keepMaps: options.keepMaps,
+                    skip: ["cache", "standalone", "types"],
+                    log: (m) => console.log(`[bertha] ${m}`),
+                }).catch((e) => console.warn(`[bertha] Source maps weren't processed: ${String(e)}`));
+            },
+        },
+    };
+    return next;
+}

package/dist/next/index.d.ts

@@ -0,0 +1,16 @@
+export declare function register(): Promise<void>;
+interface NextRequestInfo {
+    path: string;
+    method: string;
+    headers: Record<string, string | string[] | undefined>;
+}
+interface NextErrorContext {
+    routerKind: "Pages Router" | "App Router";
+    routePath: string;
+    routeType: "render" | "route" | "action" | "middleware" | "proxy";
+    renderSource?: string;
+    revalidateReason?: string;
+}
+/** Next calls this for errors in server components, route handlers, actions and middleware. */
+export declare function onRequestError(error: unknown, request: NextRequestInfo, context: NextErrorContext): Promise<void>;
+export {};

package/dist/next/index.js

@@ -0,0 +1,22 @@
+// @bigbertha/sdk/next, for instrumentation.ts:
+//   export { register, onRequestError } from "@bigbertha/sdk/next"
+import { captureException, flush } from "../core/hub.js";
+export async function register() {
+    if (process.env.NEXT_RUNTIME === "nodejs")
+        (await import("../node/index.js")).init();
+    else if (process.env.NEXT_RUNTIME === "edge")
+        (await import("../edge/index.js")).init();
+}
+/** Next calls this for errors in server components, route handlers, actions and middleware. */
+export async function onRequestError(error, request, context) {
+    const host = header(request.headers.host);
+    const proto = header(request.headers["x-forwarded-proto"]) ?? "https";
+    captureException(error, {
+        request: { method: request.method, url: host ? `${proto}://${host}${request.path}` : request.path },
+        tags: { route: context.routePath, routeType: context.routeType },
+    });
+    await flush();
+}
+function header(v) {
+    return Array.isArray(v) ? v[0] : v;
+}

package/dist/node/index.d.ts

@@ -0,0 +1,19 @@
+import { Client } from "../core/client.ts";
+import type { Options } from "../core/types.ts";
+export { addBreadcrumb, captureException, captureMessage, flush, getClient, setTag, setUser } from "../core/hub.ts";
+export type { CaptureContext, IngestEvent, Options } from "../core/types.ts";
+export interface NodeOptions extends Partial<Options> {
+    /** Report uncaught exceptions and unhandled rejections, then exit as Node would. On by default. */
+    handlers?: boolean;
+    /** Tell bertha the process is alive every 20 minutes. On by default. */
+    heartbeat?: boolean;
+}
+export declare const HEARTBEAT_MS: number;
+/** Reads BERTHA_KEY, BERTHA_URL, BERTHA_RELEASE and NODE_ENV unless given. */
+export declare function init(options?: NodeOptions): Client | undefined;
+export declare function sendHeartbeat(o: Pick<Options, "url" | "key" | "release" | "environment">): Promise<boolean>;
+/**
+ * Wraps a request handler (Node http, Express, Fastify, Hono…): errors it throws
+ * or rejects with are reported with the request, then rethrown.
+ */
+export declare function wrapHandler<A extends unknown[], R>(handler: (...args: A) => R): (...args: A) => R;

package/dist/node/index.js

@@ -0,0 +1,98 @@
+// @bigbertha/sdk/node: uncaught exceptions and unhandled rejections, a heartbeat so
+// quiet hours read as "no errors" rather than "no data", and a handler wrapper.
+import { arch, platform } from "node:os";
+import { gzipSync } from "node:zlib";
+import { Client } from "../core/client.js";
+import { firstEnv } from "../core/env.js";
+import { getClient, setClient } from "../core/hub.js";
+import { endpoint, fetchTransport } from "../core/transport.js";
+import { VERSION } from "../core/version.js";
+export { addBreadcrumb, captureException, captureMessage, flush, getClient, setTag, setUser } from "../core/hub.js";
+export const HEARTBEAT_MS = 20 * 60 * 1000;
+const EXIT_FLUSH_MS = 2000;
+let handlersInstalled = false;
+let heartbeat;
+/** Reads BERTHA_KEY, BERTHA_URL, BERTHA_RELEASE and NODE_ENV unless given. */
+export function init(options = {}) {
+    const key = options.key ?? firstEnv("BERTHA_KEY", "NEXT_PUBLIC_BERTHA_KEY");
+    const url = options.url ?? firstEnv("BERTHA_URL", "NEXT_PUBLIC_BERTHA_URL");
+    if (!key || !url) {
+        console.warn("[bertha] Set BERTHA_KEY and BERTHA_URL (or pass key and url). Nothing will be sent.");
+        return undefined;
+    }
+    const opts = {
+        ...options,
+        key,
+        url,
+        release: options.release ?? firstEnv("BERTHA_RELEASE"),
+        environment: options.environment ?? firstEnv("BERTHA_ENVIRONMENT", "NODE_ENV"),
+    };
+    const client = new Client(opts, fetchTransport({ url, key, gzip: async (body) => new Uint8Array(gzipSync(body)) }), { name: "bertha.node", version: VERSION }, { runtime: `Node ${process.versions.node}`, os: `${platform()} ${arch()}` });
+    setClient(client);
+    if (options.handlers !== false && !handlersInstalled) {
+        handlersInstalled = true;
+        process.on("uncaughtException", (error) => void crash("uncaughtException", error));
+        process.on("unhandledRejection", (reason) => void crash("unhandledRejection", reason));
+        process.on("beforeExit", () => void getClient()?.flush());
+    }
+    if (options.heartbeat !== false) {
+        clearInterval(heartbeat);
+        const beat = () => void sendHeartbeat(opts);
+        beat();
+        heartbeat = setInterval(beat, HEARTBEAT_MS);
+        heartbeat.unref();
+    }
+    return client;
+}
+/** Reports, flushes and then, if nothing else is listening, exits as Node would have. */
+async function crash(event, error) {
+    const client = getClient();
+    client?.captureException(error, { level: "fatal" });
+    await Promise.race([client?.flush(), new Promise((r) => setTimeout(r, EXIT_FLUSH_MS).unref())]);
+    if (process.listenerCount(event) > 1)
+        return;
+    console.error(event === "unhandledRejection" && !(error instanceof Error) ? `Unhandled rejection: ${String(error)}` : error);
+    process.exit(1);
+}
+export async function sendHeartbeat(o) {
+    try {
+        const res = await fetch(endpoint(o.url, "heartbeat"), {
+            method: "POST",
+            headers: { authorization: `Bearer ${o.key}`, "content-type": "application/json" },
+            body: JSON.stringify({ environment: o.environment, release: o.release }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Wraps a request handler (Node http, Express, Fastify, Hono…): errors it throws
+ * or rejects with are reported with the request, then rethrown.
+ */
+export function wrapHandler(handler) {
+    return function (...args) {
+        const report = (error) => {
+            getClient()?.captureException(error, requestContext(args[0]));
+            throw error;
+        };
+        try {
+            const r = handler.apply(this, args);
+            return (r instanceof Promise ? r.catch(report) : r);
+        }
+        catch (error) {
+            return report(error);
+        }
+    };
+}
+function requestContext(req) {
+    const r = req;
+    if (!r || typeof r.method !== "string")
+        return {};
+    const path = r.originalUrl ?? r.url ?? "/";
+    const host = typeof r.headers?.host === "string" ? r.headers.host : undefined;
+    const proto = typeof r.headers?.["x-forwarded-proto"] === "string" ? r.headers["x-forwarded-proto"] : "http";
+    return { request: { method: r.method, url: host && path.startsWith("/") ? `${proto}://${host}${path}` : path } };
+}

package/dist/vite/index.d.ts

@@ -0,0 +1,44 @@
+import { type Report } from "../build/index.ts";
+export interface BerthaViteOptions {
+    release?: string;
+    url?: string;
+    uploadKey?: string;
+    /** Keep .map files in the output after uploading. Default false. */
+    keepMaps?: boolean;
+    /** Called with what was uploaded, for tests and custom logging. */
+    onReport?: (report: Report) => void;
+}
+interface ResolvedConfig {
+    root: string;
+    mode: string;
+    build: {
+        outDir: string;
+        ssr?: unknown;
+    };
+    logger: {
+        info(msg: string): void;
+        warn(msg: string): void;
+    };
+}
+export interface VitePlugin {
+    name: string;
+    apply: "build";
+    enforce: "post";
+    config(config: {
+        build?: {
+            sourcemap?: unknown;
+        };
+    }): {
+        build: {
+            sourcemap: "hidden";
+        };
+    } | undefined;
+    configResolved(config: ResolvedConfig): Promise<void>;
+    closeBundle: {
+        order: "post";
+        sequential: true;
+        handler(): Promise<void>;
+    };
+}
+export declare function bertha(options?: BerthaViteOptions): VitePlugin;
+export {};

package/dist/vite/index.js

@@ -0,0 +1,63 @@
+// @bigbertha/sdk/vite: plugins: [bertha()]
+// Builds with hidden source maps, then gives bundles debug ids, uploads the maps
+// and removes them from the output. Reads BERTHA_UPLOAD_KEY and VITE_BERTHA_URL
+// (or BERTHA_URL) from the environment or .env files.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { resolve } from "node:path";
+import { detectRelease, processDirectory } from "../build/index.js";
+export function bertha(options = {}) {
+    let outDir = "";
+    let root = "";
+    let env = {};
+    let logger;
+    return {
+        name: "bertha",
+        apply: "build",
+        enforce: "post",
+        config(config) {
+            if (!config.build?.sourcemap)
+                return { build: { sourcemap: "hidden" } };
+            return undefined;
+        },
+        async configResolved(config) {
+            root = config.root;
+            outDir = resolve(config.root, config.build.outDir);
+            logger = config.logger;
+            try {
+                const vite = (await import(__rewriteRelativeImportExtension("vite")));
+                env = vite.loadEnv(config.mode, config.root, "");
+            }
+            catch {
+                env = {};
+            }
+        },
+        closeBundle: {
+            order: "post",
+            sequential: true,
+            async handler() {
+                const pick = (...names) => names.map((n) => process.env[n] || env[n]).find(Boolean);
+                try {
+                    const report = await processDirectory({
+                        dir: outDir,
+                        release: options.release ?? pick("BERTHA_RELEASE") ?? detectRelease(root),
+                        url: options.url ?? pick("BERTHA_URL", "VITE_BERTHA_URL"),
+                        uploadKey: options.uploadKey ?? pick("BERTHA_UPLOAD_KEY"),
+                        keepMaps: options.keepMaps,
+                        log: (m) => logger?.info(`[bertha] ${m}`),
+                    });
+                    options.onReport?.(report);
+                }
+                catch (e) {
+                    logger?.warn(`[bertha] Source maps weren't processed: ${String(e)}`);
+                }
+            },
+        },
+    };
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@bigbertha/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Error reporting for bertha: browser, Node, edge and Next.js, with source maps by debug id.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/felixowens/bertha.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://github.com/felixowens/bertha/tree/main/sdk#readme",
+  "keywords": [
+    "error-tracking",
+    "bertha",
+    "nextjs",
+    "vite",
+    "source-maps"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": [
+    "./dist/next/client.js"
+  ],
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "bertha": "./dist/bin.js"
+  },
+  "exports": {
+    "./browser": "./dist/browser/index.js",
+    "./node": "./dist/node/index.js",
+    "./edge": "./dist/edge/index.js",
+    "./next": "./dist/next/index.js",
+    "./next/client": "./dist/next/client.js",
+    "./next/config": "./dist/next/config.js",
+    "./vite": "./dist/vite/index.js",
+    "./build": "./dist/build/index.js",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/bin.js",
+    "check": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "size": "node scripts/size.ts",
+    "e2e": "node e2e/run.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "esbuild": "^0.27.0",
+    "typescript": "~6.0.2",
+    "vite": "^8.3.4",
+    "vitest": "^4.0.0"
+  }
+}