@dainamite/cpq 0.4.0 → 0.6.0

package/src/modules/cpq/components/PriceWaterfall.tsx

@@ -0,0 +1,94 @@
+'use client'
+
+import * as React from 'react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Tag } from '@open-mercato/ui/primitives/tag'
+import {
+  discountDepth,
+  formatDepth,
+  waterfallRows,
+  type WaterfallChargeInput,
+} from '../lib/priceAdjustmentView'
+
+function money(amount: number, currency: string): string {
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(amount)
+}
+
+const TYPE_FALLBACKS: Record<string, string> = {
+  discount_percent: '% discount',
+  discount_absolute: 'amount off',
+  surcharge_percent: '% surcharge',
+  surcharge_absolute: 'fixed surcharge',
+  price_override: 'price override',
+}
+
+/** Signed depth badge: "−20%" for a discount, "+5%" for a surcharge; text, never colour only. */
+export function DepthBadge({ before, after, title }: { before: number | null | undefined; after: number | null | undefined; title?: string }) {
+  const label = formatDepth(discountDepth(before, after))
+  if (!label) return null
+  return <Tag variant="neutral" className="px-1.5 text-xs font-mono" title={title}>{label}</Tag>
+}
+
+export type PriceWaterfallProps = {
+  charge: WaterfallChargeInput & { chargeName?: string }
+  currency: string
+  /** Reason code → label; manual rows fall back to the code. */
+  reasonLabels?: Record<string, string>
+  /** Optional per-adjustment actions (edit / delete) rendered on manual rows. */
+  renderManualActions?: (adjustmentId: string) => React.ReactNode
+}
+
+/** Read-only list → rule → standard → manual → offer breakdown for one charge (unit prices). */
+export function PriceWaterfall({ charge, currency, reasonLabels, renderManualActions }: PriceWaterfallProps) {
+  const t = useT()
+  const rows = waterfallRows(charge)
+  const fmtValue = (ruleType: string, value: number) =>
+    ruleType.endsWith('_percent') ? `${value}%` : money(value, currency)
+  return (
+    <table className="w-full text-xs" data-testid="cpq-price-waterfall">
+      <thead>
+        <tr className="text-muted-foreground">
+          <th className="text-left py-0.5 font-medium">{t('cpq.priceAdjustments.waterfall.step', 'Step')}</th>
+          <th className="text-left py-0.5 font-medium">{t('cpq.priceAdjustments.waterfall.source', 'Source')}</th>
+          <th className="text-right py-0.5 font-medium">{t('cpq.priceAdjustments.waterfall.value', 'Value')}</th>
+          <th className="text-right py-0.5 font-medium">{t('cpq.priceAdjustments.waterfall.delta', 'Delta')}</th>
+          <th className="text-right py-0.5 font-medium">{t('cpq.priceAdjustments.waterfall.unitPrice', 'Unit price')}</th>
+          {renderManualActions && <th className="w-16" />}
+        </tr>
+      </thead>
+      <tbody>
+        {rows.map((row, index) => {
+          if (row.kind === 'list' || row.kind === 'standard' || row.kind === 'offer') {
+            const label = row.kind === 'list'
+              ? t('cpq.priceAdjustments.waterfall.list', 'List price')
+              : row.kind === 'standard'
+                ? t('cpq.priceAdjustments.waterfall.standard', 'Standard price')
+                : t('cpq.priceAdjustments.waterfall.offer', 'Offer price')
+            return (
+              <tr key={`${row.kind}-${index}`} className={`border-t border-border/30 ${row.kind === 'offer' ? 'font-semibold' : 'font-medium'}`}>
+                <td className="py-0.5" colSpan={4}>{label}</td>
+                <td className="py-0.5 text-right font-mono">{money(row.unitPrice, currency)}</td>
+                {renderManualActions && <td />}
+              </tr>
+            )
+          }
+          const source = row.kind === 'rule'
+            ? `${t('cpq.priceAdjustments.waterfall.rule', 'Price rule')}: ${row.label}`
+            : `${t('cpq.priceAdjustments.waterfall.manual', 'Negotiated')}: ${reasonLabels?.[row.reasonCode ?? ''] ?? row.reasonCode ?? row.label}`
+          return (
+            <tr key={`${row.kind}-${index}`} className="border-t border-border/30">
+              <td className="py-0.5 pl-3 text-muted-foreground">{t(`cpq.priceAdjustments.types.${row.ruleType}`, TYPE_FALLBACKS[row.ruleType] ?? row.ruleType)}</td>
+              <td className="py-0.5">{source}</td>
+              <td className="py-0.5 text-right font-mono">{fmtValue(row.ruleType, row.value)}</td>
+              <td className="py-0.5 text-right font-mono">{row.delta > 0 ? '+' : ''}{money(row.delta, currency)}</td>
+              <td className="py-0.5 text-right font-mono">{money(row.unitPriceAfter, currency)}</td>
+              {renderManualActions && (
+                <td className="py-0.5 text-right">{row.kind === 'manual' && row.adjustmentId ? renderManualActions(row.adjustmentId) : null}</td>
+              )}
+            </tr>
+          )
+        })}
+      </tbody>
+    </table>
+  )
+}

