@intuned/browser-dev 0.1.4-dev.0

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

@@ -0,0 +1,113 @@
+---
+title: sanitizeHtml
+description: ""
+---
+
+```typescript
+export declare function sanitizeHtml(options: SanitizeHtmlOptions): string;
+```
+
+Sanitizes and cleans HTML content by removing unwanted elements, attributes, and whitespace.
+Provides fine-grained control over each cleaning operation through configurable options.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Basic Sanitization
+import { sanitizeHtml } from "@intuned/browser";
+export default async function handler(params, page, context){
+const dirtyHtml = `
+  <div>
+    <script>alert('xss')</script>
+    <p style="color: red;">Hello World</p>
+    <span></span>
+  </div>
+`;
+const sanitizedHtml = sanitizeHtml({ html: dirtyHtml });
+// Returns: '<div><p>Hello World</p></div>'
+}
+```
+
+```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"]
+});
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="options" type="SanitizeHtmlOptions" required
+>
+Configuration options for sanitization
+
+<Expandable title="options">
+<ParamField path="options.html" type="string">
+The HTML content to sanitize
+</ParamField>
+
+<ParamField path="options.removeScripts" type="boolean">
+Remove all `<script>` elements. Defaults to true.
+</ParamField>
+
+<ParamField path="options.removeStyles" type="boolean">
+Remove all `<style>` elements. Defaults to true.
+</ParamField>
+
+<ParamField path="options.removeSvgs" type="boolean">
+Remove all `<svg>` elements. Defaults to true.
+</ParamField>
+
+<ParamField path="options.removeComments" type="boolean">
+Remove HTML comments. Defaults to true.
+</ParamField>
+
+<ParamField path="options.removeLongAttributes" type="boolean">
+Remove attributes longer than maxAttributeLength. Defaults to true.
+</ParamField>
+
+<ParamField path="options.maxAttributeLength" type="number">
+Maximum length for attributes before removal. Defaults to 500.
+</ParamField>
+
+<ParamField path="options.preserveAttributes" type="Array<string>">
+List of attribute names to always preserve. Defaults to ["class", "src"].
+</ParamField>
+
+<ParamField path="options.removeEmptyTags" type="boolean">
+Remove empty tags (except preserved ones). Defaults to true.
+</ParamField>
+
+<ParamField path="options.preserveEmptyTags" type="Array<string>">
+List of tag names to preserve even when empty. Defaults to ["img"].
+</ParamField>
+
+<ParamField path="options.minifyWhitespace" type="boolean">
+Remove extra whitespace between tags and empty lines. Defaults to true.
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `string`
+
+The sanitized HTML string

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

