The TypeScript SDK is a Node.js library that instruments your provider clients in-process. It does not proxy requests — the call still goes directly from your app to OpenAI / Anthropic / Vercel AI. ScopeCall only observes the inputs and outputs in the same Node.js process.

Install

npm install @scopecall/scopecall-js
# or
pnpm add @scopecall/scopecall-js
# or
yarn add @scopecall/scopecall-js

Requires Node.js 18 or later.

Initialise

import { init } from "@scopecall/scopecall-js";

const sdk = init({
  apiKey: process.env.SCOPECALL_API_KEY!,
  endpoint: "http://localhost:8080/v1/ingest",  // ingest URL
});

Call init() exactly once at app startup. It returns the SDK instance you use to instrument clients and create traces.

`init` options

Option	Type	Required	Notes
`apiKey`	`string`	✅	`sc_live_...` from Settings → API Keys
`endpoint`	`string`	✅	Full ingest URL — `http://localhost:8080/v1/ingest` for self-hosted, or your Cloud URL
`defaultPromptVersion`	`string`	optional	Prompt version label applied to events without a per-call override
`environment`	`string`	optional	Defaults to `process.env.NODE_ENV ?? "production"`
`flushIntervalMs`	`number`	optional	Defaults to `5000`. Events auto-flush every 5 seconds.
`captureContent`	`boolean`	optional	Defaults to `true`. Set `false` to omit prompt / response bodies.

Instrument a provider

OpenAI

import OpenAI from "openai";

const openai = new OpenAI();
sdk.instrument(openai);  // wraps chat.completions.create in place

// Every call through this client is now traced.
const response = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello" }],
});

Streaming is supported — stream_options.include_usage=true is auto-added so the final chunk carries token counts.

Anthropic

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic();
sdk.instrument(anthropic, "anthropic");

const response = await anthropic.messages.create({
  model: "claude-3-5-sonnet-latest",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }],
});

Vercel AI SDK

import { wrapAISDKModel } from "@scopecall/scopecall-js";
import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";

const model = wrapAISDKModel(sdk, openai("gpt-4o-mini"));

const { text } = await generateText({
  model,
  prompt: "Hello, ScopeCall.",
});

Works for generateText, streamText, generateObject, and streamObject.

Workflow spans

Wrap a sequence of LLM calls in sdk.trace() to surface them as a single workflow in the dashboard's trace tree and Flow Map.

await sdk.trace("daily-summary", { userId: "u_42" }, async () => {
  const draft = await openai.chat.completions.create({ /* ... */ });
  const polished = await openai.chat.completions.create({ /* ... */ });
  return polished;
});

Inside the block, every LLM call automatically becomes a child of the workflow span. Trace identity (user, session, feature, prompt version) propagates to every child.

Trace options

Option	Type	Notes
`userId`	`string`	Per-customer attribution in cost breakdowns
`sessionId`	`string`	Groups multiple workflows into a conversation
`featureName`	`string`	High-level feature label (e.g. `"daily-summary"`)
`promptVersion`	`string`	Per-trace prompt version override

Manual `recordLLMCall`

For frameworks ScopeCall doesn't auto-instrument (LangChain, LlamaIndex, custom wrappers), record events manually:

sdk.recordLLMCall({
  model: "gpt-4o-mini",
  provider: "openai",
  inputTokens: 240,
  outputTokens: 180,
  latencyMs: 820,
  inputText: "...",
  outputText: "...",
});

Inherits the current trace context (user / session / feature / prompt version) automatically.

Graceful shutdown

process.on("SIGTERM", async () => {
  await sdk.flush({ timeoutMs: 5000 });
  process.exit(0);
});

sdk.flush() ships any in-buffer events before exit. Without it, the last few seconds of traces can be lost on quick container restarts.

PII redaction

const sdk = init({
  apiKey: "...",
  endpoint: "...",
  redactPatterns: [
    { name: "EMAIL", pattern: /[\w.+-]+@[\w-]+\.[\w.-]+/g, replacement: "[EMAIL]" },
  ],
});

Redaction runs on both input_text and output_text before events leave the process. The defaults include patterns for emails, credit card numbers, SSNs, IP addresses, and phone numbers.

Source

The SDK source is open at github.com/scopecall/scopecall/tree/main/sdks/typescript.