@dainamite/billing 0.17.0

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

@@ -0,0 +1,190 @@
+import { rateUsageForItem, rateUsageQuantity } from '../../lib/usageRater'
+import type { BillingItem } from '../../data/entities'
+
+describe('rateUsageQuantity — simple flat rate', () => {
+  it('charges quantity × unit_price (canonical case)', () => {
+    const result = rateUsageQuantity({ unit_price: 0.001 }, 12000)
+    expect(result.amount).toBe('12.0000')
+    expect(result.breakdown).toEqual([
+      { tierIndex: 0, upTo: null, rangeQuantity: 12000, rate: 0.001, amount: '12.0000' },
+    ])
+  })
+
+  it('returns zero on zero quantity', () => {
+    const result = rateUsageQuantity({ unit_price: 0.001 }, 0)
+    expect(result.amount).toBe('0.0000')
+  })
+
+  it('rounds half-up to 2dp (1.005 → 1.01)', () => {
+    // unit_price=0.001 × quantity=1005 = 1.005 → 1.01
+    const result = rateUsageQuantity({ unit_price: 0.001 }, 1005)
+    expect(result.amount).toBe('1.0100')
+  })
+
+  it('safe-guards negative quantity (treated as 0)', () => {
+    const result = rateUsageQuantity({ unit_price: 0.001 }, -100)
+    expect(result.amount).toBe('0.0000')
+  })
+})
+
+describe('rateUsageQuantity — volume tier (whole-quantity at top reached tier)', () => {
+  const volumeLadder = {
+    model: 'volume' as const,
+    tiers: [
+      { up_to: 10000, unit_price: 0 },
+      { up_to: 50000, unit_price: 0.001 },
+      { up_to: null, unit_price: 0.0005 },
+    ],
+  }
+
+  it('25k requests at [10k=0, 50k=0.001, ∞=0.0005] → 25000 × 0.001 = 25 EUR (spec example)', () => {
+    const result = rateUsageQuantity(volumeLadder, 25000)
+    expect(result.amount).toBe('25.0000')
+    expect(result.breakdown[0].rangeQuantity).toBe(0)
+    expect(result.breakdown[1].rangeQuantity).toBe(25000)
+    expect(result.breakdown[2].rangeQuantity).toBe(0)
+  })
+
+  it('5k requests fall into the bottom (free) tier → 0 EUR', () => {
+    const result = rateUsageQuantity(volumeLadder, 5000)
+    expect(result.amount).toBe('0.0000')
+    expect(result.breakdown[0].rangeQuantity).toBe(5000)
+  })
+
+  it('100k requests overflow into the open-ended top tier → 100k × 0.0005 = 50 EUR', () => {
+    const result = rateUsageQuantity(volumeLadder, 100000)
+    expect(result.amount).toBe('50.0000')
+    expect(result.breakdown[2].rangeQuantity).toBe(100000)
+  })
+
+  it('exact boundary (50k) stays in the middle tier — 50000 × 0.001 = 50', () => {
+    const result = rateUsageQuantity(volumeLadder, 50000)
+    expect(result.amount).toBe('50.0000')
+    expect(result.breakdown[1].rangeQuantity).toBe(50000)
+  })
+})
+
+describe('rateUsageQuantity — graduated tier (per-unit at tier)', () => {
+  const graduatedLadder = {
+    model: 'graduated' as const,
+    tiers: [
+      { up_to: 10000, unit_price: 0 },
+      { up_to: null, unit_price: 0.001 },
+    ],
+  }
+
+  it('25k requests at [10k=0, ∞=0.001] → 10k×0 + 15k×0.001 = 15 EUR (spec example)', () => {
+    const result = rateUsageQuantity(graduatedLadder, 25000)
+    expect(result.amount).toBe('15.0000')
+    expect(result.breakdown[0].rangeQuantity).toBe(10000)
+    expect(result.breakdown[0].amount).toBe('0.0000')
+    expect(result.breakdown[1].rangeQuantity).toBe(15000)
+    expect(result.breakdown[1].amount).toBe('15.0000')
+  })
+
+  it('5k requests stay in the free tier → 0 EUR', () => {
+    const result = rateUsageQuantity(graduatedLadder, 5000)
+    expect(result.amount).toBe('0.0000')
+    expect(result.breakdown[0].rangeQuantity).toBe(5000)
+    expect(result.breakdown[1].rangeQuantity).toBe(0)
+  })
+
+  it('exactly 10k stays free (boundary inclusive of the lower tier)', () => {
+    const result = rateUsageQuantity(graduatedLadder, 10000)
+    expect(result.amount).toBe('0.0000')
+  })
+
+  it('three-tier ladder splits correctly', () => {
+    const ladder = {
+      model: 'graduated' as const,
+      tiers: [
+        { up_to: 100, unit_price: 1 },
+        { up_to: 200, unit_price: 0.5 },
+        { up_to: null, unit_price: 0.1 },
+      ],
+    }
+    const result = rateUsageQuantity(ladder, 350)
+    // 100 × 1 + 100 × 0.5 + 150 × 0.1 = 100 + 50 + 15 = 165
+    expect(result.amount).toBe('165.0000')
+  })
+})
+
+describe('rateUsageQuantity — flat tier (one fee for highest tier reached)', () => {
+  const flatLadder = {
+    model: 'flat' as const,
+    tiers: [
+      { up_to: 10000, flat_amount: 50 },
+      { up_to: 50000, flat_amount: 200 },
+      { up_to: null, flat_amount: 1000 },
+    ],
+  }
+
+  it('25k requests → top tier reached is 50k → 200 EUR (spec example)', () => {
+    const result = rateUsageQuantity(flatLadder, 25000)
+    expect(result.amount).toBe('200.0000')
+    expect(result.breakdown[1].amount).toBe('200.0000')
+  })
+
+  it('exactly 10k → bottom tier → 50 EUR', () => {
+    const result = rateUsageQuantity(flatLadder, 10000)
+    expect(result.amount).toBe('50.0000')
+  })
+
+  it('overflows into open-ended top tier → 1000 EUR', () => {
+    const result = rateUsageQuantity(flatLadder, 75000)
+    expect(result.amount).toBe('1000.0000')
+  })
+
+  it('zero quantity still hits the bottom tier (consistent with billable presence)', () => {
+    const result = rateUsageQuantity(flatLadder, 0)
+    // 0 is ≤ first tier's up_to=10000, so the rate is 50 EUR.
+    expect(result.amount).toBe('50.0000')
+  })
+})
+
+describe('rateUsageForItem (dispatch wrapper)', () => {
+  function makeItem(rate: unknown, type: 'usage' | 'recurring' = 'usage'): BillingItem {
+    return {
+      id: 'i1',
+      type,
+      rateJson: rate,
+    } as unknown as BillingItem
+  }
+
+  it('returns null for non-usage items (defensive)', () => {
+    expect(rateUsageForItem(makeItem({ unit_price: 0.001 }, 'recurring'), 100)).toBeNull()
+  })
+
+  it('returns null for null rateJson', () => {
+    expect(rateUsageForItem(makeItem(null), 100)).toBeNull()
+  })
+
+  it('returns null for tiered rate with empty tiers array', () => {
+    expect(
+      rateUsageForItem(makeItem({ model: 'graduated', tiers: [] }), 100),
+    ).toBeNull()
+  })
+
+  it('returns null for simple rate missing unit_price', () => {
+    expect(rateUsageForItem(makeItem({}), 100)).toBeNull()
+  })
+
+  it('dispatches to simple-flat path for { unit_price }', () => {
+    const result = rateUsageForItem(makeItem({ unit_price: 0.001 }), 12000)
+    expect(result?.amount).toBe('12.0000')
+  })
+
+  it('dispatches to graduated path for { model: graduated, tiers }', () => {
+    const result = rateUsageForItem(
+      makeItem({
+        model: 'graduated',
+        tiers: [
+          { up_to: 10000, unit_price: 0 },
+          { up_to: null, unit_price: 0.001 },
+        ],
+      }),
+      25000,
+    )
+    expect(result?.amount).toBe('15.0000')
+  })
+})

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

