@dainamite/billing 0.17.0

package/src/modules/billing/cli.ts

@@ -0,0 +1,89 @@
+import type { ModuleCli } from '@open-mercato/shared/modules/registry'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { seedBillingDemo } from './lib/seeds/demo'
+
+/**
+ * `mercato billing seed [--reset] [--tenant <id>] [--org <id>]`
+ *
+ * Loads self-contained billing test data (demo accounts + recurring/usage
+ * items + an unrated usage record) into a single tenant. With no `--tenant`/
+ * `--org`, it resolves the first (primary) organization created by
+ * `mercato init`. `--reset` clears the seed's own rows first.
+ */
+
+function parseArgs(rest: string[]): Record<string, string | boolean> {
+  const out: Record<string, string | boolean> = {}
+  for (let i = 0; i < rest.length; i++) {
+    const token = rest[i]
+    if (!token || !token.startsWith('--')) continue
+    const key = token.slice(2)
+    const next = rest[i + 1]
+    if (next === undefined || next.startsWith('--')) out[key] = true
+    else {
+      out[key] = next
+      i++
+    }
+  }
+  return out
+}
+
+async function resolveScope(
+  em: EntityManager,
+  args: Record<string, string | boolean>,
+): Promise<{ tenantId: string; organizationId: string } | null> {
+  const orgArg = typeof args.org === 'string' ? args.org : undefined
+  const tenantArg = typeof args.tenant === 'string' ? args.tenant : undefined
+
+  const { Organization } = await import('@open-mercato/core/modules/directory/data/entities')
+
+  if (orgArg) {
+    const org = await em.findOne(Organization, { id: orgArg } as never)
+    if (!org) return null
+    return { organizationId: org.id, tenantId: tenantArg ?? org.tenant.id }
+  }
+
+  const orgs = await em.find(
+    Organization,
+    { isActive: true } as never,
+    { orderBy: { createdAt: 'asc' } as never, limit: 5 },
+  )
+  if (orgs.length === 0) return null
+  const org = orgs[0]
+  if (orgs.length > 1) {
+    console.warn(
+      `[billing seed] Multiple organizations found — defaulting to "${org.name}" (${org.id}). ` +
+        `Pass --org <id> to target another.`,
+    )
+  }
+  return { organizationId: org.id, tenantId: tenantArg ?? org.tenant.id }
+}
+
+const seed: ModuleCli = {
+  command: 'seed',
+  async run(rest) {
+    const args = parseArgs(rest)
+    const reset = Boolean(args.reset)
+
+    const container = await createRequestContainer()
+    const em = container.resolve<EntityManager>('em')
+
+    const scope = await resolveScope(em, args)
+    if (!scope) {
+      console.error(
+        '[billing seed] No organization found. Run "yarn initialize" first, or pass --org <id>.',
+      )
+      return
+    }
+
+    const res = await seedBillingDemo(em, scope, { reset })
+    console.log(
+      `[billing seed] tenant=${scope.tenantId} org=${scope.organizationId}${reset ? ' (reset)' : ''}\n` +
+        `  ✓ accounts +${res.accountsCreated}, items +${res.itemsCreated}, usage +${res.usageCreated} ` +
+        `(existing rows left untouched)\n` +
+        `  → Bill Runs · New run · As-of = today · Real → invoice for the previous month.`,
+    )
+  },
+}
+
+export default [seed]

package/src/modules/billing/commands/accounts.ts

