@atlas-parthenon/sdk-nodejs

Node.js SDK for sending Atlas telemetry through installation-authenticated, batched ingest.

Install

pnpm add @atlas-parthenon/sdk-nodejs

Usage

import { AtlasNodeClient } from "@atlas-parthenon/sdk-nodejs";

const atlas = new AtlasNodeClient({
  baseUrl: process.env.ATLAS_INGEST_BASE_URL ?? "http://localhost:3000",
  installationId: process.env.ATLAS_INSTALLATION_ID!,
  installationSecret: process.env.ATLAS_INSTALLATION_SECRET!,
  serviceName: "checkout-api",
  deploymentEnvironment: process.env.NODE_ENV
});

atlas.captureLog({
  severityText: "info",
  bodyText: "checkout request started",
  eventAttrs: {
    cartId: "cart_123"
  }
});

try {
  throw new Error("payment gateway timeout");
} catch (error) {
  atlas.captureException(error, {
    operationName: "POST /checkout",
    httpRoute: "/checkout",
    httpMethod: "POST",
    eventAttrs: {
      provider: "stripe"
    }
  });
}

await atlas.flush();
await atlas.shutdown();

Runtime Contract

• The SDK uses the global Node.js fetch implementation and requires Node 18+.
• Customer apps authenticate with installationId plus installationSecret.
• The SDK exchanges those credentials for a short-lived ingest lease at /api/ingest/session.
• Events are buffered in memory, grouped into ordered batches, gzip-compressed by default, and sent to the lease-provided ingest URL.
• Each batch carries sequence, prevBatchHash, and batchHash so retries are idempotent and the server can validate the receipt chain.
• captureException serializes Error objects into Atlas exception fields and sends them through the same batched transport.
• In Next.js, use this package in Node-based route handlers, server actions, cron jobs, and background work. Do not use it in the Edge runtime.

Environment Variables

• ATLAS_INGEST_BASE_URL: Atlas app origin, for example https://atlas.example.com
• ATLAS_INSTALLATION_ID: installation public id created in the Atlas dashboard
• ATLAS_INSTALLATION_SECRET: reveal-once machine secret for that installation

Atlas maintainers should read apps/web/lib/ingest/README.md and docs/sdk-ingest-v2.md in the repository before changing the transport contract.