@dainamite/billing 0.19.0 → 0.21.0

package/src/modules/billing/lib/invoiceDelivery.ts

@@ -0,0 +1,197 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { z } from 'zod'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import type { SendEmailOptions } from '@open-mercato/shared/lib/email/send'
+import { BillingAccount, BillingInvoice } from '../data/entities'
+import { emitBillingEvent } from '../events'
+import { DEFAULT_INVOICE_LANGUAGE } from './invoiceLanguages'
+import { formatIban } from './iban'
+import { documentLocale, formatDocumentDate, formatDocumentMoney, type DocumentTranslate } from './pdf/invoiceModel'
+import { getInvoicePdf, loadDocumentTranslator, type TranslatorLoader } from './pdf/invoicePdf'
+
+/**
+ * Emails a posted billing document to the account's invoice address with
+ * the frozen PDF attached (Spec B), through the platform's standard
+ * `sendEmail()` — no custom transport.
+ *
+ *   - posted (non-draft, non-test) documents only → 409 `billing.invoice.not_posted`;
+ *   - the connector's placeholder addresses (`@invalid.local`) and malformed
+ *     emails are refused → 422 `billing.invoice.email_invalid`, nothing sent;
+ *   - every attempt appends `{ at, to, status, error?, trigger }` to
+ *     `metadata.deliveries` (atomic jsonb append — concurrent sends never
+ *     lose an entry) and emits `billing.invoice.sent` / `send_failed`;
+ *   - transport errors (e.g. `EMAIL_TRANSPORT_NOT_CONFIGURED`) are recorded
+ *     as a `failed` delivery and returned, never thrown — posting is
+ *     unaffected and the operator sees the reason.
+ */
+
+export type DeliveryTrigger = 'manual' | 'auto'
+
+export type InvoiceDelivery = {
+  at: string
+  to: string
+  status: 'sent' | 'failed'
+  error?: string | null
+  trigger: DeliveryTrigger
+}
+
+export type SendInvoiceResult = { invoiceId: string; to: string; status: 'sent' | 'failed'; error: string | null }
+
+export type SendEmailFn = (options: SendEmailOptions) => Promise<void>
+
+export type SendInvoiceDeps = {
+  sendEmail?: SendEmailFn
+  loadTranslator?: TranslatorLoader
+  now?: () => Date
+}
+
+const PLACEHOLDER_DOMAIN = '@invalid.local'
+const emailSchema = z.string().trim().email()
+
+export function isDeliverableEmail(value: string | null | undefined): value is string {
+  if (!value) return false
+  if (value.trim().toLowerCase().endsWith(PLACEHOLDER_DOMAIN)) return false
+  return emailSchema.safeParse(value).success
+}
+
+export function hasSuccessfulDelivery(
+  invoice: Pick<BillingInvoice, 'metadata'>,
+  trigger?: DeliveryTrigger,
+): boolean {
+  const deliveries = (invoice.metadata?.deliveries ?? []) as InvoiceDelivery[]
+  return Array.isArray(deliveries) && deliveries.some((d) => d.status === 'sent' && (!trigger || d.trigger === trigger))
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c)
+}
+
+function fill(template: string, params: Record<string, string>): string {
+  return template.replace(/\{(\w+)\}/g, (match, key: string) => params[key] ?? match)
+}
+
+/** Subject + plain-text and HTML bodies in the document language. Pure. */
+export function buildInvoiceEmail(params: {
+  invoice: Pick<BillingInvoice, 'number' | 'totalGross' | 'currencyCode' | 'dueDate'>
+  buyerName: string
+  sellerName: string | null
+  iban: string | null
+  language: string
+  translate: DocumentTranslate
+}): { subject: string; text: string; html: string } {
+  const { invoice, translate: t } = params
+  const locale = documentLocale(params.language)
+  const values = {
+    number: invoice.number,
+    name: params.buyerName,
+    amount: formatDocumentMoney(invoice.totalGross, invoice.currencyCode, locale).replace(/[  ]/g, ' '),
+    dueDate: formatDocumentDate(invoice.dueDate ?? null, locale),
+    iban: params.iban ? formatIban(params.iban) : '',
+  }
+  const paragraphs = [
+    fill(t('billing.email.invoice.greeting', 'Hello {name},'), values),
+    fill(t('billing.email.invoice.body', 'Please find attached invoice {number} for {amount}, due on {dueDate}.'), values),
+    params.iban
+      ? fill(t('billing.email.invoice.payment', 'Please pay to IBAN {iban} with the transfer title {number}.'), values)
+      : '',
+    [t('billing.email.invoice.closing', 'Kind regards,'), params.sellerName ?? ''].filter(Boolean).join('\n'),
+  ].filter(Boolean)
+  return {
+    subject: fill(t('billing.email.invoice.subject', 'Invoice {number}'), values),
+    text: paragraphs.join('\n\n'),
+    html: paragraphs.map((p) => `<p>${escapeHtml(p).replace(/\n/g, '<br/>')}</p>`).join(''),
+  }
+}
+
+async function defaultSendEmail(options: SendEmailOptions): Promise<void> {
+  const { sendEmail } = await import('@open-mercato/shared/lib/email/send')
+  await sendEmail(options)
+}
+
+async function appendDelivery(em: EntityManager, invoice: BillingInvoice, delivery: InvoiceDelivery): Promise<void> {
+  await em.execute(
+    `UPDATE billing_invoices
+        SET metadata = jsonb_set(COALESCE(metadata, '{}'::jsonb), '{deliveries}',
+                                 COALESCE(metadata->'deliveries', '[]'::jsonb) || ?::jsonb),
+            updated_at = now()
+      WHERE id = ? AND tenant_id = ? AND organization_id = ?`,
+    [JSON.stringify([delivery]), invoice.id, invoice.tenantId, invoice.organizationId],
+  )
+  const deliveries = Array.isArray(invoice.metadata?.deliveries) ? (invoice.metadata?.deliveries as InvoiceDelivery[]) : []
+  invoice.metadata = { ...(invoice.metadata ?? {}), deliveries: [...deliveries, delivery] }
+}
+
+export async function sendInvoice(
+  em: EntityManager,
+  params: { invoiceId: string; tenantId: string; organizationId: string; trigger: DeliveryTrigger },
+  deps: SendInvoiceDeps = {},
+): Promise<SendInvoiceResult> {
+  const scope = { tenantId: params.tenantId, organizationId: params.organizationId }
+  const invoice = await em.findOne(BillingInvoice, { id: params.invoiceId, ...scope, deletedAt: null } as never)
+  if (!invoice) throw new CrudHttpError(404, { error: 'Invoice not found' })
+  if (invoice.status === 'draft' || invoice.testRun) {
+    throw new CrudHttpError(409, {
+      error: 'Only posted invoices can be sent',
+      code: 'billing.invoice.not_posted',
+    })
+  }
+
+  // The live account address wins (an operator may fix a bad address and
+  // resend); the frozen buyer snapshot is the fallback for a deleted account.
+  const account = await em.findOne(BillingAccount, { id: invoice.billAccountId, ...scope } as never)
+  const buyer = (invoice.buyerSnapshot ?? {}) as Record<string, unknown>
+  const to = account?.invoiceEmail ?? (typeof buyer.invoice_email === 'string' ? buyer.invoice_email : '')
+  if (!isDeliverableEmail(to)) {
+    throw new CrudHttpError(422, {
+      error: 'The billing account has no deliverable invoice email',
+      code: 'billing.invoice.email_invalid',
+    })
+  }
+
+  const language =
+    (typeof buyer.invoice_language === 'string' && buyer.invoice_language) ||
+    account?.invoiceLanguage ||
+    DEFAULT_INVOICE_LANGUAGE
+  const translate = await (deps.loadTranslator ?? loadDocumentTranslator)(language)
+  const seller = (invoice.sellerSnapshot ?? {}) as Record<string, unknown>
+  const email = buildInvoiceEmail({
+    invoice,
+    buyerName: (typeof buyer.name === 'string' && buyer.name) || account?.name || '',
+    sellerName: typeof seller.legal_name === 'string' ? seller.legal_name : null,
+    iban: typeof seller.iban === 'string' ? seller.iban : null,
+    language,
+    translate,
+  })
+
+  const now = deps.now ?? (() => new Date())
+  let error: string | null = null
+  try {
+    const pdf = await getInvoicePdf(em, invoice, { loadTranslator: deps.loadTranslator })
+    await (deps.sendEmail ?? defaultSendEmail)({
+      to,
+      subject: email.subject,
+      text: email.text,
+      html: email.html,
+      attachments: [{ filename: pdf.fileName, content: Buffer.from(pdf.bytes).toString('base64'), contentType: 'application/pdf' }],
+      tenantId: params.tenantId,
+      organizationId: params.organizationId,
+    })
+  } catch (err) {
+    error = err instanceof Error ? err.message : String(err)
+    console.warn('[billing.invoice.send] delivery failed', invoice.id, error)
+  }
+
+  const status: InvoiceDelivery['status'] = error ? 'failed' : 'sent'
+  await appendDelivery(em, invoice, { at: now().toISOString(), to, status, error, trigger: params.trigger })
+  await emitBillingEvent(status === 'sent' ? 'billing.invoice.sent' : 'billing.invoice.send_failed', {
+    invoiceId: invoice.id,
+    invoiceNumber: invoice.number,
+    billAccountId: invoice.billAccountId,
+    to,
+    trigger: params.trigger,
+    error,
+    tenantId: invoice.tenantId,
+    organizationId: invoice.organizationId,
+  })
+  return { invoiceId: invoice.id, to, status, error }
+}

