npm package: @pritypandey/kyc-sdk
Description: Complete KYC (Know Your Customer) verification SDK with authentication, mobile/email verification, PAN/Aadhaar verification, document e-signature, and more
Author: Webninjaz
Latest version: 4.0.8

# KYC SDK - Authentication & Verification SDK

A comprehensive React SDK for KYC (Know Your Customer) verification and authentication flows.

## 📦 Installation

```bash
npm install @pritypandey/kyc-sdk
```

or

```bash
yarn add @pritypandey/kyc-sdk
```

or

```bash
pnpm add @pritypandey/kyc-sdk
```

## 🚀 Quick Start

### Basic Usage

```tsx
import { KYCProvider, KYCPage } from '@pritypandey/kyc-sdk';

function App() {
  return (
    <KYCProvider config={{
      baseUrl: 'https://kyc.webninjaz.com/sdk',
      clientId: 'your-client-id',
      onAuthChange: (user) => {
        console.log('Auth state changed:', user);
      },
      onError: (error) => {
        console.error('Auth error:', error);
      }
    }}>
      <KYCPage />
    </KYCProvider>
  );
}
```

## 📚 API Reference

### Components

#### `KYCProvider`

The main provider component that wraps your application and manages authentication state.

**Props:**
- `config` (required): Configuration object
  - `baseUrl` (optional): API base URL (default: `https://kyc.webninjaz.com/sdk`)
  - `clientId` (required): Your application/client identifier
  - `onAuthRequired` (optional): Callback when authentication is required
  - `onAuthChange` (optional): Callback when auth state changes
  - `onError` (optional): Error handler callback

**Example:**
```tsx
import { KYCProvider } from '@pritypandey/kyc-sdk';

<KYCProvider config={{
  clientId: 'your-client-id',
  baseUrl: 'https://kyc.webninjaz.com/sdk',
  onAuthChange: (user) => {
    if (user) {
      console.log('User logged in:', user);
    } else {
      console.log('User logged out');
    }
  }
}}>
  <YourApp />
</KYCProvider>
```

#### `KYCPage`

The main KYC verification page component that handles the entire KYC flow.

**Example:**
```tsx
import { KYCPage } from '@pritypandey/kyc-sdk';

function KYCVerification() {
  return <KYCPage />;
}
```

#### `useAuth` Hook

React hook to access authentication state and methods.

**Returns:**
- `user`: Current user object or null
- `tokens`: Authentication tokens or null
- `loading`: Boolean indicating loading state
- `error`: Error message or null
- `signIn`: Function to sign in
- `signOut`: Function to sign out
- `refresh`: Function to refresh tokens
- `getToken`: Function to get current access token

**Example:**
```tsx
import { useAuth } from '@pritypandey/kyc-sdk';

function MyComponent() {
  const { user, loading, signIn, signOut } = useAuth();

  if (loading) return <div>Loading...</div>;

  return (
    <div>
      {user ? (
        <div>
          <p>Welcome, {user.name || user.email}</p>
          <button onClick={signOut}>Sign Out</button>
        </div>
      ) : (
        <button onClick={() => signIn({ username: 'user', password: 'pass' })}>
          Sign In
        </button>
      )}
    </div>
  );
}
```

### Individual Components

You can also import individual components for more granular control:

```tsx
import {
  KYCMainPage,
  KYCVerificationStep,
  KYCApplicationSubmitted,
  KYCVerificationPage,
  Loader,
  Permissions,
  ErrorAlert
} from '@pritypandey/kyc-sdk';
```

#### `KYCMainPage`

The main landing page for KYC verification where users enter their Company ID and User ID.

#### `KYCVerificationStep`

The verification step component that handles individual verification steps.

#### `KYCApplicationSubmitted`

Component shown after successful KYC submission.

#### `KYCVerificationPage`

The verification page component.

#### `Loader`

Loading spinner component.

#### `Permissions`

Component for handling browser permissions.

#### `ErrorAlert`

Error alert component for displaying error messages.

## 🔧 TypeScript Support

The SDK is written in TypeScript and includes type definitions. All types are exported:

```tsx
import type {
  AuthConfig,
  AuthState,
  AuthTokens,
  User,
  AuthContextValue
} from '@pritypandey/kyc-sdk';
```

