Skip to main content

Function: computeOverageCatchupCentavos()

computeOverageCatchupCentavos(svc, companyId, contractorId, assignmentId, period, newlyApprovedWeekStart): Promise<number>

Defined in: src/server/services/catchupPay.ts:139

The marginal pay that APPROVING newlyApprovedWeekStart's overage adds to an already-paid period: pay(all approved overage weeks) − pay(all approved EXCEPT this one), on the period's payable hours. Other weeks (paid at close) cancel out, isolating just this approval's premium. Call AFTER the approval row is marked approved (so it's in the set). Returns 0 when the period can't be priced.

Approving an overage lifts the per-week billing/pay cap from contracted to the actually-logged hours for that week, so the premium is the extra pay those over-contract hours now earn.

newlyApprovedWeekStart is the approval's stored week_start; it is run through overageApprovalWeekToPayWeek (identity for a new Monday week, +1 for a legacy Sunday week) so it lands in the same Monday pay-week key space as the loaded approved set before the marginal subtraction — the subtraction can't silently no-op.

Parameters​

svc​

SupabaseClient

Service-role Supabase client (bypasses RLS); all queries are still scoped by companyId.

companyId​

string

Tenant scope applied to every query.

contractorId​

string

Contractor whose leave and overage approvals are loaded.

assignmentId​

string

Contractor↔facility assignment supplying the rate, contracted hours, and effective/end dates.

period​

BiMonthlyPeriod

Bi-monthly pay period to price (billing and pay both key on the Mon–Sun week, ADR-0044).

newlyApprovedWeekStart​

string

The just-approved overage week's stored week_start (Monday for new approvals, Sunday for legacy); snapped to its Monday pay week internally.

Returns​

Promise<number>

Non-negative incremental overage pay in integer centavos (clamped at 0); 0 if the assignment/rate is missing or the engine cannot price the period.

Throws​

Error when a bundle read fails or is truncated (#170/#171); DateError if newlyApprovedWeekStart (or a stored assignment date) is not a valid YYYY-MM-DD; MoneyError on a non-integer stored rate.