VECU IDV Web SDK

A secure, TypeScript-first identity verification SDK for web applications. Built with security in mind, featuring a clean, simple API.

Features

• 🔐 Secure by Design: Built with security best practices
• 🔌 Flexible Integration: Easy to integrate with your existing applications
• 🚀 Optimized Performance: Resources 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 vec-idp-web-sdk
# or
yarn add vec-idp-web-sdk
# or
pnpm add vec-idp-web-sdk

Quick Start

Browser (UMD Bundle)

<script src="https://unpkg.com/vec-idp-web-sdk/dist/vecu-idv-sdk.bundle.js"></script>
<script>
  // Configure the SDK first
  VecuIDVSDK.configure({
    deploymentStage: 'sandbox', // or 'production', 'preprod'
    enableDirectAPI: true,      // Required for startVerificationWithCustomer
    debug: true
  });

  // SDK is available as window.VecuIDVSDK
  VecuIDVSDK.startVerificationWithCustomer(
    '#verification-container',
    {
      customerInfo: {
        firstName: 'John',
        lastName: 'Doe',
        email: '[email protected]',
        address: {
          line1: '123 Main St',
          locality: 'Anytown',
          majorAdminDivision: 'CA',
          country: 'US',
          postalCode: '12345',
          type: 'residential'
        }
      },
      onSuccess: (result) => {
        console.log('Verification completed!', result);
      },
      onError: (error) => {
        console.error('Verification failed:', error);
      }
    }
  );
</script>

Alternatively, you can use the factory function approach:

<script src="https://unpkg.com/vec-idp-web-sdk/dist/index.umd.js"></script>
<script>
  // SDK factory is available as window.VecuIDV
  const sdk = VecuIDV.createVecuIDVSDK({
    deploymentStage: 'sandbox',
    debug: true,
    enableDirectAPI: true  // Required for startVerificationWithCustomer
  });
  
  sdk.startVerificationWithCustomer('#verification-container', {
    customerInfo: {
      firstName: 'John',
      lastName: 'Doe',
      email: '[email protected]',
      address: {
        line1: '123 Main St',
        locality: 'Anytown',
        majorAdminDivision: 'CA',
        country: 'US',
        postalCode: '12345',
        type: 'residential'
      }
    },
    onSuccess: (result) => {
      console.log('Verification completed!', result);
    },
    onError: (error) => {
      console.error('Verification failed:', error);
    }
  });
</script>

ES Modules / TypeScript

import { createVecuIDVSDK } from 'vec-idp-web-sdk';

// Create SDK instance with configuration
const sdk = createVecuIDVSDK({
  apiUrl: 'https://api.vecu.com',
  debug: true,
  logLevel: 'info',
  deploymentStage: 'sandbox',
  enableDirectAPI: true  // Required for startVerificationWithCustomer
});

