@dainamite/cpq 0.4.0 → 0.6.0

package/src/modules/cpq/services/priceAdjustments/resolveManualAdjustments.ts

@@ -0,0 +1,116 @@
+import type { AdjustmentError, PriceAdjustment } from '../../data/price-adjustments'
+import type { ResolvedCharge } from '../types'
+import { withChargeWaterfall } from './chargeWaterfall'
+
+export interface AdjustmentPricingLine {
+  lineId: string
+  parentLineId: string | null
+  enginePriced: boolean
+  mirrored: boolean
+  charges: ResolvedCharge[]
+}
+
+/** Most-specific valid manual adjustment wins; each is evaluated against standard. */
+export function resolveManualAdjustments(
+  lines: AdjustmentPricingLine[],
+  adjustments: PriceAdjustment[],
+  currencyCode: string,
+): { lines: AdjustmentPricingLine[]; errors: AdjustmentError[] } {
+  const errors: AdjustmentError[] = []
+  const byId = new Map(lines.map((line) => [line.lineId, line]))
+  const eligible = (line: AdjustmentPricingLine) => line.enginePriced && !line.mirrored
+  const output = lines.map((line) => ({
+    ...line,
+    charges: line.charges.map((charge) => {
+      const normalized = withChargeWaterfall(charge)
+      return { ...normalized, unitPrice: eligible(line) ? normalized.standardUnitPrice! : normalized.unitPrice,
+        totalPrice: eligible(line) ? normalized.standardTotalPrice! : normalized.totalPrice,
+        adjustments: (eligible(line) ? normalized.adjustments?.filter((entry) => entry.origin !== 'manual') : normalized.adjustments) ?? [], adjustmentErrors: [] as AdjustmentError[] }
+    }),
+  }))
+  const outById = new Map(output.map((line) => [line.lineId, line]))
+  const addError = (row: PriceAdjustment, code: AdjustmentError['code'], chargeCode?: string, lineId = row.quoteLineId) => {
+    if (errors.some((entry) => entry.adjustmentId === row.id && entry.quoteLineId === lineId && entry.chargeCode === chargeCode && entry.code === code)) return
+    const error: AdjustmentError = { adjustmentId: row.id, quoteLineId: lineId, ...(chargeCode ? { chargeCode } : {}), code }
+    errors.push(error)
+    for (const charge of outById.get(lineId)?.charges ?? []) {
+      if (!chargeCode || charge.chargeCode === chargeCode) charge.adjustmentErrors.push(error)
+    }
+  }
+  // Missing/ambiguous targets are invalid even if another adjustment could win.
+  const invalid = new Set<string>()
+  for (const row of adjustments) {
+    const target = byId.get(row.quoteLineId)
+    let code: AdjustmentError['code'] | undefined
+    if (!target) code = 'ADJUSTMENT_TARGET_MISSING'
+    else if (!eligible(target)) code = 'LINE_NOT_ELIGIBLE'
+    else if (row.level === 'charge') {
+      const matches = target.charges.filter((charge) => charge.chargeCode === row.chargeCode)
+      if (!matches.length) code = 'ADJUSTMENT_TARGET_MISSING'
+      else if (matches.length > 1) code = 'TARGET_AMBIGUOUS'
+    }
+    if (code) { addError(row, code, row.chargeCode ?? undefined); invalid.add(row.id) }
+  }
+  for (const line of output) {
+    if (!eligible(line)) continue
+    const lineage: string[] = []
+    const visited = new Set<string>([line.lineId])
+    let parent = line.parentLineId
+    while (parent && !visited.has(parent)) {
+      visited.add(parent); lineage.push(parent); parent = byId.get(parent)?.parentLineId ?? null
+    }
+    // Declared before use: `.sort()` below calls it eagerly (a `const` after it would hit the TDZ).
+    const rank = (row: PriceAdjustment) =>
+      row.level === 'charge' ? 0 : row.quoteLineId === line.lineId ? 1 : 2 + lineage.indexOf(row.quoteLineId)
+    for (const charge of line.charges) {
+      const candidates = adjustments.filter((row) => !invalid.has(row.id) && (
+        row.level === 'charge'
+          ? row.quoteLineId === line.lineId && row.chargeCode === charge.chargeCode
+          : (row.quoteLineId === line.lineId || lineage.includes(row.quoteLineId)) &&
+            (!row.chargeTypeFilter || row.chargeTypeFilter === charge.chargeType)
+      )).sort((a, b) => rank(a) - rank(b) || a.id.localeCompare(b.id))
+      const standard = charge.standardUnitPrice!
+      const total = charge.standardTotalPrice
+      const valid = candidates.filter((row) => {
+        // Line discounts cover billable NRC/MRC, never metered usage.
+        if (charge.chargeType === 'usage' && row.level === 'line') return false
+        let code: AdjustmentError['code'] | undefined
+        if (charge.chargeType === 'usage' || total === null || !Number.isFinite(row.value) || row.value < 0 ||
+          (row.adjustmentType === 'price_override' && charge.pricingMethod !== 'flat' && charge.pricingMethod !== 'per_unit') ||
+          (row.level === 'line' && row.adjustmentType !== 'discount_percent') ||
+          (row.adjustmentType === 'discount_percent' && (row.value <= 0 || row.value > 100)) ||
+          (row.adjustmentType === 'discount_absolute' && row.value <= 0)) code = 'TYPE_NOT_ALLOWED'
+        else if ((row.currencyCode && row.currencyCode !== currencyCode) || charge.currencyCode !== currencyCode ||
+          (row.adjustmentType !== 'discount_percent' && !row.currencyCode)) code = 'CURRENCY_MISMATCH'
+        else if (row.adjustmentType === 'price_override' && row.value > standard) code = 'ABOVE_STANDARD'
+        if (code) addError(row, code, charge.chargeCode, line.lineId)
+        return !code
+      })
+      let applied = false
+      for (const row of valid) {
+        if (valid.filter((other) => rank(other) === rank(row)).length > 1) {
+          addError(row, 'ADJUSTMENT_OVERLAP', charge.chargeCode, line.lineId)
+          continue
+        }
+        if (applied) continue
+        const quantity = charge.quantity ?? 1
+        const afterTotal = row.adjustmentType === 'discount_absolute' ? Math.max(0, total! - row.value)
+          : row.adjustmentType === 'discount_percent' ? Math.max(0, total! * (1 - row.value / 100))
+            : row.value * quantity
+        const afterUnit = row.adjustmentType === 'discount_percent' ? standard * (1 - row.value / 100)
+          : row.adjustmentType === 'price_override' ? row.value : quantity > 0 ? afterTotal / quantity : 0
+        charge.unitPrice = afterUnit
+        charge.totalPrice = afterTotal
+        charge.adjustments.push({
+          origin: 'manual', adjustmentId: row.id, class: 'rep', level: row.level,
+          windowKind: 'relative', fromMonth: 1, toMonth: null,
+          ruleCode: row.id, ruleName: row.reasonCode, ruleType: row.adjustmentType,
+          reasonCode: row.reasonCode, createdByUserId: row.createdByUserId,
+          value: row.value, unitPriceBefore: standard, unitPriceAfter: afterUnit, delta: afterUnit - standard,
+        })
+        applied = true
+      }
+    }
+  }
+  return { lines: output, errors }
+}

