بناء محرك مطابقة تسوية المدفوعات السعودية بـ TypeScript

npm install -D typescript vitest

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "skipLibCheck": true
  }
}

/** A signed integer number of halalas. 1 SAR = 100 halalas. */
export type Halalas = number & { readonly __brand: unique symbol };
 
export function halalas(value: number): Halalas {
  if (!Number.isSafeInteger(value)) {
    throw new RangeError(`Halalas must be a safe integer, received: ${value}`);
  }
  return value as Halalas;
}
 
export function addHalalas(...values: Halalas[]): Halalas {
  return halalas(values.reduce<number>((sum, v) => sum + v, 0));
}
 
/** Accepts "1234.56", "1,234.5", "-80", "0.07". Rejects anything else. */
const SAR_DECIMAL = /^(-)?(\d{1,3}(?:,\d{3})*|\d+)(?:\.(\d{1,2}))?$/;
 
export function parseSarToHalalas(raw: string): Halalas {
  const trimmed = raw.trim();
  const match = SAR_DECIMAL.exec(trimmed);
  if (match === null) {
    throw new TypeError(`Unparseable SAR amount: ${JSON.stringify(raw)}`);
  }
  const [, sign, whole = '0', fraction = ''] = match;
  const units = Number.parseInt(whole.replace(/,/g, ''), 10);
  const cents = Number.parseInt(fraction.padEnd(2, '0'), 10);
  const magnitude = units * 100 + cents;
  return halalas(sign === '-' ? -magnitude : magnitude);
}

/**
 * VAT on the acquirer fee, rounded half-up on the absolute value so that a
 * refund's fee VAT mirrors the sale's exactly instead of drifting by 1 halala.
 */
export function vatOnFee(fee: Halalas, ratePercent: number): Halalas {
  const sign = fee < 0 ? -1 : 1;
  const raw = (Math.abs(fee) * ratePercent) / 100;
  return halalas(sign * Math.round(raw));
}

/** Saudi Arabia's weekend is Friday and Saturday, not Saturday and Sunday. */
const FRIDAY = 5;
const SATURDAY = 6;
 
export type IsoDate = string; // YYYY-MM-DD
 
const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
 
function toUtc(date: IsoDate): Date {
  if (!ISO_DATE.test(date)) {
    throw new TypeError(`Expected YYYY-MM-DD, received: ${JSON.stringify(date)}`);
  }
  const parsed = new Date(`${date}T00:00:00.000Z`);
  // Date rolls impossible days over silently: '2026-02-30' becomes March 2nd
  // rather than NaN. Only a round-trip comparison catches that.
  if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== date) {
    throw new TypeError(`Not a real calendar date: ${date}`);
  }
  return parsed;
}
 
export function isBusinessDay(date: IsoDate, holidays: ReadonlySet<IsoDate>): boolean {
  const day = toUtc(date).getUTCDay();
  return day !== FRIDAY && day !== SATURDAY && !holidays.has(date);
}
 
/** Walks forward `count` business days, skipping Fri/Sat and Eid closures. */
export function addBusinessDays(
  start: IsoDate,
  count: number,
  holidays: ReadonlySet<IsoDate> = new Set(),
): IsoDate {
  if (!Number.isInteger(count) || count < 0) {
    throw new RangeError(`count must be a non-negative integer, received: ${count}`);
  }
  const cursor = toUtc(start);
  let remaining = count;
  while (remaining > 0) {
    cursor.setUTCDate(cursor.getUTCDate() + 1);
    if (isBusinessDay(cursor.toISOString().slice(0, 10), holidays)) remaining -= 1;
  }
  return cursor.toISOString().slice(0, 10);
}

export type Provider = 'mada' | 'moyasar' | 'tabby';
export type EntryKind = 'sale' | 'refund' | 'chargeback' | 'adjustment';
 
/** What our own system believes happened. */
export interface LedgerEntry {
  readonly paymentId: string;
  readonly orderId: string;
  readonly provider: Provider;
  /** The PSP's own id, when we stored it. Null for terminal-only sales. */
  readonly providerRef: string | null;
  /** Retrieval Reference Number — the only id a mada acquirer file guarantees. */
  readonly rrn: string | null;
  readonly kind: Extract<EntryKind, 'sale' | 'refund'>;
  /** Signed: sales positive, refunds negative. */
  readonly grossHalalas: Halalas;
  readonly capturedOn: IsoDate;
}
 
