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

package/src/modules/warranty_claims/api/return-label/route.ts

@@ -0,0 +1,291 @@
+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 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 { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { WarrantyClaim, WarrantyClaimLine } from '../../data/entities'
+import { claimSetReturnLabelSchema, type ClaimSetReturnLabelInput } from '../../data/validators'
+import type { WarrantyReturnLabelProvider } from '../../services/returnLabelProvider'
+import {
+  WARRANTY_CLAIM_RESOURCE_KIND,
+  enforceWarrantyClaimOptimisticLock,
+  requireScopedClaim,
+} 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
+}
+
+type ReturnLabelCreatedResponse = {
+  status: 'created'
+  labelUrl: string | null
+  trackingNumber: string | null
+  carrier: string | null
+}
+type ReturnLabelCommandResult = Omit<ReturnLabelCreatedResponse, 'status'> & { claimId: string }
+
+const uuid = z.string().uuid()
+const returnLabelText = (max: number) => z.string().trim().min(1).max(max).optional()
+const optimisticLockTokenSchema = z.string().datetime().nullable().optional()
+
+const returnLabelRequestSchema = z
+  .object({
+    claimId: uuid,
+    manual: z.boolean().optional(),
+    labelUrl: returnLabelText(2048),
+    trackingNumber: returnLabelText(191),
+    carrier: returnLabelText(120),
+    updatedAt: optimisticLockTokenSchema,
+  })
+  .strict()
+
+type ReturnLabelRequest = z.infer<typeof returnLabelRequestSchema>
+
+const returnLabelResponseSchema = z.discriminatedUnion('status', [
+  z.object({
+    status: z.literal('created'),
+    labelUrl: z.string().nullable(),
+    trackingNumber: z.string().nullable(),
+    carrier: z.string().nullable(),
+  }),
+  z.object({ status: z.literal('notConfigured') }),
+])
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['warranty_claims.claim.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 toReturnLabelRequest(payload: Record<string, unknown>): ReturnLabelRequest {
+  return returnLabelRequestSchema.parse({
+    claimId: payload.claimId ?? payload.id,
+    manual: payload.manual,
+    labelUrl: payload.labelUrl,
+    trackingNumber: payload.trackingNumber,
+    carrier: payload.carrier,
+    updatedAt: payload.updatedAt,
+  })
+}
+
+function isManualRequest(input: ReturnLabelRequest): boolean {
+  return input.manual === true
+    || input.labelUrl !== undefined
+    || input.trackingNumber !== undefined
+    || input.carrier !== undefined
+}
+
+function toSetReturnLabelInput(
+  input: ReturnLabelRequest,
+  context: ActionRouteContext,
+): ClaimSetReturnLabelInput {
+  const scopedPayload = withScopedPayload({
+    id: input.claimId,
+    labelUrl: input.labelUrl,
+    trackingNumber: input.trackingNumber,
+    carrier: input.carrier,
+    updatedAt: input.updatedAt,
+  }, context.ctx, context.translate)
+  return claimSetReturnLabelSchema.parse(scopedPayload)
+}
+
+async function runGuard(
+  req: Request,
+  context: ActionRouteContext,
+  input: ReturnLabelRequest,
+): 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 },
+    },
+  })
+}
+
+async function loadClaimAndLines(
+  context: ActionRouteContext,
+  claimId: string,
+): Promise<{ claim: WarrantyClaim; lines: WarrantyClaimLine[] }> {
+  const scope = { tenantId: context.tenantId, organizationId: context.organizationId }
+  const em = (context.ctx.container.resolve('em') as EntityManager).fork()
+  const claim = await requireScopedClaim(em, claimId, scope)
+  const lines = await findWithDecryption(
+    em,
+    WarrantyClaimLine,
+    { claim: claim.id, tenantId: scope.tenantId, organizationId: scope.organizationId, deletedAt: null },
+    {},
+    scope,
+  )
+  return { claim, lines }
+}
+
+function assertGeneratableStatus(claim: WarrantyClaim): void {
+  if (claim.status !== 'approved' && claim.status !== 'awaiting_return') {
+    throw new CrudHttpError(400, { error: 'warranty_claims.errors.returnLabelInvalidStatus' })
+  }
+}
+
+async function executeSetReturnLabel(
+  commandBus: CommandBus,
+  input: ClaimSetReturnLabelInput,
+  ctx: CommandRuntimeContext,
+): Promise<ReturnLabelCreatedResponse> {
+  const { result } = await commandBus.execute<ClaimSetReturnLabelInput, ReturnLabelCommandResult>(
+    'warranty_claims.claim.set_return_label',
+    { input, ctx },
+  )
+  if (!result) throw new CrudHttpError(400, { error: 'warranty_claims.errors.save_failed' })
+  return {
+    status: 'created',
+    labelUrl: result.labelUrl,
+    trackingNumber: result.trackingNumber,
+    carrier: result.carrier,
+  }
+}
+
+export function firstTranslatableIssueKey(err: z.ZodError): string {
+  const keyed = err.issues.find(
+    (issue) => typeof issue.message === 'string' && issue.message.startsWith('warranty_claims.'),
+  )?.message
+  return keyed ?? 'warranty_claims.errors.invalidInput'
+}
+
+export async function POST(req: Request) {
+  try {
+    const context = await resolveActionContext(req)
+    const requestInput = toReturnLabelRequest(toRecord(await readJsonSafe(req, {})))
+    const guarded = await runGuard(req, context, requestInput)
+    if (!guarded.ok) {
+      return guarded.response
+    }
+    const guardedInput = guarded.modifiedPayload ? toReturnLabelRequest(guarded.modifiedPayload) : requestInput
+    const commandBus = context.ctx.container.resolve('commandBus') as CommandBus
+
+    if (isManualRequest(guardedInput)) {
+      const response = await executeSetReturnLabel(
+        commandBus,
+        toSetReturnLabelInput(guardedInput, context),
+        context.ctx,
+      )
+      await guarded.runAfterSuccess()
+      return NextResponse.json(response)
+    }
+
+    const { claim, lines } = await loadClaimAndLines(context, guardedInput.claimId)
+    assertGeneratableStatus(claim)
+    await enforceWarrantyClaimOptimisticLock(
+      context.ctx,
+      claim,
+      WARRANTY_CLAIM_RESOURCE_KIND,
+      guardedInput.updatedAt ?? undefined,
+    )
+
+    const provider = context.ctx.container.resolve<WarrantyReturnLabelProvider>('warrantyReturnLabelProvider')
+    const result = await provider.createReturnLabel(
+      { claim, lines },
+      { tenantId: context.tenantId, organizationId: context.organizationId },
+      context.ctx.container,
+    )
+
+    if (result.status === 'notConfigured') {
+      return NextResponse.json({ status: 'notConfigured' })
+    }
+
+    const response = await executeSetReturnLabel(
+      commandBus,
+      toSetReturnLabelInput({
+        ...guardedInput,
+        labelUrl: result.labelUrl,
+        trackingNumber: result.trackingNumber,
+        carrier: result.carrier,
+      }, context),
+      context.ctx,
+    )
+    await guarded.runAfterSuccess()
+    return NextResponse.json(response)
+  } catch (err) {
+    if (isCrudHttpError(err)) return NextResponse.json(err.body, { status: err.status })
+    if (err instanceof z.ZodError) {
+      return NextResponse.json({ error: firstTranslatableIssueKey(err) }, { status: 400 })
+    }
+    logger.error('warranty_claims.return-label.post failed', { err })
+    return NextResponse.json({ error: 'warranty_claims.errors.save_failed' }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Warranty Claims',
+  summary: 'Create or record a return label for a warranty claim',
+  methods: {
+    POST: {
+      summary: 'Generate a carrier return label or record manual label details',
+      requestBody: { contentType: 'application/json', schema: returnLabelRequestSchema },
+      responses: [
+        {
+          status: 200,
+          description: 'Return label created or provider not configured',
+          schema: returnLabelResponseSchema,
+        },
+      ],
+    },
+  },
+}

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

@@ -0,0 +1,112 @@
+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 { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { WarrantyClaimLine } from '../../data/entities'
+import { requireScopedClaim, type WarrantyClaimScope } from '../../commands/shared'
+import { evaluateClaimRisk } from '../../lib/risk'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('warranty_claims')
+
+const querySchema = z.object({
+  claimId: z.string().uuid(),
+}).strict()
+
+const riskSignalSchema = 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(),
+})
+
+const responseSchema = z.object({
+  ok: z.literal(true),
+  result: z.object({
+    level: z.enum(['none', 'low', 'medium', 'high']),
+    signals: z.array(riskSignalSchema),
+  }),
+})
+
+type RiskRouteContext = {
+  tenantId: string
+  organizationId: string
+  scope: WarrantyClaimScope
+  em: EntityManager
+}
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['warranty_claims.claim.view'] },
+}
+
+async function resolveRiskContext(req: Request): Promise<RiskRouteContext> {
+  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') })
+  }
+  const em = container.resolve('em') as EntityManager
+  return {
+    tenantId: auth.tenantId,
+    organizationId,
+    scope: { tenantId: auth.tenantId, organizationId },
+    em,
+  }
+}
+
+export async function GET(req: Request) {
+  try {
+    const context = await resolveRiskContext(req)
+    const url = new URL(req.url)
+    const query = querySchema.parse(Object.fromEntries(url.searchParams))
+    const claim = await requireScopedClaim(context.em, query.claimId, context.scope)
+    const lines = await findWithDecryption(
+      context.em,
+      WarrantyClaimLine,
+      { claim: claim.id, tenantId: context.tenantId, organizationId: context.organizationId, deletedAt: null },
+      { orderBy: { lineNo: 'ASC' } },
+      context.scope,
+    )
+    const result = await evaluateClaimRisk(context.em, claim, lines)
+    return NextResponse.json({ ok: true, result })
+  } 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.risk.get failed', { err })
+    return NextResponse.json({ error: translate('warranty_claims.errors.load_failed', 'Failed to load warranty claim data') }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Warranty Claims',
+  summary: 'Evaluate warranty claim risk',
+  methods: {
+    GET: {
+      summary: 'Evaluate deterministic risk signals for a claim',
+      query: querySchema,
+      responses: [
+        {
+          status: 200,
+          description: 'Risk assessment',
+          schema: responseSchema,
+        },
+      ],
+    },
+  },
+}