@dainamite/billing 0.20.0 → 0.21.0

package/src/modules/billing/lib/pdf/invoicePdf.ts

@@ -0,0 +1,216 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { BillingAccount, BillingInvoice, BillingInvoiceLine } from '../../data/entities'
+import { billingEntityIds } from '../../data/entityIds'
+import { buildSellerSnapshot, getBillingSettings } from '../billingSettings'
+import { buildBuyerSnapshot } from '../documentParties'
+import { DEFAULT_INVOICE_LANGUAGE } from '../invoiceLanguages'
+import { buildInvoiceDocumentModel, type DocumentTranslate, type PdfAddress } from './invoiceModel'
+import { renderInvoicePdf, type PdfLogo } from './invoiceTemplate'
+import { attachmentIdFromUrl, readAttachment, storeAttachment } from './attachmentStore'
+
+/**
+ * Billing document PDFs (Spec B, P-D1 / B-D5):
+ *
+ *   - posted documents are rendered once and frozen as an attachment
+ *     (`pdf_attachment_id`); later downloads stream the stored file, so the
+ *     document never changes after issue. If freezing failed at post, the
+ *     first download renders and freezes it (lazy fallback).
+ *   - drafts and test documents are rendered live with a DRAFT / TEST
+ *     watermark and never stored.
+ *
+ * Parties come from the frozen snapshots on posted documents and from the
+ * live account / settings on drafts. Labels use the document language
+ * (`invoice_language`), never the operator's UI locale.
+ */
+
+export type TranslatorLoader = (language: string) => Promise<DocumentTranslate>
+
+/** Billing i18n for a document language (en / pl, falling back to en). */
+export const loadDocumentTranslator: TranslatorLoader = async (language) => {
+  const { loadDictionary } = await import('@open-mercato/shared/lib/i18n/server')
+  const { createFallbackTranslator } = await import('@open-mercato/shared/lib/i18n/translate')
+  const locale = language === 'pl' ? 'pl' : 'en'
+  const translate = createFallbackTranslator(await loadDictionary(locale))
+  return (key, fallback) => translate(key, fallback)
+}
+
+type Snapshot = Record<string, unknown>
+
+function str(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() !== '' ? value : null
+}
+
+function address(value: unknown): PdfAddress | null {
+  return value && typeof value === 'object' ? (value as PdfAddress) : null
+}
+
+export function pdfFileName(invoice: Pick<BillingInvoice, 'number'>): string {
+  return `${invoice.number.replace(/[^A-Za-z0-9._-]+/g, '-')}.pdf`
+}
+
+function isFrozenDocument(invoice: Pick<BillingInvoice, 'status' | 'testRun'>): boolean {
+  return invoice.status !== 'draft' && !invoice.testRun
+}
+
+async function resolveParties(em: EntityManager, invoice: BillingInvoice) {
+  const scope = { tenantId: invoice.tenantId, organizationId: invoice.organizationId }
+  let seller: Snapshot | null = isFrozenDocument(invoice) ? (invoice.sellerSnapshot ?? null) : null
+  let buyer: Snapshot | null = isFrozenDocument(invoice) ? (invoice.buyerSnapshot ?? null) : null
+  if (!seller || !('legal_name' in seller)) seller = buildSellerSnapshot(await getBillingSettings(em, scope))
+  if (!buyer) {
+    const account = await em.findOne(BillingAccount, { id: invoice.billAccountId, ...scope } as never)
+    buyer = account ? buildBuyerSnapshot(account) : { name: '' }
+  }
+  return { seller, buyer }
+}
+
+async function resolveLogo(em: EntityManager, invoice: BillingInvoice, seller: Snapshot): Promise<PdfLogo | null> {
+  const scope = { tenantId: invoice.tenantId, organizationId: invoice.organizationId }
+  let attachmentId = str(seller.logo_attachment_id)
+  if (!attachmentId) {
+    // Fallback: the organization logo, only when it is one of our own
+    // attachments (never fetch arbitrary URLs server-side).
+    const rows = (await em.execute(`SELECT logo_url FROM organizations WHERE id = ? LIMIT 1`, [
+      invoice.organizationId,
+    ])) as unknown as Array<{ logo_url: string | null }>
+    attachmentId = attachmentIdFromUrl(rows?.[0]?.logo_url)
+  }
+  if (!attachmentId) return null
+  const file = await readAttachment(em, scope, attachmentId)
+  return file ? { bytes: file.bytes, mimeType: file.mimeType } : null
+}
+
+/** Renders a billing document as it should print now (no storage). */
+export async function renderBillingDocument(
+  em: EntityManager,
+  invoice: BillingInvoice,
+  deps: { loadTranslator?: TranslatorLoader } = {},
+): Promise<Uint8Array> {
+  const scope = { tenantId: invoice.tenantId, organizationId: invoice.organizationId }
+  const lines = await em.find(
+    BillingInvoiceLine,
+    { invoiceId: invoice.id, ...scope, deletedAt: null } as never,
+    { orderBy: { lineNumber: 'asc' } as never },
+  )
+  const { seller, buyer } = await resolveParties(em, invoice)
+  const language = str(buyer.invoice_language) ?? DEFAULT_INVOICE_LANGUAGE
+  const translate = await (deps.loadTranslator ?? loadDocumentTranslator)(language)
+
+  let correctsNumber: string | null = null
+  if (invoice.correctsInvoiceId) {
+    const corrected = await em.findOne(BillingInvoice, { id: invoice.correctsInvoiceId, ...scope } as never)
+    correctsNumber = corrected?.number ?? null
+  }
+
+  const model = buildInvoiceDocumentModel({
+    invoice: {
+      number: invoice.number,
+      documentType: invoice.documentType as 'invoice' | 'credit_memo' | 'debit_memo' | 'receipt',
+      status: invoice.status,
+      testRun: invoice.testRun,
+      issueDate: invoice.issueDate ?? null,
+      dueDate: invoice.dueDate ?? null,
+      billDate: invoice.billDate ?? null,
+      periodStart: invoice.periodStart ?? null,
+      periodEnd: invoice.periodEnd ?? null,
+      currencyCode: invoice.currencyCode,
+      subtotalNet: invoice.subtotalNet,
+      taxTotal: invoice.taxTotal,
+      totalGross: invoice.totalGross,
+      correctsNumber: invoice.correctsInvoiceNumber ?? correctsNumber,
+      correctsIssueDate: invoice.correctsIssueDate ?? null,
+      correctionReason: invoice.correctionReason ?? null,
+    },
+    lines: lines.map((line) => ({
+      description: line.description,
+      quantity: line.quantity,
+      unitPriceNet: line.unitPriceNet,
+      taxRate: line.taxRate,
+      netAmount: line.netAmount,
+      taxAmount: line.taxAmount,
+      grossAmount: line.grossAmount,
+      servicePeriodStart: line.servicePeriodStart ?? null,
+      servicePeriodEnd: line.servicePeriodEnd ?? null,
+    })),
+    seller: {
+      legalName: str(seller.legal_name),
+      address: address(seller.address),
+      taxId: str(seller.tax_id),
+      bankName: str(seller.bank_name),
+      iban: str(seller.iban),
+      bic: str(seller.bic),
+      footer: str(seller.invoice_footer),
+    },
+    buyer: {
+      name: str(buyer.name) ?? '',
+      address: address(buyer.invoice_address),
+      taxId: str(buyer.tax_id),
+    },
+    language,
+    translate,
+  })
+  return renderInvoicePdf(model, { logo: await resolveLogo(em, invoice, seller) })
+}
+
+/**
+ * Renders and stores the PDF of a posted document once. Idempotent: returns
+ * the existing attachment id when already frozen. The column is claimed with
+ * a conditional update, so concurrent freezes never overwrite each other.
+ */
+export async function freezeInvoicePdf(
+  em: EntityManager,
+  invoice: BillingInvoice,
+  deps: { loadTranslator?: TranslatorLoader } = {},
+): Promise<{ attachmentId: string; bytes: Uint8Array | null }> {
+  if (invoice.pdfAttachmentId) return { attachmentId: invoice.pdfAttachmentId, bytes: null }
+  if (!isFrozenDocument(invoice)) throw new Error('Only posted, non-test documents are frozen')
+  const bytes = await renderBillingDocument(em, invoice, deps)
+  const scope = { tenantId: invoice.tenantId, organizationId: invoice.organizationId }
+  const attachmentId = await storeAttachment(em, scope, {
+    entityId: billingEntityIds.invoice,
+    recordId: invoice.id,
+    fileName: pdfFileName(invoice),
+    mimeType: 'application/pdf',
+    bytes,
+  })
+  await em.nativeUpdate(
+    BillingInvoice,
+    { id: invoice.id, ...scope, pdfAttachmentId: null } as never,
+    { pdfAttachmentId: attachmentId } as never,
+  )
+  invoice.pdfAttachmentId = attachmentId
+  return { attachmentId, bytes }
+}
+
+/**
+ * The PDF to serve / attach: the frozen file for posted documents (frozen
+ * now if it never was), a live watermarked render for drafts and tests.
+ */
+export async function getInvoicePdf(
+  em: EntityManager,
+  invoice: BillingInvoice,
+  deps: { loadTranslator?: TranslatorLoader } = {},
+): Promise<{ bytes: Uint8Array; fileName: string; frozen: boolean }> {
+  const fileName = pdfFileName(invoice)
+  if (!isFrozenDocument(invoice)) {
+    return { bytes: await renderBillingDocument(em, invoice, deps), fileName, frozen: false }
+  }
+  if (invoice.pdfAttachmentId) {
+    const stored = await readAttachment(
+      em,
+      { tenantId: invoice.tenantId, organizationId: invoice.organizationId },
+      invoice.pdfAttachmentId,
+    )
+    if (stored) return { bytes: stored.bytes, fileName, frozen: true }
+    // Stored file lost (storage moved / purged): serve a fresh render from
+    // the frozen snapshots rather than failing; the attachment id is kept.
+    console.warn('[billing.pdf] frozen PDF unreadable, rendering from snapshots', invoice.id)
+    return { bytes: await renderBillingDocument(em, invoice, deps), fileName, frozen: true }
+  }
+  const frozen = await freezeInvoicePdf(em, invoice, deps)
+  return {
+    bytes: frozen.bytes ?? (await renderBillingDocument(em, invoice, deps)),
+    fileName,
+    frozen: true,
+  }
+}

