@kyciris/core 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -1,3 +1,31 @@
+/**
+ * Pluggable, platform-agnostic key/value storage used to persist the verification
+ * session so a paused flow survives the app being closed.
+ *
+ * Inject a concrete implementation: AsyncStorage on React Native, or an adapter
+ * around localStorage on web. Methods may be sync or async; results are awaited.
+ */
+interface KYCStorage {
+    /** Returns the stored value for a key, or null if absent */
+    getItem(key: string): string | null | Promise<string | null>;
+    /** Persists a value for a key */
+    setItem(key: string, value: string): void | Promise<void>;
+    /** Removes a stored key */
+    removeItem(key: string): void | Promise<void>;
+}
+/**
+ * The persisted verification session, used to resume an in-flight verification.
+ */
+interface KYCSession {
+    /** Identity ID owning the verification */
+    identityId: string;
+    /** Verification ID being completed */
+    verificationId: string;
+    /** External reference ID provided when starting (if any) */
+    externalId?: string;
+    /** Document type for the verification */
+    documentType?: 'IDENTITY_CARD' | 'DRIVING_LICENSE';
+}
 /**
  * Credentials required to initialize the KYC SDK
  */
@@ -6,6 +34,11 @@ interface KYCCredentials {
     apiKey: string;
     /** Base URL of the KYC API */
     baseUrl: string;
+    /**
+     * Optional storage adapter. When provided, the SDK persists the verification
+     * session on startVerification and reads it back to resume a paused flow.
+     */
+    storage?: KYCStorage;
 }
 /**
  * Parameters required to start a verification session
@@ -20,6 +53,24 @@ interface StartVerificationParams {
     /** Optional external reference ID */
     externalId?: string;
 }
+interface FaceMatchVerificationParams {
+    /** The identity ID to perform face match on */
+    identityId: string;
+    /** Base64 encoded image data, data URI, or file:// URI */
+    file: string;
+    /** MIME type of the image (default: image/jpeg) */
+    mimeType?: string;
+}
+interface FaceMatchStatusParams {
+    /** The identity ID to check face match status for */
+    identityId: string;
+    /** The face check ID from the face match verification response */
+    faceCheckId: string;
+    /** Polling interval in milliseconds (default: 3000) */
+    interval?: number;
+    /** Maximum time to wait in milliseconds (default: 120000) */
+    timeout?: number;
+}
 /**
  * Response from starting a verification session
  */
