@errorgap/bun 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,13 @@
 # @errorgap/bun
 
-Bun notifier for [Errorgap](https://errorgap.com). Errors only in v1.
+Bun notifier for [Errorgap](https://errorgap.com). Captures errors with
+source-aware backtraces, nested `Error.cause` chains, breadcrumbs, structured
+logs, and APM transactions.
+
+Because Bun executes TypeScript directly, backtrace frames point at the
+original source, so each frame ships a source excerpt (file, line, function,
+and surrounding lines) read straight from disk — the dashboard renders
+highlighted source with no build step or source maps.
 
 Requires Bun 1.0+.
 
@@ -44,6 +51,48 @@ try {
 `notify` returns a `DeliveryResult` (`status`, `body`, `error`, `queued`).
 The SDK never throws.
 
+Nested errors are captured automatically: pass a chain built with
+`new Error("…", { cause })` and each cause's type/message lands in
+`context.causes` while its frames merge into the backtrace.
+
+## Breadcrumbs
+
+```ts
+Errorgap.addBreadcrumb("received GET /orders", { category: "http" });
+```
+
+Recorded breadcrumbs attach to every notice as `context.breadcrumbs`.
+
+## Structured logs
+
+```ts
+await Errorgap.log("payment gateway timeout", "error", { source: "payments" });
+```
+
+Levels are `trace < debug < info < warn < error < fatal`; anything below
+`minimumLogLevel` is dropped client-side.
+
+## Performance (APM)
+
+```ts
+await Errorgap.trackTransaction(
+  { method: "GET", path: "/orders/{orderId}", pathRaw: "/orders/123" },
+  async (spans) => {
+    spans.database("SELECT * FROM orders WHERE id = 123", 4.2, { function: "OrderRepo.get" });
+    spans.external(88, { function: "PaymentGateway.charge" });
+    await handleRequest();
+  },
+);
+
+await Errorgap.trackJob("ReceiptJob", async (spans) => {
+  spans.database("INSERT INTO receipts …", 6);
+}, { queue: "mailers" });
+```
+
+`path` is the normalized route template used for grouping; `path_raw` is the
+concrete URL. Both helpers time the callback and deliver on completion. Use
+`Errorgap.notifyTransaction(...)` for a pre-measured transaction.
+
 ## Configuration reference
 
 | Option | Default | Notes |
@@ -53,10 +102,16 @@ The SDK never throws.
 | `projectId` | `ERRORGAP_PROJECT_ID` | |
 | `apiKey` | `ERRORGAP_API_KEY` | Sent as `x-errorgap-project-key` |
 | `environment` | `NODE_ENV` or `"production"` | |
-| `release` | — | |
+| `release` | `ERRORGAP_RELEASE` | |
+| `rootDirectory` | `process.cwd()` | Relativizes backtrace source paths |
 | `async` | `true` | Fire-and-forget delivery |
 | `logger` | `console` | Pass `null` to silence |
 | `filterKeys` | `["password", "token", ...]` | Substring, case-insensitive |
+| `apmEnabled` | `true` | Deliver APM transactions |
+| `apmSampleRate` | `1.0` | Fraction (0..1) of transactions delivered |
+| `logsEnabled` | `true` | Deliver structured logs |
+| `minimumLogLevel` | `info` | Drop logs below this level |
+| `maxBreadcrumbs` | `25` | Breadcrumbs retained per notice |
 | `captureGlobals` | `true` | Install process error hooks |
 
 ## Graceful flush

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@errorgap/bun",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Bun notifier for Errorgap error tracking.",
   "license": "MIT",
   "author": "Errorgap",
@@ -9,7 +9,13 @@
     "type": "git",
     "url": "https://github.com/errorgaphq/errorgap-bun.git"
   },
-  "keywords": ["errorgap", "bun", "error-tracking", "exceptions", "monitoring"],
+  "keywords": [
+    "errorgap",
+    "bun",
+    "error-tracking",
+    "exceptions",
+    "monitoring"
+  ],
   "type": "module",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
@@ -21,7 +27,11 @@
     },
     "./package.json": "./package.json"
   },
