@dainamite/cpq 0.5.0 → 0.6.0

package/src/modules/cpq/__integration__/TC-CPQ-ARC-012.spec.ts

@@ -0,0 +1,134 @@
+import { test, expect, type Page } from '@playwright/test'
+import { login } from '@open-mercato/core/helpers/integration/auth'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+import {
+  seedActiveSubscription,
+  seedCustomer,
+  deleteSubscription,
+  deleteCustomer,
+  hideFloatingOverlays,
+  uniq,
+} from './_helpers/cpqArcFixtures'
+
+/**
+ * TC-CPQ-ARC-012 — Amend: removing an existing item cancels it on the subscription
+ * (manual: xd-250-arc-flow.md → "Removing an existing item on Amend / Renew quotes")
+ *
+ * Deleting a line that mirrors a live subscription item must not drop the
+ * line — activation only applies explicit line actions, so the item would
+ * silently stay active. Instead a confirmation dialog explains the effect,
+ * the line becomes a greyed-out `remove` line, the ARC summary keeps it in
+ * Current MRC but not in New MRC, and Restore brings it back. After
+ * convert + activate, the removed item is terminated and the kept one stays.
+ */
+
+type QuoteLine = { lineId: string; offeringName: string; action: string }
+type SubscriptionItem = { id: string; name: string; status: string }
+
+function lineRow(page: Page, name: string) {
+  return page.getByTestId('cpq-quote-line').filter({ hasText: name })
+}
+
+test.describe('TC-CPQ-ARC-012 — Amend: remove an existing item', () => {
+  test('confirm → remove line → MRC delta → restore → remove → activate terminates the item', async ({ page, request }) => {
+    const token = await getAuthToken(request, 'admin')
+    const customerId = await seedCustomer(request, token)
+    const keptName = `Kept Port ${uniq()}`
+    const removedName = `Removed Storage ${uniq()}`
+    const sub = await seedActiveSubscription(request, token, {
+      customerId,
+      name: 'Remove-item target',
+      items: [
+        { name: keptName, mrcAmount: 250 },
+        { name: removedName, mrcAmount: 100 },
+      ],
+    })
+
+    try {
+      await login(page, 'admin')
+
+      // 1. Amend from the subscription.
+      await page.goto(`/backend/cpq/inventory/subscriptions/${sub.id}`, { waitUntil: 'domcontentloaded' })
+      await hideFloatingOverlays(page)
+      await page.getByRole('button', { name: /^Amend$/ }).click()
+      await page.waitForURL(/\/backend\/cpq\/quotes\/[0-9a-f-]+$/, { timeout: 15_000 })
+      const quoteId = page.url().split('/').pop()!
+      await hideFloatingOverlays(page)
+
+      const removedRow = lineRow(page, removedName)
+      await expect(removedRow).toBeVisible()
+      await expect(removedRow).not.toHaveAttribute('data-removed', 'true')
+
+      // 2. Trash → confirmation dialog explains the item is cancelled. Cancel keeps the line.
+      await removedRow.getByTitle('Remove').click()
+      const dialog = page.getByRole('alertdialog')
+      await expect(dialog).toContainText(`Remove ${removedName} from the subscription?`)
+      await expect(dialog).toContainText('cancelled on the subscription')
+      await dialog.getByRole('button', { name: /^Cancel$/ }).click()
+      await expect(dialog).toBeHidden()
+      await expect(removedRow).not.toHaveAttribute('data-removed', 'true')
+
+      // 3. Confirm → the line stays as a `remove` line with a Restore action.
+      await removedRow.getByTitle('Remove').click()
+      await page.getByRole('alertdialog').getByRole('button', { name: 'Remove item' }).click()
+      await expect(removedRow).toHaveAttribute('data-removed', 'true')
+      await expect(removedRow.getByText(/^remove$/)).toBeVisible()
+      await expect(removedRow.getByTestId('cpq-line-restore')).toBeVisible()
+
+      // 4. Summary: removed item stays in Current MRC, drops out of New MRC.
+      await expect(page.getByTestId('cpq-arc-current-mrc')).toContainText('$350.00')
+      await expect(page.getByTestId('cpq-arc-new-mrc')).toContainText('$250.00')
+      await expect(page.getByTestId('cpq-arc-mrc-change')).toContainText('-$100.00')
+
+      // 5. Restore → back to a normal line; totals back to unchanged.
+      await removedRow.getByTestId('cpq-line-restore').click()
+      await expect(removedRow).not.toHaveAttribute('data-removed', 'true')
+      await expect(page.getByTestId('cpq-arc-new-mrc')).toContainText('$350.00')
+
+      // 6. Remove again for the activation leg.
+      await removedRow.getByTitle('Remove').click()
+      await page.getByRole('alertdialog').getByRole('button', { name: 'Remove item' }).click()
+      await expect(removedRow).toHaveAttribute('data-removed', 'true')
+
+      // The API agrees: one cancel line, one modify line.
+      const quoteRes = await apiRequest(request, 'GET', `/api/cpq/quotes/${quoteId}`, { token })
+      expect(quoteRes.ok()).toBeTruthy()
+      const quote = (await quoteRes.json()) as { cpqStatus: string; lines: QuoteLine[] }
+      expect(quote.lines.find((l) => l.offeringName === removedName)?.action).toBe('cancel')
+      expect(quote.lines.find((l) => l.offeringName === keptName)?.action).toBe('modify')
+
+      // 7. API — approval ladder (from wherever recalculation left the quote), convert, activate.
+      const ladder = ['ready', 'in_approval', 'approved', 'with_customer', 'accepted']
+      for (const targetStatus of ladder.slice(ladder.indexOf(quote.cpqStatus) + 1)) {
+        const res = await apiRequest(request, 'POST', `/api/cpq/quotes/${quoteId}/status`, { token, data: { targetStatus } })
+        expect(res.ok(), `transition to ${targetStatus} returned ${res.status()}: ${await res.text()}`).toBeTruthy()
+      }
+      const convertRes = await apiRequest(request, 'POST', '/api/cpq/orders', { token, data: { quoteId } })
+      expect(convertRes.ok(), `convert returned ${convertRes.status()}: ${await convertRes.text()}`).toBeTruthy()
+      const order = (await convertRes.json()) as { id: string }
+
+      // The order page mirrors the quote: same ARC summary, removed line marked "remove".
+      await page.goto(`/backend/cpq/orders/${order.id}`, { waitUntil: 'domcontentloaded' })
+      await hideFloatingOverlays(page)
+      await expect(page.getByTestId('cpq-pricing-summary')).toBeVisible()
+      await expect(page.getByTestId('cpq-arc-current-mrc')).toContainText('$350.00')
+      await expect(page.getByTestId('cpq-arc-new-mrc')).toContainText('$250.00')
+      const removedOrderLine = page.getByTestId('cpq-order-line').filter({ hasText: removedName })
+      await expect(removedOrderLine).toHaveAttribute('data-removed', 'true')
+      await expect(removedOrderLine.getByText(/^remove$/)).toBeVisible()
+      const activateRes = await apiRequest(request, 'POST', `/api/cpq/orders/${order.id}/activate`, { token })
+      expect(activateRes.ok(), `activate returned ${activateRes.status()}: ${await activateRes.text()}`).toBeTruthy()
+
+      // 8. The removed item is terminated; the other one is untouched.
+      const itemsRes = await apiRequest(request, 'GET', `/api/cpq/inventory/subscription-items?subscriptionId=${sub.id}`, { token })
+      expect(itemsRes.ok()).toBeTruthy()
+      const body = (await itemsRes.json()) as SubscriptionItem[] | { items: SubscriptionItem[] }
+      const items = Array.isArray(body) ? body : body.items
+      expect(items.find((i) => i.name === removedName)?.status).toBe('terminated')
+      expect(items.find((i) => i.name === keptName)?.status).toBe('active')
+    } finally {
+      await deleteSubscription(request, token, sub.id).catch(() => undefined)
+      await deleteCustomer(request, token, customerId).catch(() => undefined)
+    }
+  })
+})

