@intuned/browser-dev 2.2.3-unify-sdks.20

package/dist/helpers/export.d.ts

@@ -0,0 +1,1294 @@
+/* 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";
+
+/**
+ * Configuration options for sanitizing HTML content.
+ */
+export interface SanitizeHtmlOptions {
+  /** 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 {string} htmlString - The HTML content to sanitize
+ * @param {SanitizeHtmlOptions} options - Configuration options for sanitization
+ * @returns {string} The sanitized HTML string
+ *
+ * @example
+ * ```typescript Basic HTML Sanitization
+ * import { sanitizeHtml } from "@intuned/sdk/helpers";
+ *
+ * const dirtyHtml = `
+ *   <div>
+ *     <script>alert('xss')</script>
+ *     <p style="color: red;">Hello World</p>
+ *     <span></span>
+ *   </div>
+ * `;
+ *
+ * const sanitizedHtml = sanitizeHtml(dirtyHtml);
+ * // Returns: '<div><p>Hello World</p></div>'
+ * ```
+ *
+ * @example
+ * ```typescript Custom Sanitization Options
+ * import { sanitizeHtml } from "@intuned/sdk/helpers";
+ *
+ * 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"]
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript Preserve Specific Elements
+ * import { sanitizeHtml } from "@intuned/sdk/helpers";
+ *
+ * const html = `
+ *   <div>
+ *     <svg><path d="M10,10"/></svg>
+ *     <img src="image.jpg" alt="" />
+ *     <span></span>
+ *   </div>
+ * `;
+ *
+ * // Keep SVGs and empty spans
+ * const result = sanitizeHtml(html, {
+ *   removeSvgs: false,
+ *   preserveEmptyTags: ["img", "span"]
+ * });
+ * ```
+ */
+
+export declare function sanitizeHtml(
+  htmlString: string,
+  options?: SanitizeHtmlOptions
+): string;
+
+/**
+ * Download a file from a web page using a trigger
+ * This function supports three different ways to trigger a download:
+ *     1. By URL
+ *     2. By clicking on a playwright locator
+ *     3. By executing a callback function that takes a page object as an argument and uses it to initiate the download.
+ * @param {Page} page - The Playwright Page object.
+ * @param {Trigger} trigger - [Trigger](../type-aliases/Trigger) to use for downloading the file.
+ * @param {number} [options.timeoutInMs=5000] - Optional. The maximum time in milliseconds to wait for the download to complete. Default = 5000
+ * @returns {Promise<Download >} A promise that resolves to a playwright Download object.
+ *
+ * @example
+ * ```typescript URL Download
+ * import { downloadFile } from "@intuned/sdk/helpers";
+ *
+ * const download = await downloadFile(page, "https://sandbox.intuned.dev/pdfs");
+ * console.log(await download.path());
+ * ```
+ *
+ * @example
+ * ```typescript Locator Download - Link
+ * import { downloadFile } from "@intuned/sdk/helpers";
+ *
+ * const download = await downloadFile(page, page.locator("[href='/download/file.pdf']"));
+ * console.log(await download.path());
+ * ```
+ *
+ * @example
+ * ```typescript Locator Download - Button
+ * import { downloadFile } from "@intuned/sdk/helpers";
+ *
+ * const download = await downloadFile(page, page.locator("button:has-text('Download')"));
+ * console.log(await download.path());
+ * ```
+ *
+ * @example
+ * ```typescript Callback Function Download
+ * import { downloadFile } from "@intuned/sdk/helpers";
+ *
+ * const download = await downloadFile(page, (page) => page.locator("button:has-text('Download')").click());
+ * console.log(await download.path());
+ * ```
+ * - If a URL is provided as the trigger, a new page will be created and closed after the download is complete.
+ * - If a locator is provided as the trigger, the page will be used to click the element and initiate the download.
+ * - If a callback function is provided as the trigger, the function will be called with the page object as an argument and will be responsible for initiating the download.
+ */
+export declare function downloadFile(options: {
+  page: Page;
+  trigger: Trigger;
+  timeoutInMs?: number;
+}): Promise<Download>;
+
+/**
+ * Recursively filters out empty values from nested dictionaries and arrays.
+ *
+ * Removes:
+ * - null/undefined values
+ * - Empty strings (after trimming whitespace)
+ * - Empty arrays
+ * - Empty objects
+ * - Arrays/objects that become empty after filtering their contents
+ *
+ * @param {T} 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
+ * filterEmptyValues({ a: "", b: "hello", c: null }) // Returns { b: "hello" }
+ * filterEmptyValues([1, "", null, [2, ""]]) // Returns [1, [2]]
+ * filterEmptyValues({ users: [{ name: "" }, { name: "John" }] }) // Returns { users: [{ name: "John" }] }
+ * ```
+ */
+export declare function filterEmptyValues<T>(input: { data: T }): T;
+
+/**
+ * Navigates to a specified URL on the provided playwright page.
+ *
+ * @param {Page} page - The Playwright page object to navigate.
+ * @param {string} url - The URL to navigate to.
+ * @param {number} [options.retries] - Referer header value. If provided, it will take preference over the referer header value set by `page.setExtraHTTPHeaders(headers)`.
+ * @param {number} [options.timeoutInMs=30000] - Maximum operation time in milliseconds. This can be configured via various timeout settings on the page or browser context. default 30000.
+ 
+ * @param {string} [options.waitUntil=networkidle] - When to consider the operation succeeded. Default = networkidle
+ * @param {boolean} [options.throwOnTimeout=False] - Whether to throw if the `page.goto` times out. By default, it ignores the error. default = false.
+ * @param {boolean} [options.waitForLoadingStateUsingAi=False] - If true, it will perform an AI Check to determine if the page is fully loaded and idle. default = false.
+ * @param {ModelType} [options.model] - [ModelType](../type-aliases/modelType) to use for the AI Check. default claude-3-haiku-20240307
+ * @param {string} [options.apiKey] - The API key for the AI service. If not provided, it will use the default API key.
+ * @returns {void} - Returns nothing. If the operation fails, it will throw an error unless `throwOnTimeout` is set to false.
+ *
+ * @example
+ * ```typescript without options
+ * import { goto } from "@intuned/sdk/helpers";
+ *
+ * await goto(page, 'https://example.com');
+ *
+ * ```
+ *
+ * ```typescript with options
+ *  import { goto } from "@intuned/sdk/helpers";
+ *
+ *  await goto(page, 'https://example.com', {
+ *    waitUntil: "load",
+ *    throwOnTimeout: true,
+ *    timeoutInMs: 10_000,
+ *    retries: 3,
+ *    waitForLoadingStateUsingAi: true,
+ *    model: "gpt-4",
+ *  });
+ * ```
+ */
+export declare function goToUrl(input: {
+  page: Page;
+  url: string;
+  timeoutInMs?: number;
+  waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+  retries?: number;
+  throwOnTimeout?: boolean;
+  waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+  waitForLoadingStateUsingAi?: boolean;
+  model?: ModelType;
+  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} [options] - Configuration options
+ * @param {Page | Locator} [ptions.page] - The Playwright page object
+ * @param {Function} [options.onScrollProgress] - Optional callback function to call during each scroll iteration
+ * @param {Locator} [options.scrollableContainer] - Specific element to scroll.
+ * @param {number} [options.maxScrolls=50] - Maximum number of scroll attempts before stopping, default = 50
+ * @param {number} [options.delay=100] - Delay in milliseconds between scroll attempts, default = 100
+ * @param {number} [options.minHeightChange=100] - Minimum height change required to continue scrolling, default = 100
+ * @returns {Promise<void>} Promise that resolves when scrolling is complete
+ *
+ * @example
+ * ```typescript Basic Infinite Scroll
+ * import { scrollToLoadContent } from "@intuned/sdk/helpers";
+ *
+ * // Scroll through entire page content
+ * await scrollToLoadContent(page);
+ *
+ * // Now all content is loaded and visible
+ * const allItems = await page.locator('.item').count();
+ * ```
+ *
+ * @example
+ * ```typescript Scroll Specific Container
+ * import { scrollToLoadContent } from "@intuned/sdk/helpers";
+ *
+ * // Scroll through a specific scrollable div
+ * const container = page.locator('.scrollable-feed');
+ * await scrollToLoadContent(page, undefined, {
+ *   scrollableContainer: container,
+ *   maxScrolls: 20
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript With Progress Tracking
+ * import { scrollToLoadContent } from "@intuned/sdk/helpers";
+ *
+ * let scrollCount = 0;
+ * await scrollToLoadContent(
+ *   page,
+ *   () => console.log(`Scroll attempt ${++scrollCount}`),
+ *   {
+ *     maxScrolls: 100,
+ *     delay: 0.5
+ *   }
+ * );
+ * ```
+ */
+
+export declare function scrollToLoadContent(options: {
+  page: Page | Locator;
+  onScrollProgress?: CallableFunction;
+  scrollableContainer?: Locator | null;
+  maxScrolls?: number;
+  delay?: number;
+  minHeightChange?: number;
+}): Promise<void>;
+
+/**
+ * Uses AI vision to determine if a webpage has finished loading by analyzing a screenshot.
+ * Detects loading spinners, blank content, or incomplete page states.
+ *
+ * @param {Page} page - The Playwright page to check
+ * @param {Object} [options] - Optional configuration object
+ * @param {ModelType} [options.model="gpt-4o-2024-08-06"] - [ModelType](../type-aliases/modelType) to use for the AI Check. default gpt-4o-2024-08-06
+ * @param {number} [options.timeoutInMs=10000] - Screenshot timeout in milliseconds
+ * @param {string} [options.apiKey] - Optional API key for the AI service
+ * @returns {Promise.<{status: LoadingStatus, reason: (string|null|undefined), cost: (number|undefined)}>}
+ * - `status`: "True" if page is loaded, "False" if still loading, "Dont know" if uncertain
+ * - `reason`: Optional reason for the status (e.g., detected loading spinner)
+ * - `cost`: Optional cost of the AI analysis (if applicable)
+ * @example
+ * ```typescript Check Page Loading
+ * import { isPageLoaded } from "@intuned/sdk/helpers";
+ *
+ * // Wait for page to finish loading
+ * await page.goto('https://example.com');
+ *
+ * const pageLoaded = await isPageLoaded(page);
+ * if (pageLoaded['status']) {
+ *   console.log("Page loaded:", pageLoaded['reason']);
+ *   // Continue with scraping or interactions
+ * } else {
+ *   console.log("Still loading:", pageLoaded['reason']);
+ *   // Wait longer or retry
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Loading Loop
+ * import { isPageLoaded } from "@intuned/sdk/helpers";
+ *
+ * // Keep checking until page loads
+ * let attempts = 0;
+ * while (attempts < 10) {
+ *   const pageLoaded = await isPageLoaded(page, "gpt-4o", 5);
+ *   if (pageLoaded['status']) break;
+ *
+ *   await page.waitForTimeout(2000);
+ *   attempts++;
+ * }
+ * ```
+ *
+ */
+export declare function isPageLoaded(
+  page: Page,
+  options?: {
+    timeoutInMs?: number;
+    model?: ModelType;
+    apiKey?: string;
+  }
+): Promise<{
+  status: LoadingStatus;
+  reason?: string | null;
+  cost?: number;
+}>;
+
+/**
+ * Process various date string formats into Date objects.
+ * Returns only the date part (year, month, day).
+ * This method can accept a 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 {string} dateString - A string containing a date in various possible formats
+ * @returns Date object with only date components if parsing successful, null if parsing fails
+ *
+ * @example
+ * ```typescript Basic Date Processing
+ * import { processDate } from "@intuned/sdk/helpers";
+ * 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 a downloaded file to S3 storage.
+ * @param {S3UploadableFile} file - The file to upload, it can be a downloaded file by the downloadFile function or another content, the file is of type [S3UploadableFile](../type-aliases/S3UploadableFile.md)
+ * @param {Object} options - The options for uploading the file.
+ * @param {S3Configs} [options.s3Configs] - Optional [S3Configs](../interfaces/S3Configs) configuration options.
+ * @param {string} [options.fileNameOverride] - Optional. Override for the file name.
+ * @param {string} [options.contentType] - Optional. The MIME type of the file, used to specify the type of content being uploaded to S3.
+ * @returns {Promise<Attachment>} A promise that resolves to an [Attachment](../interfaces/Attachment) object containing the uploaded file's details.
+ *
+ *
+ * @example
+ * ```typescript Download
+ * import { downloadFile, uploadFileToS3 } from "@intuned/sdk/helpers";
+ *
+ * const download = await downloadFile(page, {
+ *   type: "DownloadByOpeningNewTab",
+ *   downloadTrigger: (page) => page.locator(".download_button").click(),
+ * });
+ *
+ * const s3Configs: S3Configs = {
+ *   bucket: 'my-bucket',
+ *   region: 'us-west-1',
+ *   accessKeyId: '....',
+ *   secretAccessKey: '....'
+ * };
+ *
+ * const uploadedFile = await uploadFileToS3(download, { s3Configs });
+ * console.log(uploadedFile.urlDescriptor());
+ * ```
+ */
+
+export declare function uploadFileToS3(input: {
+  file: S3UploadableFile;
+  configs?: S3UploadOptions;
+}): Promise<Attachment>;
+
+/**
+ * Validates data against a JSON schema using AJV validator.
+ * The function automatically cleans the input data before validation by removing empty strings, null values, and undefined properties (recursively for nested objects and arrays), then throws a detailed ValidationError if the cleaned data doesn't match the schema requirements.
+ * @param {DataInput} data - [DataInput](../interfaces/DataInput) is the data to validate (will be cleaned before validation)
+ * @param {Record<string, any>} 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/sdk/helpers";
+ *
+ * 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(userData, userSchema);
+ * // Validation passes, no error thrown
+ * ```
+ *
+ * @example
+ * ```typescript API Response Validation
+ * import { validateDataUsingSchema } from "@intuned/sdk/helpers";
+ *
+ * const apiResponse = {
+ *   success: true,
+ *   data: {
+ *     items: [
+ *       { id: 1, title: "Product 1", price: 29.99 },
+ *       { id: 2, title: "Product 2", price: 49.99 }
+ *     ],
+ *     total: 2
+ *   }
+ * };
+ *
+ * const responseSchema = {
+ *   type: "object",
+ *   required: ["success", "data"],
+ *   properties: {
+ *     success: { type: "boolean" },
+ *     data: {
+ *       type: "object",
+ *       required: ["items", "total"],
+ *       properties: {
+ *         items: {
+ *           type: "array",
+ *           items: {
+ *             type: "object",
+ *             required: ["id", "title", "price"],
+ *             properties: {
+ *               id: { type: "number" },
+ *               title: { type: "string" },
+ *               price: { type: "number", minimum: 0 }
+ *             }
+ *           }
+ *         },
+ *         total: { type: "number", minimum: 0 }
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * await validateDataUsingSchema(apiResponse, responseSchema);
+ * // Validates complex nested API response structure
+ * ```
+ *
+ * @example
+ * ```typescript Form Data Validation with Error Handling
+ * import { validateDataUsingSchema, ValidationError } from "@intuned/sdk/helpers";
+ *
+ * const formData = {
+ *   username: "",  // Invalid: empty string
+ *   password: "123",  // Invalid: too short
+ *   confirmPassword: "456",  // Invalid: doesn't match
+ *   email: "invalid-email"  // Invalid: bad format
+ * };
+ *
+ * const formSchema = {
+ *   type: "object",
+ *   required: ["username", "password", "email"],
+ *   properties: {
+ *     username: { type: "string", minLength: 3 },
+ *     password: { type: "string", minLength: 8 },
+ *     email: { type: "string", format: "email" }
+ *   }
+ * };
+ *
+ * try {
+ *   await validateDataUsingSchema(formData, formSchema);
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.error('Validation failed:', error.message);
+ *     console.error('Invalid data:', error.data);
+ *     // Handle validation errors in UI
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Configuration Validation
+ * import { validateDataUsingSchema } from "@intuned/sdk/helpers";
+ *
+ * const config = {
+ *   database: {
+ *     host: "localhost",
+ *     port: 5432,
+ *     name: "myapp"
+ *   },
+ *   features: {
+ *     enableLogging: true,
+ *     maxRetries: 3,
+ *     timeoutInMs: 30000
+ *   }
+ * };
+ *
+ * const configSchema = {
+ *   type: "object",
+ *   required: ["database", "features"],
+ *   properties: {
+ *     database: {
+ *       type: "object",
+ *       required: ["host", "port", "name"],
+ *       properties: {
+ *         host: { type: "string", minLength: 1 },
+ *         port: { type: "number", minimum: 1, maximum: 65535 },
+ *         name: { type: "string", pattern: "^[a-zA-Z0-9_]+$" }
+ *       }
+ *     },
+ *     features: {
+ *       type: "object",
+ *       properties: {
+ *         enableLogging: { type: "boolean" },
+ *         maxRetries: { type: "number", minimum: 0, maximum: 10 },
+ *         timeoutInMs: { type: "number", minimum: 1000 }
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * await validateDataUsingSchema(config, configSchema);
+ * // Ensures configuration meets requirements before app startup
+ * ```
+ *
+ */
+export declare function validateDataUsingSchema(input: {
+  data: DataInput;
+  schema: Record<string, any>;
+}): Promise<void>;
+
+/**
+ * Versatile function that waits for network requests to settle after executing an action.
+ * Can be used as a simple decorator, parameterized decorator, or direct async call.
+ *
+ * @param {Function | Object} funcOrOptions - Either a function to wrap, configuration options for decorator, or full options with page and function
+ * @param {number} [funcOrOptions.timeoutInMs=30000] - Maximum time to wait in milliseconds before timing out
+ * @param {number} [funcOrOptions.maxInflightRequests=0] - Maximum number of pending requests to consider as "settled"
+ * @param {Page} [funcOrOptions.page] - Playwright page object (required for direct async call)
+ * @param {Function} [funcOrOptions.func] - Function to execute (required for direct async call)
+ * @returns {Function | Promise} Returns wrapped function for decorator usage, or Promise for direct async call
+ *
+ * @example
+ * ```typescript Simple Decorator Usage
+ * import { waitForNetworkIdle } from "@intuned/sdk/helpers";
+ *
+ * // Wrap any async function that takes a Page as first argument
+ * const clickAndWait = waitForNetworkIdle(async (page: Page, selector: string) => {
+ *   await page.locator(selector).click();
+ *   return 'clicked';
+ * });
+ *
+ * // Use the wrapped function - it will automatically wait for network to settle
+ * const result = await clickAndWait(page, '.submit-btn');
+ * ```
+ *
+ * @example
+ * ```typescript Parameterized Decorator Usage
+ * import { waitForNetworkIdle } from "@intuned/sdk/helpers";
+ *
+ * // Create a decorator with custom timeout and max inflight requests
+ * const scrollByAmount = waitForNetworkIdle({
+ *   timeoutInMs: 10000,
+ *   maxInflightRequests: 2
+ * })(async (page: Page, amount: number) => {
+ *   await page.mouse.wheel(0, amount);
+ * });
+ *
+ * // Use the configured wrapper
+ * await scrollByAmount(page, 500);
+ * ```
+ *
+ * @example
+ * ```typescript Direct Async Call Usage
+ * import { waitForNetworkIdle } from "@intuned/sdk/helpers";
+ *
+ * // Direct execution with all parameters provided
+ * const result = await waitForNetworkIdle({
+ *   page,
+ *   func: async () => {
+ *     await page.locator('.submit-btn').click();
+ *     await page.fill('#input', 'some text');
+ *     return 'form submitted';
+ *   },
+ *   timeoutInMs: 30000,
+ *   maxInflightRequests: 0
+ * });
+ *
+ * console.log(result); // 'form submitted'
+ * ```
+ *
+ * @example
+ * ```typescript Real-world Usage in Tests
+ * import { waitForNetworkIdle } from "@intuned/sdk/helpers";
+ *
+ * // Test with network-heavy interactions
+ * const clickElement = waitForNetworkIdle({ timeoutInMs: 10000 })(
+ *   async (page: Page, selector: string, timeoutInMs = 10) => {
+ *     await page.locator(selector).first().click({ timeout: timeoutInMs});
+ *   }
+ * );
+ *
+ * await page.goto("https://example.com/search");
+ * await clickElement(page, "[aria-label='Next page']", 10);
+ * // Function automatically waits for all network requests to complete
+ * ```
+ */
+export declare function waitForNetworkIdle(
+  funcOrOptions?:
+    | ((...args) => Promise<any>)
+    | { timeoutInMs?: number; maxInflightRequests?: number }
+    | {
+        page: Page;
+        func: (...args: T) => Promise<any>;
+        timeoutInMs?: number;
+        maxInflightRequests?: number;
+      }
+): any;
+
+/**
+ * Wait 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 options - Configuration object with different properties based on the overload
+ * @param {Page} options.page - The Playwright Page to monitor for DOM changes.
+ *   When provided, monitors the entire document for changes.
+ * @param {Locator} options.locator - The Playwright Locator pointing to a specific
+ *   element to monitor. When provided, only monitors changes within this element.
+ * @param {number} [options.settleDuration=500] - Milliseconds the DOM must remain unchanged to be
+ *   considered settled. Defaults to 0.5.
+ * @param {number} [options.timeoutInMs=30000] - Maximum milliseconds to wait before giving up.
+ *   Defaults to 30000.
+ *
+ * @returns Promise that resolves to true if DOM settled within timeout, false if timeout error occurred
+ *
+ * @throws {Error} When invalid parameter combinations are provided (both page and locator,
+ *   or neither page nor locator)
+ *
+ * @example
+ * ```typescript Wait for Page Content to Stabilize
+ * import { waitForDomSettled } from '@intuned/sdk';
+ *
+ * // Navigate to a dynamic page
+ * await page.goto('https://dynamic-site.com');
+ *
+ * // Wait for entire page content to stabilize
+ * const settled = await waitForDomSettled({
+ *   page: page,
+ *   settleDuration: 1000
+ * });
+ *
+ * if (settled) {
+ *   // Safe to scrape or interact with content
+ *   const items = await page.locator('.item').count();
+ *   console.log(`Found ${items} stable items`);
+ * } else {
+ *   console.log("DOM never fully settled, proceeding anyway");
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Monitor Specific Container
+ * import { waitForDomSettled } from '@intuned/sdk';
+ *
+ * // Wait for a specific feed container to stop updating
+ * const newsFeed = page.locator("#news-feed");
+ * const settled = await waitForDomSettled({
+ *   locator: newsFeed,
+ *   settleDuration: 2000,
+ *   timeoutInMs: 15000,
+ * });
+ *
+ * if (settled) {
+ *   // Now the feed is stable, safe to extract articles
+ *   const articles = await newsFeed.locator('.article').all();
+ *   console.log(`Feed stabilized with ${articles.length} articles`);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Handle Fast-Changing Content
+ * import { waitForDomSettled } from '@intuned/sdk';
+ *
+ * // For rapidly updating content, use shorter settle duration
+ * const liveScores = page.locator("#live-scores");
+ * const settled = await waitForDomSettled({
+ *   locator: liveScores,
+ *   settleDuration: 200,  // Very brief pause in updates
+ *   timeoutInMs: 10000,
+ * });
+ *
+ * // Capture current state even if constantly updating
+ * const currentScores = await liveScores.textContent();
+ * ```
+ *
+ * @example
+ * ```typescript Robust Error Handling
+ * import { waitForDomSettled } from '@intuned/sdk';
+ *
+ * try {
+ *   // Wait for dynamic table to settle
+ *   const settled = await waitForDomSettled({
+ *     page: page,
+ *     settleDuration: 1500,
+ *     timeoutInMs: 20000,
+ *   });
+ *
+ *   if (settled) {
+ *     // Extract data from settled DOM
+ *     const rows = await page.locator('tbody tr').count();
+ *     console.log(`Table settled with ${rows} rows`);
+ *   } else {
+ *     console.log("DOM never fully settled, proceeding anyway");
+ *   }
+ * } catch (error) {
+ *   console.log(`DOM monitoring failed: ${error}`);
+ *   // Fallback to simple wait
+ *   await page.waitForTimeout(2000);
+ * }
+ * ```
+ */
+
+export async function waitForDomSettled(options: {
+  page: Page;
+  settleDuration?: number;
+  timeoutInMs?: number;
+}): Promise<boolean>;
+
+export async function waitForDomSettled(options: {
+  locator: Locator;
+  settleDuration?: number;
+  timeoutInMs?: number;
+}): Promise<boolean>;
+
+/**
+ * Convert HTML content or a Playwright locator to semantic markdown.
+ *
+ * @param {string | Locator} source - The source of the HTML content, can be a string of HTML or a Playwright Locator.
+ * @returns {Promise<string>} A promise that resolves to the markdown representation of the HTML content.
+ * @example
+ * ```typescript locator source
+ * import { extractMarkdown } from "@intuned/sdk/helpers";
+ * import { Page, Locator } from "playwright";
+ * headerLocator = page.locator('h1')
+ * markdown = await extractMarkdown(headerLocator)
+ * console.log(markdown); // Outputs the markdown representation of the header
+ * ```
+ * @example
+ * ```typescript string source
+ * import { extractMarkdown } from "@intuned/sdk/helpers";
+ * import { Page } from "playwright";
+ * const htmlString = "<h1>Hello World</h1>";
+ * markdown = await extractMarkdown(htmlString);
+ * console.log(markdown); // Outputs "# Hello World"
+ * ```
+ *
+ */
+export declare function extractMarkdown(input: {
+  source: Page | Locator;
+}): Promise<string>;
+
+/**
+ * Convert any URL source to an absolute, properly encoded URL.
+ *
+ * This function provides a unified interface for resolving URLs from different sources:
+ * string URLs (relative or absolute), Playwright Locators pointing to anchor elements,
+ * or Locator objects representing anchor elements.
+ *
+ * @param options - Configuration object with different properties based on the overload
+ * @param {string | Locator} options.url - The URL source to resolve.
+ *   - If string: A relative or absolute URL string
+ *   - If Locator: Must point to an anchor element
+ *   - If ElementHandle: Must represent an anchor element
+ * @param {string} [options.baseUrl] - Base URL string to resolve relative URLs against.
+ *   Required when url is a string and page is not provided.
+ *   Cannot be used with Locator url.
+ * @param {Page} [options.page] - Playwright Page object to extract base URL from.
+ *   Required when url is a string and baseUrl is not provided.
+ *   Cannot be used with Locator url.
+ *
+ * @returns Promise that resolves to the absolute, properly encoded URL string
+ *
+ * @throws {Error} When invalid parameter combinations are provided or when
+ *   Locator doesn't point to an anchor element
+ * @throws {TypeError} When url is not of a supported type
+ *
+ * @example
+ * ```typescript Resolve String URLs with baseUrl
+ * import { resolveUrl } from '@intuned/sdk';
+ *
+ * // Using explicit base URL
+ * const absoluteUrl = await resolveUrl({
+ *   url: "/api/users",
+ *   baseUrl: "https://example.com"
+ * });
+ * // Returns: "https://example.com/api/users"
+ * ```
+ *
+ * @example
+ * ```typescript Resolve String URLs with page
+ * import { resolveUrl } from '@intuned/sdk';
+ *
+ * // Using current page as base
+ * await page.goto("https://example.com/dashboard");
+ * const absoluteUrl = await resolveUrl({
+ *   url: "../settings",
+ *   page: page
+ * });
+ * // Returns: "https://example.com/settings"
+ * ```
+ *
+ * @example
+ * ```typescript Resolve from Anchor Elements with Locator
+ * import { resolveUrl } from '@intuned/sdk';
+ *
+ * // Using Locator pointing to anchor
+ * const linkLocator = page.locator('a[href="/products"]');
+ * const absoluteUrl = await resolveUrl({ url: linkLocator });
+ * // Returns: "https://example.com/products" (automatically resolved by browser)
+ * ```
+ *
+ * @example
+ * ```typescript Resolve from Anchor Elements with ElementHandle
+ * import { resolveUrl } from '@intuned/sdk';
+ *
+ * // Using ElementHandle
+ * const anchorElement = await page.$('a.nav-link');
+ * if (anchorElement) {
+ *   const absoluteUrl = await resolveUrl({ url: anchorElement });
+ *   // Returns the fully resolved href attribute
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Handle Complex URLs
+ * import { resolveUrl } from '@intuned/sdk';
+ *
+ * // URLs with special characters are properly encoded
+ * const encodedUrl = await resolveUrl({
+ *   url: "/search?q=hello world&category=news",
+ *   baseUrl: "https://example.com"
+ * });
+ * // Returns: "https://example.com/search?q=hello%20world&category=news"
+ *
+ * // Already absolute URLs are returned unchanged
+ * const fullUrl = await resolveUrl({
+ *   url: "https://other-site.com/page",
+ *   baseUrl: "https://example.com"
+ * });
+ * // Returns: "https://other-site.com/page"
+ * ```
+ */
+
+export declare function resolveUrl(options: {
+  url: string | Locator;
+  baseUrl?: string;
+  page?: Page;
+}): Promise<string>;
+
+/**
+ * DataObject is a record of string keys and any values.
+ * It can be used to represent a single data object.
+ */
+export type DataObject = Record<string, any>;
+
+/**
+ * DataInput is a [DataObject](./DataObject) or an array of DataObjects.
+ * It can be used to represent either a single data object or an array of data objects.
+ */
+export type DataInput = DataObject | DataObject[];
+
+/**
+ * @class Attachment
+ * 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 signed URLs, serialization, and accessing
+ * file metadata.
+ *
+ * @example
+ * ```typescript
+ * // Create from data
+ * const fileData = {
+ *   fileName: "documents/report.pdf",
+ *   bucket: "my-uploads",
+ *   region: "us-east-1",
+ *   suggestedFileName: "Monthly Report.pdf"
+ * };
+ * const uploadedFile: Attachment = createUploadedFile(fileData);
+ *
+ * // Get a signed URL for download
+ * const downloadUrl = await uploadedFile.getSignedUrl(3600); // 1 hour
+ *
+ * // Convert to dictionary for storage
+ * 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;
+
+  /**
+   * @method UploadFile.toJSON
+   * Returns a JSON-serializable record representation of the file.
+   * @returns Complete model data including all fields
+   *
+   * @example
+   * ```typescript
+   * file.toJSON()
+   * // {
+   * //   'fileName': 'docs/report.pdf',
+   * //   'bucket': 'uploads',
+   * //   'region': 'us-east-1',
+   * //   'endpoint': undefined,
+   * //   'suggestedFileName': 'Report.pdf'
+   * // }
+   * ```
+   */
+  toJSON(): Record<string, string>;
+
+  /**
+   * @method UploadFile.toDict
+   * Converts the file metadata to a record, excluding the endpoint field.
+   *
+   * @returns Record with fileName, bucket, region, and suggestedFileName
+   *
+   * @example
+   * ```typescript
+   * file.toDict()
+   * // {
+   * //   'fileName': 'docs/report.pdf',
+   * //   'bucket': 'uploads',
+   * //   'region': 'us-east-1',
+   * //   'suggestedFileName': 'Report.pdf'
+   * // }
+   * ```
+   */
+  toDict(): Record<string, string>;
+
+  /**
+   * @method UploadFile.getS3Key
+   * Returns the full S3 URL for the file.
+   *
+   * @returns Complete S3 URL
+   *
+   * @example
+   * ```typescript
+   * file.getS3Key()
+   * // "https://uploads.s3.us-east-1.amazonaws.com/docs/report.pdf"
+   * ```
+   */
+  getS3Key(): string;
+
+  /**
+   * @method UploadFile.getFilePath
+   * Returns the file path/key within the S3 bucket.
+   *
+   * @returns The fileName property (S3 object key)
+   *
+   * @example
+   * ```typescript
+   * file.getFilePath()
+   * // "docs/report.pdf"
+   * ```
+   */
+  getFilePath(): string;
+
+  /**
+   * @method UploadFile.getBucket
+   * Generates a presigned URL for secure, temporary access to the file.
+   *
+   * @param expiration - URL expiration time in seconds. Defaults to 432000 (5 days)
+   * @returns Promise that resolves to presigned URL for downloading the file
+   *
+   * @example
+   * ```typescript
+   * const url = await file.getSignedUrl(3600); // 1 hour expiration
+   * ```
+   */
+  getSignedUrl(expiration?: number): Promise<string>;
+}
+
+/**
+ * Types of triggers for downloading a file from a web page.
+ * - `string`: A URL to navigate to for downloading the file.
+ * - `Locator`: A Playwright Locator to click for initiating the download.
+ * - `(page: Page) => Promise<void>`: A callback function that takes a Playwright Page as an argument and performs actions to trigger the download.
+ */
+export type Trigger = string | Locator | ((page: Page) => Promise<void>);
+
+/**
+ * @interface S3Configs
+ * Configuration options for AWS S3 storage operations.
+ *
+ * This interface defines the required authentication and configuration properties
+ * for connecting to and performing operations with AWS S3 storage. All properties
+ * are required for proper S3 access.
+ *
+ * @example
+ * ```typescript
+ * // Basic S3 configuration
+ * const s3Config: S3Configs = {
+ *   bucket: "my-app-uploads",
+ *   region: "us-east-1",
+ *   accessKeyId: "AKIAIOSFODNN7EXAMPLE",
+ *   secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+ * };
+ *
+ * // Use with file upload
+ * const attachment = await uploadFileToS3(file, { s3Configs: s3Config });
+ *
+ * // Use with download operations
+ * const downloadedFile = await downloadFromPageToS3(page, url, { s3Configs: 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;
+}
+
+/**
+ * @interface S3UploadOptions
+ * Configuration options for customizing S3 file upload operations.
+ *
+ * This interface provides optional parameters to control various aspects of file uploads
+ * to AWS S3, including file naming, S3 configuration, custom endpoints, and content type
+ * specification. All properties are optional and have sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * // Basic upload with custom filename
+ * const options: S3UploadOptions = {
+ *   fileNameOverride: "reports/monthly-report-2024.pdf"
+ * };
+ * const attachment = await uploadFileToS3(file, options);
+ *
+ * // Complete configuration with custom S3 settings
+ * const fullOptions: S3UploadOptions = {
+ *   fileNameOverride: "documents/contract.pdf",
+ *   s3Configs: {
+ *     bucket: "legal-documents",
+ *     region: "us-west-2",
+ *     accessKeyId: "AKIAIOSFODNN7EXAMPLE",
+ *     secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+ *     endpoint: "https://s3.custom-domain.com",
+ *   },
+ *   contentType: "application/pdf"
+ * };
+ * const result = await uploadFileToS3(document, fullOptions);
+ * ```
+ */
+export interface S3UploadOptions {
+  /** Optional custom filename/key for the uploaded file in S3. If not provided, uses original filename */
+  fileNameOverride?: string;
+
+  /** Optional [S3Configs](../interfaces/S3Configs) configuration settings. If not provided, uses default or environment-configured S3 settings */
+  s3Configs?: S3Configs;
+
+  /** Optional MIME type specification for the uploaded file (e.g., "application/pdf", "image/jpeg") */
+  contentType?: string;
+}
+
+/**
+ * S3UploadableFile is a union of Download, Uint8Array, Buffer, and ReadStream.
+ */
+export type S3UploadableFile = Download | Uint8Array | Buffer | ReadStream;
+
+/**
+ * ModelType is a string representing the model type.
+ * Current supported models are:
+ * - "gpt-4o"
+ * - "gpt-4o-mini"
+ * - "gpt-4o-turbo"
+ * - "gpt-4o-turbo-preview"
+ * - "gpt-4o-turbo-preview-2024-07-18"
+ * - "gpt-4o-turbo-preview-2024-07-18"
+ */
+export type ModelType = string;
+
+/**
+ * Downloads a file from a web page and uploads it to S3 storage.
+ * This function supports three different ways to trigger a download:
+ *     - By URL
+ *     - By clicking on a Playwright locator
+ *     - By executing a callback function that takes a Playwright page as an argument and uses it to initiate the download.
+ * @param {Page} page - The Playwright Page object.
+ * @param {Trigger} trigger - [Trigger](../type-aliases/Trigger) to use for downloading the file.
+ * @param {number} [timeoutInMs] - The timeout in milliseconds for the download operation. Default = 5000
+ * @param {S3UploadOptions} uploadOptions - [S3UploadOptions](../interfaces/S3UploadOptions) for uploading the file to S3.
+ * @returns {Promise<Attachment>} A promise that resolves to an [Attachment](../interfaces/Attachment) object containing the uploaded file's details.
+ *
+ * @example
+ * ```typescript URL Download and Upload
+ * import { downloadFromPageToS3 } from "@intuned/sdk/helpers";
+ * import { S3UploadOptions } from "@intuned/sdk/types";
+ *
+ * const uploadOptions: S3UploadOptions = {
+ *   s3Configs: {
+ *     bucket: 'my-bucket',
+ *     region: 'us-west-1',
+ *      }
+ * };
+ * const uploadedFile = await downloadFromPageToS3(page, "https://sandbox.intuned.dev/pdfs", uploadOptions);
+ * console.log(uploadedFile.getS3Key());
+ * ```
+ *
+ * @example
+ * ```typescript Locator Download and Upload
+ * import { downloadFromPageToS3 } from "@intuned/sdk/helpers";
+ * import { S3UploadOptions } from "@intuned/sdk/types";
+ * const uploadOptions: S3UploadOptions = {
+ *   s3Configs: {
+ *     bucket: 'my-bucket',
+ *     region: 'us-west-1',
+ *   }
+ * };
+ * const uploadedFile = await downloadFromPageToS3(page, page.locator("[href='/download/file.pdf']"), uploadOptions);
+ * console.log(uploadedFile.getS3Key());
+ * ```
+ *
+ * @example
+ * ```typescript Callback Function Download and Upload
+ * import { downloadFromPageToS3 } from "@intuned/sdk/helpers";
+ * import { S3UploadOptions } from "@intuned/sdk/types";
+ * const uploadOptions: S3UploadOptions = {
+ *   s3Configs: {
+ *     bucket: 'my-bucket',
+ *   region: 'us-west-1',
+ * }
+ *  };
+ * const uploadedFile = await downloadFromPageToS3(page, async (page) => {
+ *   await page.locator("button:has-text('Download')").click();
+ * }, uploadOptions);
+ * console.log(uploadedFile.getS3Key());
+ * ```
+ * @note
+ * - If a URL is provided as the trigger, a new page will be created and closed after the download is complete.
+ * - If a locator is provided as the trigger, the page will be used to click the element and initiate the download.
+ * - If a callback function is provided as the trigger, the function will be called with the page object as an argument and will be responsible for initiating the download.
+ */
+export declare function downloadFromPageToS3(
+  page: Page,
+  trigger: Trigger,
+  timeoutInMs?: number,
+  uploadOptions: S3UploadOptions
+): Promise<Attachment>;
+/**
+ * Downloads a file from a web page and uploads it to S3 storage.
+ * This function supports three different ways to trigger a download:
+ *     - By URL
+ *     - By clicking on a Playwright locator
+ *     - By executing a callback function that takes a Playwright page as an argument and uses it to initiate the download.
+ * @param {Page} page - The Playwright Page object.
+ * @param {Trigger} trigger - [Trigger](../type-aliases/Trigger) to use for downloading the file.
+ * @param {number} [timeoutInMs = 5000] - The timeout in milliseconds for the download operation. Default = 5000
+ * @param {S3UploadOptions} uploadOptions - [S3UploadOptions](../interfaces/S3UploadOptions) for uploading the file to S3.
+ * @returns {Promise<Attachment>} A promise that resolves to an [Attachment](../interfaces/Attachment) object containing the uploaded file's details.
+ *
+ * @example
+ * ```typescript URL Download and Upload
+ * import { saveFileToS3 } from "@intuned/sdk/helpers";
+ * import { S3UploadOptions } from "@intuned/sdk/types";
+ *
+ * const uploadOptions: S3UploadOptions = {
+ *   s3Configs: {
+ *     bucket: 'my-bucket',
+ *     region: 'us-west-1',
+ *      }
+ * };
+ * const uploadedFile = await saveFileToS3(page, "https://sandbox.intuned.dev/pdfs", uploadOptions);
+ * console.log(uploadedFile.getS3Key());
+ * ```
+ *
+ * @example
+ * ```typescript Locator Download and Upload
+ * import { saveFileToS3 } from "@intuned/sdk/helpers";
+ * import { S3UploadOptions } from "@intuned/sdk/types";
+ * const uploadOptions: S3UploadOptions = {
+ *   s3Configs: {
+ *     bucket: 'my-bucket',
+ *     region: 'us-west-1',
+ *   }
+ * };
+ * const uploadedFile = await saveFileToS3(page, page.locator("[href='/download/file.pdf']"), uploadOptions);
+ * console.log(uploadedFile.getS3Key());
+ * ```
+ *
+ * @example
+ * ```typescript Callback Function Download and Upload
+ * import { saveFileToS3 } from "@intuned/sdk/helpers";
+ * import { S3UploadOptions } from "@intuned/sdk/types";
+ * const uploadOptions: S3UploadOptions = {
+ *   s3Configs: {
+ *     bucket: 'my-bucket',
+ *   region: 'us-west-1',
+ * }
+ *  };
+ * const uploadedFile = await saveFileToS3(page, async (page) => {
+ *   await page.locator("button:has-text('Download')").click();
+ * }, uploadOptions);
+ * console.log(uploadedFile.getS3Key());
+ * ```
+ * @note
+ * - If a URL is provided as the trigger, a new page will be created and closed after the download is complete.
+ * - If a locator is provided as the trigger, the page will be used to click the element and initiate the download.
+ * - If a callback function is provided as the trigger, the function will be called with the page object as an argument and will be responsible for initiating the download.
+ */
+export declare function saveFileToS3(input: {
+  page: Page;
+  trigger: Trigger;
+  timeoutInMs?: number;
+  uploadOptions: S3UploadOptions;
+}): Promise<Attachment>;
+
+/**
+ * LoadingStatus is a union of true, false, and "Dont know".
+ */
+export type LoadingStatus = true | false | "Dont know";
+
+/**
+ * AttachmentType is a string representing the type of the file.
+ * Current supported types are:
+ * - "document"
+ */
+export type AttachmentType = "document";