kreltix-react-native-sdk 0.1.0

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "kreltix-react-native-sdk",
+  "version": "0.1.0",
+  "description": "Kreltix Liveness & Face-Match SDK for React Native (Expo)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "expo-camera": ">=16.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.74.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-native": "^0.74.0",
+    "typescript": "^5.3.0"
+  },
+  "keywords": ["kreltix", "liveness", "face", "verification", "kyc", "react-native", "expo"],
+  "license": "MIT"
+}

package/src/KreltixSDK.ts

@@ -0,0 +1,114 @@
+import { ApiClient } from './api/client';
+import { KreltixError } from './errors/KreltixError';
+import type {
+  SDKConfig,
+  SDKOptions,
+  FaceMatchOptions,
+  FaceMatchResult,
+  CombinedFaceMatchOptions,
+  CombinedFaceMatchResult,
+} from './api/types';
+
+const DEFAULT_BASE_URL   = 'https://api.kreltix.com';
+const DEFAULT_TIMEOUT    = 10_000;
+const DEFAULT_MAX_RETRIES = 2;
+
+/**
+ * KreltixSDK — programmatic access to the Kreltix API without camera UI.
+ *
+ * For camera-based liveness verification, use <KreltixLivenessView> or useLiveness().
+ *
+ * @example
+ * const sdk = KreltixSDK.initialize('pk_live_...');
+ * const result = await sdk.faceMatch({ idCardImage: '...', selfieImage: '...' });
+ */
+export class KreltixSDK {
+  private apiClient: ApiClient;
+
+  private constructor(private readonly config: SDKConfig) {
+    this.apiClient = new ApiClient(config);
+  }
+
+  static initialize(publicKey: string, options?: SDKOptions): KreltixSDK {
+    if (!publicKey.startsWith('pk_live_')) {
+      throw new KreltixError(
+        "Invalid key. Use a public key (pk_live_...) for the client-side SDK.",
+        'INVALID_KEY',
+      );
+    }
+    return new KreltixSDK({
+      publicKey,
+      baseUrl:    options?.baseUrl    ?? DEFAULT_BASE_URL,
+      timeout:    options?.timeout    ?? DEFAULT_TIMEOUT,
+      maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES,
+    });
+  }
+
+  /**
+   * Compare two face images. No camera session required.
+   * Useful for one-shot face verification when you already have both images.
+   */
+  async faceMatch(options: FaceMatchOptions): Promise<FaceMatchResult> {
+    const raw = await this.apiClient.verifyFace(
+      options.idCardImage,
+      options.selfieImage,
+      options.metadata,
+    );
+    return {
+      requestId: raw.request_id,
+      match:     raw.match,
+      distance:  raw.distance,
+      verified:  raw.verified,
+      status:    raw.status,
+      error:     raw.error,
+    };
+  }
+
+  /**
+   * Run liveness + face match in a single API call without a camera session.
+   * For standard tier: provide `image` (selfie base64 or URL).
+   * For premium tier: provide `video` or `videoUrl` + `challenge`.
+   */
+  async combinedFaceMatch(options: CombinedFaceMatchOptions): Promise<CombinedFaceMatchResult> {
+    const { idCardImage, tier = 'standard', metadata, image, video, videoUrl, challenge } = options;
+
+    const body: Record<string, unknown> = {
+      tier,
+      id_card_image: idCardImage,
+      ...(metadata ? { metadata } : {}),
+    };
+
+    if (tier === 'standard') {
+      if (!image) throw new KreltixError('Standard tier requires an `image`.', 'VALIDATION_ERROR');
+      body.image = image;
+    } else {
+      if (!video && !videoUrl) {
+        throw new KreltixError('Premium tier requires `video` or `videoUrl`.', 'VALIDATION_ERROR');
+      }
+      if (!challenge) {
+        throw new KreltixError('Premium tier requires a `challenge`.', 'VALIDATION_ERROR');
+      }
+      if (video)    body.video     = video;
+      if (videoUrl) body.video_url = videoUrl;
+      body.challenge = challenge;
+    }
+
+    const raw = await this.apiClient.combinedCheck(body);
+    return {
+      requestId:           raw.request_id,
+      tier:                raw.tier,
+      isLive:              raw.is_live,
+      livenessConfidence:  raw.liveness_confidence,
+      challengeCompleted:  raw.challenge_completed,
+      challengeType:       raw.challenge_type,
+      faceChecked:         raw.face_checked,
+      faceMatch:           raw.face_match,
+      faceDistance:        raw.face_distance,
+      verified:            raw.verified,
+      indicators:          raw.indicators,
+      recommendation:      raw.recommendation,
+      error:               raw.error,
+      chargeAmount:        raw.charge_amount,
+    };
+  }
+}

package/src/api/client.ts

