TypeScript SDK overview

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

• 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