package/src/modules/billing/lib/pdf/invoiceTemplate.ts

@@ -0,0 +1,338 @@
+import { PDFDocument, degrees, rgb, type PDFFont, type PDFImage, type PDFPage } from 'pdf-lib'
+import fontkit from '@pdf-lib/fontkit'
+import { NOTO_SANS_BOLD_BASE64, NOTO_SANS_REGULAR_BASE64 } from './fonts/embeddedFonts'
+import type { InvoiceDocumentModel } from './invoiceModel'
+
+/**
+ * Built-in A4 invoice template (Spec B) — lays out an `InvoiceDocumentModel`
+ * with pdf-lib and an embedded Unicode font (Noto Sans subset, so Polish
+ * diacritics render — the standard Helvetica font cannot).
+ *
+ * Layout: logo + title | seller / buyer blocks | meta rows | lines table
+ * (wrapped descriptions, header repeated on every page) | VAT summary |
+ * totals | payment instructions | footer | "Page n of m" | optional
+ * diagonal watermark (DRAFT / TEST). Characters the subset font lacks are
+ * replaced with "?" so rendering never throws on exotic customer text.
+ */
+
+export type PdfLogo = { bytes: Uint8Array; mimeType: string }
+
+const PAGE_WIDTH = 595.28
+const PAGE_HEIGHT = 841.89
+const MARGIN = 40
+const CONTENT_WIDTH = PAGE_WIDTH - 2 * MARGIN
+const FOOTER_HEIGHT = 48
+const BODY_SIZE = 9
+const SMALL_SIZE = 8
+const LINE_GAP = 3
+
+// # | description | qty | unit net | VAT % | net | VAT | gross  (sums to CONTENT_WIDTH)
+const TABLE_COLUMNS = [24, 179, 30, 62, 36, 62, 56, 66.28]
+
+const TEXT = rgb(0.12, 0.12, 0.14)
+const MUTED = rgb(0.42, 0.42, 0.46)
+const RULE = rgb(0.82, 0.82, 0.85)
+const HEADER_FILL = rgb(0.95, 0.95, 0.96)
+const WATERMARK = rgb(0.85, 0.85, 0.87)
+
+type Fonts = { regular: PDFFont; bold: PDFFont; charset: Set<number> }
+
+function base64ToBytes(value: string): Uint8Array {
+  return Uint8Array.from(Buffer.from(value, 'base64'))
+}
+
+/** Replaces characters the embedded subset cannot draw. */
+export function sanitizeForFont(text: string, charset: Set<number>): string {
+  let out = ''
+  for (const char of text.replace(/\t/g, ' ')) {
+    const code = char.codePointAt(0) ?? 63
+    out += code === 10 || charset.has(code) ? char : '?'
+  }
+  return out
+}
+
+function wrap(text: string, font: PDFFont, size: number, width: number): string[] {
+  const lines: string[] = []
+  for (const paragraph of text.split('\n')) {
+    let current = ''
+    for (const word of paragraph.split(/\s+/).filter(Boolean)) {
+      const candidate = current ? `${current} ${word}` : word
+      if (font.widthOfTextAtSize(candidate, size) <= width) {
+        current = candidate
+        continue
+      }
+      if (current) lines.push(current)
+      // A single word wider than the column is split by characters.
+      let chunk = ''
+      for (const char of word) {
+        if (font.widthOfTextAtSize(chunk + char, size) > width && chunk) {
+          lines.push(chunk)
+          chunk = char
+        } else {
+          chunk += char
+        }
+      }
+      current = chunk
+    }
+    lines.push(current)
+  }
+  return lines
+}
+
+class Layout {
+  readonly pages: PDFPage[] = []
+  page!: PDFPage
+  y = 0
+
+  constructor(
+    private readonly doc: PDFDocument,
+    private readonly fonts: Fonts,
+  ) {
+    this.newPage()
+  }
+
+  get boldFont(): PDFFont {
+    return this.fonts.bold
+  }
+
+  newPage(): void {
+    this.page = this.doc.addPage([PAGE_WIDTH, PAGE_HEIGHT])
+    this.pages.push(this.page)
+    this.y = PAGE_HEIGHT - MARGIN
+  }
+
+  /** Starts a new page when fewer than `height` points remain above the footer. */
+  ensure(height: number): boolean {
+    if (this.y - height < MARGIN + FOOTER_HEIGHT) {
+      this.newPage()
+      return true
+    }
+    return false
+  }
+
+  text(value: string, x: number, opts: { size?: number; bold?: boolean; color?: ReturnType<typeof rgb>; y?: number } = {}) {
+    const size = opts.size ?? BODY_SIZE
+    this.page.drawText(sanitizeForFont(value, this.fonts.charset), {
+      x,
+      y: opts.y ?? this.y,
+      size,
+      font: opts.bold ? this.fonts.bold : this.fonts.regular,
+      color: opts.color ?? TEXT,
+    })
+  }
+
+  width(value: string, size: number, bold = false): number {
+    return (bold ? this.fonts.bold : this.fonts.regular).widthOfTextAtSize(sanitizeForFont(value, this.fonts.charset), size)
+  }
+
+  rule(y = this.y): void {
+    this.page.drawLine({ start: { x: MARGIN, y }, end: { x: PAGE_WIDTH - MARGIN, y }, thickness: 0.5, color: RULE })
+  }
+}
+
+function drawTableHeader(layout: Layout, headers: string[], align: Array<'left' | 'right'>, columns: number[], x0 = MARGIN) {
+  // Headers wrap inside their column (Polish labels are long: "Cena netto").
+  const wrapped = headers.map((header, i) => wrap(header, layout.boldFont, SMALL_SIZE, columns[i] - 6))
+  const lineHeight = SMALL_SIZE + 2
+  const height = Math.max(...wrapped.map((lines) => lines.length)) * lineHeight + 8
+  const total = columns.reduce((sum, w) => sum + w, 0)
+  layout.page.drawRectangle({ x: x0, y: layout.y - height + 4, width: total, height, color: HEADER_FILL })
+  let x = x0
+  wrapped.forEach((lines, i) => {
+    const w = columns[i]
+    lines.forEach((line, li) => {
+      const tx = align[i] === 'right' ? x + w - 3 - layout.width(line, SMALL_SIZE, true) : x + 3
+      layout.text(line, tx, { size: SMALL_SIZE, bold: true, y: layout.y - SMALL_SIZE - 1 - li * lineHeight })
+    })
+    x += w
+  })
+  layout.y -= height + 2
+}
+
+function drawRows(
+  layout: Layout,
+  rows: string[][],
+  headers: string[],
+  align: Array<'left' | 'right'>,
+  columns: number[],
+  fonts: Fonts,
+  x0 = MARGIN,
+) {
+  const lineHeight = BODY_SIZE + LINE_GAP
+  for (const row of rows) {
+    const cells = row.map((cell, i) =>
+      wrap(sanitizeForFont(cell, fonts.charset), fonts.regular, BODY_SIZE, columns[i] - 6),
+    )
+    const rowHeight = Math.max(...cells.map((c) => c.length)) * lineHeight + 4
+    if (layout.ensure(rowHeight)) drawTableHeader(layout, headers, align, columns, x0)
+    let x = x0
+    cells.forEach((cellLines, i) => {
+      const w = columns[i]
+      cellLines.forEach((line, li) => {
+        const tx = align[i] === 'right' ? x + w - 3 - layout.width(line, BODY_SIZE) : x + 3
+        layout.text(line, tx, { y: layout.y - BODY_SIZE - li * lineHeight })
+      })
+      x += w
+    })
+    layout.y -= rowHeight
+    layout.page.drawLine({
+      start: { x: x0, y: layout.y + 1 },
+      end: { x: x0 + columns.reduce((s, w) => s + w, 0), y: layout.y + 1 },
+      thickness: 0.3,
+      color: RULE,
+    })
+  }
+}
+
+function drawBlock(layout: Layout, heading: string, lines: string[], x: number, width: number, top: number, fonts: Fonts): number {
+  let y = top
+  layout.text(heading.toUpperCase(), x, { size: SMALL_SIZE, bold: true, color: MUTED, y })
+  y -= SMALL_SIZE + 6
+  lines.forEach((line, index) => {
+    for (const part of wrap(sanitizeForFont(line, fonts.charset), index === 0 ? fonts.bold : fonts.regular, BODY_SIZE, width)) {
+      layout.text(part, x, { bold: index === 0, y })
+      y -= BODY_SIZE + LINE_GAP
+    }
+  })
+  return y
+}
+
+async function embedLogo(doc: PDFDocument, logo: PdfLogo | null | undefined): Promise<PDFImage | null> {
+  if (!logo) return null
+  try {
+    if (logo.mimeType === 'image/png') return await doc.embedPng(logo.bytes)
+    if (logo.mimeType === 'image/jpeg' || logo.mimeType === 'image/jpg') return await doc.embedJpg(logo.bytes)
+  } catch (err) {
+    console.warn('[billing.pdf] logo could not be embedded', err)
+  }
+  return null
+}
+
+export async function renderInvoicePdf(model: InvoiceDocumentModel, opts: { logo?: PdfLogo | null } = {}): Promise<Uint8Array> {
+  const doc = await PDFDocument.create()
+  doc.registerFontkit(fontkit)
+  // subset: false — the fonts are already subset at build time, and pdf-lib's
+  // own subsetting drops kerning on some glyph runs.
+  const regular = await doc.embedFont(base64ToBytes(NOTO_SANS_REGULAR_BASE64), { subset: false })
+  const bold = await doc.embedFont(base64ToBytes(NOTO_SANS_BOLD_BASE64), { subset: false })
+  const fonts: Fonts = { regular, bold, charset: new Set(regular.getCharacterSet()) }
+  doc.setTitle(sanitizeForFont(`${model.title} ${model.number}`, fonts.charset))
+  doc.setLanguage(model.language)
+  doc.setProducer('Dainamite Billing')
+
+  const layout = new Layout(doc, fonts)
+
+  // ── Header: logo left, title + number right ──
+  const logo = await embedLogo(doc, opts.logo)
+  if (logo) {
+    const scale = Math.min(140 / logo.width, 48 / logo.height, 1)
+    layout.page.drawImage(logo, {
+      x: MARGIN,
+      y: layout.y - logo.height * scale,
+      width: logo.width * scale,
+      height: logo.height * scale,
+    })
+  }
+  const titleSize = 18
+  layout.text(model.title, PAGE_WIDTH - MARGIN - layout.width(model.title, titleSize, true), {
+    size: titleSize,
+    bold: true,
+    y: layout.y - titleSize,
+  })
+  layout.text(model.number, PAGE_WIDTH - MARGIN - layout.width(model.number, 11), {
+    size: 11,
+    color: MUTED,
+    y: layout.y - titleSize - 16,
+  })
+  layout.y -= 64
+
+  // ── Meta rows (right-aligned key: value list) ──
+  for (const [label, value] of model.meta) {
+    const text = `${label}: ${value}`
+    layout.text(text, PAGE_WIDTH - MARGIN - layout.width(text, BODY_SIZE), { y: layout.y })
+    layout.y -= BODY_SIZE + LINE_GAP
+  }
+  layout.y -= 10
+
+  // ── Seller | Buyer ──
+  const half = CONTENT_WIDTH / 2 - 10
+  const top = layout.y
+  const sellerBottom = drawBlock(layout, model.seller.heading, model.seller.lines, MARGIN, half, top, fonts)
+  const buyerBottom = drawBlock(layout, model.buyer.heading, model.buyer.lines, MARGIN + half + 20, half, top, fonts)
+  layout.y = Math.min(sellerBottom, buyerBottom) - 14
+
+  // ── Lines ──
+  layout.ensure(40)
+  drawTableHeader(layout, model.table.headers, model.table.align, TABLE_COLUMNS)
+  drawRows(layout, model.table.rows, model.table.headers, model.table.align, TABLE_COLUMNS, fonts)
+  layout.y -= 14
+
+  // ── VAT summary (right half) + totals ──
+  const summaryColumns = [60, 75, 70, 85]
+  const summaryX = PAGE_WIDTH - MARGIN - summaryColumns.reduce((s, w) => s + w, 0)
+  layout.ensure(SMALL_SIZE + 30 + model.vatSummary.rows.length * (BODY_SIZE + 7))
+  layout.text(model.vatSummary.heading, summaryX, { size: SMALL_SIZE, bold: true, color: MUTED })
+  layout.y -= SMALL_SIZE + 4
+  const summaryAlign: Array<'left' | 'right'> = ['right', 'right', 'right', 'right']
+  drawTableHeader(layout, model.vatSummary.headers, summaryAlign, summaryColumns, summaryX)
+  drawRows(layout, model.vatSummary.rows, model.vatSummary.headers, summaryAlign, summaryColumns, fonts, summaryX)
+  layout.y -= 10
+
+  layout.ensure(model.totals.length * 16 + 10)
+  model.totals.forEach(([label, value], index) => {
+    const last = index === model.totals.length - 1
+    const size = last ? 12 : BODY_SIZE + 1
+    layout.text(value, PAGE_WIDTH - MARGIN - layout.width(value, size, last), { size, bold: last })
+    layout.text(label, summaryX, { size, bold: last, color: last ? TEXT : MUTED })
+    layout.y -= size + 6
+  })
+  layout.y -= 10
+
+  // ── Payment instructions ──
+  if (model.payment) {
+    layout.ensure((model.payment.lines.length + 1) * (BODY_SIZE + LINE_GAP) + 16)
+    layout.rule(layout.y + 4)
+    layout.y -= 10
+    layout.text(model.payment.heading.toUpperCase(), MARGIN, { size: SMALL_SIZE, bold: true, color: MUTED })
+    layout.y -= SMALL_SIZE + 6
+    for (const line of model.payment.lines) {
+      layout.text(line, MARGIN)
+      layout.y -= BODY_SIZE + LINE_GAP
+    }
+  }
+
+  // ── Footer, page numbers, watermark on every page ──
+  const pages = layout.pages
+  pages.forEach((page, index) => {
+    layout.page = page
+    let fy = MARGIN + FOOTER_HEIGHT - 14
+    for (const line of model.footer.slice(0, 3)) {
+      for (const part of wrap(sanitizeForFont(line, fonts.charset), regular, SMALL_SIZE - 1, CONTENT_WIDTH - 90).slice(0, 2)) {
+        layout.text(part, MARGIN, { size: SMALL_SIZE - 1, color: MUTED, y: fy })
+        fy -= SMALL_SIZE + 1
+      }
+    }
+    const pageText = model.pageLabel(index + 1, pages.length)
+    layout.text(pageText, PAGE_WIDTH - MARGIN - layout.width(pageText, SMALL_SIZE), {
+      size: SMALL_SIZE,
+      color: MUTED,
+      y: MARGIN,
+    })
+    if (model.watermark) {
+      const size = 96
+      const text = sanitizeForFont(model.watermark, fonts.charset)
+      const w = bold.widthOfTextAtSize(text, size)
+      page.drawText(text, {
+        x: PAGE_WIDTH / 2 - (w / 2) * Math.cos(Math.PI / 4),
+        y: PAGE_HEIGHT / 2 - (w / 2) * Math.sin(Math.PI / 4),
+        size,
+        font: bold,
+        color: WATERMARK,
+        rotate: degrees(45),
+        opacity: 0.5,
+      })
+    }
+  })
+
+  return doc.save()
+}

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

