# natscan

**Offline OCR pipeline for React Native/Expo receipt scanning** with multilingual support (Simplified Chinese, Traditional Chinese, and English) using Google ML Kit.

## Features

- ✅ **Offline Processing** - No internet connection required
- ✅ **React Native 0.81 & Expo SDK 54+ Compatible** - Works seamlessly with latest versions
- ✅ **Multilingual Support** - English, Simplified Chinese, Traditional Chinese
- ✅ **Automatic Language Detection** - Detects receipt language automatically
- ✅ **Native Performance** - Uses Google ML Kit for fast, on-device OCR
- ✅ **Structured Data Extraction** - Extracts 7 key fields from receipts plus raw OCR text
- ✅ **TypeScript Support** - Full type definitions included
- ✅ **Cross-Platform** - Works on both iOS and Android

## Installation

```bash
npm install natscan
```

**That's it!** ML Kit will be installed automatically as a dependency.

### iOS Setup

```bash
cd ios && pod install && cd ..
```

## Quick Start

```typescript
import { processReceipt } from "natscan";

// Process a receipt image
const result = await processReceipt("path/to/receipt.jpg");

console.log(result);
// {
//   receiptno: "INV-123456",
//   shopname: "ABC Supermarket",
//   date: "2025-12-19",
//   time: "14:30",
//   netAmount: 45.5,
//   grossAmount: 50.0,
//   totalItems: 5,
//   rawInput: "Full OCR text..."
// }
```

## Response Format

The pipeline returns a `ReceiptScanResponse` object with the following structure:

```typescript
{
  receiptno: string; // Receipt/invoice number
  shopname: string; // Store/shop name
  date: string; // Date in ISO format (YYYY-MM-DD)
  time: string; // Time in 24-hour format (HH:MM)
  netAmount: number; // Net amount (before tax)
  grossAmount: number; // Gross amount (total including tax)
  totalItems: number; // Total number of items purchased
  rawInput: string; // Raw OCR text extracted from the image
}
```

## Usage Examples

### Basic Usage

```typescript
import { processReceipt } from "natscan";

const result = await processReceipt("./receipt.jpg");
console.log("Shop:", result.shopname);
console.log("Total:", result.grossAmount);
```

### Advanced Usage

```typescript
import { OCRPipeline } from "natscan";

const pipeline = new OCRPipeline({
  languages: ["eng", "chi_sim", "chi_tra"],
  preprocessingLevel: "high",
  confidenceThreshold: 0.7,
  debug: true,
});

// Process single receipt
const result = await pipeline.processReceipt("receipt.jpg");

// Process multiple receipts
const results = await pipeline.processBatch([
  "receipt1.jpg",
  "receipt2.jpg",
  "receipt3.jpg",
]);

// Clean up resources
await pipeline.cleanup();
```

## Configuration

### Default Configuration

```typescript
{
  languages: ['eng', 'chi_sim', 'chi_tra'],
  preprocessingLevel: 'medium',
  confidenceThreshold: 0.6,
  debug: false,
}
```

### Configuration Options

```typescript
interface OCRConfig {
  languages: ("chi_sim" | "chi_tra" | "eng")[];
  preprocessingLevel: "low" | "medium" | "high";
  confidenceThreshold: number; // 0-1
  debug?: boolean;
}
```

## Supported Languages

- **English** (`eng`) - US, UK, international formats
- **Simplified Chinese** (`chi_sim`) - Mainland China formats
- **Traditional Chinese** (`chi_tra`) - Taiwan, Hong Kong formats

## Supported Image Formats

- JPEG (`.jpg`, `.jpeg`)
- PNG (`.png`)
- WebP (`.webp`)
- TIFF (`.tiff`, `.tif`)

## Requirements

- **React Native** >= 0.81.0 (tested with 0.81)
- **Expo SDK** >= 50.0.0 (tested with SDK 54)
- **Node.js** >= 18.0.0
- **iOS** >= 15.5 (required by ML Kit)
- **Android** >= API 21 (Android 5.0)



## Documentation

For detailed documentation, please refer to the [docs](./docs/) folder:

- **[Getting Started](./docs/getting-started.md)** - Quick start guide and basic usage
- **[API Reference](./docs/api-reference.md)** - Complete API documentation
- **[Response Format](./docs/response-format.md)** - Detailed response structure and examples
- **[React Native & Expo](./docs/react-native.md)** - React Native/Expo specific guide
- **[Best Practices](./docs/best-practices.md)** - Tips for optimal results
- **[Troubleshooting](./docs/troubleshooting.md)** - Common issues and solutions

## Development

### Build

```bash
npm run build
```

### Test

```bash
# Interactive test script
npm run test:local

# Unit tests
npm test
```

### Development Mode

```bash
npm run dev
```

## Performance

- **Average processing time**: 2-5 seconds per receipt
- **Accuracy**: 85-95% on clear, well-lit receipts
- **Image requirements**:
  - Minimum width: 800px
  - Supported formats: JPG, PNG, WEBP, TIFF
  - Recommended: Good lighting, minimal blur

## License

MIT

## Support

For issues and questions, please refer to the [Troubleshooting](./docs/troubleshooting.md) guide or open an issue on the repository.