@prompteryx/sdk 0.4.0

package/src/resources/customNodes.ts

@@ -0,0 +1,62 @@
+/**
+ * ⚠️ NOT SHIPPED in @prompteryx/sdk 0.4.0 (2026-09-03) — not exported from
+ * src/index.ts. The /api/v1/custom-nodes* routes this resource targets do
+ * not exist on the live API (every call 404s). Verified against the 31
+ * live v1 routes in docs/API_SDK_DEVELOPER_PLAN_GOLIVE_AUDIT.md. Kept as
+ * source for a future release; do not re-export without re-verifying.
+ *
+ * `px.customNodes.*` — user-built reusable nodes.
+ *
+ * Custom Nodes are HTTP-call wrappers, expression transforms, or
+ * composed sub-workflows the user creates in the platform. They
+ * become first-class node types available in Visual Studio AND via
+ * the SDK as direct one-shot invocations.
+ *
+ * Use cases:
+ *   - Call a private API your team owns with a stored credential
+ *     reference (you wire up the auth once, every workflow uses it).
+ *   - Reusable data transforms shared across workflows.
+ *   - Sub-workflows you compose into bigger ones.
+ *
+ * Billing: a custom node run counts as 1 workflow execution (it
+ * runs as a single-node workflow internally). Credentials referenced
+ * by the node are scoped to the SAME user / project as the node;
+ * cross-user credential access is forbidden by the runtime.
+ */
+
+import type { HttpClient } from '../client'
+import type { CustomNodeSummary, ExecutionRecord } from '../types'
+
+export class CustomNodesResource {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(): Promise<CustomNodeSummary[]> {
+    const res = await this.http.request<{ nodes: CustomNodeSummary[] }>(
+      '/api/v1/custom-nodes',
+    )
+    return res.nodes ?? []
+  }
+
+  async get(nodeId: string): Promise<CustomNodeSummary> {
+    return this.http.request(`/api/v1/custom-nodes/${encodeURIComponent(nodeId)}`)
+  }
+
+  /**
+   * Execute a custom node with the given input. Returns the node's
+   * structured output. Same SSRF protections + credential isolation
+   * as Visual Studio.
+   *
+   * ```ts
+   * const result = await px.customNodes.run('node_abc', {
+   *   userId: 'u_123',
+   *   action: 'lookup',
+   * })
+   * ```
+   */
+  async run(nodeId: string, input: Record<string, unknown> = {}): Promise<{ output: unknown; execution: ExecutionRecord }> {
+    return this.http.request(`/api/v1/custom-nodes/${encodeURIComponent(nodeId)}/execute`, {
+      method: 'POST',
+      body: { input },
+    })
+  }
+}

package/src/resources/executions.ts

@@ -0,0 +1,84 @@
+/**
+ * `px.executions.*` — status, logs (polled OR streamed), wait.
+ */
+
+import type { HttpClient } from '../client'
+import { TimeoutError } from '../errors'
+import type { ExecutionLogEvent, ExecutionRecord, ExecutionStatus } from '../types'
+
+const TERMINAL_STATES: ExecutionStatus[] = [
+  'completed',
+  'failed',
+  'cancelled',
+  'timed_out',
+]
+
+export class ExecutionsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Get current execution record. */
+  async get(executionId: string): Promise<ExecutionRecord> {
+    return this.http.request(`/api/v1/executions/${encodeURIComponent(executionId)}`)
+  }
+
+  /**
+   * Block until the execution reaches a terminal state. Polls every
+   * `pollIntervalMs` (default 2s) until it's `completed`/`failed`/
+   * `cancelled`/`timed_out`, OR until `timeoutMs` elapses (default 5min).
+   *
+   * Throws `TimeoutError` on timeout; otherwise returns the final record.
+   */
+  async wait(
+    executionId: string,
+    opts: { timeoutMs?: number; pollIntervalMs?: number; signal?: AbortSignal } = {},
+  ): Promise<ExecutionRecord> {
+    const timeoutMs = opts.timeoutMs ?? 5 * 60_000
+    const pollIntervalMs = opts.pollIntervalMs ?? 2_000
+    const deadline = Date.now() + timeoutMs
+    while (true) {
+      if (opts.signal?.aborted) throw new TimeoutError(`Wait cancelled for ${executionId}`)
+      const exec = await this.get(executionId)
+      if (TERMINAL_STATES.includes(exec.status)) return exec
+      if (Date.now() > deadline) {
+        throw new TimeoutError(`Execution ${executionId} did not finish within ${timeoutMs}ms`)
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs))
+    }
+  }
+
+  /**
+   * Get the logs for a finished (or in-progress) execution as a one-shot
+   * fetch. For real-time streaming use `stream(executionId)` instead.
+   */
+  async logs(executionId: string): Promise<ExecutionLogEvent[]> {
+    const res = await this.http.request<{ logs: ExecutionLogEvent[] }>(
+      `/api/v1/executions/${encodeURIComponent(executionId)}/logs`,
+    )
+    return res.logs ?? []
+  }
+
+  /**
+   * Stream log events as they arrive. Async iterable:
+   *
+   *   for await (const ev of px.executions.stream(execId)) {
+   *     console.log(ev.message)
+   *     if (ev.type === 'done') break
+   *   }
+   */
+  async *stream(
+    executionId: string,
+    opts: { signal?: AbortSignal } = {},
+  ): AsyncGenerator<ExecutionLogEvent, void, void> {
+    yield* this.http.streamSse<ExecutionLogEvent>(
+      `/api/v1/executions/${encodeURIComponent(executionId)}/logs/stream`,
+      { signal: opts.signal },
+    )
+  }
+
+  /** Get a single node's output from a finished execution. */
+  async getNodeOutput(executionId: string, nodeId: string): Promise<unknown> {
+    return this.http.request(
+      `/api/v1/executions/${encodeURIComponent(executionId)}/nodes/${encodeURIComponent(nodeId)}/output`,
+    )
+  }
+}

