@intuned/browser-dev 2.2.3-unify-sdks.28 → 2.2.3-unify-sdks.30

package/dist/ai/export.d.ts

@@ -1,4 +1,5 @@
 import { Locator, Page } from "playwright-core";
+import { z } from "zod";
 
 /**
  * Base schema interface that all JSON schema types extend from.
@@ -19,7 +20,7 @@ export interface BasicSchema {
  * @interface StringSchema
  * @extends BasicSchema
  * @example
- * ```typescript
+ * ```typescript String Schema
  * const nameSchema: StringSchema = {
  *   type: "string",
  *   minLength: 2,
@@ -48,7 +49,7 @@ export interface StringSchema extends BasicSchema {
  * @interface NumberSchema
  * @extends BasicSchema
  * @example
- * ```typescript
+ * ```typescript Number Schema
  * const ageSchema: NumberSchema = {
  *   type: "integer",
  *   minimum: 0,
@@ -78,7 +79,7 @@ export interface NumberSchema extends BasicSchema {
  * @interface BooleanSchema
  * @extends BasicSchema
  * @example
- * ```typescript
+ * ```typescript Boolean Schema
  * const isActiveSchema: BooleanSchema = {
  *   type: "boolean",
  *   description: "Whether the user account is active"
@@ -96,7 +97,7 @@ export interface BooleanSchema extends BasicSchema {
  * @interface ArraySchema
  * @extends BasicSchema
  * @example
- * ```typescript
+ * ```typescript Array Schema
  * const tagsSchema: ArraySchema = {
  *   type: "array",
  *   items: { type: "string" },
@@ -111,7 +112,7 @@ export interface ArraySchema extends BasicSchema {
   /** Must be "array" for array schemas */
   type: "array";
   /** Schema definition for array items */
-  items: JsonSchema;
+  items: JsonSchema | z.ZodSchema;
   /** Maximum number of items allowed */
   maxItems?: number;
   /** Minimum number of items required */
