@dainamite/cpq 0.4.0 → 0.6.0

package/src/modules/cpq/api/quotes/[quoteId]/status/__tests__/route.test.ts

@@ -0,0 +1,74 @@
+const transitionStatus = jest.fn()
+const runCpqMutationGuards = jest.fn()
+const runAfterSuccess = jest.fn()
+
+jest.mock('../../../../context', () => ({
+  resolveCpqRouteContext: jest.fn().mockResolvedValue({
+    auth: { sub: '77777777-7777-4777-8777-777777777777', tenantId: 't-1' },
+    organizationId: 'org-1',
+    tenantId: 't-1',
+  }),
+}))
+
+jest.mock('../../../../resolveQuotingService', () => ({
+  resolveQuotingService: () => ({ transitionStatus }),
+}))
+
+jest.mock('../../../../_helpers/quoteMutationGuard', () => ({
+  CPQ_QUOTE_RESOURCE_KIND: 'cpq.quote',
+  runCpqMutationGuards: (...args: unknown[]) => runCpqMutationGuards(...args),
+}))
+
+import { POST } from '../route'
+
+function postStatus(targetStatus: string): Request {
+  return new Request('http://localhost/api/cpq/quotes/cpq-1/status', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ targetStatus }),
+  })
+}
+
+const params = { params: Promise.resolve({ quoteId: 'cpq-1' }) }
+
+describe('POST /api/cpq/quotes/{quoteId}/status — mutation guards', () => {
+  beforeEach(() => {
+    transitionStatus.mockReset()
+    transitionStatus.mockResolvedValue({ id: 'cpq-1', cpqStatus: 'with_customer' })
+    runAfterSuccess.mockReset()
+    runCpqMutationGuards.mockReset()
+  })
+
+  it('transitions when the guards pass and then runs their after-success hooks', async () => {
+    runCpqMutationGuards.mockResolvedValue({ ok: true, runAfterSuccess })
+
+    const res = await POST(postStatus('with_customer'), params)
+
+    expect(res.status).toBe(200)
+    expect(runCpqMutationGuards).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.any(Request),
+      {
+        resourceKind: 'cpq.quote',
+        resourceId: 'cpq-1',
+        operation: 'custom',
+        mutationPayload: { action: 'transition_status', targetStatus: 'with_customer' },
+      },
+    )
+    expect(transitionStatus).toHaveBeenCalledWith('cpq-1', 'with_customer', { organizationId: 'org-1', tenantId: 't-1' }, '77777777-7777-4777-8777-777777777777')
+    expect(runAfterSuccess).toHaveBeenCalledTimes(1)
+  })
+
+  it('returns the guard response and leaves the status unchanged when a project guard blocks', async () => {
+    runCpqMutationGuards.mockResolvedValue({
+      ok: false,
+      response: Response.json({ error: 'Discount above 15% needs approval' }, { status: 422 }),
+    })
+
+    const res = await POST(postStatus('with_customer'), params)
+
+    expect(res.status).toBe(422)
+    expect(await res.json()).toEqual({ error: 'Discount above 15% needs approval' })
+    expect(transitionStatus).not.toHaveBeenCalled()
+  })
+})

package/src/modules/cpq/api/quotes/[quoteId]/status/route.ts

@@ -1,8 +1,12 @@
 import { NextResponse } from 'next/server'
 import { resolveCpqRouteContext } from '../../../context'
+import { resolveAuditActor } from '../../../../lib/auditActor'
 import { cpqTransitionStatusSchema } from '../../../../data/validators'
 import { resolveQuotingService } from '../../../resolveQuotingService'
 import { handleArcError } from '../../../_helpers/handleArcError'
