@prompteryx/sdk 0.4.0

package/src/types.ts

@@ -0,0 +1,680 @@
+/**
+ * Shared types for the Prompteryx SDK.
+ *
+ * Two important framing decisions reflected here:
+ *
+ * 1. NAMING: We use Prompteryx-native names throughout — `copilot`,
+ *    `autopilot`, `read`, `scan`, `do`, `run`. We deliberately don't
+ *    use the Stagehand vocabulary (act/extract/observe/agent).
+ * 2. EXTENSIBILITY: Many fields accept `string` rather than enums so
+ *    new Visual Studio nodes / new Gemini models / new providers
+ *    work the moment they're available server-side, without the SDK
+ *    needing a release. Where we DO enum, the type adds `| string`
+ *    so callers can still pass forward-compatible values.
+ */
+
+import type { AutopilotModel } from './models'
+
+// ─── Common ──────────────────────────────────────────────────────────────
+
+export type ExecutionStatus =
+  | 'queued'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'timed_out'
+
+export type Region =
+  | 'us-east-1'
+  | 'us-west-2'
+  | 'eu-west-1'
+  | 'eu-central-1'
+  | 'ap-southeast-1'
+  | (string & {})
+
+export type ProxyLocation =
+  | 'auto'
+  | 'us' | 'gb' | 'ca' | 'de' | 'fr' | 'au' | 'in' | 'br' | 'jp'
+  | (string & {})
+
+/** Where a workflow runs. Cloud = our infrastructure (always works).
+ *  Local = the user's own Chrome via the Prompteryx plugin (more
+ *  capable for tasks needing the user's real logins). */
+export type ExecutionTarget = 'cloud' | 'local'
+
+// ─── Workflows ───────────────────────────────────────────────────────────
+
+export interface WorkflowSummary {
+  /** `wf_…` */
+  id: string
+  name: string
+  description?: string
+  createdAt: string
+  updatedAt: string
+  nodeCount?: number
+  /** True if the workflow has an active schedule attached. */
+  scheduled?: boolean
+  /** Tags / categories the user has assigned. */
+  tags?: string[]
+}
+
+/**
+ * Every option the Visual Studio UI exposes when you run a workflow.
+ * Adding a new option in the UI? Add it here too. Anything passed in
+ * an `executionOptions` field unrecognised by the SDK still rides
+ * through (passthrough = future-proof).
+ */
+export interface WorkflowExecutionOptions {
+  /** Run on cloud browser (default) or via the user's local Chrome
+   *  through the Prompteryx plugin. */
+  target?: ExecutionTarget
+  /** Chrome profile id (cloud or local). Override the workflow's
+   *  saved profile for this one run. */
+  chromeProfile?: string
+  /** 'visible' = headed; 'headless' = no UI. */
+  runMode?: 'visible' | 'headless'
+  /** Capture a video recording. */
+  videoRecording?: boolean
+  /** "Turbo" mode skips visual polish + delay tweaks for speed. */
+  turboBoost?: boolean
+  /** Max execution time in ms. */
+  timeout?: number
+  /** Return every node's output in the execution record (heavy). */
+  includeNodeOutputs?: boolean
+  /** Override viewport size. */
+  viewport?: { width: number; height: number }
+  /** Run in a specific region (cloud only). */
+  region?: Region
+  /** Use residential proxy. */
+  useProxy?: boolean
+  /** Proxy exit country. */
+  proxyLocation?: ProxyLocation
+  /** Auto-solve CAPTCHAs during the run. */
+  useCaptcha?: boolean
+  /** Free-form passthrough — anything unrecognised by the SDK is
+   *  forwarded to the server intact. Use for new server-side
+   *  options before the SDK gets a release for them. */
+  passthrough?: Record<string, unknown>
+}
+
+export interface RunWorkflowOptions {
+  /** Workflow variables / input the workflow expects. */
+  input?: Record<string, unknown>
+  /** Execution options — overrides the workflow's saved settings. */
+  execution?: WorkflowExecutionOptions
+}
+
+export interface RunWorkflowResult {
+  executionId: string
+  status: ExecutionStatus
+  workflowId: string
+  startedAt?: string
+}
+
+// ─── Executions ──────────────────────────────────────────────────────────
+
+export interface ExecutionRecord {
+  id: string
+  workflowId: string
+  status: ExecutionStatus
+  startedAt: string
+  finishedAt?: string
+  durationMs?: number
+  outputs?: Record<string, unknown>
+  /** Detailed final state of every node (only when
+   *  `execution.includeNodeOutputs` was set to true). */
+  nodeOutputs?: Record<string, unknown>
+  error?: { message: string; nodeId?: string; nodeLabel?: string }
+  nodeErrors?: Array<{ nodeId: string; nodeLabel?: string; message: string }>
+  /** AI Credit + cloud-minute + proxy-MB + CAPTCHA consumption. */
+  usage?: {
+    aiCredits?: number
+    cloudBrowserMinutes?: number
+    proxyDataMB?: number
+    captchaSolves?: number
+    connectHubCalls?: number
+  }
+}
+
+export interface ExecutionLogEvent {
+  type: 'log' | 'progress' | 'node-start' | 'node-end' | 'error' | 'done'
+  message?: string
+  nodeId?: string
+  nodeLabel?: string
+  timestamp: string
+  level?: 'info' | 'warn' | 'error' | 'debug'
+  data?: unknown
+}
+
+// ─── Cloud Browser ───────────────────────────────────────────────────────
+
+export interface CreateSessionOptions {
+  /**
+   * Where the browser should actually run.
+   *  • 'cloud' (default) — Prompteryx Cloud / AWS fleet, billed in
+   *    cloud-browser minutes.
+   *  • 'local' — your own Chrome via the Prompteryx plugin + Electron
+   *    runner. ZERO cloud minutes, but requires the plugin to be
+   *    running on the SAME machine as the SDK consumer (your script
+   *    talks to localhost). Best for personal dev work where you want
+   *    a real browser but don't want to spend cloud minutes.
+   * See README "Local mode" for the prereqs.
+   */
+  target?: 'cloud' | 'local'
+  recordSession?: boolean
+  captureDownloads?: boolean
+  /** Storage keys for bring-your-own Chrome extensions
+   *  (.tar.gz bundles uploaded via the platform). */
+  extensions?: string[]
+  /** Route the session through a residential proxy (sent as the wire
+   *  field `proxy`). */
+  useProxy?: boolean
+  /** Proxy exit country (sent as the wire field `country`, e.g. 'us'). */
+  proxyLocation?: ProxyLocation
+  /** Auto-close the session after this many minutes. */
+  sessionTimeoutMinutes?: number
+  /**
+   * Reuse a named cloud profile (preserves cookies + storage state
+   * across sessions). OPTIONAL — when omitted the session is
+   * ephemeral: nothing is loaded at start, nothing is saved at close,
+   * which is usually what you want for one-off automations. Naming a
+   * profile implicitly opts in to persistence — you don't need to set
+   * `persistContext` as well.
+   */
+  profileId?: string
+  /**
+   * Explicit persistence opt-in WITHOUT naming a profile. Uses the
+   * account's Default profile. Most users should leave this alone and
+   * either pass `profileId` (named profile) or nothing (ephemeral).
+   */
+  persistContext?: boolean
+  /** Custom viewport. */
+  viewport?: { width: number; height: number }
+  /** Anything unrecognised by the SDK is forwarded as-is. */
+  passthrough?: Record<string, unknown>
+}
+
+/** Response of `sessions.create` — matches POST /api/v1/cloud-browser/sessions. */
+export interface CloudSession {
+  id: string
+  /** CDP endpoint — pass to `chromium.connectOverCDP(connectUrl)`. */
+  connectUrl: string
+  /** Watch-it-live URL (when the provider supports it). */
+  liveURL?: string | null
+  status: 'launching' | 'active' | 'closed' | 'failed' | (string & {})
+  startedAt: string
+  recordSession?: boolean
+}
+
+/** Row returned by `sessions.list` / `sessions.get` — durable session
+ *  history, NOT a live handle (no connectUrl). */
+export interface CloudSessionSummary {
+  id: string
+  status: string
+  provider?: string
+  startedAt?: string
+  endedAt?: string | null
+  durationMs?: number | null
+  region?: string
+  hasRecording?: boolean
+}
+
+/** Options for the one-shot `cloudBrowser.fetch` — matches
+ *  POST /api/v1/cloud-browser/fetch. */
+export interface CloudFetchOptions {
+  url: string
+  /** What to return in `content`. Default 'text' (readable text —
+   *  token-efficient for LLMs). 'links' fills `links` instead. */
+  format?: 'text' | 'markdown' | 'html' | 'links'
+  /** Navigation wait state. Default 'domcontentloaded'. */
+  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit'
+  /** Page-load budget in ms (5000–60000, default 30000). */
+  timeoutMs?: number
+  /** Route through a residential proxy. */
+  proxy?: boolean
+  /** Proxy exit country (with `proxy: true`), e.g. 'us'. */
+  country?: string
+  /** After load, wait until this CSS selector exists (JS-rendered content). */
+  waitForSelector?: string
+  /** Extra settle time after load/selector, ms (capped at 10000). */
+  waitMs?: number
+  /** Up to 10 CSS selectors extracted deterministically — per selector the
+   *  match count and the first 50 elements' text + outerHTML (capped). */
+  selectors?: string[]
+  /** Include a base64 JPEG of the viewport in the response. */
+  screenshot?: boolean
+}
+
+/** Response of `cloudBrowser.fetch`. */
+export interface CloudFetchResult {
+  url: string
+  finalUrl: string
+  title: string
+  status: string
+  /** Page content in the requested `format` (absent for format 'links'). */
+  content?: string
+  /** Present for format 'links'. */
+  links?: Array<{ text: string; href: string }>
+  /** Present when `waitForSelector` was given — whether it appeared in time. */
+  waitedSelector?: boolean
+  /** Present when `selectors` were given. */
+  extracted?: Array<{
+    selector: string
+    count?: number
+    elements?: Array<{ text: string; html: string }>
+    error?: string
+  }>
+  /** Present when `screenshot: true`. */
+  screenshotBase64?: string
+}
+
+export interface CloudSearchResult {
+  title: string
+  url: string
+  snippet: string
+}
+
+// ─── Autopilot (autonomous agent) ────────────────────────────────────────
+
+/**
+ * Every option exposed by the in-app AI Browser Agent surface, plus
+ * SDK-only hooks. Naming is `autopilot` not `agent` — autopilot
+ * implies "runs the whole task end-to-end without you", which is
+ * what this actually does.
+ */
+export interface AutopilotRunOptions {
+  /** What the autopilot should accomplish, in plain English. */
+  goal: string
+  /** Where to start. The autopilot navigates here before reasoning. */
+  startUrl?: string
+  /** Max reasoning steps before giving up. Default 30. */
+  maxSteps?: number
+  /** Hard cap on AI Credits this run may spend — the run stops once reached.
+   *  A cost guardrail for unattended/automated runs (pairs with maxSteps). */
+  maxCredits?: number
+  /** Cost-saving action batching — let the model chain several safe actions per
+   *  screenshot before taking the next one (cheaper on simple same-page tasks).
+   *  Default false. */
+  costSaving?: boolean
+  /** When `costSaving` is on: max actions the model may chain per screenshot
+   *  (2–20, default 5). Higher = cheaper on simple pages; lower = safer. */
+  costSavingMaxBatch?: number
+  /** When `costSaving` is on: "careful batching" — take a fresh screenshot after
+   *  each submit/commit action in a batch, so the agent never types the next
+   *  record blind. Fewer skipped/duplicated rows on form loops. Default false. */
+  carefulBatching?: boolean
+  /** AI Vision quality preset. Lower presets are cheaper and faster per step;
+   *  higher presets read small text and dense pages more accurately.
+   *  One of: 'ultra-saver' | 'low' | 'saver' | 'efficient' | 'balanced' |
+   *  'detailed' | 'enhanced' | 'precision' | 'max-precision'. */
+  aiVision?: 'ultra-saver' | 'low' | 'saver' | 'efficient' | 'balanced'
+    | 'detailed' | 'enhanced' | 'precision' | 'max-precision' | (string & {})
+  /** Final-step quality boost: one extra look at the finished page at this
+   *  preset right before the answer is written — sharper reads of prices,
+   *  dates and small text for one screenshot's extra cost.
+   *  'same' (default) = off. */
+  finalStepVision?: 'same' | 'ultra-saver' | 'low' | 'saver' | 'efficient'
+    | 'balanced' | 'detailed' | 'enhanced' | 'precision' | 'max-precision' | (string & {})
+  /** Structured output: a JSON Schema object for the final answer. When set,
+   *  `finalAnswer` is JSON conforming to this schema (the server also accepts
+   *  the snake_case `output_schema` spelling via passthrough). */
+  outputSchema?: Record<string, unknown>
+  /**
+   * Safety checkpoints. 'auto' (default) auto-consents past the model's safety
+   * decisions (e.g. submitting a form) — best for unattended runs. 'ask' pauses
+   * the job (status becomes terminal `awaiting_input`, with the checkpoint in
+   * `finalAnswer`) so you can review and resume it. Mirrors the settings dialog's
+   * "Auto-consent to safety checkpoints" toggle.
+   */
+  safetyConsent?: 'auto' | 'ask'
+  /**
+   * "Check unclear or risky tasks" (default ON). When on, a too-vague goal makes
+   * the agent ask a clarifying question first, and it confirms before an
+   * irreversible/costly action instead of guessing — surfacing as a terminal
+   * `awaiting_input` with the question in `finalAnswer`. Pass false to always
+   * proceed with a best guess.
+   */
+  confirmUnclear?: boolean
+  /**
+   * Smart Context Compression (default OFF). Summarises long sessions to cut token
+   * cost (~70% on long tasks). `compressionThreshold` = compress after this many
+   * steps (default 8).
+   */
+  enableContextCompression?: boolean
+  compressionThreshold?: number
+  /**
+   * Fresh-session reset (default OFF) — an alternative long-task cost saver. Every
+   * N turns it starts a clean session from a verified progress summary so per-step
+   * cost stops climbing. `sessionResetThreshold` = reset every N turns (default 12).
+   */
+  enableSessionReset?: boolean
+  sessionResetThreshold?: number
+  /**
+   * Where the autopilot should drive the browser.
+   *  • 'cloud' (default) — cloud browser, bills cloud-browser minutes.
+   *  • 'local' (v0.3+) — YOUR local Chrome via the Prompteryx desktop app.
+   *    ZERO cloud-browser minutes; AI Credits still apply. Requirements:
+   *    the desktop app must be RUNNING and SIGNED IN on this machine, and
+   *    your code must run on the same machine (the SDK talks to the app
+   *    directly at http://localhost:61337 — override with `runnerUrl`).
+   *    The browser tab stays open after the run for inspection/follow-ups.
+   */
+  target?: 'cloud' | 'local'
+  /** Local target only: the desktop app's local address.
+   *  Default 'http://localhost:61337'. */
+  runnerUrl?: string
+  /** Which browser-agent model to use. Default: 'gemini-3.5-flash'.
+   *  The known catalog is `AUTOPILOT_MODELS` (see models.ts — mirrored from
+   *  the platform's canonical V2_BROWSER_MODELS list); any other string is
+   *  forwarded as-is for forward compatibility, but an id the server doesn't
+   *  know hard-400s with UNSUPPORTED_MODEL. */
+  model?: AutopilotModel
+  /**
+   * Capture the discovered action sequence as a permanent workflow
+   * the user can replay forever at zero AI cost — the action-caching
+   * pattern, materialised as a first-class Visual Studio workflow
+   * (schedulable, shareable, editable, multi-option-selector
+   * resilient). The response includes `savedWorkflowId`.
+   */
+  saveAsWorkflow?: boolean
+  /** Display name for the saved workflow. Defaults to a slug of `goal`. */
+  savedWorkflowName?: string
+  /** Hard timeout for the whole run in ms. Default 5 minutes. */
+  timeoutMs?: number
+  /** Run on a pre-existing cloud session. If omitted the autopilot
+   *  spins up a fresh one + closes it on completion. */
+  sessionId?: string
+  /** Override the autopilot's system prompt. Advanced — most users
+   *  shouldn't set this. Used for niche bespoke tasks where the
+   *  default prompt loses subtlety (e.g. "always confirm before
+   *  submitting any form"). */
+  systemPromptOverride?: string
+  /** Restrict the tools the autopilot can use. By default all of
+   *  click / type / scroll / navigate / press_key / hover / extract
+   *  are available; pass a subset to constrain behaviour (e.g.
+   *  `['click', 'extract']` for a read-only task). */
+  allowedTools?: string[]
+  /** Viewport for the cloud browser session the autopilot uses. */
+  viewport?: { width: number; height: number }
+  /** Per-session controls forwarded to the underlying cloud-browser
+   *  session creation. Ignored when `sessionId` is set. */
+  session?: Omit<CreateSessionOptions, 'viewport'>
+  /**
+   * MULTI-AGENT SWARM. Run the goal across N parallel cloud agents instead of
+   * one. Default 1 (a normal single-agent run). When > 1 the response gains a
+   * `swarm` block with per-agent answers/usage, and `finalAnswer` is the merged
+   * result across all agents. Each agent still respects `maxCredits`; use
+   * `maxRunCredits` to bound the whole run.
+   */
+  agents?: number
+  /**
+   * Swarm coordination style (only meaningful when `agents` > 1):
+   *  • false (default) — N INDEPENDENT agents, each runs the FULL `goal` in its
+   *    own browser (fastest for "do the same thing N ways / N places").
+   *  • true — COLLABORATE via a shared work-queue: the goal (or the attached
+   *    spreadsheet, one item per row) is split into work items that agents claim
+   *    atomically — none done twice, none missed, idle agents work-steal.
+   */
+  collaborate?: boolean
+  /** Collaborate mode: a spreadsheet's TEXT (CSV / TSV / pipe table). When it looks
+   *  like a row table the shared queue is seeded ONE work item per ROW. */
+  attachmentContext?: string
+  /** Swarm whole-run credit budget (admission control). Once the run's total AI
+   *  Credits reach this, agents stop claiming new work items and wrap up what's in
+   *  flight. 0/undefined = no cap. Distinct from per-agent `maxCredits`. */
+  maxRunCredits?: number
+  /** Passthrough for future server-side options. */
+  passthrough?: Record<string, unknown>
+}
+
+export interface AutopilotStep {
+  step: number
+  action: string
+  reasoning?: string
+  /** Base64 JPEG screenshot taken before the step (debugging aid). */
+  screenshot?: string
+  result?: unknown
+}
+
+export interface AutopilotRunResult {
+  success: boolean
+  /** The autopilot's final summary / answer. */
+  finalAnswer?: string
+  steps: AutopilotStep[]
+  /** `wf_…` if `saveAsWorkflow` was true. Run it later with
+   *  `px.workflows.run(savedWorkflowId)` for zero-AI-cost replay. */
+  savedWorkflowId?: string
+  /** AI Credit + token usage telemetry. Sums ALL agents on a swarm run. */
+  usage?: {
+    aiCredits: number
+    tokensIn?: number
+    tokensOut?: number
+    /** USD cost the platform charged the user (1 credit = $0.01). */
+    costUSD?: number
+    /** Model turns (think-and-act cycles) the run took. */
+    turns?: number
+  }
+  /** Present only when `agents` > 1 — the multi-agent swarm detail. `finalAnswer`
+   *  above is the merged answer across every agent; this exposes each agent's own
+   *  answer/usage/session and (collaborate mode) the shared work-queue coverage. */
+  swarm?: {
+    mode: 'collaborate' | 'independent'
+    status: 'completed' | 'partial' | 'error'
+    agents: Array<{
+      idx: number
+      title: string
+      status: 'completed' | 'error' | 'stopped'
+      finalAnswer: string
+      costUSD: number
+      inTokens: number
+      outTokens: number
+      turns: number
+      sessionId: string
+      recordingUrl?: string
+      error?: string
+    }>
+    /** Shared-queue coverage (collaborate mode): items total / done / failed / etc. */
+    coverage?: {
+      total: number
+      done: number
+      failed: number
+      claimed: number
+      unclaimed: number
+    }
+  }
+}
+
+// ─── Copilot (single-action / read / scan) ───────────────────────────────
+
+export interface CopilotDoResult {
+  success: boolean
+  action: string
+  selector?: string
+  /** True when every ranked selector failed and the AI-vision coordinate
+   *  fallback was used instead. Lets you spot pages where stable selectors
+   *  aren't resolving so you can tighten them. */
+  usedVisionFallback?: boolean
+  durationMs: number
+  error?: string
+}
+
+export interface DiscoveredAction {
+  /** Semantic intent: 'click', 'fill', 'select', 'hover'. */
+  type: string
+  selector: string
+  alternativeSelectors?: string[]
+  description: string
+  /** Natural-language instruction the user would describe this with
+   *  ("click the Sign up button"). Useful for `px.copilot.do(page, a.example)`. */
+  example?: string
+}
+
+// ─── Connect Hub (2,800+ integrations) ───────────────────────────────────
+
+export interface ConnectHubAppSummary {
+  /** Pipedream slug ('gmail', 'google-sheets', ...). */
+  slug: string
+  name: string
+  iconUrl?: string
+  /** Categories the app belongs to. */
+  categories?: string[]
+}
+
+export interface ConnectHubActionSummary {
+  app: string
+  /** Action key ('send_message', 'create_row', etc.). */
+  action: string
+  name: string
+  description?: string
+  /** Parameter spec — the schema the user must satisfy in `params`. */
+  parameters?: Record<string, unknown>
+}
+
+export interface RunConnectHubActionOptions {
+  app: string
+  action: string
+  /** Action parameters. Shape depends on the action — call
+   *  `px.connectHub.getAction(app, action)` to fetch the schema. */
+  params: Record<string, unknown>
+  /** Optional credential id if the user has multiple accounts of the
+   *  same app connected. Defaults to the most recently used. */
+  credentialId?: string
+}
+
+// ─── Custom Nodes (user-built) ───────────────────────────────────────────
+
+export interface CustomNodeSummary {
+  id: string
+  name: string
+  description?: string
+  /** 'http' (one external call) or 'expression' (data transform) or
+   *  'composition' (sub-workflow). */
+  kind: 'http' | 'expression' | 'composition'
+  /** Input schema the node accepts. */
+  inputSchema?: Record<string, unknown>
+  /** Output schema the node returns. */
+  outputSchema?: Record<string, unknown>
+}
+
+// ─── Schedules ───────────────────────────────────────────────────────────
+
+export interface ScheduleSummary {
+  id: string
+  workflowId: string
+  workflowName?: string
+  /** Cron expression in the schedule's timezone. */
+  cronExpression: string
+  timezone: string
+  active: boolean
+  nextRun?: string
+  lastRun?: string
+  createdAt: string
+}
+
+export interface CreateScheduleOptions {
+  workflowId: string
+  cronExpression: string
+  /** IANA timezone ('America/New_York'). */
+  timezone?: string
+  /** Initial state. Default true. */
+  active?: boolean
+  /** Override the workflow's saved execution options for scheduled
+   *  runs. */
+  execution?: WorkflowExecutionOptions
+  /** Input variables passed every scheduled run. */
+  input?: Record<string, unknown>
+}
+
+// ─── Templates ───────────────────────────────────────────────────────────
+
+export interface TemplateSummary {
+  id: string
+  name: string
+  description?: string
+  categories?: string[]
+  /** Author of the template (the platform team or another user). */
+  author?: string
+  /** Indicative complexity. */
+  nodeCount?: number
+}
+
+// ─── Profiles ────────────────────────────────────────────────────────────
+
+export interface ProfileSummary {
+  id: string
+  name: string
+  /** 'cloud' = persistent cloud profile; 'local' = Chrome profile
+   *  on the user's machine (requires the Prompteryx plugin). */
+  kind: 'cloud' | 'local'
+  /** Cookies / storage size. */
+  sizeBytes?: number
+  lastUsedAt?: string
+}
+
+// ─── Subscription / billing ─────────────────────────────────────────────
+
+export interface SubscriptionStatus {
+  tier: 'free' | 'starter' | 'developer' | 'pro' | 'enterprise' | (string & {})
+  renewedAt?: string
+  /** Plan-included balances. */
+  balances: {
+    aiCredits: { remaining: number; included: number }
+    cloudBrowserMinutes: { remaining: number; included: number }
+    proxyDataMB: { remaining: number; included: number }
+    captchaSolves: { remaining: number; included: number }
+    connectHubCalls: { remaining: number; included: number }
+    monthlyExecutions: { remaining: number; included: number }
+  }
+  /** Top-up balances (don't reset monthly). */
+  topUpBalances: {
+    aiCredits: number
+    cloudBrowserMinutes: number
+    proxyDataMB: number
+    captchaSolves: number
+    connectHubCalls: number
+  }
+}
+
+// ─── Recordings + API Keys ──────────────────────────────────────────────
+
+export interface SessionRecording {
+  sessionId: string
+  startedAt: string
+  endedAt?: string
+  url: string
+  durationMs?: number
+  sizeBytes?: number
+}
+
+export interface ApiKeySummary {
+  id: string
+  name: string
+  keyPrefix: string
+  createdAt: string
+  lastUsedAt?: string
+  expiresAt?: string
+  status: 'active' | 'expired' | 'revoked'
+  usageCount: number
+}
+
+// ─── Client config ───────────────────────────────────────────────────────
+
+export interface PrompteryxClientOptions {
+  /** Platform API key (`px_live_…`) — sent as `Authorization: Bearer`.
+   *  Rate limits: 60 requests/minute, 10,000/day. */
+  apiKey: string
+  /**
+   * Cloud Browser API key (`pcb_live_…`) — a SEPARATE key family, created
+   * under Cloud Platform → API Keys. Required for `px.cloudBrowser.*`
+   * (sessions / fetch / search), which authenticates with `x-api-key`
+   * rather than the platform Bearer key. Calls to `px.cloudBrowser.*`
+   * throw an AuthError explaining this when it's absent.
+   */
+  cloudBrowserKey?: string
+  baseUrl?: string
+  timeoutMs?: number
+  maxRetries?: number
+  defaultHeaders?: Record<string, string>
+  fetch?: typeof fetch
+}