package/src/modules/cpq/services/priceAdjustments/storedAdjustmentFailure.ts

@@ -0,0 +1,31 @@
+import type { CpqQuoteConfiguration, CpqQuoteLineConfiguration } from '../../data/entities'
+import { adjustmentErrorSchema } from '../../data/price-adjustments'
+
+type Failure = { lineId: string | null; code: string }
+function recordedError(value: unknown, fallback: string | null): Failure | null {
+  if (!value || typeof value !== 'object') return null
+  const record = value as Record<string, unknown>
+  const parsed = adjustmentErrorSchema.shape.code.safeParse(record.code ?? record.message)
+  return parsed.success ? { lineId: typeof record.lineId === 'string' ? record.lineId : fallback, code: parsed.data } : null
+}
+
+/** Conversion validates the reviewed stored snapshot, without calling the price engine. */
+export function storedAdjustmentFailure(quote: CpqQuoteConfiguration, lines: CpqQuoteLineConfiguration[]): Failure | null {
+  for (const line of lines) {
+    for (const charge of line.charges ?? []) {
+      if (Array.isArray(charge.adjustmentErrors) && charge.adjustmentErrors.length) {
+        return recordedError(charge.adjustmentErrors[0], line.quoteLineId) ?? { lineId: line.quoteLineId, code: 'ADJUSTMENT_INVALID' }
+      }
+    }
+    for (const error of line.validationErrors ?? []) {
+      const failure = recordedError(error, line.quoteLineId)
+      if (failure) return failure
+    }
+  }
+  const errors = quote.validationResult?.errors
+  if (Array.isArray(errors)) for (const error of errors) {
+    const failure = recordedError(error, null)
+    if (failure) return failure
+  }
+  return null
+}

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

