@dainamite/cpq 0.4.0 → 0.6.0

package/src/modules/cpq/lib/__tests__/priceAdjustmentDefaults.test.ts

@@ -0,0 +1,37 @@
+import { seedPriceAdjustmentDefaults } from '../priceAdjustmentDefaults'
+import { Dictionary, DictionaryEntry } from '@open-mercato/core/modules/dictionaries/data/entities'
+import { FeatureToggle } from '@open-mercato/core/modules/feature_toggles/data/entities'
+import { DEFAULT_ADJUSTMENT_REASONS } from '../../data/price-adjustments'
+import { setup } from '../../setup'
+import { features } from '../../acl'
+const scope = { tenantId: 'tenant', organizationId: 'org' }
+it('seeds seven editable reasons idempotently without resetting a disabled rollout toggle or custom label', async () => {
+  let dictionary: Record<string, unknown> | null = null
+  const entries: Array<Record<string, unknown>> = []
+  const flag = { identifier: 'cpq.manual_price_adjustments', defaultValue: false }
+  const em = {
+    upsert: jest.fn(async () => flag),
+    findOne: jest.fn(async () => dictionary), find: jest.fn(async () => entries),
+    create: jest.fn((entity: unknown, values: Record<string, unknown>) => {
+      const row = { id: `id-${entries.length}`, ...values }
+      if (entity === Dictionary) dictionary = row
+      if (entity === DictionaryEntry) entries.push(row)
+      return row
+    }), persist: jest.fn(), flush: jest.fn().mockResolvedValue(undefined),
+  }
+  await seedPriceAdjustmentDefaults(em as never, scope)
+  expect(entries).toHaveLength(7)
+  expect(entries.map((entry) => entry.value)).toEqual(DEFAULT_ADJUSTMENT_REASONS.map((entry) => entry.value))
+  expect(dictionary).toMatchObject({ managerVisibility: 'default', isSystem: false, ...scope })
+  entries[0].label = 'Tenant custom label'
+  await seedPriceAdjustmentDefaults(em as never, scope)
+  expect(entries).toHaveLength(7)
+  expect(entries[0].label).toBe('Tenant custom label')
+  expect(flag.defaultValue).toBe(false)
+  expect(em.upsert).toHaveBeenCalledWith(FeatureToggle, expect.objectContaining({ defaultValue: true, createdAt: expect.any(Date), updatedAt: expect.any(Date) }), { onConflictFields: ['identifier'], onConflictAction: 'ignore' })
+})
+it('declares and grants adjustment permission to both sales roles', () => {
+  expect(features.some((entry) => entry.id === 'cpq.quotes.adjust_price')).toBe(true)
+  expect(setup.defaultRoleFeatures?.admin).toContain('cpq.quotes.adjust_price')
+  expect(setup.defaultRoleFeatures?.employee).toContain('cpq.quotes.adjust_price')
+})

package/src/modules/cpq/lib/__tests__/priceAdjustmentView.test.ts

