@skyvern/client 1.0.2 → 1.0.6

package/dist/esm/library/SkyvernBrowserPage.d.mts

@@ -0,0 +1,152 @@
+import type { Page } from "playwright";
+import type { SkyvernBrowser } from "./SkyvernBrowser.mjs";
+import { SkyvernBrowserPageAgent } from "./SkyvernBrowserPageAgent.mjs";
+/**
+ * A browser page wrapper that combines Playwright's page API with Skyvern's AI capabilities.
+ *
+ * This class provides a unified interface for both traditional browser automation (via Playwright)
+ * and AI-powered task execution (via Skyvern). It exposes standard page methods like click, fill,
+ * goto, etc., while also providing access to Skyvern's task and workflow execution through the
+ * `agent` attribute.
+ *
+ * @example
+ * ```typescript
+ * // Use standard Playwright methods
+ * await page.goto("https://example.com");
+ * await page.fill("#username", "user@example.com");
+ * await page.click("#login-button");
+ *
+ * // Or use Skyvern's AI capabilities
+ * await page.agent.runTask("Fill out the contact form and submit it");
+ * ```
+ */
+export declare class SkyvernBrowserPageCore {
+    private readonly _browser;
+    private readonly _page;
+    private readonly _ai;
+    readonly agent: SkyvernBrowserPageAgent;
+    private readonly _proxy;
+    private constructor();
+    static create(browser: SkyvernBrowser, page: Page): SkyvernBrowserPage;
+    get page(): Page;
+    get browser(): SkyvernBrowser;
+    /**
+     * Click an element using a CSS selector, AI-powered prompt matching, or both.
+     *
+     * This method supports three modes:
+     * - **Selector-based**: Click the element matching the CSS selector
+     * - **AI-powered**: Use natural language to describe which element to click
+     * - **Fallback mode**: Try the selector first, fall back to AI if it fails
+     *
+     * @param selector - CSS selector for the target element.
+     * @param options - Click options including prompt.
+     * @param options.prompt - Natural language description of which element to click.
+     *
+     * @example
+     * ```typescript
+     * // Click using a CSS selector
+     * await page.click("#open-invoice-button");
+     *
+     * // Click using AI with natural language
+     * await page.click({ prompt: "Click on the 'Open Invoice' button" });
+     *
+     * // Try selector first, fall back to AI if selector fails
+     * await page.click("#open-invoice-button", { prompt: "Click on the 'Open Invoice' button" });
+     * ```
+     */
+    click(selector: string, options?: Parameters<Page["click"]>[1]): Promise<void>;
+    click(options: {
+        prompt: string;
+    } & Partial<Parameters<Page["click"]>[1]>): Promise<void>;
+    click(selector: string, options: {
+        prompt: string;
+    } & Partial<Parameters<Page["click"]>[1]>): Promise<void>;
+    /**
+     * Fill an input field using a CSS selector, AI-powered prompt matching, or both.
+     *
+     * This method supports three modes:
+     * - **Selector-based**: Fill the input field with a value using CSS selector
+     * - **AI-powered**: Use natural language prompt (AI extracts value from prompt or uses provided value)
+     * - **Fallback mode**: Try the selector first, fall back to AI if it fails
+     *
+     * @param selector - CSS selector for the target input element.
+     * @param value - The text value to input into the field.
+     * @param options - Fill options including prompt.
+     * @param options.prompt - Natural language description of which field to fill and what value.
+     *
+     * @example
+     * ```typescript
+     * // Fill using selector and value
+     * await page.fill("#email-input", "user@example.com");
+     *
+     * // Fill using AI with natural language
+     * await page.fill({ prompt: "Fill 'user@example.com' in the email address field" });
+     *
+     * // Try selector first, fall back to AI if selector fails
+     * await page.fill("#email-input", "user@example.com", { prompt: "Fill the email address" });
+     * ```
+     */
+    fill(selector: string, value: string, options?: Parameters<Page["fill"]>[2]): Promise<void>;
+    fill(options: {
+        prompt: string;
+        value?: string;
+    } & Partial<Parameters<Page["fill"]>[2]>): Promise<void>;
+    fill(selector: string, value: string, options: {
+        prompt: string;
+    } & Partial<Parameters<Page["fill"]>[2]>): Promise<void>;
+    /**
+     * Select an option from a dropdown using a CSS selector, AI-powered prompt matching, or both.
+     *
+     * This method supports three modes:
+     * - **Selector-based**: Select the option with a value using CSS selector
+     * - **AI-powered**: Use natural language prompt (AI extracts value from prompt or uses provided value)
+     * - **Fallback mode**: Try the selector first, fall back to AI if it fails
+     *
+     * @param selector - CSS selector for the target select/dropdown element.
+     * @param value - The option value to select.
+     * @param options - Select options including prompt.
+     * @param options.prompt - Natural language description of which option to select.
+     *
+     * @example
+     * ```typescript
+     * // Select using selector and value
+     * await page.selectOption("#country", "us");
+     *
+     * // Select using AI with natural language
+     * await page.selectOption({ prompt: "Select 'United States' from the country dropdown" });
+     *
+     * // Try selector first, fall back to AI if selector fails
+     * await page.selectOption("#country", "us", { prompt: "Select United States from country" });
+     * ```
+     */
+    selectOption(selector: string, values: string | string[], options?: Parameters<Page["selectOption"]>[2]): Promise<void>;
+    selectOption(options: {
+        prompt: string;
+        value?: string;
+    } & Partial<Parameters<Page["selectOption"]>[2]>): Promise<void>;
+    selectOption(selector: string, values: string | string[], options: {
+        prompt: string;
+    } & Partial<Parameters<Page["selectOption"]>[2]>): Promise<void>;
+    /**
+     * Perform an action on the page using AI based on a natural language prompt.
+     *
+     * @param prompt - Natural language description of the action to perform.
+     *
+     * @example
+     * ```typescript
+     * // Simple action
+     * await page.act("Click the login button");
+     * ```
+     */
+    act(prompt: string): Promise<void>;
+    extract(options: {
+        prompt: string;
+        schema?: Record<string, unknown> | unknown[] | string;
+        errorCodeMapping?: Record<string, string>;
+        intention?: string;
+        data?: string | Record<string, unknown>;
+    }): Promise<Record<string, unknown> | unknown[] | string | null>;
+    validate(prompt: string, model?: Record<string, unknown> | string): Promise<boolean>;
+    prompt(prompt: string, schema?: Record<string, unknown>, model?: Record<string, unknown> | string): Promise<Record<string, unknown> | unknown[] | string | null>;
+}
+export type SkyvernBrowserPage = SkyvernBrowserPageCore & Page;

