@xyph3r/faultline 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# faultline
+
+Self-hosted error tracking SDK. Zero dependencies, works everywhere.
+
+```ts
+import { Faultline } from "faultline"
+
+Faultline.init({
+  dsn: process.env.FAULTLINE_DSN,
+  baseUrl: process.env.FAULTLINE_BASE_URL
+})
+
+// Manual capture
+Faultline.capture(err, { route: "/api/checkout", userId: "usr_123" })
+
+// Wrap a handler
+export const POST = Faultline.withCapture(async (req: Request) => {
+  // thrown errors are captured and rethrown
+})
+
+// Observer hooks
+Faultline.on("beforeCapture", (payload) => {
+  delete payload.metadata?.password // strip PII
+})
+```
+
+## Install
+
+```bash
+npm install faultline
+```
+
+## Requirements
+
+Node 18+, Bun, Deno, or any runtime with `fetch` and `crypto`.

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+import type { CaptureContext, FaultlineOptions, IngestPayload } from "./types";
+export declare class FaultlineClient {
+    readonly options: {
+        dsn: string | undefined;
+        baseUrl: string | undefined;
+        env: string;
+        enabled: boolean;
+        debug: boolean;
+        fetch: typeof fetch | undefined;
+        onBeforeCapture: ((payload: IngestPayload) => IngestPayload | void) | undefined;
+        onAfterCapture: ((payload: IngestPayload) => void) | undefined;
+        onCaptureError: ((error: Error, payload: IngestPayload) => void) | undefined;
+    };
+    constructor(options?: FaultlineOptions);
+    capture(error: unknown, context?: CaptureContext): Promise<void>;
+    private buildIngestUrl;
+    private send;
+    private warn;
+}

package/dist/client.js

