TypeScript SDK Overview

The Solwyn TypeScript SDK wraps the provider client you already use. Your application keeps the provider's request syntax and TypeScript request types while Solwyn adds budget checks, usage reporting, provider failover, and run attribution.

Provider requests still go directly from your process to the provider. Solwyn Cloud receives content-free usage and operational metadata, plus tags you explicitly provide. Prompt and response content is not sent to Solwyn or logged by the SDK. When local token estimation or cross-dialect failover requires inspecting content, that inspection stays inside your process. See TypeScript SDK privacy for the exact boundary.

Start here

One wrapped call

Install the published 0.2.0 with the provider SDK your application already uses:

npm install @solwyn/sdk@0.2.0 openai

Set SOLWYN_API_KEY to a Solwyn project key and keep OPENAI_API_KEY in your normal provider configuration. Then wrap the provider client once and reuse the wrapper:

import { Solwyn } from "@solwyn/sdk";
import OpenAI from "openai";

const solwynApiKey = process.env.SOLWYN_API_KEY;
if (!solwynApiKey) throw new Error("SOLWYN_API_KEY is required");

const client = new Solwyn(new OpenAI(), { apiKey: solwynApiKey });

try {
  const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Say hello in one sentence." }],
    max_completion_tokens: 64,
  });

  console.log(response.choices[0]?.message.content);
} finally {
  await client.close();
}

Solwyn is an ES Proxy over the wrapped client. Tracked provider methods run through the budget and reporting lifecycle. Known and newly observed spend-capable surfaces follow onUnmetered; structural and non-spend values pass through with their native values and types. The wrapper preserves instanceof, .constructor, stable method identity, and provider request types. Tracked OpenAI-style calls deliberately return an ordinary Promise, so provider-only promise helpers such as .withResponse() and .asResponse() are not available on those calls.

What the SDK adds

Solwyn Cloud owns provider and model pricing. The SDK reports token counts and bounded media quantities; it does not contain a provider price table or calculate the actual price of a call.

Provider packages are optional

@solwyn/sdk has no runtime import of OpenAI, Anthropic, Google, AWS, Together, the Vercel AI SDK, LangChain, or OpenAI Agents. Provider adapters are duck-typed and loaded only when needed. Installing only @solwyn/sdk therefore supports provider-free runtime loading of every entry point:

TypeScript use and declaration checking of @solwyn/sdk/ai-sdk require the ai peer, and those of @solwyn/sdk/openai-agents require @openai/agents. This is useful for shared libraries and offline tests.

A real model call still needs a supported provider client supplied by your application. Solwyn does not create a provider client or take custody of provider credentials. See TypeScript SDK providers for the package to pair with each dialect, or offline testing for a provider-free test path.

Lifecycle

Always wait for shutdown. await client.close() first waits for in-flight calls and settles open streams from the usage observed so far, then flushes settlement reporting, untracked-surface advisories, and budget and lease state, and finally calls the wrapped provider's own close() method when it has one. reporterShutdownDeadline bounds the wait for in-flight calls, stream settlement, reporting, and advisories. Lease cleanup has a separate one-second budget, and the provider's own close() is awaited afterward with its own duration. Concurrent or repeated close calls share the same promise. Once close() begins, new intercepted calls reject with SolwynError("client is closed"); create a new wrapper for later work.

On Node.js 22 or 24 with a compiler that supports explicit resource management, await using calls the same async disposal path:

import { Solwyn } from "@solwyn/sdk";
import OpenAI from "openai";

const solwynApiKey = process.env.SOLWYN_API_KEY;
if (!solwynApiKey) throw new Error("SOLWYN_API_KEY is required");

await using client = new Solwyn(new OpenAI(), { apiKey: solwynApiKey });

await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello from an async-disposed client." }],
});

Do not rely on process exit to drain queued reports. Long-running services should create one wrapper per provider client and close it from their normal shutdown hook.

Compatibility at a glance

• Full release lanes: exact Node.js 22.23.2 and 24.21.0 runtime qualification, ESM and CommonJS.
• Declarations: exact TypeScript 5.8.3 and 6.0.3, with consumer checks using strict: true and skipLibCheck: false.
• Legacy Node.js 20: installed-artifact, provider-free core compatibility only while engines.node remains >=20; it is not a source-build, AI SDK, framework-integration, or full provider lane. OpenAI 7, AI SDK 7, and the LangChain and OpenAI Agents integrations require Node.js 22 or later.
• Browser and edge: the edge-safe core is bundle-, VM-, and real-browser-qualified without Node globals, but those checks do not certify a deployment on every named edge platform.

Use Node.js 22 or 24 for new deployments. The full provider boundary matrix and edge caveats are documented under providers and configuration.

Next steps