VECU IDV Web SDK

A secure, TypeScript-first identity verification SDK that provides a unified interface for multiple identity verification providers. Built with security in mind, featuring hidden API keys and a clean, simple API.

Features

• 🔐 Secure by Design: API keys are hidden from network inspection
• 🔌 Provider Agnostic: Support for multiple IDV providers (Socure, Jumio, Onfido, etc.)
• 🚀 Lazy Loading: Providers loaded on-demand for optimal performance
• 📦 Multiple Formats: Available as UMD, ESM, and CommonJS
• 🎯 TypeScript First: Full type safety with comprehensive definitions
• 🌐 Framework Agnostic: Works with React, Vue, Angular, or vanilla JS
• 📱 Mobile Ready: QR code handoff for mobile verification flows
• 🔄 Event-Driven: Comprehensive event system for real-time updates

Installation

npm install @vecu/idv-web-sdk
# or
yarn add @vecu/idv-web-sdk
# or
pnpm add @vecu/idv-web-sdk

Quick Start

Browser (UMD Bundle)

<script src="https://unpkg.com/@vecu/idv-web-sdk/dist/vecu-idv-sdk.bundle.min.js"></script>
<script>
  // SDK is available as window.VecuIDVSDK
  VecuIDVSDK.launch(
    'your-sdk-key',
    'transaction-token',
    '#verification-container',
    {
      onSuccess: (result) => {
        console.log('Verification completed!', result);
      },
      onError: (error) => {
        console.error('Verification failed:', error);
      }
    }
  );
</script>

ES Modules / TypeScript

import { createVecuIDVSDK } from '@vecu/idv-web-sdk';

// Create SDK instance with your API key
const sdk = createVecuIDVSDK('your-sdk-key', {
  apiUrl: 'https://api.vecu.com',
  debug: true
});

// Launch verification
const cleanup = await sdk.launch(
  'transaction-token',
  document.getElementById('verification-container'),
  {
    provider: 'socure',
    mode: 'embedded',
    onProgress: (event) => {
      console.log(`Progress: ${event.step} (${event.percentage}%)`);
    },
    onSuccess: (result) => {
      console.log('Verification completed!', result);
    },
    onError: (error) => {
      console.error('Verification failed:', error);
    }
  }
);

// Cleanup when done
cleanup();

API Reference

Global SDK (Browser)

window.VecuIDVSDK.launch(
  sdkKey: string,
  transactionToken: string,
  containerSelector: string | HTMLElement,
  options?: LaunchOptions
): Promise<() => void>

Factory Function

createVecuIDVSDK(sdkKey: string, config?: SDKConfig): VecuIDVSDK

SDKConfig

interface SDKConfig {
  apiUrl?: string;        // API endpoint (default: 'https://api.vecu.com')
  timeout?: number;       // Request timeout in ms (default: 30000)
  maxRetries?: number;    // Max retry attempts (default: 3)
  logLevel?: 'debug' | 'info' | 'warn' | 'error';
  debug?: boolean;        // Enable debug mode
}

LaunchOptions

interface LaunchOptions {
  // Callbacks
  onProgress?: (event: ProgressEvent) => void;
  onSuccess?: (result: VerificationResult) => void;
  onError?: (error: Error) => void;
  
  // Configuration
  provider?: string;      // Provider name (default: 'socure')
  mode?: 'modal' | 'embedded';  // UI mode (default: 'embedded')
  theme?: object;         // Custom theme configuration
  language?: string;      // Language code (e.g., 'en', 'es')
  config?: object;        // Provider-specific configuration
}

SDK Instance Methods

interface VecuIDVSDK {
  // Launch verification
  launch(token: string, container: string | HTMLElement, options?: LaunchOptions): Promise<() => void>;
  
  // Event handling
  on(event: string, handler: Function): void;
  off(event: string, handler: Function): void;
  once(event: string, handler: Function): void;
  
  // Session management
  getVerificationResult(sessionId: string): Promise<VerificationResult>;
  cancelVerification(sessionId: string): Promise<void>;
  
  // Cleanup
  destroy(): void;
}

Events

The SDK emits various events during the verification process:

// SDK lifecycle
sdk.on('sdk:init', () => {});
sdk.on('sdk:ready', () => {});
sdk.on('sdk:error', (event) => {});

// Verification events
sdk.on('verification:started', (event) => {});
sdk.on('verification:progress', (event) => {});
sdk.on('verification:completed', (event) => {});
sdk.on('verification:failed', (event) => {});
sdk.on('verification:cancelled', (event) => {});

// UI events
sdk.on('ui:ready', (event) => {});
sdk.on('ui:closed', (event) => {});

// Provider events
sdk.on('provider:loaded', (event) => {});
sdk.on('provider:error', (event) => {});

Framework Examples

React

import { useEffect, useRef } from 'react';
import { createVecuIDVSDK } from '@vecu/idv-web-sdk';

function VerificationComponent({ sdkKey, token }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const cleanupRef = useRef<(() => void) | null>(null);

  useEffect(() => {
    if (!token || !containerRef.current) return;

    const sdk = createVecuIDVSDK(sdkKey);
    
    sdk.launch(token, containerRef.current, {
      onSuccess: (result) => {
        console.log('Verification completed!', result);
      },
      onError: (error) => {
        console.error('Verification failed:', error);
      }
    }).then(cleanup => {
      cleanupRef.current = cleanup;
    });

    return () => {
      cleanupRef.current?.();
      sdk.destroy();
    };
  }, [sdkKey, token]);

  return <div ref={containerRef} style={{ minHeight: '600px' }} />;
}

Vue

<template>
  <div ref="verificationContainer" :style="{ minHeight: '600px' }"></div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import { createVecuIDVSDK } from '@vecu/idv-web-sdk';

const props = defineProps(['sdkKey', 'token']);
const verificationContainer = ref(null);
let sdk = null;
let cleanup = null;

onMounted(async () => {
  sdk = createVecuIDVSDK(props.sdkKey);
  
  cleanup = await sdk.launch(
    props.token,
    verificationContainer.value,
    {
      onSuccess: (result) => {
        console.log('Verification completed!', result);
      }
    }
  );
});

onUnmounted(() => {
  cleanup?.();
  sdk?.destroy();
});
</script>

Security

The VECU IDV Web SDK is designed with security as a top priority:

• Hidden API Keys: SDK keys are never exposed in network requests
• Secure Token Exchange: Uses short-lived session tokens
• HTTPS Only: All communication is encrypted
• CSP Compatible: Works with Content Security Policy
• No Local Storage: No sensitive data is stored client-side

Browser Support

• Chrome/Edge: Latest 2 versions
• Firefox: Latest 2 versions
• Safari: 14+
• Mobile: iOS Safari 14+, Chrome for Android

TypeScript

The SDK is written in TypeScript and includes comprehensive type definitions. For the best development experience, we recommend using TypeScript in your project.

License

MIT © VECU Team

Support

For support, please contact:

• Email: [email protected]
• Documentation: https://docs.vecu.com
• Issues: https://github.com/VehicleCustody/vecu-idv-web-sdk/issues