@@ -0,0 +1,152 @@
+import {
+  adjustmentAccess, adjustmentErrorCode, collectAdjustmentErrors, allowedAdjustmentTypes, buildAdjustmentDraft, canDeleteInvalidAdjustment, discountDepth, formatDepth, parseStoredCharge, toAdjustmentPatch,
+  lineAdjustmentBlock, lineWaterfallTotals, waterfallRows,
+} from '../priceAdjustmentView'
+import { TERMINAL_STATUSES } from '../../services/types'
+
+const rule = { origin: 'rule' as const, ruleCode: 'VOL', ruleName: 'Volume', ruleType: 'discount_percent', value: 10, unitPriceBefore: 100, unitPriceAfter: 90, delta: -10 }
+const manual = { origin: 'manual' as const, adjustmentId: 'a1', ruleCode: 'a1', ruleName: 'competitive_match', ruleType: 'price_override', value: 80, unitPriceBefore: 90, unitPriceAfter: 80, delta: -10, reasonCode: 'competitive_match' }
+
+describe('waterfallRows', () => {
+  it('orders list, rules, standard, manual, offer', () => {
+    const rows = waterfallRows({ chargeType: 'mrc', unitPrice: 80, totalPrice: 80, listUnitPrice: 100, standardUnitPrice: 90, adjustments: [manual, rule] })
+    expect(rows.map((row) => row.kind)).toEqual(['list', 'rule', 'standard', 'manual', 'offer'])
+    expect(rows[0]).toEqual({ kind: 'list', unitPrice: 100 })
+    expect(rows[2]).toEqual({ kind: 'standard', unitPrice: 90 })
+    expect(rows[3]).toMatchObject({ reasonCode: 'competitive_match', adjustmentId: 'a1', delta: -10 })
+    expect(rows[4]).toEqual({ kind: 'offer', unitPrice: 80 })
+  })
+
+  it('shows list and offer only when nothing adjusted the price', () => {
+    expect(waterfallRows({ chargeType: 'nrc', unitPrice: 50, totalPrice: 50 }).map((row) => row.kind)).toEqual(['list', 'offer'])
+  })
+
+  it('treats legacy rule entries without origin as rules and derives list from them', () => {
+    const { origin: _origin, ...legacy } = rule
+    const rows = waterfallRows({ chargeType: 'mrc', unitPrice: 90, totalPrice: 90, adjustments: [legacy] })
+    expect(rows).toEqual([
+      { kind: 'list', unitPrice: 100 },
+      expect.objectContaining({ kind: 'rule', label: 'Volume' }),
+      { kind: 'standard', unitPrice: 90 },
+      { kind: 'offer', unitPrice: 90 },
+    ])
+  })
+})
+
+describe('depth', () => {
+  it('is signed and formatted with one decimal', () => {
+    expect(discountDepth(100, 80)).toBeCloseTo(0.2)
+    expect(formatDepth(discountDepth(100, 80))).toBe('−20%')
+    expect(formatDepth(discountDepth(100, 112.5))).toBe('+12.5%')
+    expect(formatDepth(discountDepth(100, 100))).toBeNull()
+    expect(discountDepth(0, 0)).toBeNull()
+    expect(discountDepth(null, 5)).toBeNull()
+  })
+
+  it('totals a line by quantity and skips usage', () => {
+    expect(lineWaterfallTotals({ quantity: 2, charges: [
+      { chargeType: 'mrc', unitPrice: 80, totalPrice: 80, listTotalPrice: 100, standardTotalPrice: 90 },
+      { chargeType: 'usage', unitPrice: 1, totalPrice: null },
+      { chargeType: 'nrc', unitPrice: 10, totalPrice: 10 },
+    ] })).toEqual({ list: 220, standard: 200, offer: 180 })
+  })
+})
+
+describe('allowedAdjustmentTypes', () => {
+  it.each([
+    ['line', undefined, ['discount_percent']],
+    ['charge', { chargeType: 'mrc', pricingMethod: 'flat' }, ['price_override', 'discount_percent', 'discount_absolute']],
+    ['charge', { chargeType: 'nrc', pricingMethod: 'per_unit' }, ['price_override', 'discount_percent', 'discount_absolute']],
+    ['charge', { chargeType: 'mrc', pricingMethod: 'tiered' }, ['discount_percent', 'discount_absolute']],
+    ['charge', { chargeType: 'mrc', pricingMethod: 'volume' }, ['discount_percent', 'discount_absolute']],
+    ['charge', { chargeType: 'usage', pricingMethod: 'flat' }, []],
+  ] as const)('%s %j → %j', (level, charge, expected) => {
+    expect(allowedAdjustmentTypes(level, charge)).toEqual(expected)
+  })
+})
+
+describe('eligibility and access', () => {
+  it('blocks ARC mirror and free-form lines', () => {
+    expect(lineAdjustmentBlock({ offeringId: 'o', configuration: { _arcMirroredFromItemId: 'i' } }, 'amend')).toBe('mirror')
+    expect(lineAdjustmentBlock({ offeringId: 'o', configuration: { _arcMirroredFromItemId: 'i' } }, 'new')).toBeNull()
+    expect(lineAdjustmentBlock({ offeringId: null }, 'new')).toBe('free_form')
+    expect(lineAdjustmentBlock({ offeringId: null, productId: 'p1' }, 'new')).toBeNull()
+    expect(lineAdjustmentBlock({ offeringId: 'o', configuration: {} }, 'renew')).toBeNull()
+  })
+
+  const base = { enabled: true, canAdjust: true, cpqStatus: 'ready', convertedOrderId: null }
+  it.each([
+    [{}, null],
+    [{ enabled: null }, 'loading'],
+    [{ enabled: false }, 'disabled'],
+    [{ canAdjust: false }, 'no_permission'],
+    [{ convertedOrderId: 'order' }, 'converted'],
+    [{ cpqStatus: 'in_approval' }, 'locked'],
+  ] as const)('%j → %s', (patch, reason) => {
+    expect(adjustmentAccess({ ...base, ...patch }).reason).toBe(reason)
+  })
+
+  it('lets invalid adjustments be deleted while submitted, never once final', () => {
+    expect(canDeleteInvalidAdjustment({ ...base, cpqStatus: 'in_approval' })).toBe(true)
+    for (const status of TERMINAL_STATUSES) expect(canDeleteInvalidAdjustment({ ...base, cpqStatus: status })).toBe(false)
+    expect(canDeleteInvalidAdjustment({ ...base, convertedOrderId: 'x' })).toBe(false)
+  })
+})
+
+describe('request bodies', () => {
+  const form = { adjustmentType: 'price_override' as const, value: '80', reasonCode: 'competitive_match', reasonNote: '', chargeTypeFilter: '' as const }
+  it('builds a charge override with currency and revision', () => {
+    expect(buildAdjustmentDraft(form, { level: 'charge', quoteLineId: 'l1', chargeCode: 'fee' }, 'USD', 3)).toEqual({
+      level: 'charge', quoteLineId: 'l1', chargeCode: 'fee', adjustmentType: 'price_override', value: 80, currencyCode: 'USD', reasonCode: 'competitive_match', expectedRevision: 3,
+    })
+  })
+  it('builds a line percentage without currency, with filter and note; accepts a decimal comma', () => {
+    expect(buildAdjustmentDraft({ ...form, adjustmentType: 'discount_percent', value: '12,5', chargeTypeFilter: 'mrc', reasonCode: 'other', reasonNote: ' match ' }, { level: 'line', quoteLineId: 'l1' }, 'USD')).toEqual({
+      level: 'line', quoteLineId: 'l1', chargeTypeFilter: 'mrc', adjustmentType: 'discount_percent', value: 12.5, reasonCode: 'other', reasonNote: 'match',
+    })
+  })
+  it('returns null for empty or non-numeric values', () => {
+    expect(buildAdjustmentDraft({ ...form, value: ' ' }, { level: 'line', quoteLineId: 'l1' }, 'USD')).toBeNull()
+    expect(buildAdjustmentDraft({ ...form, value: 'abc' }, { level: 'line', quoteLineId: 'l1' }, 'USD')).toBeNull()
+  })
+  it('drops immutable target fields from a patch and clears removed notes', () => {
+    const draft = buildAdjustmentDraft(form, { level: 'charge', quoteLineId: 'l1', chargeCode: 'fee' }, 'USD', 2)!
+    expect(toAdjustmentPatch(draft)).toEqual({ adjustmentType: 'price_override', value: 80, currencyCode: 'USD', reasonCode: 'competitive_match', reasonNote: null, expectedRevision: 2 })
+  })
+  it.each([
+    [409, { error: 'STALE_REVISION' }, 'STALE_REVISION'],
+    [400, { error: 'Validation error', details: [{ message: 'Invalid' }, { message: 'INVALID_PERCENT' }] }, 'INVALID_PERCENT'],
+    [422, { error: 'ABOVE_STANDARD' }, 'ABOVE_STANDARD'],
+    [403, { error: 'Manual price adjustments are disabled' }, 'FORBIDDEN'],
+    [500, null, 'UNKNOWN'],
+  ])('maps %s %j → %s', (status, body, code) => {
+    expect(adjustmentErrorCode(status, body)).toBe(code)
+  })
+})
+
+describe('parseStoredCharge', () => {
+  it('keeps waterfall fields and well-formed adjustments, drops malformed ones', () => {
+    const parsed = parseStoredCharge({ chargeCode: 'fee', chargeType: 'mrc', unitPrice: 80, totalPrice: 80, quantity: 1, listUnitPrice: 100, standardUnitPrice: 90,
+      adjustments: [{ ...manual }, { ruleType: 'x' }, null] })
+    expect(parsed).toMatchObject({ chargeName: 'fee', chargeType: 'mrc', unitPrice: 80, listUnitPrice: 100, standardUnitPrice: 90, quantity: 1 })
+    expect(parsed?.adjustments).toHaveLength(1)
+  })
+  it.each([null, 'x', { chargeType: 'mrc' }, { chargeType: 'other', unitPrice: 1 }])('rejects %j', (raw) => {
+    expect(parseStoredCharge(raw)).toBeNull()
+  })
+})
+
+describe('collectAdjustmentErrors', () => {
+  it('reads recalculation errors, charge errors and persisted validation errors (after reload)', () => {
+    const map = collectAdjustmentErrors({
+      adjustmentErrors: [{ adjustmentId: 'a1', code: 'ABOVE_STANDARD' }],
+      lines: [{ charges: [{ adjustmentErrors: [{ adjustmentId: 'a1', code: 'CURRENCY_MISMATCH' }, { adjustmentId: 'a2', code: 'ADJUSTMENT_OVERLAP' }] }],
+        validationErrors: [{ adjustmentId: 'a3', message: 'ADJUSTMENT_TARGET_MISSING' }, { message: 'Port size is required' }] }],
+      validationResult: { errors: [{ adjustmentId: 'a4', message: 'TARGET_AMBIGUOUS' }] },
+    })
+    expect(Object.fromEntries(map)).toEqual({ a1: 'ABOVE_STANDARD', a2: 'ADJUSTMENT_OVERLAP', a3: 'ADJUSTMENT_TARGET_MISSING', a4: 'TARGET_AMBIGUOUS' })
+  })
+  it('is empty for a missing quote', () => {
+    expect(collectAdjustmentErrors(null).size).toBe(0)
+  })
+})