package/src/modules/cpq/acl.ts

@@ -1,4 +1,5 @@
 export const features = [
+  { id: 'cpq.quotes.adjust_price', title: 'Adjust CPQ quote prices', module: 'cpq' },
   { id: 'cpq.quotes.view', title: 'View CPQ Quotes', module: 'cpq' },
   { id: 'cpq.quotes.manage', title: 'Manage CPQ Quotes', module: 'cpq' },
   { id: 'cpq.pricing.view', title: 'View Pricing', module: 'cpq' },

package/src/modules/cpq/api/__tests__/adjustmentRoutes.test.ts

@@ -0,0 +1,79 @@
+const execute = jest.fn(), list = jest.fn(), preview = jest.fn(), guards = jest.fn(), after = jest.fn()
+const ctx = { auth: { sub: 'user', tenantId: 'tenant' }, tenantId: 'tenant', organizationId: 'org', organizationScope: null,
+  container: { resolve: (name: string) => name === 'commandBus' ? { execute } : { list, preview } } }
+jest.mock('../context', () => ({ resolveCpqRouteContext: jest.fn(async () => ctx) }))
+jest.mock('../_helpers/quoteMutationGuard', () => ({ runCpqMutationGuards: (...args: unknown[]) => guards(...args) }))
+import { GET, POST, metadata } from '../quotes/[quoteId]/price-adjustments/route'
+import { POST as PREVIEW } from '../quotes/[quoteId]/price-adjustments/preview/route'
+import { PATCH, DELETE } from '../quotes/[quoteId]/price-adjustments/[adjustmentId]/route'
+import { QuotingError } from '../../services/cpqQuotingService'
+const quoteId = '11111111-1111-4111-8111-111111111111', adjustmentId = '22222222-2222-4222-8222-222222222222'
+const params = { params: Promise.resolve({ quoteId, adjustmentId }) }
+const input = { level: 'charge', quoteLineId: quoteId, chargeCode: 'fee', adjustmentType: 'price_override', value: 80, currencyCode: 'USD', reasonCode: 'competitive_match' }
+function request(method: string, body?: unknown, query = '') { return new Request(`http://localhost/api/cpq/quotes/${quoteId}/price-adjustments${query}`, { method, headers: { 'Content-Type': 'application/json' }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) }) }
+beforeEach(() => {
+  jest.clearAllMocks()
+  guards.mockResolvedValue({ ok: true, runAfterSuccess: after })
+  execute.mockResolvedValue({ result: { adjustment: { id: adjustmentId }, quote: { id: quoteId } }, logEntry: null })
+  preview.mockResolvedValue({ quote: { id: quoteId }, errors: [] })
+  list.mockResolvedValue({ items: [], total: 0, page: 1, pageSize: 25, pricingRevision: 1 })
+})
+it('requires view on GET and both immutable manage/adjust features on POST', () => {
+  expect(metadata.GET.requireFeatures).toEqual(['cpq.quotes.view'])
+  expect(metadata.POST.requireFeatures).toEqual(['cpq.quotes.manage', 'cpq.quotes.adjust_price'])
+})
+it('creates through the command bus with server scope and guard hooks', async () => {
+  const response = await POST(request('POST', input), params)
+  expect(response.status).toBe(201)
+  expect(execute).toHaveBeenCalledWith('cpq.quote_price_adjustment.create', expect.objectContaining({ input: { quoteId, adjustment: input }, ctx: expect.objectContaining({ selectedOrganizationId: 'org', auth: ctx.auth }) }))
+  expect(guards).toHaveBeenCalledWith(ctx, expect.any(Request), expect.objectContaining({ resourceKind: 'cpq.quote_price_adjustment', operation: 'create', mutationPayload: { quoteId, ...input } }))
+  expect(after).toHaveBeenCalledTimes(1)
+  expect(execute.mock.invocationCallOrder[0]).toBeLessThan(after.mock.invocationCallOrder[0])
+})
+it('applies guard modifications but never replaces quote path identity', async () => {
+  guards.mockResolvedValue({ ok: true, modifiedPayload: { quoteId: adjustmentId, value: 70 }, runAfterSuccess: after })
+  await POST(request('POST', input), params)
+  expect(execute.mock.calls[0][1].input).toEqual({ quoteId, adjustment: { ...input, value: 70 } })
+})
+it('refuses invalid guard modifications and guard rejections before the command', async () => {
+  guards.mockResolvedValue({ ok: true, modifiedPayload: { value: -1 }, runAfterSuccess: after })
+  expect((await POST(request('POST', input), params)).status).toBe(400)
+  guards.mockResolvedValue({ ok: false, response: Response.json({ error: 'Approval required' }, { status: 423 }) })
+  expect((await POST(request('POST', input), params)).status).toBe(423)
+  expect(execute).not.toHaveBeenCalled()
+  expect(after).not.toHaveBeenCalled()
+})
+it.each([403, 404, 409, 422])('preserves command error %s without after-success', async (status) => {
+  execute.mockRejectedValue(new QuotingError(status, 'Rejected'))
+  const response = await POST(request('POST', input), params)
+  expect(response.status).toBe(status)
+  expect(await response.json()).toEqual({ error: 'Rejected' })
+  expect(after).not.toHaveBeenCalled()
+})
+it('updates immutable targets through PATCH and deletes with a revision token', async () => {
+  expect((await PATCH(request('PATCH', { value: 70 }), params)).status).toBe(200)
+  expect(execute.mock.calls[0][1].input).toEqual({ quoteId, adjustmentId, patch: { value: 70 } })
+  expect((await DELETE(request('DELETE', undefined, '?expectedRevision=3'), params)).status).toBe(200)
+  expect(execute.mock.calls[1][1].input).toEqual({ quoteId, adjustmentId, expectedRevision: 3 })
+  expect((await PATCH(request('PATCH', { quoteLineId: adjustmentId }), params)).status).toBe(400)
+})
+it('lists with bounded pagination and rejects malformed bodies and identifiers', async () => {
+  expect((await GET(request('GET', undefined, '?page=2&pageSize=10'), params)).status).toBe(200)
+  expect(list).toHaveBeenCalledWith(quoteId, { tenantId: 'tenant', organizationId: 'org' }, 2, 10)
+  expect((await GET(request('GET', undefined, '?pageSize=101'), params)).status).toBe(400)
+  expect((await POST(request('POST', {}), params)).status).toBe(400)
+  expect((await POST(request('POST', input), { params: Promise.resolve({ quoteId: 'bad' }) })).status).toBe(400)
+})
+it('returns the framework undo operation metadata for a logged command', async () => {
+  execute.mockResolvedValue({ result: { adjustment: { id: adjustmentId }, quote: { id: quoteId } },
+    logEntry: { id: 'log', commandId: 'cpq.quote_price_adjustment.create', undoToken: 'undo', createdAt: new Date() } })
+  expect((await POST(request('POST', input), params)).headers.get('x-om-operation')).toBeTruthy()
+})
+it('previews through the read-only service without commands or mutation hooks', async () => {
+  const response = await PREVIEW(request('POST', { draft: input }), params)
+  expect(response.status).toBe(200)
+  expect(preview).toHaveBeenCalledWith(quoteId, input, undefined, { tenantId: 'tenant', organizationId: 'org' })
+  expect(execute).not.toHaveBeenCalled()
+  expect(guards).not.toHaveBeenCalled()
+  expect((await PREVIEW(request('POST', { draft: {} }), params)).status).toBe(400)
+})

