@dainamite/cpq 0.4.0 → 0.6.0

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

@@ -0,0 +1,165 @@
+/**
+ * Frozen Amend mirror lines.
+ *
+ * An Amend quote mirrors every live subscription item as a `modify` line.
+ * Engine-priced mirror lines used to be re-priced at today's catalog price on
+ * every recalculation, and activation wrote that price back to the
+ * subscription item — so amending one item silently moved every other item's
+ * price. A mirror line on an Amend quote is therefore created **frozen**: it
+ * keeps the source item's stored charges until a pricing input of that line
+ * changes, at which point it is re-priced as before.
+ *
+ * The flag lives in the line configuration jsonb next to the existing
+ * `_arcMirrored*` markers, so no schema change is needed.
+ */
+
+export const ARC_PRICE_FROZEN_KEY = '_arcPriceFrozen'
+
+/**
+ * Set when the server unfreezes an Amend mirror line because a pricing input
+ * changed — drives the "re-priced at the current catalog price" notice (an
+ * explicit marker, so Amend quotes created before freezing existed don't
+ * show it).
+ */
+export const ARC_REPRICED_KEY = '_arcRepriced'
+
+/** Markers that describe quote-time pricing state and never leave the quote. */
+const QUOTE_ONLY_ARC_KEYS = [ARC_PRICE_FROZEN_KEY, ARC_REPRICED_KEY] as const
+
+const ARC_MARKER_PREFIX = '_arc'
+
+export type ArcMirrorQuoteType = 'amend' | 'cancel' | 'renew'
+
+export function isArcPriceFrozen(configuration: Record<string, unknown> | null | undefined): boolean {
+  return configuration?.[ARC_PRICE_FROZEN_KEY] === true
+}
+
+/**
+ * Whether recalculation must keep a line's stored charges. Only server-made
+ * mirror lines on Amend quotes qualify — the flag alone is never trusted
+ * (client input is stripped of `_arc*` keys, and a clone of an Amend quote
+ * is a new quote).
+ */
+export function isArcMirrorLine(configuration: Record<string, unknown> | null | undefined, quoteType: string | null | undefined): boolean {
+  return (quoteType === 'amend' || quoteType === 'renew' || quoteType === 'cancel') && typeof configuration?._arcMirroredFromItemId === 'string'
+}
+
+export function isFrozenAmendMirrorLine(
+  configuration: Record<string, unknown> | null | undefined,
+  quoteType: string | null | undefined,
+): boolean {
+  return (
+    quoteType === 'amend' &&
+    typeof configuration?._arcMirroredFromItemId === 'string' &&
+    isArcPriceFrozen(configuration)
+  )
+}
+
+/**
+ * Configuration for a mirror line: the item's configuration plus the ARC
+ * markers. Only Amend lines are frozen — Renew re-prices by product decision
+ * and Cancel lines are not priced.
+ */
+export function buildArcMirrorConfiguration(
+  itemConfiguration: Record<string, unknown> | null | undefined,
+  item: { id: string; name: string },
+  quoteType: ArcMirrorQuoteType,
+): Record<string, unknown> {
+  return {
+    // An item's configuration can carry markers from an earlier ARC quote
+    // (activation copies line configuration onto the item); never inherit them.
+    ...stripArcMarkers(itemConfiguration),
+    _arcMirroredFromItemId: item.id,
+    _arcMirroredName: item.name,
+    ...(quoteType === 'amend' ? { [ARC_PRICE_FROZEN_KEY]: true } : {}),
+  }
+}
+
+/**
+ * Line configuration as it may leave the quote (order lines, subscription
+ * items, clones): quote-only pricing markers are dropped; the descriptive
+ * `_arcMirrored*` markers stay.
+ */
+export function stripQuoteOnlyArcMarkers(
+  configuration: Record<string, unknown> | null | undefined,
+): Record<string, unknown> | null | undefined {
+  if (!configuration || !QUOTE_ONLY_ARC_KEYS.some((key) => key in configuration)) return configuration
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(configuration)) {
+    if (!(QUOTE_ONLY_ARC_KEYS as readonly string[]).includes(key)) out[key] = value
+  }
+  return out
+}
+
+/**
+ * Configuration without any `_arc*` marker. ARC markers are server-owned:
+ * client-supplied configuration goes through this before it is stored.
+ */
+export function stripArcMarkers(configuration: Record<string, unknown> | null | undefined): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(configuration ?? {})) {
+    if (!key.startsWith(ARC_MARKER_PREFIX)) out[key] = value
+  }
+  return out
+}
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+  if (value && typeof value === 'object') {
+    const entries = Object.keys(value as Record<string, unknown>)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonical((value as Record<string, unknown>)[key])}`)
+    return `{${entries.join(',')}}`
+  }
+  return JSON.stringify(value ?? null)
+}
+
+function isoDay(value: Date | string | null | undefined): string | null {
+  if (!value) return null
+  if (value instanceof Date) return value.toISOString().slice(0, 10)
+  return String(value).slice(0, 10)
+}
+
+export type ArcLinePricingState = {
+  configuration: Record<string, unknown> | null | undefined
+  quantity: number
+  termMonths?: number | null
+  startDate?: Date | string | null
+  endDate?: Date | string | null
+  usageEstimates?: Array<{ chargeCode: string; estimatedQuantity: number }> | null
+}
+
+export type ArcLinePricingUpdate = {
+  configuration: Record<string, unknown>
+  quantity?: number
+  termMonths?: number
+  startDate?: string
+  endDate?: string
+  usageEstimates?: Array<{ chargeCode: string; estimatedQuantity: number }>
+}
+
+/**
+ * Whether an update changes any input the pricing engine reads. The quote UI
+ * always resubmits the full configuration, so "a field was sent" is not a
+ * change — values are compared (ARC markers ignored, key order ignored).
+ * Fields the update omits keep their stored value.
+ */
+export function arcPricingInputsChanged(before: ArcLinePricingState, update: ArcLinePricingUpdate): boolean {
+  if (canonical(stripArcMarkers(before.configuration)) !== canonical(stripArcMarkers(update.configuration))) {
+    return true
+  }
+  if (update.quantity !== undefined && update.quantity !== before.quantity) return true
+  if (update.termMonths !== undefined && update.termMonths !== (before.termMonths ?? undefined)) return true
+  if (update.startDate !== undefined && isoDay(update.startDate) !== isoDay(before.startDate)) return true
+  if (update.endDate !== undefined && isoDay(update.endDate) !== isoDay(before.endDate)) return true
+  if (update.usageEstimates !== undefined) {
+    const normalize = (list: Array<{ chargeCode: string; estimatedQuantity: number }> | null | undefined) =>
+      canonical(
+        [...(list ?? [])]
+          .map((e) => ({ chargeCode: e.chargeCode, estimatedQuantity: e.estimatedQuantity }))
+          .sort((a, b) => a.chargeCode.localeCompare(b.chargeCode)),
+      )
+    if (normalize(update.usageEstimates) !== normalize(before.usageEstimates)) return true
+  }
+  return false
+}

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

@@ -1,3 +1,5 @@
+import { storedAdjustmentFailure } from './priceAdjustments/storedAdjustmentFailure'
+import { withQuotePricingWrite } from './priceAdjustments/quotePricingWrite'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { SalesOrder, SalesOrderLine } from '@open-mercato/core/modules/sales/data/entities'
 import type { SalesDocumentNumberGenerator } from '@open-mercato/core/modules/sales/services/salesDocumentNumberGenerator'
@@ -25,6 +27,8 @@ import {
   type TenantScope,
 } from './types'
 import { emitCpqEvent } from '../events'
+import { stripQuoteOnlyArcMarkers } from './arcPriceFreeze'
+import { summarizeOrderPricing, type OrderWaterfallSummary } from './orderPricingSummary'
 
 // ─── Types ──────────────────────────────────────────────────────
 
@@ -89,11 +93,12 @@ interface OrderResult {
    * order detail page to render the AMEND / RENEW / CANCEL badge. */
   quoteType: string
   currencyCode: string
+  /** NRC / MRC totals plus the source quote's list / discount / deal-value figures. */
   pricingSummary: {
     nrcTotal: number
     mrcTotal: number
     currencyCode: string
-  }
+  } & OrderWaterfallSummary
   activatedAt: string | null
   createdAt: string
   lines: OrderLineResult[]
@@ -129,29 +134,12 @@ export class DefaultCpqOrderService {
   // ─── Convert Quote to Order ─────────────────────────────────
 
   async convertQuoteToOrder(quoteId: string, scope: TenantScope): Promise<OrderResult> {
-    const em = this.em
-
-    const cpqConfig = await em.findOne(CpqQuoteConfiguration, {
-      id: quoteId,
-      organizationId: scope.organizationId,
-      tenantId: scope.tenantId,
-      deletedAt: null,
-    })
-    if (!cpqConfig) {
-      const byQuoteId = await em.findOne(CpqQuoteConfiguration, {
-        quoteId,
-        organizationId: scope.organizationId,
-        tenantId: scope.tenantId,
-        deletedAt: null,
-      })
-      if (!byQuoteId) throw new OrderError(404, 'Quote not found')
-      return this.convertFromConfig(byQuoteId, scope)
-    }
-    return this.convertFromConfig(cpqConfig, scope)
+    return withQuotePricingWrite(this.em, quoteId, scope,
+      (em, quote) => this.convertFromConfig(quote, scope, em),
+      (status, message) => new OrderError(status, message))
   }
 
-  private async convertFromConfig(cpqConfig: CpqQuoteConfiguration, scope: TenantScope): Promise<OrderResult> {
-    const em = this.em
+  private async convertFromConfig(cpqConfig: CpqQuoteConfiguration, scope: TenantScope, em: EntityManager): Promise<OrderResult> {
 
     const blockedStatuses = ['cancelled', 'rejected']
     if (blockedStatuses.includes(cpqConfig.cpqStatus)) {
@@ -186,6 +174,9 @@ export class DefaultCpqOrderService {
       throw new OrderError(422, 'Cannot convert a quote with no line items')
     }
 
+    const invalidAdjustment = storedAdjustmentFailure(cpqConfig, quoteLines)
+    if (invalidAdjustment) throw new OrderError(422, 'ADJUSTMENT_INVALID', invalidAdjustment)
+
     const { number: orderNumber } = await this.numberGenerator.generate({
       kind: 'order',
       organizationId: scope.organizationId,
@@ -309,7 +300,8 @@ export class DefaultCpqOrderService {
         startDate: ql.startDate,
         termMonths: ql.termMonths ?? null,
         endDate: ql.endDate,
-        configuration: { ...ql.configuration, offeringName },
+        // Quote-only ARC pricing markers stay on the quote.
+        configuration: { ...stripQuoteOnlyArcMarkers(ql.configuration), offeringName },
         quantity: ql.quantity,
         charges: ql.charges ? [...ql.charges] : null,
         nrcTotal: ql.nrcTotal,
@@ -641,7 +633,7 @@ export class DefaultCpqOrderService {
       offeringId: line.offeringId ?? undefined,
       specId: line.specId ?? undefined,
       name: this.getLineName(line),
-      configuration: line.configuration ?? {},
+      configuration: stripQuoteOnlyArcMarkers(line.configuration) ?? {},
       charges: (line.charges ?? []) as Array<Record<string, unknown>>,
       mrcAmount: Number(line.mrcTotal),
       nrcAmount: Number(line.nrcTotal),
@@ -711,7 +703,7 @@ export class DefaultCpqOrderService {
           purchasePrice: Number(line.nrcTotal),
           quantity: line.quantity,
           purchaseDate: new Date().toISOString().split('T')[0],
-          configuration: line.configuration ?? {},
+          configuration: stripQuoteOnlyArcMarkers(line.configuration) ?? {},
           charges: (line.charges ?? []) as Array<Record<string, unknown>>,
           sourceOrderId: orderConfig.id,
           sourceQuoteLineId: line.sourceQuoteLineId ?? undefined,
@@ -976,7 +968,7 @@ export class DefaultCpqOrderService {
         action: lc.action,
         parentLineId: lc.parentLineId ?? null,
         quantity: lc.quantity,
-        configuration: lc.configuration ?? {},
+        configuration: stripQuoteOnlyArcMarkers(lc.configuration) ?? {},
         startDate: lc.startDate?.toISOString() ?? null,
         termMonths: lc.termMonths ?? null,
         endDate: lc.endDate?.toISOString() ?? null,
@@ -1018,6 +1010,7 @@ export class DefaultCpqOrderService {
         nrcTotal: Number((pricing as Record<string, unknown>).nrcTotal ?? 0),
         mrcTotal: Number((pricing as Record<string, unknown>).mrcTotal ?? 0),
         currencyCode: orderConfig.currencyCode,
+        ...summarizeOrderPricing(lines, quoteType, orderConfig.currencyCode),
       },
       activatedAt: orderConfig.activatedAt?.toISOString() ?? null,
       createdAt: orderConfig.createdAt.toISOString(),
@@ -1045,16 +1038,27 @@ function pickArcSourceFromConfig(
 
 // ─── Error class ──────────────────────────────────────────────────
 
+// Cross-realm brand — see QUOTING_ERROR_BRAND in cpqQuotingService.ts for why
+// route handlers must not rely on `instanceof`. Use `isOrderError`.
+const ORDER_ERROR_BRAND = Symbol.for('@dainamite/cpq/OrderError')
+
 export class OrderError extends Error {
+  readonly [ORDER_ERROR_BRAND] = true
+
   constructor(
     public status: number,
     message: string,
+    public details?: Record<string, unknown>,
   ) {
     super(message)
     this.name = 'OrderError'
   }
 }
 
+export function isOrderError(err: unknown): err is OrderError {
+  return !!err && typeof err === 'object' && (err as Record<symbol, unknown>)[ORDER_ERROR_BRAND] === true
+}
+
 // ─── ARC helpers (XD-250) ─────────────────────────────────────────
 
 /**
@@ -1072,7 +1076,7 @@ function buildArcLineChange(
       offeringId: line.offeringId ?? undefined,
       specId: line.specId ?? undefined,
       name: resolveLineName(line, specMap),
-      configuration: line.configuration ?? {},
+      configuration: stripQuoteOnlyArcMarkers(line.configuration) ?? {},
       charges: (line.charges ?? null) as Array<Record<string, unknown>> | undefined,
       mrcAmount: Number(line.mrcTotal),
       nrcAmount: Number(line.nrcTotal),
@@ -1099,7 +1103,7 @@ function buildArcLineChange(
     action,
     sourceSubscriptionItemId: line.sourceSubscriptionItemId ?? null,
     modifyPatch: {
-      configuration: line.configuration ?? undefined,
+      configuration: stripQuoteOnlyArcMarkers(line.configuration) ?? undefined,
       charges: (line.charges ?? undefined) as Array<Record<string, unknown>> | undefined,
       mrcAmount: Number(line.mrcTotal),
       nrcAmount: Number(line.nrcTotal),

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

@@ -119,6 +119,8 @@ export class DefaultCpqPricingService {
       if (currencyCode) {
         resolved.currencyCode = currencyCode
       }
+      resolved.listUnitPrice = resolved.unitPrice
+      resolved.listTotalPrice = resolved.totalPrice
       resolved.adjustments = []
       results.push(resolved)
     }
@@ -133,6 +135,11 @@ export class DefaultCpqPricingService {
       this.applyPriceRules(results, rules, configuration)
     }
 
+    for (const resolved of results) {
+      resolved.standardUnitPrice = resolved.unitPrice
+      resolved.standardTotalPrice = resolved.totalPrice
+    }
+
     return results
   }
 
@@ -219,6 +226,7 @@ export class DefaultCpqPricingService {
         }
 
         const adjustment: RuleAdjustment = {
+          origin: 'rule',
           ruleCode: rule.code,
           ruleName: rule.name,
           ruleType: rule.ruleType,