@managemint-solutions/sdk 0.45.0 → 0.50.0

package/dist/leave/index.js

@@ -1,7 +1,8 @@
 "use strict";
 // Leave, the first slice of the HR module: one resource per table, the DTOs the api validates
-// with, and the calendar arithmetic the api counts days with. The resources hang off
-// `SupabaseClient` as `leaveTypes`, `leaveEntitlements` and `leaveRequests`; the holiday
+// with, and the calendar and policy arithmetic the api counts days and balances with. The
+// resources hang off `SupabaseClient` as `leaveTypes`, `leaveEntitlements`, `leaveAdjustments`
+// and `leaveRequests`; the holiday
 // calendar the day count reads is its own resource, `publicHolidays` (src/public-holidays).
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -18,9 +19,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LeaveRequestsResource = exports.LeaveEntitlementsResource = exports.LeaveTypesResource = void 0;
+exports.LeaveRequestsResource = exports.LeaveEntitlementsResource = exports.LeaveTypesResource = exports.LeaveAdjustmentsResource = void 0;
 __exportStar(require("./dto"), exports);
 __exportStar(require("./working-days"), exports);
+__exportStar(require("./leave-policy"), exports);
+var leave_adjustments_1 = require("./leave-adjustments");
+Object.defineProperty(exports, "LeaveAdjustmentsResource", { enumerable: true, get: function () { return leave_adjustments_1.LeaveAdjustmentsResource; } });
 var leave_types_1 = require("./leave-types");
 Object.defineProperty(exports, "LeaveTypesResource", { enumerable: true, get: function () { return leave_types_1.LeaveTypesResource; } });
 var leave_entitlements_1 = require("./leave-entitlements");

package/dist/leave/leave-adjustments.d.ts

@@ -0,0 +1,18 @@
+import type { LeaveAdjustmentEntity } from '@managemint-solutions/entities/leave';
+import { type AuditActor, type AuditResource } from '../audit';
+import type { TypedSupabaseClient } from '../client';
+import type { CreateLeaveAdjustmentDto } from './dto';
+/**
+ * Manual corrections to an entitlement's balance. Insert and read only: the table has no
+ * update or delete grant, so a mistake is corrected by a second adjustment and both stay on
+ * record. The balance itself sums them in `LeaveEntitlementsResource`.
+ */
+export declare class LeaveAdjustmentsResource {
+    private readonly supabase;
+    private readonly auth;
+    private readonly table;
+    constructor(supabase: TypedSupabaseClient, auth: AuditActor, audit: AuditResource);
+    /** The adjustments of the given entitlements, oldest first. */
+    list(leaveEntitlementIds: string[]): Promise<LeaveAdjustmentEntity[]>;
+    create(leaveEntitlementId: string, input: CreateLeaveAdjustmentDto): Promise<LeaveAdjustmentEntity>;
+}

