محرك أجر الإجازة المرضية بـ TypeScript — المادة 117

/**
 * Which statutory instrument governs this employment relationship.
 *
 * `labour-law` — a private-sector contract under نظام العمل. Article 117
 *   applies: 30 days full, 60 at three quarters, 30 unpaid, per sick year.
 *
 * `civil-service` — a government post under the public-sector human-resources
 *   regulations. A materially longer and differently tiered ladder applies.
 *   This engine does NOT implement it.
 */
export type Regime = 'labour-law' | 'civil-service';
 
export class RegimeNotSupportedError extends Error {
  constructor(public readonly regime: Regime) {
    super(
      `Sick leave under the ${regime} regime is not implemented by this engine. ` +
        `Article 117 of the Labour Law governs private-sector contracts only.`,
    );
    this.name = 'RegimeNotSupportedError';
  }
}
 
export function assertLabourLaw(regime: Regime): asserts regime is 'labour-law' {
  if (regime !== 'labour-law') throw new RegimeNotSupportedError(regime);
}

/** All money is integer halalas. 1 SAR = 100 halalas. Never floats. */
export type Halalas = number;
 
export type WageComponents = {
  basic: Halalas;
  housing: Halalas;
  transport: Halalas;
  /** Other fixed monthly pay: allowances, and in-kind benefits at their contract value. */
  otherRegular: Halalas;
  /**
   * Variable pay — commission, percentage of sales, piece rates. Part of the
   * actual wage under Article 2, averaged per day actually worked under
   * Article 96. `earned` over the reference period, `workedDays` in it.
   */
  variable: { earned: Halalas; workedDays: number };
};
 
export type WageBase = 'actual' | 'basic';
 
/** The fixed monthly part of the wage. Variable pay has no monthly figure. */
export function fixedMonthlyWage(w: WageComponents, base: WageBase): Halalas {
  if (base === 'basic') return w.basic;
  return w.basic + w.housing + w.transport + w.otherRegular;
}
 
/** Article 96: variable pay divided by the days actually worked to earn it. */
export function variableDailyAverage(w: WageComponents): number {
  const { earned, workedDays } = w.variable;
  if (earned === 0) return 0;
  if (!Number.isInteger(workedDays) || workedDays <= 0) {
    throw new RangeError('variable.workedDays must be a positive whole number');
  }
  return earned / workedDays;
}
 
/**
 * The daily rate. The fixed part is priced at a thirtieth of the month
 * (Article 2 defines the month as thirty days), whatever the calendar month
 * holds. The variable part is already a daily figure. Kept fractional on
 * purpose — see Step 4.
 */
export function dailyRate(w: WageComponents, base: WageBase): number {
  const fixed = fixedMonthlyWage(w, base) / 30;
  return base === 'basic' ? fixed : fixed + variableDailyAverage(w);
}

/** Article 10: Hijri unless the contract or the work regulations say otherwise. */
export type CalendarBasis = 'hijri' | 'gregorian';
 
export type SickYear = {
  /** Inclusive ISO date on which this window opened. */
  start: string;
  /** Inclusive ISO date on which it closes: the day before the same date a year on. */
  end: string;
  calendar: CalendarBasis;
};
 
const DAY_MS = 86_400_000;
 
type Ymd = readonly [number, number, number];
 
const HIJRI = new Intl.DateTimeFormat('en-u-ca-islamic-umalqura-nu-latn', {
  timeZone: 'UTC',
  year: 'numeric',
  month: 'numeric',
  day: 'numeric',
});
 
function toUTC(iso: string): number {
  const [y, m, d] = iso.split('-').map(Number);
  return Date.UTC(y, m - 1, d);
}
 
function toISO(ms: number): string {
  return new Date(ms).toISOString().slice(0, 10);
}
 
