npm package: @scanmama/sdk
Description: Cloud document scanning API for web apps. No WASM, no build errors.
Author: ScanMama
Latest version: 1.4.2

# @scanmama/sdk

Cloud document scanning API for web apps. No WASM, no build errors.

## Install

```bash
npm install @scanmama/sdk
```

## Usage

```typescript
import { scanMama } from '@scanmama/sdk';

const result = await scanMama({
  apiKey: 'sm_live_xxx',
  file: fileInput.files[0],
});

console.log(result.pdfUrl);
```

## Features

- ✅ **Edge detection & perspective correction** - Automatically detects document edges
- ✅ **PDF output** - Converts scanned images to PDF
- ✅ **Works everywhere** - Next.js, React, Vue, vanilla JavaScript
- ✅ **No WASM** - Pure JavaScript, no WebAssembly build issues
- ✅ **Tiny bundle** - Under 3KB minified
- ✅ **TypeScript** - Full type safety included
- ✅ **Zero dependencies** - No runtime dependencies

## Examples

### Basic File Upload

```typescript
import { scanMama } from '@scanmama/sdk';

const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

const result = await scanMama({
  apiKey: 'sm_live_xxx',
  file
});

window.open(result.pdfUrl);
```

### With Options

```typescript
const result = await scanMama({
  apiKey: 'sm_live_xxx',
  file,
  outputFormat: 'pdf',      // 'pdf' | 'png' | 'jpeg'
  quality: 'high',          // 'draft' | 'standard' | 'high'
  colorMode: 'grayscale'    // 'color' | 'grayscale' | 'bw'
});
```

### Error Handling

```typescript
import { scanMama, ScanMamaError, ErrorCodes } from '@scanmama/sdk';

try {
  const result = await scanMama({
    apiKey: 'sm_live_xxx',
    file
  });
  console.log('Success:', result.pdfUrl);
} catch (error) {
  if (error instanceof ScanMamaError) {
    if (error.code === ErrorCodes.TRIAL_EXPIRED) {
      window.location.href = error.upgradeUrl;
    } else {
      console.error('Scan failed:', error.message);
    }
  }
}
```

### Usage Tracking

```typescript
const result = await scanMama({
  apiKey: 'sm_live_xxx',
  file
});

console.log(`Used ${result.usage.scansUsedThisPeriod} of ${result.usage.scansIncluded} scans`);

if (result.usage.isOverage) {
  console.log('This scan was charged as overage');
}
```

## API Reference

### `scanMama(options)`

Process a document scan.

**Options:**
- `apiKey` (string, required) - Your ScanMama API key
- `file` (File | Blob, required) - Image to process
- `outputFormat` (string, optional) - Output format: `'pdf'` | `'png'` | `'jpeg'` (default: `'pdf'`)
- `quality` (string, optional) - Processing quality: `'draft'` | `'standard'` | `'high'` (default: `'standard'`)
- `colorMode` (string, optional) - Color mode: `'color'` | `'grayscale'` | `'bw'` (default: `'color'`)

**Returns:** `Promise<ScanResult>`

**ScanResult:**
```typescript
{
  scanId: string;
  pdfUrl: string;           // Signed URL, expires in 1 hour
  imageUrl: string;         // Processed image URL
  originalUrl: string;      // Original image URL
  width: number;            // Document width in pixels
  height: number;           // Document height in pixels
  processingTimeMs: number; // Server processing time
  documentDetected: boolean;// Was a document found?
  usage: UsageInfo;         // Usage information
}
```

## Error Codes

- `INVALID_API_KEY` - API key is invalid or missing
- `TRIAL_EXPIRED` - Free trial has been used up
- `RATE_LIMIT_EXCEEDED` - Too many requests
- `INVALID_IMAGE` - Image file is invalid
- `FILE_TOO_LARGE` - File exceeds 10MB limit
- `PROCESSING_FAILED` - Server processing error
- `NETWORK_ERROR` - Network connection issue
- `SERVER_ERROR` - Temporary server error

## Get API Key

Sign up at [scanmama.com](https://scanmama.com)

## Documentation

Full documentation at [scanmama.com/docs](https://scanmama.com/docs)

## License

MIT