@errorgap/bun 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Errorgap
+
+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.

package/README.md

@@ -0,0 +1,77 @@
+# @errorgap/bun
+
+Bun notifier for [Errorgap](https://errorgap.com). Errors only in v1.
+
+Requires Bun 1.0+.
+
+## Install
+
+```sh
+bun add @errorgap/bun
+```
+
+The package ships as TypeScript source — no build step. Bun loads it
+directly.
+
+## Configure
+
+```ts
+import { Errorgap } from "@errorgap/bun";
+
+Errorgap.init({
+  endpoint:    process.env.ERRORGAP_ENDPOINT,
+  projectSlug: process.env.ERRORGAP_PROJECT_SLUG,
+  apiKey:      process.env.ERRORGAP_API_KEY,
+  environment: process.env.NODE_ENV ?? "production",
+});
+```
+
+`init` reads `ERRORGAP_*` env vars when fields are omitted. By default
+it installs `process.on("uncaughtException")` and
+`process.on("unhandledRejection")`; pass `captureGlobals: false` to skip.
+
+## Manual notification
+
+```ts
+try {
+  await risky();
+} catch (err) {
+  await Errorgap.notify(err, { context: { component: "checkout" } });
+  throw err;
+}
+```
+
+`notify` returns a `DeliveryResult` (`status`, `body`, `error`, `queued`).
+The SDK never throws.
+
+## Configuration reference
+
+| Option | Default | Notes |
+|---|---|---|
+| `endpoint` | `ERRORGAP_ENDPOINT` or `http://127.0.0.1:3030` | |
+| `projectSlug` | `ERRORGAP_PROJECT_SLUG` | **Required** |
+| `projectId` | `ERRORGAP_PROJECT_ID` | |
+| `apiKey` | `ERRORGAP_API_KEY` | Sent as `x-errorgap-project-key` |
+| `environment` | `NODE_ENV` or `"production"` | |
+| `release` | — | |
+| `async` | `true` | Fire-and-forget delivery |
+| `logger` | `console` | Pass `null` to silence |
+| `filterKeys` | `["password", "token", ...]` | Substring, case-insensitive |
+| `captureGlobals` | `true` | Install process error hooks |
+
+## Graceful flush
+
+```ts
+await Errorgap.flush();
+```
+
+## Development
+
+```sh
+bun install
+bun test
+```
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@errorgap/bun",
+  "version": "0.1.0",
+  "description": "Bun notifier for Errorgap error tracking.",
+  "license": "MIT",
+  "author": "Errorgap",
+  "homepage": "https://github.com/errorgaphq/errorgap-bun",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/errorgaphq/errorgap-bun.git"
+  },
+  "keywords": ["errorgap", "bun", "error-tracking", "exceptions", "monitoring"],
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["src", "README.md", "LICENSE"],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.0",
+    "typescript": "^5.3.3"
+  }
+}

package/src/backtrace.ts

@@ -0,0 +1,42 @@
+export interface BacktraceFrame {
+  file?: string;
+  line?: number;
+  function?: string;
+  in_app?: boolean;
+  index: number;
+}
+
+const V8_AT = /^\s*at\s+(?:(.*?)\s+\()?(.+?)(?::(\d+))?(?::(\d+))?\)?$/;
+
+export function parseBacktrace(error: Error): BacktraceFrame[] {
+  const stack = typeof error.stack === "string" ? error.stack : "";
+  if (!stack) return [];
+  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;
+    const m = trimmed.match(V8_AT);
+    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,
+      function: fnName || undefined,
+      in_app: isInApp(location),
+      index: index++,
+    });
+  }
+  return frames;
+}
+
+function isInApp(file: string): boolean {
+  if (!file) return false;
+  if (file.includes("/node_modules/")) return false;
+  if (file.startsWith("node:")) return false;
+  if (file.startsWith("bun:")) return false; // Bun internal modules
+  return true;
+}

package/src/client.ts

