SDK: docs and improvements (#4310)
This commit is contained in:
Stanislav Novosad
committed by
GitHub
GitHub
parent
0d6a070a80
commit
5d2bb07371
@@ -63,74 +63,295 @@ export class SkyvernBrowserPageCore {
|
||||
return this._browser;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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" });
|
||||
* ```
|
||||
*/
|
||||
async click(selector: string, options?: Parameters<Page["click"]>[1]): Promise<void>;
|
||||
async click(options: { prompt: string } & Partial<Parameters<Page["click"]>[1]>): Promise<void>;
|
||||
async click(
|
||||
selectorOrOptions: string | ({ prompt: string } & Partial<Parameters<Page["click"]>[1]>),
|
||||
options?: Parameters<Page["click"]>[1],
|
||||
selector: string,
|
||||
options: { prompt: string } & Partial<Parameters<Page["click"]>[1]>,
|
||||
): Promise<void>;
|
||||
async click(
|
||||
selectorOrOptions?: string | ({ prompt: string } & Partial<Parameters<Page["click"]>[1]>),
|
||||
options?: Parameters<Page["click"]>[1] | ({ prompt?: string } & Partial<Parameters<Page["click"]>[1]>),
|
||||
): Promise<void> {
|
||||
let selector: string | undefined;
|
||||
let prompt: string | undefined;
|
||||
let clickOptions: Partial<Parameters<Page["click"]>[1]> = {};
|
||||
let timeout: number | undefined;
|
||||
|
||||
// Parse arguments
|
||||
if (typeof selectorOrOptions === "string") {
|
||||
return this._page.click(selectorOrOptions, options);
|
||||
} else {
|
||||
const { prompt, timeout, ...data } = selectorOrOptions;
|
||||
selector = selectorOrOptions;
|
||||
if (options && typeof options === "object") {
|
||||
const { prompt: p, timeout: t, ...rest } = options as {
|
||||
prompt?: string;
|
||||
timeout?: number;
|
||||
} & Partial<Parameters<Page["click"]>[1]>;
|
||||
prompt = p;
|
||||
timeout = t;
|
||||
clickOptions = rest;
|
||||
} else if (options) {
|
||||
clickOptions = options;
|
||||
}
|
||||
} else if (selectorOrOptions && typeof selectorOrOptions === "object") {
|
||||
const { prompt: p, timeout: t, ...rest } = selectorOrOptions;
|
||||
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: Error | undefined;
|
||||
if (selector) {
|
||||
try {
|
||||
await this._page.click(selector, { ...clickOptions, timeout });
|
||||
return;
|
||||
} catch (error) {
|
||||
errorToRaise = error as Error;
|
||||
selector = undefined;
|
||||
}
|
||||
}
|
||||
|
||||
// If the original selector doesn't work, try to click the element with the AI generated selector
|
||||
if (prompt) {
|
||||
await this._ai.aiClick({
|
||||
intention: prompt,
|
||||
data: Object.keys(clickOptions).length > 0 ? clickOptions : undefined,
|
||||
timeout,
|
||||
data: Object.keys(data).length > 0 ? data : undefined,
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
if (errorToRaise) {
|
||||
throw errorToRaise;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 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" });
|
||||
* ```
|
||||
*/
|
||||
async fill(selector: string, value: string, options?: Parameters<Page["fill"]>[2]): Promise<void>;
|
||||
async fill(options: { prompt: string; value?: string } & Partial<Parameters<Page["fill"]>[2]>): Promise<void>;
|
||||
async fill(
|
||||
selectorOrOptions: string | ({ prompt: string; value?: string } & Partial<Parameters<Page["fill"]>[2]>),
|
||||
selector: string,
|
||||
value: string,
|
||||
options: { prompt: string } & Partial<Parameters<Page["fill"]>[2]>,
|
||||
): Promise<void>;
|
||||
async fill(
|
||||
selectorOrOptions?: string | ({ prompt: string; value?: string } & Partial<Parameters<Page["fill"]>[2]>),
|
||||
value?: string,
|
||||
options?: Parameters<Page["fill"]>[2],
|
||||
options?: Parameters<Page["fill"]>[2] | ({ prompt?: string } & Partial<Parameters<Page["fill"]>[2]>),
|
||||
): Promise<void> {
|
||||
let selector: string | undefined;
|
||||
let fillValue: string | undefined;
|
||||
let prompt: string | undefined;
|
||||
let fillOptions: Partial<Parameters<Page["fill"]>[2]> = {};
|
||||
let timeout: number | undefined;
|
||||
|
||||
if (typeof selectorOrOptions === "string") {
|
||||
if (value === undefined) {
|
||||
throw new Error("value is required when selector is provided");
|
||||
selector = selectorOrOptions;
|
||||
fillValue = value;
|
||||
if (options && typeof options === "object") {
|
||||
const { prompt: p, timeout: t, ...rest } = options as {
|
||||
prompt?: string;
|
||||
timeout?: number;
|
||||
} & Partial<Parameters<Page["fill"]>[2]>;
|
||||
prompt = p;
|
||||
timeout = t;
|
||||
fillOptions = rest;
|
||||
} else if (options) {
|
||||
fillOptions = options;
|
||||
}
|
||||
return this._page.fill(selectorOrOptions, value, options);
|
||||
} else {
|
||||
const { prompt, value: fillValue, timeout, ...data } = selectorOrOptions;
|
||||
} else if (selectorOrOptions && typeof selectorOrOptions === "object") {
|
||||
const { prompt: p, value: v, timeout: t, ...rest } = selectorOrOptions;
|
||||
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: Error | undefined;
|
||||
if (selector && fillValue !== undefined) {
|
||||
try {
|
||||
await this._page.fill(selector, fillValue, { ...fillOptions, timeout });
|
||||
return;
|
||||
} catch (error) {
|
||||
errorToRaise = error as Error;
|
||||
selector = undefined;
|
||||
}
|
||||
}
|
||||
|
||||
if (prompt) {
|
||||
await this._ai.aiInputText({
|
||||
value: fillValue,
|
||||
intention: prompt,
|
||||
data: Object.keys(fillOptions).length > 0 ? fillOptions : undefined,
|
||||
timeout,
|
||||
data: Object.keys(data).length > 0 ? data : undefined,
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
if (errorToRaise) {
|
||||
throw errorToRaise;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 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" });
|
||||
* ```
|
||||
*/
|
||||
async selectOption(
|
||||
selector: string,
|
||||
values: string | string[],
|
||||
options?: Parameters<Page["selectOption"]>[2],
|
||||
): Promise<string[]>;
|
||||
): Promise<void>;
|
||||
async selectOption(
|
||||
options: { prompt: string; value?: string } & Partial<Parameters<Page["selectOption"]>[2]>,
|
||||
): Promise<string[]>;
|
||||
): Promise<void>;
|
||||
async selectOption(
|
||||
selectorOrOptions: string | ({ prompt: string; value?: string } & Partial<Parameters<Page["selectOption"]>[2]>),
|
||||
selector: string,
|
||||
values: string | string[],
|
||||
options: { prompt: string } & Partial<Parameters<Page["selectOption"]>[2]>,
|
||||
): Promise<void>;
|
||||
async selectOption(
|
||||
selectorOrOptions?:
|
||||
| string
|
||||
| ({ prompt: string; value?: string } & Partial<Parameters<Page["selectOption"]>[2]>),
|
||||
values?: string | string[],
|
||||
options?: Parameters<Page["selectOption"]>[2],
|
||||
): Promise<string[]> {
|
||||
options?: Parameters<Page["selectOption"]>[2] | ({ prompt?: string } & Partial<Parameters<Page["selectOption"]>[2]>),
|
||||
): Promise<void> {
|
||||
let selector: string | undefined;
|
||||
let selectValue: string | string[] | undefined;
|
||||
let prompt: string | undefined;
|
||||
let selectOptions: Partial<Parameters<Page["selectOption"]>[2]> = {};
|
||||
let timeout: number | undefined;
|
||||
|
||||
// Parse arguments
|
||||
if (typeof selectorOrOptions === "string") {
|
||||
if (values === undefined) {
|
||||
throw new Error("value is required when selector is provided");
|
||||
selector = selectorOrOptions;
|
||||
selectValue = values;
|
||||
if (options && typeof options === "object") {
|
||||
const { prompt: p, timeout: t, ...rest } = options as {
|
||||
prompt?: string;
|
||||
timeout?: number;
|
||||
} & Partial<Parameters<Page["selectOption"]>[2]>;
|
||||
prompt = p;
|
||||
timeout = t;
|
||||
selectOptions = rest;
|
||||
} else if (options) {
|
||||
selectOptions = options;
|
||||
}
|
||||
return this._page.selectOption(selectorOrOptions, values, options);
|
||||
} else {
|
||||
const { prompt, value, timeout, ...data } = selectorOrOptions;
|
||||
} else if (selectorOrOptions && typeof selectorOrOptions === "object") {
|
||||
const { prompt: p, value: v, timeout: t, ...rest } = selectorOrOptions;
|
||||
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: Error | undefined;
|
||||
if (selector && selectValue !== undefined) {
|
||||
try {
|
||||
await this._page.selectOption(selector, selectValue, { ...selectOptions, timeout });
|
||||
return;
|
||||
} catch (error) {
|
||||
errorToRaise = error as Error;
|
||||
selector = undefined;
|
||||
}
|
||||
}
|
||||
|
||||
// If the original selector doesn't work, try to select the option with AI
|
||||
if (prompt) {
|
||||
await this._ai.aiSelectOption({
|
||||
value,
|
||||
value: typeof selectValue === "string" ? selectValue : selectValue?.[0],
|
||||
intention: prompt,
|
||||
data: Object.keys(selectOptions).length > 0 ? selectOptions : undefined,
|
||||
timeout,
|
||||
data: Object.keys(data).length > 0 ? data : undefined,
|
||||
});
|
||||
return value ? [value] : [];
|
||||
return;
|
||||
}
|
||||
|
||||
if (errorToRaise) {
|
||||
throw errorToRaise;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user