@uverifyng/node 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,498 @@
+/** Anything that becomes base64 for an image field: a Buffer/Uint8Array, a base64 string, or a data: URL. */
+type ImageInput = Buffer | Uint8Array | string;
+type Environment = 'test' | 'live';
+interface Page<T> {
+    items: T[];
+    pagination: {
+        page: number;
+        per_page: number;
+        total: number;
+        total_pages: number;
+    };
+}
+interface PageParams {
+    page?: number;
+    per_page?: number;
+}
+interface CheckBase {
+    /** Your unique ID for the check. Generated for you when omitted; reusing one never charges twice. */
+    reference?: string;
+    /** When the record is found, screen it against the sanctions lists (billed per name). */
+    aml_screening?: boolean;
+    /** Screen as above and keep watching the names (billed monthly per name). */
+    aml_monitoring?: boolean;
+}
+interface PersonCheckParams extends CheckBase {
+    id_number: string;
+    first_name?: string;
+    last_name?: string;
+    /** YYYY-MM-DD, compared with the record. */
+    dob?: string;
+    /** Return the photo on the ID record (never stored by UVerify). */
+    include_photo?: boolean;
+}
+/** BVN, driver's licence and voter's card need the person's names. */
+interface NamedCheckParams extends PersonCheckParams {
+    first_name: string;
+    last_name: string;
+}
+/** The face to match: a passed liveness session (recommended) or a selfie image. */
+type FaceInput = {
+    liveness_session_id: string;
+    selfie_image?: never;
+} | {
+    selfie_image: ImageInput;
+    liveness_session_id?: never;
+};
+interface CacCheckParams extends CheckBase {
+    /** RC, BN or IT number, e.g. RC123456. */
+    id_number: string;
+    business_type?: string;
+}
+interface AmlSummary {
+    status: 'clear' | 'potential_match' | 'unavailable';
+    reason?: string;
+    screenings: {
+        id: string;
+        subject: 'person' | 'company' | 'director';
+        status: 'clear' | 'potential_match';
+        matches: number;
+        monitor_id?: string | null;
+    }[];
+}
+interface Verification {
+    id: string;
+    reference: string;
+    type: 'bvn' | 'nin' | 'drivers_license' | 'voters_card' | 'tin' | 'cac';
+    type_label: string;
+    service: string;
+    service_label: string;
+    environment: Environment;
+    /** verified (record found) · not_found · failed (registry unreachable; refunded) · pending. */
+    status: 'pending' | 'verified' | 'not_found' | 'failed';
+    message: string;
+    id_number: string;
+    field_matches: Record<string, boolean | null> | null;
+    face_match: {
+        status: 'matched' | 'not_matched' | 'unavailable';
+        score: number | null;
+        liveness: 'passed' | 'not_checked';
+        liveness_session_id?: string;
+        reason?: string;
+    } | null;
+    duplicate_check: {
+        status: 'clear' | 'returning' | 'other_id' | 'flagged';
+        matches: unknown[];
+    } | null;
+    aml_screening: AmlSummary | null;
+    /** The record. Present on the check's response and on get(); lists leave it out. */
+    data: Record<string, unknown> | null;
+    photo?: string;
+    data_deleted_at?: string;
+    amount_charged: number;
+    currency: 'NGN';
+    created_at: string;
+}
+interface ListVerificationsParams extends PageParams {
+    type?: Verification['type'];
+    service?: string;
+    status?: Verification['status'];
+    reference?: string;
+}
+interface CreateLivenessParams {
+    reference?: string;
+    /** https URL to send the person to when they finish. */
+    redirect_url?: string;
+}
+interface LivenessSession {
+    id: string;
+    reference: string;
+    environment: Environment;
+    status: 'pending' | 'passed' | 'failed' | 'expired';
+    live: boolean;
+    score: number | null;
+    reasons: string[];
+    attempts: number;
+    max_attempts: number;
+    usable_for_face_match: boolean;
+    used_by_verification_id: string | null;
+    duplicates: {
+        count: number;
+        matches: unknown[];
+    } | null;
+    redirect_url: string | null;
+    amount_charged: number;
+    currency: 'NGN';
+    expires_at: string;
+    completed_at: string | null;
+    created_at: string;
+    /** Only when created: the hosted page to send the person to. */
+    url?: string;
+}
+interface SimulateLivenessParams {
+    outcome: 'passed' | 'failed' | 'expired';
+    /** Sandbox stand-in for a face: the same string on two sessions is the same person. */
+    face?: string;
+}
+type DocumentType = 'nin_slip' | 'nin_card' | 'drivers_license' | 'voters_card' | 'passport';
+interface VerifyDocumentParams {
+    front_image: ImageInput;
+    back_image?: ImageInput;
+    document_type?: DocumentType;
+    liveness_session_id?: string;
+    selfie_image?: ImageInput;
+    /** Look the number up in the registry (billed as that lookup). Default true. */
+    verify_with_registry?: boolean;
+    reference?: string;
+    /** Sandbox only: the result to act out. */
+    sandbox_outcome?: 'verified' | 'unreadable' | 'expired' | 'tampered' | 'not_in_registry' | 'other_person' | 'face_mismatch';
+}
+interface IdDocument {
+    id: string;
+    reference: string;
+    environment: Environment;
+    /** verified · review (a person should look) · rejected · failed (couldn't be checked; refunded). */
+    status: 'verified' | 'review' | 'rejected' | 'failed';
+    reasons: string[];
+    document_type: DocumentType | 'other' | null;
+    expected_type: DocumentType | null;
+    id_number: string | null;
+    checks: Record<string, unknown> | null;
+    verification_id: string | null;
+    liveness_session_id: string | null;
+    /** What was read off the document (on verify and get). */
+    extracted?: Record<string, unknown> | null;
+    amount_charged: number;
+    currency: 'NGN';
+    created_at: string;
+}
+interface ScreenParams {
+    /** Full name (a person needs at least two names), or an organisation's name. */
+    name: string;
+    entity_type?: 'person' | 'entity';
+    /** YYYY-MM-DD or YYYY: sharpens matches. */
+    date_of_birth?: string;
+    nationality?: string;
+    reference?: string;
+    /** Keep watching this name after screening. */
+    monitor?: boolean;
+}
+interface AmlMatch {
+    source: 'un' | 'ofac' | 'uk' | 'eu' | 'ng';
+    source_label: string;
+    list_id: string;
+    kind: 'person' | 'entity';
+    name: string;
+    matched_name: string;
+    score: number;
+    date_of_birth: string[];
+    dob_match: boolean | null;
+    nationalities: string[];
+    programs: string[];
+    listed_on: string | null;
+}
+interface AmlScreening {
+    id: string;
+    reference: string;
+    environment: Environment;
+    status: 'clear' | 'potential_match';
+    entity_type: 'person' | 'entity';
+    name: string | null;
+    date_of_birth: string | null;
+    nationality: string | null;
+    matches: AmlMatch[];
+    lists_checked: {
+        source: string;
+        synced_at: string | null;
+        entries: number;
+    }[];
+    decision: 'cleared' | 'confirmed' | null;
+    decision_note: string | null;
+    decided_at: string | null;
+    monitor_id?: string | null;
+    amount_charged: number;
+    currency: 'NGN';
+    created_at: string;
+}
+type MonitorParams = Omit<ScreenParams, 'monitor'>;
+interface AmlMonitor {
+    id: string;
+    reference: string;
+    environment: Environment;
+    status: 'active' | 'paused' | 'stopped';
+    entity_type: 'person' | 'entity';
+    name?: string | null;
+    date_of_birth?: string | null;
+    matches_known: number;
+    last_screening_id: string | null;
+    last_checked_at: string | null;
+    verification_id: string | null;
+    created_at: string;
+    stopped_at: string | null;
+}
+interface SanctionsList {
+    source: string;
+    label: string;
+    publisher: string;
+    url: string;
+    status: 'ok' | 'error' | 'never';
+    entries: number;
+    synced_at: string | null;
+}
+interface CreateKycLinkParams {
+    reference?: string;
+    /** IDs the customer may choose from. Default: bvn and nin. */
+    id_types?: ('bvn' | 'nin' | 'drivers_license' | 'voters_card')[];
+    customer_name?: string;
+    customer_email?: string;
+    redirect_url?: string;
+    /** Also ask for a photo of their ID after the face check. */
+    require_document?: boolean;
+    aml_screening?: boolean;
+    aml_monitoring?: boolean;
+}
+interface KycLink {
+    id: string;
+    reference: string;
+    environment: Environment;
+    status: 'pending' | 'in_progress' | 'completed' | 'failed' | 'expired';
+    outcome: 'verified' | 'face_mismatch' | 'face_unavailable' | 'not_found' | 'liveness_failed' | 'error' | 'document_rejected' | 'document_mismatch' | null;
+    customer_name: string | null;
+    customer_email: string | null;
+    id_types: string[];
+    id_type: string | null;
+    id_number: string | null;
+    attempts: number;
+    verification: Verification | null;
+    liveness: {
+        id: string;
+        status: string;
+        score: number | null;
+        attempts: number;
+    } | null;
+    require_document: boolean;
+    document: {
+        id: string;
+        status: string;
+        reasons: string[];
+        document_type: string | null;
+    } | null;
+    aml_screening?: boolean;
+    aml_monitoring?: boolean;
+    amount_charged: number;
+    currency: 'NGN';
+    redirect_url: string | null;
+    expires_at: string;
+    completed_at: string | null;
+    created_at: string;
+    /** Only when created: send this to the customer. */
+    url?: string;
+}
+interface ListKycLinksParams extends PageParams {
+    status?: KycLink['status'];
+    outcome?: NonNullable<KycLink['outcome']>;
+    reference?: string;
+}
+interface Balance {
+    balance: number;
+    currency: 'NGN';
+    billing_mode?: 'prepaid' | 'postpaid';
+    credit_limit?: number;
+    available?: number;
+    owed?: number;
+}
+interface Price {
+    check_type: string;
+    label: string;
+    default_price: number;
+    custom_price: number | null;
+    price: number;
+    currency: 'NGN';
+    is_enabled: boolean;
+}
+type WebhookEventType = 'verification.completed' | 'liveness.completed' | 'kyc.completed' | 'document.completed' | 'aml.match_found' | 'webhook.test';
+interface WebhookEvent<T = unknown> {
+    /** Unique per event; deliveries can repeat, so dedupe on it. */
+    id: string;
+    type: WebhookEventType | string;
+    created_at: string;
+    environment: Environment;
+    data: T;
+}
+
+/**
+ * Verify a webhook and return its event. Pass the raw request body exactly as
+ * received (a Buffer or string, not re-serialised JSON), the UVerify-Signature
+ * header, and your endpoint's signing secret (whsec_…).
+ *
+ * Throws UVerifySignatureError if the signature doesn't match or the event is
+ * older than `toleranceSeconds` (a replay). Deliveries can repeat: dedupe on
+ * `event.id`.
+ */
+declare function constructEvent<T = unknown>(rawBody: string | Buffer | Uint8Array, signatureHeader: string | string[] | undefined | null, secret: string, toleranceSeconds?: number): WebhookEvent<T>;
+/** Sign a payload the way UVerify does, for your own tests. */
+declare function signPayload(body: string, secret: string, timestamp?: number): string;
+
+declare const VERSION = "0.1.0";
+interface UVerifyOptions {
+    /** uvk_test_… (sandbox, free) or uvk_live_…. Defaults to the UVERIFY_API_KEY environment variable. */
+    apiKey?: string;
+    /** Defaults to https://api.uverify.com.ng/v1. */
+    baseUrl?: string;
+    /** Per attempt. Face matches and ID documents can take several seconds. Default 60s. */
+    timeoutMs?: number;
+    /** Retries after a timeout, a connection error, a 5xx or a rate limit. Default 2. */
+    maxRetries?: number;
+    /** Bring your own fetch (tests, proxies). Defaults to the global fetch (Node 18+). */
+    fetch?: typeof fetch;
+}
+interface RequestOptions {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: Record<string, unknown>;
+    /** Safe to repeat: GETs, and POSTs that carry a reference. */
+    retryable?: boolean;
+}
+/**
+ * The UVerify API client.
+ *
+ * ```ts
+ * import { UVerify } from '@uverifyng/node';
+ * const uverify = new UVerify({ apiKey: process.env.UVERIFY_API_KEY });
+ * const v = await uverify.identity.nin({ id_number: '12345678901' });
+ * if (v.status === 'verified') { … }
+ * ```
+ */
+declare class UVerify {
+    readonly identity: IdentityResource;
+    readonly business: BusinessResource;
+    readonly verifications: VerificationsResource;
+    readonly liveness: LivenessResource;
+    readonly documents: DocumentsResource;
+    readonly aml: AmlResource;
+    readonly kyc: KycResource;
+    readonly account: AccountResource;
+    static readonly webhooks: {
+        constructEvent: typeof constructEvent;
+        signPayload: typeof signPayload;
+    };
+    /** Verify webhook signatures. Also usable without a client: `UVerify.webhooks.constructEvent(…)`. */
+    readonly webhooks: {
+        constructEvent: typeof constructEvent;
+        signPayload: typeof signPayload;
+    };
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(options?: UVerifyOptions | string);
+    /** 'test' for a sandbox key, 'live' for a live one. */
+    get environment(): 'test' | 'live';
+    /** @internal */
+    request<T>(method: 'GET' | 'POST' | 'DELETE', path: string, opts?: RequestOptions): Promise<T>;
+    /** @internal An identity/business check: always carries a reference, so it can be retried safely. */
+    check(path: string, params: object): Promise<Verification>;
+    /** @internal A create that carries a reference (safe to retry). */
+    create<T>(path: string, params: object, prefix: string): Promise<T>;
+}
+declare class Resource {
+    protected readonly client: UVerify;
+    constructor(client: UVerify);
+}
+declare class IdentityResource extends Resource {
+    /** BVN lookup. Names are required by the registry. */
+    bvn(params: NamedCheckParams): Promise<Verification>;
+    /** BVN lookup + face match against the BVN photo. */
+    bvnFaceMatch(params: NamedCheckParams & FaceInput): Promise<Verification>;
+    nin(params: PersonCheckParams): Promise<Verification>;
+    ninFaceMatch(params: PersonCheckParams & FaceInput): Promise<Verification>;
+    driversLicense(params: NamedCheckParams): Promise<Verification>;
+    driversLicenseFaceMatch(params: NamedCheckParams & FaceInput): Promise<Verification>;
+    votersCard(params: NamedCheckParams): Promise<Verification>;
+    votersCardFaceMatch(params: NamedCheckParams & FaceInput): Promise<Verification>;
+    /** Tax ID lookup. */
+    tin(params: {
+        id_number: string;
+        reference?: string;
+    }): Promise<Verification>;
+}
+declare class BusinessResource extends Resource {
+    /** CAC lookup: status, address, directors, owners. */
+    cac(params: CacCheckParams): Promise<Verification>;
+}
+declare class VerificationsResource extends Resource {
+    list(params?: ListVerificationsParams): Promise<Page<Verification>>;
+    /** One verification, with its record. */
+    get(id: string): Promise<Verification>;
+}
+declare class LivenessResource extends Resource {
+    /** A hosted camera check. Send the person to `session.url`, then pass `session.id` to a face match. */
+    createSession(params?: CreateLivenessParams): Promise<LivenessSession>;
+    getSession(id: string): Promise<LivenessSession>;
+    /** Sandbox only: finish a session without a camera. */
+    simulate(id: string, params: SimulateLivenessParams): Promise<LivenessSession>;
+}
+declare class DocumentsResource extends Resource {
+    /** Read and check a photo of an ID (NIN slip or card, licence, voter's card, passport). Images: Buffer or base64. */
+    verify(params: VerifyDocumentParams): Promise<IdDocument>;
+    get(id: string): Promise<IdDocument>;
+}
+declare class AmlMonitorsResource extends Resource {
+    /** Screen a name now and keep watching it (billed monthly). */
+    create(params: MonitorParams): Promise<AmlMonitor>;
+    list(params?: PageParams & {
+        status?: AmlMonitor['status'];
+    }): Promise<Page<AmlMonitor>>;
+    get(id: string): Promise<AmlMonitor>;
+    /** Stop watching a name. */
+    stop(id: string): Promise<AmlMonitor>;
+}
+declare class AmlResource extends Resource {
+    readonly monitors: AmlMonitorsResource;
+    /** Screen a person or organisation against the UN, OFAC, UK, EU and Nigeria sanctions lists. */
+    screen(params: ScreenParams): Promise<AmlScreening & {
+        monitor_id?: string;
+    }>;
+    getScreening(id: string): Promise<AmlScreening>;
+    /** The lists screened, and how fresh each is. */
+    lists(): Promise<SanctionsList[]>;
+}
+declare class KycResource extends Resource {
+    /** A hosted verification link: send `link.url` to your customer. */
+    createLink(params?: CreateKycLinkParams): Promise<KycLink>;
+    getLink(id: string): Promise<KycLink>;
+    listLinks(params?: ListKycLinksParams): Promise<Page<KycLink>>;
+}
+declare class AccountResource extends Resource {
+    balance(): Promise<Balance>;
+    /** Your prices per check (custom prices included). */
+    pricing(): Promise<Price[]>;
+}
+
+/** Every API error. Branch on `code`: it's stable (https://uverify.com.ng/docs#responses). */
+declare class UVerifyError extends Error {
+    /** e.g. validation_error, insufficient_balance, duplicate_reference, rate_limited. */
+    readonly code: string;
+    /** HTTP status (0 when the request never got a response). */
+    readonly status: number;
+    /** Quote this to UVerify support to trace the request. */
+    readonly requestId: string | null;
+    /** Field errors for validation_error; retry_after_seconds for rate_limited; … */
+    readonly details: unknown;
+    constructor(message: string, opts: {
+        code: string;
+        status: number;
+        requestId?: string | null;
+        details?: unknown;
+    });
+}
+/** The request didn't complete: timeout, DNS, connection reset. Safe to retry with the same reference. */
+declare class UVerifyConnectionError extends UVerifyError {
+    constructor(message: string, cause?: unknown);
+}
+/** A webhook failed signature or timestamp verification. Don't trust its body. */
+declare class UVerifySignatureError extends Error {
+    constructor(message: string);
+}
+
+export { type AmlMatch, type AmlMonitor, type AmlScreening, type AmlSummary, type Balance, type CacCheckParams, type CreateKycLinkParams, type CreateLivenessParams, type DocumentType, type Environment, type FaceInput, type IdDocument, type ImageInput, type KycLink, type ListKycLinksParams, type ListVerificationsParams, type LivenessSession, type MonitorParams, type NamedCheckParams, type Page, type PageParams, type PersonCheckParams, type Price, type SanctionsList, type ScreenParams, type SimulateLivenessParams, UVerify, UVerifyConnectionError, UVerifyError, type UVerifyOptions, UVerifySignatureError, VERSION, type Verification, type VerifyDocumentParams, type WebhookEvent, type WebhookEventType, constructEvent, UVerify as default, signPayload };