@dainamite/billing 0.19.0 → 0.21.0

package/src/modules/billing/__tests__/package-isolation.test.ts

@@ -15,10 +15,10 @@ import { metadata } from '../index'
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..')
 
-// Must mirror peerDependencies in packages/billing/package.json (plus
-// relatives + node builtins). Adding a prefix here without adding it to
-// peerDependencies = silent runtime failure for consumers that don't have
-// the dep transitively.
+// Must mirror peerDependencies + dependencies in packages/billing/package.json
+// (plus relatives + node builtins). Adding a prefix here without adding it to
+// package.json = silent runtime failure for consumers that don't have the dep
+// transitively. `pdf-lib` / `@pdf-lib/` are regular dependencies (Spec B PDF).
 const ALLOWED_IMPORT_PREFIXES = [
   './',
   '../',
@@ -36,6 +36,8 @@ const ALLOWED_IMPORT_PREFIXES = [
   '@dainamite/',
   'node:',
   '@tanstack/',
+  'pdf-lib',
+  '@pdf-lib/',
 ]
 
 const NODE_BUILTINS = new Set([
@@ -128,10 +130,22 @@ describe('@dainamite/billing package isolation', () => {
     }
   })
 
-  it('declares all required modules in metadata.requires', () => {
-    expect(metadata.requires).toEqual(
-      expect.arrayContaining(['auth', 'directory', 'dictionaries', 'configs', 'sales']),
-    )
+  it('requires only platform modules (Spec 0: no core business modules; Spec B: attachments)', () => {
+    expect(metadata.requires).toEqual(['auth', 'directory', 'attachments'])
+  })
+
+  it('never imports core sales / configs / dictionaries / payment_gateways (Spec 0)', () => {
+    const banned = new Set(['sales', 'configs', 'dictionaries', 'payment_gateways'])
+    const violations: string[] = []
+    for (const [file, specs] of importsByFile) {
+      for (const spec of specs) {
+        const subModule = extractCoreModuleSubpath(spec)
+        if (subModule && banned.has(subModule)) violations.push(`  ${path.relative(PACKAGE_ROOT, file)} → ${spec}`)
+      }
+    }
+    if (violations.length > 0) {
+      throw new Error(`Billing must not depend on core business modules:\n${violations.join('\n')}`)
+    }
   })
 
   it('does not import from sibling app modules', () => {

package/src/modules/billing/__tests__/setup.test.ts

@@ -16,9 +16,17 @@ import setup from '../setup'
 const featureIds = new Set<string>(features.map((f) => f.id))
 
 describe('billing setup — contract', () => {
-  it('exports onTenantCreated and seedDefaults hooks', () => {
-    expect(typeof setup.onTenantCreated).toBe('function')
+  it('exports a seedDefaults hook (billing settings) and no core-config tenant hook', () => {
     expect(typeof setup.seedDefaults).toBe('function')
+    expect(setup.onTenantCreated).toBeUndefined()
+  })
+
+  it('seedDefaults warms up the organization billing settings row', async () => {
+    const row = { id: 's-1' }
+    const em = { findOne: jest.fn(async () => row), execute: jest.fn() }
+    await setup.seedDefaults!({ em, tenantId: 't-1', organizationId: 'o-1' } as never)
+    expect(em.findOne).toHaveBeenCalledTimes(1)
+    expect(em.execute).not.toHaveBeenCalled()
   })
 
   it('does not declare seedExamples (billing ships no demo data)', () => {
@@ -77,8 +85,8 @@ describe('billing setup — contract', () => {
 })
 
 describe('billing acl — surface', () => {
-  it('exports exactly 19 features (12 Phase 0 + 7 SPEC-002 prepaid)', () => {
-    expect(features).toHaveLength(19)
+  it('exports exactly 27 features (12 Phase 0 + 7 SPEC-002 prepaid + 2 Spec 0 settings + 1 Spec B send + 3 Spec C payments + 1 Spec D memos + 1 Spec F run delete)', () => {
+    expect(features).toHaveLength(27)
   })
 
   it('all feature IDs are prefixed `billing.` (no leaking module boundary)', () => {
@@ -98,6 +106,7 @@ describe('billing acl — surface', () => {
     'billing.run.trigger',
     'billing.run.dry_run',
     'billing.run.view',
+    'billing.run.delete',
     'billing.invoice.post',
     'billing.invoice.edit_draft',
     'billing.invoice.view',

package/src/modules/billing/__tests__/validators.test.ts

@@ -20,6 +20,7 @@ import {
   rateJsonUsageVolume,
   validateRateJson,
 } from '../data/validators'
+import { DEFAULT_INVOICE_LANGUAGE, SUPPORTED_INVOICE_LANGUAGES } from '../lib/invoiceLanguages'
 
 describe('rate_json — one_time', () => {
   it('accepts a positive amount', () => {
@@ -293,9 +294,6 @@ describe('exported enums', () => {
     ])
   })
 
-  it('INVOICE_STATUSES matches the dictionary entries seeded by setup', () => {
-    expect([...INVOICE_STATUSES]).toEqual(['draft', 'posted', 'paid', 'void'])
-  })
 })
 
 // ─── Phase 1 — CRUD payload schemas ────────────────────────────────
@@ -304,6 +302,11 @@ import {
   billingAccountCreateSchema,
   billingAccountListQuerySchema,
   billingAccountUpdateSchema,
+  billingItemBulkCreateSchema,
+  billingRunTriggerSchema,
+  CHARGE_TIMING_RECURRING_ONLY_MESSAGE,
+  billingInvoiceListQuerySchema,
+  billingSettingsUpdateSchema,
   billingItemCreateSchema,
   billingItemListQuerySchema,
   billingItemUpdateSchema,
@@ -367,6 +370,45 @@ describe('billingAccountCreateSchema', () => {
     expect(() => billingAccountCreateSchema.parse(withoutTenant)).toThrow()
     void tenantId
   })
+  // Spec E — B2C accounts + invoice-language picklist.
+  it('defaults customerKind to company', () => {
+    expect(billingAccountCreateSchema.parse(validAccountCreate).customerKind).toBe('company')
+  })
+
+  it('accepts customerKind person', () => {
+    const parsed = billingAccountCreateSchema.parse({ ...validAccountCreate, customerKind: 'person' })
+    expect(parsed.customerKind).toBe('person')
+  })
+
+  it('rejects an unknown customerKind', () => {
+    expect(() =>
+      billingAccountCreateSchema.parse({ ...validAccountCreate, customerKind: 'household' }),
+    ).toThrow()
+  })
+
+  it('accepts every template-supported invoice language, case/space tolerant', () => {
+    for (const { code } of SUPPORTED_INVOICE_LANGUAGES) {
+      const parsed = billingAccountCreateSchema.parse({
+        ...validAccountCreate,
+        invoiceLanguage: ` ${code.toUpperCase()} `,
+      })
+      expect(parsed.invoiceLanguage).toBe(code)
+    }
+  })
+
+  it('rejects an invoice language the template does not support', () => {
+    expect(() =>
+      billingAccountCreateSchema.parse({ ...validAccountCreate, invoiceLanguage: 'de' }),
+    ).toThrow()
+  })
+
+  it('defaults invoiceLanguage when omitted', () => {
+    const { invoiceLanguage, ...withoutLanguage } = validAccountCreate
+    void invoiceLanguage
+    expect(billingAccountCreateSchema.parse(withoutLanguage).invoiceLanguage).toBe(
+      DEFAULT_INVOICE_LANGUAGE,
+    )
+  })
 })
 
 describe('billingAccountUpdateSchema', () => {
@@ -397,6 +439,16 @@ describe('billingAccountUpdateSchema', () => {
   it('does not declare customerId (immutable per spec)', () => {
     expect('customerId' in billingAccountUpdateSchema.shape).toBe(false)
   })
+
+  it('does not declare customerKind (immutable per spec)', () => {
+    expect('customerKind' in billingAccountUpdateSchema.shape).toBe(false)
+  })
+
+  it('validates invoiceLanguage against supported languages', () => {
+    const base = { tenantId: TENANT, organizationId: ORG, id: ACCOUNT }
+    expect(billingAccountUpdateSchema.parse({ ...base, invoiceLanguage: 'PL' }).invoiceLanguage).toBe('pl')
+    expect(() => billingAccountUpdateSchema.parse({ ...base, invoiceLanguage: 'fr' })).toThrow()
+  })
 })
 
 describe('billingAccountListQuerySchema', () => {
@@ -415,6 +467,11 @@ describe('billingAccountListQuerySchema', () => {
     expect(parsed.page).toBe(1)
     expect(parsed.pageSize).toBe(50)
   })
+
+  it('accepts a customerKind filter and rejects unknown kinds', () => {
+    expect(billingAccountListQuerySchema.parse({ customerKind: 'person' }).customerKind).toBe('person')
+    expect(() => billingAccountListQuerySchema.parse({ customerKind: 'robot' })).toThrow()
+  })
 })
 
 const validItemRecurring = {
@@ -592,3 +649,136 @@ describe('billingUsageListQuerySchema', () => {
     expect(() => billingUsageListQuerySchema.parse({ pageSize: '101' })).toThrow()
   })
 })
+
+// ─── Spec A — charge timing, proration, no catch-up flag ─────────
+
+describe('Spec A validators', () => {
+  const recurring = {
+    tenantId: TENANT,
+    organizationId: ORG,
+    billAccountId: ACCOUNT,
+    type: 'recurring' as const,
+    billStartDate: '2026-11-14',
+    description: 'Internet 300',
+    rateJson: { unit_price: 79 },
+  }
+
+  it('accepts chargeTiming / prorate on recurring items and leaves defaults to the command', () => {
+    expect(billingItemCreateSchema.parse(recurring)).not.toHaveProperty('chargeTiming')
+    const parsed = billingItemCreateSchema.parse({ ...recurring, chargeTiming: 'in_arrears', prorate: false })
+    expect(parsed).toMatchObject({ chargeTiming: 'in_arrears', prorate: false })
+  })
+
+  it('rejects an unknown charge timing', () => {
+    expect(() => billingItemCreateSchema.parse({ ...recurring, chargeTiming: 'whenever' })).toThrow()
+  })
+
+  it('rejects non-default timing / proration on non-recurring items', () => {
+    const oneTime = { ...recurring, type: 'one_time' as const, rateJson: { amount: 10 } }
+    expect(billingItemCreateSchema.parse({ ...oneTime, chargeTiming: 'in_advance', prorate: true })).toBeTruthy()
+    expect(() => billingItemCreateSchema.parse({ ...oneTime, chargeTiming: 'in_arrears' })).toThrow(
+      CHARGE_TIMING_RECURRING_ONLY_MESSAGE,
+    )
+    expect(() => billingItemCreateSchema.parse({ ...oneTime, prorate: false })).toThrow(
+      CHARGE_TIMING_RECURRING_ONLY_MESSAGE,
+    )
+  })
+
+  it('applies the same rule to bulk entries and allows both on update', () => {
+    const { tenantId, organizationId, ...entry } = recurring
+    expect(() =>
+      billingItemBulkCreateSchema.parse({
+        tenantId,
+        organizationId,
+        items: [{ ...entry, type: 'usage', uomCode: 'gb', rateJson: { unit_price: 1 }, prorate: false }],
+      }),
+    ).toThrow()
+    expect(
+      billingItemUpdateSchema.parse({ tenantId, organizationId, id: ACCOUNT, chargeTiming: 'in_arrears', prorate: false }),
+    ).toMatchObject({ chargeTiming: 'in_arrears', prorate: false })
+  })
+
+  it('strips a legacy catchUp flag from the run trigger', () => {
+    const parsed = billingRunTriggerSchema.parse({ tenantId: TENANT, organizationId: ORG, catchUp: true })
+    expect(parsed).not.toHaveProperty('catchUp')
+    expect(parsed.mode).toBe('real')
+  })
+})
+
+// ─── Spec 0 — ledger validators ──────────────────────────────────
+
+describe('Spec 0 validators', () => {
+  it('invoice statuses drop void and add partially_paid / credited', () => {
+    expect(INVOICE_STATUSES).toEqual(['draft', 'posted', 'partially_paid', 'paid', 'credited'])
+  })
+
+  it('parses testRun literally (false stays false)', () => {
+    expect(billingInvoiceListQuerySchema.parse({ testRun: 'false' }).testRun).toBe(false)
+    expect(billingInvoiceListQuerySchema.parse({ testRun: 'true' }).testRun).toBe(true)
+    expect(billingInvoiceListQuerySchema.parse({}).testRun).toBeUndefined()
+    expect(() => billingInvoiceListQuerySchema.parse({ status: 'void' })).toThrow()
+  })
+
+  it('validates number masks on settings update', () => {
+    const base = { tenantId: TENANT, organizationId: ORG }
+    expect(
+      billingSettingsUpdateSchema.parse({ ...base, numberMasks: { invoice: 'FV/{YYYY}/{SEQUENCE_NUM_YEAR:5}' } }).numberMasks,
+    ).toEqual({ invoice: 'FV/{YYYY}/{SEQUENCE_NUM_YEAR:5}' })
+    expect(() => billingSettingsUpdateSchema.parse({ ...base, numberMasks: { invoice: 'FV/{SEQUENCE_NUM_MONTH}' } })).toThrow(
+      'mask_month_scope_needs_year_and_month',
+    )
+    expect(() => billingSettingsUpdateSchema.parse({ ...base, numberMasks: { bogus: 'X{SEQUENCE_NUM}' } })).toThrow()
+    expect(() => billingSettingsUpdateSchema.parse({ ...base, topupTaxRate: 120 })).toThrow()
+  })
+})
+
+describe('Spec B validators', () => {
+  const base = { tenantId: TENANT, organizationId: ORG }
+  const item = {
+    ...base,
+    billAccountId: ACCOUNT,
+    type: 'recurring' as const,
+    billStartDate: '2026-11-14',
+    description: 'Internet 300',
+    rateJson: { unit_price: 79 },
+  }
+
+  it('item taxRate is optional on create (the command fills the default) and bounded 0–100', () => {
+    expect(billingItemCreateSchema.parse(item)).not.toHaveProperty('taxRate')
+    expect(billingItemCreateSchema.parse({ ...item, taxRate: '8' }).taxRate).toBe(8)
+    expect(() => billingItemCreateSchema.parse({ ...item, taxRate: -1 })).toThrow()
+    expect(() => billingItemCreateSchema.parse({ ...item, taxRate: 101 })).toThrow()
+  })
+
+  it('normalizes and checksum-validates the seller IBAN; empty clears it', () => {
+    expect(billingSettingsUpdateSchema.parse({ ...base, iban: 'pl61 1090 1014 0000 0712 1981 2874' }).iban).toBe(
+      'PL61109010140000071219812874',
+    )
+    expect(billingSettingsUpdateSchema.parse({ ...base, iban: '' }).iban).toBeNull()
+    expect(() => billingSettingsUpdateSchema.parse({ ...base, iban: 'PL61109010140000071219812875' })).toThrow(
+      'billing.settings.error.iban_invalid',
+    )
+    expect(() => billingSettingsUpdateSchema.parse({ ...base, bic: 'XX' })).toThrow('billing.settings.error.bic_invalid')
+  })
+
+  it('validates seller address, terms and default rate', () => {
+    const parsed = billingSettingsUpdateSchema.parse({
+      ...base,
+      legalName: '  Seller  ',
+      taxId: '',
+      sellerAddress: { line1: 'ul. A 1', city: 'Kraków', postal_code: '30-001', country: 'PL' },
+      defaultPaymentTermsDays: '30',
+      defaultTaxRate: 23,
+    })
+    expect(parsed).toMatchObject({ legalName: 'Seller', taxId: null, defaultPaymentTermsDays: 30, defaultTaxRate: 23 })
+    expect(() => billingSettingsUpdateSchema.parse({ ...base, sellerAddress: { line1: 'x' } })).toThrow()
+    expect(() => billingSettingsUpdateSchema.parse({ ...base, defaultPaymentTermsDays: 400 })).toThrow()
+  })
+
+  it('accepts overdue / due-date filters on the invoice list', () => {
+    const parsed = billingInvoiceListQuerySchema.parse({ overdue: 'true', dueFrom: '2026-11-01', dueTo: '2026-11-30' })
+    expect(parsed).toMatchObject({ overdue: true, dueFrom: '2026-11-01', dueTo: '2026-11-30' })
+    expect(() => billingInvoiceListQuerySchema.parse({ dueFrom: '01.11.2026' })).toThrow()
+  })
+})
+

package/src/modules/billing/acl.ts

@@ -8,9 +8,18 @@ export const features = [
   { id: 'billing.run.trigger', title: 'Trigger Bill Run', module: 'billing' },
   { id: 'billing.run.dry_run', title: 'Trigger Bill Run (dry-run)', module: 'billing' },
   { id: 'billing.run.view', title: 'View Bill Run History', module: 'billing' },
+  // Spec F — delete test / dry runs (real runs are never deleted)
+  { id: 'billing.run.delete', title: 'Delete Test / Dry Bill Runs', module: 'billing' },
   { id: 'billing.invoice.post', title: 'Post Draft Invoice', module: 'billing' },
   { id: 'billing.invoice.edit_draft', title: 'Edit Draft Invoice', module: 'billing' },
   { id: 'billing.invoice.view', title: 'View Billing Invoices', module: 'billing' },
+  { id: 'billing.invoice.send', title: 'Email Billing Invoices', module: 'billing' },
+  // Spec D — corrective documents
+  { id: 'billing.invoice.correct', title: 'Create Credit / Debit Memos', module: 'billing' },
+  // Spec C — payments
+  { id: 'billing.payment.view', title: 'View Billing Payments', module: 'billing' },
+  { id: 'billing.payment.manage', title: 'Manage Billing Payments (assign, allocate, ignore, convert)', module: 'billing' },
+  { id: 'billing.payment.import', title: 'Import Bank Payments (CSV)', module: 'billing' },
   // ─── Prepaid balance billing (SPEC-002) ──────────────────────
   { id: 'billing.balance.view', title: 'View Balance & Transactions', module: 'billing' },
   { id: 'billing.balance.adjust', title: 'Adjust Balance (manual credit/debit)', module: 'billing' },
@@ -19,6 +28,9 @@ export const features = [
   { id: 'billing.statement.view', title: 'View Consumption Statements', module: 'billing' },
   { id: 'billing.statement.generate', title: 'Generate Consumption Statement', module: 'billing' },
   { id: 'billing.credit.view', title: 'View Account Credit Status', module: 'billing' },
+  // ─── Billing settings (Spec 0) ───────────────────────────────
+  { id: 'billing.settings.view', title: 'View Billing Settings', module: 'billing' },
+  { id: 'billing.settings.manage', title: 'Manage Billing Settings', module: 'billing' },
 ] as const
 
 export default features

package/src/modules/billing/api/accounts/[id]/summary/route.ts

@@ -0,0 +1,62 @@
+import { NextResponse } from 'next/server'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { BillingAccount } from '../../../../data/entities'
+import { getAccountWorkspaceSummary } from '../../../../lib/accountSummary'
+
+/**
+ * `GET /api/billing/accounts/[id]/summary` — what the customer owes (Spec B
+ * AR summary; Spec E extends the same endpoint for the account workspace).
+ * One aggregate query; see `lib/accountSummary.ts`.
+ */
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.account.view'] },
+}
+
+export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    if (!auth || !auth.tenantId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+    const organizationId = (auth as { orgId?: string }).orgId ?? null
+    if (!organizationId) {
+      return NextResponse.json({ error: 'Organization scope required' }, { status: 403 })
+    }
+    const { id: accountId } = await params
+    const em = (container.resolve('em') as EntityManager).fork()
+    const account = await em.findOne(BillingAccount, {
+      id: accountId,
+      tenantId: auth.tenantId,
+      organizationId,
+      deletedAt: null,
+    })
+    if (!account) {
+      return NextResponse.json({ error: 'Account not found' }, { status: 404 })
+    }
+    return NextResponse.json(await getAccountWorkspaceSummary(em, account))
+  } catch (err) {
+    console.error('[billing/accounts/summary.GET]', err)
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+
+export const openApi = {
+  methods: {
+    GET: {
+      tags: ['Billing'],
+      summary: 'Get a billing account receivables summary',
+      parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string', format: 'uuid' } }],
+      description:
+        'Returns `{ bill_account_id, currency_code, open_amount, overdue_amount, overdue_count, ' +
+        'credit_amount }` over posted / partially paid invoices and debit memos (test runs excluded). ' +
+        'Overdue = past due date with outstanding > 0. `credit_amount` = unallocated payments + open credit memos. ' +
+        'Spec F (account workspace) adds `billing_mode`, `bill_cycle`, `next_bill_date`, `last_invoice` ' +
+        '(`{ id, number, issue_date, total_gross }` or null) and, for prepaid accounts, `prepaid { balance, ' +
+        'balance_status, credit_limit, last_statement }` (null for postpaid).',
+    },
+  },
+}

package/src/modules/billing/api/accounts/route.ts

@@ -2,7 +2,13 @@ import { z } from 'zod'
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { withScopedPayload } from '@open-mercato/shared/lib/api/scoped'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AwilixContainer } from 'awilix'
 import { BillingAccount } from '../../data/entities'
+import { fetchAccountFinancials, fetchOverdueAccountIds, financialsOrZero } from '../../lib/accountFinancials'
+
+/** A uuid no row has — narrows an `$in` filter to nothing. */
+const NO_MATCH_ID = '00000000-0000-4000-8000-000000000000'
 import { billingEntityIds } from '../../data/entityIds'
 import {
   billingAccountCreateSchema,
@@ -33,6 +39,7 @@ export const metadata = routeMetadata
 const billingAccountListItemSchema = z.object({
   id: z.string().uuid(),
   customer_id: z.string(),
+  customer_kind: z.enum(['company', 'person']),
   name: z.string(),
   currency_code: z.string(),
   bill_cycle: z.string(),
@@ -45,6 +52,11 @@ const billingAccountListItemSchema = z.object({
   last_bill_date: z.string().nullable(),
   billing_mode: z.string(),
   credit_limit: z.string(),
+  payment_terms_days: z.number().int().nullable(),
+  auto_send_invoice: z.boolean(),
+  /** Spec F (F8): Σ outstanding of open receivables and its overdue subset (batched per page). */
+  balance_due: z.string(),
+  overdue_amount: z.string(),
   is_active: z.boolean(),
   organization_id: z.string().uuid(),
   tenant_id: z.string().uuid(),
@@ -71,6 +83,7 @@ const crud = makeCrudRoute({
     fields: [
       'id',
       'customer_id',
+      'customer_kind',
       'name',
       'currency_code',
       'bill_cycle',
@@ -83,6 +96,8 @@ const crud = makeCrudRoute({
       'last_bill_date',
       'billing_mode',
       'credit_limit',
+      'payment_terms_days',
+      'auto_send_invoice',
       'is_active',
       'organization_id',
       'tenant_id',
@@ -95,16 +110,28 @@ const crud = makeCrudRoute({
       updatedAt: 'updated_at',
       nextBillDate: 'next_bill_date',
     },
-    buildFilters: async (query) => {
+    buildFilters: async (query, ctx) => {
       const filters: Record<string, unknown> = {}
+      // Spec F (F8): accounts with an overdue receivable — one indexed
+      // DISTINCT over billing_invoices, intersected with any `id` filter.
+      if (query.hasOverdue === true && ctx.auth?.tenantId) {
+        const organizationIds = ctx.organizationIds ?? (ctx.selectedOrganizationId ? [ctx.selectedOrganizationId] : [])
+        const em = ctx.container.resolve<EntityManager>('em')
+        const overdueIds = await fetchOverdueAccountIds(em, { tenantId: ctx.auth.tenantId, organizationIds })
+        filters.id = { $in: overdueIds.length > 0 ? overdueIds : [NO_MATCH_ID] }
+      }
       // `?id=<uuid>` narrows the list to one row — the detail page
       // reads a single account through this filter.
       if (typeof query.id === 'string' && query.id) {
-        filters.id = { $eq: query.id }
+        const current = filters.id as { $in?: string[] } | undefined
+        filters.id = current?.$in ? { $in: current.$in.includes(query.id) ? [query.id] : [NO_MATCH_ID] } : { $eq: query.id }
       }
       if (typeof query.customerId === 'string' && query.customerId) {
         filters.customer_id = { $eq: query.customerId }
       }
+      if (typeof query.customerKind === 'string' && query.customerKind) {
+        filters.customer_kind = { $eq: query.customerKind }
+      }
       if (typeof query.currencyCode === 'string' && query.currencyCode) {
         filters.currency_code = { $eq: query.currencyCode.toUpperCase() }
       }
@@ -124,6 +151,30 @@ const crud = makeCrudRoute({
       return filters
     },
   },
+  hooks: {
+    // Spec F (F8): balance due / overdue per row — one GROUP BY for the page.
+    afterList: async (payload: unknown, ctx: unknown) => {
+      const items = ((payload as { items?: unknown[] } | null)?.items ?? []) as Array<Record<string, unknown>>
+      if (items.length === 0) return
+      const first = items[0]
+      const tenantId = typeof first.tenant_id === 'string' ? first.tenant_id : null
+      const organizationId = typeof first.organization_id === 'string' ? first.organization_id : null
+      const ids = items.map((row) => row.id).filter((id): id is string => typeof id === 'string')
+      const financials =
+        tenantId && organizationId
+          ? await fetchAccountFinancials(
+              (ctx as { container: AwilixContainer }).container.resolve<EntityManager>('em'),
+              { tenantId, organizationId },
+              ids,
+            )
+          : new Map()
+      for (const row of items) {
+        const values = financialsOrZero(financials, String(row.id))
+        row.balance_due = values.balance_due
+        row.overdue_amount = values.overdue_amount
+      }
+    },
+  },
   actions: {
     create: {
       commandId: 'billing.accounts.create',
@@ -190,12 +241,15 @@ export const openApi = createBillingCrudOpenApi({
   create: {
     schema: billingAccountCreateSchema,
     responseSchema: defaultCreateResponseSchema,
-    description: 'Creates a new billing account for a customer.',
+    description:
+      'Creates a new billing account for a customer — a company or a person (`customerKind`, default `company`). ' +
+      '`invoiceLanguage` must be a language supported by the invoice template (`en`, `pl`; default `en`).',
   },
   update: {
     schema: billingAccountUpdateSchema,
     responseSchema: defaultOkResponseSchema,
-    description: 'Updates a billing account. `currencyCode` and `customerId` are immutable.',
+    description:
+      'Updates a billing account. `currencyCode`, `customerId` and `customerKind` are immutable.',
   },
   del: {
     schema: z.object({ id: z.string().uuid() }),

package/src/modules/billing/api/export/account/[id]/route.ts

@@ -10,8 +10,8 @@ import {
   BillingItem,
   BillingStatement,
   BillingTopup,
-  BillRunOutcome,
-  DraftInvoiceEdit,
+  BillingRunOutcome,
+  BillingDraftInvoiceEdit,
 } from '../../../../data/entities'
 
 /**
@@ -22,10 +22,9 @@ import {
  *   - The account row itself.
  *   - Every active + soft-deleted `BillingItem` for the account.
  *   - Every `BillingAccountUsage` record.
- *   - Every `BillRunOutcome` row referencing the account.
- *   - Every `core/sales` invoice the engine emitted for the account
- *     (matched via `metadata->>'bill_account_id'`).
- *   - Every `DraftInvoiceEdit` audit row for those invoices.
+ *   - Every `BillingRunOutcome` row referencing the account.
+ *   - Every billing document (`billing_invoices`) of the account.
+ *   - Every `BillingDraftInvoiceEdit` audit row for those invoices.
  *
  * Scope: the caller's auth tenant/organization is the authority — a
  * 404 is returned even for valid UUIDs that belong to a different
@@ -108,7 +107,7 @@ export async function GET(
         { limit: EXPORT_HARD_LIMIT, orderBy: { periodEnd: 'DESC' } },
       ),
       em.find(
-        BillRunOutcome,
+        BillingRunOutcome,
         {
           tenantId,
           organizationId,
@@ -154,18 +153,18 @@ export async function GET(
       ),
     ])
 
-    // Invoices created in the window. The `metadata->>'bill_account_id'`
-    // predicate keeps non-billing core/sales invoices out.
+    // Billing documents created in the window (Spec 0: billing_invoices).
     const invoiceRows = (await em.execute(
-      `SELECT id, invoice_number, status, status_entry_id, issue_date, due_date,
-              currency_code, subtotal_net_amount, grand_total_net_amount,
-              grand_total_gross_amount, paid_total_amount, outstanding_amount,
-              metadata, created_at, updated_at, deleted_at
-       FROM sales_invoices
+      `SELECT id, number, document_type, series, status, test_run, bill_run_id, bill_date,
+              period_start, period_end, issue_date, due_date, posted_at, currency_code,
+              subtotal_net, tax_total, total_gross, paid_total, credited_total, outstanding,
+              corrects_invoice_id, correction_reason, topup_id, buyer_snapshot, seller_snapshot,
+              metadata, created_at, updated_at
+       FROM billing_invoices
        WHERE tenant_id = ?
          AND organization_id = ?
          AND deleted_at IS NULL
-         AND metadata->>'bill_account_id' = ?
+         AND bill_account_id = ?
          AND created_at >= ?
          AND created_at <= ?
        ORDER BY created_at DESC
@@ -177,7 +176,7 @@ export async function GET(
     const draftEdits =
       invoiceIds.length > 0
         ? await em.find(
-            DraftInvoiceEdit,
+            BillingDraftInvoiceEdit,
             {
               tenantId,
               organizationId,
@@ -190,7 +189,10 @@ export async function GET(
     return NextResponse.json({
       exportedAt: new Date().toISOString(),
       // v2 adds prepaid balance / transactions / top-ups / statements (SPEC-002).
-      schemaVersion: 2,
+      // v3 (Spec 0): invoices come from billing_invoices with billing field names.
+      // v4 (Spec B): items carry taxRate; the account carries paymentTermsDays /
+      // autoSendInvoice; invoice metadata may carry draft_number / deliveries.
+      schemaVersion: 4,
       tenantId,
       organizationId,
       window: {
@@ -272,7 +274,7 @@ export const openApi = {
         },
       ],
       description:
-        "Returns a JSON dump of a single Billing Account: the account itself, every Billing Item (no time cap — items often outlive a single export window), and the Usage records / BillRunOutcomes / emitted core/sales invoices / DraftInvoiceEdit rows whose timestamps fall in the [since, until] window (defaults to the last 12 months). Each collection is independently capped by EXPORT_HARD_LIMIT = 50,000 rows. Lifetime dumps for outlier accounts need a follow-up chunked background-job approach — out of scope for this v1 endpoint.",
+        "Returns a JSON dump of a single Billing Account: the account itself, every Billing Item (no time cap — items often outlive a single export window), and the Usage records / BillRunOutcomes / emitted core/sales invoices / BillingDraftInvoiceEdit rows whose timestamps fall in the [since, until] window (defaults to the last 12 months). Each collection is independently capped by EXPORT_HARD_LIMIT = 50,000 rows. Lifetime dumps for outlier accounts need a follow-up chunked background-job approach — out of scope for this v1 endpoint.",
     },
   },
 }