@@ -126,7 +127,7 @@ export interface ArraySchema extends BasicSchema {
  * @interface ObjectSchema
  * @extends BasicSchema
  * @example
- * ```typescript
+ * ```typescript Object Schema
  * const userSchema: ObjectSchema = {
  *   type: "object",
  *   properties: {
@@ -143,7 +144,7 @@ export interface ObjectSchema extends BasicSchema {
   /** Must be "object" for object schemas */
   type: "object";
   /** Schema definitions for object properties */
-  properties: Record<string, JsonSchema>;
+  properties: Record<string, JsonSchema | z.ZodSchema>;
   /** Array of required property names */
   required?: string[];
   /** Maximum number of properties allowed */
@@ -153,22 +154,54 @@ export interface ObjectSchema extends BasicSchema {
 }
 
 /**
- * Extract structured data from web pages using AI-powered content analysis.
+ * Union type representing all supported JSON schema types.
+ * Can be a StringSchema, NumberSchema, BooleanSchema, ArraySchema, or ObjectSchema.
+ * Each schema type provides validation constraints for its respective data type.
  *
+ * @type JsonSchema
+ * @example
+ * ```typescript Object Schema
+ * const schema: JsonSchema = {
+ *   type: "object",
+ *   properties: {
+ *     name: { type: "string" },
+ *     age: { type: "number" }
+ *   },
+ *   required: ["name"]
+ * };
+ * ```
+ * @example
+ * ```typescript Array Schema
+ * const schema: JsonSchema = {
+ *   type: "array",
+ *   items: { type: "string" },
+ *   minItems: 1
+ * };
+ * ```
+ */
+export type JsonSchema =
+  | StringSchema
+  | NumberSchema
+  | BooleanSchema
+  | ArraySchema
+  | ObjectSchema;
+/**
+ * Extract structured data from web pages using AI-powered content analysis.
+ * @overload From Page or Locator
  * This function provides intelligent data extraction from web pages using various strategies
  * including HTML parsing, image analysis, and Markdown conversion. It supports extraction
  * from entire pages or specific elements, with built-in caching and retry mechanisms.
  *
  * @param {Object} options - Configuration object containing extraction parameters
  * @param {Page | Locator} options.source - Playwright Page object to extract data from the entire page or Locator object to extract data from a specific element
- * @param {JsonSchema} options.dataSchema - [JsonSchema](../interfaces/JsonSchema) defining the structure of the data to extract
- * @param {SUPPORTED_MODELS} [options.model] - AI model to use for extraction (e.g., "gpt-4", "claude-3"), see [SUPPORTED_MODELS](../type-aliases/SUPPORTED_MODELS) for all supported models.
- * @param {string} [options.strategy] - Type of extraction: "HTML", "IMAGE", or "MARKDOWN"
+ * @param {JsonSchema | z.ZodSchema} options.dataSchema - JsonSchema defining the structure of the data to extract. This can be a [JsonSchema](../type-aliases/JsonSchema) or ZodSchema
+ * @param {SUPPORTED_MODELS} [options.model="claude-3-5-haiku-latest"] - AI model to use for extraction. See [SUPPORTED_MODELS](../type-aliases/SUPPORTED_MODELS) for all supported models. Defaults to "claude-3-5-haiku-latest"
+ * @param {string} [options.strategy="HTML"] - Type of extraction: "HTML", "IMAGE", or "MARKDOWN". Defaults to "HTML"
  * @param {string} [options.prompt] - Optional prompt to guide the extraction process and provide more context
- * @param {string} [options.apiKey] - Optional API key for AI extraction (if provided, will not be billed to your account)s
- * @param {boolean} [options.enableDomMatching=false] - Whether to disable DOM element matching during extraction. Defaults to False. When set to false, all types in the schema must be strings to match with the DOM elements. The extracted resultes will be matched with the DOM elements and returned, then will be 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.
- * @param {boolean} [options.enableCache=true] - Whether to enable caching of the extracted data. default true
-* @param {integer} [options.retries=3] - Maximum number of retry attempts on failures. Failures can be validation errors, api errors, output errors, etc.
+ * @param {string} [options.apiKey] - Optional API key for AI extraction (if provided, will not be billed to your account)
+ * @param {boolean} [options.enableDomMatching=false] - 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.
+ * @param {boolean} [options.enableCache=true] - Whether to enable caching of the extracted data. Defaults to true
+ * @param {number} [options.maxRetries=3] - Maximum number of retry attempts on failures. Failures can be validation errors, API errors, output errors, etc. Defaults to 3
  *
  * @returns Promise resolving to the extracted structured data matching the provided schema
 
@@ -176,7 +209,11 @@ export interface ObjectSchema extends BasicSchema {
  * ```typescript Extract Product Information from Entire Page
  * import { extractStructuredData } from '@intuned/browser/ai';
  *
- * const productSchema = {
+ * const product = await extractStructuredData({
+ *   source: page,
+ *   strategy: "HTML",
+ *   model: "gpt-4o",
+ *   dataSchema: {
  *   type: "object",
  *   properties: {
  *     name: { type: "string" },
@@ -185,13 +222,7 @@ export interface ObjectSchema extends BasicSchema {
  *     inStock: { type: "boolean" }
  *   },
  *   required: ["name", "price"]
- * };
- *
- * const product = await extractStructuredData({
- *   source: page,
- *   strategy: "HTML",
- *   model: "gpt-4o",
- *   dataSchema: productSchema,
+ * },
  *   prompt: "Extract product details from this e-commerce page"
  * });
  *
@@ -202,7 +233,12 @@ export interface ObjectSchema extends BasicSchema {
  * ```typescript Extract Article Data from Specific Element
  * import { extractStructuredData } from '@intuned/browser/ai';
  *
- * const articleSchema = {
+ * const articleContainer = page.locator("article.main-content");
+ * const article = await extractStructuredData({
+ *   source: articleContainer,
+ *   strategy: "MARKDOWN",
+ *   model: "claude-3",
+ *   dataSchema: {
  *   type: "object",
  *   properties: {
  *     title: { type: "string" },
@@ -212,64 +248,107 @@ export interface ObjectSchema extends BasicSchema {
  *     tags: { type: "array", items: { type: "string" } }
  *   },
  *   required: ["title", "content"]
- * };
- *
- * const articleContainer = page.locator("article.main-content");
- * const article = await extractStructuredData({
- *   source: articleContainer,
- *   strategy: "MARKDOWN",
- *   model: "claude-3",
- *   dataSchema: articleSchema,
+ * },
  *   maxRetries: 5
  * });
  *
  * console.log(`Article: ${article.title} by ${article.author}`);
  * ```
+ */
+export declare function extractStructuredData(options: {
+  source: Page | Locator;
+  dataSchema: JsonSchema | z.ZodSchema;
+  prompt?: string;
+  strategy?: "IMAGE" | "MARKDOWN" | "HTML";
+  model?: SUPPORTED_MODELS;
+  apiKey?: string;
+  enableDomMatching?: boolean;
+  enableCache?: boolean;
+  maxRetries?: number;
+}): Promise<any>;
+
+/**
+ * Extract structured data from content items (text, images) using AI-powered analysis.
+ * @overload From Content
+ * This overload provides a simplified interface for data extraction from various content types
+ * without requiring a page source or extraction strategy. It accepts text content, image buffers,
+ * or image URLs and extracts structured data according to the provided schema.
  *
- * @example 
- * ```typescript Extract Data from Screenshots using Image Strategy
+ * @param {Object} options - Configuration object containing extraction parameters
+ * @param {TextContentItem | ImageBufferContentItem | ImageUrlContentItem | Array<TextContentItem | ImageBufferContentItem | ImageUrlContentItem>} options.content - Content to extract data from - can be a single content item or array of content items
+ * @param {JsonSchema | z.ZodSchema} options.dataSchema - [JsonSchema](../type-aliases/JsonSchema) defining the structure of the data to extract
+ * @param {SUPPORTED_MODELS} options.model - AI model to use for extraction (e.g., "gpt-4", "claude-3"), see [SUPPORTED_MODELS](../type-aliases/SUPPORTED_MODELS) for all supported models
+ * @param {string} [options.prompt] - Optional prompt to guide the extraction process and provide more context
+ * @param {string} [options.apiKey] - Optional API key for AI extraction (if provided, will not be billed to your account)
+ * @param {boolean} [options.enableCache=true] - Whether to enable caching of the extracted data. Defaults to true
+ * @param {number} [options.maxRetries=3] - Maximum number of retry attempts on failures. Failures can be validation errors, API errors, output errors, etc. Defaults to 3
+ *
+ * @returns Promise resolving to the extracted structured data matching the provided schema
+ *
+ * @example
+ * ```typescript Extract Data from Text Content
  * import { extractStructuredData } from '@intuned/browser/ai';
  *
- * const chartSchema = {
- *   type: "object",
- *   properties: {
- *     title: { type: "string" },
- *     dataPoints: {
- *       type: "array",
- *       items: {
- *         type: "object",
- *         properties: {
- *           label: { type: "string" },
- *           value: { type: "number" }
- *         }
- *       }
- *     }
- *   }
+ * const textContent: TextContentItem = {
+ *   type: "text",
+ *   data: "John Doe, age 30, works as a Software Engineer at Tech Corp"
  * };
  *
- * const chartElement = page.locator("#data-visualization");
- * const chartData = await extractStructuredData({
- *   source: chartElement,
- *   strategy: "IMAGE",
+ * const person = await extractStructuredData({
+ *   content: textContent,
  *   model: "gpt-4o",
- *   dataSchema: chartSchema,
- *   prompt: "Extract the chart title and all data points with their values"
+ *   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(`Chart: ${chartData.title}`);
- * chartData.dataPoints.forEach(point => {
- *   console.log(`${point.label}: ${point.value}`);
+ * console.log(`Found person: ${person.name}, ${person.age} years old`);
+ * ```
+ *
+ * @example
+ * ```typescript Extract Data from Multiple Content Items
+ * import { extractStructuredData } from '@intuned/browser/ai';
+ *
+ * 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
  * });
  * ```
  */
 export declare function extractStructuredData(options: {
-  source: Page | Locator;
-  dataSchema: JsonSchema;
+  content:
+    | (TextContentItem | ImageBufferContentItem | ImageUrlContentItem)[]
+    | TextContentItem
+    | ImageBufferContentItem
+    | ImageUrlContentItem;
+  dataSchema: JsonSchema | z.ZodSchema;
   prompt?: string;
-  strategy?: "IMAGE" | "MARKDOWN" | "HTML";
-  model?: SUPPORTED_MODELS;
+  model: SUPPORTED_MODELS;
   apiKey?: string;
-  enableDomMatching?: boolean;
   enableCache?: boolean;
   maxRetries?: number;
 }): Promise<any>;
@@ -347,82 +426,98 @@ type SUPPORTED_OPENAI_MODELS =
   | "o4-mini-deep-research"
   | "o4-mini-deep-research-2025-06-26";
 /**
- * This type defines the supported AI models for data extraction.
- * It includes models from OpenAI, Anthropic, and Google Gemini.
- * The models are used in the extraction strategies to process and analyze the content of web pages or elements.
- * @type SUPPORTED_MODELS
- */
-type SUPPORTED_MODELS = SUPPORTED_CLAUDE_MODELS | SUPPORTED_OPENAI_MODELS;
-
-/**
- * Represents a JSON Schema definition for validating data structures.
- * Supports various schema types including string, number, boolean, array, and object schemas
- * with their respective validation rules and constraints.
+ * Union type representing all supported AI models for data extraction.
+ * Includes models from both OpenAI and Anthropic.
  *
- * This type is a union of different schema types:
- * - StringSchema: For string validation with length and pattern constraints
- * - NumberSchema: For number/integer validation with range constraints
- * - BooleanSchema: For boolean values
- * - ArraySchema: For array validation with item constraints
- * - ObjectSchema: For object validation with property constraints
- *
- * @type JsonSchema
- * @example
- * ```typescript String Schema
- * const stringSchema: JsonSchema = {
- *   type: "string",
- *   minLength: 3,
- *   maxLength: 50,
- *   pattern: "^[A-Za-z]+$"
- * };
- * ```
- *
- * @example
- * ```typescript Number Schema
- * const numberSchema: JsonSchema = {
- *   type: "number",
- *   minimum: 0,
- *   maximum: 100,
- *   multipleOf: 0.5
- * };
- * ```
+ * **Supported OpenAI Models:**
+ * "gpt-3.5-turbo"
+ * "gpt-3.5-turbo-0125"
+ * "gpt-3.5-turbo-0301"
+ * "gpt-3.5-turbo-0613"
+ * "gpt-3.5-turbo-1106"
+ * "gpt-3.5-turbo-16k"
+ * "gpt-3.5-turbo-16k-0613"
+ * "gpt-3.5-turbo-instruct"
+ * "gpt-3.5-turbo-instruct-0914"
+ * "gpt-4"
+ * "gpt-4-0314"
+ * "gpt-4-0613"
+ * "gpt-4-32k"
+ * "gpt-4-32k-0314"
+ * "gpt-4-32k-0613"
+ * "gpt-4-turbo"
+ * "gpt-4-turbo-2024-04-09"
+ * "gpt-4.1"
+ * "gpt-4.1-2025-04-14"
+ * "gpt-4.1-mini"
+ * "gpt-4.1-mini-2025-04-14"
+ * "gpt-4.1-nano"
+ * "gpt-4.1-nano-2025-04-14"
+ * "gpt-4o"
+ * "gpt-4o-2024-05-13"
+ * "gpt-4o-2024-08-06"
+ * "gpt-4o-2024-11-20"
+ * "gpt-4o-mini"
+ * "gpt-4o-mini-2024-07-18"
+ * "gpt-5"
+ * "gpt-5-2025-08-07"
+ * "gpt-5-chat"
+ * "gpt-5-chat-latest"
+ * "gpt-5-mini"
+ * "gpt-5-mini-2025-08-07"
+ * "gpt-5-nano"
+ * "gpt-5-nano-2025-08-07"
+ * "o1"
+ * "o1-2024-12-17"
+ * "o1-mini"
+ * "o1-mini-2024-09-12"
+ * "o1-pro"
+ * "o1-pro-2025-03-19"
+ * "o3"
+ * "o3-2025-04-16"
+ * "o3-deep-research"
+ * "o3-deep-research-2025-06-26"
+ * "o3-mini"
+ * "o3-mini-2025-01-31"
+ * "o3-pro"
+ * "o3-pro-2025-06-10"
+ * "o4-mini"
+ * "o4-mini-2025-04-16"
+ * "o4-mini-deep-research"
+ * "o4-mini-deep-research-2025-06-26"
  *
- * @example
- * ```typescript Array Schema
- * const arraySchema: JsonSchema = {
- *   type: "array",
- *   items: {
- *     type: "string"
- *   },
- *   minItems: 1,
- *   maxItems: 10,
- *   uniqueItems: true
- * };
- * ```
+ * **Supported Anthropic (Claude) Models:**
+ * "claude-3-5-haiku-20241022"
+ * "claude-3-5-haiku-latest"
+ * "claude-3-5-sonnet-20240620"
+ * "claude-3-5-sonnet-20241022"
+ * "claude-3-5-sonnet-latest"
+ * "claude-3-7-sonnet-20250219"
+ * "claude-3-7-sonnet-latest"
+ * "claude-3-haiku-20240307"
+ * "claude-4-opus-20250514"
+ * "claude-4-sonnet-20250514"
+ * "claude-opus-4-1"
+ * "claude-opus-4-1-20250805"
+ * "claude-opus-4-20250514"
+ * "claude-sonnet-4-20250514"
  *
- * @example
- * ```typescript Object Schema
- * const objectSchema: JsonSchema = {
- *   type: "object",
- *   properties: {
- *     name: { type: "string" },
- *     age: { type: "number", minimum: 0 },
- *     email: { type: "string", pattern: "^[^@]+@[^@]+\\.[^@]+$" }
- *   },
- *   required: ["name", "email"]
- * };
- * ```
+ * @type SUPPORTED_MODELS
  */
+export type SUPPORTED_MODELS =
+  | SUPPORTED_CLAUDE_MODELS
+  | SUPPORTED_OPENAI_MODELS;
 
 /**
  * Uses AI vision to determine if a webpage has finished loading by analyzing a screenshot.
  * Detects loading spinners, blank content, or incomplete page states.
+ *
  * @param {Object} input - Input object containing the page to check
  * @param {Page} input.page - The Playwright page to check
- * @param {number} [input.timeoutInMs=10000] - Screenshot timeout in milliseconds
- * @param {SUPPORTED_MODELS} [input.model="gpt-4o-2024-08-06"] - [SUPPORTED_MODELS](../type-aliases/SUPPORTED_MODELS) to use for the AI Check. default gpt-4o-2024-08-06
- * @param {string} [input.apiKey] - Optional API key for the AI service
- * @returns {Promise.<boolean>} True if page is loaded, false if still loading
+ * @param {number} [input.timeoutInMs=10000] - Screenshot timeout in milliseconds. Defaults to 10000
+ * @param {SUPPORTED_MODELS} [input.model="gpt-4o-2024-08-06"] - 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"
+ * @param {string} [input.apiKey] - Optional API key for the AI service (if provided, will not be billed to your account)
+ * @returns {Promise<boolean>} Promise resolving to true if page is loaded, false if still loading
  * @example
  * ```typescript Check Page Loading
  * import { isPageLoaded } from "@intuned/browser/ai";
@@ -465,9 +560,47 @@ export declare function isPageLoaded(input: {
   apiKey?: string;
 }): Promise<boolean>;
 
-export type JsonSchema =
-  | StringSchema
-  | NumberSchema
-  | BooleanSchema
-  | ArraySchema
-  | ObjectSchema;
+/**
+ * Represents text content for AI extraction.
+ * Used when passing text data directly to extractStructuredData without a page source.
+ *
+ * @interface TextContentItem
+ * @property {string} type - The type of the content item, which is always "text"
+ * @property {string} data - The text content to extract data from
+ */
+export interface TextContentItem {
+  type: "text";
+  data: string;
+}
+
+/**
+ * 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.
+ *
+ * @interface ImageBufferContentItem
+ * @property {string} type - The type of the content item, which is always "image-buffer"
+ * @property {string} image_type - The image format (e.g., "png", "jpeg", "gif", "webp")
+ * @property {Buffer} data - The Buffer containing the raw image data
+ */
+export interface ImageBufferContentItem {
+  type: "image-buffer";
+  image_type: "png" | "jpeg" | "gif" | "webp";
+  data: Buffer;
+}
+
+/**
+ * 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.
+ *
+ * @interface ImageUrlContentItem
+ * @property {string} type - The type of the content item, which is always "image-url"
+ * @property {string} image_type - The image format (e.g., "png", "jpeg", "gif", "webp")
+ * @property {string} data - The URL of the image to fetch and analyze
+ */
+export interface ImageUrlContentItem {
+  type: "image-url";
+  image_type: "png" | "jpeg" | "gif" | "webp";
+  data: string;
+}