@@ -0,0 +1,136 @@
+import {
+  KreltixAuthError,
+  KreltixInsufficientFundsError,
+  KreltixNetworkError,
+  KreltixServerError,
+  KreltixSessionExpiredError,
+  KreltixValidationError,
+} from '../errors/KreltixError';
+import { withRetry } from '../utils/retry';
+import type {
+  SDKConfig,
+  CreateSessionResponse,
+  SubmitVerificationResponse,
+  VerifyFaceApiResponse,
+  CombinedCheckApiResponse,
+} from './types';
+
+export class ApiClient {
+  private config: SDKConfig;
+
+  constructor(config: SDKConfig) {
+    this.config = config;
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: Record<string, unknown>,
+    timeoutOverride?: number,
+  ): Promise<T> {
+    const url = `${this.config.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(
+      () => controller.abort(),
+      timeoutOverride ?? this.config.timeout,
+    );
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': this.config.publicKey,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      if (response.ok) {
+        return (await response.json()) as T;
+      }
+
+      const errorBody = await response
+        .json()
+        .catch(() => ({ detail: response.statusText }));
+      const detail = (errorBody as { detail?: string }).detail ?? response.statusText;
+
+      switch (response.status) {
+        case 401:
+        case 403:
+          throw new KreltixAuthError(detail);
+        case 402:
+          throw new KreltixInsufficientFundsError(detail);
+        case 409:
+          throw new KreltixValidationError(detail);
+        case 410:
+          throw new KreltixSessionExpiredError(detail);
+        case 429:
+          throw new KreltixServerError('Rate limit exceeded. Try again shortly.');
+        default:
+          if (response.status >= 500) throw new KreltixServerError(detail);
+          throw new KreltixValidationError(detail);
+      }
+    } catch (err) {
+      if (err instanceof TypeError || (err as Error).name === 'AbortError') {
+        throw new KreltixNetworkError(
+          (err as Error).name === 'AbortError' ? 'Request timed out' : 'Network request failed',
+        );
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async createSession(metadata?: Record<string, unknown>): Promise<CreateSessionResponse> {
+    return withRetry(
+      () => this.request<CreateSessionResponse>('POST', '/api/v1/sessions/', {
+        metadata: metadata ?? null,
+      }),
+      this.config.maxRetries,
+    );
+  }
+
+  // No retry — sessions are single-use; a timed-out upload that retried would
+  // re-submit an already-consumed session token and cause a 409.
+  async submitVerification(
+    sessionId: string,
+    sessionToken: string,
+    videos: string[],
+  ): Promise<SubmitVerificationResponse> {
+    return this.request<SubmitVerificationResponse>(
+      'POST',
+      `/api/v1/sessions/${sessionId}/verify`,
+      { session_token: sessionToken, videos },
+      60_000, // 60s — multi-video upload can be slow on mobile
+    );
+  }
+
+  async verifyFace(
+    idCardImage: string,
+    selfieImage: string,
+    metadata?: Record<string, unknown>,
+  ): Promise<VerifyFaceApiResponse> {
+    return withRetry(
+      () => this.request<VerifyFaceApiResponse>('POST', '/api/v1/verification/verify-face', {
+        id_card_image: idCardImage,
+        selfie_image: selfieImage,
+        ...(metadata ? { metadata } : {}),
+      }),
+      this.config.maxRetries,
+    );
+  }
+
+  async combinedCheck(body: Record<string, unknown>): Promise<CombinedCheckApiResponse> {
+    return withRetry(
+      () => this.request<CombinedCheckApiResponse>(
+        'POST',
+        '/api/v1/verification/combined-check',
+        body,
+        60_000,
+      ),
+      this.config.maxRetries,
+    );
+  }
+}

package/src/api/types.ts

@@ -0,0 +1,196 @@
+// ── SDK config ──────────────────────────────────────────────────────────────────
+
+export interface SDKConfig {
+  publicKey: string;
+  baseUrl: string;
+  timeout: number;
+  maxRetries: number;
+}
+
+export interface SDKOptions {
+  /** Override the default Kreltix API base URL. */
+  baseUrl?: string;
+  /** Request timeout in ms. Default: 10 000. */
+  timeout?: number;
+  /** Max retries for retryable errors. Default: 2. */
+  maxRetries?: number;
+}
+
+// ── Raw API response shapes ──────────────────────────────────────────────────────
+
+export interface CreateSessionResponse {
+  session_id: string;
+  session_token: string;
+  challenges: string[];
+  instructions: string[];
+  expires_at: string;
+}
+
+export interface ChallengeStepResult {
+  challenge: string;
+  completed: boolean;
+  indicators: Record<string, unknown> | null;
+}
+
+export interface SubmitVerificationResponse {
+  session_id: string;
+  is_live: boolean;
+  confidence: number;
+  challenges_completed: ChallengeStepResult[];
+  all_challenges_passed: boolean;
+  indicators: Record<string, unknown> | null;
+  recommendation: string | null;
+  error: string | null;
+  charge_amount: number | null;
+  captured_frame: string | null;
+}
+
+export interface VerifyFaceApiResponse {
+  request_id: string | null;
+  match: boolean;
+  distance: number;
+  verified: boolean;
+  status: string;
+  error: string | null;
+}
+
+export interface CombinedCheckApiResponse {
+  request_id: string | null;
+  tier: string;
+  is_live: boolean;
+  liveness_confidence: number;
+  challenge_completed: boolean | null;
+  challenge_type: string | null;
+  face_checked: boolean;
+  face_match: boolean | null;
+  face_distance: number | null;
+  verified: boolean;
+  indicators: Record<string, unknown> | null;
+  recommendation: string | null;
+  error: string | null;
+  charge_amount: number | null;
+}
+
+// ── Public result types ──────────────────────────────────────────────────────────
+
+export interface LivenessResult {
+  sessionId: string;
+  isLive: boolean;
+  confidence: number;
+  challengeResults: ChallengeStepResult[];
+  allChallengesPassed: boolean;
+  recommendation: string | null;
+  error: string | null;
+  /** Base64 JPEG of the sharpest frame captured during liveness. Null if not available. */
+  capturedFrame: string | null;
+}
+
+export interface CombinedCheckResult {
+  sessionId: string;
+  isLive: boolean;
+  livenessConfidence: number;
+  allChallengesPassed: boolean;
+  challengeResults: ChallengeStepResult[];
+  recommendation: string | null;
+  faceChecked: boolean;
+  faceMatch: boolean | null;
+  faceDistance: number | null;
+  /** True only when liveness passed AND face matches the id card. */
+  verified: boolean;
+  capturedFrame: string | null;
+}
+
+export interface FaceMatchResult {
+  requestId: string | null;
+  match: boolean;
+  distance: number;
+  verified: boolean;
+  status: string;
+  error: string | null;
+}
+
+export interface CombinedFaceMatchResult {
+  requestId: string | null;
+  tier: string;
+  isLive: boolean;
+  livenessConfidence: number;
+  challengeCompleted: boolean | null;
+  challengeType: string | null;
+  faceChecked: boolean;
+  faceMatch: boolean | null;
+  faceDistance: number | null;
+  verified: boolean;
+  indicators: Record<string, unknown> | null;
+  recommendation: string | null;
+  error: string | null;
+  chargeAmount: number | null;
+}
+
+// ── Progress & events ────────────────────────────────────────────────────────────
+
+export type ProgressStage =
+  | 'permission_request'
+  | 'session_created'
+  | 'camera_ready'
+  | 'recording'
+  | 'uploading'
+  | 'complete';
+
+export interface ProgressEvent {
+  stage: ProgressStage;
+  message: string;
+  /** Index of the challenge currently being recorded (0-based). */
+  challengeIndex?: number;
+  /** Total number of challenges in this session. */
+  totalChallenges?: number;
+}
+
+// ── Options types ────────────────────────────────────────────────────────────────
+
+export type LivenessTier = 'standard' | 'premium';
+export type ChallengeType = 'blink' | 'turn_left' | 'turn_right' | 'smile';
+
+export interface LivenessOptions {
+  /** Custom metadata attached to the Kreltix session. */
+  metadata?: Record<string, unknown>;
+  /** How long (ms) each challenge video is recorded. Default: 4000. */
+  recordingDurationMs?: number;
+  /** Pause (ms) between showing the challenge instruction and starting recording. Default: 2000. */
+  guidePauseMs?: number;
+  onSessionCreated?: (session: CreateSessionResponse) => void;
+  onChallengeStarted?: (challenge: string, index: number, total: number) => void;
+  onProgress?: (event: ProgressEvent) => void;
+  onError?: (error: Error) => void;
+}
+
+export interface CombinedCheckOptions extends LivenessOptions {
+  /**
+   * Reference face to match against (the employee's enrolled photo).
+   * Accepts a base64 string (with or without data URI prefix) or a URL.
+   */
+  idCardImage: string;
+}
+
+export interface FaceMatchOptions {
+  /** Reference face (e.g. employee profile photo). Base64 or URL. */
+  idCardImage: string;
+  /** Selfie to compare against. Base64 or URL. */
+  selfieImage: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CombinedFaceMatchOptions {
+  /** Reference face. Base64 or URL. */
+  idCardImage: string;
+  /** Liveness tier. Default: "standard". */
+  tier?: LivenessTier;
+  /** Selfie image for standard tier. */
+  image?: string;
+  /** Base64-encoded video for premium tier. */
+  video?: string;
+  /** Publicly accessible video URL for premium tier. */
+  videoUrl?: string;
+  /** Challenge type — required for premium tier. */
+  challenge?: ChallengeType;
+  metadata?: Record<string, unknown>;
+}

package/src/camera/CameraRecorder.ts

@@ -0,0 +1,46 @@
+import type { RefObject } from 'react';
+import type { CameraView } from 'expo-camera';
+
+import { KreltixCameraError } from '../errors/KreltixError';
+import { videoUriToBase64 } from '../utils/video';
+
+export interface RecordingOptions {
+  /** Maximum recording duration in seconds. Default: 4. */
+  maxDurationSeconds?: number;
+}
+
+/**
+ * Thin wrapper around expo-camera's CameraView that records one video clip
+ * and converts it to a base64 string ready for the Kreltix API.
+ */
+export class CameraRecorder {
+  private ref: RefObject<CameraView | null>;
+
+  constructor(cameraRef: RefObject<CameraView | null>) {
+    this.ref = cameraRef;
+  }
+
+  /**
+   * Record a single video clip and return it as a base64 string.
+   * The camera must already be mounted and permissions granted.
+   */
+  async record(options: RecordingOptions = {}): Promise<string> {
+    const { maxDurationSeconds = 4 } = options;
+    const camera = this.ref.current;
+    if (!camera) {
+      throw new KreltixCameraError('CameraView ref is not attached — make sure the camera is mounted before recording.');
+    }
+
+    const result = await camera.recordAsync({ maxDuration: maxDurationSeconds });
+    if (!result?.uri) {
+      throw new KreltixCameraError('Recording produced no video URI.');
+    }
+
+    return videoUriToBase64(result.uri);
+  }
+
+  /** Stop an in-progress recording early. */
+  stopRecording(): void {
+    this.ref.current?.stopRecording();
+  }
+}

package/src/errors/KreltixError.ts

@@ -0,0 +1,60 @@
+export class KreltixError extends Error {
+  code: string;
+  isRetryable: boolean;
+
+  constructor(message: string, code: string, isRetryable = false) {
+    super(message);
+    this.name = 'KreltixError';
+    this.code = code;
+    this.isRetryable = isRetryable;
+  }
+}
+
+export class KreltixNetworkError extends KreltixError {
+  constructor(message = 'Network request failed') {
+    super(message, 'NETWORK_ERROR', true);
+    this.name = 'KreltixNetworkError';
+  }
+}
+
+export class KreltixAuthError extends KreltixError {
+  constructor(message = 'Invalid or expired API key') {
+    super(message, 'AUTH_ERROR', false);
+    this.name = 'KreltixAuthError';
+  }
+}
+
+export class KreltixSessionExpiredError extends KreltixError {
+  constructor(message = 'Liveness session expired') {
+    super(message, 'SESSION_EXPIRED', false);
+    this.name = 'KreltixSessionExpiredError';
+  }
+}
+
+export class KreltixCameraError extends KreltixError {
+  constructor(message = 'Camera not available or permission denied') {
+    super(message, 'CAMERA_ERROR', false);
+    this.name = 'KreltixCameraError';
+  }
+}
+
+export class KreltixServerError extends KreltixError {
+  constructor(message = 'Server error') {
+    super(message, 'SERVER_ERROR', true);
+    this.name = 'KreltixServerError';
+  }
+}
+
+export class KreltixValidationError extends KreltixError {
+  constructor(message = 'Validation error') {
+    super(message, 'VALIDATION_ERROR', false);
+    this.name = 'KreltixValidationError';
+  }
+}
+
+export class KreltixInsufficientFundsError extends KreltixError {
+  constructor(message = 'Insufficient wallet balance') {
+    super(message, 'INSUFFICIENT_FUNDS', false);
+    this.name = 'KreltixInsufficientFundsError';
+  }
+}

package/src/hooks/useLiveness.ts

@@ -0,0 +1,248 @@
+import { useRef, useState, useCallback, type RefObject } from 'react';
+import type { CameraView } from 'expo-camera';
+import { useCameraPermissions, useMicrophonePermissions } from 'expo-camera';
+import { ApiClient } from '../api/client';
+import { SessionManager } from '../session/SessionManager';
+import { CameraRecorder } from '../camera/CameraRecorder';
+import { KreltixCameraError } from '../errors/KreltixError';
+import type {
+  SDKConfig,
+  LivenessOptions,
+  LivenessResult,
+  CombinedCheckOptions,
+  CombinedCheckResult,
+  CreateSessionResponse,
+  ProgressEvent,
+} from '../api/types';
+
+export type LivenessPhase =
+  | 'idle'
+  | 'requesting_permissions'
+  | 'creating_session'
+  | 'challenge'      // guide shown, recording starts automatically after guidePauseMs
+  | 'recording'      // camera recording in progress
+  | 'uploading'      // videos submitted to Kreltix
+  | 'complete'
+  | 'error';
+
+export interface UseLivenessState {
+  phase: LivenessPhase;
+  /** Current challenge index (0-based). */
+  challengeIndex: number;
+  /** Challenge key for the current step, e.g. "blink". */
+  currentChallenge: string;
+  /** Human-readable instruction for the current challenge. */
+  currentInstruction: string;
+  /** Total number of challenges in this session. */
+  totalChallenges: number;
+  /** Countdown seconds remaining during recording phase. */
+  countdown: number;
+  /** Set when phase === 'complete'. */
+  result: LivenessResult | null;
+  combinedResult: CombinedCheckResult | null;
+  /** Set when phase === 'error'. */
+  error: Error | null;
+  /** Ref to attach to the <CameraView> component. */
+  cameraRef: RefObject<CameraView | null>;
+}
+
+export interface UseLivenessActions {
+  /** Start the liveness flow. Idempotent if already running. */
+  start(options?: LivenessOptions): Promise<void>;
+  /** Start liveness + face match combined check. */
+  startCombined(options: CombinedCheckOptions): Promise<void>;
+  /** Reset to idle state so the flow can be restarted. */
+  reset(): void;
+}
+
+const DEFAULT_RECORDING_MS = 4000;
+const DEFAULT_GUIDE_PAUSE_MS = 2000;
+
+export function useLiveness(config: SDKConfig): UseLivenessState & UseLivenessActions {
+  const cameraRef = useRef<CameraView>(null);
+  const [camPerm, requestCamPerm] = useCameraPermissions();
+  const [micPerm, requestMicPerm] = useMicrophonePermissions();
+
+  const [phase, setPhase] = useState<LivenessPhase>('idle');
+  const [challengeIndex, setChallengeIndex] = useState(0);
+  const [currentChallenge, setCurrentChallenge] = useState('');
+  const [currentInstruction, setCurrentInstruction] = useState('');
+  const [totalChallenges, setTotalChallenges] = useState(0);
+  const [countdown, setCountdown] = useState(0);
+  const [result, setResult] = useState<LivenessResult | null>(null);
+  const [combinedResult, setCombinedResult] = useState<CombinedCheckResult | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+
+  function reset() {
+    setPhase('idle');
+    setChallengeIndex(0);
+    setCurrentChallenge('');
+    setCurrentInstruction('');
+    setTotalChallenges(0);
+    setCountdown(0);
+    setResult(null);
+    setCombinedResult(null);
+    setError(null);
+  }
+
+  const runFlow = useCallback(async (options: LivenessOptions, idCardImage?: string) => {
+    const {
+      metadata,
+      recordingDurationMs = DEFAULT_RECORDING_MS,
+      guidePauseMs = DEFAULT_GUIDE_PAUSE_MS,
+      onSessionCreated,
+      onChallengeStarted,
+      onProgress,
+      onError,
+    } = options;
+
+    const notify = (event: ProgressEvent) => onProgress?.(event);
+    const recordingSeconds = Math.round(recordingDurationMs / 1000);
+
+    try {
+      // 1. Permissions
+      setPhase('requesting_permissions');
+      notify({ stage: 'permission_request', message: 'Requesting camera permissions…' });
+
+      const cam = camPerm?.granted ? camPerm : await requestCamPerm();
+      const mic = micPerm?.granted ? micPerm : await requestMicPerm();
+      if (!cam?.granted || !mic?.granted) {
+        throw new KreltixCameraError('Camera and microphone permissions are required.');
+      }
+
+      // 2. Create session
+      setPhase('creating_session');
+      notify({ stage: 'session_created', message: 'Creating verification session…' });
+
+      const apiClient = new ApiClient(config);
+      const sessionManager = new SessionManager(apiClient);
+      const session: CreateSessionResponse = await sessionManager.createSession(metadata);
+      onSessionCreated?.(session);
+
+      const { challenges, instructions } = session;
+      setTotalChallenges(challenges.length);
+      notify({
+        stage: 'session_created',
+        message: `Session ready — ${challenges.length} challenge${challenges.length > 1 ? 's' : ''}`,
+        totalChallenges: challenges.length,
+      });
+
+      // 3. Record each challenge
+      const recorder = new CameraRecorder(cameraRef);
+      const videos: string[] = [];
+
+      for (let i = 0; i < challenges.length; i++) {
+        const challenge = challenges[i];
+        const instruction = instructions[i] ?? challenge;
+
+        // Show challenge guide
+        setChallengeIndex(i);
+        setCurrentChallenge(challenge);
+        setCurrentInstruction(instruction);
+        setPhase('challenge');
+        onChallengeStarted?.(challenge, i, challenges.length);
+        notify({
+          stage: 'recording',
+          message: `Step ${i + 1}/${challenges.length}: ${challenge}`,
+          challengeIndex: i,
+          totalChallenges: challenges.length,
+        });
+
+        // Guide pause so the user can read the instruction
+        await new Promise((resolve) => setTimeout(resolve, guidePauseMs));
+
+        // Start recording + countdown
+        setPhase('recording');
+        setCountdown(recordingSeconds);
+        const tick = setInterval(() => {
+          setCountdown((prev: number) => Math.max(0, prev - 1));
+        }, 1000);
+
+        try {
+          const base64 = await recorder.record({ maxDurationSeconds: recordingSeconds });
+          videos.push(base64);
+        } finally {
+          clearInterval(tick);
+        }
+
+        // Brief inter-challenge pause
+        if (i < challenges.length - 1) {
+          await new Promise((resolve) => setTimeout(resolve, 600));
+        }
+      }
+
+      // 4. Upload and verify
+      setPhase('uploading');
+      notify({ stage: 'uploading', message: 'Uploading videos…' });
+
+      const raw = await sessionManager.submitVerification(videos);
+
+      // 5. Map result
+      if (idCardImage) {
+        // Combined check result
+        const cr: CombinedCheckResult = {
+          sessionId:           raw.session_id,
+          isLive:              raw.is_live,
+          livenessConfidence:  raw.confidence,
+          allChallengesPassed: raw.all_challenges_passed,
+          challengeResults:    raw.challenges_completed,
+          recommendation:      raw.recommendation,
+          faceChecked:         (raw as unknown as { face_checked?: boolean }).face_checked ?? false,
+          faceMatch:           (raw as unknown as { face_match?: boolean | null }).face_match ?? null,
+          faceDistance:        (raw as unknown as { face_distance?: number | null }).face_distance ?? null,
+          verified:            (raw as unknown as { verified?: boolean }).verified ?? false,
+          capturedFrame:       raw.captured_frame,
+        };
+        setCombinedResult(cr);
+      } else {
+        const lr: LivenessResult = {
+          sessionId:           raw.session_id,
+          isLive:              raw.is_live,
+          confidence:          raw.confidence,
+          challengeResults:    raw.challenges_completed,
+          allChallengesPassed: raw.all_challenges_passed,
+          recommendation:      raw.recommendation,
+          error:               raw.error,
+          capturedFrame:       raw.captured_frame,
+        };
+        setResult(lr);
+      }
+
+      setPhase('complete');
+      notify({ stage: 'complete', message: 'Verification complete' });
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      setError(e);
+      setPhase('error');
+      onError?.(e);
+    }
+  }, [config, camPerm, micPerm, requestCamPerm, requestMicPerm]);
+
+  const start = useCallback(
+    async (options: LivenessOptions = {}) => runFlow(options),
+    [runFlow],
+  );
+
+  const startCombined = useCallback(
+    async (options: CombinedCheckOptions) => runFlow(options, options.idCardImage),
+    [runFlow],
+  );
+
+  return {
+    // State
+    phase,
+    challengeIndex,
+    currentChallenge,
+    currentInstruction,
+    totalChallenges,
+    countdown,
+    result,
+    combinedResult,
+    error,
+    cameraRef,
+    // Actions
+    start,
+    startCombined,
+    reset,
+  };
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+// Main SDK class (programmatic, no UI)
+export { KreltixSDK } from './KreltixSDK';
+
+// React Native component — the primary integration point
+export { KreltixLivenessView } from './ui/LivenessView';
+export type { KreltixLivenessViewProps, LivenessViewProps, CombinedCheckViewProps } from './ui/LivenessView';
+
+// React hook — for custom UI with SDK-managed session + recording
+export { useLiveness } from './hooks/useLiveness';
+export type { UseLivenessState, UseLivenessActions, LivenessPhase } from './hooks/useLiveness';
+
+// Types
+export type {
+  SDKConfig,
+  SDKOptions,
+  LivenessOptions,
+  CombinedCheckOptions,
+  FaceMatchOptions,
+  CombinedFaceMatchOptions,
+  LivenessResult,
+  CombinedCheckResult,
+  FaceMatchResult,
+  CombinedFaceMatchResult,
+  ChallengeStepResult,
+  CreateSessionResponse,
+  SubmitVerificationResponse,
+  ProgressEvent,
+  ProgressStage,
+  LivenessTier,
+  ChallengeType,
+} from './api/types';
+
+// Errors
+export {
+  KreltixError,
+  KreltixNetworkError,
+  KreltixAuthError,
+  KreltixSessionExpiredError,
+  KreltixCameraError,
+  KreltixServerError,
+  KreltixValidationError,
+  KreltixInsufficientFundsError,
+} from './errors/KreltixError';
+
+// Lower-level building blocks (for custom integrations)
+export { CameraRecorder } from './camera/CameraRecorder';
+export { SessionManager } from './session/SessionManager';
+export { ApiClient } from './api/client';
+export { videoUriToBase64 } from './utils/video';
+export { withRetry } from './utils/retry';

package/src/session/SessionManager.ts

@@ -0,0 +1,37 @@
+import { ApiClient } from '../api/client';
+import type { CreateSessionResponse, SubmitVerificationResponse } from '../api/types';
+
+export class SessionManager {
+  private client: ApiClient;
+  private currentSession: CreateSessionResponse | null = null;
+
+  constructor(client: ApiClient) {
+    this.client = client;
+  }
+
+  async createSession(metadata?: Record<string, unknown>): Promise<CreateSessionResponse> {
+    this.currentSession = await this.client.createSession(metadata);
+    return this.currentSession;
+  }
+
+  async submitVerification(videos: string[]): Promise<SubmitVerificationResponse> {
+    if (!this.currentSession) {
+      throw new Error('No active session. Call createSession() first.');
+    }
+    const result = await this.client.submitVerification(
+      this.currentSession.session_id,
+      this.currentSession.session_token,
+      videos,
+    );
+    this.currentSession = null;
+    return result;
+  }
+
+  getCurrentSession(): CreateSessionResponse | null {
+    return this.currentSession;
+  }
+
+  clearSession(): void {
+    this.currentSession = null;
+  }
+}

package/src/ui/LivenessView.tsx

@@ -0,0 +1,313 @@
+import React, { useEffect } from 'react';
+import {
+  View,
+  Text,
+  TouchableOpacity,
+  ActivityIndicator,
+  StyleSheet,
+  ViewStyle,
+} from 'react-native';
+import { CameraView } from 'expo-camera';
+import { useLiveness, type LivenessPhase } from '../hooks/useLiveness';
+import type {
+  SDKConfig,
+  SDKOptions,
+  LivenessOptions,
+  LivenessResult,
+  CombinedCheckOptions,
+  CombinedCheckResult,
+} from '../api/types';
+
+// ── Challenge display labels ─────────────────────────────────────────────────
+
+const CHALLENGE_LABELS: Record<string, string> = {
+  blink:      'Blink your eyes once clearly',
+  turn_left:  'Slowly turn your head to the left',
+  turn_right: 'Slowly turn your head to the right',
+  smile:      'Smile visibly',
+};
+
+const CHALLENGE_EMOJI: Record<string, string> = {
+  blink:      '👁',
+  turn_left:  '←',
+  turn_right: '→',
+  smile:      '😊',
+};
+
+// ── Props ────────────────────────────────────────────────────────────────────
+
+interface BaseProps {
+  /** Kreltix public key (pk_live_...). */
+  publicKey: string;
+  /** Override the default API base URL. Useful for self-hosted Kreltix instances. */
+  baseUrl?: string;
+  /** Called when liveness verification completes successfully. */
+  onComplete?: (result: LivenessResult | CombinedCheckResult) => void;
+  /** Called when an error occurs. */
+  onError?: (error: Error) => void;
+  /** Custom metadata to attach to the Kreltix session. */
+  metadata?: Record<string, unknown>;
+  /** Override recording duration per challenge in ms. Default: 4000. */
+  recordingDurationMs?: number;
+  /** Override guide pause before recording in ms. Default: 2000. */
+  guidePauseMs?: number;
+  /** Style for the outer container. */
+  style?: ViewStyle;
+  /** Accent colour used for progress dots, buttons, and countdown badge. */
+  accentColor?: string;
+}
+
+export interface LivenessViewProps extends BaseProps {
+  mode: 'liveness';
+}
+
+export interface CombinedCheckViewProps extends BaseProps {
+  mode: 'combined';
+  /** Reference face to match against. Base64 or URL. */
+  idCardImage: string;
+}
+
+export type KreltixLivenessViewProps = LivenessViewProps | CombinedCheckViewProps;
+
+// ── Component ────────────────────────────────────────────────────────────────
+
+export function KreltixLivenessView(props: KreltixLivenessViewProps) {
+  const {
+    publicKey,
+    baseUrl = 'https://api.kreltix.com',
+    onComplete,
+    onError,
+    metadata,
+    recordingDurationMs,
+    guidePauseMs,
+    style,
+    accentColor = '#6C47FF',
+  } = props;
+
+  const config: SDKConfig = {
+    publicKey,
+    baseUrl,
+    timeout: 10_000,
+    maxRetries: 2,
+  };
+
+  const options: LivenessOptions = {
+    metadata,
+    recordingDurationMs,
+    guidePauseMs,
+    onError,
+  };
+
+  const sdk = useLiveness(config);
+
+  // Auto-start on mount
+  useEffect(() => {
+    if (props.mode === 'combined') {
+      sdk.startCombined({ ...options, idCardImage: props.idCardImage } as CombinedCheckOptions);
+    } else {
+      sdk.start(options);
+    }
+  }, []);
+
+  // Fire onComplete when done
+  useEffect(() => {
+    if (sdk.phase !== 'complete') return;
+    const r = sdk.combinedResult ?? sdk.result;
+    if (r) onComplete?.(r);
+  }, [sdk.phase]);
+
+  const accent = accentColor;
+
+  // ── Camera phases ────────────────────────────────────────────────────────
+
+  const isCamera = sdk.phase === 'challenge' || sdk.phase === 'recording';
+
+  if (isCamera) {
+    const label =
+      CHALLENGE_LABELS[sdk.currentChallenge] ?? sdk.currentInstruction;
+    const emoji = CHALLENGE_EMOJI[sdk.currentChallenge] ?? '●';
+    const isRecording = sdk.phase === 'recording';
+
+    return (
+      <View style={[s.root, style]}>
+        <CameraView
+          ref={sdk.cameraRef}
+          style={s.camera}
+          facing="front"
+          mode="video"
+        />
+
+        {/* Overlay */}
+        <View style={StyleSheet.absoluteFill} pointerEvents="none">
+          {/* Face oval guide */}
+          <View style={s.ovalContainer}>
+            <View style={[s.oval, isRecording && { borderColor: accent }]} />
+          </View>
+
+          {/* Progress dots */}
+          {sdk.totalChallenges > 1 && (
+            <View style={s.dotsRow}>
+              {Array.from({ length: sdk.totalChallenges }, (_, i) => (
+                <View
+                  key={i}
+                  style={[
+                    s.dot,
+                    i < sdk.challengeIndex && s.dotDone,
+                    i === sdk.challengeIndex && { ...s.dotActive, backgroundColor: accent },
+                  ]}
+                />
+              ))}
+            </View>
+          )}
+
+          {/* Instruction card */}
+          <View style={s.instructionCard}>
+            {isRecording && sdk.countdown > 0 && (
+              <View style={[s.countdownBadge, { backgroundColor: accent }]}>
+                <Text style={s.countdownNum}>{sdk.countdown}</Text>
+              </View>
+            )}
+            <Text style={s.challengeEmoji}>{emoji}</Text>
+            <Text style={s.instLabel}>
+              {isRecording ? 'RECORDING — HOLD STILL' : 'GET READY'}
+            </Text>
+            <Text style={s.instText}>{label}</Text>
+            {!isRecording && (
+              <Text style={s.instSub}>Recording starts automatically…</Text>
+            )}
+          </View>
+        </View>
+      </View>
+    );
+  }
+
+  // ── Spinner phases ───────────────────────────────────────────────────────
+
+  if (sdk.phase !== 'complete' && sdk.phase !== 'error') {
+    const msg: Record<LivenessPhase, string> = {
+      idle:                 '',
+      requesting_permissions: 'Requesting camera access…',
+      creating_session:    'Setting up verification…',
+      challenge:           '',
+      recording:           '',
+      uploading:           'Verifying identity…',
+      complete:            '',
+      error:               '',
+    };
+    return (
+      <View style={[s.root, s.center, style]}>
+        <ActivityIndicator size="large" color={accent} />
+        <Text style={s.statusText}>{msg[sdk.phase]}</Text>
+      </View>
+    );
+  }
+
+  // ── Error ────────────────────────────────────────────────────────────────
+
+  if (sdk.phase === 'error') {
+    return (
+      <View style={[s.root, s.center, style]}>
+        <Text style={s.errorIcon}>✕</Text>
+        <Text style={s.statusText}>{sdk.error?.message ?? 'Verification failed.'}</Text>
+        <TouchableOpacity
+          style={[s.retryBtn, { borderColor: accent }]}
+          onPress={() => {
+            sdk.reset();
+            if (props.mode === 'combined') {
+              sdk.startCombined({ ...options, idCardImage: props.idCardImage } as CombinedCheckOptions);
+            } else {
+              sdk.start(options);
+            }
+          }}
+          activeOpacity={0.8}
+        >
+          <Text style={[s.retryTxt, { color: accent }]}>Try Again</Text>
+        </TouchableOpacity>
+      </View>
+    );
+  }
+
+  // ── Complete ─────────────────────────────────────────────────────────────
+
+  const verified =
+    sdk.combinedResult?.verified ??
+    (sdk.result?.isLive && sdk.result.allChallengesPassed);
+
+  return (
+    <View style={[s.root, s.center, style]}>
+      <Text style={[s.doneIcon, { color: verified ? '#22c55e' : '#f59e0b' }]}>
+        {verified ? '✓' : '!'}
+      </Text>
+      <Text style={s.statusText}>
+        {verified ? 'Verification complete' : 'Check your result'}
+      </Text>
+    </View>
+  );
+}
+
+// ── Styles ───────────────────────────────────────────────────────────────────
+
+const s = StyleSheet.create({
+  root:    { overflow: 'hidden', backgroundColor: '#000', borderRadius: 16 },
+  camera:  { flex: 1, minHeight: 320 },
+  center:  { alignItems: 'center', justifyContent: 'center', padding: 24, minHeight: 240, gap: 16 },
+
+  // Face oval
+  ovalContainer: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  oval: {
+    width: 180,
+    height: 240,
+    borderRadius: 90,
+    borderWidth: 2.5,
+    borderColor: 'rgba(255,255,255,0.5)',
+  },
+
+  // Progress dots
+  dotsRow: {
+    flexDirection: 'row',
+    gap: 6,
+    justifyContent: 'center',
+    paddingTop: 16,
+  },
+  dot:       { width: 8, height: 8, borderRadius: 4, backgroundColor: 'rgba(255,255,255,0.25)' },
+  dotDone:   { backgroundColor: 'rgba(255,255,255,0.6)' },
+  dotActive: { backgroundColor: '#fff' },
+
+  // Instruction card
+  instructionCard: {
+    backgroundColor: 'rgba(0,0,0,0.7)',
+    borderRadius: 12,
+    margin: 16,
+    padding: 16,
+    alignItems: 'center',
+    gap: 6,
+  },
+  countdownBadge: {
+    width: 44, height: 44, borderRadius: 22,
+    alignItems: 'center', justifyContent: 'center',
+    marginBottom: 4,
+  },
+  countdownNum:   { fontSize: 20, fontWeight: '800', color: '#fff' },
+  challengeEmoji: { fontSize: 28 },
+  instLabel:  { fontSize: 11, fontWeight: '700', color: 'rgba(255,255,255,0.55)', letterSpacing: 0.8 },
+  instText:   { fontSize: 16, fontWeight: '700', color: '#fff', textAlign: 'center' },
+  instSub:    { fontSize: 12, color: 'rgba(255,255,255,0.45)', marginTop: 2 },
+
+  // Status
+  statusText: { fontSize: 14, color: '#888', textAlign: 'center' },
+
+  // Error
+  errorIcon: { fontSize: 36, color: '#ef4444', fontWeight: '800' },
+  retryBtn: {
+    borderWidth: 1, borderRadius: 99,
+    paddingHorizontal: 28, paddingVertical: 10, marginTop: 4,
+  },
+  retryTxt:  { fontSize: 14, fontWeight: '700' },
+
+  // Done
+  doneIcon: { fontSize: 48, fontWeight: '800' },
+});

package/src/utils/retry.ts

@@ -0,0 +1,28 @@
+import { KreltixError } from '../errors/KreltixError';
+
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  maxRetries: number,
+  baseDelayMs = 1000,
+): Promise<T> {
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err as Error;
+
+      if (err instanceof KreltixError && !err.isRetryable) {
+        throw err;
+      }
+
+      if (attempt < maxRetries) {
+        const delay = baseDelayMs * Math.pow(2, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  throw lastError;
+}

package/src/utils/video.ts

@@ -0,0 +1,31 @@
+import { KreltixCameraError } from '../errors/KreltixError';
+
+/**
+ * Convert a local file URI (returned by expo-camera's recordAsync) to a
+ * base64-encoded string. Uses fetch + FileReader — both available in RN ≥ 0.74.
+ */
+export async function videoUriToBase64(uri: string): Promise<string> {
+  let response: Response;
+  try {
+    response = await fetch(uri);
+  } catch {
+    throw new KreltixCameraError(`Failed to read video file: ${uri}`);
+  }
+
+  const blob = await response.blob();
+
+  return new Promise<string>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onloadend = () => {
+      const result = reader.result as string;
+      const base64 = result.split('base64,')[1];
+      if (base64) {
+        resolve(base64);
+      } else {
+        reject(new KreltixCameraError('Failed to encode video as base64'));
+      }
+    };
+    reader.onerror = () => reject(new KreltixCameraError('FileReader error'));
+    reader.readAsDataURL(blob);
+  });
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "module": "Node16",
+    "moduleResolution": "node16",
+    "jsx": "react-native",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*"]
+}