@uverifyng/node 0.1.0

package/README.md

@@ -0,0 +1,109 @@
+# UVerify for Node.js
+
+The official Node.js library for [UVerify](https://uverify.com.ng): BVN, NIN, driver’s licence and voter’s card checks, liveness and face match, ID documents, AML screening and CAC, for Nigerian businesses.
+
+```bash
+npm install @uverifyng/node
+```
+
+Node 18 or later. No dependencies. ESM and CommonJS, with TypeScript types.
+
+## Quick start
+
+```ts
+import { UVerify } from '@uverifyng/node';
+
+const uverify = new UVerify({ apiKey: process.env.UVERIFY_API_KEY }); // uvk_test_… is the free sandbox
+
+const v = await uverify.identity.nin({ id_number: '12345678901', first_name: 'Adaeze', last_name: 'Okafor' });
+if (v.status === 'verified') {
+  console.log(v.data, v.field_matches); // the record, and which details matched
+}
+```
+
+In the sandbox the last two digits of the ID number choose the result: `00` not found, `99` registry error, `98` face mismatch, anything else verified.
+
+## A live customer, end to end
+
+```ts
+// 1. A liveness session: send the person to session.url (any phone browser)
+const session = await uverify.liveness.createSession({ redirect_url: 'https://yourapp.com/kyc/done' });
+
+// 2. When they return, match the face that passed to their BVN photo
+const v = await uverify.identity.bvnFaceMatch({
+  id_number: '22212345678', first_name: 'Adaeze', last_name: 'Okafor',
+  liveness_session_id: session.id,
+  aml_screening: true, // also screen the verified person against sanctions lists
+});
+
+if (v.status === 'verified' && v.face_match?.status === 'matched' && v.aml_screening?.status === 'clear') {
+  // approve
+}
+```
+
+## Everything else
+
+```ts
+await uverify.identity.bvn({ id_number, first_name, last_name });            // also driversLicense, votersCard, tin
+await uverify.identity.ninFaceMatch({ id_number, selfie_image: buffer });    // a selfie instead of liveness (Buffer or base64)
+await uverify.business.cac({ id_number: 'RC123456', aml_screening: true });  // company + each director screened
+
+await uverify.documents.verify({ front_image: fs.readFileSync('nin.jpg'), document_type: 'nin_card', liveness_session_id });
+await uverify.aml.screen({ name: 'Adaeze Okafor', date_of_birth: '1990-01-15' });
+await uverify.aml.monitors.create({ name: 'Adaeze Okafor' });                // re-screened after every list update
+
+const link = await uverify.kyc.createLink({ customer_name: 'Ada', require_document: true }); // no-code: send link.url
+
+await uverify.verifications.list({ status: 'verified' });
+await uverify.account.balance();
+```
+
+## Errors
+
+Every failure is a `UVerifyError` with a stable `code`:
+
+```ts
+import { UVerifyError } from '@uverifyng/node';
+
+try {
+  await uverify.identity.nin({ id_number });
+} catch (e) {
+  if (e instanceof UVerifyError && e.code === 'insufficient_balance') { /* top up */ }
+  console.log(e.code, e.message, e.requestId, e.details);
+}
+```
+
+A check that finds nothing is **not** an error: it returns `status: 'not_found'` (and you aren’t charged).
+
+## Retries
+
+Timeouts, connection errors, 5xx responses and rate limits are retried twice with backoff (`maxRetries`, `timeoutMs`). Every check carries a `reference` (one is generated if you don’t pass your own), so a retry can never charge twice; if the first attempt did go through, the library returns that result.
+
+## Webhooks
+
+```ts
+import express from 'express';
+import { UVerify } from '@uverifyng/node';
+
+app.post('/webhooks/uverify', express.raw({ type: 'application/json' }), (req, res) => {
+  let event;
+  try {
+    event = UVerify.webhooks.constructEvent(req.body, req.header('UVerify-Signature'), process.env.UVERIFY_WEBHOOK_SECRET!);
+  } catch {
+    return res.sendStatus(400);
+  }
+  if (event.type === 'verification.completed') { /* event.data is the verification */ }
+  res.sendStatus(200);
+});
+```
+
+Pass the **raw** body. Deliveries can repeat, so dedupe on `event.id`.
+
+## Tests
+
+```bash
+npm test                                            # offline
+UVERIFY_TEST_KEY=uvk_test_… npx vitest run test/sandbox.test.ts   # against the real sandbox
+```
+
+MIT licence. API reference: https://uverify.com.ng/docs

package/dist/index.cjs

@@ -0,0 +1,355 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  UVerify: () => UVerify,
+  UVerifyConnectionError: () => UVerifyConnectionError,
+  UVerifyError: () => UVerifyError,
+  UVerifySignatureError: () => UVerifySignatureError,
+  VERSION: () => VERSION,
+  constructEvent: () => constructEvent,
+  default: () => index_default,
+  signPayload: () => signPayload
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_node_crypto2 = require("crypto");
+
+// src/errors.ts
+var UVerifyError = class extends Error {
+  /** e.g. validation_error, insufficient_balance, duplicate_reference, rate_limited. */
+  code;
+  /** HTTP status (0 when the request never got a response). */
+  status;
+  /** Quote this to UVerify support to trace the request. */
+  requestId;
+  /** Field errors for validation_error; retry_after_seconds for rate_limited; … */
+  details;
+  constructor(message, opts) {
+    super(message);
+    this.name = "UVerifyError";
+    this.code = opts.code;
+    this.status = opts.status;
+    this.requestId = opts.requestId ?? null;
+    this.details = opts.details;
+  }
+};
+var UVerifyConnectionError = class extends UVerifyError {
+  constructor(message, cause) {
+    super(message, { code: "connection_error", status: 0 });
+    this.name = "UVerifyConnectionError";
+    if (cause) this.cause = cause;
+  }
+};
+var UVerifySignatureError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UVerifySignatureError";
+  }
+};
+
+// src/webhooks.ts
+var import_node_crypto = require("crypto");
+function constructEvent(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
+  const header = Array.isArray(signatureHeader) ? signatureHeader[0] : signatureHeader;
+  if (!header) throw new UVerifySignatureError("Missing UVerify-Signature header.");
+  if (!secret) throw new UVerifySignatureError("Missing webhook secret.");
+  const parts = Object.fromEntries(
+    header.split(",").map((p) => {
+      const i = p.indexOf("=");
+      return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
+    })
+  );
+  const t = parts.t;
+  const v1 = parts.v1;
+  if (!t || !v1 || !/^\d+$/.test(t)) throw new UVerifySignatureError("Malformed UVerify-Signature header.");
+  const body = typeof rawBody === "string" ? rawBody : Buffer.from(rawBody).toString("utf8");
+  const expected = (0, import_node_crypto.createHmac)("sha256", secret).update(`${t}.${body}`).digest("hex");
+  const a = Buffer.from(expected, "hex");
+  const b = Buffer.from(v1.length === expected.length ? v1 : "", "hex");
+  if (a.length !== b.length || !(0, import_node_crypto.timingSafeEqual)(a, b)) throw new UVerifySignatureError("Signature does not match. Check the secret and that you passed the raw body.");
+  if (toleranceSeconds > 0 && Math.abs(Date.now() / 1e3 - Number(t)) > toleranceSeconds) throw new UVerifySignatureError("Signature is too old (possible replay).");
+  try {
+    return JSON.parse(body);
+  } catch {
+    throw new UVerifySignatureError("Body is not JSON.");
+  }
+}
+function signPayload(body, secret, timestamp = Math.floor(Date.now() / 1e3)) {
+  return `t=${timestamp},v1=${(0, import_node_crypto.createHmac)("sha256", secret).update(`${timestamp}.${body}`).digest("hex")}`;
+}
+
+// src/client.ts
+var VERSION = "0.1.0";
+var DEFAULT_BASE_URL = "https://api.uverify.com.ng/v1";
+var IMAGE_FIELDS = ["selfie_image", "front_image", "back_image"];
+var newReference = (prefix) => `${prefix}_${(0, import_node_crypto2.randomBytes)(9).toString("base64url")}`;
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function toBase64(v) {
+  return typeof v === "string" ? v : Buffer.from(v).toString("base64");
+}
+var UVerify = class _UVerify {
+  identity;
+  business;
+  verifications;
+  liveness;
+  documents;
+  aml;
+  kyc;
+  account;
+  static webhooks = { constructEvent, signPayload };
+  /** Verify webhook signatures. Also usable without a client: `UVerify.webhooks.constructEvent(…)`. */
+  webhooks = _UVerify.webhooks;
+  apiKey;
+  baseUrl;
+  timeoutMs;
+  maxRetries;
+  fetchImpl;
+  constructor(options = {}) {
+    const o = typeof options === "string" ? { apiKey: options } : options;
+    const key = o.apiKey ?? process.env.UVERIFY_API_KEY ?? "";
+    if (!key) throw new Error("UVerify: pass an apiKey (uvk_test_\u2026 or uvk_live_\u2026) or set UVERIFY_API_KEY.");
+    this.apiKey = key;
+    this.baseUrl = (o.baseUrl ?? process.env.UVERIFY_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeoutMs = o.timeoutMs ?? 6e4;
+    this.maxRetries = o.maxRetries ?? 2;
+    this.fetchImpl = o.fetch ?? fetch;
+    this.identity = new IdentityResource(this);
+    this.business = new BusinessResource(this);
+    this.verifications = new VerificationsResource(this);
+    this.liveness = new LivenessResource(this);
+    this.documents = new DocumentsResource(this);
+    this.aml = new AmlResource(this);
+    this.kyc = new KycResource(this);
+    this.account = new AccountResource(this);
+  }
+  /** 'test' for a sandbox key, 'live' for a live one. */
+  get environment() {
+    return /_live_/.test(this.apiKey) ? "live" : "test";
+  }
+  /** @internal */
+  async request(method, path, opts = {}) {
+    const url = new URL(this.baseUrl + path);
+    for (const [k, v] of Object.entries(opts.query ?? {})) if (v !== void 0) url.searchParams.set(k, String(v));
+    const body = opts.body ? JSON.stringify(Object.fromEntries(Object.entries(opts.body).filter(([, v]) => v !== void 0))) : void 0;
+    const retryable = opts.retryable ?? method === "GET";
+    for (let attempt = 0; ; attempt++) {
+      let res;
+      try {
+        res = await this.fetchImpl(url, {
+          method,
+          headers: {
+            authorization: `Bearer ${this.apiKey}`,
+            accept: "application/json",
+            "user-agent": `uverify-node/${VERSION} node/${process.version}`,
+            ...body ? { "content-type": "application/json" } : {}
+          },
+          body,
+          signal: AbortSignal.timeout(this.timeoutMs)
+        });
+      } catch (e) {
+        if (retryable && attempt < this.maxRetries) {
+          await sleep(backoff(attempt));
+          continue;
+        }
+        const timedOut = e?.name === "TimeoutError";
+        throw new UVerifyConnectionError(timedOut ? `UVerify didn't answer within ${this.timeoutMs}ms.` : `Couldn't reach UVerify: ${e.message}`, e);
+      }
+      const json = await res.json().catch(() => null);
+      if (res.ok && json?.success !== false) return json?.data ?? json;
+      const err = new UVerifyError(json?.error?.message ?? `UVerify returned HTTP ${res.status}.`, {
+        code: json?.error?.code ?? (res.status >= 500 ? "internal_error" : "http_error"),
+        status: res.status,
+        requestId: json?.request_id ?? res.headers.get("x-request-id"),
+        details: json?.error?.details
+      });
+      const rateLimited = res.status === 429 && err.code === "rate_limited";
+      if (retryable && attempt < this.maxRetries && (rateLimited || res.status >= 500 && res.status !== 501)) {
+        const after = Number(err.details?.retry_after_seconds);
+        await sleep(rateLimited && after > 0 ? Math.min(after, 60) * 1e3 : backoff(attempt));
+        continue;
+      }
+      if (attempt > 0 && err.code === "duplicate_reference") throw Object.assign(err, { __duplicateOnRetry: true });
+      throw err;
+    }
+  }
+  /** @internal An identity/business check: always carries a reference, so it can be retried safely. */
+  async check(path, params) {
+    const body = { ...params, reference: params.reference ?? newReference("sdk") };
+    for (const f of IMAGE_FIELDS) if (body[f] !== void 0) body[f] = toBase64(body[f]);
+    try {
+      return await this.request("POST", path, { body, retryable: true });
+    } catch (e) {
+      if (e.__duplicateOnRetry) {
+        const found = await this.verifications.list({ reference: body.reference, per_page: 1 });
+        if (found.items[0]) return this.verifications.get(found.items[0].id);
+      }
+      throw e;
+    }
+  }
+  /** @internal A create that carries a reference (safe to retry). */
+  async create(path, params, prefix) {
+    const body = { ...params, reference: params.reference ?? newReference(prefix) };
+    for (const f of IMAGE_FIELDS) if (body[f] !== void 0) body[f] = toBase64(body[f]);
+    return this.request("POST", path, { body, retryable: true });
+  }
+};
+var backoff = (attempt) => Math.min(8e3, 500 * 2 ** attempt) * (0.75 + Math.random() * 0.5);
+var Resource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+};
+var IdentityResource = class extends Resource {
+  /** BVN lookup. Names are required by the registry. */
+  bvn(params) {
+    return this.client.check("/identity/bvn", params);
+  }
+  /** BVN lookup + face match against the BVN photo. */
+  bvnFaceMatch(params) {
+    return this.client.check("/identity/bvn/face-match", params);
+  }
+  nin(params) {
+    return this.client.check("/identity/nin", params);
+  }
+  ninFaceMatch(params) {
+    return this.client.check("/identity/nin/face-match", params);
+  }
+  driversLicense(params) {
+    return this.client.check("/identity/drivers-license", params);
+  }
+  driversLicenseFaceMatch(params) {
+    return this.client.check("/identity/drivers-license/face-match", params);
+  }
+  votersCard(params) {
+    return this.client.check("/identity/voters-card", params);
+  }
+  votersCardFaceMatch(params) {
+    return this.client.check("/identity/voters-card/face-match", params);
+  }
+  /** Tax ID lookup. */
+  tin(params) {
+    return this.client.check("/identity/tin", params);
+  }
+};
+var BusinessResource = class extends Resource {
+  /** CAC lookup: status, address, directors, owners. */
+  cac(params) {
+    return this.client.check("/business/cac", params);
+  }
+};
+var VerificationsResource = class extends Resource {
+  list(params = {}) {
+    return this.client.request("GET", "/verifications", { query: { ...params } });
+  }
+  /** One verification, with its record. */
+  get(id) {
+    return this.client.request("GET", `/verifications/${encodeURIComponent(id)}`);
+  }
+};
+var LivenessResource = class extends Resource {
+  /** A hosted camera check. Send the person to `session.url`, then pass `session.id` to a face match. */
+  createSession(params = {}) {
+    return this.client.create("/liveness/sessions", params, "lv");
+  }
+  getSession(id) {
+    return this.client.request("GET", `/liveness/sessions/${encodeURIComponent(id)}`);
+  }
+  /** Sandbox only: finish a session without a camera. */
+  simulate(id, params) {
+    return this.client.request("POST", `/liveness/sessions/${encodeURIComponent(id)}/simulate`, { body: { ...params } });
+  }
+};
+var DocumentsResource = class 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) {
+    return this.client.create("/documents/verify", params, "doc");
+  }
+  get(id) {
+    return this.client.request("GET", `/documents/${encodeURIComponent(id)}`);
+  }
+};
+var AmlMonitorsResource = class extends Resource {
+  /** Screen a name now and keep watching it (billed monthly). */
+  create(params) {
+    return this.client.create("/aml/monitors", params, "amon");
+  }
+  list(params = {}) {
+    return this.client.request("GET", "/aml/monitors", { query: { ...params } });
+  }
+  get(id) {
+    return this.client.request("GET", `/aml/monitors/${encodeURIComponent(id)}`);
+  }
+  /** Stop watching a name. */
+  stop(id) {
+    return this.client.request("DELETE", `/aml/monitors/${encodeURIComponent(id)}`, { retryable: true });
+  }
+};
+var AmlResource = class extends Resource {
+  monitors = new AmlMonitorsResource(this.client);
+  /** Screen a person or organisation against the UN, OFAC, UK, EU and Nigeria sanctions lists. */
+  screen(params) {
+    return this.client.create("/aml/screen", params, "aml");
+  }
+  getScreening(id) {
+    return this.client.request("GET", `/aml/screenings/${encodeURIComponent(id)}`);
+  }
+  /** The lists screened, and how fresh each is. */
+  lists() {
+    return this.client.request("GET", "/aml/lists");
+  }
+};
+var KycResource = class extends Resource {
+  /** A hosted verification link: send `link.url` to your customer. */
+  createLink(params = {}) {
+    return this.client.create("/kyc/requests", params, "kyc");
+  }
+  getLink(id) {
+    return this.client.request("GET", `/kyc/requests/${encodeURIComponent(id)}`);
+  }
+  listLinks(params = {}) {
+    return this.client.request("GET", "/kyc/requests", { query: { ...params } });
+  }
+};
+var AccountResource = class extends Resource {
+  balance() {
+    return this.client.request("GET", "/balance");
+  }
+  /** Your prices per check (custom prices included). */
+  pricing() {
+    return this.client.request("GET", "/pricing");
+  }
+};
+
+// src/index.ts
+var index_default = UVerify;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  UVerify,
+  UVerifyConnectionError,
+  UVerifyError,
+  UVerifySignatureError,
+  VERSION,
+  constructEvent,
+  signPayload
+});