package/src/modules/cpq/api/__tests__/quoteWriteGuards.test.ts

@@ -0,0 +1,100 @@
+import { OrderError } from '../../services/cpqOrderService'
+const addQuoteItem = jest.fn()
+const updateQuoteItem = jest.fn()
+const removeQuoteItem = jest.fn()
+const convertQuoteToOrder = jest.fn()
+const runCpqMutationGuards = jest.fn()
+const runAfterSuccess = jest.fn()
+
+jest.mock('../context', () => ({
+  resolveCpqRouteContext: jest.fn().mockImplementation(async () => ({
+    auth: { sub: 'user-1' }, organizationId: 'org-1', tenantId: 'tenant-1',
+    container: { resolve: () => ({ convertQuoteToOrder }) },
+  })),
+}))
+jest.mock('../resolveQuotingService', () => ({
+  resolveQuotingService: () => ({ addQuoteItem, updateQuoteItem, removeQuoteItem }),
+}))
+jest.mock('../_helpers/quoteMutationGuard', () => ({
+  CPQ_QUOTE_RESOURCE_KIND: 'cpq.quote',
+  CPQ_QUOTE_LINE_RESOURCE_KIND: 'cpq.quote_line',
+  runCpqMutationGuards: (...args: unknown[]) => runCpqMutationGuards(...args),
+}))
+
+import { POST as add } from '../quotes/[quoteId]/items/route'
+import { PUT as update, DELETE as remove } from '../quotes/[quoteId]/items/[lineId]/route'
+import { POST as convert } from '../orders/route'
+
+const quoteId = '11111111-1111-4111-8111-111111111111'
+const lineId = '22222222-2222-4222-8222-222222222222'
+const scope = { organizationId: 'org-1', tenantId: 'tenant-1' }
+const params = { params: Promise.resolve({ quoteId, lineId }) }
+function request(method: string, body?: unknown) {
+  return new Request('http://localhost/api/cpq/quotes', {
+    method, headers: { 'Content-Type': 'application/json' },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  })
+}
+const cases = [
+  { name: 'add', invoke: () => add(request('POST', { configuration: {}, quantity: 1 }), params), service: addQuoteItem, operation: 'create', resourceKind: 'cpq.quote_line', status: 201 },
+  { name: 'update', invoke: () => update(request('PUT', { configuration: {}, quantity: 1 }), params), service: updateQuoteItem, operation: 'update', resourceKind: 'cpq.quote_line', status: 200 },
+  { name: 'remove', invoke: () => remove(request('DELETE'), params), service: removeQuoteItem, operation: 'delete', resourceKind: 'cpq.quote_line', status: 200 },
+  { name: 'convert', invoke: () => convert(request('POST', { quoteId })), service: convertQuoteToOrder, operation: 'custom', resourceKind: 'cpq.quote', status: 201 },
+]
+
+beforeEach(() => {
+  jest.clearAllMocks()
+  for (const entry of cases) entry.service.mockResolvedValue({ id: quoteId })
+  runCpqMutationGuards.mockResolvedValue({ ok: true, runAfterSuccess })
+})
+
+describe.each(cases)('$name quote write guards', ({ invoke, service, operation, resourceKind, status }) => {
+  it('consults the guard before writing and invokes after-success after writing', async () => {
+    expect((await invoke()).status).toBe(status)
+    expect(runCpqMutationGuards).toHaveBeenCalledWith(expect.anything(), expect.any(Request),
+      expect.objectContaining({ operation, resourceKind }))
+    expect(service).toHaveBeenCalledTimes(1)
+    expect(runAfterSuccess).toHaveBeenCalledTimes(1)
+    expect(runCpqMutationGuards.mock.invocationCallOrder[0]).toBeLessThan(service.mock.invocationCallOrder[0])
+    expect(service.mock.invocationCallOrder[0]).toBeLessThan(runAfterSuccess.mock.invocationCallOrder[0])
+  })
+  it('returns a guard rejection without writing or calling after-success', async () => {
+    runCpqMutationGuards.mockResolvedValue({ ok: false, response: Response.json({ error: 'Approval required' }, { status: 423 }) })
+    const response = await invoke()
+    expect(response.status).toBe(423)
+    expect(await response.json()).toEqual({ error: 'Approval required' })
+    expect(service).not.toHaveBeenCalled()
+    expect(runAfterSuccess).not.toHaveBeenCalled()
+  })
+  it('does not call after-success if the write fails', async () => {
+    const log = jest.spyOn(console, 'error').mockImplementation(() => {})
+    try {
+      service.mockRejectedValueOnce(new Error('Write failed'))
+      expect((await invoke()).status).toBe(500)
+      expect(runAfterSuccess).not.toHaveBeenCalled()
+    } finally { log.mockRestore() }
+  })
+})
+
+it.each(cases.slice(0, 2))('$name validates and applies guard-modified fields', async ({ invoke, service, name }) => {
+  runCpqMutationGuards.mockResolvedValue({ ok: true, modifiedPayload: { quantity: 3 }, runAfterSuccess })
+  await invoke()
+  const args = name === 'add'
+    ? [quoteId, expect.objectContaining({ quantity: 3 }), scope]
+    : [quoteId, lineId, expect.objectContaining({ quantity: 3 }), scope]
+  expect(service).toHaveBeenCalledWith(...args)
+})
+it.each(cases.slice(0, 2))('$name refuses invalid guard-modified fields before writing', async ({ invoke, service }) => {
+  runCpqMutationGuards.mockResolvedValue({ ok: true, modifiedPayload: { quantity: 0 }, runAfterSuccess })
+  expect((await invoke()).status).toBe(400)
+  expect(service).not.toHaveBeenCalled()
+  expect(runAfterSuccess).not.toHaveBeenCalled()
+})
+
+it('returns the invalid adjustment line/code from conversion without running after-success', async () => {
+  convertQuoteToOrder.mockRejectedValueOnce(new OrderError(422, 'ADJUSTMENT_INVALID', { lineId, code: 'ABOVE_STANDARD' }))
+  const response = await convert(request('POST', { quoteId }))
+  expect(response.status).toBe(422)
+  expect(await response.json()).toEqual({ error: 'ADJUSTMENT_INVALID', lineId, code: 'ABOVE_STANDARD' })
+  expect(runAfterSuccess).not.toHaveBeenCalled()
+})

