# TypeScript SDK

> Package: `@switchboard/sdk` — multi-cell failover client + AI SDK proxy helpers.

## Install / import

```bash
npm install @switchboard/sdk
# or from this monorepo while unpublished publicly:
# npm install ./sdk/typescript
```

```ts
import {
  SwitchboardClient,
  createProxyFetch,
  providerProxyBaseUrl,
  switchboardTiersBaseUrl,
  THINKING_TIERS,
} from "@switchboard/sdk";
```

Source: `sdk/typescript/` — see package [CHANGELOG.md](../sdk/typescript/CHANGELOG.md).

## Hub-native client

```ts
const sb = new SwitchboardClient({
  endpoints: [
    process.env.SWITCHBOARD_BASE_URL!,
    // optional failover cell
  ],
  apiKey: process.env.SB_KEY!,
});

await sb.call({
  op: "twilio.send_sms",
  body: { To: "+15550192", Body: "hi" },
  idempotencyKey: "sms-1",
  feature: "onboarding",
});
```

Retries **connection errors** and **503** across `endpoints`, reusing the same `Idempotency-Key`. Non-retryable 4xx fail immediately.

## AI SDK + thinking tiers

```ts
import { createOpenAI } from "@ai-sdk/openai";
import { createAnthropic } from "@ai-sdk/anthropic";

const cell = process.env.SWITCHBOARD_BASE_URL!;
const key = process.env.SB_KEY!;
const fetch = createProxyFetch(key, { headers: { "SB-Feature": "spine" } });

const tiers = createOpenAI({
  apiKey: key,
  baseURL: switchboardTiersBaseUrl(cell), // /v1/proxy/switchboard
  fetch,
});
// model: "anybody" | "thinker" | "expert"  — see THINKING_TIERS

const anthropic = createAnthropic({
  apiKey: key,
  baseURL: providerProxyBaseUrl(cell, "anthropic"),
  fetch,
});

const openai = createOpenAI({
  apiKey: key,
  baseURL: providerProxyBaseUrl(cell, "openai"),
  fetch,
});
```

`createProxyFetch`:

- Forces Switchboard Bearer; strips vendor auth headers / Google `?key=`
- Unwraps success `{ data, meta }` → provider `data`
- Keeps `{ error, data: null }` failures intact
- Passes SSE through unchanged

## Env contract

```bash
SWITCHBOARD_BASE_URL=https://us1.switchboard.example
SB_KEY=sb_live_…                 # or SWITCHBOARD_API_KEY
USE_SWITCHBOARD=true             # product flag if applicable
```

## Types

Envelope types can be regenerated from `platform/schemas/envelope.schema.json`:

```bash
cd sdk/typescript && npm run gen
```