@prompteryx/sdk 0.4.0

package/dist/page.d.mts

@@ -0,0 +1 @@
+export { l as CopilotHelpers, m as PageLike } from './page-8LsjwpEo.mjs';

package/dist/page.d.ts

@@ -0,0 +1 @@
+export { l as CopilotHelpers, m as PageLike } from './page-8LsjwpEo.js';

package/dist/page.js

@@ -0,0 +1,230 @@
+"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/page.ts
+var page_exports = {};
+__export(page_exports, {
+  CopilotHelpers: () => CopilotHelpers
+});
+module.exports = __toCommonJS(page_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 ValidationError = class _ValidationError extends PrompteryxError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+
+// 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");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CopilotHelpers
+});
+//# sourceMappingURL=page.js.map

package/dist/page.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/page.ts","../src/errors.ts"],"sourcesContent":["/**\r\n * Copilot primitives — `do`, `read`, `scan` — operating on a Playwright\r\n * page.\r\n *\r\n * Two namespaces in the Prompteryx SDK:\r\n *   • Copilot  → SDK helps with ONE step you describe in plain English.\r\n *                Your code drives Playwright; copilot just figures out\r\n *                which selector to click / what data to pull / what's\r\n *                discoverable on the current page.\r\n *   • Autopilot → SDK runs an autonomous multi-step task with no per-\r\n *                 action involvement from you. See ./resources/autopilot.ts.\r\n *\r\n * The copilot primitives:\r\n *   • `do(page, instruction)` — execute a single natural-language\r\n *     action (\"click the Sign up button\", \"fill the email field with\r\n *     hello@example.com\"). Returns a structured result describing\r\n *     what was done.\r\n *   • `read(page, schema)` — pull typed data from the page. Pass a\r\n *     Zod schema or a raw JSON Schema; the SDK returns the populated\r\n *     object validated against your schema.\r\n *   • `scan(page, hint?)` — list discoverable actions on the page.\r\n *     Useful as a pre-step to `do()` for resilient automations:\r\n *     scan → pick the action whose description matches your intent →\r\n *     do() against it.\r\n *\r\n * Architecturally the SDK never drives the browser server-side. The\r\n * server returns a structured plan and the SDK executes it locally\r\n * against your Playwright page, so your trace, debugger, and any\r\n * custom event handlers continue to work normally.\r\n */\r\n\r\nimport type { HttpClient } from './client'\r\nimport { ValidationError } from './errors'\r\nimport type { CopilotDoResult, DiscoveredAction } from './types'\r\n\r\n/** Minimal Page surface — anything satisfying this works (Playwright's\r\n *  Page does, by structural typing, without an explicit import). */\r\nexport interface PageLike {\r\n  url(): string\r\n  title(): Promise<string>\r\n  screenshot(opts?: { type?: 'png' | 'jpeg'; quality?: number; fullPage?: boolean }): Promise<Buffer | Uint8Array>\r\n  evaluate<T>(fn: (...args: unknown[]) => T): Promise<T>\r\n  click(selector: string, opts?: { timeout?: number }): Promise<void>\r\n  fill(selector: string, value: string, opts?: { timeout?: number }): Promise<void>\r\n  selectOption(selector: string, value: string | string[], opts?: { timeout?: number }): Promise<unknown>\r\n  goto(url: string, opts?: { timeout?: number }): Promise<unknown>\r\n  hover(selector: string, opts?: { timeout?: number }): Promise<void>\r\n  keyboard: { press(key: string): Promise<void>; type(text: string, opts?: { delay?: number }): Promise<void> }\r\n  // Used by the AI-vision fallback (when all ranked selectors fail). Playwright's\r\n  // Page provides both; optional so a minimal page can still satisfy PageLike.\r\n  mouse?: { click(x: number, y: number): Promise<void>; move?(x: number, y: number): Promise<void> }\r\n  viewportSize?(): { width: number; height: number } | null\r\n  locator(selector: string): {\r\n    first(): { isVisible(opts?: { timeout?: number }): Promise<boolean>; textContent(opts?: { timeout?: number }): Promise<string | null> }\r\n  }\r\n}\r\n\r\ninterface ZodLikeSchema<T> {\r\n  parse(input: unknown): T\r\n  _def?: unknown\r\n}\r\n\r\nexport class CopilotHelpers {\r\n  constructor(private readonly http: HttpClient) {}\r\n\r\n  /**\r\n   * Execute a single natural-language action against the page.\r\n   *\r\n   * ```ts\r\n   * await px.copilot.do(page, 'click the Sign up button')\r\n   * await px.copilot.do(page, 'fill the email field with hello@example.com')\r\n   * ```\r\n   *\r\n   * Internally: snapshot the page → POST `/api/v1/copilot/do` → server\r\n   * returns a structured action plan (ranked selector + alternatives +\r\n   * value + a normalised vision point) → SDK executes locally, trying the\r\n   * ranked selectors in order, and ONLY if every selector fails, falling\r\n   * back to an AI-vision coordinate click. Costs 1 AI Credit per call.\r\n   *\r\n   * This is the key resilience advantage over a pure-LLM `act()`: the cheap,\r\n   * deterministic ranked selectors are tried first (no flakiness, no re-asking\r\n   * the model); the vision fallback is a safety net, not the default path. Pass\r\n   * `{ visionFallback: false }` to disable the fallback (selectors-only).\r\n   */\r\n  async do(page: PageLike, instruction: string, opts: { timeout?: number; visionFallback?: boolean } = {}): Promise<CopilotDoResult> {\r\n    const start = Date.now()\r\n    const snapshot = await this.snapshotPage(page)\r\n    const plan = await this.http.request<{\r\n      type: 'click' | 'fill' | 'select' | 'hover' | 'press_key' | 'goto'\r\n      selector?: string\r\n      alternativeSelectors?: string[]\r\n      point?: { x: number; y: number }\r\n      value?: string\r\n      url?: string\r\n      description: string\r\n    }>('/api/v1/copilot/do', {\r\n      method: 'POST',\r\n      body: { instruction, snapshot },\r\n      timeoutMs: 45_000,\r\n    })\r\n    const allowVision = opts.visionFallback !== false\r\n    try {\r\n      const usedVisionFallback = await this.runAction(page, plan, opts.timeout ?? 15_000, allowVision)\r\n      return {\r\n        success: true,\r\n        action: plan.description,\r\n        selector: plan.selector,\r\n        usedVisionFallback,\r\n        durationMs: Date.now() - start,\r\n      }\r\n    } catch (err) {\r\n      return {\r\n        success: false,\r\n        action: plan.description,\r\n        selector: plan.selector,\r\n        durationMs: Date.now() - start,\r\n        error: err instanceof Error ? err.message : String(err),\r\n      }\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Pull typed structured data from the page conforming to a schema.\r\n   *\r\n   * ```ts\r\n   * import { z } from 'zod'\r\n   * const product = await px.copilot.read(page, z.object({\r\n   *   name: z.string(),\r\n   *   pricePerMonth: z.number(),\r\n   *   features: z.array(z.string()),\r\n   * }))\r\n   * // product is fully typed; ValidationError is thrown if the model\r\n   * // returns data that doesn't match the schema.\r\n   * ```\r\n   *\r\n   * Accepts a Zod schema (preferred — gives you compile-time types)\r\n   * OR a raw JSON Schema via `{ jsonSchema: ... }` if you don't want\r\n   * a `zod` peer dep.\r\n   */\r\n  async read<T>(page: PageLike, schema: ZodLikeSchema<T> | { jsonSchema: unknown }): Promise<T> {\r\n    const snapshot = await this.snapshotPage(page)\r\n    const jsonSchema = 'jsonSchema' in schema\r\n      ? (schema as { jsonSchema: unknown }).jsonSchema\r\n      : this.zodToJsonSchema(schema as ZodLikeSchema<T>)\r\n    const raw = await this.http.request<{ data: unknown }>(\r\n      '/api/v1/copilot/read',\r\n      { method: 'POST', body: { snapshot, jsonSchema }, timeoutMs: 60_000 },\r\n    )\r\n    if ('parse' in (schema as object) && typeof (schema as ZodLikeSchema<T>).parse === 'function') {\r\n      try {\r\n        return (schema as ZodLikeSchema<T>).parse(raw.data)\r\n      } catch (e) {\r\n        throw new ValidationError(\r\n          `Extracted data didn't match the schema: ${e instanceof Error ? e.message : String(e)}`,\r\n          { raw: raw.data },\r\n        )\r\n      }\r\n    }\r\n    return raw.data as T\r\n  }\r\n\r\n  /**\r\n   * Scan the page for available actions. Returns a ranked list of\r\n   * actions a user / agent could take next, with selectors + multi-\r\n   * option fallbacks + human-readable descriptions.\r\n   *\r\n   * Useful as a pre-step to `do()` for resilient automations:\r\n   *   const actions = await px.copilot.scan(page, 'sign up flow')\r\n   *   const target = actions.find(a => a.description.includes('Sign up'))\r\n   *   if (target) await px.copilot.do(page, target.example ?? `click ${target.description}`)\r\n   */\r\n  async scan(page: PageLike, hint?: string): Promise<DiscoveredAction[]> {\r\n    const snapshot = await this.snapshotPage(page)\r\n    const res = await this.http.request<{ actions: DiscoveredAction[] }>(\r\n      '/api/v1/copilot/scan',\r\n      { method: 'POST', body: { snapshot, hint }, timeoutMs: 45_000 },\r\n    )\r\n    return res.actions ?? []\r\n  }\r\n\r\n  // ── internals ────────────────────────────────────────────────────────\r\n\r\n  private async snapshotPage(page: PageLike): Promise<{ url: string; title: string; screenshot: string }> {\r\n    const buf = await page.screenshot({ type: 'jpeg', quality: 60, fullPage: false })\r\n    const screenshot = bufferToBase64(buf)\r\n    return {\r\n      url: page.url(),\r\n      title: await page.title().catch(() => ''),\r\n      screenshot,\r\n    }\r\n  }\r\n\r\n  /** Execute the plan. Returns true if the AI-vision fallback was used. */\r\n  private async runAction(\r\n    page: PageLike,\r\n    plan: {\r\n      type: 'click' | 'fill' | 'select' | 'hover' | 'press_key' | 'goto'\r\n      selector?: string\r\n      alternativeSelectors?: string[]\r\n      point?: { x: number; y: number }\r\n      value?: string\r\n      url?: string\r\n    },\r\n    timeout: number,\r\n    allowVision: boolean,\r\n  ): Promise<boolean> {\r\n    if (plan.type === 'press_key' && plan.value) {\r\n      await page.keyboard.press(plan.value)\r\n      return false\r\n    }\r\n    if (plan.type === 'goto' && plan.url) {\r\n      await page.goto(plan.url, { timeout })\r\n      return false\r\n    }\r\n    const candidates = [plan.selector, ...(plan.alternativeSelectors ?? [])].filter(\r\n      (s): s is string => typeof s === 'string' && s.length > 0,\r\n    )\r\n    // 1) Try the ranked selectors in order (cheap + deterministic).\r\n    let lastErr: unknown\r\n    for (const sel of candidates) {\r\n      try {\r\n        switch (plan.type) {\r\n          case 'click': await page.click(sel, { timeout }); return false\r\n          case 'fill': await page.fill(sel, plan.value ?? '', { timeout }); return false\r\n          case 'select': await page.selectOption(sel, plan.value ?? '', { timeout }); return false\r\n          case 'hover': await page.hover(sel, { timeout }); return false\r\n          default: throw new Error(`Unsupported action type: ${plan.type}`)\r\n        }\r\n      } catch (e) {\r\n        lastErr = e\r\n      }\r\n    }\r\n    // 2) AI-vision fallback: every selector failed → click the model's\r\n    //    normalised point. <select> can't be operated by a coordinate, so it's\r\n    //    selectors-only. Requires page.mouse (Playwright provides it).\r\n    if (allowVision && plan.point && plan.type !== 'select' && page.mouse) {\r\n      const vp = page.viewportSize?.() || { width: 1280, height: 800 }\r\n      const x = Math.round((plan.point.x / 1000) * vp.width)\r\n      const y = Math.round((plan.point.y / 1000) * vp.height)\r\n      await page.mouse.click(x, y)\r\n      if (plan.type === 'fill' && plan.value) await page.keyboard.type(plan.value, { delay: 20 })\r\n      // hover via mouse.move when available, else the click above is close enough.\r\n      if (plan.type === 'hover' && page.mouse.move) await page.mouse.move(x, y)\r\n      return true\r\n    }\r\n    if (candidates.length === 0) throw new Error(`No selector or vision point returned for action ${plan.type}`)\r\n    throw lastErr ?? new Error(`No selector worked for ${plan.type} (and vision fallback unavailable)`)\r\n  }\r\n\r\n  private zodToJsonSchema<T>(schema: ZodLikeSchema<T>): unknown {\r\n    return { type: 'object', _zodHint: String(schema) }\r\n  }\r\n}\r\n\r\nfunction bufferToBase64(buf: Buffer | Uint8Array): string {\r\n  if (typeof Buffer !== 'undefined' && buf instanceof Buffer) {\r\n    return buf.toString('base64')\r\n  }\r\n  let binary = ''\r\n  const bytes = buf as Uint8Array\r\n  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i])\r\n  const g = globalThis as any\r\n  return g.btoa ? g.btoa(binary) : Buffer.from(binary, 'binary').toString('base64')\r\n}\r\n","/**\r\n * Typed error hierarchy for the Prompteryx SDK.\r\n *\r\n * Every error from the SDK is an instance of `PrompteryxError`. Subclass\r\n * by HTTP status family so callers can `if (err instanceof QuotaError)`\r\n * without parsing strings. Network/parse errors get their own classes\r\n * too so retries can fork on category.\r\n */\r\n\r\n/** Base class — every SDK error inherits from this. */\r\nexport class PrompteryxError extends Error {\r\n  public readonly status?: number\r\n  public readonly code?: string\r\n  public readonly requestId?: string\r\n  public readonly raw?: unknown\r\n\r\n  constructor(message: string, opts: { status?: number; code?: string; requestId?: string; raw?: unknown } = {}) {\r\n    super(message)\r\n    this.name = 'PrompteryxError'\r\n    this.status = opts.status\r\n    this.code = opts.code\r\n    this.requestId = opts.requestId\r\n    this.raw = opts.raw\r\n    // Restore prototype chain for `instanceof` checks across realms.\r\n    Object.setPrototypeOf(this, new.target.prototype)\r\n  }\r\n}\r\n\r\n/** 401 / 403 — bad or revoked API key, or insufficient scope. */\r\nexport class AuthError extends PrompteryxError {\r\n  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] = {}) {\r\n    super(message, opts)\r\n    this.name = 'AuthError'\r\n    Object.setPrototypeOf(this, AuthError.prototype)\r\n  }\r\n}\r\n\r\n/** 402 — plan allowance exhausted (AI Credits, cloud minutes, etc.). */\r\nexport class QuotaError extends PrompteryxError {\r\n  /** Which resources are exhausted, when known. */\r\n  public readonly resources?: string[]\r\n  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] & { resources?: string[] } = {}) {\r\n    super(message, opts)\r\n    this.name = 'QuotaError'\r\n    this.resources = opts.resources\r\n    Object.setPrototypeOf(this, QuotaError.prototype)\r\n  }\r\n}\r\n\r\n/** 404 — resource doesn't exist (workflow id, execution id, session id). */\r\nexport class NotFoundError extends PrompteryxError {\r\n  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] = {}) {\r\n    super(message, opts)\r\n    this.name = 'NotFoundError'\r\n    Object.setPrototypeOf(this, NotFoundError.prototype)\r\n  }\r\n}\r\n\r\n/** 422 — request body shape was wrong. */\r\nexport class ValidationError extends PrompteryxError {\r\n  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] = {}) {\r\n    super(message, opts)\r\n    this.name = 'ValidationError'\r\n    Object.setPrototypeOf(this, ValidationError.prototype)\r\n  }\r\n}\r\n\r\n/** 429 — rate-limited. Caller can retry after `retryAfterSeconds`. */\r\nexport class RateLimitError extends PrompteryxError {\r\n  public readonly retryAfterSeconds?: number\r\n  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] & { retryAfterSeconds?: number } = {}) {\r\n    super(message, opts)\r\n    this.name = 'RateLimitError'\r\n    this.retryAfterSeconds = opts.retryAfterSeconds\r\n    Object.setPrototypeOf(this, RateLimitError.prototype)\r\n  }\r\n}\r\n\r\n/** 5xx — server-side failure. SDK retries these by default for idempotent ops. */\r\nexport class ServerError extends PrompteryxError {\r\n  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] = {}) {\r\n    super(message, opts)\r\n    this.name = 'ServerError'\r\n    Object.setPrototypeOf(this, ServerError.prototype)\r\n  }\r\n}\r\n\r\n/** Network / DNS / socket / aborted — never reached the server. */\r\nexport class NetworkError extends PrompteryxError {\r\n  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] = {}) {\r\n    super(message, opts)\r\n    this.name = 'NetworkError'\r\n    Object.setPrototypeOf(this, NetworkError.prototype)\r\n  }\r\n}\r\n\r\n/** Response body parse failure (server returned a non-JSON 500 page, etc.). */\r\nexport class ParseError extends PrompteryxError {\r\n  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] = {}) {\r\n    super(message, opts)\r\n    this.name = 'ParseError'\r\n    Object.setPrototypeOf(this, ParseError.prototype)\r\n  }\r\n}\r\n\r\n/** Timed-out waiting for a long-running op (execution polling, agent run). */\r\nexport class TimeoutError extends PrompteryxError {\r\n  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] = {}) {\r\n    super(message, opts)\r\n    this.name = 'TimeoutError'\r\n    Object.setPrototypeOf(this, TimeoutError.prototype)\r\n  }\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACUO,IAAM,kBAAN,cAA8B,MAAM;AAAA,EAMzC,YAAY,SAAiB,OAA8E,CAAC,GAAG;AAC7G,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,SAAS,KAAK;AACnB,SAAK,OAAO,KAAK;AACjB,SAAK,YAAY,KAAK;AACtB,SAAK,MAAM,KAAK;AAEhB,WAAO,eAAe,MAAM,WAAW,SAAS;AAAA,EAClD;AACF;AAiCO,IAAM,kBAAN,MAAM,yBAAwB,gBAAgB;AAAA,EACnD,YAAY,SAAiB,OAAyD,CAAC,GAAG;AACxF,UAAM,SAAS,IAAI;AACnB,SAAK,OAAO;AACZ,WAAO,eAAe,MAAM,iBAAgB,SAAS;AAAA,EACvD;AACF;;;ADHO,IAAM,iBAAN,MAAqB;AAAA,EAC1B,YAA6B,MAAkB;AAAlB;AAAA,EAAmB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAqBhD,MAAM,GAAG,MAAgB,aAAqB,OAAuD,CAAC,GAA6B;AACjI,UAAM,QAAQ,KAAK,IAAI;AACvB,UAAM,WAAW,MAAM,KAAK,aAAa,IAAI;AAC7C,UAAM,OAAO,MAAM,KAAK,KAAK,QAQ1B,sBAAsB;AAAA,MACvB,QAAQ;AAAA,MACR,MAAM,EAAE,aAAa,SAAS;AAAA,MAC9B,WAAW;AAAA,IACb,CAAC;AACD,UAAM,cAAc,KAAK,mBAAmB;AAC5C,QAAI;AACF,YAAM,qBAAqB,MAAM,KAAK,UAAU,MAAM,MAAM,KAAK,WAAW,MAAQ,WAAW;AAC/F,aAAO;AAAA,QACL,SAAS;AAAA,QACT,QAAQ,KAAK;AAAA,QACb,UAAU,KAAK;AAAA,QACf;AAAA,QACA,YAAY,KAAK,IAAI,IAAI;AAAA,MAC3B;AAAA,IACF,SAAS,KAAK;AACZ,aAAO;AAAA,QACL,SAAS;AAAA,QACT,QAAQ,KAAK;AAAA,QACb,UAAU,KAAK;AAAA,QACf,YAAY,KAAK,IAAI,IAAI;AAAA,QACzB,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,MACxD;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAoBA,MAAM,KAAQ,MAAgB,QAAgE;AAC5F,UAAM,WAAW,MAAM,KAAK,aAAa,IAAI;AAC7C,UAAM,aAAa,gBAAgB,SAC9B,OAAmC,aACpC,KAAK,gBAAgB,MAA0B;AACnD,UAAM,MAAM,MAAM,KAAK,KAAK;AAAA,MAC1B;AAAA,MACA,EAAE,QAAQ,QAAQ,MAAM,EAAE,UAAU,WAAW,GAAG,WAAW,IAAO;AAAA,IACtE;AACA,QAAI,WAAY,UAAqB,OAAQ,OAA4B,UAAU,YAAY;AAC7F,UAAI;AACF,eAAQ,OAA4B,MAAM,IAAI,IAAI;AAAA,MACpD,SAAS,GAAG;AACV,cAAM,IAAI;AAAA,UACR,2CAA2C,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC,CAAC;AAAA,UACrF,EAAE,KAAK,IAAI,KAAK;AAAA,QAClB;AAAA,MACF;AAAA,IACF;AACA,WAAO,IAAI;AAAA,EACb;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,MAAM,KAAK,MAAgB,MAA4C;AACrE,UAAM,WAAW,MAAM,KAAK,aAAa,IAAI;AAC7C,UAAM,MAAM,MAAM,KAAK,KAAK;AAAA,MAC1B;AAAA,MACA,EAAE,QAAQ,QAAQ,MAAM,EAAE,UAAU,KAAK,GAAG,WAAW,KAAO;AAAA,IAChE;AACA,WAAO,IAAI,WAAW,CAAC;AAAA,EACzB;AAAA;AAAA,EAIA,MAAc,aAAa,MAA6E;AACtG,UAAM,MAAM,MAAM,KAAK,WAAW,EAAE,MAAM,QAAQ,SAAS,IAAI,UAAU,MAAM,CAAC;AAChF,UAAM,aAAa,eAAe,GAAG;AACrC,WAAO;AAAA,MACL,KAAK,KAAK,IAAI;AAAA,MACd,OAAO,MAAM,KAAK,MAAM,EAAE,MAAM,MAAM,EAAE;AAAA,MACxC;AAAA,IACF;AAAA,EACF;AAAA;AAAA,EAGA,MAAc,UACZ,MACA,MAQA,SACA,aACkB;AAClB,QAAI,KAAK,SAAS,eAAe,KAAK,OAAO;AAC3C,YAAM,KAAK,SAAS,MAAM,KAAK,KAAK;AACpC,aAAO;AAAA,IACT;AACA,QAAI,KAAK,SAAS,UAAU,KAAK,KAAK;AACpC,YAAM,KAAK,KAAK,KAAK,KAAK,EAAE,QAAQ,CAAC;AACrC,aAAO;AAAA,IACT;AACA,UAAM,aAAa,CAAC,KAAK,UAAU,GAAI,KAAK,wBAAwB,CAAC,CAAE,EAAE;AAAA,MACvE,CAAC,MAAmB,OAAO,MAAM,YAAY,EAAE,SAAS;AAAA,IAC1D;AAEA,QAAI;AACJ,eAAW,OAAO,YAAY;AAC5B,UAAI;AACF,gBAAQ,KAAK,MAAM;AAAA,UACjB,KAAK;AAAS,kBAAM,KAAK,MAAM,KAAK,EAAE,QAAQ,CAAC;AAAG,mBAAO;AAAA,UACzD,KAAK;AAAQ,kBAAM,KAAK,KAAK,KAAK,KAAK,SAAS,IAAI,EAAE,QAAQ,CAAC;AAAG,mBAAO;AAAA,UACzE,KAAK;AAAU,kBAAM,KAAK,aAAa,KAAK,KAAK,SAAS,IAAI,EAAE,QAAQ,CAAC;AAAG,mBAAO;AAAA,UACnF,KAAK;AAAS,kBAAM,KAAK,MAAM,KAAK,EAAE,QAAQ,CAAC;AAAG,mBAAO;AAAA,UACzD;AAAS,kBAAM,IAAI,MAAM,4BAA4B,KAAK,IAAI,EAAE;AAAA,QAClE;AAAA,MACF,SAAS,GAAG;AACV,kBAAU;AAAA,MACZ;AAAA,IACF;AAIA,QAAI,eAAe,KAAK,SAAS,KAAK,SAAS,YAAY,KAAK,OAAO;AACrE,YAAM,KAAK,KAAK,eAAe,KAAK,EAAE,OAAO,MAAM,QAAQ,IAAI;AAC/D,YAAM,IAAI,KAAK,MAAO,KAAK,MAAM,IAAI,MAAQ,GAAG,KAAK;AACrD,YAAM,IAAI,KAAK,MAAO,KAAK,MAAM,IAAI,MAAQ,GAAG,MAAM;AACtD,YAAM,KAAK,MAAM,MAAM,GAAG,CAAC;AAC3B,UAAI,KAAK,SAAS,UAAU,KAAK,MAAO,OAAM,KAAK,SAAS,KAAK,KAAK,OAAO,EAAE,OAAO,GAAG,CAAC;AAE1F,UAAI,KAAK,SAAS,WAAW,KAAK,MAAM,KAAM,OAAM,KAAK,MAAM,KAAK,GAAG,CAAC;AACxE,aAAO;AAAA,IACT;AACA,QAAI,WAAW,WAAW,EAAG,OAAM,IAAI,MAAM,mDAAmD,KAAK,IAAI,EAAE;AAC3G,UAAM,WAAW,IAAI,MAAM,0BAA0B,KAAK,IAAI,oCAAoC;AAAA,EACpG;AAAA,EAEQ,gBAAmB,QAAmC;AAC5D,WAAO,EAAE,MAAM,UAAU,UAAU,OAAO,MAAM,EAAE;AAAA,EACpD;AACF;AAEA,SAAS,eAAe,KAAkC;AACxD,MAAI,OAAO,WAAW,eAAe,eAAe,QAAQ;AAC1D,WAAO,IAAI,SAAS,QAAQ;AAAA,EAC9B;AACA,MAAI,SAAS;AACb,QAAM,QAAQ;AACd,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,IAAK,WAAU,OAAO,aAAa,MAAM,CAAC,CAAC;AAC7E,QAAM,IAAI;AACV,SAAO,EAAE,OAAO,EAAE,KAAK,MAAM,IAAI,OAAO,KAAK,QAAQ,QAAQ,EAAE,SAAS,QAAQ;AAClF;","names":[]}

package/dist/page.mjs

@@ -0,0 +1,7 @@
+import {
+  CopilotHelpers
+} from "./chunk-ODLNHNQT.mjs";
+export {
+  CopilotHelpers
+};
+//# sourceMappingURL=page.mjs.map

package/dist/page.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

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

package/src/client.ts

@@ -0,0 +1,286 @@
+/**
+ * HTTP client for the Prompteryx SDK.
+ *
+ * Thin layer over `fetch` that adds:
+ *   - Bearer auth from the configured API key
+ *   - JSON serialisation + content-type
+ *   - Status-to-typed-error mapping (see errors.ts)
+ *   - Configurable timeout via AbortController
+ *   - Bounded retry for idempotent ops on 5xx / network errors
+ *   - Optional SSE streaming for execution logs / agent traces
+ *
+ * Anything that needs raw `Response` (e.g. downloading a recording
+ * binary) can use `rawRequest()`. Everything else should use
+ * `request<T>()` which returns the parsed JSON body typed as T.
+ */
+
+import {
+  AuthError,
+  NetworkError,
+  NotFoundError,
+  ParseError,
+  PrompteryxError,
+  QuotaError,
+  RateLimitError,
+  ServerError,
+  TimeoutError,
+  ValidationError,
+} from './errors'
+import type { PrompteryxClientOptions } from './types'
+
+const DEFAULT_BASE_URL = 'https://prompteryx.com'
+const DEFAULT_TIMEOUT_MS = 60_000
+const DEFAULT_MAX_RETRIES = 2
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PATCH' | 'DELETE'
+  /** Object that will be JSON.stringified into the body. Skip for GET/DELETE. */
+  body?: unknown
+  /** Extra headers merged into the defaults. */
+  headers?: Record<string, string>
+  /** Override the client default timeout for this single call. */
+  timeoutMs?: number
+  /** Whether this op is safe to retry on transient failure. Defaults
+   *  based on method: GET = yes, others = no. The caller can force
+   *  retry for idempotent POSTs (e.g. a poll loop). */
+  retry?: boolean
+  /** Query string params (URI-encoded automatically). */
+  query?: Record<string, string | number | boolean | undefined | null>
+  /** Optional AbortSignal for caller-side cancellation. */
+  signal?: AbortSignal
+}
+
+export class HttpClient {
+  private readonly apiKey: string
+  /** Optional Cloud Browser key (`pcb_live_…`) — a separate key family used
+   *  only by the /api/v1/cloud-browser/* endpoints (sent as `x-api-key`). */
+  public readonly cloudBrowserKey?: string
+  private readonly baseUrl: string
+  private readonly timeoutMs: number
+  private readonly maxRetries: number
+  private readonly defaultHeaders: Record<string, string>
+  private readonly fetchImpl: typeof fetch
+
+  constructor(opts: PrompteryxClientOptions) {
+    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).',
+      )
+    }
+    // Bind so `this` doesn't get lost on assignment.
+    this.fetchImpl = f.bind(globalThis)
+  }
+
+  /** Returns the JSON-parsed body typed as T. Throws typed errors on non-2xx. */
+  async request<T = unknown>(path: string, opts: RequestOptions = {}): Promise<T> {
+    const res = await this.rawRequest(path, opts)
+    const text = await res.text()
+    if (!text) return undefined as T
+    try {
+      return JSON.parse(text) as T
+    } 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: string, opts: RequestOptions = {}): Promise<Response> {
+    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: unknown
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        const res = await this.sendOnce(url, method, opts)
+        if (res.ok) return res
+        // Map status → typed error. For 5xx / 429 with retries remaining,
+        // throw a retryable subclass and try again.
+        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) {
+        // Network / abort errors: treat as retryable when we have budget.
+        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
+      }
+    }
+    // Shouldn't reach here, but TS likes a return.
+    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<T = unknown>(path: string, opts: RequestOptions = {}): AsyncGenerator<T, void, void> {
+    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 })
+      // SSE events separated by blank line. Each event has one or more
+      // `data: ` lines we concatenate.
+      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) as T
+        } catch {
+          // Skip malformed events rather than dropping the whole stream.
+          // Real-world SSE has occasional keepalive comments + heartbeat
+          // lines we don't want to crash on.
+        }
+      }
+    }
+  }
+
+  // ── internals ────────────────────────────────────────────────────────
+
+  private async sendOnce(url: string, method: string, opts: RequestOptions): Promise<Response> {
+    const timeoutMs = opts.timeoutMs ?? this.timeoutMs
+    const ctl = new AbortController()
+    const t = setTimeout(() => ctl.abort(), timeoutMs)
+    // Combine caller signal with our timeout signal.
+    if (opts.signal) {
+      if (opts.signal.aborted) ctl.abort()
+      else opts.signal.addEventListener('abort', () => ctl.abort(), { once: true })
+    }
+    try {
+      const headers: Record<string, string> = {
+        Authorization: `Bearer ${this.apiKey}`,
+        Accept: 'application/json',
+        ...this.defaultHeaders,
+        ...(opts.headers ?? {}),
+      }
+      let body: BodyInit | undefined
+      if (opts.body !== undefined) {
+        headers['Content-Type'] = 'application/json'
+        body = JSON.stringify(opts.body)
+      }
+      return await this.fetchImpl(url, {
+        method,
+        headers,
+        body,
+        signal: ctl.signal,
+      })
+    } finally {
+      clearTimeout(t)
+    }
+  }
+
+  private buildUrl(path: string, query?: RequestOptions['query']): string {
+    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 === undefined || v === null) continue
+      params.set(k, String(v))
+    }
+    const qs = params.toString()
+    return qs ? `${base}${base.includes('?') ? '&' : '?'}${qs}` : base
+  }
+
+  private async errorFromResponse(res: Response): Promise<PrompteryxError> {
+    let parsed: any = null
+    try {
+      const text = await res.text()
+      parsed = text ? JSON.parse(text) : null
+    } catch { /* ignore — body wasn't JSON */ }
+    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') ?? undefined
+    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 : undefined })
+      }
+      default:
+        if (res.status >= 500) return new ServerError(message, opts)
+        return new PrompteryxError(message, opts)
+    }
+  }
+
+  private wrapTransport(e: unknown): PrompteryxError {
+    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}`)
+  }
+
+  private isRetryable(err: PrompteryxError): boolean {
+    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
+  }
+
+  private async backoff(attempt: number, err: PrompteryxError): Promise<void> {
+    // Honour `Retry-After` when the server provided one.
+    const retryAfter = (err as RateLimitError).retryAfterSeconds
+    if (retryAfter && retryAfter > 0) {
+      return new Promise((r) => setTimeout(r, Math.min(retryAfter, 30) * 1000))
+    }
+    // Otherwise exponential backoff with jitter: 250ms, 500ms, 1s, 2s, ...
+    const base = 250 * Math.pow(2, attempt)
+    const jitter = Math.random() * 100
+    return new Promise((r) => setTimeout(r, base + jitter))
+  }
+}