usetraceforge 0.1.4 → 0.1.5

package/README.md

@@ -1,35 +1,36 @@
-# traceforge
+# usetraceforge
 
 TraceForge JavaScript SDK for sending errors to your TraceForge backend.
 
 ## Install
 
 ```bash
-npm install traceforge
+npm install usetraceforge
 ```
 
 ## Local pack test
 
 ```bash
 cd packages/sdk
+npm run build
 npm pack
 ```
 
 Then in any local app:
 
 ```bash
-npm install /path/to/traceforge-0.1.0.tgz
+npm install /path/to/usetraceforge-0.1.4.tgz
 ```
 
-## Usage
+## Frontend setup
 ```ts
-import TraceForge from "traceforge";
+import TraceForge from "usetraceforge";
 
 TraceForge.init({
   apiKey: "YOUR_PROJECT_API_KEY",
   endpoint: "http://localhost:3001/ingest",
   autoCapture: true,
-  environment: "development",
+  environment: "production",
   release: "web@1.0.0"
 });
 
@@ -42,6 +43,37 @@ try {
 }
 ```
 
+## Backend setup
+```ts
+import express from "express";
+import TraceForge from "usetraceforge";
+
+TraceForge.init({
+  apiKey: process.env.TRACEFORGE_API_KEY!,
+  endpoint: process.env.TRACEFORGE_INGEST_URL,
+  environment: process.env.TRACEFORGE_ENV || "production",
+  release: process.env.TRACEFORGE_RELEASE || "api@1.0.0"
+});
+
+const app = express();
+
+app.use((error: unknown, _req, res, _next) => {
+  TraceForge.captureException(error, {
+    payload: { route: "express-error-handler" }
+  }).catch(() => undefined);
+
+  res.status(500).json({ error: "Internal server error" });
+});
+```
+
+## Environment variables
+```env
+TRACEFORGE_INGEST_URL=http://localhost:3001/ingest
+TRACEFORGE_API_KEY=YOUR_PROJECT_API_KEY
+TRACEFORGE_ENV=production
+TRACEFORGE_RELEASE=web@1.0.0
+```
+
 ## Options
 - `autoCapture`: Listen to `window.onerror` and `window.onunhandledrejection`.
 - `ignoreErrors`: Array of strings or regex to skip noisy errors.
@@ -61,7 +93,5 @@ npm publish --access public
 After publish, consumers can install it with:
 
 ```bash
-npm install traceforge
+npm install usetraceforge
 ```
-
-If the unscoped npm name is unavailable, publish under a scoped package name and update the install line to match.

package/dist/express.d.ts

@@ -0,0 +1,6 @@
+import { Request, Response, NextFunction } from "express";
+/**
+ * Express middleware to catch unhandled errors and report them to TraceForge.
+ * Ensure this is added AFTER all your routes and controllers, but BEFORE your custom error handler.
+ */
+export declare const TraceForgeErrorHandler: (error: Error, req: Request, res: Response, next: NextFunction) => void;

package/dist/express.js

@@ -0,0 +1,27 @@
+import TraceForge from "./index.js";
+/**
+ * Express middleware to catch unhandled errors and report them to TraceForge.
+ * Ensure this is added AFTER all your routes and controllers, but BEFORE your custom error handler.
+ */
+export const TraceForgeErrorHandler = (error, req, res, next) => {
+    TraceForge.captureException(error, {
+        environment: "node",
+        tags: {
+            method: req.method,
+            url: req.url,
+            path: req.path,
+            ip: req.ip || "Unknown"
+        },
+        payload: {
+            query: req.query,
+            body: req.body,
+            headers: {
+                ...req.headers,
+                authorization: req.headers.authorization ? "[REDACTED]" : undefined,
+                cookie: req.headers.cookie ? "[REDACTED]" : undefined
+            }
+        }
+    }).catch(() => undefined);
+    // Pass the error to the next error handler
+    next(error);
+};

package/dist/index.js

@@ -1,6 +1,16 @@
 let config = null;
 let autoCaptureInitialized = false;
+let setupHandshakeSent = false;
 const defaultEndpoint = "http://localhost:3001/ingest";
