Node SDK

Instrument Node apps with @shipgauge/node

The official Node SDK wraps OpenAI / Anthropic clients and records metadata only.

Package: @shipgauge/node (MIT).

Install

npm i @shipgauge/node
# peer: openai and/or @anthropic-ai/sdk as needed

Initialize

import { ShipGauge } from "@shipgauge/node";

const sg = ShipGauge.init({
  apiKey: process.env.SHIPGAUGE_API_KEY!,
  projectId: process.env.SHIPGAUGE_PROJECT_ID!,
  baseUrl: process.env.SHIPGAUGE_BASE_URL ?? "https://shipgauge.dev",
  // Defaults to "production" if omitted — set from your host env:
  environment: process.env.VERCEL_ENV ?? process.env.SHIPGAUGE_ENVIRONMENT ?? "development",
});

Wrap OpenAI

import OpenAI from "openai";

const openai = sg.wrapOpenAI(new OpenAI(), {
  defaultTags: { feature_id: "chat" },
});

const res = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello" }],
});

Use wrapAnthropic() the same way for Anthropic.

Manual record

await sg.record({
  feature_id: "summarize",
  model: "gpt-4o-mini",
  input_tokens: 500,
  output_tokens: 120,
  customer_id: "cus_123", // optional — Margin view
});

Budgets in-process

Configure a handler for hard budget responses so your app can fail fast:

sg.configureBudget({
  onBlocked: (info) => {
    console.warn("budget blocked", info);
  },
});

OpenTelemetry

Optional best-effort OTLP export — see OpenTelemetry.

Environment variables

Variable	Description
`SHIPGAUGE_API_KEY`	Ingest key (`sg_ingest_...`)
`SHIPGAUGE_PROJECT_ID`	Project UUID
`SHIPGAUGE_BASE_URL`	API origin (default hosted app URL)
`SHIPGAUGE_ENVIRONMENT`	Optional env label when not using `VERCEL_ENV` / config

Verify

Call a wrapped completion, then refresh Overview. New rows should appear under your feature_id.