@creativecodelabs/ocr

@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