@dainamite/cpq-billing-connector 0.1.0

package/src/modules/cpq_billing_connector/__tests__/lib/prorationHelper.test.ts

@@ -0,0 +1,93 @@
+import {
+  computeProration,
+  formatProrationDescription,
+} from '../../lib/prorationHelper'
+
+describe('computeProration', () => {
+  it('canonical spec example: 29 EUR × 17/31 → 15.90 (Story 2)', () => {
+    const result = computeProration({
+      unitPrice: 29,
+      quantity: 1,
+      daysInPeriod: 31,
+      daysRemaining: 17,
+    })
+    // 29 × 17 / 31 = 15.903225… → 15.90
+    expect(result.amount).toBe(15.9)
+    expect(result.amountString).toBe('15.9000')
+  })
+
+  it('full-period proration equals full unit_price × quantity', () => {
+    const result = computeProration({
+      unitPrice: 49.99,
+      quantity: 2,
+      daysInPeriod: 30,
+      daysRemaining: 30,
+    })
+    expect(result.amount).toBe(99.98)
+  })
+
+  it('zero days remaining → zero amount', () => {
+    const result = computeProration({
+      unitPrice: 49,
+      quantity: 1,
+      daysInPeriod: 30,
+      daysRemaining: 0,
+    })
+    expect(result.amount).toBe(0)
+  })
+
+  it('rounds half-up to 2dp', () => {
+    // 1 × 1 × 1 / 200 = 0.005 → 0.01 (half-up)
+    const result = computeProration({
+      unitPrice: 1,
+      quantity: 1,
+      daysInPeriod: 200,
+      daysRemaining: 1,
+    })
+    expect(result.amount).toBe(0.01)
+    expect(result.amountString).toBe('0.0100')
+  })
+
+  it('defends against daysInPeriod === 0 (degenerate input)', () => {
+    const result = computeProration({
+      unitPrice: 49,
+      quantity: 1,
+      daysInPeriod: 0,
+      daysRemaining: 5,
+    })
+    expect(result.amount).toBe(0)
+  })
+
+  it('clamps negative daysRemaining to 0 (defensive)', () => {
+    const result = computeProration({
+      unitPrice: 49,
+      quantity: 1,
+      daysInPeriod: 30,
+      daysRemaining: -3,
+    })
+    expect(result.amount).toBe(0)
+  })
+
+  it('scales by quantity correctly', () => {
+    // 10 seats × 5 EUR × 15/30 = 25 EUR
+    const result = computeProration({
+      unitPrice: 5,
+      quantity: 10,
+      daysInPeriod: 30,
+      daysRemaining: 15,
+    })
+    expect(result.amount).toBe(25)
+  })
+})
+
+describe('formatProrationDescription', () => {
+  it('matches the spec example phrasing', () => {
+    expect(
+      formatProrationDescription({
+        productName: 'Package X',
+        effectiveDate: '2026-05-15',
+        cycleEnd: '2026-05-31',
+      }),
+    ).toBe('Proration: Package X from 2026-05-15 to 2026-05-31')
+  })
+})

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