package/dist/leave/leave-adjustments.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LeaveAdjustmentsResource = void 0;
+const enum_1 = require("@managemint-solutions/entities/audit-trail/enum");
+const audit_1 = require("../audit");
+const errors_1 = require("../errors");
+const LEAVE_ADJUSTMENT_SELECT = `
+        mms_id,
+        created_at,
+        created_by:user_profiles!created_by (*),
+        leave_entitlement_id,
+        days,
+        reason
+      `;
+/**
+ * Manual corrections to an entitlement's balance. Insert and read only: the table has no
+ * update or delete grant, so a mistake is corrected by a second adjustment and both stay on
+ * record. The balance itself sums them in `LeaveEntitlementsResource`.
+ */
+class LeaveAdjustmentsResource {
+    supabase;
+    auth;
+    table;
+    constructor(supabase, auth, audit) {
+        this.supabase = supabase;
+        this.auth = auth;
+        this.table = (0, audit_1.auditedTable)(supabase, auth, audit, {
+            table: 'leave_adjustments',
+            entityType: enum_1.AuditTrailEntityType.LEAVE_ADJUSTMENTS,
+        });
+    }
+    /** The adjustments of the given entitlements, oldest first. */
+    async list(leaveEntitlementIds) {
+        if (leaveEntitlementIds.length === 0)
+            return [];
+        const { data, error } = await this.supabase
+            .from('leave_adjustments')
+            .select(LEAVE_ADJUSTMENT_SELECT)
+            .eq('organization_id', this.auth.organization_id)
+            .in('leave_entitlement_id', leaveEntitlementIds)
+            .order('created_at');
+        if (error)
+            throw (0, errors_1.mapPostgrestError)(error);
+        return (data ?? []).map((row) => ({ ...row, days: Number(row.days) }));
+    }
+    async create(leaveEntitlementId, input) {
+        const row = await this.table.insert({
+            leave_entitlement_id: leaveEntitlementId,
+            days: input.days,
+            reason: input.reason,
+            organization_id: this.auth.organization_id,
+            created_by: this.auth.mms_id,
+            created_at: new Date().toISOString(),
+        });
+        const [created] = (await this.list([leaveEntitlementId])).filter((adjustment) => adjustment.mms_id === row.mms_id);
+        return created;
+    }
+}
+exports.LeaveAdjustmentsResource = LeaveAdjustmentsResource;

package/dist/leave/leave-entitlements.d.ts

@@ -1,18 +1,19 @@
 import type { MmsList } from '@managemint-solutions/entities/common';
 import type { LeaveEntitlementEntity, LeavePeriod } from '@managemint-solutions/entities/leave';
+import { LeaveGrantMethod } from '@managemint-solutions/entities/leave/enum';
 import { type AuditActor, type AuditResource } from '../audit';
 import type { TypedSupabaseClient } from '../client';
 import type { GetLeaveEntitlementsDto, UpdateLeaveEntitlementDto } from './dto';
-/** What the request path needs of the entitlement covering a date: the period and the cap. */
-export type LeaveEntitlementCover = LeavePeriod & {
-    mms_id: string;
-    days_entitled: number;
-};
-/** The create input after the api has resolved the period defaults. */
+/** The create input after the api has resolved the defaults and copied the type's policy on. */
 export type CreateLeaveEntitlementInput = LeavePeriod & {
     user_id: string;
     leave_type_id: string;
     days_entitled: number;
+    days_carried: number;
+    carried_expires_on: string | null;
+    grant_method: LeaveGrantMethod;
+    initial_until: string | null;
+    initial_days_per_month: number | null;
     max_carry_over_days: number;
     notes?: string | null;
 };