@@ -0,0 +1,205 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandHandler, CommandRuntimeContext } from '@open-mercato/shared/lib/commands/types'
+import { registerCommand } from '@open-mercato/shared/lib/commands'
+import {
+  ensureOrganizationScope,
+  ensureTenantScope,
+} from '@open-mercato/shared/lib/commands/scope'
+import {
+  emitCrudSideEffects,
+  requireId,
+} from '@open-mercato/shared/lib/commands/helpers'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
+import { BillingAccount } from '../data/entities'
+import { billingEntityIds } from '../data/entityIds'
+import {
+  billingAccountCreateSchema,
+  billingAccountDeleteSchema,
+  billingAccountUpdateSchema,
+  type BillingAccountCreateInput,
+  type BillingAccountDeleteInput,
+  type BillingAccountUpdateInput,
+} from '../data/validators'
+
+/**
+ * BillingAccount writes — create / update / soft-delete.
+ *
+ * Phase 1 keeps the command surface lean — no undo / snapshot / audit
+ * log. Phase 4 (admin UI + posting flow) revisits to add operator-driven
+ * undo. The patterns to add:
+ *   - `prepare`: capture BEFORE snapshot for update / delete
+ *   - `captureAfter`: capture AFTER snapshot
+ *   - `buildLog`: emit a structured audit log entry
+ *   - `undo`: restore from snapshots + reverse side effects
+ * See `node_modules/@open-mercato/core/src/modules/customers/commands/people.ts`
+ * for the canonical full-feature shape.
+ */
+
+const accountIndexer = { entityType: billingEntityIds.account } as const
+const accountEvents = { module: 'billing', entity: 'account', persistent: true } as const
+
+function getEm(ctx: CommandRuntimeContext): EntityManager {
+  return (ctx.container.resolve('em') as EntityManager).fork()
+}
+
+function getDataEngine(ctx: CommandRuntimeContext): DataEngine {
+  return ctx.container.resolve('dataEngine') as DataEngine
+}
+
+// ─── Create ──────────────────────────────────────────────────────
+
+const createAccountCommand: CommandHandler<BillingAccountCreateInput, { id: string }> = {
+  id: 'billing.accounts.create',
+
+  async execute(rawInput, ctx) {
+    const parsed = billingAccountCreateSchema.parse(rawInput)
+    ensureTenantScope(ctx, parsed.tenantId)
+    ensureOrganizationScope(ctx, parsed.organizationId)
+
+    const em = getEm(ctx)
+    const now = new Date()
+    const entity = em.create(BillingAccount, {
+      organizationId: parsed.organizationId,
+      tenantId: parsed.tenantId,
+      customerId: parsed.customerId,
+      name: parsed.name,
+      currencyCode: parsed.currencyCode,
+      billCycle: parsed.billCycle,
+      billCycleAnchor: parsed.billCycleAnchor,
+      invoiceEmail: parsed.invoiceEmail,
+      invoiceLanguage: parsed.invoiceLanguage,
+      taxId: parsed.taxId ?? null,
+      invoiceAddress: parsed.invoiceAddress as Record<string, unknown>,
+      nextBillDate: parsed.nextBillDate,
+      lastBillDate: parsed.lastBillDate ?? null,
+      isActive: parsed.isActive ?? true,
+      createdAt: now,
+      updatedAt: now,
+    })
+    em.persist(entity)
+    await em.flush()
+
+    await emitCrudSideEffects({
+      dataEngine: getDataEngine(ctx),
+      action: 'created',
+      entity,
+      identifiers: {
+        id: entity.id,
+        tenantId: entity.tenantId,
+        organizationId: entity.organizationId,
+      },
+      indexer: accountIndexer,
+      events: accountEvents,
+    })
+
+    return { id: entity.id }
+  },
+}
+
+// ─── Update ──────────────────────────────────────────────────────
+
+const updateAccountCommand: CommandHandler<BillingAccountUpdateInput, { id: string }> = {
+  id: 'billing.accounts.update',
+
+  async execute(rawInput, ctx) {
+    const parsed = billingAccountUpdateSchema.parse(rawInput)
+    ensureTenantScope(ctx, parsed.tenantId)
+    ensureOrganizationScope(ctx, parsed.organizationId)
+
+    const em = getEm(ctx)
+    const record = await em.findOne(BillingAccount, {
+      id: parsed.id,
+      tenantId: parsed.tenantId,
+      organizationId: parsed.organizationId,
+      deletedAt: null,
+    })
+    if (!record) {
+      throw new CrudHttpError(404, { error: 'Billing account not found' })
+    }
+
+    if (parsed.name !== undefined) record.name = parsed.name
+    if (parsed.billCycle !== undefined) record.billCycle = parsed.billCycle
+    if (parsed.billCycleAnchor !== undefined) record.billCycleAnchor = parsed.billCycleAnchor
+    if (parsed.invoiceEmail !== undefined) record.invoiceEmail = parsed.invoiceEmail
+    if (parsed.invoiceLanguage !== undefined) record.invoiceLanguage = parsed.invoiceLanguage
+    if (parsed.taxId !== undefined) record.taxId = parsed.taxId
+    if (parsed.invoiceAddress !== undefined) {
+      record.invoiceAddress = parsed.invoiceAddress as Record<string, unknown>
+    }
+    if (parsed.nextBillDate !== undefined) record.nextBillDate = parsed.nextBillDate
+    if (parsed.lastBillDate !== undefined) record.lastBillDate = parsed.lastBillDate
+    if (parsed.isActive !== undefined) record.isActive = parsed.isActive
+
+    record.updatedAt = new Date()
+    await em.flush()
+
+    await emitCrudSideEffects({
+      dataEngine: getDataEngine(ctx),
+      action: 'updated',
+      entity: record,
+      identifiers: {
+        id: record.id,
+        tenantId: record.tenantId,
+        organizationId: record.organizationId,
+      },
+      indexer: accountIndexer,
+      events: accountEvents,
+    })
+
+    return { id: record.id }
+  },
+}
+
+// ─── Delete (soft) ───────────────────────────────────────────────
+
+const deleteAccountCommand: CommandHandler<BillingAccountDeleteInput, { id: string }> = {
+  id: 'billing.accounts.delete',
+
+  async execute(rawInput, ctx) {
+    const parsed = billingAccountDeleteSchema.parse(rawInput)
+    ensureTenantScope(ctx, parsed.tenantId)
+    ensureOrganizationScope(ctx, parsed.organizationId)
+    const id = requireId(parsed)
+
+    const em = getEm(ctx)
+    const record = await em.findOne(BillingAccount, {
+      id,
+      tenantId: parsed.tenantId,
+      organizationId: parsed.organizationId,
+      deletedAt: null,
+    })
+    if (!record) {
+      throw new CrudHttpError(404, { error: 'Billing account not found' })
+    }
+
+    record.deletedAt = new Date()
+    record.updatedAt = record.deletedAt
+    await em.flush()
+
+    await emitCrudSideEffects({
+      dataEngine: getDataEngine(ctx),
+      action: 'deleted',
+      entity: record,
+      identifiers: {
+        id: record.id,
+        tenantId: record.tenantId,
+        organizationId: record.organizationId,
+      },
+      indexer: accountIndexer,
+      events: accountEvents,
+    })
+
+    return { id: record.id }
+  },
+}
+
+registerCommand(createAccountCommand)
+registerCommand(updateAccountCommand)
+registerCommand(deleteAccountCommand)
+
+export {
+  createAccountCommand,
+  updateAccountCommand,
+  deleteAccountCommand,
+}

package/src/modules/billing/commands/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Billing module command registry.
+ *
+ * Each file below side-effect-registers its commands via
+ * `registerCommand(...)` from `@open-mercato/shared/lib/commands`.
+ * Importing this barrel forces the registrations to run. The CRUD
+ * factory's `commandId` lookups then resolve at request time.
+ */
+import './accounts'
+import './items'
+import './usage'
+import './runs'
+import './invoices'