vec-idp-web-sdk/README.md

VECU Identity Verification Web SDK - A secure, easy-to-integrate identity verification solution

# 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

```bash
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)

```html
<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:

```html
<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

```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:

```typescript
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:

```typescript
// 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)

```typescript
// 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

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

#### ISDKConfig

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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:

```typescript
// 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

```tsx
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

```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: support@vecu.com
- Documentation: https://docs.vecu.com
- Issues: https://github.com/VehicleCustody/vecu-idv-web-sdk/issues