@intuned/browser-dev 0.1.7-dev.0 → 0.1.9-dev.0

package/dist/helpers/index.d.ts

@@ -3,7 +3,6 @@
 import type { Locator, Page, ElementHandle } from "playwright";
 import type { ReadStream } from "fs";
 import { Download } from "playwright";
-import { SUPPORTED_MODELS } from "../ai/export";
 
 /**
  * Configuration options for sanitizing HTML content.
@@ -11,11 +10,11 @@ import { SUPPORTED_MODELS } from "../ai/export";
 export interface SanitizeHtmlOptions {
   /** The HTML content to sanitize */
   html: string;
-  /** Remove all <script> elements. Defaults to true. */
+  /** Remove all \<script\> elements. Defaults to true. */
   removeScripts?: boolean;
-  /** Remove all <style> elements. Defaults to true. */
+  /** Remove all \<style\> elements. Defaults to true. */
   removeStyles?: boolean;
-  /** Remove all <svg> elements. Defaults to true. */
+  /** Remove all \<svg\> elements. Defaults to true. */
   removeSvgs?: boolean;
   /** Remove HTML comments. Defaults to true. */
   removeComments?: boolean;
@@ -53,108 +52,101 @@ export interface SanitizeHtmlOptions {
  *
  * @example
  * ```typescript Basic Sanitization
+ * import { BrowserContext, Page } from "playwright";
  * 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"]
- * });
- * }
+ * interface Params {}
+ *
+ * export default async function handler(
+ *   params: Params,
+ *   page: Page,
+ *   context: BrowserContext
+ * ) {
+ *  await page.goto("https://books.toscrape.com");
+ *  const firstRow = page.locator("ol.row").locator("li").first();
+ *  // Get the HTML of the first row.
+ *  const html = await firstRow.innerHTML();
+ *  // Sanitize the HTML.
+ *  const sanitizedHtml = sanitizeHtml({ html });
+ *  // Log the sanitized HTML.
+ *  console.log(sanitizedHtml);
+ *  // Return the sanitized HTML.
+ *  return sanitizedHtml;
+}
  * ```
  */
 
 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
+* Downloads a file from a web page using various trigger methods. This function provides three flexible ways to initiate file downloads:
+*
+* - **URL**: Creates a new page, navigates to the URL, waits for download, then automatically closes the page. Ideal for direct download links.
+* - **Locator**: Uses the current page to click the element and capture the resulting download. Perfect for download buttons or interactive elements.
+* - **Callback**: Executes the provided function with the page object and captures the first triggered download. Offers maximum flexibility for complex download scenarios.
  *
  * @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
+ * @param {Trigger} input.trigger - The [Trigger](../type-references/Trigger) method to initiate the download
+ * @param {number} [input.timeoutInMs=5000] - Maximum time in milliseconds to wait for the download to trigger. Defaults to 5000.
+ * @returns {Promise<Download>} Promise that resolves to a [Playwright Download object](https://playwright.dev/docs/api/class-download)
  *
  * @example
- * ```typescript URL trigger
+ * ```typescript Download from direct URL
  * 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()}`);
+ * import { BrowserContext, Page } from "playwright";
+
+ * interface Params {}
+
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *  // Download from a direct URL, this will open the url and automatically download the content in it.
+ *   const download = await downloadFile({
+ *     page,
+ *     trigger: "https://intuned-docs-public-images.s3.amazonaws.com/32UP83A_ENG_US.pdf"
+ *   });
+ *   file_name = download.suggestedFilename();
+ *   return file_name;
+ *   
  * }
  * ```
  *
  * @example
- * ```typescript Locator trigger
+ * ```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()}`);
+ * import { BrowserContext, Page } from "playwright";
+ * 
+ * interface Params {}
+
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   await page.goto("https://sandbox.intuned.dev/pdfs");
+ *   const download = await downloadFile({
+ *     page,
+ *     trigger: page.locator("xpath=//tbody/tr[1]//*[name()='svg']")
+ *   });
+ *   file_name = download.suggestedFilename();
+ *   return file_name;
  * }
  * ```
  *
  * @example
- * ```typescript Callback trigger
+ * ```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()}`);
+ * import { BrowserContext, Page } from "playwright";
+ * 
+ * interface Params {}
+ * 
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   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();
+ *     }
+ *   });
+ *   file_name = download.suggestedFilename();
+ *   return file_name;
  * }
  * ```