package/dist/esm/library/SkyvernBrowserPage.mjs

@@ -0,0 +1,271 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { SkyvernBrowserPageAgent } from "./SkyvernBrowserPageAgent.mjs";
+import { SkyvernBrowserPageAi } from "./SkyvernBrowserPageAi.mjs";
+/**
+ * A browser page wrapper that combines Playwright's page API with Skyvern's AI capabilities.
+ *
+ * This class provides a unified interface for both traditional browser automation (via Playwright)
+ * and AI-powered task execution (via Skyvern). It exposes standard page methods like click, fill,
+ * goto, etc., while also providing access to Skyvern's task and workflow execution through the
+ * `agent` attribute.
+ *
+ * @example
+ * ```typescript
+ * // Use standard Playwright methods
+ * await page.goto("https://example.com");
+ * await page.fill("#username", "user@example.com");
+ * await page.click("#login-button");
+ *
+ * // Or use Skyvern's AI capabilities
+ * await page.agent.runTask("Fill out the contact form and submit it");
+ * ```
+ */
+export class SkyvernBrowserPageCore {
+    constructor(browser, page) {
+        this._browser = browser;
+        this._page = page;
+        this._ai = new SkyvernBrowserPageAi(browser, page);
+        this.agent = new SkyvernBrowserPageAgent(browser, page);
+        this._proxy = new Proxy(this, {
+            get(target, prop, receiver) {
+                if (prop in target) {
+                    return Reflect.get(target, prop, receiver);
+                }
+                const value = Reflect.get(target._page, prop, target._page);
+                if (typeof value === "function") {
+                    return value.bind(target._page);
+                }
+                return value;
+            },
+        });
+    }
+    static create(browser, page) {
+        const instance = new SkyvernBrowserPageCore(browser, page);
+        return instance._proxy;
+    }
+    get page() {
+        return this._page;
+    }
+    get browser() {
+        return this._browser;
+    }
+    click(selectorOrOptions, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let selector;
+            let prompt;
+            let clickOptions = {};
+            let timeout;
+            // Parse arguments
+            if (typeof selectorOrOptions === "string") {
+                selector = selectorOrOptions;
+                if (options && typeof options === "object") {
+                    const _a = options, { prompt: p, timeout: t } = _a, rest = __rest(_a, ["prompt", "timeout"]);
+                    prompt = p;
+                    timeout = t;
+                    clickOptions = rest;
+                }
+                else if (options) {
+                    clickOptions = options;
+                }
+            }
+            else if (selectorOrOptions && typeof selectorOrOptions === "object") {
+                const { prompt: p, timeout: t } = selectorOrOptions, rest = __rest(selectorOrOptions, ["prompt", "timeout"]);
+                prompt = p;
+                timeout = t;
+                clickOptions = rest;
+            }
+            if (!selector && !prompt) {
+                throw new Error("Missing input: pass a selector and/or a prompt.");
+            }
+            // Try to click the element with the original selector first
+            let errorToRaise;
+            if (selector) {
+                try {
+                    yield this._page.click(selector, Object.assign(Object.assign({}, clickOptions), { timeout }));
+                    return;
+                }
+                catch (error) {
+                    errorToRaise = error;
+                    selector = undefined;
+                }
+            }
+            // If the original selector doesn't work, try to click the element with the AI generated selector
+            if (prompt) {
+                yield this._ai.aiClick({
+                    intention: prompt,
+                    data: Object.keys(clickOptions).length > 0 ? clickOptions : undefined,
+                    timeout,
+                });
+                return;
+            }
+            if (errorToRaise) {
+                throw errorToRaise;
+            }
+        });
+    }
+    fill(selectorOrOptions, value, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let selector;
+            let fillValue;
+            let prompt;
+            let fillOptions = {};
+            let timeout;
+            if (typeof selectorOrOptions === "string") {
+                selector = selectorOrOptions;
+                fillValue = value;
+                if (options && typeof options === "object") {
+                    const _a = options, { prompt: p, timeout: t } = _a, rest = __rest(_a, ["prompt", "timeout"]);
+                    prompt = p;
+                    timeout = t;
+                    fillOptions = rest;
+                }
+                else if (options) {
+                    fillOptions = options;
+                }
+            }
+            else if (selectorOrOptions && typeof selectorOrOptions === "object") {
+                const { prompt: p, value: v, timeout: t } = selectorOrOptions, rest = __rest(selectorOrOptions, ["prompt", "value", "timeout"]);
+                prompt = p;
+                fillValue = v;
+                timeout = t;
+                fillOptions = rest;
+            }
+            if (!selector && !prompt) {
+                throw new Error("Missing input: pass a selector and/or a prompt.");
+            }
+            let errorToRaise;
+            if (selector && fillValue !== undefined) {
+                try {
+                    yield this._page.fill(selector, fillValue, Object.assign(Object.assign({}, fillOptions), { timeout }));
+                    return;
+                }
+                catch (error) {
+                    errorToRaise = error;
+                    selector = undefined;
+                }
+            }
+            if (prompt) {
+                yield this._ai.aiInputText({
+                    value: fillValue,
+                    intention: prompt,
+                    data: Object.keys(fillOptions).length > 0 ? fillOptions : undefined,
+                    timeout,
+                });
+                return;
+            }
+            if (errorToRaise) {
+                throw errorToRaise;
+            }
+        });
+    }
+    selectOption(selectorOrOptions, values, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let selector;
+            let selectValue;
+            let prompt;
+            let selectOptions = {};
+            let timeout;
+            // Parse arguments
+            if (typeof selectorOrOptions === "string") {
+                selector = selectorOrOptions;
+                selectValue = values;
+                if (options && typeof options === "object") {
+                    const _a = options, { prompt: p, timeout: t } = _a, rest = __rest(_a, ["prompt", "timeout"]);
+                    prompt = p;
+                    timeout = t;
+                    selectOptions = rest;
+                }
+                else if (options) {
+                    selectOptions = options;
+                }
+            }
+            else if (selectorOrOptions && typeof selectorOrOptions === "object") {
+                const { prompt: p, value: v, timeout: t } = selectorOrOptions, rest = __rest(selectorOrOptions, ["prompt", "value", "timeout"]);
+                prompt = p;
+                selectValue = v;
+                timeout = t;
+                selectOptions = rest;
+            }
+            if (!selector && !prompt) {
+                throw new Error("Missing input: pass a selector and/or a prompt.");
+            }
+            // Try to select the option with the original selector first
+            let errorToRaise;
+            if (selector && selectValue !== undefined) {
+                try {
+                    yield this._page.selectOption(selector, selectValue, Object.assign(Object.assign({}, selectOptions), { timeout }));
+                    return;
+                }
+                catch (error) {
+                    errorToRaise = error;
+                    selector = undefined;
+                }
+            }
+            // If the original selector doesn't work, try to select the option with AI
+            if (prompt) {
+                yield this._ai.aiSelectOption({
+                    value: typeof selectValue === "string" ? selectValue : selectValue === null || selectValue === void 0 ? void 0 : selectValue[0],
+                    intention: prompt,
+                    data: Object.keys(selectOptions).length > 0 ? selectOptions : undefined,
+                    timeout,
+                });
+                return;
+            }
+            if (errorToRaise) {
+                throw errorToRaise;
+            }
+        });
+    }
+    /**
+     * Perform an action on the page using AI based on a natural language prompt.
+     *
+     * @param prompt - Natural language description of the action to perform.
+     *
+     * @example
+     * ```typescript
+     * // Simple action
+     * await page.act("Click the login button");
+     * ```
+     */
+    act(prompt) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this._ai.aiAct(prompt);
+        });
+    }
+    extract(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this._ai.aiExtract(options);
+        });
+    }
+    validate(prompt, model) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const normalizedModel = typeof model === "string" ? { modelName: model } : model;
+            return this._ai.aiValidate({ prompt, model: normalizedModel });
+        });
+    }
+    prompt(prompt, schema, model) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const normalizedModel = typeof model === "string" ? { modelName: model } : model;
+            return this._ai.aiPrompt({ prompt, schema, model: normalizedModel });
+        });
+    }
+}

