@dainamite/cpq 0.5.0 → 0.6.0

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

@@ -4,6 +4,9 @@ import { resolveCpqRouteContext } from '../../../../context'
 import { cpqUpdateQuoteItemSchema } from '../../../../../data/validators'
 import { isQuotingError } from '../../../../../services/cpqQuotingService'
 import { resolveQuotingService } from '../../../../resolveQuotingService'
+import { CPQ_QUOTE_LINE_RESOURCE_KIND, runCpqMutationGuards } from '../../../../_helpers/quoteMutationGuard'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { CPQ_GUARDED_WRITE_ERRORS } from '../../../../_helpers/quoteRouteOpenApi'
 
 export const metadata = {
   PUT: { requireAuth: true, requireFeatures: ['cpq.quotes.manage'] },
@@ -19,8 +22,20 @@ export async function PUT(req: Request, { params }: { params: Promise<{ quoteId:
     const body = cpqUpdateQuoteItemSchema.parse(await req.json())
     const scope = { organizationId: ctx.organizationId, tenantId: ctx.tenantId }
 
+    const guard = await runCpqMutationGuards(ctx, req, {
+      resourceKind: CPQ_QUOTE_LINE_RESOURCE_KIND,
+      resourceId: lineId,
+      operation: 'update',
+      mutationPayload: { quoteId, ...body },
+    })
+    if (!guard.ok) return guard.response
+    const effective = guard.modifiedPayload
+      ? cpqUpdateQuoteItemSchema.parse({ ...body, ...guard.modifiedPayload })
+      : body
+
     const service = resolveQuotingService(ctx)
-    const result = await service.updateQuoteItem(quoteId, lineId, body, scope)
+    const result = await service.updateQuoteItem(quoteId, lineId, effective, scope)
+    await guard.runAfterSuccess()
     return NextResponse.json(result)
   } catch (err) {
     if (err instanceof z.ZodError) {
@@ -42,8 +57,17 @@ export async function DELETE(req: Request, { params }: { params: Promise<{ quote
     const { quoteId, lineId } = await params
     const scope = { organizationId: ctx.organizationId, tenantId: ctx.tenantId }
 
+    const guard = await runCpqMutationGuards(ctx, req, {
+      resourceKind: CPQ_QUOTE_LINE_RESOURCE_KIND,
+      resourceId: lineId,
+      operation: 'delete',
+      mutationPayload: { quoteId },
+    })
+    if (!guard.ok) return guard.response
+
     const service = resolveQuotingService(ctx)
     const result = await service.removeQuoteItem(quoteId, lineId, scope)
+    await guard.runAfterSuccess()
     return NextResponse.json(result)
   } catch (err) {
     if (isQuotingError(err)) {
@@ -53,3 +77,26 @@ export async function DELETE(req: Request, { params }: { params: Promise<{ quote
     return NextResponse.json({ error: 'Internal error' }, { status: 500 })
   }
 }
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'CPQ Quotes',
+  summary: 'CPQ quote line',
+  pathParams: z.object({ quoteId: z.string().uuid(), lineId: z.string().uuid() }),
+  methods: {
+    PUT: {
+      summary: 'Update a quote line (configuration, quantity, term)',
+      description:
+        'Re-prices the line unless it is a frozen Amend mirror line whose pricing inputs are unchanged. Mutation guards run first (resource kind `cpq.quote_line`, update). `_arc*` configuration keys are server-owned and ignored.',
+      requestBody: { schema: cpqUpdateQuoteItemSchema },
+      responses: [{ status: 200, description: 'Quote after the update' }],
+      errors: CPQ_GUARDED_WRITE_ERRORS,
+    },
+    DELETE: {
+      summary: 'Remove a quote line',
+      description:
+        'On an Amend / Renew quote, a line mirroring a live subscription item is not deleted: it (and its mirrored components) becomes a `cancel` line with zero totals, and activation terminates the item; lines this quote added under it are deleted. 409 when the item is already marked for removal — use `POST .../restore` to undo. Other lines are deleted with their descendants. Mutation guards run first (resource kind `cpq.quote_line`, delete).',
+      responses: [{ status: 200, description: 'Quote after the removal' }],
+      errors: CPQ_GUARDED_WRITE_ERRORS.filter((doc) => doc.status !== 400),
+    },
+  },
+}

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

@@ -3,6 +3,9 @@ import { resolveCpqRouteContext } from '../../../context'
 import { cpqAddQuoteItemSchema } from '../../../../data/validators'
 import { resolveQuotingService } from '../../../resolveQuotingService'
 import { handleArcError } from '../../../_helpers/handleArcError'
+import { CPQ_QUOTE_LINE_RESOURCE_KIND, runCpqMutationGuards } from '../../../_helpers/quoteMutationGuard'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { CPQ_GUARDED_WRITE_ERRORS, cpqQuoteIdPathParams } from '../../../_helpers/quoteRouteOpenApi'
 
 export const metadata = {
   POST: { requireAuth: true, requireFeatures: ['cpq.quotes.manage'] },
@@ -17,10 +20,37 @@ export async function POST(req: Request, { params }: { params: Promise<{ quoteId
     const body = cpqAddQuoteItemSchema.parse(await req.json())
     const scope = { organizationId: ctx.organizationId, tenantId: ctx.tenantId }
 
+    const guard = await runCpqMutationGuards(ctx, req, {
+      resourceKind: CPQ_QUOTE_LINE_RESOURCE_KIND,
+      operation: 'create',
+      mutationPayload: { quoteId, ...body },
+    })
+    if (!guard.ok) return guard.response
+    const effective = guard.modifiedPayload
+      ? cpqAddQuoteItemSchema.parse({ ...body, ...guard.modifiedPayload })
+      : body
+
     const service = resolveQuotingService(ctx)
-    const result = await service.addQuoteItem(quoteId, body, scope)
+    const result = await service.addQuoteItem(quoteId, effective, scope)
+    await guard.runAfterSuccess()
     return NextResponse.json(result, { status: 201 })
   } catch (err) {
     return handleArcError(err, 'cpq/quotes/[quoteId]/items.POST')
   }
 }
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'CPQ Quotes',
+  summary: 'CPQ quote lines',
+  pathParams: cpqQuoteIdPathParams,
+  methods: {
+    POST: {
+      summary: 'Add a configured line to a CPQ quote',
+      description:
+        'Prices the line and recalculates the quote. Mutation guards run first (resource kind `cpq.quote_line`, create). `_arc*` configuration keys are server-owned and ignored.',
+      requestBody: { schema: cpqAddQuoteItemSchema },
+      responses: [{ status: 201, description: 'Quote after the line was added' }],
+      errors: CPQ_GUARDED_WRITE_ERRORS,
+    },
+  },
+}

package/src/modules/cpq/api/quotes/[quoteId]/price-adjustments/[adjustmentId]/route.ts

@@ -0,0 +1,39 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { resolveCpqRouteContext } from '../../../../context'
+import { cpqPriceAdjustmentPatchSchema } from '../../../../../data/price-adjustments'
+import { adjustmentCommandRoute } from '../../../../_helpers/adjustmentCommandRoute'
+import { handleArcError } from '../../../../_helpers/handleArcError'
+import { cpqErrorDoc } from '../../../../_helpers/quoteRouteOpenApi'
+
+export const metadata = {
+  PATCH: { requireAuth: true, requireFeatures: ['cpq.quotes.manage', 'cpq.quotes.adjust_price'] },
+  DELETE: { requireAuth: true, requireFeatures: ['cpq.quotes.manage', 'cpq.quotes.adjust_price'] },
+}
+const pathParams = z.object({ quoteId: z.string().uuid(), adjustmentId: z.string().uuid() })
+const deletionSchema = z.object({ expectedRevision: z.coerce.number().int().min(0).optional() }).strict()
+type Params = { params: Promise<{ quoteId: string; adjustmentId: string }> }
+export async function PATCH(req: Request, { params }: Params) {
+  try {
+    const ctx = await resolveCpqRouteContext(req)
+    if (!ctx.auth) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    const { quoteId, adjustmentId } = pathParams.parse(await params)
+    const body = cpqPriceAdjustmentPatchSchema.parse(await req.json())
+    return await adjustmentCommandRoute(req, ctx, quoteId, body, cpqPriceAdjustmentPatchSchema, 'update', adjustmentId)
+  } catch (error) { return handleArcError(error, 'cpq/price-adjustments.PATCH') }
+}
+export async function DELETE(req: Request, { params }: Params) {
+  try {
+    const ctx = await resolveCpqRouteContext(req)
+    if (!ctx.auth) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    const { quoteId, adjustmentId } = pathParams.parse(await params)
+    const body = deletionSchema.parse(Object.fromEntries(new URL(req.url).searchParams))
+    return await adjustmentCommandRoute(req, ctx, quoteId, body, deletionSchema, 'delete', adjustmentId)
+  } catch (error) { return handleArcError(error, 'cpq/price-adjustments.DELETE') }
+}
+const errors = [cpqErrorDoc(400, 'Invalid input'), cpqErrorDoc(403, 'Missing permission or disabled feature'), cpqErrorDoc(404, 'Quote or adjustment not found'), cpqErrorDoc(409, 'Adjustment locked, stale revision or changed undo target'), cpqErrorDoc(422, 'Invalid adjustment or guard rejection')]
+export const openApi: OpenApiRouteDoc = { tag: 'CPQ Quotes', pathParams, methods: {
+  PATCH: { summary: 'Update a negotiated quote price adjustment', requestBody: { schema: cpqPriceAdjustmentPatchSchema }, responses: [{ status: 200, description: 'Adjustment and updated quote' }], errors },
+  DELETE: { summary: 'Remove a negotiated quote price adjustment', query: deletionSchema, responses: [{ status: 200, description: 'Updated quote' }], errors },
+} }

package/src/modules/cpq/api/quotes/[quoteId]/price-adjustments/preview/route.ts

@@ -0,0 +1,24 @@
+import { NextResponse } from 'next/server'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { resolveCpqRouteContext } from '../../../../context'
+import { cpqPriceAdjustmentPreviewSchema } from '../../../../../data/price-adjustments'
+import type { CpqAdjustmentService } from '../../../../../services/priceAdjustments/adjustmentService'
+import { handleArcError } from '../../../../_helpers/handleArcError'
+import { cpqErrorDoc, cpqQuoteIdPathParams } from '../../../../_helpers/quoteRouteOpenApi'
+
+export const metadata = { POST: { requireAuth: true, requireFeatures: ['cpq.quotes.manage', 'cpq.quotes.adjust_price'] } }
+export async function POST(req: Request, { params }: { params: Promise<{ quoteId: string }> }) {
+  try {
+    const ctx = await resolveCpqRouteContext(req)
+    if (!ctx.auth) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    const { quoteId } = cpqQuoteIdPathParams.parse(await params)
+    const body = cpqPriceAdjustmentPreviewSchema.parse(await req.json())
+    const service = ctx.container.resolve<CpqAdjustmentService>('cpqAdjustmentService')
+    return NextResponse.json(await service.preview(quoteId, body.draft, body.replaceAdjustmentId, { tenantId: ctx.tenantId, organizationId: ctx.organizationId }))
+  } catch (error) { return handleArcError(error, 'cpq/price-adjustments/preview.POST') }
+}
+export const openApi: OpenApiRouteDoc = { tag: 'CPQ Quotes', pathParams: cpqQuoteIdPathParams, methods: { POST: {
+  summary: 'Preview a draft adjustment without saving or emitting events', requestBody: { schema: cpqPriceAdjustmentPreviewSchema },
+  responses: [{ status: 200, description: 'Draft quote and adjustment errors; nothing persisted' }],
+  errors: [cpqErrorDoc(400, 'Invalid draft'), cpqErrorDoc(403, 'Missing permission or disabled feature'), cpqErrorDoc(404, 'Quote, line or replaced adjustment not found'), cpqErrorDoc(409, 'Adjustment locked or stale revision'), cpqErrorDoc(422, 'Ineligible target or invalid reason')],
+} } }

package/src/modules/cpq/api/quotes/[quoteId]/price-adjustments/route.ts

@@ -0,0 +1,40 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { resolveCpqRouteContext } from '../../../context'
+import { cpqPriceAdjustmentInputSchema } from '../../../../data/price-adjustments'
+import type { CpqAdjustmentService } from '../../../../services/priceAdjustments/adjustmentService'
+import { adjustmentCommandRoute } from '../../../_helpers/adjustmentCommandRoute'
+import { handleArcError } from '../../../_helpers/handleArcError'
+import { cpqErrorDoc, cpqQuoteIdPathParams } from '../../../_helpers/quoteRouteOpenApi'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['cpq.quotes.view'] },
+  POST: { requireAuth: true, requireFeatures: ['cpq.quotes.manage', 'cpq.quotes.adjust_price'] },
+}
+const listQuery = z.object({ page: z.coerce.number().int().min(1).default(1), pageSize: z.coerce.number().int().min(1).max(100).default(25) })
+type Params = { params: Promise<{ quoteId: string }> }
+export async function GET(req: Request, { params }: Params) {
+  try {
+    const ctx = await resolveCpqRouteContext(req)
+    if (!ctx.auth) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    const { quoteId } = cpqQuoteIdPathParams.parse(await params)
+    const { page, pageSize } = listQuery.parse(Object.fromEntries(new URL(req.url).searchParams))
+    const service = ctx.container.resolve<CpqAdjustmentService>('cpqAdjustmentService')
+    return NextResponse.json(await service.list(quoteId, { organizationId: ctx.organizationId, tenantId: ctx.tenantId }, page, pageSize))
+  } catch (error) { return handleArcError(error, 'cpq/price-adjustments.GET') }
+}
+export async function POST(req: Request, { params }: Params) {
+  try {
+    const ctx = await resolveCpqRouteContext(req)
+    if (!ctx.auth) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    const { quoteId } = cpqQuoteIdPathParams.parse(await params)
+    const body = cpqPriceAdjustmentInputSchema.parse(await req.json())
+    return await adjustmentCommandRoute(req, ctx, quoteId, body, cpqPriceAdjustmentInputSchema, 'create')
+  } catch (error) { return handleArcError(error, 'cpq/price-adjustments.POST') }
+}
+const errors = [cpqErrorDoc(400, 'Invalid input'), cpqErrorDoc(403, 'Missing permission or disabled feature'), cpqErrorDoc(404, 'Quote not found'), cpqErrorDoc(409, 'Adjustment locked or stale revision'), cpqErrorDoc(422, 'Invalid adjustment or guard rejection')]
+export const openApi: OpenApiRouteDoc = { tag: 'CPQ Quotes', pathParams: cpqQuoteIdPathParams, methods: {
+  GET: { summary: 'List quote price adjustments', query: listQuery, responses: [{ status: 200, description: 'Paged adjustments, pricing revision, feature state and the reason options (`reasons: [{ value, label }]`)' }], errors },
+  POST: { summary: 'Create a negotiated quote price adjustment', requestBody: { schema: cpqPriceAdjustmentInputSchema }, responses: [{ status: 201, description: 'Adjustment and updated quote' }], errors },
+} }

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

@@ -0,0 +1,95 @@
+/**
+ * Recalculate route contract.
+ *
+ * Route-level `requireFeatures` is enforced by the API dispatcher, so the
+ * permission contract is pinned through the exported `metadata`; the handler
+ * contract (body → guard → service call) is pinned with mocked collaborators.
+ */
+
+const recalculate = jest.fn()
+const runCpqMutationGuards = jest.fn()
+const runAfterSuccess = jest.fn()
+
+jest.mock('../../../../context', () => ({
+  resolveCpqRouteContext: jest.fn().mockResolvedValue({
+    auth: { sub: 'user-1', tenantId: 't-1' },
+    organizationId: 'org-1',
+    tenantId: 't-1',
+  }),
+}))
+
+jest.mock('../../../../resolveQuotingService', () => ({
+  resolveQuotingService: () => ({ recalculate }),
+}))
+
+jest.mock('../../../../_helpers/quoteMutationGuard', () => ({
+  CPQ_QUOTE_RESOURCE_KIND: 'cpq.quote',
+  runCpqMutationGuards: (...args: unknown[]) => runCpqMutationGuards(...args),
+}))
+
+import { metadata, openApi, POST } from '../route'
+
+function postRequest(body: unknown): Request {
+  return new Request('http://localhost/api/cpq/quotes/cpq-1/recalculate', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+}
+
+const params = { params: Promise.resolve({ quoteId: 'cpq-1' }) }
+
+describe('POST /api/cpq/quotes/{quoteId}/recalculate', () => {
+  beforeEach(() => {
+    recalculate.mockReset()
+    recalculate.mockResolvedValue({ id: 'cpq-1' })
+    runAfterSuccess.mockReset()
+    runCpqMutationGuards.mockReset()
+    runCpqMutationGuards.mockResolvedValue({ ok: true, runAfterSuccess })
+  })
+
+  it('requires an authenticated user with cpq.quotes.manage (view-only users get 403 from the dispatcher)', () => {
+    expect(metadata.POST).toEqual({ requireAuth: true, requireFeatures: ['cpq.quotes.manage'] })
+  })
+
+  it('documents the route in openApi', () => {
+    expect(openApi.methods?.POST?.errors).toEqual(expect.arrayContaining([expect.objectContaining({ status: 409 })]))
+    expect(openApi.methods?.POST?.requestBody).toBeDefined()
+  })
+
+  it('runs the mutation guards before a saved recalculation and their after-success hooks after it', async () => {
+    const res = await POST(postRequest({ save: true }), params)
+
+    expect(res.status).toBe(200)
+    expect(runCpqMutationGuards).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.any(Request),
+      expect.objectContaining({ resourceKind: 'cpq.quote', resourceId: 'cpq-1', operation: 'custom' }),
+    )
+    expect(recalculate).toHaveBeenCalledWith(
+      'cpq-1',
+      expect.objectContaining({ save: true }),
+      { organizationId: 'org-1', tenantId: 't-1' },
+    )
+    expect(runAfterSuccess).toHaveBeenCalledTimes(1)
+  })
+
+  it('skips the guards for a dry run (save=false)', async () => {
+    await POST(postRequest({ save: false }), params)
+
+    expect(runCpqMutationGuards).not.toHaveBeenCalled()
+    expect(recalculate).toHaveBeenCalled()
+  })
+
+  it('returns the guard response and does not recalculate when a guard blocks', async () => {
+    runCpqMutationGuards.mockResolvedValue({
+      ok: false,
+      response: Response.json({ error: 'Quote awaits approval' }, { status: 423 }),
+    })
+
+    const res = await POST(postRequest({ save: true }), params)
+
+    expect(res.status).toBe(423)
+    expect(recalculate).not.toHaveBeenCalled()
+  })
+})

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

@@ -4,9 +4,15 @@ import { resolveCpqRouteContext } from '../../../context'
 import { cpqRecalculateSchema } from '../../../../data/validators'
 import { isQuotingError } from '../../../../services/cpqQuotingService'
 import { resolveQuotingService } from '../../../resolveQuotingService'
+import { CPQ_QUOTE_RESOURCE_KIND, runCpqMutationGuards } from '../../../_helpers/quoteMutationGuard'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { cpqErrorDoc, cpqQuoteIdPathParams } from '../../../_helpers/quoteRouteOpenApi'
 
+// Recalculation re-resolves and (with `save: true`) persists prices, so it
+// needs the same feature as any other quote write. The quote page always
+// saves; viewers read stored prices through GET /api/cpq/quotes/{quoteId}.
 export const metadata = {
-  POST: { requireAuth: true, requireFeatures: ['cpq.quotes.view'] },
+  POST: { requireAuth: true, requireFeatures: ['cpq.quotes.manage'] },
 }
 
 export async function POST(req: Request, { params }: { params: Promise<{ quoteId: string }> }) {
@@ -18,8 +24,20 @@ export async function POST(req: Request, { params }: { params: Promise<{ quoteId
     const body = cpqRecalculateSchema.parse(await req.json())
     const scope = { organizationId: ctx.organizationId, tenantId: ctx.tenantId }
 
+    // Only a saved recalculation writes; a dry run needs no guard.
+    const guard = body.save
+      ? await runCpqMutationGuards(ctx, req, {
+          resourceKind: CPQ_QUOTE_RESOURCE_KIND,
+          resourceId: quoteId,
+          operation: 'custom',
+          mutationPayload: { action: 'recalculate' },
+        })
+      : null
+    if (guard && !guard.ok) return guard.response
+
     const service = resolveQuotingService(ctx)
     const result = await service.recalculate(quoteId, body, scope)
+    if (guard) await guard.runAfterSuccess()
     return NextResponse.json(result)
   } catch (err) {
     if (err instanceof z.ZodError) {
@@ -32,3 +50,24 @@ export async function POST(req: Request, { params }: { params: Promise<{ quoteId
     return NextResponse.json({ error: 'Internal error' }, { status: 500 })
   }
 }
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'CPQ Quotes',
+  summary: 'CPQ quote recalculation',
+  pathParams: cpqQuoteIdPathParams,
+  methods: {
+    POST: {
+      summary: 'Re-price every line of a CPQ quote',
+      description:
+        'Re-resolves charges and price rules. With `save: true` the result is persisted (refused on accepted, rejected and cancelled quotes) and mutation guards (resource kind `cpq.quote`, action `recalculate`) run first. Frozen Amend mirror lines keep their stored price.',
+      requestBody: { schema: cpqRecalculateSchema },
+      responses: [{ status: 200, description: 'Recalculated quote' }],
+      errors: [
+        cpqErrorDoc(400, 'Validation error'),
+        cpqErrorDoc(404, 'Quote not found'),
+        cpqErrorDoc(409, 'Saved recalculation on a terminal quote'),
+        cpqErrorDoc(422, 'Blocked by a mutation guard'),
+      ],
+    },
+  },
+}

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/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