@prompteryx/sdk 0.4.0

package/src/errors.ts

@@ -0,0 +1,113 @@
+/**
+ * Typed error hierarchy for the Prompteryx SDK.
+ *
+ * Every error from the SDK is an instance of `PrompteryxError`. Subclass
+ * by HTTP status family so callers can `if (err instanceof QuotaError)`
+ * without parsing strings. Network/parse errors get their own classes
+ * too so retries can fork on category.
+ */
+
+/** Base class — every SDK error inherits from this. */
+export class PrompteryxError extends Error {
+  public readonly status?: number
+  public readonly code?: string
+  public readonly requestId?: string
+  public readonly raw?: unknown
+
+  constructor(message: string, opts: { status?: number; code?: string; requestId?: string; raw?: unknown } = {}) {
+    super(message)
+    this.name = 'PrompteryxError'
+    this.status = opts.status
+    this.code = opts.code
+    this.requestId = opts.requestId
+    this.raw = opts.raw
+    // Restore prototype chain for `instanceof` checks across realms.
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+}
+
+/** 401 / 403 — bad or revoked API key, or insufficient scope. */
+export class AuthError extends PrompteryxError {
+  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] = {}) {
+    super(message, opts)
+    this.name = 'AuthError'
+    Object.setPrototypeOf(this, AuthError.prototype)
+  }
+}
+
+/** 402 — plan allowance exhausted (AI Credits, cloud minutes, etc.). */
+export class QuotaError extends PrompteryxError {
+  /** Which resources are exhausted, when known. */
+  public readonly resources?: string[]
+  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] & { resources?: string[] } = {}) {
+    super(message, opts)
+    this.name = 'QuotaError'
+    this.resources = opts.resources
+    Object.setPrototypeOf(this, QuotaError.prototype)
+  }
+}
+
+/** 404 — resource doesn't exist (workflow id, execution id, session id). */
+export class NotFoundError extends PrompteryxError {
+  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] = {}) {
+    super(message, opts)
+    this.name = 'NotFoundError'
+    Object.setPrototypeOf(this, NotFoundError.prototype)
+  }
+}
+
+/** 422 — request body shape was wrong. */
+export class ValidationError extends PrompteryxError {
+  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] = {}) {
+    super(message, opts)
+    this.name = 'ValidationError'
+    Object.setPrototypeOf(this, ValidationError.prototype)
+  }
+}
+
+/** 429 — rate-limited. Caller can retry after `retryAfterSeconds`. */
+export class RateLimitError extends PrompteryxError {
+  public readonly retryAfterSeconds?: number
+  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] & { retryAfterSeconds?: number } = {}) {
+    super(message, opts)
+    this.name = 'RateLimitError'
+    this.retryAfterSeconds = opts.retryAfterSeconds
+    Object.setPrototypeOf(this, RateLimitError.prototype)
+  }
+}
+
+/** 5xx — server-side failure. SDK retries these by default for idempotent ops. */
+export class ServerError extends PrompteryxError {
+  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] = {}) {
+    super(message, opts)
+    this.name = 'ServerError'
+    Object.setPrototypeOf(this, ServerError.prototype)
+  }
+}
+
+/** Network / DNS / socket / aborted — never reached the server. */
+export class NetworkError extends PrompteryxError {
+  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] = {}) {
+    super(message, opts)
+    this.name = 'NetworkError'
+    Object.setPrototypeOf(this, NetworkError.prototype)
+  }
+}
+
+/** Response body parse failure (server returned a non-JSON 500 page, etc.). */
+export class ParseError extends PrompteryxError {
+  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] = {}) {
+    super(message, opts)
+    this.name = 'ParseError'
+    Object.setPrototypeOf(this, ParseError.prototype)
+  }
+}
+
+/** Timed-out waiting for a long-running op (execution polling, agent run). */
+export class TimeoutError extends PrompteryxError {
+  constructor(message: string, opts: ConstructorParameters<typeof PrompteryxError>[1] = {}) {
+    super(message, opts)
+    this.name = 'TimeoutError'
+    Object.setPrototypeOf(this, TimeoutError.prototype)
+  }
+}

