@zenith/liveness-sdk

A React component SDK that wraps the Rekognition Face Liveness flow. Third-party consumers integrate with this SDK only — no direct API calls, no much configuration needed.

Installation

npm install @zenith/liveness-sdk

Peer dependencies (your app must already have these):

npm install react react-dom


## Quick Start

```tsx
import { ZenithLivenessCheck } from '@zenith/liveness-sdk';
import '@zenith/liveness-sdk/style.css';
import type { LivenessResult, LivenessError } from '@zenith/liveness-sdk';

function MyLivenessPage() {
  const handleSuccess = (result: LivenessResult) => {
    console.log('Liveness passed:', result.isSuccess);
    // result: { isSuccess: true, isFailure: false, error: { code: "", name: "" } }
  };

  const handleError = (error: LivenessError) => {
    console.error('Liveness failed:', error.message);
    // error: { message: string, code?: string, statusCode?: number }
  };

  return (
    <ZenithLivenessCheck
      credentials={{
        username: "your-username",
        password: "your-password",
      }}
      sessionData={{
        identificationNumber: "12345678901",
        idType: "bvn",
        channel: "accountOpening",
      }}
      onSuccess={handleSuccess}
      onError={handleError}
    />
  );
}

Props

ZenithLivenessCheckProps

| Prop | Type | Required | Description | |------|------|----------|-------------| | credentials | BasicAuthCredentials | ✅ | { username, password } for API auth | | sessionData | SessionData | ✅ | Identification and channel data | | onSuccess | (result: LivenessResult) => void | ✅ | Called on successful verification | | onError | (error: LivenessError) => void | ❌ | Called on any error | | onSessionCreated | (sessionId: string) => void | ❌ | Called when session is created | | onCancel | () => void | ❌ | Called when user cancels | | components | CustomComponents | ❌ | Override default UI components |

SessionData

| Field | Type | Required | Description | |-------|------|----------|-------------| | identificationNumber | string | ✅ | e.g. BVN number | | idType | string | ✅ | e.g. "bvn" | | channel | string | ✅ | e.g. "accountOpening" | | action | string | ❌ | Defaults to "" |

LivenessResult

{
  isSuccess: boolean;
  isFailure: boolean;
  error: {
    code: string;
    name: string;
  };
}

LivenessError

{
  message: string;    // Human-readable error message
  code?: string;      // Error code from API
  statusCode?: number; // HTTP status code
}

Custom Components

Override the default loading, success, and error views:

import type { SuccessViewProps, ErrorViewProps } from '@zenith/liveness-sdk';

const MyLoader = () => <div>Loading...</div>;

const MySuccess = ({ result, onProceed }: SuccessViewProps) => (
  <div>
    <p>Verified!</p>
    <button onClick={onProceed}>Continue</button>
  </div>
);

const MyError = ({ error, onRetry }: ErrorViewProps) => (
  <div>
    <p>Error: {error.message}</p>
    <button onClick={onRetry}>Try Again</button>
  </div>
);

<ZenithLivenessCheck
  credentials={...}
  sessionData={...}
  onSuccess={handleSuccess}
  components={{
    Loading: MyLoader,
    Success: MySuccess,
    Error: MyError,
  }}
/>

How It Works

1. Session Creation — On mount, the SDK calls the internal API (POST /create-session) with the consumer's identification data and Basic Auth credentials.
2. Liveness Detection — The FaceLivenessDetector component renders a camera feed and runs the liveness challenge (oval alignment + freshness color sequence).
3. Face Verification — Once the detector completes, the SDK automatically calls POST /verify-face with the session ID.
4. Result — The onSuccess callback fires with the verification result, or onError fires with error details.

Building

npm run build        # TypeScript check + Vite library build
npm run typecheck    # TypeScript only

Distribution

Option 1: npm pack (share as .tgz)

# Build and pack the SDK
npm run build
npm pack

# In consumer app:
npm install ./path/to/zenith-liveness-sdk-1.0.0.tgz

Option 2: npm link (local development)

# In the SDK directory:
npm link

# In the consumer app:
npm link @zenith/liveness-sdk

Option 3: file: dependency (monorepo / local testing)

In the consumer app's package.json:

{
  "dependencies": {
    "@zenith/liveness-sdk": "file:../ZenithLivenessSDK"
  }
}

Local Development with Test App

A standalone test app is included at test-app/ for development and testing:

# 1. Build the SDK first
npm run build

# 2. Install test app dependencies
cd test-app
npm install

# 3. Run the test app
npm run dev

The test app provides a form to enter credentials and session data, then renders the <ZenithLivenessCheck /> component with a live event log.