@prompteryx/sdk 0.4.0

package/src/resources/autopilot.ts

@@ -0,0 +1,385 @@
+/**
+ * `px.autopilot.*` — autonomous browser agent.
+ *
+ * **Autopilot** is the autonomous, multi-step surface. You hand it
+ * a goal in plain English; it drives the browser end-to-end and
+ * returns a step-by-step trace. Counterpart to **Copilot** which
+ * helps with one step at a time (see ../page.ts).
+ *
+ * Built on the existing AI Browser Agent runtime. Every option the
+ * in-app UI exposes — model, max steps, system-prompt override,
+ * tool restrictions, viewport, region, proxy, CAPTCHA, recording —
+ * is available via the SDK. New options added to the runtime ride
+ * through `passthrough` without an SDK release.
+ *
+ * **Action caching superpower** — set `saveAsWorkflow: true` and the
+ * autopilot's discovered action sequence is captured as a permanent
+ * Visual Studio workflow you can replay for free forever. The
+ * response includes `savedWorkflowId`. Subsequent calls to
+ * `px.workflows.run(savedWorkflowId)` cost no AI Credits and benefit
+ * from multi-option-selector resilience to UI changes.
+ */
+
+import { ParseError, PrompteryxError } from '../errors'
+import type { HttpClient } from '../client'
+import type {
+  AutopilotRunOptions,
+  AutopilotRunResult,
+  AutopilotStep,
+} from '../types'
+
+export class AutopilotResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * Run the autopilot. Blocks until the task finishes (success, step
+   * limit, or error). Returns the trace plus optionally the saved
+   * workflow id.
+   *
+   * ```ts
+   * const result = await px.autopilot.run({
+   *   goal: 'Apply for the Senior Engineer role at OpenAI',
+   *   startUrl: 'https://openai.com/careers',
+   *   maxSteps: 40,
+   *   saveAsWorkflow: true,         // Replay-forever, zero AI cost
+   *   session: { useProxy: true, useCaptcha: true },
+   * })
+   * if (result.savedWorkflowId) {
+   *   console.log('Saved as workflow:', result.savedWorkflowId)
+   *   // Run it later for free:
+   *   await px.workflows.run(result.savedWorkflowId)
+   * }
+   * ```
+   */
+  async run(opts: AutopilotRunOptions): Promise<AutopilotRunResult> {
+    if (opts.target === 'local') {
+      // Local Chrome autopilot (v0.3+): drive the user's OWN Chrome via the
+      // Prompteryx desktop app on THIS machine. Zero cloud-browser minutes.
+      // The SDK talks directly to the local runner (localhost:61337) — the
+      // cloud API can't reach the user's machine — so requirements are: the
+      // desktop app RUNNING + SIGNED IN, and your code on the same machine.
+      return this.runLocal(opts)
+    }
+    // Multi-agent swarm runs server-side and returns a MERGED result in one
+    // response — keep it on the single-request path (unchanged).
+    if (opts.agents && opts.agents > 1) {
+      return this.runSwarm(opts)
+    }
+    // Single cloud agent: ASYNC start → run(poll) so a LONG task (e.g. filling a
+    // form once per CSV row) never runs in one synchronous request — which would
+    // exceed the infra GATEWAY timeout and hand the caller an HTML error page that
+    // res.json() chokes on. Each request stays short; we loop until the job is done.
+    return this.runAsync(opts)
+  }
+
+  /** The task params shared by the sync, swarm, and async request bodies. */
+  private cloudTaskBody(opts: AutopilotRunOptions): Record<string, unknown> {
+    return {
+      instruction: opts.goal,
+      startUrl: opts.startUrl,
+      maxSteps: opts.maxSteps,
+      maxCredits: opts.maxCredits,
+      model: opts.model,
+      aiVision: opts.aiVision,
+      finalStepVision: opts.finalStepVision,
+      outputSchema: opts.outputSchema,
+      costSaving: opts.costSaving,
+      costSavingMaxBatch: opts.costSavingMaxBatch,
+      carefulBatching: opts.carefulBatching,
+      saveAsWorkflow: opts.saveAsWorkflow,
+      savedWorkflowName: opts.savedWorkflowName,
+      sessionId: opts.sessionId,
+      systemPromptOverride: opts.systemPromptOverride,
+      allowedTools: opts.allowedTools,
+      viewport: opts.viewport,
+      session: opts.session,
+      // Settings parity (2026-07-15) — mirror the AI Browser Agent settings dialog.
+      safetyConsent: opts.safetyConsent,
+      confirmUnclear: opts.confirmUnclear,
+      enableContextCompression: opts.enableContextCompression,
+      compressionThreshold: opts.compressionThreshold,
+      enableSessionReset: opts.enableSessionReset,
+      sessionResetThreshold: opts.sessionResetThreshold,
+      ...opts.passthrough,
+    }
+  }
+
+  /** Multi-agent swarm — one synchronous request; the server merges all lanes. */
+  private async runSwarm(opts: AutopilotRunOptions): Promise<AutopilotRunResult> {
+    const env = await this.http.request<{ data?: unknown }>('/api/v1/ai-browser/execute', {
+      method: 'POST',
+      timeoutMs: opts.timeoutMs ?? 10 * 60_000,
+      body: {
+        ...this.cloudTaskBody(opts),
+        agents: opts.agents,
+        collaborate: opts.collaborate,
+        attachmentContext: opts.attachmentContext,
+        maxRunCredits: opts.maxRunCredits,
+      },
+    })
+    return this.mapResult(env?.data ?? env)
+  }
+
+  /**
+   * Async single-agent run: POST { mode:'start' } to set up the job (returns a
+   * jobId immediately), then POST { mode:'run' } in a loop — each advances the job
+   * for up to ~230s server-side and returns the current status — until the job is
+   * terminal or `opts.timeoutMs` elapses. No single request is long, so the gateway
+   * timeout is never hit. Same `AutopilotRunResult` shape as before.
+   */
+  private async runAsync(opts: AutopilotRunOptions): Promise<AutopilotRunResult> {
+    const timeoutMs = opts.timeoutMs ?? 10 * 60_000
+    const deadline = Date.now() + timeoutMs
+    const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+    // 1) START — SETUP only. Short request; returns { jobId, sessionId }.
+    const startEnv = await this.http.request<{ data?: any }>('/api/v1/ai-browser/execute', {
+      method: 'POST',
+      timeoutMs: 60_000,
+      body: { ...this.cloudTaskBody(opts), mode: 'start' },
+    })
+    const jobId: string | undefined = startEnv?.data?.jobId
+    if (!jobId) {
+      // Back-compat: an OLDER server without async mode ran the whole task
+      // synchronously for mode:'start', so the response IS a full result. Return it.
+      return this.mapResult(startEnv?.data ?? startEnv)
+    }
+
+    // 2) RUN — advance in ≤230s chunks until terminal (or the SDK timeout). The
+    //    chunk itself is the wait; a transport blip on a chunk is safe to retry.
+    let view: any = null
+    while (Date.now() < deadline) {
+      const runEnv = await this.http.request<{ data?: any }>('/api/v1/ai-browser/execute', {
+        method: 'POST',
+        timeoutMs: 250_000,
+        retry: true,
+        body: { jobId, mode: 'run', maxSteps: opts.maxSteps },
+      })
+      view = runEnv?.data ?? null
+      if (!view || view.terminal || view.status !== 'running') break
+      await sleep(500)
+    }
+
+    // 3) If we bailed on the SDK timeout while still running, one status read gives
+    //    the latest known state (and triggers server finalize if it's since ended).
+    if (view && view.status === 'running') {
+      try {
+        const statusEnv = await this.http.request<{ data?: any }>('/api/v1/ai-browser/execute', {
+          query: { jobId },
+          timeoutMs: 30_000,
+        })
+        if (statusEnv?.data) view = statusEnv.data
+      } catch { /* keep the last view */ }
+    }
+
+    return this.mapResult(view)
+  }
+
+  /** Map an execute-endpoint payload (sync result, swarm result, or async status
+   *  view — they share finalAnswer / steps / usage / savedWorkflowId / status) into
+   *  the public AutopilotRunResult shape. */
+  private mapResult(data: any): AutopilotRunResult {
+    const d = data || {}
+    const status: string | undefined = d.status
+    const success = status === 'completed' || status === 'max_steps_reached'
+    const steps: AutopilotStep[] = Array.isArray(d.steps)
+      ? d.steps.map((s: any, i: number) => ({
+          step: i + 1,
+          action: typeof s?.action === 'string' ? s.action : (s?.action?.name || 'action'),
+          result: s?.details ?? s?.result,
+        }))
+      : []
+    return {
+      success,
+      finalAnswer: d.finalAnswer,
+      steps,
+      savedWorkflowId: d.savedWorkflowId,
+      usage: d.usage,
+      swarm: d.swarm,
+    }
+  }
+
+  /**
+   * Local Chrome autopilot — talks DIRECTLY to the Prompteryx desktop app on
+   * this machine (localhost:61337): opens your local Chrome, runs the agent
+   * loop there, polls until done. Same options as `run` (model, aiVision
+   * preset, maxSteps, maxCredits, costSaving). Credits still apply; cloud
+   * minutes do not. The tab stays open after the run for follow-ups.
+   */
+  private async runLocal(opts: AutopilotRunOptions): Promise<AutopilotRunResult> {
+    const fetchImpl: typeof fetch = (globalThis as any).fetch
+    if (!fetchImpl) {
+      throw new Error('[Prompteryx SDK] Local target needs a global fetch (Node 18+ / browser).')
+    }
+    const base = (opts.runnerUrl || 'http://localhost:61337').replace(/\/$/, '')
+    const sessionId = `sdk-local-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+    const goal = opts.startUrl
+      ? `First, go to ${opts.startUrl}. Then: ${opts.goal}`
+      : opts.goal
+
+    const post = async (path: string, body: unknown) => {
+      let r: Response
+      try {
+        r = await fetchImpl(`${base}${path}`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(body),
+        })
+      } catch (e) {
+        throw new Error(
+          `[Prompteryx SDK] Couldn't reach the desktop app at ${base}. ` +
+          `Make sure the Prompteryx desktop app is running and signed in on this machine. (${(e as Error).message})`,
+        )
+      }
+      if (!r.ok) {
+        let msg = `${path} failed (${r.status})`
+        try { const j = await r.json(); if ((j as any)?.error) msg = (j as any).error } catch { /* */ }
+        throw new Error(`[Prompteryx SDK] ${msg}`)
+      }
+      return r.json().catch(() => ({}))
+    }
+
+    // 1) Open the local Chrome + create the agent session.
+    await post('/launch-gemini-browser', {
+      sessionId,
+      profileId: (opts.session as any)?.profileId,
+      enableRecording: false,
+    })
+
+    // 2) Start the agent loop with the same knobs as the cloud path.
+    await post('/local-agent/start', {
+      sessionId,
+      task: goal,
+      model: opts.model,
+      aiVision: opts.aiVision,           // preset slug — resolved app-side
+      maxTurns: opts.maxSteps,
+      maxCredits: opts.maxCredits,
+      costSaving: (opts.passthrough as any)?.costSaving === true,
+      costSavingMaxBatch: (opts.passthrough as any)?.costSavingMaxBatch,
+    })
+
+    // 3) Poll state until terminal (or the SDK timeout).
+    const deadline = Date.now() + (opts.timeoutMs ?? 10 * 60_000)
+    const sleep = (ms: number) => new Promise((res) => setTimeout(res, ms))
+    let state: any = null
+    while (Date.now() < deadline) {
+      await sleep(1200)
+      const r = await fetchImpl(`${base}/local-agent/state/${encodeURIComponent(sessionId)}`).catch(() => null)
+      if (!r || !r.ok) continue
+      state = await r.json().catch(() => null)
+      if (!state || state.found === false) continue
+      if (state.status && state.status !== 'running') break
+    }
+
+    const status = state?.status
+    return {
+      success: status === 'done' || status === 'awaiting_input',
+      finalAnswer: state?.answer,
+      steps: (state?.steps || []).map((s: any, i: number) => ({
+        step: i + 1,
+        action: s?.name || s?.action?.name || 'action',
+        result: s?.args || s?.action?.args,
+      })),
+      usage: {
+        aiCredits: Math.max(0, Math.round((state?.costUSD || 0) / 0.01)),
+        tokensIn: state?.inTokens || 0,
+        tokensOut: state?.outTokens || 0,
+        costUSD: state?.costUSD || 0,
+        turns: state?.turns || 0,
+      },
+    }
+  }
+
+  /**
+   * Ask a running async job to stop at its next step boundary
+   * (`POST { jobId, mode: 'stop' }`). Use it to wind down a job you
+   * started via the raw API (or a run you're abandoning) instead of
+   * leaving it stepping against a dead browser session until the step
+   * cap — an abandoned job burns a model call + timeout per step.
+   *
+   * ```ts
+   * const { stopRequested, status } = await px.autopilot.stop(jobId)
+   * ```
+   */
+  async stop(jobId: string): Promise<{ jobId: string; stopRequested: boolean; status?: string }> {
+    const env = await this.http.request<{ data?: any }>('/api/v1/ai-browser/execute', {
+      method: 'POST',
+      timeoutMs: 30_000,
+      body: { jobId, mode: 'stop' },
+    })
+    const d = env?.data ?? env ?? {}
+    return { jobId: d.jobId ?? jobId, stopRequested: d.stopRequested === true, status: d.status }
+  }
+
+  /**
+   * Run the autopilot over the keep-alive stream endpoint and yield the
+   * step trace. Ends with a `{ step: -1, action: 'done' }` sentinel whose
+   * `result` field carries the full `AutopilotRunResult`.
+   *
+   * ```ts
+   * for await (const step of px.autopilot.stream({ goal: 'Buy a ticket' })) {
+   *   console.log('Step', step.step, '→', step.action)
+   *   if (step.action === 'done') break
+   * }
+   * ```
+   *
+   * PROTOCOL (matches /api/v1/ai-browser/execute-stream — it is NOT SSE):
+   * the server emits a 1-space heartbeat every 15s while the run executes,
+   * then the complete execute-route JSON as the final chunk, i.e. the body
+   * is `<heartbeats>\n<json>`. The heartbeats exist to defeat the ~300s
+   * infra idle timeout on long synchronous runs; per-step live events are
+   * not available on this route, so steps arrive together when the run
+   * finishes. Prefer `run()` unless you specifically want the keep-alive
+   * transport for a long single-request run.
+   */
+  async *stream(
+    opts: AutopilotRunOptions & { signal?: AbortSignal },
+  ): AsyncGenerator<AutopilotStep, void, void> {
+    if (opts.target === 'local') {
+      // Local streaming isn't wired — the local runner has no step emitter.
+      // Use the blocking `run({ target: 'local' })` (its result includes
+      // the full step list) for local Chrome today.
+      throw new Error(
+        '[Prompteryx SDK] Streaming is cloud-only. For local Chrome use ' +
+        'autopilot.run({ target: "local" }) — its result contains all steps.',
+      )
+    }
+    const res = await this.http.rawRequest('/api/v1/ai-browser/execute-stream', {
+      method: 'POST',
+      timeoutMs: opts.timeoutMs ?? 15 * 60_000,
+      body: this.cloudTaskBody(opts),
+      signal: opts.signal,
+    })
+    // Accumulate the whole body: heartbeat spaces, then '\n' + the JSON.
+    let text = ''
+    if (res.body) {
+      const reader = res.body.getReader()
+      const decoder = new TextDecoder()
+      while (true) {
+        const { value, done } = await reader.read()
+        if (done) break
+        if (value) text += decoder.decode(value, { stream: true })
+      }
+      text += decoder.decode()
+    } else {
+      text = await res.text()
+    }
+    // Strip the heartbeats — the JSON is always the last (and only) content.
+    const payload = text.trim()
+    let parsed: any
+    try {
+      parsed = JSON.parse(payload)
+    } catch {
+      throw new ParseError('execute-stream returned a non-JSON payload', {
+        raw: payload.slice(0, 500),
+      })
+    }
+    if (parsed && parsed.success === false) {
+      const msg = parsed?.error?.message ?? parsed?.error ?? 'AI Browser Agent run failed'
+      throw new PrompteryxError(String(msg), { code: parsed?.error?.code, raw: parsed })
+    }
+    const result = this.mapResult(parsed?.data ?? parsed)
+    for (const step of result.steps) yield step
+    yield { step: -1, action: 'done', result }
+  }
+}