- *
- * @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;
@@ -179,10 +171,26 @@ export declare function downloadFile(input: {
  * @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" }] }
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   // Filter empty values from dictionary
+ *   const result1 = filterEmptyValues({ data: { a: "", b: "hello", c: null } });
+ *   // Output: { b: "hello" }
+ *   console.log(result1);
+ *
+ *   // Filter empty values from list
+ *   const result2 = filterEmptyValues({ data: [1, "", null, [2, ""]] });
+ *   // Output: [1, [2]]
+ *   console.log(result2);
+ *
+ *   // Filter nested structures
+ *   const result3 = filterEmptyValues({ data: { users: [{ name: "" }, { name: "John" }] } });
+ *   // Output: { users: [{ name: "John" }] }
+ *   console.log(result3);
+ *   return "All data filtered successfully";
  * }
  * ```
  */
@@ -190,66 +198,78 @@ 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-5-mini-2025-08-07"] - AI model to use for loading verification. See [SUPPORTED_MODELS](../type-aliases/SUPPORTED_MODELS) for all supported models. Defaults to "gpt-5-mini-2025-08-07"
- * @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
+ * intelligent timeout handling, 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.
+ *
+ * This method can also use AI vision to verify the page is fully loaded by checking for loading spinners, blank content, or incomplete states.
+ *
+ * @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.timeoutInMs=30000] - Maximum time in milliseconds to wait for navigation. Defaults to 30000.
+ * @param {number} [input.retries=3] - Number of retry attempts with exponential backoff (factor: 2). Defaults to 3.
+ * @param {("load"|"domcontentloaded"|"networkidle"|"commit")} [input.waitForLoadState="load"] - When to consider navigation succeeded. Defaults to `"load"`
+ * @param {boolean} [input.throwOnTimeout=false] - Whether to throw an error if navigation times out. When true, the function throws an error on navigation timeout. Defaults to false.
+ * @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 3 times with 5-second delays. Defaults to false
+ * Check [isPageLoaded](../../ai/functions/isPageLoaded) for more details on the AI loading verification.
+ * @param {string} [input.model="gpt-5-mini-2025-08-07"] - AI model to use for loading verification. Defaults to `"gpt-5-mini-2025-08-07"`
+ * @param {string} [input.apiKey] - Optional API key for the AI check.
+ * @returns {Promise<void>} Promise that resolves when navigation completes. If the operation fails and `throwOnTimeout` is false, resolves without error
  *
  * @example
- * ```typescript Basic Navigation
+ * ```typescript Without options
  * 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
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   await goToUrl({
+ *     page,
+ *     url: 'https://sandbox.intuned.dev/'
+ *   });
+ * // At this point, goToUrl has waited for the page to be loaded and the network requests to be settled.
  * }
  * ```
  *
  * @example
- * ```typescript Navigation with options
+ * ```typescript 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
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   await goToUrl({
+ *     page,
+ *     url: 'https://intunedhq.com',
+ *     waitForLoadState: "domcontentloaded", // Faster than "load" state. The function automatically waits for the page to settle.
+ *     throwOnTimeout: true,
+ *     timeoutInMs: 10000,
+ *     retries: 3
+ *   });
+ * // At this point, DOM content is loaded and goToUrl has waited for network requests to settle.
  * }
  * ```
  *
  * @example
- * ```typescript AI-Verified Loading for Dynamic Sites
+ * ```typescript With AI Loading Detection
  * 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
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   await goToUrl({
+ *     page,
+ *     url: 'https://intunedhq.com',
+ *     waitForLoadingStateUsingAi: true,
+ *     model: "gpt-4o"
+ *   });
+ *  // The page is loaded and ready to use.
+ *  // If the AI check fails, the method won't throw even if throwOnTimeout is true.
+ *  // It only throws if the page times out reaching the default load state and throwOnTimeout is true.
  * }
  * ```
  */
@@ -259,9 +279,9 @@ export declare function goToUrl(input: {
   timeoutInMs?: number;
   retries?: number;
   throwOnTimeout?: boolean;
-  waitForLoadState?: "load" | "domcontentloaded" | "networkidle";
+  waitForLoadState?: "load" | "domcontentloaded" | "networkidle" | "commit";
   waitForLoadingStateUsingAi?: boolean;
-  model?: SUPPORTED_MODELS;
+  model?: string;
   apiKey?: string;
 }): Promise<void>;
 
