# TypeScript SDK

@seachat/platform-sdk — a typed client over the public /v1 API with one Bearer credential.

## Install

`@seachat/platform-sdk` ships dual ESM + CJS with bundled TypeScript declarations, so both `import` and `require` work. It is built on the global WHATWG `fetch`; use Node.js 18+, Bun, Deno, or any edge runtime that provides `fetch` (or pass a `fetch` implementation via the constructor).

```bash
npm install @seachat/platform-sdk
# or: bun add @seachat/platform-sdk / pnpm add @seachat/platform-sdk
```

## Construct the client

Create one client and reuse it. `apiKey` is required and is sent as `Authorization: Bearer <apiKey>`. `baseUrl` falls back to `SEACHAT_BASE_URL` then `https://seachat.ai`. Optional `timeout` (ms), `fetch`, and `defaultHeaders` are also accepted. If `apiKey` is missing the constructor throws immediately.

```bash
import { SeaChat } from "@seachat/platform-sdk";

const client = new SeaChat({
  apiKey: process.env.SEACHAT_API_KEY!,   // required
  baseUrl: "https://seachat.ai",          // optional, defaults shown
  timeout: 30_000,                         // optional per-request timeout (ms)
});
```

## Resource map

The typed namespaces map directly onto `/v1` routes: `client.chat.completions` and `client.responses` (inference), `client.models` (discovery), `client.embeddings` / `client.images` / `client.audio` / `client.video` / `client.rerank` (multimodal over `/v1/invoke`), `client.threads` and `client.threads.messages` (conversation), `client.tools` (plugins), `client.files` (artifacts), `client.docs` (documents), `client.usage`, `client.capabilities`, `client.me`, `client.authKeys`, and `client.tasks` (async polling).

For anything the typed namespaces do not cover, use the raw escape hatch `client.invoke(path, body?)` → `POST /v1/invoke/{path}`.


## Error handling

Any non-2xx response throws a `SeaChatError` carrying `status`, `code`, `message`, `requestId`, and the raw `body`. Timeouts, network failures, and constructor misuse surface as plain `Error`s instead, so branch on `err instanceof SeaChatError` first.

```bash
import { SeaChat, SeaChatError } from "@seachat/platform-sdk";

try {
  await client.me.get();
} catch (err) {
  if (err instanceof SeaChatError) {
    console.error(err.status, err.code, err.message, err.requestId);
  } else {
    throw err; // network failure, timeout, or programmer error
  }
}
```