package/src/modules/cpq/api/_helpers/__tests__/quoteMutationGuard.test.ts

@@ -0,0 +1,48 @@
+const runRouteMutationGuards = jest.fn()
+
+jest.mock('@open-mercato/shared/lib/crud/route-mutation-guard', () => ({
+  runRouteMutationGuards: (...args: unknown[]) => runRouteMutationGuards(...args),
+}))
+
+import { CPQ_QUOTE_RESOURCE_KIND, runCpqMutationGuards } from '../quoteMutationGuard'
+
+describe('runCpqMutationGuards', () => {
+  beforeEach(() => {
+    runRouteMutationGuards.mockReset()
+    runRouteMutationGuards.mockResolvedValue({ ok: true, runAfterSuccess: jest.fn() })
+  })
+
+  it('forwards the route actor, tenant scope and input to the framework guard runner', async () => {
+    const container = { resolve: jest.fn() }
+    const req = new Request('http://localhost/api/cpq/quotes/q-1/status', { method: 'POST' })
+    const input = {
+      resourceKind: CPQ_QUOTE_RESOURCE_KIND,
+      resourceId: 'q-1',
+      operation: 'custom' as const,
+      mutationPayload: { action: 'transition_status', targetStatus: 'with_customer' },
+    }
+
+    await runCpqMutationGuards(
+      { container: container as never, auth: { sub: 'user-1' } as never, tenantId: 't-1', organizationId: 'org-1' },
+      req,
+      input,
+    )
+
+    expect(runRouteMutationGuards).toHaveBeenCalledWith({
+      container,
+      req,
+      auth: { userId: 'user-1', tenantId: 't-1', organizationId: 'org-1' },
+      input,
+    })
+  })
+
+  it('passes a null organization when the route has none selected', async () => {
+    await runCpqMutationGuards(
+      { container: {} as never, auth: { sub: 'user-1' } as never, tenantId: 't-1', organizationId: '' },
+      new Request('http://localhost/x', { method: 'POST' }),
+      { resourceKind: CPQ_QUOTE_RESOURCE_KIND },
+    )
+
+    expect(runRouteMutationGuards.mock.calls[0][0].auth.organizationId).toBeNull()
+  })
+})