@@ -0,0 +1,184 @@
+/**
+ * Package isolation guard for @dainamite/cpq-billing-connector.
+ *
+ * Mirrors the @dainamite/billing variant. Allowed import prefixes
+ * include `@dainamite/billing/...` since the connector imports
+ * billing's entity classes (BillingAccount, BillingItem) for
+ * read-side lookups — peer-dep, declared in package.json, fine.
+ */
+
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+
+import { metadata } from '../index'
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..')
+
+const ALLOWED_IMPORT_PREFIXES = [
+  './',
+  '../',
+  '@open-mercato/',
+  '@mikro-orm/',
+  '@dainamite/',
+  'awilix',
+  'lucide-react',
+  'next',
+  'next/',
+  'react',
+  'react/',
+  'react-dom',
+  'react-dom/',
+  'zod',
+  'node:',
+]
+
+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/',
+  '../../../../auth/',
+  '../../../../directory/',
+  '../../../../demo_',
+  '../../../../portal/',
+  '../../../../customer_accounts/',
+  '../../../../example/',
+]
+
+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))
+}
+
+describe('@dainamite/cpq-billing-connector 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('metadata.requires lists cpq + billing (peer-dep modules)', () => {
+    expect(metadata.requires).toEqual(
+      expect.arrayContaining(['cpq', 'billing']),
+    )
+  })
+
+  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:\n${violations
+          .map((v) => `  ${v.file} → ${v.spec}`)
+          .join('\n')}`,
+      )
+    }
+  })
+
+  it('only uses allowed import prefixes', () => {
+    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')}`,
+      )
+    }
+  })
+
+  it('contains no ORM relations (FK string only, peer-dep contract)', async () => {
+    const relRe = /@(ManyToOne|OneToMany|ManyToMany|OneToOne)\s*\(/g
+    const violations: Array<{ file: string; line: number }> = []
+    for (const file of allFiles) {
+      const source = await fs.readFile(file, 'utf-8')
+      const lines = source.split('\n')
+      lines.forEach((line, idx) => {
+        if (line.match(relRe)) {
+          violations.push({ file: path.relative(PACKAGE_ROOT, file), line: idx + 1 })
+        }
+      })
+    }
+    if (violations.length > 0) {
+      throw new Error(
+        `Cross-entity ORM relations forbidden in connector:\n${violations
+          .map((v) => `  ${v.file}:${v.line}`)
+          .join('\n')}`,
+      )
+    }
+  })
+
+  it('module index.ts loads without throwing', async () => {
+    const mod = await import('../index')
+    expect(mod.metadata).toBeDefined()
+    expect(mod.metadata.name).toBe('cpq_billing_connector')
+    expect(mod.features).toBeDefined()
+  })
+})

package/src/modules/cpq_billing_connector/acl.ts

@@ -0,0 +1,12 @@
+/**
+ * The connector is plumbing — it executes work in response to CPQ
+ * events on the system's authority, not on a user's request. There
+ * are therefore no operator-facing actions to gate at this layer.
+ *
+ * A future "manually replay CPQ events for subscription X" admin
+ * feature (Phase 4b backstop for ops emergencies) would declare a
+ * feature here.
+ */
+export const features = [] as const
+
+export default features

package/src/modules/cpq_billing_connector/ce.ts

@@ -0,0 +1,6 @@
+import type { CustomEntitySpec } from '@open-mercato/shared/modules/entities'
+
+const entities: CustomEntitySpec[] = []
+
+export { entities }
+export default entities

package/src/modules/cpq_billing_connector/di.ts

@@ -0,0 +1,12 @@
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+
+/**
+ * No DI registrations — the connector resolves billing's command bus
+ * + dependencies from the host container at subscriber invocation
+ * time. Kept as a no-op so the generator picks `cpq_billing_connector`
+ * up as a DI-aware module without surprises when registrations land
+ * in a later phase.
+ */
+export function register(_container: AppContainer): void {
+  // intentionally empty
+}

package/src/modules/cpq_billing_connector/index.ts

@@ -0,0 +1,20 @@
+import type { ModuleInfo } from '@open-mercato/shared/modules/registry'
+
+export const metadata: ModuleInfo = {
+  name: 'cpq_billing_connector',
+  title: 'CPQ → Billing Connector',
+  version: '0.1.0',
+  description:
+    'Wires @dainamite/cpq subscription lifecycle events to @dainamite/billing API calls. ' +
+    'Owns proration math (CPQ stays neutral on billing calendar semantics).',
+  author: 'Dainamite',
+  license: 'MIT',
+  // `requires` lists every module whose data we read (directly or via
+  // command-bus calls). The connector itself stores no entities — it's
+  // pure plumbing — but it does call billing's command bus + needs CPQ
+  // events to fire.
+  requires: ['cpq', 'billing', 'auth', 'directory'],
+  ejectable: false,
+}
+
+export { features } from './acl'

