@plungeai/one-api

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

npm install @plungeai/one-api

Usage

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

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

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

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
}

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:

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.