@docscanner/sdk

Official Node.js/TypeScript SDK for DocScanner.io - AI-powered document analysis API.

Installation

npm install @docscanner/sdk

Or using yarn:

yarn add @docscanner/sdk

Quick Start

import { FileAnalyzerClient } from '@docscanner/sdk';

// Initialize the client with your API key
const client = new FileAnalyzerClient({
  apiKey: process.env.FILE_ANALYZER_API_KEY!,
});

// Extract data from a document
const result = await client.extract({
  file: './invoice.pdf',
  prompt: 'Extract invoice number, date, and total amount',
});

console.log(result);
// {
//   id: '123',
//   status: 'completed',
//   result: {
//     invoice_number: 'INV-2024-001',
//     date: '2024-11-25',
//     total_amount: 2376.00
//   }
// }

Configuration

const client = new FileAnalyzerClient({
  // Required: Your API key (format: sk_live_...)
  apiKey: 'sk_live_your_api_key_here',

  // Optional: API base URL (default: https://api.docscanner.io)
  baseUrl: 'https://api.docscanner.io',

  // Optional: Request timeout in ms (default: 120000)
  timeout: 120000,

  // Optional: Max retries for failed requests (default: 3)
  maxRetries: 3,

  // Optional: Polling interval when waiting for jobs (default: 2000)
  pollingInterval: 2000,
});

API Key

To use this SDK, you need an API key from DocScanner.io:

1. Sign up at docscanner.io
2. Subscribe to a paid plan (Starter or higher)
3. Generate an API key in your dashboard under Settings > API Keys

Important: Keep your API key secure and never commit it to version control.

// Recommended: Load from environment variable
const apiKey = process.env.FILE_ANALYZER_API_KEY;

Usage Examples

Basic Extraction

const result = await client.extract({
  file: './invoice.pdf',
  prompt: 'Extract invoice number, customer name, and line items',
});

console.log(result.result);

Extract from Buffer

import * as fs from 'fs';

const fileBuffer = fs.readFileSync('./invoice.pdf');

const result = await client.extract({
  file: fileBuffer,
  filename: 'invoice.pdf',
  prompt: 'Extract all invoice details',
});

Async Mode (Fire and Forget)

// Submit job without waiting for completion
const job = await client.extract({
  file: './document.pdf',
  prompt: 'Extract data',
  async: true,
});

console.log(`Job submitted: ${job.id}`);

// Check status later
const status = await client.getJob(job.id);
console.log(status.status); // 'pending' | 'processing' | 'completed' | 'failed'

With Webhook

const result = await client.extract({
  file: './invoice.pdf',
  prompt: 'Extract invoice data',
  webhookUrl: 'https://your-app.com/webhook',
  async: true,
});

// Your webhook will receive a POST when the job completes

Check Credit Balance

const credits = await client.getCredits();

console.log(`Total balance: ${credits.balance.totalBalance}`);
console.log(`Monthly credits: ${credits.balance.monthlyCredits}`);
console.log(`Purchased credits: ${credits.balance.purchasedCredits}`);

Error Handling

The SDK provides typed error classes for different failure scenarios:

import {
  FileAnalyzerClient,
  AuthenticationError,
  InsufficientCreditsError,
  RateLimitError,
  ValidationError,
  NotFoundError,
  JobProcessingError,
  TimeoutError,
  NetworkError,
} from '@docscanner/sdk';

try {
  const result = await client.extract({
    file: './document.pdf',
    prompt: 'Extract data',
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof InsufficientCreditsError) {
    console.error(`Need ${error.required} credits, have ${error.currentBalance}`);
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof ValidationError) {
    console.error('Invalid request:', error.message);
  } else if (error instanceof TimeoutError) {
    console.error(`Request timed out after ${error.timeoutMs}ms`);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  }
}

API Reference

FileAnalyzerClient

Constructor

new FileAnalyzerClient(config: FileAnalyzerConfig)

Methods

| Method | Description | |--------|-------------| | extract(options) | Extract data from a document | | getJob(jobId) | Get job status and result | | waitForJob(jobId, maxWaitTime?) | Wait for a job to complete | | getCredits() | Get credit balance information | | listAPIKeys() | List all active API keys | | createAPIKey(name, scopes?) | Create a new API key | | revokeAPIKey(keyId) | Revoke an API key |

Types

interface ExtractOptions {
  file: string | Buffer | ReadStream;
  filename?: string;
  prompt: string;
  webhookUrl?: string;
  maxWaitTime?: number;
  async?: boolean;
}

interface JobResult {
  id: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  result?: Record<string, unknown>;
  usage?: { creditsCost: number };
  error?: string;
}

interface CreditBalance {
  balance: {
    totalBalance: number;
    monthlyCredits: number;
    purchasedCredits: number;
    reservedCredits: number;
  };
  monthlyAllowance: number;
  tier: string;
  recentTransactions: CreditTransaction[];
}

TypeScript Support

This SDK is written in TypeScript and provides full type definitions out of the box.

import type {
  FileAnalyzerConfig,
  ExtractOptions,
  JobResult,
  CreditBalance,
} from '@docscanner/sdk';

Requirements

• Node.js >= 16.0.0
• TypeScript >= 4.7.0 (optional, for TypeScript users)

Support

• Documentation: docscanner.io/docs
• Issues: GitHub Issues
• Email: [email protected]

License

MIT