@intuned/browser-dev 0.1.4-dev.0

package/generated-docs/ai/type-aliases/SUPPORTED_MODELS.mdx

@@ -0,0 +1,85 @@
+---
+title: SUPPORTED_MODELS
+description: ""
+---
+
+```typescript
+export type SUPPORTED_MODELS = | SUPPORTED_CLAUDE_MODELS
+  | SUPPORTED_OPENAI_MODELS;
+```
+
+Union type representing all supported AI models for data extraction.
+Includes models from both OpenAI and Anthropic.
+
+**Supported OpenAI Models:**
+"gpt-3.5-turbo"
+"gpt-3.5-turbo-0125"
+"gpt-3.5-turbo-0301"
+"gpt-3.5-turbo-0613"
+"gpt-3.5-turbo-1106"
+"gpt-3.5-turbo-16k"
+"gpt-3.5-turbo-16k-0613"
+"gpt-3.5-turbo-instruct"
+"gpt-3.5-turbo-instruct-0914"
+"gpt-4"
+"gpt-4-0314"
+"gpt-4-0613"
+"gpt-4-32k"
+"gpt-4-32k-0314"
+"gpt-4-32k-0613"
+"gpt-4-turbo"
+"gpt-4-turbo-2024-04-09"
+"gpt-4.1"
+"gpt-4.1-2025-04-14"
+"gpt-4.1-mini"
+"gpt-4.1-mini-2025-04-14"
+"gpt-4.1-nano"
+"gpt-4.1-nano-2025-04-14"
+"gpt-4o"
+"gpt-4o-2024-05-13"
+"gpt-4o-2024-08-06"
+"gpt-4o-2024-11-20"
+"gpt-4o-mini"
+"gpt-4o-mini-2024-07-18"
+"gpt-5"
+"gpt-5-2025-08-07"
+"gpt-5-chat"
+"gpt-5-chat-latest"
+"gpt-5-mini"
+"gpt-5-mini-2025-08-07"
+"gpt-5-nano"
+"gpt-5-nano-2025-08-07"
+"o1"
+"o1-2024-12-17"
+"o1-mini"
+"o1-mini-2024-09-12"
+"o1-pro"
+"o1-pro-2025-03-19"
+"o3"
+"o3-2025-04-16"
+"o3-deep-research"
+"o3-deep-research-2025-06-26"
+"o3-mini"
+"o3-mini-2025-01-31"
+"o3-pro"
+"o3-pro-2025-06-10"
+"o4-mini"
+"o4-mini-2025-04-16"
+"o4-mini-deep-research"
+"o4-mini-deep-research-2025-06-26"
+
+**Supported Anthropic (Claude) Models:**
+"claude-3-5-haiku-20241022"
+"claude-3-5-haiku-latest"
+"claude-3-5-sonnet-20240620"
+"claude-3-5-sonnet-20241022"
+"claude-3-5-sonnet-latest"
+"claude-3-7-sonnet-20250219"
+"claude-3-7-sonnet-latest"
+"claude-3-haiku-20240307"
+"claude-4-opus-20250514"
+"claude-4-sonnet-20250514"
+"claude-opus-4-1"
+"claude-opus-4-1-20250805"
+"claude-opus-4-20250514"
+"claude-sonnet-4-20250514"

package/generated-docs/helpers/functions/downloadFile.mdx

