@scanmama/sdk

Cloud document scanning API for web apps. No WASM, no build errors.

Install

npm install @scanmama/sdk

Usage

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

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

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

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

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:

{
  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

Documentation

Full documentation at scanmama.com/docs

License

MIT