function partsOf(ms: number, calendar: CalendarBasis): Ymd {
  const date = new Date(ms);
  if (calendar === 'gregorian') {
    return [date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate()];
  }
  const parts = HIJRI.formatToParts(date);
  const pick = (type: string) => Number(parts.find((p) => p.type === type)?.value);
  return [pick('year'), pick('month'), pick('day')];
}
 
const compare = (a: Ymd, b: Ymd) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
 
/** The latest day whose date is on or before `target`. `guess` only needs to be close. */
function lastDayOnOrBefore(target: Ymd, calendar: CalendarBasis, guess: number): number {
  let t = guess;
  while (compare(partsOf(t + DAY_MS, calendar), target) <= 0) t += DAY_MS;
  while (compare(partsOf(t, calendar), target) > 0) t -= DAY_MS;
  return t;
}
 
const YEAR_DAYS: Record<CalendarBasis, number> = { gregorian: 365, hijri: 354 };
 
export function openSickYear(firstSickDay: string, calendar: CalendarBasis): SickYear {
  const start = toUTC(firstSickDay);
  const [y, m, d] = partsOf(start, calendar);
  // The day before the same date one year on. Day 0 sorts before day 1, so a
  // window opened on the 1st closes on the last day of the previous month,
  // and a date the closing month lacks settles on that month's last day.
  const guess = start + (YEAR_DAYS[calendar] - 1) * DAY_MS;
  const end = lastDayOnOrBefore([y + 1, m, d - 1], calendar, guess);
  return { start: firstSickDay, end: toISO(end), calendar };
}
 
export function isWithin(year: SickYear, day: string): boolean {
  const t = toUTC(day);
  return t >= toUTC(year.start) && t <= toUTC(year.end);
}

export type Tier = {
  /** Cumulative day number, inclusive, at which this tier ends. */
  throughDay: number;
  numerator: number;
  denominator: number;
  label: string;
};
 
/** Article 117: 30 days full, the next 60 at three quarters, the next 30 unpaid. */
export const ARTICLE_117: readonly Tier[] = [
  { throughDay: 30, numerator: 1, denominator: 1, label: 'full pay' },
  { throughDay: 90, numerator: 3, denominator: 4, label: 'three quarters' },
  { throughDay: 120, numerator: 0, denominator: 1, label: 'unpaid' },
];
 
/**
 * Split `days` new sick days, starting after `alreadyUsed` days consumed in
 * this window, into per-tier slices. Days beyond 120 fall outside the
 * entitlement entirely and are returned separately.
 */
export function splitAcrossTiers(
  alreadyUsed: number,
  days: number,
): { slices: { tier: Tier; days: number }[]; beyondEntitlement: number } {
  const slices: { tier: Tier; days: number }[] = [];
  let cursor = alreadyUsed;
  let remaining = days;
 
  for (const tier of ARTICLE_117) {
    if (remaining <= 0) break;
    const roomInTier = tier.throughDay - cursor;
    if (roomInTier <= 0) continue;
    const take = Math.min(roomInTier, remaining);
    slices.push({ tier, days: take });
    cursor += take;
    remaining -= take;
  }
 
  return { slices, beyondEntitlement: remaining };
}

export type PaySlice = {
  tier: string;
  days: number;
  amount: Halalas;
};
 
export function priceSlices(
  slices: { tier: Tier; days: number }[],
  rate: number,
): PaySlice[] {
  return slices.map(({ tier, days }) => ({
    tier: tier.label,
    days,
    // Multiply across the whole slice, then round once. Rounding per day
    // drifts by several riyals over a 60-day spell.
    amount: Math.round((rate * days * tier.numerator) / tier.denominator),
  }));
}

export type AbsenceCause = 'illness' | 'occupational-injury';
 
export type Routed =
  | { route: 'article-117'; days: string[] }
  | { route: 'occupational-hazards'; days: string[]; note: string };
 
