@intuned/browser-dev 0.1.4-dev.0

package/dist/helpers/export.d.ts

@@ -0,0 +1,1220 @@
+/* eslint-disable prettier/prettier */
+// prettier-ignore-file
+import type { Locator, Page, ElementHandle } from "playwright-core";
+import type { ReadStream } from "fs";
+import { Download } from "playwright-core";
+import { SUPPORTED_MODELS } from "../ai/export";
+
+/**
+ * Configuration options for sanitizing HTML content.
+ */
+export interface SanitizeHtmlOptions {
+  /** The HTML content to sanitize */
+  html: string;
+  /** Remove all <script> elements. Defaults to true. */
+  removeScripts?: boolean;
+  /** Remove all <style> elements. Defaults to true. */
+  removeStyles?: boolean;
+  /** Remove all <svg> elements. Defaults to true. */
+  removeSvgs?: boolean;
+  /** Remove HTML comments. Defaults to true. */
+  removeComments?: boolean;
+  /** Remove attributes longer than maxAttributeLength. Defaults to true. */
+  removeLongAttributes?: boolean;
+  /** Maximum length for attributes before removal. Defaults to 500. */
+  maxAttributeLength?: number;
+  /** List of attribute names to always preserve. Defaults to ["class", "src"]. */
+  preserveAttributes?: string[];
+  /** Remove empty tags (except preserved ones). Defaults to true. */
+  removeEmptyTags?: boolean;
+  /** List of tag names to preserve even when empty. Defaults to ["img"]. */
+  preserveEmptyTags?: string[];
+  /** Remove extra whitespace between tags and empty lines. Defaults to true. */
+  minifyWhitespace?: boolean;
+}
+
+/**
+ * Sanitizes and cleans HTML content by removing unwanted elements, attributes, and whitespace.
+ * Provides fine-grained control over each cleaning operation through configurable options.
+ *
+ * @param {SanitizeHtmlOptions} options - Configuration options for sanitization
+ * @param {string} options.html - The HTML content to sanitize
+ * @param {boolean} [options.removeScripts=true] - Remove all `<script>` elements. Defaults to true.
+ * @param {boolean} [options.removeStyles=true] - Remove all `<style>` elements. Defaults to true.
+ * @param {boolean} [options.removeSvgs=true] - Remove all `<svg>` elements. Defaults to true.
+ * @param {boolean} [options.removeComments=true] - Remove HTML comments. Defaults to true.
+ * @param {boolean} [options.removeLongAttributes=true] - Remove attributes longer than maxAttributeLength. Defaults to true.
+ * @param {number} [options.maxAttributeLength=500] - Maximum length for attributes before removal. Defaults to 500.
+ * @param {string[]} [options.preserveAttributes=["class", "src"]] - List of attribute names to always preserve. Defaults to ["class", "src"].
+ * @param {boolean} [options.removeEmptyTags=true] - Remove empty tags (except preserved ones). Defaults to true.
+ * @param {string[]} [options.preserveEmptyTags=["img"]] - List of tag names to preserve even when empty. Defaults to ["img"].
+ * @param {boolean} [options.minifyWhitespace=true] - Remove extra whitespace between tags and empty lines. Defaults to true.
+ * @returns {string} The sanitized HTML string
+ *
+ * @example
+ * ```typescript Basic Sanitization
+ * import { sanitizeHtml } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * const dirtyHtml = `
+ *   <div>
+ *     <script>alert('xss')</script>
+ *     <p style="color: red;">Hello World</p>
+ *     <span></span>
+ *   </div>
+ * `;
+ * const sanitizedHtml = sanitizeHtml({ html: dirtyHtml });
+ * // Returns: '<div><p>Hello World</p></div>'
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Sanitization Options
+ * import { sanitizeHtml } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * const html = `
+ *   <div data-long-attr="${'x'.repeat(600)}">
+ *     <style>.test { color: red; }</style>
+ *     <script>alert('test')</script>
+ *     <p style="color: blue;">Content</p>
+ *     <!-- Comment -->
+ *   </div>
+ * `;
+ * // Keep styles but remove scripts and comments
+ * const result = sanitizeHtml({ html,
+ *   removeScripts: true,
+ *   removeStyles: false,
+ *   removeComments: true,
+ *   maxAttributeLength: 100,
+ *   preserveAttributes: ["class", "src", "style"]
+ * });
+ * }
+ * ```
+ */
+
+export declare function sanitizeHtml(options: SanitizeHtmlOptions): string;
+
+/**
+ * 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
+ *
+ * @param {Object} input - Configuration object for the download operation
+ * @param {Page} input.page - The Playwright Page object to use for the download
+ * @param {Trigger} input.trigger - The [Trigger](../type-aliases/Trigger) method to initiate the download
+ * @param {number} [input.timeoutInMs=5000] - Maximum time in milliseconds to wait for download completion. Defaults to 5000.
+ * @returns {Promise<Download>} Promise that resolves to a Playwright Download object
+ *
+ * @example
+ * ```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()}`);
+ * }
+ * ```
+ *
+ * @example
+ * ```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()}`);
+ * }
+ * ```
+ *
+ * @example
+ * ```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()}`);
+ * }
+ * ```
+ *
+ * @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
+ */
+export declare function downloadFile(input: {
+  page: Page;
+  trigger: Trigger;
+  timeoutInMs?: number;
+}): Promise<Download>;
+
+/**
+ * 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
+ *
+ * @param {Object} input - The input object containing the data to filter
+ * @param {T} input.data - The data structure to filter (object, array, or any other type)
+ * @returns {T} Filtered data structure with empty values removed
+ *
+ * @example
+ * ```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" }] }
+ * }
+ * ```
+ */
+export declare function filterEmptyValues<T>(input: { data: T }): T;
+
+/**
+ * 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.
+ *
+ * @param {Object} input - The input object containing the page and url
+ * @param {Page} input.page - The Playwright page object to navigate
+ * @param {string} input.url - The URL to navigate to
+ * @param {number} [input.retries=3] - Number of retry attempts with exponential backoff (factor: 2, minTimeout: 1000ms). Defaults to 3
+ * @param {number} [input.timeoutInMs=30000] - Maximum time in milliseconds to wait for navigation. Defaults to 30000
+ * @param {string} [input.waitForLoadState="load"] - When to consider navigation succeeded. Options: "load", "domcontentloaded", "networkidle", "commit". Defaults to "load"
+ * @param {boolean} [input.throwOnTimeout=true] - Whether to throw an error if navigation times out. When false, the function returns without throwing, allowing continued execution. Defaults to true.
+ * @param {boolean} [input.waitForLoadingStateUsingAi=false] - 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
+ * @param {SUPPORTED_MODELS} [input.model="gpt-4o-2024-08-06"] - 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"
+ * @param {string} [input.apiKey] - Optional API key for the AI service (if provided, will not be billed to your account)
+ * @returns {Promise<void>} Promise that resolves when navigation completes successfully. If the operation fails and `throwOnTimeout` is false, resolves without error
+ *
+ * @example
+ * ```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
+ * }
+ * ```
+ *
+ * @example
+ * ```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
+ * }
+ * ```
+ *
+ * @example
+ * ```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
+ * }
+ * ```
+ */
+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>;
+
+/**
+ * Automatically scrolls through infinite scroll content by repeatedly scrolling to the bottom
+ * until no new content loads or maximum scroll limit is reached.
+ *
+ * @param {Object} input - The input object containing the data to scroll to load content
+ * @param {Page | Locator} input.source - The Playwright Page or Locator to scroll
+ * @param {Function} [input.onScrollProgress] - Optional callback function to call during each scroll iteration
+ * @param {number} [input.maxScrolls=50] - Maximum number of scroll attempts before stopping. Defaults to 50
+ * @param {number} [input.delayInMs=100] - Delay in milliseconds between scroll attempts. Defaults to 100
+ * @param {number} [input.minHeightChange=100] - Minimum height change in pixels required to continue scrolling. Defaults to 100
+ * @returns {Promise<void>} Promise that resolves when scrolling is complete
+ *
+ * @example
+ * ```typescript Basic Infinite Scroll
+ * import { scrollToLoadContent } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * // Scroll through entire page content
+ * await page.goto("https://docs.intunedhq.com/docs-old/getting-started/introduction")
+ * await scrollToLoadContent({
+ *   source: page,
+ * });
+ * // Now all content is loaded and visible
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Scroll Specific Container
+ * import { scrollToLoadContent } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * // Scroll through a specific scrollable div
+ * await page.goto("https://docs.intunedhq.com/docs-old/getting-started/introduction")
+ * const container = page.locator("xpath=//div[@id='sidebar-content']");
+ * await scrollToLoadContent({
+ *   source: container,
+ *   maxScrolls: 20
+ * });
+ * }
+ * ```
+ */
+
+export declare function scrollToLoadContent(input: {
+  source: Page | Locator;
+  onScrollProgress?: CallableFunction;
+  maxScrolls?: number;
+  delayInMs?: number;
+  minHeightChange?: number;
+}): Promise<void>;
+
+/**
+ * Click a button and wait briefly for content to load.
+ *
+ * This function clicks a button element and waits for a specified delay, allowing time for
+ * any triggered content to load. It automatically waits for network activity to settle.
+ *
+ * @param {Object} input - Configuration options
+ * @param {Page} input.page - Playwright Page object
+ * @param {Locator} input.buttonLocator - Locator for the button element to click
+ * @param {number} [input.clickDelay=0.5] - Delay after clicking the button (in seconds)
+ * @returns {Promise<void>} Promise that resolves when the click and wait is complete
+ *
+ * @example
+ * ```typescript Basic Button Click
+ * import { clickButtonAndWait } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * await page.goto("https://example.com/products");
+ * const loadMoreButton = page.locator("#load-more-button");
+ * await clickButtonAndWait({
+ *   page,
+ *   buttonLocator: loadMoreButton,
+ *   clickDelay: 1.0
+ * });
+ * }
+ * ```
+ */
+export declare function clickButtonAndWait(input: {
+  page: Page;
+  buttonLocator: Locator;
+  clickDelay?: number;
+}): Promise<void>;
+
+/**
+ * Repeatedly click a button until no new content appears or max clicks reached.
+ *
+ * This function is useful for "Load More" buttons or paginated content where you need to
+ * keep clicking until all content is loaded. It provides several stopping conditions:
+ * - Button becomes invisible
+ * - Button becomes disabled
+ * - Maximum number of clicks reached
+ * - No change detected in container content (when containerLocator is provided)
+ *
+ * @param {Object} input - Configuration options
+ * @param {Page} input.page - Playwright Page object
+ * @param {Locator} input.buttonLocator - Locator for the button to click repeatedly
+ * @param {CallableFunction} [input.heartbeat] - Optional callback invoked after each click
+ * @param {Locator} [input.containerLocator] - Optional content container to detect changes
+ * @param {number} [input.maxClicks=50] - Maximum number of times to click the button
+ * @param {number} [input.clickDelay=0.5] - Delay after each click (in seconds)
+ * @param {number} [input.noChangeThreshold=0] - Minimum change in content size to continue clicking
+ * @returns {Promise<void>} Promise that resolves when clicking is exhausted
+ *
+ * @example
+ * ```typescript Load All Items
+ * import { clickUntilExhausted } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * await page.goto("https://example.com/products");
+ * const loadMoreButton = page.locator("button:has-text('Load More')");
+ *
+ * // Click until button disappears or is disabled
+ * await clickUntilExhausted({
+ *   page,
+ *   buttonLocator: loadMoreButton,
+ *   maxClicks: 20
+ * });
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Track Container Changes
+ * import { clickUntilExhausted } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * await page.goto("https://example.com/products");
+ * const loadMoreButton = page.locator("#load-more");
+ * const productsContainer = page.locator("#products-list");
+ *
+ * let clickCount = 0;
+ * await clickUntilExhausted({
+ *   page,
+ *   buttonLocator: loadMoreButton,
+ *   containerLocator: productsContainer,
+ *   heartbeat: () => {
+ *     clickCount++;
+ *     console.log(`Clicked ${clickCount} times`);
+ *   },
+ *   maxClicks: 30,
+ *   clickDelay: 0.5,
+ *   noChangeThreshold: 0
+ * });
+ * }
+ * ```
+ */
+export declare function clickUntilExhausted(input: {
+  page: Page;
+  buttonLocator: Locator;
+  heartbeat?: CallableFunction;
+  containerLocator?: Locator;
+  maxClicks?: number;
+  clickDelay?: number;
+  noChangeThreshold?: number;
+}): Promise<void>;
+
+/**
+ * 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")
+ *
+ * @param {Object} input - The input object containing the date to process
+ * @param {string} input.date - A string containing a date in various possible formats
+ * @returns {Date | null} Date object with only date components (time set to 00:00:00) if parsing successful, null if parsing fails
+ *
+ * @example
+ * ```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
+ * }
+ * ```
+ */
+export declare function processDate(input: { date: string }): Date | null;
+
+/**
+ * Uploads files to AWS S3 storage with flexible configuration options.
+ *
+ * This function accepts various file types including Playwright Download objects, binary data,
+ * and file streams, making it versatile for different upload scenarios. It automatically
+ * handles file metadata and provides comprehensive S3 configuration options.
+ *
+ * @param {Object} input - Configuration object for the upload operation
+ * @param {FileType} input.file - The file to upload. Accepts [FileType](../type-aliases/FileType) types including:
+ *   - Playwright Download objects (from `downloadFile`)
+ *   - Uint8Array or Buffer (binary data)
+ *   - ReadStream (file streams)
+ * @param {S3Configs} [input.configs] - Optional [S3Configs](../interfaces/S3Configs) for customizing the S3 upload. If not provided, uses environment variables or default configuration
+ * @param {string} [input.fileNameOverride] - Optional custom filename for the uploaded file. If not provided, uses the original filename
+ * @param {string} [input.contentType] - Optional MIME type for the uploaded file (e.g., "application/pdf", "image/png")
+ * @returns {Promise<Attachment>} Promise that resolves to an [Attachment](../interfaces/Attachment) object with file metadata and utility methods
+ *
+ * @example
+ * ```typescript Upload Downloaded File
+ * import { downloadFile, uploadFileToS3 } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * // Download and upload a file with custom S3 configuration
+ * await page.goto("https://sandbox.intuned.dev/pdfs")
+ * const download = await downloadFile({
+ *   page,
+ *   trigger: page.locator("xpath=//tbody/tr[1]//*[name()='svg']")
+ * });
+ *
+ * const uploadedFile = await uploadFileToS3({
+ *   file: download,
+ *   configs: {
+ *       bucket: 'my-documents',
+ *       region: 'us-west-2',
+ *       accessKeyId: 'accessKeyId',
+ *       secretAccessKey: 'SecretAccessKeyId'
+ *     },
+ *     fileNameOverride: 'reports/monthly-report.pdf'
+ *   }
+ * });
+ *
+ * console.log(`File uploaded: ${uploadedFile.suggestedFileName}`);
+ * console.log(`S3 URL: ${uploadedFile.getS3Key()}`);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Upload Binary Data
+ * import { uploadFileToS3 } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * // Upload binary data with minimal configuration
+ * const fileBuffer = Buffer.from('Hello World', 'utf8');
+ * const uploadedFile = await uploadFileToS3({
+ *   file: fileBuffer,
+ *   configs: {
+ *     bucket: 'my-documents',
+ *     region: 'us-west-2',
+ *     accessKeyId: 'accessKeyId',
+ *     secretAccessKey: 'SecretAccessKeyId'
+ *   },
+ *   fileNameOverride: 'data/text-file.txt',
+ *   contentType: 'text/plain'
+ *   }
+ * });
+ *
+ * // Generate a temporary download URL
+ * const downloadUrl = await uploadedFile.getSignedUrl(3600); // 1 hour
+ * }
+ * ```
+ *
+ * @note
+ * **S3 Configuration Priority:**
+ * 1. **Explicit configs**: Values provided in `input.configs.s3Configs`
+ * 2. **Environment variables**: Standard AWS environment variables:
+ *    - `AWS_BUCKET`
+ *    - `AWS_REGION`
+ *    - `AWS_ACCESS_KEY_ID`
+ *    - `AWS_SECRET_ACCESS_KEY`
+ *    - `AWS_ENDPOINT_URL`
+ * 3. **Default fallback**: Intuned's default S3 configuration
+ */
+
+export declare function uploadFileToS3(input: {
+  file: FileType;
+  configs?: S3Configs;
+  fileNameOverride?: string;
+  contentType?: string;
+}): Promise<Attachment>;
+
+/**
+ * Validates data against a JSON schema using the AJV validator.
+ * This function can validate any given data against a given schema. It supports validating custom data types such as the [Attachment](../interfaces/Attachment) type.
+ *
+ * @param {Object} input - The input object containing data and schema
+ * @param {Record<string, any> | Record<string, any>[]} input.data - The data to validate. Can be a single data object or an array of data objects
+ * @param {Record<string, any>} input.schema - JSON schema object defining validation rules
+ * @returns {Promise<void>} Promise that resolves if validation passes, throws ValidationError if it fails
+ *
+ * @example
+ * ```typescript Basic User Data Validation
+ * import { validateDataUsingSchema } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * const userData = {
+ *   name: "John Doe",
+ *   email: "john@example.com",
+ *   age: 30
+ * };
+ *
+ * const userSchema = {
+ *   type: "object",
+ *   required: ["name", "email", "age"],
+ *   properties: {
+ *     name: { type: "string", minLength: 1 },
+ *     email: { type: "string", format: "email" },
+ *     age: { type: "number", minimum: 0 }
+ *   }
+ * };
+ *
+ * await validateDataUsingSchema({ data: userData, schema: userSchema });
+ * // Validation passes, no error thrown
+ * }
+ * ```
+ * @example
+ * ```typescript Invalid Data Validation
+ * import { validateDataUsingSchema } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * const userData = {
+ *   name: "John Doe",
+ *   email: "john@example.com",
+ * };
+ *
+ * const userSchema = {
+ *   type: "object",
+ *   required: ["name", "email", "age"],
+ *   properties: {
+ *     name: { type: "string", minLength: 1 },
+ *     email: { type: "string", format: "email" },
+ *     age: { type: "number", minimum: 0 }
+ *   }
+ * };
+ *
+ * await validateDataUsingSchema({ data: userData, schema: userSchema });
+ * // Validation fails, throws ValidationError
+ * }
+ * ```
+ */
+export declare function validateDataUsingSchema(input: {
+  data: Record<string, any>[] | Record<string, any>;
+  schema: Record<string, any>;
+}): Promise<void>;
+
+/**
+ * Executes a callback function and waits for network requests to settle before returning.
+ *
+ * This function monitors network activity and waits for all pending requests to complete
+ * (or reach the specified maximum) before resolving. Useful for ensuring dynamic content
+ * has fully loaded after performing actions that trigger network requests.
+ *
+ * @param {Function} callback - The callback function to execute. Receives the page object as parameter
+ * @param {Object} [options] - Configuration options for network monitoring
+ * @param {Page} options.page - The Playwright page object to monitor for network activity
+ * @param {number} [options.timeoutInMs=30000] - Maximum time to wait in milliseconds before timing out. Defaults to 30000
+ * @param {number} [options.maxInflightRequests=0] - Maximum number of pending requests to consider as "settled". Defaults to 0 (waits for all requests to complete)
+ * @returns {Promise<T>} Promise that resolves to the callback's return value after network settles
+ * @example
+ * ```typescript Navigation with Network Settlement
+ * import { withNetworkSettledWait } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * // Navigate and ensure all resources are loaded
+ * await withNetworkSettledWait(
+ *   async (page) => {
+ *     await page.goto('https://spa-app.com/dashboard');
+ *     // Return when navigation is complete and network is idle
+ *   },
+ *   {
+ *     page,
+ *     timeoutInMs: 20000,
+ *     maxInflightRequests: 0 // Wait for complete network silence
+ *   }
+ * );
+ * }
+ * ```
+ */
+export declare function withNetworkSettledWait<T>(
+  callback: (page: Page) => Promise<T>,
+  options?: {
+    page: Page;
+    timeoutInMs?: number;
+    maxInflightRequests?: number;
+  }
+): Promise<T>;
+
+/**
+ * Waits for the DOM to stop changing before proceeding. Useful for dynamic content
+ * that loads progressively or elements that appear/update after initial page load.
+ *
+ * This function monitors DOM mutations and waits for a specified duration of stability
+ * before considering the DOM "settled". It can monitor either the entire page or a
+ * specific element within the page.
+ *
+ * @param {Object} options - Configuration object for DOM settlement monitoring
+ * @param {Page | Locator} options.source - The Playwright Page or Locator to monitor for DOM changes. When a Page is provided, monitors the entire document for changes. When a Locator is provided, only monitors changes within that specific element
+ * @param {number} [options.settleDurationMs=500] - Milliseconds the DOM must remain unchanged to be considered settled. Defaults to 500
+ * @param {number} [options.timeoutInMs=30000] - Maximum milliseconds to wait before giving up. Defaults to 30000
+ * @returns {Promise<boolean>} Promise that resolves to true if DOM settled within timeout, false if timeout or error occurred
+ *
+ * @example
+ * ```typescript Wait for Page Content to Stabilize
+ * import { waitForDomSettled } from '@intuned/browser';
+ * export default async function handler(params, page, context){
+ * // Navigate to a dynamic page
+ * await page.goto('https://docs.intunedhq.com/docs-old/getting-started/introduction');
+ *
+ * // Wait for entire page content to stabilize
+ * const settled = await waitForDomSettled({
+ *   source: page,
+ *   settleDurationMs: 1000
+ * });
+ *
+ * if (settled) {
+ *   // Safe to scrape or interact with content
+ *   console.log(`Found stable items`);
+ * } else {
+ *   console.log("DOM never fully settled, proceeding anyway");
+ * }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Monitor Specific Container
+ * import { waitForDomSettled } from '@intuned/browser';
+ * export default async function handler(params, page, context){
+ * await page.goto("https://docs.intunedhq.com/")
+ * // Wait for a specific feed container to stop updating
+ * const settled = await waitForDomSettled({
+ *   source: page.locator("xpath=//div[@id='sidebar-content']"),
+ *   settleDurationMs: 2000,
+ *   timeoutInMs: 15000,
+ * });
+ *
+ * if (settled) {
+ *   // Now the feed is stable, safe to extract articles
+ *   console.log(`Feed stabilized`);
+ * }
+ * }
+ * ```
+ */
+
+export declare function waitForDomSettled(options: {
+  source: Page | Locator;
+  settleDurationMs?: number;
+  timeoutInMs?: number;
+}): Promise<boolean>;
+/**
+ * Converts HTML content from a Playwright Page or Locator to semantic markdown format.
+ *
+ * @param {Object} input - The input object containing the source of the HTML content
+ * @param {Page | Locator} input.source - 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
+ * @returns {Promise<string>} Promise that resolves to the markdown representation of the HTML content
+ * @example
+ * ```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
+ * }
+ * ```
+ * @example
+ * ```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
+ * }
+ * ```
+ *
+ */
+export declare function extractMarkdown(input: {
+  source: Page | Locator;
+}): Promise<string>;
+
+/**
+ * Converts any URL source to an absolute, properly encoded URL by combining a relative URL with a base URL string.
+ *
+ * @overload From Base URL String
+ * @param {Object} input - Configuration object with different properties based on the overload
+ * @param {string} input.url - The relative or absolute URL to resolve
+ * @param {string} input.baseUrl - Base URL string to resolve relative URLs against
+ * @returns {Promise<string>} Promise that resolves to the absolute, properly encoded URL string
+ * @example
+ * ```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"
+ * }
+ * ```
+ */
+export declare function resolveUrl(input: {
+  url: string;
+  baseUrl: string;
+}): Promise<string>;
+
+/**
+ * Converts any URL source to an absolute, properly encoded URL by using the current page's URL as the base URL.
+ *
+ * @overload From The Current Page's URL
+ * @param {Object} input - Configuration object with different properties based on the overload
+ * @param {string} input.url - The relative or absolute URL to resolve
+ * @param {Page} input.page - Playwright Page object to extract base URL from. The current page URL will be used as the base URL
+ * @returns {Promise<string>} Promise that resolves to the absolute, properly encoded URL string
+ * @example
+ * ```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"
+ * }
+ * ```
+ */
+export declare function resolveUrl(input: {
+  url: string;
+  page: Page;
+}): 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.
+ *
+ * @overload From Anchor Element
+ * @param {Object} input - Configuration object with different properties based on the overload
+ * @param {Locator} input.url - Playwright Locator pointing to an anchor element. The href attribute will be extracted and resolved
+ * @returns {Promise<string>} Promise that resolves to the absolute, properly encoded URL string
+ * @example
+ * ```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"
+ * }
+ * ```
+ */
+export declare function resolveUrl(input: { url: Locator }): Promise<string>;
+
+/**
+ * Represents an uploaded file stored in AWS S3 with metadata and utility methods.
+ *
+ * This interface provides a structured way to handle file information for files stored
+ * in S3, including methods for generating presigned URLs, serialization, and accessing
+ * file metadata.
+ *
+ * @interface Attachment
+ * @example
+ * ```typescript Attachment Usage
+ * import { uploadFileToS3 } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * // Typically returned from uploadFileToS3 or saveFileToS3
+ *
+ * const uploadedFile: Attachment = await uploadFileToS3({
+ *   file: myFile,
+ *   configs: s3Config
+ * });
+ *
+ * // Access file properties
+ * console.log(uploadedFile.fileName); // "documents/report.pdf"
+ * console.log(uploadedFile.suggestedFileName); // "Monthly Report.pdf"
+ *
+ * // Get a presigned URL for download
+ * const downloadUrl = await uploadedFile.getSignedUrl(3600); // 1 hour
+ *
+ * // Convert to dictionary for storage or API responses
+ * const fileDict = uploadedFile.toDict();
+ * }
+ * ```
+ */
+export interface Attachment {
+  /** The name/key of the file in the S3 bucket */
+  fileName: string;
+
+  /** The S3 bucket name where the file is stored */
+  bucket: string;
+
+  /** The AWS region where the S3 bucket is located */
+  region: string;
+
+  /** Optional custom S3 endpoint URL. Defaults to undefined for standard AWS S3 */
+  endpoint?: string;
+
+  /** A human-readable filename suggestion for downloads or display */
+  suggestedFileName: string;
+
+  /** The file type of the file */
+  fileType?: AttachmentType;
+
+  /**
+   * Returns a JSON-serializable record representation of the file.
+   *
+   * @method Attachment.toJSON
+   * @returns {Record<string, string>} Complete model data including all fields
+   *
+   * @example
+   * ```typescript
+   * import { uploadFileToS3 } from "@intuned/browser";
+   * export default async function handler(params, page, context){
+   * file.toJSON()
+   * // {
+   * //   'fileName': 'docs/report.pdf',
+   * //   'bucket': 'uploads',
+   * //   'region': 'us-east-1',
+   * //   'endpoint': undefined,
+   * //   'suggestedFileName': 'Report.pdf'
+   * // }
+   * }
+   * ```
+   */
+  toJSON(): Record<string, string>;
+
+  /**
+   * Converts the file metadata to a record, excluding the endpoint field.
+   *
+   * @method Attachment.toDict
+   * @returns {Record<string, string>} Record with fileName, bucket, region, and suggestedFileName
+   *
+   * @example
+   * ```typescript
+   * import { uploadFileToS3 } from "@intuned/browser";
+   * export default async function handler(params, page, context){
+   * file.toDict()
+   * // {
+   * //   'fileName': 'docs/report.pdf',
+   * //   'bucket': 'uploads',
+   * //   'region': 'us-east-1',
+   * //   'suggestedFileName': 'Report.pdf'
+   * // }
+   * }
+   * ```
+   */
+  toDict(): Record<string, string>;
+
+  /**
+   * Returns the full S3 URL for the file.
+   *
+   * @method Attachment.getS3Key
+   * @returns {string} Complete S3 URL
+   *
+   * @example
+   * ```typescript
+   * import { uploadFileToS3 } from "@intuned/browser";
+   * export default async function handler(params, page, context){
+   * file.getS3Key()
+   * // "https://uploads.s3.us-east-1.amazonaws.com/docs/report.pdf"
+   * }
+   * ```
+   */
+  getS3Key(): string;
+
+  /**
+   * Returns the file path/key within the S3 bucket.
+   *
+   * @method Attachment.getFilePath
+   * @returns {string} The fileName property (S3 object key)
+   *
+   * @example
+   * ```typescript
+   * import { uploadFileToS3 } from "@intuned/browser";
+   * export default async function handler(params, page, context){
+   * file.getFilePath()
+   * // "docs/report.pdf"
+   * }
+   * ```
+   */
+  getFilePath(): string;
+
+  /**
+   * Generates a presigned URL for secure, temporary access to the file.
+   *
+   * @method Attachment.getSignedUrl
+   * @param {number} [expiration=432000] - URL expiration time in seconds. Defaults to 432000 (5 days)
+   * @returns {Promise<string>} Promise that resolves to presigned URL for downloading the file
+   *
+   * @example
+   * ```typescript
+   * import { uploadFileToS3 } from "@intuned/browser";
+   * export default async function handler(params, page, context){
+   * const url = await file.getSignedUrl(3600); // 1 hour expiration
+   * }
+   * ```
+   */
+  getSignedUrl(expiration?: number): Promise<string>;
+}
+
+/**
+ * A union type representing different methods to trigger file downloads in web automation.
+ *
+ * This type alias standardizes how download operations can be initiated, providing
+ * multiple approaches to suit different automation scenarios.
+ *
+ * @type Trigger
+ *
+ * **Type Information:**
+ * - `string`: Direct URL string to download from
+ * - `Locator`: Playwright Locator object pointing to a clickable download element
+ * - `(page: Page) => Promise<void>`: Custom function that takes a Page and triggers the download
+ *
+ * @example
+ * ```typescript URL String Trigger
+ * import { downloadFile } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * // Direct download from URL
+ * const download = await downloadFile({
+ *   page,
+ *   trigger: "https://example.com/report.pdf"
+ * });
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Locator Trigger
+ * import { downloadFile } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * // Click a download button/link
+ * const downloadButton = page.locator("#download-btn");
+ * const download = await downloadFile({
+ *   page,
+ *   trigger: downloadButton
+ * });
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Custom Function Trigger
+ * import { downloadFile } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * // Complex download logic
+ * const download = await downloadFile({
+ *   page,
+ *   trigger: async (page) => {
+ *     await page.click(".menu-trigger");
+ *     await page.waitForSelector(".download-option");
+ *     await page.click(".download-option");
+ *   }
+ * });
+ * }
+ * ```
+ *
+ * @note
+ * All download functions in the helpers module accept Trigger for consistency.
+ * The trigger method determines how the download operation is initiated.
+ */
+export type Trigger = string | Locator | ((page: Page) => Promise<void>);
+
+/**
+ * Configuration options for AWS S3 storage operations.
+ *
+ * This interface defines the authentication and configuration properties
+ * for connecting to and performing operations with AWS S3 storage. All properties
+ * are optional and will fall back to environment variables or default configuration.
+ *
+ * @interface S3Configs
+ * @example
+ * ```typescript S3 Configuration
+ * import { uploadFileToS3 } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * // Basic S3 configuration
+ * const s3Config: S3Configs = {
+ *   bucket: "my-app-uploads",
+ *   region: "us-east-1",
+ *   accessKeyId: "accessKeyId",
+ *   secretAccessKey: "SecretAccessKeyId"
+ * };
+ *
+ * // Use with file upload
+ * const attachment = await uploadFileToS3({
+ *   file: myFile,
+ *   configs: s3Config
+ * });
+ *
+ * // Use with download and upload operations
+ * const uploadedFile = await saveFileToS3({
+ *   page,
+ *   trigger: downloadUrl,
+ *   configs: s3Config
+ * });
+ * }
+ * ```
+ */
+export interface S3Configs {
+  /** The name of the S3 bucket where files will be stored or retrieved */
+  bucket?: string;
+
+  /** The AWS region where the S3 bucket is located (e.g., "us-east-1", "eu-west-1") */
+  region?: string;
+
+  /** AWS access key ID for authentication and authorization */
+  accessKeyId?: string;
+
+  /** AWS secret access key for authentication and authorization */
+  secretAccessKey?: string;
+
+  /** Custom S3 endpoint URL for S3-compatible storage services */
+  endpoint?: string;
+}
+
+/**
+ * A union type representing different file formats that can be processed by the SDK.
+ *
+ * This type alias provides flexibility in how files can be passed to various functions,
+ * supporting multiple input formats for maximum convenience.
+ *
+ * @type FileType
+ *
+ * **Type Information:**
+ * - `Download`: Playwright Download object from browser download operations
+ * - `Uint8Array`: Binary data as Uint8Array
+ * - `Buffer`: Node.js Buffer containing binary data
+ * - `ReadStream`: Node.js file stream for reading files
+ *
+ * @example
+ * ```typescript Using Download Object
+ * import { downloadFile, uploadFileToS3 } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * // From a browser download
+ * const download = await downloadFile({
+ *   page,
+ *   trigger: "https://example.com/file.pdf"
+ * });
+ * const uploaded = await uploadFileToS3({
+ *   file: download,
+ *   configs: s3Config
+ * });
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Using Buffer
+ * import { uploadFileToS3 } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * // From raw buffer
+ * const fileBuffer = Buffer.from("PDF content here...", "utf8");
+ * const uploaded = await uploadFileToS3({
+ *   file: fileBuffer,
+ *   fileNameOverride: "generated.pdf",
+ *   configs: s3Config
+ * });
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Using ReadStream
+ * import { uploadFileToS3 } from "@intuned/browser";
+ * import { createReadStream } from "fs";
+ * export default async function handler(params, page, context){
+ * // From a file stream
+ * const fileStream = createReadStream("/path/to/document.pdf");
+ * const uploaded = await uploadFileToS3({
+ *   file: fileStream,
+ *   fileNameOverride: "renamed.pdf",
+ *   configs: s3Config
+ * });
+ * }
+ * ```
+ */
+export type FileType = Download | Uint8Array | Buffer | ReadStream;
+
+/**
+ * Downloads a file from a web page and automatically uploads it to AWS S3 storage in a single operation.
+ *
+ * This convenience function combines the functionality of `downloadFile` and `uploadFileToS3`,
+ * providing a streamlined workflow for capturing files from web pages and storing them in S3.
+ * It supports the same flexible trigger methods as `downloadFile` with additional S3 upload configuration.
+ *
+ * @param {Object} input - Configuration object for the download and upload operation
+ * @param {Page} input.page - The Playwright Page object to use for downloading
+ * @param {Trigger} input.trigger - The [Trigger](../type-aliases/Trigger) method to initiate the download:
+ *   - **URL string**: Navigate directly to a download URL
+ *   - **Locator**: Click on an element to trigger download
+ *   - **Callback function**: Execute custom logic to initiate download
+ * @param {number} [input.timeoutInMs=5000] - Maximum time in milliseconds to wait for download completion. Defaults to 5000.
+ * @param {S3Configs} [input.configs] - Optional [S3Configs](../interfaces/S3Configs) to customize the S3 upload
+ * @param {string} [input.fileNameOverride] - Optional filename override for the uploaded file
+ * @param {string} [input.contentType] - Optional content type for the uploaded file
+ * @returns {Promise<Attachment>} Promise that resolves to an [Attachment](../interfaces/Attachment) object with file metadata and S3 utilities
+ *
+ * @example
+ * ```typescript URL trigger
+ * import { saveFileToS3 } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * // Download from URL and upload to S3 with custom configuration
+ * const uploadedFile = await saveFileToS3({
+ *   page,
+ *   trigger: "https://sandbox.intuned.dev/pdfs/report.pdf",
+ *   configs: {
+ *      bucket: 'document-storage',
+ *       region: 'us-east-1',
+ *       accessKeyId: 'accessKeyId',
+ *       secretAccessKey: 'SecretAccessKeyId'
+ * },
+ * fileNameOverride: 'reports/monthly-report.pdf',
+ * contentType: 'application/pdf'
+ * });
+ *
+ * console.log(`File uploaded to: ${uploadedFile.getS3Key()}`);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Locator trigger
+ * import { saveFileToS3 } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ * // Click download link and save to S3
+ * await page.goto("https://sandbox.intuned.dev/pdfs")
+ * const uploadedFile = await saveFileToS3({
+ *   page,
+ *   trigger: page.locator("xpath=//tbody/tr[1]//*[name()='svg']"),
+ *   timeoutInMs: 10000,
+ *   configs: {
+ *     bucket: 'invoice-archive',
+ *     region: 'us-west-2',
+ *     accessKeyId: 'accessKeyId',
+ *     secretAccessKey: 'SecretAccessKeyId'
+ *   },
+ *   fileNameOverride: 'invoices/invoice.pdf',
+ *   contentType: 'application/pdf'
+ * });
+ *
+ * // Generate temporary access URL
+ * const downloadUrl = await uploadedFile.getSignedUrl(7200); // 2 hours
+ * console.log(`Temporary access: ${downloadUrl}`);
+ * }
+ * ```
+ * @note
+ * **S3 Configuration hierarchy:** (same as `uploadFileToS3`):
+ * 1. Explicit `configs` values from the input
+ * 2. Standard AWS environment variables (`AWS_BUCKET`, `AWS_REGION`, etc.)
+ * 3. Intuned's default S3 configuration as fallback
+ *
+ * **Trigger Behavior** (same as `downloadFile`):
+ * - **URL**: Creates temporary page, navigates to URL, captures download, closes page
+ * - **Locator**: Uses current page to click element and capture download
+ * - **Callback**: Executes custom function and captures any resulting downloads
+ */
+export declare function saveFileToS3(input: {
+  page: Page;
+  trigger: Trigger;
+  timeoutInMs?: number;
+  configs?: S3Configs;
+  fileNameOverride?: string;
+  contentType?: string;
+}): Promise<Attachment>;
+
+/**
+ * Union type representing the supported attachment file types.
+ *
+ * @type AttachmentType
+ * Currently supported types:
+ * - `"document"`: Document files (PDFs, Word docs, etc.)
+ */
+export type AttachmentType = "document";