بوابة الرقم الضريبي للمورد في الحسابات الدائنة بـ TypeScript

// src/vatNumber.ts
// BR-KSA-40 (XML Implementation Standard v1.2): the seller VAT number
// "must contain 15 digits. The first and the last digits are '3'".
// That is the whole published rule. Nothing here checks more than that.
 
export type VatNumberResult =
  | { ok: true; value: string }
  | { ok: false; reason: VatNumberError; value: string };
 
export type VatNumberError =
  | "EMPTY"
  | "NOT_DIGITS"
  | "LOOKS_LIKE_CR" // 10 digits: almost always a commercial registration number
  | "WRONG_LENGTH"
  | "FIRST_OR_LAST_NOT_3";
 
const ARABIC_INDIC = "٠١٢٣٤٥٦٧٨٩";
const EXTENDED_ARABIC_INDIC = "۰۱۲۳۴۵۶۷۸۹";
 
export function normalizeVatNumber(raw: string): string {
  let out = "";
  for (const ch of raw.trim()) {
    const a = ARABIC_INDIC.indexOf(ch);
    const e = EXTENDED_ARABIC_INDIC.indexOf(ch);
    if (a >= 0) out += String(a);
    else if (e >= 0) out += String(e);
    else if (ch === " " || ch === "-" || ch === " ") continue;
    else out += ch;
  }
  return out;
}
 
export function checkVatNumber(raw: string): VatNumberResult {
  const value = normalizeVatNumber(raw);
  if (value === "") return { ok: false, reason: "EMPTY", value };
  if (!/^[0-9]+$/.test(value)) return { ok: false, reason: "NOT_DIGITS", value };
  if (value.length === 10) return { ok: false, reason: "LOOKS_LIKE_CR", value };
  if (value.length !== 15) return { ok: false, reason: "WRONG_LENGTH", value };
  if (value[0] !== "3" || value[14] !== "3") {
    return { ok: false, reason: "FIRST_OR_LAST_NOT_3", value };
  }
  return { ok: true, value };
}

// src/supplier.ts
import { checkVatNumber, VatNumberError } from "./vatNumber";
 
// Only ZATCA's registration lookup can say a number is registered.
// The supplier record keeps what was checked, when, and how.
 
export type Registration =
  | { status: "unchecked" }
  | { status: "registered"; checkedOn: string; evidence: string }
  | { status: "not_registered"; checkedOn: string; evidence: string };
 
export interface Supplier {
  id: string;
  registeredName: string; // as shown by the ZATCA lookup
  vatNumber: string; // normalised, passed checkVatNumber
  registration: Registration;
}
 
export type CreateResult =
  | { ok: true; supplier: Supplier }
  | { ok: false; reason: VatNumberError };
 
// The gate at onboarding: a malformed number is never saved.
export function createSupplier(id: string, registeredName: string, rawVat: string): CreateResult {
  const vat = checkVatNumber(rawVat);
  if (!vat.ok) return { ok: false, reason: vat.reason };
  return {
    ok: true,
    supplier: { id, registeredName, vatNumber: vat.value, registration: { status: "unchecked" } },
  };
}
 
// Our policy, not a ZATCA rule: a registration check is fresh for the
// period being filed only if it was made on or after the period start.
export function needsLookup(s: Supplier, periodStart: string): boolean {
  return s.registration.status === "unchecked" || s.registration.checkedOn < periodStart;
}
 
// One column of numbers, to paste into the template ZATCA's lookup
// service offers for checking several establishments at once.
export function lookupBatch(suppliers: Supplier[], periodStart: string): string[] {
  const out = new Set<string>();
  for (const s of suppliers) if (needsLookup(s, periodStart)) out.add(s.vatNumber);
  return [...out].sort();
}
 
export interface LookupRow {
  vatNumber: string;
  registered: boolean;
}
 
export function applyLookup(
  suppliers: Supplier[],
  rows: LookupRow[],
  checkedOn: string,
  evidence: string,
): Supplier[] {
  const byNumber = new Map(rows.map((r) => [r.vatNumber, r.registered]));
  return suppliers.map((s) => {
    const registered = byNumber.get(s.vatNumber);
    if (registered === undefined) return s;
    return {
      ...s,
      registration: registered
        ? { status: "registered", checkedOn, evidence }
        : { status: "not_registered", checkedOn, evidence },
    };
  });
}