/** What the money actually did, according to the settlement file. */
export interface SettlementRow {
  readonly fileId: string;
  readonly rowId: string;
  readonly provider: Provider;
  readonly providerRef: string | null;
  readonly rrn: string | null;
  readonly kind: EntryKind;
  readonly grossHalalas: Halalas;
  /** What the acquirer kept. Positive on sales, zero on most refunds. */
  readonly feeHalalas: Halalas;
  readonly feeVatHalalas: Halalas;
  /** Must equal gross - fee - feeVat. Verified on ingest. */
  readonly netHalalas: Halalas;
  readonly settledOn: IsoDate;
}

export interface ProviderPolicy {
  /** Business days from capture to money-in-bank before we call it overdue. */
  readonly settlementSlaBusinessDays: number;
  /** Tolerance for rounding drift between our fee model and theirs. */
  readonly feeToleranceHalalas: number;
}
 
export const DEFAULT_POLICIES: Readonly<Record<Provider, ProviderPolicy>> = {
  // Card rails settle fast; anything past this is a real operational break.
  mada: { settlementSlaBusinessDays: 2, feeToleranceHalalas: 2 },
  moyasar: { settlementSlaBusinessDays: 3, feeToleranceHalalas: 2 },
  // BNPL pays the merchant on its own cycle, unrelated to customer instalments.
  tabby: { settlementSlaBusinessDays: 7, feeToleranceHalalas: 5 },
};

export interface RawMadaRow {
  readonly RRN: string;
  readonly AUTH_CODE: string;
  readonly TXN_TYPE: string;
  readonly TXN_AMOUNT: string;
  readonly MDR_AMOUNT: string;
  readonly MDR_VAT: string;
  readonly NET_AMOUNT: string;
  readonly SETTLEMENT_DATE: string;
}
 
export function normaliseMadaRow(fileId: string, index: number, raw: RawMadaRow): SettlementRow {
  const isCredit = raw.TXN_TYPE === 'REFUND' || raw.TXN_TYPE === 'CHARGEBACK';
  const sign = isCredit ? -1 : 1;
  return {
    fileId,
    rowId: `${fileId}:${index}`,
    provider: 'mada',
    providerRef: null,
    rrn: raw.RRN,
    kind: raw.TXN_TYPE === 'CHARGEBACK' ? 'chargeback' : isCredit ? 'refund' : 'sale',
    grossHalalas: halalas(sign * parseSarToHalalas(raw.TXN_AMOUNT)),
    feeHalalas: halalas(sign * parseSarToHalalas(raw.MDR_AMOUNT)),
    feeVatHalalas: halalas(sign * parseSarToHalalas(raw.MDR_VAT)),
    netHalalas: halalas(sign * parseSarToHalalas(raw.NET_AMOUNT)),
    settledOn: raw.SETTLEMENT_DATE,
  };
}

export class FeeInvariantError extends Error {
  constructor(readonly row: SettlementRow, readonly expected: Halalas) {
    super(
      `Row ${row.rowId}: net ${row.netHalalas} != gross ${row.grossHalalas} ` +
        `- fee ${row.feeHalalas} - vat ${row.feeVatHalalas} (expected ${expected})`,
    );
    this.name = 'FeeInvariantError';
  }
}
 
export function assertFeeInvariant(row: SettlementRow): void {
  const expected = addHalalas(
    row.grossHalalas,
    halalas(-row.feeHalalas),
    halalas(-row.feeVatHalalas),
  );
  if (expected !== row.netHalalas) throw new FeeInvariantError(row, expected);
}

export interface IngestResult {
  readonly accepted: readonly SettlementRow[];
  readonly duplicates: readonly string[];
  readonly rejected: readonly { readonly rowId: string; readonly reason: string }[];
}
 
export function ingest(
  rows: readonly SettlementRow[],
  alreadyIngested: ReadonlySet<string> = new Set(),
): IngestResult {
  const seen = new Set(alreadyIngested);
  const accepted: SettlementRow[] = [];
  const duplicates: string[] = [];
  const rejected: { rowId: string; reason: string }[] = [];
 
  for (const row of rows) {
    if (seen.has(row.rowId)) {
      duplicates.push(row.rowId);
      continue;
    }
    try {
      assertFeeInvariant(row);
      seen.add(row.rowId);
      accepted.push(row);
    } catch (error) {
      rejected.push({
        rowId: row.rowId,
        reason: error instanceof Error ? error.message : String(error),
      });
    }
  }
  return { accepted, duplicates, rejected };
}

interface Claim {
  readonly entry: LedgerEntry;
  readonly rows: SettlementRow[];
  tier: 1 | 2 | 3;
}

