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

```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/index.umd.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

```typescript
import { createVecuIDVSDK } from 'vec-idp-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)

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

### Factory Function

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

#### SDKConfig

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

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

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

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

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

## Framework Examples

### React

```tsx
import { useEffect, useRef } from 'react';
import { createVecuIDVSDK } from 'vec-idp-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

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