Peeng JavaScript SDK — Node.js, Browser & Edge Logging

The official Peeng JavaScript and TypeScript SDK (npm install peeng) gives you a fully-typed client that wraps POST /v1/logs with non-blocking queuing, automatic batching, retries, and idempotency. Every peeng.info(...) call enqueues the log and returns immediately — the SDK handles delivery entirely in the background, so logging never blocks your app or throws exceptions into it.

MIT licensed. Requires Node ≥ 18 (uses the built-in global fetch and crypto.randomUUID); also works in browsers and edge runtimes.

Install

npm install peeng

yarn add peeng

pnpm add peeng

Quick start

Use ESM imports in TypeScript or modern Node.js:

import { PeengClient } from 'peeng';

const peeng = new PeengClient({
  apiKey: process.env.PEENG_API_KEY!,
  environment: 'production',
  service: 'checkout-api',
});

peeng.info('Order placed', { statusCode: 200, requestId: 'req_123', userId: 'user_456' });

peeng.error('Payment failed', {
  statusCode: 500,
  metadata: { orderId: 'order_789' },
  stackTrace: err.stack,
});

CommonJS works the same way — swap import for require:

const { PeengClient, LogLevel } = require('peeng');

const peeng = new PeengClient({ apiKey: process.env.PEENG_API_KEY });

peeng.warn('Slow query', { statusCode: 200, metadata: { durationMs: 1200 } });

Why use the SDK

Background batching

peeng.info(...) returns immediately — it enqueues, it never blocks on network I/O. The buffer flushes automatically every flushIntervalMs, or as soon as it hits maxBatchSize.

Automatic retries

Transient failures (network errors, 429s, 5xxs) are retried with backoff, reusing one Idempotency-Key per batch so retries can’t double-insert.

Never throws

Delivery failures go to onError instead of raising out of a logging call — a Peeng outage should never crash your app.

Fully typed

Ships CJS, ESM, and .d.ts declarations — full autocomplete on log options in every editor.

Constructor options

Pass an options object to new PeengClient(options) to configure the client.

Option	Type	Default	Description
`apiKey`	`string`	required	Your Peeng project API key.
`baseUrl`	`string`	`http://localhost:3000`	Peeng API base URL — set to `https://api.peeng.dev` for real traffic.
`environment`	`string`	—	Default `environment` for logs that don’t set their own.
`service`	`string`	—	Default `service` for logs that don’t set their own.
`maxBatchSize`	`number`	`100`	Flush once the buffer reaches this size. Hard-capped at `500`.
`flushIntervalMs`	`number`	`2000`	How often the background timer flushes the buffer (in milliseconds).
`maxRetries`	`number`	`3`	Retry attempts on top of the initial try for network errors, `429`s, and `5xx`s.
`onError`	`(error: unknown) => void`	—	Called with errors from failed background flushes.

Logging methods

The SDK exposes one convenience method per log level:

peeng.debug(message: string, opts: LogOptions): void
peeng.info(message: string, opts: LogOptions): void
peeng.warn(message: string, opts: LogOptions): void
peeng.error(message: string, opts: LogOptions): void
peeng.fatal(message: string, opts: LogOptions): void

opts.statusCode is required on every call (100–599). The following fields are optional: service, metadata, stackTrace, hostname, requestId, userId, timestamp, and a per-call environment override. See the field reference for what each one means. For anything the convenience methods don’t cover, use the generic form:

peeng.log({
  level: LogLevel.DEBUG,
  message: 'Cache miss',
  statusCode: 200,
  environment: 'staging',
});

Graceful shutdown

Call flush() to send whatever is currently in the buffer right now, and close() to stop the background timer and flush any remaining logs before your process exits.

await peeng.flush(); // send whatever's currently buffered right now
await peeng.close(); // stop the background timer and flush remaining logs

Hook into your process’s SIGTERM signal to give the client time to drain before shutdown:

process.on('SIGTERM', async () => {
  await peeng.close();
  process.exit(0);
});

The client also best-effort auto-flushes on Node’s beforeExit event as a safety net — close() is the deterministic way to guarantee delivery.

Custom batching config

Override the default batching and retry settings at construction time:

const peeng = new PeengClient({
  apiKey: process.env.PEENG_API_KEY!,
  environment: 'production',
  maxBatchSize: 250,
  flushIntervalMs: 5000,
  maxRetries: 5,
  onError: (err) => {
    console.error('peeng flush failed', err);
  },
});

Error handling

Background delivery failures are routed to onError, but you can also await peeng.flush() directly and catch errors in a try/catch block. The SDK surfaces two error types:

PeengApiError — the server responded with an error envelope. Carries statusCode, message, error (from the server envelope), and a context object with batchSize, idempotencyKey, and url. This is thrown for non-retryable errors (e.g. 400) or after retries are exhausted (e.g. repeated 5xx).
Plain Error — a network failure with no HTTP response at all (DNS failure, connection refused), surfaced after retries are exhausted.

import { PeengApiError } from 'peeng';

try {
  await peeng.flush();
} catch (err) {
  if (err instanceof PeengApiError) {
    console.error(`Peeng API error ${err.statusCode}: ${err.message}`);
  } else {
    console.error('Peeng flush failed', err);
  }
}

See Errors for the full retryable/non-retryable rules.

Get Started

Essentials

SDKs

Peeng JavaScript SDK — Node.js, Browser & Edge Logging

Install

Quick start

Why use the SDK

Background batching

Automatic retries

Never throws

Fully typed

Constructor options

Logging methods

Graceful shutdown

Custom batching config

Error handling

​Install

​Quick start

​Why use the SDK

Background batching

Automatic retries

Never throws

Fully typed

​Constructor options

​Logging methods

​Graceful shutdown

​Custom batching config

​Error handling

Install

Quick start

Why use the SDK

Constructor options

Logging methods

Graceful shutdown

Custom batching config

Error handling