@onklave/errors

Onklave error-tracking SDK — a thin, vendor-neutral client that posts errors to the Onklave errors service ingest endpoint (POST /api/v1/events/errors), authenticated with a per-project ingest key.

Implements §5.2.1–5.2.3 and §7.3 of _docs/specs/ONKLAVE_CAPTURE_AND_ERROR_TRACKING_SPEC.md.

• Zero runtime dependencies (uses the platform fetch).
• Capture is fire-and-forget with a tiny retry and never throws into the host app.
• The server resolves org + project from the ingest key; the SDK never sends a trusted projectId in the body.

Install

npm install @onklave/errors

Core usage

import { OnklaveErrors } from '@onklave/errors';

OnklaveErrors.init({
  key: 'oerr_live_…',                      // project ingest key (resolves org+project server-side)
  serviceName: 'streaming-gateway',        // which app/service/lib in the monorepo
  release: '1.4.2',
  environment: 'production',
  component: '@onklave/streaming-gateway',  // optional finer-grained entry point
  commitSha: process.env.COMMIT_SHA,
  tags: { region: 'eu', tier: 'enterprise' },
  // endpoint defaults to https://api.onklave.app/errors
});

OnklaveErrors.captureException(err, {
  request: { method: 'GET', path: '/vaults/123', statusCode: 500 },
  context: { route: '/vaults/:id' },
});

OnklaveErrors.captureMessage('cache miss storm', 'warning');

await OnklaveErrors.flush(); // await pending sends (e.g. before process exit)

Browser global handlers (@onklave/errors/browser)

import { OnklaveErrors } from '@onklave/errors';
import { installGlobalHandlers } from '@onklave/errors/browser';

OnklaveErrors.init({ key: '…', serviceName: 'portal', release: '1.0.0', environment: 'production' });
const uninstall = installGlobalHandlers(); // wires window.onerror + unhandledrejection

End-user feedback

Submit feedback from your app's users straight into your project's feedback triage in the Onklave portal (org + project are resolved server-side from the same ingest key — nothing in the body routes it). Unlike error capture this resolves a result, so you can confirm receipt to the user; it still never throws.

const ok = await OnklaveErrors.submitFeedback({
  title: 'Search is slow',
  description: 'Searching invoices takes ~10 seconds.',
  category: 'other', // ui_ux | nav_naming | nav_reorder | content | dark_light | other
  priority: 'medium', // critical | high | medium | low
  reporter: { email: '[email protected]' }, // optional, shown to the triager
});

In-app feedback widget (@onklave/errors/widget)

A dependency-free floating button + form your users submit feedback through — straight into the project's feedback triage in the Onklave portal. It probes the server first and renders ONLY when the project has end-user feedback enabled (portal → project → Feedback), so it can ship in every app and stay invisible until switched on.

import { installFeedbackWidget } from '@onklave/errors/widget';

// After OnklaveErrors.init(); resolves to an uninstall function.
const uninstall = await installFeedbackWidget();

NestJS exception filter (@onklave/errors/nestjs)

@nestjs/common is a peer dependency (not bundled). The filter reports the exception then rethrows, so Nest's default handling still produces the response.

import { OnklaveExceptionFilter } from '@onklave/errors/nestjs';

app.useGlobalFilters(new OnklaveExceptionFilter());

Build / test / lint

npx nx build @onklave/errors
npx nx test @onklave/errors
npx nx lint @onklave/errors