@skyvern/client 1.0.3 → 1.0.10

package/dist/cjs/core/file/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./file.js"), exports);
+__exportStar(require("./types.js"), exports);

package/dist/cjs/core/file/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A file that can be uploaded. Can be a file-like object (stream, buffer, blob, etc.),
+ * a path to a file, or an object with a file-like object and metadata.
+ */
+export type Uploadable = Uploadable.FileLike | Uploadable.FromPath | Uploadable.WithMetadata;
+export declare namespace Uploadable {
+    /**
+     * Various file-like objects that can be used to upload a file.
+     */
+    type FileLike = ArrayBuffer | ArrayBufferLike | ArrayBufferView | Uint8Array | import("buffer").Buffer | import("buffer").Blob | import("buffer").File | import("stream").Readable | import("stream/web").ReadableStream | globalThis.Blob | globalThis.File | ReadableStream;
+    /**
+     * A file path with optional metadata, used for uploading a file from the file system.
+     */
+    type FromPath = {
+        /** The path to the file to upload */
+        path: string;
+        /**
+         * Optional override for the file name (defaults to basename of path).
+         * This is used to set the `Content-Disposition` header in upload requests.
+         */
+        filename?: string;
+        /**
+         * Optional MIME type of the file (e.g., 'image/jpeg', 'text/plain').
+         * This is used to set the `Content-Type` header in upload requests.
+         */
+        contentType?: string;
+        /**
+         * Optional file size in bytes.
+         * If not provided, the file size will be determined from the file system.
+         * The content length is used to set the `Content-Length` header in upload requests.
+         */
+        contentLength?: number;
+    };
+    /**
+     * A file-like object with metadata, used for uploading files.
+     */
+    type WithMetadata = {
+        /** The file data */
+        data: FileLike;
+        /**
+         * Optional override for the file name (defaults to basename of path).
+         * This is used to set the `Content-Disposition` header in upload requests.
+         */
+        filename?: string;
+        /**
+         * Optional MIME type of the file (e.g., 'image/jpeg', 'text/plain').
+         * This is used to set the `Content-Type` header in upload requests.
+         *
+         * If not provided, the content type may be determined from the data itself.
+         * * If the data is a `File`, `Blob`, or similar, the content type will be determined from the file itself, if the type is set.
+         * * Any other data type will not have a content type set, and the upload request will use `Content-Type: application/octet-stream` instead.
+         */
+        contentType?: string;
+        /**
+         * Optional file size in bytes.
+         * The content length is used to set the `Content-Length` header in upload requests.
+         * If the content length is not provided and cannot be determined, the upload request will not include the `Content-Length` header, but will use `Transfer-Encoding: chunked` instead.
+         *
+         * If not provided, the file size will be determined depending on the data type.
+         * * If the data is of type `fs.ReadStream` (`createReadStream`), the size will be determined from the file system.
+         * * If the data is a `Buffer`, `ArrayBuffer`, `Uint8Array`, `Blob`, `File`, or similar, the size will be determined from the data itself.
+         * * If the data is a `Readable` or `ReadableStream`, the size will not be determined.
+         */
+        contentLength?: number;
+    };
+}

package/dist/cjs/core/file/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/core/form-data-utils/FormDataWrapper.d.ts

@@ -0,0 +1,15 @@
+import { type Uploadable } from "../../core/file/index.js";
+interface FormDataRequest<Body> {
+    body: Body;
+    headers: Record<string, string>;
+    duplex?: "half";
+}
+export declare function newFormData(): Promise<FormDataWrapper>;
+export declare class FormDataWrapper {
+    private fd;
+    setup(): Promise<void>;
+    append(key: string, value: unknown): void;
+    appendFile(key: string, value: Uploadable): Promise<void>;
+    getRequest(): FormDataRequest<FormData>;
+}
+export {};

package/dist/cjs/core/form-data-utils/FormDataWrapper.js