export function matchEntries(
  ledger: readonly LedgerEntry[],
  rows: readonly SettlementRow[],
  policies: Readonly<Record<Provider, ProviderPolicy>>,
  holidays: ReadonlySet<IsoDate>,
): { claims: Claim[]; unclaimed: SettlementRow[] } {
  const available = new Map(rows.map((row) => [row.rowId, row]));
  const claims: Claim[] = [];
 
  const take = (candidates: SettlementRow[]): SettlementRow[] => {
    for (const row of candidates) available.delete(row.rowId);
    return candidates;
  };
 
  const remaining = (predicate: (row: SettlementRow) => boolean): SettlementRow[] =>
    [...available.values()].filter(predicate);
 
  for (const entry of ledger) {
    const sameProvider = (row: SettlementRow): boolean => row.provider === entry.provider;
 
    if (entry.providerRef !== null) {
      const byRef = remaining((r) => sameProvider(r) && r.providerRef === entry.providerRef);
      if (byRef.length > 0) {
        claims.push({ entry, rows: take(byRef), tier: 1 });
        continue;
      }
    }
 
    if (entry.rrn !== null) {
      const byRrn = remaining(
        (r) => sameProvider(r) && r.rrn === entry.rrn && r.grossHalalas === entry.grossHalalas,
      );
      if (byRrn.length > 0) {
        claims.push({ entry, rows: take(byRrn), tier: 2 });
        continue;
      }
    }
 
    const policy = policies[entry.provider];
    const deadline = addBusinessDays(entry.capturedOn, policy.settlementSlaBusinessDays, holidays);
    const byWindow = remaining(
      (r) =>
        sameProvider(r) &&
        r.grossHalalas === entry.grossHalalas &&
        r.settledOn >= entry.capturedOn &&
        r.settledOn <= deadline,
    );
    // Exactly one, or we refuse — two identical amounts on the same day are a
    // genuinely ambiguous pair and a human has to look at them.
    if (byWindow.length === 1) {
      claims.push({ entry, rows: take(byWindow), tier: 3 });
    } else {
      claims.push({ entry, rows: [], tier: 3 });
    }
  }
 
  return { claims, unclaimed: [...available.values()] };
}

export type BreakCode =
  | 'MISSING_IN_SETTLEMENT'
  | 'OVERDUE_IN_SETTLEMENT'
  | 'MISSING_IN_LEDGER'
  | 'AMOUNT_MISMATCH'
  | 'DUPLICATE_SETTLEMENT'
  | 'FEE_INVARIANT_BROKEN';

function sumBy(rows: readonly SettlementRow[], pick: (r: SettlementRow) => Halalas): Halalas {
  return addHalalas(...rows.map(pick));
}
 
export interface ReconcileInput {
  readonly asOf: IsoDate;
  readonly ledger: readonly LedgerEntry[];
  readonly settlement: readonly SettlementRow[];
  readonly policies?: Readonly<Record<Provider, ProviderPolicy>>;
  readonly holidays?: ReadonlySet<IsoDate>;
}

export function reconcile(input: ReconcileInput): ReconciliationReport {
  const policies = input.policies ?? DEFAULT_POLICIES;
  const holidays = input.holidays ?? new Set<IsoDate>();
  const { claims, unclaimed } = matchEntries(input.ledger, input.settlement, policies, holidays);
 
  const breaks: Break[] = [];
  const matched: MatchedPair[] = [];
  let grossSettled = halalas(0);
  let netSettled = halalas(0);
  let fees = halalas(0);
  let unsettled = halalas(0);
 
  for (const claim of claims) {
    const { entry, rows } = claim;
    const policy = policies[entry.provider];
 
    if (rows.length === 0) {
      unsettled = addHalalas(unsettled, entry.grossHalalas);
      const deadline = addBusinessDays(entry.capturedOn, policy.settlementSlaBusinessDays, holidays);
      const overdue = input.asOf > deadline;
      breaks.push({
        code: overdue ? 'OVERDUE_IN_SETTLEMENT' : 'MISSING_IN_SETTLEMENT',
        provider: entry.provider,
        paymentId: entry.paymentId,
        rowIds: [],
        expectedHalalas: entry.grossHalalas,
        actualHalalas: null,
        detail: overdue
          ? `Captured ${entry.capturedOn}, due by ${deadline}, still unsettled on ${input.asOf}.`
          : `Captured ${entry.capturedOn}, within SLA until ${deadline}.`,
      });
      continue;
    }
 
    const gross = sumBy(rows, (r) => r.grossHalalas);
    const net = sumBy(rows, (r) => r.netHalalas);
    const fee = addHalalas(
      sumBy(rows, (r) => r.feeHalalas),
      sumBy(rows, (r) => r.feeVatHalalas),
    );
 
    if (rows.length > 1) {
      breaks.push({
        code: 'DUPLICATE_SETTLEMENT',
        provider: entry.provider,
        paymentId: entry.paymentId,
        rowIds: rows.map((r) => r.rowId),
        expectedHalalas: entry.grossHalalas,
        actualHalalas: gross,
        detail: `${rows.length} settlement rows point at one payment.`,
      });
    } else if (Math.abs(gross - entry.grossHalalas) > policy.feeToleranceHalalas) {
      breaks.push({
        code: 'AMOUNT_MISMATCH',
        provider: entry.provider,
        paymentId: entry.paymentId,
        rowIds: rows.map((r) => r.rowId),
        expectedHalalas: entry.grossHalalas,
        actualHalalas: gross,
        detail: `Ledger and settlement disagree by ${gross - entry.grossHalalas} halalas.`,
      });
    }
 
    grossSettled = addHalalas(grossSettled, gross);
    netSettled = addHalalas(netSettled, net);
    fees = addHalalas(fees, fee);
    matched.push({
      paymentId: entry.paymentId,
      tier: claim.tier,
      rowIds: rows.map((r) => r.rowId),
      grossHalalas: gross,
      netHalalas: net,
      feeHalalas: fee,
    });
  }
 
  for (const row of unclaimed) {
    breaks.push({
      code: 'MISSING_IN_LEDGER',
      provider: row.provider,
      paymentId: null,
      rowIds: [row.rowId],
      expectedHalalas: null,
      actualHalalas: row.grossHalalas,
      detail: `Settled ${row.settledOn} as ${row.kind}, no matching ledger entry.`,
    });
  }
 
  return {
    asOf: input.asOf,
    matched,
    breaks,
    totals: {
      grossSettledHalalas: grossSettled,
      netSettledHalalas: netSettled,
      feesHalalas: fees,
      unsettledHalalas: unsettled,
    },
  };
}