package/src/index.ts

@@ -0,0 +1,140 @@
+/**
+ * @prompteryx/sdk
+ *
+ * Official TypeScript SDK for the Prompteryx platform.
+ *
+ * Two AI surfaces:
+ *
+ *   • **Copilot** — helps with ONE step you describe in plain English.
+ *     Your code drives Playwright; copilot just figures out the
+ *     selector to click / the data to pull / what's on the page.
+ *
+ *     ```ts
+ *     await px.copilot.do(page, 'click the Sign up button')
+ *     const product = await px.copilot.read(page, productSchema)
+ *     const actions = await px.copilot.scan(page, 'checkout buttons')
+ *     ```
+ *
+ *   • **Autopilot** — runs an autonomous multi-step task end-to-end
+ *     with no per-action involvement from you.
+ *
+ *     ```ts
+ *     const result = await px.autopilot.run({
+ *       goal: 'Apply for the Senior Engineer role at OpenAI',
+ *       saveAsWorkflow: true,   // permanent zero-AI-cost replay
+ *     })
+ *     ```
+ *
+ * Plus workflows, executions, cloud browser sessions / fetch / search,
+ * schedules, profiles, and subscription telemetry.
+ *
+ * TWO KEY FAMILIES:
+ *   • `apiKey` (`px_live_…`) — the platform API key; sent as
+ *     `Authorization: Bearer`. 60 requests/minute, 10,000/day.
+ *   • `cloudBrowserKey` (`pcb_live_…`) — the Cloud Browser key; required
+ *     only for `px.cloudBrowser.*`, sent as `x-api-key`.
+ *
+ * Quick start:
+ *
+ * ```ts
+ * import { Prompteryx } from '@prompteryx/sdk'
+ * import { chromium } from 'playwright-core'
+ *
+ * const px = new Prompteryx({
+ *   apiKey: process.env.PROMPTERYX_API_KEY!,                    // px_live_…
+ *   cloudBrowserKey: process.env.PROMPTERYX_CLOUD_BROWSER_KEY,  // pcb_live_…
+ * })
+ *
+ * // 1. Cloud browser session
+ * const session = await px.cloudBrowser.sessions.create({
+ *   useProxy: true, proxyLocation: 'us',
+ * })
+ * const browser = await chromium.connectOverCDP(session.connectUrl)
+ * const page = browser.contexts()[0].pages()[0]
+ *
+ * // 2. Copilot on top of Playwright
+ * await page.goto('https://news.ycombinator.com')
+ * const top = await px.copilot.read(page, z.object({
+ *   stories: z.array(z.object({ title: z.string(), url: z.string() })),
+ * }))
+ * ```
+ *
+ * See PROMPTERYX_SDK.md in docs/ for the full design + reference.
+ */
+
+import { HttpClient } from './client'
+import { AutopilotResource } from './resources/autopilot'
+import { CloudBrowserResource } from './resources/cloudBrowser'
+import { ExecutionsResource } from './resources/executions'
+import { ProfilesResource } from './resources/profiles'
+import { SchedulesResource } from './resources/schedules'
+import { SubscriptionResource } from './resources/subscription'
+import { WorkflowsResource } from './resources/workflows'
+import { CopilotHelpers, type PageLike } from './page'
+import type {
+  CopilotDoResult,
+  DiscoveredAction,
+  PrompteryxClientOptions,
+} from './types'
+
+// Public re-exports
+export * from './errors'
+export * from './types'
+export * from './models'
+export type { PageLike }
+
+// v0.4.0 (2026-09-03): the connectHub, customNodes, templates, apiKeys and
+// recordings namespaces plus subscription.usage() were REMOVED from the
+// public surface — the routes they target don't exist on the live API (or,
+// for api-keys, can never accept API-key auth). The source files remain in
+// src/resources/ with dated NOT-SHIPPED headers for a future release.
+
+/**
+ * Copilot surface — bundles the three on-page primitives behind a
+ * single namespace so calling code reads as
+ * `px.copilot.do(...)` / `px.copilot.read(...)` / `px.copilot.scan(...)`.
+ * Used internally by the Prompteryx class.
+ */
+class Copilot {
+  constructor(private readonly helpers: CopilotHelpers) {}
+  /** Execute a natural-language action on a connected Playwright page. */
+  do(page: PageLike, instruction: string, opts?: { timeout?: number }): Promise<CopilotDoResult> {
+    return this.helpers.do(page, instruction, opts)
+  }
+  /** Pull typed data from the page (Zod schema or raw JSON Schema). */
+  read<T>(page: PageLike, schema: { parse(input: unknown): T } | { jsonSchema: unknown }): Promise<T> {
+    return this.helpers.read<T>(page, schema as any)
+  }
+  /** Discover available actions on the page; useful pre-`do` step. */
+  scan(page: PageLike, hint?: string): Promise<DiscoveredAction[]> {
+    return this.helpers.scan(page, hint)
+  }
+}
+
+export class Prompteryx {
+  private readonly http: HttpClient
+
+  // Core resources — the verified live surface.
+  public readonly workflows: WorkflowsResource
+  public readonly executions: ExecutionsResource
+  public readonly cloudBrowser: CloudBrowserResource
+  public readonly autopilot: AutopilotResource
+  public readonly copilot: Copilot
+  public readonly schedules: SchedulesResource
+  public readonly profiles: ProfilesResource
+  public readonly subscription: SubscriptionResource
+
+  constructor(opts: PrompteryxClientOptions) {
+    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)
+  }
+}
+
+export default Prompteryx

