ocr-ai 1.0.3 → 1.0.4

package/README.md

@@ -453,6 +453,126 @@ const ocr = new OcrAI({
 | Real-time applications | `gpt-4.1-nano` |
 | Budget-conscious projects | `gpt-4o-mini` |
 
+## Promise API
+
+For users who prefer callbacks or need more control over async operations, `ocr-ai` provides an alternative `OcrAIPromise` class with additional features.
+
+### Basic Usage with Callbacks
+
+```typescript
+import { OcrAIPromise } from 'ocr-ai';
+
+const ocr = new OcrAIPromise({
+  provider: 'gemini',
+  apiKey: 'YOUR_API_KEY',
+});
+
+// Using callback style
+ocr.extract('./invoice.png', {}, (error, result) => {
+  if (error) {
+    console.error('Extraction failed:', error.message);
+    return;
+  }
+  console.log('Extracted:', result.content);
+});
+```
+
+### Using .then()/.catch()
+
+```typescript
+import { OcrAIPromise } from 'ocr-ai';
+
+const ocr = new OcrAIPromise({
+  provider: 'gemini',
+  apiKey: 'YOUR_API_KEY',
+});
+
+// Promise chain style
+ocr.extract('./invoice.png')
+  .then((result) => {
+    if (result.success) {
+      console.log('Content:', result.content);
+    }
+  })
+  .catch((error) => {
+    console.error('Error:', error);
+  });
+```
+
+### Extract Multiple Files in Parallel
+
+```typescript
+const ocr = new OcrAIPromise({
+  provider: 'gemini',
+  apiKey: 'YOUR_API_KEY',
+});
+
+// Extract many files at once
+const results = await ocr.extractMany([
+  './invoice1.png',
+  './invoice2.png',
+  './invoice3.png',
+]);
+
+results.forEach((result, index) => {
+  if (result.success) {
+    console.log(`File ${index + 1}:`, result.content);
+  }
+});
+```
+
+### Batch Extraction with Individual Options
+
+```typescript
+const ocr = new OcrAIPromise({
+  provider: 'gemini',
+  apiKey: 'YOUR_API_KEY',
+});
+
+// Each file with its own options
+const results = await ocr.extractBatch([
+  { source: './invoice.png', options: { format: 'json', schema: invoiceSchema } },
+  { source: './receipt.png', options: { format: 'text' } },
+  { source: './contract.pdf', options: { prompt: 'Extract key dates and amounts' } },
+]);
+```
+
+### Automatic Retry on Failure
+
+```typescript
+const ocr = new OcrAIPromise({
+  provider: 'gemini',
+  apiKey: 'YOUR_API_KEY',
+});
+
+// Retry up to 3 times with 1 second delay between attempts
+const result = await ocr.extractWithRetry(
+  './invoice.png',
+  { format: 'json', schema: invoiceSchema },
+  3,    // retries
+  1000  // delay in ms
+);
+
+if (result.success) {
+  console.log('Extracted after retries:', result.data);
+}
+```
+
+### Access Underlying OcrAI Instance
+
+```typescript
+const ocrPromise = new OcrAIPromise({
+  provider: 'gemini',
+  apiKey: 'YOUR_API_KEY',
+});
+
+// Get the underlying OcrAI instance for direct access
+const ocr = ocrPromise.getOcrAI();
+
+// Use standard async/await if needed
+const result = await ocr.extract('./invoice.png');
+```
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -235,6 +235,79 @@ declare class OcrAI {
  * Factory function to create OcrAI instance
  */
 declare function createOcrAI(config: OcrConfig): OcrAI;
+/**
+ * Callback types for Promise-based API
+ */
+type ExtractionCallback<T = ExtractionResult> = (error: Error | null, result?: T) => void;
+/**
+ * Promise-based wrapper for OcrAI with callback support
+ * Provides an alternative async API for users who prefer callbacks or need more control over promise handling
+ */
+declare class OcrAIPromise {
+    private ocr;
+    constructor(config: OcrConfig);
+    /**
+     * Extract content from a file path or URL with callback support
+     * @param source - File path or URL
+     * @param options - Extraction options
+     * @param callback - Optional callback (error, result)
+     * @returns Promise if no callback provided
+     */
+    extract(source: string, options?: ExtractionOptions, callback?: ExtractionCallback): Promise<ExtractionResult> | void;
+    /**
+     * Extract content from a Buffer with callback support
+     */
+    extractFromBuffer(buffer: Buffer, fileName: string, options?: ExtractionOptions, callback?: ExtractionCallback): Promise<ExtractionResult> | void;
+    /**
+     * Extract content from a base64 string with callback support
+     */
+    extractFromBase64(base64: string, fileName: string, options?: ExtractionOptions, callback?: ExtractionCallback): Promise<ExtractionResult> | void;
+    /**
+     * Extract multiple files in parallel
+     * @param sources - Array of file paths or URLs
+     * @param options - Extraction options (applied to all)
+     * @returns Promise resolving to array of results
+     */
+    extractMany(sources: string[], options?: ExtractionOptions): Promise<ExtractionResult[]>;
+    /**
+     * Extract multiple files with individual options
+     * @param items - Array of { source, options } objects
+     * @returns Promise resolving to array of results
+     */
+    extractBatch(items: Array<{
+        source: string;
+        options?: ExtractionOptions;
+    }>): Promise<ExtractionResult[]>;
+    /**
+     * Extract with automatic retry on failure
+     * @param source - File path or URL
+     * @param options - Extraction options
+     * @param retries - Number of retries (default: 3)
+     * @param delayMs - Delay between retries in ms (default: 1000)
+     * @returns Promise resolving to extraction result
+     */
+    extractWithRetry(source: string, options?: ExtractionOptions, retries?: number, delayMs?: number): Promise<ExtractionResult>;
+    /**
+     * Get the underlying OcrAI instance
+     */
+    getOcrAI(): OcrAI;
+    /**
+     * Get current provider name
+     */
+    getProvider(): AIProvider;
+    /**
+     * Get current model
+     */
+    getModel(): string;
+    /**
+     * Change the AI provider
+     */
+    setProvider(provider: AIProvider, apiKey: string, model?: string): void;
+}
+/**
+ * Factory function to create OcrAIPromise instance
+ */
+declare function createOcrAIPromise(config: OcrConfig): OcrAIPromise;
 
 /**
  * Load a file from disk and prepare it for AI processing
@@ -360,4 +433,4 @@ declare class VertexProvider extends BaseProvider {
     private buildContents;
 }
 
-export { type AIProvider, BaseProvider, ClaudeProvider, type ExtractionError, type ExtractionMetadata, type ExtractionOptions, type ExtractionResult, type FileInfo, GeminiProvider, GrokProvider, type IAIProvider, type JsonExtractionResult, type ModelConfig, OcrAI, type OcrConfig, OpenAIProvider, type OutputFormat, type ProviderConfig, type SupportedFileType, type TextExtractionResult, type TokenUsage, type VertexConfig$1 as VertexConfig, VertexProvider, createOcrAI, getSupportedExtensions, isExtensionSupported, isUrl, loadFile, loadFileFromBase64, loadFileFromBuffer, loadFileFromUrl, saveToFile };
+export { type AIProvider, BaseProvider, ClaudeProvider, type ExtractionCallback, type ExtractionError, type ExtractionMetadata, type ExtractionOptions, type ExtractionResult, type FileInfo, GeminiProvider, GrokProvider, type IAIProvider, type JsonExtractionResult, type ModelConfig, OcrAI, OcrAIPromise, type OcrConfig, OpenAIProvider, type OutputFormat, type ProviderConfig, type SupportedFileType, type TextExtractionResult, type TokenUsage, type VertexConfig$1 as VertexConfig, VertexProvider, createOcrAI, createOcrAIPromise, getSupportedExtensions, isExtensionSupported, isUrl, loadFile, loadFileFromBase64, loadFileFromBuffer, loadFileFromUrl, saveToFile };

package/dist/index.d.ts

@@ -235,6 +235,79 @@ declare class OcrAI {
  * Factory function to create OcrAI instance
  */
 declare function createOcrAI(config: OcrConfig): OcrAI;
+/**
+ * Callback types for Promise-based API
+ */
+type ExtractionCallback<T = ExtractionResult> = (error: Error | null, result?: T) => void;
+/**
+ * Promise-based wrapper for OcrAI with callback support
+ * Provides an alternative async API for users who prefer callbacks or need more control over promise handling
+ */
+declare class OcrAIPromise {
+    private ocr;
+    constructor(config: OcrConfig);
+    /**
+     * Extract content from a file path or URL with callback support
+     * @param source - File path or URL
+     * @param options - Extraction options
+     * @param callback - Optional callback (error, result)
+     * @returns Promise if no callback provided
+     */
+    extract(source: string, options?: ExtractionOptions, callback?: ExtractionCallback): Promise<ExtractionResult> | void;
+    /**
+     * Extract content from a Buffer with callback support
+     */
+    extractFromBuffer(buffer: Buffer, fileName: string, options?: ExtractionOptions, callback?: ExtractionCallback): Promise<ExtractionResult> | void;
+    /**
+     * Extract content from a base64 string with callback support
+     */
+    extractFromBase64(base64: string, fileName: string, options?: ExtractionOptions, callback?: ExtractionCallback): Promise<ExtractionResult> | void;
+    /**
+     * Extract multiple files in parallel
+     * @param sources - Array of file paths or URLs
+     * @param options - Extraction options (applied to all)
+     * @returns Promise resolving to array of results
+     */
+    extractMany(sources: string[], options?: ExtractionOptions): Promise<ExtractionResult[]>;
+    /**
+     * Extract multiple files with individual options
+     * @param items - Array of { source, options } objects
+     * @returns Promise resolving to array of results
+     */
+    extractBatch(items: Array<{
+        source: string;
+        options?: ExtractionOptions;
+    }>): Promise<ExtractionResult[]>;
+    /**
+     * Extract with automatic retry on failure
+     * @param source - File path or URL
+     * @param options - Extraction options
+     * @param retries - Number of retries (default: 3)
+     * @param delayMs - Delay between retries in ms (default: 1000)
+     * @returns Promise resolving to extraction result
+     */
+    extractWithRetry(source: string, options?: ExtractionOptions, retries?: number, delayMs?: number): Promise<ExtractionResult>;
+    /**
+     * Get the underlying OcrAI instance
+     */
+    getOcrAI(): OcrAI;
+    /**
+     * Get current provider name
+     */
+    getProvider(): AIProvider;
+    /**
+     * Get current model
+     */
+    getModel(): string;
+    /**
+     * Change the AI provider
+     */
+    setProvider(provider: AIProvider, apiKey: string, model?: string): void;
+}
+/**
+ * Factory function to create OcrAIPromise instance
+ */
+declare function createOcrAIPromise(config: OcrConfig): OcrAIPromise;
 
 /**
  * Load a file from disk and prepare it for AI processing
@@ -360,4 +433,4 @@ declare class VertexProvider extends BaseProvider {
     private buildContents;
 }
 
-export { type AIProvider, BaseProvider, ClaudeProvider, type ExtractionError, type ExtractionMetadata, type ExtractionOptions, type ExtractionResult, type FileInfo, GeminiProvider, GrokProvider, type IAIProvider, type JsonExtractionResult, type ModelConfig, OcrAI, type OcrConfig, OpenAIProvider, type OutputFormat, type ProviderConfig, type SupportedFileType, type TextExtractionResult, type TokenUsage, type VertexConfig$1 as VertexConfig, VertexProvider, createOcrAI, getSupportedExtensions, isExtensionSupported, isUrl, loadFile, loadFileFromBase64, loadFileFromBuffer, loadFileFromUrl, saveToFile };
+export { type AIProvider, BaseProvider, ClaudeProvider, type ExtractionCallback, type ExtractionError, type ExtractionMetadata, type ExtractionOptions, type ExtractionResult, type FileInfo, GeminiProvider, GrokProvider, type IAIProvider, type JsonExtractionResult, type ModelConfig, OcrAI, OcrAIPromise, type OcrConfig, OpenAIProvider, type OutputFormat, type ProviderConfig, type SupportedFileType, type TextExtractionResult, type TokenUsage, type VertexConfig$1 as VertexConfig, VertexProvider, createOcrAI, createOcrAIPromise, getSupportedExtensions, isExtensionSupported, isUrl, loadFile, loadFileFromBase64, loadFileFromBuffer, loadFileFromUrl, saveToFile };

package/dist/index.js

@@ -990,15 +990,144 @@ var OcrAI = class {
 function createOcrAI(config) {
   return new OcrAI(config);
 }
+var OcrAIPromise = class {
+  ocr;
+  constructor(config) {
+    this.ocr = new OcrAI(config);
+  }
+  /**
+   * Extract content from a file path or URL with callback support
+   * @param source - File path or URL
+   * @param options - Extraction options
+   * @param callback - Optional callback (error, result)
+   * @returns Promise if no callback provided
+   */
+  extract(source, options, callback) {
+    const promise = this.ocr.extract(source, options);
+    if (callback) {
+      promise.then((result) => {
+        if (result.success) {
+          callback(null, result);
+        } else {
+          callback(new Error(result.error), result);
+        }
+      }).catch((error) => callback(error instanceof Error ? error : new Error(String(error))));
+      return;
+    }
+    return promise;
+  }
+  /**
+   * Extract content from a Buffer with callback support
+   */
+  extractFromBuffer(buffer, fileName, options, callback) {
+    const promise = this.ocr.extractFromBuffer(buffer, fileName, options);
+    if (callback) {
+      promise.then((result) => {
+        if (result.success) {
+          callback(null, result);
+        } else {
+          callback(new Error(result.error), result);
+        }
+      }).catch((error) => callback(error instanceof Error ? error : new Error(String(error))));
+      return;
+    }
+    return promise;
+  }
+  /**
+   * Extract content from a base64 string with callback support
+   */
+  extractFromBase64(base64, fileName, options, callback) {
+    const promise = this.ocr.extractFromBase64(base64, fileName, options);
+    if (callback) {
+      promise.then((result) => {
+        if (result.success) {
+          callback(null, result);
+        } else {
+          callback(new Error(result.error), result);
+        }
+      }).catch((error) => callback(error instanceof Error ? error : new Error(String(error))));
+      return;
+    }
+    return promise;
+  }
+  /**
+   * Extract multiple files in parallel
+   * @param sources - Array of file paths or URLs
+   * @param options - Extraction options (applied to all)
+   * @returns Promise resolving to array of results
+   */
+  extractMany(sources, options) {
+    return Promise.all(sources.map((source) => this.ocr.extract(source, options)));
+  }
+  /**
+   * Extract multiple files with individual options
+   * @param items - Array of { source, options } objects
+   * @returns Promise resolving to array of results
+   */
+  extractBatch(items) {
+    return Promise.all(items.map((item) => this.ocr.extract(item.source, item.options)));
+  }
+  /**
+   * Extract with automatic retry on failure
+   * @param source - File path or URL
+   * @param options - Extraction options
+   * @param retries - Number of retries (default: 3)
+   * @param delayMs - Delay between retries in ms (default: 1000)
+   * @returns Promise resolving to extraction result
+   */
+  async extractWithRetry(source, options, retries = 3, delayMs = 1e3) {
+    let lastResult;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      const result = await this.ocr.extract(source, options);
+      if (result.success) {
+        return result;
+      }
+      lastResult = result;
+      if (attempt < retries) {
+        await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+      }
+    }
+    return lastResult;
+  }
+  /**
+   * Get the underlying OcrAI instance
+   */
+  getOcrAI() {
+    return this.ocr;
+  }
+  /**
+   * Get current provider name
+   */
+  getProvider() {
+    return this.ocr.getProvider();
+  }
+  /**
+   * Get current model
+   */
+  getModel() {
+    return this.ocr.getModel();
+  }
+  /**
+   * Change the AI provider
+   */
+  setProvider(provider, apiKey, model) {
+    this.ocr.setProvider(provider, apiKey, model);
+  }
+};
+function createOcrAIPromise(config) {
+  return new OcrAIPromise(config);
+}
 
 exports.BaseProvider = BaseProvider;
 exports.ClaudeProvider = ClaudeProvider;
 exports.GeminiProvider = GeminiProvider;
 exports.GrokProvider = GrokProvider;
 exports.OcrAI = OcrAI;
+exports.OcrAIPromise = OcrAIPromise;
 exports.OpenAIProvider = OpenAIProvider;
 exports.VertexProvider = VertexProvider;
 exports.createOcrAI = createOcrAI;
+exports.createOcrAIPromise = createOcrAIPromise;
 exports.getSupportedExtensions = getSupportedExtensions;
 exports.isExtensionSupported = isExtensionSupported;
 exports.isUrl = isUrl;