package/src/modules/cpq/components/PricingSummaryCard.tsx

@@ -0,0 +1,128 @@
+'use client'
+
+import * as React from 'react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { formatDepth } from '../lib/priceAdjustmentView'
+import { chargeTypeDepths, formatChangePct, type ArcRecurringDelta } from '../lib/quoteSummaryView'
+import { formatMoney } from '../lib/formatMoney'
+
+/** Pricing summary fields shared by quote and order results. Waterfall fields are absent on legacy snapshots. */
+export type PricingSummaryView = {
+  nrcTotal: number
+  mrcTotal: number
+  listNrcTotal?: number
+  listMrcTotal?: number
+  dealValue?: { list: number; standard: number; offer: number }
+  discountDepth?: { total: number | null } | null
+  usageTotalEstimated?: number | null
+  usageCharges?: Array<{ chargeName: string; unitPrice: number }>
+}
+
+export function SummaryFigure({
+  label,
+  value,
+  note,
+  title,
+  size = 'lg',
+  valueClassName,
+  testId,
+}: {
+  label: string
+  value: string
+  note?: string | null
+  title?: string
+  size?: 'lg' | 'sm'
+  valueClassName?: string
+  testId?: string
+}) {
+  return (
+    <div data-testid={testId}>
+      <p className="text-xs text-muted-foreground" title={title}>{label}</p>
+      <p className={`${size === 'lg' ? 'text-lg' : 'text-sm'} font-semibold font-mono ${valueClassName ?? ''}`}>
+        {value}
+        {note && <span className="ml-1.5 text-xs font-normal text-muted-foreground">({note})</span>}
+      </p>
+    </div>
+  )
+}
+
+/**
+ * NRC / MRC / deal value with discount depth in brackets, plus the ARC
+ * current → new MRC row on Amend / Renew documents. Shared by the quote and
+ * order detail pages so both read the same.
+ */
+export function PricingSummaryCard({ summary, currency, arcDelta }: {
+  summary: PricingSummaryView
+  currency: string
+  arcDelta?: ArcRecurringDelta | null
+}) {
+  const t = useT()
+  const typeDepths = chargeTypeDepths(summary)
+  const usageCharges = summary.usageCharges ?? []
+  return (
+    <div className="rounded-lg border bg-card p-4" data-testid="cpq-pricing-summary">
+      <h3 className="text-sm font-medium mb-3">{t('cpq.quotes.summary.title', 'Pricing Summary')}</h3>
+      <div className="grid grid-cols-2 sm:grid-cols-4 gap-4">
+        <SummaryFigure
+          label={t('cpq.quotes.summary.nrc', 'Non-Recurring (NRC)')}
+          value={formatMoney(summary.nrcTotal, currency)}
+          note={formatDepth(typeDepths.nrc)}
+          testId="cpq-summary-nrc"
+        />
+        <SummaryFigure
+          label={t('cpq.quotes.summary.mrc', 'Monthly Recurring (MRC)')}
+          value={formatMoney(summary.mrcTotal, currency)}
+          note={formatDepth(typeDepths.mrc)}
+          testId="cpq-summary-mrc"
+        />
+        {summary.dealValue && (
+          <SummaryFigure
+            label={t('cpq.priceAdjustments.summary.dealValue', 'Deal value')}
+            title={t('cpq.priceAdjustments.summary.hint', 'Deal value counts recurring charges over the term plus one-time charges; existing subscription items on change quotes are excluded.')}
+            value={formatMoney(summary.dealValue.offer, currency)}
+            note={formatDepth(summary.discountDepth?.total ?? null)}
+            testId="cpq-deal-value"
+          />
+        )}
+        {summary.usageTotalEstimated != null && (
+          <SummaryFigure
+            label={t('cpq.quotes.summary.usageEstimated', 'Usage (est.)')}
+            value={formatMoney(summary.usageTotalEstimated, currency)}
+          />
+        )}
+        {usageCharges.length > 0 && (
+          <div>
+            <p className="text-xs text-muted-foreground">{t('cpq.quotes.summary.usageCharges', 'Usage Charges')}</p>
+            {usageCharges.map((uc, i) => (
+              <p key={i} className="text-xs mt-0.5">{uc.chargeName}: {formatMoney(uc.unitPrice, currency)}/unit</p>
+            ))}
+          </div>
+        )}
+      </div>
+      {arcDelta && (
+        <div className="mt-4 grid grid-cols-2 sm:grid-cols-4 gap-4 border-t pt-3" data-testid="cpq-arc-delta">
+          <SummaryFigure
+            size="sm"
+            testId="cpq-arc-current-mrc"
+            label={t('cpq.quotes.summary.arc.currentMrc', 'Current MRC')}
+            value={formatMoney(arcDelta.currentMrc, currency)}
+          />
+          <SummaryFigure
+            size="sm"
+            testId="cpq-arc-new-mrc"
+            label={t('cpq.quotes.summary.arc.newMrc', 'New MRC')}
+            value={formatMoney(arcDelta.newMrc, currency)}
+          />
+          <SummaryFigure
+            size="sm"
+            testId="cpq-arc-mrc-change"
+            label={t('cpq.quotes.summary.arc.mrcChange', 'MRC change')}
+            value={`${arcDelta.delta > 0 ? '+' : ''}${formatMoney(arcDelta.delta, currency)}`}
+            valueClassName={arcDelta.delta > 0 ? 'text-status-success-text' : arcDelta.delta < 0 ? 'text-destructive' : undefined}
+            note={formatChangePct(arcDelta.deltaPct)}
+          />
+        </div>
+      )}
+    </div>
+  )
+}