-  "files": ["src", "README.md", "LICENSE"],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "engines": {
     "bun": ">=1.0.0"
   },

package/src/apm.ts

@@ -0,0 +1,104 @@
+import type { Configuration } from "./configuration.js";
+
+export interface Span {
+  kind: string;
+  sql?: string;
+  file?: string;
+  line?: number;
+  function?: string;
+  durationMs: number;
+}
+
+export interface SpanLocation {
+  file?: string;
+  line?: number;
+  function?: string;
+}
+
+export function databaseSpan(sql: string, durationMs: number, location: SpanLocation = {}): Span {
+  return { kind: "db", sql: normalizeSql(sql), durationMs, ...location };
+}
+
+export function externalSpan(durationMs: number, location: SpanLocation = {}): Span {
+  return { kind: "http", durationMs, ...location };
+}
+
+/** Collects spans recorded while a transaction or job is in flight. */
+export class SpanCollector {
+  private spans: Span[] = [];
+
+  add(span: Span): void {
+    this.spans.push(span);
+  }
+
+  database(sql: string, durationMs: number, location: SpanLocation = {}): void {
+    this.add(databaseSpan(sql, durationMs, location));
+  }
+
+  external(durationMs: number, location: SpanLocation = {}): void {
+    this.add(externalSpan(durationMs, location));
+  }
+
+  snapshot(): Span[] {
+    return [...this.spans];
+  }
+}
+
+export interface Transaction {
+  /** "web" for HTTP interactions, "job" for background work. */
+  kind?: string;
+  method?: string;
+  /** Normalized route template used for grouping, e.g. `/orders/{id}`. */
+  path?: string;
+  /** Concrete path for a single request, e.g. `/orders/123`. */
+  pathRaw?: string;
+  statusCode?: number;
+  durationMs: number;
+  environment?: string;
+  /** ISO-8601. Defaults to now. */
+  occurredAt?: string;
+  spans?: Span[];
+  jobClass?: string;
+  queue?: string;
+}
+
+export function transactionPayload(
+  transaction: Transaction,
+  configuration: Configuration,
+): Record<string, unknown> {
+  const payload: Record<string, unknown> = {
+    kind: transaction.kind ?? "web",
+    duration_ms: transaction.durationMs,
+    environment: transaction.environment ?? configuration.environment,
+    occurred_at: transaction.occurredAt ?? new Date().toISOString(),
+    spans: (transaction.spans ?? []).map(spanPayload),
+  };
+  if (transaction.method !== undefined) payload.method = transaction.method;
+  if (transaction.path !== undefined) payload.path = transaction.path;
+  if (transaction.pathRaw !== undefined) payload.path_raw = transaction.pathRaw;
+  if (transaction.statusCode !== undefined) payload.status_code = transaction.statusCode;
+  if (transaction.jobClass !== undefined) payload.job_class = transaction.jobClass;
+  if (transaction.queue !== undefined) payload.queue = transaction.queue;
+  return payload;
+}
+
+function spanPayload(span: Span): Record<string, unknown> {
+  const payload: Record<string, unknown> = {
+    kind: span.kind,
+    duration_ms: span.durationMs,
+  };
+  if (span.sql !== undefined) payload.sql = span.sql;
+  if (span.file !== undefined) payload.file = span.file;
+  if (span.line !== undefined) payload.line = span.line;
+  if (span.function !== undefined) payload.fn_name = span.function;
+  return payload;
+}
+
+/** Strip literals so query shapes aggregate: '…' and numbers become ?. */
+export function normalizeSql(sql: string): string {
+  return sql
+    .replace(/'(?:''|[^'])*'/g, "?")
+    .replace(/\b\d+(?:\.\d+)?\b/g, "?")
+    .replace(/\s+/g, " ")
+    .trim();
+}

package/src/backtrace.ts