@@ -1,58 +1,49 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
-import { ModuleConfig } from '@open-mercato/core/modules/configs/data/entities'
+import { getBillingSettings, receiptTaxRate, type SettingsScope } from './billingSettings'
 
 /**
- * Typed readers for the prepaid billing module configs (SPEC-002), seeded by
- * `setup.ts → seedBillingConfigs`. Stored as raw JSON scalars in
- * `ModuleConfig.valueJson`. Each reader falls back to the same default the
- * seed uses, so a missing row (older tenant) behaves identically.
+ * Typed readers for the prepaid billing settings (SPEC-002), stored per
+ * organization in `billing_settings` (Spec 0, E-D2 — previously tenant-wide
+ * core `configs` rows). Every reader takes the organization scope; the
+ * defaults are identical to the old config seed, so behaviour is unchanged.
  */
 
-async function readConfig(em: EntityManager, name: string): Promise<unknown> {
-  const row = await em.findOne(ModuleConfig, { moduleId: 'billing', name })
-  if (!row) return undefined
-  return row.valueJson as unknown
-}
-
 function asNumberString(value: unknown, fallback: string): string {
   if (value === null || value === undefined) return fallback
   if (typeof value === 'number' && Number.isFinite(value)) return String(value)
   if (typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value))) {
-    return value.trim()
+    return String(Number(value))
   }
   return fallback
 }
 
