# Astra KYC SDK

A comprehensive KYC (Know Your Customer) SDK with web and mobile support, featuring face capture, document upload, and seamless device switching.

## Features

- **Face Capture**: Live camera capture with web
- **Document Upload**: Support for CNIC and Passport documents
- **Device Switching**: QR code-based switching from web to mobile
- **Session Management**: Automatic session validation and expiry handling
- **TypeScript Support**: Full type definitions included
- **React Integration**: Ready-to-use React components

## Installation

```bash
npm install astra-sdk-astra
```

## Quick Start

### Basic Usage (Modal flow)

```tsx
import React, { useState } from "react";
import { VerificationSDK, KycModal } from "astra-sdk-astra";
import "astra-sdk-astra/kycModal.css";

const sdk = new VerificationSDK({ serverKey: "your-server-key" });

function App() {
  const [showModal, setShowModal] = useState(false);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const startKyc = async () => {
    setError(null);
    setLoading(true);
    try {
      await sdk.init({
        reference: "user123",
        email: "user@example.com",
        callback_url: "https://your-app.com/callback",
        redirect_url: "https://your-app.com/redirect",
        device_type: "WEB"
      });
      setShowModal(true);
    } catch (err: any) {
      setError(err?.message || "Failed to initialize KYC");
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <button onClick={startKyc} disabled={loading}>
        {loading ? "Starting..." : "Start KYC"}
      </button>
      {error && <div style={{ color: "red" }}>{error}</div>}
      {showModal && (
        <KycModal
          sdk={sdk}
          onClose={() => setShowModal(false)}
        />
      )}
    </div>
  );
}
```

What users see in the modal:
- Face capture step (with QR to switch to mobile)
- Document step with CNIC/Passport selector; if an upload fails, an "Upload again" button appears so users can retry immediately
- Status step showing the verification outcome







### Turnkey Flow (optional)
If you prefer an out-of-the-box flow with a start button, init form, terms screen, and modal managed for you:

```tsx
import { KycFlow } from "astra-sdk-astra";
import "astra-sdk-astra/kycModal.css";

function App() {
  return (
    <KycFlow serverKey="your-server-key" startLabel="Start KYC" />
  );
}
```

### Button → Init Form → Modal (previous structure)
If you want a simple "Start KYC" button that opens the init form first and, on success, opens the KYC modal:

```tsx
import { useState } from "react";
import { VerificationSDK, KycInitForm, KycModal } from "astra-sdk-astra";
import "astra-sdk-astra/kycModal.css";

const sdk = new VerificationSDK({ serverKey: "your-server-key" });

function App() {
  const [showInit, setShowInit] = useState(false);
  const [showModal, setShowModal] = useState(false);

  return (
    <div>
      <button
        type="button"
        className="kyc-input"
        style={{
          background: "linear-gradient(90deg, #FF8A00 0%, #FF3D77 100%)",
          color: "#fff",
          border: "none",
          borderRadius: 8,
          padding: 10,
          cursor: "pointer"
        }}
        onClick={() => setShowInit(true)}
      >
        Start KYC
      </button>

      {showInit && (
        <div className="kyc-backdrop">
          <div className="kyc-container">
            <KycInitForm
              sdk={sdk}
              onStarted={() => {
                setShowInit(false);
                setShowModal(true);
              }}
            />
          </div>
        </div>
      )}

      {showModal && (
        <KycModal sdk={sdk} onClose={() => setShowModal(false)} />
      )}
    </div>
  );
}
```

## API Reference

### VerificationSDK

#### Constructor
```tsx
new VerificationSDK({ serverKey: string })
```

#### Methods

##### `init(options: InitOptions): Promise<InitResponse>`
Initialize a new KYC session.

```tsx
interface InitOptions {
  reference: string;
  email: string;
  callback_url: string;
  redirect_url: string;
  device_type?: "WEB" | "MOBILE";
}
```

##### `uploadFace(faceBlob: Blob): Promise<any>`
Upload face capture image.

##### `uploadDocument(docBlob: Blob, type: string): Promise<any>`
Upload document (CNIC or PASSPORT).

##### `getStatus(): Promise<any>`
Get current session status.

### Components

#### KycModal
Main KYC modal component for web usage.

```tsx
interface KycModalProps {
  sdk: VerificationSDK;
  onClose: () => void;
  classNames?: KycModalClassNames;
  styles?: KycModalStyleOverrides;
}
```







### CSS Classes
- `kyc-backdrop` - Modal backdrop
- `kyc-container` - Modal container
- `kyc-close` - Close button
- `kyc-title` - Step titles
- `kyc-input` - Input elements
- `kyc-status` - Status display
- `kyc-error` - Error messages
- `kyc-loading` - Loading indicators

### Custom Styling
```tsx
<KycModal
  sdk={sdk}
  onClose={() => setShowModal(false)}
  styles={{
    backdrop: { backgroundColor: "rgba(0,0,0,0.7)" },
    container: { maxWidth: 520 },
    title: { color: "#1f2937" }
  }}
  classNames={{
    container: "my-custom-modal",
    title: "my-custom-title"
  }}
/>
```

## Error Handling

The SDK handles various error scenarios:

- **Session Expired**: Automatic detection and user notification
- **Face Already Registered**: Graceful handling with user feedback
- **Document Already Exists**: Prevents duplicate uploads
- **Network Errors**: Proper error messages and retry options

## Browser Support

- **Web**: Modern browsers with camera support


## TypeScript

Full TypeScript support with exported types:

```tsx
import type { 
  InitOptions, 
  InitResponse, 
  InitResponseData 
} from "astra-sdk-astra";
```

## Development

### Building the SDK
```bash
npm run build:lib
```

### Testing
```bash
npm test
```

## License

MIT License - see LICENSE file for details.

## Support

For support and questions, please contact the development team.