@@ -1,19 +1,44 @@
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+export interface SourceExcerpt {
+  start_line: number;
+  lines: string[];
+}
+
 export interface BacktraceFrame {
   file?: string;
   line?: number;
+  column?: number;
   function?: string;
   in_app?: boolean;
   index: number;
+  source?: SourceExcerpt;
 }
 
 const V8_AT = /^\s*at\s+(?:(.*?)\s+\()?(.+?)(?::(\d+))?(?::(\d+))?\)?$/;
 
-export function parseBacktrace(error: Error): BacktraceFrame[] {
+const SOURCE_CONTEXT_RADIUS = 6;
+const MAX_SOURCE_LINE_CHARS = 400;
+const MAX_SOURCE_FILE_BYTES = 2 * 1024 * 1024;
+
+/** Cache of file line arrays, keyed by resolved path, for one notice build. */
+const fileCache = new Map<string, string[] | null>();
+
+/**
+ * Parse a V8-style `Error.stack` into Errorgap frames. Because Bun executes
+ * TypeScript directly, frame locations point at the original source files, so
+ * each frame's source excerpt is read straight from disk.
+ */
+export function parseBacktrace(error: Error, rootDirectory?: string): BacktraceFrame[] {
   const stack = typeof error.stack === "string" ? error.stack : "";
   if (!stack) return [];
+  fileCache.clear();
+
   const lines = stack.split("\n");
   const frames: BacktraceFrame[] = [];
   let index = 0;
+
   for (const raw of lines) {
     const trimmed = raw.trim();
     if (!trimmed.startsWith("at ")) continue;
@@ -21,15 +46,25 @@ export function parseBacktrace(error: Error): BacktraceFrame[] {
     if (!m) continue;
     const fnName = m[1];
     const location = (m[2] ?? "").replace(/^file:\/\//, "");
-    const lineNumber = m[3] ? Number(m[3]) : undefined;
-    frames.push({
-      file: location,
-      line: lineNumber,
+    const line = m[3] ? Number(m[3]) : undefined;
+    const column = m[4] ? Number(m[4]) : undefined;
+
+    const frame: BacktraceFrame = {
+      file: displayPath(location, rootDirectory),
+      line,
+      column,
       function: fnName || undefined,
       in_app: isInApp(location),
       index: index++,
-    });
+    };
+
+    const source = sourceExcerpt(location, line, rootDirectory);
+    if (source) frame.source = source;
+
+    frames.push(frame);
   }
+
+  fileCache.clear();
   return frames;
 }
 
@@ -40,3 +75,53 @@ function isInApp(file: string): boolean {
   if (file.startsWith("bun:")) return false; // Bun internal modules
   return true;
 }
+
+/** Strip the app root prefix for a cleaner in-app display path. */
+function displayPath(file: string, root?: string): string {
+  if (!file) return file;
+  if (root) {
+    const normalized = root.endsWith("/") ? root : root + "/";
+    if (file.startsWith(normalized)) return file.slice(normalized.length);
+  }
+  return file;
+}
+
+function sourceExcerpt(
+  file: string,
+  line: number | undefined,
+  root?: string,
+): SourceExcerpt | undefined {
+  if (!file || !line || line < 1) return undefined;
+  if (file.startsWith("node:") || file.startsWith("bun:")) return undefined;
+
+  const contents = readSourceLines(resolvePath(file, root));
+  if (!contents || line > contents.length) return undefined;
+
+  const startLine = Math.max(1, line - SOURCE_CONTEXT_RADIUS);
+  const endLine = Math.min(contents.length, line + SOURCE_CONTEXT_RADIUS);
+  return {
+    start_line: startLine,
+    lines: contents.slice(startLine - 1, endLine).map((l) => l.slice(0, MAX_SOURCE_LINE_CHARS)),
+  };
+}
+
+function resolvePath(file: string, root?: string): string {
+  if (isAbsolute(file)) return file;
+  if (root) return join(root, file);
+  return file;
+}
+
+function readSourceLines(path: string): string[] | null {
+  if (fileCache.has(path)) return fileCache.get(path) ?? null;
+  let lines: string[] | null = null;
+  try {
+    const stat = statSync(path);
+    if (stat.isFile() && stat.size <= MAX_SOURCE_FILE_BYTES) {
+      lines = readFileSync(path, "utf8").split(/\r?\n/);
+    }
+  } catch {
+    lines = null;
+  }
+  fileCache.set(path, lines);
+  return lines;
+}

package/src/breadcrumbs.ts

@@ -0,0 +1,42 @@
+export interface Breadcrumb {
+  message: string;
+  category?: string;
+  metadata?: Record<string, unknown>;
+  timestamp: string;
+}
+
+export interface BreadcrumbInput {
+  category?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Fixed-size ring of recent app events (requests, queries, jobs) attached to
+ * every notice as `context.breadcrumbs`.
+ */
+export class BreadcrumbBuffer {
+  private crumbs: Breadcrumb[] = [];
+
+  constructor(private capacity: number) {}
+
+  add(message: string, input: BreadcrumbInput = {}): void {
+    if (this.capacity <= 0) return;
+    this.crumbs.push({
+      message,
+      ...(input.category !== undefined ? { category: input.category } : {}),
+      ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+      timestamp: new Date().toISOString(),
+    });
+    if (this.crumbs.length > this.capacity) {
+      this.crumbs.splice(0, this.crumbs.length - this.capacity);
+    }
+  }
+
+  clear(): void {
+    this.crumbs = [];
+  }
+
+  snapshot(): Breadcrumb[] {
+    return [...this.crumbs];
+  }
+}

package/src/client.ts

@@ -1,5 +1,7 @@
 import type { Configuration } from "./configuration.js";
 import { buildNotice, type NoticeContext, type NoticePayload } from "./notice.js";
+import { transactionPayload, type Transaction } from "./apm.js";
+import { logLevelRank, normalizeLogLevel } from "./logs.js";
 import { VERSION } from "./version.js";
 
 export interface DeliveryResult {
@@ -9,6 +11,13 @@ export interface DeliveryResult {
   queued?: boolean;
 }
 
+export interface LogOptions {
+  source?: string;
+  environment?: string;
+  occurredAt?: string;
+  sync?: boolean;
+}
+
 export class Client {
   private pending = new Set<Promise<unknown>>();
 
@@ -26,23 +35,80 @@ export class Client {
       this.configuration.validate();
       const err = coerceError(error);
       const notice = buildNotice(err, this.configuration, options);
+      return this.submit("notices", notice, options.sync);
+    } catch (exception) {
+      this.log(exception);
+      return { error: exception };
+    }
+  }
 
-      if (options.sync || !this.configuration.async) {
-        const p = this.deliver(notice);
-        this.track(p);
-        return await p;
-      }
+  /** Deliver an APM transaction (HTTP interaction or background job). */
+  async notifyTransaction(
+    transaction: Transaction,
+    options: { sync?: boolean } = {},
+  ): Promise<DeliveryResult> {
+    try {
+      this.configuration.validate();
+    } catch (exception) {
+      this.log(exception);
+      return { error: exception };
+    }
+    if (!this.configuration.apmEnabled) {
+      return { status: 204 };
+    }
+    const rate = this.configuration.apmSampleRate;
+    if (!(rate >= 1 || (rate > 0 && Math.random() < rate))) {
+      return { status: 204 };
+    }
+    return this.submit("transactions", transactionPayload(transaction, this.configuration), options.sync);
+  }
 
-      this.track(this.deliver(notice));
-      return { queued: true, status: 202 };
+  /** Deliver a structured log line. */
+  async notifyLog(
+    message: string,
+    level = "info",
+    options: LogOptions = {},
+  ): Promise<DeliveryResult> {
+    try {
+      this.configuration.validate();
     } catch (exception) {
       this.log(exception);
       return { error: exception };
     }
+    const normalizedLevel = normalizeLogLevel(level);
+    if (
+      !this.configuration.logsEnabled ||
+      logLevelRank(normalizedLevel) <
+        logLevelRank(normalizeLogLevel(this.configuration.minimumLogLevel))
+    ) {
+      return { status: 204 };
+    }
+    const payload: Record<string, unknown> = {
+      message,
+      level: normalizedLevel,
+      environment: options.environment ?? this.configuration.environment,
+      occurred_at: options.occurredAt ?? new Date().toISOString(),
+    };
+    if (options.source) payload.source = options.source;
+    return this.submit("logs", payload, options.sync);
+  }
+
+  private async submit(
+    resource: string,
+    payload: unknown,
+    sync?: boolean,
+  ): Promise<DeliveryResult> {
+    if (sync || !this.configuration.async) {
+      const p = this.deliver(resource, payload);
+      this.track(p);
+      return await p;
+    }
+    this.track(this.deliver(resource, payload));
+    return { queued: true, status: 202 };
   }
 
-  async deliver(notice: NoticePayload): Promise<DeliveryResult> {
-    const url = noticesUrl(this.configuration);
+  async deliver(resource: string, payload: unknown): Promise<DeliveryResult> {
+    const url = resourceUrl(this.configuration, resource);
     const headers: Record<string, string> = {
       "content-type": "application/json",
       "user-agent": `errorgap-bun/${VERSION}`,
@@ -54,7 +120,7 @@ export class Client {
       const response = await fetch(url, {
         method: "POST",
         headers,
-        body: JSON.stringify(notice),
+        body: JSON.stringify(payload),
       });
       const body = await safeBody(response);
       return { status: response.status, body };
@@ -79,18 +145,19 @@ export class Client {
   private log(exception: unknown): void {
     const logger = this.configuration.logger;
     if (!logger) return;
-    const message = exception instanceof Error
-      ? `${exception.name}: ${exception.message}`
-      : String(exception);
+    const message =
+      exception instanceof Error
+        ? `${exception.name}: ${exception.message}`
+        : String(exception);
     logger.warn(`[errorgap] ${message}`);
   }
 }
 
-function noticesUrl(configuration: Configuration): string {
+function resourceUrl(configuration: Configuration, resource: string): string {
   const base = configuration.endpoint.endsWith("/")
     ? configuration.endpoint.slice(0, -1)
     : configuration.endpoint;
-  return `${base}/api/projects/${configuration.projectSlug}/notices`;
+  return `${base}/api/projects/${configuration.projectSlug}/${resource}`;
 }
 
 async function safeBody(response: Response): Promise<string> {

package/src/configuration.ts

@@ -12,6 +12,18 @@ export interface ConfigurationInput {
   async?: boolean;
   logger?: Logger | null;
   filterKeys?: string[];
+  /** Root directory used to relativize backtrace source paths. Default cwd. */
+  rootDirectory?: string;
+  /** Enable APM transaction delivery. Default true. */
+  apmEnabled?: boolean;
+  /** Fraction (0..1) of transactions to deliver. Default 1. */
+  apmSampleRate?: number;
+  /** Enable structured log delivery. Default true. */
+  logsEnabled?: boolean;
+  /** Drop logs below this level (trace<debug<info<warn<error<fatal). Default "info". */
+  minimumLogLevel?: string;
+  /** Number of breadcrumbs retained and attached to notices. Default 25. */
+  maxBreadcrumbs?: number;
 }
 
 const DEFAULT_FILTER_KEYS = [
@@ -34,6 +46,12 @@ export class Configuration {
   async: boolean;
   logger: Logger | null;
   filterKeys: string[];
+  rootDirectory: string;
+  apmEnabled: boolean;
+  apmSampleRate: number;
+  logsEnabled: boolean;
+  minimumLogLevel: string;
+  maxBreadcrumbs: number;
 
   constructor(input: ConfigurationInput = {}) {
     this.endpoint = input.endpoint ?? process.env.ERRORGAP_ENDPOINT ?? "http://127.0.0.1:3030";
@@ -41,10 +59,16 @@ export class Configuration {
     this.projectId = input.projectId ?? process.env.ERRORGAP_PROJECT_ID;
     this.apiKey = input.apiKey ?? process.env.ERRORGAP_API_KEY;
     this.environment = input.environment ?? process.env.NODE_ENV ?? "production";
-    this.release = input.release;
+    this.release = input.release ?? process.env.ERRORGAP_RELEASE;
     this.async = input.async ?? true;
     this.logger = input.logger === undefined ? console : input.logger;
     this.filterKeys = input.filterKeys ?? [...DEFAULT_FILTER_KEYS];
+    this.rootDirectory = input.rootDirectory ?? process.cwd();
+    this.apmEnabled = input.apmEnabled ?? true;
+    this.apmSampleRate = clampRate(input.apmSampleRate ?? 1);
+    this.logsEnabled = input.logsEnabled ?? true;
+    this.minimumLogLevel = input.minimumLogLevel ?? "info";
+    this.maxBreadcrumbs = Math.max(0, Math.trunc(input.maxBreadcrumbs ?? 25));
   }
 
   validate(): void {
@@ -56,3 +80,8 @@ export class Configuration {
     }
   }
 }
+
+function clampRate(rate: number): number {
+  if (!Number.isFinite(rate)) return 1;
+  return Math.min(1, Math.max(0, rate));
+}

package/src/handlers.ts

@@ -1,4 +1,5 @@
 import type { Client } from "./client.js";
+import type { BreadcrumbBuffer } from "./breadcrumbs.js";
 
 let installed = false;
 let uncaughtHandler: ((err: Error) => void) | null = null;
@@ -8,19 +9,23 @@ let rejectionHandler: ((reason: unknown) => void) | null = null;
  * Hook Bun's `uncaughtException` and `unhandledRejection` events on the
  * Node-compatible `process` global.
  */
-export function installProcessHandlers(client: Client): void {
+export function installProcessHandlers(client: Client, breadcrumbs?: BreadcrumbBuffer): void {
   if (installed) return;
   installed = true;
+  const snapshot = () => breadcrumbs?.snapshot() ?? [];
+
   uncaughtHandler = (err: Error) => {
     void client.notify(err, {
       sync: true,
       context: { source: "uncaughtException" },
+      breadcrumbs: snapshot(),
     });
   };
   rejectionHandler = (reason: unknown) => {
     void client.notify(reason, {
       sync: true,
       context: { source: "unhandledRejection" },
+      breadcrumbs: snapshot(),
     });
   };
   process.on("uncaughtException", uncaughtHandler);

package/src/index.ts

@@ -1,19 +1,26 @@
-import { Client, type DeliveryResult } from "./client.js";
+import { Client, type DeliveryResult, type LogOptions } from "./client.js";
 import { Configuration, type ConfigurationInput } from "./configuration.js";
 import { installProcessHandlers, uninstallProcessHandlers } from "./handlers.js";
+import { BreadcrumbBuffer, type BreadcrumbInput } from "./breadcrumbs.js";
+import { SpanCollector, type Transaction } from "./apm.js";
 import type { NoticeContext } from "./notice.js";
 import { VERSION } from "./version.js";
 
 export type { ConfigurationInput, Logger } from "./configuration.js";
-export type { BacktraceFrame } from "./backtrace.js";
-export type { NoticeContext, NoticePayload } from "./notice.js";
-export type { DeliveryResult } from "./client.js";
+export type { BacktraceFrame, SourceExcerpt } from "./backtrace.js";
+export type { NoticeContext, NoticePayload, NoticeCause } from "./notice.js";
+export type { DeliveryResult, LogOptions } from "./client.js";
+export type { Breadcrumb, BreadcrumbInput } from "./breadcrumbs.js";
+export type { Span, SpanLocation, Transaction } from "./apm.js";
 export { Client } from "./client.js";
 export { Configuration } from "./configuration.js";
+export { SpanCollector, databaseSpan, externalSpan, normalizeSql } from "./apm.js";
+export { BreadcrumbBuffer } from "./breadcrumbs.js";
 export { VERSION };
 
 let configuration = new Configuration();
 let client = new Client(configuration);
+let breadcrumbs = new BreadcrumbBuffer(configuration.maxBreadcrumbs);
 
 export interface InitOptions extends ConfigurationInput {
   /** Install process.uncaughtException / unhandledRejection handlers. */
@@ -24,8 +31,9 @@ function init(options: InitOptions = {}): void {
   const { captureGlobals = true, ...rest } = options;
   configuration = new Configuration(rest);
   client.configure(configuration);
+  breadcrumbs = new BreadcrumbBuffer(configuration.maxBreadcrumbs);
   if (captureGlobals) {
-    installProcessHandlers(client);
+    installProcessHandlers(client, breadcrumbs);
   } else {
     uninstallProcessHandlers();
   }
@@ -35,7 +43,80 @@ function notify(
   error: unknown,
   options: NoticeContext & { sync?: boolean } = {},
 ): Promise<DeliveryResult> {
-  return client.notify(error, options);
+  return client.notify(error, { breadcrumbs: breadcrumbs.snapshot(), ...options });
+}
+
+/** Record a diagnostic breadcrumb attached to subsequent notices. */
+function addBreadcrumb(message: string, input: BreadcrumbInput = {}): void {
+  breadcrumbs.add(message, input);
+}
+
+function clearBreadcrumbs(): void {
+  breadcrumbs.clear();
+}
+
+/** Deliver a structured log line at the given level. */
+function log(message: string, level = "info", options: LogOptions = {}): Promise<DeliveryResult> {
+  return client.notifyLog(message, level, options);
+}
+
+/** Deliver an APM transaction (HTTP interaction or background job). */
+function notifyTransaction(
+  transaction: Transaction,
+  options: { sync?: boolean } = {},
+): Promise<DeliveryResult> {
+  return client.notifyTransaction(transaction, options);
+}
+
+/**
+ * Time an HTTP interaction and deliver it as a transaction. The callback
+ * receives a `SpanCollector` for recording DB/HTTP spans.
+ */
+async function trackTransaction<T>(
+  meta: Omit<Transaction, "durationMs" | "spans" | "kind"> & { kind?: string },
+  operation: (spans: SpanCollector) => Promise<T> | T,
+): Promise<T> {
+  const spans = new SpanCollector();
+  const startedAt = new Date().toISOString();
+  const start = Date.now();
+  try {
+    return await operation(spans);
+  } finally {
+    void notifyTransaction({
+      kind: meta.kind ?? "web",
+      ...meta,
+      occurredAt: meta.occurredAt ?? startedAt,
+      durationMs: Date.now() - start,
+      spans: spans.snapshot(),
+    });
+  }
+}
+
+/**
+ * Time a background job and deliver it as a `job` transaction. The callback
+ * receives a `SpanCollector` for recording DB/HTTP spans.
+ */
+async function trackJob<T>(
+  jobClass: string,
+  operation: (spans: SpanCollector) => Promise<T> | T,
+  meta: { queue?: string; environment?: string } = {},
+): Promise<T> {
+  const spans = new SpanCollector();
+  const startedAt = new Date().toISOString();
+  const start = Date.now();
+  try {
+    return await operation(spans);
+  } finally {
+    void notifyTransaction({
+      kind: "job",
+      jobClass,
+      queue: meta.queue ?? "default",
+      environment: meta.environment,
+      occurredAt: startedAt,
+      durationMs: Date.now() - start,
+      spans: spans.snapshot(),
+    });
+  }
 }
 
 function flush(): Promise<void> {
@@ -53,10 +134,26 @@ function getClient(): Client {
 export const Errorgap = {
   init,
   notify,
+  addBreadcrumb,
+  clearBreadcrumbs,
+  log,
+  notifyTransaction,
+  trackTransaction,
+  trackJob,
   flush,
   configuration: getConfiguration,
   client: getClient,
   VERSION,
 };
 
-export { init, notify, flush };
+export {
+  init,
+  notify,
+  addBreadcrumb,
+  clearBreadcrumbs,
+  log,
+  notifyTransaction,
+  trackTransaction,
+  trackJob,
+  flush,
+};

package/src/logs.ts

@@ -0,0 +1,44 @@
+export function normalizeLogLevel(level: string): string {
+  switch (level.trim().toLowerCase()) {
+    case "warning":
+    case "warn":
+      return "warn";
+    case "err":
+    case "severe":
+    case "critical":
+      return "error";
+    case "notice":
+      return "info";
+    case "fine":
+    case "finer":
+    case "finest":
+      return "debug";
+    case "trace":
+    case "debug":
+    case "info":
+    case "error":
+    case "fatal":
+      return level.trim().toLowerCase();
+    default:
+      return "info";
+  }
+}
+
+export function logLevelRank(level: string): number {
+  switch (level) {
+    case "trace":
+      return 0;
+    case "debug":
+      return 10;
+    case "info":
+      return 20;
+    case "warn":
+      return 30;
+    case "error":
+      return 40;
+    case "fatal":
+      return 50;
+    default:
+      return 20;
+  }
+}

package/src/notice.ts

@@ -1,13 +1,22 @@
 import type { Configuration } from "./configuration.js";
 import { parseBacktrace, type BacktraceFrame } from "./backtrace.js";
+import type { Breadcrumb } from "./breadcrumbs.js";
 import { filterParams } from "./filter.js";
 import { VERSION } from "./version.js";
 
+const MAX_CAUSE_DEPTH = 10;
+
 export interface NoticeContext {
   context?: Record<string, unknown>;
   environment?: Record<string, unknown>;
   session?: Record<string, unknown>;
   params?: Record<string, unknown>;
+  breadcrumbs?: Breadcrumb[];
+}
+
+export interface NoticeCause {
+  type: string;
+  message: string;
 }
 
 export interface NoticePayload {
@@ -29,6 +38,9 @@ export function buildNotice(
   configuration: Configuration,
   options: NoticeContext = {},
 ): NoticePayload {
+  const causes = collectCauses(error);
+  const breadcrumbs = options.breadcrumbs ?? [];
+
   return {
     project_id: configuration.projectId,
     received_at: new Date().toISOString(),
@@ -36,7 +48,7 @@ export function buildNotice(
       {
         type: errorType(error),
         message: String(error.message ?? ""),
-        backtrace: parseBacktrace(error),
+        backtrace: flattenBacktrace(error, configuration.rootDirectory),
       },
     ],
     context: {
@@ -46,6 +58,8 @@ export function buildNotice(
       release: configuration.release,
       runtime: "bun",
       runtime_version: tryBunVersion(),
+      ...(causes.length > 0 ? { causes } : {}),
+      ...(breadcrumbs.length > 0 ? { breadcrumbs } : {}),
       ...(options.context ?? {}),
     },
     environment: options.environment ?? {},
@@ -54,6 +68,39 @@ export function buildNotice(
   };
 }
 
+/**
+ * Walk `error.cause` (ES2022) and merge each cause's frames into a single
+ * backtrace, re-indexing so the dashboard renders the full chain in one view.
+ */
+function flattenBacktrace(error: Error, rootDirectory: string): BacktraceFrame[] {
+  const frames: BacktraceFrame[] = [];
+  let index = 0;
+  for (const link of errorChain(error)) {
+    for (const frame of parseBacktrace(link, rootDirectory)) {
+      frames.push({ ...frame, index: index++ });
+    }
+  }
+  return frames;
+}
+
+function collectCauses(error: Error): NoticeCause[] {
+  return errorChain(error)
+    .slice(1)
+    .map((link) => ({ type: errorType(link), message: String(link.message ?? "") }));
+}
+
+function errorChain(error: Error): Error[] {
+  const chain: Error[] = [];
+  let current: unknown = error;
+  const seen = new Set<unknown>();
+  while (current instanceof Error && !seen.has(current) && chain.length < MAX_CAUSE_DEPTH) {
+    seen.add(current);
+    chain.push(current);
+    current = (current as { cause?: unknown }).cause;
+  }
+  return chain;
+}
+
 function tryBunVersion(): string | undefined {
   try {
     // @ts-ignore — Bun global is defined when running under Bun.

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.1.0";
+export const VERSION = "0.2.0";