npm package: @finclusionaibuild/verification-package
Description: Reusable KYC/KYB verification components for Finclusion products
Author: Finclusion
Latest version: 1.0.2

# @finclusionaibuild/verification-package

A comprehensive React component library for KYC (Know Your Customer) and KYB (Know Your Business) verification flows. This package provides ready-to-use components for various verification types including BVN, NIN, CAC, TIN, and Liveliness checks.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Components](#components)
- [Theme Configuration](#theme-configuration)
- [Styling Guide](#styling-guide)
- [Verification Types](#verification-types)
- [API Endpoints](#api-endpoints)
- [Hooks](#hooks)
- [Advanced Usage](#advanced-usage)
- [TypeScript Support](#typescript-support)
- [Examples](#examples)
- [Troubleshooting](#troubleshooting)
- [API Reference](#api-reference)
- [License](#license)

## Features

- ✅ **Dynamic Tier System** - Backend-driven verification tiers with serial progression
- ✅ **Multiple Verification Types** - BVN, NIN, CAC, TIN, and Liveliness checks
- ✅ **Fully Customizable Themes** - Complete control over colors, typography, spacing, and styling
- ✅ **TypeScript Support** - Full type definitions included
- ✅ **Responsive Design** - Mobile-first, works on all screen sizes
- ✅ **Accessible** - WCAG compliant with proper ARIA labels
- ✅ **Flexible API Integration** - Customizable endpoints for your backend
- ✅ **Progress Tracking** - Real-time progress indicators and status badges
- ✅ **Error Handling** - Comprehensive error handling with user-friendly messages

## Installation

### Prerequisites

- React 18.3.1 or higher
- React DOM 18.3.1 or higher
- Node.js 16+ and npm/yarn/pnpm

### Install the Package

```bash
# Using npm
npm install @finclusionaibuild/verification-package

# Using yarn
yarn add @finclusionaibuild/verification-package

# Using pnpm
pnpm add @finclusionaibuild/verification-package
```

### Install Peer Dependencies

```bash
npm install react@^18.3.1 react-dom@^18.3.1 lucide-react@^0.344.0
```

### Import CSS Styles

**Important:** You must import the package styles in your application entry point:

```typescript
// In your main App.tsx or index.tsx
import '@finclusionaibuild/verification-package/styles.css';
```

Or if using a CSS import:

```typescript
import '@finclusionaibuild/verification-package/dist/styles.css';
```

### Tailwind CSS Requirement

This package uses Tailwind CSS for styling. Ensure your project has Tailwind CSS configured:

```bash
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
```

Add to your `tailwind.config.js`:

```javascript
module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
    "./node_modules/@finclusionaibuild/verification-package/**/*.{js,jsx,ts,tsx}",
  ],
  // ... rest of config
}
```

## Quick Start

### Basic Setup

1. **Wrap your app with KYCProvider:**

```typescript
import React from 'react';
import { KYCProvider, DynamicKYC } from '@finclusionaibuild/verification-package';
import '@finclusionaibuild/verification-package/styles.css';

function App() {
  const config = {
    apiBaseUrl: 'https://api.yourdomain.com',
    getAuthToken: () => localStorage.getItem('authToken'),
    userType: 'individual', // or 'business'
  };

  return (
    <KYCProvider config={config}>
      <DynamicKYC />
    </KYCProvider>
  );
}

export default App;
```

2. **That's it!** The `DynamicKYC` component will automatically:
   - Fetch verification status from your backend
   - Display available tiers
   - Handle verification flows
   - Track progress

## Configuration

### KYCConfig Interface

The `KYCConfig` interface defines all configuration options:

```typescript
interface KYCConfig {
  // Required
  apiBaseUrl: string;                    // Your API base URL
  getAuthToken: () => string | null;     // Function to retrieve auth token
  userType: 'individual' | 'business';  // User type

  // Optional
  appCode?: string;                     // Application code (e.g., "JP" for BVN)
  
  // Callbacks
  onVerificationComplete?: (tier: number, data?: any) => void;
  onTierChange?: (tier: number) => void;
  onError?: (error: Error) => void;
  
  // Theming
  theme?: ThemeConfig;                  // Complete theme configuration
  customStyles?: Record<string, React.CSSProperties | string>;
  
  // Behavior
  locale?: string;                      // Locale for i18n (future)
  enabledTiers?: number[];              // [1, 2, 3] or subset
  requireTierSequence?: boolean;        // Must complete tiers in order
  
  // API Endpoints
  endpoints?: {
    bvn?: string;
    nin?: string;
    liveliness?: string | {
      startSession?: string;
      submitSession?: string;
    };
    livelinessStatus?: string;
    dynamicKYCStatus?: string;
    documentsUpload?: string;
    documents?: string;
    verify?: string;
    cac?: {
      endpoint?: string;
      googleMapsAPIKey?: string;
    };
  };
  
  // Powered By Logo
  poweredBy?: {
    logoUrl?: string;
    altText?: string;
    linkUrl?: string;
    width?: string;
    height?: string;
    position?: 'left' | 'center' | 'right';
    textPrefix?: string;
    show?: boolean;
  };
}
```

### Complete Configuration Example

```typescript
import { KYCConfig } from '@finclusionaibuild/verification-package';

const config: KYCConfig = {
  // Required fields
  apiBaseUrl: 'https://api.yourdomain.com',
  getAuthToken: () => {
    // Get token from your auth system
    return localStorage.getItem('accessToken') || sessionStorage.getItem('token');
  },
  userType: 'individual', // or 'business'
  
  // Optional: Application code
  appCode: 'JP',
  
  // Callbacks
  onVerificationComplete: (tier, data) => {
    console.log(`Tier ${tier} completed!`, data);
    // Update your app state, show notification, etc.
  },
  onTierChange: (tier) => {
    console.log(`User moved to tier ${tier}`);
  },
  onError: (error) => {
    console.error('KYC Error:', error);
    // Send to error tracking service
  },
  
  // Custom endpoints (optional - uses defaults if not provided)
  endpoints: {
    bvn: '/api/verify/bvn',
    nin: '/api/verify/nin',
    dynamicKYCStatus: '/api/kyc/status',
    verify: '/api/kyc/verify/{verificationType}',
    cac: {
      endpoint: '/api/verify/cac',
      googleMapsAPIKey: 'your-google-maps-api-key',
    },
  },
  
  // Powered By Logo (optional)
  poweredBy: {
    logoUrl: 'https://yourdomain.com/logo.png',
    altText: 'Powered by Your Company',
    linkUrl: 'https://yourdomain.com',
    position: 'center',
    textPrefix: 'Powered by',
    width: 'w-24',
    height: 'h-8',
  },
};
```

## Components

### DynamicKYC

The main component that displays the verification interface with tier cards and progress tracking.

```typescript
import { DynamicKYC } from '@finclusionaibuild/verification-package';

<DynamicKYC
  onVerificationComplete={(tier, verifications) => {
    console.log(`Tier ${tier} completed with:`, verifications);
  }}
  showHeader={true} // Show/hide the header section
/>
```

**Props:**
- `onVerificationComplete?: (tier: string, verifications: string[]) => void` - Callback when a tier is completed
- `showHeader?: boolean` - Show/hide the header (default: `true`)

### DynamicTierCard

Individual tier card component (used internally by DynamicKYC).

### VerificationOrchestrator

Manages the flow of individual verification modals (used internally).

### Individual Verification Modals

You can use verification modals individually if needed:

```typescript
import {
  BVNVerificationModal,
  NINVerificationModal,
  CACVerificationModal,
  TINVerificationModal,
  LivelinessVerificationModal,
} from '@finclusionaibuild/verification-package';

// Example: BVN Verification
<BVNVerificationModal
  onComplete={(data) => {
    console.log('BVN verified:', data);
  }}
  onClose={() => {
    // Handle close
  }}
  initialData={{
    // Pre-fill if available
  }}
/>
```

## Theme Configuration

The package provides a comprehensive theming system that allows you to customize every aspect of the UI.

### Theme Structure

```typescript
interface ThemeConfig {
  statusColors?: {
    completed?: string;
    inProgress?: string;
    pending?: string;
    locked?: string;
    error?: string;
  };
  primaryColors?: {
    main?: string;
    hover?: string;
    text?: string;
    light?: string;
  };
  neutralColors?: {
    background?: string;
    textPrimary?: string;
    textSecondary?: string;
    textTertiary?: string;
    border?: string;
    progressBg?: string;
  };
  componentStyles?: {
    cardPadding?: string;
    cardPaddingCompact?: string;
    cardBorderRadius?: string;
    cardBorderRadiusLarge?: string;
    buttonBorderRadius?: string;
    badgeBorderRadius?: string;
    progressBorderRadius?: string;
    cardShadow?: string;
    cardShadowHover?: string;
    modalShadow?: string;
  };
  typography?: {
    heading1?: string;
    heading2?: string;
    heading3?: string;
    body?: string;
    bodySmall?: string;
    button?: string;
  };
  iconSizes?: {
    tier?: string;
    status?: string;
    small?: string;
    button?: string;
  };
  progressBar?: {
    height?: string;
    heightSmall?: string;
  };
  modal?: {
    overlayOpacity?: string;
    maxWidth?: string;
  };
  spacing?: {
    sectionGap?: string;
    gridGap?: string;
  };
  opacity?: {
    locked?: string;
  };
  formElements?: {
    labelText?: string;
    helperText?: string;
    inputPadding?: string;
    inputBorderRadius?: string;
    inputBorder?: string;
    inputFocusRing?: string;
    secondaryButtonBorder?: string;
    disabledOpacity?: string;
  };
}
```

### Color Values

All color values can be:
- **Hex colors**: `"#2563eb"`, `"#10b981"`
- **RGB/RGBA**: `"rgb(37, 99, 235)"`, `"rgba(37, 99, 235, 0.1)"`
- **CSS color names**: `"blue"`, `"green"`

### Spacing and Typography

Spacing, border radius, and typography use **Tailwind CSS classes**:
- Spacing: `"p-6"`, `"px-4"`, `"py-2"`
- Border radius: `"rounded-lg"`, `"rounded-full"`
- Typography: `"text-sm"`, `"text-2xl font-bold"`

### Theme Examples

#### Minimal Theme (Only Customize What You Need)

```typescript
const config: KYCConfig = {
  // ... other config
  theme: {
    primaryColors: {
      main: "#6366f1",      // Custom indigo
      hover: "#4f46e5",
    },
    statusColors: {
      completed: "#10b981",  // Custom green
    },
  },
};
```

#### Complete Light Theme

```typescript
const config: KYCConfig = {
  // ... other config
  theme: {
    statusColors: {
      completed: "#10b981",      // Green
      inProgress: "#2563eb",     // Blue
      pending: "#f59e0b",         // Amber
      locked: "#9ca3af",         // Gray
      error: "#ef4444",          // Red
    },
    primaryColors: {
      main: "#2563eb",           // Blue
      hover: "#1d4ed8",
      text: "#ffffff",
      light: "#dbeafe",
    },
    neutralColors: {
      background: "#ffffff",
      textPrimary: "#111827",
      textSecondary: "#4b5563",
      textTertiary: "#6b7280",
      border: "#e5e7eb",
      progressBg: "#e5e7eb",
    },
    componentStyles: {
      cardPadding: "p-6",
      cardBorderRadius: "rounded-lg",
      buttonBorderRadius: "rounded-lg",
      cardShadow: "shadow-sm",
    },
    typography: {
      heading1: "text-2xl font-bold",
      heading2: "text-lg font-semibold",
      body: "text-sm",
    },
  },
};
```

#### Dark Theme

```typescript
const config: KYCConfig = {
  // ... other config
  theme: {
    statusColors: {
      completed: "#34d399",      // Lighter green
      inProgress: "#60a5fa",     // Lighter blue
      pending: "#fbbf24",         // Lighter yellow
      locked: "#6b7280",
      error: "#f87171",          // Lighter red
    },
    primaryColors: {
      main: "#60a5fa",
      hover: "#3b82f6",
      text: "#ffffff",
      light: "#1e3a8a",
    },
    neutralColors: {
      background: "#1f2937",     // Dark gray
      textPrimary: "#f9fafb",    // Light text
      textSecondary: "#d1d5db",
      textTertiary: "#9ca3af",
      border: "#374151",
      progressBg: "#374151",
    },
    componentStyles: {
      cardShadow: "shadow-lg",
      modalShadow: "shadow-2xl",
    },
  },
};
```

#### Custom Brand Theme

```typescript
const config: KYCConfig = {
  // ... other config
  theme: {
    statusColors: {
      completed: "#22c55e",
      inProgress: "#3b82f6",
      pending: "#f59e0b",
      locked: "#94a3b8",
      error: "#ef4444",
    },
    primaryColors: {
      main: "#8b5cf6",           // Purple brand color
      hover: "#7c3aed",
      text: "#ffffff",
      light: "#ede9fe",
    },
    neutralColors: {
      background: "#ffffff",
      textPrimary: "#0f172a",
      textSecondary: "#475569",
      textTertiary: "#64748b",
      border: "#cbd5e1",
      progressBg: "#e2e8f0",
    },
    componentStyles: {
      cardBorderRadius: "rounded-xl",  // More rounded
      cardPadding: "p-8",              // More padding
    },
    typography: {
      heading1: "text-3xl font-bold",  // Larger heading
    },
  },
};
```

### Theme Property Reference

For a complete reference of all theme properties, see the `THEME_CONFIG_EXAMPLE.ts` file in the package or check the TypeScript definitions.

## Styling Guide

### CSS Import

**Always import the package styles:**

```typescript
import '@finclusionaibuild/verification-package/styles.css';
```

### Tailwind CSS

The package uses Tailwind CSS. Ensure your project has Tailwind configured and includes the package in your content paths:

```javascript
// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
    "./node_modules/@finclusionaibuild/verification-package/**/*.{js,jsx,ts,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}
```

### CSS Variables

The package uses CSS custom properties (variables) for theming. These are automatically injected by the `KYCProvider`:

```css
/* Example CSS variables */
--kyc-color-primary-main: #2563eb;
--kyc-color-status-completed: #10b981;
--kyc-color-neutral-background: #ffffff;
/* ... and more */
```

### Custom CSS Overrides

You can override styles using CSS:

```css
/* Override specific component styles */
.kyc-tier-card {
  border: 2px solid #custom-color;
}

/* Override theme variables */
:root {
  --kyc-color-primary-main: #your-color;
}
```

## Verification Types

### BVN (Bank Verification Number)

**Required for:** Individual users (Nigeria)

**Data Required:**
- BVN number
- First name
- Last name
- Middle name (optional)
- Date of birth (DD/MM/YYYY)
- Gender

**Example:**
```typescript
// Automatically handled by DynamicKYC
// Or use individually:
<BVNVerificationModal
  onComplete={(data) => {
    console.log('BVN verified:', data);
  }}
  onClose={() => {}}
/>
```

### NIN (National Identification Number)

**Required for:** Individual users (Nigeria)

**Data Required:**
- NIN number

**Example:**
```typescript
<NINVerificationModal
  onComplete={(data) => {
    console.log('NIN verified:', data);
  }}
  onClose={() => {}}
/>
```

### CAC (Corporate Affairs Commission)

**Required for:** Business users (Nigeria)

**Data Required:**
- Company registration number
- Company name
- Company address
- Director information
- Supporting documents (upload)

**Example:**
```typescript
<CACVerificationModal
  onComplete={(data) => {
    console.log('CAC verified:', data);
  }}
  onClose={() => {}}
/>
```

### TIN (Tax Identification Number)

**Required for:** Business users

**Data Required:**
- TIN number

**Example:**
```typescript
<TINVerificationModal
  onComplete={(data) => {
    console.log('TIN verified:', data);
  }}
  onClose={() => {}}
/>
```

### Liveliness Check

**Required for:** Individual users (face verification)

**Data Required:**
- Video recording of face
- Follows on-screen instructions

**Example:**
```typescript
<LivelinessVerificationModal
  onComplete={(data) => {
    console.log('Liveliness verified:', data);
  }}
  onClose={() => {}}
/>
```

## API Endpoints

### Default Endpoints

The package uses these default endpoints (relative to `apiBaseUrl`):

```typescript
{
  bvn: '/nigeria/bvn',
  nin: '/nigeria/nin',
  liveliness: '/api/liveliness',
  livelinessStatus: '/api/liveliness/{sessionId}',
  dynamicKYCStatus: '/kyc-status',
  documentsUpload: '/kyc/documents/upload',
  documents: '/kyc/documents',
  verify: '/kyc/verify/{verificationType}',
}
```

### Custom Endpoints

Override defaults in your config:

```typescript
const config: KYCConfig = {
  // ... other config
  endpoints: {
    bvn: '/api/custom/bvn-verify',
    nin: '/api/custom/nin-verify',
    dynamicKYCStatus: '/api/custom/kyc/status',
    verify: '/api/custom/verify/{verificationType}',
    cac: {
      endpoint: '/api/custom/cac-verify',
      googleMapsAPIKey: 'your-key-here',
    },
    liveliness: {
      startSession: '/api/liveness/start',
      submitSession: '/api/liveness/{sessionId}/submit',
    },
  },
};
```

### Endpoint Placeholders

Some endpoints support placeholders that are replaced at runtime:

- `{sessionId}` - Replaced with actual session ID
- `{verificationType}` - Replaced with verification type (bvn, nin, etc.)

### Authentication

All API requests include the authentication token from `getAuthToken()`:

```typescript
// Example: Token in Authorization header
Authorization: Bearer <token-from-getAuthToken()>
```

### Expected Response Formats

#### Dynamic KYC Status

```typescript
{
  currentTier: "tier1" | "tier2" | "tier3",
  overallProgress: number, // 0-100
  isFullyCompleted: boolean,
  tierRequirements: [
    {
      tier: "tier1",
      required: ["bvn", "nin"],
      completed: ["bvn"],
      pending: ["nin"],
      progress: 50,
      isCompleted: false,
    },
    // ... more tiers
  ],
  collectedPersonalInfo: boolean,
}
```

#### Verification Response

```typescript
{
  success: boolean,
  message: string,
  data?: any,
}
```

## Hooks

### useKYC

Hook to access KYC status and operations (legacy - for non-dynamic KYC).

```typescript
import { useKYC } from '@finclusionaibuild/verification-package';

function MyComponent() {
  const { status, progress, loading, error, refresh, service } = useKYC();

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <p>Status: {status?.overall}</p>
      <p>Progress: {progress?.percentage}%</p>
      <button onClick={refresh}>Refresh</button>
    </div>
  );
}
```

**Returns:**
- `status: KYCStatus | null` - Current KYC status
- `progress: KYCProgress | null` - Progress information
- `loading: boolean` - Loading state
- `error: Error | null` - Error state
- `refresh: () => Promise<void>` - Refresh function
- `service: KYCService` - Service instance

### useKYCContext

Access the KYC context (config and service).

```typescript
import { useKYCContext } from '@finclusionaibuild/verification-package';

function MyComponent() {
  const { config, service, theme } = useKYCContext();

  return (
    <div>
      <p>User Type: {config.userType}</p>
    </div>
  );
}
```

**Returns:**
- `config: KYCConfig` - Current configuration
- `service: KYCService` - Service instance
- `theme: Required<ThemeConfig>` - Merged theme configuration

### useKYCTheme

Access the merged theme configuration.

```typescript
import { useKYCTheme } from '@finclusionaibuild/verification-package';

function MyComponent() {
  const theme = useKYCTheme();

  return (
    <div style={{ color: `var(--kyc-color-primary-main)` }}>
      <h1 className={theme.typography.heading1}>Title</h1>
    </div>
  );
}
```

**Returns:**
- `theme: Required<ThemeConfig>` - Complete theme configuration with defaults merged

## Advanced Usage

### Custom Verification Flow

```typescript
import { VerificationOrchestrator } from '@finclusionaibuild/verification-package';

function CustomFlow() {
  const [verifications, setVerifications] = useState(['bvn', 'nin']);
  const [showModal, setShowModal] = useState(false);

  return (
    <>
      <button onClick={() => setShowModal(true)}>
        Start Verification
      </button>
      {showModal && (
        <VerificationOrchestrator
          requiredVerifications={verifications}
          onComplete={(completed) => {
            console.log('Completed:', completed);
            setShowModal(false);
          }}
          onClose={() => setShowModal(false)}
        />
      )}
    </>
  );
}
```

### Error Handling

```typescript
const config: KYCConfig = {
  // ... other config
  onError: (error) => {
    // Log to error tracking service
    console.error('KYC Error:', error);
    
    // Show user-friendly message
    toast.error('Verification failed. Please try again.');
    
    // Send to analytics
    analytics.track('kyc_error', {
      error: error.message,
    });
  },
};
```

### Conditional Tier Enabling

```typescript
const config: KYCConfig = {
  // ... other config
  enabledTiers: [1, 2], // Only enable tier 1 and 2
  requireTierSequence: true, // Must complete in order
};
```

### Custom Styling Per Component

```typescript
const config: KYCConfig = {
  // ... other config
  customStyles: {
    'tier-card': {
      border: '2px solid #custom-color',
    },
    'verification-modal': {
      maxWidth: '800px',
    },
  },
};
```

## TypeScript Support

The package includes full TypeScript definitions. All types are exported:

```typescript
import type {
  KYCConfig,
  ThemeConfig,
  DynamicKYCStatusResponse,
  TierRequirement,
  VerificationType,
  BVNVerificationRequest,
  BVNVerificationResponse,
  // ... and more
} from '@finclusionaibuild/verification-package';
```

### Type Safety Example

```typescript
import type { KYCConfig } from '@finclusionaibuild/verification-package';

const config: KYCConfig = {
  apiBaseUrl: 'https://api.example.com',
  getAuthToken: () => localStorage.getItem('token'),
  userType: 'individual', // TypeScript will error if invalid
};
```

## Examples

### Example 1: Individual User Setup

```typescript
import React from 'react';
import { KYCProvider, DynamicKYC } from '@finclusionaibuild/verification-package';
import '@finclusionaibuild/verification-package/styles.css';

function IndividualKYC() {
  const config = {
    apiBaseUrl: 'https://api.yourdomain.com',
    getAuthToken: () => localStorage.getItem('authToken'),
    userType: 'individual' as const,
    onVerificationComplete: (tier, data) => {
      console.log(`Tier ${tier} completed!`);
    },
  };

  return (
    <KYCProvider config={config}>
      <DynamicKYC showHeader={true} />
    </KYCProvider>
  );
}

export default IndividualKYC;
```

### Example 2: Business User Setup

```typescript
import React from 'react';
import { KYCProvider, DynamicKYC } from '@finclusionaibuild/verification-package';
import '@finclusionaibuild/verification-package/styles.css';

function BusinessKYB() {
  const config = {
    apiBaseUrl: 'https://api.yourdomain.com',
    getAuthToken: () => localStorage.getItem('authToken'),
    userType: 'business' as const,
    endpoints: {
      cac: {
        endpoint: '/api/verify/cac',
        googleMapsAPIKey: 'your-google-maps-key',
      },
    },
    onVerificationComplete: (tier, data) => {
      console.log(`Business tier ${tier} completed!`);
    },
  };

  return (
    <KYCProvider config={config}>
      <DynamicKYC showHeader={true} />
    </KYCProvider>
  );
}

export default BusinessKYB;
```

### Example 3: Custom Theme

```typescript
import React from 'react';
import { KYCProvider, DynamicKYC } from '@finclusionaibuild/verification-package';
import '@finclusionaibuild/verification-package/styles.css';

function ThemedKYC() {
  const config = {
    apiBaseUrl: 'https://api.yourdomain.com',
    getAuthToken: () => localStorage.getItem('authToken'),
    userType: 'individual' as const,
    theme: {
      primaryColors: {
        main: '#8b5cf6', // Purple brand
        hover: '#7c3aed',
      },
      statusColors: {
        completed: '#22c55e',
        inProgress: '#3b82f6',
        pending: '#f59e0b',
      },
      componentStyles: {
        cardBorderRadius: 'rounded-xl',
        cardPadding: 'p-8',
      },
      typography: {
        heading1: 'text-3xl font-bold',
      },
    },
  };

  return (
    <KYCProvider config={config}>
      <DynamicKYC />
    </KYCProvider>
  );
}

export default ThemedKYC;
```

### Example 4: Custom Endpoints

```typescript
import React from 'react';
import { KYCProvider, DynamicKYC } from '@finclusionaibuild/verification-package';
import '@finclusionaibuild/verification-package/styles.css';

function CustomEndpointsKYC() {
  const config = {
    apiBaseUrl: 'https://api.yourdomain.com',
    getAuthToken: () => localStorage.getItem('authToken'),
    userType: 'individual' as const,
    endpoints: {
      bvn: '/api/v2/verify/bvn',
      nin: '/api/v2/verify/nin',
      dynamicKYCStatus: '/api/v2/kyc/status',
      verify: '/api/v2/kyc/verify/{verificationType}',
      liveliness: {
        startSession: '/api/v2/liveness/start',
        submitSession: '/api/v2/liveness/{sessionId}/submit',
      },
    },
  };

  return (
    <KYCProvider config={config}>
      <DynamicKYC />
    </KYCProvider>
  );
}

export default CustomEndpointsKYC;
```

### Example 5: Complete Integration

```typescript
import React, { useState } from 'react';
import { KYCProvider, DynamicKYC, useKYCContext } from '@finclusionaibuild/verification-package';
import '@finclusionaibuild/verification-package/styles.css';

function App() {
  const config = {
    apiBaseUrl: process.env.REACT_APP_API_URL || 'https://api.yourdomain.com',
    getAuthToken: () => {
      // Get from your auth system
      return localStorage.getItem('accessToken');
    },
    userType: 'individual' as const,
    appCode: 'JP',
    onVerificationComplete: (tier, data) => {
      // Update your app state
      console.log(`Tier ${tier} completed!`, data);
      
      // Show success notification
      // Update user permissions
      // Redirect if needed
    },
    onError: (error) => {
      console.error('KYC Error:', error);
      // Handle error (show toast, log to service, etc.)
    },
    theme: {
      primaryColors: {
        main: '#2563eb',
        hover: '#1d4ed8',
      },
    },
    poweredBy: {
      logoUrl: 'https://yourdomain.com/logo.png',
      altText: 'Powered by Your Company',
      position: 'center',
    },
  };

  return (
    <KYCProvider config={config}>
      <div className="app">
        <header>
          <h1>My Application</h1>
        </header>
        <main>
          <DynamicKYC showHeader={true} />
        </main>
      </div>
    </KYCProvider>
  );
}

export default App;
```

## Troubleshooting

### React Multiple Instances Error

If you see: `Cannot read properties of undefined (reading 'ReactCurrentDispatcher')`

**Solution:**
1. Rebuild the package: `npm run build` in the package directory
2. Clear node_modules and reinstall in your project
3. Ensure peer dependencies are installed correctly
4. Add to your Vite config (if using Vite):

```typescript
// vite.config.ts
export default {
  resolve: {
    dedupe: ['react', 'react-dom'],
  },
  optimizeDeps: {
    include: ['react', 'react-dom'],
  },
}
```

### Styles Not Applying

**Solution:**
1. Ensure you've imported the CSS: `import '@finclusionaibuild/verification-package/styles.css'`
2. Check that Tailwind CSS is configured correctly
3. Verify the package is included in Tailwind's content paths

### Theme Not Working

**Solution:**
1. Ensure `KYCProvider` is wrapping your components
2. Check that theme properties use correct formats (hex for colors, Tailwind classes for spacing)
3. Verify CSS variables are being injected (check browser DevTools)

### API Errors

**Solution:**
1. Verify `apiBaseUrl` is correct
2. Check that `getAuthToken()` returns a valid token
3. Ensure your backend endpoints match the configured endpoints
4. Check network tab for actual request/response

### TypeScript Errors

**Solution:**
1. Ensure you're using the latest version of the package
2. Check that types are installed: `npm install --save-dev @types/react @types/react-dom`
3. Restart your TypeScript server in your IDE

### Build Errors

**Solution:**
1. Ensure all peer dependencies are installed
2. Check Node.js version (16+ required)
3. Clear build cache and rebuild

## API Reference

### KYCService

The service class handles all API communication.

**Methods:**
- `getDynamicKYCStatus(): Promise<DynamicKYCStatusResponse>`
- `submitVerification(verificationType, data): Promise<{success, message, data}>`
- `submitCACTierOne(formData): Promise<{success, message, data}>`

### Components

#### DynamicKYC

Main verification component.

**Props:**
```typescript
interface DynamicKYCProps {
  onVerificationComplete?: (tier: string, verifications: string[]) => void;
  showHeader?: boolean;
}
```

#### KYCProvider

Context provider for KYC configuration.

**Props:**
```typescript
interface KYCProviderProps {
  config: KYCConfig;
  children: ReactNode;
}
```

### Types

All types are exported from the package. See TypeScript definitions for complete reference.

## Contributing

Contributions are welcome! Please see the repository for contribution guidelines.

## License

MIT

---

**Need Help?** Open an issue on [GitHub](https://github.com/finclusion/verification-package) or contact support.