Getting Started

SDK Reference

Reduck provides an official TypeScript SDK. Create a client, start a run, iterate over events.

Installation

npm install @reduck-ai/sdk

ReduckClient

import { ReduckClient } from "@reduck-ai/sdk"

Constructor

// API key (recommended for server-side)
const client = new ReduckClient({ apiKey: "rk_..." })

// OAuth token (for user-facing apps)
const client = new ReduckClient({ oauthToken: "..." })

One of apiKey or oauthToken is required.

client.listDevices()

Returns Promise<Device[]> — all devices for the authenticated user.

interface Device {
  id: string
  name: string | null
  browser: string | null
  os: string | null
  reachable: boolean
  created_at: string
}

client.run()

Starts an automation and returns a Run — an AsyncIterable<RunEvent> that streams events in real-time via WebSocket.

const run = client.run(prompt: string, options: { deviceId: string, mount?: string[] })

Option	Type	Description
deviceId	string	Target device ID (required)
mount	string[]	Local file paths to upload and make available

run.id

Promise<string> — resolves to the run ID once the server accepts it.

run.cancel()

Cancels the running automation.

client.listRuns()

Returns Promise<RunsPage> — a paginated list of runs for the authenticated user.

interface RunsPage {
  data: RunRecord[]
  hasNextPage: boolean
}

Option	Type	Default	Description
page	number	0	Zero-based page index

client.getRun()

Returns Promise<RunRecord> — a single run by ID.

interface RunRecord {
  id: string
  started_at: string
  finished_at: string | null
  result: {
    success?: boolean
    cancelled?: boolean
    reason?: string
    output?: string
  } | null
  resolved: {
    url?: string
    prompt?: string
  } | null
}

client.interrupt()

Cancels a run by ID (useful if you only have the ID, not the Run object):

await client.interrupt(runId: string)

Events

The run async iterable yields these events:

Type	Fields	Terminal?	Description
run_started	timestamp	No	Automation has started
progress	text, timestamp	No	Step-by-step progress update
assistant	text, timestamp	No	Assistant message
turn_completed	timestamp	No	Agent turn completed
run_completed	timestamp	No	Automation finished executing
done	success, output?	Yes	Final result
failure	error	Yes	Automation failed
cancel	—	Yes	Automation was cancelled

Full example

import { ReduckClient } from "@reduck-ai/sdk"

const client = new ReduckClient({ apiKey: process.env.REDUCK_API_KEY! })

const devices = await client.listDevices()

const run = client.run("Find the cheapest flight to Tokyo next week", {
  deviceId: devices[0].id,
})

const runId = await run.id
console.log(`Started run: ${runId}`)

for await (const event of run) {
  if (event.type === "progress") console.log("→", event.text)
  if (event.type === "done") console.log(event.success ? "✓ Done" : "✗ Failed")
  if (event.type === "failure") console.error("✗", event.error)
}