@corelayer/sdk

Lightweight TypeScript SDK for sending metrics to the Corelayer API. Handles batching, automatic retries with exponential backoff, and queue management out of the box.

Install

npm install @corelayer/sdk

Quick Start

import { CorelayerClient } from "@corelayer/sdk";

const client = new CorelayerClient({
  apiKey: "your-api-key",
});

// Track a metric — queued and flushed automatically
client.trackMetric({
  metricId: "api.request.duration",
  value: 142,
  partitions: { endpoint: "/users", method: "GET", status: 200 },
});

// Graceful shutdown (flushes remaining metrics)
await client.shutdown();

Configuration

const client = new CorelayerClient({
  apiKey: "your-api-key",       // Required
  baseUrl: "https://...",       // Default: https://api.corelayer.dev
  flushIntervalMs: 5000,        // Auto-flush interval (default: 5s)
  maxBatchSize: 100,            // Metrics per batch POST (default: 100)
  maxQueueSize: 1000,           // Queue capacity before dropping oldest (default: 1000)
  maxRetries: 4,                // Retry attempts per batch (default: 4)
  timeoutMs: 5000,              // Per-request timeout (default: 5s)
  debug: false,                 // Log internal errors to console (default: false)
});

API

trackMetric(data: MetricData)

Queue a metric for submission. Metrics are batched and sent automatically on the flush interval or when the batch size threshold is reached.

client.trackMetric({
  metricId: "db.query.count",   // Required — metric identifier
  value: 1,                     // Required — numeric value
  partitions: {                 // Optional — dimensions/tags
    table: "users",
    operation: "SELECT",
  },
  timestamp: "2025-01-15T...",  // Optional — ISO 8601, defaults to now
});

flush()

Manually flush all queued metrics. Safe to call concurrently — duplicate flushes are no-ops.

await client.flush();

shutdown()

Stop the auto-flush timer and send any remaining metrics. Call this before process exit.

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

Reliability

• Batching — Metrics are queued and sent in configurable batches to minimize network overhead.
• Automatic retries — Failed requests are retried with exponential backoff (500ms, 1s, 2s, 4s). Respects Retry-After headers. Retries on 429 and 5xx status codes.
• Queue overflow — When the queue is full, the oldest metrics are dropped to keep memory bounded. Enable debug: true to log drop warnings.
• Concurrent flush safety — Only one flush runs at a time; concurrent calls are safely ignored.

Development

npm run build         # Build to dist/ (ESM + CJS)
npm run dev           # Watch mode

License

MIT