> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# @plungeai/one-api

> The official TypeScript SDK for the One API — typed resources, streaming, pagination, retries and errors, generated from the OpenAPI document.


The official TypeScript SDK for the PlungeAI One API (`https://api.plungeai.com`). Targets One API `2.5.0`; package version `1.0.0`. The resource methods and their types are generated from the API's own OpenAPI document (`GET /v1/openapi.json`). Zero runtime dependencies.

Release status: `npm view @plungeai/one-api version`; until it answers, build from `sdk/one-api-client/` (`npm ci && npm run build`).

## Installation

```sh
npm install @plungeai/one-api
```

## Usage

```ts
import PlungeAI from '@plungeai/one-api'

const client = new PlungeAI({
	apiKey: process.env['PLUNGEAI_API_KEY'], // the default; can be omitted
})

const me = await client.whoami()
const run = await client.agents.execute('calculator-agent', { prompt: '6*7' })
const hits = await client.discovery.search({ q: 'web search', kind: 'agents' })
```

## Streaming responses

```ts
const stream = await client.workflows.executeInlineStream({ workflow })
for await (const event of stream) {
	if (event.event === 'token') process.stdout.write((event.data as { delta: string }).delta)
}
```

`break` out of the loop or call `stream.controller.abort()` to stop; either aborts the underlying request. `stream.tee()` splits a stream in two, `stream.toReadableStream()` hands it on as a web `ReadableStream`. Methods that take `stream: true` (`client.agents.execute`, `client.chat.completions.create`) return the same `Stream`.

## Auto-pagination

```ts
for await (const w of client.workflows.list({ kind: 'bot' })) {
	console.log(w)
}

let page = await client.workflows.list({ limit: 50 })
for (const w of page.data) console.log(w)
while (page.hasNextPage()) {
	page = await page.getNextPage()
	for (const w of page.data) console.log(w)
}
```

## Handling errors

```ts
try {
	await client.agents.execute('calculator-agent', { prompt: '6*7' })
} catch (err) {
	if (err instanceof PlungeAI.FailedDependencyError) console.log(err.connect?.link)
	else if (err instanceof PlungeAI.APIError) console.log(err.status, err.code, err.requestID)
	else throw err
}
```

| Status | Error class |
|---|---|
| 400 | `BadRequestError` |
| 401 | `AuthenticationError` |
| 403 | `PermissionDeniedError` |
| 404 | `NotFoundError` |
| 409 | `ConflictError` |
| 422 | `UnprocessableEntityError` |
| 424 | `FailedDependencyError` — `connect: { provider, method, link }` says where to connect the missing account |
| 429 | `RateLimitError` |
| ≥ 500 | `InternalServerError` |
| no response | `APIConnectionError` (`APIConnectionTimeoutError` on timeout) |

Every class is exported by name and as a static on `PlungeAI`. `err.code` is the envelope's `error.code`; `err.requestID` is the `x-request-id` header.

## Retries

Failed requests are retried 2 times by default with short exponential backoff (honouring `Retry-After`): connection errors, timeouts, 408, 429 and ≥ 500. 409 and 424 are never retried — on the One API they are semantic answers (`approval_required`, `duplicate_execution_id`, a missing connection), and a retried execute would start a second run. Set `maxRetries` on the client or per request:

```ts
const client = new PlungeAI({ maxRetries: 0 })
await client.agents.execute('calculator-agent', { prompt: '6*7' }, { maxRetries: 5 })
```

`idempotencyKey` (per request) is sent as `x-trace-id`, the API's idempotency key: it becomes the run's execution id, is re-sent on every retry of the call, and a replay answers 409 `duplicate_execution_id`.

## Timeouts

Requests time out after 10 minutes by default and throw `APIConnectionTimeoutError` (retried as above). Set `timeout` in milliseconds on the client or per request: `new PlungeAI({ timeout: 20_000 })`, `client.whoami({ timeout: 5_000 })`.

## Models plane

`client.chat.completions.create` (plus `client.embeddings` and `client.models`) covers the OpenAI-compatible routes here; the OpenAI SDK also works with `baseURL: 'https://api.plungeai.com/v1'` and the same key.

## Requirements

Node.js 20+, Deno, Bun, Cloudflare Workers and Vercel Edge. Browsers are refused unless you pass `dangerouslyAllowBrowser: true`, because a browser client exposes your `ozk_` key to anyone who loads the page.