@intuned/browser-dev 2.2.3-test-build.0

package/dist/optimized-extractors/validators.js

@@ -0,0 +1,152 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.strategySchema = exports.simpleObjectJsonSchema = exports.simpleArrayItemJsonSchema = exports.extractObjectOptimizedInputSchema = exports.extractArrayOptimizedInputSchema = void 0;
+var _zod = require("zod");
+var _aiModelsValidation = require("./types/aiModelsValidation");
+const htmlStrategySchema = _zod.z.object({
+  model: _zod.z.enum(_aiModelsValidation.SUPPORTED_TEXT_MODELS, {
+    required_error: "strategy model is required",
+    invalid_type_error: "strategy model is invalid"
+  }),
+  type: _zod.z.literal("HTML", {
+    required_error: "strategy type is required",
+    invalid_type_error: "strategy type is invalid"
+  })
+});
+const imageStrategySchema = _zod.z.object({
+  model: _zod.z.enum(_aiModelsValidation.SUPPORTED_VISION_MODELS, {
+    required_error: "strategy model is required",
+    invalid_type_error: "strategy model is invalid"
+  }),
+  type: _zod.z.literal("IMAGE", {
+    required_error: "strategy type is required",
+    invalid_type_error: "strategy type is invalid"
+  })
+});
+const simpleStringSchema = _zod.z.object({
+  type: _zod.z.literal("string", {
+    required_error: "property type is required",
+    invalid_type_error: "optimized extractors only support string types"
+  }),
+  description: _zod.z.string({
+    required_error: "property description is required",
+    invalid_type_error: "property description must be a string"
+  }).optional()
+});
+const simpleArrayStringSchema = simpleStringSchema.extend({
+  primary: _zod.z.boolean().optional()
+});
+const simpleObjectJsonSchema = exports.simpleObjectJsonSchema = _zod.z.object({
+  type: _zod.z.literal("object", {
+    errorMap: () => ({
+      message: 'schema type is required, and must have the value "object"'
+    })
+  }),
+  description: _zod.z.string().optional(),
+  properties: _zod.z.record(_zod.z.string(), simpleStringSchema, {
+    required_error: "properties is required in object schemas"
+  }),
+  required: _zod.z.array(_zod.z.string(), {
+    required_error: "required must be an array of strings",
+    invalid_type_error: "required must be an array of strings"
+  }).min(1, {
+    message: "at least one property must be required"
+  })
+}, {
+  required_error: "schema is required"
+}).refine(data => {
+  return data.required.every(key => Object.keys(data.properties).includes(key));
+}, {
+  message: "All required keys must be defined in the properties object"
+}).refine(data => {
+  return Object.keys(data.properties).length > 0;
+}, {
+  message: "you must have at least one property in the properties object"
+});
+const simpleArrayItemJsonSchema = exports.simpleArrayItemJsonSchema = _zod.z.object({
+  type: _zod.z.literal("object", {
+    errorMap: () => ({
+      message: 'schema type is required, and must have the value "object"'
+    })
+  }),
+  description: _zod.z.string().optional(),
+  properties: _zod.z.record(_zod.z.string(), simpleArrayStringSchema, {
+    required_error: "properties is required in object schemas"
+  }),
+  required: _zod.z.array(_zod.z.string(), {
+    required_error: "required must be an array of strings",
+    invalid_type_error: "required must be an array of strings"
+  }).min(1, {
+    message: "at least one property must be required"
+  })
+}, {
+  required_error: "schema is required"
+}).refine(data => {
+  return data.required.every(key => Object.keys(data.properties).includes(key));
+}, {
+  message: "All required keys must be defined in the properties object"
+}).refine(data => {
+  const primaryField = Object.entries(data.properties).find(([k, v]) => v.primary);
+  return primaryField;
+}, {
+  message: "you must have one primary property"
+}).refine(data => {
+  const primaryField = Object.entries(data.properties).find(([k, v]) => v.primary);
+  if (!primaryField) {
+    return false;
+  }
+  return data.required.includes(primaryField[0]);
+}, {
+  message: "The primary field must be required"
+});
+const strategySchema = exports.strategySchema = _zod.z.union([htmlStrategySchema, imageStrategySchema], {
+  errorMap: (err, context) => {
+    if (err.code === "invalid_union" && context.data.model === "gpt3.5-turbo" && context.data.type === "IMAGE") {
+      return {
+        message: "gpt3.5-turbo does not support IMAGE strategy"
+      };
+    }
+    return {
+      message: err.message ?? "invalid strategy configuration"
+    };
+  }
+}).optional().default({
+  model: "claude-3-haiku",
+  type: "HTML"
+});
+const labelSchema = _zod.z.string({
+  invalid_type_error: "label must be a string",
+  required_error: "label is required"
+}).min(1, "label must be at least 1 character long");
+const entityNameSchema = _zod.z.string().min(1, {
+  message: "entity name must be at least 1 character long."
+}).max(50, {
+  message: "entity name must be no more than 50 characters long."
+}).regex(/^[a-zA-Z0-9_-]+$/, {
+  message: "entity name can only contain letters, digits, underscores, and hyphens."
+});
+const extractObjectOptimizedInputSchema = exports.extractObjectOptimizedInputSchema = _zod.z.object({
+  label: labelSchema,
+  strategy: strategySchema,
+  entityName: entityNameSchema,
+  entitySchema: simpleObjectJsonSchema,
+  variantKey: _zod.z.string().optional().default("about:blank"),
+  prompt: _zod.z.string().optional(),
+  optionalPropertiesInvalidator: _zod.z.function().returns(_zod.z.array(_zod.z.string())).optional().default(() => () => []),
+  apiKey: _zod.z.string().optional()
+}, {
+  required_error: "extractObjectOptimized function missing configurations"
+});
+const extractArrayOptimizedInputSchema = exports.extractArrayOptimizedInputSchema = _zod.z.object({
+  label: labelSchema,
+  strategy: strategySchema,
+  prompt: _zod.z.string().optional(),
+  itemEntityName: entityNameSchema,
+  itemEntitySchema: simpleArrayItemJsonSchema,
+  variantKey: _zod.z.string().optional(),
+  optionalPropertiesInvalidator: _zod.z.function().returns(_zod.z.array(_zod.z.string())).optional().default(() => () => []),
+  apiKey: _zod.z.string().optional()
+});

