Skip to main content

Function: computeOverageCatchupCentavos()

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

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

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.

Note the week-anchor translation: newlyApprovedWeekStart is the raw Sunday billing-week key as stored on the approval, while the loaded approved set holds Monday pay-week keys; it is run through overageApprovalWeekToPayWeek before removal, otherwise the "without" set is identical and the marginal subtraction yields 0.

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 weeks are Sunday-anchored; the pay engine keys on Monday ISO weeks).

newlyApprovedWeekStart​

string

The just-approved overage week's Sunday billing-week start (ISO YYYY-MM-DD); translated internally to the engine's Monday pay week.

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.