// Start verification with customer info
const cleanup = await sdk.startVerificationWithCustomer(
  document.getElementById('verification-container'),
  {
    customerInfo: {
      firstName: 'John',
      lastName: 'Doe',
      email: '[email protected]',
      phone: '+1-555-123-4567',
      address: {
        line1: '123 Main St',
        locality: 'Anytown',
        majorAdminDivision: 'CA',
        country: 'US',
        postalCode: '12345',
        type: 'residential'
      }
    },
    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();

Customer Verification Flow

For verification flows with pre-filled customer information:

import { createVecuIDVSDK } from 'vec-idp-web-sdk';

const sdk = createVecuIDVSDK({
  deploymentStage: 'sandbox',
  enableDirectAPI: true,  // Required for startVerificationWithCustomer
  debug: true
});

// Start verification with customer info (SDK instance method)
const cleanup = await sdk.startVerificationWithCustomer(
  document.getElementById('verification-container'),
  {
    customerInfo: {
      firstName: 'John',
      lastName: 'Doe',
      email: '[email protected]',
      phone: '+1-555-123-4567',
      address: {
        line1: '123 Main St',
        locality: 'Anytown',
        majorAdminDivision: 'CA',
        country: 'US',
        postalCode: '12345',
        type: 'residential'
      }
    },
    referenceId: 'customer-ref-123',
    onSuccess: (result) => {
      console.log('Verification completed!', result);
    },
    onError: (error) => {
      console.error('Verification failed:', error);
    }
  }
);

Global SDK Customer Verification

Alternatively, you can use the global SDK method:

// Global SDK method
const cleanup = await window.VecuIDVSDK.startVerificationWithCustomer(
  document.getElementById('verification-container'),
  {
    customerInfo: {
      firstName: 'John',
      lastName: 'Doe',
      // ... rest of customer info
    },
    onSuccess: (result) => {
      console.log('Verification completed!', result);
    }
  }
);

API Reference

Global SDK (Browser)

// Configure global settings (call this first!)
window.VecuIDVSDK.configure(options: GlobalConfigOptions): void

// Start verification with customer info (requires enableDirectAPI: true)
window.VecuIDVSDK.startVerificationWithCustomer(
  containerSelector: string | HTMLElement,
  options: CustomerVerificationOptions
): Promise<() => void>

// Launch verification with existing transaction token
window.VecuIDVSDK.launch(
  transactionToken: string,
  containerSelector: string | HTMLElement,
  options?: LaunchOptions
): Promise<() => void>

Factory Function

createVecuIDVSDK(config?: ISDKConfig, dependencies?: ISDKDependencies): VecuIDVSecureSDK

ISDKConfig

interface ISDKConfig {
  apiUrl?: string;                        // API endpoint
  timeout?: number;                       // Request timeout in ms (default: 30000)
  maxRetries?: number;                    // Max retry attempts (default: 3)
  logLevel?: 'debug' | 'info' | 'warn' | 'error'; // Log level (default: 'info')
  debug?: boolean;                        // Enable debug mode (default: false)
  enableDirectAPI?: boolean;              // Enable direct API calls (default: false)
  deploymentStage?: 'sandbox' | 'production' | 'preprod'; // Deployment environment
  bearerToken?: string;                   // Bearer token for API authentication
  apiEndpoints?: {
    startVerification?: string;           // Custom endpoint for starting verification
  };
}

LaunchOptions

interface LaunchOptions {
  // Callbacks
  onProgress?: (event: ProgressEvent) => void;
  onSuccess?: (result: VerificationResult) => void;
  onError?: (error: Error) => void;
  
  // Configuration
  mode?: 'modal' | 'embedded';  // UI mode (default: 'embedded')
  theme?: object;         // Custom theme configuration
  language?: string;      // Language code (e.g., 'en', 'es')
  config?: object;        // Additional configuration options
  deploymentStage?: 'sandbox' | 'production' | 'preprod'; // Deployment environment
}

CustomerVerificationOptions

interface CustomerVerificationOptions {
  customerInfo: ICustomerInfo;
  referenceId?: string;
  deploymentStage?: 'sandbox' | 'production' | 'preprod';
  
  // Callbacks
  onProgress?: (event: ProgressEvent) => void;
  onSuccess?: (result: VerificationResult) => void;
  onError?: (error: Error) => void;
  
  // UI Configuration
  mode?: 'modal' | 'embedded';
  theme?: object;
  language?: string;
  config?: object;
}

ICustomerInfo

interface ICustomerInfo {
  firstName: string;
  lastName: string;
  middleName?: string;
  email?: string;
  phone?: string;
  address: {
    line1: string;
    line2?: string;
    locality: string;           // City
    minorAdminDivision?: string; // County
    majorAdminDivision: string; // State/Province
    country: string;           // Country code (e.g., 'US')
    postalCode: string;        // ZIP/Postal code
    type: 'residential' | 'commercial';
  };
}

SDK Instance Methods

interface VecuIDVSecureSDK {
  // Recommended: Start verification with customer info (requires enableDirectAPI: true)
  startVerificationWithCustomer(container: string | HTMLElement, options: CustomerVerificationOptions): Promise<() => void>;
  
  // Event handling
  on(event: string, handler: (event: unknown) => void): void;
  off(event: string, handler: (event: unknown) => void): void;
  once(event: string, handler: (event: unknown) => void): void;
  
  // Configuration updates
  updateConfig(config: Partial<ISDKConfig>): void;
  
  // Cleanup - destroys the SDK instance and removes all event listeners
  destroy(): void;
  
  // Launch verification with existing transaction token
  launch(token: string, container: string | HTMLElement, options?: LaunchOptions): Promise<() => void>;
}

Important Notes:

• The enableDirectAPI: true configuration is required when using startVerificationWithCustomer()
• Verification results are provided through the onSuccess callback in the options
• The returned cleanup function from both launch() and startVerificationWithCustomer() handles cancellation and cleanup

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) => {});

Framework Examples

React

import { useEffect, useRef } from 'react';
import { createVecuIDVSDK } from 'vec-idp-web-sdk';

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

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

    const sdk = createVecuIDVSDK({
      debug: process.env.NODE_ENV === 'development',
      deploymentStage: 'sandbox',
      logLevel: 'info',
      enableDirectAPI: true  // Required for startVerificationWithCustomer
    });
    
    sdk.startVerificationWithCustomer(containerRef.current, {
      customerInfo,
      mode: 'embedded',
      onSuccess: (result) => {
        console.log('Verification completed!', result);
      },
      onError: (error) => {
        console.error('Verification failed:', error);
      },
      onProgress: (event) => {
        console.log(`Step: ${event.step}, Progress: ${event.percentage}%`);
      }
    }).then(cleanup => {
      cleanupRef.current = cleanup;
    });

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

  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 'vec-idp-web-sdk';

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

onMounted(async () => {
  sdk = createVecuIDVSDK({
    debug: import.meta.env.DEV,
    deploymentStage: 'sandbox',
    logLevel: 'info',
    enableDirectAPI: true  // Required for startVerificationWithCustomer
  });
  
  cleanup = await sdk.startVerificationWithCustomer(
    verificationContainer.value,
    {
      customerInfo: props.customerInfo,
      mode: 'embedded',
      onSuccess: (result) => {
        console.log('Verification completed!', result);
      },
      onError: (error) => {
        console.error('Verification failed:', error);
      },
      onProgress: (event) => {
        console.log(`Step: ${event.step}, Progress: ${event.percentage}%`);
      }
    }
  );
});

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

Security

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

• Secure Communication: All data transmission is encrypted
• 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