package/dist/vite-env.d.js

@@ -0,0 +1 @@
+"use strict";

package/dist/vite-env.d.ts

@@ -0,0 +1,9 @@
+interface ImportMetaEnv {
+  readonly VITE_S3_BUCKET: string;
+  readonly VITE_AWS_REGION?: string;
+  readonly VITE_API_URL?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/docs.md

@@ -0,0 +1,14 @@
+to generate all docs run:
+  ```bash
+  yarn generate-all-docs
+  ```
+
+or run:
+```bash
+  yarn generate-docs <input.d.tx> [outputdir]
+```
+These commands will go to all export.d.ts file of the 5 namespaces and generate their docs.
+The script in ./scripts/generate-docs reads the JSDOCs in the directories and passes them to the markdown converters. And outputs functions in outputdir/functions and Interfaces at outputdir/interfaces
+The markdown converters scripts parse JSDOCs into a Mintlify compatable format.
+
+To write a jsdoc, follow the conventions found in any export.d.ts file, especially the one in `helpers/export.d.ts`.

package/generated-docs/ai/functions/extractStructuredData.mdx

@@ -0,0 +1,255 @@
+---
+title: extractStructuredData
+description: ""
+---
+
+<Tabs>
+
+<Tab title="From Page or Locator">
+
+```typescript
+export declare function extractStructuredData(options: {
+  source: Page | Locator;
+  dataSchema: JsonSchema | z.ZodSchema;
+  prompt?: string;
+  strategy?: "IMAGE" | "MARKDOWN" | "HTML";
+  enableDomMatching?: boolean;
+  enableCache?: boolean;
+  maxRetries?: number;
+  model?: SUPPORTED_MODELS;
+  apiKey?: string;
+}): Promise<any>;
+```
+
+Extract structured data from web pages using AI-powered content analysis.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Page source
+import { extractStructuredData } from '@intuned/browser/ai';
+export default async function handler(params, page, context){
+await page.goto("https://books.toscrape.com/")
+const product = await extractStructuredData({
+  source: page,
+  strategy: "HTML",
+  model: "gpt-4o"
+  dataSchema: {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      price: { type: "string" },
+      description: { type: "string" },
+      inStock: { type: "boolean" }
+    },
+    required: ["name", "price"]
+  },
+  prompt: "Extract product details from this e page"
+});
+}
+console.log(`Found book: ${product.name} - ${product.price}`);
+```
+
+```typescript Locator source
+import { extractStructuredData } from '@intuned/browser/ai';
+export default async function handler(params, page, context){
+await page.goto("https://books.toscrape.com/")
+const articleContainer = page.locator("article").first()
+const article = await extractStructuredData({
+  source: articleContainer,
+  strategy: "MARKDOWN",
+  model: "claude-3",
+  dataSchema: {
+  type: "object",
+  properties: {
+    title: { type: "string" },
+    author: { type: "string" },
+    publishDate: { type: "string" },
+    content: { type: "string" },
+  },
+  required: ["title"]
+},
+  maxRetries: 5
+});
+}
+console.log(`Found book: ${article.title}`);
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="options" type="Object" required
+>
+Configuration object containing extraction parameters
+
+<Expandable title="options">
+<ParamField path="options.source" type="Page | Locator">
+Playwright Page object to extract data from the entire page or Locator object to extract data from a specific element
+</ParamField>
+
+<ParamField path="options.dataSchema" type="JsonSchema | z.ZodSchema">
+JsonSchema defining the structure of the data to extract. This can be a JsonSchema or ZodSchema
+</ParamField>
+
+<ParamField path="options.strategy" type="string">
+Type of extraction: "HTML", "IMAGE", or "MARKDOWN". Defaults to "HTML"
+</ParamField>
+
+<ParamField path="options.prompt" type="string">
+Optional prompt to guide the extraction process and provide more context
+</ParamField>
+
+<ParamField path="options.enableDomMatching" type="boolean">
+Whether to enable DOM element matching during extraction. Defaults to false. When set to true, all types in the schema must be strings to match with the DOM elements. The extracted results will be matched with the DOM elements and returned, then cached in a smart fashion so that the next time the same data is extracted, the result will be returned from the cache even if the DOM has minor changes.
+</ParamField>
+
+<ParamField path="options.enableCache" type="boolean">
+Whether to enable caching of the extracted data. Defaults to true
+</ParamField>
+
+<ParamField path="options.maxRetries" type="number">
+Maximum number of retry attempts on failures. Failures can be validation errors, API errors, output errors, etc. Defaults to 3
+</ParamField>
+
+<ParamField path="options.model" type="SUPPORTED_MODELS">
+AI model to use for extraction. See [SUPPORTED_MODELS](../type-aliases/SUPPORTED_MODELS) for all supported models. Defaults to "claude-3-5-haiku-latest"
+</ParamField>
+
+<ParamField path="options.apiKey" type="string">
+Optional API key for AI extraction (if provided, will not be billed to your account)
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `any`
+
+Promise resolving to the extracted structured data matching the provided schema
+
+</Tab>
+
+<Tab title="From Content">
+
+```typescript
+export declare function extractStructuredData(options: {
+  content: ContentItem[] | ContentItem;
+  dataSchema: JsonSchema | z.ZodSchema;
+  prompt?: string;
+  maxRetires?: number;
+  enableCache?: boolean;
+  model: SUPPORTED_MODELS;
+  apiKey?: string;
+}): Promise<any>;
+```
+
+Extract structured data from content items (text, images) using AI-powered analysis.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Text Content
+import { extractStructuredData } from '@intuned/browser/ai';
+export default async function handler(params, page, context){
+const textContent: TextContentItem = {
+  type: "text",
+  data: "John Doe, age 30, works as a Software Engineer at Tech Corp"
+};
+
+const person = await extractStructuredData({
+  content: textContent,
+  model: "gpt-4o",
+  dataSchema: {
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    age: { type: "number" },
+    occupation: { type: "string" },
+    company: { type: "string" }
+  },
+  required: ["name"]
+},
+  prompt: "Extract person information from the text"
+});
+
+console.log(`Found person: ${person.name}, ${person.age} years old`);
+}
+```
+
+```typescript Multiple Content Items
+import { extractStructuredData } from '@intuned/browser/ai';
+export default async function handler(params, page, context){
+const mixedContent = [
+  { type: "text", data: "Product: iPhone 15" },
+  { type: "image-url", image_type: "jpeg", data: "https://mintcdn.com/intuned-7/asXJUUPBWwDlStUB/logo/light.svg?fit=max&auto=format&n=asXJUUPBWwDlStUB&q=85&s=6525c0b299b3226464eba6afa9b7ebe6" }
+];
+
+
+const product = await extractStructuredData({
+  content: mixedContent,
+  model: "claude-3",
+  dataSchema: {
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    price: { type: "string" },
+    features: { type: "array", items: { type: "string" } }
+  }
+},
+  maxRetries: 1,
+  enableCache: true
+});
+}
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="options" type="Object" required
+>
+Configuration object containing extraction parameters
+
+<Expandable title="options">
+<ParamField path="options.content" type="Array<ContentItem> | ContentItem">
+Content to extract data from - can be a single content item or array of content items
+</ParamField>
+
+<ParamField path="options.dataSchema" type="JsonSchema | z.ZodSchema">
+JsonSchema defining the structure of the data to extract
+</ParamField>
+
+<ParamField path="options.prompt" type="string">
+Optional prompt to guide the extraction process and provide more context
+</ParamField>
+
+<ParamField path="options.enableCache" type="boolean">
+Whether to enable caching of the extracted data. Defaults to true
+</ParamField>
+
+<ParamField path="options.maxRetries" type="number">
+Maximum number of retry attempts on failures. Failures can be validation errors, API errors, output errors, etc. Defaults to 3
+</ParamField>
+
+<ParamField path="options.model" type="SUPPORTED_MODELS">
+AI model to use for extraction (e.g., "gpt-4", "claude-3"), see [SUPPORTED_MODELS](../type-aliases/SUPPORTED_MODELS) for all supported models
+</ParamField>
+
+<ParamField path="options.apiKey" type="string">
+Optional API key for AI extraction (if provided, will not be billed to your account)
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `any`
+
+Promise resolving to the extracted structured data matching the provided schema
+
+</Tab>
+
+</Tabs>

