@dainamite/cpq 0.2.2

package/src/modules/cpq/services/types.ts

@@ -0,0 +1,303 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+
+// ─── Shared types for CPQ Quoting v2 ─────────────────────────────
+
+export interface TenantScope {
+  organizationId: string
+  tenantId: string
+}
+
+const DEFAULT_CURRENCY = 'USD'
+
+/**
+ * Returns the base currency code for a given tenant scope.
+ * Falls back to 'USD' if no base currency is found.
+ */
+export async function getBaseCurrencyCode(
+  em: EntityManager,
+  scope: TenantScope,
+): Promise<string> {
+  try {
+    const { Currency } = await import(
+      '@open-mercato/core/modules/currencies/data/entities'
+    )
+    const base = await em.findOne(Currency, {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      isBase: true,
+      deletedAt: null,
+    })
+    return base?.code ?? DEFAULT_CURRENCY
+  } catch {
+    return DEFAULT_CURRENCY
+  }
+}
+
+// ─── Quote lifecycle ─────────────────────────────────────────────
+
+export const CPQ_STATUSES = [
+  'new',
+  'incomplete',
+  'ready',
+  'in_approval',
+  'pre_approved',
+  'approved',
+  'with_customer',
+  'accepted',
+  'rejected',
+  'cancelled',
+] as const
+
+export type CpqStatus = (typeof CPQ_STATUSES)[number]
+
+export const TERMINAL_STATUSES: CpqStatus[] = ['accepted', 'rejected', 'cancelled']
+
+// Per product decision: the CPQ status path is operator-driven and can
+// jump between any pair of statuses. Self-transitions are excluded
+// because they're no-ops. ARC-specific guards (`validateArcQuote`,
+// concurrent-ARC checks) still run inside `transitionStatus` and are
+// the real safety net — this table only enforces the "no self loop"
+// invariant.
+export const ALLOWED_TRANSITIONS: Record<CpqStatus, CpqStatus[]> = Object.fromEntries(
+  CPQ_STATUSES.map((from) => [from, CPQ_STATUSES.filter((to) => to !== from)]),
+) as Record<CpqStatus, CpqStatus[]>
+
+// ─── Service input/output types ──────────────────────────────────
+
+export interface CreateQuoteInput {
+  customerId: string
+  quoteId?: string                      // Link to existing SalesQuote instead of creating a new one
+  dealId?: string
+  currencyCode?: string
+  quoteContext?: Record<string, string | number | boolean>
+}
+
+export interface QuoteItemInput {
+  offeringId?: string
+  productId?: string
+  configuration: Record<string, unknown>
+  quantity?: number
+  usageEstimates?: Array<{ chargeCode: string; estimatedQuantity: number }>
+  action?: 'add' | 'modify' | 'cancel'
+  parentLineId?: string
+  startDate?: string
+  termMonths?: number
+  endDate?: string
+  /** XD-250 ARC: target subscription this line acts on. Auto-inherited from
+   * the quote's single attached target when omitted. Required when the ARC
+   * quote has multiple non-merge targets (operator must pick). */
+  targetSubscriptionId?: string | null
+}
+
+export interface ValidationError {
+  type?: 'attribute' | 'relationship'
+  attribute?: string
+  relationshipType?: string
+  sourceSpec?: string
+  targetSpec?: string
+  message: string
+}
+
+/** XD-250 ARC: snapshot of the source subscription item's *current* state.
+ * Surfaced on quote / order lines so the operator can compare "before" (this
+ * snapshot) vs "after" (the line's current configuration). Null for lines
+ * that aren't ARC-mirrored (e.g. a fresh `add` line on an amend quote). */
+export interface ArcLineSource {
+  subscriptionItemId: string
+  name: string
+  mrcAmount: number
+  nrcAmount: number
+  quantity: number
+}
+
+export interface QuoteLineResult {
+  lineId: string
+  offeringId: string | null
+  offeringName: string
+  offeringType: string | null
+  productId: string | null
+  action: string
+  parentLineId: string | null
+  quantity: number
+  configuration: Record<string, unknown>
+  startDate: string | null
+  termMonths: number | null
+  endDate: string | null
+  nrcTotal: number
+  mrcTotal: number
+  usageEstimates: Array<{ chargeCode: string; estimatedQuantity: number; estimatedTotal: number }> | null
+  usageTotalEstimated: number | null
+  charges: ResolvedCharge[]
+  isConfigured: boolean
+  validationErrors: ValidationError[] | null
+  arcSource: ArcLineSource | null
+  /** XD-250 multi-target ARC: which target subscription this line acts on. */
+  targetSubscriptionId: string | null
+}
+
+export interface PricingSummary {
+  nrcTotal: number
+  mrcTotal: number
+  usageCharges: Array<{
+    chargeCode: string
+    chargeName: string
+    unitPrice: number
+    note: string | null
+  }>
+  usageTotalEstimated: number | null
+  discountTotal: number
+  surchargeTotal: number
+  currencyCode: string
+}
+
+export interface QuoteResult {
+  id: string
+  quoteId: string
+  quoteNumber: string
+  customerId: string
+  /** Resolved customer display name (CustomerEntity.displayName). */
+  customerName: string | null
+  cpqStatus: string
+  version: number
+  parentQuoteId: string | null
+  currencyCode: string
+  /**
+   * Set when this quote has been converted to a CPQ order. UI uses this
+   * to lock editing and surface a "Go to order" entry point instead of
+   * the Convert button. Backed by `CpqOrderConfiguration.sourceQuoteId`.
+   */
+  convertedOrderId: string | null
+  validationResult: {
+    valid: boolean
+    errors: ValidationError[]
+  }
+  pricingSummary: PricingSummary
+  lines: QuoteLineResult[]
+}
+
+// ─── Resolved charge (extended for v2) ───────────────────────────
+
+export interface RuleAdjustment {
+  ruleCode: string
+  ruleName: string
+  ruleType: string
+  value: number
+  unitPriceBefore: number
+  unitPriceAfter: number
+  delta: number
+}
+
+export interface TierBreakdown {
+  tiers: Array<{
+    tier: number
+    from: number
+    to: number
+    pricePerUnit: number
+    quantity: number
+    subtotal: number
+  }>
+}
+
+export interface ResolvedCharge {
+  chargeCode: string
+  chargeName: string
+  chargeType: 'nrc' | 'mrc' | 'usage'
+  pricingMethod: 'flat' | 'tiered' | 'per_unit'
+  unitPrice: number
+  quantity: number | null
+  totalPrice: number | null
+  currencyCode: string
+  breakdown?: TierBreakdown | null
+  note?: string | null
+  adjustments?: RuleAdjustment[] | null
+}
+
+// ─── Inventory status constants ──────────────────────────────────
+
+export const INVENTORY_SUBSCRIPTION_STATUSES = [
+  'pending',
+  'active',
+  'suspended',
+  'terminated',
+  'expired',
+  'superseded',
+] as const
+export type InventorySubscriptionStatus = (typeof INVENTORY_SUBSCRIPTION_STATUSES)[number]
+
+export const INVENTORY_SUBSCRIPTION_TRANSITIONS: Record<InventorySubscriptionStatus, InventorySubscriptionStatus[]> = {
+  pending: ['active', 'terminated'],
+  active: ['suspended', 'terminated', 'expired', 'superseded'],
+  suspended: ['active', 'terminated', 'superseded'],
+  terminated: [],
+  expired: [],
+  superseded: [],
+}
+
+export const INVENTORY_SUBSCRIPTION_ITEM_STATUSES = [
+  'pending',
+  'active',
+  'suspended',
+  'terminated',
+  'expired',
+  'superseded',
+] as const
+export type InventorySubscriptionItemStatus = (typeof INVENTORY_SUBSCRIPTION_ITEM_STATUSES)[number]
+
+export const INVENTORY_ASSET_STATUSES = ['pending', 'delivered', 'active', 'returned', 'cancelled'] as const
+export type InventoryAssetStatus = (typeof INVENTORY_ASSET_STATUSES)[number]
+
+export const INVENTORY_ASSET_TRANSITIONS: Record<InventoryAssetStatus, InventoryAssetStatus[]> = {
+  pending: ['delivered', 'active', 'cancelled'],
+  delivered: ['active', 'returned'],
+  active: ['returned'],
+  returned: [],
+  cancelled: [],
+}
+
+// ─── Order status constants ─────────────────────────────────────
+
+export const CPQ_ORDER_STATUSES = ['draft', 'pending_activation', 'active', 'cancelled', 'fulfilled'] as const
+export type CpqOrderStatus = (typeof CPQ_ORDER_STATUSES)[number]
+
+export const CPQ_ORDER_TRANSITIONS: Record<CpqOrderStatus, CpqOrderStatus[]> = {
+  draft: ['pending_activation', 'active', 'cancelled'],
+  pending_activation: ['active', 'cancelled'],
+  active: ['fulfilled', 'cancelled'],
+  cancelled: [],
+  fulfilled: [],
+}
+
+// ─── ARC (Amend / Renew / Cancel) constants ─────────────────────
+
+export const CPQ_QUOTE_TYPES = ['new', 'amend', 'renew', 'cancel'] as const
+export type CpqQuoteType = (typeof CPQ_QUOTE_TYPES)[number]
+
+export const ARC_QUOTE_TYPES: ReadonlyArray<Exclude<CpqQuoteType, 'new'>> = ['amend', 'renew', 'cancel']
+
+export const CHANGE_LOG_TYPES = [
+  'created',
+  'amend',
+  'renew',
+  'cancel',
+  'merge-result',
+  'merge-source',
+] as const
+export type ChangeLogType = (typeof CHANGE_LOG_TYPES)[number]
+
+export const MERGE_ACTIONS = ['standalone', 'absorb'] as const
+export type MergeAction = (typeof MERGE_ACTIONS)[number]
+
+export const ARC_REASON_CODES = [
+  'upgrade',
+  'downgrade',
+  'config-change',
+  'price-adjustment',
+  'term-extension',
+  'term-reduction',
+  'consolidation',
+  'customer-request',
+  'non-payment',
+  'contract-breach',
+  'other',
+] as const
+export type ArcReasonCode = (typeof ARC_REASON_CODES)[number]

