Skip to main content

Function: fetchInvoiceShelf()

fetchInvoiceShelf(companyId, facilityId, weekStart): Promise<InvoiceShelfData | null>

Defined in: src/server/services/invoice/weeklyRun.ts:193

Billing detail for a facility's Sun–Sat week: per-contractor contracted-vs-logged with the approval split, plus a live preview total and the send-readiness flags.

Mirrors what the invoice generator will actually bill and send, so the shelf's preview never drifts from the eventual draft:

  • Assignment set matches buildInvoicePreview (same window, NO active filter); one row per contractor via latest-effective / primary-on-tie / lowest-id. Null-rate assignments are kept only to raise the "No rate" warning — they bill $0.
  • Logged hours = sum of time entries in PAYABLE statuses; the approved/unapproved split uses APPROVED/UNAPPROVED. Each line bills the lesser of logged and contracted × rate, unless an approved overage for that assignment/contractor this week lifts the cap.
  • A line is variance-flagged only when its overage was NOT approved and its variance exceeds the facility's variance_flag_threshold_pct (default 10).

Parameters​

companyId​

string

Tenant scope; every underlying query is filtered by it (signed-in admin's company).

facilityId​

string

The facility whose week is being reconciled.

weekStart​

CalendarDate

The Sunday anchoring the billing week (CalendarDate); the period is weekStart..weekStart + 6 inclusive.

Returns​

Promise<InvoiceShelfData | null>

The InvoiceShelfData for the facility+week, or null if the facility does not exist for this company. When the facility exists but has no in-window assignments, returns a base payload with empty lines and a zero totalCents (still carrying the existing-invoice / contact flags). Money fields are integer cents.