محرك أجر الإجازة المرضية بـ 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 allowances paid regularly and unconditionally, per month. */
  otherRegular: Halalas;
  /** Variable pay: commission, bonuses, irregular incentives. Excluded. */
  variable: Halalas;
};
 
export type WageBase = 'actual' | 'basic';
 
export function monthlyWage(w: WageComponents, base: WageBase): Halalas {
  if (base === 'basic') return w.basic;
  // The actual wage: basic plus what is paid regularly and unconditionally.
  // Variable pay is deliberately excluded — it is not part of the fixed wage.
  return w.basic + w.housing + w.transport + w.otherRegular;
}
 
/**
 * The daily rate. The Labour Law prices a month at 30 days for wage
 * purposes, so this divisor is 30 regardless of how many days the
 * calendar month actually has. Kept fractional on purpose — see Step 4.
 */
export function dailyRate(w: WageComponents, base: WageBase): number {
  return monthlyWage(w, base) / 30;
}

export type SickYear = {
  /** Inclusive ISO date on which this window opened. */
  start: string;
  /** Inclusive ISO date on which it closes: start plus one year, minus one day. */
  end: string;
};
 
const DAY_MS = 86_400_000;
 
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);
}
 
export function openSickYear(firstSickDay: string): SickYear {
  const [y, m, d] = firstSickDay.split('-').map(Number);
  // One year later, minus one day, so the window is inclusive on both ends.
  const endMs = Date.UTC(y + 1, m - 1, d) - DAY_MS;
  return { start: firstSickDay, end: toISO(endMs) };
}
 
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;
  /** True while the statutory sick-leave entitlement is not yet exhausted. */
  protected: boolean;
  windowEnds: string;
};
 
const ENTITLEMENT_DAYS = 120;
 
export function protectionStatus(year: SickYear, daysUsed: number): Protection {
  const daysRemaining = Math.max(0, ENTITLEMENT_DAYS - daysUsed);
  return {
    daysUsed,
    daysRemaining,
    protected: daysRemaining > 0,
    windowEnds: year.end,
  };
}

export type Employee = {
  id: string;
  regime: Regime;
  wage: WageComponents;
  wageBase: WageBase;
};
 
export type SickLeaveResult = {
  employeeId: string;
  period: { from: string; to: string };
  year: SickYear;
  slices: PaySlice[];
  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 illnessDays: string[] = [];
  const injuryDays: 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);
    if (routed.route === 'occupational-hazards') injuryDays.push(...routed.days);
    else illnessDays.push(...routed.days);
  }
 
  illnessDays.sort();
 
  // The window opens on the first sick day if none is open, and rolls
  // forward the moment a sick day falls outside the current one.
  let year = openWindow;
  let used = priorDaysUsed;
  if (year === null && illnessDays.length > 0) {
    year = openSickYear(illnessDays[0]);
    used = 0;
  }
  if (year !== null) {
    for (const day of illnessDays) {
      if (!isWithin(year, day)) {
        year = openSickYear(day);
        used = 0;
        break;
      }
    }
  }
  if (year === null) year = openSickYear(period.from);
 
  const inWindow = illnessDays.filter((d) => isWithin(year!, d));
  const { slices, beyondEntitlement } = splitAcrossTiers(used, inWindow.length);
  const priced = priceSlices(slices, dailyRate(employee.wage, employee.wageBase));
 
  return {
    employeeId: employee.id,
    period,
    year,
    slices: priced,
    total: priced.reduce((sum, s) => sum + s.amount, 0),
    beyondEntitlement,
    routedToInsurance: injuryDays,
    protection: protectionStatus(year, used + inWindow.length),
  };
}
 
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: 300_000,   // commission — must be excluded
};
 
describe('Article 117 sick leave', () => {
  it('excludes variable pay from the actual wage', () => {
    expect(monthlyWage(wage, 'actual')).toBe(1_050_000);
    expect(monthlyWage(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('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 the window one year after the first sick day, inclusive', () => {
    expect(openSickYear('2026-03-10')).toEqual({
      start: '2026-03-10',
      end: '2027-03-09',
    });
  });
 
  it('handles a leap year without losing a day', () => {
    expect(openSickYear('2027-03-01').end).toBe('2028-02-29');
  });
 
  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 = {
      code: 'GSL-000',
      from: '2026-05-01',
      to: '2026-05-05',
      cause: 'illness',
      verified: false,
    };
    expect(() => assertVerified(cert)).toThrow(UnverifiedCertificateError);
  });
 
  it('does not consume Article 117 balance for an occupational injury', () => {
    const routed = routeByCause('occupational-injury', ['2026-06-01', '2026-06-02']);
    expect(routed.route).toBe('occupational-hazards');
  });
 
  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));
  });
});