@prompteryx/sdk 0.4.0 → 0.4.1

package/package.json

@@ -1,86 +1,86 @@
-{
-  "name": "@prompteryx/sdk",
-  "version": "0.4.0",
-  "description": "Official TypeScript SDK for Prompteryx — cloud browser, the AI Browser Agent (autopilot), workflows, and the copilot do/read/scan primitives.",
-  "license": "MIT",
-  "author": "Prompteryx <support@prompteryx.com>",
-  "homepage": "https://prompteryx.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/prompteryx/sdk-js.git"
-  },
-  "type": "commonjs",
-  "keywords": [
-    "prompteryx",
-    "browser-automation",
-    "playwright",
-    "ai-agent",
-    "cloud-browser",
-    "autopilot",
-    "copilot",
-    "web-automation"
-  ],
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.mts",
-        "default": "./dist/index.mjs"
-      },
-      "require": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      }
-    },
-    "./page": {
-      "import": {
-        "types": "./dist/page.d.mts",
-        "default": "./dist/page.mjs"
-      },
-      "require": {
-        "types": "./dist/page.d.ts",
-        "default": "./dist/page.js"
-      }
-    }
-  },
-  "sideEffects": false,
-  "files": [
-    "dist",
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run typecheck && npm run build",
-    "clean": "rimraf dist"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "peerDependencies": {
-    "playwright-core": ">=1.40.0",
-    "zod": ">=3.20.0"
-  },
-  "peerDependenciesMeta": {
-    "playwright-core": {
-      "optional": true
-    },
-    "zod": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@types/node": ">=18.0.0",
-    "playwright-core": "^1.56.1",
-    "tsup": "^8.5.0",
-    "typescript": "^5.0.0",
-    "zod": "^3.24.1"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "@prompteryx/sdk",
+  "version": "0.4.1",
+  "description": "Official TypeScript SDK for Prompteryx \u2014 cloud browser, the AI Browser Agent (autopilot), workflows, and the copilot do/read/scan primitives.",
+  "license": "MIT",
+  "author": "Prompteryx <support@prompteryx.ai>",
+  "homepage": "https://www.prompteryx.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prompteryx/sdk-js.git"
+  },
+  "type": "commonjs",
+  "keywords": [
+    "prompteryx",
+    "browser-automation",
+    "playwright",
+    "ai-agent",
+    "cloud-browser",
+    "autopilot",
+    "copilot",
+    "web-automation"
+  ],
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./page": {
+      "import": {
+        "types": "./dist/page.d.mts",
+        "default": "./dist/page.mjs"
+      },
+      "require": {
+        "types": "./dist/page.d.ts",
+        "default": "./dist/page.js"
+      }
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build",
+    "clean": "rimraf dist"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "playwright-core": ">=1.40.0",
+    "zod": ">=3.20.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright-core": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": ">=18.0.0",
+    "playwright-core": "^1.56.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.0.0",
+    "zod": "^3.24.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/client.ts

@@ -28,7 +28,7 @@ import {
 } from './errors'
 import type { PrompteryxClientOptions } from './types'
 
-const DEFAULT_BASE_URL = 'https://prompteryx.com'
+const DEFAULT_BASE_URL = 'https://www.prompteryx.ai'
 const DEFAULT_TIMEOUT_MS = 60_000
 const DEFAULT_MAX_RETRIES = 2
 
@@ -50,6 +50,26 @@ export interface RequestOptions {
   signal?: AbortSignal
 }
 
+/**
+ * Every /api/v1 route answers `{ success, data, meta }`. Resources read the
+ * payload directly (`res.workflows`, `res.apps`, …), so unwrap the envelope
+ * here. Before 0.4.1 the raw envelope was returned and every list() came
+ * back empty. Non-envelope bodies (webhooks, raw payloads) pass through.
+ */
+function unwrapEnvelope(parsed: unknown): unknown {
+  if (
+    parsed &&
+    typeof parsed === 'object' &&
+    !Array.isArray(parsed) &&
+    'success' in parsed &&
+    'data' in parsed &&
+    typeof (parsed as { success: unknown }).success === 'boolean'
+  ) {
+    return (parsed as { data: unknown }).data
+  }
+  return parsed
+}
+
 export class HttpClient {
   private readonly apiKey: string
   /** Optional Cloud Browser key (`pcb_live_…`) — a separate key family used
@@ -86,14 +106,16 @@ export class HttpClient {
     const res = await this.rawRequest(path, opts)
     const text = await res.text()
     if (!text) return undefined as T
+    let parsed: unknown
     try {
-      return JSON.parse(text) as T
+      parsed = JSON.parse(text)
     } catch {
       throw new ParseError(`Failed to parse JSON response from ${path}`, {
         status: res.status,
         raw: text.slice(0, 500),
       })
     }
+    return unwrapEnvelope(parsed) as T
   }
 
   /** Returns the raw Response. Throws typed errors on non-2xx, but does

package/src/index.ts

@@ -1,140 +1,140 @@
-/**
- * @prompteryx/sdk
- *
- * Official TypeScript SDK for the Prompteryx platform.
- *
- * Two AI surfaces:
- *
- *   • **Copilot** — helps with ONE step you describe in plain English.
- *     Your code drives Playwright; copilot just figures out the
- *     selector to click / the data to pull / what's on the page.
- *
- *     ```ts
- *     await px.copilot.do(page, 'click the Sign up button')
- *     const product = await px.copilot.read(page, productSchema)
- *     const actions = await px.copilot.scan(page, 'checkout buttons')
- *     ```
- *
- *   • **Autopilot** — runs an autonomous multi-step task end-to-end
- *     with no per-action involvement from you.
- *
- *     ```ts
- *     const result = await px.autopilot.run({
- *       goal: 'Apply for the Senior Engineer role at OpenAI',
- *       saveAsWorkflow: true,   // permanent zero-AI-cost replay
- *     })
- *     ```
- *
- * Plus workflows, executions, cloud browser sessions / fetch / search,
- * schedules, profiles, and subscription telemetry.
- *
- * TWO KEY FAMILIES:
- *   • `apiKey` (`px_live_…`) — the platform API key; sent as
- *     `Authorization: Bearer`. 60 requests/minute, 10,000/day.
- *   • `cloudBrowserKey` (`pcb_live_…`) — the Cloud Browser key; required
- *     only for `px.cloudBrowser.*`, sent as `x-api-key`.
- *
- * Quick start:
- *
- * ```ts
- * import { Prompteryx } from '@prompteryx/sdk'
- * import { chromium } from 'playwright-core'
- *
- * const px = new Prompteryx({
- *   apiKey: process.env.PROMPTERYX_API_KEY!,                    // px_live_…
- *   cloudBrowserKey: process.env.PROMPTERYX_CLOUD_BROWSER_KEY,  // pcb_live_…
- * })
- *
- * // 1. Cloud browser session
- * 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]
- *
- * // 2. Copilot on top of Playwright
- * await page.goto('https://news.ycombinator.com')
- * const top = await px.copilot.read(page, z.object({
- *   stories: z.array(z.object({ title: z.string(), url: z.string() })),
- * }))
- * ```
- *
- * See PROMPTERYX_SDK.md in docs/ for the full design + reference.
- */
-
-import { HttpClient } from './client'
-import { AutopilotResource } from './resources/autopilot'
-import { CloudBrowserResource } from './resources/cloudBrowser'
-import { ExecutionsResource } from './resources/executions'
-import { ProfilesResource } from './resources/profiles'
-import { SchedulesResource } from './resources/schedules'
-import { SubscriptionResource } from './resources/subscription'
-import { WorkflowsResource } from './resources/workflows'
-import { CopilotHelpers, type PageLike } from './page'
-import type {
-  CopilotDoResult,
-  DiscoveredAction,
-  PrompteryxClientOptions,
-} from './types'
-
-// Public re-exports
-export * from './errors'
-export * from './types'
-export * from './models'
-export type { PageLike }
-
-// v0.4.0 (2026-09-03): the connectHub, customNodes, templates, apiKeys and
-// recordings namespaces plus subscription.usage() were REMOVED from the
-// public surface — the routes they target don't exist on the live API (or,
-// for api-keys, can never accept API-key auth). The source files remain in
-// src/resources/ with dated NOT-SHIPPED headers for a future release.
-
-/**
- * Copilot surface — bundles the three on-page primitives behind a
- * single namespace so calling code reads as
- * `px.copilot.do(...)` / `px.copilot.read(...)` / `px.copilot.scan(...)`.
- * Used internally by the Prompteryx class.
- */
-class Copilot {
-  constructor(private readonly helpers: CopilotHelpers) {}
-  /** Execute a natural-language action on a connected Playwright page. */
-  do(page: PageLike, instruction: string, opts?: { timeout?: number }): Promise<CopilotDoResult> {
-    return this.helpers.do(page, instruction, opts)
-  }
-  /** Pull typed data from the page (Zod schema or raw JSON Schema). */
-  read<T>(page: PageLike, schema: { parse(input: unknown): T } | { jsonSchema: unknown }): Promise<T> {
-    return this.helpers.read<T>(page, schema as any)
-  }
-  /** Discover available actions on the page; useful pre-`do` step. */
-  scan(page: PageLike, hint?: string): Promise<DiscoveredAction[]> {
-    return this.helpers.scan(page, hint)
-  }
-}
-
-export class Prompteryx {
-  private readonly http: HttpClient
-
-  // Core resources — the verified live surface.
-  public readonly workflows: WorkflowsResource
-  public readonly executions: ExecutionsResource
-  public readonly cloudBrowser: CloudBrowserResource
-  public readonly autopilot: AutopilotResource
-  public readonly copilot: Copilot
-  public readonly schedules: SchedulesResource
-  public readonly profiles: ProfilesResource
-  public readonly subscription: SubscriptionResource
-
-  constructor(opts: PrompteryxClientOptions) {
-    this.http = new HttpClient(opts)
-    this.workflows = new WorkflowsResource(this.http)
-    this.executions = new ExecutionsResource(this.http)
-    this.cloudBrowser = new CloudBrowserResource(this.http)
-    this.autopilot = new AutopilotResource(this.http)
-    this.copilot = new Copilot(new CopilotHelpers(this.http))
-    this.schedules = new SchedulesResource(this.http)
-    this.profiles = new ProfilesResource(this.http)
-    this.subscription = new SubscriptionResource(this.http)
-  }
-}
-
-export default Prompteryx
+/**
+ * @prompteryx/sdk
+ *
+ * Official TypeScript SDK for the Prompteryx platform.
+ *
+ * Two AI surfaces:
+ *
+ *   • **Copilot** — helps with ONE step you describe in plain English.
+ *     Your code drives Playwright; copilot just figures out the
+ *     selector to click / the data to pull / what's on the page.
+ *
+ *     ```ts
+ *     await px.copilot.do(page, 'click the Sign up button')
+ *     const product = await px.copilot.read(page, productSchema)
+ *     const actions = await px.copilot.scan(page, 'checkout buttons')
+ *     ```
+ *
+ *   • **Autopilot** — runs an autonomous multi-step task end-to-end
+ *     with no per-action involvement from you.
+ *
+ *     ```ts
+ *     const result = await px.autopilot.run({
+ *       goal: 'Apply for the Senior Engineer role at OpenAI',
+ *       saveAsWorkflow: true,   // permanent zero-AI-cost replay
+ *     })
+ *     ```
+ *
+ * Plus workflows, executions, cloud browser sessions / fetch / search,
+ * schedules, profiles, and subscription telemetry.
+ *
+ * TWO KEY FAMILIES:
+ *   • `apiKey` (`px_live_…`) — the platform API key; sent as
+ *     `Authorization: Bearer`. 60 requests/minute, 10,000/day.
+ *   • `cloudBrowserKey` (`pcb_live_…`) — the Cloud Browser key; required
+ *     only for `px.cloudBrowser.*`, sent as `x-api-key`.
+ *
+ * Quick start:
+ *
+ * ```ts
+ * import { Prompteryx } from '@prompteryx/sdk'
+ * import { chromium } from 'playwright-core'
+ *
+ * const px = new Prompteryx({
+ *   apiKey: process.env.PROMPTERYX_API_KEY!,                    // px_live_…
+ *   cloudBrowserKey: process.env.PROMPTERYX_CLOUD_BROWSER_KEY,  // pcb_live_…
+ * })
+ *
+ * // 1. Cloud browser session
+ * 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]
+ *
+ * // 2. Copilot on top of Playwright
+ * await page.goto('https://news.ycombinator.com')
+ * const top = await px.copilot.read(page, z.object({
+ *   stories: z.array(z.object({ title: z.string(), url: z.string() })),
+ * }))
+ * ```
+ *
+ * See PROMPTERYX_SDK.md in docs/ for the full design + reference.
+ */
+
+import { HttpClient } from './client'
+import { AutopilotResource } from './resources/autopilot'
+import { CloudBrowserResource } from './resources/cloudBrowser'
+import { ExecutionsResource } from './resources/executions'
+import { ProfilesResource } from './resources/profiles'
+import { SchedulesResource } from './resources/schedules'
+import { SubscriptionResource } from './resources/subscription'
+import { WorkflowsResource } from './resources/workflows'
+import { CopilotHelpers, type PageLike } from './page'
+import type {
+  CopilotDoResult,
+  DiscoveredAction,
+  PrompteryxClientOptions,
+} from './types'
+
+// Public re-exports
+export * from './errors'
+export * from './types'
+export * from './models'
+export type { PageLike }
+
+// v0.4.0 (2026-09-03): the connectHub, customNodes, templates, apiKeys and
+// recordings namespaces plus subscription.usage() were REMOVED from the
+// public surface — the routes they target don't exist on the live API (or,
+// for api-keys, can never accept API-key auth). The source files remain in
+// src/resources/ with dated NOT-SHIPPED headers for a future release.
+
+/**
+ * Copilot surface — bundles the three on-page primitives behind a
+ * single namespace so calling code reads as
+ * `px.copilot.do(...)` / `px.copilot.read(...)` / `px.copilot.scan(...)`.
+ * Used internally by the Prompteryx class.
+ */
+class Copilot {
+  constructor(private readonly helpers: CopilotHelpers) {}
+  /** Execute a natural-language action on a connected Playwright page. */
+  do(page: PageLike, instruction: string, opts?: { timeout?: number }): Promise<CopilotDoResult> {
+    return this.helpers.do(page, instruction, opts)
+  }
+  /** Pull typed data from the page (Zod schema or raw JSON Schema). */
+  read<T>(page: PageLike, schema: { parse(input: unknown): T } | { jsonSchema: unknown }): Promise<T> {
+    return this.helpers.read<T>(page, schema as any)
+  }
+  /** Discover available actions on the page; useful pre-`do` step. */
+  scan(page: PageLike, hint?: string): Promise<DiscoveredAction[]> {
+    return this.helpers.scan(page, hint)
+  }
+}
+
+export class Prompteryx {
+  private readonly http: HttpClient
+
+  // Core resources — the verified live surface.
+  public readonly workflows: WorkflowsResource
+  public readonly executions: ExecutionsResource
+  public readonly cloudBrowser: CloudBrowserResource
+  public readonly autopilot: AutopilotResource
+  public readonly copilot: Copilot
+  public readonly schedules: SchedulesResource
+  public readonly profiles: ProfilesResource
+  public readonly subscription: SubscriptionResource
+
+  constructor(opts: PrompteryxClientOptions) {
+    this.http = new HttpClient(opts)
+    this.workflows = new WorkflowsResource(this.http)
+    this.executions = new ExecutionsResource(this.http)
+    this.cloudBrowser = new CloudBrowserResource(this.http)
+    this.autopilot = new AutopilotResource(this.http)
+    this.copilot = new Copilot(new CopilotHelpers(this.http))
+    this.schedules = new SchedulesResource(this.http)
+    this.profiles = new ProfilesResource(this.http)
+    this.subscription = new SubscriptionResource(this.http)
+  }
+}
+
+export default Prompteryx

package/src/models.ts

@@ -1,63 +1,66 @@
-/**
- * Browser-agent model catalog — the ids `px.autopilot.run({ model })` accepts.
- *
- * ⚠️ MUST MIRROR `components/unified-chat-v2/browser-models.ts`
- * `V2_BROWSER_MODELS` in the platform repo — that file is the canonical
- * catalog the server validates against (an unknown id hard-400s with
- * `UNSUPPORTED_MODEL` under strict validation). When that list changes,
- * regenerate this one. Last synced: 2026-09-03 — 32 ids.
- *
- * The type stays open (`| (string & {})`) so a model the server adds
- * tomorrow works without an SDK release, while editors still autocomplete
- * the known catalog.
- */
-
-export const AUTOPILOT_MODELS = [
-  // ── Standard (Gemini native Computer Use) ────────────────────────────────
-  'gemini-3.5-flash', // Recommended — fast and cheap. THE DEFAULT.
-  'gemini-3.7-flash', // Newest GA Flash — Google-recommended for computer use
-  'gemini-3.6-flash', // Newest Flash (Computer Use preview)
-  'gemini-default', // Gemini 2.5 Computer Use (legacy)
-  // ── Experimental (Gemini) ────────────────────────────────────────────────
-  'gemini-3-flash-preview',
-  'gemini-3.5-flash-lite',
-  // Harness aliases — resolved server-side to an underlying brain + prompt.
-  'model-a',
-  'model-a1',
-  'model-b',
-  'model-j',
-  'model-k',
-  'model-k37',
-  // ── Anthropic / OpenAI native Computer Use ───────────────────────────────
-  'claude-sonnet-4-6',
-  'claude-opus-4-8',
-  'gpt-5.6-terra',
-  'gpt-5.6-sol',
-  'gpt-5.5',
-  // ── Generic Vision Loop (standard chat models on screenshots) ────────────
-  'claude-fable-5-vision',
-  'claude-opus-5-vision',
-  'claude-sonnet-5-vision',
-  'claude-sonnet-4-6-vision',
-  'gpt-5.6-luna-vision',
-  'gpt-5.4-vision',
-  'gpt-4o-vision',
-  'kimi-k3-vision',
-  // ── Experimental server-side harness engines ─────────────────────────────
-  'modelc',
-  'model-d',
-  'model-d1',
-  'model-e',
-  'model-f',
-  'model-h',
-  'model-i',
-] as const
-
-/** A model id from the known catalog. */
-export type AutopilotModelId = (typeof AUTOPILOT_MODELS)[number]
-
-/** Open union: known ids autocomplete, forward-compatible strings still pass. */
-export type AutopilotModel = AutopilotModelId | (string & {})
-
-/** The platform default when `model` is omitted. */
-export const DEFAULT_AUTOPILOT_MODEL = 'gemini-3.5-flash'
+/**
+ * Browser-agent model catalog — the ids `px.autopilot.run({ model })` accepts.
+ *
+ * ⚠️ MUST MIRROR `components/unified-chat-v2/browser-models.ts`
+ * `V2_BROWSER_MODELS` in the platform repo — that file is the canonical
+ * catalog the server validates against (an unknown id hard-400s with
+ * `UNSUPPORTED_MODEL` under strict validation). When that list changes,
+ * regenerate this one. Last synced: 2026-09-07 — 35 ids.
+ *
+ * The type stays open (`| (string & {})`) so a model the server adds
+ * tomorrow works without an SDK release, while editors still autocomplete
+ * the known catalog.
+ */
+
+export const AUTOPILOT_MODELS = [
+  // ── Standard (Gemini native Computer Use) ────────────────────────────────
+  'gemini-3.5-flash', // Recommended — fast and cheap. THE DEFAULT.
+  'gemini-3.7-flash', // Newest GA Flash — Google-recommended for computer use
+  'gemini-3.6-flash', // Newest Flash (Computer Use preview)
+  'gemini-default', // Gemini 2.5 Computer Use (legacy)
+  // ── Experimental (Gemini) ────────────────────────────────────────────────
+  'gemini-3-flash-preview',
+  'gemini-3.5-flash-lite',
+  // Harness aliases — resolved server-side to an underlying brain + prompt.
+  'model-a',
+  'model-a1',
+  'model-b',
+  'model-j',
+  'model-k',
+  'model-k37',
+  // ── Anthropic / OpenAI native Computer Use ───────────────────────────────
+  'claude-sonnet-4-6',
+  'claude-opus-4-8',
+  'gpt-5.6-terra',
+  'gpt-5.6-sol',
+  'gpt-5.5',
+  'gpt-6-astra', // OpenAI flagship (Sep 2026) — admin-gated in the UI for now
+  // ── Generic Vision Loop (standard chat models on screenshots) ────────────
+  'claude-fable-5-1-vision',
+  'claude-fable-5-vision',
+  'claude-opus-5-vision',
+  'claude-sonnet-5-vision',
+  'claude-sonnet-4-6-vision',
+  'gpt-6-astra-vision', // admin-gated in the UI for now
+  'gpt-5.6-luna-vision',
+  'gpt-5.4-vision',
+  'gpt-4o-vision',
+  'kimi-k3-vision',
+  // ── Experimental server-side harness engines ─────────────────────────────
+  'modelc',
+  'model-d',
+  'model-d1',
+  'model-e',
+  'model-f',
+  'model-h',
+  'model-i',
+] as const
+
+/** A model id from the known catalog. */
+export type AutopilotModelId = (typeof AUTOPILOT_MODELS)[number]
+
+/** Open union: known ids autocomplete, forward-compatible strings still pass. */
+export type AutopilotModel = AutopilotModelId | (string & {})
+
+/** The platform default when `model` is omitted. */
+export const DEFAULT_AUTOPILOT_MODEL = 'gemini-3.5-flash'