@dainamite/cpq 0.4.0 → 0.6.0

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

@@ -2,8 +2,11 @@ import { NextResponse } from 'next/server'
 import { z } from 'zod'
 import { resolveCpqRouteContext } from '../context'
 import { cpqConvertQuoteToOrderSchema } from '../../data/validators'
-import { OrderError } from '../../services/cpqOrderService'
+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')
@@ -65,8 +79,8 @@ function handleError(err: unknown, context: string) {
   if (err instanceof z.ZodError) {
     return NextResponse.json({ error: 'Validation error', details: err.issues }, { status: 400 })
   }
-  if (err instanceof OrderError) {
-    return NextResponse.json({ error: err.message }, { status: err.status })
+  if (isOrderError(err)) {
+    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]/clone/route.ts

@@ -1,6 +1,6 @@
 import { NextResponse } from 'next/server'
 import { resolveCpqRouteContext } from '../../../context'
-import { QuotingError } from '../../../../services/cpqQuotingService'
+import { isQuotingError } from '../../../../services/cpqQuotingService'
 import { resolveQuotingService } from '../../../resolveQuotingService'
 
 export const metadata = {
@@ -19,7 +19,7 @@ export async function POST(req: Request, { params }: { params: Promise<{ quoteId
     const result = await service.cloneQuote(quoteId, scope)
     return NextResponse.json(result, { status: 201 })
   } catch (err) {
-    if (err instanceof QuotingError) {
+    if (isQuotingError(err)) {
       return NextResponse.json({ error: err.message }, { status: err.status })
     }
     console.error('[cpq/quotes/[quoteId]/clone.POST]', err)

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

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

@@ -2,8 +2,11 @@ import { NextResponse } from 'next/server'
 import { z } from 'zod'
 import { resolveCpqRouteContext } from '../../../../context'
 import { cpqUpdateQuoteItemSchema } from '../../../../../data/validators'
-import { QuotingError } from '../../../../../services/cpqQuotingService'
+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,14 +22,26 @@ 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) {
       return NextResponse.json({ error: 'Validation error', details: err.issues }, { status: 400 })
     }
-    if (err instanceof QuotingError) {
+    if (isQuotingError(err)) {
       return NextResponse.json({ error: err.message }, { status: err.status })
     }
     console.error('[cpq/quotes/[quoteId]/items/[lineId].PUT]', err)
@@ -42,14 +57,46 @@ 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 (err instanceof QuotingError) {
+    if (isQuotingError(err)) {
       return NextResponse.json({ error: err.message }, { status: err.status })
     }
     console.error('[cpq/quotes/[quoteId]/items/[lineId].DELETE]', err)
     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

@@ -2,11 +2,17 @@ import { NextResponse } from 'next/server'
 import { z } from 'zod'
 import { resolveCpqRouteContext } from '../../../context'
 import { cpqRecalculateSchema } from '../../../../data/validators'
-import { QuotingError } from '../../../../services/cpqQuotingService'
+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,17 +24,50 @@ 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) {
       return NextResponse.json({ error: 'Validation error', details: err.issues }, { status: 400 })
     }
-    if (err instanceof QuotingError) {
+    if (isQuotingError(err)) {
       return NextResponse.json({ error: err.message }, { status: err.status })
     }
     console.error('[cpq/quotes/[quoteId]/recalculate.POST]', err)
     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]/route.ts

@@ -1,7 +1,7 @@
 import { NextResponse } from 'next/server'
 import { resolveCpqRouteContext } from '../../context'
 import { cpqUpdateQuoteSchema } from '../../../data/validators'
-import { QuotingError } from '../../../services/cpqQuotingService'
+import { isQuotingError } from '../../../services/cpqQuotingService'
 import { resolveQuotingService } from '../../resolveQuotingService'
 import { CpqQuoteConfiguration, CpqQuoteLineConfiguration } from '../../../data/entities'
 import { SalesQuote, SalesQuoteLine } from '@open-mercato/core/modules/sales/data/entities'
@@ -25,7 +25,7 @@ export async function GET(req: Request, { params }: { params: Promise<{ quoteId:
     const result = await service.getQuote(quoteId, scope)
     return NextResponse.json(result)
   } catch (err) {
-    if (err instanceof QuotingError) {
+    if (isQuotingError(err)) {
       return NextResponse.json({ error: err.message }, { status: err.status })
     }
     console.error('[cpq/quotes/[quoteId].GET]', err)