package/src/resources/profiles.ts

@@ -0,0 +1,48 @@
+/**
+ * `px.profiles.*` — Chrome profile management.
+ *
+ * Profiles are persistent browser identities — they store cookies,
+ * local storage, extensions, and login state across sessions. Two
+ * kinds:
+ *   • `cloud` — lives on the Prompteryx cloud browser infrastructure.
+ *     Accessible from any device, but starts logged out (you have to
+ *     log in once after creating).
+ *   • `local` — runs on the user's own Chrome via the Prompteryx
+ *     plugin. Reuses whatever Chrome profile the user is already
+ *     signed into (Gmail, banking, internal SSO). Cloud-only
+ *     workloads can't access this.
+ */
+
+import type { HttpClient } from '../client'
+import type { ProfileSummary } from '../types'
+
+export class ProfilesResource {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(opts: { kind?: 'cloud' | 'local' } = {}): Promise<ProfileSummary[]> {
+    const res = await this.http.request<{ profiles: ProfileSummary[] }>(
+      '/api/v1/profiles',
+      { query: { kind: opts.kind } },
+    )
+    return res.profiles ?? []
+  }
+
+  async get(profileId: string): Promise<ProfileSummary> {
+    return this.http.request(`/api/v1/profiles/${encodeURIComponent(profileId)}`)
+  }
+
+  /** Create a new CLOUD profile. Local profiles are managed by the
+   *  plugin and cannot be created via the API. */
+  async create(opts: { name: string }): Promise<ProfileSummary> {
+    return this.http.request('/api/v1/profiles', {
+      method: 'POST',
+      body: { name: opts.name, kind: 'cloud' },
+    })
+  }
+
+  async delete(profileId: string): Promise<{ ok: true }> {
+    return this.http.request(`/api/v1/profiles/${encodeURIComponent(profileId)}`, {
+      method: 'DELETE',
+    })
+  }
+}

package/src/resources/recordings.ts

@@ -0,0 +1,32 @@
+/**
+ * ⚠️ NOT SHIPPED in @prompteryx/sdk 0.4.0 (2026-09-03) — not exported from
+ * src/index.ts. The live /api/v1/recordings route is a POST-only ACTION
+ * recorder used by the MCP server (actions: start/stop/save — it captures
+ * workflow actions, not session videos); GET list is a 405 and
+ * /api/v1/recordings/{id} does not exist. Verified in
+ * docs/API_SDK_DEVELOPER_PLAN_GOLIVE_AUDIT.md. Kept as source for a future
+ * release; do not re-export without re-verifying the endpoints.
+ *
+ * `px.recordings.*` — list session recordings + signed-URL retrieval.
+ */
+
+import type { HttpClient } from '../client'
+import type { SessionRecording } from '../types'
+
+export class RecordingsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /** List your recordings, newest first. */
+  async list(opts: { limit?: number } = {}): Promise<SessionRecording[]> {
+    const res = await this.http.request<{ recordings: SessionRecording[] }>(
+      '/api/v1/recordings',
+      { query: { limit: opts.limit } },
+    )
+    return res.recordings ?? []
+  }
+
+  /** Get a single recording's metadata + signed playback URL. */
+  async get(sessionId: string): Promise<SessionRecording> {
+    return this.http.request(`/api/v1/recordings/${encodeURIComponent(sessionId)}`)
+  }
+}

