واجهة واثق في TypeScript: التحقق من الأعمال السعودية (KYB)

// src/wathq/config.ts
export interface WathqConfig {
  baseUrl: string;      // e.g. https://api.wathq.sa/v5/commercialregistration
  apiKey: string;
  timeoutMs: number;
}
 
export function loadWathqConfig(): WathqConfig {
  const baseUrl = process.env.WATHQ_CR_BASE_URL;
  const apiKey = process.env.WATHQ_API_KEY;
  if (!baseUrl || !apiKey) {
    throw new Error("WATHQ_CR_BASE_URL and WATHQ_API_KEY must be set");
  }
  return { baseUrl, apiKey, timeoutMs: 10_000 };
}

// src/wathq/identifiers.ts
export type CrIdentifier =
  | { kind: "national"; value: string }   // 700xxxxxxx — active/pending records
  | { kind: "legacy"; value: string };    // pre-unification CR number
 
export class CrIdentifierError extends Error {
  constructor(public readonly code: "NOT_DIGITS" | "NOT_TEN_DIGITS") {
    super(code);
  }
}
 
export function parseCrIdentifier(raw: string): CrIdentifier {
  // Merchants paste from PDFs: strip spaces, dashes, and Arabic-Indic digits.
  const ARABIC_INDIC = "٠١٢٣٤٥٦٧٨٩";
  const normalized = [...raw.trim()]
    .map((ch) => {
      const i = ARABIC_INDIC.indexOf(ch);
      return i === -1 ? ch : String(i);
    })
    .join("")
    .replace(/[\s-]/g, "");
 
  // Mirror the API's own validation: 400.1.2 (digits only), 400.1.3 (10 digits)
  if (!/^\d+$/.test(normalized)) throw new CrIdentifierError("NOT_DIGITS");
  if (normalized.length !== 10) throw new CrIdentifierError("NOT_TEN_DIGITS");
 
  return normalized.startsWith("700")
    ? { kind: "national", value: normalized }
    : { kind: "legacy", value: normalized };
}

// src/wathq/client.ts
import type { WathqConfig } from "./config";
 
const BUSINESS_ERRORS = {
  "400.1.1": "INPUT_REQUIRED",
  "400.1.2": "NOT_DIGITS",
  "400.1.3": "NOT_TEN_DIGITS",
  "400.1.4": "BAD_LANGUAGE",
  "400.1.5": "NEEDS_NATIONAL_700_NUMBER",
  "400.1.6": "INVALID_ID_TYPE",
  "400.1.7": "BAD_ID_LENGTH",
  "404.2.1": "NO_RESULTS",
} as const;
 
export type WathqBusinessCode =
  (typeof BUSINESS_ERRORS)[keyof typeof BUSINESS_ERRORS];
 
export class WathqError extends Error {
  constructor(
    public readonly kind:
      | { type: "business"; code: WathqBusinessCode }
      | { type: "auth" }              // 401 / 403 — key invalid or lacks scope
      | { type: "quota" }             // 429 — do NOT blind-retry: costs money
      | { type: "upstream"; status: number }, // 5xx gateway family
  ) {
    super(JSON.stringify(kind));
  }
}
 
export class WathqClient {
  constructor(private readonly config: WathqConfig) {}
 
  private async get<T>(path: string): Promise<T> {
    const res = await fetch(`${this.config.baseUrl}${path}`, {
      headers: { apiKey: this.config.apiKey, Accept: "application/json" },
      signal: AbortSignal.timeout(this.config.timeoutMs),
    });
 
    if (res.ok) return (await res.json()) as T;
 
    if (res.status === 401 || res.status === 403)
      throw new WathqError({ type: "auth" });
    if (res.status === 429) throw new WathqError({ type: "quota" });
    if (res.status >= 500)
      throw new WathqError({ type: "upstream", status: res.status });
 
    // 400/404 carry a business code in the body
    const body = (await res.json().catch(() => null)) as
      | { code?: string }
      | null;
    const mapped =
      body?.code && body.code in BUSINESS_ERRORS
        ? BUSINESS_ERRORS[body.code as keyof typeof BUSINESS_ERRORS]
        : undefined;
    if (mapped) throw new WathqError({ type: "business", code: mapped });
    throw new WathqError({ type: "upstream", status: res.status });
  }
 