@@ -0,0 +1,129 @@
+export class FaultlineClient {
+    options;
+    constructor(options = {}) {
+        this.options = {
+            dsn: options.dsn ?? process.env.FAULTLINE_DSN,
+            baseUrl: options.baseUrl ?? process.env.FAULTLINE_BASE_URL ?? "https://faultline.dev",
+            env: options.env ?? process.env.NODE_ENV ?? "production",
+            enabled: options.enabled ?? true,
+            debug: options.debug ?? false,
+            fetch: options.fetch,
+            onBeforeCapture: options.onBeforeCapture,
+            onAfterCapture: options.onAfterCapture,
+            onCaptureError: options.onCaptureError
+        };
+    }
+    capture(error, context = {}) {
+        if (!this.options.enabled) {
+            return Promise.resolve();
+        }
+        if (!this.options.dsn) {
+            this.warn("FAULTLINE_DSN is not set");
+            return Promise.resolve();
+        }
+        let payload = buildPayload(error, {
+            ...context,
+            env: this.options.env
+        });
+        if (this.options.onBeforeCapture) {
+            const modified = this.options.onBeforeCapture(payload);
+            if (modified)
+                payload = modified;
+        }
+        return this.send(payload);
+    }
+    buildIngestUrl() {
+        return `${this.options.baseUrl}/ingest/${this.options.dsn}`;
+    }
+    async send(payload) {
+        const fetchImpl = this.options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== "function") {
+            this.warn("Global fetch is not available in this runtime");
+            return;
+        }
+        try {
+            await fetchImpl(this.buildIngestUrl(), {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json"
+                },
+                body: JSON.stringify(payload)
+            });
+            this.options.onAfterCapture?.(payload);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.options.onCaptureError?.(err, payload);
+            this.warn(`Faultline capture failed: ${err.message}`);
+        }
+    }
+    warn(message) {
+        if (this.options.debug) {
+            console.warn(message);
+        }
+    }
+}
+function buildPayload(error, context) {
+    const normalized = normalizeError(error);
+    return {
+        title: normalized.title,
+        message: normalized.message,
+        stack: normalized.stack,
+        file: normalized.file,
+        line: normalized.line,
+        col: normalized.col,
+        route: context.route,
+        env: context.env,
+        level: context.level ?? "error",
+        userId: context.userId,
+        metadata: context.metadata
+    };
+}
+function normalizeError(error) {
+    if (error instanceof Error) {
+        const stackLocation = parseStackLocation(error.stack);
+        return {
+            title: error.name || "Error",
+            message: error.message,
+            stack: error.stack,
+            file: stackLocation?.file,
+            line: stackLocation?.line,
+            col: stackLocation?.col
+        };
+    }
+    if (typeof error === "string") {
+        return {
+            title: "Error",
+            message: error
+        };
+    }
+    return {
+        title: "UnknownError",
+        message: safeJson(error)
+    };
+}
+function parseStackLocation(stack) {
+    if (!stack) {
+        return undefined;
+    }
+    const lines = stack.split("\n");
+    for (const line of lines) {
+        const match = line.match(/\(?([^\s()]+):(\d+):(\d+)\)?$/);
+        if (match) {
+            return {
+                file: match[1],
+                line: Number(match[2]),
+                col: Number(match[3])
+            };
+        }
+    }
+    return undefined;
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import type { CaptureContext, FaultlineEvents, FaultlineOptions } from "./types";
+type EventHandler<E extends keyof FaultlineEvents> = (payload: FaultlineEvents[E]) => void;
+/**
+ * # Pattern: Singleton + Observer
+ * # Problem: Error capture must work from anywhere without passing an instance,
+ *   and consumers need hooks to filter/enrich/log events.
+ * # Solution: Faultline.init() creates a global singleton; Faultline.on() registers
+ *   typed observers; Faultline.capture() delegates to the singleton.
+ * # Trade-off: Global mutable state — justified because error tracking is
+ *   a cross-cutting concern like logging. Multiple instances still work via constructor.
+ */
+export declare class Faultline {
+    private static client;
+    private static listeners;
+    static init(options?: FaultlineOptions): typeof Faultline;
+    static capture(error: unknown, context?: CaptureContext): Promise<void>;
+    static withCapture<TArgs extends unknown[], TResult>(handler: (...args: TArgs) => TResult | Promise<TResult>, getContext?: (error: unknown, args: TArgs) => CaptureContext): (...args: TArgs) => Promise<TResult>;
+    static expressHandler(): (error: unknown, req: {
+        originalUrl?: string;
+        url?: string;
+        route?: {
+            path?: string;
+        };
+    }, _res: unknown, next: (error?: unknown) => void) => Promise<void>;
+    static on<E extends keyof FaultlineEvents>(event: E, handler: EventHandler<E>): () => void;
+    static off<E extends keyof FaultlineEvents>(event: E, handler: EventHandler<E>): void;
+    private static emit;
+    private client;
+    constructor(options?: FaultlineOptions);
+    capture(error: unknown, context?: CaptureContext): Promise<void>;
+    withCapture: typeof Faultline.withCapture;
+    expressHandler: typeof Faultline.expressHandler;
+}
+export type { CaptureContext, FaultlineOptions };
+export type { IngestPayload, FaultlineEvents } from "./types";
+export { FaultlineClient } from "./client";

package/dist/index.js

@@ -0,0 +1,103 @@
+import { FaultlineClient } from "./client";
+/**
+ * # Pattern: Singleton + Observer
+ * # Problem: Error capture must work from anywhere without passing an instance,
+ *   and consumers need hooks to filter/enrich/log events.
+ * # Solution: Faultline.init() creates a global singleton; Faultline.on() registers
+ *   typed observers; Faultline.capture() delegates to the singleton.
+ * # Trade-off: Global mutable state — justified because error tracking is
+ *   a cross-cutting concern like logging. Multiple instances still work via constructor.
+ */
+export class Faultline {
+    static client = null;
+    static listeners = new Map();
+    // ── Singleton ──
+    static init(options = {}) {
+        Faultline.client = new FaultlineClient({
+            ...options,
+            onBeforeCapture: (payload) => {
+                Faultline.emit("beforeCapture", payload);
+                return payload;
+            },
+            onAfterCapture: (payload) => {
+                Faultline.emit("afterCapture", payload);
+            },
+            onCaptureError: (error, payload) => {
+                Faultline.emit("captureError", { error: error.message, ...payload });
+            }
+        });
+        return Faultline;
+    }
+    static capture(error, context = {}) {
+        if (!Faultline.client) {
+            if (typeof process !== "undefined" && process.env.NODE_ENV === "development") {
+                console.warn("Faultline not initialized — call Faultline.init() first");
+            }
+            return Promise.resolve();
+        }
+        return Faultline.client.capture(error, context);
+    }
+    static withCapture(handler, getContext) {
+        return async (...args) => {
+            try {
+                return await handler(...args);
+            }
+            catch (error) {
+                const context = getContext ? getContext(error, args) : inferContext(args);
+                await Faultline.capture(error, context);
+                throw error;
+            }
+        };
+    }
+    static expressHandler() {
+        return async (error, req, _res, next) => {
+            await Faultline.capture(error, {
+                route: req.originalUrl ?? req.route?.path ?? req.url
+            });
+            next(error);
+        };
+    }
+    // ── Observer ──
+    static on(event, handler) {
+        if (!Faultline.listeners.has(event)) {
+            Faultline.listeners.set(event, new Set());
+        }
+        Faultline.listeners.get(event).add(handler);
+        return () => Faultline.off(event, handler);
+    }
+    static off(event, handler) {
+        Faultline.listeners.get(event)?.delete(handler);
+    }
+    static emit(event, payload) {
+        Faultline.listeners.get(event)?.forEach((fn) => {
+            try {
+                fn(payload);
+            }
+            catch { /* observer errors must never propagate */ }
+        });
+    }
+    // ── Instance (isolated, for testing or multi-project use) ──
+    client;
+    constructor(options = {}) {
+        this.client = new FaultlineClient(options);
+    }
+    capture(error, context = {}) {
+        return this.client.capture(error, context);
+    }
+    withCapture = Faultline.withCapture;
+    expressHandler = Faultline.expressHandler;
+}
+// ── Helpers ──
+function inferContext(args) {
+    const [first] = args;
+    if (first && typeof first === "object" && "url" in first && typeof first.url === "string") {
+        try {
+            return { route: new URL(first.url).pathname };
+        }
+        catch {
+            return { route: first.url };
+        }
+    }
+    return {};
+}
+export { FaultlineClient } from "./client";

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+export type CaptureContext = {
+    userId?: string;
+    route?: string;
+    metadata?: Record<string, unknown>;
+    level?: "error" | "warning" | "info";
+};
+export type IngestPayload = {
+    title: string;
+    message?: string;
+    stack?: string;
+    route?: string;
+    file?: string;
+    line?: number;
+    col?: number;
+    env?: string;
+    level?: "error" | "warning" | "info";
+    userId?: string;
+    metadata?: Record<string, unknown>;
+};
+export type FaultlineOptions = {
+    baseUrl?: string;
+    dsn?: string;
+    env?: string;
+    enabled?: boolean;
+    debug?: boolean;
+    fetch?: typeof fetch;
+    onBeforeCapture?: (payload: IngestPayload) => IngestPayload | void;
+    onAfterCapture?: (payload: IngestPayload) => void;
+    onCaptureError?: (error: Error, payload: IngestPayload) => void;
+};
+export type FaultlineEvents = {
+    beforeCapture: IngestPayload;
+    afterCapture: IngestPayload;
+    captureError: IngestPayload & {
+        error: string;
+    };
+};
+export type ExpressLikeRequest = {
+    originalUrl?: string;
+    url?: string;
+    route?: {
+        path?: string;
+    };
+};
+export type ExpressLikeNext = (error?: unknown) => void;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@xyph3r/faultline",
+  "version": "0.1.0",
+  "description": "Self-hosted error tracking SDK. Zero dependencies, works everywhere.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/faisalahmedsifat/faultline.git",
+    "directory": "packages/sdk"
+  },
+  "keywords": [
+    "error-tracking",
+    "error-monitoring",
+    "self-hosted",
+    "sentry-alternative",
+    "typescript"
+  ],
+  "author": "Faisal Ahmed Sifat",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}