@@ -269,38 +289,49 @@ export declare function goToUrl(input: {
  * 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
+ * @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.
+ * If the page has loaded all content and we still haven't reached the maxScrolls, the minHeightChange will detect that no new content is loaded and stop the scrolling.
+ * @returns {Promise<void>} Promise that resolves when scrolling is complete.
  *
  * @example
- * ```typescript Basic Infinite Scroll
+ * ```typescript Basic Infinite Scroll handling
  * import { scrollToLoadContent } from "@intuned/browser";
- * export default async function handler(params, page, context){
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
  * // Scroll through entire page content
- * await page.goto("https://docs.intunedhq.com/docs-old/getting-started/introduction")
+ * await page.goto("https://sandbox.intuned.dev/infinite-scroll")
  * await scrollToLoadContent({
  *   source: page,
  * });
- * // Now all content is loaded and visible
+ * // Will keep scrolling until the page has loaded all content or the maxScrolls is reached.
  * }
  * ```
  *
  * @example
  * ```typescript Scroll Specific Container
  * import { scrollToLoadContent } from "@intuned/browser";
- * export default async function handler(params, page, context){
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
  * // Scroll through a specific scrollable div
- * await page.goto("https://docs.intunedhq.com/docs-old/getting-started/introduction")
+ * await page.goto("https://docs.intunedhq.com/docs/00-getting-started/introduction")
+ * // This will scroll the sidebar content only and watch its height to change.
  * const container = page.locator("xpath=//div[@id='sidebar-content']");
  * await scrollToLoadContent({
  *   source: container,
  *   maxScrolls: 20
  * });
+ * // Will keep scrolling until the sidebar content has loaded all content or the maxScrolls is reached.
  * }
  * ```
  */
@@ -313,32 +344,6 @@ export declare function scrollToLoadContent(input: {
   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;
@@ -350,8 +355,7 @@ export declare function clickButtonAndWait(input: {
  *
  * 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
+ * - Button becomes invisible/disabled
  * - Maximum number of clicks reached
  * - No change detected in container content (when containerLocator is provided)
  *
@@ -360,17 +364,21 @@ export declare function clickButtonAndWait(input: {
  * @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
+ * @param {number} [input.maxClicks=50] - Maximum number of times to click the button. Defaults to 50.
+ * @param {number} [input.clickDelay=0.5] - Delay after each click (in seconds). Defaults to 0.5.
+ * @param {number} [input.noChangeThreshold=0] - Minimum change in content size to continue clicking. Defaults to 0.
  * @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')");
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ * await page.goto("https://sandbox.intuned.dev/load-more");
+ * const loadMoreButton = page.locator("main main button"); // Select the main button in the main content area.
  *
  * // Click until button disappears or is disabled
  * await clickUntilExhausted({
@@ -378,22 +386,27 @@ export declare function clickButtonAndWait(input: {
  *   buttonLocator: loadMoreButton,
  *   maxClicks: 20
  * });
+ * // Will keep clicking the button until the button disappears or is disabled or the maxClicks is reached.
  * }
  * ```
  *
  * @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");
+ * import { BrowserContext, Page } from "playwright";
  *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ * await page.goto("https://sandbox.intuned.dev/load-more");
+ * const loadMoreButton = page.locator("aside button"); // Select the button in the sidebar.
+ * const container = page.locator('xpath=//*[@id="root"]/div[1]/main/slot/div/aside/div/div/slot/slot'); // Watch the sidebar container to detect changes.
+ * // This will count the elements under the container given before each click and after, if the count is the same, the function will stop.
  * let clickCount = 0;
  * await clickUntilExhausted({
  *   page,
  *   buttonLocator: loadMoreButton,
- *   containerLocator: productsContainer,
+ *   containerLocator: container,
  *   heartbeat: () => {
  *     clickCount++;
  *     console.log(`Clicked ${clickCount} times`);
@@ -402,6 +415,7 @@ export declare function clickButtonAndWait(input: {
  *   clickDelay: 0.5,
  *   noChangeThreshold: 0
  * });
+ * // Will keep clicking the button until the button disappears or is disabled or the maxClicks is reached or no more content is loaded.
  * }
  * ```
  */
@@ -416,30 +430,76 @@ export declare function clickUntilExhausted(input: {
 }): 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")
+ * Parses various date string formats into Date objects, returning only the date part with time set to midnight.
+ * This utility function provides robust date parsing capabilities for a wide range of common formats.
+ *
+ * ## Key features
+ *
+ * - Returns only the date part (year, month, day)
+ * - Time is always set to 00:00:00
+ * - Supports multiple international formats
+ * - Handles timezones and AM/PM formats
+ *
+ * ## Supported formats
+ *
+ * The function handles these date format categories:
+ *
+ * ### Standard date formats
+ * - `DD/MM/YYYY`: "22/11/2024", "13/12/2024"
+ * - `MM/DD/YYYY`: "01/17/2025", "10/25/2024"
+ * - Single-digit variants: "8/16/2019", "9/28/2024"
+ *
+ * ### Date-time combinations
+ * - With 24-hour time: "22/11/2024 21:19:05"
+ * - With AM/PM: "12/09/2024 9:00 AM"
+ * - With dash separator: "12/19/2024 - 2:00 PM"
+ *
+ * ### Timezone support
+ * - With timezone abbreviations: "10/23/2024 12:06 PM CST"
+ * - With timezone offset: "01/17/2025 3:00:00 PM CT"
+ *
+ * ### Text month formats
+ * - Short month: "5 Dec 2024", "11 Sep 2024"
+ * - With time: "5 Dec 2024 8:00 AM PST"
+ * - Full month: "November 14, 2024", "January 31, 2025, 5:00 pm"
  *
  * @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
+ * @returns {Date | null} Returns a `Date` object with only date components preserved (year, month, day), time always set to 00:00:00, or `null` if parsing fails
  *
  * @example
- * ```typescript Basic Date Processing
+ * ```typescript Basic Usage
  * 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
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   // Basic date string
+ *   const date1 = processDate({ date: "22/11/2024" });
+ *   console.log(date1); // 2024-11-22 00:00:00
+ *
+ *   // Date with time (time is ignored)
+ *   const date2 = processDate({ date: "5 Dec 2024 8:00 AM PST" });
+ *   console.log(date2); // 2024-12-05 00:00:00
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Invalid Date
+ * import { processDate } from "@intuned/browser";
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   // Invalid date returns null
+ *   const invalidDate = processDate({ date: "invalid date" });
+ *   console.log(invalidDate); // will return null.
+ * if (invalidDate === null) {
+ * throw new Error("Invalid date");
+ * }
+ * return "should not reach here";
  * }
  * ```
  */
@@ -449,81 +509,83 @@ 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
+ * making it versatile for different upload scenarios. It automatically
  * handles file metadata and provides comprehensive S3 configuration options.
  *
+ * ## S3 configuration fallback
+ *
+ * The function uses a fallback system to determine S3 settings:
+ *
+ * 1. **S3Configs Parameter** - If provided, uses the explicit `configs` object with your custom settings.
+ * 2. **Environment Variables** - If no configs provided, automatically reads from environment variables:
+ *    - `AWS_ACCESS_KEY_ID` - Your AWS access key
+ *    - `AWS_SECRET_ACCESS_KEY` - Your AWS secret key
+ *    - `AWS_REGION` - AWS region (e.g., "us-west-1")
+ *    - `AWS_BUCKET` - S3 bucket name
+ *    - `AWS_ENDPOINT_URL` - Optional custom S3 endpoint
+ *    - Check [Environment Variables & Secrets](https://docs.intunedhq.com/docs/02-features/environment-variables-secrets) to learn more about setting environment variables.
+ * 3. **Intuned Defaults** - If environment variables aren't set, falls back to Intuned's managed S3 storage. See [S3 Attachment Storage](https://docs.intunedhq.com/docs/04-integrations/s3/s3-attachment-storage) for more details.
+ *
  * @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 {FileType} input.file - The file to upload. Accepts [FileType](../type-references/FileType) types including Playwright Download objects, Uint8Array, Buffer, or ReadStream
+ * @param {S3Configs} [input.configs] - Optional [S3Configs](../type-references/S3Configs) for customizing the S3 upload. If not provided, uses environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, `AWS_ENDPOINT_URL`, `AWS_BUCKET`). If environment variables aren't set, uses default Intuned S3 settings.
+ * @param {string} [input.fileNameOverride] - Optional custom filename for the uploaded file. If not provided, uses the original filename or generates a unique name.
  * @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
+ * @returns {Promise<Attachment>} Promise that resolves to an [Attachment](../type-references/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']")
- * });
+ * import { BrowserContext, Page } from "playwright";
  *
- * const uploadedFile = await uploadFileToS3({
- *   file: download,
- *   configs: {
- *       bucket: 'my-documents',
- *       region: 'us-west-2',
- *       accessKeyId: 'accessKeyId',
- *       secretAccessKey: 'SecretAccessKeyId'
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   await page.goto("https://sandbox.intuned.dev/pdfs");
+ *   const download = await downloadFile({
+ *     page,
+ *     trigger: page.locator("xpath=//tbody/tr[1]//*[name()='svg']")
+ *   });
+ *   // Set your environment variables for the AWS credentials.
+ *   // Check https://docs.intunedhq.com/docs/02-features/environment-variables-secrets to learn more about setting environment variables.
+ *   const uploadedFile = await uploadFileToS3({
+ *     file: download,
+ *     configs: {
+ *       bucket: process.env.AWS_BUCKET,
+ *       region: process.env.AWS_REGION,
+ *       accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+ *       secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
  *     },
  *     fileNameOverride: 'reports/monthly-report.pdf'
- *   }
- * });
+ *   });
  *
- * console.log(`File uploaded: ${uploadedFile.suggestedFileName}`);
- * console.log(`S3 URL: ${uploadedFile.getS3Key()}`);
+ *   console.log(`File uploaded: ${uploadedFile.suggestedFileName}`);
  * }
  * ```
  *
  * @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
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   const fileBuffer = Buffer.from('Hello World', 'utf8');
+ *   const uploadedFile = await uploadFileToS3({
+ *     file: fileBuffer,
+ *     fileNameOverride: 'data/text-file.txt',
+ *     contentType: 'text/plain'
+ *   });
+ *
+ *   // Generate a temporary download URL
+ *   const downloadUrl = await uploadedFile.getSignedUrl();
+ *   console.log(`Download URL: ${downloadUrl}`);
+ *   return {
+ *     downloadUrl: downloadUrl
+ *   };
  * }
  * ```
- *
- * @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: {
@@ -535,41 +597,58 @@ export declare function uploadFileToS3(input: {
 
 /**
  * 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.
+ * This function can validate any given data against a given schema. It supports validating custom data types such as the [Attachment](../type-references/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 {void} Returns nothing if validation passes, throws ValidationError if it fails
+ * @throws {ValidationError} If validation fails
  *
  * @example
- * ```typescript Basic User Data Validation
+ * ```typescript Basic 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
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ * const uploadData = {
+ *   file: {
+ *     fileName: "documents/report.pdf",
+ *     bucket: "my-bucket",
+ *     region: "us-east-1",
+ *     key: "documents/report.pdf",
+ *     endpoint: null,
+ *     suggestedFileName: "Monthly Report.pdf",
+ *     fileType: "document"
+ *   },
+ *   name: "Test File Upload"
  * };
  *
- * const userSchema = {
+ * const uploadSchema = {
  *   type: "object",
- *   required: ["name", "email", "age"],
+ *   required: ["file", "name"],
  *   properties: {
- *     name: { type: "string", minLength: 1 },
- *     email: { type: "string", format: "email" },
- *     age: { type: "number", minimum: 0 }
+ *     file: { type: "attachment" },
+ *     name: { type: "string" }
  *   }
  * };
  *
- * validateDataUsingSchema({ data: userData, schema: userSchema });
- * // Validation passes, no error thrown
+ * validateDataUsingSchema({ data: uploadData, schema: uploadSchema });
+ * // Validation passes with Attachment type
+ * console.log("Validation passed");
+ * return "Validation passed";
  * }
  * ```
  * @example
  * ```typescript Invalid Data Validation
  * import { validateDataUsingSchema } from "@intuned/browser";
- * export default async function handler(params, page, context){
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
  * const userData = {
  *   name: "John Doe",
  *   email: "john@example.com",
@@ -585,8 +664,10 @@ export declare function uploadFileToS3(input: {
  *   }
  * };
  *
- * validateDataUsingSchema({ data: userData, schema: userSchema });
+ * validateDataUsingSchema({ data: userData, schema: userSchema }); // this will throw
  * // Validation fails, throws ValidationError
+ * console.log("Never reached");
+ * return "Never reached";
  * }
  * ```
  */
@@ -596,11 +677,11 @@ export declare function validateDataUsingSchema(input: {
 }): void;
 
 /**
- * Executes a callback function and waits for network requests to settle before returning.
+ * Executes a callback function and waits for network activity 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.
+ * ## `withNetworkSettledWait` vs `waitForDomSettled`
+ * - Use `withNetworkSettledWait` when watching **network requests** (API calls, form submissions, resource loading)
+ * - Use [waitForDomSettled](../functions/waitForDomSettled) when watching **DOM mutations** (elements added/removed/modified, loading spinners, dynamic content injection)
  *
  * @param {Function} callback - The callback function to execute. Receives the page object as parameter
  * @param {Object} [options] - Configuration options for network monitoring
@@ -609,21 +690,59 @@ export declare function validateDataUsingSchema(input: {
  * @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
+ * ```typescript Wrapper with Inline Function
  * 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
- *   }
- * );
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   await page.goto('https://sandbox.intuned.dev/infinite-scroll');
+ *
+ *   // Execute action and wait for network to settle
+ *   const result = await withNetworkSettledWait(
+ *     async (page) => {
+ *       // scroll to load more content
+ *       await page.evaluate(() => {
+ *         window.scrollTo(0, document.body.scrollHeight);
+ *       });
+ *       return "scrolled";
+ *     },
+ *     {
+ *       page,
+ *       timeoutInMs: 15000,
+ *       maxInflightRequests: 0
+ *     }
+ *   );
+ *   console.log(result); // "scrolled"
+ *   return result;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Click Link with Network Wait
+ * import { withNetworkSettledWait } from "@intuned/browser";
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   await page.goto('https://sandbox.intuned.dev/');
+ *
+ *   // Click Object Extractors link and wait for page to load
+ *   await withNetworkSettledWait(
+ *     async (page) => {
+ *       await page.getByText('Object Extractors').click();
+ *     },
+ *     {
+ *       page,
+ *       timeoutInMs: 10000,
+ *       maxInflightRequests: 0
+ *     }
+ *   );
+ *   // Object Extractors page loaded
+ *   const title = await page.locator('div h2').innerText();
+ *   return title;
  * }
  * ```
  */
@@ -637,57 +756,70 @@ export declare function withNetworkSettledWait<T>(
 ): 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.
+ * Waits for DOM mutations to settle without executing any function first. This helper uses a MutationObserver to monitor DOM changes and waits until the DOM has been stable (no mutations) for the specified settle duration.
  *
- * 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.
+ * ## `waitForDomSettled` vs `withNetworkSettledWait`
+ *
+ * - Use `waitForDomSettled` when watching **DOM mutations** (elements added/removed/modified, loading spinners, dynamic content injection)
+ * - Use [withNetworkSettledWait](../functions/withNetworkSettledWait) when watching **network requests** (API calls, form submissions, resource loading)
  *
  * @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 {Page | Locator} options.source - The Playwright Page or Locator to monitor for DOM changes. When a Page is provided, monitors the entire document. When a Locator is provided, monitors only 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
+ * ```typescript Wait After Navigation
  * 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');
+ * import { BrowserContext, Page } from "playwright";
  *
- * // Wait for entire page content to stabilize
- * const settled = await waitForDomSettled({
- *   source: page,
- *   settleDurationMs: 1000
- * });
+ * interface Params {}
  *
- * if (settled) {
- *   // Safe to scrape or interact with content
- *   console.log(`Found stable items`);
- * } else {
- *   console.log("DOM never fully settled, proceeding anyway");
- * }
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   // Navigate to page with dynamic content
+ *   await page.goto('https://sandbox.intuned.dev/lists/table');
+ *
+ *   // Wait for all DOM mutations to complete
+ *   const settled = await waitForDomSettled({
+ *     source: page,
+ *     settleDurationMs: 1000,
+ *     timeoutInMs: 20000
+ *   });
+ *
+ *   if (settled) {
+ *     // DOM is stable, safe to extract data
+ *     const rows = await page.locator('table tr').all();
+ *     return rows.length;
+ *   }
+ *   return 0;
  * }
  * ```
  *
  * @example
- * ```typescript Monitor Specific Container
+ * ```typescript Watch 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,
- * });
+ * import { BrowserContext, Page } from "playwright";
  *
- * if (settled) {
- *   // Now the feed is stable, safe to extract articles
- *   console.log(`Feed stabilized`);
- * }
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   await page.goto("https://sandbox.intuned.dev/lists/table");
+ *
+ *   // Only watch table container (ignore header/footer changes)
+ *   const table = page.locator("table");
+ *   const settled = await waitForDomSettled({
+ *     source: table,
+ *     settleDurationMs: 800,
+ *     timeoutInMs: 15000,
+ *   });
+ *
+ *   if (settled) {
+ *     // Table has finished loading
+ *     const rows = await table.locator('tr').count();
+ *     return rows;
+ *   }
+ *   return 0;
  * }
  * ```
  */
@@ -701,53 +833,71 @@ export declare function waitForDomSettled(options: {
  * 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
+ * @param {Page | Locator} input.source - The source of the HTML content. When a Page is provided, extracts from the entire page. When a Locator is provided, extracts from that specific element.
  * @returns {Promise<string>} Promise that resolves to the markdown representation of the HTML content
+ *
  * @example
- * ```typescript locator source
+ * ```typescript Extract Markdown from Locator
  * 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
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   await page.goto("https://books.toscrape.com/");
+ *   const headerLocator = page.locator('h1').first(); // First title on the page
+ *   const markdown = await extractMarkdown({ source: headerLocator }); // Extract markdown from the first title
+ *   console.log(markdown);
+ *   return markdown;
  * }
  * ```
+ *
  * @example
- * ```typescript string source
+ * ```typescript Extract Markdown from Page
  * 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
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   await page.goto("https://sandbox.intuned.dev/pdfs");
+ *   const markdown = await extractMarkdown({ source: page });
+ *   console.log(markdown);
+ *   return markdown;
  * }
  * ```
- *
  */
 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.
+ * Converts any URL source to an absolute, properly encoded URL.
+ *
+ * @overload Base URL String
+ *
+ * Combines a relative URL with a base URL string. Use when you have an explicit base URL string to resolve relative paths against.
  *
- * @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
+ * ```typescript Resolve from Base URL String
  * import { resolveUrl } from '@intuned/browser';
- * export default async function handler(params, page, context){
- * await page.goto("https://example.com");
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
  *
- * // Using explicit base URL
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ * // Resolve from base URL string
  * const absoluteUrl = await resolveUrl({
- *   url: "/api/users",
- *   baseUrl: "https://example.com"
+ *   url: "/lists/table",
+ *   baseUrl: "https://sandbox.intuned.dev"
  * });
- * // Returns: "https://example.com/api/users"
+ * // Returns: "https://sandbox.intuned.dev/lists/table"
+ * console.log(absoluteUrl);
+ * return absoluteUrl;
  * }
  * ```
  */
@@ -757,24 +907,33 @@ export declare function resolveUrl(input: {
 }): Promise<string>;
 
 /**
- * Converts any URL source to an absolute, properly encoded URL by using the current page's URL as the base URL.
+ * Converts any URL source to an absolute, properly encoded URL.
+ *
+ * @overload Current Page's URL
+ *
+ * Uses the current page's URL as the base URL. Use when resolving URLs relative to the current page.
  *
- * @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
+ * ```typescript Resolve from the Current Page's URL
  * 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
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ * await page.goto("https://sandbox.intuned.dev/");
+ * // Resolve from the current page's URL
  * const absoluteUrl = await resolveUrl({
- *   url: "/api/users",
+ *   url: "/lists/table",
  *   page: page
  * });
- * // Returns: "https://example.com/api/users"
+ * // Returns: "https://sandbox.intuned.dev/lists/table"
+ * console.log(absoluteUrl);
+ * return absoluteUrl;
  * }
  * ```
  */
@@ -784,21 +943,31 @@ export declare function resolveUrl(input: {
 }): 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.
+ * Converts any URL source to an absolute, properly encoded URL.
+ *
+ * @overload Anchor Elements
+ *
+ * Extracts the href attribute from a Playwright Locator pointing to an anchor element. Use when extracting and resolving URLs from anchor (`<a>`) elements.
  *
- * @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
+ * @param {Locator} input.url - Playwright Locator pointing to an anchor element. The href attribute will be extracted and resolved relative to the current page.
  * @returns {Promise<string>} Promise that resolves to the absolute, properly encoded URL string
  * @example
- * ```typescript Locator source
+ * ```typescript Resolve from Anchor Element
  * 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"
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   await page.goto("https://sandbox.intuned.dev/");
+ *   // Resolve from Anchor Element
+ *   const absoluteUrl = await resolveUrl({
+ *     url: page.locator("xpath=//a[normalize-space()='Steps Form']"),
+ *   });
+ *   // Returns: "https://sandbox.intuned.dev/steps-form"
+ *   console.log(absoluteUrl);
+ *   return absoluteUrl;
  * }
  * ```
  */
@@ -807,31 +976,64 @@ 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.
+ * 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
+ * ```typescript Basic Usage
+ * import { uploadFileToS3, Attachment } from "@intuned/browser";
+ * import { BrowserContext, Page } from "playwright";
  *
- * const uploadedFile: Attachment = await uploadFileToS3({
- *   file: myFile,
- *   configs: s3Config
- * });
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   const uploadedFile: Attachment = await uploadFileToS3({
+ *     file: myFile,
+ *     configs: s3Config
+ *   });
+ *
+ *   // Access file properties
+ *   console.log(uploadedFile.fileName);
+ *   console.log(uploadedFile.suggestedFileName);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Working with Presigned URLs
+ * import { uploadFileToS3, Attachment } from "@intuned/browser";
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
  *
- * // Access file properties
- * console.log(uploadedFile.fileName); // "documents/report.pdf"
- * console.log(uploadedFile.suggestedFileName); // "Monthly Report.pdf"
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   const uploadedFile: Attachment = await uploadFileToS3({
+ *     file: myFile
+ *   });
  *
- * // Get a presigned URL for download
- * const downloadUrl = await uploadedFile.getSignedUrl(3600); // 1 hour
+ *   // Generate a presigned URL for temporary access
+ *   const downloadUrl = await uploadedFile.getSignedUrl(3600); // 1 hour expiration
  *
- * // Convert to dictionary for storage or API responses
- * const fileDict = uploadedFile.toDict();
+ *   // Get the permanent S3 URL
+ *   const s3Url = uploadedFile.getS3Key();
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript Serialization
+ * import { uploadFileToS3, Attachment } from "@intuned/browser";
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   const uploadedFile: Attachment = await uploadFileToS3({
+ *     file: myFile
+ *   });
+ *
+ *   // Convert to dictionary for storage or API responses
+ *   const fileDict = uploadedFile.toDict();
+ *   const fileJson = uploadedFile.toJSON();
  * }
  * ```
  */
@@ -860,96 +1062,36 @@ export interface Attachment {
   /**
    * 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'
-   * // }
-   * }
-   * ```
+   * @returns `Record<string, string>` - Complete model data including all fields
    */
   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
+   * Converts the file metadata to a record.
    *
-   * @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'
-   * // }
-   * }
-   * ```
+   * @returns `Record<string, string>` - Record with fileName, key, bucket, region, endpoint, suggestedFileName, and fileType
    */
   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"
-   * }
-   * ```
+   * @returns `string` - Complete S3 URL in format: https://bucket.s3.region.amazonaws.com/filename
    */
   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"
-   * }
-   * ```
+   * @returns `string` - The fileName property (S3 object key)
    */
   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
-   * }
-   * ```
+   * @param expiration - URL expiration time in seconds. Defaults to 432000 (5 days)
+   * @returns `Promise<string>` - Presigned URL for downloading the file
    */
   getSignedUrl(expiration?: number): Promise<string>;
 }