package/src/modules/cpq/components/__tests__/PriceWaterfall.test.tsx

@@ -0,0 +1,38 @@
+import * as React from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { I18nProvider } from '@open-mercato/shared/lib/i18n/context'
+import { DepthBadge, PriceWaterfall } from '../PriceWaterfall'
+
+const withI18n = (node: React.ReactNode) => <I18nProvider locale="en" dict={{}}>{node}</I18nProvider>
+
+const text = (html: string) => html.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim()
+
+it('renders list, rule, standard, negotiated and offer steps with the reason label', () => {
+  const html = renderToStaticMarkup(withI18n(
+    <PriceWaterfall
+      currency="USD"
+      reasonLabels={{ competitive_match: 'Competitive match' }}
+      charge={{
+        chargeType: 'mrc', unitPrice: 80, totalPrice: 80, listUnitPrice: 100, standardUnitPrice: 90,
+        adjustments: [
+          { origin: 'rule', ruleCode: 'VOL', ruleName: 'Volume', ruleType: 'discount_percent', value: 10, unitPriceBefore: 100, unitPriceAfter: 90, delta: -10 },
+          { origin: 'manual', adjustmentId: 'a1', ruleCode: 'a1', ruleName: 'competitive_match', ruleType: 'price_override', value: 80, unitPriceBefore: 90, unitPriceAfter: 80, delta: -10, reasonCode: 'competitive_match' },
+        ],
+      }}
+      renderManualActions={(id) => <button>edit {id}</button>}
+    />,
+  ))
+  const content = text(html)
+  expect(content).toMatch(/List price \$100\.00/)
+  expect(content).toMatch(/Price rule: Volume 10%/)
+  expect(content).toMatch(/Standard price \$90\.00/)
+  expect(content).toMatch(/Negotiated: Competitive match \$80\.00/)
+  expect(content).toMatch(/Offer price \$80\.00/)
+  expect(content).toContain('edit a1')
+  expect(content.match(/edit/g)).toHaveLength(1)
+})
+
+it('renders a signed depth badge only when prices differ', () => {
+  expect(text(renderToStaticMarkup(<DepthBadge before={100} after={80} />))).toBe('−20%')
+  expect(renderToStaticMarkup(<DepthBadge before={100} after={100} />)).toBe('')
+})