+import { CPQ_QUOTE_RESOURCE_KIND, runCpqMutationGuards } from '../../../_helpers/quoteMutationGuard'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { cpqErrorDoc, cpqQuoteIdPathParams } from '../../../_helpers/quoteRouteOpenApi'
 
 export const metadata = {
   POST: { requireAuth: true, requireFeatures: ['cpq.quotes.manage'] },
@@ -17,10 +21,42 @@ export async function POST(req: Request, { params }: { params: Promise<{ quoteId
     const body = cpqTransitionStatusSchema.parse(await req.json())
     const scope = { organizationId: ctx.organizationId, tenantId: ctx.tenantId }
 
+    // Projects enforce approval rules here (e.g. block `ready → with_customer`
+    // until a discounted quote is approved).
+    const guard = await runCpqMutationGuards(ctx, req, {
+      resourceKind: CPQ_QUOTE_RESOURCE_KIND,
+      resourceId: quoteId,
+      operation: 'custom',
+      mutationPayload: { action: 'transition_status', targetStatus: body.targetStatus },
+    })
+    if (!guard.ok) return guard.response
+
     const service = resolveQuotingService(ctx)
-    const result = await service.transitionStatus(quoteId, body.targetStatus, scope)
+    const result = await service.transitionStatus(quoteId, body.targetStatus, scope, resolveAuditActor(ctx.auth))
+    await guard.runAfterSuccess()
     return NextResponse.json(result)
   } catch (err) {
     return handleArcError(err, 'cpq/quotes/[quoteId]/status.POST')
   }
 }
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'CPQ Quotes',
+  summary: 'CPQ quote status',
+  pathParams: cpqQuoteIdPathParams,
+  methods: {
+    POST: {
+      summary: 'Transition a CPQ quote to another status',
+      description:
+        'Operator-driven status change. Registered mutation guards (resource kind `cpq.quote`, action `transition_status`) run first — projects use them to enforce approvals.',
+      requestBody: { schema: cpqTransitionStatusSchema },
+      responses: [{ status: 200, description: 'Quote with its new status' }],
+      errors: [
+        cpqErrorDoc(400, 'Validation error'),
+        cpqErrorDoc(404, 'Quote not found'),
+        cpqErrorDoc(409, 'Transition not allowed'),
+        cpqErrorDoc(422, 'ARC validation failed or blocked by a mutation guard'),
+      ],
+    },
+  },
+}

package/src/modules/cpq/api/quotes/price/__tests__/route.test.ts

@@ -0,0 +1,37 @@
+const resolveProductCharges = jest.fn()
+jest.mock('../../../context', () => ({ resolveCpqRouteContext: async () => ({ auth: { sub: 'user' }, tenantId: 'tenant', organizationId: 'org', container: { resolve: () => ({ resolveProductCharges }) } }) }))
+import { POST, openApi } from '../route'
+const offeringId = '11111111-1111-4111-8111-111111111111'
+const charge = { chargeCode: 'fee', chargeName: 'Fee', chargeType: 'mrc', pricingMethod: 'flat', quantity: 1,
+  unitPrice: 90, totalPrice: 90, currencyCode: 'USD', listUnitPrice: 100, listTotalPrice: 100, standardUnitPrice: 90, standardTotalPrice: 90,
+  adjustments: [{ origin: 'rule', ruleCode: 'volume', ruleName: 'Volume', ruleType: 'discount_percent', value: 10, unitPriceBefore: 100, unitPriceAfter: 90, delta: -10 }] }
+const body = { primaryItem: { offeringId, configuration: {} }, childItems: [{ offeringId, configuration: {} }], currencyCode: 'USD' }
+function request(input: unknown) { return new Request('http://localhost/api/cpq/quotes/price', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(input) }) }
+beforeEach(() => { resolveProductCharges.mockReset(); resolveProductCharges.mockResolvedValue([charge]) })
+it('keeps waterfall fields out of primary and child prices by default while tagging rules', async () => {
+  const response = await POST(request(body))
+  expect(response.status).toBe(200)
+  const result = await response.json()
+  for (const item of [result.primaryCharges[0], result.childItems[0].charges[0]]) {
+    expect(item).not.toHaveProperty('listUnitPrice')
+    expect(item).not.toHaveProperty('listTotalPrice')
+    expect(item).not.toHaveProperty('standardUnitPrice')
+    expect(item).not.toHaveProperty('standardTotalPrice')
+    expect(item.adjustments[0].origin).toBe('rule')
+  }
+  expect(result.totals.mrcTotal).toBe(180)
+})
+it('returns list and standard fields only with explicit includeWaterfall', async () => {
+  const result = await (await POST(request({ ...body, includeWaterfall: true }))).json()
+  expect(result.primaryCharges[0]).toEqual(charge)
+  expect(result.childItems[0].charges[0]).toEqual(charge)
+})
+it('never forwards draft adjustments to the catalog engine', async () => {
+  await POST(request({ ...body, priceAdjustments: [{ value: 80 }] }))
+  expect(resolveProductCharges).toHaveBeenCalledWith({ offeringId, productId: undefined, configuration: {}, currencyCode: 'USD', tenantId: 'tenant', organizationId: 'org' })
+})
+it('rejects malformed waterfall flags and documents the request contract', async () => {
+  expect((await POST(request({ ...body, includeWaterfall: 'yes' }))).status).toBe(400)
+  expect(resolveProductCharges).not.toHaveBeenCalled()
+  expect(openApi.methods.POST?.requestBody).toBeDefined()
+})

package/src/modules/cpq/api/quotes/price/route.ts

