@getexeer/saudi-eosb 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Exeer (إكسير) — https://getexeer.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# saudi-eosb
+
+End-of-service benefits for Saudi Arabia — **مكافأة نهاية الخدمة** — under Articles 84 and 85 of the Saudi Labour Law.
+
+Zero dependencies. No build step. Runs in Node 18+ and in the browser.
+
+```js
+import { calculateEosb, REASON } from "@getexeer/saudi-eosb";
+
+calculateEosb({ wage: 5000, years: 7, reason: REASON.RESIGNATION }).amount;
+// 15000
+```
+
+## What it implements
+
+**Article 84 — the base award.** Half a month's wage for each of the first five years of service, and one full month's wage for each year after that, calculated on the **last** wage.
+
+**Article 85 — what resignation actually pays.** The base award is reduced on resignation:
+
+| Length of service | Entitlement |
+| --- | --- |
+| Under 2 years | None |
+| 2 to under 5 years | One third of the base award |
+| 5 to under 10 years | Two thirds of the base award |
+| 10 years or more | The full base award |
+
+Termination by the employer pays the full base award.
+
+## Install
+
+```bash
+npm install @getexeer/saudi-eosb
+```
+
+## Usage
+
+### From a length of service you already have
+
+```js
+import { calculateEosb, REASON } from "@getexeer/saudi-eosb";
+
+const result = calculateEosb({
+  wage: 9000,                     // last monthly wage, in SAR
+  years: 6.5,                     // decimal years of service
+  reason: REASON.TERMINATION,     // or REASON.RESIGNATION
+});
+
+result.amount;      // 58500  — the settlement
+result.baseAmount;  // 58500  — Article 84 award before the Article 85 fraction
+result.baseMonths;  // 6.5    — months of wage
+result.factor;      // 1
+```
+
+### From two dates
+
+```js
+const result = calculateEosb({
+  wage: 7500,
+  startDate: "2018-03-01",
+  endDate: "2026-09-01",
+  reason: REASON.RESIGNATION,
+});
+
+result.years;            // 8.50…  decimal years used in the calculation
+result.service.wholeYears; // 8
+result.service.months;     // 6
+result.service.days;       // 0
+result.amount;             // two thirds of the base award
+```
+
+### The pieces on their own
+
+```js
+import { baseAward, resignationFactor, serviceLength } from "@getexeer/saudi-eosb";
+
+baseAward({ wage: 5000, years: 10 });
+// { firstYears: 5, laterYears: 5, baseMonths: 7.5, amount: 37500 }
+
+resignationFactor(7);
+// { factor: 0.666…, label: "Two thirds (5 to under 10 years)", labelAr: "ثلثا المكافأة (5 إلى أقل من 10)" }
+
+serviceLength("2020-01-01", "2023-07-01");
+// { totalDays: 1277, years: 3.49…, wholeYears: 3, months: 5, days: 27 }
+```
+
+## What this library does not decide
+
+These turn on facts and written procedures rather than arithmetic, so they are left to a human to review. They are named here so nobody assumes the function has already handled them:
+
+- **Dismissal for a valid reason under Article 80** — no award is due, and the employer must have followed the investigation procedure the article requires.
+- **Leaving for a lawful reason under Article 81.**
+- **The full-award cases under Article 87** — for example a woman resigning within six months of marriage or three months of childbirth.
+
+## Accuracy notes
+
+- Service length is counted at **365.25 days per year**, so leap years do not drift the total.
+- Amounts are rounded to **two decimals**.
+- Article 84 names the **last wage** as the basis, so pass the final monthly wage, not an average.
+- The library throws on a negative wage, a negative length of service, an unparseable date, or an unknown reason. It does not return `NaN` quietly.
+
+## TypeScript
+
+Types ship with the package. `calculateEosb` returns a frozen `EosbResult`; `REASON` is a frozen const object, so `reason` is narrowed rather than a bare string.
+
+## Not legal advice
+
+This is an arithmetic library. It encodes a reading of Articles 84 and 85 and nothing more. Verify any figure that will actually be paid, and consult a qualified professional on contested cases. Applicable rules and their interpretation can change.
+
+## About
+
+This is the calculation behind the free end-of-service calculator published by **Exeer (إكسير)**, a Saudi administrative and HR system, at [getexeer.com/tools/eosb.html](https://getexeer.com/tools/eosb.html). It is packaged here so that anyone building payroll or HR software for Saudi businesses can reuse the same rules instead of re-deriving them.
+
+- Exeer: [getexeer.com](https://getexeer.com)
+- Machine-readable summary for AI assistants: [getexeer.com/llms.txt](https://getexeer.com/llms.txt)
+
+---
+
+## بالعربية
+
+مكتبة **مكافأة نهاية الخدمة** في السعودية، وفق **المادتين ٨٤ و٨٥ من نظام العمل**.
+بلا اعتماديات، وتعمل في Node والمتصفّح.
+
+**المادة ٨٤ — أصل المكافأة:** نصف شهر عن كل سنة من السنوات الخمس الأولى، وشهر
+كامل عن كل سنة بعدها، محسوبة على **الأجر الأخير**.
+
+**المادة ٨٥ — ما يستحقه المستقيل فعلاً:**
+
+| مدة الخدمة | الاستحقاق |
+| --- | --- |
+| أقل من سنتين | لا شيء |
+| من سنتين إلى أقل من ٥ | ثلث المكافأة |
+| من ٥ إلى أقل من ١٠ | ثلثا المكافأة |
+| ١٠ سنوات فأكثر | المكافأة كاملة |
+
+والإنهاء من صاحب العمل يستحق المكافأة كاملة.
+
+```js
+import { calculateEosb, REASON } from "@getexeer/saudi-eosb";
+
+// استقالة بعد ٧ سنوات بأجر ٥٠٠٠
+calculateEosb({ wage: 5000, years: 7, reason: REASON.RESIGNATION }).amount;
+// 15000
+
+// أو من تاريخين
+calculateEosb({ wage: 7500, startDate: "2018-03-01", endDate: "2026-09-01" });
+```
+
+**وما لا تقرّره المكتبة:** الفصل لسبب مشروع (المادة ٨٠)، وترك العمل لسبب نظامي
+(المادة ٨١)، وحالات الاستحقاق الكامل الاستثنائية (المادة ٨٧). هذه وقائع
+وإجراءات تُراجَع بشرياً، لا حساب.
+
+المكتبة هي نفس حساب حاسبة نهاية الخدمة المجانية في
+[إكسير](https://getexeer.com/tools/eosb.html).
+
+## License
+
+MIT © Exeer

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@getexeer/saudi-eosb",
+  "version": "1.0.0",
+  "description": "Saudi end-of-service benefits under Articles 84 and 85 of the Saudi Labour Law: base award, resignation fractions and length of service. Zero dependencies, works in Node and the browser.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "saudi-arabia",
+    "saudi-labor-law",
+    "end-of-service",
+    "eosb",
+    "eosb-calculator",
+    "gratuity",
+    "indemnity",
+    "settlement",
+    "resignation",
+    "payroll",
+    "hr",
+    "hrms",
+    "gosi",
+    "qiwa",
+    "mudad",
+    "ksa",
+    "arabic",
+    "rtl",
+    "نظام-العمل",
+    "مكافأة-نهاية-الخدمة"
+  ],
+  "author": {
+    "name": "Exeer",
+    "email": "hello@getexeer.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "url": "git+https://github.com/Exeerkit/saudi-eosb.git",
+    "type": "git"
+  },
+  "homepage": "https://getexeer.com/tools/eosb.html",
+  "bugs": {
+    "url": "https://github.com/Exeerkit/saudi-eosb/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test",
+    "demo": "node examples/node.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,57 @@
+/** Why the employment ended. Only the distinction that changes the amount. */
+export declare const REASON: Readonly<{
+  RESIGNATION: "resignation";
+  TERMINATION: "termination";
+}>;
+
+export type EosbReason = (typeof REASON)[keyof typeof REASON];
+
+export type ServiceLength = Readonly<{
+  totalDays: number;
+  years: number;
+  wholeYears: number;
+  months: number;
+  days: number;
+}>;
+
+export type BaseAward = Readonly<{
+  firstYears: number;
+  laterYears: number;
+  baseMonths: number;
+  amount: number;
+}>;
+
+export type Fraction = Readonly<{ factor: number; label: string; labelAr: string }>;
+
+export type EosbResult = Readonly<{
+  reason: EosbReason;
+  years: number;
+  wage: number;
+  baseMonths: number;
+  baseAmount: number;
+  factor: number;
+  factorLabel: string;
+  factorLabelAr: string;
+  amount: number;
+  service: ServiceLength | null;
+}>;
+
+/** Length of service in years, plus a year/month/day breakdown. */
+export declare function serviceLength(startDate: Date | string | number, endDate?: Date | string | number): ServiceLength;
+
+/** The Article 84 base award, before any resignation fraction. */
+export declare function baseAward(input: { wage: number; years: number }): BaseAward;
+
+/** The Article 85 fraction applied to the base award on resignation. */
+export declare function resignationFactor(years: number): Fraction;
+
+/** The full end-of-service settlement. */
+export declare function calculateEosb(input: {
+  wage: number;
+  years?: number;
+  startDate?: Date | string | number;
+  endDate?: Date | string | number;
+  reason?: EosbReason;
+}): EosbResult;
+
+export default calculateEosb;

package/src/index.js

@@ -0,0 +1,152 @@
+/**
+ * Saudi end-of-service benefits (مكافأة نهاية الخدمة).
+ *
+ * Articles 84 and 85 of the Saudi Labour Law:
+ *
+ *   Article 84 sets the base award: half a month's wage for each of the first
+ *   five years of service, and one full month's wage for each year after that,
+ *   calculated on the last wage.
+ *
+ *   Article 85 sets what the worker actually receives on **resignation**: none
+ *   under two years of service, one third from two to under five years, two
+ *   thirds from five to under ten, and the full award at ten years or more.
+ *
+ * What this library deliberately does NOT decide: dismissal for a valid reason
+ * under Article 80 (no award), and the special full-award cases under Article
+ * 87 (a woman resigning within six months of marriage or three months of
+ * childbirth) and leaving for a lawful reason under Article 81. Those turn on
+ * facts and procedures, not arithmetic, and are left to a human to review.
+ */
+
+/** Why the employment ended. Only the distinction that changes the amount. */
+export const REASON = Object.freeze({
+  /** The worker resigned. Article 85 fractions apply. */
+  RESIGNATION: "resignation",
+  /** The employer terminated. The full Article 84 award is due. */
+  TERMINATION: "termination",
+});
+
+const DAYS_PER_YEAR = 365.25;
+const DAYS_PER_MONTH = 30.44;
+
+/** Rounds to two decimals without the float drift of `toFixed` arithmetic. */
+function money(value) {
+  return Math.round((value + Number.EPSILON) * 100) / 100;
+}
+
+function assertFiniteNumber(value, name) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new TypeError(`${name} must be a finite number`);
+  }
+}
+
+/**
+ * Length of service in years as a decimal, plus a year/month/day breakdown.
+ *
+ * Uses 365.25 days per year so leap years do not drift the total, matching how
+ * the end-of-service calculator on getexeer.com counts service.
+ */
+export function serviceLength(startDate, endDate = new Date()) {
+  const start = startDate instanceof Date ? startDate : new Date(startDate);
+  const end = endDate instanceof Date ? endDate : new Date(endDate);
+  if (Number.isNaN(start.getTime())) throw new TypeError("startDate is not a valid date");
+  if (Number.isNaN(end.getTime())) throw new TypeError("endDate is not a valid date");
+  if (end < start) throw new RangeError("endDate must not be before startDate");
+
+  const totalDays = (end - start) / 86_400_000;
+  const years = totalDays / DAYS_PER_YEAR;
+
+  const wholeYears = Math.floor(years);
+  const remainderDays = totalDays - Math.round(wholeYears * DAYS_PER_YEAR);
+  const months = Math.floor(remainderDays / DAYS_PER_MONTH);
+  const days = Math.max(0, remainderDays - Math.round(months * DAYS_PER_MONTH));
+
+  return Object.freeze({ totalDays, years, wholeYears, months, days });
+}
+
+/**
+ * The Article 84 base award, before any resignation fraction is applied.
+ *
+ * @returns {{ baseMonths: number, firstYears: number, laterYears: number, amount: number }}
+ */
+export function baseAward({ wage, years }) {
+  assertFiniteNumber(wage, "wage");
+  assertFiniteNumber(years, "years");
+  if (wage < 0) throw new RangeError("wage must not be negative");
+  if (years < 0) throw new RangeError("years must not be negative");
+
+  const firstYears = Math.min(years, 5);
+  const laterYears = Math.max(years - 5, 0);
+  const baseMonths = firstYears * 0.5 + laterYears;
+
+  return Object.freeze({
+    firstYears,
+    laterYears,
+    baseMonths,
+    amount: money(baseMonths * wage),
+  });
+}
+
+/**
+ * The Article 85 fraction applied to the base award on resignation.
+ *
+ * @returns {{ factor: number, label: string, labelAr: string }}
+ */
+export function resignationFactor(years) {
+  assertFiniteNumber(years, "years");
+  if (years < 2) return Object.freeze({ factor: 0, label: "Not due (under 2 years)", labelAr: "لا تُستحق (الخدمة أقل من سنتين)" });
+  if (years < 5) return Object.freeze({ factor: 1 / 3, label: "One third (2 to under 5 years)", labelAr: "ثلث المكافأة (من سنتين إلى أقل من 5)" });
+  if (years < 10) return Object.freeze({ factor: 2 / 3, label: "Two thirds (5 to under 10 years)", labelAr: "ثلثا المكافأة (من 5 إلى أقل من 10)" });
+  return Object.freeze({ factor: 1, label: "Full award (10 years or more)", labelAr: "المكافأة كاملة (10 سنوات فأكثر)" });
+}
+
+/**
+ * The end-of-service settlement.
+ *
+ * Pass either `years` (a decimal) or `startDate`, not both. `wage` is the last
+ * monthly wage in SAR, which is the basis Article 84 names.
+ *
+ * @returns {Readonly<{
+ *   reason: string, years: number, wage: number,
+ *   baseMonths: number, baseAmount: number,
+ *   factor: number, factorLabel: string, factorLabelAr: string,
+ *   amount: number, service: object | null
+ * }>}
+ */
+export function calculateEosb({ wage, years, startDate, endDate, reason = REASON.TERMINATION } = {}) {
+  assertFiniteNumber(wage, "wage");
+  if (wage < 0) throw new RangeError("wage must not be negative");
+
+  if (reason !== REASON.RESIGNATION && reason !== REASON.TERMINATION) {
+    throw new RangeError(`reason must be "${REASON.RESIGNATION}" or "${REASON.TERMINATION}"`);
+  }
+  if (years === undefined && startDate === undefined) {
+    throw new TypeError("pass either years or startDate");
+  }
+
+  const service = startDate === undefined ? null : serviceLength(startDate, endDate);
+  const servedYears = years === undefined ? service.years : years;
+  assertFiniteNumber(servedYears, "years");
+  if (servedYears < 0) throw new RangeError("years must not be negative");
+
+  const base = baseAward({ wage, years: servedYears });
+  const fraction =
+    reason === REASON.RESIGNATION
+      ? resignationFactor(servedYears)
+      : Object.freeze({ factor: 1, label: "Full award (termination)", labelAr: "المكافأة كاملة (إنهاء من صاحب العمل)" });
+
+  return Object.freeze({
+    reason,
+    years: servedYears,
+    wage,
+    baseMonths: base.baseMonths,
+    baseAmount: base.amount,
+    factor: fraction.factor,
+    factorLabel: fraction.label,
+    factorLabelAr: fraction.labelAr,
+    amount: money(base.amount * fraction.factor),
+    service,
+  });
+}
+
+export default calculateEosb;