@@ -0,0 +1,99 @@
+---
+title: downloadFile
+description: ""
+---
+
+```typescript
+export declare function downloadFile(input: {
+  page: Page;
+  trigger: Trigger;
+  timeoutInMs?: number;
+}): Promise<Download>;
+```
+
+<Note>
+**Trigger Behavior:**
+- **URL**: Creates a new page, navigates to the URL, waits for download, then closes the page
+- **Locator**: Uses the current page to click the element and capture the resulting download
+- **Callback**: Executes the provided function with the page object and captures the first triggered downloads
+</Note>
+
+Downloads a file from a web page using various trigger methods.
+
+This function provides three flexible ways to initiate file downloads:
+1. **URL Navigation**: Directly navigate to a URL that triggers a download
+2. **Element Interaction**: Click on a Playwright locator (e.g., download button or link)
+3. **Custom Callback**: Execute a custom function to trigger the download programmatically
+
+## Examples
+
+<CodeGroup>
+
+```typescript URL trigger
+import { downloadFile } from "@intuned/browser";
+export default async function handler(params, page, context){
+// Download by navigating directly to a URL
+const download = await downloadFile({
+  page,
+  trigger: "https://intuned-docs-public-images.s3.amazonaws.com/32UP83A_ENG_US.pdf"
+});
+console.log(`Downloaded to: ${await download.path()}`);
+}
+```
+
+```typescript Locator trigger
+import { downloadFile } from "@intuned/browser";
+export default async function handler(params, page, context){
+// Download by clicking a link or button
+await page.goto("https://sandbox.intuned.dev/pdfs")
+const download = await downloadFile({
+  page,
+  trigger: page.locator("xpath=//tbody/tr[1]//*[name()='svg']")
+});
+console.log(`File saved at: ${await download.path()}`);
+}
+```
+
+```typescript Callback trigger
+import { downloadFile } from "@intuned/browser";
+export default async function handler(params, page, context){
+// Download using a custom interaction sequence
+await page.goto("https://sandbox.intuned.dev/pdfs")
+const download = await downloadFile({
+  page,
+  trigger: async (page) => {
+    await page.locator("xpath=//tbody/tr[1]//*[name()='svg']").click();
+  }
+});
+console.log(`Download completed: ${await download.path()}`);
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="input" type="Object" required
+>
+Configuration object for the download operation
+
+<Expandable title="input">
+<ParamField path="input.page" type="Page">
+The Playwright Page object to use for the download
+</ParamField>
+
+<ParamField path="input.trigger" type="Trigger">
+The [Trigger](../type-aliases/Trigger) method to initiate the download
+</ParamField>
+
+<ParamField path="input.timeoutInMs" type="number">
+Maximum time in milliseconds to wait for download completion. Defaults to 5000.
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `Promise<Download>`
+
+Promise that resolves to a Playwright Download object

package/generated-docs/helpers/functions/extractMarkdown.mdx

@@ -0,0 +1,56 @@
+---
+title: extractMarkdown
+description: ""
+---
+
+```typescript
+export declare function extractMarkdown(input: {
+  source: Page | Locator;
+}): Promise<string>;
+```
+
+Converts HTML content from a Playwright Page or Locator to semantic markdown format.
+
+## Examples
+
+<CodeGroup>
+
+```typescript locator source
+import { extractMarkdown } from "@intuned/browser";
+export default async function handler(params, page, context){
+await page.goto("https://example.com");
+const headerLocator = page.locator('h1')
+const markdown = await extractMarkdown({ source: headerLocator })
+console.log(markdown); // Outputs the markdown representation of the header
+}
+```
+
+```typescript string source
+import { extractMarkdown } from "@intuned/browser";
+export default async function handler(params, page, context){
+await page.goto("https://example.com");
+const markdown = await extractMarkdown({ source: page });
+console.log(markdown); // Outputs the markdown representation of the page
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="input" type="Object" required
+>
+The input object containing the source of the HTML content
+
+<Expandable title="input">
+<ParamField path="input.source" type="Page | Locator">
+The source of the HTML content. Can be a Playwright Page or a Playwright Locator. If a Playwright Page is provided, the HTML content will be extracted from the entire page. If a Playwright Locator is provided, the HTML content will be extracted from the specific element
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `Promise<string>`
+
+Promise that resolves to the markdown representation of the HTML content

package/generated-docs/helpers/functions/filterEmptyValues.mdx

@@ -0,0 +1,51 @@
+---
+title: filterEmptyValues
+description: ""
+---
+
+```typescript
+export declare function filterEmptyValues<T>(input: { data: T }): T;
+```
+
+Recursively filters out empty values from nested objects and arrays.
+
+This function removes the following empty values:
+- `null` and `undefined` values
+- Empty strings (after trimming whitespace)
+- Empty arrays
+- Empty objects
+- Arrays and objects that become empty after filtering their contents
+
+## Examples
+
+<CodeGroup>
+
+```typescript Basic Usage
+import { filterEmptyValues } from "@intuned/browser";
+export default async function handler(params, page, context){
+filterEmptyValues({ data: { a: "", b: "hello", c: null } }) // Returns { b: "hello" }
+filterEmptyValues({ data: [1, "", null, [2, ""]] }) // Returns [1, [2]]
+filterEmptyValues({ data: { users: [{ name: "" }, { name: "John" }] } }) // Returns { users: [{ name: "John" }] }
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="input" type="Object" required
+>
+The input object containing the data to filter
+
+<Expandable title="input">
+<ParamField path="input.data" type="T">
+The data structure to filter (object, array, or any other type)
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `T`
+
+Filtered data structure with empty values removed

package/generated-docs/helpers/functions/goToUrl.mdx

@@ -0,0 +1,124 @@
+---
+title: goToUrl
+description: ""
+---
+
+```typescript
+export declare function goToUrl(input: {
+  page: Page;
+  url: string;
+  timeoutInMs?: number;
+  retries?: number;
+  throwOnTimeout?: boolean;
+  waitForLoadState?: "load" | "domcontentloaded" | "networkidle";
+  waitForLoadingStateUsingAi?: boolean;
+  model?: SUPPORTED_MODELS;
+  apiKey?: string;
+}): Promise<void>;
+```
+
+Navigates to a specified URL with enhanced reliability features including automatic retries with exponential backoff,
+intelligent timeout detection, and optional AI-powered loading verification.
+
+This function handles common navigation challenges by automatically retrying failed requests, detecting navigation hangs, and ensuring the page reaches a truly idle state. For dynamic applications,
+it can optionally verify page loading completion using AI vision to detect loading spinners, blank content, or incomplete states.
+The function can be configured to either throw errors or gracefully continue execution when navigation issues occur.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Basic Navigation
+import { goToUrl } from "@intuned/browser";
+export default async function handler(params, page, context){
+// Navigate with automatic retries on failure
+await goToUrl({
+  page,
+  url: 'https://example.com'
+});
+// Automatically retries up to 3 times with exponential backoff
+}
+```
+
+```typescript Navigation with options
+import { goToUrl } from "@intuned/browser";
+export default async function handler(params, page, context){
+// Navigate to an unreliable site without throwing on timeout
+await goToUrl({
+  page,
+  url: 'https://www.google.com',
+  throwOnTimeout: false, // Continue even if navigation fails
+  retries: 5, // Try more times for unreliable sites
+  timeoutInMs: 60000 // Give it more time
+});
+// If navigation fails after all retries, execution continues
+}
+```
+
+```typescript AI-Verified Loading for Dynamic Sites
+import { goToUrl } from "@intuned/browser";
+export default async function handler(params, page, context){
+await goToUrl({
+  page,
+  url: 'https://sandbox.intuned.dev/',
+  waitForLoadState: "load",
+  waitForLoadingStateUsingAi: true, // AI checks for spinners/loading states
+  model: "gpt-4o",
+  retries: 3
+});
+// AI verifies no loading spinners or blank content before proceeding
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="input" type="Object" required
+>
+The input object containing the page and url
+
+<Expandable title="input">
+<ParamField path="input.page" type="Page">
+The Playwright page object to navigate
+</ParamField>
+
+<ParamField path="input.url" type="string">
+The URL to navigate to
+</ParamField>
+
+<ParamField path="input.retries" type="number">
+Number of retry attempts with exponential backoff (factor: 2, minTimeout: 1000ms). Defaults to 3
+</ParamField>
+
+<ParamField path="input.timeoutInMs" type="number">
+Maximum time in milliseconds to wait for navigation. Defaults to 30000
+</ParamField>
+
+<ParamField path="input.waitForLoadState" type="string">
+When to consider navigation succeeded. Options: "load", "domcontentloaded", "networkidle", "commit". Defaults to "load"
+</ParamField>
+
+<ParamField path="input.throwOnTimeout" type="boolean">
+Whether to throw an error if navigation times out. When false, the function returns without throwing, allowing continued execution. Defaults to true.
+</ParamField>
+
+<ParamField path="input.waitForLoadingStateUsingAi" type="boolean">
+When true, uses AI vision to verify the page is fully loaded by checking for loading spinners, blank content, or incomplete states. Retries up to 4 times with 5-second delays. Defaults to false
+</ParamField>
+
+<ParamField path="input.model" type="SUPPORTED_MODELS">
+AI model to use for loading verification. See [SUPPORTED_MODELS](../type-aliases/SUPPORTED_MODELS) for all supported models. Defaults to "gpt-4o-2024-08-06"
+</ParamField>
+
+<ParamField path="input.apiKey" type="string">
+Optional API key for the AI service (if provided, will not be billed to your account)
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `Promise<void>`
+
+Promise that resolves when navigation completes successfully. If the operation fails and `throwOnTimeout` is false, resolves without error

package/generated-docs/helpers/functions/processDate.mdx

@@ -0,0 +1,55 @@
+---
+title: processDate
+description: ""
+---
+
+```typescript
+export declare function processDate(input: { date: string }): Date | null;
+```
+
+Parses various date string formats into Date objects.
+Returns only the date part (year, month, day) with time set to 00:00:00.
+
+Supports a wide variety of date formats including:
+- DD/MM/YYYY with optional time (e.g., "22/11/2024 21:19:05", "13/12/2024")
+- MM/DD/YYYY with optional time and timezone (e.g., "01/17/2025 3:00:00 PM CT", "10/25/2024")
+- MM/DD/YYYY with time and timezone abbreviations (e.g., "10/23/2024 12:06 PM CST")
+- MM/DD/YYYY with AM/PM time format (e.g., "11/28/2024 1:59:59 AM", "12/09/2024 9:00 AM")
+- MM/DD/YYYY with dash separator and time (e.g., "12/19/2024 - 2:00 PM")
+- M/DD/YYYY and MM/D/YYYY formats (e.g., "8/16/2019", "9/28/2024")
+- DD MMM YYYY with optional time and timezone (e.g., "5 Dec 2024 8:00 AM PST", "11 Sep 2024")
+- Full month name formats (e.g., "November 14, 2024", "January 31, 2025, 5:00 pm")
+- 24-hour time format (e.g., "22/11/2024 19:45:00", "09/01/2025 15:00:00")
+
+## Examples
+
+<CodeGroup>
+
+```typescript Basic Date Processing
+import { processDate } from "@intuned/browser";
+export default async function handler(params, page, context){
+processDate("22/11/2024 21:19:05") // Returns Date with 2024-11-22 00:00:00
+processDate("5 Dec 2024 8:00 AM PST") // Returns Date with 2024-12-05 00:00:00
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="input" type="Object" required
+>
+The input object containing the date to process
+
+<Expandable title="input">
+<ParamField path="input.date" type="string">
+A string containing a date in various possible formats
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `Date | any`
+
+Date object with only date components (time set to 00:00:00) if parsing successful, null if parsing fails

package/generated-docs/helpers/functions/resolveUrl.mdx

@@ -0,0 +1,165 @@
+---
+title: resolveUrl
+description: ""
+---
+
+<Tabs>
+
+<Tab title="From Base URL String">
+
+```typescript
+export declare function resolveUrl(input: {
+  url: string;
+  baseUrl: string;
+}): Promise<string>;
+```
+
+Converts any URL source to an absolute, properly encoded URL by combining a relative URL with a base URL string.
+
+## Examples
+
+<CodeGroup>
+
+```typescript String source
+import { resolveUrl } from '@intuned/browser';
+export default async function handler(params, page, context){
+await page.goto("https://example.com");
+
+// Using explicit base URL
+const absoluteUrl = await resolveUrl({
+  url: "/api/users",
+  baseUrl: "https://example.com"
+});
+// Returns: "https://example.com/api/users"
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="input" type="Object" required
+>
+Configuration object with different properties based on the overload
+
+<Expandable title="input">
+<ParamField path="input.url" type="string">
+The relative or absolute URL to resolve
+</ParamField>
+
+<ParamField path="input.baseUrl" type="string">
+Base URL string to resolve relative URLs against
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `Promise<string>`
+
+Promise that resolves to the absolute, properly encoded URL string
+
+</Tab>
+
+<Tab title="From The Current Page's URL">
+
+```typescript
+export declare function resolveUrl(input: {
+  url: string;
+  page: Page;
+}): Promise<string>;
+```
+
+Converts any URL source to an absolute, properly encoded URL by using the current page's URL as the base URL.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Page source
+import { resolveUrl } from '@intuned/browser';
+export default async function handler(params, page, context){
+await page.goto("https://example.com");
+// Using current page as base URL
+const absoluteUrl = await resolveUrl({
+  url: "/api/users",
+  page: page
+});
+// Returns: "https://example.com/api/users"
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="input" type="Object" required
+>
+Configuration object with different properties based on the overload
+
+<Expandable title="input">
+<ParamField path="input.url" type="string">
+The relative or absolute URL to resolve
+</ParamField>
+
+<ParamField path="input.page" type="Page">
+Playwright Page object to extract base URL from. The current page URL will be used as the base URL
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `Promise<string>`
+
+Promise that resolves to the absolute, properly encoded URL string
+
+</Tab>
+
+<Tab title="From Anchor Element">
+
+```typescript
+export declare function resolveUrl(input: { url: Locator }): Promise<string>;
+```
+
+Converts any URL source to an absolute, properly encoded URL by extracting the href attribute from a Playwright Locator pointing to an anchor element.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Locator source
+import { resolveUrl } from '@intuned/browser';
+export default async function handler(params, page, context){
+await page.goto("https://sandbox.intuned.dev/");
+const absoluteUrl = await resolveUrl({
+  url: page.locator("xpath=//a[normalize-space()='Steps Form']"),
+});
+// Returns: "https://sandbox.intuned.dev/steps-form"
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="input" type="Object" required
+>
+Configuration object with different properties based on the overload
+
+<Expandable title="input">
+<ParamField path="input.url" type="Locator">
+Playwright Locator pointing to an anchor element. The href attribute will be extracted and resolved
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `Promise<string>`
+
+Promise that resolves to the absolute, properly encoded URL string
+
+</Tab>
+
+</Tabs>