package/src/modules/cpq_billing_connector/lib/billingApiClient.ts

@@ -0,0 +1,215 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AwilixContainer } from 'awilix'
+import type { CommandBus } from '@open-mercato/shared/lib/commands/command-bus'
+// TODO(L2-boundary): direct entity-class import couples the connector to
+// billing's internal ORM shape — violates the dainamite-layering rule that
+// cross-package coupling should be FK strings or REST. Tolerable at v0.1.x
+// because reads are em-driven for performance (one round-trip vs serialise/
+// deserialise via REST), but a `BillingAccount` / `BillingItem` rename in
+// `@dainamite/billing` will manifest here as a silent runtime crash.
+// Migrate to billing REST list endpoints once the connector graduates to
+// stable v1 — track in the dainamite-cpq packaging plan.
+import { BillingAccount, BillingItem } from '@dainamite/billing/modules/billing/data/entities'
+
+/**
+ * Thin facade the connector uses to talk to billing.
+ *
+ * Reads (existence checks, lookups by subscription) go through the
+ * EM directly — billing's REST list endpoints would work, but going
+ * via the EM is one round-trip instead of a serialize-then-deserialize
+ * loop. Writes go through the billing command bus exclusively, so
+ * there is one and only one write path for every billing state
+ * mutation (the same path the REST routes invoke).
+ *
+ * Auth context: subscribers run as a system identity, not as a user.
+ * The command-bus `ctx` therefore carries `auth: null` and the
+ * tenant/organization explicitly. `ensureTenantScope` /
+ * `ensureOrganizationScope` are no-ops when `ctx.auth` is null
+ * (verified against `@open-mercato/shared/lib/commands/scope`) so
+ * the explicit fields in the payload are the authority.
+ */
+
+export type Scope = {
+  tenantId: string
+  organizationId: string
+}
+
+export type AccountSeed = {
+  customerId: string
+  name: string
+  currencyCode: string
+  billCycle: 'monthly' | 'quarterly' | 'annually' | 'weekly'
+  billCycleAnchor: string
+  invoiceEmail: string
+  invoiceLanguage: string
+  invoiceAddress: Record<string, unknown>
+  nextBillDate: Date
+  taxId?: string | null
+}
+
+export type ItemCreatePayload = {
+  billAccountId: string
+  type: 'one_time' | 'recurring' | 'usage'
+  billStartDate: Date | string
+  billEndDate?: Date | string | null
+  description: string
+  rateJson: Record<string, unknown>
+  uomCode?: string
+  subscriptionId?: string
+  subscriptionItemId?: string
+  sourceRef?: string
+}
+
+export type ItemUpdatePayload = {
+  id: string
+  billEndDate?: Date | string | null
+  subscriptionId?: string | null
+  subscriptionItemId?: string | null
+  isActive?: boolean
+}
+
+function buildSystemCtx(container: AwilixContainer, scope: Scope) {
+  return {
+    container,
+    auth: null,
+    organizationScope: null,
+    selectedOrganizationId: scope.organizationId,
+    organizationIds: [scope.organizationId],
+  }
+}
+
+export class BillingApiClient {
+  private readonly em: EntityManager
+  private readonly commandBus: CommandBus
+
+  constructor(private readonly container: AwilixContainer) {
+    this.em = (container.resolve('em') as EntityManager).fork()
+    this.commandBus = container.resolve('commandBus') as CommandBus
+  }
+
+  // ─── Accounts ───────────────────────────────────────────────────
+
+  /**
+   * Find a non-deleted Billing Account for `(tenant, organization,
+   * customer)`. Returns the first match or `null`. The connector
+   * uses this to skip account creation when the customer already
+   * has one.
+   */
+  async findAccountByCustomer(scope: Scope, customerId: string): Promise<BillingAccount | null> {
+    return this.em.findOne(BillingAccount, {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      customerId,
+      deletedAt: null,
+    })
+  }
+
+  async createAccount(scope: Scope, seed: AccountSeed): Promise<{ id: string }> {
+    const result = await this.commandBus.execute('billing.accounts.create', {
+      input: {
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        ...seed,
+      },
+      ctx: buildSystemCtx(this.container, scope),
+    })
+    return (result as { result?: { id: string } }).result ?? { id: '' }
+  }
+
+  async getOrCreateAccount(scope: Scope, seed: AccountSeed): Promise<{ id: string; created: boolean }> {
+    const existing = await this.findAccountByCustomer(scope, seed.customerId)
+    if (existing) return { id: existing.id, created: false }
+    const created = await this.createAccount(scope, seed)
+    return { id: created.id, created: true }
+  }
+
+  // ─── Items ──────────────────────────────────────────────────────
+
+  async findItemsBySubscription(scope: Scope, subscriptionId: string): Promise<BillingItem[]> {
+    return this.em.find(BillingItem, {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      subscriptionId,
+      deletedAt: null,
+    } as never)
+  }
+
+  async findItemsBySubscriptionItem(
+    scope: Scope,
+    subscriptionItemId: string,
+  ): Promise<BillingItem[]> {
+    return this.em.find(BillingItem, {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      subscriptionItemId,
+      deletedAt: null,
+    } as never)
+  }
+
+  async createItem(
+    scope: Scope,
+    payload: ItemCreatePayload,
+  ): Promise<{ id: string; deduplicated: boolean }> {
+    const result = await this.commandBus.execute('billing.items.create', {
+      input: {
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        ...payload,
+      },
+      ctx: buildSystemCtx(this.container, scope),
+    })
+    const r = (result as { result?: { id: string; deduplicated: boolean } }).result
+    return r ?? { id: '', deduplicated: false }
+  }
+
+  /**
+   * Batch-create items in a single `billing.items.bulk_create`
+   * command. Use this whenever a subscriber has more than one item
+   * to create — it collapses N command-bus round-trips + N flushes
+   * into one. Idempotent per `source_ref` exactly like `createItem`.
+   *
+   * No-ops on an empty payload so callers skip the length guard.
+   */
+  async bulkCreateItems(
+    scope: Scope,
+    items: ItemCreatePayload[],
+  ): Promise<{
+    created: number
+    deduplicated: number
+    items: Array<{ sourceRef: string | null; id: string; deduplicated: boolean }>
+  }> {
+    if (items.length === 0) {
+      return { created: 0, deduplicated: 0, items: [] }
+    }
+    const result = await this.commandBus.execute('billing.items.bulk_create', {
+      input: {
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        items,
+      },
+      ctx: buildSystemCtx(this.container, scope),
+    })
+    const r = (
+      result as {
+        result?: {
+          created: number
+          deduplicated: number
+          items: Array<{ sourceRef: string | null; id: string; deduplicated: boolean }>
+        }
+      }
+    ).result
+    return r ?? { created: 0, deduplicated: 0, items: [] }
+  }
+
+  async updateItem(scope: Scope, payload: ItemUpdatePayload): Promise<{ id: string }> {
+    const result = await this.commandBus.execute('billing.items.update', {
+      input: {
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        ...payload,
+      },
+      ctx: buildSystemCtx(this.container, scope),
+    })
+    return (result as { result?: { id: string } }).result ?? { id: '' }
+  }
+}