package/src/modules/cpq/api/_helpers/adjustmentCommandRoute.ts

@@ -0,0 +1,45 @@
+import { NextResponse } from 'next/server'
+import type { z } from 'zod'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/operationMetadata'
+import type { CpqRouteContext } from '../context'
+import { runCpqMutationGuards } from './quoteMutationGuard'
+import type { AdjustmentWriteResult } from '../../services/priceAdjustments/adjustmentService'
+
+export async function adjustmentCommandRoute<T extends object>(
+  req: Request, ctx: CpqRouteContext, quoteId: string, body: T,
+  schema: z.ZodType<T>, operation: 'create' | 'update' | 'delete', adjustmentId?: string,
+): Promise<NextResponse | Response> {
+  const guard = await runCpqMutationGuards(ctx, req, {
+    resourceKind: 'cpq.quote_price_adjustment', resourceId: adjustmentId,
+    operation, mutationPayload: { quoteId, ...body },
+  })
+  if (!guard.ok) return guard.response
+  // Path identifiers belong to the server, even when a project guard returns
+  // the full payload including the original quoteId metadata.
+  const modified = Object.fromEntries(Object.entries(guard.modifiedPayload ?? {})
+    .filter(([key]) => key !== 'quoteId' && key !== 'adjustmentId'))
+  const effective = schema.parse({ ...body, ...modified })
+  const input = operation === 'create' ? { quoteId, adjustment: effective }
+    : operation === 'update' ? { quoteId, adjustmentId, patch: effective }
+      : { quoteId, adjustmentId, ...effective }
+  const commandCtx: CommandRuntimeContext = {
+    container: ctx.container, auth: ctx.auth, organizationScope: ctx.organizationScope,
+    selectedOrganizationId: ctx.organizationId, organizationIds: [ctx.organizationId], request: req,
+  }
+  const bus = ctx.container.resolve<CommandBus>('commandBus')
+  const commandId = `cpq.quote_price_adjustment.${operation}`
+  const { result, logEntry } = await bus.execute<typeof input, AdjustmentWriteResult>(commandId, { input, ctx: commandCtx })
+  if (!result) throw new Error('Adjustment command did not return a result')
+  await guard.runAfterSuccess()
+  const response = NextResponse.json(operation === 'delete' ? { quote: result.quote }
+    : { adjustment: result.adjustment, quote: result.quote }, { status: operation === 'create' ? 201 : 200 })
+  if (logEntry?.undoToken && logEntry.id && logEntry.commandId) {
+    response.headers.set('x-om-operation', serializeOperationMetadata({ id: logEntry.id, undoToken: logEntry.undoToken,
+      commandId: logEntry.commandId, actionLabel: logEntry.actionLabel ?? null,
+      resourceKind: 'cpq.quote_price_adjustment', resourceId: result.adjustment.id,
+      executedAt: logEntry.createdAt instanceof Date ? logEntry.createdAt.toISOString()
+        : typeof logEntry.createdAt === 'string' ? logEntry.createdAt : new Date().toISOString() }))
+  }
+  return response
+}