  info(id: string, language: "ar" | "en" = "ar") {
    return this.get<CrInfo>(`/info/${id}?language=${language}`);
  }
  fullInfo(id: string, language: "ar" | "en" = "ar") {
    return this.get<CrFullInfo>(`/fullinfo/${id}?language=${language}`);
  }
  owners(id: string, language: "ar" | "en" = "ar") {
    return this.get<CrOwners>(`/owners/${id}?language=${language}`);
  }
  managers(id: string, language: "ar" | "en" = "ar") {
    return this.get<CrManagers>(`/managers/${id}?language=${language}`);
  }
}

// src/wathq/types.ts — minimal shapes the engine depends on
export interface CrInfo {
  crNationalNumber: string;
  name: string;
  status: { name: string };        // e.g. active / suspended / cancelled
  expiryDate?: string;             // present on records that still carry one
  activities: Array<{ id: string; name: string }>;
}
export interface CrOwners {
  parties: Array<{
    identity: { id: string; type: string };
    name: string;
    sharesPercentage?: number;
  }>;
}
export interface CrManagers {
  parties: Array<{ identity: { id: string; type: string }; name: string }>;
}
export type CrFullInfo = CrInfo & { owners?: CrOwners["parties"] };

// src/wathq/cached-client.ts
import type { Redis } from "ioredis";
import { WathqClient, WathqError } from "./client";
import type { CrFullInfo } from "./types";
 
const POSITIVE_TTL = 24 * 60 * 60; // seconds
const NEGATIVE_TTL = 60 * 60;
 
export class CachedWathqClient {
  constructor(
    private readonly inner: WathqClient,
    private readonly redis: Redis,
  ) {}
 
  async fullInfo(id: string): Promise<CrFullInfo | null> {
    const key = `wathq:cr:fullinfo:${id}`;
    const hit = await this.redis.get(key);
    if (hit !== null) {
      return hit === "" ? null : (JSON.parse(hit) as CrFullInfo);
    }
    try {
      const fresh = await this.inner.fullInfo(id);
      await this.redis.set(key, JSON.stringify(fresh), "EX", POSITIVE_TTL);
      return fresh;
    } catch (err) {
      if (
        err instanceof WathqError &&
        err.kind.type === "business" &&
        err.kind.code === "NO_RESULTS"
      ) {
        await this.redis.set(key, "", "EX", NEGATIVE_TTL);
        return null;
      }
      throw err; // quota/auth/upstream: never cached, always surfaced
    }
  }
}

// src/verify/engine.ts
import type { CachedWathqClient } from "../wathq/cached-client";
import { parseCrIdentifier, CrIdentifierError } from "../wathq/identifiers";
 
// Same national-ID shape used in our Nafath tutorial: 10 digits, 1=citizen, 2=resident
const NID = /^[12]\d{9}$/;
 
export type Verdict =
  | { outcome: "verified"; crNationalNumber: string; verifiedAt: string }
  | { outcome: "rejected"; reasons: RejectReason[] }
  | { outcome: "needs_review"; reasons: RejectReason[] };
 
export type RejectReason =
  // merchant-fixable — ask for corrected input
  | "MALFORMED_CR_INPUT"
  | "LEGACY_NUMBER_PROVIDED"
  | "CR_NOT_FOUND"
  // terminal — do not onboard
  | "CR_NOT_ACTIVE"
  | "CR_EXPIRED"
  // judgement calls — route to a human
  | "ACTIVITY_MISMATCH"
  | "SIGNATORY_NOT_OWNER_OR_MANAGER";
 