package/src/modules/cpq/setup.ts

@@ -0,0 +1,63 @@
+import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+
+/**
+ * CPQ module setup. After XD-276 the cpq module ships with NO customer
+ * demo data — that lives in app-level demo modules (`src/modules/demo_<x>/`)
+ * which register use-case bundles via `cpq/lib/seeds/api.ts`. This keeps
+ * `@dainamite/cpq` clean of vertical-specific seeds when it extracts to a
+ * standalone npm package per SPEC-001.
+ *
+ * What still lives here:
+ *   - `defaultRoleFeatures` — required for any tenant that has cpq enabled
+ *   - structural defaults (currently none beyond role features)
+ *
+ * What used to live here and moved out:
+ *   - GIX product/pricing/charge/rule/bundle/wizard seed → `src/modules/demo_gix/`
+ *   - Acme/Globex demo customers + quotes → `src/modules/demo_gix/seeds/examples.ts`
+ *   - GIX wizard definition → `src/modules/demo_gix/seeds/wizards.ts`
+ */
+export const setup: ModuleSetupConfig = {
+  defaultRoleFeatures: {
+    admin: [
+      'cpq.quotes.view',
+      'cpq.quotes.manage',
+      'cpq.pricing.view',
+      'cpq.pricing.manage',
+      'cpq.products.view',
+      'cpq.products.manage',
+      'cpq.specifications.view',
+      'cpq.specifications.manage',
+      'cpq.offerings.view',
+      'cpq.offerings.manage',
+      'cpq.wizards.view',
+      'cpq.wizards.manage',
+      'cpq.inventory.view',
+      'cpq.inventory.manage',
+      'cpq.orders.view',
+      'cpq.orders.manage',
+      // XD-250 ARC features — admins can drive every ARC flow.
+      'cpq.arc.amend.manage',
+      'cpq.arc.renew.manage',
+      'cpq.arc.cancel.manage',
+      'cpq.arc.changelog.view',
+    ],
+    employee: [
+      'cpq.quotes.view',
+      'cpq.quotes.manage',
+      'cpq.pricing.view',
+      'cpq.products.view',
+      'cpq.specifications.view',
+      'cpq.offerings.view',
+      'cpq.wizards.view',
+      'cpq.inventory.view',
+      'cpq.orders.view',
+      // XD-250 ARC: anyone with cpq.quotes.manage drives ARC quotes.
+      'cpq.arc.amend.manage',
+      'cpq.arc.renew.manage',
+      'cpq.arc.cancel.manage',
+      'cpq.arc.changelog.view',
+    ],
+  },
+}
+
+export default setup