package/src/modules/cpq/api/_helpers/quoteMutationGuard.ts

@@ -0,0 +1,38 @@
+import {
+  runRouteMutationGuards,
+  type RouteMutationGuardInput,
+  type RouteMutationGuardResult,
+} from '@open-mercato/shared/lib/crud/route-mutation-guard'
+import type { CpqRouteContext } from '../context'
+
+/** Mutation-guard resource kinds for CPQ quote writes (`module.entity`). */
+export const CPQ_QUOTE_RESOURCE_KIND = 'cpq.quote'
+export const CPQ_QUOTE_LINE_RESOURCE_KIND = 'cpq.quote_line'
+
+/**
+ * Run every registered mutation guard for a CPQ custom write route.
+ *
+ * Quote routes are hand-written (not `makeCrudRoute`), so they wire guards
+ * explicitly through the framework's registry-based wrapper. Projects use
+ * this hook to enforce rules CPQ does not own — e.g. blocking
+ * `ready → with_customer` or order conversion until an approval workflow
+ * signs a discounted quote off. With no guard registered the call passes.
+ *
+ * Call `runAfterSuccess()` on the passed result only after the write commits.
+ */
+export function runCpqMutationGuards(
+  ctx: Pick<CpqRouteContext, 'container' | 'auth' | 'tenantId' | 'organizationId'>,
+  req: Request,
+  input: RouteMutationGuardInput,
+): Promise<RouteMutationGuardResult> {
+  return runRouteMutationGuards({
+    container: ctx.container,
+    req,
+    auth: {
+      userId: ctx.auth?.sub ?? '',
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId || null,
+    },
+    input,
+  })
+}

