@dydydm/ekyc-sdk

JavaScript/TypeScript SDK for eKYC verification — OCR, Liveness Detection, and Face Match.

Installation

npm install @dydydm/ekyc-sdk

Quick Start

Initialize the client

import { EkycClient } from '@dydydm/ekyc-sdk';

const client = new EkycClient({
  baseUrl: 'https://your-api-url.com/ekyc',
  apiKey: 'your-api-key',
});

Full verification (one call)

The simplest way — one call does everything (create session → upload → OCR → liveness → face match):

const result = await client.verify({
  idFront: idFrontFile,   // File or Blob — front of ID card
  idBack: idBackFile,     // File or Blob — back of ID card (optional)
  selfie: selfieFile,     // File or Blob — selfie photo
  livenessFrames: [       // Optional — for liveness detection
    { file: frame1, action: 'center' },
    { file: frame2, action: 'turn_left' },
  ],
  onStep: (step, detail) => console.log(step, detail),
});

console.log(result.ocr.passed);       // ID card text extracted?
console.log(result.liveness?.passed); // Real person?
console.log(result.faceMatch.passed); // Face matched?
console.log(result.ocr.data);         // Extracted ID info (name, DOB, etc.)

Step-by-Step Usage

For more control, use each step manually.

1. Create a session

const deviceContext = EkycClient.detectDevice(); // auto-detect browser info
const session = await client.session.create({ deviceContext });
const { sessionId } = session;

2. Upload files

// Upload ID front (required)
const front = await client.artifact.upload(sessionId, idFrontFile, 'ID_FRONT');

// Upload ID back (optional)
const back = await client.artifact.upload(sessionId, idBackFile, 'ID_BACK');

// Upload selfie
const selfie = await client.artifact.upload(sessionId, selfieFile, 'SELFIE');

Upload with progress callback:

const result = await client.artifact.upload(sessionId, file, 'ID_FRONT', {
  onProgress: (p) => console.log(`${p.percent}%`),
});

3. Run OCR

const ocr = await client.task.ocr(sessionId, { ocrEngine: 'surya' });

console.log(ocr.passed);  // true / false
console.log(ocr.data);    // { idNumber, name, dateOfBirth, sex, nationality, ... }

4. Liveness Detection

Per-frame liveness — check each frame individually:

// Upload selfie frame with action metadata
const frame = await client.artifact.upload(sessionId, frameBlob, 'SELFIE', {
  action: 'center',
});

// Check liveness for this frame
const lv = await client.task.liveness(sessionId, frame.artifactId, 'center');
console.log(lv.passed);    // true / false
console.log(lv.decision);  // "real" or "spoofed"
console.log(lv.score);     // confidence score

Batch liveness — check all uploaded SELFIE frames at once:

const lvBatch = await client.task.livenessBatch(sessionId);
console.log(lvBatch.passed);

Supported actions:

| Action | Description | |---|---| | center | Look straight at the camera | | blink | Blink your eyes | | turn_left | Turn head to the left | | turn_right | Turn head to the right | | smile | Smile | | nod | Nod your head |

5. Face Match

const faceMatch = await client.task.faceMatch(sessionId);

console.log(faceMatch.passed);  // true / false
console.log(faceMatch.data);    // { verified, cosineSimilarity, similarityPercentage, ... }

6. Get all results

const { data } = await client.task.getResults(sessionId);
data.forEach(r => console.log(r.taskType, r.passed));

Configuration

const client = new EkycClient({
  baseUrl: 'https://your-api-url.com/ekyc',  // Required
  apiKey: 'your-api-key',                     // Required
  timeout: 30000,                             // Request timeout in ms (default: 30000)
  debug: false,                               // Enable debug logging (default: false)
  retry: {                                    // Retry config (optional)
    maxRetries: 3,
    backoff: 'exponential',                   // 'fixed' | 'exponential'
  },
  onEvent: (event) => {                       // Listen to SDK events (optional)
    console.log(event.type, event.data);
  },
});

Event types

| Event | Description | |---|---| | session.creating / session.created | Session lifecycle | | upload.start / upload.done / upload.failed | Upload lifecycle | | task.start / task.done / task.failed | Task lifecycle | | verify.start / verify.step / verify.done / verify.failed | Full verify flow |

Error Handling

import { EkycError } from '@dydydm/ekyc-sdk';

try {
  const result = await client.verify({ idFront, selfie });
} catch (err) {
  if (err instanceof EkycError) {
    console.error(err.message);     // Error message
    console.error(err.statusCode);  // HTTP status code
    console.error(err.code);        // Error code (optional)
  }
}

TypeScript

All types are exported:

import type {
  EkycConfig,
  Session,
  TaskResult,
  OcrData,
  LivenessData,
  FaceMatchData,
  UploadResult,
  LivenessAction,
  DeviceContext,
} from '@dydydm/ekyc-sdk';

License

MIT