Core verification manager and interfaces for KYC/KYB verification
npm install porkate-valid8Core verification manager, interfaces, events system, and exceptions for the Valid8 KYC/KYB verification framework.
📖 View Full API Documentation - Complete API reference with all classes, interfaces, and examples.
``bash`
npm install porkate-valid8or
yarn add porkate-valid8or
pnpm add porkate-valid8
- Verification Manager: Centralized management of multiple verification adapters
- Type-Safe Interfaces: Comprehensive TypeScript interfaces for all verification types
- Event System: Built-in event emitter for tracking verification lifecycle
- Exception Handling: Standardized exception types for error management
- Metrics Collection: Performance tracking and monitoring
- Event Logging: Comprehensive logging with customizable log levels
- Adapter Fallback: Automatic fallback to alternative adapters when primary fails
`typescript
import { VerificationManager } from 'porkate-valid8';
import { IdentityPassAdapter } from 'porkate-valid8-identitypass';
// Create verification manager
const manager = new VerificationManager({
defaultAdapter: 'identitypass',
enableFallback: true,
adapters: [
{
name: 'identitypass',
enabled: true,
priority: 1,
config: {
apiKey: process.env.IDENTITY_PASS_API_KEY,
},
},
],
});
// Register adapter factory
manager.registerFactory('identitypass', (config) => {
return new IdentityPassAdapter(config);
});
// Get adapter and verify
const adapter = manager.getDefaultAdapter();
const result = await adapter.verifyNIN({
nin: '12345678901',
firstName: 'John',
lastName: 'Doe',
});
console.log(result.success); // true/false
console.log(result.data); // Verification data
console.log(result.meta); // Original adapter response
`
`typescript
import { IdentityPassCompositeAdapter } from 'porkate-valid8-identitypass';
const adapter = new IdentityPassCompositeAdapter({
apiKey: process.env.IDENTITY_PASS_API_KEY,
});
// Get NIN verification service
const ninService = adapter.getNINService();
if (ninService) {
// Basic verification
const result = await ninService.verifyNIN({
nin: '12345678901',
firstName: 'John',
lastName: 'Doe',
});
// Advanced verification with face matching
if (ninService.verifyNINWithFace) {
const faceResult = await ninService.verifyNINWithFace({
nin: '12345678901',
firstName: 'John',
lastName: 'Doe',
image: 'base64-encoded-image',
});
}
}
`
The VerificationManager handles multiple adapters with fallback support:
`typescript
const manager = new VerificationManager({
defaultAdapter: 'identitypass',
enableFallback: true, // Enable automatic fallback
adapters: [
{ name: 'identitypass', enabled: true, priority: 1, config: {...} },
{ name: 'youverify', enabled: true, priority: 2, config: {...} },
],
});
// Get adapter with fallback
const adapter = manager.getAdapterWithFallback('identitypass');
`
All verification methods return a standardized response:
`typescript`
interface VerificationResponse
success: boolean; // Verification success status
data?: T; // Typed verification data
message?: string; // Human-readable message
error?: string; // Error message if failed
provider: string; // Adapter name
timestamp: Date; // Response timestamp
meta?: M; // Original adapter response
}
Track verification lifecycle with events:
`typescript
import { VerificationEventEmitter } from 'porkate-valid8';
const eventEmitter = new VerificationEventEmitter();
// Listen to verification events
eventEmitter.on('verification:started', (data) => {
console.log(Verification started: ${data.serviceType});
});
eventEmitter.on('verification:completed', (data) => {
console.log(Verification completed in ${data.duration}ms);
});
eventEmitter.on('verification:failed', (data) => {
console.error(Verification failed: ${data.error});`
});
Collect and analyze verification metrics:
`typescript
import { MetricsCollector } from 'porkate-valid8';
const metricsCollector = new MetricsCollector(eventEmitter);
// Get metrics
const metrics = metricsCollector.getMetrics();
console.log(metrics.totalVerifications);
console.log(metrics.successRate);
console.log(metrics.averageResponseTime);
// Get metrics by service type
const ninMetrics = metricsCollector.getMetricsByService('nin');
`
Log verification activities:
`typescript
import { EventLogger, LogLevel } from 'porkate-valid8';
const logger = new EventLogger(eventEmitter, {
logLevel: LogLevel.INFO,
logToConsole: true,
customLogger: (level, message, data) => {
// Custom logging implementation
myLogger.log(level, message, data);
},
});
`
The package provides 12 specialized service interfaces for different verification types:
typescript
interface ININVerificationService {
verifyNIN(data: NINVerificationRequest): Promise>;
verifyNINWithFace?(data: NINWithFaceVerificationRequest): Promise>;
verifyNINSlip?(data: NINSlipVerificationRequest): Promise>;
verifyVirtualNIN?(data: VirtualNINVerificationRequest): Promise>;
isReady(): boolean;
}
`$3
typescript
interface IBVNVerificationService {
verifyBVN(data: BVNVerificationRequest): Promise>;
verifyBVNAdvance?(data: BVNAdvanceVerificationRequest): Promise>;
verifyBVNWithFace?(data: BVNWithFaceVerificationRequest): Promise>;
getBVNByPhoneNumber?(data: BVNByPhoneNumberRequest): Promise>;
isReady(): boolean;
}
`$3
- - Company/CAC verification
- IDriversLicenseVerificationService - Driver's license verification
- IPassportVerificationService - International passport verification
- IPhoneVerificationService - Phone number verification
- IBankAccountVerificationService - Bank account verification
- IVehicleVerificationService - Vehicle/VIN verification
- ITaxVerificationService - TIN and stamp duty verification
- IVotersCardVerificationService - Voter's card verification
- ICreditBureauVerificationService - Credit bureau checks
- IOtherVerificationService - Miscellaneous verificationsException Handling
`typescript
import {
VerificationException,
VerificationFailedException,
VerificationConfigurationException,
AdapterNotFoundException,
NotImplementedException,
} from 'porkate-valid8';try {
const adapter = manager.getAdapter('unknown');
} catch (error) {
if (error instanceof AdapterNotFoundException) {
console.error('Adapter not found:', error.message);
console.log('Available adapters:', error.details.availableAdapters);
}
}
// Handle unsupported methods
const service = adapter.getSomeService();
if (!service) {
throw new NotImplementedException('Service not supported by this adapter');
}
`Configuration
$3
typescript
interface AdapterConfig {
name: string;
enabled?: boolean;
priority?: number;
config: T;
}
`$3
typescript
interface VerificationManagerConfig {
defaultAdapter?: string;
enableFallback?: boolean;
adapters: AdapterConfig[];
}
`Best Practices
1. Use Type-Safe Interfaces: Always use specific service interfaces instead of
2. Handle Fallback: Enable fallback for production environments
3. Monitor Events: Use event emitter to track verification lifecycle
4. Collect Metrics: Implement metrics collection for performance monitoring
5. Check Service Availability: Always check if a service exists before using it
6. Access Original Response: Use the field when you need the raw adapter response
7. Handle Errors Gracefully: Catch and handle exceptions appropriatelyTypeScript Support
This package is written in TypeScript and includes comprehensive type definitions:
`typescript
import type {
IVerificationAdapter,
ICompositeVerificationAdapter,
VerificationResponse,
NINVerificationRequest,
NINVerificationData,
// ... all other types
} from 'porkate-valid8';
`Testing
bash
Run tests
npm testRun tests in watch mode
npm run test:watchGenerate coverage report
npm run test:coverage
`Building
bash
Build the package
npm run buildWatch mode for development
npm run dev
``Contributions are welcome! Please follow these guidelines:
1. Write tests for new features
2. Ensure all tests pass
3. Follow the existing code style
4. Update documentation
MIT
- GitHub Issues: PorkAte-Valid8
- Documentation: See package README files and ARCHITECTURE.md
- porkate-valid8-identitypass - IdentityPass adapter
- porkate-valid8-dashboard - Monitoring dashboard
- porkate-valid8-nest - NestJS integration