@@ -0,0 +1,127 @@
+---
+title: saveFileToS3
+description: ""
+---
+
+```typescript
+export declare function saveFileToS3(input: {
+  page: Page;
+  trigger: Trigger;
+  timeoutInMs?: number;
+  configs?: S3Configs;
+  fileNameOverride?: string;
+  contentType?: string;
+}): Promise<Attachment>;
+```
+
+<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
+</Note>
+
+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.
+
+## Examples
+
+<CodeGroup>
+
+```typescript URL trigger
+import { saveFileToS3 } from "@intuned/browser";
+export default async function handler(params, page, context){
+// Download from URL and upload to S3 with custom configuration
+const uploadedFile = await saveFileToS3({
+  page,
+  trigger: "https://sandbox.intuned.dev/pdfs/report.pdf",
+  configs: {
+     bucket: 'document-storage',
+      region: 'us-east-1',
+      accessKeyId: 'accessKeyId',
+      secretAccessKey: 'SecretAccessKeyId'
+},
+fileNameOverride: 'reports/monthly-report.pdf',
+contentType: 'application/pdf'
+});
+
+console.log(`File uploaded to: ${uploadedFile.getS3Key()}`);
+}
+```
+
+```typescript Locator trigger
+import { saveFileToS3 } from "@intuned/browser";
+export default async function handler(params, page, context){
+// Click download link and save to S3
+await page.goto("https://sandbox.intuned.dev/pdfs")
+const uploadedFile = await saveFileToS3({
+  page,
+  trigger: page.locator("xpath=//tbody/tr[1]//*[name()='svg']"),
+  timeoutInMs: 10000,
+  configs: {
+    bucket: 'invoice-archive',
+    region: 'us-west-2',
+    accessKeyId: 'accessKeyId',
+    secretAccessKey: 'SecretAccessKeyId'
+  },
+  fileNameOverride: 'invoices/invoice.pdf',
+  contentType: 'application/pdf'
+});
+
+// Generate temporary access URL
+const downloadUrl = await uploadedFile.getSignedUrl(7200); // 2 hours
+console.log(`Temporary access: ${downloadUrl}`);
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="input" type="Object" required
+>
+Configuration object for the download and upload operation
+
+<Expandable title="input">
+<ParamField path="input.page" type="Page">
+The Playwright Page object to use for downloading
+</ParamField>
+
+<ParamField path="input.trigger" type="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
+</ParamField>
+
+<ParamField path="input.timeoutInMs" type="number">
+Maximum time in milliseconds to wait for download completion. Defaults to 5000.
+</ParamField>
+
+<ParamField path="input.configs" type="S3Configs">
+Optional [S3Configs](../interfaces/S3Configs) to customize the S3 upload
+</ParamField>
+
+<ParamField path="input.fileNameOverride" type="string">
+Optional filename override for the uploaded file
+</ParamField>
+
+<ParamField path="input.contentType" type="string">
+Optional content type for the uploaded file
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `Promise<Attachment>`
+
+Promise that resolves to an [Attachment](../interfaces/Attachment) object with file metadata and S3 utilities

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

@@ -0,0 +1,89 @@
+---
+title: scrollToLoadContent
+description: ""
+---
+
+```typescript
+export declare function scrollToLoadContent(input: {
+  source: Page | Locator;
+  onScrollProgress?: CallableFunction;
+  scrollableContainer?: Locator | null;
+  maxScrolls?: number;
+  delayInMs?: number;
+  minHeightChange?: number;
+}): 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.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Basic Infinite Scroll
+import { scrollToLoadContent } from "@intuned/browser";
+export default async function handler(params, page, context){
+// Scroll through entire page content
+await page.goto("https://docs.intunedhq.com/docs-old/getting-started/introduction")
+await scrollToLoadContent({
+  source: page,
+});
+// Now all content is loaded and visible
+}
+```
+
+```typescript Scroll Specific Container
+import { scrollToLoadContent } from "@intuned/browser";
+export default async function handler(params, page, context){
+// Scroll through a specific scrollable div
+await page.goto("https://docs.intunedhq.com/docs-old/getting-started/introduction")
+const container = page.locator("xpath=//div[@id='sidebar-content']");
+await scrollToLoadContent({
+  source: page,
+  scrollableContainer: container,
+  maxScrolls: 20
+});
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="input" type="Object" required
+>
+The input object containing the data to scroll to load content
+
+<Expandable title="input">
+<ParamField path="input.source" type="Page | Locator">
+The Playwright Page or Locator to scroll
+</ParamField>
+
+<ParamField path="input.onScrollProgress" type="Function">
+Optional callback function to call during each scroll iteration
+</ParamField>
+
+<ParamField path="input.scrollableContainer" type="Locator">
+Specific scrollable element to scroll within. If not provided, scrolls the entire page
+</ParamField>
+
+<ParamField path="input.maxScrolls" type="number">
+Maximum number of scroll attempts before stopping. Defaults to 50
+</ParamField>
+
+<ParamField path="input.delayInMs" type="number">
+Delay in milliseconds between scroll attempts. Defaults to 100
+</ParamField>
+
+<ParamField path="input.minHeightChange" type="number">
+Minimum height change in pixels required to continue scrolling. Defaults to 100
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `Promise<void>`
+
+Promise that resolves when scrolling is complete

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

@@ -0,0 +1,121 @@
+---
+title: uploadFileToS3
+description: ""
+---
+
+```typescript
+export declare function uploadFileToS3(input: {
+  file: FileType;
+  configs?: S3Configs;
+  fileNameOverride?: string;
+  contentType?: string;
+}): Promise<Attachment>;
+```
+
+<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
+</Note>
+
+Uploads files to AWS S3 storage with flexible configuration options.
+
+This function accepts various file types including Playwright Download objects, binary data,
+and file streams, making it versatile for different upload scenarios. It automatically
+handles file metadata and provides comprehensive S3 configuration options.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Upload Downloaded File
+import { downloadFile, uploadFileToS3 } from "@intuned/browser";
+export default async function handler(params, page, context){
+// Download and upload a file with custom S3 configuration
+await page.goto("https://sandbox.intuned.dev/pdfs")
+const download = await downloadFile({
+  page,
+  trigger: page.locator("xpath=//tbody/tr[1]//*[name()='svg']")
+});
+
+const uploadedFile = await uploadFileToS3({
+  file: download,
+  configs: {
+      bucket: 'my-documents',
+      region: 'us-west-2',
+      accessKeyId: 'accessKeyId',
+      secretAccessKey: 'SecretAccessKeyId'
+    },
+    fileNameOverride: 'reports/monthly-report.pdf'
+  }
+});
+
+console.log(`File uploaded: ${uploadedFile.suggestedFileName}`);
+console.log(`S3 URL: ${uploadedFile.getS3Key()}`);
+}
+```
+
+```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
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="input" type="Object" required
+>
+Configuration object for the upload operation
+
+<Expandable title="input">
+<ParamField path="input.file" type="FileType">
+The file to upload. Accepts [FileType](../type-aliases/FileType) types including:
+  - Playwright Download objects (from `downloadFile`)
+  - Uint8Array or Buffer (binary data)
+  - ReadStream (file streams)
+</ParamField>
+
+<ParamField path="input.configs" type="S3Configs">
+Optional [S3Configs](../interfaces/S3Configs) for customizing the S3 upload. If not provided, uses environment variables or default configuration
+</ParamField>
+
+<ParamField path="input.fileNameOverride" type="string">
+Optional custom filename for the uploaded file. If not provided, uses the original filename
+</ParamField>
+
+<ParamField path="input.contentType" type="string">
+Optional MIME type for the uploaded file (e.g., "application/pdf", "image/png")
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `Promise<Attachment>`
+
+Promise that resolves to an [Attachment](../interfaces/Attachment) object with file metadata and utility methods

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