package/src/resources/schedules.ts

@@ -0,0 +1,49 @@
+/**
+ * `px.schedules.*` — server-side workflow scheduling.
+ *
+ * Set a workflow to run on cron / interval; the platform's Cloud
+ * Scheduler will fire it on schedule even when no client is connected.
+ * Wraps the same scheduling primitive the Visual Studio "Active"
+ * toggle uses.
+ */
+
+import type { HttpClient } from '../client'
+import type { CreateScheduleOptions, ScheduleSummary } from '../types'
+
+export class SchedulesResource {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(opts: { active?: boolean; workflowId?: string } = {}): Promise<ScheduleSummary[]> {
+    const res = await this.http.request<{ schedules: ScheduleSummary[] }>(
+      '/api/v1/schedules',
+      { query: { active: opts.active, workflowId: opts.workflowId } },
+    )
+    return res.schedules ?? []
+  }
+
+  async get(scheduleId: string): Promise<ScheduleSummary> {
+    return this.http.request(`/api/v1/schedules/${encodeURIComponent(scheduleId)}`)
+  }
+
+  /** Create a new schedule. Returns the created record. */
+  async create(opts: CreateScheduleOptions): Promise<ScheduleSummary> {
+    return this.http.request('/api/v1/schedules', {
+      method: 'POST',
+      body: opts,
+    })
+  }
+
+  /** Pause / resume / change cron / timezone. */
+  async update(scheduleId: string, patch: Partial<CreateScheduleOptions> & { active?: boolean }): Promise<ScheduleSummary> {
+    return this.http.request(`/api/v1/schedules/${encodeURIComponent(scheduleId)}`, {
+      method: 'PATCH',
+      body: patch,
+    })
+  }
+
+  async delete(scheduleId: string): Promise<{ ok: true }> {
+    return this.http.request(`/api/v1/schedules/${encodeURIComponent(scheduleId)}`, {
+      method: 'DELETE',
+    })
+  }
+}

package/src/resources/subscription.ts

@@ -0,0 +1,27 @@
+/**
+ * `px.subscription.*` — plan + balance + usage telemetry.
+ *
+ * Programmatic access to the same numbers the in-app `/subscription`
+ * and `/cloud-platform/plans` pages display. Use this to:
+ *   • Check the user's remaining AI Credits before kicking off a
+ *     long workflow.
+ *   • Read monthly execution counts for your own dashboards.
+ *   • Detect a plan downgrade and react in your code.
+ */
+
+import type { HttpClient } from '../client'
+import type { SubscriptionStatus } from '../types'
+
+export class SubscriptionResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Get the current plan + balances + usage. */
+  async get(): Promise<SubscriptionStatus> {
+    return this.http.request('/api/v1/subscription')
+  }
+
+  // NOT SHIPPED (2026-09-03, v0.4.0): usage() was removed — the route it
+  // targeted (/api/v1/subscription/usage) does not exist on the live API
+  // (the only usage route is /api/v1/usage, with a different shape).
+  // Re-add once a real time-series endpoint ships.
+}

package/src/resources/templates.ts

