@uverifyng/node 0.1.0

package/dist/index.js

@@ -0,0 +1,322 @@
+// src/client.ts
+import { randomBytes } from "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
+import { createHmac, timingSafeEqual } from "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 = 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 || !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=${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}_${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;
+export {
+  UVerify,
+  UVerifyConnectionError,
+  UVerifyError,
+  UVerifySignatureError,
+  VERSION,
+  constructEvent,
+  index_default as default,
+  signPayload
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@uverifyng/node",
+  "version": "0.1.0",
+  "description": "Official Node.js library for the UVerify API: BVN, NIN and ID checks, liveness, face match, ID documents and AML screening for Nigeria.",
+  "license": "MIT",
+  "author": "Elasto Web Services Limited",
+  "homepage": "https://uverify.com.ng/docs",
+  "repository": { "type": "git", "url": "https://github.com/elastodev/uverify-sdks", "directory": "node" },
+  "keywords": ["uverify", "kyc", "bvn", "nin", "liveness", "face-match", "aml", "nigeria", "identity-verification"],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
+    }
+  },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=18" },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}