@prompteryx/sdk 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,541 @@
+import { H as HttpClient, A as AutopilotRunOptions, a as AutopilotRunResult, b as AutopilotStep, C as CreateSessionOptions, c as CloudSession, d as CloudSessionSummary, e as CloudFetchOptions, f as CloudFetchResult, g as CloudSearchResult, E as ExecutionRecord, h as ExecutionLogEvent, P as ProfileSummary, S as ScheduleSummary, i as CreateScheduleOptions, j as SubscriptionStatus, W as WorkflowSummary, R as RunWorkflowOptions, k as RunWorkflowResult, l as CopilotHelpers, m as PageLike, n as CopilotDoResult, D as DiscoveredAction, o as PrompteryxClientOptions } from './page-8LsjwpEo.js';
+export { p as AUTOPILOT_MODELS, q as ApiKeySummary, r as AutopilotModel, s as AutopilotModelId, t as ConnectHubActionSummary, u as ConnectHubAppSummary, v as CustomNodeSummary, w as DEFAULT_AUTOPILOT_MODEL, x as ExecutionStatus, y as ExecutionTarget, z as ProxyLocation, B as Region, F as RunConnectHubActionOptions, G as SessionRecording, T as TemplateSummary, I as WorkflowExecutionOptions } from './page-8LsjwpEo.js';
+
+/**
+ * `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.
+ */
+
+declare class AutopilotResource {
+    private readonly http;
+    constructor(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)
+     * }
+     * ```
+     */
+    run(opts: AutopilotRunOptions): Promise<AutopilotRunResult>;
+    /** The task params shared by the sync, swarm, and async request bodies. */
+    private cloudTaskBody;
+    /** Multi-agent swarm — one synchronous request; the server merges all lanes. */
+    private runSwarm;
+    /**
+     * 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 runAsync;
+    /** 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;
+    /**
+     * 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 runLocal;
+    /**
+     * 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)
+     * ```
+     */
+    stop(jobId: string): Promise<{
+        jobId: string;
+        stopRequested: boolean;
+        status?: string;
+    }>;
+    /**
+     * 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.
+     */
+    stream(opts: AutopilotRunOptions & {
+        signal?: AbortSignal;
+    }): AsyncGenerator<AutopilotStep, void, void>;
+}
+
+/**
+ * `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.
+ */
+
+/** Sub-resource: cloud browser sessions. */
+declare class SessionsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Headers for the pcb_live_ key family (throws a clear error if absent). */
+    private cbAuth;
+    private cbRequest;
+    /** 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.
+     */
+    create(opts?: CreateSessionOptions): Promise<CloudSession>;
+    /** 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. */
+    get(sessionId: string): Promise<CloudSessionSummary>;
+    /** List recent sessions for your account, newest first. */
+    list(opts?: {
+        limit?: number;
+    }): Promise<CloudSessionSummary[]>;
+    /** 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. */
+    close(sessionId: string): Promise<{
+        ok: boolean;
+        proxyMB?: number;
+    }>;
+}
+declare class CloudBrowserResource {
+    private readonly http;
+    readonly sessions: SessionsResource;
+    constructor(http: HttpClient);
+    private cbAuth;
+    /**
+     * 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 …
+     * ```
+     */
+    fetch(opts: CloudFetchOptions): Promise<CloudFetchResult>;
+    /**
+     * 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.
+     */
+    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[]>;
+}
+
+/**
+ * `px.executions.*` — status, logs (polled OR streamed), wait.
+ */
+
+declare class ExecutionsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Get current execution record. */
+    get(executionId: string): Promise<ExecutionRecord>;
+    /**
+     * Block until the execution reaches a terminal state. Polls every
+     * `pollIntervalMs` (default 2s) until it's `completed`/`failed`/
+     * `cancelled`/`timed_out`, OR until `timeoutMs` elapses (default 5min).
+     *
+     * Throws `TimeoutError` on timeout; otherwise returns the final record.
+     */
+    wait(executionId: string, opts?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+        signal?: AbortSignal;
+    }): Promise<ExecutionRecord>;
+    /**
+     * Get the logs for a finished (or in-progress) execution as a one-shot
+     * fetch. For real-time streaming use `stream(executionId)` instead.
+     */
+    logs(executionId: string): Promise<ExecutionLogEvent[]>;
+    /**
+     * Stream log events as they arrive. Async iterable:
+     *
+     *   for await (const ev of px.executions.stream(execId)) {
+     *     console.log(ev.message)
+     *     if (ev.type === 'done') break
+     *   }
+     */
+    stream(executionId: string, opts?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<ExecutionLogEvent, void, void>;
+    /** Get a single node's output from a finished execution. */
+    getNodeOutput(executionId: string, nodeId: string): Promise<unknown>;
+}
+
+/**
+ * `px.profiles.*` — Chrome profile management.
+ *
+ * Profiles are persistent browser identities — they store cookies,
+ * local storage, extensions, and login state across sessions. Two
+ * kinds:
+ *   • `cloud` — lives on the Prompteryx cloud browser infrastructure.
+ *     Accessible from any device, but starts logged out (you have to
+ *     log in once after creating).
+ *   • `local` — runs on the user's own Chrome via the Prompteryx
+ *     plugin. Reuses whatever Chrome profile the user is already
+ *     signed into (Gmail, banking, internal SSO). Cloud-only
+ *     workloads can't access this.
+ */
+
+declare class ProfilesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(opts?: {
+        kind?: 'cloud' | 'local';
+    }): Promise<ProfileSummary[]>;
+    get(profileId: string): Promise<ProfileSummary>;
+    /** Create a new CLOUD profile. Local profiles are managed by the
+     *  plugin and cannot be created via the API. */
+    create(opts: {
+        name: string;
+    }): Promise<ProfileSummary>;
+    delete(profileId: string): Promise<{
+        ok: true;
+    }>;
+}
+
+/**
+ * `px.schedules.*` — server-side workflow scheduling.
+ *
+ * Set a workflow to run on cron / interval; the platform's Cloud
+ * Scheduler will fire it on schedule even when no client is connected.
+ * Wraps the same scheduling primitive the Visual Studio "Active"
+ * toggle uses.
+ */
+
+declare class SchedulesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(opts?: {
+        active?: boolean;
+        workflowId?: string;
+    }): Promise<ScheduleSummary[]>;
+    get(scheduleId: string): Promise<ScheduleSummary>;
+    /** Create a new schedule. Returns the created record. */
+    create(opts: CreateScheduleOptions): Promise<ScheduleSummary>;
+    /** Pause / resume / change cron / timezone. */
+    update(scheduleId: string, patch: Partial<CreateScheduleOptions> & {
+        active?: boolean;
+    }): Promise<ScheduleSummary>;
+    delete(scheduleId: string): Promise<{
+        ok: true;
+    }>;
+}
+
+/**
+ * `px.subscription.*` — plan + balance + usage telemetry.
+ *
+ * Programmatic access to the same numbers the in-app `/subscription`
+ * and `/cloud-platform/plans` pages display. Use this to:
+ *   • Check the user's remaining AI Credits before kicking off a
+ *     long workflow.
+ *   • Read monthly execution counts for your own dashboards.
+ *   • Detect a plan downgrade and react in your code.
+ */
+
+declare class SubscriptionResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Get the current plan + balances + usage. */
+    get(): Promise<SubscriptionStatus>;
+}
+
+/**
+ * `px.workflows.*` — Visual Studio workflows.
+ *
+ * Trigger workflows you (or anyone you share with) built in Visual
+ * Studio. Workflows are first-class platform objects: they have
+ * permanent IDs, can be scheduled, shared, templated, and edited
+ * visually. Triggering one via the SDK is fully equivalent to
+ * pressing Run in the UI — same runtime, same node executor, same
+ * billing path.
+ */
+
+declare class WorkflowsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(opts?: {
+        limit?: number;
+        search?: string;
+        tag?: string;
+    }): Promise<WorkflowSummary[]>;
+    get(workflowId: string): Promise<WorkflowSummary & {
+        nodes?: unknown[];
+    }>;
+    /**
+     * Trigger a workflow. Returns immediately with `executionId`. Use
+     * `px.executions.wait(id)` to block until completion or
+     * `px.executions.stream(id)` to follow log events live.
+     *
+     * The `execution` options override the workflow's saved settings
+     * for this one run — you don't have to edit the workflow in VS to
+     * change the proxy, region, profile, etc.
+     */
+    run(workflowId: string, opts?: RunWorkflowOptions): Promise<RunWorkflowResult>;
+    /**
+     * Run + block. Returns the final ExecutionRecord. Throws
+     * `TimeoutError` if the run takes longer than `timeoutMs`
+     * (default 5 minutes).
+     */
+    runAndWait(workflowId: string, opts?: RunWorkflowOptions & {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<ExecutionRecord>;
+    private waitInternal;
+}
+
+/**
+ * Typed error hierarchy for the Prompteryx SDK.
+ *
+ * Every error from the SDK is an instance of `PrompteryxError`. Subclass
+ * by HTTP status family so callers can `if (err instanceof QuotaError)`
+ * without parsing strings. Network/parse errors get their own classes
+ * too so retries can fork on category.
+ */
+/** Base class — every SDK error inherits from this. */
+declare class PrompteryxError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    readonly requestId?: string;
+    readonly raw?: unknown;
+    constructor(message: string, opts?: {
+        status?: number;
+        code?: string;
+        requestId?: string;
+        raw?: unknown;
+    });
+}
+/** 401 / 403 — bad or revoked API key, or insufficient scope. */
+declare class AuthError extends PrompteryxError {
+    constructor(message: string, opts?: ConstructorParameters<typeof PrompteryxError>[1]);
+}
+/** 402 — plan allowance exhausted (AI Credits, cloud minutes, etc.). */
+declare class QuotaError extends PrompteryxError {
+    /** Which resources are exhausted, when known. */
+    readonly resources?: string[];
+    constructor(message: string, opts?: ConstructorParameters<typeof PrompteryxError>[1] & {
+        resources?: string[];
+    });
+}
+/** 404 — resource doesn't exist (workflow id, execution id, session id). */
+declare class NotFoundError extends PrompteryxError {
+    constructor(message: string, opts?: ConstructorParameters<typeof PrompteryxError>[1]);
+}
+/** 422 — request body shape was wrong. */
+declare class ValidationError extends PrompteryxError {
+    constructor(message: string, opts?: ConstructorParameters<typeof PrompteryxError>[1]);
+}
+/** 429 — rate-limited. Caller can retry after `retryAfterSeconds`. */
+declare class RateLimitError extends PrompteryxError {
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, opts?: ConstructorParameters<typeof PrompteryxError>[1] & {
+        retryAfterSeconds?: number;
+    });
+}
+/** 5xx — server-side failure. SDK retries these by default for idempotent ops. */
+declare class ServerError extends PrompteryxError {
+    constructor(message: string, opts?: ConstructorParameters<typeof PrompteryxError>[1]);
+}
+/** Network / DNS / socket / aborted — never reached the server. */
+declare class NetworkError extends PrompteryxError {
+    constructor(message: string, opts?: ConstructorParameters<typeof PrompteryxError>[1]);
+}
+/** Response body parse failure (server returned a non-JSON 500 page, etc.). */
+declare class ParseError extends PrompteryxError {
+    constructor(message: string, opts?: ConstructorParameters<typeof PrompteryxError>[1]);
+}
+/** Timed-out waiting for a long-running op (execution polling, agent run). */
+declare class TimeoutError extends PrompteryxError {
+    constructor(message: string, opts?: ConstructorParameters<typeof PrompteryxError>[1]);
+}
+
+/**
+ * @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.
+ */
+
+/**
+ * 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.
+ */
+declare class Copilot {
+    private readonly helpers;
+    constructor(helpers: CopilotHelpers);
+    /** Execute a natural-language action on a connected Playwright page. */
+    do(page: PageLike, instruction: string, opts?: {
+        timeout?: number;
+    }): Promise<CopilotDoResult>;
+    /** 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>;
+    /** Discover available actions on the page; useful pre-`do` step. */
+    scan(page: PageLike, hint?: string): Promise<DiscoveredAction[]>;
+}
+declare class Prompteryx {
+    private readonly http;
+    readonly workflows: WorkflowsResource;
+    readonly executions: ExecutionsResource;
+    readonly cloudBrowser: CloudBrowserResource;
+    readonly autopilot: AutopilotResource;
+    readonly copilot: Copilot;
+    readonly schedules: SchedulesResource;
+    readonly profiles: ProfilesResource;
+    readonly subscription: SubscriptionResource;
+    constructor(opts: PrompteryxClientOptions);
+}
+
+export { AuthError, AutopilotRunOptions, AutopilotRunResult, AutopilotStep, CloudFetchOptions, CloudFetchResult, CloudSearchResult, CloudSession, CloudSessionSummary, CopilotDoResult, CreateScheduleOptions, CreateSessionOptions, DiscoveredAction, ExecutionLogEvent, ExecutionRecord, NetworkError, NotFoundError, PageLike, ParseError, ProfileSummary, Prompteryx, PrompteryxClientOptions, PrompteryxError, QuotaError, RateLimitError, RunWorkflowOptions, RunWorkflowResult, ScheduleSummary, ServerError, SubscriptionStatus, TimeoutError, ValidationError, WorkflowSummary, Prompteryx as default };