-/** `prepaid.low_balance_threshold_default` — numeric string (default '0'). */
-export async function getLowBalanceThresholdDefault(em: EntityManager): Promise<string> {
-  return asNumberString(await readConfig(em, 'prepaid.low_balance_threshold_default'), '0')
+/** Low-balance threshold default — numeric string (default '0'). */
+export async function getLowBalanceThresholdDefault(em: EntityManager, scope: SettingsScope): Promise<string> {
+  return asNumberString((await getBillingSettings(em, scope)).lowBalanceThresholdDefault, '0')
+}
+
+/** Near-credit-limit buffer default — numeric string (default '0'). */
+export async function getNearLimitBufferDefault(em: EntityManager, scope: SettingsScope): Promise<string> {
+  return asNumberString((await getBillingSettings(em, scope)).nearLimitBufferDefault, '0')
 }
 
-/** `credit.near_limit_buffer_default` — numeric string (default '0'). */
-export async function getNearLimitBufferDefault(em: EntityManager): Promise<string> {
-  return asNumberString(await readConfig(em, 'credit.near_limit_buffer_default'), '0')
+/** Gateway provider key for top-ups (default 'stripe'). */
+export async function getTopupProvider(em: EntityManager, scope: SettingsScope): Promise<string> {
+  const value = (await getBillingSettings(em, scope)).topupProvider
+  return typeof value === 'string' && value.trim() ? value.trim() : 'stripe'
 }
 
-/** `prepaid.topup_provider` — gateway provider key (default 'stripe'). */
-export async function getTopupProvider(em: EntityManager): Promise<string> {
-  const value = await readConfig(em, 'prepaid.topup_provider')
-  return typeof value === 'string' && value.trim() !== '' ? value.trim() : 'stripe'
+/** Consumption statements master switch (default true). */
+export async function getStatementEnabled(em: EntityManager, scope: SettingsScope): Promise<boolean> {
+  return (await getBillingSettings(em, scope)).statementEnabled !== false
 }
 
-/** `prepaid.statement_enabled` — master switch (default true). */
-export async function getStatementEnabled(em: EntityManager): Promise<boolean> {
-  const value = await readConfig(em, 'prepaid.statement_enabled')
-  if (value === undefined || value === null) return true
-  if (typeof value === 'boolean') return value
-  // A stored string "false" must read as false (Boolean("false") === true).
-  if (typeof value === 'string') return value.trim().toLowerCase() !== 'false'
-  return Boolean(value)
+/** VAT percent on top-up receipts (default 0; always 0 when tax is charged at consumption). */
+export async function getTopupTaxRate(em: EntityManager, scope: SettingsScope): Promise<number> {
+  return receiptTaxRate(await getBillingSettings(em, scope))
 }
 
-/** `prepaid.topup_tax_rate` — VAT percent on top-up receipts (default 0). */
-export async function getTopupTaxRate(em: EntityManager): Promise<number> {
-  const value = await readConfig(em, 'prepaid.topup_tax_rate')
-  if (typeof value === 'number' && Number.isFinite(value)) return value
-  if (typeof value === 'string' && Number.isFinite(Number(value))) return Number(value)
-  return 0
+/** Where prepaid VAT is charged (Spec F, F-D3). Default `topup`. */
+export async function getPrepaidTaxPoint(em: EntityManager, scope: SettingsScope): Promise<'topup' | 'consumption'> {
+  return (await getBillingSettings(em, scope)).prepaidTaxPoint === 'consumption' ? 'consumption' : 'topup'
 }