API reference

@fixback/node reference

The complete API of @fixback/node. For a narrative walkthrough, see the Backend errors guide.

Exports

ts

import {  init,  captureException,  captureMessage,  setUser,  mintHostIdentity,} from "@fixback/node";// framework adapters (optional, subpath imports):import { fixbackRequestContext, fixbackErrorHandler } from "@fixback/node/express";import { FixbackModule } from "@fixback/node/nestjs";

init(options)

Call once, as early in the process as possible.

Option	Type	Description
`secretKey`	`string`	Required. The Project's secret key (`sk_…`). Server-side only.
`environment`	`string`	The deploy environment — `"production"`, `"staging"`, … Stored on every captured error.
`release`	`string`	The build identifier, symbolicated against sourcemaps uploaded for the same release.
`enabled`	`boolean`	Gate capture on or off — e.g. `process.env.NODE_ENV === "production"` to stay quiet in local dev.
`beforeSend`	`(event) => event \| null`	Redact fields, or drop an event entirely by returning `null`.
`scrub`	`boolean`	Run the built-in PII scrubbers before `beforeSend`. Defaults to `true`.
`apiUrl`	`string`	The Fixback API origin. Override for a self-hosted deployment.
`autoCapture`	`boolean`	The umbrella for the two process handlers below. Defaults to `true`; `false` installs neither.
`captureUncaughtException`	`boolean`	Install the polite `uncaughtException` handler. Defaults to `autoCapture`.
`captureUnhandledRejection`	`boolean`	Install the polite `unhandledRejection` handler. Defaults to `autoCapture`.
`requestIdHeader`	`string`	The header a correlation id is read from. Defaults to `x-request-id`.

Set the two per-signal flags to override the umbrella individually — e.g. { autoCapture: false, captureUnhandledRejection: true } installs only the rejection handler.

Transport tuning

Sensible by default; reach for these only when your traffic shape asks for it.

Option	Default	Description
`maxBatchSize`	`100`	Flush once the buffer reaches this many errors. Capped at the server's limit of 500.
`flushIntervalMs`	`5000`	Flush a non-empty buffer at least this often.
`maxQueueSize`	`1024`	Cap the in-memory buffer so a flood can't grow it without bound.
`timeoutMs`	`30000`	Per-request transport timeout; `0` disables it.

The single init call also wires a batched secret-key transport (backs off on 429, honouring Retry-After) and process-level uncaughtException / unhandledRejection capture that never changes your process's exit behaviour.

Capture functions

Function	Description
`captureException(err)`	Report a handled error (`handled: true`).
`captureMessage(message, level?)`	Report a message string with a level (e.g. `"warning"`).
`setUser(ref)`	Attach an app-supplied, opaque user reference to errors captured during the current request.

mintHostIdentity(options)

A Host identity is the escape hatch for a product that already knows who its users are: your server mints a short-lived token from the Project's secret key and hands it to a capture SDK (web or Expo) as its hostIdentity. Fixback verifies it and tiers the Reporter — Internal when the token's email is an Org Member, otherwise Invited — with no Connect round trip. A verified Host identity whose email matches a Fixback Account resolves to that same person, so the host and the platform are one Reporter.

ts

import { mintHostIdentity } from "@fixback/node";// On your server, for a user you already authenticated:const hostIdentity = mintHostIdentity({  secretKey: process.env.FIXBACK_SECRET_KEY!, // sk_… — never ship it to a client  subject: user.id,                            // your stable id for the user (JWT sub)  email: user.email,                           // optional — Member ⇒ internal tier  expiresInSeconds: 3600,                       // optional — defaults to one hour});// Hand it to a capture SDK as its hostIdentity option://   web:  Fixback.init({ key: "pk_…", hostIdentity })//   expo: <FixbackProvider options={{ key, origin, hostIdentity }} />

Option	Type	Description
`secretKey`	`string`	Required. The Project's secret key (`sk_…`), issued in the dashboard. Signs the token; keep it server-side.
`subject`	`string`	Required. Your stable identifier for the user — the JWT `sub`, which keys the Reporter.
`email`	`string`	The user's email. Decides `internal` vs `invited`, and unifies the Reporter with a matching Account. Omit for a valid-but-external identity (`invited`).
`expiresInSeconds`	`number`	Token lifetime; defaults to one hour. An `exp` is always set — an identity assertion must expire.

The recipe is an HS256 JWT signed with sha256(secretKey) — the value Fixback stores for the key and verifies against (the secret plaintext is shown once at issuance and never kept). This helper is that recipe, so you never hand-roll JWT signing. Issue and revoke secret keys under a Project's Secret keys in the dashboard; a revoked key stops verifying at once.

Express adapter — `@fixback/node/express`

Middleware	Where	Description
`fixbackRequestContext()`	before your routes	Opens per-request context so captures carry request metadata.
`fixbackErrorHandler()`	after your routes	Captures errors that reach `next(err)`.

NestJS adapter — `@fixback/node/nestjs`

Export	Description
`FixbackModule.forRoot()`	Registers the request-context middleware and a global exception filter that captures thrown request errors and re-throws them, leaving your own error handling unchanged.