bloop-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Conway
+
+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,51 @@
+# @bloop/sdk
+
+Lightweight error reporting SDK for [Bloop](https://github.com/jaikoo/eewwror) — self-hosted error tracking.
+
+## Install
+
+```bash
+npm install @bloop/sdk
+```
+
+## Usage
+
+```typescript
+import { BloopClient } from "@bloop/sdk";
+
+const bloop = new BloopClient({
+  endpoint: "https://errors.myapp.com",
+  projectKey: "bloop_abc123...",
+  environment: "production",
+  release: "1.2.0",
+});
+
+// Capture an Error object
+try {
+  riskyOperation();
+} catch (err) {
+  bloop.captureError(err, { route: "POST /api/users", httpStatus: 500 });
+}
+
+// Capture a structured event
+bloop.capture({
+  errorType: "ValidationError",
+  message: "Invalid email format",
+  route: "POST /api/users",
+  httpStatus: 422,
+});
+
+// Flush on shutdown
+await bloop.shutdown();
+```
+
+## Features
+
+- **Zero dependencies** — Uses the Web Crypto API (works in Node.js and browsers)
+- **Automatic batching** — Events are buffered and sent in configurable batches
+- **HMAC-SHA256 signing** — All requests are cryptographically signed
+- **Graceful shutdown** — `shutdown()` flushes pending events before exit
+
+## License
+
+MIT

package/dist/bloop.d.ts

@@ -0,0 +1,44 @@
+export interface BloopConfig {
+    endpoint: string;
+    /** Project API key (used for both auth and project identification). */
+    projectKey: string;
+    /** @deprecated Use projectKey instead. Legacy HMAC secret for backward compat. */
+    secret?: string;
+    source?: "ios" | "android" | "api";
+    environment: string;
+    release: string;
+    maxBufferSize?: number;
+    flushIntervalMs?: number;
+}
+export interface ErrorEvent {
+    errorType: string;
+    message: string;
+    route?: string;
+    stack?: string;
+    httpStatus?: number;
+    requestId?: string;
+    userIdHash?: string;
+    metadata?: Record<string, unknown>;
+}
+export declare class BloopClient {
+    private config;
+    private buffer;
+    private timer;
+    private signingKey;
+    private keyReady;
+    constructor(config: BloopConfig);
+    /** Import the HMAC key using Web Crypto API. */
+    private importKey;
+    /** Capture an Error object. */
+    captureError(error: Error, context?: Partial<ErrorEvent>): void;
+    /** Capture a structured error event. */
+    capture(event: ErrorEvent): void;
+    /** Flush buffered events to the server. */
+    flush(): Promise<void>;
+    /** Express/Koa error middleware. */
+    errorMiddleware(): (err: Error, req: any, _res: any, next: any) => void;
+    /** Stop the flush timer. Call on process shutdown. */
+    close(): Promise<void>;
+    /** Sign a body string using Web Crypto HMAC-SHA256. */
+    private sign;
+}

package/dist/bloop.js

@@ -0,0 +1,145 @@
+export class BloopClient {
+    constructor(config) {
+        this.buffer = [];
+        this.timer = null;
+        this.signingKey = null;
+        this.config = {
+            source: "api",
+            maxBufferSize: 20,
+            flushIntervalMs: 5000,
+            ...config,
+        };
+        // Pre-import the signing key (async)
+        this.keyReady = this.importKey();
+        this.timer = setInterval(() => this.flush(), this.config.flushIntervalMs);
+    }
+    /** Import the HMAC key using Web Crypto API. */
+    async importKey() {
+        const secret = this.config.projectKey || this.config.secret || "";
+        const encoder = new TextEncoder();
+        this.signingKey = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    }
+    /** Capture an Error object. */
+    captureError(error, context) {
+        this.capture({
+            errorType: error.constructor.name,
+            message: error.message,
+            stack: error.stack,
+            ...context,
+        });
+    }
+    /** Capture a structured error event. */
+    capture(event) {
+        const ingestEvent = {
+            timestamp: Date.now(),
+            source: this.config.source,
+            environment: this.config.environment,
+            release: this.config.release,
+            error_type: event.errorType,
+            message: event.message,
+        };
+        if (event.route)
+            ingestEvent.route_or_procedure = event.route;
+        if (event.stack)
+            ingestEvent.stack = event.stack.slice(0, 8192);
+        if (event.httpStatus)
+            ingestEvent.http_status = event.httpStatus;
+        if (event.requestId)
+            ingestEvent.request_id = event.requestId;
+        if (event.userIdHash)
+            ingestEvent.user_id_hash = event.userIdHash;
+        if (event.metadata)
+            ingestEvent.metadata = event.metadata;
+        this.buffer.push(ingestEvent);
+        if (this.buffer.length >= (this.config.maxBufferSize ?? 20)) {
+            this.flush();
+        }
+    }
+    /** Flush buffered events to the server. */
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        // Ensure key is ready
+        await this.keyReady;
+        const events = this.buffer.splice(0);
+        const body = JSON.stringify({ events });
+        const signature = await this.sign(body);
+        const headers = {
+            "Content-Type": "application/json",
+            "X-Signature": signature,
+        };
+        // Send project key header if using new auth
+        if (this.config.projectKey) {
+            headers["X-Project-Key"] = this.config.projectKey;
+        }
+        try {
+            const resp = await fetch(`${this.config.endpoint}/v1/ingest/batch`, {
+                method: "POST",
+                headers,
+                body,
+            });
+            if (!resp.ok) {
+                console.warn(`[bloop] flush failed: ${resp.status}`);
+            }
+        }
+        catch (err) {
+            // Silently fail - error reporting shouldn't break the app
+            if (typeof globalThis !== "undefined" &&
+                globalThis.process?.env?.NODE_ENV !== "production") {
+                console.warn("[bloop] flush error:", err);
+            }
+        }
+    }
+    /** Express/Koa error middleware. */
+    errorMiddleware() {
+        return (err, req, _res, next) => {
+            this.captureError(err, {
+                route: req?.path || req?.url,
+                httpStatus: err instanceof HttpError ? err.statusCode : 500,
+                requestId: req?.headers?.["x-request-id"],
+            });
+            next(err);
+        };
+    }
+    /** Stop the flush timer. Call on process shutdown. */
+    async close() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.flush();
+    }
+    /** Sign a body string using Web Crypto HMAC-SHA256. */
+    async sign(body) {
+        if (!this.signingKey) {
+            await this.keyReady;
+        }
+        const encoder = new TextEncoder();
+        const signature = await crypto.subtle.sign("HMAC", this.signingKey, encoder.encode(body));
+        return Array.from(new Uint8Array(signature))
+            .map((b) => b.toString(16).padStart(2, "0"))
+            .join("");
+    }
+}
+class HttpError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+    }
+}
+// --- Usage ---
+// const client = new BloopClient({
+//   endpoint: "https://errors.yoursite.com",
+//   projectKey: "bloop_abc123...",
+//   environment: "production",
+//   release: "1.0.0",
+// });
+//
+// // Capture errors
+// client.captureError(new Error("something broke"), { route: "/api/users" });
+//
+// // Express middleware
+// app.use(client.errorMiddleware());
+//
+// // Graceful shutdown
+// process.on("SIGTERM", () => client.close());

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "bloop-sdk",
+  "version": "0.2.0",
+  "description": "Lightweight error reporting SDK for bloop",
+  "main": "dist/bloop.js",
+  "types": "dist/bloop.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["error-tracking", "observability", "bloop"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jaikoo/bloop-js"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}