@dainamite/cpq 0.2.2

package/src/modules/cpq/di.ts

@@ -0,0 +1,70 @@
+import { asFunction } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import type { SalesDocumentNumberGenerator } from '@open-mercato/core/modules/sales/services/salesDocumentNumberGenerator'
+import { DefaultCpqPricingService } from './services/cpqPricingService'
+import { DefaultCpqValidationService } from './services/cpqValidationService'
+import { DefaultCpqProductService } from './services/cpqProductService'
+import { DefaultCpqQuotingService } from './services/cpqQuotingService'
+import { DefaultCpqWizardService } from './services/cpqWizardService'
+import { DefaultCpqInventoryService } from './services/cpqInventoryService'
+import { DefaultCpqOrderService } from './services/cpqOrderService'
+import { DefaultCpqBundleService } from './services/cpqBundleService'
+
+/**
+ * Resolve dependencies from the container closure rather than via destructured
+ * factory parameters.  The container uses InjectionMode.CLASSIC, and Turbopack
+ * transpiles destructured arrow functions in a way that breaks Awilix's
+ * parameter-name parser.  Core modules are unaffected because they ship
+ * pre-compiled in node_modules.
+ */
+export function register(container: AppContainer) {
+  container.register({
+    cpqPricingService: asFunction(({ em }: { em: EntityManager }) => {
+      return new DefaultCpqPricingService(em)
+    }).scoped().proxy(),
+    cpqValidationService: asFunction(({ em }: { em: EntityManager }) => {
+      return new DefaultCpqValidationService(em)
+    }).scoped().proxy(),
+    cpqProductService: asFunction(({ em }: { em: EntityManager }) => {
+      return new DefaultCpqProductService(em)
+    }).scoped().proxy(),
+    cpqQuotingService: asFunction(({
+      em,
+      cpqPricingService,
+      cpqValidationService,
+      cpqProductService,
+      salesDocumentNumberGenerator,
+    }: {
+      em: EntityManager
+      cpqPricingService: DefaultCpqPricingService
+      cpqValidationService: DefaultCpqValidationService
+      cpqProductService: DefaultCpqProductService
+      salesDocumentNumberGenerator: SalesDocumentNumberGenerator
+    }) => {
+      return new DefaultCpqQuotingService({
+        em: container.resolve('em'),
+        cpqPricingService: container.resolve('cpqPricingService'),
+        cpqValidationService: container.resolve('cpqValidationService'),
+        cpqProductService: container.resolve('cpqProductService'),
+        salesDocumentNumberGenerator: container.resolve('salesDocumentNumberGenerator'),
+      })
+    }).scoped().proxy(),
+    cpqInventoryService: asFunction(() => {
+      return new DefaultCpqInventoryService(container.resolve('em'))
+    }).scoped(),
+    cpqOrderService: asFunction(() => {
+      return new DefaultCpqOrderService({
+        em: container.resolve('em'),
+        cpqInventoryService: container.resolve('cpqInventoryService'),
+        salesDocumentNumberGenerator: container.resolve('salesDocumentNumberGenerator'),
+      })
+    }).scoped(),
+    cpqWizardService: asFunction(({ em }: { em: EntityManager }) => {
+      return new DefaultCpqWizardService(em)
+    }).scoped().proxy(),
+    cpqBundleService: asFunction(() => {
+      return new DefaultCpqBundleService(container.resolve('em'))
+    }).scoped(),
+  })
+}

package/src/modules/cpq/events.ts