@@ -0,0 +1,90 @@
+---
+title: validateDataUsingSchema
+description: ""
+---
+
+```typescript
+export declare function validateDataUsingSchema(input: {
+  data: Record<string, any>[] | Record<string, any>;
+  schema: Record<string, any>;
+}): Promise<void>;
+```
+
+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.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Basic User Data Validation
+import { validateDataUsingSchema } from "@intuned/browser";
+export default async function handler(params, page, context){
+const userData = {
+  name: "John Doe",
+  email: "john@example.com",
+  age: 30
+};
+
+const userSchema = {
+  type: "object",
+  required: ["name", "email", "age"],
+  properties: {
+    name: { type: "string", minLength: 1 },
+    email: { type: "string", format: "email" },
+    age: { type: "number", minimum: 0 }
+  }
+};
+
+await validateDataUsingSchema({ data: userData, schema: userSchema });
+// Validation passes, no error thrown
+}
+```
+
+```typescript Invalid Data Validation
+import { validateDataUsingSchema } from "@intuned/browser";
+export default async function handler(params, page, context){
+const userData = {
+  name: "John Doe",
+  email: "john@example.com",
+};
+
+const userSchema = {
+  type: "object",
+  required: ["name", "email", "age"],
+  properties: {
+    name: { type: "string", minLength: 1 },
+    email: { type: "string", format: "email" },
+    age: { type: "number", minimum: 0 }
+  }
+};
+
+await validateDataUsingSchema({ data: userData, schema: userSchema });
+// Validation fails, throws ValidationError
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="input" type="Object" required
+>
+The input object containing data and schema
+
+<Expandable title="input">
+<ParamField path="input.data" type="Record<string, any> | Array<Record<string, any>>">
+The data to validate. Can be a single data object or an array of data objects
+</ParamField>
+
+<ParamField path="input.schema" type="Record<string, any>">
+JSON schema object defining validation rules
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `Promise<void>`
+
+Promise that resolves if validation passes, throws ValidationError if it fails

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

@@ -0,0 +1,91 @@
+---
+title: waitForDomSettled
+description: ""
+---
+
+```typescript
+export declare function waitForDomSettled(options: {
+  source: Page | Locator;
+  settleDurationMs?: number;
+  timeoutInMs?: number;
+}): Promise<boolean>;
+```
+
+Waits for the DOM to stop changing before proceeding. Useful for dynamic content
+that loads progressively or elements that appear/update after initial page load.
+
+This function monitors DOM mutations and waits for a specified duration of stability
+before considering the DOM "settled". It can monitor either the entire page or a
+specific element within the page.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Wait for Page Content to Stabilize
+import { waitForDomSettled } from '@intuned/browser';
+export default async function handler(params, page, context){
+// Navigate to a dynamic page
+await page.goto('https://docs.intunedhq.com/docs-old/getting-started/introduction');
+
+// Wait for entire page content to stabilize
+const settled = await waitForDomSettled({
+  source: page,
+  settleDurationMs: 1000
+});
+
+if (settled) {
+  // Safe to scrape or interact with content
+  console.log(`Found stable items`);
+} else {
+  console.log("DOM never fully settled, proceeding anyway");
+}
+}
+```
+
+```typescript Monitor Specific Container
+import { waitForDomSettled } from '@intuned/browser';
+export default async function handler(params, page, context){
+await page.goto("https://docs.intunedhq.com/")
+// Wait for a specific feed container to stop updating
+const settled = await waitForDomSettled({
+  source: page.locator("xpath=//div[@id='sidebar-content']"),
+  settleDurationMs: 2000,
+  timeoutInMs: 15000,
+});
+
+if (settled) {
+  // Now the feed is stable, safe to extract articles
+  console.log(`Feed stabilized`);
+}
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="options" type="Object" required
+>
+Configuration object for DOM settlement monitoring
+
+<Expandable title="options">
+<ParamField path="options.source" type="Page | Locator">
+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
+</ParamField>
+
+<ParamField path="options.settleDurationMs" type="number">
+Milliseconds the DOM must remain unchanged to be considered settled. Defaults to 500
+</ParamField>
+
+<ParamField path="options.timeoutInMs" type="number">
+Maximum milliseconds to wait before giving up. Defaults to 30000
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `Promise<boolean>`
+
+Promise that resolves to true if DOM settled within timeout, false if timeout or error occurred