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
• 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.

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