@@ -1,10 +1,13 @@
 import { NextResponse } from 'next/server'
 import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { cpqErrorDoc } from '../../_helpers/quoteRouteOpenApi'
 import { resolveCpqRouteContext } from '../../context'
 import { cpqPricePreviewSchema } from '../../../data/validators'
 import type { DefaultCpqPricingService } from '../../../services/cpqPricingService'
 import type { ResolvedCharge } from '../../../services/types'
 import { getBaseCurrencyCode } from '../../../services/types'
+import { withChargeWaterfall, withoutChargeWaterfall } from '../../../services/priceAdjustments/chargeWaterfall'
 
 export const metadata = {
   POST: { requireAuth: true, requireFeatures: ['cpq.quotes.view'] },
@@ -65,9 +68,10 @@ export async function POST(req: Request) {
         note: c.note ?? 'Usage-based charge — billed on actual consumption.',
       }))
 
+    const presentCharge = body.includeWaterfall ? withChargeWaterfall : withoutChargeWaterfall
     return NextResponse.json({
-      primaryCharges,
-      childItems,
+      primaryCharges: primaryCharges.map(presentCharge),
+      childItems: childItems.map((item) => ({ ...item, charges: item.charges.map(presentCharge) })),
       totals: { nrcTotal, mrcTotal, usageCharges },
       currencyCode,
     })
@@ -79,3 +83,25 @@ export async function POST(req: Request) {
     return NextResponse.json({ error: 'Internal error' }, { status: 500 })
   }
 }
+
+
+const chargeDoc = z.object({
+  chargeCode: z.string(), chargeName: z.string(), chargeType: z.enum(['nrc', 'mrc', 'usage']),
+  pricingMethod: z.enum(['flat', 'per_unit', 'volume', 'tiered']), currencyCode: z.string(),
+  unitPrice: z.number(), quantity: z.number().nullable(), totalPrice: z.number().nullable(),
+  listUnitPrice: z.number().optional(), listTotalPrice: z.number().nullable().optional(),
+  standardUnitPrice: z.number().optional(), standardTotalPrice: z.number().nullable().optional(),
+  adjustments: z.array(z.object({ origin: z.literal('rule'), ruleCode: z.string(), ruleName: z.string(),
+    ruleType: z.string(), value: z.number(), unitPriceBefore: z.number(), unitPriceAfter: z.number(), delta: z.number() }).passthrough()).nullish(),
+}).passthrough()
+export const openApi: OpenApiRouteDoc = { tag: 'CPQ Pricing', methods: { POST: {
+  summary: 'Calculate catalog prices and price rules without saving',
+  description: 'Manual quote adjustments are never applied. Set includeWaterfall=true to return list and standard prices; these fields are omitted by default.',
+  requestBody: { schema: cpqPricePreviewSchema },
+  responses: [{ status: 200, description: 'Resolved rule prices and optional waterfall', schema: z.object({
+    primaryCharges: z.array(chargeDoc),
+    childItems: z.array(z.object({ offeringId: z.string().nullable(), productId: z.string().nullable(), charges: z.array(chargeDoc) })),
+    totals: z.object({ nrcTotal: z.number(), mrcTotal: z.number(), usageCharges: z.array(z.unknown()) }), currencyCode: z.string(),
+  }) }],
+  errors: [cpqErrorDoc(400, 'Invalid pricing request'), cpqErrorDoc(500, 'Price calculation failed')],
+} } }

package/src/modules/cpq/api/quotes/route.ts

@@ -2,7 +2,7 @@ import { NextResponse } from 'next/server'
 import { z } from 'zod'
 import { resolveCpqRouteContext } from '../context'
 import { cpqCreateQuoteSchema } from '../../data/validators'
-import { QuotingError } from '../../services/cpqQuotingService'
+import { isQuotingError } from '../../services/cpqQuotingService'
 import { resolveQuotingService } from '../resolveQuotingService'
 import { CpqQuoteConfiguration } from '../../data/entities'
 import { SalesQuote } from '@open-mercato/core/modules/sales/data/entities'
