@fictura/node — backend error capture

Reports your Node backend's errors to Fictura's Issues page: grouped by cause, ranked by users affected, with New / Ongoing / Escalating status and alerts on first-seen and regressions.

Zero dependencies. One file.

Install

npm install @fictura/node

Wire it (2 lines)

import { Fictura } from "@fictura/node";

const fictura = new Fictura({
  apiBase: process.env.FICTURA_API_BASE!,
  apiKey: process.env.FICTURA_API_KEY!,   // Dashboard → Setup → SDK app key
  release: process.env.GIT_SHA,
  environment: process.env.NODE_ENV,
});
fictura.install();

That's the whole integration. Three kinds of failure now reach the Issues page, and only the third asks anything of you.

1. Crashes and failed awaits. uncaughtException and unhandledRejection. Your process still dies on an uncaught error, with the same exit code — adding a listener normally suppresses that, so this puts it back.

2. Errors you already log. console.error(...) becomes an Issue:

try {
  await gemini.generate(prompt);
} catch (e) {
  console.error("Generation failed:", e);   // already an Issue. No new code.
  return fallback();
}

This matters more than it looks. Most real failures — a vendor API down, a database call that fails over — are caught and logged, never re-thrown, so the crash handlers alone would never see them. Pass captureConsole: false to opt out.

3. Anything you want to be explicit about:

catch (e) {
  fictura.captureException(e, { route: "/api/v1/generate", userId: user.id });
}

An error that is both logged and thrown is reported once, not twice.

Express

app.use(fictura.errorHandler());   // after your routes

Failed requests then carry their route template and user id, so /users/1 and /users/2 stay one issue. The error is passed on to your own handler untouched.

Guarantees

• Never throws into your app; never blocks a response (bounded queue, drops oldest on overflow, 2s HTTP timeout, no retry storms).
• The flush timer is unref'd — a finished script still exits.
• Grouping is server-side: error name + top app frames + route, so node_modules internals and line-number churn don't split issues.

Also available

• Python / FastAPI — pip install fictura
• React Native / Expo — @fictura/sdk, where error capture is already on if you call Growth.init()