// src/qr.ts
// Reads the QR payload of a Saudi e-invoice (Security Features
// Implementation Standards, section 4): Base64 of TLV records, one byte
// for the tag, one byte for the length, then the value.
// Tags 1-5 are UTF-8 text. Tags 6-9 (hash, signature, public key, ZATCA
// stamp signature) are kept as raw bytes: this reader does not verify them.
 
export interface ZatcaQr {
  sellerName: string; // tag 1
  sellerVatNumber: string; // tag 2
  timestamp: string; // tag 3, ISO 8601
  totalWithVat: string; // tag 4
  vatTotal: string; // tag 5
  phase2Tags: number[]; // which of 6-9 are present
}
 
export class QrError extends Error {}
 
export function decodeZatcaQr(base64: string): ZatcaQr {
  const bytes = Buffer.from(base64.trim(), "base64");
  if (bytes.length === 0) throw new QrError("QR payload is empty or not Base64");
 
  const text = new Map<number, string>();
  const binary: number[] = [];
  let i = 0;
  while (i < bytes.length) {
    if (i + 2 > bytes.length) throw new QrError(`truncated header at byte ${i}`);
    const tag = bytes[i];
    const len = bytes[i + 1];
    const start = i + 2;
    const end = start + len;
    if (end > bytes.length) throw new QrError(`tag ${tag} runs past the end`);
    if (tag >= 1 && tag <= 5) {
      if (text.has(tag)) throw new QrError(`tag ${tag} appears twice`);
      text.set(tag, bytes.subarray(start, end).toString("utf8"));
    } else if (tag >= 6 && tag <= 9) {
      binary.push(tag);
    } else {
      throw new QrError(`unknown tag ${tag}`);
    }
    i = end;
  }
 
  for (const t of [1, 2, 3, 4, 5]) {
    if (!text.has(t)) throw new QrError(`mandatory tag ${t} is missing`);
  }
  const timestamp = text.get(3)!;
  if (Number.isNaN(Date.parse(timestamp))) {
    throw new QrError(`tag 3 is not a date: ${timestamp}`);
  }
 
  return {
    sellerName: text.get(1)!,
    sellerVatNumber: text.get(2)!,
    timestamp,
    totalWithVat: text.get(4)!,
    vatTotal: text.get(5)!,
    phase2Tags: binary,
  };
}
 
// "1150.00" -> 115000. Integer halalas, never floats.
export function toHalalas(amount: string): number {
  const m = /^(\d+)(?:\.(\d{1,2}))?$/.exec(amount.trim());
  if (!m) throw new QrError(`not an amount: ${amount}`);
  return Number(m[1]) * 100 + Number((m[2] ?? "").padEnd(2, "0"));
}

// src/gate.ts
import { checkVatNumber } from "./vatNumber";
import { decodeZatcaQr, QrError, toHalalas } from "./qr";
import { Supplier, needsLookup } from "./supplier";
 
export interface InboundInvoice {
  supplierId: string;
  kind: "tax" | "simplified";
  printedSellerVat: string; // as typed from the invoice header
  supplyDate: string; // YYYY-MM-DD
  totalWithVat: number; // halalas, as booked
  vat: number; // halalas, as booked
  qr?: string; // Base64 payload, if one was scanned
}
 
export type Decision =
  | { action: "deduct"; notes: string[] }
  | { action: "hold"; reasons: string[] }
  | { action: "no_deduction"; reasons: string[] };
 
// IR Art. 49(8): no deduction "in any period falling after five years
// from the calendar year in which the supply took place". Our reading:
// the last eligible period must end on or before 31 December of year + 5.
export function lastDeductibleDay(supplyDate: string): string {
  const year = Number(supplyDate.slice(0, 4));
  return `${year + 5}-12-31`;
}
 
// Heuristic, ours: enough to catch a different company, not a legal test.
export function sameName(a: string, b: string): boolean {
  const norm = (s: string) =>
    s
      .normalize("NFKC")
      .replace(/[ً-ْـ]/g, "") // harakat and tatweel
      .replace(/[أإآ]/g, "ا")
      .replace(/ة/g, "ه")
      .replace(/ى/g, "ي")
      .toLowerCase()
      .replace(/[^\p{L}\p{N}]+/gu, " ")
      .trim();
  return norm(a) === norm(b);
}
 
