Function: createSupplementalInvoice()

createSupplementalInvoice(companyId, parentInvoiceId, createdBy, expectedTotalCents, expectedLinesKey): Promise<{ invoiceId: string; invoiceNumber: string; pdfStored: boolean; } | { error: string; }>

Defined in: src/server/services/invoice/supplemental.ts:275

Create the supplemental atomically (the extended create_facility_invoice RPC locks and re-validates the parent, allocates the next number, and inserts the invoice + lines in one transaction with origin='supplemental' and the parent link), then render and store its PDF with the "Supplement to INV-XXXX" notice. Owner-gated upstream. On any guard failure nothing persists.

Parameters

companyId

string

Tenant scope.

parentInvoiceId

string

The drifted parent invoice to supplement.

createdBy

string

User id recorded as the creator (audit).

expectedTotalCents

number

Integer cents the owner confirmed in the preview; refused if the freshly recomputed delta no longer matches (optimistic concurrency, as the generator's).

expectedLinesKey

string

supplementalLinesKey of the previewed lines; refused if the fresh composition differs — two line sets can sum to the same cents (issue #137), so the total check alone doesn't prove the operator reviewed THESE lines. Both bindings are REQUIRED here, not just at the action's Zod boundary: a future second caller (e.g. a cron) must not get an unbound create silently.

Returns

Promise<{ invoiceId: string; invoiceNumber: string; pdfStored: boolean; } | { error: string; }>

{ invoiceId, invoiceNumber, pdfStored } on success (pdfStored: false = created but the PDF render failed, recoverable via Regenerate PDF); otherwise { error }.