package/src/modules/cpq/api/_helpers/quoteRouteOpenApi.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod'
+import type { OpenApiResponseDoc } from '@open-mercato/shared/lib/openapi'
+
+/** Error body every CPQ quote route returns (`{ error, ... }`). */
+export const cpqErrorResponseSchema = z.object({ error: z.string() }).passthrough()
+
+export function cpqErrorDoc(status: number, description: string): OpenApiResponseDoc {
+  return { status, description, schema: cpqErrorResponseSchema }
+}
+
+export const cpqQuoteIdPathParams = z.object({ quoteId: z.string().uuid() })
+
+/** Shared error docs for quote writes guarded by mutation guards. */
+export const CPQ_GUARDED_WRITE_ERRORS: OpenApiResponseDoc[] = [
+  cpqErrorDoc(400, 'Validation error'),
+  cpqErrorDoc(404, 'Quote or line not found'),
+  cpqErrorDoc(409, 'Quote is in a terminal status'),
+  cpqErrorDoc(422, 'Blocked by a mutation guard'),
+]

package/src/modules/cpq/api/orders/[orderId]/route.ts

@@ -1,4 +1,7 @@
 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 { isOrderError } from '../../../services/cpqOrderService'
 import type { DefaultCpqOrderService } from '../../../services/cpqOrderService'
@@ -26,3 +29,18 @@ export async function GET(req: Request, { params }: { params: Promise<{ orderId:
     return NextResponse.json({ error: 'Internal error' }, { status: 500 })
   }
 }
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'CPQ Orders',
+  summary: 'CPQ order',
+  pathParams: z.object({ orderId: z.string().uuid() }),
+  methods: {
+    GET: {
+      summary: 'Get a CPQ order with its lines and pricing summary',
+      description:
+        '`pricingSummary` carries NRC / MRC totals plus the source quote\'s waterfall figures (`listNrcTotal`, `listMrcTotal`, `standard*Total`, `ruleDiscountTotal`, `manualDiscountTotal`, `dealValue`, `discountDepth`), computed from the line charges copied at conversion. ARC lines carry `arcSource` (the subscription item before the change).',
+      responses: [{ status: 200, description: 'The order' }],
+      errors: [cpqErrorDoc(401, 'Unauthorized'), cpqErrorDoc(404, 'Order not found')],
+    },
+  },
+}

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

@@ -4,6 +4,9 @@ import { resolveCpqRouteContext } from '../context'
 import { cpqConvertQuoteToOrderSchema } from '../../data/validators'
 import { isOrderError } from '../../services/cpqOrderService'
 import type { DefaultCpqOrderService } from '../../services/cpqOrderService'
