@prompteryx/sdk 0.4.0 → 0.4.1

package/README.md

@@ -1,336 +1,336 @@
-# @prompteryx/sdk
-
-Official TypeScript SDK for [Prompteryx](https://prompteryx.com).
-
-```bash
-npm install @prompteryx/sdk
-```
-
-Optional peers for the most-used features:
-
-```bash
-npm install zod playwright-core
-```
-
-Works on Node 18+ (global `fetch`), ESM **and** CommonJS.
-
-## Authentication — two key families
-
-| Key | Format | Used by | Sent as | Rate limits |
-|---|---|---|---|---|
-| Platform API key | `px_live_…` | everything except `cloudBrowser` | `Authorization: Bearer` | 60 req/min, 10,000 req/day |
-| Cloud Browser key | `pcb_live_…` | `px.cloudBrowser.*` (sessions / fetch / search) | `x-api-key` | per-plan session quotas |
-
-Create the `px_live_` key in Settings → API Keys, and the `pcb_live_` key in
-Cloud Platform → API Keys. `px.cloudBrowser.*` throws a descriptive
-`AuthError` if you call it without `cloudBrowserKey`.
-
-```ts
-const px = new Prompteryx({
-  apiKey: process.env.PROMPTERYX_API_KEY!,                    // px_live_…
-  cloudBrowserKey: process.env.PROMPTERYX_CLOUD_BROWSER_KEY,  // pcb_live_… (only for cloudBrowser)
-})
-```
-
-## Two AI surfaces — Copilot and Autopilot
-
-Prompteryx has two distinct ways AI helps you automate the browser:
-
-- **Copilot** — you drive Playwright; copilot helps with ONE step.
-  You're in control, AI is the assistant.
-- **Autopilot** — you give a goal in plain English; autopilot drives
-  the whole task end-to-end.
-
-```ts
-import { Prompteryx } from '@prompteryx/sdk'
-import { chromium } from 'playwright-core'
-import { z } from 'zod'
-
-const px = new Prompteryx({
-  apiKey: process.env.PROMPTERYX_API_KEY!,
-  cloudBrowserKey: process.env.PROMPTERYX_CLOUD_BROWSER_KEY,
-})
-
-// — Copilot: assisted single steps —
-const session = await px.cloudBrowser.sessions.create({
-  useProxy: true, proxyLocation: 'us',
-})
-const browser = await chromium.connectOverCDP(session.connectUrl)
-const page = browser.contexts()[0].pages()[0]
-await page.goto('https://example.com/signup')
-
-await px.copilot.do(page, 'click the Sign up button')
-await px.copilot.do(page, 'fill the email field with hello@example.com')
-
-const plan = await px.copilot.read(page, z.object({
-  name: z.string(),
-  pricePerMonth: z.number(),
-  features: z.array(z.string()),
-}))
-
-const actions = await px.copilot.scan(page, 'checkout flow')
-
-// — Autopilot: hand it a goal, it runs end-to-end —
-const result = await px.autopilot.run({
-  goal: 'Find the cheapest direct flight from London to Lisbon next Tuesday and screenshot the booking page',
-  maxSteps: 30,                     // default is 30
-  saveAsWorkflow: true,             // ← key superpower, see below
-})
-// result.usage → { aiCredits, tokensIn, tokensOut, costUSD, turns }
-```
-
-## Action caching = saved workflows
-
-This is Prompteryx's killer feature for cost-conscious users. Set
-`saveAsWorkflow: true` on any `autopilot.run` call and the discovered
-action sequence is captured as a permanent Visual Studio workflow:
-
-```ts
-const result = await px.autopilot.run({
-  goal: 'Apply for the Senior Engineer role at OpenAI',
-  saveAsWorkflow: true,
-  savedWorkflowName: 'apply-openai-senior',
-})
-
-// Replay forever at ZERO AI cost:
-await px.workflows.run(result.savedWorkflowId!)
-```
-
-The saved workflow is a first-class platform object — schedulable,
-editable in Visual Studio, shareable, API-triggerable. It uses
-multi-option ranked selectors so it stays resilient to UI changes.
-
-## Structured output + final-step vision
-
-```ts
-const result = await px.autopilot.run({
-  goal: 'Get the top 3 HN stories',
-  outputSchema: {                       // finalAnswer becomes JSON matching this
-    type: 'object',
-    properties: {
-      stories: {
-        type: 'array',
-        items: { type: 'object', properties: { title: { type: 'string' }, url: { type: 'string' } } },
-      },
-    },
-  },
-  finalStepVision: 'precision',         // one extra high-quality look before answering
-})
-const data = JSON.parse(result.finalAnswer!)
-```
-
-## The SDK surface (verified against the live API)
-
-| Resource | What it does |
-|---|---|
-| `px.workflows.{list,get,run,runAndWait}` | Visual Studio workflows. |
-| `px.executions.{get,wait,logs,stream,getNodeOutput}` | Execution status + logs. |
-| `px.cloudBrowser.sessions.{create,get,list,close}` | Cloud browser sessions for your own Playwright code (`pcb_live_` key). |
-| `px.cloudBrowser.{fetch,search}` | One-shot page fetch + web search via the cloud browser, no session management (`pcb_live_` key). |
-| `px.copilot.{do,read,scan}` | Assisted single-step primitives on a Playwright page. |
-| `px.autopilot.{run,stream,stop}` | Autonomous multi-step agent with `saveAsWorkflow` action caching. |
-| `px.schedules.{list,get,create,update,delete}` | Server-side cron schedules — the platform fires them even when no client is connected. |
-| `px.profiles.{list,get,create,delete}` | Cloud and local Chrome profiles. |
-| `px.subscription.get` | Plan, balances, top-ups. |
-
-> Removed in 0.4.0 after a live-API audit: `connectHub`, `customNodes`,
-> `templates`, `apiKeys`, `recordings`, `subscription.usage`, and
-> `sessions.getDownloads/getRecording` — their routes don't exist on the
-> live API today (or, for `apiKeys`, can never accept API-key auth). A
-> smaller honest SDK beats a 404ing surface; they return when their
-> endpoints ship.
-
-## Models
-
-`autopilot.run({ model })` defaults to **`gemini-3.5-flash`** (recommended —
-fast and cheap). The full catalog of 32 ids is exported as
-`AUTOPILOT_MODELS` (type `AutopilotModel`), mirrored from the platform's
-canonical list — highlights:
-
-- `gemini-3.5-flash` (default), `gemini-3.7-flash` (newest GA Flash),
-  `gemini-3.6-flash`, `gemini-default` (legacy 2.5)
-- `claude-sonnet-4-6`, `claude-opus-4-8` (native computer use)
-- `gpt-5.6-terra`, `gpt-5.6-sol`, `gpt-5.5`
-- Vision-loop variants (`claude-fable-5-vision`, `gpt-5.6-luna-vision`, …)
-  and experimental harness engines (`model-h`, `modelc`, …)
-
-Unknown ids are forwarded for forward-compatibility but hard-400 with
-`UNSUPPORTED_MODEL` under strict validation — stick to the catalog.
-
-## One-shot fetch and search
-
-No Playwright, no session management — a real cloud Chromium loads the page
-(so JS-rendered sites work) and returns token-efficient content:
-
-```ts
-const pageData = await px.cloudBrowser.fetch({
-  url: 'https://example.com/pricing',
-  format: 'markdown',                  // 'text' (default) | 'markdown' | 'html' | 'links'
-  waitForSelector: '.pricing-table',   // wait for JS-rendered content
-  selectors: ['.pricing-table .plan'], // deterministic CSS extraction (count + text + html)
-  screenshot: true,                    // base64 JPEG in .screenshotBase64
-})
-
-// Web search — DuckDuckGo in a real browser, structured results:
-const results = await px.cloudBrowser.search({ query: 'best CDP libraries', limit: 5 })
-// [{ title, url, snippet }, …]
-```
-
-## Local mode — use your own Chrome, zero cloud minutes
-
-If you want to skip cloud-browser minutes entirely, you can point the SDK at
-your own local Chrome via the **Prompteryx plugin + Electron runner**. Two
-paths connect your own Playwright over CDP (autopilot local mode is a third —
-covered just below):
-
-**1. `px.cloudBrowser.sessions.create({ target: 'local' })`** — returns a
-session whose `connectUrl` points at `http://127.0.0.1:9222`. Hand that to
-Playwright and drive your own Chrome:
-
-```ts
-const s = await px.cloudBrowser.sessions.create({ target: 'local' })
-// s.connectUrl === 'http://127.0.0.1:9222'
-const browser = await chromium.connectOverCDP(s.connectUrl)
-// …drive it. No cloud minutes billed.
-await px.cloudBrowser.sessions.close(s.id)  // no-op for local sessions
-```
-
-**2. `px.workflows.run(id, { execution: { target: 'local' } })`** — runs
-a saved workflow against your local Chrome instead of the cloud browser:
-
-```ts
-await px.workflows.run('wf_abc123', {
-  execution: { target: 'local', chromeProfile: 'Work' },
-})
-```
-
-**Prereqs (both paths):**
-- The **Prompteryx plugin** is installed in your Chrome.
-- The **Electron runner** is running on the same machine as the SDK consumer
-  (the SDK talks to `localhost`, so they must co-locate).
-- Chrome is launched with remote debugging on port 9222. The plugin manages
-  this for you when it's connected.
-
-### Autopilot in local mode
-
-`px.autopilot.run({ target: 'local' })` runs the autonomous agent against
-your own local Chrome. Unlike the two CDP paths above, it talks **directly to
-the Prompteryx desktop app** at `http://localhost:61337` (override with
-`runnerUrl`):
-
-```ts
-const result = await px.autopilot.run({
-  target: 'local',
-  goal: 'Open my Gmail and tell me how many unread emails I have',
-  aiVision: 'balanced',   // quality preset — lower = cheaper/faster, higher = more accurate
-  maxSteps: 30,
-})
-```
-
-**Requirements:** the **Prompteryx desktop app** must be **running and signed
-in** on this machine, and your code must run on the **same machine** (the SDK
-talks to `localhost`). Zero cloud-browser minutes are billed — AI Credits
-still apply — and the browser tab stays open after the run for inspection or
-follow-ups. It supports the same knobs as cloud: `model`, `aiVision` preset,
-`maxSteps`, `maxCredits`, `costSaving`.
-
-> `px.autopilot.stream({ target: 'local' })` throws a clear message —
-> use the blocking `autopilot.run` for local runs.
-
-## Streaming an autopilot run
-
-`autopilot.stream()` runs the task over the keep-alive stream endpoint
-(`/api/v1/ai-browser/execute-stream`). Note the protocol: the server sends
-heartbeats while the run executes and the full result at the end — so steps
-arrive together when the run finishes (not one-by-one live), ending with a
-`{ step: -1, action: 'done' }` sentinel whose `result` carries the full
-`AutopilotRunResult`. Prefer `run()` unless you want the keep-alive
-transport for a long single-request run.
-
-```ts
-for await (const step of px.autopilot.stream({ goal: 'Buy a ticket' })) {
-  if (step.action === 'done') break
-  console.log('Step', step.step, '→', step.action)
-}
-```
-
-## Stopping a job
-
-```ts
-await px.autopilot.stop(jobId)   // POST { jobId, mode: 'stop' } — stops at the next step boundary
-```
-
-## Configuration
-
-```ts
-new Prompteryx({
-  apiKey: '…',                          // required — px_live_…
-  cloudBrowserKey: '…',                 // optional — pcb_live_…, for px.cloudBrowser.*
-  baseUrl: 'https://prompteryx.com',   // override for self-hosted
-  timeoutMs: 60_000,                    // default per-request timeout
-  maxRetries: 2,                        // retries for transient 5xx/network errors
-  defaultHeaders: { 'X-Project-Id': '…' },
-  fetch: customFetch,                   // for tests / non-default runtimes
-})
-```
-
-## Typed error handling
-
-```ts
-import {
-  AuthError, QuotaError, RateLimitError, NotFoundError,
-  ValidationError, ServerError, NetworkError, TimeoutError, ParseError,
-} from '@prompteryx/sdk'
-
-try {
-  await px.workflows.run('wf_abc')
-} catch (err) {
-  if (err instanceof QuotaError) {
-    // Out of AI Credits / cloud minutes / proxy data / etc.
-    console.log('Exhausted resources:', err.resources)
-  } else if (err instanceof RateLimitError) {
-    // Back off — err.retryAfterSeconds is set when the server provided one
-  } else {
-    throw err
-  }
-}
-```
-
-## Streaming log events
-
-```ts
-const exec = await px.workflows.run('wf_abc')
-for await (const ev of px.executions.stream(exec.executionId)) {
-  console.log(`[${ev.level || 'info'}]`, ev.message)
-  if (ev.type === 'done') break
-}
-```
-
-## Future-proof customisation
-
-`autopilot.run` exposes every option the in-app AI Browser Agent UI
-exposes — model, AI Vision quality preset, final-step vision, structured
-output, max steps, credit cap, cost-saving batching, system-prompt
-override, allowed tools, viewport, proxy, recording, profile id, etc. New
-options added server-side ride through the `passthrough` field without an
-SDK release:
-
-```ts
-await px.autopilot.run({
-  goal: '...',
-  model: 'gemini-3.7-flash',           // catalog in AUTOPILOT_MODELS; default gemini-3.5-flash
-  aiVision: 'balanced',                // quality preset: lower = cheaper/faster, higher = more accurate
-  maxCredits: 50,                      // hard AI-Credit cap (cost guardrail)
-  costSaving: true,                    // batch several safe actions per screenshot
-  allowedTools: ['click', 'extract'],  // restrict capabilities for read-only tasks
-  systemPromptOverride: 'Always confirm before submitting any form.',
-  passthrough: { newServerOption: true },
-})
-```
-
-Same passthrough pattern on `workflows.run` and
-`cloudBrowser.sessions.create`.
-
-## License
-
-MIT
+# @prompteryx/sdk
+
+Official TypeScript SDK for [Prompteryx](https://www.prompteryx.ai).
+
+```bash
+npm install @prompteryx/sdk
+```
+
+Optional peers for the most-used features:
+
+```bash
+npm install zod playwright-core
+```
+
+Works on Node 18+ (global `fetch`), ESM **and** CommonJS.
+
+## Authentication — two key families
+
+| Key | Format | Used by | Sent as | Rate limits |
+|---|---|---|---|---|
+| Platform API key | `px_live_…` | everything except `cloudBrowser` | `Authorization: Bearer` | 60 req/min, 10,000 req/day |
+| Cloud Browser key | `pcb_live_…` | `px.cloudBrowser.*` (sessions / fetch / search) | `x-api-key` | per-plan session quotas |
+
+Create the `px_live_` key in Settings → API Keys, and the `pcb_live_` key in
+Cloud Platform → API Keys. `px.cloudBrowser.*` throws a descriptive
+`AuthError` if you call it without `cloudBrowserKey`.
+
+```ts
+const px = new Prompteryx({
+  apiKey: process.env.PROMPTERYX_API_KEY!,                    // px_live_…
+  cloudBrowserKey: process.env.PROMPTERYX_CLOUD_BROWSER_KEY,  // pcb_live_… (only for cloudBrowser)
+})
+```
+
+## Two AI surfaces — Copilot and Autopilot
+
+Prompteryx has two distinct ways AI helps you automate the browser:
+
+- **Copilot** — you drive Playwright; copilot helps with ONE step.
+  You're in control, AI is the assistant.
+- **Autopilot** — you give a goal in plain English; autopilot drives
+  the whole task end-to-end.
+
+```ts
+import { Prompteryx } from '@prompteryx/sdk'
+import { chromium } from 'playwright-core'
+import { z } from 'zod'
+
+const px = new Prompteryx({
+  apiKey: process.env.PROMPTERYX_API_KEY!,
+  cloudBrowserKey: process.env.PROMPTERYX_CLOUD_BROWSER_KEY,
+})
+
+// — Copilot: assisted single steps —
+const session = await px.cloudBrowser.sessions.create({
+  useProxy: true, proxyLocation: 'us',
+})
+const browser = await chromium.connectOverCDP(session.connectUrl)
+const page = browser.contexts()[0].pages()[0]
+await page.goto('https://example.com/signup')
+
+await px.copilot.do(page, 'click the Sign up button')
+await px.copilot.do(page, 'fill the email field with hello@example.com')
+
+const plan = await px.copilot.read(page, z.object({
+  name: z.string(),
+  pricePerMonth: z.number(),
+  features: z.array(z.string()),
+}))
+
+const actions = await px.copilot.scan(page, 'checkout flow')
+
+// — Autopilot: hand it a goal, it runs end-to-end —
+const result = await px.autopilot.run({
+  goal: 'Find the cheapest direct flight from London to Lisbon next Tuesday and screenshot the booking page',
+  maxSteps: 30,                     // default is 30
+  saveAsWorkflow: true,             // ← key superpower, see below
+})
+// result.usage → { aiCredits, tokensIn, tokensOut, costUSD, turns }
+```
+
+## Action caching = saved workflows
+
+This is Prompteryx's killer feature for cost-conscious users. Set
+`saveAsWorkflow: true` on any `autopilot.run` call and the discovered
+action sequence is captured as a permanent Visual Studio workflow:
+
+```ts
+const result = await px.autopilot.run({
+  goal: 'Apply for the Senior Engineer role at OpenAI',
+  saveAsWorkflow: true,
+  savedWorkflowName: 'apply-openai-senior',
+})
+
+// Replay forever at ZERO AI cost:
+await px.workflows.run(result.savedWorkflowId!)
+```
+
+The saved workflow is a first-class platform object — schedulable,
+editable in Visual Studio, shareable, API-triggerable. It uses
+multi-option ranked selectors so it stays resilient to UI changes.
+
+## Structured output + final-step vision
+
+```ts
+const result = await px.autopilot.run({
+  goal: 'Get the top 3 HN stories',
+  outputSchema: {                       // finalAnswer becomes JSON matching this
+    type: 'object',
+    properties: {
+      stories: {
+        type: 'array',
+        items: { type: 'object', properties: { title: { type: 'string' }, url: { type: 'string' } } },
+      },
+    },
+  },
+  finalStepVision: 'precision',         // one extra high-quality look before answering
+})
+const data = JSON.parse(result.finalAnswer!)
+```
+
+## The SDK surface (verified against the live API)
+
+| Resource | What it does |
+|---|---|
+| `px.workflows.{list,get,run,runAndWait}` | Visual Studio workflows. |
+| `px.executions.{get,wait,logs,stream,getNodeOutput}` | Execution status + logs. |
+| `px.cloudBrowser.sessions.{create,get,list,close}` | Cloud browser sessions for your own Playwright code (`pcb_live_` key). |
+| `px.cloudBrowser.{fetch,search}` | One-shot page fetch + web search via the cloud browser, no session management (`pcb_live_` key). |
+| `px.copilot.{do,read,scan}` | Assisted single-step primitives on a Playwright page. |
+| `px.autopilot.{run,stream,stop}` | Autonomous multi-step agent with `saveAsWorkflow` action caching. |
+| `px.schedules.{list,get,create,update,delete}` | Server-side cron schedules — the platform fires them even when no client is connected. |
+| `px.profiles.{list,get,create,delete}` | Cloud and local Chrome profiles. |
+| `px.subscription.get` | Plan, balances, top-ups. |
+
+> Removed in 0.4.0 after a live-API audit: `connectHub`, `customNodes`,
+> `templates`, `apiKeys`, `recordings`, `subscription.usage`, and
+> `sessions.getDownloads/getRecording` — their routes don't exist on the
+> live API today (or, for `apiKeys`, can never accept API-key auth). A
+> smaller honest SDK beats a 404ing surface; they return when their
+> endpoints ship.
+
+## Models
+
+`autopilot.run({ model })` defaults to **`gemini-3.5-flash`** (recommended —
+fast and cheap). The full catalog of 32 ids is exported as
+`AUTOPILOT_MODELS` (type `AutopilotModel`), mirrored from the platform's
+canonical list — highlights:
+
+- `gemini-3.5-flash` (default), `gemini-3.7-flash` (newest GA Flash),
+  `gemini-3.6-flash`, `gemini-default` (legacy 2.5)
+- `claude-sonnet-4-6`, `claude-opus-4-8` (native computer use)
+- `gpt-5.6-terra`, `gpt-5.6-sol`, `gpt-5.5`
+- Vision-loop variants (`claude-fable-5-vision`, `gpt-5.6-luna-vision`, …)
+  and experimental harness engines (`model-h`, `modelc`, …)
+
+Unknown ids are forwarded for forward-compatibility but hard-400 with
+`UNSUPPORTED_MODEL` under strict validation — stick to the catalog.
+
+## One-shot fetch and search
+
+No Playwright, no session management — a real cloud Chromium loads the page
+(so JS-rendered sites work) and returns token-efficient content:
+
+```ts
+const pageData = await px.cloudBrowser.fetch({
+  url: 'https://example.com/pricing',
+  format: 'markdown',                  // 'text' (default) | 'markdown' | 'html' | 'links'
+  waitForSelector: '.pricing-table',   // wait for JS-rendered content
+  selectors: ['.pricing-table .plan'], // deterministic CSS extraction (count + text + html)
+  screenshot: true,                    // base64 JPEG in .screenshotBase64
+})
+
+// Web search — DuckDuckGo in a real browser, structured results:
+const results = await px.cloudBrowser.search({ query: 'best CDP libraries', limit: 5 })
+// [{ title, url, snippet }, …]
+```
+
+## Local mode — use your own Chrome, zero cloud minutes
+
+If you want to skip cloud-browser minutes entirely, you can point the SDK at
+your own local Chrome via the **Prompteryx plugin + Electron runner**. Two
+paths connect your own Playwright over CDP (autopilot local mode is a third —
+covered just below):
+
+**1. `px.cloudBrowser.sessions.create({ target: 'local' })`** — returns a
+session whose `connectUrl` points at `http://127.0.0.1:9222`. Hand that to
+Playwright and drive your own Chrome:
+
+```ts
+const s = await px.cloudBrowser.sessions.create({ target: 'local' })
+// s.connectUrl === 'http://127.0.0.1:9222'
+const browser = await chromium.connectOverCDP(s.connectUrl)
+// …drive it. No cloud minutes billed.
+await px.cloudBrowser.sessions.close(s.id)  // no-op for local sessions
+```
+
+**2. `px.workflows.run(id, { execution: { target: 'local' } })`** — runs
+a saved workflow against your local Chrome instead of the cloud browser:
+
+```ts
+await px.workflows.run('wf_abc123', {
+  execution: { target: 'local', chromeProfile: 'Work' },
+})
+```
+
+**Prereqs (both paths):**
+- The **Prompteryx plugin** is installed in your Chrome.
+- The **Electron runner** is running on the same machine as the SDK consumer
+  (the SDK talks to `localhost`, so they must co-locate).
+- Chrome is launched with remote debugging on port 9222. The plugin manages
+  this for you when it's connected.
+
+### Autopilot in local mode
+
+`px.autopilot.run({ target: 'local' })` runs the autonomous agent against
+your own local Chrome. Unlike the two CDP paths above, it talks **directly to
+the Prompteryx desktop app** at `http://localhost:61337` (override with
+`runnerUrl`):
+
+```ts
+const result = await px.autopilot.run({
+  target: 'local',
+  goal: 'Open my Gmail and tell me how many unread emails I have',
+  aiVision: 'balanced',   // quality preset — lower = cheaper/faster, higher = more accurate
+  maxSteps: 30,
+})
+```
+
+**Requirements:** the **Prompteryx desktop app** must be **running and signed
+in** on this machine, and your code must run on the **same machine** (the SDK
+talks to `localhost`). Zero cloud-browser minutes are billed — AI Credits
+still apply — and the browser tab stays open after the run for inspection or
+follow-ups. It supports the same knobs as cloud: `model`, `aiVision` preset,
+`maxSteps`, `maxCredits`, `costSaving`.
+
+> `px.autopilot.stream({ target: 'local' })` throws a clear message —
+> use the blocking `autopilot.run` for local runs.
+
+## Streaming an autopilot run
+
+`autopilot.stream()` runs the task over the keep-alive stream endpoint
+(`/api/v1/ai-browser/execute-stream`). Note the protocol: the server sends
+heartbeats while the run executes and the full result at the end — so steps
+arrive together when the run finishes (not one-by-one live), ending with a
+`{ step: -1, action: 'done' }` sentinel whose `result` carries the full
+`AutopilotRunResult`. Prefer `run()` unless you want the keep-alive
+transport for a long single-request run.
+
+```ts
+for await (const step of px.autopilot.stream({ goal: 'Buy a ticket' })) {
+  if (step.action === 'done') break
+  console.log('Step', step.step, '→', step.action)
+}
+```
+
+## Stopping a job
+
+```ts
+await px.autopilot.stop(jobId)   // POST { jobId, mode: 'stop' } — stops at the next step boundary
+```
+
+## Configuration
+
+```ts
+new Prompteryx({
+  apiKey: '…',                          // required — px_live_…
+  cloudBrowserKey: '…',                 // optional — pcb_live_…, for px.cloudBrowser.*
+  baseUrl: 'https://www.prompteryx.ai',   // override for self-hosted
+  timeoutMs: 60_000,                    // default per-request timeout
+  maxRetries: 2,                        // retries for transient 5xx/network errors
+  defaultHeaders: { 'X-Project-Id': '…' },
+  fetch: customFetch,                   // for tests / non-default runtimes
+})
+```
+
+## Typed error handling
+
+```ts
+import {
+  AuthError, QuotaError, RateLimitError, NotFoundError,
+  ValidationError, ServerError, NetworkError, TimeoutError, ParseError,
+} from '@prompteryx/sdk'
+
+try {
+  await px.workflows.run('wf_abc')
+} catch (err) {
+  if (err instanceof QuotaError) {
+    // Out of AI Credits / cloud minutes / proxy data / etc.
+    console.log('Exhausted resources:', err.resources)
+  } else if (err instanceof RateLimitError) {
+    // Back off — err.retryAfterSeconds is set when the server provided one
+  } else {
+    throw err
+  }
+}
+```
+
+## Streaming log events
+
+```ts
+const exec = await px.workflows.run('wf_abc')
+for await (const ev of px.executions.stream(exec.executionId)) {
+  console.log(`[${ev.level || 'info'}]`, ev.message)
+  if (ev.type === 'done') break
+}
+```
+
+## Future-proof customisation
+
+`autopilot.run` exposes every option the in-app AI Browser Agent UI
+exposes — model, AI Vision quality preset, final-step vision, structured
+output, max steps, credit cap, cost-saving batching, system-prompt
+override, allowed tools, viewport, proxy, recording, profile id, etc. New
+options added server-side ride through the `passthrough` field without an
+SDK release:
+
+```ts
+await px.autopilot.run({
+  goal: '...',
+  model: 'gemini-3.7-flash',           // catalog in AUTOPILOT_MODELS; default gemini-3.5-flash
+  aiVision: 'balanced',                // quality preset: lower = cheaper/faster, higher = more accurate
+  maxCredits: 50,                      // hard AI-Credit cap (cost guardrail)
+  costSaving: true,                    // batch several safe actions per screenshot
+  allowedTools: ['click', 'extract'],  // restrict capabilities for read-only tasks
+  systemPromptOverride: 'Always confirm before submitting any form.',
+  passthrough: { newServerOption: true },
+})
+```
+
+Same passthrough pattern on `workflows.run` and
+`cloudBrowser.sessions.create`.
+
+## License
+
+MIT