@@ -24,32 +25,37 @@ export declare class LeaveEntitlementsResource {
     list(query: GetLeaveEntitlementsDto): Promise<MmsList<LeaveEntitlementEntity>>;
     getById(leaveEntitlementId: string): Promise<LeaveEntitlementEntity>;
     /**
-     * The entitlement of `userId` for `leaveTypeId` whose period contains `date`, or null when the
+     * The entitlement of `userId` for `leaveTypeId` whose period contains `date`, with its balance
+     * as it stands on that day - what a request starting then is checked against. Null when the
      * type is not tracked for them then. The periods of one user and type cannot overlap (the
      * table's exclusion constraint), so there is at most one.
      */
-    findFor(userId: string, leaveTypeId: string, date: string): Promise<LeaveEntitlementCover | null>;
+    balanceOn(userId: string, leaveTypeId: string, date: string, excludeRequestId?: string): Promise<LeaveEntitlementEntity | null>;
     /**
      * Whether `userId` already has an entitlement of `leaveTypeId` touching any day of
      * `start`..`end`. The readable half of the rule; the table's exclusion constraint is the half
-     * that survives a race. `excludeId` leaves out the entitlement being edited.
+     * that survives a race.
      */
-    overlaps(userId: string, leaveTypeId: string, start: string, end: string, excludeId?: string): Promise<boolean>;
+    overlaps(userId: string, leaveTypeId: string, start: string, end: string): Promise<boolean>;
     /**
-     * Every entitlement of the organization whose period ends on `periodEnd`, balances included -
-     * what the leave-year rollover carries forward. Walks the table in pages so a large tenant is
-     * not cut short by the row cap.
+     * Every entitlement of the organization that ended before `today` and has no successor - no
+     * later period of the same user and type - balances included: what the rollover carries
+     * forward. An ended period keeps qualifying until its next one exists, so a missed run is
+     * caught up by the next. PostgREST cannot say "no later row exists", so this reads the ended
+     * rows and every row's start, and filters in code. Both reads walk the table in pages so a
+     * large tenant is not cut short by the row cap.
      */
-    endingOn(periodEnd: string): Promise<LeaveEntitlementEntity[]>;
+    endedWithoutSuccessor(today: string): Promise<LeaveEntitlementEntity[]>;
     create(input: CreateLeaveEntitlementInput): Promise<LeaveEntitlementEntity>;
     update(leaveEntitlementId: string, input: UpdateLeaveEntitlementDto): Promise<LeaveEntitlementEntity>;
     /** Hard delete: the type simply becomes untracked for that user and period. */
     remove(leaveEntitlementId: string): Promise<void>;
     /**
-     * Adds the computed balance to each row from one query over the requests that could count
-     * against any of them - the approved and pending ones of these users and types, starting in
-     * the span the periods cover. Nothing is stored: a balance is always what the requests say.
-     * Paged, since `endingOn` hands it a whole tenant at once.
+     * Adds the balance to each row (on `asOf`, today by default) from one query over the requests
+     * that could count against any of them - the approved and pending ones of these users and
+     * types, starting in the span the periods cover - and the adjustments embedded in the rows.
+     * Nothing is stored: a balance is always what the requests, the policy and the adjustments
+     * say. Paged, since `endedWithoutSuccessor` hands it a whole tenant at once.
      */
     private withBalances;
 }

package/dist/leave/leave-entitlements.js

@@ -6,6 +6,9 @@ const enum_2 = require("@managemint-solutions/entities/leave/enum");
 const audit_1 = require("../audit");
 const errors_1 = require("../errors");
 const transforms_1 = require("../transforms");
+const leave_policy_1 = require("./leave-policy");
+const working_days_1 = require("./working-days");
+// `adjustments` is embedded only to be summed into the balance; it never leaves the resource.
 const LEAVE_ENTITLEMENT_SELECT = `
         mms_id,
         created_at,
@@ -16,14 +19,21 @@ const LEAVE_ENTITLEMENT_SELECT = `
         leave_type:leave_types!leave_type_id (
           mms_id,
           name,
-          requires_document
+          document_after_days
         ),
         period_start,
         period_end,
         days_entitled,
+        days_carried,
+        carried_expires_on,
+        grant_method,
+        initial_until,
+        initial_days_per_month,
         max_carry_over_days,