package/src/modules/cpq/lib/__tests__/quotePermissions.test.ts

@@ -0,0 +1,30 @@
+import { canRecalculateQuote, TERMINAL_QUOTE_STATUSES } from '../quotePermissions'
+import { TERMINAL_STATUSES } from '../../services/types'
+
+describe('TERMINAL_QUOTE_STATUSES', () => {
+  it('mirrors the service-layer TERMINAL_STATUSES', () => {
+    expect([...TERMINAL_QUOTE_STATUSES].sort()).toEqual([...TERMINAL_STATUSES].sort())
+  })
+})
+
+describe('canRecalculateQuote', () => {
+  it('allows a user with cpq.quotes.manage on a non-terminal quote', () => {
+    expect(canRecalculateQuote(['cpq.quotes.manage'], 'ready')).toBe(true)
+  })
+
+  it('honours wildcard grants', () => {
+    expect(canRecalculateQuote(['cpq.*'], 'incomplete')).toBe(true)
+  })
+
+  it('denies a view-only user', () => {
+    expect(canRecalculateQuote(['cpq.quotes.view'], 'ready')).toBe(false)
+  })
+
+  it('denies before the feature check has loaded (no granted features)', () => {
+    expect(canRecalculateQuote([], 'ready')).toBe(false)
+  })
+
+  it.each(['accepted', 'rejected', 'cancelled'])('denies on a %s (terminal) quote', (status) => {
+    expect(canRecalculateQuote(['cpq.quotes.manage'], status)).toBe(false)
+  })
+})

