@scwar/nestjs-smile-identity-core

A comprehensive NestJS module for integrating with the Smile Identity API. This package provides a complete wrapper around all Smile Identity API endpoints with robust error handling, retries, and TypeScript support.

Features

• 🚀 Complete API Coverage: All Smile Identity API endpoints implemented
• 🔄 Automatic Retries: Built-in retry mechanism with exponential backoff
• 🛡️ Robust Error Handling: Comprehensive error handling with detailed error messages
• 📝 TypeScript Support: Full type definitions for all API requests and responses
• 🔐 Signature Management: Built-in signature generation and verification
• 🧪 Comprehensive Testing: Extensive test coverage for all endpoints
• ⚡ Performance: Uses native fetch API for optimal performance
• 🔧 Configurable: Easy configuration through NestJS module options

Installation

npm install @scwar/nestjs-smile-identity-core

Quick Start

1. Import the module

import { SmileIdentityModule } from '@scwar/nestjs-smile-identity-core';

@Module({
  imports: [
    SmileIdentityModule.forRoot({
      partnerId: 'your-smile-identity-partner-id',
      apiKey: 'your-smile-identity-api-key',
      baseUrl: 'https://api.smileidentity.com/v1',
      timeout: 30000,
      retries: 3,
    }),
  ],
})
export class AppModule {}

2. Inject and use the service

import { SmileIdentityService } from '@scwar/nestjs-smile-identity-core';
import { JobType } from '@scwar/nestjs-smile-identity-core';

@Injectable()
export class VerificationService {
  constructor(private readonly smileIdentityService: SmileIdentityService) {}

  async submitKyc(userId: string, jobId: string, imageBase64: string) {
    return this.smileIdentityService.webApi.submitJob({
      userId,
      jobId,
      jobType: JobType.BIOMETRIC_KYC,
      imageDetails: [
        {
          image_type_id: 0,
          image: imageBase64,
        },
      ],
      callbackUrl: 'https://your-domain.com/callback',
    });
  }
}

Configuration Options

interface SmileIdentityModuleOptions {
  partnerId: string;
  apiKey: string;
  defaultCallback?: string;
  baseUrl?: string;
  timeout?: number;
  retries?: number;
  retryDelay?: number;
  maxRetryDelay?: number;
}

Available Services

WebApi Service

The WebApi service handles jobs that require images:

• submitJob: Submit jobs for Biometric KYC, Document Verification, SmartSelfie™ Authentication
• getJobStatus: Retrieve job status and results
• getWebToken: Generate web token for Hosted Web Integration

IDApi Service

The IDApi service handles ID verification jobs:

• submitEnhancedKyc: Submit Enhanced KYC job
• submitBasicKyc: Submit Basic KYC job
• submitBusinessVerification: Submit Business Verification job
• submitJob: Generic job submission (alias for submitEnhancedKyc)

Signature Service

The Signature service handles cryptographic operations:

• generateSignature: Generate cryptographic signature for API requests
• confirmSignature: Validate signatures from API responses

Utilities Service

The Utilities service provides utility functions:

• getJobStatus: Get job status with automatic signature verification

Usage Examples

Biometric KYC

const response = await this.smileIdentityService.webApi.submitJob({
  userId: 'user-123',
  jobId: 'job-456',
  jobType: JobType.BIOMETRIC_KYC,
  imageDetails: [
    {
      image_type_id: 0, // Selfie
      image: base64EncodedImage,
    },
  ],
  callbackUrl: 'https://your-domain.com/callback',
});

Enhanced KYC

const response = await this.smileIdentityService.idApi.submitEnhancedKyc({
  userId: 'user-123',
  jobId: 'job-456',
  idInfo: {
    first_name: 'John',
    last_name: 'Doe',
    country: 'NG',
    id_type: 1, // National ID
    id_number: '12345678901',
    dob: '1990-01-01',
  },
});

Get Job Status

const status = await this.smileIdentityService.webApi.getJobStatus('user-123', 'job-456', {
  imageLinks: true,
  history: true,
});

Generate Signature

const { signature, timestamp } = this.smileIdentityService.signature.generateSignature(
  partnerId,
  apiKey,
);

Get Web Token

const token = await this.smileIdentityService.webApi.getWebToken(
  'user-123',
  'job-456',
  'biometric_kyc',
  'https://your-domain.com/callback',
);

Error Handling

The package provides comprehensive error handling with detailed error messages:

try {
  const result = await this.smileIdentityService.webApi.submitJob(data);
} catch (error) {
  if (error instanceof SmileIdentityError) {
    console.log('Smile Identity Error:', error.message);
    console.log('Error Code:', error.code);
    console.log('HTTP Status:', error.status);
  }
}

Retry Mechanism

Automatic retries with exponential backoff for failed requests:

// Configure retries in module options
SmileIdentityModule.forRoot({
  partnerId: 'your-partner-id',
  apiKey: 'your-api-key',
  retries: 3,           // Number of retry attempts
  retryDelay: 1000,     // Initial delay in ms
  maxRetryDelay: 10000, // Maximum delay in ms
})

Job Types

The package includes the following job types:

• BIOMETRIC_KYC (1): Biometric KYC verification
• SMART_SELFIE_AUTH (2): SmartSelfie™ Authentication
• SMART_SELFIE_REGISTRATION (4): SmartSelfie™ Registration
• DOCUMENT_VERIFICATION (5): Document Verification
• ENHANCED_KYC (5): Enhanced KYC
• BASIC_KYC (5): Basic KYC
• BUSINESS_VERIFICATION (5): Business Verification

ID Types

Supported ID types for document verification:

• NATIONAL_ID (1): National ID
• PASSPORT (2): Passport
• DRIVERS_LICENSE (3): Driver's License
• VOTERS_ID (4): Voter's ID

Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:cov

Version Management & Releases

This package includes an automated version bumping system that follows semantic versioning and conventional commits.

Automatic Version Bumping

The system automatically determines the appropriate version bump based on your commits:

# Automatically determine and bump version
npm run version:auto

# Manual version bumps
npm run version:patch  # 1.0.0 → 1.0.1
npm run version:minor  # 1.0.0 → 1.1.0
npm run version:major  # 1.0.0 → 2.0.0

Conventional Commits

All commits must follow the Conventional Commits specification:

# Feature commits (minor version bump)
git commit -m "feat: add new verification method"

# Bug fix commits (patch version bump)
git commit -m "fix: resolve authentication issue"

# Breaking change commits (major version bump)
git commit -m "feat!: breaking change in API"

# Documentation commits (no version bump)
git commit -m "docs: update README with examples"

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes using conventional commit format
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Important: All commits must follow the conventional commit format to ensure proper version bumping.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please open an issue on GitHub or contact the maintainers.

Changelog

See CHANGELOG.md for a list of changes and version history.