TypeScript SDK overview

@superpenguin/js wraps native provider SDKs and supports Vercel AI SDK helpers, OpenTelemetry span ingestion, and OpenAI Realtime sessions.

The SDK OTel helper is distinct from hosted OTLP ingestion, where OpenRouter or an exporter sends OTLP JSON directly.

• Package: @superpenguin/js on npm
• Current version: 0.14.0
• License: MIT
• Runtime: Node.js (server-side only)

Install

npm install @superpenguin/js

Install only the provider packages you use (optional peers):

npm install openai @anthropic-ai/sdk @google/genai
npm install @deepgram/sdk @elevenlabs/elevenlabs-js
npm install ai  # Vercel AI SDK

Quick start

import OpenAI from "openai";
import { init, wrap } from "@superpenguin/js";

init({ apiKey: process.env.SP_API_KEY });

const openai = wrap(new OpenAI(), {
  metadata: {
    environment: "production",
    feature: "support_agent",
  },
});

await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Write a concise reply." }],
  spMetadata: { customer_id: "cust_acme_123" },
});

wrap() auto-detects supported clients and strips spMetadata / sp_metadata before the request leaves your process.

Read current spend

Version 0.9.1 provides typed, low-latency spend reads. Use the same SDK key you use for ingestion; the authenticated organization is selected from that key.

import { init } from "@superpenguin/js";

const superpenguin = init({ apiKey: process.env.SP_API_KEY });

const current = await superpenguin.spend.get({ window: "1d" });

console.log(current.spendUsd);
console.log(current.asOf, current.stalenessMs);

1d means the current UTC calendar day, not the trailing 24 hours. Numbered windows include today plus the preceding N - 1 UTC days. month means the current UTC calendar month through today. Supported values are 1d through 7d, 14d, and month.

Filter by the feature or model recorded on usage events, or combine them:

const filtered = await superpenguin.spend.get({
  window: "7d",
  feature: "document-processing",
  model: "gpt-5",
});

The response contains:

There is no public freshThrough field; use asOf and stalenessMs to assess freshness. A spend result is advisory, not a reservation or concurrency-safe budget guarantee.

The SDK flushes locally buffered usage before the read by default. The ingest and materialization path is still asynchronous, so a flush does not guarantee a zero-staleness result. Set flush: false to skip that local flush. Identical concurrent reads in one process share a single flush and HTTP request.

Spend reads use https://spend.superpenguin.ai automatically. You do not need to set SP_SPEND_BASE_URL. Advanced staging or private-gateway setups can set that variable or pass spendBaseUrl; the override affects only spend reads, while ingestion continues to use SP_BASE_URL / baseUrl.

Invalid requests and service failures throw SuperPenguinSpendError, with code, retryable, and optional HTTP status properties. The SDK makes one bounded spend request and does not retry it automatically; retry only when retryable is true and doing so fits your application's policy. Codes are invalid_request, invalid_api_key, rate_limited, spend_unavailable, and request_failed.

Runtime behavior

• Events submit immediately by default so serverless functions do not exit early.
• Transient ingest failures retry with backoff and requeue.
• Attribution failures do not crash the user request path unless throwOnError: true.
• For long-lived workers, use flushMode: "interval" and call flush() before shutdown.

Next

• Supported providers
• Vercel AI SDK
• OpenTelemetry

Agent runs and dynamic metadata

Version 0.11.0 and later supports execution-local metadata and agent framework adapters. See agent SDKs and dynamic metadata for Vercel AI SDK, OpenAI Agents, LangGraph/LangChain, Pi, OpenCode and custom harness examples. These APIs are not in 0.9.1 or 0.10.0.