package/src/modules/cpq/lib/__tests__/quoteSummaryView.test.ts

@@ -0,0 +1,56 @@
+import { arcRecurringDelta, chargeTypeDepths, formatChangePct } from '../quoteSummaryView'
+
+describe('chargeTypeDepths', () => {
+  it('computes list → offer depth per charge type', () => {
+    const depths = chargeTypeDepths({ nrcTotal: 80, mrcTotal: 90, listNrcTotal: 100, listMrcTotal: 100 })
+    expect(depths.nrc).toBeCloseTo(0.2)
+    expect(depths.mrc).toBeCloseTo(0.1)
+  })
+
+  it('returns null for legacy snapshots and zero list', () => {
+    expect(chargeTypeDepths({ nrcTotal: 80, mrcTotal: 90 })).toEqual({ nrc: null, mrc: null })
+    expect(chargeTypeDepths({ nrcTotal: 0, mrcTotal: 0, listNrcTotal: 0, listMrcTotal: 0 })).toEqual({ nrc: null, mrc: null })
+  })
+})
+
+describe('arcRecurringDelta', () => {
+  it('compares mirrored items against surviving lines', () => {
+    const result = arcRecurringDelta([
+      { action: 'modify', mrcTotal: 120, arcSource: { mrcAmount: 100 } }, // re-rated
+      { action: 'cancel', mrcTotal: 50, arcSource: { mrcAmount: 50 } }, // removed
+      { action: 'add', mrcTotal: 30, arcSource: null }, // new
+    ])
+    expect(result).toEqual({ currentMrc: 150, newMrc: 150, delta: 0, deltaPct: 0 })
+  })
+
+  it('reports a signed change and percentage', () => {
+    const result = arcRecurringDelta([
+      { action: 'modify', mrcTotal: 100, arcSource: { mrcAmount: 100 } },
+      { action: 'add', mrcTotal: 25, arcSource: null },
+    ])
+    expect(result.delta).toBe(25)
+    expect(result.deltaPct).toBeCloseTo(0.25)
+  })
+
+  it('has no percentage when there is no current recurring value', () => {
+    expect(arcRecurringDelta([{ action: 'add', mrcTotal: 10, arcSource: null }]).deltaPct).toBeNull()
+  })
+
+  it('replacing an item: the removed item counts as current, only the new one as new', () => {
+    // Amend: existing $400 port removed (cancel line, zero totals) and a $1,130 port added.
+    const result = arcRecurringDelta([
+      { action: 'cancel', mrcTotal: 0, arcSource: { mrcAmount: 400 } },
+      { action: 'add', mrcTotal: 1130, arcSource: null },
+    ])
+    expect(result).toEqual({ currentMrc: 400, newMrc: 1130, delta: 730, deltaPct: 1.825 })
+  })
+})
+
+describe('formatChangePct', () => {
+  it('formats signed changes and hides ~0', () => {
+    expect(formatChangePct(0.25)).toBe('+25%')
+    expect(formatChangePct(-0.125)).toBe('−12.5%')
+    expect(formatChangePct(0)).toBeNull()
+    expect(formatChangePct(null)).toBeNull()
+  })
+})

package/src/modules/cpq/lib/auditActor.ts