export function routeByCause(cause: AbsenceCause, days: string[]): Routed {
  if (cause === 'occupational-injury') {
    return {
      route: 'occupational-hazards',
      days,
      note:
        'Compensated through the occupational hazards branch of social insurance. ' +
        'Does NOT consume Article 117 balance and must not be paid as sick leave.',
    };
  }
  return { route: 'article-117', days };
}

export type Certificate = {
  /** The sick leave service code issued with the certificate. */
  code: string;
  from: string;
  to: string;
  cause: AbsenceCause;
  /** Set only after checking the code against the issuing platform. */
  verified: boolean;
  verifiedAt?: string;
};
 
export class UnverifiedCertificateError extends Error {
  constructor(code: string) {
    super(
      `Sick leave certificate ${code} has not been verified. ` +
        `Days covered by it cannot be paid under Article 117.`,
    );
    this.name = 'UnverifiedCertificateError';
  }
}
 
export function assertVerified(cert: Certificate): void {
  if (!cert.verified) throw new UnverifiedCertificateError(cert.code);
}

export type Protection = {
  daysUsed: number;
  daysRemaining: number;
  /** Article 82: true while the statutory sick-leave periods are not yet exhausted. */
  protected: boolean;
  /** Null until a first sick day opens a window. */
  windowEnds: string | null;
};
 
const ENTITLEMENT_DAYS = 120;
 
export function protectionStatus(year: SickYear | null, daysUsed: number): Protection {
  const daysRemaining = Math.max(0, ENTITLEMENT_DAYS - daysUsed);
  return {
    daysUsed,
    daysRemaining,
    protected: daysRemaining > 0,
    windowEnds: year === null ? null : year.end,
  };
}

export type Employee = {
  id: string;
  regime: Regime;
  wage: WageComponents;
  wageBase: WageBase;
  /** Required, no default: Hijri unless the contract says otherwise (Article 10). */
  calendar: CalendarBasis;
};
 
export type SickLeaveResult = {
  employeeId: string;
  period: { from: string; to: string };
  /** The window open at the end of the period. Persist it with `daysUsed`. */
  year: SickYear | null;
  daysUsed: number;
  slices: (PaySlice & { windowStart: string })[];
  total: Halalas;
  beyondEntitlement: number;
  routedToInsurance: string[];
  protection: Protection;
};
 
export function computeSickLeavePay(
  employee: Employee,
  certificates: Certificate[],
  period: { from: string; to: string },
  priorDaysUsed: number,
  openWindow: SickYear | null,
): SickLeaveResult {
  assertLabourLaw(employee.regime);
  certificates.forEach(assertVerified);
 
  const illness = new Set<string>();
  const injury = new Set<string>();
 
  for (const cert of certificates) {
    const days = expandDays(cert.from, cert.to).filter(
      (d) => d >= period.from && d <= period.to,
    );
    const routed = routeByCause(cert.cause, days);
    const target = routed.route === 'occupational-hazards' ? injury : illness;
    routed.days.forEach((d) => target.add(d));
  }
 
  // Walk the sick days in order. A day outside the current window opens a
  // new one; the days before it stay priced in the window they fell in.
  let year = openWindow;
  let used = openWindow === null ? 0 : priorDaysUsed;
  const segments: { year: SickYear; used: number; days: number }[] = [];
 
  for (const day of [...illness].sort()) {
    if (year === null || !isWithin(year, day)) {
      year = openSickYear(day, employee.calendar);
      used = 0;
      segments.push({ year, used, days: 0 });
    } else if (segments.length === 0) {
      segments.push({ year, used, days: 0 });
    }
    segments[segments.length - 1].days += 1;
    used += 1;
  }
 
  const rate = dailyRate(employee.wage, employee.wageBase);
  const slices: (PaySlice & { windowStart: string })[] = [];
  let beyondEntitlement = 0;
 
  for (const seg of segments) {
    const split = splitAcrossTiers(seg.used, seg.days);
    for (const s of priceSlices(split.slices, rate)) {
      slices.push({ ...s, windowStart: seg.year.start });
    }
    beyondEntitlement += split.beyondEntitlement;
  }
 
  return {
    employeeId: employee.id,
    period,
    year,
    daysUsed: used,
    slices,
    total: slices.reduce((sum, s) => sum + s.amount, 0),
    beyondEntitlement,
    routedToInsurance: [...injury].sort(),
    protection: protectionStatus(year, used),
  };
}
 