@@ -0,0 +1,223 @@
+/**
+ * Package isolation guard for @dainamite/billing.
+ *
+ * Mirrors the @dainamite/cpq package-isolation test — proves the billing
+ * package can be loaded without any sibling `src/modules/<x>` modules and
+ * that every import resolves to a peerDependency or sibling file. See the
+ * cpq variant for the full rationale; this version reflects billing's
+ * narrower allowed-imports and required-modules surface.
+ */
+
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+
+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.
+const ALLOWED_IMPORT_PREFIXES = [
+  './',
+  '../',
+  '@open-mercato/',
+  '@mikro-orm/',
+  'awilix',
+  'lucide-react',
+  'next',
+  'next/',
+  'react',
+  'react/',
+  'react-dom',
+  'react-dom/',
+  'zod',
+  '@dainamite/',
+  'node:',
+  '@tanstack/',
+]
+
+const NODE_BUILTINS = new Set([
+  'crypto',
+  'fs',
+  'path',
+  'os',
+  'util',
+  'stream',
+  'buffer',
+  'http',
+  'https',
+  'url',
+  'querystring',
+  'child_process',
+  'zlib',
+  'events',
+  'assert',
+])
+
+const FORBIDDEN_PREFIXES = [
+  '@/modules/',
+  'src/modules/',
+  '../../../../catalog/',
+  '../../../../sales/',
+  '../../../../customers/',
+  '../../../../dictionaries/',
+  '../../../../auth/',
+  '../../../../directory/',
+  '../../../../demo_',
+  '../../../../portal/',
+  '../../../../customer_accounts/',
+  '../../../../example/',
+  '../../../../cpq/',
+]
+
+async function walk(dir: string, acc: string[] = []): Promise<string[]> {
+  const entries = await fs.readdir(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === 'dist') continue
+    if (entry.name === '__tests__' || entry.name === '__integration__') continue
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      await walk(full, acc)
+    } else if (/\.(ts|tsx|mts|cts)$/.test(entry.name) && !/\.d\.ts$/.test(entry.name)) {
+      acc.push(full)
+    }
+  }
+  return acc
+}
+
+const IMPORT_RE = /(?:^|\n)\s*(?:import\s+(?:[^'"]+\s+from\s+)?|export\s+(?:[^'"]+\s+from\s+)|import\s*\(\s*)["']([^"']+)["']/g
+
+function extractImports(source: string): string[] {
+  const out: string[] = []
+  let m: RegExpExecArray | null
+  while ((m = IMPORT_RE.exec(source)) !== null) {
+    out.push(m[1])
+  }
+  return out
+}
+
+function isAllowedSpecifier(spec: string): boolean {
+  if (NODE_BUILTINS.has(spec)) return true
+  return ALLOWED_IMPORT_PREFIXES.some((p) => spec === p || spec.startsWith(p))
+}
+
+function isForbiddenSpecifier(spec: string): boolean {
+  return FORBIDDEN_PREFIXES.some((p) => spec.startsWith(p))
+}
+
+function extractCoreModuleSubpath(spec: string): string | null {
+  const prefix = '@open-mercato/core/modules/'
+  if (!spec.startsWith(prefix)) return null
+  const rest = spec.slice(prefix.length)
+  const slash = rest.indexOf('/')
+  return slash === -1 ? rest : rest.slice(0, slash)
+}
+
+describe('@dainamite/billing package isolation', () => {
+  let allFiles: string[] = []
+  let importsByFile = new Map<string, string[]>()
+
+  beforeAll(async () => {
+    allFiles = await walk(PACKAGE_ROOT)
+    importsByFile = new Map()
+    for (const file of allFiles) {
+      const source = await fs.readFile(file, 'utf-8')
+      importsByFile.set(file, extractImports(source))
+    }
+  })
+
+  it('declares all required modules in metadata.requires', () => {
+    expect(metadata.requires).toEqual(
+      expect.arrayContaining(['auth', 'directory', 'dictionaries', 'configs', 'sales']),
+    )
+  })
+
+  it('does not import from sibling app modules', () => {
+    const violations: Array<{ file: string; spec: string }> = []
+    for (const [file, specs] of importsByFile) {
+      for (const spec of specs) {
+        if (isForbiddenSpecifier(spec)) {
+          violations.push({ file: path.relative(PACKAGE_ROOT, file), spec })
+        }
+      }
+    }
+    if (violations.length > 0) {
+      throw new Error(
+        `Forbidden cross-module imports found:\n${violations
+          .map((v) => `  ${v.file} → ${v.spec}`)
+          .join('\n')}`,
+      )
+    }
+  })
+
+  it('only uses allowed import prefixes (no surprise package leaks)', () => {
+    const violations: Array<{ file: string; spec: string }> = []
+    for (const [file, specs] of importsByFile) {
+      for (const spec of specs) {
+        if (!isAllowedSpecifier(spec)) {
+          violations.push({ file: path.relative(PACKAGE_ROOT, file), spec })
+        }
+      }
+    }
+    if (violations.length > 0) {
+      throw new Error(
+        `Imports outside the allowed prefix set:\n${violations
+          .map((v) => `  ${v.file} → ${v.spec}`)
+          .join('\n')}\n` +
+          `If a new prefix is legitimate, add it to ALLOWED_IMPORT_PREFIXES in this test.`,
+      )
+    }
+  })
+
+  it('only deep-imports from core modules declared in metadata.requires', () => {
+    const declared = new Set<string>(metadata.requires ?? [])
+    const violations: Array<{ file: string; spec: string; module: string }> = []
+    for (const [file, specs] of importsByFile) {
+      for (const spec of specs) {
+        const subModule = extractCoreModuleSubpath(spec)
+        if (subModule && !declared.has(subModule)) {
+          violations.push({ file: path.relative(PACKAGE_ROOT, file), spec, module: subModule })
+        }
+      }
+    }
+    if (violations.length > 0) {
+      throw new Error(
+        `Deep imports into @open-mercato/core/modules/<x> for modules not in metadata.requires:\n${violations
+          .map((v) => `  ${v.file} → ${v.spec} (add '${v.module}' to requires)`)
+          .join('\n')}`,
+      )
+    }
+  })
+
+  it('contains no @ManyToOne / @OneToMany / @ManyToMany / @OneToOne ORM relations', async () => {
+    const relRe = /@(ManyToOne|OneToMany|ManyToMany|OneToOne)\s*\(/g
+    const violations: Array<{ file: string; line: number; match: string }> = []
+    for (const file of allFiles) {
+      const source = await fs.readFile(file, 'utf-8')
+      const lines = source.split('\n')
+      lines.forEach((line, idx) => {
+        const m = line.match(relRe)
+        if (m) {
+          violations.push({ file: path.relative(PACKAGE_ROOT, file), line: idx + 1, match: m.join(', ') })
+        }
+      })
+    }
+    if (violations.length > 0) {
+      throw new Error(
+        `Cross-entity ORM relations forbidden in @dainamite/billing (use FK string columns):\n${violations
+          .map((v) => `  ${v.file}:${v.line} — ${v.match}`)
+          .join('\n')}`,
+      )
+    }
+  })
+
+  it('module index.ts loads without throwing', async () => {
+    const mod = await import('../index')
+    expect(mod.metadata).toBeDefined()
+    expect(mod.metadata.name).toBe('billing')
+    expect(mod.features).toBeDefined()
+    expect(Array.isArray(mod.features)).toBe(true)
+  })
+})

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

@@ -0,0 +1,107 @@
+/**
+ * Setup contract tests.
+ *
+ * These are structural tests on the exported `ModuleSetupConfig` — they
+ * verify the seed contract surface (role grants, callable hooks) without
+ * spinning up MikroORM. Behavioral idempotency of the dictionary / config
+ * seeds is exercised end-to-end via the integration suite once Phase 1
+ * lands a real REST API; the structural checks below catch the most
+ * common drift (missing role grant, deleted hook, wrong feature spelled
+ * differently from acl.ts).
+ */
+
+import { features } from '../acl'
+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')
+    expect(typeof setup.seedDefaults).toBe('function')
+  })
+
+  it('does not declare seedExamples (billing ships no demo data)', () => {
+    expect(setup.seedExamples).toBeUndefined()
+  })
+
+  it('grants the admin role the billing.* wildcard', () => {
+    expect(setup.defaultRoleFeatures?.admin).toEqual(['billing.*'])
+  })
+
+  it('billing_admin role gets every concrete billing feature', () => {
+    const grants = setup.defaultRoleFeatures?.billing_admin ?? []
+    for (const id of featureIds) {
+      expect(grants).toContain(id)
+    }
+  })
+
+  it('billing_finance_user is read-only + dry-run (no posting / no real trigger)', () => {
+    const grants = setup.defaultRoleFeatures?.billing_finance_user ?? []
+    // Read-only baseline
+    expect(grants).toEqual(
+      expect.arrayContaining([
+        'billing.account.view',
+        'billing.item.view',
+        'billing.usage.view',
+        'billing.run.view',
+        'billing.invoice.view',
+      ]),
+    )
+    // Dry-run preview is explicitly granted
+    expect(grants).toContain('billing.run.dry_run')
+    // …but not the real trigger / posting / editing
+    expect(grants).not.toContain('billing.run.trigger')
+    expect(grants).not.toContain('billing.invoice.post')
+    expect(grants).not.toContain('billing.invoice.edit_draft')
+    expect(grants).not.toContain('billing.usage.ingest')
+  })
+
+  it('billing_usage_writer is narrow scope: usage.ingest only', () => {
+    expect(setup.defaultRoleFeatures?.billing_usage_writer).toEqual(['billing.usage.ingest'])
+  })
+
+  it('every feature granted to any default role exists in acl.ts (no typos)', () => {
+    for (const [role, grants] of Object.entries(setup.defaultRoleFeatures ?? {})) {
+      for (const grant of grants ?? []) {
+        // Wildcards (`billing.*`) bypass the typo check by design.
+        if (grant.endsWith('.*')) continue
+        if (!featureIds.has(grant)) {
+          throw new Error(
+            `Role "${role}" grants unknown feature "${grant}" — not declared in acl.ts`,
+          )
+        }
+      }
+    }
+  })
+})
+
+describe('billing acl — surface', () => {
+  it('exports exactly 12 features per Phase 0 spec', () => {
+    expect(features).toHaveLength(12)
+  })
+
+  it('all feature IDs are prefixed `billing.` (no leaking module boundary)', () => {
+    for (const f of features) {
+      expect(f.id.startsWith('billing.')).toBe(true)
+      expect(f.module).toBe('billing')
+    }
+  })
+
+  it.each([
+    'billing.account.manage',
+    'billing.account.view',
+    'billing.item.manage',
+    'billing.item.view',
+    'billing.usage.ingest',
+    'billing.usage.view',
+    'billing.run.trigger',
+    'billing.run.dry_run',
+    'billing.run.view',
+    'billing.invoice.post',
+    'billing.invoice.edit_draft',
+    'billing.invoice.view',
+  ])('declares feature %s', (id) => {
+    expect(featureIds.has(id)).toBe(true)
+  })
+})