@@ -0,0 +1,185 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+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 __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FormDataWrapper = void 0;
+exports.newFormData = newFormData;
+const index_js_1 = require("../../core/file/index.js");
+const json_js_1 = require("../../core/json.js");
+const index_js_2 = require("../runtime/index.js");
+function newFormData() {
+    return __awaiter(this, void 0, void 0, function* () {
+        return new FormDataWrapper();
+    });
+}
+class FormDataWrapper {
+    constructor() {
+        this.fd = new FormData();
+    }
+    setup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // noop
+        });
+    }
+    append(key, value) {
+        this.fd.append(key, String(value));
+    }
+    appendFile(key, value) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { data, filename, contentType } = yield (0, index_js_1.toMultipartDataPart)(value);
+            const blob = yield convertToBlob(data, contentType);
+            if (filename) {
+                this.fd.append(key, blob, filename);
+            }
+            else {
+                this.fd.append(key, blob);
+            }
+        });
+    }
+    getRequest() {
+        return {
+            body: this.fd,
+            headers: {},
+            duplex: "half",
+        };
+    }
+}
+exports.FormDataWrapper = FormDataWrapper;
+function isStreamLike(value) {
+    return typeof value === "object" && value != null && ("read" in value || "pipe" in value);
+}
+function isReadableStream(value) {
+    return typeof value === "object" && value != null && "getReader" in value;
+}
+function isBuffer(value) {
+    return typeof Buffer !== "undefined" && Buffer.isBuffer && Buffer.isBuffer(value);
+}
+function isArrayBufferView(value) {
+    return ArrayBuffer.isView(value);
+}
+function streamToBuffer(stream) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, stream_1, stream_1_1;
+        var _b, e_1, _c, _d;
+        if (index_js_2.RUNTIME.type === "node") {
+            const { Readable } = yield Promise.resolve().then(() => __importStar(require("stream")));
+            if (stream instanceof Readable) {
+                const chunks = [];
+                try {
+                    for (_a = true, stream_1 = __asyncValues(stream); stream_1_1 = yield stream_1.next(), _b = stream_1_1.done, !_b; _a = true) {
+                        _d = stream_1_1.value;
+                        _a = false;
+                        const chunk = _d;
+                        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                    }
+                }
+                catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                finally {
+                    try {
+                        if (!_a && !_b && (_c = stream_1.return)) yield _c.call(stream_1);
+                    }
+                    finally { if (e_1) throw e_1.error; }
+                }
+                return Buffer.concat(chunks);
+            }
+        }
+        if (isReadableStream(stream)) {
+            const reader = stream.getReader();
+            const chunks = [];
+            try {
+                while (true) {
+                    const { done, value } = yield reader.read();
+                    if (done)
+                        break;
+                    chunks.push(value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+            const result = new Uint8Array(totalLength);
+            let offset = 0;
+            for (const chunk of chunks) {
+                result.set(chunk, offset);
+                offset += chunk.length;
+            }
+            return Buffer.from(result);
+        }
+        throw new Error(`Unsupported stream type: ${typeof stream}. Expected Node.js Readable stream or Web ReadableStream.`);
+    });
+}
+function convertToBlob(value, contentType) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (isStreamLike(value) || isReadableStream(value)) {
+            const buffer = yield streamToBuffer(value);
+            return new Blob([buffer], { type: contentType });
+        }
+        if (value instanceof Blob) {
+            return value;
+        }
+        if (isBuffer(value)) {
+            return new Blob([value], { type: contentType });
+        }
+        if (value instanceof ArrayBuffer) {
+            return new Blob([value], { type: contentType });
+        }
+        if (isArrayBufferView(value)) {
+            return new Blob([value], { type: contentType });
+        }
+        if (typeof value === "string") {
+            return new Blob([value], { type: contentType });
+        }
+        if (typeof value === "object" && value !== null) {
+            return new Blob([(0, json_js_1.toJson)(value)], { type: contentType !== null && contentType !== void 0 ? contentType : "application/json" });
+        }
+        return new Blob([String(value)], { type: contentType });
+    });
+}

package/dist/cjs/core/form-data-utils/encodeAsFormParameter.d.ts