export async function verifyBusiness(
  client: CachedWathqClient,
  input: { crRaw: string; signatoryNid: string; requiredActivityIds: string[] },
  asOf: Date, // injected, never new Date() inside — keeps replays honest
): Promise<Verdict> {
  if (!NID.test(input.signatoryNid)) {
    return { outcome: "rejected", reasons: ["MALFORMED_CR_INPUT"] };
  }
 
  let id;
  try {
    id = parseCrIdentifier(input.crRaw);
  } catch (err) {
    if (err instanceof CrIdentifierError) {
      return { outcome: "rejected", reasons: ["MALFORMED_CR_INPUT"] };
    }
    throw err;
  }
  if (id.kind === "legacy") {
    // Don't spend an inquiry to be told 400.1.5 — we already know.
    return { outcome: "rejected", reasons: ["LEGACY_NUMBER_PROVIDED"] };
  }
 
  const record = await client.fullInfo(id.value);
  if (record === null) {
    return { outcome: "rejected", reasons: ["CR_NOT_FOUND"] };
  }
 
  const reasons: RejectReason[] = [];
 
  if (record.status.name.toLowerCase() !== "active") {
    reasons.push("CR_NOT_ACTIVE");
  }
  if (record.expiryDate && new Date(record.expiryDate) < asOf) {
    reasons.push("CR_EXPIRED");
  }
  if (reasons.length > 0) return { outcome: "rejected", reasons };
 
  const activityOk = record.activities.some((a) =>
    input.requiredActivityIds.includes(a.id),
  );
  if (!activityOk) reasons.push("ACTIVITY_MISMATCH");
 
  const parties = record.owners ?? [];
  const signatoryListed = parties.some(
    (p) => p.identity.id === input.signatoryNid,
  );
  if (!signatoryListed) reasons.push("SIGNATORY_NOT_OWNER_OR_MANAGER");
 
  if (reasons.length > 0) return { outcome: "needs_review", reasons };
 
  return {
    outcome: "verified",
    crNationalNumber: record.crNationalNumber,
    verifiedAt: asOf.toISOString(),
  };
}

// src/verify/ledger.ts
export interface VerificationRow {
  crNationalNumber: string;
  lastVerifiedAt: string;       // ISO date of last confirmed-good check
  lastOutcome: "verified" | "rejected" | "needs_review";
}
 
const RECHECK_AFTER_DAYS = 30;
 
export function dueForRecheck(rows: VerificationRow[], asOf: Date) {
  const cutoff = new Date(asOf);
  cutoff.setUTCDate(cutoff.getUTCDate() - RECHECK_AFTER_DAYS);
  return rows.filter(
    (r) => r.lastOutcome === "verified" && new Date(r.lastVerifiedAt) < cutoff,
  );
}

// test/engine.test.ts
import { describe, it, expect } from "vitest";
import { verifyBusiness } from "../src/verify/engine";
 
const ASOF = new Date("2026-08-20T00:00:00.000Z");
 
function stubClient(record: unknown) {
  return { fullInfo: async () => record } as never;
}
 
const ACTIVE = {
  crNationalNumber: "7001234567",
  name: "مؤسسة المثال التجارية",
  status: { name: "active" },
  activities: [{ id: "4791", name: "Retail via internet" }],
  owners: [{ identity: { id: "1234567890", type: "nid" }, name: "صاحب السجل" }],
};
 
describe("verifyBusiness", () => {
  it("rejects a legacy CR number without spending an inquiry", async () => {
    const v = await verifyBusiness(
      stubClient(ACTIVE),
      { crRaw: "1010123456", signatoryNid: "1234567890", requiredActivityIds: ["4791"] },
      ASOF,
    );
    expect(v).toEqual({ outcome: "rejected", reasons: ["LEGACY_NUMBER_PROVIDED"] });
  });
 
  it("normalizes Arabic-Indic digits before classifying", async () => {
    const v = await verifyBusiness(
      stubClient(ACTIVE),
      { crRaw: "٧٠٠١٢٣٤٥٦٧", signatoryNid: "1234567890", requiredActivityIds: ["4791"] },
      ASOF,
    );
    expect(v.outcome).toBe("verified");
  });
 
  it("routes an unlisted signatory to review, not rejection", async () => {
    const v = await verifyBusiness(
      stubClient(ACTIVE),
      { crRaw: "7001234567", signatoryNid: "2999999999", requiredActivityIds: ["4791"] },
      ASOF,
    );
    expect(v).toEqual({
      outcome: "needs_review",
      reasons: ["SIGNATORY_NOT_OWNER_OR_MANAGER"],
    });
  });
});