package/src/modules/cpq/subscribers/subscription-amended-log.ts

@@ -0,0 +1,20 @@
+/**
+ * Placeholder persistent subscriber for `cpq.subscription.amended`.
+ *
+ * Logs the payload for human review until downstream billing /
+ * notification modules subscribe with real handlers (XD-250).
+ */
+export const metadata = {
+  event: 'cpq.subscription.amended',
+  persistent: true,
+  id: 'cpq-subscription-amended-log',
+}
+
+export default async function handler(payload: Record<string, unknown>): Promise<void> {
+  console.info(
+    '[cpq.arc] amended',
+    payload.subscriptionId,
+    'changeLog=' + payload.changeLogId,
+    'order=' + payload.sourceOrderId,
+  )
+}

package/src/modules/cpq/subscribers/subscription-cancelled-log.ts

@@ -0,0 +1,19 @@
+/**
+ * Placeholder persistent subscriber for `cpq.subscription.cancelled`.
+ * Cancel quote payload includes ETF + reason metadata.
+ */
+export const metadata = {
+  event: 'cpq.subscription.cancelled',
+  persistent: true,
+  id: 'cpq-subscription-cancelled-log',
+}
+
+export default async function handler(payload: Record<string, unknown>): Promise<void> {
+  console.info(
+    '[cpq.arc] cancelled',
+    payload.subscriptionId,
+    'reason=' + (payload.reasonCode ?? 'none'),
+    'etf=' + (payload.etfAmount ?? 'none'),
+    'changeLog=' + payload.changeLogId,
+  )
+}