export function assessInvoice(
  inv: InboundInvoice,
  supplier: Supplier,
  periodStart: string,
  periodEnd: string,
): Decision {
  if (periodEnd > lastDeductibleDay(inv.supplyDate)) {
    return { action: "no_deduction", reasons: ["OUT_OF_TIME_ART_49_8"] };
  }
  if (supplier.registration.status === "not_registered") {
    return { action: "no_deduction", reasons: ["SUPPLIER_NOT_REGISTERED"] };
  }
 
  const reasons: string[] = [];
  const notes: string[] = [];
 
  const printed = checkVatNumber(inv.printedSellerVat);
  if (!printed.ok) reasons.push(`PRINTED_VAT_${printed.reason}`);
  else if (printed.value !== supplier.vatNumber) reasons.push("PRINTED_VAT_NOT_SUPPLIER_VAT");
 
  if (needsLookup(supplier, periodStart)) reasons.push("REGISTRATION_NOT_CHECKED_THIS_PERIOD");
 
  if (!inv.qr) {
    reasons.push("NO_QR_SCANNED");
  } else {
    try {
      const qr = decodeZatcaQr(inv.qr);
      if (qr.sellerVatNumber !== supplier.vatNumber) reasons.push("QR_VAT_NOT_SUPPLIER_VAT");
      if (!sameName(qr.sellerName, supplier.registeredName)) reasons.push("QR_NAME_NOT_REGISTERED_NAME");
      if (toHalalas(qr.totalWithVat) !== inv.totalWithVat) reasons.push("QR_TOTAL_NOT_BOOKED_TOTAL");
      if (toHalalas(qr.vatTotal) !== inv.vat) reasons.push("QR_VAT_NOT_BOOKED_VAT");
      if (qr.phase2Tags.length === 0) notes.push("QR_HAS_NO_PHASE2_TAGS");
    } catch (e) {
      if (!(e instanceof QrError)) throw e;
      reasons.push(`QR_UNREADABLE: ${e.message}`);
    }
  }
 
  if (inv.kind === "simplified") notes.push("SIMPLIFIED_INVOICE_ART_49_7_A");
 
  return reasons.length > 0 ? { action: "hold", reasons } : { action: "deduct", notes };
}

// tests/gate.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";
import { checkVatNumber } from "../src/vatNumber";
import { decodeZatcaQr, QrError, toHalalas } from "../src/qr";
import { createSupplier, lookupBatch, applyLookup, Supplier } from "../src/supplier";
import { assessInvoice, lastDeductibleDay, InboundInvoice } from "../src/gate";
 
function qr(fields: [number, string][]): string {
  const parts = fields.map(([tag, value]) => {
    const v = Buffer.from(value, "utf8");
    return Buffer.concat([Buffer.from([tag, v.length]), v]);
  });
  return Buffer.concat(parts).toString("base64");
}
 
const VAT = "310122393500003";
const NAME = "شركة المورد للتجارة";
const goodQr = qr([
  [1, NAME],
  [2, VAT],
  [3, "2026-10-12T09:30:00Z"],
  [4, "1150.00"],
  [5, "150.00"],
]);
 
function supplier(): Supplier {
  const r = createSupplier("S1", NAME, VAT);
  if (!r.ok) throw new Error(r.reason);
  return applyLookup([r.supplier], [{ vatNumber: VAT, registered: true }], "2026-10-02", "lookup-2026-10-02.xlsx")[0];
}
 
const invoice: InboundInvoice = {
  supplierId: "S1",
  kind: "tax",
  printedSellerVat: VAT,
  supplyDate: "2026-10-12",
  totalWithVat: 115000,
  vat: 15000,
  qr: goodQr,
};
 
test("BR-KSA-40: 15 digits, first and last are 3", () => {
  assert.equal(checkVatNumber("310122393500003").ok, true);
  assert.equal(checkVatNumber("٣١٠١٢٢٣٩٣٥٠٠٠٠٣").ok, true);
  assert.equal(checkVatNumber("310 1223 9350 0003").ok, true);
  assert.deepEqual(checkVatNumber("1010123456"), { ok: false, reason: "LOOKS_LIKE_CR", value: "1010123456" });
  assert.equal((checkVatNumber("31012239350000") as { reason: string }).reason, "WRONG_LENGTH");
  assert.equal((checkVatNumber("310122393500001") as { reason: string }).reason, "FIRST_OR_LAST_NOT_3");
  assert.equal((checkVatNumber("31012239350000O") as { reason: string }).reason, "NOT_DIGITS");
});
 
test("a malformed number is never saved to the supplier master", () => {
  assert.deepEqual(createSupplier("S2", "x", "7001234567"), { ok: false, reason: "LOOKS_LIKE_CR" });
});
 