package/src/modules/cpq/components/useGrantedFeatures.ts

@@ -0,0 +1,35 @@
+'use client'
+
+import * as React from 'react'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+
+type FeatureCheckResponse = { granted: string[] }
+
+/**
+ * Resolve which of `features` the current user holds, through the framework's
+ * `POST /api/auth/feature-check` endpoint (the same one the component-override
+ * provider uses). Returns an empty list until the check completes, so callers
+ * hide privileged actions by default.
+ */
+export function useGrantedFeatures(features: readonly string[]): readonly string[] {
+  const [granted, setGranted] = React.useState<readonly string[]>([])
+  const key = features.join('|')
+
+  React.useEffect(() => {
+    if (!key) return
+    let cancelled = false
+    void (async () => {
+      const call = await apiCall<FeatureCheckResponse>('/api/auth/feature-check', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ features: key.split('|') }),
+      })
+      if (!cancelled && call.ok && call.result?.granted) setGranted(call.result.granted)
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [key])
+
+  return granted
+}

package/src/modules/cpq/data/__tests__/price-adjustment-migration.test.ts

@@ -0,0 +1,11 @@
+import { Migration20261110213052 } from '../../migrations/Migration20261110213052'
+
+it('generates a rollback that removes the new table before it can be recreated', () => {
+  const up: string[] = [], down: string[] = []
+  Migration20261110213052.prototype.up.call({ addSql: (sql: string) => up.push(sql) } as never)
+  Migration20261110213052.prototype.down.call({ addSql: (sql: string) => down.push(sql) } as never)
+  expect(up.join('\n')).toContain('create table "cpq_quote_price_adjustments"')
+  expect(down.join('\n')).toContain('drop table if exists "cpq_quote_price_adjustments"')
+  expect(up.join('\n')).toContain('add "pricing_revision"')
+  expect(down.join('\n')).toContain('drop column "pricing_revision"')
+})

package/src/modules/cpq/data/__tests__/price-adjustments.test.ts

