@prompteryx/sdk 0.4.0 → 0.4.1

package/src/resources/cloudBrowser.ts

@@ -1,197 +1,197 @@
-/**
- * `px.cloudBrowser.*` — sessions, one-shot fetch, search.
- *
- * The most-used path: `sessions.create()` returns a `connectUrl` you
- * pass to Playwright's `chromium.connectOverCDP(connectUrl)`. Your own
- * Playwright code drives the browser from there; we handle the
- * infrastructure (residential proxies, recording, persistence).
- *
- * ⚠️ KEY FAMILY (verified live 2026-09-03): every /api/v1/cloud-browser/*
- * route authenticates with a CLOUD BROWSER key (`pcb_live_…`) sent as
- * `x-api-key` — NOT the platform `px_live_…` Bearer key the rest of the
- * SDK uses. Pass it as `new Prompteryx({ apiKey, cloudBrowserKey })`;
- * calls throw a descriptive AuthError when it's missing.
- */
-
-import type { HttpClient, RequestOptions } from '../client'
-import { AuthError } from '../errors'
-import type {
-  CloudFetchOptions,
-  CloudFetchResult,
-  CloudSearchResult,
-  CloudSession,
-  CloudSessionSummary,
-  CreateSessionOptions,
-} from '../types'
-
-const MISSING_CB_KEY_MESSAGE =
-  'px.cloudBrowser.* uses a Cloud Browser API key (pcb_live_…), which is a ' +
-  'separate key family from the platform px_live_… key. Create one under ' +
-  'Cloud Platform → API Keys and pass it as ' +
-  'new Prompteryx({ apiKey, cloudBrowserKey }).'
-
-/** Sub-resource: cloud browser sessions. */
-export class SessionsResource {
-  constructor(private readonly http: HttpClient) {}
-
-  /** Headers for the pcb_live_ key family (throws a clear error if absent). */
-  private cbAuth(): Record<string, string> {
-    const key = this.http.cloudBrowserKey
-    if (!key) throw new AuthError(MISSING_CB_KEY_MESSAGE)
-    return { 'x-api-key': key }
-  }
-
-  private cbRequest<T>(path: string, opts: RequestOptions = {}): Promise<T> {
-    return this.http.request<T>(path, {
-      ...opts,
-      headers: { ...this.cbAuth(), ...(opts.headers ?? {}) },
-    })
-  }
-
-  /** Create a new browser session.
-   *
-   *  Cloud (default):
-   *    ```ts
-   *    const s = await px.cloudBrowser.sessions.create()
-   *    // s.connectUrl → Prompteryx Cloud CDP. Bills cloud-browser minutes.
-   *    ```
-   *
-   *  Local — uses YOUR machine's Chrome via the Prompteryx plugin +
-   *  Electron runner. ZERO cloud-browser minutes. Requires the plugin
-   *  to be running on the same machine as the SDK consumer; the call
-   *  short-circuits to localhost and never reaches the API.
-   *    ```ts
-   *    const s = await px.cloudBrowser.sessions.create({ target: 'local' })
-   *    // s.connectUrl → http://localhost:9222 (your Chrome's debug port)
-   *    ```
-   *
-   *  When `target: 'local'` is set, cloud-only fields (recordSession,
-   *  proxy, profileId) are ignored — you're driving your own Chrome
-   *  with whatever cookies/extensions you've already installed.
-   */
-  async create(opts: CreateSessionOptions = {}): Promise<CloudSession> {
-    if (opts.target === 'local') {
-      // Local mode short-circuit. We don't hit the API at all — the
-      // session is just a thin wrapper over the user's local Chrome's
-      // CDP endpoint (managed by the Prompteryx plugin). Saves cloud
-      // minutes AND avoids a round-trip. Failure to connect is the
-      // consumer's problem at .connectOverCDP() time.
-      const localCdp = 'http://127.0.0.1:9222'
-      const localId = `local_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
-      return {
-        id: localId,
-        connectUrl: localCdp,
-        status: 'active',
-        startedAt: new Date().toISOString(),
-        recordSession: false,
-      }
-    }
-    // Wire names match the route (proxy/country), while the SDK options keep
-    // the friendlier useProxy/proxyLocation spelling.
-    return this.cbRequest<CloudSession>('/api/v1/cloud-browser/sessions', {
-      method: 'POST',
-      body: {
-        recordSession: opts.recordSession,
-        captureDownloads: opts.captureDownloads,
-        extensions: opts.extensions,
-        proxy: opts.useProxy,
-        country: opts.proxyLocation,
-        sessionTimeoutMinutes: opts.sessionTimeoutMinutes,
-        profileId: opts.profileId,
-        persistContext: opts.persistContext,
-        viewport: opts.viewport,
-        ...(opts.passthrough || {}),
-      },
-    })
-  }
-
-  /** Retrieve a session's history record (status/duration/recording flag).
-   *  Note: this is durable history, not a live handle — it has no
-   *  `connectUrl`. Keep the `create()` response for connecting. */
-  async get(sessionId: string): Promise<CloudSessionSummary> {
-    return this.cbRequest(
-      `/api/v1/cloud-browser/sessions/${encodeURIComponent(sessionId)}`,
-    )
-  }
-
-  /** List recent sessions for your account, newest first. */
-  async list(opts: { limit?: number } = {}): Promise<CloudSessionSummary[]> {
-    const res = await this.cbRequest<{ sessions: CloudSessionSummary[] }>(
-      '/api/v1/cloud-browser/sessions',
-      { query: { limit: opts.limit } },
-    )
-    return res.sessions ?? []
-  }
-
-  /** Close a session, finalising the recording (if any) + releasing the
-   *  cloud-browser slot. Idempotent. No-op for local sessions
-   *  (target: 'local') — those don't have a slot to release. */
-  async close(sessionId: string): Promise<{ ok: boolean; proxyMB?: number }> {
-    // Local sessions are pure client-side handles — nothing to release.
-    if (sessionId.startsWith('local_')) return { ok: true }
-    return this.cbRequest(
-      `/api/v1/cloud-browser/sessions/${encodeURIComponent(sessionId)}`,
-      { method: 'DELETE' },
-    )
-  }
-}
-
-export class CloudBrowserResource {
-  readonly sessions: SessionsResource
-
-  constructor(private readonly http: HttpClient) {
-    this.sessions = new SessionsResource(http)
-  }
-
-  private cbAuth(): Record<string, string> {
-    const key = this.http.cloudBrowserKey
-    if (!key) throw new AuthError(MISSING_CB_KEY_MESSAGE)
-    return { 'x-api-key': key }
-  }
-
-  /**
-   * One-shot fetch through the cloud browser. Spins up a short-lived
-   * session, loads the page in real Chromium (so JS-rendered sites work),
-   * extracts the content, and tears down. Use this when you only need ONE
-   * page and don't want to manage Playwright yourself.
-   *
-   * ```ts
-   * const page = await px.cloudBrowser.fetch({
-   *   url: 'https://example.com/pricing',
-   *   format: 'markdown',                    // 'text' (default) | 'markdown' | 'html' | 'links'
-   *   waitForSelector: '.pricing-table',     // for JS-rendered content
-   *   selectors: ['.pricing-table .plan'],   // deterministic CSS extraction
-   * })
-   * // page.content, page.extracted, page.title, page.finalUrl …
-   * ```
-   */
-  async fetch(opts: CloudFetchOptions): Promise<CloudFetchResult> {
-    return this.http.request('/api/v1/cloud-browser/fetch', {
-      method: 'POST',
-      body: opts,
-      headers: this.cbAuth(),
-      timeoutMs: Math.max(90_000, (opts.timeoutMs ?? 30_000) + 30_000),
-    })
-  }
-
-  /**
-   * Search the web through the cloud browser and get structured results
-   * (title/url/snippet). Runs the query against DuckDuckGo's server-rendered
-   * HTML endpoint in a real browser — there is no engine choice today.
-   */
-  async search(opts: {
-    query: string
-    /** Max results, 1–25. Default 10. */
-    limit?: number
-    /** Route through a residential proxy. */
-    proxy?: boolean
-    /** Proxy exit country (with `proxy: true`), e.g. 'us'. */
-    country?: string
-  }): Promise<CloudSearchResult[]> {
-    const res = await this.http.request<{ query: string; results: CloudSearchResult[] }>(
-      '/api/v1/cloud-browser/search',
-      { method: 'POST', body: opts, headers: this.cbAuth(), timeoutMs: 90_000 },
-    )
-    return res.results ?? []
-  }
-}
+/**
+ * `px.cloudBrowser.*` — sessions, one-shot fetch, search.
+ *
+ * The most-used path: `sessions.create()` returns a `connectUrl` you
+ * pass to Playwright's `chromium.connectOverCDP(connectUrl)`. Your own
+ * Playwright code drives the browser from there; we handle the
+ * infrastructure (residential proxies, recording, persistence).
+ *
+ * ⚠️ KEY FAMILY (verified live 2026-09-03): every /api/v1/cloud-browser/*
+ * route authenticates with a CLOUD BROWSER key (`pcb_live_…`) sent as
+ * `x-api-key` — NOT the platform `px_live_…` Bearer key the rest of the
+ * SDK uses. Pass it as `new Prompteryx({ apiKey, cloudBrowserKey })`;
+ * calls throw a descriptive AuthError when it's missing.
+ */
+
+import type { HttpClient, RequestOptions } from '../client'
+import { AuthError } from '../errors'
+import type {
+  CloudFetchOptions,
+  CloudFetchResult,
+  CloudSearchResult,
+  CloudSession,
+  CloudSessionSummary,
+  CreateSessionOptions,
+} from '../types'
+
+const MISSING_CB_KEY_MESSAGE =
+  'px.cloudBrowser.* uses a Cloud Browser API key (pcb_live_…), which is a ' +
+  'separate key family from the platform px_live_… key. Create one under ' +
+  'Cloud Platform → API Keys and pass it as ' +
+  'new Prompteryx({ apiKey, cloudBrowserKey }).'
+
+/** Sub-resource: cloud browser sessions. */
+export class SessionsResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Headers for the pcb_live_ key family (throws a clear error if absent). */
+  private cbAuth(): Record<string, string> {
+    const key = this.http.cloudBrowserKey
+    if (!key) throw new AuthError(MISSING_CB_KEY_MESSAGE)
+    return { 'x-api-key': key }
+  }
+
+  private cbRequest<T>(path: string, opts: RequestOptions = {}): Promise<T> {
+    return this.http.request<T>(path, {
+      ...opts,
+      headers: { ...this.cbAuth(), ...(opts.headers ?? {}) },
+    })
+  }
+
+  /** Create a new browser session.
+   *
+   *  Cloud (default):
+   *    ```ts
+   *    const s = await px.cloudBrowser.sessions.create()
+   *    // s.connectUrl → Prompteryx Cloud CDP. Bills cloud-browser minutes.
+   *    ```
+   *
+   *  Local — uses YOUR machine's Chrome via the Prompteryx plugin +
+   *  Electron runner. ZERO cloud-browser minutes. Requires the plugin
+   *  to be running on the same machine as the SDK consumer; the call
+   *  short-circuits to localhost and never reaches the API.
+   *    ```ts
+   *    const s = await px.cloudBrowser.sessions.create({ target: 'local' })
+   *    // s.connectUrl → http://localhost:9222 (your Chrome's debug port)
+   *    ```
+   *
+   *  When `target: 'local'` is set, cloud-only fields (recordSession,
+   *  proxy, profileId) are ignored — you're driving your own Chrome
+   *  with whatever cookies/extensions you've already installed.
+   */
+  async create(opts: CreateSessionOptions = {}): Promise<CloudSession> {
+    if (opts.target === 'local') {
+      // Local mode short-circuit. We don't hit the API at all — the
+      // session is just a thin wrapper over the user's local Chrome's
+      // CDP endpoint (managed by the Prompteryx plugin). Saves cloud
+      // minutes AND avoids a round-trip. Failure to connect is the
+      // consumer's problem at .connectOverCDP() time.
+      const localCdp = 'http://127.0.0.1:9222'
+      const localId = `local_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
+      return {
+        id: localId,
+        connectUrl: localCdp,
+        status: 'active',
+        startedAt: new Date().toISOString(),
+        recordSession: false,
+      }
+    }
+    // Wire names match the route (proxy/country), while the SDK options keep
+    // the friendlier useProxy/proxyLocation spelling.
+    return this.cbRequest<CloudSession>('/api/v1/cloud-browser/sessions', {
+      method: 'POST',
+      body: {
+        recordSession: opts.recordSession,
+        captureDownloads: opts.captureDownloads,
+        extensions: opts.extensions,
+        proxy: opts.useProxy,
+        country: opts.proxyLocation,
+        sessionTimeoutMinutes: opts.sessionTimeoutMinutes,
+        profileId: opts.profileId,
+        persistContext: opts.persistContext,
+        viewport: opts.viewport,
+        ...(opts.passthrough || {}),
+      },
+    })
+  }
+
+  /** Retrieve a session's history record (status/duration/recording flag).
+   *  Note: this is durable history, not a live handle — it has no
+   *  `connectUrl`. Keep the `create()` response for connecting. */
+  async get(sessionId: string): Promise<CloudSessionSummary> {
+    return this.cbRequest(
+      `/api/v1/cloud-browser/sessions/${encodeURIComponent(sessionId)}`,
+    )
+  }
+
+  /** List recent sessions for your account, newest first. */
+  async list(opts: { limit?: number } = {}): Promise<CloudSessionSummary[]> {
+    const res = await this.cbRequest<{ sessions: CloudSessionSummary[] }>(
+      '/api/v1/cloud-browser/sessions',
+      { query: { limit: opts.limit } },
+    )
+    return res.sessions ?? []
+  }
+
+  /** Close a session, finalising the recording (if any) + releasing the
+   *  cloud-browser slot. Idempotent. No-op for local sessions
+   *  (target: 'local') — those don't have a slot to release. */
+  async close(sessionId: string): Promise<{ ok: boolean; proxyMB?: number }> {
+    // Local sessions are pure client-side handles — nothing to release.
+    if (sessionId.startsWith('local_')) return { ok: true }
+    return this.cbRequest(
+      `/api/v1/cloud-browser/sessions/${encodeURIComponent(sessionId)}`,
+      { method: 'DELETE' },
+    )
+  }
+}
+
+export class CloudBrowserResource {
+  readonly sessions: SessionsResource
+
+  constructor(private readonly http: HttpClient) {
+    this.sessions = new SessionsResource(http)
+  }
+
+  private cbAuth(): Record<string, string> {
+    const key = this.http.cloudBrowserKey
+    if (!key) throw new AuthError(MISSING_CB_KEY_MESSAGE)
+    return { 'x-api-key': key }
+  }
+
+  /**
+   * One-shot fetch through the cloud browser. Spins up a short-lived
+   * session, loads the page in real Chromium (so JS-rendered sites work),
+   * extracts the content, and tears down. Use this when you only need ONE
+   * page and don't want to manage Playwright yourself.
+   *
+   * ```ts
+   * const page = await px.cloudBrowser.fetch({
+   *   url: 'https://example.com/pricing',
+   *   format: 'markdown',                    // 'text' (default) | 'markdown' | 'html' | 'links'
+   *   waitForSelector: '.pricing-table',     // for JS-rendered content
+   *   selectors: ['.pricing-table .plan'],   // deterministic CSS extraction
+   * })
+   * // page.content, page.extracted, page.title, page.finalUrl …
+   * ```
+   */
+  async fetch(opts: CloudFetchOptions): Promise<CloudFetchResult> {
+    return this.http.request('/api/v1/cloud-browser/fetch', {
+      method: 'POST',
+      body: opts,
+      headers: this.cbAuth(),
+      timeoutMs: Math.max(90_000, (opts.timeoutMs ?? 30_000) + 30_000),
+    })
+  }
+
+  /**
+   * Search the web through the cloud browser and get structured results
+   * (title/url/snippet). Runs the query against DuckDuckGo's server-rendered
+   * HTML endpoint in a real browser — there is no engine choice today.
+   */
+  async search(opts: {
+    query: string
+    /** Max results, 1–25. Default 10. */
+    limit?: number
+    /** Route through a residential proxy. */
+    proxy?: boolean
+    /** Proxy exit country (with `proxy: true`), e.g. 'us'. */
+    country?: string
+  }): Promise<CloudSearchResult[]> {
+    const res = await this.http.request<{ query: string; results: CloudSearchResult[] }>(
+      '/api/v1/cloud-browser/search',
+      { method: 'POST', body: opts, headers: this.cbAuth(), timeoutMs: 90_000 },
+    )
+    return res.results ?? []
+  }
+}

package/src/resources/connectHub.ts

@@ -5,7 +5,7 @@
  * 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.connectHub.*` — 2,800+ integrations.
+ * `px.connectHub.*` — 3,000+ integrations.
  *
  * Browse + run actions from any of the Pipedream-backed apps
  * Prompteryx exposes via Connect Hub (Gmail, Sheets, Slack,

package/src/types.ts

@@ -510,7 +510,7 @@ export interface DiscoveredAction {
   example?: string
 }
 
-// ─── Connect Hub (2,800+ integrations) ───────────────────────────────────
+// ─── Connect Hub (3,000+ integrations) ───────────────────────────────────
 
 export interface ConnectHubAppSummary {
   /** Pipedream slug ('gmail', 'google-sheets', ...). */