package/dist/esm/library/SkyvernBrowserPageAgent.d.mts

@@ -0,0 +1,183 @@
+import type { Page } from "playwright";
+import type * as Skyvern from "../api/index.mjs";
+import type { SkyvernBrowser } from "./SkyvernBrowser.mjs";
+/**
+ * Provides methods to run Skyvern tasks and workflows in the context of a browser page.
+ *
+ * This class enables executing AI-powered browser automation tasks while sharing the
+ * context of an existing browser page. It supports running custom tasks, login workflows,
+ * and pre-defined workflows with automatic waiting for completion.
+ */
+export declare class SkyvernBrowserPageAgent {
+    private readonly _browser;
+    private readonly _page;
+    constructor(browser: SkyvernBrowser, page: Page);
+    /**
+     * Run a task in the context of this page and wait for it to finish.
+     *
+     * @param prompt - Natural language description of the task to perform.
+     * @param options - Optional configuration
+     * @param options.engine - The execution engine to use. Defaults to skyvern_v2.
+     * @param options.model - LLM model configuration options.
+     * @param options.url - URL to navigate to. If not provided, uses the current page URL.
+     * @param options.webhookUrl - URL to receive webhook notifications about task progress.
+     * @param options.totpIdentifier - Identifier for TOTP (Time-based One-Time Password) authentication.
+     * @param options.totpUrl - URL to fetch TOTP codes from.
+     * @param options.title - Human-readable title for this task run.
+     * @param options.errorCodeMapping - Mapping of error codes to custom error messages.
+     * @param options.dataExtractionSchema - Schema defining what data to extract from the page.
+     * @param options.maxSteps - Maximum number of steps the agent can take.
+     * @param options.timeout - Maximum time in seconds to wait for task completion.
+     *
+     * @returns TaskRunResponse containing the task execution results.
+     */
+    runTask(prompt: string, options?: {
+        engine?: Skyvern.RunEngine;
+        model?: Record<string, unknown>;
+        url?: string;
+        webhookUrl?: string;
+        totpIdentifier?: string;
+        totpUrl?: string;
+        title?: string;
+        errorCodeMapping?: Record<string, string>;
+        dataExtractionSchema?: Record<string, unknown> | string;
+        maxSteps?: number;
+        timeout?: number;
+    }): Promise<Skyvern.TaskRunResponse>;
+    /**
+     * Run a login task in the context of this page and wait for it to finish.
+     *
+     * This method has multiple overloaded signatures for different credential types:
+     *
+     * 1. Skyvern credentials:
+     *    ```typescript
+     *    await page.agent.login("skyvern", {
+     *        credentialId: "cred_123"
+     *    });
+     *    ```
+     *
+     * 2. Bitwarden credentials:
+     *    ```typescript
+     *    await page.agent.login("bitwarden", {
+     *        bitwardenItemId: "item_id",
+     *        bitwardenCollectionId: "collection_id"
+     *    });
+     *    ```
+     *
+     * 3. 1Password credentials:
+     *    ```typescript
+     *    await page.agent.login("1password", {
+     *        onepasswordVaultId: "vault_id",
+     *        onepasswordItemId: "item_id"
+     *    });
+     *    ```
+     *
+     * 4. Azure Vault credentials:
+     *    ```typescript
+     *    await page.agent.login("azure_vault", {
+     *        azureVaultName: "vault_name",
+     *        azureVaultUsernameKey: "username_key",
+     *        azureVaultPasswordKey: "password_key",
+     *    });
+     *    ```
+     */
+    login(credentialType: "skyvern", options: {
+        credentialId: string;
+        url?: string;
+        prompt?: string;
+        webhookUrl?: string;
+        totpIdentifier?: string;
+        totpUrl?: string;
+        extraHttpHeaders?: Record<string, string>;
+        timeout?: number;
+    }): Promise<Skyvern.WorkflowRunResponse>;
+    login(credentialType: "bitwarden", options: {
+        bitwardenItemId: string;
+        bitwardenCollectionId?: string;
+        url?: string;
+        prompt?: string;
+        webhookUrl?: string;
+        totpIdentifier?: string;
+        totpUrl?: string;
+        extraHttpHeaders?: Record<string, string>;
+        timeout?: number;
+    }): Promise<Skyvern.WorkflowRunResponse>;
+    login(credentialType: "1password", options: {
+        onepasswordVaultId: string;
+        onepasswordItemId: string;
+        url?: string;
+        prompt?: string;
+        webhookUrl?: string;
+        totpIdentifier?: string;
+        totpUrl?: string;
+        extraHttpHeaders?: Record<string, string>;
+        timeout?: number;
+    }): Promise<Skyvern.WorkflowRunResponse>;
+    login(credentialType: "azure_vault", options: {
+        azureVaultName: string;
+        azureVaultUsernameKey: string;
+        azureVaultPasswordKey: string;
+        azureVaultTotpSecretKey?: string;
+        url?: string;
+        prompt?: string;
+        webhookUrl?: string;
+        totpIdentifier?: string;
+        totpUrl?: string;
+        extraHttpHeaders?: Record<string, string>;
+        timeout?: number;
+    }): Promise<Skyvern.WorkflowRunResponse>;
+    /**
+     * Run a file download task in the context of this page and wait for it to finish.
+     *
+     * @param prompt - Instructions for navigating to and downloading the file.
+     * @param options - Optional configuration
+     * @param options.url - URL to navigate to for file download. If not provided, uses the current page URL.
+     * @param options.downloadSuffix - Suffix or complete filename for the downloaded file.
+     * @param options.downloadTimeout - Timeout in seconds for the download operation.
+     * @param options.maxStepsPerRun - Maximum number of steps to execute.
+     * @param options.webhookUrl - URL to receive webhook notifications about download progress.
+     * @param options.totpIdentifier - Identifier for TOTP authentication.
+     * @param options.totpUrl - URL to fetch TOTP codes from.
+     * @param options.extraHttpHeaders - Additional HTTP headers to include in requests.
+     * @param options.timeout - Maximum time in seconds to wait for download completion.
+     *
+     * @returns WorkflowRunResponse containing the file download workflow execution results.
+     */
+    downloadFiles(prompt: string, options?: {
+        url?: string;
+        downloadSuffix?: string;
+        downloadTimeout?: number;
+        maxStepsPerRun?: number;
+        webhookUrl?: string;
+        totpIdentifier?: string;
+        totpUrl?: string;
+        extraHttpHeaders?: Record<string, string>;
+        timeout?: number;
+    }): Promise<Skyvern.WorkflowRunResponse>;
+    /**
+     * Run a workflow in the context of this page and wait for it to finish.
+     *
+     * @param workflowId - ID of the workflow to execute.
+     * @param options - Optional configuration
+     * @param options.parameters - Dictionary of parameters to pass to the workflow.
+     * @param options.template - Whether this is a workflow template.
+     * @param options.title - Human-readable title for this workflow run.
+     * @param options.webhookUrl - URL to receive webhook notifications about workflow progress.
+     * @param options.totpUrl - URL to fetch TOTP codes from.
+     * @param options.totpIdentifier - Identifier for TOTP authentication.
+     * @param options.timeout - Maximum time in seconds to wait for workflow completion.
+     *
+     * @returns WorkflowRunResponse containing the workflow execution results.
+     */
+    runWorkflow(workflowId: string, options?: {
+        parameters?: Record<string, unknown>;
+        template?: boolean;
+        title?: string;
+        webhookUrl?: string;
+        totpUrl?: string;
+        totpIdentifier?: string;
+        timeout?: number;
+    }): Promise<Skyvern.WorkflowRunResponse>;
+    private _waitForRunCompletion;
+    private _getPageUrl;
+}