@@ -92,6 +92,8 @@ export interface QuoteItemInput {
 }
 
 export interface ValidationError {
+  lineId?: string
+  adjustmentId?: string
   type?: 'attribute' | 'relationship'
   attribute?: string
   relationshipType?: string
@@ -137,7 +139,20 @@ export interface QuoteLineResult {
   targetSubscriptionId: string | null
 }
 
-export interface PricingSummary {
+export interface PricingWaterfallSummary {
+  listNrcTotal: number
+  listMrcTotal: number
+  standardNrcTotal: number
+  standardMrcTotal: number
+  ruleDiscountTotal: number
+  manualDiscountTotal: number
+  dealValue: { list: number; standard: number; offer: number }
+  discountDepth: { rule: number | null; manual: number | null; total: number | null; maxLineManual: number | null }
+  hasTimeBasedAdjustments: boolean
+  snapshotHash: string
+}
+
+export interface PricingSummary extends Partial<PricingWaterfallSummary> {
   nrcTotal: number
   mrcTotal: number
   usageCharges: Array<{
@@ -153,6 +168,8 @@ export interface PricingSummary {
 }
 
 export interface QuoteResult {
+  adjustmentErrors?: import('../data/price-adjustments').AdjustmentError[]
+  pricingRevision?: number
   id: string
   quoteId: string
   quoteNumber: string
@@ -180,6 +197,16 @@ export interface QuoteResult {
 // ─── Resolved charge (extended for v2) ───────────────────────────
 
 export interface RuleAdjustment {
+  adjustmentId?: string
+  class?: 'rep' | 'carried_over'
+  level?: 'charge' | 'line' | 'quote'
+  windowKind?: 'relative' | 'absolute'
+  fromMonth?: number
+  toMonth?: number | null
+  reasonCode?: string
+  createdByUserId?: string
+  /** Missing on legacy snapshots. */
+  origin?: 'rule' | 'manual'
   ruleCode: string
   ruleName: string
   ruleType: string
@@ -210,6 +237,12 @@ export interface ResolvedCharge {
   quantity: number | null
   totalPrice: number | null
   currencyCode: string
+  /** Additive waterfall fields; absent on snapshots saved before negotiated pricing. */
+  adjustmentErrors?: import('../data/price-adjustments').AdjustmentError[]
+  listUnitPrice?: number
+  listTotalPrice?: number | null
+  standardUnitPrice?: number
+  standardTotalPrice?: number | null
   breakdown?: TierBreakdown | null
   note?: string | null
   adjustments?: RuleAdjustment[] | null

package/src/modules/cpq/setup.ts

@@ -1,3 +1,4 @@
+import { seedPriceAdjustmentDefaults } from './lib/priceAdjustmentDefaults'
 import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
 
 /**
@@ -9,7 +10,7 @@ import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
  *
  * What still lives here:
  *   - `defaultRoleFeatures` — required for any tenant that has cpq enabled
- *   - structural defaults (currently none beyond role features)
+ *   - structural defaults (price adjustment reasons and rollout toggle)
  *
  * What used to live here and moved out:
  *   - GIX product/pricing/charge/rule/bundle/wizard seed → `src/modules/demo_gix/`
@@ -17,10 +18,14 @@ import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
  *   - GIX wizard definition → `src/modules/demo_gix/seeds/wizards.ts`
  */
 export const setup: ModuleSetupConfig = {
+  async seedDefaults({ em, tenantId, organizationId }) {
+    if (tenantId && organizationId) await seedPriceAdjustmentDefaults(em, { tenantId, organizationId })
+  },
   defaultRoleFeatures: {
     admin: [
       'cpq.quotes.view',
       'cpq.quotes.manage',
+      'cpq.quotes.adjust_price',
       'cpq.pricing.view',
       'cpq.pricing.manage',
       'cpq.products.view',
@@ -44,6 +49,7 @@ export const setup: ModuleSetupConfig = {
     employee: [
       'cpq.quotes.view',
       'cpq.quotes.manage',
+      'cpq.quotes.adjust_price',
       'cpq.pricing.view',
       'cpq.products.view',
       'cpq.specifications.view',