@@ -0,0 +1,116 @@
+import type { Configuration } from "./configuration.js";
+import { buildNotice, type NoticeContext, type NoticePayload } from "./notice.js";
+import { VERSION } from "./version.js";
+
+export interface DeliveryResult {
+  status?: number;
+  body?: string;
+  error?: unknown;
+  queued?: boolean;
+}
+
+export class Client {
+  private pending = new Set<Promise<unknown>>();
+
+  constructor(private configuration: Configuration) {}
+
+  configure(configuration: Configuration): void {
+    this.configuration = configuration;
+  }
+
+  async notify(
+    error: unknown,
+    options: NoticeContext & { sync?: boolean } = {},
+  ): Promise<DeliveryResult> {
+    try {
+      this.configuration.validate();
+      const err = coerceError(error);
+      const notice = buildNotice(err, this.configuration, options);
+
+      if (options.sync || !this.configuration.async) {
+        const p = this.deliver(notice);
+        this.track(p);
+        return await p;
+      }
+
+      this.track(this.deliver(notice));
+      return { queued: true, status: 202 };
+    } catch (exception) {
+      this.log(exception);
+      return { error: exception };
+    }
+  }
+
+  async deliver(notice: NoticePayload): Promise<DeliveryResult> {
+    const url = noticesUrl(this.configuration);
+    const headers: Record<string, string> = {
+      "content-type": "application/json",
+      "user-agent": `errorgap-bun/${VERSION}`,
+    };
+    if (this.configuration.apiKey) {
+      headers["x-errorgap-project-key"] = this.configuration.apiKey;
+    }
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(notice),
+      });
+      const body = await safeBody(response);
+      return { status: response.status, body };
+    } catch (exception) {
+      this.log(exception);
+      return { error: exception };
+    }
+  }
+
+  async flush(): Promise<void> {
+    while (this.pending.size > 0) {
+      await Promise.all(Array.from(this.pending));
+    }
+  }
+
+  private track(promise: Promise<unknown>): void {
+    const wrapped = promise.catch(() => undefined);
+    this.pending.add(wrapped);
+    void wrapped.finally(() => this.pending.delete(wrapped));
+  }
+
+  private log(exception: unknown): void {
+    const logger = this.configuration.logger;
+    if (!logger) return;
+    const message = exception instanceof Error
+      ? `${exception.name}: ${exception.message}`
+      : String(exception);
+    logger.warn(`[errorgap] ${message}`);
+  }
+}
+
+function noticesUrl(configuration: Configuration): string {
+  const base = configuration.endpoint.endsWith("/")
+    ? configuration.endpoint.slice(0, -1)
+    : configuration.endpoint;
+  return `${base}/api/projects/${configuration.projectSlug}/notices`;
+}
+
+async function safeBody(response: Response): Promise<string> {
+  try {
+    return await response.text();
+  } catch {
+    return "";
+  }
+}
+
+function coerceError(error: unknown): Error {
+  if (error instanceof Error) return error;
+  if (typeof error === "string") return new Error(error);
+  if (error && typeof error === "object") {
+    const obj = error as { message?: unknown; name?: unknown };
+    const err = new Error(
+      typeof obj.message === "string" ? obj.message : JSON.stringify(error),
+    );
+    if (typeof obj.name === "string") err.name = obj.name;
+    return err;
+  }
+  return new Error(String(error));
+}

package/src/configuration.ts

@@ -0,0 +1,58 @@
+export interface Logger {
+  warn(message: string, ...args: unknown[]): void;
+}
+
+export interface ConfigurationInput {
+  endpoint?: string;
+  projectSlug?: string;
+  projectId?: string;
+  apiKey?: string;
+  environment?: string;
+  release?: string;
+  async?: boolean;
+  logger?: Logger | null;
+  filterKeys?: string[];
+}
+
+const DEFAULT_FILTER_KEYS = [
+  "password",
+  "password_confirmation",
+  "token",
+  "secret",
+  "api_key",
+  "authorization",
+  "cookie",
+];
+
+export class Configuration {
+  endpoint: string;
+  projectSlug: string | undefined;
+  projectId: string | undefined;
+  apiKey: string | undefined;
+  environment: string;
+  release: string | undefined;
+  async: boolean;
+  logger: Logger | null;
+  filterKeys: string[];
+
+  constructor(input: ConfigurationInput = {}) {
+    this.endpoint = input.endpoint ?? process.env.ERRORGAP_ENDPOINT ?? "http://127.0.0.1:3030";
+    this.projectSlug = input.projectSlug ?? process.env.ERRORGAP_PROJECT_SLUG;
+    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.async = input.async ?? true;
+    this.logger = input.logger === undefined ? console : input.logger;
+    this.filterKeys = input.filterKeys ?? [...DEFAULT_FILTER_KEYS];
+  }
+
+  validate(): void {
+    if (!this.endpoint || this.endpoint.trim().length === 0) {
+      throw new Error("Errorgap endpoint is required");
+    }
+    if (!this.projectSlug || this.projectSlug.trim().length === 0) {
+      throw new Error("Errorgap projectSlug is required");
+    }
+  }
+}

package/src/filter.ts

@@ -0,0 +1,31 @@
+const FILTERED = "[FILTERED]";
+
+export function filterParams(
+  params: Record<string, unknown>,
+  filterKeys: string[],
+): Record<string, unknown> {
+  const lowered = filterKeys.map((k) => k.toLowerCase());
+  return walk(params, lowered);
+}
+
+function walk(
+  value: Record<string, unknown>,
+  loweredKeys: string[],
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(value)) {
+    if (isSensitive(key, loweredKeys)) {
+      out[key] = FILTERED;
+    } else if (val && typeof val === "object" && !Array.isArray(val)) {
+      out[key] = walk(val as Record<string, unknown>, loweredKeys);
+    } else {
+      out[key] = val;
+    }
+  }
+  return out;
+}
+
+function isSensitive(key: string, loweredKeys: string[]): boolean {
+  const k = key.toLowerCase();
+  return loweredKeys.some((needle) => k.includes(needle));
+}

