TypeScript SDK Quickstart
Install the Solwyn TypeScript SDK, wrap an OpenAI client, report one call, and shut down cleanly.
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.
Create a project and get a key
This quickstart needs Node.js 22 or 24. The Solwyn CLI, which creates the project here, needs Python 3.11 or newer.
uv tool install --python 3.11 'solwyn-cli>=0.5.1'
solwyn login
solwyn projects create --name my-app --budget 50 --mode hard_deny --store-keysolwyn login prints a URL and a code. Open the URL, sign up or sign in, and approve. Creating
the project needs one more approval in the browser. --store-key keeps the key in the CLI's
credential store without printing it; the next step reads it from there. Inside a git repository
it also writes .solwyn.env, which names the project (SOLWYN_PROJECT="my-app"). Commit that
file: it holds no secret. See Scoped login.
Or create a project in Solwyn Cloud and copy its API key and name when they are shown. The key is displayed only once; the API-key guide covers creation, storage, rotation, and revocation.
Solwyn API keys begin with solwyn_sk_ followed by 64 lowercase hexadecimal characters. A key
belongs to your account and works for the projects listed on it, so every app also names its
project with SOLWYN_PROJECT: a project name or its proj_ id. The Solwyn key is separate from
your provider credential.
Install the SDK and provider client
@solwyn/sdk@0.4.0 is the current npm latest. Pin the exact
version so an upgrade is a deliberate change:
npm install @solwyn/sdk@0.4.0 openai
npm install --save-dev typescript tsx @types/nodeThe SDK does not bundle provider clients. openai is an optional peer that you install because
this example uses OpenAI. Anthropic, Google, Bedrock, Together, and compatible-client packages
are listed under TypeScript SDK providers.
Install 0.4.0 from npm. Do not substitute an unversioned local build for 0.4.0
in production.
Set server-side credentials
export OPENAI_API_KEY="<your OpenAI API key>"The Solwyn key stays in the CLI's credential store. The run step below hands it and the project to
the one command that needs them, as SOLWYN_API_KEY and SOLWYN_PROJECT. If you copied the key
from the dashboard, run
export SOLWYN_API_KEY="solwyn_sk_<64 lowercase hexadecimal characters>" and
export SOLWYN_PROJECT="my-app" instead.
Keep both values in your server environment or secret manager. Never embed them in browser JavaScript, commit them, or pass provider credentials to Solwyn.
Wrap the client and make a call
Save the following as quickstart.mts. Use a model available to your OpenAI account if you need
to change gpt-4o.
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,
project: process.env.SOLWYN_PROJECT,
});
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();
}Run it on Node.js 22 or 24, with the stored key and the project in that command's environment only:
(solwyn_env="$(solwyn --format table keys env)" && eval "$solwyn_env" && exec npx tsx quickstart.mts)The subshell keeps the key out of your shell, and nothing runs when no key is stored. --format table
asks keys env for the plain export lines that eval expects. If you exported
the key and project yourself, run npx tsx quickstart.mts.
The client checks the key and project with Solwyn once, before its first call. To fail at startup
instead, await client.validate() after constructing it.
Wrap the provider client where your application constructs it and use the wrapped client for subsequent calls. The provider request goes directly to OpenAI; Solwyn's control-plane requests carry budget and usage metadata, not the prompt or completion.
Confirm the integration
The terminal should show a short response and the provider's usage object. In your Solwyn project, look for the call's provider, model, token counts, status, and latency after the script closes.
Reporting is batched. await client.close() attempts to settle reservations and flush queued
events before exit. A successful provider response alone does not prove reporting succeeded,
because the default outage posture allows calls when the Solwyn API is temporarily unreachable.
| If you see… | Check… |
|---|---|
ConfigurationError with field === "api_key" | Supply the complete Solwyn API key (solwyn_sk_...), not the OpenAI key, a placeholder or an old sk_proj_ key. |
ConfigurationError with field === "project" | Set SOLWYN_PROJECT (or the project option) to a project the key reaches. SOLWYN_PROJECT_ID is not read. |
ApiKeyRefusedError | Solwyn refused the key or the project: error.code says why. See TypeScript SDK errors. |
| A provider authentication or model error | Check OPENAI_API_KEY and use a model enabled for that account. Provider errors pass through unchanged. |
| A response but no event in Solwyn | Confirm close() was awaited, inspect SDK warnings, and verify access to the configured apiUrl. |
| An unmetered-surface warning | Review provider coverage; wrapping a client does not make every method budget-trackable. |
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,
project: process.env.SOLWYN_PROJECT,
});
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.
Other providers
Use Anthropic, Google, Bedrock, Together, or an OpenAI-compatible endpoint.
Configuration
Review strict option validation, environment precedence, runtime support, and defaults.
Privacy
See exactly what the SDK inspects locally and what it transmits.
Streaming
Consume the stream to its terminal usage event and understand cancellation behavior.