@dainamite/billing 0.20.0 → 0.22.0

package/src/modules/billing/__tests__/commands/runsPostDrafts.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Posting a real run's draft invoices in cursor batches (`billing.runs.post_drafts`).
+ */
+
+jest.mock('../../events', () => ({ emitBillingEvent: jest.fn(async () => undefined) }))
+jest.mock('../../lib/billRunEngine', () => ({ runBillRun: jest.fn() }))
+
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { postDraftsCommand } from '../../commands/runs'
+
+const TENANT = '11111111-1111-4111-8111-111111111111'
+const ORG = '22222222-2222-4222-8222-222222222222'
+const RUN_ID = '33333333-3333-4333-8333-333333333333'
+const A = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+const B = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb'
+const C = 'cccccccc-cccc-4ccc-8ccc-cccccccccccc'
+
+type RunRow = { id: string; dryRun: boolean; testMode: boolean; status: string }
+
+function createEnv(opts: { run: RunRow | null; drafts: Array<{ id: string; number: string }>; remaining?: number; failOn?: Record<string, { code: string; error: string }> }) {
+  const posted: string[] = []
+  const executed: Array<{ sql: string; params: unknown[] }> = []
+  const em = {
+    findOne: jest.fn(async () => opts.run),
+    execute: jest.fn(async (sql: string, params: unknown[] = []) => {
+      executed.push({ sql, params })
+      if (sql.includes('COUNT(*)')) return [{ remaining: opts.remaining ?? 0 }]
+      return opts.drafts
+    }),
+    fork: jest.fn((): unknown => em),
+  }
+  const commandBus = {
+    execute: jest.fn(async (_id: string, args: { input: { invoiceId: string } }) => {
+      const failure = opts.failOn?.[args.input.invoiceId]
+      if (failure) throw new CrudHttpError(409, failure)
+      posted.push(args.input.invoiceId)
+      return { result: { status: 'posted' } }
+    }),
+  }
+  const ctx = {
+    container: { resolve: jest.fn((name: string) => (name === 'commandBus' ? commandBus : em)) },
+    auth: { tenantId: TENANT, orgId: ORG },
+    selectedOrganizationId: ORG,
+    organizationIds: [ORG],
+    organizationScope: null,
+  }
+  return { ctx, posted, executed, commandBus }
+}
+
+const realRun: RunRow = { id: RUN_ID, dryRun: false, testMode: false, status: 'completed' }
+const input = { tenantId: TENANT, organizationId: ORG, billRunId: RUN_ID }
+
+describe('postDraftsCommand', () => {
+  it('posts each draft through billing.invoices.post and returns the cursor + remaining', async () => {
+    const env = createEnv({ run: realRun, drafts: [{ id: A, number: 'DRAFT-A' }, { id: B, number: 'DRAFT-B' }], remaining: 5 })
+    const result = await postDraftsCommand.execute({ ...input, limit: 2 }, env.ctx as never)
+    expect(env.posted).toEqual([A, B])
+    expect(env.commandBus.execute).toHaveBeenCalledWith('billing.invoices.post', expect.objectContaining({
+      input: { tenantId: TENANT, organizationId: ORG, invoiceId: A },
+    }))
+    expect(result).toEqual({ posted: 2, failed: [], nextCursor: B, remaining: 5, stoppedReason: null })
+    // Draft selection is scoped, real-only and keyset-paged.
+    const select = env.executed[0]
+    expect(select.sql).toContain("status = 'draft'")
+    expect(select.sql).toContain('test_run = false')
+    expect(select.params).toEqual([TENANT, ORG, RUN_ID, null, null, 2])
+  })
+
+  it('reports a failing invoice and carries on with the rest', async () => {
+    const env = createEnv({
+      run: realRun,
+      drafts: [{ id: A, number: 'DRAFT-A' }, { id: B, number: 'DRAFT-B' }, { id: C, number: 'DRAFT-C' }],
+      failOn: { [B]: { code: 'billing.invoice.number_conflict', error: 'Number already issued' } },
+    })
+    const result = await postDraftsCommand.execute(input, env.ctx as never)
+    expect(env.posted).toEqual([A, C])
+    expect(result.failed).toEqual([
+      { invoiceId: B, number: 'DRAFT-B', error: 'Number already issued', code: 'billing.invoice.number_conflict' },
+    ])
+    expect(result.nextCursor).toBe(C)
+  })
+
+  it('stops at incomplete seller settings and keeps the starting cursor', async () => {
+    const env = createEnv({
+      run: realRun,
+      drafts: [{ id: A, number: 'DRAFT-A' }, { id: B, number: 'DRAFT-B' }],
+      remaining: 2,
+      failOn: { [A]: { code: 'billing.settings.incomplete', error: 'Fill in the seller details' } },
+    })
+    const result = await postDraftsCommand.execute(input, env.ctx as never)
+    expect(env.commandBus.execute).toHaveBeenCalledTimes(1)
+    expect(result).toMatchObject({ posted: 0, stoppedReason: 'billing.settings.incomplete', nextCursor: null, remaining: 2 })
+  })
+
+  it('refuses test / dry runs (422), running runs (409) and unknown runs (404)', async () => {
+    await expect(
+      postDraftsCommand.execute(input, createEnv({ run: { ...realRun, testMode: true }, drafts: [] }).ctx as never),
+    ).rejects.toMatchObject({ status: 422, body: { code: 'billing.run.not_real' } })
+    await expect(
+      postDraftsCommand.execute(input, createEnv({ run: { ...realRun, status: 'running' }, drafts: [] }).ctx as never),
+    ).rejects.toMatchObject({ status: 409 })
+    await expect(postDraftsCommand.execute(input, createEnv({ run: null, drafts: [] }).ctx as never)).rejects.toMatchObject({
+      status: 404,
+    })
+  })
+})

