Install

The package is not yet published to the npm registry. Install from the monorepo or a tarball.

# From the CodeRadar monorepo (workspace install)
pnpm add @coderadar/sdk

# Or from a local tarball
pnpm add ./path/to/coderadar-sdk-0.1.0.tgz

Init

Call init() as early as possible — ideally the very first line of your entry point — so global error handlers are registered before any other module runs.

import { init } from "@coderadar/sdk";

init({
  dsn:         process.env.CODERADAR_DSN,
  project:     "your-project-slug",
  environment: process.env.NODE_ENV ?? "production",
  serviceName: "api",
});

Init options

Option	Default	Notes
`dsn`	—	Required. DSN URL or raw project key.
`project`	—	Project slug. Required if not embedded in the DSN.
`environment`	"production"	dev / staging / production / preview-*
`serviceName`	""	Attached to every event. Useful in multi-service orgs.
`disableGlobalHandlers`	false	Set to true to skip uncaughtException / unhandledRejection hooks.
`maxBreadcrumbs`	50	Per-event breadcrumb buffer size.
`flushIntervalMs`	5000	Periodic background flush interval in ms.
`ingestUrl`	"https://ingest.coderadar.app/v1/events"	Override the ingest endpoint (useful for proxies or local dev).

captureException

import { captureException } from "@coderadar/sdk";

try {
  await riskyOperation();
} catch (err) {
  captureException(err, {
    tags:  { stage: "checkout", region: "us-central1" },
    user:  { id: user.id, email: user.email },
    extra: { orderId: order.id },
  });
  throw err; // re-throw if the caller needs to handle it
}

captureMessage

import { captureMessage } from "@coderadar/sdk";

// levels: "debug" | "info" | "warning" | "error" | "fatal"
captureMessage("background job started", "info");
captureMessage("rate limit approaching 80%", "warning");

Breadcrumbs

Breadcrumbs are a trail of events leading up to the captured error. The SDK auto-instruments console and outbound fetch calls. Add manual breadcrumbs for business-logic checkpoints.

import { addBreadcrumb } from "@coderadar/sdk";

addBreadcrumb({
  category: "checkout",
  message:  "cart validated — 3 items",
  data:     { cartId: cart.id, total: cart.total },
});

User context

import { setUser } from "@coderadar/sdk";

// Call after authentication resolves. Context attaches to all subsequent events.
setUser({ id: user.id, email: user.email, segment: user.plan });

Flush on shutdown

The SDK queues events and flushes them in batches. On process shutdown, call flush() to drain the queue before the process exits.

import { flush } from "@coderadar/sdk";

process.on("SIGTERM", async () => {
  await flush();
  process.exit(0);
});

Source-map upload

Upload maps after each build so minified stack traces resolve to original source lines. See the source maps guide.

# curl upload — one file at a time
curl -X POST https://ingest.coderadar.app/v1/sourcemaps \
  -H "Authorization: Bearer $CODERADAR_PROJECT_KEY" \
  -F "release=your-app@$GIT_SHA" \
  -F "name=main.js.map" \
  -F "file=@dist/main.js.map"

Common gotchas

Init must run before any async imports — If you use dynamic import() at the top of your entry point, place init() before those calls. Node resolves synchronous imports before any user code runs, so a static import of @coderadar/sdk at the top of the file and a first-line init() call is the safest pattern.
ESM / CJS mismatch — The package ships both ESM (.mjs) and CJS (.cjs) builds. Node 20+ in "type": "module" projects will use the ESM build automatically. Older toolchains may need require("@coderadar/sdk").
Package not published — @coderadar/sdk is not yet on the npm registry. Use a workspace install or a local tarball until a release is cut.
Flush timeout on Lambda / Cloud Run with min-instances=0 — The periodic flush timer is unref'd so it does not prevent process exit. On serverless runtimes that freeze the process mid-flight, call await flush() explicitly at the end of each request handler or cold-start bootstrap.