@@ -957,124 +1099,129 @@ export interface Attachment {
 /**
  * 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
+ * This type standardizes how download operations can be initiated, providing multiple approaches for different automation scenarios.
  *
- * **Type Information:**
+ * **Type variants:**
  * - `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
+ * - `(page: Page) => Promise<void>`: Custom async 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"
- * });
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   // 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
- * });
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   // Click a download button
+ *   const download = await downloadFile({
+ *     page,
+ *     trigger: page.locator("#download-btn")
+ *   });
  * }
  * ```
  *
  * @example
- * ```typescript Custom Function Trigger
+ * ```typescript Callback 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");
- *   }
- * });
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   // Custom download logic
+ *   const download = await downloadFile({
+ *     page,
+ *     trigger: async (p) => {
+ *       await p.locator("button.prepare").click();
+ *       await p.waitForSelector(".ready");
+ *       await p.locator("a.download-link").click();
+ *     }
+ *   });
  * }
  * ```
- *
- * @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.
+ * Configuration 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.
+ * Defines the parameters needed to connect to and interact with AWS S3 storage services. Supports both standard AWS S3 and S3-compatible storage services through custom endpoints.
  *
  * @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
- * });
+ * @example
+ * ```typescript Basic Configuration
+ * import { uploadFileToS3, S3Configs } from "@intuned/browser";
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   // Using explicit credentials
+ *   const s3Config: S3Configs = {
+ *     accessKeyId: "accessKeyId",
+ *     secretAccessKey: "SecretAccessKeyId",
+ *     bucket: "my-app-uploads",
+ *     region: "us-east-1"
+ *   };
+ * }
+ * ```
  *
- * // Use with download and upload operations
- * const uploadedFile = await saveFileToS3({
- *   page,
- *   trigger: downloadUrl,
- *   configs: s3Config
- * });
+ * @example
+ * ```typescript Environment Variables Configuration
+ * import { uploadFileToS3, S3Configs } from "@intuned/browser";
+ * export default async function handler(params, page, context){
+ *   // Credentials will be picked up from environment or IAM roles
+ *   const s3Config: S3Configs = {
+ *     bucket: "my-app-uploads",
+ *     region: "us-west-2"
+ *   };
  * }
  * ```
  */
 export interface S3Configs {
-  /** The name of the S3 bucket where files will be stored or retrieved */
+  /** Name of the S3 bucket to store files in. Must be a valid S3 bucket name following AWS naming conventions. */
   bucket?: string;
 
-  /** The AWS region where the S3 bucket is located (e.g., "us-east-1", "eu-west-1") */
+  /** AWS region where the S3 bucket is located. Examples: "us-east-1", "eu-west-1", "ap-southeast-1" */
   region?: string;
 
-  /** AWS access key ID for authentication and authorization */
+  /** AWS access key ID for authentication. If undefined, will attempt to use default AWS credentials or environment variables. */
   accessKeyId?: string;
 
-  /** AWS secret access key for authentication and authorization */
+  /** AWS secret access key for authentication. If undefined, will attempt to use default AWS credentials or environment variables. */
   secretAccessKey?: string;
 
-  /** Custom S3 endpoint URL for S3-compatible storage services */
+  /** Custom endpoint URL for S3-compatible storage services. Use this for services like MinIO, DigitalOcean Spaces, or other S3-compatible APIs. For standard AWS S3, leave this undefined. */
   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.
+ * Provides flexibility in how files can be passed to various functions, supporting multiple input formats.
  *
  * @type FileType
  *
- * **Type Information:**
+ * **Type variants:**
  * - `Download`: Playwright Download object from browser download operations
  * - `Uint8Array`: Binary data as Uint8Array
  * - `Buffer`: Node.js Buffer containing binary data
@@ -1130,79 +1277,59 @@ 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.
+ * Combines [downloadFile](./downloadFile) (for trigger methods) and [uploadFileToS3](./uploadFileToS3)
+ * (for S3 configuration), providing a streamlined workflow for capturing and storing files.
  *
  * @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
+ * @param {Trigger} input.trigger - The [Trigger](../type-references/Trigger) method to initiate the download
+ * @param {number} [input.timeoutInMs=5000] - Maximum time in milliseconds to wait for download to start. Defaults to 5000.
+ * @param {S3Configs} [input.configs] - Optional [S3Configs](../type-references/S3Configs) to customize the S3 upload. If not provided, uses environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_ENDPOINT_URL, AWS_BUCKET). If environment variables aren't set, uses default Intuned S3 settings.
+ * @param {string} [input.fileNameOverride] - Optional custom filename for the uploaded file. If not provided, uses the original filename or generates a unique name.
+ * @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](../type-references/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',
+ * ```typescript URL Trigger
+ * import { saveFileToS3 } from "@intuned/browser"
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   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()}`);
+ *     },
+ *     fileNameOverride: 'reports/monthly-report.pdf'
+ *   });
+ *   console.log(`File uploaded to: ${uploadedFile.getS3Key()}`);
  * }
  * ```
  *
  * @example
- * ```typescript Locator trigger
+ * ```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'
- * });
+ * import { BrowserContext, Page } from "playwright";
  *
- * // Generate temporary access URL
- * const downloadUrl = await uploadedFile.getSignedUrl(7200); // 2 hours
- * console.log(`Temporary access: ${downloadUrl}`);
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext){
+ *   await page.goto("https://sandbox.intuned.dev/pdfs");
+ *   const uploadedFile = await saveFileToS3({
+ *     page,
+ *     trigger: page.locator("xpath=//tbody/tr[1]//*[name()='svg']"),
+ *     timeoutInMs: 10000
+ *   });
+ *   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;
@@ -1216,7 +1343,6 @@ export declare function saveFileToS3(input: {
 /**
  * Union type representing the supported attachment file types.
  *
- * @type AttachmentType
  * Currently supported types:
  * - `"document"`: Document files (PDFs, Word docs, etc.)
  */