package/src/modules/billing/__tests__/commands/topups.test.ts

@@ -25,6 +25,8 @@ function makeCtx(em: MockEm, gateway: unknown) {
   return {
     auth: { sub: '99999999-9999-4999-8999-999999999999', tenantId: TENANT, orgId: ORG },
     container: {
+      // E-D1: the gateway is optional — registered only when one is passed.
+      hasRegistration: jest.fn((name: string) => name !== 'paymentGatewayService' || gateway != null),
       resolve: jest.fn((name: string) => {
         if (name === 'em') return em
         if (name === 'dataEngine') return dataEngine
@@ -101,4 +103,13 @@ describe('createTopupCommand', () => {
     expect(result.redirectUrl).toBe('https://pay.example/prior')
     expect(gateway.createPaymentSession).not.toHaveBeenCalled()
   })
+
+  it('returns 501 gateway_unavailable without persisting when payment_gateways is not installed', async () => {
+    const em = createPrepaidMockEm({ account: prepaidAccount(), topup: null })
+    await expect(createTopupCommand.execute(baseInput, makeCtx(em, null) as never)).rejects.toMatchObject({
+      status: 501,
+      body: expect.objectContaining({ code: 'billing.topup.gateway_unavailable' }),
+    })
+    expect(em.persisted.some((e) => (e as { status?: string }).status === 'pending')).toBe(false)
+  })
 })

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

@@ -58,6 +58,13 @@ const EXPECTED_TABLES: Record<string, string> = {
   [billingEntityIds.transaction]: 'billing_account_transactions',
   [billingEntityIds.topup]: 'billing_topups',
   [billingEntityIds.statement]: 'billing_statements',
+  [billingEntityIds.invoice]: 'billing_invoices',
+  [billingEntityIds.invoiceLine]: 'billing_invoice_lines',
+  [billingEntityIds.documentSequence]: 'billing_document_sequences',
+  [billingEntityIds.settings]: 'billing_settings',
+  [billingEntityIds.payment]: 'billing_payments',
+  [billingEntityIds.allocation]: 'billing_allocations',
+  [billingEntityIds.paymentImport]: 'billing_payment_imports',
 }
 
 /** PascalCase of an id suffix — the class name the framework looks up. */
@@ -104,7 +111,7 @@ describe('shipped registry — generated/entities.ids.generated.ts', () => {
     // are what matters.
     const expected = Object.fromEntries(ALL_IDS.map((id) => [suffixOf(id), id]))
     expect(E.billing).toEqual(expected)
-    expect(Object.keys(E.billing)).toHaveLength(10)
+    expect(Object.keys(E.billing)).toHaveLength(17)
   })
 
   it('ships one column file per entity, matching the ORM columns', () => {

package/src/modules/billing/__tests__/helpers/prepaidMockEm.ts

@@ -4,7 +4,7 @@
  * Models the subset of operations `balanceLedger` / `prepaidConsume` /
  * `accountStatus` touch: the raw `INSERT … ON CONFLICT` + `UPDATE … RETURNING`
  * balance statements, the `SUM(amount)` reconciliation query, the postpaid
- * `SUM(outstanding_amount)` query, plus findOne/find/create/persist/flush.
+ * `SUM(outstanding)` query on `billing_invoices`, plus findOne/find/create/persist/flush.
  *
  * The balance math reuses the real `money` helpers so the mock's rounding
  * matches production exactly — that is the whole point of the reconciliation
@@ -31,9 +31,9 @@ export type MockEmOptions = {
   existingStatement?: Row | null
   /** A PRIOR BillingStatement (periodEnd < periodStart) for opening-chaining tests. */
   priorStatement?: Row | null
-  /** Module config values keyed by name (e.g. { 'prepaid.topup_tax_rate': 23 }). */
+  /** Billing settings by legacy config name (e.g. { 'prepaid.topup_tax_rate': 23 }), served as a BillingSettings row. */
   configs?: Record<string, unknown>
-  /** Postpaid outstanding total returned by the SUM(outstanding_amount) query. */
+  /** Postpaid outstanding total returned by the SUM(outstanding) query on billing_invoices. */
   postpaidOutstanding?: string | number
 }
 
@@ -50,6 +50,8 @@ export type MockEm = {
   persist: jest.Mock
   flush: jest.Mock
   execute: jest.Mock
+  /** Series names of document numbers claimed (Spec 0). */
+  sequenceClaims: string[]
   nativeUpdate: jest.Mock
   transactional: jest.Mock
   fork: () => MockEm
@@ -80,6 +82,7 @@ export function createPrepaidMockEm(options: MockEmOptions = {}): MockEm {
     usages,
     balances,
     persisted,
+    sequenceClaims: [] as string[],
   } as MockEm
 
   em.create = jest.fn((entity: unknown, data: Row) => {
@@ -146,14 +149,23 @@ export function createPrepaidMockEm(options: MockEmOptions = {}): MockEm {
       }
       return options.existingStatement ?? null
     }
-    // resolveInvoiceStatusEntryId looks up Dictionary then DictionaryEntry.
-    if (ctor === 'Dictionary') return { id: 'dict-invoice-status' }
-    if (ctor === 'DictionaryEntry') return { id: `status-${(where.value as string) ?? 'x'}` }
-    if (ctor === 'ModuleConfig') {
-      const name = where.name as string
+    // Spec 0: prepaid settings live on the per-org BillingSettings row. The
+    // `configs` option keeps the old config names so tests stay readable.
+    if (ctor === 'BillingSettings') {
       const configs = options.configs ?? {}
-      if (name in configs) return { moduleId: 'billing', name, valueJson: configs[name] }
-      return null
+      const pick = (name: string, fallback: unknown) => (name in configs ? configs[name] : fallback)
+      return {
+        id: 'settings-1',
+        tenantId: where.tenantId,
+        organizationId: where.organizationId,
+        lowBalanceThresholdDefault: String(pick('prepaid.low_balance_threshold_default', '0')),
+        nearLimitBufferDefault: String(pick('credit.near_limit_buffer_default', '0')),
+        statementEnabled: pick('prepaid.statement_enabled', true),
+        topupTaxRate: String(pick('prepaid.topup_tax_rate', '0')),
+        prepaidTaxPoint: pick('prepaid.tax_point', 'topup'),
+        topupProvider: pick('prepaid.topup_provider', 'stripe'),
+        numberMasks: null,
+      }
     }
     return null
   }) as never
@@ -165,6 +177,11 @@ export function createPrepaidMockEm(options: MockEmOptions = {}): MockEm {
   }) as never
 
   em.execute = jest.fn(async (sql: string, params: unknown[] = []) => {
+    // Spec 0 numbering: claimDocumentNumber's sequence upsert.
+    if (sql.includes('billing_document_sequences')) {
+      em.sequenceClaims.push(params[2] as string)
+      return [{ seq: 42 }]
+    }
     if (sql.includes('INSERT INTO billing_account_balances')) {
       // params: [org, tenant, acct, ccy, now, now]
       const [organizationId, tenantId, billAccountId, currencyCode] = params as string[]
@@ -221,7 +238,7 @@ export function createPrepaidMockEm(options: MockEmOptions = {}): MockEm {
       const sum = transactions.reduce((acc, t) => addMoney(acc, (t.amount as string) ?? '0'), '0')
       return [{ sum_amount: sum }]
     }
-    if (sql.includes('SUM(outstanding_amount)')) {
+    if (sql.includes('SUM(outstanding)') && sql.includes('billing_invoices')) {
       return [{ total: String(options.postpaidOutstanding ?? '0') }]
     }
     return []

package/src/modules/billing/__tests__/i18n/dictionaries.test.ts

@@ -0,0 +1,64 @@
+import { readdirSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { INVOICE_LANGUAGE_CODES } from '../../lib/invoiceLanguages'
+
+/**
+ * Guardrails for billing dictionaries (spec 2026-11-15-billing-multi-language):
+ * every `i18n/<locale>.json` mirrors `en.json` key for key and keeps every
+ * `{placeholder}` intact — a translated placeholder would print as a raw token
+ * on a customer's invoice or email. Picks up new dictionaries automatically.
+ */
+
+const I18N_DIR = join(__dirname, '..', '..', 'i18n')
+
+function load(locale: string): Record<string, string> {
+  return JSON.parse(readFileSync(join(I18N_DIR, `${locale}.json`), 'utf8')) as Record<string, string>
+}
+
+function placeholders(value: string): string[] {
+  return [...value.matchAll(/\{(\w+)\}/g)].map((m) => m[1]).sort()
+}
+
+const locales = readdirSync(I18N_DIR)
+  .filter((file) => file.endsWith('.json'))
+  .map((file) => file.replace(/\.json$/, ''))
+  .sort()
+const en = load('en')
+const enKeys = Object.keys(en)
+const translated = locales.filter((locale) => locale !== 'en')
+
+describe('billing i18n dictionaries', () => {
+  it('ships an English base dictionary and at least one translation', () => {
+    expect(locales).toContain('en')
+    expect(translated.length).toBeGreaterThan(0)
+  })
+
+  describe.each(translated)('%s.json', (locale) => {
+    const dict = load(locale)
+
+    it('has exactly the keys of en.json, in the same order', () => {
+      expect(Object.keys(dict)).toEqual(enKeys)
+    })
+
+    it('keeps every {placeholder} of the English value', () => {
+      const mismatches = enKeys
+        .filter((key) => typeof dict[key] === 'string')
+        .filter((key) => placeholders(dict[key]).join(',') !== placeholders(en[key]).join(','))
+      expect(mismatches).toEqual([])
+    })
+
+    it('has no empty values', () => {
+      expect(enKeys.filter((key) => typeof dict[key] !== 'string' || dict[key].trim() === '')).toEqual([])
+    })
+  })
+
+  it('has a dictionary for every supported invoice language, covering every document and email key', () => {
+    const documentKeys = enKeys.filter((key) => key.startsWith('billing.pdf.') || key.startsWith('billing.email.'))
+    expect(documentKeys.length).toBeGreaterThan(0)
+    for (const code of INVOICE_LANGUAGE_CODES) {
+      expect(locales).toContain(code)
+      const dict = load(code)
+      expect(documentKeys.filter((key) => !dict[key])).toEqual([])
+    }
+  })
+})

package/src/modules/billing/__tests__/lib/accountFinancials.test.ts

@@ -0,0 +1,53 @@
+import {
+  ACCOUNT_FINANCIALS_SQL,
+  OVERDUE_ACCOUNT_IDS_SQL,
+  fetchAccountFinancials,
+  fetchOverdueAccountIds,
+  financialsOrZero,
+} from '../../lib/accountFinancials'
+
+const scope = { tenantId: 't-1', organizationId: 'o-1' }
+
+describe('fetchAccountFinancials (Spec F, P-D15)', () => {
+  it('runs ONE grouped query for the whole page (today first, then scope and the id array)', async () => {
+    const execute = jest.fn(async () => [
+      { bill_account_id: 'a-1', balance_due: '120.5', overdue_amount: '20' },
+    ])
+    const result = await fetchAccountFinancials({ execute } as never, scope, ['a-1', 'a-2'], new Date('2026-11-15T09:00:00Z'))
+    expect(execute).toHaveBeenCalledTimes(1)
+    expect(execute).toHaveBeenCalledWith(ACCOUNT_FINANCIALS_SQL, ['2026-11-15', 't-1', 'o-1', '{a-1,a-2}'])
+    expect(result.get('a-1')).toEqual({ balance_due: '120.5000', overdue_amount: '20.0000' })
+    expect(financialsOrZero(result, 'a-2')).toEqual({ balance_due: '0.0000', overdue_amount: '0.0000' })
+  })
+
+  it('skips the query for an empty page', async () => {
+    const execute = jest.fn()
+    expect((await fetchAccountFinancials({ execute } as never, scope, [])).size).toBe(0)
+    expect(execute).not.toHaveBeenCalled()
+  })
+
+  it('counts open receivables only and never test runs', () => {
+    expect(ACCOUNT_FINANCIALS_SQL).toContain('i.test_run = false')
+    expect(ACCOUNT_FINANCIALS_SQL).toContain("i.status IN ('posted', 'partially_paid')")
+    expect(ACCOUNT_FINANCIALS_SQL).toContain('GROUP BY i.bill_account_id')
+  })
+})
+
+describe('fetchOverdueAccountIds', () => {
+  it('returns distinct ids across the visible organizations', async () => {
+    const execute = jest.fn(async () => [{ bill_account_id: 'a-9' }])
+    const ids = await fetchOverdueAccountIds(
+      { execute } as never,
+      { tenantId: 't-1', organizationIds: ['o-1', 'o-2'] },
+      new Date('2026-11-15T00:00:00Z'),
+    )
+    expect(ids).toEqual(['a-9'])
+    expect(execute).toHaveBeenCalledWith(OVERDUE_ACCOUNT_IDS_SQL, ['t-1', '{o-1,o-2}', '2026-11-15'])
+  })
+
+  it('returns nothing without an organization scope', async () => {
+    const execute = jest.fn()
+    expect(await fetchOverdueAccountIds({ execute } as never, { tenantId: 't-1', organizationIds: [] })).toEqual([])
+    expect(execute).not.toHaveBeenCalled()
+  })
+})

package/src/modules/billing/__tests__/lib/accountSummary.test.ts

@@ -0,0 +1,97 @@
+import {
+  ACCOUNT_SUMMARY_SQL,
+  BALANCE_SQL,
+  LAST_INVOICE_SQL,
+  LAST_STATEMENT_SQL,
+  getAccountArSummary,
+  getAccountWorkspaceSummary,
+} from '../../lib/accountSummary'
+
+const account = { id: 'acc-1', tenantId: 't-1', organizationId: 'o-1', currencyCode: 'PLN' }
+
+describe('getAccountArSummary', () => {
+  it('runs one aggregate query with today bound for both overdue filters, then the scope', async () => {
+    const execute = jest.fn(async (sql: string) =>
+      sql === ACCOUNT_SUMMARY_SQL
+        ? [{ open_amount: '300.5', overdue_amount: '120', overdue_count: 2 }]
+        : [{ source_type: 'payment', id: 'p-1', available: '25.5' }, { source_type: 'credit_memo', id: 'm-1', available: '10' }],
+    )
+    const result = await getAccountArSummary({ execute } as never, account, new Date('2026-11-14T10:00:00Z'))
+    expect(execute).toHaveBeenCalledTimes(2)
+    expect(execute).toHaveBeenCalledWith(ACCOUNT_SUMMARY_SQL, ['2026-11-14', '2026-11-14', 't-1', 'o-1', 'acc-1'])
+    expect(result).toEqual({
+      bill_account_id: 'acc-1',
+      currency_code: 'PLN',
+      open_amount: '300.5000',
+      overdue_amount: '120.0000',
+      overdue_count: 2,
+      // Spec C: unallocated payments + open credit memos
+      credit_amount: '35.5000',
+    })
+  })
+
+  it('returns zeros when the account has no open documents', async () => {
+    const execute = jest.fn(async (sql: string) =>
+      sql === ACCOUNT_SUMMARY_SQL ? [{ open_amount: null, overdue_amount: null, overdue_count: null }] : [],
+    )
+    const result = await getAccountArSummary({ execute } as never, account)
+    expect(result).toMatchObject({ open_amount: '0.0000', overdue_amount: '0.0000', overdue_count: 0 })
+  })
+
+  it('excludes test runs and non-receivable documents', () => {
+    expect(ACCOUNT_SUMMARY_SQL).toContain('i.test_run = false')
+    expect(ACCOUNT_SUMMARY_SQL).toContain("i.document_type IN ('invoice', 'debit_memo')")
+    expect(ACCOUNT_SUMMARY_SQL).toContain("i.status IN ('posted', 'partially_paid')")
+  })
+})
+
+describe('getAccountWorkspaceSummary (Spec F, F8)', () => {
+  const settingsRow = { id: 's-1', lowBalanceThresholdDefault: '10' }
+  function fakeEm(rows: Record<string, unknown[]>) {
+    return {
+      execute: jest.fn(async (sql: string) => rows[sql] ?? []),
+      findOne: jest.fn(async () => settingsRow),
+    }
+  }
+
+  it('postpaid: AR + cycle state + last invoice, no prepaid block', async () => {
+    const em = fakeEm({
+      [ACCOUNT_SUMMARY_SQL]: [{ open_amount: '50', overdue_amount: '0', overdue_count: 0 }],
+      [LAST_INVOICE_SQL]: [{ id: 'inv-1', number: 'INV/2026/11/0001', issue_date: '2026-11-14', total_gross: '61.5' }],
+    })
+    const result = await getAccountWorkspaceSummary(
+      em as never,
+      { ...account, billingMode: 'postpaid', billCycle: 'monthly', nextBillDate: '2026-12-14' as never, creditLimit: '0' },
+      new Date('2026-11-15T00:00:00Z'),
+    )
+    expect(result).toMatchObject({
+      billing_mode: 'postpaid',
+      next_bill_date: '2026-12-14',
+      last_invoice: { id: 'inv-1', number: 'INV/2026/11/0001', issue_date: '2026-11-14', total_gross: '61.5000' },
+      prepaid: null,
+    })
+    expect(em.execute).not.toHaveBeenCalledWith(BALANCE_SQL, expect.anything())
+  })
+
+  it('prepaid: balance with status from the threshold, credit limit and last statement', async () => {
+    const em = fakeEm({
+      [ACCOUNT_SUMMARY_SQL]: [{ open_amount: '0', overdue_amount: '0', overdue_count: 0 }],
+      [BALANCE_SQL]: [{ balance: '8.5', low_balance_threshold: null }],
+      [LAST_STATEMENT_SQL]: [{ id: 'st-1', period_start: '2026-10-14', period_end: '2026-11-13', closing_balance: '8.5' }],
+    })
+    const result = await getAccountWorkspaceSummary(em as never, {
+      ...account,
+      billingMode: 'prepaid',
+      billCycle: 'monthly',
+      nextBillDate: new Date('2026-12-14T00:00:00Z'),
+      creditLimit: '100',
+    })
+    expect(result.prepaid).toEqual({
+      balance: '8.5000',
+      balance_status: 'low', // 8.50 ≤ the 10.00 org default threshold
+      credit_limit: '100.0000',
+      last_statement: { id: 'st-1', period_start: '2026-10-14', period_end: '2026-11-13', closing_balance: '8.5000' },
+    })
+    expect(result.last_invoice).toBeNull()
+  })
+})