@@ -0,0 +1,46 @@
+/**
+ * ⚠️ NOT SHIPPED in @prompteryx/sdk 0.4.0 (2026-09-03) — not exported from
+ * src/index.ts. The /api/v1/templates* routes this resource targets do not
+ * exist on the live API (every call 404s). Verified against the 31 live v1
+ * routes in docs/API_SDK_DEVELOPER_PLAN_GOLIVE_AUDIT.md. Kept as source for
+ * a future release; do not re-export without re-verifying.
+ *
+ * `px.templates.*` — workflow templates catalogue.
+ *
+ * Templates are pre-built workflows the user can fork into their
+ * own account. They include both platform-curated templates and
+ * user-shared ones. Forking a template returns a new `workflowId`
+ * scoped to the calling user.
+ */
+
+import type { HttpClient } from '../client'
+import type { TemplateSummary } from '../types'
+
+export class TemplatesResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Browse templates. Use `category` + `search` to filter. */
+  async list(opts: { category?: string; search?: string; limit?: number } = {}): Promise<TemplateSummary[]> {
+    const res = await this.http.request<{ templates: TemplateSummary[] }>(
+      '/api/v1/templates',
+      { query: { category: opts.category, q: opts.search, limit: opts.limit } },
+    )
+    return res.templates ?? []
+  }
+
+  async get(templateId: string): Promise<TemplateSummary & { nodes?: unknown[] }> {
+    return this.http.request(`/api/v1/templates/${encodeURIComponent(templateId)}`)
+  }
+
+  /**
+   * Fork a template into the user's workspace. Returns the new
+   * workflow id; the user can then run / edit it like any other
+   * workflow.
+   */
+  async fork(templateId: string, opts: { name?: string } = {}): Promise<{ workflowId: string }> {
+    return this.http.request(`/api/v1/templates/${encodeURIComponent(templateId)}/fork`, {
+      method: 'POST',
+      body: { name: opts.name },
+    })
+  }
+}

package/src/resources/workflows.ts

@@ -0,0 +1,84 @@
+/**
+ * `px.workflows.*` — Visual Studio workflows.
+ *
+ * Trigger workflows you (or anyone you share with) built in Visual
+ * Studio. Workflows are first-class platform objects: they have
+ * permanent IDs, can be scheduled, shared, templated, and edited
+ * visually. Triggering one via the SDK is fully equivalent to
+ * pressing Run in the UI — same runtime, same node executor, same
+ * billing path.
+ */
+
+import type { HttpClient } from '../client'
+import { TimeoutError } from '../errors'
+import type {
+  ExecutionRecord,
+  RunWorkflowOptions,
+  RunWorkflowResult,
+  WorkflowSummary,
+} from '../types'
+
+export class WorkflowsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(opts: { limit?: number; search?: string; tag?: string } = {}): Promise<WorkflowSummary[]> {
+    const res = await this.http.request<{ workflows: WorkflowSummary[] }>(
+      '/api/v1/workflows',
+      { query: { limit: opts.limit, q: opts.search, tag: opts.tag } },
+    )
+    return res.workflows ?? []
+  }
+
+  async get(workflowId: string): Promise<WorkflowSummary & { nodes?: unknown[] }> {
+    return this.http.request(`/api/v1/workflows/${encodeURIComponent(workflowId)}`)
+  }
+
+  /**
+   * Trigger a workflow. Returns immediately with `executionId`. Use
+   * `px.executions.wait(id)` to block until completion or
+   * `px.executions.stream(id)` to follow log events live.
+   *
+   * The `execution` options override the workflow's saved settings
+   * for this one run — you don't have to edit the workflow in VS to
+   * change the proxy, region, profile, etc.
+   */
+  async run(workflowId: string, opts: RunWorkflowOptions = {}): Promise<RunWorkflowResult> {
+    return this.http.request<RunWorkflowResult>(
+      `/api/v1/workflows/${encodeURIComponent(workflowId)}/execute`,
+      {
+        method: 'POST',
+        body: {
+          variables: opts.input,
+          executionOptions: opts.execution,
+        },
+      },
+    )
+  }
+
+  /**
+   * Run + block. Returns the final ExecutionRecord. Throws
+   * `TimeoutError` if the run takes longer than `timeoutMs`
+   * (default 5 minutes).
+   */
+  async runAndWait(
+    workflowId: string,
+    opts: RunWorkflowOptions & { timeoutMs?: number; pollIntervalMs?: number } = {},
+  ): Promise<ExecutionRecord> {
+    const started = await this.run(workflowId, opts)
+    return this.waitInternal(started.executionId, opts.timeoutMs ?? 5 * 60_000, opts.pollIntervalMs ?? 2_000)
+  }
+
+  private async waitInternal(executionId: string, timeoutMs: number, pollIntervalMs: number): Promise<ExecutionRecord> {
+    const deadline = Date.now() + timeoutMs
+    while (true) {
+      const exec = await this.http.request<ExecutionRecord>(
+        `/api/v1/executions/${encodeURIComponent(executionId)}`,
+      )
+      if (['completed', 'failed', 'cancelled', 'timed_out'].includes(exec.status)) return exec
+      if (Date.now() > deadline) {
+        throw new TimeoutError(`Execution ${executionId} did not finish within ${timeoutMs}ms`)
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs))
+    }
+  }
+}