package/src/models.ts

@@ -0,0 +1,63 @@
+/**
+ * Browser-agent model catalog — the ids `px.autopilot.run({ model })` accepts.
+ *
+ * ⚠️ MUST MIRROR `components/unified-chat-v2/browser-models.ts`
+ * `V2_BROWSER_MODELS` in the platform repo — that file is the canonical
+ * catalog the server validates against (an unknown id hard-400s with
+ * `UNSUPPORTED_MODEL` under strict validation). When that list changes,
+ * regenerate this one. Last synced: 2026-09-03 — 32 ids.
+ *
+ * The type stays open (`| (string & {})`) so a model the server adds
+ * tomorrow works without an SDK release, while editors still autocomplete
+ * the known catalog.
+ */
+
+export const 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',
+] as const
+
+/** A model id from the known catalog. */
+export type AutopilotModelId = (typeof AUTOPILOT_MODELS)[number]
+
+/** Open union: known ids autocomplete, forward-compatible strings still pass. */
+export type AutopilotModel = AutopilotModelId | (string & {})
+
+/** The platform default when `model` is omitted. */
+export const DEFAULT_AUTOPILOT_MODEL = 'gemini-3.5-flash'

package/src/page.ts

@@ -0,0 +1,264 @@
+/**
+ * Copilot primitives — `do`, `read`, `scan` — operating on a Playwright
+ * page.
+ *
+ * Two namespaces in the Prompteryx SDK:
+ *   • Copilot  → SDK helps with ONE step you describe in plain English.
+ *                Your code drives Playwright; copilot just figures out
+ *                which selector to click / what data to pull / what's
+ *                discoverable on the current page.
+ *   • Autopilot → SDK runs an autonomous multi-step task with no per-
+ *                 action involvement from you. See ./resources/autopilot.ts.
+ *
+ * The copilot primitives:
+ *   • `do(page, instruction)` — execute a single natural-language
+ *     action ("click the Sign up button", "fill the email field with
+ *     hello@example.com"). Returns a structured result describing
+ *     what was done.
+ *   • `read(page, schema)` — pull typed data from the page. Pass a
+ *     Zod schema or a raw JSON Schema; the SDK returns the populated
+ *     object validated against your schema.
+ *   • `scan(page, hint?)` — list discoverable actions on the page.
+ *     Useful as a pre-step to `do()` for resilient automations:
+ *     scan → pick the action whose description matches your intent →
+ *     do() against it.
+ *
+ * Architecturally the SDK never drives the browser server-side. The
+ * server returns a structured plan and the SDK executes it locally
+ * against your Playwright page, so your trace, debugger, and any
+ * custom event handlers continue to work normally.
+ */
+
+import type { HttpClient } from './client'
+import { ValidationError } from './errors'
+import type { CopilotDoResult, DiscoveredAction } from './types'
+
+/** Minimal Page surface — anything satisfying this works (Playwright's
+ *  Page does, by structural typing, without an explicit import). */
+export interface PageLike {
+  url(): string
+  title(): Promise<string>
+  screenshot(opts?: { type?: 'png' | 'jpeg'; quality?: number; fullPage?: boolean }): Promise<Buffer | Uint8Array>
+  evaluate<T>(fn: (...args: unknown[]) => T): Promise<T>
+  click(selector: string, opts?: { timeout?: number }): Promise<void>
+  fill(selector: string, value: string, opts?: { timeout?: number }): Promise<void>
+  selectOption(selector: string, value: string | string[], opts?: { timeout?: number }): Promise<unknown>
+  goto(url: string, opts?: { timeout?: number }): Promise<unknown>
+  hover(selector: string, opts?: { timeout?: number }): Promise<void>
+  keyboard: { press(key: string): Promise<void>; type(text: string, opts?: { delay?: number }): Promise<void> }
+  // Used by the AI-vision fallback (when all ranked selectors fail). Playwright's
+  // Page provides both; optional so a minimal page can still satisfy PageLike.
+  mouse?: { click(x: number, y: number): Promise<void>; move?(x: number, y: number): Promise<void> }
+  viewportSize?(): { width: number; height: number } | null
+  locator(selector: string): {
+    first(): { isVisible(opts?: { timeout?: number }): Promise<boolean>; textContent(opts?: { timeout?: number }): Promise<string | null> }
+  }
+}
+
+interface ZodLikeSchema<T> {
+  parse(input: unknown): T
+  _def?: unknown
+}
+
+export class CopilotHelpers {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * 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: PageLike, instruction: string, opts: { timeout?: number; visionFallback?: boolean } = {}): Promise<CopilotDoResult> {
+    const start = Date.now()
+    const snapshot = await this.snapshotPage(page)
+    const plan = await this.http.request<{
+      type: 'click' | 'fill' | 'select' | 'hover' | 'press_key' | 'goto'
+      selector?: string
+      alternativeSelectors?: string[]
+      point?: { x: number; y: number }
+      value?: string
+      url?: string
+      description: string
+    }>('/api/v1/copilot/do', {
+      method: 'POST',
+      body: { instruction, snapshot },
+      timeoutMs: 45_000,
+    })
+    const allowVision = opts.visionFallback !== false
+    try {
+      const usedVisionFallback = await this.runAction(page, plan, opts.timeout ?? 15_000, 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<T>(page: PageLike, schema: ZodLikeSchema<T> | { jsonSchema: unknown }): Promise<T> {
+    const snapshot = await this.snapshotPage(page)
+    const jsonSchema = 'jsonSchema' in schema
+      ? (schema as { jsonSchema: unknown }).jsonSchema
+      : this.zodToJsonSchema(schema as ZodLikeSchema<T>)
+    const raw = await this.http.request<{ data: unknown }>(
+      '/api/v1/copilot/read',
+      { method: 'POST', body: { snapshot, jsonSchema }, timeoutMs: 60_000 },
+    )
+    if ('parse' in (schema as object) && typeof (schema as ZodLikeSchema<T>).parse === 'function') {
+      try {
+        return (schema as ZodLikeSchema<T>).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 as T
+  }
+
+  /**
+   * 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: PageLike, hint?: string): Promise<DiscoveredAction[]> {
+    const snapshot = await this.snapshotPage(page)
+    const res = await this.http.request<{ actions: DiscoveredAction[] }>(
+      '/api/v1/copilot/scan',
+      { method: 'POST', body: { snapshot, hint }, timeoutMs: 45_000 },
+    )
+    return res.actions ?? []
+  }
+
+  // ── internals ────────────────────────────────────────────────────────
+
+  private async snapshotPage(page: PageLike): Promise<{ url: string; title: string; screenshot: string }> {
+    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. */
+  private async runAction(
+    page: PageLike,
+    plan: {
+      type: 'click' | 'fill' | 'select' | 'hover' | 'press_key' | 'goto'
+      selector?: string
+      alternativeSelectors?: string[]
+      point?: { x: number; y: number }
+      value?: string
+      url?: string
+    },
+    timeout: number,
+    allowVision: boolean,
+  ): Promise<boolean> {
+    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): s is string => typeof s === 'string' && s.length > 0,
+    )
+    // 1) Try the ranked selectors in order (cheap + deterministic).
+    let lastErr: unknown
+    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
+      }
+    }
+    // 2) AI-vision fallback: every selector failed → click the model's
+    //    normalised point. <select> can't be operated by a coordinate, so it's
+    //    selectors-only. Requires page.mouse (Playwright provides it).
+    if (allowVision && plan.point && plan.type !== 'select' && page.mouse) {
+      const vp = page.viewportSize?.() || { width: 1280, height: 800 }
+      const x = Math.round((plan.point.x / 1000) * vp.width)
+      const y = Math.round((plan.point.y / 1000) * vp.height)
+      await page.mouse.click(x, y)
+      if (plan.type === 'fill' && plan.value) await page.keyboard.type(plan.value, { delay: 20 })
+      // hover via mouse.move when available, else the click above is close enough.
+      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)`)
+  }
+
+  private zodToJsonSchema<T>(schema: ZodLikeSchema<T>): unknown {
+    return { type: 'object', _zodHint: String(schema) }
+  }
+}
+
+function bufferToBase64(buf: Buffer | Uint8Array): string {
+  if (typeof Buffer !== 'undefined' && buf instanceof Buffer) {
+    return buf.toString('base64')
+  }
+  let binary = ''
+  const bytes = buf as Uint8Array
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i])
+  const g = globalThis as any
+  return g.btoa ? g.btoa(binary) : Buffer.from(binary, 'binary').toString('base64')
+}

package/src/resources/apiKeys.ts

@@ -0,0 +1,53 @@
+/**
+ * ⚠️ NOT SHIPPED in @prompteryx/sdk 0.4.0 (2026-09-03) — not exported from
+ * src/index.ts. The live /api/v1/api-keys route requires a Firebase session
+ * ID token — an API key can NEVER manage API keys (401 by design), so this
+ * resource cannot work from an SDK authenticated with an API key. Verified
+ * in docs/API_SDK_DEVELOPER_PLAN_GOLIVE_AUDIT.md. Kept as source in case a
+ * session-token auth mode ships; do not re-export before then.
+ *
+ * `px.apiKeys.*` — programmatically manage your own API keys.
+ *
+ * Useful for orgs that rotate keys via CI, or for embedding "create a
+ * temporary key for this sub-account" flows.
+ */
+
+import type { HttpClient } from '../client'
+import type { ApiKeySummary } from '../types'
+
+export class ApiKeysResource {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(): Promise<ApiKeySummary[]> {
+    const res = await this.http.request<{ data: { apiKeys: ApiKeySummary[] } }>(
+      '/api/v1/api-keys',
+    )
+    return res.data?.apiKeys ?? []
+  }
+
+  /**
+   * Create a new API key. The full key is returned ONCE in `apiKey` —
+   * store it immediately, you can never see it again.
+   */
+  async create(opts: {
+    name: string
+    /** Days until the key expires. `null` = never. Default 90. */
+    expiresInDays?: number | null
+  }): Promise<{ apiKey: string; keyId: string; keyPrefix: string }> {
+    const res = await this.http.request<{ data: { apiKey: string; keyId: string; keyPrefix: string } }>(
+      '/api/v1/api-keys',
+      {
+        method: 'POST',
+        body: { name: opts.name, expiresInDays: opts.expiresInDays ?? 90 },
+      },
+    )
+    return res.data
+  }
+
+  /** Revoke a key by id. Immediate; no soft delete. */
+  async delete(keyId: string): Promise<{ ok: true }> {
+    return this.http.request(`/api/v1/api-keys/${encodeURIComponent(keyId)}`, {
+      method: 'DELETE',
+    })
+  }
+}