Package Exports

vec-idp-web-sdk
vec-idp-web-sdk/dist/index.esm.js
vec-idp-web-sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (vec-idp-web-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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: 'john.doe@example.com',
        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: 'john.doe@example.com',
      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: 'john.doe@example.com',
      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: 'john.doe@example.com',
      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

Support

For support, please contact:

Email: support@vecu.com
Documentation: https://docs.vecu.com
Issues: https://github.com/VehicleCustody/vecu-idv-web-sdk/issues