Installation

The TypeScript SDK ships as @spanly/sdk on npm. It works under Node, Bun, and Deno (with npm: specifiers). No native dependencies.

Install

npm install @spanly/sdk
# or
pnpm add @spanly/sdk
# or
yarn add @spanly/sdk
# or
bun add @spanly/sdk

Supported runtimes

The SDK ships dual CJS + ESM builds plus type definitions.

Configure the API key

The SDK reads the API key from the apiKey option you pass to the constructor. Always source it from the environment – never hard-code it:

import { SpanlyClient } from '@spanly/sdk';

const spanly = new SpanlyClient({
  apiKey: process.env.SPANLY_API_KEY,
});

Get a key by signing in at spanly.com, opening your project, and going to Settings → API keys. The region (us / eu) is encoded in the key prefix, so no extra config is needed.

When to use the SDK vs the CLI

For most users the CLI is the easier path – it wraps your MCP server with zero code changes and works in any language.

Reach for the SDK when you need:

• Per-request hooks (onCollect, onError) – mutate or filter packets, drop traffic by predicate.
• Per-request multi-tenant tagging beyond what --context-header covers (e.g. extract tenant from auth tokens, JWT claims, request body).
• In-process embedding – no extra binary, no sidecar.
• Test integration – direct control over the monitor lifecycle from Jest / Vitest.

If none of those apply, prefer the CLI.