package/generated-docs/ai/functions/isPageLoaded.mdx

@@ -0,0 +1,88 @@
+---
+title: isPageLoaded
+description: ""
+---
+
+```typescript
+export declare function isPageLoaded(input: {
+  page: Page;
+  timeoutInMs?: number;
+  model?: SUPPORTED_MODELS;
+  apiKey?: string;
+}): Promise<boolean>;
+```
+
+Uses AI vision to determine if a webpage has finished loading by analyzing a screenshot.
+Detects loading spinners, blank content, or incomplete page states.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Check Page Loading
+import { isPageLoaded } from "@intuned/browser/ai";
+export default async function handler(params, page, context){
+// Wait for page to finish loading
+await page.goto('https://example.com');
+
+const pageLoaded = await isPageLoaded({page});
+if (pageLoaded) {
+  // Continue with scraping or interactions
+} else {
+  // Wait longer or retry
+}
+}
+```
+
+```typescript Loading Loop
+import { isPageLoaded } from "@intuned/browser/ai";
+export default async function handler(params, page, context){
+// Keep checking until page loads
+await page.goto("https://example.com");
+let attempts = 0;
+while (attempts < 10) {
+  const pageLoaded = await isPageLoaded({
+    page,
+    model: "gpt-4o",
+    timeoutInMs: 5000
+  });
+  if (pageLoaded) break;
+
+  await page.waitForTimeout(2000);
+  attempts++;
+}
+```
+}
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField path="input" type="Object" required
+>
+Input object containing the page to check
+
+<Expandable title="input">
+<ParamField path="input.page" type="Page">
+The Playwright page to check
+</ParamField>
+
+<ParamField path="input.timeoutInMs" type="number">
+Screenshot timeout in milliseconds. Defaults to 10000
+</ParamField>
+
+<ParamField path="input.model" type="SUPPORTED_MODELS">
+AI model to use for the check. See [SUPPORTED_MODELS](../type-aliases/SUPPORTED_MODELS) for all supported models. Defaults to "gpt-4o-2024-08-06"
+</ParamField>
+
+<ParamField path="input.apiKey" type="string">
+Optional API key for the AI service (if provided, will not be billed to your account)
+</ParamField>
+
+</Expandable>
+
+</ParamField>
+
+## Returns: `Promise<boolean>`
+
+Promise resolving to true if page is loaded, false if still loading

package/generated-docs/ai/interfaces/ArraySchema.mdx

@@ -0,0 +1,36 @@
+---
+title: ArraySchema
+description: ""
+---
+
+```typescript
+export interface ArraySchema extends BasicSchema {
+  type: "array";
+  items: JsonSchema | z.ZodSchema;
+  maxItems?: number;
+  minItems?: number;
+  uniqueItems?: boolean;
+}
+```
+
+Schema definition for array values with item validation and constraints.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Array Schema
+import { ArraySchema } from "@intuned/browser/ai";
+export default async function handler(params, page, context){
+const tagsSchema: ArraySchema = {
+  type: "array",
+  items: { type: "string" },
+  minItems: 1,
+  maxItems: 10,
+  uniqueItems: true,
+  description: "List of tags"
+};
+}
+```
+
+</CodeGroup>

package/generated-docs/ai/interfaces/BasicSchema.mdx

@@ -0,0 +1,14 @@
+---
+title: BasicSchema
+description: ""
+---
+
+```typescript
+export interface BasicSchema {
+  type: "string" | "number" | "integer" | "boolean" | "array" | "object";
+  description?: string;
+}
+```
+
+Base schema interface that all JSON schema types extend from.
+Provides common properties like type and description.

package/generated-docs/ai/interfaces/BooleanSchema.mdx

@@ -0,0 +1,28 @@
+---
+title: BooleanSchema
+description: ""
+---
+
+```typescript
+export interface BooleanSchema extends BasicSchema {
+  type: "boolean";
+}
+```
+
+Schema definition for boolean values.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Boolean Schema
+import { BooleanSchema } from "@intuned/browser/ai";
+export default async function handler(params, page, context){
+const isActiveSchema: BooleanSchema = {
+  type: "boolean",
+  description: "Whether the user account is active"
+};
+}
+```
+
+</CodeGroup>

package/generated-docs/ai/interfaces/ImageBufferContentItem.mdx

@@ -0,0 +1,16 @@
+---
+title: ImageBufferContentItem
+description: ""
+---
+
+```typescript
+export interface ImageBufferContentItem {
+  type: "image-buffer";
+  image_type: "png" | "jpeg" | "gif" | "webp";
+  data: Buffer;
+}
+```
+
+Represents image content provided as a Buffer for AI extraction.
+Used when passing image data directly to extractStructuredData without a page source.
+The image will be analyzed by AI vision models for data extraction.

package/generated-docs/ai/interfaces/ImageUrlContentItem.mdx

@@ -0,0 +1,16 @@
+---
+title: ImageUrlContentItem
+description: ""
+---
+
+```typescript
+export interface ImageUrlContentItem {
+  type: "image-url";
+  image_type: "png" | "jpeg" | "gif" | "webp";
+  data: string;
+}
+```
+
+Represents image content provided as a URL for AI extraction.
+Used when passing image URLs directly to extractStructuredData without a page source.
+The image will be fetched from the URL and analyzed by AI vision models for data extraction.

package/generated-docs/ai/interfaces/NumberSchema.mdx

@@ -0,0 +1,35 @@
+---
+title: NumberSchema
+description: ""
+---
+
+```typescript
+export interface NumberSchema extends BasicSchema {
+  type: "number" | "integer";
+  multipleOf?: number;
+  maximum?: number;
+  exclusiveMaximum?: number;
+  minimum?: number;
+  exclusiveMinimum?: number;
+}
+```
+
+Schema definition for numeric values (numbers and integers) with validation constraints.
+
+## Examples
+
+<CodeGroup>
+
+```typescript Number Schema
+import { NumberSchema } from "@intuned/browser/ai";
+export default async function handler(params, page, context){
+const ageSchema: NumberSchema = {
+  type: "integer",
+  minimum: 0,
+  maximum: 150,
+  description: "Person's age in years"
+};
+}
+```
+
+</CodeGroup>