+import { CPQ_QUOTE_RESOURCE_KIND, runCpqMutationGuards } from '../_helpers/quoteMutationGuard'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { cpqErrorDoc } from '../_helpers/quoteRouteOpenApi'
 
 export const metadata = {
   POST: { requireAuth: true, requireFeatures: ['cpq.orders.manage'] },
@@ -18,8 +21,19 @@ export async function POST(req: Request) {
     const body = cpqConvertQuoteToOrderSchema.parse(await req.json())
     const scope = { organizationId: ctx.organizationId, tenantId: ctx.tenantId }
 
+    // Conversion turns a quote into an order — projects can block it (e.g.
+    // until an approval workflow has signed a discounted quote off).
+    const guard = await runCpqMutationGuards(ctx, req, {
+      resourceKind: CPQ_QUOTE_RESOURCE_KIND,
+      resourceId: body.quoteId,
+      operation: 'custom',
+      mutationPayload: { action: 'convert_to_order' },
+    })
+    if (!guard.ok) return guard.response
+
     const service = ctx.container.resolve('cpqOrderService') as DefaultCpqOrderService
     const result = await service.convertQuoteToOrder(body.quoteId, scope)
+    await guard.runAfterSuccess()
     return NextResponse.json(result, { status: 201 })
   } catch (err) {
     return handleError(err, 'cpq/orders.POST')
@@ -66,7 +80,7 @@ function handleError(err: unknown, context: string) {
     return NextResponse.json({ error: 'Validation error', details: err.issues }, { status: 400 })
   }
   if (isOrderError(err)) {
-    return NextResponse.json({ error: err.message }, { status: err.status })
+    return NextResponse.json({ error: err.message, ...err.details }, { status: err.status })
   }
   const errObj = err as Record<string, unknown>
   if (typeof errObj?.status === 'number' && typeof errObj?.error === 'string') {
@@ -75,3 +89,39 @@ function handleError(err: unknown, context: string) {
   console.error(`[${context}]`, err)
   return NextResponse.json({ error: 'Internal error' }, { status: 500 })
 }
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'CPQ Orders',
+  summary: 'CPQ orders',
+  methods: {
+    POST: {
+      summary: 'Convert a CPQ quote into an order',
+      description:
+        'Creates the sales order and CPQ order configuration from the quote. Refused for cancelled or rejected quotes; mutation guards (resource kind `cpq.quote`, action `convert_to_order`) run first.',
+      requestBody: { schema: cpqConvertQuoteToOrderSchema },
+      responses: [{ status: 201, description: 'Created order' }],
+      errors: [
+        cpqErrorDoc(400, 'Validation error'),
+        cpqErrorDoc(404, 'Quote not found'),
+        cpqErrorDoc(409, 'Quote cannot be converted in its status or is already converted'),
+        cpqErrorDoc(422, 'Quote has no lines or has invalid stored adjustments, or blocked by a mutation guard'),
+      ],
+    },
+    GET: {
+      summary: 'List CPQ orders',
+      query: z.object({
+        customerId: z.string().uuid().optional(),
+        sourceQuoteId: z.string().uuid().optional(),
+        salesOrderId: z.string().uuid().optional(),
+        cpqStatus: z.string().optional(),
+        currencyCode: z.string().optional(),
+        search: z.string().optional(),
+        sortField: z.enum(['createdAt', 'updatedAt', 'cpqStatus', 'activatedAt', 'currencyCode']).optional(),
+        sortDir: z.enum(['asc', 'desc']).optional(),
+        page: z.coerce.number().int().min(1).optional(),
+        pageSize: z.coerce.number().int().min(1).max(100).optional(),
+      }),
+      responses: [{ status: 200, description: 'Paged list of CPQ orders' }],
+    },
+  },
+}

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

@@ -0,0 +1,56 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { resolveCpqRouteContext } from '../../../../../context'
+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 = {
+  POST: { requireAuth: true, requireFeatures: ['cpq.quotes.manage'] },
+}
+
+export async function POST(req: Request, { params }: { params: Promise<{ quoteId: string; lineId: string }> }) {
+  try {
+    const ctx = await resolveCpqRouteContext(req)
+    if (!ctx.auth) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+
+    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: 'update',
+      mutationPayload: { quoteId, restore: true },
+    })
+    if (!guard.ok) return guard.response
+
+    const service = resolveQuotingService(ctx)
+    const result = await service.restoreQuoteItem(quoteId, lineId, scope)
+    await guard.runAfterSuccess()
+    return NextResponse.json(result)
+  } catch (err) {
+    if (isQuotingError(err)) {
+      return NextResponse.json({ error: err.message }, { status: err.status })
+    }
+    console.error('[cpq/quotes/[quoteId]/items/[lineId]/restore.POST]', err)
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'CPQ Quotes',
+  summary: 'Restore a subscription item marked for removal',
+  pathParams: z.object({ quoteId: z.string().uuid(), lineId: z.string().uuid() }),
+  methods: {
+    POST: {
+      summary: 'Restore a removed subscription item on an Amend / Renew quote',
+      description:
+        'Turns a `cancel` line that mirrors a live subscription item back into a `modify` line, rebuilt from the item (configuration, quantity, stored price). Its cancelled mirrored components are restored with it. 409 when the line is not a removed item, its parent is still removed, or the item is no longer active. Mutation guards run first (resource kind `cpq.quote_line`, update).',
+      responses: [{ status: 200, description: 'Quote after the restore' }],
+      errors: CPQ_GUARDED_WRITE_ERRORS.filter((doc) => doc.status !== 400),
+    },
+  },
+}