@@ -0,0 +1 @@
+export declare function encodeAsFormParameter(value: unknown): Record<string, string>;

package/dist/cjs/core/form-data-utils/encodeAsFormParameter.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeAsFormParameter = encodeAsFormParameter;
+const qs_js_1 = require("../url/qs.js");
+function encodeAsFormParameter(value) {
+    const stringified = (0, qs_js_1.toQueryString)(value, { encode: false });
+    const keyValuePairs = stringified.split("&").map((pair) => {
+        const [key, value] = pair.split("=");
+        return [key, value];
+    });
+    return Object.fromEntries(keyValuePairs);
+}

package/dist/cjs/core/form-data-utils/index.d.ts

@@ -0,0 +1,2 @@
+export { encodeAsFormParameter } from "./encodeAsFormParameter.js";
+export * from "./FormDataWrapper.js";

package/dist/cjs/core/form-data-utils/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeAsFormParameter = void 0;
+var encodeAsFormParameter_js_1 = require("./encodeAsFormParameter.js");
+Object.defineProperty(exports, "encodeAsFormParameter", { enumerable: true, get: function () { return encodeAsFormParameter_js_1.encodeAsFormParameter; } });
+__exportStar(require("./FormDataWrapper.js"), exports);

package/dist/cjs/core/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./fetcher/index.js";
+export * as file from "./file/index.js";
+export * from "./form-data-utils/index.js";
 export * from "./runtime/index.js";
 export * as url from "./url/index.js";

package/dist/cjs/core/index.js

@@ -36,7 +36,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.url = void 0;
+exports.url = exports.file = void 0;
 __exportStar(require("./fetcher/index.js"), exports);
+exports.file = __importStar(require("./file/index.js"));
+__exportStar(require("./form-data-utils/index.js"), exports);
 __exportStar(require("./runtime/index.js"), exports);
 exports.url = __importStar(require("./url/index.js"));

package/dist/cjs/exports.d.ts

@@ -0,0 +1 @@
+export * from "./core/exports.js";

package/dist/cjs/exports.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./core/exports.js"), exports);

package/dist/cjs/index.d.ts

@@ -3,5 +3,6 @@ export type { BaseClientOptions, BaseRequestOptions } from "./BaseClient.js";
 export { SkyvernClient } from "./Client.js";
 export { SkyvernEnvironment } from "./environments.js";
 export { SkyvernError, SkyvernTimeoutError } from "./errors/index.js";
+export * from "./exports.js";
 export { Skyvern, SkyvernBrowser, SkyvernBrowserPageAgent, SkyvernBrowserPageAi } from "./library/index.js";
 export type { SkyvernOptions, SkyvernBrowserPage } from "./library/index.js";

package/dist/cjs/index.js

@@ -32,6 +32,9 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SkyvernBrowserPageAi = exports.SkyvernBrowserPageAgent = exports.SkyvernBrowser = exports.Skyvern = exports.SkyvernTimeoutError = exports.SkyvernError = exports.SkyvernEnvironment = exports.SkyvernClient = exports.SkyvernApi = void 0;
 exports.SkyvernApi = __importStar(require("./api/index.js"));