package/src/modules/billing/lib/invoiceLanguages.ts

@@ -0,0 +1,34 @@
+/**
+ * Invoice languages the built-in billing document template can render.
+ *
+ * Single source of truth for the account form's language picklist and the
+ * `invoiceLanguage` validator. Adding a language means adding the template
+ * labels for it AND one entry here — never one without the other.
+ *
+ * `label` is the language's own name (endonym), so it reads correctly no
+ * matter which UI locale the operator uses — it is intentionally not routed
+ * through i18n.
+ *
+ * Spec: .ai/specs/2026-11-14-billing-account-workspace.md (D22). Narrowing the
+ * list per organization (`BillingSettings.enabled_invoice_languages`) arrives
+ * with the standalone-ledger spec; until then every supported language is
+ * selectable.
+ */
+
+export const SUPPORTED_INVOICE_LANGUAGES = [
+  { code: 'en', label: 'English' },
+  { code: 'pl', label: 'Polski' },
+] as const
+
+export type InvoiceLanguageCode = (typeof SUPPORTED_INVOICE_LANGUAGES)[number]['code']
+
+export const INVOICE_LANGUAGE_CODES = SUPPORTED_INVOICE_LANGUAGES.map((l) => l.code) as [
+  InvoiceLanguageCode,
+  ...InvoiceLanguageCode[],
+]
+
+export const DEFAULT_INVOICE_LANGUAGE: InvoiceLanguageCode = 'en'
+
+export function isSupportedInvoiceLanguage(value: string): value is InvoiceLanguageCode {
+  return (INVOICE_LANGUAGE_CODES as readonly string[]).includes(value)
+}

