PulseBase Node.js SDK

First SDK target for PulseBase v1. Requires Node.js 18+ (global fetch). Ships as both ESM and CommonJS with bundled type declarations.

import { createLogger } from "@repzo/pulsebase-sdk";

const logger = createLogger({
  ingestionKey: process.env.PULSEBASE_INGESTION_KEY!,
  // endpoint defaults to https://pulsebase-ingest.repzo.me;
  // override with PULSEBASE_ENDPOINT for local dev.
  service: "api",
  environment: "production",
  defaultTags: ["node"]
});

logger.info("Order created", {
  app_tenant_id: "tenant-1",
  app_user_id: "user-1",
  meta: {
    order_id: "ord_123"
  }
});

logger.error(new Error("Payment provider failed"));

await logger.close();

API

createLogger(options)
setupDefaultLogger(options)
getDefaultLogger()

Logger methods:

logger.trace(message, options)
logger.debug(message, options)
logger.info(message, options)
logger.warn(message, options)
logger.error(messageOrError, options)
logger.fatal(messageOrError, options)
logger.http(options)
logger.flush()
logger.close()
logger.addMetaProperty(key, value)
logger.removeMetaProperty(key)

The SDK is fail-open. Ingestion errors are emitted as optional events and dropped after retry exhaustion; application code should not fail because telemetry is unavailable.

Batching

The client buffers in memory and flushes by:

• interval: flushIntervalMs, default 3000
• event count: maxBatchSize, default 250
• payload target: maxBatchBytes, default PULSEBASE_LIMITS.sdkBatchTargetMaxBytes

Retries use exponential backoff with jitter for transient network errors and retryable HTTP statuses.

Compression

Set compress: true to gzip each batch before sending (off by default, async so it stays off the event loop). Batches below compressThreshold bytes (default 1024) are sent as plain JSON, since gzip only pays off on larger payloads. The edge ingestion endpoint decompresses content-encoding: gzip request bodies, so high-volume Node services can cut egress significantly:

const logger = createLogger({
  ingestionKey: process.env.PULSEBASE_INGESTION_KEY!,
  service: "api",
  compress: true
});

Events

logger.on("send", (event) => {})
logger.on("cleared", (event) => {})
logger.on("warn", (event) => {})
logger.on("error", (event) => {})
logger.on("drop", (event) => {})

error is only emitted when a listener is registered, so the logger remains fail-open by default.

When events are dropped (send failed after retries, or buffer overflow) and no drop listener is attached, the SDK logs a throttled console.warn (at most once per 60s) so the loss is never silent. Attach a drop listener to handle it yourself, or pass silent: true to suppress the warning.

Build & Publish

The package is consumed from source inside the monorepo. For external Node services it builds to a self-contained dist (the @pulsebase/schemas workspace package is bundled in):

corepack pnpm --filter @repzo/pulsebase-sdk build   # -> dist/index.js (ESM), index.cjs (CJS), index.d.ts

prepublishOnly runs the build automatically. publishConfig repoints main/module/types/exports at dist for the published tarball, so dev in the monorepo keeps using the TypeScript source.

Express Middleware

import express from "express";
import { createLogger, expressMiddleware } from "@repzo/pulsebase-sdk";

const app = express();
const logger = createLogger({
  ingestionKey: process.env.PULSEBASE_INGESTION_KEY!,
  endpoint: "http://127.0.0.1:8787",
  service: "api"
});

app.use(
  expressMiddleware(logger, {
    getTenantId: (request) => request.user?.tenantId,
    getUserId: (request) => request.user?.id
  })
);

Local Development

Run the edge ingest worker locally, then point the SDK at it:

corepack pnpm --filter @pulsebase/edge-ingest dev:sync-config
corepack pnpm exec wrangler dev \
  -c cloudflare/edge-ingest/wrangler.toml \
  -c cloudflare/queue-consumer/wrangler.toml

PULSEBASE_ENDPOINT=http://127.0.0.1:8787
PULSEBASE_INGESTION_KEY=pbik_...