@prompteryx/sdk 0.4.0

package/dist/index.js

@@ -0,0 +1,1258 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  AUTOPILOT_MODELS: () => AUTOPILOT_MODELS,
+  AuthError: () => AuthError,
+  DEFAULT_AUTOPILOT_MODEL: () => DEFAULT_AUTOPILOT_MODEL,
+  NetworkError: () => NetworkError,
+  NotFoundError: () => NotFoundError,
+  ParseError: () => ParseError,
+  Prompteryx: () => Prompteryx,
+  PrompteryxError: () => PrompteryxError,
+  QuotaError: () => QuotaError,
+  RateLimitError: () => RateLimitError,
+  ServerError: () => ServerError,
+  TimeoutError: () => TimeoutError,
+  ValidationError: () => ValidationError,
+  default: () => src_default
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/errors.ts
+var PrompteryxError = class extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "PrompteryxError";
+    this.status = opts.status;
+    this.code = opts.code;
+    this.requestId = opts.requestId;
+    this.raw = opts.raw;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthError = class _AuthError extends PrompteryxError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "AuthError";
+    Object.setPrototypeOf(this, _AuthError.prototype);
+  }
+};
+var QuotaError = class _QuotaError extends PrompteryxError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "QuotaError";
+    this.resources = opts.resources;
+    Object.setPrototypeOf(this, _QuotaError.prototype);
+  }
+};
+var NotFoundError = class _NotFoundError extends PrompteryxError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "NotFoundError";
+    Object.setPrototypeOf(this, _NotFoundError.prototype);
+  }
+};
+var ValidationError = class _ValidationError extends PrompteryxError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+var RateLimitError = class _RateLimitError extends PrompteryxError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "RateLimitError";
+    this.retryAfterSeconds = opts.retryAfterSeconds;
+    Object.setPrototypeOf(this, _RateLimitError.prototype);
+  }
+};
+var ServerError = class _ServerError extends PrompteryxError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "ServerError";
+    Object.setPrototypeOf(this, _ServerError.prototype);
+  }
+};
+var NetworkError = class _NetworkError extends PrompteryxError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "NetworkError";
+    Object.setPrototypeOf(this, _NetworkError.prototype);
+  }
+};
+var ParseError = class _ParseError extends PrompteryxError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "ParseError";
+    Object.setPrototypeOf(this, _ParseError.prototype);
+  }
+};
+var TimeoutError = class _TimeoutError extends PrompteryxError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "TimeoutError";
+    Object.setPrototypeOf(this, _TimeoutError.prototype);
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://prompteryx.com";
+var DEFAULT_TIMEOUT_MS = 6e4;
+var DEFAULT_MAX_RETRIES = 2;
+var HttpClient = class {
+  constructor(opts) {
+    if (!opts.apiKey) {
+      throw new PrompteryxError("apiKey is required to construct a Prompteryx client");
+    }
+    this.apiKey = opts.apiKey;
+    this.cloudBrowserKey = opts.cloudBrowserKey;
+    this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.defaultHeaders = opts.defaultHeaders ?? {};
+    const f = opts.fetch ?? globalThis.fetch;
+    if (!f) {
+      throw new PrompteryxError(
+        "No fetch implementation found. Provide options.fetch or run on a runtime with global fetch (Node 18+, browser, Cloudflare Workers)."
+      );
+    }
+    this.fetchImpl = f.bind(globalThis);
+  }
+  /** Returns the JSON-parsed body typed as T. Throws typed errors on non-2xx. */
+  async request(path, opts = {}) {
+    const res = await this.rawRequest(path, opts);
+    const text = await res.text();
+    if (!text) return void 0;
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new ParseError(`Failed to parse JSON response from ${path}`, {
+        status: res.status,
+        raw: text.slice(0, 500)
+      });
+    }
+  }
+  /** Returns the raw Response. Throws typed errors on non-2xx, but does
+   *  not attempt to read the body. Useful for downloading binaries. */
+  async rawRequest(path, opts = {}) {
+    const method = opts.method ?? "GET";
+    const url = this.buildUrl(path, opts.query);
+    const shouldRetry = opts.retry ?? method === "GET";
+    const maxAttempts = shouldRetry ? this.maxRetries + 1 : 1;
+    let lastErr;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        const res = await this.sendOnce(url, method, opts);
+        if (res.ok) return res;
+        const err = await this.errorFromResponse(res);
+        if (this.isRetryable(err) && attempt < maxAttempts - 1) {
+          await this.backoff(attempt, err);
+          lastErr = err;
+          continue;
+        }
+        throw err;
+      } catch (e) {
+        if (e instanceof PrompteryxError) throw e;
+        const wrapped = this.wrapTransport(e);
+        if (this.isRetryable(wrapped) && attempt < maxAttempts - 1) {
+          await this.backoff(attempt, wrapped);
+          lastErr = wrapped;
+          continue;
+        }
+        throw wrapped;
+      }
+    }
+    throw lastErr ?? new PrompteryxError("Unknown error after retries exhausted");
+  }
+  /**
+   * Stream a Server-Sent Events response line-by-line as JSON-parsed
+   * payloads. Yields each event's `data:` payload parsed as JSON. The
+   * caller is responsible for breaking the loop / cancelling the
+   * AbortSignal when done.
+   */
+  async *streamSse(path, opts = {}) {
+    const res = await this.rawRequest(path, {
+      ...opts,
+      headers: { ...opts.headers, Accept: "text/event-stream" }
+    });
+    if (!res.body) return;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      let idx;
+      while ((idx = buf.indexOf("\n\n")) !== -1) {
+        const raw = buf.slice(0, idx);
+        buf = buf.slice(idx + 2);
+        const dataLines = raw.split("\n").filter((l) => l.startsWith("data:")).map((l) => l.slice(5).trim());
+        if (dataLines.length === 0) continue;
+        const payload = dataLines.join("\n");
+        if (!payload) continue;
+        try {
+          yield JSON.parse(payload);
+        } catch {
+        }
+      }
+    }
+  }
+  // ── internals ────────────────────────────────────────────────────────
+  async sendOnce(url, method, opts) {
+    const timeoutMs = opts.timeoutMs ?? this.timeoutMs;
+    const ctl = new AbortController();
+    const t = setTimeout(() => ctl.abort(), timeoutMs);
+    if (opts.signal) {
+      if (opts.signal.aborted) ctl.abort();
+      else opts.signal.addEventListener("abort", () => ctl.abort(), { once: true });
+    }
+    try {
+      const headers = {
+        Authorization: `Bearer ${this.apiKey}`,
+        Accept: "application/json",
+        ...this.defaultHeaders,
+        ...opts.headers ?? {}
+      };
+      let body;
+      if (opts.body !== void 0) {
+        headers["Content-Type"] = "application/json";
+        body = JSON.stringify(opts.body);
+      }
+      return await this.fetchImpl(url, {
+        method,
+        headers,
+        body,
+        signal: ctl.signal
+      });
+    } finally {
+      clearTimeout(t);
+    }
+  }
+  buildUrl(path, query) {
+    const base = path.startsWith("http") ? path : `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+    if (!query) return base;
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+      if (v === void 0 || v === null) continue;
+      params.set(k, String(v));
+    }
+    const qs = params.toString();
+    return qs ? `${base}${base.includes("?") ? "&" : "?"}${qs}` : base;
+  }
+  async errorFromResponse(res) {
+    let parsed = null;
+    try {
+      const text = await res.text();
+      parsed = text ? JSON.parse(text) : null;
+    } catch {
+    }
+    const message = parsed?.error?.message ?? parsed?.message ?? parsed?.error ?? `Request failed with ${res.status}`;
+    const code = parsed?.error?.code ?? parsed?.code;
+    const requestId = res.headers.get("x-request-id") ?? void 0;
+    const opts = { status: res.status, code, requestId, raw: parsed };
+    switch (res.status) {
+      case 401:
+      case 403:
+        return new AuthError(message, opts);
+      case 402:
+        return new QuotaError(message, { ...opts, resources: parsed?.error?.resources ?? parsed?.resources });
+      case 404:
+        return new NotFoundError(message, opts);
+      case 422:
+        return new ValidationError(message, opts);
+      case 429: {
+        const retryAfter = parseInt(res.headers.get("retry-after") ?? "0", 10);
+        return new RateLimitError(message, { ...opts, retryAfterSeconds: Number.isFinite(retryAfter) ? retryAfter : void 0 });
+      }
+      default:
+        if (res.status >= 500) return new ServerError(message, opts);
+        return new PrompteryxError(message, opts);
+    }
+  }
+  wrapTransport(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (e instanceof Error && (e.name === "AbortError" || msg.includes("aborted"))) {
+      return new TimeoutError(`Request timed out: ${msg}`);
+    }
+    return new NetworkError(`Network error: ${msg}`);
+  }
+  isRetryable(err) {
+    if (err instanceof ServerError) return true;
+    if (err instanceof RateLimitError) return true;
+    if (err instanceof NetworkError) return true;
+    if (err instanceof TimeoutError) return true;
+    return false;
+  }
+  async backoff(attempt, err) {
+    const retryAfter = err.retryAfterSeconds;
+    if (retryAfter && retryAfter > 0) {
+      return new Promise((r) => setTimeout(r, Math.min(retryAfter, 30) * 1e3));
+    }
+    const base = 250 * Math.pow(2, attempt);
+    const jitter = Math.random() * 100;
+    return new Promise((r) => setTimeout(r, base + jitter));
+  }
+};
+
+// src/resources/autopilot.ts
+var AutopilotResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 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) {
+    if (opts.target === "local") {
+      return this.runLocal(opts);
+    }
+    if (opts.agents && opts.agents > 1) {
+      return this.runSwarm(opts);
+    }
+    return this.runAsync(opts);
+  }
+  /** The task params shared by the sync, swarm, and async request bodies. */
+  cloudTaskBody(opts) {
+    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. */
+  async runSwarm(opts) {
+    const env = await this.http.request("/api/v1/ai-browser/execute", {
+      method: "POST",
+      timeoutMs: opts.timeoutMs ?? 10 * 6e4,
+      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.
+   */
+  async runAsync(opts) {
+    const timeoutMs = opts.timeoutMs ?? 10 * 6e4;
+    const deadline = Date.now() + timeoutMs;
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    const startEnv = await this.http.request("/api/v1/ai-browser/execute", {
+      method: "POST",
+      timeoutMs: 6e4,
+      body: { ...this.cloudTaskBody(opts), mode: "start" }
+    });
+    const jobId = startEnv?.data?.jobId;
+    if (!jobId) {
+      return this.mapResult(startEnv?.data ?? startEnv);
+    }
+    let view = null;
+    while (Date.now() < deadline) {
+      const runEnv = await this.http.request("/api/v1/ai-browser/execute", {
+        method: "POST",
+        timeoutMs: 25e4,
+        retry: true,
+        body: { jobId, mode: "run", maxSteps: opts.maxSteps }
+      });
+      view = runEnv?.data ?? null;
+      if (!view || view.terminal || view.status !== "running") break;
+      await sleep(500);
+    }
+    if (view && view.status === "running") {
+      try {
+        const statusEnv = await this.http.request("/api/v1/ai-browser/execute", {
+          query: { jobId },
+          timeoutMs: 3e4
+        });
+        if (statusEnv?.data) view = statusEnv.data;
+      } catch {
+      }
+    }
+    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. */
+  mapResult(data) {
+    const d = data || {};
+    const status = d.status;
+    const success = status === "completed" || status === "max_steps_reached";
+    const steps = Array.isArray(d.steps) ? d.steps.map((s, i) => ({
+      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.
+   */
+  async runLocal(opts) {
+    const fetchImpl = globalThis.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, body) => {
+      let r;
+      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.message})`
+        );
+      }
+      if (!r.ok) {
+        let msg = `${path} failed (${r.status})`;
+        try {
+          const j = await r.json();
+          if (j?.error) msg = j.error;
+        } catch {
+        }
+        throw new Error(`[Prompteryx SDK] ${msg}`);
+      }
+      return r.json().catch(() => ({}));
+    };
+    await post("/launch-gemini-browser", {
+      sessionId,
+      profileId: opts.session?.profileId,
+      enableRecording: false
+    });
+    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?.costSaving === true,
+      costSavingMaxBatch: opts.passthrough?.costSavingMaxBatch
+    });
+    const deadline = Date.now() + (opts.timeoutMs ?? 10 * 6e4);
+    const sleep = (ms) => new Promise((res) => setTimeout(res, ms));
+    let state = 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, i) => ({
+        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) {
+    const env = await this.http.request("/api/v1/ai-browser/execute", {
+      method: "POST",
+      timeoutMs: 3e4,
+      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) {
+    if (opts.target === "local") {
+      throw new Error(
+        '[Prompteryx SDK] Streaming is cloud-only. For local Chrome use autopilot.run({ target: "local" }) \u2014 its result contains all steps.'
+      );
+    }
+    const res = await this.http.rawRequest("/api/v1/ai-browser/execute-stream", {
+      method: "POST",
+      timeoutMs: opts.timeoutMs ?? 15 * 6e4,
+      body: this.cloudTaskBody(opts),
+      signal: opts.signal
+    });
+    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();
+    }
+    const payload = text.trim();
+    let parsed;
+    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 };
+  }
+};
+
+// src/resources/cloudBrowser.ts
+var MISSING_CB_KEY_MESSAGE = "px.cloudBrowser.* uses a Cloud Browser API key (pcb_live_\u2026), which is a separate key family from the platform px_live_\u2026 key. Create one under Cloud Platform \u2192 API Keys and pass it as new Prompteryx({ apiKey, cloudBrowserKey }).";
+var SessionsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Headers for the pcb_live_ key family (throws a clear error if absent). */
+  cbAuth() {
+    const key = this.http.cloudBrowserKey;
+    if (!key) throw new AuthError(MISSING_CB_KEY_MESSAGE);
+    return { "x-api-key": key };
+  }
+  cbRequest(path, opts = {}) {
+    return this.http.request(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 = {}) {
+    if (opts.target === "local") {
+      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: (/* @__PURE__ */ new Date()).toISOString(),
+        recordSession: false
+      };
+    }
+    return this.cbRequest("/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) {
+    return this.cbRequest(
+      `/api/v1/cloud-browser/sessions/${encodeURIComponent(sessionId)}`
+    );
+  }
+  /** List recent sessions for your account, newest first. */
+  async list(opts = {}) {
+    const res = await this.cbRequest(
+      "/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) {
+    if (sessionId.startsWith("local_")) return { ok: true };
+    return this.cbRequest(
+      `/api/v1/cloud-browser/sessions/${encodeURIComponent(sessionId)}`,
+      { method: "DELETE" }
+    );
+  }
+};
+var CloudBrowserResource = class {
+  constructor(http) {
+    this.http = http;
+    this.sessions = new SessionsResource(http);
+  }
+  cbAuth() {
+    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) {
+    return this.http.request("/api/v1/cloud-browser/fetch", {
+      method: "POST",
+      body: opts,
+      headers: this.cbAuth(),
+      timeoutMs: Math.max(9e4, (opts.timeoutMs ?? 3e4) + 3e4)
+    });
+  }
+  /**
+   * 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) {
+    const res = await this.http.request(
+      "/api/v1/cloud-browser/search",
+      { method: "POST", body: opts, headers: this.cbAuth(), timeoutMs: 9e4 }
+    );
+    return res.results ?? [];
+  }
+};
+
+// src/resources/executions.ts
+var TERMINAL_STATES = [
+  "completed",
+  "failed",
+  "cancelled",
+  "timed_out"
+];
+var ExecutionsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Get current execution record. */
+  async get(executionId) {
+    return this.http.request(`/api/v1/executions/${encodeURIComponent(executionId)}`);
+  }
+  /**
+   * 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.
+   */
+  async wait(executionId, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 5 * 6e4;
+    const pollIntervalMs = opts.pollIntervalMs ?? 2e3;
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      if (opts.signal?.aborted) throw new TimeoutError(`Wait cancelled for ${executionId}`);
+      const exec = await this.get(executionId);
+      if (TERMINAL_STATES.includes(exec.status)) return exec;
+      if (Date.now() > deadline) {
+        throw new TimeoutError(`Execution ${executionId} did not finish within ${timeoutMs}ms`);
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+  }
+  /**
+   * Get the logs for a finished (or in-progress) execution as a one-shot
+   * fetch. For real-time streaming use `stream(executionId)` instead.
+   */
+  async logs(executionId) {
+    const res = await this.http.request(
+      `/api/v1/executions/${encodeURIComponent(executionId)}/logs`
+    );
+    return res.logs ?? [];
+  }
+  /**
+   * 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
+   *   }
+   */
+  async *stream(executionId, opts = {}) {
+    yield* this.http.streamSse(
+      `/api/v1/executions/${encodeURIComponent(executionId)}/logs/stream`,
+      { signal: opts.signal }
+    );
+  }
+  /** Get a single node's output from a finished execution. */
+  async getNodeOutput(executionId, nodeId) {
+    return this.http.request(
+      `/api/v1/executions/${encodeURIComponent(executionId)}/nodes/${encodeURIComponent(nodeId)}/output`
+    );
+  }
+};
+
+// src/resources/profiles.ts
+var ProfilesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  async list(opts = {}) {
+    const res = await this.http.request(
+      "/api/v1/profiles",
+      { query: { kind: opts.kind } }
+    );
+    return res.profiles ?? [];
+  }
+  async get(profileId) {
+    return this.http.request(`/api/v1/profiles/${encodeURIComponent(profileId)}`);
+  }
+  /** Create a new CLOUD profile. Local profiles are managed by the
+   *  plugin and cannot be created via the API. */
+  async create(opts) {
+    return this.http.request("/api/v1/profiles", {
+      method: "POST",
+      body: { name: opts.name, kind: "cloud" }
+    });
+  }
+  async delete(profileId) {
+    return this.http.request(`/api/v1/profiles/${encodeURIComponent(profileId)}`, {
+      method: "DELETE"
+    });
+  }
+};
+
+// src/resources/schedules.ts
+var SchedulesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  async list(opts = {}) {
+    const res = await this.http.request(
+      "/api/v1/schedules",
+      { query: { active: opts.active, workflowId: opts.workflowId } }
+    );
+    return res.schedules ?? [];
+  }
+  async get(scheduleId) {
+    return this.http.request(`/api/v1/schedules/${encodeURIComponent(scheduleId)}`);
+  }
+  /** Create a new schedule. Returns the created record. */
+  async create(opts) {
+    return this.http.request("/api/v1/schedules", {
+      method: "POST",
+      body: opts
+    });
+  }
+  /** Pause / resume / change cron / timezone. */
+  async update(scheduleId, patch) {
+    return this.http.request(`/api/v1/schedules/${encodeURIComponent(scheduleId)}`, {
+      method: "PATCH",
+      body: patch
+    });
+  }
+  async delete(scheduleId) {
+    return this.http.request(`/api/v1/schedules/${encodeURIComponent(scheduleId)}`, {
+      method: "DELETE"
+    });
+  }
+};
+
+// src/resources/subscription.ts
+var SubscriptionResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Get the current plan + balances + usage. */
+  async get() {
+    return this.http.request("/api/v1/subscription");
+  }
+  // NOT SHIPPED (2026-09-03, v0.4.0): usage() was removed — the route it
+  // targeted (/api/v1/subscription/usage) does not exist on the live API
+  // (the only usage route is /api/v1/usage, with a different shape).
+  // Re-add once a real time-series endpoint ships.
+};
+
+// src/resources/workflows.ts
+var WorkflowsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  async list(opts = {}) {
+    const res = await this.http.request(
+      "/api/v1/workflows",
+      { query: { limit: opts.limit, q: opts.search, tag: opts.tag } }
+    );
+    return res.workflows ?? [];
+  }
+  async get(workflowId) {
+    return this.http.request(`/api/v1/workflows/${encodeURIComponent(workflowId)}`);
+  }
+  /**
+   * 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.
+   */
+  async run(workflowId, opts = {}) {
+    return this.http.request(
+      `/api/v1/workflows/${encodeURIComponent(workflowId)}/execute`,
+      {
+        method: "POST",
+        body: {
+          variables: opts.input,
+          executionOptions: opts.execution
+        }
+      }
+    );
+  }
+  /**
+   * Run + block. Returns the final ExecutionRecord. Throws
+   * `TimeoutError` if the run takes longer than `timeoutMs`
+   * (default 5 minutes).
+   */
+  async runAndWait(workflowId, opts = {}) {
+    const started = await this.run(workflowId, opts);
+    return this.waitInternal(started.executionId, opts.timeoutMs ?? 5 * 6e4, opts.pollIntervalMs ?? 2e3);
+  }
+  async waitInternal(executionId, timeoutMs, pollIntervalMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const exec = await this.http.request(
+        `/api/v1/executions/${encodeURIComponent(executionId)}`
+      );
+      if (["completed", "failed", "cancelled", "timed_out"].includes(exec.status)) return exec;
+      if (Date.now() > deadline) {
+        throw new TimeoutError(`Execution ${executionId} did not finish within ${timeoutMs}ms`);
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+  }
+};
+
+// src/page.ts
+var CopilotHelpers = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Execute a single natural-language action against the page.
+   *
+   * ```ts
+   * await px.copilot.do(page, 'click the Sign up button')
+   * await px.copilot.do(page, 'fill the email field with hello@example.com')
+   * ```
+   *
+   * Internally: snapshot the page → POST `/api/v1/copilot/do` → server
+   * returns a structured action plan (ranked selector + alternatives +
+   * value + a normalised vision point) → SDK executes locally, trying the
+   * ranked selectors in order, and ONLY if every selector fails, falling
+   * back to an AI-vision coordinate click. Costs 1 AI Credit per call.
+   *
+   * This is the key resilience advantage over a pure-LLM `act()`: the cheap,
+   * deterministic ranked selectors are tried first (no flakiness, no re-asking
+   * the model); the vision fallback is a safety net, not the default path. Pass
+   * `{ visionFallback: false }` to disable the fallback (selectors-only).
+   */
+  async do(page, instruction, opts = {}) {
+    const start = Date.now();
+    const snapshot = await this.snapshotPage(page);
+    const plan = await this.http.request("/api/v1/copilot/do", {
+      method: "POST",
+      body: { instruction, snapshot },
+      timeoutMs: 45e3
+    });
+    const allowVision = opts.visionFallback !== false;
+    try {
+      const usedVisionFallback = await this.runAction(page, plan, opts.timeout ?? 15e3, allowVision);
+      return {
+        success: true,
+        action: plan.description,
+        selector: plan.selector,
+        usedVisionFallback,
+        durationMs: Date.now() - start
+      };
+    } catch (err) {
+      return {
+        success: false,
+        action: plan.description,
+        selector: plan.selector,
+        durationMs: Date.now() - start,
+        error: err instanceof Error ? err.message : String(err)
+      };
+    }
+  }
+  /**
+   * Pull typed structured data from the page conforming to a schema.
+   *
+   * ```ts
+   * import { z } from 'zod'
+   * const product = await px.copilot.read(page, z.object({
+   *   name: z.string(),
+   *   pricePerMonth: z.number(),
+   *   features: z.array(z.string()),
+   * }))
+   * // product is fully typed; ValidationError is thrown if the model
+   * // returns data that doesn't match the schema.
+   * ```
+   *
+   * Accepts a Zod schema (preferred — gives you compile-time types)
+   * OR a raw JSON Schema via `{ jsonSchema: ... }` if you don't want
+   * a `zod` peer dep.
+   */
+  async read(page, schema) {
+    const snapshot = await this.snapshotPage(page);
+    const jsonSchema = "jsonSchema" in schema ? schema.jsonSchema : this.zodToJsonSchema(schema);
+    const raw = await this.http.request(
+      "/api/v1/copilot/read",
+      { method: "POST", body: { snapshot, jsonSchema }, timeoutMs: 6e4 }
+    );
+    if ("parse" in schema && typeof schema.parse === "function") {
+      try {
+        return schema.parse(raw.data);
+      } catch (e) {
+        throw new ValidationError(
+          `Extracted data didn't match the schema: ${e instanceof Error ? e.message : String(e)}`,
+          { raw: raw.data }
+        );
+      }
+    }
+    return raw.data;
+  }
+  /**
+   * Scan the page for available actions. Returns a ranked list of
+   * actions a user / agent could take next, with selectors + multi-
+   * option fallbacks + human-readable descriptions.
+   *
+   * Useful as a pre-step to `do()` for resilient automations:
+   *   const actions = await px.copilot.scan(page, 'sign up flow')
+   *   const target = actions.find(a => a.description.includes('Sign up'))
+   *   if (target) await px.copilot.do(page, target.example ?? `click ${target.description}`)
+   */
+  async scan(page, hint) {
+    const snapshot = await this.snapshotPage(page);
+    const res = await this.http.request(
+      "/api/v1/copilot/scan",
+      { method: "POST", body: { snapshot, hint }, timeoutMs: 45e3 }
+    );
+    return res.actions ?? [];
+  }
+  // ── internals ────────────────────────────────────────────────────────
+  async snapshotPage(page) {
+    const buf = await page.screenshot({ type: "jpeg", quality: 60, fullPage: false });
+    const screenshot = bufferToBase64(buf);
+    return {
+      url: page.url(),
+      title: await page.title().catch(() => ""),
+      screenshot
+    };
+  }
+  /** Execute the plan. Returns true if the AI-vision fallback was used. */
+  async runAction(page, plan, timeout, allowVision) {
+    if (plan.type === "press_key" && plan.value) {
+      await page.keyboard.press(plan.value);
+      return false;
+    }
+    if (plan.type === "goto" && plan.url) {
+      await page.goto(plan.url, { timeout });
+      return false;
+    }
+    const candidates = [plan.selector, ...plan.alternativeSelectors ?? []].filter(
+      (s) => typeof s === "string" && s.length > 0
+    );
+    let lastErr;
+    for (const sel of candidates) {
+      try {
+        switch (plan.type) {
+          case "click":
+            await page.click(sel, { timeout });
+            return false;
+          case "fill":
+            await page.fill(sel, plan.value ?? "", { timeout });
+            return false;
+          case "select":
+            await page.selectOption(sel, plan.value ?? "", { timeout });
+            return false;
+          case "hover":
+            await page.hover(sel, { timeout });
+            return false;
+          default:
+            throw new Error(`Unsupported action type: ${plan.type}`);
+        }
+      } catch (e) {
+        lastErr = e;
+      }
+    }
+    if (allowVision && plan.point && plan.type !== "select" && page.mouse) {
+      const vp = page.viewportSize?.() || { width: 1280, height: 800 };
+      const x = Math.round(plan.point.x / 1e3 * vp.width);
+      const y = Math.round(plan.point.y / 1e3 * vp.height);
+      await page.mouse.click(x, y);
+      if (plan.type === "fill" && plan.value) await page.keyboard.type(plan.value, { delay: 20 });
+      if (plan.type === "hover" && page.mouse.move) await page.mouse.move(x, y);
+      return true;
+    }
+    if (candidates.length === 0) throw new Error(`No selector or vision point returned for action ${plan.type}`);
+    throw lastErr ?? new Error(`No selector worked for ${plan.type} (and vision fallback unavailable)`);
+  }
+  zodToJsonSchema(schema) {
+    return { type: "object", _zodHint: String(schema) };
+  }
+};
+function bufferToBase64(buf) {
+  if (typeof Buffer !== "undefined" && buf instanceof Buffer) {
+    return buf.toString("base64");
+  }
+  let binary = "";
+  const bytes = buf;
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  const g = globalThis;
+  return g.btoa ? g.btoa(binary) : Buffer.from(binary, "binary").toString("base64");
+}
+
+// src/models.ts
+var 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"
+];
+var DEFAULT_AUTOPILOT_MODEL = "gemini-3.5-flash";
+
+// src/index.ts
+var Copilot = class {
+  constructor(helpers) {
+    this.helpers = helpers;
+  }
+  /** Execute a natural-language action on a connected Playwright page. */
+  do(page, instruction, opts) {
+    return this.helpers.do(page, instruction, opts);
+  }
+  /** Pull typed data from the page (Zod schema or raw JSON Schema). */
+  read(page, schema) {
+    return this.helpers.read(page, schema);
+  }
+  /** Discover available actions on the page; useful pre-`do` step. */
+  scan(page, hint) {
+    return this.helpers.scan(page, hint);
+  }
+};
+var Prompteryx = class {
+  constructor(opts) {
+    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);
+  }
+};
+var src_default = Prompteryx;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AUTOPILOT_MODELS,
+  AuthError,
+  DEFAULT_AUTOPILOT_MODEL,
+  NetworkError,
+  NotFoundError,
+  ParseError,
+  Prompteryx,
+  PrompteryxError,
+  QuotaError,
+  RateLimitError,
+  ServerError,
+  TimeoutError,
+  ValidationError
+});
+//# sourceMappingURL=index.js.map