@@ -104,7 +104,7 @@ function handleError(err: unknown, context: string) {
   if (err instanceof z.ZodError) {
     return NextResponse.json({ error: 'Validation error', details: err.issues }, { status: 400 })
   }
-  if (err instanceof QuotingError) {
+  if (isQuotingError(err)) {
     const body: Record<string, unknown> = { error: err.message }
     if (err.cpqStatus) body.cpqStatus = err.cpqStatus
     return NextResponse.json(body, { status: err.status })

package/src/modules/cpq/backend/cpq/inventory/AssetsTable.tsx

@@ -2,7 +2,7 @@
 import * as React from 'react'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { useRouter } from 'next/navigation'
-import type { ColumnDef } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { DataTable } from '@open-mercato/ui/backend/DataTable'
 import { RowActions } from '@open-mercato/ui/backend/RowActions'
 import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'

package/src/modules/cpq/backend/cpq/inventory/SubscriptionsTable.tsx

@@ -2,7 +2,7 @@
 import * as React from 'react'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { useRouter } from 'next/navigation'
-import type { ColumnDef } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { DataTable } from '@open-mercato/ui/backend/DataTable'
 import { RowActions } from '@open-mercato/ui/backend/RowActions'
 import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'

package/src/modules/cpq/backend/cpq/inventory/page.meta.ts

@@ -10,7 +10,7 @@ export const metadata = {
   pageTitleKey: 'cpq.inventory.title',
   pageGroup: 'CPQ',
   pageGroupKey: 'customers~sales~cpq.nav.group',
-  pageOrder: 92,
+  pageOrder: 3,
   icon: inventoryIcon,
   breadcrumb: [{ label: 'CPQ Subscriptions', labelKey: 'cpq.inventory.title' }],
 } as const

package/src/modules/cpq/backend/cpq/inventory/subscriptions/[id]/page.tsx

@@ -11,6 +11,8 @@ import {
   type SubscriptionStatus,
 } from '../../../../../components/statusMaps'
 import { StatusPath } from '../../../../../components/StatusPath'
+import { DepthBadge, PriceWaterfall } from '../../../../../components/PriceWaterfall'
+import { parseStoredCharge } from '../../../../../lib/priceAdjustmentView'
 
 // XD-250 — ARC integration on subscription detail.
 //   • header buttons (Amend / Renew / Cancel) call /from-subscription
@@ -682,21 +684,41 @@ export default function SubscriptionDetailPage(props: { params?: { id?: string }
                               <tr className="text-muted-foreground">
                                 <th className="text-left py-1 font-medium">Charge</th>
                                 <th className="text-left py-1 font-medium">Type</th>
-                                <th className="text-right py-1 font-medium">Unit Price</th>
+                                <th className="text-right py-1 font-medium">List</th>
+                                <th className="text-right py-1 font-medium">Offer</th>
                                 <th className="text-right py-1 font-medium">Qty</th>
                                 <th className="text-right py-1 font-medium">Total</th>
                               </tr>
                             </thead>
                             <tbody>
-                              {item.charges.map((c, i) => (
-                                <tr key={i} className="border-t border-dashed border-border/50">
-                                  <td className="py-1">{(c as any).chargeName ?? '—'}</td>
-                                  <td className="py-1 uppercase">{(c as any).chargeType ?? '—'}</td>
-                                  <td className="py-1 text-right font-mono">{(c as any).unitPrice != null ? fmt((c as any).unitPrice, currency) : '—'}</td>
-                                  <td className="py-1 text-right font-mono">{(c as any).quantity ?? '—'}</td>
-                                  <td className="py-1 text-right font-mono">{(c as any).totalPrice != null ? fmt((c as any).totalPrice, currency) : '—'}</td>
-                                </tr>
-                              ))}
+                              {item.charges.map((raw, i) => {
+                                const c = parseStoredCharge(raw)
+                                if (!c) return null
+                                return (
+                                  <React.Fragment key={i}>
+                                    <tr className="border-t border-dashed border-border/50">
+                                      <td className="py-1">{c.chargeName}</td>
+                                      <td className="py-1 uppercase">{c.chargeType}</td>
+                                      <td className="py-1 text-right font-mono text-muted-foreground">{fmt(c.listUnitPrice ?? c.unitPrice, currency)}</td>
+                                      <td className="py-1 text-right font-mono">
+                                        <span className="inline-flex items-center gap-1">
+                                          <DepthBadge before={c.listUnitPrice ?? c.unitPrice} after={c.unitPrice} />
+                                          {fmt(c.unitPrice, currency)}
+                                        </span>
+                                      </td>
+                                      <td className="py-1 text-right font-mono">{c.quantity ?? '—'}</td>
+                                      <td className="py-1 text-right font-mono">{c.totalPrice != null ? fmt(c.totalPrice, currency) : '—'}</td>
+                                    </tr>
+                                    {(c.adjustments?.length ?? 0) > 0 && (
+                                      <tr>
+                                        <td colSpan={6} className="pb-2 pl-4">
+                                          <PriceWaterfall charge={c} currency={currency} />
+                                        </td>
+                                      </tr>
+                                    )}
+                                  </React.Fragment>
+                                )
+                              })}
                             </tbody>
                           </table>
                         </div>

package/src/modules/cpq/backend/cpq/offerings/page.tsx

@@ -2,7 +2,7 @@
 import * as React from 'react'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { useRouter } from 'next/navigation'
-import type { ColumnDef } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { type BulkAction } from '@open-mercato/ui/backend/DataTable'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { Checkbox } from '@open-mercato/ui/primitives/checkbox'