@open-mercato/core 0.6.8-develop.6998.1.d2bc46c56c → 0.6.8-develop.7001.1.03608ab252

package/src/modules/warranty_claims/api/ai/suggest/route.ts

@@ -0,0 +1,190 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { buildWarrantyClaimTriageSuggestion } from '../../../lib/triage'
+import {
+  claimDispositionSchema,
+  claimPrioritySchema,
+  claimTypeSchema,
+  claimWarrantyStatusSchema,
+} from '../../../data/validators'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('warranty_claims')
+
+const suggestSchema = z.object({
+  claimId: z.string().uuid(),
+}).strict()
+
+const triageReasonSchema = z.object({
+  messageKey: z.string(),
+  params: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
+})
+
+const triageSuggestionSchema = z.object({
+  claim: z.object({
+    id: z.string().uuid(),
+    claimNumber: z.string(),
+    claimType: claimTypeSchema,
+    status: z.string(),
+    customerName: z.string().nullable(),
+    submittedAt: z.string().nullable(),
+    slaDueAt: z.string().nullable(),
+  }),
+  eligibility: z.object({
+    status: z.enum(['fast_track_candidate', 'review_required']),
+    reason: triageReasonSchema,
+  }),
+  priority: z.object({
+    currentPriority: claimPrioritySchema,
+    suggestedPriority: claimPrioritySchema,
+    ageHours: z.number().nullable(),
+    slaDueAt: z.string().nullable(),
+    overdue: z.boolean(),
+    reason: triageReasonSchema,
+  }),
+  lines: z.array(z.object({
+    lineId: z.string().uuid(),
+    lineNo: z.number().int(),
+    sku: z.string().nullable(),
+    productName: z.string().nullable(),
+    serialNumber: z.string().nullable(),
+    qtyClaimed: z.number(),
+    eligibility: z.object({
+      status: claimWarrantyStatusSchema,
+      purchaseDate: z.string().nullable(),
+      warrantyMonths: z.number().int().nullable(),
+      warrantyExpiresAt: z.string().nullable(),
+      reason: triageReasonSchema,
+    }),
+    suggestedDisposition: claimDispositionSchema,
+    suggestedPath: z.enum(['replace', 'repair_review', 'deny', 'credit_with_restocking_fee', 'core_accept']),
+    reason: triageReasonSchema,
+    restockingFeePercent: z.number().nullable(),
+  })),
+  risk: z.object({
+    level: z.enum(['none', 'low', 'medium', 'high']),
+    signals: z.array(z.object({
+      id: z.enum(['duplicate_serial', 'duplicate_order_claim', 'outside_return_window', 'over_quantity_claim', 'repeat_claimer', 'value_velocity']),
+      level: z.enum(['low', 'medium', 'high']),
+      messageKey: z.string(),
+      params: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
+      relatedClaimNumbers: z.array(z.string()).optional(),
+    })),
+  }),
+  generatedAt: z.string(),
+})
+
+type SuggestRouteContext = {
+  tenantId: string
+  organizationId: string
+  em: EntityManager
+  translate: (key: string, fallback?: string) => string
+}
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['warranty_claims.claim.view'] },
+  POST: { requireAuth: true, requireFeatures: ['warranty_claims.claim.view'] },
+}
+
+function toRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+}
+
+async function resolveSuggestContext(req: Request): Promise<SuggestRouteContext> {
+  const container = await createRequestContainer()
+  const auth = await getAuthFromRequest(req)
+  const { translate } = await resolveTranslations()
+  if (!auth || !auth.tenantId) {
+    throw new CrudHttpError(401, { error: translate('warranty_claims.errors.unauthorized', 'Unauthorized') })
+  }
+  const organizationScope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+  const organizationId = organizationScope?.selectedId ?? auth.orgId ?? null
+  if (!organizationId) {
+    throw new CrudHttpError(400, { error: translate('warranty_claims.errors.organization_required', 'Organization context is required') })
+  }
+  return {
+    tenantId: auth.tenantId,
+    organizationId,
+    em: container.resolve<EntityManager>('em').fork(),
+    translate,
+  }
+}
+
+async function buildResponse(context: SuggestRouteContext, input: z.infer<typeof suggestSchema>) {
+  const suggestions = await buildWarrantyClaimTriageSuggestion({
+    em: context.em,
+    claimId: input.claimId,
+    scope: { tenantId: context.tenantId, organizationId: context.organizationId },
+  })
+  return NextResponse.json(suggestions)
+}
+
+export async function GET(req: Request) {
+  try {
+    const context = await resolveSuggestContext(req)
+    const url = new URL(req.url)
+    const input = suggestSchema.parse({ claimId: url.searchParams.get('claimId') ?? undefined })
+    return buildResponse(context, input)
+  } catch (err) {
+    if (isCrudHttpError(err)) return NextResponse.json(err.body, { status: err.status })
+    const { translate } = await resolveTranslations()
+    if (err instanceof z.ZodError) {
+      return NextResponse.json({ error: translate('warranty_claims.errors.invalidInput', 'Invalid input') }, { status: 400 })
+    }
+    logger.error('warranty_claims.ai.suggest.get failed', { err })
+    return NextResponse.json({ error: translate('warranty_claims.errors.notFound', 'Warranty claim not found.') }, { status: 404 })
+  }
+}
+
+export async function POST(req: Request) {
+  try {
+    const context = await resolveSuggestContext(req)
+    const input = suggestSchema.parse(toRecord(await readJsonSafe(req, {})))
+    return buildResponse(context, input)
+  } catch (err) {
+    if (isCrudHttpError(err)) return NextResponse.json(err.body, { status: err.status })
+    const { translate } = await resolveTranslations()
+    if (err instanceof z.ZodError) {
+      return NextResponse.json({ error: translate('warranty_claims.errors.invalidInput', 'Invalid input') }, { status: 400 })
+    }
+    logger.error('warranty_claims.ai.suggest.post failed', { err })
+    return NextResponse.json({ error: translate('warranty_claims.errors.notFound', 'Warranty claim not found.') }, { status: 404 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Warranty Claims',
+  summary: 'Suggest warranty claim triage',
+  methods: {
+    GET: {
+      summary: 'Return deterministic triage suggestions for a claim',
+      query: suggestSchema,
+      responses: [
+        {
+          status: 200,
+          description: 'Triage suggestions',
+          schema: triageSuggestionSchema,
+        },
+      ],
+    },
+    POST: {
+      summary: 'Return deterministic triage suggestions for a claim',
+      requestBody: { contentType: 'application/json', schema: suggestSchema },
+      responses: [
+        {
+          status: 200,
+          description: 'Triage suggestions',
+          schema: triageSuggestionSchema,
+        },
+      ],
+    },
+  },
+}

package/src/modules/warranty_claims/api/assign/route.ts

@@ -0,0 +1,142 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { runRouteMutationGuards, type RouteMutationGuardResult } from '@open-mercato/shared/lib/crud/route-mutation-guard'
+import { withScopedPayload } from '@open-mercato/shared/lib/api/scoped'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { assignClaimInputSchema, type AssignClaimInput } from '../../data/validators'
+import { WARRANTY_CLAIM_RESOURCE_KIND } from '../../commands/shared'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('warranty_claims')
+
+type ActionRouteContext = {
+  ctx: CommandRuntimeContext
+  tenantId: string
+  organizationId: string
+  translate: (key: string, fallback?: string) => string
+}
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['warranty_claims.claim.manage'] },
+}
+
+function toRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+}
+
+async function resolveActionContext(req: Request): Promise<ActionRouteContext> {
+  const container = await createRequestContainer()
+  const auth = await getAuthFromRequest(req)
+  const { translate } = await resolveTranslations()
+  if (!auth || !auth.tenantId) {
+    throw new CrudHttpError(401, { error: translate('warranty_claims.errors.unauthorized', 'Unauthorized') })
+  }
+  const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+  const organizationId = scope?.selectedId ?? auth.orgId ?? null
+  if (!organizationId) {
+    throw new CrudHttpError(400, { error: translate('warranty_claims.errors.organization_required', 'Organization context is required') })
+  }
+  return {
+    ctx: {
+      container,
+      auth,
+      organizationScope: scope,
+      selectedOrganizationId: organizationId,
+      organizationIds: scope?.filterIds ?? (auth.orgId ? [auth.orgId] : null),
+      request: req,
+    },
+    tenantId: auth.tenantId,
+    organizationId,
+    translate,
+  }
+}
+
+function toAssignInput(scopedPayload: Record<string, unknown>): AssignClaimInput {
+  return assignClaimInputSchema.parse({
+    id: scopedPayload.id,
+    assigneeUserId: scopedPayload.assigneeUserId,
+  })
+}
+
+async function runGuard(
+  req: Request,
+  context: ActionRouteContext,
+  input: AssignClaimInput,
+): Promise<RouteMutationGuardResult> {
+  const userId = context.ctx.auth?.sub
+  if (!userId) {
+    throw new CrudHttpError(401, { error: context.translate('warranty_claims.errors.unauthorized', 'Unauthorized') })
+  }
+  return runRouteMutationGuards({
+    container: context.ctx.container,
+    req,
+    auth: {
+      userId,
+      tenantId: context.tenantId,
+      organizationId: context.organizationId,
+    },
+    input: {
+      resourceKind: WARRANTY_CLAIM_RESOURCE_KIND,
+      resourceId: input.id,
+      operation: 'custom',
+      mutationPayload: { ...input },
+    },
+  })
+}
+
+export async function POST(req: Request) {
+  try {
+    const context = await resolveActionContext(req)
+    const payload = toRecord(await readJsonSafe(req, {}))
+    const scopedPayload = withScopedPayload(payload, context.ctx, context.translate)
+    const input = toAssignInput(scopedPayload)
+    const guarded = await runGuard(req, context, input)
+    if (!guarded.ok) {
+      return guarded.response
+    }
+    const commandInput = guarded.modifiedPayload ? toAssignInput(guarded.modifiedPayload) : input
+
+    const commandBus = context.ctx.container.resolve('commandBus') as CommandBus
+    const { result } = await commandBus.execute<AssignClaimInput, { claimId: string }>(
+      'warranty_claims.claim.assign',
+      { input: commandInput, ctx: context.ctx },
+    )
+
+    await guarded.runAfterSuccess()
+
+    return NextResponse.json({ ok: true, claimId: result?.claimId ?? commandInput.id })
+  } catch (err) {
+    if (isCrudHttpError(err)) return NextResponse.json(err.body, { status: err.status })
+    const { translate } = await resolveTranslations()
+    if (err instanceof z.ZodError) {
+      return NextResponse.json({ error: translate('warranty_claims.errors.invalidInput', 'Invalid input') }, { status: 400 })
+    }
+    logger.error('warranty_claims.assign.post failed', { err })
+    return NextResponse.json({ error: translate('warranty_claims.errors.save_failed', 'Failed to save warranty claim') }, { status: 400 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Warranty Claims',
+  summary: 'Assign warranty claim',
+  methods: {
+    POST: {
+      summary: 'Assign or unassign a claim',
+      requestBody: { contentType: 'application/json', schema: assignClaimInputSchema },
+      responses: [
+        {
+          status: 200,
+          description: 'Claim assigned',
+          schema: z.object({ ok: z.boolean(), claimId: z.string().uuid() }),
+        },
+      ],
+    },
+  },
+}

package/src/modules/warranty_claims/api/assignees/route.ts

@@ -0,0 +1,102 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { parseCommaSeparatedList } from '@open-mercato/shared/lib/string'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { resolveAssigneeDisplayNames } from '../../lib/assigneeNames'
+
+const logger = createLogger('warranty_claims')
+
+export const MAX_ASSIGNEE_LOOKUP_IDS = 100
+
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+const querySchema = z.object({
+  ids: z.string().min(1),
+}).strict()
+
+const responseSchema = z.object({
+  items: z.array(z.object({
+    id: z.string(),
+    name: z.string().nullable(),
+  })),
+})
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['warranty_claims.claim.view'] },
+}
+
+export function parseRequestedIds(raw: string): string[] {
+  const deduped = new Set<string>()
+  for (const value of parseCommaSeparatedList(raw)) {
+    if (UUID_REGEX.test(value)) deduped.add(value)
+  }
+  return [...deduped].slice(0, MAX_ASSIGNEE_LOOKUP_IDS)
+}
+
+export async function GET(req: Request) {
+  try {
+    const url = new URL(req.url)
+    const parsedQuery = querySchema.parse(Object.fromEntries(url.searchParams))
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    const { translate } = await resolveTranslations()
+    if (!auth || !auth.tenantId) {
+      throw new CrudHttpError(401, { error: translate('warranty_claims.errors.unauthorized', 'Unauthorized') })
+    }
+
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+    const tenantId = scope.tenantId ?? auth.tenantId
+    if (!tenantId) {
+      throw new CrudHttpError(401, { error: translate('warranty_claims.errors.unauthorized', 'Unauthorized') })
+    }
+
+    const requestedIds = parseRequestedIds(parsedQuery.ids)
+    if (!requestedIds.length) return NextResponse.json({ items: [] })
+
+    const displayNames = await resolveAssigneeDisplayNames({
+      container,
+      tenantId,
+      organizationId: scope.selectedId,
+      organizationIds: scope.filterIds,
+    }, requestedIds)
+    const items = requestedIds.flatMap((id) => {
+      const name = displayNames.get(id)
+      return name ? [{ id, name }] : []
+    })
+    return NextResponse.json({ items })
+  } catch (error) {
+    if (isCrudHttpError(error)) {
+      return NextResponse.json(error.body, { status: error.status })
+    }
+    if (error instanceof z.ZodError) {
+      return NextResponse.json({ error: 'warranty_claims.errors.invalidInput' }, { status: 400 })
+    }
+    logger.error('[warranty_claims] Failed to resolve assignee display names', { error })
+    return NextResponse.json({ error: 'warranty_claims.errors.load_failed' }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Warranty Claims',
+  summary: 'Warranty claim assignee display names',
+  methods: {
+    GET: {
+      summary: 'Resolve assignee user ids to display names',
+      description: `Resolves up to ${MAX_ASSIGNEE_LOOKUP_IDS} explicitly supplied user ids to their display name, scoped to the caller's tenant and selected or visible organizations. Requires \`ids\`; it cannot enumerate the user directory, and it returns neither role assignments nor organization membership.`,
+      query: querySchema,
+      responses: [
+        {
+          status: 200,
+          description: 'Assignee display names',
+          schema: responseSchema,
+        },
+      ],
+    },
+  },
+}

package/src/modules/warranty_claims/api/credit-memo/route.ts

@@ -0,0 +1,191 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { runRouteMutationGuards, type RouteMutationGuardResult } from '@open-mercato/shared/lib/crud/route-mutation-guard'
+import { withScopedPayload } from '@open-mercato/shared/lib/api/scoped'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import {
+  claimCreateCreditMemoSchema,
+  type ClaimCreateCreditMemoInput,
+} from '../../data/validators'
+import { WARRANTY_CLAIM_RESOURCE_KIND } from '../../commands/shared'
+
+const logger = createLogger('warranty_claims')
+
+type ActionRouteContext = {
+  ctx: CommandRuntimeContext
+  tenantId: string
+  organizationId: string
+  translate: (key: string, fallback?: string) => string
+}
+
+type CreditMemoCommandResult = {
+  claimId: string
+  creditMemoId: string
+  creditMemoUpdatedAt: string | null
+  skippedLineIds: string[]
+  grandTotalGrossAmount: string
+  currencyCode: string
+}
+
+const creditMemoRequestSchema = z
+  .object({
+    claimId: z.string().uuid(),
+    updatedAt: z.string().datetime().nullable().optional(),
+  })
+  .strict()
+
+type CreditMemoRequest = z.infer<typeof creditMemoRequestSchema>
+
+const creditMemoResponseSchema = z.object({
+  creditMemoId: z.string().uuid(),
+  skippedLineIds: z.array(z.string().uuid()),
+  grandTotalGrossAmount: z.string(),
+  currencyCode: z.string(),
+})
+
+const errorResponseSchema = z.object({
+  error: z.string(),
+})
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['warranty_claims.claim.manage', 'sales.credit_memos.manage'] },
+}
+
+function translateKey(key: string): string {
+  return key
+}
+
+function toRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+}
+
+async function resolveActionContext(req: Request): Promise<ActionRouteContext> {
+  const container = await createRequestContainer()
+  const auth = await getAuthFromRequest(req)
+  if (!auth || !auth.tenantId) {
+    throw new CrudHttpError(401, { error: 'warranty_claims.errors.unauthorized' })
+  }
+  const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+  const organizationId = scope?.selectedId ?? auth.orgId ?? null
+  if (!organizationId) {
+    throw new CrudHttpError(400, { error: 'warranty_claims.errors.organization_required' })
+  }
+  return {
+    ctx: {
+      container,
+      auth,
+      organizationScope: scope,
+      selectedOrganizationId: organizationId,
+      organizationIds: scope?.filterIds ?? (auth.orgId ? [auth.orgId] : null),
+      request: req,
+    },
+    tenantId: auth.tenantId,
+    organizationId,
+    translate: translateKey,
+  }
+}
+
+function toCreditMemoRequest(payload: Record<string, unknown>): CreditMemoRequest {
+  return creditMemoRequestSchema.parse(payload)
+}
+
+function toCommandInput(
+  input: CreditMemoRequest,
+  context: ActionRouteContext,
+): ClaimCreateCreditMemoInput {
+  const scopedPayload = withScopedPayload({
+    id: input.claimId,
+    updatedAt: input.updatedAt,
+  }, context.ctx, context.translate)
+  return claimCreateCreditMemoSchema.parse(scopedPayload)
+}
+
+async function runGuard(
+  req: Request,
+  context: ActionRouteContext,
+  input: CreditMemoRequest,
+): Promise<RouteMutationGuardResult> {
+  const userId = context.ctx.auth?.sub
+  if (!userId) {
+    throw new CrudHttpError(401, { error: 'warranty_claims.errors.unauthorized' })
+  }
+  return runRouteMutationGuards({
+    container: context.ctx.container,
+    req,
+    auth: {
+      userId,
+      tenantId: context.tenantId,
+      organizationId: context.organizationId,
+    },
+    input: {
+      resourceKind: WARRANTY_CLAIM_RESOURCE_KIND,
+      resourceId: input.claimId,
+      operation: 'custom',
+      mutationPayload: { ...input },
+    },
+  })
+}
+
+export async function POST(req: Request) {
+  try {
+    const context = await resolveActionContext(req)
+    const requestInput = toCreditMemoRequest(toRecord(await readJsonSafe(req, {})))
+    const guarded = await runGuard(req, context, requestInput)
+    if (!guarded.ok) {
+      return guarded.response
+    }
+    const guardedInput = guarded.modifiedPayload
+      ? toCreditMemoRequest(guarded.modifiedPayload)
+      : requestInput
+    const commandBus = context.ctx.container.resolve('commandBus') as CommandBus
+    const { result } = await commandBus.execute<ClaimCreateCreditMemoInput, CreditMemoCommandResult>(
+      'warranty_claims.claim.create_credit_memo',
+      { input: toCommandInput(guardedInput, context), ctx: context.ctx },
+    )
+    if (!result) throw new CrudHttpError(400, { error: 'warranty_claims.errors.save_failed' })
+    await guarded.runAfterSuccess()
+    return NextResponse.json({
+      creditMemoId: result.creditMemoId,
+      skippedLineIds: result.skippedLineIds,
+      grandTotalGrossAmount: result.grandTotalGrossAmount,
+      currencyCode: result.currencyCode,
+    })
+  } catch (err) {
+    if (isCrudHttpError(err)) return NextResponse.json(err.body, { status: err.status })
+    if (err instanceof z.ZodError) {
+      return NextResponse.json({ error: 'warranty_claims.errors.invalidInput' }, { status: 400 })
+    }
+    logger.error('warranty_claims.credit-memo.post failed', { err })
+    return NextResponse.json({ error: 'warranty_claims.errors.save_failed' }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Warranty Claims',
+  summary: 'Create a credit memo from a warranty claim',
+  methods: {
+    POST: {
+      summary: 'Create and link a credit memo from eligible received credit or refund lines',
+      description: 'Amounts are prorated from source order-line totals. Version 1 does not prorate order-level adjustments.',
+      requestBody: { contentType: 'application/json', schema: creditMemoRequestSchema },
+      responses: [
+        {
+          status: 200,
+          description: 'Credit memo created and linked; ineligible or unresolvable claim lines are reported as skipped',
+          schema: creditMemoResponseSchema,
+        },
+        { status: 400, description: 'Invalid request or claim is not eligible for credit-memo creation', schema: errorResponseSchema },
+        { status: 401, description: 'Authentication required', schema: errorResponseSchema },
+        { status: 403, description: 'Insufficient permissions', schema: errorResponseSchema },
+        { status: 409, description: 'Optimistic lock conflict', schema: errorResponseSchema },
+      ],
+    },
+  },
+}