package/src/handlers.ts

@@ -0,0 +1,37 @@
+import type { Client } from "./client.js";
+
+let installed = false;
+let uncaughtHandler: ((err: Error) => void) | null = null;
+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 {
+  if (installed) return;
+  installed = true;
+  uncaughtHandler = (err: Error) => {
+    void client.notify(err, {
+      sync: true,
+      context: { source: "uncaughtException" },
+    });
+  };
+  rejectionHandler = (reason: unknown) => {
+    void client.notify(reason, {
+      sync: true,
+      context: { source: "unhandledRejection" },
+    });
+  };
+  process.on("uncaughtException", uncaughtHandler);
+  process.on("unhandledRejection", rejectionHandler);
+}
+
+export function uninstallProcessHandlers(): void {
+  if (!installed) return;
+  if (uncaughtHandler) process.off("uncaughtException", uncaughtHandler);
+  if (rejectionHandler) process.off("unhandledRejection", rejectionHandler);
+  uncaughtHandler = null;
+  rejectionHandler = null;
+  installed = false;
+}

package/src/index.ts

@@ -0,0 +1,62 @@
+import { Client, type DeliveryResult } from "./client.js";
+import { Configuration, type ConfigurationInput } from "./configuration.js";
+import { installProcessHandlers, uninstallProcessHandlers } from "./handlers.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 { Client } from "./client.js";
+export { Configuration } from "./configuration.js";
+export { VERSION };
+
+let configuration = new Configuration();
+let client = new Client(configuration);
+
+export interface InitOptions extends ConfigurationInput {
+  /** Install process.uncaughtException / unhandledRejection handlers. */
+  captureGlobals?: boolean;
+}
+
+function init(options: InitOptions = {}): void {
+  const { captureGlobals = true, ...rest } = options;
+  configuration = new Configuration(rest);
+  client.configure(configuration);
+  if (captureGlobals) {
+    installProcessHandlers(client);
+  } else {
+    uninstallProcessHandlers();
+  }
+}
+
+function notify(
+  error: unknown,
+  options: NoticeContext & { sync?: boolean } = {},
+): Promise<DeliveryResult> {
+  return client.notify(error, options);
+}
+
+function flush(): Promise<void> {
+  return client.flush();
+}
+
+function getConfiguration(): Configuration {
+  return configuration;
+}
+
+function getClient(): Client {
+  return client;
+}
+
+export const Errorgap = {
+  init,
+  notify,
+  flush,
+  configuration: getConfiguration,
+  client: getClient,
+  VERSION,
+};
+
+export { init, notify, flush };

package/src/notice.ts

@@ -0,0 +1,71 @@
+import type { Configuration } from "./configuration.js";
+import { parseBacktrace, type BacktraceFrame } from "./backtrace.js";
+import { filterParams } from "./filter.js";
+import { VERSION } from "./version.js";
+
+export interface NoticeContext {
+  context?: Record<string, unknown>;
+  environment?: Record<string, unknown>;
+  session?: Record<string, unknown>;
+  params?: Record<string, unknown>;
+}
+
+export interface NoticePayload {
+  project_id?: string;
+  received_at: string;
+  errors: Array<{
+    type: string;
+    message: string;
+    backtrace: BacktraceFrame[];
+  }>;
+  context: Record<string, unknown>;
+  environment: Record<string, unknown>;
+  session: Record<string, unknown>;
+  params: Record<string, unknown>;
+}
+
+export function buildNotice(
+  error: Error,
+  configuration: Configuration,
+  options: NoticeContext = {},
+): NoticePayload {
+  return {
+    project_id: configuration.projectId,
+    received_at: new Date().toISOString(),
+    errors: [
+      {
+        type: errorType(error),
+        message: String(error.message ?? ""),
+        backtrace: parseBacktrace(error),
+      },
+    ],
+    context: {
+      notifier: "errorgap-bun",
+      notifier_version: VERSION,
+      environment: configuration.environment,
+      release: configuration.release,
+      runtime: "bun",
+      runtime_version: tryBunVersion(),
+      ...(options.context ?? {}),
+    },
+    environment: options.environment ?? {},
+    session: options.session ?? {},
+    params: filterParams(options.params ?? {}, configuration.filterKeys),
+  };
+}
+
+function tryBunVersion(): string | undefined {
+  try {
+    // @ts-ignore — Bun global is defined when running under Bun.
+    return typeof Bun !== "undefined" ? Bun.version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function errorType(error: Error): string {
+  if (typeof error.name === "string" && error.name.length > 0) {
+    return error.name;
+  }
+  return error.constructor?.name ?? "Error";
+}

package/src/version.ts

@@ -0,0 +1 @@
+export const VERSION = "0.1.0";