+const getIngestEndpoint = () => config?.endpoint || defaultEndpoint;
+const getSetupEndpoint = () => {
+    const endpoint = getIngestEndpoint();
+    const normalized = endpoint.replace(/\/+$/, "");
+    if (normalized.endsWith("/setup")) {
+        return normalized;
+    }
+    return `${normalized}/setup`;
+};
 const ensureConfig = () => {
     if (!config) {
         throw new Error("TraceForge not initialized. Call TraceForge.init({ apiKey }) first.");
@@ -52,7 +62,7 @@ const sendEvent = async (event) => {
     if (!processed) {
         return;
     }
-    await fetch(config.endpoint || defaultEndpoint, {
+    await fetch(getIngestEndpoint(), {
         method: "POST",
         headers: {
             "Content-Type": "application/json",
@@ -66,6 +76,29 @@ const capture = async (error, extras) => {
     const event = buildEvent(error, extras);
     await sendEvent(event);
 };
+const sendSetupHandshake = async () => {
+    if (!config?.apiKey || setupHandshakeSent) {
+        return;
+    }
+    setupHandshakeSent = true;
+    try {
+        await fetch(getSetupEndpoint(), {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Traceforge-Key": config.apiKey
+            },
+            body: JSON.stringify({
+                environment: config.environment,
+                release: config.release,
+                tags: config.tags
+            })
+        });
+    }
+    catch {
+        setupHandshakeSent = false;
+    }
+};
 const setupAutoCapture = () => {
     if (autoCaptureInitialized)
         return;
@@ -88,11 +121,18 @@ const setupAutoCapture = () => {
 };
 const TraceForge = {
     init: (options) => {
+        const previousApiKey = config?.apiKey ?? null;
+        const previousEndpoint = config?.endpoint ?? defaultEndpoint;
         config = {
             endpoint: defaultEndpoint,
             autoCapture: false,
             ...options
         };
+        const currentEndpoint = config.endpoint || defaultEndpoint;
+        if (previousApiKey !== config.apiKey || previousEndpoint !== currentEndpoint) {
+            setupHandshakeSent = false;
+        }
+        void sendSetupHandshake();
         if (config.autoCapture) {
             setupAutoCapture();
         }

package/dist/next.d.ts

@@ -0,0 +1 @@
+export declare function withTraceForge(handler: Function): (...args: any[]) => Promise<any>;

package/dist/next.js

@@ -0,0 +1,20 @@
+import TraceForge from "./index.js";
+// A wrapper for Next.js API Routes (App Router or Pages Router)
+export function withTraceForge(handler) {
+    return async function (...args) {
+        try {
+            return await handler(...args);
+        }
+        catch (error) {
+            // Catch Next.js serverless API errors
+            await TraceForge.captureException(error, {
+                environment: "node",
+                tags: {
+                    runtime: "nextjs-api"
+                }
+            }).catch(() => undefined);
+            // Re-throw so Next.js can handle the 500 response natively
+            throw error;
+        }
+    };
+}

package/dist/react.d.ts

@@ -0,0 +1,18 @@
+import React, { Component, ErrorInfo, ReactNode } from "react";
+interface Props {
+    children?: ReactNode;
+    fallback?: ReactNode | ((error: Error) => ReactNode);
+    environment?: string;
+    release?: string;
+}
+interface State {
+    hasError: boolean;
+    error: Error | null;
+}
+export declare class TraceForgeErrorBoundary extends Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): React.ReactNode;
+}
+export {};

package/dist/react.js

@@ -0,0 +1,33 @@
+import { Component } from "react";
+import TraceForge from "./index.js";
+export class TraceForgeErrorBoundary extends Component {
+    state = {
+        hasError: false,
+        error: null
+    };
+    static getDerivedStateFromError(error) {
+        return { hasError: true, error };
+    }
+    componentDidCatch(error, errorInfo) {
+        TraceForge.captureException(error, {
+            environment: this.props.environment || "browser",
+            release: this.props.release,
+            tags: {
+                componentStack: errorInfo.componentStack || "Unknown"
+            }
+        }).catch(() => undefined);
+    }
+    render() {
+        if (this.state.hasError && this.state.error) {
+            if (typeof this.props.fallback === "function") {
+                return this.props.fallback(this.state.error);
+            }
+            if (this.props.fallback) {
+                return this.props.fallback;
+            }
+            // Default fallback if nothing is provided
+            return null;
+        }
+        return this.props.children;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usetraceforge",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "private": false,
   "description": "TraceForge JavaScript SDK for sending errors to a TraceForge ingest endpoint.",
   "type": "module",
@@ -9,7 +9,7 @@
   "types": "dist/index.d.ts",
   "repository": {
     "type": "git",
-    "url": "https://github.com/khushalp2004/TraceForge.git",
+    "url": "git+https://github.com/khushalp2004/TraceForge.git",
     "directory": "packages/sdk"
   },
   "homepage": "https://usetraceforge.com/docs",
@@ -28,6 +28,18 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "import": "./dist/express.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js"
     }
   },
   "files": [
@@ -47,6 +59,16 @@
   "dependencies": {},
   "devDependencies": {
     "typescript": "^5.5.4",
-    "tsx": "^4.16.2"
+    "tsx": "^4.16.2",
+    "@types/react": "^18.2.0",
+    "@types/express": "^4.17.21"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "express": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "express": { "optional": true }
   }
 }