## 📋 Complete Example

```tsx
import React from 'react';
import {
  KYCProvider,
  KYCPage,
  useAuth
} from '@pritypandey/kyc-sdk';

// Configure the SDK
const sdkConfig = {
  clientId: 'your-client-id',
  baseUrl: 'https://kyc.webninjaz.com/sdk',
  onAuthChange: (user) => {
    console.log('Auth changed:', user);
  },
  onError: (error) => {
    console.error('Error:', error);
  }
};

function App() {
  return (
    <KYCProvider config={sdkConfig}>
      <KYCPage />
    </KYCProvider>
  );
}

export default App;
```

## 🎯 Features

- ✅ Complete KYC verification flow
- ✅ Mobile number verification
- ✅ Email verification
- ✅ PAN verification
- ✅ Aadhaar verification
- ✅ Personal, Family, and Professional details collection
- ✅ Nominee management
- ✅ Bank account linking
- ✅ Webcam verification with face detection
- ✅ E-signature support
- ✅ Real-time progress tracking
- ✅ Socket.io integration for real-time updates
- ✅ Error handling and validation
- ✅ TypeScript support

## 📝 Verification Steps

The SDK handles the following verification steps:

1. **Start** - Initial landing page
2. **Permissions** - Browser permissions check
3. **Mobile Verification** - Mobile number OTP verification
4. **Email Verification** - Email OTP verification
5. **PAN Verification** - PAN card verification
6. **Brokerage Selection** - Segment/brokerage selection
7. **Aadhaar Verification** - Aadhaar card verification
8. **Personal Details** - Personal information collection
9. **Family Details** - Family information collection
10. **Professional Details** - Professional information collection
11. **Nominee Management** - Add/edit/delete nominees
12. **Bank Account Linking** - Link bank account
13. **Webcam Verification** - Selfie verification with face detection
14. **E-Signature** - Document e-signature
15. **Application Submitted** - Success page

## 🔌 Socket Events

The SDK uses Socket.io for real-time communication. Events are handled automatically, but you can listen to them:

- `verify-mobile` - Mobile verification step
- `verify-mobile-otp` - Mobile OTP verification
- `verify-email` - Email verification step
- `verify-email-otp` - Email OTP verification
- `verify-pan` - PAN verification step
- `select-segments` - Brokerage selection step
- `verify-aadhaar` - Aadhaar verification step
- `personal-details` - Personal details step
- `family-details` - Family details step
- `professional-details` - Professional details step
- `add-nominee-verification` - Nominee verification step
- `link-bank-account` - Bank account linking step
- `webcam-verification` - Webcam verification step
- `esign-document` - E-signature step
- `kyc-complete` - KYC completion

## 🛠️ Requirements

- React >= 18
- React DOM >= 18

## 📦 Peer Dependencies

The SDK requires the following peer dependencies:

- `react` (>=18)
- `react-dom` (>=18)

## 🎨 Styling

The SDK includes its own CSS modules. Make sure to import the styles if needed:

```tsx
import '@pritypandey/kyc-sdk/dist/kyc-tool/page.module.css';
```

## 🔐 Authentication Flow

1. User enters Company ID and User ID
2. SDK authenticates with the backend
3. Receives access token
4. Establishes Socket.io connection
5. Proceeds with verification steps based on server events

## 📱 Browser Support

- Chrome (recommended)
- Firefox
- Safari
- Edge

**Note:** Camera and microphone permissions are required for webcam verification.

## 🐛 Troubleshooting

### Common Issues

1. **Socket connection fails**
   - Ensure the baseUrl is correct
   - Check if the access token is valid
   - Verify network connectivity

2. **Camera not working**
   - Check browser permissions
   - Ensure HTTPS is used (required for camera access)
   - Try refreshing the page

3. **Import errors**
   - Ensure React 18+ is installed
   - Check if all peer dependencies are installed
   - Verify TypeScript configuration if using TypeScript

## 📄 License

MIT

## 🤝 Support

For support, please contact the development team or open an issue in the repository.

## 🔄 Version History

- **2.0.0** - Current version with complete KYC flow
- Initial release with authentication and verification features

---

Made with ❤️ by Webninjaz