@orello/error

TypeScript SDK for reporting production errors to the Orello monitor service.

Works with any Node.js application (Express, Fastify, NestJS, Koa, workers, or plain scripts). Use @orello/error/browser in front-end apps.

Install

npm install @orello/error

Quick start

import { Orello } from "@orello/error";

const orello = new Orello({
  apiKey: process.env.ORELLO_API_KEY!,
  service: "payment-service",
  environment: "production",
  // origin optional — defaults to current hostname (browser) or deployment env (Node)
  origin: "app.example.com",
  // monitorApiBaseUrl defaults to https://api.monitor.orello.space/api/v1
});

await orello.validateApiKey();

try {
  await charge(user, amount);
} catch (error) {
  const { payload, ingestion } = await orello.error(error, {
    context: { userId: user.id, route: "/checkout" },
  });
  // AI root-cause analysis runs server-side on the monitor service during ingest
  console.log(ingestion?.incidentId);
}

Node.js-wide capture (framework agnostic)

import { Orello, installNodeErrorHandlers } from "@orello/error";

const orello = new Orello({
  apiKey: process.env.ORELLO_API_KEY!,
  service: "api",
  environment: process.env.NODE_ENV ?? "development",
});

const detach = installNodeErrorHandlers(orello, {
  context: { app: "api-server" },
});

// later, if needed
// detach();

Server-side analysis

Clients send the error payload and Orello API key only. The monitor service runs AI analysis on ingest when credentials are configured:

1. Per-org keys from Dashboard → Voice & AI
2. Orello fallback — GOOGLE_GENERATIVE_AI_API_KEY on monitor infrastructure

Routine client errors (401/403, unauthorized, invalid token, etc.) are ignored and not stored.

Optional endpoint: POST /api/v1/errors/analyze (same auth as ingest).

Browser apps:

import { Orello } from "@orello/error/browser";

wrap

await orello.wrap(async () => {
  await paymentService.charge(user, amount);
}, { context: { userId: user.id } });

Email notifications

Not part of the SDK. The monitor service sends alerts after ingest when configured:

| Variable | Purpose | | -------- | ------- | | ORELLO_ERROR_ALERT_TO | Comma-separated recipients | | ORELLO_ERROR_SMTP_* | Optional org SMTP (HOST, PORT, USER, PASS, FROM) | | ORELLO_ERROR_RESEND_API_KEY | Optional org Resend key | | ORELLO_RESEND_API_KEY | Orello fallback Resend |

Auto-attached local context (Node)

On every orello.error() call (Node.js), the SDK automatically loads .orello/context and sends it under context.orelloLocal:

• notes.md — long-term notes
• Recent snapshots from .orello/context/snapshots/ (newest first, capped)
• Optional project file tree when includeProjectStructureOnError: true

const orello = new Orello({
  apiKey: process.env.ORELLO_API_KEY!,
  service: "api",
  environment: "production",
  attachLocalContext: true, // default
});

await orello.initContext();
await orello.addContextNote("Payment provider uses Stripe webhooks v2");

await orello.error(err, {
  context: { route: "/checkout" },
  attachLocalContext: false, // per-report opt-out
});

Use saveContext(), addContextNote(), and investigation tools to populate .orello/context before errors occur.

Browser (@orello/error/browser) has no filesystem — pass context manually.

Environment variables

| Variable | Purpose | | -------- | ------- | | ORELLO_ERROR_API_KEY | Monitor API key (orl_...) | | ORELLO_ERROR_ORIGIN | Hostname for API key domain validation |