@@ -0,0 +1,62 @@
+import { createModuleEvents } from '@open-mercato/shared/modules/events'
+
+/**
+ * CPQ Module Events.
+ *
+ * Currently only the XD-250 ARC (Amend / Renew / Cancel) lifecycle events
+ * are declared here. Downstream modules (billing, notifications) subscribe
+ * to these to react to subscription mutations driven by CPQ orders.
+ *
+ * Emission rule: events fire AFTER the activation transaction commits.
+ * `cpqOrderService.activateOrder` is the sole emitter site.
+ */
+const events = [
+  {
+    id: 'cpq.subscription.amended',
+    label: 'Subscription Amended',
+    entity: 'subscription',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
+  {
+    id: 'cpq.subscription.renewed',
+    label: 'Subscription Renewed',
+    entity: 'subscription',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
+  {
+    id: 'cpq.subscription.merged',
+    label: 'Subscription Merged',
+    entity: 'subscription',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
+  {
+    id: 'cpq.subscription.cancelled',
+    label: 'Subscription Cancelled',
+    entity: 'subscription',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
+  {
+    id: 'cpq.subscription.superseded',
+    label: 'Subscription Superseded',
+    entity: 'subscription',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
+] as const
+
+export const eventsConfig = createModuleEvents({
+  moduleId: 'cpq',
+  events,
+})
+
+/** Type-safe event emitter for the CPQ module. */
+export const emitCpqEvent = eventsConfig.emit
+
+/** Event IDs that can be emitted by the CPQ module. */
+export type CpqEventId = (typeof events)[number]['id']
+
+export default eventsConfig

package/src/modules/cpq/index.ts

@@ -0,0 +1,15 @@
+import type { ModuleInfo } from '@open-mercato/shared/modules/registry'
+
+export const metadata: ModuleInfo = {
+  name: 'cpq',
+  title: 'Configure, Price, Quote',
+  version: '0.1.0',
+  description:
+    'Generic CPQ engine — configurable product attributes, multi-charge pricing tables, and guided quoting flows.',
+  author: 'App',
+  license: 'Proprietary',
+  requires: ['auth', 'directory', 'catalog', 'sales', 'customers', 'dictionaries'],
+  ejectable: false,
+}
+
+export { features } from './acl'

package/src/modules/cpq/lib/seeds/__tests__/api.test.ts

@@ -0,0 +1,86 @@
+import {
+  registerCpqUseCase,
+  listCpqUseCases,
+  getCpqUseCase,
+  clearCpqUseCases,
+  type CpqUseCase,
+} from '../api'
+
+const buildUseCase = (id: string, overrides: Partial<CpqUseCase> = {}): CpqUseCase => ({
+  id,
+  tenant: {
+    slug: id,
+    tenantName: `${id} Tenant`,
+    adminEmail: `admin@${id}.com`,
+    adminPassword: 'secret',
+  },
+  seedDefaults: jest.fn(async () => undefined),
+  ...overrides,
+})
+
+describe('cpq seed registry', () => {
+  beforeEach(() => clearCpqUseCases())
+
+  it('registers and lists a use case', () => {
+    const uc = buildUseCase('gix')
+    registerCpqUseCase(uc)
+    expect(listCpqUseCases()).toEqual([uc])
+    expect(getCpqUseCase('gix')).toBe(uc)
+  })
+
+  it('preserves registration order across multiple use cases', () => {
+    const a = buildUseCase('alpha')
+    const b = buildUseCase('beta')
+    const c = buildUseCase('gamma')
+    registerCpqUseCase(a)
+    registerCpqUseCase(b)
+    registerCpqUseCase(c)
+    expect(listCpqUseCases().map((u) => u.id)).toEqual(['alpha', 'beta', 'gamma'])
+  })
+
+  it('returns undefined for unknown ids', () => {
+    expect(getCpqUseCase('does-not-exist')).toBeUndefined()
+  })
+
+  it('overwrites and warns on duplicate id (HMR-friendly)', () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const first = buildUseCase('gix')
+    const second = buildUseCase('gix')
+    registerCpqUseCase(first)
+    registerCpqUseCase(second)
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('"gix"'))
+    expect(listCpqUseCases()).toEqual([second])
+    expect(getCpqUseCase('gix')).toBe(second)
+    warn.mockRestore()
+  })
+
+  it('rejects use cases with no id', () => {
+    expect(() => registerCpqUseCase(buildUseCase('') as CpqUseCase)).toThrow(/id is required/)
+  })
+
+  it('rejects use cases without an admin email', () => {
+    const broken: CpqUseCase = {
+      id: 'gix',
+      // @ts-expect-error — exercising the runtime guard
+      tenant: { slug: 'gix', tenantName: 'GIX', adminPassword: 'secret' },
+      seedDefaults: jest.fn(),
+    }
+    expect(() => registerCpqUseCase(broken)).toThrow(/adminEmail/)
+  })
+
+  it('rejects use cases without seedDefaults', () => {
+    const broken = {
+      id: 'gix',
+      tenant: { slug: 'gix', tenantName: 'GIX', adminEmail: 'admin@gix.com', adminPassword: 'secret' },
+    } as unknown as CpqUseCase
+    expect(() => registerCpqUseCase(broken)).toThrow(/seedDefaults/)
+  })
+
+  it('clearCpqUseCases empties the registry', () => {
+    registerCpqUseCase(buildUseCase('gix'))
+    registerCpqUseCase(buildUseCase('puffin'))
+    expect(listCpqUseCases()).toHaveLength(2)
+    clearCpqUseCases()
+    expect(listCpqUseCases()).toHaveLength(0)
+  })
+})

package/src/modules/cpq/lib/seeds/__tests__/tenant-provisioning.test.ts

@@ -0,0 +1,349 @@
+import type { CpqUseCaseTenantSpec } from '../api'
+
+jest.mock('@open-mercato/core/modules/auth/lib/setup-app', () => ({
+  setupInitialTenant: jest.fn(),
+}))
+
+jest.mock('@open-mercato/shared/lib/encryption/find', () => ({
+  findOneWithDecryption: jest.fn(),
+}))
+
+jest.mock('@open-mercato/core/modules/auth/data/entities', () => ({
+  User: class FakeUser {},
+  Role: class FakeRole {},
+  UserRole: class FakeUserRole {},
+}))
+
+jest.mock('@open-mercato/core/modules/auth/lib/emailHash', () => ({
+  computeEmailHash: (email: string) => `hash:${email}`,
+}))
+
+jest.mock('@open-mercato/shared/lib/encryption/toggles', () => ({
+  isTenantDataEncryptionEnabled: () => false,
+}))
+
+jest.mock('@open-mercato/shared/lib/encryption/tenantDataEncryptionService', () => ({
+  TenantDataEncryptionService: class {},
+}))
+
+jest.mock('@open-mercato/shared/lib/encryption/kms', () => ({
+  createKmsService: () => ({}),
+}))
+
+jest.mock('bcryptjs', () => ({
+  hash: async (value: string) => `bcrypt:${value}`,
+}))
+
+import { setupInitialTenant } from '@open-mercato/core/modules/auth/lib/setup-app'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { ensureDemoTenant, findDemoTenant } from '../tenant-provisioning'
+
+const setupMock = setupInitialTenant as jest.MockedFunction<typeof setupInitialTenant>
+const findMock = findOneWithDecryption as jest.MockedFunction<typeof findOneWithDecryption>
+
+const baseSpec: CpqUseCaseTenantSpec = {
+  slug: 'gix',
+  tenantName: 'GIX Tenant',
+  organizationName: 'GIX',
+  adminEmail: 'admin@gix.com',
+  adminPassword: 'secret',
+}
+
+const fakeEm = {} as any
+const fakeContainer = {} as any
+
+describe('ensureDemoTenant', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('creates a new tenant and returns created=true', async () => {
+    setupMock.mockResolvedValueOnce({
+      tenantId: 't-1',
+      organizationId: 'o-1',
+      reusedExistingUser: false,
+      users: [
+        { user: { id: 'u-1', email: 'admin@gix.com' } as any, roles: ['admin'], created: true },
+      ],
+    })
+
+    const result = await ensureDemoTenant(fakeEm, fakeContainer, baseSpec)
+
+    expect(result).toEqual({
+      tenantId: 't-1',
+      organizationId: 'o-1',
+      adminUserId: 'u-1',
+      created: true,
+    })
+    expect(setupMock).toHaveBeenCalledWith(
+      fakeEm,
+      expect.objectContaining({
+        orgName: 'GIX',
+        roleNames: ['admin', 'employee'],
+        primaryUserRoles: ['admin'],
+        includeSuperadminRole: false,
+        includeDerivedUsers: false,
+        primaryUser: expect.objectContaining({
+          email: 'admin@gix.com',
+          password: 'secret',
+          confirm: true,
+        }),
+      }),
+    )
+  })
+
+  it('reuses an existing tenant idempotently and returns created=false', async () => {
+    setupMock.mockResolvedValueOnce({
+      tenantId: 't-1',
+      organizationId: 'o-1',
+      reusedExistingUser: true,
+      users: [
+        { user: { id: 'u-1', email: 'admin@gix.com' } as any, roles: ['admin'], created: false },
+      ],
+    })
+
+    const result = await ensureDemoTenant(fakeEm, fakeContainer, baseSpec)
+
+    expect(result.created).toBe(false)
+    expect(result.tenantId).toBe('t-1')
+    expect(result.adminUserId).toBe('u-1')
+  })
+
+  it('falls back to findOneWithDecryption when admin not in user snapshots', async () => {
+    setupMock.mockResolvedValueOnce({
+      tenantId: 't-2',
+      organizationId: 'o-2',
+      reusedExistingUser: false,
+      users: [],
+    })
+    findMock.mockResolvedValueOnce({ id: 'u-2', email: 'admin@gix.com' } as any)
+
+    const result = await ensureDemoTenant(fakeEm, fakeContainer, baseSpec)
+
+    expect(result.adminUserId).toBe('u-2')
+    expect(findMock).toHaveBeenCalledWith(
+      fakeEm,
+      expect.anything(),
+      { email: 'admin@gix.com' },
+      expect.anything(),
+      { tenantId: 't-2', organizationId: 'o-2' },
+    )
+  })
+
+  it('throws if admin user cannot be resolved', async () => {
+    setupMock.mockResolvedValueOnce({
+      tenantId: 't-3',
+      organizationId: 'o-3',
+      reusedExistingUser: false,
+      users: [],
+    })
+    findMock.mockResolvedValueOnce(null)
+
+    await expect(ensureDemoTenant(fakeEm, fakeContainer, baseSpec)).rejects.toThrow(
+      /failed to resolve admin user id/,
+    )
+  })
+
+  it('honours role overrides on the spec', async () => {
+    setupMock.mockResolvedValueOnce({
+      tenantId: 't-4',
+      organizationId: 'o-4',
+      reusedExistingUser: false,
+      users: [
+        { user: { id: 'u-4', email: 'admin@puffin.com' } as any, roles: ['admin'], created: true },
+      ],
+    })
+
+    await ensureDemoTenant(fakeEm, fakeContainer, {
+      ...baseSpec,
+      slug: 'puffin',
+      adminEmail: 'admin@puffin.com',
+      tenantName: 'Puffin Tenant',
+      organizationName: 'Puffin Cloud',
+      roleNames: ['admin', 'employee', 'sales'],
+      primaryUserRoles: ['admin', 'sales'],
+      includeDerivedUsers: true,
+    })
+
+    expect(setupMock).toHaveBeenCalledWith(
+      fakeEm,
+      expect.objectContaining({
+        orgName: 'Puffin Cloud',
+        roleNames: ['admin', 'employee', 'sales'],
+        primaryUserRoles: ['admin', 'sales'],
+        includeDerivedUsers: true,
+      }),
+    )
+  })
+
+  it('forwards the modules list to setupInitialTenant so role ACLs are merged', async () => {
+    setupMock.mockResolvedValueOnce({
+      tenantId: 't-mods',
+      organizationId: 'o-mods',
+      reusedExistingUser: false,
+      users: [
+        { user: { id: 'u-mods', email: 'admin@gix.com' } as any, roles: ['admin'], created: true },
+      ],
+    })
+    const fakeModules = [{ id: 'dashboards' }, { id: 'cpq' }] as any
+
+    await ensureDemoTenant(fakeEm, fakeContainer, baseSpec, { modules: fakeModules })
+
+    expect(setupMock).toHaveBeenCalledWith(
+      fakeEm,
+      expect.objectContaining({ modules: fakeModules }),
+    )
+  })
+
+  it('provisions additionalUsers with their roles after the admin tenant exists', async () => {
+    setupMock.mockResolvedValueOnce({
+      tenantId: 't-add',
+      organizationId: 'o-add',
+      reusedExistingUser: false,
+      users: [
+        { user: { id: 'u-admin', email: 'admin@gix.com' } as any, roles: ['admin'], created: true },
+      ],
+    })
+    // 1) lookup existing additional user (none) → create path
+    findMock.mockResolvedValueOnce(null)
+    // 2) lookup employee role → exists
+    findMock.mockResolvedValueOnce({ id: 'r-emp', name: 'employee', tenantId: 't-add' } as any)
+    // 3) lookup existing UserRole link → none → create
+    findMock.mockResolvedValueOnce(null)
+
+    const persisted: any[] = []
+    const created: any[] = []
+    const trackingEm: any = {
+      persist: (entity: any) => persisted.push(entity),
+      flush: jest.fn().mockResolvedValue(undefined),
+      create: (Class: any, data: any) => {
+        const instance = Object.assign(new Class(), data)
+        created.push(instance)
+        return instance
+      },
+    }
+
+    await ensureDemoTenant(trackingEm, fakeContainer, {
+      ...baseSpec,
+      additionalUsers: [
+        { email: 'employee@gix.com', password: 'secret', displayName: 'GIX Employee' },
+      ],
+    })
+
+    const userRecord = created.find((c) => c.email === 'employee@gix.com')
+    expect(userRecord).toBeDefined()
+    expect(userRecord.tenantId).toBe('t-add')
+    expect(userRecord.organizationId).toBe('o-add')
+    expect(userRecord.passwordHash).toBe('bcrypt:secret')
+    expect(userRecord.emailHash).toBe('hash:employee@gix.com')
+    expect(userRecord.isConfirmed).toBe(true)
+    expect(persisted).toContain(userRecord)
+    // UserRole link was also persisted
+    expect(persisted.length).toBeGreaterThanOrEqual(2)
+  })
+
+  it('skips re-creating an additionalUser that already exists but still ensures role link', async () => {
+    setupMock.mockResolvedValueOnce({
+      tenantId: 't-exist',
+      organizationId: 'o-exist',
+      reusedExistingUser: true,
+      users: [
+        { user: { id: 'u-admin', email: 'admin@gix.com' } as any, roles: ['admin'], created: false },
+      ],
+    })
+    const existingEmployee = {
+      id: 'u-emp',
+      email: 'employee@gix.com',
+      tenantId: 't-exist',
+      organizationId: 'o-exist',
+      isConfirmed: true,
+    }
+    findMock.mockResolvedValueOnce(existingEmployee as any) // user lookup
+    findMock.mockResolvedValueOnce({ id: 'r-emp', name: 'employee', tenantId: 't-exist' } as any) // role lookup
+    findMock.mockResolvedValueOnce({ id: 'ur-1' } as any) // existing UserRole link
+
+    const persisted: any[] = []
+    const created: any[] = []
+    const trackingEm: any = {
+      persist: (entity: any) => persisted.push(entity),
+      flush: jest.fn().mockResolvedValue(undefined),
+      create: (Class: any, data: any) => {
+        const instance = Object.assign(new Class(), data)
+        created.push(instance)
+        return instance
+      },
+    }
+
+    await ensureDemoTenant(trackingEm, fakeContainer, {
+      ...baseSpec,
+      additionalUsers: [{ email: 'employee@gix.com', password: 'secret' }],
+    })
+
+    // No new User row was created
+    expect(created.find((c) => c.email === 'employee@gix.com')).toBeUndefined()
+    // No new UserRole row was persisted (link already existed)
+    expect(created.length).toBe(0)
+  })
+
+  it('defaults orgName to tenantName when organizationName is omitted', async () => {
+    setupMock.mockResolvedValueOnce({
+      tenantId: 't-5',
+      organizationId: 'o-5',
+      reusedExistingUser: false,
+      users: [
+        { user: { id: 'u-5', email: 'admin@gix.com' } as any, roles: ['admin'], created: true },
+      ],
+    })
+
+    await ensureDemoTenant(fakeEm, fakeContainer, {
+      slug: 'gix',
+      tenantName: 'Acme Demo',
+      adminEmail: 'admin@gix.com',
+      adminPassword: 'secret',
+    })
+
+    expect(setupMock).toHaveBeenCalledWith(
+      fakeEm,
+      expect.objectContaining({ orgName: 'Acme Demo' }),
+    )
+  })
+})
+
+describe('findDemoTenant', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('returns the resolved tenant when admin user exists', async () => {
+    findMock.mockResolvedValueOnce({
+      id: 'u-7',
+      tenantId: 't-7',
+      organizationId: 'o-7',
+    } as any)
+
+    const result = await findDemoTenant(fakeEm, baseSpec)
+
+    expect(result).toEqual({
+      tenantId: 't-7',
+      organizationId: 'o-7',
+      adminUserId: 'u-7',
+      created: false,
+    })
+  })
+
+  it('returns null when admin user is missing', async () => {
+    findMock.mockResolvedValueOnce(null)
+    const result = await findDemoTenant(fakeEm, baseSpec)
+    expect(result).toBeNull()
+  })
+
+  it('returns null when admin user has no tenant scope', async () => {
+    findMock.mockResolvedValueOnce({
+      id: 'u-9',
+      tenantId: null,
+      organizationId: null,
+    } as any)
+    const result = await findDemoTenant(fakeEm, baseSpec)
+    expect(result).toBeNull()
+  })
+})