@@ -0,0 +1,26 @@
+import { cpqPriceAdjustmentInputSchema, cpqPriceAdjustmentPatchSchema } from '../price-adjustments'
+const valid = {
+  level: 'charge', quoteLineId: '11111111-1111-4111-8111-111111111111', chargeCode: 'setup',
+  adjustmentType: 'price_override', value: 80, currencyCode: 'USD', reasonCode: 'competitive_match',
+}
+it('allows a zero override and percentage discounts with no currency', () => {
+  expect(cpqPriceAdjustmentInputSchema.parse({ ...valid, value: 0 }).value).toBe(0)
+  expect(cpqPriceAdjustmentInputSchema.parse({ ...valid, adjustmentType: 'discount_percent', value: 100, currencyCode: undefined }).value).toBe(100)
+})
+it.each([
+  { level: 'quote' }, { quoteLineId: 'bad' }, { chargeCode: null }, { value: -1 }, { value: Infinity }, { value: 1.23456 }, { value: 100_000_000_000_000 },
+  { adjustmentType: 'discount_percent', value: 101 }, { adjustmentType: 'discount_percent', value: 0 },
+  { adjustmentType: 'discount_absolute', value: 0 }, { currencyCode: null }, { currencyCode: 'usd' },
+  { reasonCode: 'other', reasonNote: '' }, { reasonNote: 'x'.repeat(501) },
+  { fromMonth: 2 }, { toMonth: 3 }, { windowKind: 'absolute' },
+  { level: 'line', chargeCode: undefined, adjustmentType: 'price_override' }, { chargeTypeFilter: 'mrc' },
+])('rejects malformed or unsupported adjustments: %j', (patch) => {
+  expect(cpqPriceAdjustmentInputSchema.safeParse({ ...valid, ...patch }).success).toBe(false)
+})
+it('accepts filtered line percentages and an explanation for other', () => {
+  expect(cpqPriceAdjustmentInputSchema.safeParse({ ...valid, level: 'line', chargeCode: undefined, chargeTypeFilter: 'mrc', adjustmentType: 'discount_percent', value: 20, reasonCode: 'other', reasonNote: 'One-time negotiation' }).success).toBe(true)
+})
+it('never accepts target changes through PATCH; merged patches are validated by the full schema', () => {
+  expect(cpqPriceAdjustmentPatchSchema.safeParse({ quoteLineId: valid.quoteLineId }).success).toBe(false)
+  expect(cpqPriceAdjustmentPatchSchema.parse({ reasonNote: 'New note' })).toEqual({ reasonNote: 'New note' })
+})

package/src/modules/cpq/data/entities.ts