@@ -61,6 +112,23 @@ interface UploadResult {
     message: string;
     /** Current status after upload */
     status: string;
+    /** True when the step was already uploaded and the call was a no-op */
+    skipped?: boolean;
+}
+/**
+ * Parameters for uploading a single verification step in a resume-aware way.
+ */
+interface UploadStepParams {
+    /** The step to upload */
+    step: VerificationStep;
+    /** Base64 encoded image data, data URI, or file:// URI (React Native) */
+    imageData: string;
+    /** Verification ID to attach to; falls back to the persisted session */
+    verificationId?: string;
+    /** Identity ID used to skip already-uploaded steps; falls back to the persisted session */
+    identityId?: string;
+    /** MIME type of the image (default: image/jpeg) */
+    mimeType?: string;
 }
 /** Current status of a verification session */
 interface VerificationStatus {
@@ -88,6 +156,73 @@ interface VerificationStatus {
     /** When the verification was last updated */
     updatedAt: string;
 }
+/** A single verification record as stored under an identity */
+interface VerificationRecord {
+    /** Verification ID */
+    id: string;
+    /** Current verification status */
+    status: string;
+    /** External reference ID (if provided when starting) */
+    externalId: string | null;
+    /** Type of document being verified */
+    documentType: 'IDENTITY_CARD' | 'DRIVING_LICENSE';
+    /** Country code */
+    country: string;
+    /** Face match similarity score (0-1) */
+    faceMatchScore: number | null;
+    /** OCR extracted data from document */
+    ocrData: Record<string, any> | null;
+    /** Stored path of the uploaded selfie, or null if not uploaded yet */
+    selfiePath: string | null;
+    /** Stored path of the uploaded document front, or null if not uploaded yet */
+    documentFrontPath: string | null;
+    /** Stored path of the uploaded document back, or null if not uploaded yet */
+    documentBackPath: string | null;
+    /** Stored path of the document face crop, or null if not available */
+    documentFacePath: string | null;
+    /** Reason for rejection, if rejected */
+    rejectionReason: string | null;
+    /** Type of rejection, if rejected */
+    rejectionType: string | null;
+    /** When the verification was created */
+    createdAt: string;
+    /** When the verification was last updated */
+    updatedAt: string;
+}
+/** An identity with its associated verifications */
+interface Identity {
+    /** Unique identity ID */
+    id: string;
+    /** Verifications linked to this identity */
+    verifications: VerificationRecord[];
+    /** When the identity was created */
+    createdAt: string;
+    /** When the identity was last updated */
+    updatedAt: string;
+    /** Additional OCR / identity fields */
+    [key: string]: any;
+}
+/** A single step a user must complete in a verification flow */
+type VerificationStep = 'selfie' | 'document_front' | 'document_back';
+/** Computed progress of an in-flight verification, used to resume a paused flow */
+interface VerificationProgress {
+    /** Verification ID the progress refers to */
+    verificationId: string;
+    /** Document type for this verification */
+    documentType: 'IDENTITY_CARD' | 'DRIVING_LICENSE';
+    /** Current verification status */
+    status: string;
+    /** Whether the selfie has already been uploaded */
+    selfieUploaded: boolean;
+    /** Whether the document front has already been uploaded */
+    documentFrontUploaded: boolean;
+    /** Whether the document back has already been uploaded (always false for single-sided docs) */
+    documentBackUploaded: boolean;
+    /** Steps still required to finish, in the order they should be collected */
+    missingSteps: VerificationStep[];
+    /** True when no steps remain to be uploaded */
+    isComplete: boolean;
+}
 /** Event emitted when KYC status changes */
 interface KYCStatusEvent {
     /** Type of event: statusChanged or error */
@@ -122,11 +257,29 @@ declare class KYCCore {
     private client;
     private credentials;
     private eventCallbacks;
+    private storage?;
+    /** Storage key under which the active verification session is persisted */
+    private static readonly SESSION_KEY;
     /**
      * Creates a new KYC Core instance
-     * @param credentials API credentials (apiKey and baseUrl)
+     * @param credentials API credentials (apiKey, baseUrl, and optional storage)
      */
     constructor(credentials: KYCCredentials);
+    /**
+     * Persists the active verification session via the injected storage adapter.
+     * No-op when no storage was provided.
+     */
+    private saveSession;
+    /**
+     * Reads the persisted verification session, or null if none exists or no
+     * storage adapter was provided.
+     */
+    getSession(): Promise<KYCSession | null>;
+    /**
+     * Clears the persisted verification session. Call this once a verification is
+     * fully complete so the next flow starts fresh.
+     */
+    clearSession(): Promise<void>;
     /**
      * Registers a callback for KYC status events
      * @param callback Function to call when status changes
@@ -172,6 +325,58 @@ declare class KYCCore {
      * @returns Current verification status including OCR data and face match score
      */
     getStatus(verificationId: string): Promise<VerificationStatus>;
+    /**
+     * Fetches an identity along with all of its verification records.
+     * @param identityId The identity ID to fetch
+     * @returns The identity, including the verifications array with upload paths
+     */
+    getIdentity(identityId: string): Promise<Identity>;
+    /**
+     * Returns the required steps for a given document type, in collection order.
+     * ID cards require both sides; driving licenses are single-sided.
+     */
+    private getRequiredSteps;
+    /**
+     * Computes which steps a user has already completed and which are still missing
+     * for a verification, so a paused flow can be resumed without re-uploading.
+     *
+     * Both arguments are optional: when omitted they fall back to the persisted
+     * session (see the storage adapter). Pass a verificationId to target a specific
+     * verification; otherwise the most recently updated verification is used.
+     *
+     * @param identityId Identity ID owning the verification (defaults to the session)
+     * @param verificationId Verification ID to target (defaults to the session)
+     * @returns Progress describing uploaded steps and the steps still required
+     */
+    getVerificationProgress(identityId?: string, verificationId?: string): Promise<VerificationProgress>;
+    /**
+     * Returns whether every required step of a verification has already been
+     * uploaded (both document sides where applicable, plus the selfie).
+     *
+     * This is the reliable way to tell a user who has fully submitted their
+     * documents (verification is now processing on the KYC backend) apart from one
+     * who paused mid-flow with steps still missing — both look "PENDING" from the
+     * outside. Derived purely from the identity's verification records.
+     *
+     * Returns `false` (rather than throwing) when the identity has no verification
+     * records yet, so callers can treat "nothing uploaded" as "documents missing".
+     *
+     * @param identityId Identity ID owning the verification (defaults to the session)
+     * @param verificationId Verification ID to target (defaults to the most recently updated)
+     * @returns True when no steps remain to be uploaded
+     */
+    hasAllDocuments(identityId?: string, verificationId?: string): Promise<boolean>;
+    /**
+     * Uploads a single verification step (selfie, document front, or document back)
+     * in a resume-aware way: it resolves the verification from the persisted session
+     * when not given, and skips the upload if that step is already complete.
+     *
+     * @param params The step, image data, and optional verification/identity overrides
+     * @returns The upload result; `skipped` is true when the step was already uploaded
+     */
+    uploadStep(params: UploadStepParams): Promise<UploadResult>;
+    faceMatchVerification(params: FaceMatchVerificationParams): Promise<any>;
+    faceMatchStatus({ identityId, faceCheckId, interval, timeout, }: FaceMatchStatusParams): Promise<VerificationStatus>;
     /**
      * Polls for verification status until completion or timeout
      * @param verificationId The verification ID to check
@@ -194,4 +399,4 @@ declare class KYCCore {
  */
 declare function createKYCClient(credentials: KYCCredentials): KYCCore;
 
-export { KYCCore, type KYCCredentials, type KYCEventCallback, KYCSdkError, type KYCStatusEvent, type StartVerificationParams, type UploadDocumentParams, type UploadResult, type UploadSelfieParams, type VerificationSession, type VerificationStatus, createKYCClient };
+export { type FaceMatchStatusParams, type FaceMatchVerificationParams, type Identity, KYCCore, type KYCCredentials, type KYCEventCallback, KYCSdkError, type KYCSession, type KYCStatusEvent, type KYCStorage, type StartVerificationParams, type UploadDocumentParams, type UploadResult, type UploadSelfieParams, type UploadStepParams, type VerificationProgress, type VerificationRecord, type VerificationSession, type VerificationStatus, type VerificationStep, createKYCClient };

package/dist/index.d.ts

@@ -1,3 +1,31 @@
+/**
+ * Pluggable, platform-agnostic key/value storage used to persist the verification
+ * session so a paused flow survives the app being closed.
+ *
+ * Inject a concrete implementation: AsyncStorage on React Native, or an adapter
+ * around localStorage on web. Methods may be sync or async; results are awaited.
+ */
+interface KYCStorage {
+    /** Returns the stored value for a key, or null if absent */
+    getItem(key: string): string | null | Promise<string | null>;
+    /** Persists a value for a key */
+    setItem(key: string, value: string): void | Promise<void>;
+    /** Removes a stored key */
+    removeItem(key: string): void | Promise<void>;
+}
+/**
+ * The persisted verification session, used to resume an in-flight verification.
+ */
+interface KYCSession {
+    /** Identity ID owning the verification */
+    identityId: string;
+    /** Verification ID being completed */
+    verificationId: string;
+    /** External reference ID provided when starting (if any) */
+    externalId?: string;
+    /** Document type for the verification */
+    documentType?: 'IDENTITY_CARD' | 'DRIVING_LICENSE';
+}
 /**
  * Credentials required to initialize the KYC SDK
  */
@@ -6,6 +34,11 @@ interface KYCCredentials {
     apiKey: string;
     /** Base URL of the KYC API */
     baseUrl: string;
+    /**
+     * Optional storage adapter. When provided, the SDK persists the verification
+     * session on startVerification and reads it back to resume a paused flow.
+     */
+    storage?: KYCStorage;
 }
 /**
  * Parameters required to start a verification session
@@ -20,6 +53,24 @@ interface StartVerificationParams {
     /** Optional external reference ID */
     externalId?: string;
 }
+interface FaceMatchVerificationParams {
+    /** The identity ID to perform face match on */
+    identityId: string;
+    /** Base64 encoded image data, data URI, or file:// URI */
+    file: string;
+    /** MIME type of the image (default: image/jpeg) */
+    mimeType?: string;
+}
+interface FaceMatchStatusParams {
+    /** The identity ID to check face match status for */
+    identityId: string;
+    /** The face check ID from the face match verification response */
+    faceCheckId: string;
+    /** Polling interval in milliseconds (default: 3000) */
+    interval?: number;
+    /** Maximum time to wait in milliseconds (default: 120000) */
+    timeout?: number;
+}
 /**
  * Response from starting a verification session
  */
@@ -61,6 +112,23 @@ interface UploadResult {
     message: string;
     /** Current status after upload */
     status: string;
+    /** True when the step was already uploaded and the call was a no-op */
+    skipped?: boolean;
+}
+/**
+ * Parameters for uploading a single verification step in a resume-aware way.
+ */
+interface UploadStepParams {
+    /** The step to upload */
+    step: VerificationStep;
+    /** Base64 encoded image data, data URI, or file:// URI (React Native) */
+    imageData: string;
+    /** Verification ID to attach to; falls back to the persisted session */
+    verificationId?: string;
+    /** Identity ID used to skip already-uploaded steps; falls back to the persisted session */
+    identityId?: string;
+    /** MIME type of the image (default: image/jpeg) */
+    mimeType?: string;
 }
 /** Current status of a verification session */
 interface VerificationStatus {
@@ -88,6 +156,73 @@ interface VerificationStatus {
     /** When the verification was last updated */
     updatedAt: string;
 }
+/** A single verification record as stored under an identity */
+interface VerificationRecord {
+    /** Verification ID */
+    id: string;
+    /** Current verification status */
+    status: string;
+    /** External reference ID (if provided when starting) */
+    externalId: string | null;
+    /** Type of document being verified */
+    documentType: 'IDENTITY_CARD' | 'DRIVING_LICENSE';
+    /** Country code */
+    country: string;
+    /** Face match similarity score (0-1) */
+    faceMatchScore: number | null;
+    /** OCR extracted data from document */
+    ocrData: Record<string, any> | null;
+    /** Stored path of the uploaded selfie, or null if not uploaded yet */
+    selfiePath: string | null;
+    /** Stored path of the uploaded document front, or null if not uploaded yet */
+    documentFrontPath: string | null;
+    /** Stored path of the uploaded document back, or null if not uploaded yet */
+    documentBackPath: string | null;
+    /** Stored path of the document face crop, or null if not available */
+    documentFacePath: string | null;
+    /** Reason for rejection, if rejected */
+    rejectionReason: string | null;
+    /** Type of rejection, if rejected */
+    rejectionType: string | null;
+    /** When the verification was created */
+    createdAt: string;
+    /** When the verification was last updated */
+    updatedAt: string;
+}
+/** An identity with its associated verifications */
+interface Identity {
+    /** Unique identity ID */
+    id: string;
+    /** Verifications linked to this identity */
+    verifications: VerificationRecord[];
+    /** When the identity was created */
+    createdAt: string;
+    /** When the identity was last updated */
+    updatedAt: string;
+    /** Additional OCR / identity fields */
+    [key: string]: any;
+}
+/** A single step a user must complete in a verification flow */
+type VerificationStep = 'selfie' | 'document_front' | 'document_back';
+/** Computed progress of an in-flight verification, used to resume a paused flow */
+interface VerificationProgress {
+    /** Verification ID the progress refers to */
+    verificationId: string;
+    /** Document type for this verification */
+    documentType: 'IDENTITY_CARD' | 'DRIVING_LICENSE';
+    /** Current verification status */
+    status: string;
+    /** Whether the selfie has already been uploaded */
+    selfieUploaded: boolean;
+    /** Whether the document front has already been uploaded */
+    documentFrontUploaded: boolean;
+    /** Whether the document back has already been uploaded (always false for single-sided docs) */
+    documentBackUploaded: boolean;
+    /** Steps still required to finish, in the order they should be collected */
+    missingSteps: VerificationStep[];
+    /** True when no steps remain to be uploaded */
+    isComplete: boolean;
+}
 /** Event emitted when KYC status changes */
 interface KYCStatusEvent {
     /** Type of event: statusChanged or error */
@@ -122,11 +257,29 @@ declare class KYCCore {
     private client;
     private credentials;
     private eventCallbacks;
+    private storage?;
+    /** Storage key under which the active verification session is persisted */
+    private static readonly SESSION_KEY;
     /**
      * Creates a new KYC Core instance
-     * @param credentials API credentials (apiKey and baseUrl)
+     * @param credentials API credentials (apiKey, baseUrl, and optional storage)
      */
     constructor(credentials: KYCCredentials);
+    /**
+     * Persists the active verification session via the injected storage adapter.
+     * No-op when no storage was provided.
+     */
+    private saveSession;
+    /**
+     * Reads the persisted verification session, or null if none exists or no
+     * storage adapter was provided.
+     */
+    getSession(): Promise<KYCSession | null>;
+    /**
+     * Clears the persisted verification session. Call this once a verification is
+     * fully complete so the next flow starts fresh.
+     */
+    clearSession(): Promise<void>;
     /**
      * Registers a callback for KYC status events
      * @param callback Function to call when status changes
@@ -172,6 +325,58 @@ declare class KYCCore {
      * @returns Current verification status including OCR data and face match score
      */
     getStatus(verificationId: string): Promise<VerificationStatus>;
+    /**
+     * Fetches an identity along with all of its verification records.
+     * @param identityId The identity ID to fetch
+     * @returns The identity, including the verifications array with upload paths
+     */
+    getIdentity(identityId: string): Promise<Identity>;
+    /**
+     * Returns the required steps for a given document type, in collection order.
+     * ID cards require both sides; driving licenses are single-sided.
+     */
+    private getRequiredSteps;
+    /**
+     * Computes which steps a user has already completed and which are still missing
+     * for a verification, so a paused flow can be resumed without re-uploading.
+     *
+     * Both arguments are optional: when omitted they fall back to the persisted
+     * session (see the storage adapter). Pass a verificationId to target a specific
+     * verification; otherwise the most recently updated verification is used.
+     *
+     * @param identityId Identity ID owning the verification (defaults to the session)
+     * @param verificationId Verification ID to target (defaults to the session)
+     * @returns Progress describing uploaded steps and the steps still required
+     */
+    getVerificationProgress(identityId?: string, verificationId?: string): Promise<VerificationProgress>;
+    /**
+     * Returns whether every required step of a verification has already been
+     * uploaded (both document sides where applicable, plus the selfie).
+     *
+     * This is the reliable way to tell a user who has fully submitted their
+     * documents (verification is now processing on the KYC backend) apart from one
+     * who paused mid-flow with steps still missing — both look "PENDING" from the
+     * outside. Derived purely from the identity's verification records.
+     *
+     * Returns `false` (rather than throwing) when the identity has no verification
+     * records yet, so callers can treat "nothing uploaded" as "documents missing".
+     *
+     * @param identityId Identity ID owning the verification (defaults to the session)
+     * @param verificationId Verification ID to target (defaults to the most recently updated)
+     * @returns True when no steps remain to be uploaded
+     */
+    hasAllDocuments(identityId?: string, verificationId?: string): Promise<boolean>;
+    /**
+     * Uploads a single verification step (selfie, document front, or document back)
+     * in a resume-aware way: it resolves the verification from the persisted session
+     * when not given, and skips the upload if that step is already complete.
+     *
+     * @param params The step, image data, and optional verification/identity overrides
+     * @returns The upload result; `skipped` is true when the step was already uploaded
+     */
+    uploadStep(params: UploadStepParams): Promise<UploadResult>;
+    faceMatchVerification(params: FaceMatchVerificationParams): Promise<any>;
+    faceMatchStatus({ identityId, faceCheckId, interval, timeout, }: FaceMatchStatusParams): Promise<VerificationStatus>;
     /**
      * Polls for verification status until completion or timeout
      * @param verificationId The verification ID to check
@@ -194,4 +399,4 @@ declare class KYCCore {
  */
 declare function createKYCClient(credentials: KYCCredentials): KYCCore;
 
-export { KYCCore, type KYCCredentials, type KYCEventCallback, KYCSdkError, type KYCStatusEvent, type StartVerificationParams, type UploadDocumentParams, type UploadResult, type UploadSelfieParams, type VerificationSession, type VerificationStatus, createKYCClient };
+export { type FaceMatchStatusParams, type FaceMatchVerificationParams, type Identity, KYCCore, type KYCCredentials, type KYCEventCallback, KYCSdkError, type KYCSession, type KYCStatusEvent, type KYCStorage, type StartVerificationParams, type UploadDocumentParams, type UploadResult, type UploadSelfieParams, type UploadStepParams, type VerificationProgress, type VerificationRecord, type VerificationSession, type VerificationStatus, type VerificationStep, createKYCClient };