package/src/modules/billing/lib/invoiceWriter.ts

@@ -1,62 +1,61 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
-import type { AwilixContainer } from 'awilix'
-import {
-  SalesInvoice,
-  SalesInvoiceLine,
-} from '@open-mercato/core/modules/sales/data/entities'
-import type { SalesDocumentNumberGenerator } from '@open-mercato/core/modules/sales/services/salesDocumentNumberGenerator'
+import { BillingInvoice, BillingInvoiceLine } from '../data/entities'
 import type { BillingAccount, BillingItem } from '../data/entities'
 import type { BillPeriod } from './billPeriod'
-import {
-  __resetInvoiceStatusCacheForTests,
-  resolveInvoiceStatusEntryId,
-} from './invoiceStatus'
+import type { RecurringLine } from './servicePeriods'
+import { draftNumber, testNumber } from './numbering'
+import { sumTotals } from './vat'
+import { lineVat, priceBasisOf, unitPriceNetOf, type PriceBasis } from './lineAmounts'
 
 /**
- * Writes a `core/sales` draft invoice for a billing account's bill period.
+ * Writes a billing-owned draft invoice (`billing_invoices` +
+ * `billing_invoice_lines`) for one bill date of an account — Spec 0: billing
+ * no longer records anything in core `sales`.
  *
- * Two notable deviations from the spec, documented in CHANGELOG / spec:
- *
- *   1. `SalesInvoice.invoice_number` is `NOT NULL` in the upstream
- *      schema, but the spec says "sequence number assigned at Post."
- *      Real-mode invoices get a real number via
- *      `salesDocumentNumberGenerator.generate({ kind: 'invoice' })` at
- *      *draft create time* — the spec's intent (gap-free numbering via
- *      atomic SQL upsert) is preserved; the timing differs because the
- *      upstream column is `NOT NULL`. "Post" then just transitions
- *      status `draft → posted`.
- *
- *   2. Test-mode invoices use a `TEST-<uuid>` placeholder number (not
- *      the real sequence) so test runs do not burn production numbers
- *      and can be repeated idempotently.
- *
- * VAT is NOT computed here — `core/sales`'s tax service owns the
- * per-line `tax_rate` / `tax_amount` calculation, and runs on POST.
- * Drafts therefore carry zeroes in the tax columns; the totals reflect
- * net amounts only.
+ *   - Real drafts get a temporary `DRAFT-…` number; the series number is
+ *     claimed only at post (gap-free numbering — no number is burnt by a
+ *     deleted draft).
+ *   - Test drafts get `TEST-…` and `test_run = true`; they are never posted.
+ *   - Spec B (B-D2): every line carries its item's VAT rate; tax is rounded
+ *     per line (half-up, 2 dp) and totals are sums of the rounded lines.
+ *   - Spec F (F-D2): line amounts are on the item's `price_basis`; net / tax
+ *     / gross come from `lineVat`, so a typed gross is reproduced exactly.
  */
 
 export type WriteMode = 'real' | 'test' | 'dry'
 
 export type InvoiceLineDescriptor = {
-  /** Maps to billing_item_id on the resulting SalesInvoiceLine.metadata. */
+  /** Maps to `billing_invoice_lines.billing_item_id`. */
   billingItemId: string
   /** From the spec's `metadata.billing_type` for traceability. */
   billingType: 'one_time' | 'recurring' | 'usage'
   description: string
-  /** Net unit price (numeric string for SalesInvoiceLine.unit_price_net). */
-  unitPriceNet: string
+  /** Unit price on `priceBasis` (numeric string). The writer derives `unit_price_net`. */
+  unitPrice: string
   /** Quantity (string for the numeric(18,4) column). */
   quantity: string
-  /** Total net (string). */
-  totalNetAmount: string
+  /** Extended line amount on `priceBasis` (unit × quantity × proration). */
+  lineAmount: string
+  /** Spec F: the basis `unitPrice` / `lineAmount` are on (the item's `price_basis`). */
+  priceBasis: PriceBasis
+  /** Spec B: VAT rate in percent (numeric string), from the item. */
+  taxRate: string
   /** Optional per-line metadata extension — e.g. usage tier breakdown. */
   metadataExtra?: Record<string, unknown>
+  /**
+   * Spec A: inclusive service period the line covers (recurring + usage).
+   * Written to line metadata and used for the invoice's display period.
+   */
+  servicePeriodStart?: Date
+  servicePeriodEnd?: Date
 }
 
 export type WriteInvoiceParams = {
   mode: WriteMode
   account: BillingAccount
+  /** Spec A: the bill date this invoice is for — the dedupe key. */
+  billDate: Date
+  /** Display period: min/max of the line service periods (see `displayPeriod`). */
   period: BillPeriod
   billRunId: string
   lines: InvoiceLineDescriptor[]
@@ -66,148 +65,105 @@ export type WrittenInvoice = {
   invoiceId: string | null
   invoiceNumber: string | null
   totalNet: string
+  totalGross: string
 }
 
-const DRAFT_INVOICE_STATUS_VALUE = 'draft'
+/** @deprecated kept for test-suite compatibility; the writer has no cache any more. */
+export function __resetInvoiceWriterCacheForTests(): void {}
 
-/**
- * Test hook — clears the shared resolver's status cache so the engine
- * test suite stays deterministic across mocked-EM environments.
- */
-export function __resetInvoiceWriterCacheForTests(): void {
-  __resetInvoiceStatusCacheForTests()
-}
-
-function generateTestInvoiceNumber(): string {
-  // Match the pattern operators search by: `TEST-` prefix + random
-  // suffix so the test wipe-out endpoint can filter via `LIKE 'TEST-%'`
-  // (defensive — primary filter is `metadata.test_run=true`).
-  const random = Math.floor(Math.random() * 1e9)
-    .toString(16)
-    .padStart(8, '0')
-  return `TEST-${Date.now().toString(16)}-${random}`
-}
-
-/**
- * 2dp half-up rounding that survives binary floating-point edge cases
- * (e.g. `1.005 * 100 === 100.49999...` would otherwise round DOWN to
- * `1.00` under naive `Math.round`). The `+ EPSILON` nudge pushes
- * representations like 100.4999...8 up to the true half-up boundary.
- * Matches the spec's "2 decimal places, half-up" rounding policy.
- */
+/** 2dp half-up rounding (survives 1.005-style binary edges). */
 function roundHalfUp2dp(value: number): number {
-  return Math.round((value + Number.EPSILON) * 100) / 100
+  const sign = value < 0 ? -1 : 1
+  return (sign * Math.round((Math.abs(value) + Number.EPSILON) * 100)) / 100
 }
 
 function format4dp(value: number): string {
   return roundHalfUp2dp(value).toFixed(4)
 }
 
-function sumNetTotal(lines: InvoiceLineDescriptor[]): string {
-  let total = 0
-  for (const line of lines) {
-    total += Number.parseFloat(line.totalNetAmount)
-  }
-  return format4dp(total)
+/** VAT rate of an item as a numeric string; items predating Spec B read as 0. */
+export function itemTaxRate(item: Pick<BillingItem, 'taxRate'>): string {
+  const rate = Number.parseFloat(String(item.taxRate ?? '0'))
+  return Number.isFinite(rate) && rate >= 0 ? String(rate) : '0'
+}
+
+function isoDate(date: Date): string {
+  return new Date(date).toISOString().slice(0, 10)
 }
 
 export async function writeDraftInvoice(
   em: EntityManager,
-  container: AwilixContainer,
   params: WriteInvoiceParams,
 ): Promise<WrittenInvoice> {
-  const totalNet = sumNetTotal(params.lines)
+  const amounts = params.lines.map((line) =>
+    lineVat({ amount: line.lineAmount, priceBasis: line.priceBasis, taxRate: line.taxRate }),
+  )
+  const totals = sumTotals(amounts)
 
   if (params.mode === 'dry') {
     // Compute totals; persist nothing.
-    return { invoiceId: null, invoiceNumber: null, totalNet }
+    return { invoiceId: null, invoiceNumber: null, totalNet: totals.subtotalNet, totalGross: totals.totalGross }
   }
 
   const { account, period, billRunId, lines, mode } = params
-
-  let invoiceNumber: string
-  if (mode === 'test') {
-    invoiceNumber = generateTestInvoiceNumber()
-  } else {
-    const numberGenerator = container.resolve(
-      'salesDocumentNumberGenerator',
-    ) as SalesDocumentNumberGenerator
-    const generated = await numberGenerator.generate({
-      organizationId: account.organizationId,
-      tenantId: account.tenantId,
-      kind: 'invoice',
-    })
-    invoiceNumber = generated.number
-  }
-
-  const statusEntryId = await resolveInvoiceStatusEntryId(
-    em,
-    account.tenantId,
-    account.organizationId,
-    'draft',
-  )
-
+  const invoiceNumber = mode === 'test' ? testNumber() : draftNumber()
   const now = new Date()
-  const invoice = em.create(SalesInvoice, {
+
+  const invoice = em.create(BillingInvoice, {
     organizationId: account.organizationId,
     tenantId: account.tenantId,
-    invoiceNumber,
-    statusEntryId,
-    status: DRAFT_INVOICE_STATUS_VALUE,
-    issueDate: now,
+    billAccountId: account.id,
+    documentType: 'invoice',
+    number: invoiceNumber,
+    series: null,
+    status: 'draft',
+    testRun: mode === 'test',
+    billRunId,
+    billDate: params.billDate,
+    periodStart: period.periodStart,
+    periodEnd: period.periodEnd,
     currencyCode: account.currencyCode,
-    subtotalNetAmount: totalNet,
-    subtotalGrossAmount: totalNet, // gross == net for drafts (tax computed on post)
-    discountTotalAmount: '0',
-    taxTotalAmount: '0',
-    grandTotalNetAmount: totalNet,
-    grandTotalGrossAmount: totalNet,
-    paidTotalAmount: '0',
-    outstandingAmount: totalNet,
-    metadata: {
-      bill_run_id: billRunId,
-      bill_account_id: account.id,
-      bill_period_start: period.periodStart.toISOString().slice(0, 10),
-      bill_period_end: period.periodEnd.toISOString().slice(0, 10),
-      test_run: mode === 'test' ? true : undefined,
-    },
+    subtotalNet: totals.subtotalNet,
+    taxTotal: totals.taxTotal,
+    totalGross: totals.totalGross,
+    paidTotal: '0',
+    creditedTotal: '0',
+    outstanding: totals.totalGross,
     createdAt: now,
     updatedAt: now,
   })
   em.persist(invoice)
+  await em.flush() // need the invoice id for the lines
 
-  let lineNumber = 1
-  for (const line of lines) {
-    const invoiceLine = em.create(SalesInvoiceLine, {
-      invoice,
-      organizationId: account.organizationId,
-      tenantId: account.tenantId,
-      lineNumber: lineNumber++,
-      kind: 'product',
-      description: line.description,
-      quantity: line.quantity,
-      normalizedQuantity: line.quantity,
-      currencyCode: account.currencyCode,
-      unitPriceNet: line.unitPriceNet,
-      unitPriceGross: line.unitPriceNet, // gross == net until tax computed on post
-      discountAmount: '0',
-      discountPercent: '0',
-      taxRate: '0',
-      taxAmount: '0',
-      totalNetAmount: line.totalNetAmount,
-      totalGrossAmount: line.totalNetAmount,
-      metadata: {
-        billing_item_id: line.billingItemId,
-        billing_type: line.billingType,
-        ...(line.metadataExtra ?? {}),
-      },
-    })
-    em.persist(invoiceLine)
-  }
-
+  lines.forEach((line, index) => {
+    const amount = amounts[index]
+    em.persist(
+      em.create(BillingInvoiceLine, {
+        organizationId: account.organizationId,
+        tenantId: account.tenantId,
+        invoiceId: invoice.id,
+        lineNumber: index + 1,
+        billingItemId: line.billingItemId,
+        billingType: line.billingType,
+        description: line.description,
+        quantity: line.quantity,
+        unitPriceNet:
+          line.priceBasis === 'gross' ? unitPriceNetOf(line.unitPrice, 'gross', line.taxRate) : line.unitPrice,
+        taxRate: line.taxRate,
+        netAmount: format4dp(amount.net),
+        taxAmount: format4dp(amount.tax),
+        grossAmount: format4dp(amount.gross),
+        servicePeriodStart: line.servicePeriodStart ?? null,
+        servicePeriodEnd: line.servicePeriodEnd ?? null,
+        metadata: line.metadataExtra ?? null,
+        createdAt: now,
+        updatedAt: now,
+      }),
+    )
+  })
   await em.flush()
 
-  return { invoiceId: invoice.id, invoiceNumber, totalNet }
+  return { invoiceId: invoice.id, invoiceNumber, totalNet: totals.subtotalNet, totalGross: totals.totalGross }
 }
 
 /**
@@ -238,9 +194,11 @@ export function buildInvoiceLinesFromItems(
         billingItemId: item.id,
         billingType: 'one_time',
         description: item.description,
-        unitPriceNet: amount,
+        unitPrice: amount,
         quantity: '1',
-        totalNetAmount: amount,
+        lineAmount: amount,
+        priceBasis: priceBasisOf(item.priceBasis),
+        taxRate: itemTaxRate(item),
       })
     } else if (item.type === 'recurring') {
       const rate = item.rateJson as { unit_price?: number } | null
@@ -250,11 +208,67 @@ export function buildInvoiceLinesFromItems(
         billingItemId: item.id,
         billingType: 'recurring',
         description: item.description,
-        unitPriceNet: unitPrice,
+        unitPrice,
         quantity: '1',
-        totalNetAmount: unitPrice,
+        lineAmount: unitPrice,
+        priceBasis: priceBasisOf(item.priceBasis),
+        taxRate: itemTaxRate(item),
       })
     }
   }
   return lines
 }
+
+/**
+ * Display period of an invoice: min start / max end over the lines' service
+ * periods, falling back to `fallback` (the arrears window) when no line
+ * carries one (e.g. a one_time-only invoice).
+ */
+export function displayPeriod(lines: readonly InvoiceLineDescriptor[], fallback: BillPeriod): BillPeriod {
+  let start: Date | null = null
+  let end: Date | null = null
+  for (const line of lines) {
+    if (line.servicePeriodStart && (!start || line.servicePeriodStart < start)) start = line.servicePeriodStart
+    if (line.servicePeriodEnd && (!end || line.servicePeriodEnd > end)) end = line.servicePeriodEnd
+  }
+  return { periodStart: start ?? fallback.periodStart, periodEnd: end ?? fallback.periodEnd }
+}
+
+/**
+ * Spec A: invoice lines for computed recurring service periods (charges and
+ * credits). Full-period charges keep the bare item description; partial
+ * periods and credits append the covered dates so the line is
+ * self-explanatory on any document (language-neutral — the PDF renders
+ * localized labels later).
+ */
+export function buildRecurringLineDescriptors(
+  item: Pick<BillingItem, 'id' | 'description' | 'chargeTiming' | 'taxRate' | 'priceBasis'>,
+  lines: readonly RecurringLine[],
+): InvoiceLineDescriptor[] {
+  return lines.map((line) => {
+    const amount = format4dp(line.amount)
+    const dated = line.proration !== null || line.kind === 'credit'
+    return {
+      billingItemId: item.id,
+      billingType: 'recurring' as const,
+      description: dated
+        ? `${item.description} · ${isoDate(line.servicePeriodStart)} – ${isoDate(line.servicePeriodEnd)}`
+        : item.description,
+      unitPrice: amount,
+      quantity: '1',
+      lineAmount: amount,
+      // Proration and credit lines inherit the item's rate (Spec B) and basis (Spec F).
+      priceBasis: priceBasisOf(item.priceBasis),
+      taxRate: itemTaxRate(item),
+      servicePeriodStart: line.servicePeriodStart,
+      servicePeriodEnd: line.servicePeriodEnd,
+      metadataExtra: {
+        charge_timing: item.chargeTiming,
+        ...(line.proration
+          ? { proration: { active_days: line.proration.activeDays, period_days: line.proration.periodDays } }
+          : {}),
+        ...(line.kind === 'credit' ? { credit_for: item.id } : {}),
+      },
+    }
+  })
+}