it('nets a refund that settles in a later batch than its sale', () => {
  const report = reconcile({
    asOf: '2026-08-25',
    ledger: [
      entry({ paymentId: 'pay_1', providerRef: 'moy_a', provider: 'moyasar' }),
      entry({
        paymentId: 'pay_2',
        providerRef: 'moy_a_r',
        provider: 'moyasar',
        kind: 'refund',
        grossHalalas: halalas(-115000),
        capturedOn: '2026-08-19',
      }),
    ],
    settlement: [
      row({ providerRef: 'moy_a', provider: 'moyasar' }),
      row({
        rowId: 'MADA-20260820:0',
        providerRef: 'moy_a_r',
        provider: 'moyasar',
        kind: 'refund',
        grossHalalas: halalas(-115000),
        feeHalalas: halalas(0),
        feeVatHalalas: halalas(0),
        netHalalas: halalas(-115000),
        settledOn: '2026-08-20',
      }),
    ],
  });
 
  expect(report.breaks).toHaveLength(0);
  expect(report.totals.grossSettledHalalas).toBe(0);
  // The sale's MDR is not returned when the customer is refunded.
  expect(report.totals.netSettledHalalas).toBe(-1323);
  expect(report.totals.feesHalalas).toBe(1323);
});

npx tsc --noEmit && npx vitest run

it('treats Friday and Saturday as the weekend', () => {
  expect(isBusinessDay('2026-08-14', new Set())).toBe(false); // Friday
  expect(isBusinessDay('2026-08-15', new Set())).toBe(false); // Saturday
  expect(isBusinessDay('2026-08-16', new Set())).toBe(true);  // Sunday is a work day
});
 
it('skips the weekend when computing a T+2 deadline', () => {
  // Thursday + 2 business days lands on Monday, not Saturday.
  expect(addBusinessDays('2026-08-13', 2)).toBe('2026-08-17');
});
 
it('refuses to guess between two identical amounts', () => {
  const report = reconcile({
    asOf: '2026-08-18',
    ledger: [entry({ rrn: null })],
    settlement: [row({ rrn: null }), row({ rrn: null, rowId: 'MADA-20260817:1' })],
  });
  expect(report.breaks.map((b) => b.code).sort()).toEqual([
    'MISSING_IN_LEDGER',
    'MISSING_IN_LEDGER',
    'OVERDUE_IN_SETTLEMENT',
  ]);
});
 
it('does not cross-match between providers', () => {
  const report = reconcile({
    asOf: '2026-08-18',
    ledger: [entry({ provider: 'tabby', rrn: null, providerRef: null })],
    settlement: [row({ rrn: null, providerRef: null })],
  });
  expect(report.breaks.map((b) => b.code).sort()).toEqual([
    'MISSING_IN_LEDGER',
    'MISSING_IN_SETTLEMENT',
  ]);
});