MedCard API SDK

SDK for MedCard API - Insurance Card & Driver License Extraction.

Supports both production and development modes:

• Production mode (default): All endpoints make real API calls
• Development mode: Auth endpoints make real API calls, extraction endpoints return mock data (no processing costs)

Installation

npm install medcard-api-sdk
# or
yarn add medcard-api-sdk
# or
pnpm add medcard-api-sdk

Quick Start

Browser (Frontend)

import MedCardSDK from 'medcard-api-sdk';

// Initialize SDK
const sdk = new MedCardSDK({
  baseUrl: 'https://api.example.com', // Your API base URL
});

// Authorize and get sessionId and apiKey
const authResponse = await sdk.authorize({
  email: '[email protected]',
  password: 'YourSecurePassword123',
});

// Tokens are automatically set after authorize()
// Now you can use extract endpoints

// Extract from insurance card and driver license
const result = await sdk.extractAll({
  front: frontImageFile,
  back: backImageFile,
  dl: dlImageFile,
});

console.log(result.fields);

Node.js (Backend)

import MedCardSDK from 'medcard-api-sdk';
import fs from 'fs';

const sdk = new MedCardSDK({
  baseUrl: 'https://api.example.com',
});

// Authorize
await sdk.authorize({
  email: '[email protected]',
  password: 'YourSecurePassword123',
});

// Extract driver license
const fileBuffer = fs.readFileSync('dl.jpg');
const blob = new Blob([fileBuffer]);
const result = await sdk.extractDl(blob);

console.log(result.fields);

API Reference

Constructor

const sdk = new MedCardSDK(config?: MedCardSDKConfig);

Config Options:

• baseUrl (string, optional): API base URL. Default: https://api.example.com
• sessionId (string, optional): Session token (x-session-token)
• apiKey (string, optional): API key (x-api-key)
• timeout (number, optional): Request timeout in ms. Default: 60000
• mode ('prod' | 'dev', optional): SDK mode. Default: 'prod'
  • 'prod': All endpoints make real API calls
  • 'dev': Auth endpoints make real API calls, extraction returns mock data
• simulateDelay (boolean, optional): Simulate processing delay in dev mode. Default: true
• delayMs (number, optional): Processing delay in ms for dev mode extraction. Default: 2000

Authentication Methods

authorize(credentials: AuthorizeRequest): Promise<AuthorizeResponse>

Authenticate user and get sessionId and apiKey.

const response = await sdk.authorize({
  email: '[email protected]',
  password: 'YourSecurePassword123',
});

// Tokens are automatically set
console.log(response.sessionId);
console.log(response.apiKey);

refreshAccessToken(refreshToken: string): Promise<RefreshAccessTokenResponse>

Refresh access token using refresh token.

const response = await sdk.refreshAccessToken(refreshToken);
// Returns new accessToken

setAuth(sessionId: string, apiKey: string): void

Manually set both sessionId and API key.

sdk.setAuth(sessionId, apiKey);

setSessionId(sessionId: string): void

Set only session ID.

sdk.setSessionId(sessionId);

setApiKey(apiKey: string): void

Set only API key.

sdk.setApiKey(apiKey);

clearAuth(): void

Clear all authentication.

sdk.clearAuth();

Profile Methods

getProfile(): Promise<UserProfile>

Get user profile information.

const profile = await sdk.getProfile();
console.log(profile.apiKey);
console.log(profile.apiUsageCount);

Extract Methods

extractAll(files: ExtractAllRequest): Promise<ExtractAllResponse>

Extract structured data from insurance card (front and back) and driver license.

Note: Requires both sessionId and API key.

const result = await sdk.extractAll({
  front: frontImageFile,  // Optional
  back: backImageFile,    // Optional
  dl: dlImageFile,        // Optional
});

console.log(result.fields);

extractDl(file: File | Blob): Promise<ExtractDlResponse>

Extract driver license data.

Note: Requires both sessionId and API key.

const result = await sdk.extractDl(dlImageFile);
console.log(result.fields);
console.log(result.photoBox);

Error Handling

The SDK throws custom errors for better error handling:

import {
  AuthenticationError,
  ValidationError,
  RateLimitError,
  MedCardSDKError,
} from 'medcard-api-sdk';

try {
  await sdk.extractAll({ front: file });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Auth failed:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Validation error:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit:', error.message);
  } else if (error instanceof MedCardSDKError) {
    console.error('SDK error:', error.message, error.status);
  }
}

Complete Example

import MedCardSDK from 'medcard-api-sdk';

async function example() {
  // Initialize
  const sdk = new MedCardSDK({
    baseUrl: 'https://api.example.com',
  });

  try {
    // 1. Authorize
    const auth = await sdk.authorize({
      email: '[email protected]',
      password: 'YourSecurePassword123',
    });
    console.log('Authorized:', auth.user.email);

    // 2. Get profile
    const profile = await sdk.getProfile();
    console.log('Usage:', profile.apiUsageCount, '/', profile.apiUsageLimit);

    // 3. Extract from files
    const frontFile = document.getElementById('front-input').files[0];
    const backFile = document.getElementById('back-input').files[0];
    const dlFile = document.getElementById('dl-input').files[0];

    const result = await sdk.extractAll({
      front: frontFile,
      back: backFile,
      dl: dlFile,
    });

    console.log('Extracted fields:', result.fields);

  } catch (error) {
    console.error('Error:', error.message);
  }
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions. All types are exported:

import type {
  AuthorizeRequest,
  AuthorizeResponse,
  RefreshAccessTokenRequest,
  RefreshAccessTokenResponse,
  UserProfile,
  ExtractAllRequest,
  ExtractAllResponse,
  ExtractDlRequest,
  ExtractDlResponse,
  MedCardSDKConfig,
} from 'medcard-api-sdk';

Development Mode

Use development mode to test your integration without incurring API costs for extraction:

import MedCardSDK from 'medcard-api-sdk';

// Initialize SDK in dev mode
const sdk = new MedCardSDK({
  baseUrl: 'https://dev-api.example.com',
  mode: 'dev', // Enable dev mode
  simulateDelay: true, // Simulate processing delay (default: true)
  delayMs: 2000, // 2 second delay (default: 2000ms)
});

// Auth endpoints make REAL API calls (returns real sessionId/apiKey)
const auth = await sdk.authorize({
  email: '[email protected]',
  password: 'password123',
});
console.log('Real sessionId:', auth.sessionId);

// Extraction endpoints return MOCK data (no real processing)
const result = await sdk.extractAll({
  front: frontImageFile,
  back: backImageFile,
  dl: dlImageFile,
});
console.log('Mock extracted fields:', result.fields);

Dev Mode Behavior

• ✅ Authentication endpoints (authorize, refreshAccessToken, getProfile): Make real API calls
• ✅ Extraction endpoints (extractAll, extractDl): Return mock data (simulates processing delay)

This allows you to:

• Test authentication flow with real APIs
• Test extraction logic without API costs
• Develop and debug without processing real documents

Switching to Production

Simply change the mode:

// Development
const sdk = new MedCardSDK({
  baseUrl: 'https://dev-api.example.com',
  mode: 'dev',
});

// Production (just change mode, no other code changes needed)
const sdk = new MedCardSDK({
  baseUrl: 'https://api.example.com',
  mode: 'prod', // or omit (defaults to 'prod')
});

License

MIT