TypeScript SDK Quickstart

This quickstart makes one provider request, reports its usage to a Solwyn project, and closes the reporter cleanly. It uses OpenAI, but the wrapper lifecycle is the same for every supported provider.

npm install @solwyn/sdk@0.2.0 openai
npm install --save-dev typescript tsx @types/node

export SOLWYN_API_KEY="sk_proj_<64 lowercase hexadecimal characters>"
export OPENAI_API_KEY="<your OpenAI API key>"

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);
  console.log("Provider token usage:", response.usage);
} finally {
  await client.close();
}

npx tsx quickstart.mts

Use await using instead

The wrapper implements Symbol.asyncDispose. With Node.js 22 or 24 and TypeScript explicit resource management enabled (a lib set that includes ESNext.Disposable), await using guarantees the same close path when the scope exits:

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");

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

  return await client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Return one short greeting." }],
  });
}

const response = await makeCall();
console.log(response.choices[0]?.message.content);

Repeated or concurrent calls to close() and async disposal share one promise. If the wrapped provider exposes its own close() method, Solwyn calls it after Solwyn-owned settlement, advisory, budget, and lease cleanup.

Provider-free and offline onboarding

Installing only @solwyn/sdk does not pull in any provider SDK. The core, Node, and testing entry points load without optional peers; the AI middleware module is also runtime-loadable without ai, but TypeScript use and declaration checking of @solwyn/sdk/ai-sdk require the ai peer. The LangChain and OpenAI Agents entries likewise load without their frameworks. A real LLM request still needs a provider client supplied by your application.

For CI or local development without provider credentials, start with offline testing. Its FakeControlPlane and a small duck-typed provider double let you exercise allow, deny, outage, settlement, and run-stop behavior with no network access. That is the supported provider-free path; it does not simulate a real provider account.

Add controls deliberately

Live budget mode is configured in Solwyn Cloud. The budgetMode constructor option does not turn on live hard-deny; it labels SDK-local outage decisions. failOpen defaults to true, but an applicable retained hard denial is still preserved during a later outage. Read TypeScript SDK budgets before changing the outage posture.