@@ -0,0 +1,13 @@
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * The user id to record as author. Sessions carry the user id in `sub`;
+ * API keys carry `api_key:<id>` in `sub` and the owning user (if any) in
+ * `userId`. Returns null when no user is behind the request, so callers can
+ * refuse cleanly instead of writing a non-uuid into a uuid column.
+ */
+export function resolveAuditActor(auth: { sub?: string | null; userId?: string | null } | null | undefined): string | null {
+  if (auth?.sub && UUID.test(auth.sub)) return auth.sub
+  if (auth?.userId && UUID.test(auth.userId)) return auth.userId
+  return null
+}

package/src/modules/cpq/lib/formatMoney.ts

@@ -0,0 +1,4 @@
+/** Currency amount as shown across CPQ detail pages, e.g. `$1,130.00`. */
+export function formatMoney(amount: number, currency: string): string {
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(amount)
+}

package/src/modules/cpq/lib/priceAdjustmentDefaults.ts

@@ -0,0 +1,36 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { Dictionary, DictionaryEntry } from '@open-mercato/core/modules/dictionaries/data/entities'
+import { FeatureToggle } from '@open-mercato/core/modules/feature_toggles/data/entities'
+import { ADJUSTMENT_TOGGLE, REASON_DICTIONARY, DEFAULT_ADJUSTMENT_REASONS } from '../data/price-adjustments'
+import type { TenantScope } from '../services/types'
+
+/** Add missing defaults; never overwrite an operator's labels or disabled flags. */
+export async function seedPriceAdjustmentDefaults(em: EntityManager, scope: TenantScope): Promise<void> {
+  // Multiple tenants may initialize concurrently. Ignore an existing global
+  // identifier (including disabled/deleted toggles), without resetting its value.
+  // POJO upserts skip entity property initializers, so timestamps must be explicit
+  // (`updated_at` is NOT NULL and only has an onUpdate hook).
+  const now = new Date()
+  await em.upsert(FeatureToggle, { identifier: ADJUSTMENT_TOGGLE, name: 'CPQ manual price adjustments',
+    type: 'boolean', defaultValue: true, category: 'CPQ', createdAt: now, updatedAt: now },
+    { onConflictFields: ['identifier'], onConflictAction: 'ignore' })
+  let dictionary = await findOneWithDecryption(em, Dictionary, { ...scope, key: REASON_DICTIONARY }, undefined, scope)
+  if (!dictionary) {
+    dictionary = em.create(Dictionary, { ...scope, key: REASON_DICTIONARY, name: 'Price adjustment reasons',
+      description: 'Reasons for negotiated prices on quotes.', managerVisibility: 'default', isSystem: false, isActive: true, createdAt: new Date(), updatedAt: new Date() })
+    em.persist(dictionary)
+    await em.flush()
+  }
+  if (dictionary.deletedAt) return
+  const existing = await findWithDecryption(em, DictionaryEntry, { ...scope, dictionary: dictionary.id,
+    normalizedValue: { $in: DEFAULT_ADJUSTMENT_REASONS.map((entry) => entry.value) } }, { limit: DEFAULT_ADJUSTMENT_REASONS.length }, scope)
+  const values = new Set(existing.map((entry) => entry.normalizedValue))
+  for (const [position, entry] of DEFAULT_ADJUSTMENT_REASONS.entries()) {
+    if (!values.has(entry.value)) {
+      em.persist(em.create(DictionaryEntry, { ...scope, dictionary, value: entry.value,
+        normalizedValue: entry.value, label: entry.label, position }))
+    }
+  }
+  await em.flush()
+}

package/src/modules/cpq/lib/priceAdjustmentView.ts