package/src/modules/cpq_billing_connector/lib/chargeMapper.ts

@@ -0,0 +1,120 @@
+/**
+ * CPQ charge → billing item create payload mapping.
+ *
+ * CPQ subscription events carry an `items[].charges[]` array where
+ * each charge has `type: 'one_time' | 'recurring'`, an optional
+ * `amount` (for one-time) or `unitPrice` (for recurring), and a
+ * description. This module turns each charge into the
+ * `billing.items.create` payload shape (one Billing Item per charge,
+ * not per CPQ subscription item — per the spec: "If a CPQ
+ * subscription item has both a one-time charge … and a recurring
+ * charge …, the connector creates two separate Billing Items").
+ *
+ * `sourceRef` is built deterministically:
+ *   `cpq-<subscriptionId>-<subscriptionItemId>-<charge.type>`
+ * so re-firing the same activation event hits the `(tenant_id,
+ * bill_account_id, source_ref)` unique constraint and the duplicate
+ * is dropped with `deduplicated: true` instead of creating a second
+ * item.
+ */
+
+export type CpqChargeType = 'one_time' | 'recurring'
+
+export type CpqCharge = {
+  type: CpqChargeType
+  amount?: number
+  unitPrice?: number
+  description: string
+}
+
+export type CpqSubscriptionItem = {
+  subscriptionItemId: string
+  productName: string
+  quantity: number
+  charges: CpqCharge[]
+}
+
+export type BillingItemPayload = {
+  type: CpqChargeType
+  description: string
+  rateJson: { amount: number } | { unit_price: number }
+  subscriptionId: string
+  subscriptionItemId: string
+  sourceRef: string
+  billStartDate: string
+}
+
+export function buildSourceRef(
+  subscriptionId: string,
+  subscriptionItemId: string,
+  chargeType: CpqChargeType,
+): string {
+  return `cpq-${subscriptionId}-${subscriptionItemId}-${chargeType}`
+}
+
+/**
+ * Map a single CPQ charge to a billing.items.create payload.
+ * Returns `null` if the charge is missing the required price field
+ * for its type — surfaces malformed CPQ payloads to the subscriber
+ * which can log + skip instead of crashing.
+ */
+export function mapChargeToBillingItem(params: {
+  subscriptionId: string
+  subscriptionItem: CpqSubscriptionItem
+  charge: CpqCharge
+  /** YYYY-MM-DD; typically the subscription activation date. */
+  billStartDate: string
+}): BillingItemPayload | null {
+  const { subscriptionId, subscriptionItem, charge, billStartDate } = params
+
+  if (charge.type === 'one_time') {
+    if (typeof charge.amount !== 'number') return null
+    return {
+      type: 'one_time',
+      description: `${subscriptionItem.productName} — ${charge.description}`,
+      rateJson: { amount: charge.amount },
+      subscriptionId,
+      subscriptionItemId: subscriptionItem.subscriptionItemId,
+      sourceRef: buildSourceRef(subscriptionId, subscriptionItem.subscriptionItemId, 'one_time'),
+      billStartDate,
+    }
+  }
+
+  // recurring
+  if (typeof charge.unitPrice !== 'number') return null
+  return {
+    type: 'recurring',
+    description: `${subscriptionItem.productName} — ${charge.description}`,
+    rateJson: { unit_price: charge.unitPrice },
+    subscriptionId,
+    subscriptionItemId: subscriptionItem.subscriptionItemId,
+    sourceRef: buildSourceRef(subscriptionId, subscriptionItem.subscriptionItemId, 'recurring'),
+    billStartDate,
+  }
+}
+
+/**
+ * Map every charge on every subscription item in a CPQ payload to
+ * billing item payloads. Skips charges that fail the per-charge
+ * mapping (returns `null`) — the connector logs those rather than
+ * partially-failing the whole event.
+ */
+export function mapSubscriptionItemsToBillingItems(params: {
+  subscriptionId: string
+  items: CpqSubscriptionItem[]
+  billStartDate: string
+}): BillingItemPayload[] {
+  const out: BillingItemPayload[] = []
+  for (const item of params.items) {
+    for (const charge of item.charges) {
+      const mapped = mapChargeToBillingItem({
+        subscriptionId: params.subscriptionId,
+        subscriptionItem: item,
+        charge,
+        billStartDate: params.billStartDate,
+      })
+      if (mapped) out.push(mapped)
+    }
+  }
+  return out
+}