@@ -42,6 +45,7 @@ Object.defineProperty(exports, "SkyvernEnvironment", { enumerable: true, get: fu
 var index_js_1 = require("./errors/index.js");
 Object.defineProperty(exports, "SkyvernError", { enumerable: true, get: function () { return index_js_1.SkyvernError; } });
 Object.defineProperty(exports, "SkyvernTimeoutError", { enumerable: true, get: function () { return index_js_1.SkyvernTimeoutError; } });
+__exportStar(require("./exports.js"), exports);
 var index_js_2 = require("./library/index.js");
 Object.defineProperty(exports, "Skyvern", { enumerable: true, get: function () { return index_js_2.Skyvern; } });
 Object.defineProperty(exports, "SkyvernBrowser", { enumerable: true, get: function () { return index_js_2.SkyvernBrowser; } });

package/dist/cjs/library/Skyvern.js

@@ -60,6 +60,9 @@ const environments_js_1 = require("../environments.js");
 const SkyvernBrowser_js_1 = require("./SkyvernBrowser.js");
 const logger_js_1 = require("./logger.js");
 const core = __importStar(require("../core/index.js"));
+function _getBrowserSessionUrl(browserSessionId) {
+    return `https://app.skyvern.com/browser-session/${browserSessionId}`;
+}
 /**
  * Main entry point for the Skyvern SDK.
  *
@@ -179,7 +182,12 @@ class Skyvern extends Client_js_1.SkyvernClient {
                 timeout: options === null || options === void 0 ? void 0 : options.timeout,
                 proxy_location: options === null || options === void 0 ? void 0 : options.proxyLocation,
             });
-            logger_js_1.LOG.info("Launched new cloud browser session", { browser_session_id: browserSession.browser_session_id });
+            if (this._environment === environments_js_1.SkyvernEnvironment.Cloud) {
+                logger_js_1.LOG.info("Launched new cloud browser session", { url: _getBrowserSessionUrl(browserSession.browser_session_id) });
+            }
+            else {
+                logger_js_1.LOG.info("Launched new cloud browser session", { browser_session_id: browserSession.browser_session_id });
+            }
             return this._connectToCloudBrowserSession(browserSession);
         });
     }
@@ -194,7 +202,12 @@ class Skyvern extends Client_js_1.SkyvernClient {
         return __awaiter(this, void 0, void 0, function* () {
             this._ensureCloudEnvironment();
             const browserSession = yield this.getBrowserSession(browserSessionId);
-            logger_js_1.LOG.info("Connecting to existing cloud browser session", { browser_session_id: browserSession.browser_session_id });
+            if (this._environment === environments_js_1.SkyvernEnvironment.Cloud) {
+                logger_js_1.LOG.info("Connecting to existing cloud browser session", { url: _getBrowserSessionUrl(browserSession.browser_session_id) });
+            }
+            else {
+                logger_js_1.LOG.info("Connecting to existing cloud browser session", { browser_session_id: browserSession.browser_session_id });
+            }
             return this._connectToCloudBrowserSession(browserSession);
         });
     }
@@ -218,17 +231,23 @@ class Skyvern extends Client_js_1.SkyvernClient {
             this._ensureCloudEnvironment();
             const browserSessions = yield this.getBrowserSessions();
             const browserSession = browserSessions
-                .filter((s) => s.runnable_id == null)
+                .filter((s) => s.runnable_id == null && s.started_at != null && s.browser_address != null)
                 .sort((a, b) => {
-                const aTime = a.started_at ? new Date(a.started_at).getTime() : 0;
-                const bTime = b.started_at ? new Date(b.started_at).getTime() : 0;
+                const aTime = new Date(a.started_at).getTime();
+                const bTime = new Date(b.started_at).getTime();
                 return bTime - aTime;
-            })[0];
+            })
+                .at(0);
             if (!browserSession) {
                 logger_js_1.LOG.info("No existing cloud browser session found, launching a new session");
                 return this.launchCloudBrowser(options);
             }
-            logger_js_1.LOG.info("Reusing existing cloud browser session", { browser_session_id: browserSession.browser_session_id });
+            if (this._environment === environments_js_1.SkyvernEnvironment.Cloud) {
+                logger_js_1.LOG.info("Reusing existing cloud browser session", { url: _getBrowserSessionUrl(browserSession.browser_session_id) });
+            }
+            else {
+                logger_js_1.LOG.info("Reusing existing cloud browser session", { browser_session_id: browserSession.browser_session_id });
+            }
             return this._connectToCloudBrowserSession(browserSession);
         });
     }

package/dist/cjs/library/SkyvernBrowserPage.d.ts

@@ -30,20 +30,103 @@ export declare class SkyvernBrowserPageCore {
     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>;
-    selectOption(selector: string, values: string | string[], options?: Parameters<Page["selectOption"]>[2]): Promise<string[]>;
+    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<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.
      *