test("QR: reads tags 1-5 and notes phase 2 tags", () => {
  const withHash = qr([[1, NAME], [2, VAT], [3, "2026-10-12T09:30:00Z"], [4, "1150.00"], [5, "150.00"], [6, "x".repeat(44)]]);
  const d = decodeZatcaQr(withHash);
  assert.equal(d.sellerName, NAME);
  assert.equal(d.sellerVatNumber, VAT);
  assert.deepEqual(d.phase2Tags, [6]);
});
 
test("QR: missing tag, truncation and bad Base64 are errors", () => {
  assert.throws(() => decodeZatcaQr(qr([[1, NAME], [2, VAT], [3, "2026-10-12T09:30:00Z"], [4, "1150.00"]])), QrError);
  const cut = Buffer.from(goodQr, "base64").subarray(0, 20).toString("base64");
  assert.throws(() => decodeZatcaQr(cut), QrError);
  assert.throws(() => decodeZatcaQr(""), QrError);
});
 
test("amounts are compared in halalas", () => {
  assert.equal(toHalalas("1150.00"), 115000);
  assert.equal(toHalalas("1150.5"), 115050);
  assert.equal(toHalalas("1150"), 115000);
  assert.throws(() => toHalalas("1,150.00"), QrError);
});
 
test("lookup batch lists only numbers not checked this period", () => {
  const s = supplier();
  assert.deepEqual(lookupBatch([s], "2026-10-01"), []);
  assert.deepEqual(lookupBatch([s], "2027-01-01"), [VAT]);
});
 
test("a clean invoice is deducted", () => {
  const d = assessInvoice(invoice, supplier(), "2026-10-01", "2026-12-31");
  assert.equal(d.action, "deduct");
});
 
test("QR seller VAT that differs from the supplier is held", () => {
  const other = qr([[1, NAME], [2, "300000000000003"], [3, "2026-10-12T09:30:00Z"], [4, "1150.00"], [5, "150.00"]]);
  const d = assessInvoice({ ...invoice, qr: other }, supplier(), "2026-10-01", "2026-12-31");
  assert.deepEqual(d, { action: "hold", reasons: ["QR_VAT_NOT_SUPPLIER_VAT"] });
});
 
test("booked VAT that differs from the QR is held", () => {
  const d = assessInvoice({ ...invoice, vat: 15100 }, supplier(), "2026-10-01", "2026-12-31");
  assert.deepEqual(d, { action: "hold", reasons: ["QR_VAT_NOT_BOOKED_VAT"] });
});
 
test("no QR, stale lookup and a CR number in the header all hold", () => {
  const d = assessInvoice({ ...invoice, qr: undefined, printedSellerVat: "1010123456" }, supplier(), "2027-01-01", "2027-03-31");
  assert.equal(d.action, "hold");
  assert.deepEqual((d as { reasons: string[] }).reasons, [
    "PRINTED_VAT_LOOKS_LIKE_CR",
    "REGISTRATION_NOT_CHECKED_THIS_PERIOD",
    "NO_QR_SCANNED",
  ]);
});
 
test("names are compared after Arabic normalisation", () => {
  const variant = qr([[1, "شركه المورد  للتجاره"], [2, VAT], [3, "2026-10-12T09:30:00Z"], [4, "1150.00"], [5, "150.00"]]);
  assert.equal(assessInvoice({ ...invoice, qr: variant }, supplier(), "2026-10-01", "2026-12-31").action, "deduct");
});
 
test("an unregistered supplier gives no right to deduct", () => {
  const s = applyLookup([supplier()], [{ vatNumber: VAT, registered: false }], "2026-11-02", "lookup-2026-11-02.xlsx")[0];
  assert.deepEqual(assessInvoice(invoice, s, "2026-10-01", "2026-12-31"), {
    action: "no_deduction",
    reasons: ["SUPPLIER_NOT_REGISTERED"],
  });
});
 
test("Art. 49(8): a held invoice can still be deducted until year + 5", () => {
  assert.equal(lastDeductibleDay("2026-10-12"), "2031-12-31");
  assert.equal(assessInvoice(invoice, supplier(), "2026-10-01", "2031-12-31").action, "deduct");
  assert.deepEqual(assessInvoice(invoice, supplier(), "2032-01-01", "2032-03-31"), {
    action: "no_deduction",
    reasons: ["OUT_OF_TIME_ART_49_8"],
  });
});

npx tsx --test tests/*.test.ts