@@ -631,6 +631,7 @@ export class CpqPriceRule {
 export class CpqQuoteConfiguration {
   [OptionalProps]?:
     | 'cpqStatus'
+    | 'pricingRevision'
     | 'version'
     | 'currencyCode'
     | 'quoteType'
@@ -653,6 +654,9 @@ export class CpqQuoteConfiguration {
   @Property({ name: 'customer_id', type: 'uuid' })
   customerId!: string
 
+  @Property({ name: 'pricing_revision', type: 'integer', default: 0 })
+  pricingRevision: number = 0
+
   @Property({ name: 'cpq_status', type: 'text', default: 'new' })
   cpqStatus: string = 'new'
 
@@ -1475,3 +1479,82 @@ export class CpqSubscriptionChangeLog {
   @Property({ name: 'deleted_at', type: Date, nullable: true })
   deletedAt?: Date | null
 }
+
+
+// ─── Deal-specific adjustments, separate from catalog price rules ───
+@Entity({ tableName: 'cpq_quote_price_adjustments' })
+@Index({ name: 'cpq_qpa_quote_config_idx', properties: ['organizationId', 'tenantId', 'quoteConfigurationId'] })
+@Index({ name: 'cpq_qpa_quote_line_idx', properties: ['organizationId', 'tenantId', 'quoteLineId'] })
+@Index({ name: 'cpq_qpa_quote_idx', properties: ['organizationId', 'tenantId', 'quoteId'] })
+export class CpqQuotePriceAdjustment {
+  [OptionalProps]?: 'windowKind' | 'fromMonth' | 'toMonth' | 'isActive' | 'createdAt' | 'updatedAt' | 'deletedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'quote_configuration_id', type: 'uuid' })
+  quoteConfigurationId!: string
+
+  @Property({ name: 'quote_id', type: 'uuid' })
+  quoteId!: string
+
+  @Property({ name: 'quote_line_id', type: 'uuid' })
+  quoteLineId!: string
+
+  @Property({ type: 'text' })
+  level!: 'charge' | 'line'
+
+  @Property({ name: 'charge_code', type: 'text', nullable: true })
+  chargeCode: string | null = null
+
+  @Property({ name: 'charge_type_filter', type: 'text', nullable: true })
+  chargeTypeFilter: 'nrc' | 'mrc' | null = null
+
+  @Property({ name: 'adjustment_type', type: 'text' })
+  adjustmentType!: 'discount_percent' | 'discount_absolute' | 'price_override'
+
+  @Property({ type: 'numeric', columnType: 'numeric(18, 4)' })
+  value!: string
+
+  @Property({ name: 'currency_code', type: 'text', nullable: true })
+  currencyCode: string | null = null
+
+  @Property({ name: 'window_kind', type: 'text', default: 'relative' })
+  windowKind: string = 'relative'
+
+  @Property({ name: 'from_month', type: 'integer', default: 1 })
+  fromMonth: number = 1
+
+  @Property({ name: 'to_month', type: 'integer', nullable: true })
+  toMonth: number | null = null
+
+  @Property({ name: 'reason_code', type: 'text' })
+  reasonCode!: string
+
+  @Property({ name: 'reason_note', type: 'text', nullable: true })
+  reasonNote: string | null = null
+
+  @Property({ name: 'created_by_user_id', type: 'uuid' })
+  createdByUserId!: string
+
+  @Property({ name: 'updated_by_user_id', type: 'uuid', nullable: true })
+  updatedByUserId: string | null = null
+
+  @Property({ name: 'is_active', type: 'boolean', default: true })
+  isActive: boolean = true
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt: Date | null = null
+}

package/src/modules/cpq/data/price-adjustments.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod'
+
+export const adjustmentTypeSchema = z.enum(['discount_percent', 'discount_absolute', 'price_override'])
+const adjustmentFields = {
+  adjustmentType: adjustmentTypeSchema,
+  // Match numeric(18,4), so saving never silently rounds the previewed input.
+  value: z.number().finite().min(0).max(99_999_999_999_999).multipleOf(0.0001),
+  currencyCode: z.string().regex(/^[A-Z]{3}$/).nullish(),
+  chargeTypeFilter: z.enum(['nrc', 'mrc']).nullish(),
+  reasonCode: z.string().trim().min(1).max(100),
+  reasonNote: z.string().trim().max(500).nullish(),
+  expectedRevision: z.number().int().min(0).optional(),
+}
+export const cpqPriceAdjustmentInputSchema = z.object({
+  ...adjustmentFields,
+  level: z.enum(['charge', 'line']),
+  quoteLineId: z.string().uuid(),
+  chargeCode: z.string().trim().min(1).max(255).nullish(),
+  windowKind: z.literal('relative').optional(),
+  fromMonth: z.literal(1).optional(),
+  toMonth: z.null().optional(),
+}).strict().superRefine((input, ctx) => {
+  const error = (path: string, message: string) => ctx.addIssue({ code: 'custom', path: [path], message })
+  if (input.level === 'charge' && !input.chargeCode) error('chargeCode', 'TARGET_NOT_FOUND')
+  if (input.level === 'charge' && input.chargeTypeFilter) error('chargeTypeFilter', 'TYPE_NOT_ALLOWED')
+  if (input.level === 'line' && input.chargeCode) error('chargeCode', 'TYPE_NOT_ALLOWED')
+  if (input.level === 'line' && input.adjustmentType !== 'discount_percent') error('adjustmentType', 'TYPE_NOT_ALLOWED')
+  if (input.adjustmentType === 'discount_percent' && (input.value <= 0 || input.value > 100)) error('value', 'INVALID_PERCENT')
+  if (input.adjustmentType === 'discount_absolute' && input.value <= 0) error('value', 'INVALID_AMOUNT')
+  if (input.adjustmentType !== 'discount_percent' && !input.currencyCode) error('currencyCode', 'CURRENCY_REQUIRED')
+  if (input.reasonCode === 'other' && !input.reasonNote) error('reasonNote', 'REASON_NOTE_REQUIRED')
+})
+export const cpqPriceAdjustmentPatchSchema = z.object(adjustmentFields).partial().strict()
+export type PriceAdjustmentInput = z.infer<typeof cpqPriceAdjustmentInputSchema>
+export type PriceAdjustmentPatch = z.infer<typeof cpqPriceAdjustmentPatchSchema>
+
+/** Pure pricing representation; persistence metadata stays outside the resolver. */
+export const resolvedPriceAdjustmentSchema = z.object({
+  ...cpqPriceAdjustmentInputSchema.shape,
+  id: z.string().uuid(),
+  createdByUserId: z.string().uuid().optional(),
+})
+export type PriceAdjustment = z.infer<typeof resolvedPriceAdjustmentSchema>
+export const adjustmentErrorSchema = z.object({
+  adjustmentId: z.string(),
+  quoteLineId: z.string(),
+  chargeCode: z.string().optional(),
+  code: z.enum(['ADJUSTMENT_TARGET_MISSING', 'TARGET_AMBIGUOUS', 'ABOVE_STANDARD', 'CURRENCY_MISMATCH', 'TYPE_NOT_ALLOWED', 'LINE_NOT_ELIGIBLE', 'ADJUSTMENT_OVERLAP']),
+})
+export type AdjustmentError = z.infer<typeof adjustmentErrorSchema>
+
+export const cpqPriceAdjustmentPreviewSchema = z.object({
+  draft: cpqPriceAdjustmentInputSchema,
+  replaceAdjustmentId: z.string().uuid().optional(),
+}).strict()
+
+export const ADJUSTMENT_TOGGLE = 'cpq.manual_price_adjustments'
+export const REASON_DICTIONARY = 'cpq.price_adjustment_reason'
+export const DEFAULT_ADJUSTMENT_REASONS = [
+  { value: 'competitive_match', label: 'Competitive match' },
+  { value: 'volume_commitment', label: 'Volume commitment' },
+  { value: 'loyalty', label: 'Loyalty' },
+  { value: 'promotion', label: 'Promotion' },
+  { value: 'strategic_deal', label: 'Strategic deal' },
+  { value: 'price_correction', label: 'Price correction' },
+  { value: 'other', label: 'Other' },
+] as const

package/src/modules/cpq/data/validators.ts

@@ -378,6 +378,7 @@ const cpqPricePreviewItemSchema = z.object({
 )
 
 export const cpqPricePreviewSchema = z.object({
+  includeWaterfall: z.boolean().optional().default(false),
   primaryItem: cpqPricePreviewItemSchema.nullish(),
   childItems: z.array(cpqPricePreviewItemSchema),
   currencyCode: z.string().min(1).optional(),
@@ -691,3 +692,5 @@ export const cpqConvertQuoteToOrderSchema = z.object({
 export const cpqOrderStatusTransitionSchema = z.object({
   targetStatus: z.string().min(1),
 })
+
+export { cpqPriceAdjustmentInputSchema, cpqPriceAdjustmentPatchSchema } from './price-adjustments'

package/src/modules/cpq/di.ts

@@ -9,6 +9,7 @@ import { DefaultCpqQuotingService } from './services/cpqQuotingService'
 import { DefaultCpqWizardService } from './services/cpqWizardService'
 import { DefaultCpqInventoryService } from './services/cpqInventoryService'
 import { DefaultCpqOrderService } from './services/cpqOrderService'
+import { CpqAdjustmentService } from './services/priceAdjustments/adjustmentService'
 import { DefaultCpqBundleService } from './services/cpqBundleService'
 
 /**
@@ -20,6 +21,11 @@ import { DefaultCpqBundleService } from './services/cpqBundleService'
  */
 export function register(container: AppContainer) {
   container.register({
+    cpqAdjustmentService: asFunction(() => new CpqAdjustmentService({
+      em: container.resolve('em'),
+      quotingService: container.resolve('cpqQuotingService'),
+      featureTogglesService: container.resolve('featureTogglesService'),
+    })).scoped(),
     cpqPricingService: asFunction(({ em }: { em: EntityManager }) => {
       return new DefaultCpqPricingService(em)
     }).scoped().proxy(),

package/src/modules/cpq/events.ts

@@ -1,4 +1,26 @@
 import { createModuleEvents } from '@open-mercato/shared/modules/events'
+import type { EventPayloadSchemaField } from '@open-mercato/shared/modules/events'
+
+/** Fields shared by both quote pricing signals (see `quotePricingEvents.ts`). */
+const quotePricingSnapshotFields: EventPayloadSchemaField[] = [
+  { path: 'tenantId', type: 'text' },
+  { path: 'organizationId', type: 'text' },
+  { path: 'quoteId', type: 'text', label: 'CPQ quote id' },
+  { path: 'quoteType', type: 'select', label: 'Quote type' },
+  { path: 'cpqStatus', type: 'text', label: 'Status' },
+  { path: 'currencyCode', type: 'text' },
+  { path: 'pricingRevision', type: 'number' },
+  { path: 'snapshotHash', type: 'text' },
+  { path: 'dealValue.list', type: 'number', label: 'Deal value (list)' },
+  { path: 'dealValue.standard', type: 'number', label: 'Deal value (standard)' },
+  { path: 'dealValue.offer', type: 'number', label: 'Deal value (offer)' },
+  { path: 'discountDepth.rule', type: 'number', label: 'Rule discount depth', optional: true },
+  { path: 'discountDepth.manual', type: 'number', label: 'Manual discount depth', optional: true },
+  { path: 'discountDepth.total', type: 'number', label: 'Total discount depth', optional: true },
+  { path: 'discountDepth.maxLineManual', type: 'number', label: 'Max line manual discount depth', optional: true },
+  { path: 'hasTimeBasedAdjustments', type: 'boolean' },
+  { path: 'occurredAt', type: 'date' },
+]
 
 /**
  * CPQ Module Events.
@@ -8,8 +30,9 @@ import { createModuleEvents } from '@open-mercato/shared/modules/events'
  * 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.
+ * Emission rule: events fire AFTER their transaction commits.
+ * Subscription events: `cpqOrderService.activateOrder` is the sole emitter.
+ * Quote events: `withQuotePricingWrite` (plus `cloneQuote` for the copy).
  */
 const events = [
   {
@@ -54,6 +77,34 @@ const events = [
     category: 'lifecycle',
     clientBroadcast: true,
   },
+  // Quote pricing signals (manual price adjustments). Emitted after the quote
+  // write commits by `withQuotePricingWrite`; payload carries the pricing
+  // snapshot (deal value, discount depth, snapshot hash) so project workflows
+  // can route approvals without CPQ code.
+  {
+    id: 'cpq.quote.pricing_changed',
+    label: 'Quote Pricing Changed',
+    entity: 'quote',
+    category: 'custom',
+    clientBroadcast: true,
+    payloadSchema: { fields: [...quotePricingSnapshotFields, { path: 'cause', type: 'select' }] },
+  },
+  {
+    id: 'cpq.quote.status_changed',
+    label: 'Quote Status Changed',
+    entity: 'quote',
+    category: 'lifecycle',
+    clientBroadcast: true,
+    payloadSchema: {
+      fields: [
+        ...quotePricingSnapshotFields,
+        { path: 'fromStatus', type: 'text' },
+        { path: 'toStatus', type: 'text' },
+        { path: 'cause', type: 'select' },
+        { path: 'actorUserId', type: 'text', optional: true },
+      ],
+    },
+  },
 ] as const
 
 export const eventsConfig = createModuleEvents({

package/src/modules/cpq/index.ts

@@ -8,7 +8,7 @@ export const metadata: ModuleInfo = {
     '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'],
+  requires: ['auth', 'directory', 'catalog', 'sales', 'customers', 'dictionaries', 'feature_toggles'],
   ejectable: false,
 }
 

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

@@ -0,0 +1,12 @@
+import { resolveAuditActor } from '../auditActor'
+
+const user = '77777777-7777-4777-8777-777777777777'
+it.each([
+  [{ sub: user }, user],
+  [{ sub: 'api_key:abc', userId: user }, user],
+  [{ sub: 'api_key:abc' }, null],
+  [{ sub: 'api_key:abc', userId: 'not-a-uuid' }, null],
+  [null, null],
+])('%j → %s', (auth, expected) => {
+  expect(resolveAuditActor(auth)).toBe(expected)
+})