Skip to main content

Function: computeOverageCatchupCentavos()

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

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

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. Payable hours are read from the period's settling-week range, filtered to PAYABLE_ENTRY_STATUSES.

newlyApprovedWeekStart is the approval's stored week_start; run it 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.

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​

DateError if newlyApprovedWeekStart (or a stored assignment date) is not a valid YYYY-MM-DD; throws from the Centavos guard on a non-integer stored rate.