package/src/modules/cpq/subscribers/subscription-merged-log.ts

@@ -0,0 +1,22 @@
+/**
+ * Placeholder persistent subscriber for `cpq.subscription.merged`.
+ * Fires once per merge group, on the new merge sub M.
+ */
+export const metadata = {
+  event: 'cpq.subscription.merged',
+  persistent: true,
+  id: 'cpq-subscription-merged-log',
+}
+
+export default async function handler(payload: Record<string, unknown>): Promise<void> {
+  const sources = Array.isArray(payload.mergedFromSubscriptionIds)
+    ? payload.mergedFromSubscriptionIds.length
+    : 0
+  console.info(
+    '[cpq.arc] merged',
+    payload.subscriptionId,
+    `from ${sources} sources`,
+    'changeLog=' + payload.changeLogId,
+    'order=' + payload.sourceOrderId,
+  )
+}

package/src/modules/cpq/subscribers/subscription-renewed-log.ts

@@ -0,0 +1,18 @@
+/**
+ * Placeholder persistent subscriber for `cpq.subscription.renewed`.
+ * Standalone-renew only — merge-renew fires `cpq.subscription.merged`.
+ */
+export const metadata = {
+  event: 'cpq.subscription.renewed',
+  persistent: true,
+  id: 'cpq-subscription-renewed-log',
+}
+
+export default async function handler(payload: Record<string, unknown>): Promise<void> {
+  console.info(
+    '[cpq.arc] renewed',
+    payload.subscriptionId,
+    'changeLog=' + payload.changeLogId,
+    'order=' + payload.sourceOrderId,
+  )
+}

package/src/modules/cpq/subscribers/subscription-superseded-log.ts

@@ -0,0 +1,19 @@
+/**
+ * Placeholder persistent subscriber for `cpq.subscription.superseded`.
+ * Fires once per merge source — payload carries `mergedIntoSubscriptionId`
+ * pointing at the new merge sub M.
+ */
+export const metadata = {
+  event: 'cpq.subscription.superseded',
+  persistent: true,
+  id: 'cpq-subscription-superseded-log',
+}
+
+export default async function handler(payload: Record<string, unknown>): Promise<void> {
+  console.info(
+    '[cpq.arc] superseded',
+    payload.subscriptionId,
+    'mergedInto=' + payload.mergedIntoSubscriptionId,
+    'changeLog=' + payload.changeLogId,
+  )
+}