package/src/resources/cloudBrowser.ts

@@ -0,0 +1,197 @@
+/**
+ * `px.cloudBrowser.*` — sessions, one-shot fetch, search.
+ *
+ * The most-used path: `sessions.create()` returns a `connectUrl` you
+ * pass to Playwright's `chromium.connectOverCDP(connectUrl)`. Your own
+ * Playwright code drives the browser from there; we handle the
+ * infrastructure (residential proxies, recording, persistence).
+ *
+ * ⚠️ KEY FAMILY (verified live 2026-09-03): every /api/v1/cloud-browser/*
+ * route authenticates with a CLOUD BROWSER key (`pcb_live_…`) sent as
+ * `x-api-key` — NOT the platform `px_live_…` Bearer key the rest of the
+ * SDK uses. Pass it as `new Prompteryx({ apiKey, cloudBrowserKey })`;
+ * calls throw a descriptive AuthError when it's missing.
+ */
+
+import type { HttpClient, RequestOptions } from '../client'
+import { AuthError } from '../errors'
+import type {
+  CloudFetchOptions,
+  CloudFetchResult,
+  CloudSearchResult,
+  CloudSession,
+  CloudSessionSummary,
+  CreateSessionOptions,
+} from '../types'
+
+const MISSING_CB_KEY_MESSAGE =
+  'px.cloudBrowser.* uses a Cloud Browser API key (pcb_live_…), which is a ' +
+  'separate key family from the platform px_live_… key. Create one under ' +
+  'Cloud Platform → API Keys and pass it as ' +
+  'new Prompteryx({ apiKey, cloudBrowserKey }).'
+
+/** Sub-resource: cloud browser sessions. */
+export class SessionsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Headers for the pcb_live_ key family (throws a clear error if absent). */
+  private cbAuth(): Record<string, string> {
+    const key = this.http.cloudBrowserKey
+    if (!key) throw new AuthError(MISSING_CB_KEY_MESSAGE)
+    return { 'x-api-key': key }
+  }
+
+  private cbRequest<T>(path: string, opts: RequestOptions = {}): Promise<T> {
+    return this.http.request<T>(path, {
+      ...opts,
+      headers: { ...this.cbAuth(), ...(opts.headers ?? {}) },
+    })
+  }
+
+  /** Create a new browser session.
+   *
+   *  Cloud (default):
+   *    ```ts
+   *    const s = await px.cloudBrowser.sessions.create()
+   *    // s.connectUrl → Prompteryx Cloud CDP. Bills cloud-browser minutes.
+   *    ```
+   *
+   *  Local — uses YOUR machine's Chrome via the Prompteryx plugin +
+   *  Electron runner. ZERO cloud-browser minutes. Requires the plugin
+   *  to be running on the same machine as the SDK consumer; the call
+   *  short-circuits to localhost and never reaches the API.
+   *    ```ts
+   *    const s = await px.cloudBrowser.sessions.create({ target: 'local' })
+   *    // s.connectUrl → http://localhost:9222 (your Chrome's debug port)
+   *    ```
+   *
+   *  When `target: 'local'` is set, cloud-only fields (recordSession,
+   *  proxy, profileId) are ignored — you're driving your own Chrome
+   *  with whatever cookies/extensions you've already installed.
+   */
+  async create(opts: CreateSessionOptions = {}): Promise<CloudSession> {
+    if (opts.target === 'local') {
+      // Local mode short-circuit. We don't hit the API at all — the
+      // session is just a thin wrapper over the user's local Chrome's
+      // CDP endpoint (managed by the Prompteryx plugin). Saves cloud
+      // minutes AND avoids a round-trip. Failure to connect is the
+      // consumer's problem at .connectOverCDP() time.
+      const localCdp = 'http://127.0.0.1:9222'
+      const localId = `local_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
+      return {
+        id: localId,
+        connectUrl: localCdp,
+        status: 'active',
+        startedAt: new Date().toISOString(),
+        recordSession: false,
+      }
+    }
+    // Wire names match the route (proxy/country), while the SDK options keep
+    // the friendlier useProxy/proxyLocation spelling.
+    return this.cbRequest<CloudSession>('/api/v1/cloud-browser/sessions', {
+      method: 'POST',
+      body: {
+        recordSession: opts.recordSession,
+        captureDownloads: opts.captureDownloads,
+        extensions: opts.extensions,
+        proxy: opts.useProxy,
+        country: opts.proxyLocation,
+        sessionTimeoutMinutes: opts.sessionTimeoutMinutes,
+        profileId: opts.profileId,
+        persistContext: opts.persistContext,
+        viewport: opts.viewport,
+        ...(opts.passthrough || {}),
+      },
+    })
+  }
+
+  /** Retrieve a session's history record (status/duration/recording flag).
+   *  Note: this is durable history, not a live handle — it has no
+   *  `connectUrl`. Keep the `create()` response for connecting. */
+  async get(sessionId: string): Promise<CloudSessionSummary> {
+    return this.cbRequest(
+      `/api/v1/cloud-browser/sessions/${encodeURIComponent(sessionId)}`,
+    )
+  }
+
+  /** List recent sessions for your account, newest first. */
+  async list(opts: { limit?: number } = {}): Promise<CloudSessionSummary[]> {
+    const res = await this.cbRequest<{ sessions: CloudSessionSummary[] }>(
+      '/api/v1/cloud-browser/sessions',
+      { query: { limit: opts.limit } },
+    )
+    return res.sessions ?? []
+  }
+
+  /** Close a session, finalising the recording (if any) + releasing the
+   *  cloud-browser slot. Idempotent. No-op for local sessions
+   *  (target: 'local') — those don't have a slot to release. */
+  async close(sessionId: string): Promise<{ ok: boolean; proxyMB?: number }> {
+    // Local sessions are pure client-side handles — nothing to release.
+    if (sessionId.startsWith('local_')) return { ok: true }
+    return this.cbRequest(
+      `/api/v1/cloud-browser/sessions/${encodeURIComponent(sessionId)}`,
+      { method: 'DELETE' },
+    )
+  }
+}
+
+export class CloudBrowserResource {
+  readonly sessions: SessionsResource
+
+  constructor(private readonly http: HttpClient) {
+    this.sessions = new SessionsResource(http)
+  }
+
+  private cbAuth(): Record<string, string> {
+    const key = this.http.cloudBrowserKey
+    if (!key) throw new AuthError(MISSING_CB_KEY_MESSAGE)
+    return { 'x-api-key': key }
+  }
+
+  /**
+   * One-shot fetch through the cloud browser. Spins up a short-lived
+   * session, loads the page in real Chromium (so JS-rendered sites work),
+   * extracts the content, and tears down. Use this when you only need ONE
+   * page and don't want to manage Playwright yourself.
+   *
+   * ```ts
+   * const page = await px.cloudBrowser.fetch({
+   *   url: 'https://example.com/pricing',
+   *   format: 'markdown',                    // 'text' (default) | 'markdown' | 'html' | 'links'
+   *   waitForSelector: '.pricing-table',     // for JS-rendered content
+   *   selectors: ['.pricing-table .plan'],   // deterministic CSS extraction
+   * })
+   * // page.content, page.extracted, page.title, page.finalUrl …
+   * ```
+   */
+  async fetch(opts: CloudFetchOptions): Promise<CloudFetchResult> {
+    return this.http.request('/api/v1/cloud-browser/fetch', {
+      method: 'POST',
+      body: opts,
+      headers: this.cbAuth(),
+      timeoutMs: Math.max(90_000, (opts.timeoutMs ?? 30_000) + 30_000),
+    })
+  }
+
+  /**
+   * Search the web through the cloud browser and get structured results
+   * (title/url/snippet). Runs the query against DuckDuckGo's server-rendered
+   * HTML endpoint in a real browser — there is no engine choice today.
+   */
+  async search(opts: {
+    query: string
+    /** Max results, 1–25. Default 10. */
+    limit?: number
+    /** Route through a residential proxy. */
+    proxy?: boolean
+    /** Proxy exit country (with `proxy: true`), e.g. 'us'. */
+    country?: string
+  }): Promise<CloudSearchResult[]> {
+    const res = await this.http.request<{ query: string; results: CloudSearchResult[] }>(
+      '/api/v1/cloud-browser/search',
+      { method: 'POST', body: opts, headers: this.cbAuth(), timeoutMs: 90_000 },
+    )
+    return res.results ?? []
+  }
+}

package/src/resources/connectHub.ts

@@ -0,0 +1,93 @@
+/**
+ * ⚠️ NOT SHIPPED in @prompteryx/sdk 0.4.0 (2026-09-03) — not exported from
+ * src/index.ts. The /api/v1/connect-hub/* routes this resource targets do
+ * not exist on the live API (every call 404s). Verified against the 31
+ * live v1 routes in docs/API_SDK_DEVELOPER_PLAN_GOLIVE_AUDIT.md. Kept as
+ * source for a future release; do not re-export without re-verifying.
+ *
+ * `px.connectHub.*` — 2,800+ integrations.
+ *
+ * Browse + run actions from any of the Pipedream-backed apps
+ * Prompteryx exposes via Connect Hub (Gmail, Sheets, Slack,
+ * Notion, Stripe, Airtable, WordPress, …). The user's connected
+ * credentials are reused server-side; the SDK never sees them.
+ *
+ * Billing: 1 Connect Hub credit per action call, plus whatever the
+ * underlying integration costs through Pipedream. The platform's
+ * monthly Connect Hub allowance + top-up balance both apply
+ * identically to API + UI surfaces.
+ */
+
+import type { HttpClient } from '../client'
+import type {
+  ConnectHubActionSummary,
+  ConnectHubAppSummary,
+  RunConnectHubActionOptions,
+} from '../types'
+
+export class ConnectHubResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /** List apps the platform supports. Cacheable client-side. */
+  async listApps(opts: { limit?: number; category?: string; search?: string } = {}): Promise<ConnectHubAppSummary[]> {
+    const res = await this.http.request<{ apps: ConnectHubAppSummary[] }>(
+      '/api/v1/connect-hub/apps',
+      { query: { limit: opts.limit, category: opts.category, q: opts.search } },
+    )
+    return res.apps ?? []
+  }
+
+  /** List the actions available on a specific app. */
+  async listActions(app: string): Promise<ConnectHubActionSummary[]> {
+    const res = await this.http.request<{ actions: ConnectHubActionSummary[] }>(
+      `/api/v1/connect-hub/apps/${encodeURIComponent(app)}/actions`,
+    )
+    return res.actions ?? []
+  }
+
+  /**
+   * Get the parameter schema for a specific action. Use this to
+   * build typed wrappers / validate inputs before calling `run`.
+   */
+  async getAction(app: string, action: string): Promise<ConnectHubActionSummary> {
+    return this.http.request(
+      `/api/v1/connect-hub/apps/${encodeURIComponent(app)}/actions/${encodeURIComponent(action)}`,
+    )
+  }
+
+  /**
+   * Execute a Connect Hub action.
+   *
+   * ```ts
+   * const sent = await px.connectHub.run({
+   *   app: 'gmail',
+   *   action: 'send_message',
+   *   params: {
+   *     to: 'hello@example.com',
+   *     subject: 'Hi from Prompteryx',
+   *     body: 'Hello!',
+   *   },
+   * })
+   * ```
+   *
+   * Returns whatever the integration returns. Throws `QuotaError` if
+   * the user's Connect Hub allowance is exhausted (same gate the UI
+   * uses).
+   */
+  async run(opts: RunConnectHubActionOptions): Promise<unknown> {
+    return this.http.request('/api/v1/connect-hub/run', {
+      method: 'POST',
+      body: opts,
+      timeoutMs: 60_000,
+    })
+  }
+
+  /** List the user's connected accounts (one per app, possibly
+   *  multiple per app for multi-account users). */
+  async listAccounts(): Promise<Array<{ id: string; app: string; label: string; addedAt: string }>> {
+    const res = await this.http.request<{ accounts: Array<{ id: string; app: string; label: string; addedAt: string }> }>(
+      '/api/v1/connect-hub/accounts',
+    )
+    return res.accounts ?? []
+  }
+}