Node SDK quickstart

@pushrail/sdk is the official TypeScript SDK for Node. It wraps the HTTP API, handles retries with backoff, classifies errors into typed exceptions, and offers an optional buffered mode for high-throughput emit paths. The same package works in any Node 18+ runtime, server, worker, lambda, container.

Install

pnpm add @pushrail/sdk

npm install @pushrail/sdk

The package is published to npm and bundles TypeScript declarations.

Initialize

Create one Pushrail instance per process and share it. The constructor takes your API key plus a few optional knobs.

import { Pushrail } from "@pushrail/sdk";

export const pushrail = new Pushrail({
  apiKey: process.env.PUSHRAIL_API_KEY!,
  // Optional:
  // baseUrl: "https://api.pushrail.io",   // default
  // timeout: 10_000,                       // ms, default 10s
  // maxRetries: 3,                         // default
  // buffered: false,                       // see batched-mode page
});

The client is safe to use across concurrent calls. There is no per-request state inside it. Load the API key from your secret store; never commit it.

Send your first event

const result = await pushrail.events.emit({
  eventType: "order.completed",
  source: "checkout-service",
  customerExternalId: "cust_42",
  payload: { orderId: "ord_9001", totalCents: 4999 },
});

console.log(result.id, result.status);
// e.g. "evt_01HXYZ...", "accepted"

emit returns a { id, status, idempotencyKey } object. The idempotencyKey is auto-generated as a UUIDv7 when you don't supply one. Store it if you need to correlate the emit with downstream logs.

The same client exposes events.emitBatch(inputs) for sending up to 100 events in one call. See Ingestion for the full surface.

Next steps

• Ingestion: single events, batches, error types, TypeScript types.
• Batched mode: when to enable client-side buffering and how to shut down cleanly.
• Retries: the default retry policy and how to customize it.