@kwik-id/sdk-react-native 0.0.0-stage → 0.1.0-alpha.0

package/src/types/index.ts

@@ -0,0 +1,309 @@
+/**
+ * Canonical types for @kwik-id/sdk-react-native.
+ *
+ * These are a self-contained, RN-native mirror of the KwikId protocol vocabulary.
+ * They are kept structurally compatible with `@kwik-id/sdk-core` via the build-excluded
+ * assertions in `./__compat__`. This package has NO runtime dependency on `@kwik-id/*`.
+ */
+
+// ============================================
+// Configuration
+// ============================================
+
+export interface KwikIdTheme {
+    primary?: string;
+    accent?: string;
+    background?: string;
+    foreground?: string;
+    error?: string;
+    success?: string;
+}
+
+export type Locale = "en" | "fr";
+
+export type LivenessMode = "passive" | "active" | "hybrid";
+
+export interface KwikIdConfig {
+    /** Session token obtained from your backend (POST /api/v1/sessions). */
+    clientSecret: string;
+    /** Base URL for API calls (defaults to production). */
+    baseUrl?: string;
+    /** Display name shown in the verification UI. */
+    appName?: string;
+    /** Theme customization. */
+    theme?: KwikIdTheme;
+    /** Locale for UI text. */
+    locale?: Locale;
+    /**
+     * Liveness mode; overrides the session config when set.
+     * @deprecated Not yet supported: ignored until on-device liveness lands (Phase 2).
+     */
+    livenessMode?: LivenessMode;
+    /** Request timeout in milliseconds. */
+    timeout?: number;
+    /** Enable debug logging. */
+    debug?: boolean;
+}
+
+// ============================================
+// Documents & captures
+// ============================================
+
+export type DocumentType =
+    | "id_card"
+    | "passport"
+    | "drivers_license"
+    | "voters_card"
+    | "residence_permit";
+
+export type CaptureType = "document_front" | "document_back" | "selfie" | "liveness_frame";
+
+/** RN capture descriptor — replaces the web SDK's DOM File/Blob. */
+export interface CaptureAsset {
+    uri: string;
+    name: string;
+    type: string;
+    width: number;
+    height: number;
+}
+
+export interface CaptureMetadata {
+    timestamp: number;
+    resolution: { width: number; height: number };
+    facingMode: "user" | "environment";
+    deviceId?: string;
+    qualityScore?: number;
+    faceDetected?: boolean;
+}
+
+// ============================================
+// Quality
+// ============================================
+
+export type QualityGuidance =
+    | "move_to_brighter_area"
+    | "reduce_brightness"
+    | "hold_still"
+    | "move_closer"
+    | "move_back"
+    | "center_face"
+    | "only_one_face";
+
+export interface QualityCheckResult {
+    passed: boolean;
+    value: number;
+    threshold: number;
+    issue?: string;
+}
+
+export interface QualityResult {
+    passed: boolean;
+    timestamp: number;
+    checks: {
+        luminance: QualityCheckResult & { issue?: "too_dark" | "too_bright" };
+        blur: QualityCheckResult & { issue?: "too_blurry" };
+        resolution: QualityCheckResult & { width: number; height: number };
+        face?: QualityCheckResult & {
+            count: number;
+            size?: number;
+            issue?: "no_face" | "multiple_faces" | "face_too_small";
+        };
+    };
+    guidance: QualityGuidance[];
+}
+
+// ============================================
+// Face & liveness
+// ============================================
+
+export interface FacePose {
+    yaw: number;
+    pitch: number;
+    roll: number;
+}
+
+/**
+ * Normalized per-frame face signals produced by the ML Kit frame processor.
+ * All probabilities are 0..1; angles are degrees. This is the single source the
+ * alignment + liveness detectors consume (replaces the web SDK's Landmark[] probing).
+ */
+export interface FaceSignals {
+    faceCount: number;
+    /** Face bounding-box area as a fraction of the frame area. */
+    bboxRatio: number;
+    /** Normalized horizontal offset of the face center from frame center (-1..1). */
+    centerOffsetX: number;
+    /** Normalized vertical offset of the face center from frame center (-1..1). */
+    centerOffsetY: number;
+    yaw: number;
+    pitch: number;
+    roll: number;
+    leftEyeOpen: number;
+    rightEyeOpen: number;
+    smiling: number;
+    /** Mouth open ratio (0..1); -1 when unavailable on the device. */
+    mouthOpenRatio: number;
+    confidence: number;
+}
+
+export type ChallengeType = "blink" | "smile" | "turn_left" | "turn_right" | "nod" | "open_mouth";
+
+export interface Challenge {
+    type: ChallengeType;
+    instruction: string;
+    timeoutMs: number;
+    requiredCount?: number;
+    targetAngle?: number;
+}
+
+export interface ChallengeResult {
+    challenge: Challenge;
+    passed: boolean;
+    confidence: number;
+    completedAt?: number;
+}
+
+export interface PassiveLivenessResult {
+    passed: boolean;
+    confidence: number;
+    checks: {
+        microMovement: { passed: boolean; detected: boolean };
+        naturalBlink: { passed: boolean; detected: boolean };
+        textureAnalysis: { passed: boolean; score: number };
+    };
+    spoofType?: "screen" | "print" | "mask" | "unknown";
+}
+
+export interface LivenessResult {
+    passed: boolean;
+    mode: LivenessMode;
+    passiveResult?: PassiveLivenessResult;
+    challenges?: ChallengeResult[];
+    confidence: number;
+}
+
+// ============================================
+// Session & security
+// ============================================
+
+export interface DeviceFingerprint {
+    platform: string;
+    osVersion: string;
+    deviceModel: string;
+    screenResolution: string;
+    timezone: string;
+    language: string;
+    fingerprintHash: string;
+}
+
+export interface Session {
+    sessionId: string;
+    clientSecret: string;
+    jobId?: string;
+    expiresAt: Date;
+    deviceFingerprint: string;
+    nonce: string;
+    sequenceNumber: number;
+}
+
+export interface SecurePayload {
+    sessionId: string;
+    timestamp: number;
+    nonce: string;
+    sequenceNumber: number;
+    signature: string;
+    deviceFingerprint: string;
+    data: unknown;
+}
+
+// ============================================
+// Verification results
+// ============================================
+
+export interface VerificationScores {
+    documentQuality: number;
+    documentAuthenticity: number;
+    faceMatch: number;
+    liveness: number;
+}
+
+export interface ExtractedData {
+    documentType: string;
+    documentNumber?: string;
+    fullName?: string;
+    firstName?: string;
+    lastName?: string;
+    dateOfBirth?: string;
+    expiryDate?: string;
+    issuingCountry?: string;
+    nationality?: string;
+    gender?: string;
+    address?: string;
+    [key: string]: string | undefined;
+}
+
+export interface VerificationResult {
+    jobId: string;
+    status: "verified" | "rejected" | "manual_review" | "pending" | "processing";
+    overallScore: number;
+    scores: VerificationScores;
+    extractedData?: ExtractedData;
+    rejectionReasons?: string[];
+    errorDetails?: {
+        document: string;
+        errorCode: string;
+        errorMessage: string;
+    };
+    timestamps: {
+        submitted: string;
+        completed?: string;
+    };
+    referenceId: string;
+}
+
+/** The terminal outcome surfaced to the host app from `start()`. */
+export interface VerificationOutcome {
+    status: "submitted" | "cancelled" | "error";
+    jobId?: string;
+    error?: Error;
+}
+
+// ============================================
+// Session info (GET /sdk/v1/session)
+// ============================================
+
+export interface SessionInfo {
+    sessionId: string;
+    expiresAt: string;
+    orgName?: string;
+    orgLogoUrl?: string;
+    config: {
+        documentTypes: DocumentType[];
+        livenessMode: LivenessMode;
+        maxRetries: number;
+    };
+}
+
+// ============================================
+// Verification state machine
+// ============================================
+
+export type VerificationSubStep =
+    | "intro"
+    | "handoff-redeem"
+    | "document-type"
+    | "prepare-front"
+    | "camera-front"
+    | "confirm-front"
+    | "prepare-back"
+    | "camera-back"
+    | "confirm-back"
+    | "prepare-selfie"
+    | "liveness"
+    | "confirm-selfie"
+    | "processing"
+    | "result";
+
+export type CaptureSlot = "front" | "back" | "selfie";
+
+export type { KwikIdEvents, KwikIdEventName, KwikIdEventHandler } from "./events";