[ SDK ]

@canaryhub/sdk

The JavaScript/TypeScript SDK for Node 18+, serverless, and edge runtimes. Three verbs, one key, zero dependencies. It is built so it can never hurt the app it watches: calls never throw, never block a request, and silently drop events if the network is down.

$ npm install @canaryhub/sdk

init

import { canary } from "@canaryhub/sdk";canary.init("ch_live_YOUR_KEY");// or: set CANARY_API_KEY in the environment and callcanary.init();

Call it once at startup. Without a key (argument or CANARY_API_KEY), the SDK stays dormant and every call is a silent no-op — safe to ship in code paths that run before configuration exists.

event — things going right

canary.event("signup");canary.event("payment", { value: 29 });canary.event("export-finished", { meta: { rows: 12000 } });

error — things going wrong

try {  await stripe.webhooks.constructEvent(...);} catch (err) {  canary.error("stripe webhook failed", { message: String(err) });}

Errors are events with louder routing: they land in your digest by default (with AI summaries on paid plans) instead of paging you one-by-one. message is truncated at 2,000 characters. CanaryHub deliberately does not collect stack traces or source maps — pair it with a full exception tracker if you need those; CanaryHub is the layer that decides what's worth telling you about.

flush — before you exit

export async function handler(req) {  canary.event("report-generated");  // ... your logic  await canary.flush(); // push the last batch out before the runtime freezes}

Long-running servers never need this — batches send themselves. Call it at the end of serverless handlers, cron scripts, and CLIs so queued events aren't lost when the process exits. It always resolves, even offline.

How delivery works

• Batched: events send when 20 are queued or 5 seconds pass, whichever comes first — one HTTP request instead of dozens.
• Fire-and-forget: delivery happens in the background; your request path never waits on CanaryHub.
• Fail-safe: network down, bad key, our outage — the SDK drops events silently rather than throwing. A monitoring tool must never be the thing that takes you down.
• Bounded: at most 1,000 events queue in memory (oldest dropped first), and the SDK won't hold your process open to flush telemetry.

Not using Node? The SDK is a thin wrapper over one HTTP endpoint — see the HTTP API reference. Winston and pino transports are on the roadmap.