-        notes
+        notes,
+        adjustments:leave_adjustments (days)
       `;
+const numberOrNull = (value) => (value === null || value === undefined ? null : Number(value));
 class LeaveEntitlementsResource {
     supabase;
     auth;
@@ -75,14 +85,15 @@ class LeaveEntitlementsResource {
         return row;
     }
     /**
-     * The entitlement of `userId` for `leaveTypeId` whose period contains `date`, or null when the
+     * The entitlement of `userId` for `leaveTypeId` whose period contains `date`, with its balance
+     * as it stands on that day - what a request starting then is checked against. Null when the
      * type is not tracked for them then. The periods of one user and type cannot overlap (the
      * table's exclusion constraint), so there is at most one.
      */
-    async findFor(userId, leaveTypeId, date) {
+    async balanceOn(userId, leaveTypeId, date, excludeRequestId) {
         const { data, error } = await this.supabase
             .from('leave_entitlements')
-            .select('mms_id, period_start, period_end, days_entitled')
+            .select(LEAVE_ENTITLEMENT_SELECT)
             .eq('organization_id', this.auth.organization_id)
             .eq('user_id', userId)
             .eq('leave_type_id', leaveTypeId)
@@ -93,16 +104,16 @@ class LeaveEntitlementsResource {
             throw (0, errors_1.mapPostgrestError)(error);
         if (!data)
             return null;
-        const cover = data;
-        return { ...cover, days_entitled: Number(cover.days_entitled) };
+        const [row] = await this.withBalances([data], { asOf: date, excludeRequestId });
+        return row;
     }
     /**
      * Whether `userId` already has an entitlement of `leaveTypeId` touching any day of
      * `start`..`end`. The readable half of the rule; the table's exclusion constraint is the half
-     * that survives a race. `excludeId` leaves out the entitlement being edited.
+     * that survives a race.
      */
-    async overlaps(userId, leaveTypeId, start, end, excludeId) {
-        let overlapQuery = this.supabase
+    async overlaps(userId, leaveTypeId, start, end) {
+        const { count, error } = await this.supabase
             .from('leave_entitlements')
             .select('mms_id', { count: 'exact', head: true })
             .eq('organization_id', this.auth.organization_id)
@@ -110,28 +121,44 @@ class LeaveEntitlementsResource {
             .eq('leave_type_id', leaveTypeId)
             .lte('period_start', end)
             .gte('period_end', start);
-        if (excludeId) {
-            overlapQuery = overlapQuery.neq('mms_id', excludeId);
-        }
-        const { count, error } = await overlapQuery;
         if (error)
             throw (0, errors_1.mapPostgrestError)(error);
         return (count ?? 0) > 0;
     }
     /**
-     * Every entitlement of the organization whose period ends on `periodEnd`, balances included -
-     * what the leave-year rollover carries forward. Walks the table in pages so a large tenant is
-     * not cut short by the row cap.
+     * Every entitlement of the organization that ended before `today` and has no successor - no
+     * later period of the same user and type - balances included: what the rollover carries
+     * forward. An ended period keeps qualifying until its next one exists, so a missed run is
+     * caught up by the next. PostgREST cannot say "no later row exists", so this reads the ended
+     * rows and every row's start, and filters in code. Both reads walk the table in pages so a
+     * large tenant is not cut short by the row cap.
      */
-    async endingOn(periodEnd) {
-        const rows = await (0, transforms_1.allRows)((from, to) => this.supabase
+    async endedWithoutSuccessor(today) {
+        const ended = await (0, transforms_1.allRows)((from, to) => this.supabase
             .from('leave_entitlements')
             .select(LEAVE_ENTITLEMENT_SELECT)
             .eq('organization_id', this.auth.organization_id)
-            .eq('period_end', periodEnd)
+            .lt('period_end', today)
+            .order('mms_id')
+            .range(from, to));
+        if (ended.length === 0)
+            return [];
+        const starts = await (0, transforms_1.allRows)((from, to) => this.supabase
+            .from('leave_entitlements')
+            .select('user_id, leave_type_id, period_start')
+            .eq('organization_id', this.auth.organization_id)
             .order('mms_id')
             .range(from, to));
-        return this.withBalances(rows);
+        // The periods of one user and type never overlap, so a row has a successor exactly when the
+        // latest start of its user and type falls after its end.
+        const latestStart = new Map();
+        for (const row of starts) {
+            const key = `${row.user_id}:${row.leave_type_id}`;
+            const latest = latestStart.get(key);
+            if (latest === undefined || row.period_start > latest)
+                latestStart.set(key, row.period_start);
+        }
+        return this.withBalances(ended.filter((row) => (latestStart.get(`${row.user.mms_id}:${row.leave_type.mms_id}`) ?? '') <= row.period_end));
     }
     async create(input) {
         const row = await this.table.insert({
@@ -140,6 +167,11 @@ class LeaveEntitlementsResource {
             period_start: input.period_start,
             period_end: input.period_end,
             days_entitled: input.days_entitled,
+            days_carried: input.days_carried,
+            carried_expires_on: input.carried_expires_on,
+            grant_method: input.grant_method,
+            initial_until: input.initial_until,
+            initial_days_per_month: input.initial_days_per_month,
             max_carry_over_days: input.max_carry_over_days,
             notes: input.notes ?? null,
             organization_id: this.auth.organization_id,
@@ -151,8 +183,9 @@ class LeaveEntitlementsResource {
     async update(leaveEntitlementId, input) {
         await this.table.update(leaveEntitlementId, {
             days_entitled: input.days_entitled,
+            days_carried: input.days_carried,
+            carried_expires_on: input.carried_expires_on,
             max_carry_over_days: input.max_carry_over_days,
-            period_end: input.period_end,
             notes: input.notes,
             last_updated_by: this.auth.mms_id,
             updated_at: new Date().toISOString(),
@@ -164,21 +197,23 @@ class LeaveEntitlementsResource {
         await this.table.remove(leaveEntitlementId);
     }
     /**
-     * Adds the computed balance to each row from one query over the requests that could count
-     * against any of them - the approved and pending ones of these users and types, starting in
-     * the span the periods cover. Nothing is stored: a balance is always what the requests say.
-     * Paged, since `endingOn` hands it a whole tenant at once.
+     * Adds the balance to each row (on `asOf`, today by default) from one query over the requests
+     * that could count against any of them - the approved and pending ones of these users and
+     * types, starting in the span the periods cover - and the adjustments embedded in the rows.
+     * Nothing is stored: a balance is always what the requests, the policy and the adjustments
+     * say. Paged, since `endedWithoutSuccessor` hands it a whole tenant at once.
      */
-    async withBalances(rows) {
+    async withBalances(rows, options = {}) {
         if (rows.length === 0)
             return [];
+        const asOf = options.asOf ?? (0, working_days_1.todayInJohannesburg)();
         const userIds = [...new Set(rows.map((row) => row.user.mms_id))];
         const typeIds = [...new Set(rows.map((row) => row.leave_type.mms_id))];
         const earliest = rows.map((row) => row.period_start).sort()[0];
         const latest = rows.map((row) => row.period_end).sort().reverse()[0];
         const requests = await (0, transforms_1.allRows)((from, to) => this.supabase
             .from('leave_requests')
-            .select('user_id, leave_type_id, start_date, days, status')
+            .select('mms_id, user_id, leave_type_id, start_date, days, status')
             .eq('organization_id', this.auth.organization_id)
             .in('user_id', userIds)
             .in('leave_type_id', typeIds)
@@ -187,25 +222,22 @@ class LeaveEntitlementsResource {
             .lte('start_date', latest)
             .order('mms_id')
             .range(from, to));
-        return rows.map((row) => {
-            const mine = requests.filter((request) => request.user_id === row.user.mms_id &&
-                request.leave_type_id === row.leave_type.mms_id &&
-                request.start_date >= row.period_start &&
-                request.start_date <= row.period_end);
-            const sum = (status) => mine
-                .filter((request) => request.status === status)
-                .reduce((total, request) => total + Number(request.days), 0);
-            const daysEntitled = Number(row.days_entitled);
-            const daysUsed = sum(enum_2.LeaveRequestStatus.APPROVED);
-            const daysPending = sum(enum_2.LeaveRequestStatus.PENDING);
-            return {
+        return rows.map(({ adjustments, ...row }) => {
+            const entitlement = {
                 ...row,
-                days_entitled: daysEntitled,
+                days_entitled: Number(row.days_entitled),
+                days_carried: Number(row.days_carried),
+                initial_days_per_month: numberOrNull(row.initial_days_per_month),
                 max_carry_over_days: Number(row.max_carry_over_days),
-                days_used: daysUsed,
-                days_pending: daysPending,
-                days_remaining: daysEntitled - daysUsed - daysPending,
+                leave_type: { ...row.leave_type, document_after_days: numberOrNull(row.leave_type.document_after_days) },
             };
+            const mine = requests.filter((request) => (!options.excludeRequestId || request.mms_id !== options.excludeRequestId) &&
+                request.user_id === row.user.mms_id &&
+                request.leave_type_id === row.leave_type.mms_id &&
+                request.start_date >= row.period_start &&
+                request.start_date <= row.period_end);
+            const daysAdjusted = (adjustments ?? []).reduce((total, adjustment) => total + Number(adjustment.days), 0);
+            return { ...entitlement, ...(0, leave_policy_1.balanceOf)(entitlement, mine, daysAdjusted, asOf) };
         });
     }
 }

package/dist/leave/leave-policy.d.ts

@@ -0,0 +1,50 @@
+import type { LeaveBalance, LeavePeriod, LeaveTypeEntity } from '@managemint-solutions/entities/leave';
+import { LeaveGrantMethod, LeaveRequestStatus } from '@managemint-solutions/entities/leave/enum';
+/** The entitlement columns a balance is worked out from - the type's policy as it was copied on. */
+export type BalanceEntitlement = LeavePeriod & {
+    days_entitled: number;
+    days_carried: number;
+    carried_expires_on: string | null;
+    grant_method: LeaveGrantMethod;
+    initial_until: string | null;
+    initial_days_per_month: number | null;
+};
+/** The request columns that count against a balance. */
+export type BalanceRequest = {
+    start_date: string;
+    days: number;
+    status: LeaveRequestStatus | string;
+};
+/** A cycle of a type, and the part of it a person's entitlement covers (from their start date, if later). */
+export type LeaveCycle = {
+    cycle: LeavePeriod;
+    period: LeavePeriod;
+};
+/**
+ * The cycle of `type` containing `date` for someone who started on `employmentStart`. Every
+ * cycle is `cycle_years` leave years starting on the first of the organization's leave-year
+ * month (`startMonth`, 1-12); the first one starts with the leave year the start date falls
+ * in. `period` starts no earlier than the start date, so a joiner's first period is the rest
+ * of the cycle. A March start puts 2026-02-10 in the leave year that began 2025-03-01.
+ */
+export declare const cyclePeriodFor: (type: Pick<LeaveTypeEntity, "cycle_years">, employmentStart: string, date: string, startMonth: number) => LeaveCycle;
+/** A full cycle's days scaled to the part of it `period` covers, to the half-day precision of the column. */
+export declare const proRataDays: (defaultDays: number, { cycle, period }: LeaveCycle) => number;
+/**
+ * The last day of the first-months rate for an entitlement over `period`: `initialMonths`
+ * from the start date, or null when that is over before the period begins.
+ */
+export declare const initialUntil: (employmentStart: string, initialMonths: number, period: LeavePeriod) => string | null;
+/**
+ * The part of `days_entitled` earned by the end of `asOf`. Upfront: everything from the first
+ * day. Monthly: an equal share per completed month (a short last month earns its fraction on
+ * the period's final day). Either way, inside the first-months window the total is capped at
+ * `initial_days_per_month` per completed month.
+ */
+export declare const accruedDays: (entitlement: BalanceEntitlement, asOf: string) => number;
+/**
+ * The balance of an entitlement on `asOf`, from the live requests starting inside its period
+ * and the sum of its adjustments. Carried days are spent first: whatever of them the requests
+ * starting on or before `carried_expires_on` did not use is forfeited once that day has passed.
+ */
+export declare const balanceOf: (entitlement: BalanceEntitlement, requests: BalanceRequest[], daysAdjusted: number, asOf: string) => LeaveBalance;

package/dist/leave/leave-policy.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.balanceOf = exports.accruedDays = exports.initialUntil = exports.proRataDays = exports.cyclePeriodFor = void 0;
+const enum_1 = require("@managemint-solutions/entities/leave/enum");
+const working_days_1 = require("./working-days");
+const round = (value, places) => Number(value.toFixed(places));
+const daysIn = (period) => (0, working_days_1.eachDate)(period.period_start, period.period_end).length;
+/**
+ * The cycle of `type` containing `date` for someone who started on `employmentStart`. Every
+ * cycle is `cycle_years` leave years starting on the first of the organization's leave-year
+ * month (`startMonth`, 1-12); the first one starts with the leave year the start date falls
+ * in. `period` starts no earlier than the start date, so a joiner's first period is the rest
+ * of the cycle. A March start puts 2026-02-10 in the leave year that began 2025-03-01.
+ */
+const cyclePeriodFor = (type, employmentStart, date, startMonth) => {
+    // The calendar year each leave year starts in: a date before the leave-year month belongs
+    // to the leave year that began the calendar year before.
+    const firstYear = Number(employmentStart.slice(0, 4)) - (Number(employmentStart.slice(5, 7)) < startMonth ? 1 : 0);
+    const dateYear = Number(date.slice(0, 4)) - (Number(date.slice(5, 7)) < startMonth ? 1 : 0);
+    const index = Math.floor((dateYear - firstYear) / type.cycle_years);
+    const cycleStart = `${firstYear + index * type.cycle_years}-${String(startMonth).padStart(2, '0')}-01`;
+    const cycle = {
+        period_start: cycleStart,
+        period_end: (0, working_days_1.shiftDays)((0, working_days_1.addMonths)(cycleStart, type.cycle_years * 12), -1),
+    };
+    return {
+        cycle,
+        period: {
+            period_start: cycle.period_start < employmentStart ? employmentStart : cycle.period_start,
+            period_end: cycle.period_end,
+        },
+    };
+};
+exports.cyclePeriodFor = cyclePeriodFor;
+/** A full cycle's days scaled to the part of it `period` covers, to the half-day precision of the column. */
+const proRataDays = (defaultDays, { cycle, period }) => round((defaultDays * daysIn(period)) / daysIn(cycle), 1);
+exports.proRataDays = proRataDays;
+/**
+ * The last day of the first-months rate for an entitlement over `period`: `initialMonths`
+ * from the start date, or null when that is over before the period begins.
+ */
+const initialUntil = (employmentStart, initialMonths, period) => {
+    if (initialMonths <= 0)
+        return null;
+    const until = (0, working_days_1.shiftDays)((0, working_days_1.addMonths)(employmentStart, initialMonths), -1);
+    return until >= period.period_start ? until : null;
+};
+exports.initialUntil = initialUntil;
+/**
+ * The part of `days_entitled` earned by the end of `asOf`. Upfront: everything from the first
+ * day. Monthly: an equal share per completed month (a short last month earns its fraction on
+ * the period's final day). Either way, inside the first-months window the total is capped at
+ * `initial_days_per_month` per completed month.
+ */
+const accruedDays = (entitlement, asOf) => {
+    const { period_start, period_end, days_entitled } = entitlement;
+    if (asOf < period_start)
+        return 0;
+    let earned = days_entitled;
+    if (entitlement.grant_method === enum_1.LeaveGrantMethod.MONTHLY && asOf < period_end) {
+        const whole = (0, working_days_1.completedMonths)(period_start, period_end);
+        const lastStart = (0, working_days_1.addMonths)(period_start, whole);
+        const lastLength = daysIn({ period_start: lastStart, period_end: (0, working_days_1.shiftDays)((0, working_days_1.addMonths)(period_start, whole + 1), -1) });
+        const tail = lastStart <= period_end ? daysIn({ period_start: lastStart, period_end }) / lastLength : 0;
+        earned = (days_entitled * (0, working_days_1.completedMonths)(period_start, asOf)) / (whole + tail);
+    }
+    if (entitlement.initial_until && entitlement.initial_days_per_month !== null && asOf <= entitlement.initial_until) {
+        earned = Math.min(earned, entitlement.initial_days_per_month * (0, working_days_1.completedMonths)(period_start, asOf));
+    }
+    return round(Math.min(earned, days_entitled), 2);
+};
+exports.accruedDays = accruedDays;
+/**
+ * The balance of an entitlement on `asOf`, from the live requests starting inside its period
+ * and the sum of its adjustments. Carried days are spent first: whatever of them the requests
+ * starting on or before `carried_expires_on` did not use is forfeited once that day has passed.
+ */
+const balanceOf = (entitlement, requests, daysAdjusted, asOf) => {
+    const live = requests.filter((request) => request.status === enum_1.LeaveRequestStatus.APPROVED || request.status === enum_1.LeaveRequestStatus.PENDING);
+    const sum = (rows) => rows.reduce((total, request) => total + Number(request.days), 0);
+    const daysUsed = sum(live.filter((request) => request.status === enum_1.LeaveRequestStatus.APPROVED));
+    const daysPending = sum(live.filter((request) => request.status === enum_1.LeaveRequestStatus.PENDING));
+    const expiry = entitlement.carried_expires_on;
+    const daysForfeited = expiry && asOf > expiry
+        ? Math.max(entitlement.days_carried - sum(live.filter((request) => request.start_date <= expiry)), 0)
+        : 0;
+    const daysAccrued = (0, exports.accruedDays)(entitlement, asOf);
+    return {
+        as_of: asOf,
+        days_accrued: daysAccrued,
+        days_forfeited: round(daysForfeited, 2),
+        days_adjusted: round(daysAdjusted, 2),
+        days_used: round(daysUsed, 2),
+        days_pending: round(daysPending, 2),
+        days_remaining: round(daysAccrued + entitlement.days_carried - daysForfeited + daysAdjusted - daysUsed - daysPending, 2),
+    };
+};
+exports.balanceOf = balanceOf;

package/dist/leave/leave-requests.d.ts

@@ -1,9 +1,9 @@
 import type { MmsList } from '@managemint-solutions/entities/common';
-import type { LeavePeriod, LeaveRequestEntity } from '@managemint-solutions/entities/leave';
+import type { LeaveCalendarEntry, LeaveRequestEntity } from '@managemint-solutions/entities/leave';
 import { LeaveRequestStatus, LeaveReviewDecision } from '@managemint-solutions/entities/leave/enum';
 import { type AuditActor, type AuditResource } from '../audit';
 import type { TypedSupabaseClient } from '../client';
-import type { GetLeaveRequestsDto } from './dto';
+import type { GetLeaveCalendarDto, GetLeaveRequestsDto } from './dto';
 /** A request as the api inserts it: the caller's own, with the days already counted. */
 export type CreateLeaveRequestRow = {
     user_id: string;
@@ -47,12 +47,8 @@ export declare class LeaveRequestsResource {
      * half of the rule; the table's exclusion constraint is the half that survives a race.
      */
     overlaps(userId: string, start: string, end: string, excludeId?: string): Promise<boolean>;
-    /**
-     * The days of `userId`'s requests of `leaveTypeId` in `statuses` that start inside `period` -
-     * what an entitlement's balance is checked against. `excludeId` leaves out the request being
-     * edited or approved so it is not counted against itself.
-     */
-    sumDays(userId: string, leaveTypeId: string, period: LeavePeriod, statuses: LeaveRequestStatus[], excludeId?: string): Promise<number>;
+    /** Live requests touching `date_from`..`date_to`, for everyone in the organization - the leave calendar. */
+    calendar(query: GetLeaveCalendarDto): Promise<LeaveCalendarEntry[]>;
     create(input: CreateLeaveRequestRow): Promise<LeaveRequestEntity>;
     /** Edits a request while it is still pending; null when it no longer is. */
     update(leaveRequestId: string, input: UpdateLeaveRequestRow): Promise<LeaveRequestEntity | null>;
@@ -62,7 +58,10 @@ export declare class LeaveRequestsResource {
      * can say so instead of overwriting their decision.
      */
     review(leaveRequestId: string, input: ReviewLeaveRequestRow): Promise<LeaveRequestEntity | null>;
-    /** Cancels a request while it is still pending; null when it no longer is - a decided request is final. */
-    cancel(leaveRequestId: string, cancelledBy: string): Promise<LeaveRequestEntity | null>;
+    /**
+     * Cancels a request that is still in `expected` - the status the api read and decided on.
+     * Null when it has moved on since (reviewed, or cancelled by someone else).
+     */
+    cancel(leaveRequestId: string, cancelledBy: string, expected: LeaveRequestStatus): Promise<LeaveRequestEntity | null>;
 }
 export {};