@ccl/ocr

OCR module for document scanning - receipts, invoices, and expense documents using Mindee.

Installation

npm install @ccl/ocr

Setup

Initialize the OCR client with your Mindee API key:

import { initOcrClient } from '@ccl/ocr';

initOcrClient({
  apiKey: process.env.MINDEE_API_KEY,
  // Optional: custom model IDs
  receiptModelId: 'your-custom-receipt-model',
  invoiceModelId: 'your-custom-invoice-model',
});

Usage

Scanning Receipts

import { scanReceiptFromUrl, scanReceiptFromBase64, isReceiptValid } from '@ccl/ocr';

// From URL
const result = await scanReceiptFromUrl('https://example.com/receipt.jpg');

// From base64
const result = await scanReceiptFromBase64(base64String, 'receipt.jpg');

// Check validity
if (isReceiptValid(result)) {
  console.log('Merchant:', result.merchantName);
  console.log('Total:', result.totalAmount, result.currency);
  console.log('Date:', result.transactionDate);
}

Scanning Invoices

import { scanInvoiceFromUrl, scanInvoiceFromBase64, isInvoiceValid } from '@ccl/ocr';

// From URL
const result = await scanInvoiceFromUrl('https://example.com/invoice.pdf');

// From base64
const result = await scanInvoiceFromBase64(base64String, 'invoice.pdf');

// Check validity
if (isInvoiceValid(result)) {
  console.log('Vendor:', result.vendorName);
  console.log('Invoice #:', result.invoiceNumber);
  console.log('Total:', result.totalAmount);
  console.log('Due Date:', result.dueDate);
  console.log('Line Items:', result.lineItems);
}

API Reference

Receipt Fields

| Field | Type | Description | |-------|------|-------------| | merchantName | string \| null | Store/merchant name | | merchantAddress | string \| null | Merchant address | | transactionDate | string \| null | Date (ISO format) | | totalAmount | string \| null | Total amount | | taxAmount | string \| null | Tax/VAT amount | | currency | string \| null | Currency code (USD, EUR, ZAR) | | paymentMethod | string \| null | Payment method if detected | | lineItems | ReceiptLineItem[] | Individual items | | confidence | object | Confidence scores (0-1) |

Invoice Fields

| Field | Type | Description | |-------|------|-------------| | vendorName | string \| null | Vendor/supplier name | | vendorAddress | string \| null | Vendor address | | customerName | string \| null | Customer/bill-to name | | customerAddress | string \| null | Customer address | | invoiceNumber | string \| null | Invoice number | | invoiceDate | string \| null | Invoice date | | dueDate | string \| null | Payment due date | | totalAmount | string \| null | Total amount | | subtotal | string \| null | Subtotal before tax | | taxAmount | string \| null | Tax amount | | currency | string \| null | Currency code | | poNumber | string \| null | Purchase order number | | lineItems | InvoiceLineItem[] | Line items | | confidence | object | Confidence scores (0-1) |

Error Handling

import { OcrError } from '@ccl/ocr';

try {
  const result = await scanReceiptFromUrl(url);
} catch (error) {
  if (error instanceof OcrError) {
    switch (error.code) {
      case 'NOT_CONFIGURED':
        // Client not initialized
        break;
      case 'AUTH_ERROR':
        // Invalid API key
        break;
      case 'RATE_LIMIT':
        // Rate limit exceeded
        break;
      case 'INVALID_INPUT':
        // Bad input (corrupt image, etc.)
        break;
      case 'API_ERROR':
        // General API error
        break;
    }
  }
}

License

MIT