@@ -0,0 +1,259 @@
+/**
+ * Pure view helpers for negotiated quote prices. Client-safe: no service or
+ * ORM imports. Rules mirror the server resolver
+ * (`services/priceAdjustments/resolveManualAdjustments.ts`) so the UI only
+ * offers what the API would accept; the API stays the authority.
+ */
+
+export const ADJUST_PRICE_FEATURE = 'cpq.quotes.adjust_price'
+/** Matches `assertMutable` in the adjustment service. */
+export const ADJUSTMENT_EDITABLE_STATUSES = ['new', 'incomplete', 'ready'] as const
+/** Statuses where even an invalid adjustment can no longer be deleted. */
+const INVALID_DELETE_BLOCKED = ['accepted', 'rejected', 'cancelled']
+
+export type AdjustmentType = 'discount_percent' | 'discount_absolute' | 'price_override'
+export type AdjustmentLevel = 'charge' | 'line'
+
+export type WaterfallChargeInput = {
+  chargeType: 'nrc' | 'mrc' | 'usage'
+  pricingMethod?: string | null
+  unitPrice: number
+  totalPrice: number | null
+  listUnitPrice?: number
+  listTotalPrice?: number | null
+  standardUnitPrice?: number
+  standardTotalPrice?: number | null
+  adjustments?: Array<{
+    origin?: 'rule' | 'manual'
+    adjustmentId?: string
+    ruleCode: string
+    ruleName: string
+    ruleType: string
+    value: number
+    unitPriceBefore: number
+    unitPriceAfter: number
+    delta: number
+    reasonCode?: string
+    createdByUserId?: string
+  }> | null
+}
+
+export type WaterfallRow =
+  | { kind: 'list'; unitPrice: number }
+  | { kind: 'rule' | 'manual'; label: string; ruleType: string; value: number; delta: number; unitPriceAfter: number; reasonCode?: string; adjustmentId?: string }
+  | { kind: 'standard'; unitPrice: number }
+  | { kind: 'offer'; unitPrice: number }
+
+/**
+ * List → rule rows → standard → manual rows → offer. Legacy snapshots without
+ * waterfall fields fall back to the stored unit price for list and standard.
+ */
+export function waterfallRows(charge: WaterfallChargeInput): WaterfallRow[] {
+  const entries = charge.adjustments ?? []
+  const rules = entries.filter((entry) => entry.origin !== 'manual')
+  const manual = entries.filter((entry) => entry.origin === 'manual')
+  const standard = charge.standardUnitPrice ?? (manual.length ? manual[0].unitPriceBefore : charge.unitPrice)
+  const list = charge.listUnitPrice ?? (rules.length ? rules[0].unitPriceBefore : standard)
+  const step = (kind: 'rule' | 'manual') => (entry: (typeof entries)[number]): WaterfallRow => ({
+    kind, label: entry.ruleName || entry.ruleCode, ruleType: entry.ruleType, value: entry.value,
+    delta: entry.delta, unitPriceAfter: entry.unitPriceAfter, reasonCode: entry.reasonCode, adjustmentId: entry.adjustmentId,
+  })
+  const rows: WaterfallRow[] = [{ kind: 'list', unitPrice: list }, ...rules.map(step('rule'))]
+  if (rules.length || manual.length) rows.push({ kind: 'standard', unitPrice: standard })
+  rows.push(...manual.map(step('manual')), { kind: 'offer', unitPrice: charge.unitPrice })
+  return rows
+}
+
+/** Signed fraction: positive = discount, negative = surcharge, null when undefined. */
+export function discountDepth(before: number | null | undefined, after: number | null | undefined): number | null {
+  if (before == null || after == null || before === 0) return null
+  return 1 - after / before
+}
+
+export function formatDepth(depth: number | null): string | null {
+  if (depth === null || Math.abs(depth) < 0.00005) return null
+  const percent = Math.round(depth * 1000) / 10
+  return depth > 0 ? `−${percent}%` : `+${Math.abs(percent)}%`
+}
+
+/** Line-level list / standard / offer totals (per line quantity), ignoring usage. */
+export function lineWaterfallTotals(line: { quantity: number; charges: WaterfallChargeInput[] }) {
+  let list = 0, standard = 0, offer = 0
+  for (const charge of line.charges) {
+    if (charge.chargeType === 'usage' || charge.totalPrice == null) continue
+    const offerTotal = charge.totalPrice
+    const standardTotal = charge.standardTotalPrice ?? offerTotal
+    list += (charge.listTotalPrice ?? standardTotal) * line.quantity
+    standard += standardTotal * line.quantity
+    offer += offerTotal * line.quantity
+  }
+  return { list, standard, offer }
+}
+
+/** Adjustment types the server accepts for a target. */
+export function allowedAdjustmentTypes(level: AdjustmentLevel, charge?: Pick<WaterfallChargeInput, 'chargeType' | 'pricingMethod'>): AdjustmentType[] {
+  if (level === 'line') return ['discount_percent']
+  if (!charge || charge.chargeType === 'usage') return []
+  const overridable = charge.pricingMethod == null || charge.pricingMethod === 'flat' || charge.pricingMethod === 'per_unit'
+  return overridable ? ['price_override', 'discount_percent', 'discount_absolute'] : ['discount_percent', 'discount_absolute']
+}
+
+export type LineEligibilityInput = {
+  offeringId: string | null
+  /** Product-only lines are eligible too (server: `offeringId || productId`). */
+  productId?: string | null
+  configuration?: Record<string, unknown> | null
+}
+
+/** ARC mirror lines and free-form lines take no manual adjustments yet. */
+export function lineAdjustmentBlock(line: LineEligibilityInput, quoteType: string): 'mirror' | 'free_form' | null {
+  const mirrored = quoteType !== 'new' && typeof line.configuration?._arcMirroredFromItemId === 'string'
+  if (mirrored) return 'mirror'
+  if (!line.offeringId && !line.productId) return 'free_form'
+  return null
+}
+
+export type AdjustmentAccess =
+  | { editable: true; reason: null }
+  | { editable: false; reason: 'loading' | 'disabled' | 'no_permission' | 'converted' | 'locked' }
+
+export function adjustmentAccess(input: {
+  enabled: boolean | null
+  canAdjust: boolean
+  cpqStatus: string
+  convertedOrderId: string | null
+}): AdjustmentAccess {
+  if (input.enabled === null) return { editable: false, reason: 'loading' }
+  if (!input.enabled) return { editable: false, reason: 'disabled' }
+  if (!input.canAdjust) return { editable: false, reason: 'no_permission' }
+  if (input.convertedOrderId) return { editable: false, reason: 'converted' }
+  if (!(ADJUSTMENT_EDITABLE_STATUSES as readonly string[]).includes(input.cpqStatus)) return { editable: false, reason: 'locked' }
+  return { editable: true, reason: null }
+}
+
+/** An invalid adjustment can still be deleted after submission, unless the quote is final or converted. */
+export function canDeleteInvalidAdjustment(input: { enabled: boolean | null; canAdjust: boolean; cpqStatus: string; convertedOrderId: string | null }): boolean {
+  return input.enabled === true && input.canAdjust && !input.convertedOrderId && !INVALID_DELETE_BLOCKED.includes(input.cpqStatus)
+}
+
+/** English fallbacks for server error codes; keys live under `cpq.priceAdjustments.errors.*`. */
+export const ADJUSTMENT_ERROR_FALLBACKS: Record<string, string> = {
+  ADJUSTMENT_TARGET_MISSING: 'The adjusted charge no longer exists on this line',
+  TARGET_AMBIGUOUS: 'The adjusted charge appears more than once on this line',
+  ABOVE_STANDARD: 'The price is above the standard price',
+  CURRENCY_MISMATCH: 'The currency does not match the quote',
+  TYPE_NOT_ALLOWED: 'This kind of adjustment is not allowed for this charge',
+  LINE_NOT_ELIGIBLE: 'This line cannot be adjusted',
+  ADJUSTMENT_OVERLAP: 'Another adjustment already targets this charge at the same level',
+  ADJUSTMENT_LOCKED: 'Adjustments are locked for this quote',
+  STALE_REVISION: 'Prices changed since you opened this — reload and try again',
+  REASON_NOT_FOUND: 'Pick a reason from the list',
+  REASON_NOTE_REQUIRED: 'Add a note when the reason is “Other”',
+  INVALID_PERCENT: 'Enter a percentage above 0 and up to 100',
+  INVALID_AMOUNT: 'Enter an amount above 0',
+}
+
+export type AdjustmentForm = {
+  adjustmentType: AdjustmentType
+  /** Raw text from the input; parsed on submit/preview. */
+  value: string
+  reasonCode: string
+  reasonNote: string
+  /** Line level only: '' = all billable charges. */
+  chargeTypeFilter: '' | 'nrc' | 'mrc'
+}
+
+export type AdjustmentTarget =
+  | { level: 'charge'; quoteLineId: string; chargeCode: string }
+  | { level: 'line'; quoteLineId: string }
+
+/** Shape accepted by POST /price-adjustments and the preview `draft`. */
+export function buildAdjustmentDraft(form: AdjustmentForm, target: AdjustmentTarget, currencyCode: string, expectedRevision?: number) {
+  const value = Number(form.value.trim().replace(',', '.'))
+  if (!form.value.trim() || !Number.isFinite(value)) return null
+  const note = form.reasonNote.trim()
+  return {
+    level: target.level,
+    quoteLineId: target.quoteLineId,
+    ...(target.level === 'charge' ? { chargeCode: target.chargeCode } : { chargeTypeFilter: form.chargeTypeFilter || null }),
+    adjustmentType: form.adjustmentType,
+    value,
+    ...(form.adjustmentType === 'discount_percent' ? {} : { currencyCode }),
+    reasonCode: form.reasonCode,
+    ...(note ? { reasonNote: note } : {}),
+    ...(expectedRevision !== undefined ? { expectedRevision } : {}),
+  }
+}
+
+/** PATCH body: target fields are immutable server-side, so they are dropped. */
+export function toAdjustmentPatch(draft: NonNullable<ReturnType<typeof buildAdjustmentDraft>>) {
+  const { level: _level, quoteLineId: _line, chargeCode: _charge, ...patch } = draft as typeof draft & { chargeCode?: string }
+  return { ...patch, reasonNote: patch.reasonNote ?? null, currencyCode: patch.currencyCode ?? null }
+}
+
+/** Server error body → a stable code for messages (`STALE_REVISION`, `INVALID_PERCENT`, …). */
+export function adjustmentErrorCode(status: number, body: unknown): string {
+  const record = (body ?? {}) as { error?: unknown; details?: Array<{ message?: unknown }> }
+  const detail = Array.isArray(record.details) ? record.details.find((issue) => typeof issue?.message === 'string' && /^[A-Z_]+$/.test(issue.message as string)) : undefined
+  if (detail) return detail.message as string
+  if (typeof record.error === 'string' && /^[A-Z_]+$/.test(record.error)) return record.error
+  if (status === 403) return 'FORBIDDEN'
+  if (status === 409) return 'ADJUSTMENT_LOCKED'
+  return typeof record.error === 'string' ? record.error : 'UNKNOWN'
+}
+
+/** Narrow a stored charge jsonb (subscription / order item) to the waterfall shape; null when unusable. */
+export function parseStoredCharge(raw: unknown): (WaterfallChargeInput & { chargeName: string; quantity: number | null }) | null {
+  if (!raw || typeof raw !== 'object') return null
+  const record = raw as Record<string, unknown>
+  const num = (value: unknown) => (typeof value === 'number' && Number.isFinite(value) ? value : undefined)
+  const chargeType = record.chargeType === 'nrc' || record.chargeType === 'mrc' || record.chargeType === 'usage' ? record.chargeType : null
+  const unitPrice = num(record.unitPrice)
+  if (!chargeType || unitPrice === undefined) return null
+  const adjustments = Array.isArray(record.adjustments)
+    ? (record.adjustments as Array<Record<string, unknown>>).filter((entry) =>
+      entry && typeof entry === 'object' && typeof entry.ruleType === 'string' && num(entry.unitPriceAfter) !== undefined && num(entry.delta) !== undefined) as unknown as WaterfallChargeInput['adjustments']
+    : null
+  return {
+    chargeName: typeof record.chargeName === 'string' ? record.chargeName : typeof record.chargeCode === 'string' ? record.chargeCode : '—',
+    chargeType,
+    pricingMethod: typeof record.pricingMethod === 'string' ? record.pricingMethod : null,
+    unitPrice,
+    quantity: num(record.quantity) ?? null,
+    totalPrice: num(record.totalPrice) ?? null,
+    listUnitPrice: num(record.listUnitPrice),
+    listTotalPrice: num(record.listTotalPrice) ?? null,
+    standardUnitPrice: num(record.standardUnitPrice),
+    standardTotalPrice: num(record.standardTotalPrice) ?? null,
+    adjustments,
+  }
+}
+
+type ErrorSource = { adjustmentId?: string; code?: string; message?: string }
+export type AdjustmentErrorSourceQuote = {
+  adjustmentErrors?: ErrorSource[]
+  validationResult?: { errors?: ErrorSource[] } | null
+  lines?: Array<{ validationErrors?: ErrorSource[] | null; charges?: Array<{ adjustmentErrors?: ErrorSource[] }> }>
+}
+
+/**
+ * adjustmentId → first error code. Recalculation responses carry
+ * `adjustmentErrors`; a plain GET carries only the persisted validation
+ * errors (code in `message`), which is where target-missing errors live.
+ */
+export function collectAdjustmentErrors(quote: AdjustmentErrorSourceQuote | null | undefined): Map<string, string> {
+  const map = new Map<string, string>()
+  const add = (entries: ErrorSource[] | null | undefined) => {
+    for (const entry of entries ?? []) {
+      const code = entry.code ?? entry.message
+      if (entry.adjustmentId && code && !map.has(entry.adjustmentId)) map.set(entry.adjustmentId, code)
+    }
+  }
+  add(quote?.adjustmentErrors)
+  for (const line of quote?.lines ?? []) {
+    for (const charge of line.charges ?? []) add(charge.adjustmentErrors)
+    add(line.validationErrors)
+  }
+  add(quote?.validationResult?.errors)
+  return map
+}

package/src/modules/cpq/lib/quotePermissions.ts

@@ -0,0 +1,22 @@
+import { hasAllFeatures } from '@open-mercato/shared/security/features'
+
+/** Feature required to write a quote's prices (recalculate, line edits). */
+export const QUOTE_MANAGE_FEATURE = 'cpq.quotes.manage'
+
+/**
+ * Terminal quote statuses, mirrored from `TERMINAL_STATUSES` in
+ * `services/types.ts` so client components can use this helper without
+ * pulling the service layer into the browser bundle. A unit test keeps the
+ * two lists identical.
+ */
+export const TERMINAL_QUOTE_STATUSES: readonly string[] = ['accepted', 'rejected', 'cancelled']
+
+/**
+ * Whether the quote page may offer "Recalculate": the user can manage quotes
+ * (wildcard-aware) and the quote is not terminal — a saved recalculation on a
+ * terminal quote is refused by the API (409).
+ */
+export function canRecalculateQuote(grantedFeatures: readonly string[], cpqStatus: string): boolean {
+  if (TERMINAL_QUOTE_STATUSES.includes(cpqStatus)) return false
+  return hasAllFeatures(grantedFeatures, [QUOTE_MANAGE_FEATURE])
+}