trapshot-node-client
v1.0.1
Published
Type-safe Node.js client for Trapshot error reporting. Captures uncaught exceptions and unhandled rejections and provides a custom reporting API.
Maintainers
Readme
Trapshot Node Client
Type-safe Node.js client for Trapshot error reporting. Captures uncaught exceptions and unhandled promise rejections and provides a custom reporting API.
- Node 18+ required (uses global fetch)
- Fully written in TypeScript with generated type declarations
- Silent and resilient: never throws in production paths
- Best-effort code frame extraction from stack traces (reads source file where available)
Install
npm install trapshot-node-clientRequires Node >= 18.
Quick Start
Initialize once on app start. By default, global listeners for uncaughtException and unhandledRejection are installed.
import { initTrapshot } from "trapshot-node-client";
initTrapshot({
appId: "YOUR_APP_ID",
serverUrl: "https://your.trapshot.server/api/report",
apiKey: process.env.TRAPSHOT_API_KEY, // optional: bearer token
environment: process.env.NODE_ENV, // optional
release: process.env.GIT_SHA, // optional
});Manually report application errors or arbitrary messages:
import { report } from "trapshot-node-client";
await report(new Error("Something went wrong"), {
severity: "error",
tags: { feature: "checkout" },
metadata: { cartId: "abc123" },
});Using an explicit client instance
If you prefer not to use the singleton helpers:
import { TrapshotClient } from "trapshot-node-client";
const client = new TrapshotClient({
appId: "YOUR_APP_ID",
serverUrl: "https://your.trapshot.server/api/report",
apiKey: process.env.TRAPSHOT_API_KEY, // optional: bearer token
autoCapture: true, // installs global listeners; default is true
});
// Later, you can remove the listeners:
client.uninstall();
// Manual report:
await client.report("User clicked deprecated button", {
severity: "warning",
tags: { ui: "legacy" },
});Disable auto-capture (no global listeners) and manage manually:
const client = new TrapshotClient({
appId: "YOUR_APP_ID",
serverUrl: "https://your.trapshot.server/api/report",
apiKey: process.env.TRAPSHOT_API_KEY, // optional: bearer token
autoCapture: false,
});
client.install(); // add listeners when you want
client.uninstall(); // remove them when you wantOptions
type TrapshotClientOptions = {
appId: string; // required
serverUrl: string; // required (full URL to POST endpoint)
autoCapture?: boolean; // default: true
environment?: string; // e.g. "production" | "staging" | "development"
release?: string; // e.g. git SHA or semver
maxPayloadBytes?: number;// default: 200_000
fetchTimeoutMs?: number; // default: 3000
apiKey?: string; // used as Bearer token; Authorization header auto-added if not present
headers?: Record<string, string>; // additional HTTP headers
};What gets posted
POST JSON body to serverUrl:
{
"appId": "YOUR_APP_ID",
"timestamp": "2025-01-01T12:00:00.000Z",
"environment": "production",
"release": "a1b2c3",
"runtime": {
"platform": "win32",
"arch": "x64",
"node": "20.11.1",
"pid": 12345
},
"error": {
"name": "Error",
"message": "Something went wrong",
"stack": "Error: Something went wrong\n at ...",
"codeFrame": {
"filePath": "C:\\path\\to\\file.js",
"line": 42,
"column": 15,
"pre": [" const x = 1;"],
"lineContent": " throw new Error(\"Something went wrong\")",
"post": ["}"]
}
},
"context": {
"severity": "error",
"tags": { "feature": "checkout" },
"metadata": { "cartId": "abc123" }
}
}Notes:
codeFrameis best-effort: it is included when an absolute file path and line can be parsed from the stack and the source file can be read.- Payload is automatically truncated if it exceeds
maxPayloadBytes(codeFrame removed first, then stack shortened, then metadata dropped, then message trimmed) to ensure delivery.
Server considerations
- The client makes a simple
POSTwithContent-Type: application/json. - Failures are swallowed (silent by design). Use server logs/metrics to monitor ingestion.
- You can add custom headers (e.g., authorization) via the
headersoption. - If
apiKeyis provided, anAuthorization: Bearer <key>header is automatically added unless you already setAuthorizationinheaders.
TypeScript and bundlers
- Package provides
"types": "dist/index.d.ts". - CommonJS output with
"main": "dist/index.js". - Tree-shaking friendly; side effects limited to event listener installation when
autoCaptureis enabled.
Local development
Build:
npm run buildThe compiled files will be in dist/.
Publish to npm
- Ensure your
package.jsonhas the correctname,version, and metadata. - This package runs
prepublishOnlyto build before publishing. - Publish:
npm publish --access publicLicense
ISC
