@dainamite/cpq 0.5.0 → 0.7.0

package/src/modules/cpq/__tests__/i18n/sourceScan.ts

@@ -0,0 +1,109 @@
+import { readdirSync, readFileSync, statSync } from 'fs'
+import { join, relative } from 'path'
+import ts from 'typescript'
+
+/**
+ * Static source scans backing the CPQ i18n guardrails
+ * (spec .ai/specs/2026-11-15-cpq-multi-language.md):
+ *
+ *   - `collectTranslationKeys` — every literal `t('cpq.…')` key and every
+ *     template-literal key prefix (`t(\`cpq.x.${v}\`)`) used in source;
+ *   - `collectHardcodedStrings` — user-facing English literals that bypass
+ *     `t()`: JSX text, string-valued UI attributes, and `label` / `title` /
+ *     `header` / `placeholder` / `description` properties in UI files.
+ */
+
+export const MODULE_ROOT = join(__dirname, '..', '..')
+const SKIP_DIRS = new Set(['__tests__', '__integration__', 'migrations', 'i18n', 'node_modules'])
+/** Directories whose files render UI. */
+export const UI_DIRS = ['backend', 'components', 'widgets', 'workflows']
+
+export function listSourceFiles(dir: string, exts = /\.(tsx?|mts)$/): string[] {
+  const out: string[] = []
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry)
+    if (statSync(full).isDirectory()) {
+      if (!SKIP_DIRS.has(entry)) out.push(...listSourceFiles(full, exts))
+    } else if (exts.test(entry) && !/\.test\.tsx?$/.test(entry)) {
+      out.push(full)
+    }
+  }
+  return out
+}
+
+function parse(file: string): ts.SourceFile {
+  return ts.createSourceFile(file, readFileSync(file, 'utf8'), ts.ScriptTarget.Latest, true, file.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS)
+}
+
+function literalText(node: ts.Node | undefined): string | null {
+  if (!node) return null
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text
+  return null
+}
+
+const TRANSLATE_CALLEES = new Set(['t', 'translate', 'tr'])
+
+export function collectTranslationKeys(files: string[]): { keys: Set<string>; prefixes: Set<string> } {
+  const keys = new Set<string>()
+  const prefixes = new Set<string>()
+  for (const file of files) {
+    const visit = (node: ts.Node) => {
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && TRANSLATE_CALLEES.has(node.expression.text)) {
+        const first = node.arguments[0]
+        const key = literalText(first)
+        if (key?.startsWith('cpq.')) keys.add(key)
+        if (first && ts.isTemplateExpression(first) && first.head.text.startsWith('cpq.')) prefixes.add(first.head.text)
+      }
+      // `*Key` props (page meta, breadcrumbs) and injection-table `groupLabel`s the host translates.
+      if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && /(Key|^groupLabel)$/.test(node.name.text)) {
+        const key = literalText(node.initializer)
+        if (key?.startsWith('cpq.')) keys.add(key)
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(parse(file))
+  }
+  return { keys, prefixes }
+}
+
+const UI_ATTRIBUTES = new Set(['label', 'placeholder', 'title', 'aria-label', 'description', 'emptyLabel', 'emptyMessage', 'alt'])
+const UI_PROPERTIES = new Set(['label', 'title', 'header', 'placeholder', 'description', 'emptyLabel', 'emptyMessage'])
+/** Natural-language text: two letters in a row, not a code-ish token (snake_case, dotted, kebab, path, CSS). */
+function isProse(text: string): boolean {
+  const value = text.trim()
+  if (!/[A-Za-z]{2}/.test(value)) return false
+  if (/^[a-z0-9]+([._/-][a-z0-9]+)+$/i.test(value) && !/\s/.test(value)) return false
+  return true
+}
+
+export type HardcodedHit = { file: string; line: number; text: string }
+
+export function collectHardcodedStrings(files: string[]): HardcodedHit[] {
+  const hits: HardcodedHit[] = []
+  for (const file of files) {
+    const sf = parse(file)
+    const rel = relative(MODULE_ROOT, file)
+    const hit = (node: ts.Node, text: string) =>
+      hits.push({ file: rel, line: sf.getLineAndCharacterOfPosition(node.getStart()).line + 1, text: text.trim().slice(0, 80) })
+    const visit = (node: ts.Node) => {
+      if (ts.isJsxText(node) && isProse(node.text)) hit(node, node.text)
+      if (ts.isJsxAttribute(node) && UI_ATTRIBUTES.has(node.name.getText())) {
+        const init = node.initializer
+        const text = init && ts.isStringLiteral(init) ? init.text : init && ts.isJsxExpression(init) ? literalText(init.expression) : null
+        if (text && isProse(text)) hit(node, text)
+      }
+      if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && UI_PROPERTIES.has(node.name.text)) {
+        const text = literalText(node.initializer)
+        // `{ label: 'X', labelKey: 'cpq.x' }` (page meta, breadcrumbs) is translated by the host.
+        const parent = node.parent
+        const hasKeySibling =
+          ts.isObjectLiteralExpression(parent) &&
+          parent.properties.some((p) => ts.isPropertyAssignment(p) && p.name.getText() === `${node.name.getText()}Key`)
+        if (text && isProse(text) && !hasKeySibling) hit(node, text)
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(sf)
+  }
+  return hits
+}

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),
+    },
+  },
+}