function expandDays(from: string, to: string): string[] {
  const out: string[] = [];
  for (let t = toUTC(from); t <= toUTC(to); t += DAY_MS) out.push(toISO(t));
  return out;
}

import { describe, expect, it } from 'vitest';
 
const wage: WageComponents = {
  basic: 800_000,      // 8,000 SAR
  housing: 200_000,    // 2,000 SAR
  transport: 50_000,   //   500 SAR
  otherRegular: 0,
  variable: { earned: 0, workedDays: 0 },
};
 
// 36,000 SAR of commission earned over 240 days actually worked.
const withCommission: WageComponents = {
  ...wage,
  variable: { earned: 3_600_000, workedDays: 240 },
};
 
const employee: Employee = {
  id: 'E-1',
  regime: 'labour-law',
  wage,
  wageBase: 'actual',
  calendar: 'gregorian',
};
 
const sick = (from: string, to: string): Certificate => ({
  code: `GSL-${from}`,
  from,
  to,
  cause: 'illness',
  verified: true,
  verifiedAt: '2026-01-01',
});
 
describe('Article 117 sick leave', () => {
  it('builds the fixed part of the actual wage from basic plus allowances', () => {
    expect(fixedMonthlyWage(wage, 'actual')).toBe(1_050_000);
    expect(fixedMonthlyWage(wage, 'basic')).toBe(800_000);
  });
 
  it('prices the month at 30 days regardless of the calendar', () => {
    // 10,500 SAR over 30 days = 350 SAR per day.
    expect(dailyRate(wage, 'actual')).toBe(35_000);
  });
 
  it('adds commission as a daily average over days actually worked', () => {
    // 350 SAR fixed + 36,000 / 240 = 150 SAR variable = 500 SAR per day.
    expect(dailyRate(withCommission, 'actual')).toBe(50_000);
    expect(dailyRate(withCommission, 'basic')).toBe(800_000 / 30);
  });
 
  it('refuses commission with no worked days to divide by', () => {
    const broken: WageComponents = { ...wage, variable: { earned: 100_000, workedDays: 0 } };
    expect(() => dailyRate(broken, 'actual')).toThrow(RangeError);
  });
 
  it('splits a 100-day spell across all three tiers', () => {
    const { slices, beyondEntitlement } = splitAcrossTiers(0, 100);
    expect(slices.map((s) => s.days)).toEqual([30, 60, 10]);
    expect(beyondEntitlement).toBe(0);
  });
 
  it('carries the tier cursor across intermittent spells', () => {
    // 25 days used in December, 25 more in January of the same sick year.
    const { slices } = splitAcrossTiers(25, 25);
    expect(slices.map((s) => [s.tier.label, s.days])).toEqual([
      ['full pay', 5],
      ['three quarters', 20],
    ]);
  });
 
  it('reports days beyond the 120-day entitlement separately', () => {
    const { beyondEntitlement } = splitAcrossTiers(115, 20);
    expect(beyondEntitlement).toBe(15);
  });
 
  it('closes a Hijri window one Hijri year after the first sick day', () => {
    // 21 Ramadan 1447 opens it; 20 Ramadan 1448 closes it.
    expect(openSickYear('2026-03-10', 'hijri')).toEqual({
      start: '2026-03-10',
      end: '2027-02-27',
      calendar: 'hijri',
    });
  });
 
  it('closes a Gregorian window one Gregorian year after the first sick day', () => {
    expect(openSickYear('2026-03-10', 'gregorian').end).toBe('2027-03-09');
  });
 
  it('handles a Gregorian leap year without losing a day', () => {
    expect(openSickYear('2027-03-01', 'gregorian').end).toBe('2028-02-29');
  });
 
  it('opens a new Hijri window where a Gregorian one would still be running', () => {
    const hijri = openSickYear('2026-03-10', 'hijri');
    const gregorian = openSickYear('2026-03-10', 'gregorian');
    expect(isWithin(hijri, '2027-03-01')).toBe(false);
    expect(isWithin(gregorian, '2027-03-01')).toBe(true);
  });
 
  it('prices days on both sides of a window boundary inside one period', () => {
    const openWindow = openSickYear('2025-06-01', 'gregorian'); // closes 2026-05-31
    const result = computeSickLeavePay(
      employee,
      [sick('2026-05-25', '2026-06-10')],
      { from: '2026-05-01', to: '2026-06-30' },
      20,
      openWindow,
    );
    // 7 days close the old window (days 21-27), 10 open the new one.
    expect(result.slices.map((s) => [s.windowStart, s.days])).toEqual([
      ['2025-06-01', 7],
      ['2026-06-01', 10],
    ]);
    expect(result.total).toBe(17 * 35_000);
    expect(result.year).toEqual(openSickYear('2026-06-01', 'gregorian'));
    expect(result.daysUsed).toBe(10);
  });
 
  it('counts a day covered by two certificates once', () => {
    const result = computeSickLeavePay(
      employee,
      [sick('2026-05-01', '2026-05-05'), sick('2026-05-04', '2026-05-06')],
      { from: '2026-05-01', to: '2026-05-31' },
      0,
      null,
    );
    expect(result.daysUsed).toBe(6);
  });
 
  it('opens no window for a period without sickness', () => {
    const result = computeSickLeavePay(employee, [], { from: '2026-05-01', to: '2026-05-31' }, 0, null);
    expect(result.year).toBeNull();
    expect(result.protection).toEqual({
      daysUsed: 0,
      daysRemaining: 120,
      protected: true,
      windowEnds: null,
    });
  });
 
  it('keeps the Article 82 protection until all 120 days are used', () => {
    const year = openSickYear('2026-03-10', 'hijri');
    expect(protectionStatus(year, 119).protected).toBe(true);
    expect(protectionStatus(year, 120).protected).toBe(false);
  });
 
  it('refuses to compute for a civil-service employee', () => {
    expect(() => assertLabourLaw('civil-service')).toThrow(RegimeNotSupportedError);
  });
 
  it('refuses to pay an unverified certificate', () => {
    const cert: Certificate = { ...sick('2026-05-01', '2026-05-05'), verified: false };
    expect(() => assertVerified(cert)).toThrow(UnverifiedCertificateError);
  });
 
  it('does not consume Article 117 balance for an occupational injury', () => {
    const injured: Certificate = { ...sick('2026-06-01', '2026-06-02'), cause: 'occupational-injury' };
    const result = computeSickLeavePay(
      employee,
      [injured],
      { from: '2026-06-01', to: '2026-06-30' },
      0,
      null,
    );
    expect(result.routedToInsurance).toEqual(['2026-06-01', '2026-06-02']);
    expect(result.daysUsed).toBe(0);
    expect(result.total).toBe(0);
  });
 
  it('rounds once per slice, not once per day', () => {
    // A daily rate of 333.33 SAR at three quarters over 60 days.
    const odd: WageComponents = { ...wage, housing: 0, transport: 0, basic: 999_990 };
    const rate = dailyRate(odd, 'actual');            // 33_333 halalas exactly
    const [slice] = priceSlices([{ tier: ARTICLE_117[1], days: 60 }], rate);
    expect(slice.amount).toBe(Math.round(rate * 60 * 0.75));
  });
});