@intuned/browser-dev 0.1.4-dev.0

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

@@ -0,0 +1,76 @@
+---
+title: withNetworkSettledWait
+description: ""
+---
+
+```typescript
+export declare function withNetworkSettledWait<T>(callback: (page: Page) => Promise<T>,
+  options?: {
+    page: Page;
+    timeoutInMs?: number;
+    maxInflightRequests?: number;
+  }): Promise<T>;
+```
+
+Executes a callback function and waits for network requests to settle before returning.
+
+This function monitors network activity and waits for all pending requests to complete
+(or reach the specified maximum) before resolving. Useful for ensuring dynamic content
+has fully loaded after performing actions that trigger network requests.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Navigation with Network Settlement
+import { withNetworkSettledWait } from "@intuned/browser";
+export default async function handler(params, page, context){
+// Navigate and ensure all resources are loaded
+await withNetworkSettledWait(
+  async (page) => {
+    await page.goto('https://spa-app.com/dashboard');
+    // Return when navigation is complete and network is idle
+  },
+  {
+    page,
+    timeoutInMs: 20000,
+    maxInflightRequests: 0 // Wait for complete network silence
+  }
+);
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="callback" type="Function" required
+>
+The callback function to execute. Receives the page object as parameter
+
+</ParamField>
+
+<ParamField path="options" type="Object"
+>
+Configuration options for network monitoring
+
+<Expandable title="options">
+<ParamField path="options.page" type="Page">
+The Playwright page object to monitor for network activity
+</ParamField>
+
+<ParamField path="options.timeoutInMs" type="number">
+Maximum time to wait in milliseconds before timing out. Defaults to 30000
+</ParamField>
+
+<ParamField path="options.maxInflightRequests" type="number">
+Maximum number of pending requests to consider as "settled". Defaults to 0 (waits for all requests to complete)
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `Promise<T>`
+
+Promise that resolves to the callback's return value after network settles

package/generated-docs/helpers/interfaces/Attachment.mdx

@@ -0,0 +1,56 @@
+---
+title: Attachment
+description: ""
+---
+
+```typescript
+export interface Attachment {
+  fileName: string;
+  bucket: string;
+  region: string;
+  endpoint?: string;
+  suggestedFileName: string;
+  fileType?: AttachmentType;
+  toJSON(): Record<string,
+  string>;
+  toDict(): Record<string,
+  string>;
+  getS3Key(): string;
+  getFilePath(): string;
+  getSignedUrl(expiration?: number): 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.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Attachment Usage
+import { uploadFileToS3 } from "@intuned/browser";
+export default async function handler(params, page, context){
+// Typically returned from uploadFileToS3 or saveFileToS3
+
+const uploadedFile: Attachment = await uploadFileToS3({
+  file: myFile,
+  configs: s3Config
+});
+
+// Access file properties
+console.log(uploadedFile.fileName); // "documents/report.pdf"
+console.log(uploadedFile.suggestedFileName); // "Monthly Report.pdf"
+
+// Get a presigned URL for download
+const downloadUrl = await uploadedFile.getSignedUrl(3600); // 1 hour
+
+// Convert to dictionary for storage or API responses
+const fileDict = uploadedFile.toDict();
+}
+```
+
+</CodeGroup>

package/generated-docs/helpers/interfaces/S3Configs.mdx

@@ -0,0 +1,52 @@
+---
+title: S3Configs
+description: ""
+---
+
+```typescript
+export interface S3Configs {
+  bucket?: string;
+  region?: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  endpoint?: string;
+}
+```
+
+Configuration options for AWS S3 storage operations.
+
+This interface defines the authentication and configuration properties
+for connecting to and performing operations with AWS S3 storage. All properties
+are optional and will fall back to environment variables or default configuration.
+
+## Examples
+
+<CodeGroup>
+
+```typescript S3 Configuration
+import { uploadFileToS3 } from "@intuned/browser";
+export default async function handler(params, page, context){
+// Basic S3 configuration
+const s3Config: S3Configs = {
+  bucket: "my-app-uploads",
+  region: "us-east-1",
+  accessKeyId: "accessKeyId",
+  secretAccessKey: "SecretAccessKeyId"
+};
+
+// Use with file upload
+const attachment = await uploadFileToS3({
+  file: myFile,
+  configs: s3Config
+});
+
+// Use with download and upload operations
+const uploadedFile = await saveFileToS3({
+  page,
+  trigger: downloadUrl,
+  configs: s3Config
+});
+}
+```
+
+</CodeGroup>

package/generated-docs/helpers/interfaces/SanitizeHtmlOptions.mdx

@@ -0,0 +1,22 @@
+---
+title: SanitizeHtmlOptions
+description: ""
+---
+
+```typescript
+export interface SanitizeHtmlOptions {
+  html: string;
+  removeScripts?: boolean;
+  removeStyles?: boolean;
+  removeSvgs?: boolean;
+  removeComments?: boolean;
+  removeLongAttributes?: boolean;
+  maxAttributeLength?: number;
+  preserveAttributes?: string[];
+  removeEmptyTags?: boolean;
+  preserveEmptyTags?: string[];
+  minifyWhitespace?: boolean;
+}
+```
+
+Configuration options for sanitizing HTML content.

package/generated-docs/helpers/type-aliases/AttachmentType.mdx

@@ -0,0 +1,10 @@
+---
+title: AttachmentType
+description: ""
+---
+
+```typescript
+export type AttachmentType = "document";
+```
+
+Union type representing the supported attachment file types.

package/generated-docs/helpers/type-aliases/FileType.mdx

@@ -0,0 +1,61 @@
+---
+title: FileType
+description: ""
+---
+
+```typescript
+export type FileType = Download | Uint8Array | Buffer | ReadStream;
+```
+
+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.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Using Download Object
+import { downloadFile, uploadFileToS3 } from "@intuned/browser";
+export default async function handler(params, page, context){
+// From a browser download
+const download = await downloadFile({
+  page,
+  trigger: "https://example.com/file.pdf"
+});
+const uploaded = await uploadFileToS3({
+  file: download,
+  configs: s3Config
+});
+}
+```
+
+```typescript Using Buffer
+import { uploadFileToS3 } from "@intuned/browser";
+export default async function handler(params, page, context){
+// From raw buffer
+const fileBuffer = Buffer.from("PDF content here...", "utf8");
+const uploaded = await uploadFileToS3({
+  file: fileBuffer,
+  fileNameOverride: "generated.pdf",
+  configs: s3Config
+});
+}
+```
+
+```typescript Using ReadStream
+import { uploadFileToS3 } from "@intuned/browser";
+import { createReadStream } from "fs";
+export default async function handler(params, page, context){
+// From a file stream
+const fileStream = createReadStream("/path/to/document.pdf");
+const uploaded = await uploadFileToS3({
+  file: fileStream,
+  fileNameOverride: "renamed.pdf",
+  configs: s3Config
+});
+}
+```
+
+</CodeGroup>

package/generated-docs/helpers/type-aliases/Trigger.mdx

@@ -0,0 +1,62 @@
+---
+title: Trigger
+description: ""
+---
+
+```typescript
+export type Trigger = string | Locator | ((page: Page) => Promise<void>);
+```
+
+<Note>
+All download functions in the helpers module accept Trigger for consistency.
+The trigger method determines how the download operation is initiated.
+</Note>
+
+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.
+
+## Examples
+
+<CodeGroup>
+
+```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"
+});
+}
+```
+
+```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
+});
+}
+```
+
+```typescript Custom Function Trigger
+import { downloadFile } from "@intuned/browser";
+export default async function handler(params, page, context){
+// Complex download logic
+const download = await downloadFile({
+  page,
+  trigger: async (page) => {
+    await page.click(".menu-trigger");
+    await page.waitForSelector(".download-option");
+    await page.click(".download-option");
+  }
+});
+}
+```
+
+</CodeGroup>

package/how-to-generate-docs.md

@@ -0,0 +1,61 @@
+## How to Generate Documentation
+
+### Generating Docs
+
+**Generate all docs (recommended):**
+
+```bash
+yarn generate-all-docs
+```
+
+This command processes all `export.d.ts` files from the 3 namespaces and generates their documentation.
+
+**Generate docs for a specific file:**
+
+```bash
+yarn generate-docs <input.d.ts> [outputdir]
+```
+
+**Examples:**
+
+```bash
+# Generate docs for helpers (recommended)
+yarn generate-docs ./src/helpers/export.d.ts ./generated-docs/helpers
+
+# Generate docs for AI functions
+yarn generate-docs ./src/ai/export.d.ts ./generated-docs/ai
+
+# Generate docs for optimized extractors
+yarn generate-docs ./src/optimized-extractors/export.d.ts ./generated-docs/optimized-extractors
+
+# Use default output directory (./generated-docs)
+yarn generate-docs ./src/helpers/export.d.ts
+```
+
+**Output Structure:**
+
+- Functions will be written to `[outputdir]/functions/`
+- Interfaces will be written to `[outputdir]/interfaces/`
+- Type aliases will be written to `[outputdir]/type-aliases/`
+
+### Available Namespaces
+
+The following namespaces have `export.d.ts` files that can be processed:
+
+- `./src/helpers/export.d.ts` - Helper functions for web automation
+- `./src/ai/export.d.ts` - AI-powered data extraction functions
+- `./src/optimized-extractors/export.d.ts` - Optimized data extraction functions
+
+### How It Works
+
+The script in `./scripts/generate-docs.ts` reads JSDocs from `export.d.ts` files and converts them to Mintlify-compatible markdown format using TypeScript AST parsing.
+
+### Writing JSDocs
+
+**Guidelines:**
+
+- Follow the conventions found in any `export.d.ts` file
+- Refer to `src/helpers/export.d.ts` for comprehensive examples
+- The markdown converters parse JSDocs into Mintlify-compatible format
+- Include `@example` blocks with TypeScript code snippets
+- Use `@param`, `@returns`, and `@interface` tags for proper documentation

package/how-to-run-tests.md

@@ -0,0 +1,42 @@
+## How to Run Tests
+
+### Creating Test Files
+
+Use `src/helpers/tests/extendedTest.ts` which uses Vitest by default. Import all test requirements from it and write your tests.
+
+### Running Tests
+
+**Run all tests:**
+
+```bash
+npm test
+```
+
+**Run with UI (live test reports):**
+
+```bash
+npx vitest --ui
+```
+
+**Run tests from a specific file:**
+
+```bash
+npx vitest --ui path/to/test.spec.ts
+```
+
+### Useful Flags
+
+**`-t` flag** - Filter tests by name
+
+- Run only tests that match a specific description
+- Also available as `--testNamePattern`
+
+```bash
+npx vitest -t "test description"
+```
+
+**Combine with UI:**
+
+```bash
+npx vitest --ui -t "test description"
+```

package/intuned-runtime-setup.md

@@ -0,0 +1,13 @@
+## Setting Up the TypeScript SDK and Runtime
+
+First, ensure you have Node.js and Yarn installed on your system, then run `yarn install` to set up the project dependencies.
+
+During development, you'll need to create a symlink to use your local version of `@intuned/runtime`.
+
+To set up the symlink:
+
+1. Navigate to `webApp/apps/typescript-runtime` and run `yarn build` after `yarn install` to build the runtime
+2. In the same directory, run `yarn link`
+3. Navigate to `webApp/apps/typescript-sdk` and run `yarn link "@intuned/runtime"`
+
+Note: Whenever you make changes to the runtime code, remember to run `yarn build` in the runtime directory for the changes to reflect in the SDK.

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "@intuned/browser-dev",
+  "version": "0.1.4-dev.0",
+  "description": "runner package for intuned functions",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "optimized-extractors": [
+        "./dist/optimized-extractors/index.d.ts"
+      ],
+      "ai": [
+        "./dist/ai/index.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./optimized-extractors": "./dist/optimized-extractors/index.js",
+    "./ai": "./dist/ai/index.js",
+    "./playwright": "./dist/playwright/index.js",
+    "./dist/common/settingsSchema": "./dist/common/settingsSchema.js",
+    "./dist/common/getPlaywrightConstructs": "./dist/common/getPlaywrightConstructs.js",
+    "./dist/common/contextStorageStateHelpers": "./dist/common/contextStorageStateHelpers.js",
+    "./dist/common/types": "./dist/common/types.js",
+    "./dist/common/requestMoreInfo": "./dist/common/requestMoreInfo.js",
+    "./dist/common/telemetry": "./dist/common/telemetry.js",
+    "./dist/common/jwtTokenManager": "./dist/common/jwtTokenManager.js",
+    "./dist/common/asyncLocalStorage": "./dist/common/asyncLocalStorage/index.js",
+    "./dist/common/cleanEnvironmentVariables": "./dist/common/cleanEnvironmentVariables.js",
+    "./dist/commands/common/getFirstLineNumber": "./dist/commands/common/getFirstLineNumber.js",
+    "./dist/commands/common/constants": "./dist/commands/common/constants.js",
+    "./dist/files/FileUploadAndDownload/utils": "./dist/files/FileUploadAndDownload/utils.js",
+    "./dist/ai/index.d.ts": "./dist/ai/index.d.ts"
+  },
+  "author": "Intuned Team",
+  "license": "Elastic-2.0",
+  "scripts": {
+    "generate-browser-script": "bash scripts/generate-browser-script.sh",
+    "prepare": "bash scripts/generate-browser-script.sh || echo 'Skipping browser script generation'",
+    "build": "rm -rf dist && yarn generate-browser-script && tsc -p tsconfig.json && yarn copy-dts && babel src --out-dir dist --extensions '.ts' && node scripts/ensure-index-types.js",
+    "ensure-types": "node scripts/ensure-index-types.js",
+    "test": "vitest run",
+    "test:dev": "vitest",
+    "test:watch": "vitest",
+    "clean-declarations": "find ./types-package -name \"*.d.ts\" -type f -delete",
+    "lint": "eslint .",
+    "fix": "eslint . --fix",
+    "generate-docs": "npx tsx ./scripts/generate-docs.ts",
+    "generate-all-docs": "npx tsx ./scripts/generate-docs.ts ./src/helpers/export.d.ts ./generated-docs/helpers && npx tsx ./scripts/generate-docs.ts ./src/ai/export.d.ts ./generated-docs/ai && npx tsx ./scripts/generate-docs.ts ./src/optimized-extractors/export.d.ts ./generated-docs/optimized-extractors",
+    "build-browser-scripts": "rollup -c ./src/common/browserScripts/rollup.config.mjs",
+    "copy-dts": "copyfiles -u 1 \"src/**/*.d.ts\" dist"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "2.0.1",
+    "@ai-sdk/google": "1.0.12",
+    "@ai-sdk/openai": "2.0.4",
+    "@ai-sdk/provider": "2.0.0",
+    "@anthropic-ai/sdk": "0.22.0",
+    "@aws-sdk/client-s3": "3.821.0",
+    "@aws-sdk/s3-request-presigner": "3.821.0",
+    "ai": "5.0.15",
+    "ajv": "8.13.0",
+    "ajv-formats": "2.1.1",
+    "async-mutex": "0.5.0",
+    "async-retry": "1.3.3",
+    "chalk": "4.1.2",
+    "chrono-node": "2.8.3",
+    "copyfiles": "2.4.1",
+    "date-fns": "4.1.0",
+    "dotenv": "^16.3.1",
+    "fs-extra": "11.1.1",
+    "image-size": "1.1.1",
+    "lodash": "4.17.21",
+    "neverthrow": "6.1.0",
+    "node-html-parser": "7.0.1",
+    "openai": "4.77.3",
+    "stack-utils": "2.0.6",
+    "tslib": "2.6.0",
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.24.6",
+    "zod-validation-error": "3.0.3"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.23.4",
+    "@babel/core": "^7.23.7",
+    "@babel/plugin-transform-export-namespace-from": "^7.24.1",
+    "@babel/preset-env": "^7.23.7",
+    "@babel/preset-typescript": "^7.23.3",
+    "@rollup/plugin-commonjs": "^25.0.2",
+    "@rollup/plugin-node-resolve": "15.1.0",
+    "@rollup/plugin-typescript": "11.1.2",
+    "@types/async-retry": "1.4.8",
+    "@types/fs-extra": "11.0.1",
+    "@types/jest": "^30.0.0",
+    "@types/lodash": "4.14.200",
+    "@types/node": "^24.1.0",
+    "@typescript-eslint/eslint-plugin": "^5.47.1",
+    "@typescript-eslint/parser": "^7.5.0",
+    "@vitest/ui": "^1.1.3",
+    "babel-plugin-macros": "^3.1.0",
+    "doctrine": "^3.0.0",
+    "eslint": "7.32.0",
+    "eslint-plugin-deprecation": "^1.3.3",
+    "eslint-plugin-prettier": "^4.2.1",
+    "jest": "^30.0.4",
+    "msw": "^2.1.2",
+    "playwright": "^1.55.0",
+    "prettier": "^2.8.8",
+    "rollup": "3.26.2",
+    "ts-jest": "^29.4.0",
+    "typescript": "5.4.4",
+    "vite": "^5.4.12",
+    "vite-plugin-babel-macros": "^1.0.6",
+    "vitest": "^1.1.3"
+  },
+  "peerDependencies": {
+    "@intuned/runtime": "*"
+  },
+  "peerDependenciesMeta": {
+    "@intuned/runtime": {
+      "optional": true
+    }
+  }
+}

package/tsconfig.eslint.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["**/*.ts", "**/*.d.ts"],
+  "exclude": ["node_modules"]
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "es2021",
+    "module": "esnext",
+    "esModuleInterop": true,
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "outDir": "./dist",
+    "strict": false,
+    "strictNullChecks": true,
+    "rootDir": "./src",
+    "sourceMap": false,
+    "declaration": false,
+    "emitDeclarationOnly": false,
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.d.ts",
+    "src/assets/**/*",
+    "types-package/noEmpty.ts",
+    "types-package/**/*.ts",
+    "types-package/**/*.d.ts"
+  ],
+  "exclude": ["node_modules", "**/*.test.ts", "**/__tests__/*"]
+}