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

package/src/modules/warranty_claims/api/portal/orders/route.ts

@@ -0,0 +1,206 @@
+import { NextResponse } from 'next/server'
+import { sql } from 'kysely'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { getCustomerAuthFromRequest, type CustomerAuthContext } from '@open-mercato/core/modules/customer_accounts/lib/customerAuth'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('warranty_claims')
+
+const PAGE_SIZE = 20
+
+const querySchema = z
+  .object({
+    search: z.preprocess(
+      (value) => (typeof value === 'string' ? value.trim() : value),
+      z.string().max(120).optional(),
+    ),
+    page: z.coerce.number().int().min(1).default(1),
+  })
+  .strict()
+
+const orderSchema = z.object({
+  id: z.string().uuid(),
+  orderNumber: z.string(),
+  placedAt: z.string().nullable(),
+  currencyCode: z.string().nullable(),
+  grandTotalGrossAmount: z.union([z.string(), z.number()]).nullable(),
+})
+
+const responseSchema = z.object({
+  ok: z.literal(true),
+  items: z.array(orderSchema),
+  total: z.number().int().nonnegative(),
+  page: z.number().int().min(1),
+  pageSize: z.number().int().min(1),
+})
+
+type PortalOrdersContext = {
+  auth: CustomerAuthContext
+  customerId: string
+  tenantId: string
+  organizationId: string
+  container: Awaited<ReturnType<typeof createRequestContainer>>
+  em: EntityManager
+}
+
+type PortalOrderItem = z.infer<typeof orderSchema>
+
+export const metadata = {
+  GET: { requireAuth: false },
+}
+
+function stringField(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key]
+  return typeof value === 'string' ? value : null
+}
+
+function isMissingTableError(err: unknown): boolean {
+  if (typeof err !== 'object' || err === null) return false
+  const candidate = err as { code?: unknown; message?: unknown }
+  return candidate.code === '42P01'
+    || (typeof candidate.message === 'string' && candidate.message.includes('does not exist'))
+}
+
+function amountField(record: Record<string, unknown>, key: string): string | number | null {
+  const value = record[key]
+  if (typeof value === 'string' || typeof value === 'number') return value
+  return null
+}
+
+function toIso(value: unknown): string | null {
+  if (!value) return null
+  if (value instanceof Date) return value.toISOString()
+  if (typeof value === 'string') {
+    const date = new Date(value)
+    return Number.isNaN(date.getTime()) ? value : date.toISOString()
+  }
+  return null
+}
+
+async function resolvePortalContext(req: Request): Promise<PortalOrdersContext | Response> {
+  const auth = await getCustomerAuthFromRequest(req)
+  const { translate } = await resolveTranslations()
+  if (!auth) {
+    return NextResponse.json({ ok: false, error: translate('warranty_claims.errors.unauthorized', 'Unauthorized') }, { status: 401 })
+  }
+  if (!auth.customerEntityId) {
+    return NextResponse.json({ ok: false, error: translate('warranty_claims.errors.customerAccountNotLinked', 'Customer account is not linked to a customer record') }, { status: 403 })
+  }
+  const container = await createRequestContainer()
+  const em = (container.resolve('em') as EntityManager).fork()
+  return {
+    auth,
+    customerId: auth.customerEntityId,
+    tenantId: auth.tenantId,
+    organizationId: auth.orgId,
+    container,
+    em,
+  }
+}
+
+type PortalOrdersDb = {
+  sales_orders: {
+    id: string
+    order_number: string
+    placed_at: Date | null
+    currency_code: string
+    grand_total_gross_amount: string | number | null
+    customer_entity_id: string | null
+    tenant_id: string | null
+    organization_id: string | null
+    deleted_at: Date | null
+  }
+}
+
+function serializeOrder(row: Record<string, unknown>): PortalOrderItem | null {
+  const id = stringField(row, 'id')
+  if (!id) return null
+  return {
+    id,
+    orderNumber: stringField(row, 'order_number') ?? id,
+    placedAt: toIso(row.placed_at),
+    currencyCode: stringField(row, 'currency_code'),
+    grandTotalGrossAmount: amountField(row, 'grand_total_gross_amount'),
+  }
+}
+
+export async function GET(req: Request) {
+  try {
+    const url = new URL(req.url)
+    const query = querySchema.parse(Object.fromEntries(url.searchParams))
+    const contextOrResponse = await resolvePortalContext(req)
+    if (contextOrResponse instanceof Response) return contextOrResponse
+    const context = contextOrResponse
+    const db = context.em.getKysely<PortalOrdersDb>()
+    let listQuery = db
+      .selectFrom('sales_orders')
+      .select(['id', 'order_number', 'placed_at', 'currency_code', 'grand_total_gross_amount'])
+      .where('tenant_id', '=', context.tenantId)
+      .where('organization_id', '=', context.organizationId)
+      .where('customer_entity_id', '=', context.customerId)
+      .where('deleted_at', 'is', null)
+    let countQuery = db
+      .selectFrom('sales_orders')
+      .select(sql<string>`count(*)`.as('total'))
+      .where('tenant_id', '=', context.tenantId)
+      .where('organization_id', '=', context.organizationId)
+      .where('customer_entity_id', '=', context.customerId)
+      .where('deleted_at', 'is', null)
+    if (query.search) {
+      const pattern = `%${escapeLikePattern(query.search)}%`
+      listQuery = listQuery.where('order_number', 'ilike', pattern)
+      countQuery = countQuery.where('order_number', 'ilike', pattern)
+    }
+    let rows: Array<Record<string, unknown>> = []
+    let total = 0
+    try {
+      rows = await listQuery
+        .orderBy('placed_at', 'desc')
+        .limit(PAGE_SIZE)
+        .offset((query.page - 1) * PAGE_SIZE)
+        .execute() as Array<Record<string, unknown>>
+      const countRow = await countQuery.executeTakeFirst()
+      total = Number(countRow?.total ?? 0) || 0
+    } catch (err) {
+      if (!isMissingTableError(err)) throw err
+    }
+
+    return NextResponse.json({
+      ok: true,
+      items: rows.map(serializeOrder).filter((item): item is PortalOrderItem => item !== null),
+      total,
+      page: query.page,
+      pageSize: PAGE_SIZE,
+    })
+  } catch (err) {
+    const { translate } = await resolveTranslations()
+    if (err instanceof z.ZodError) {
+      return NextResponse.json({ ok: false, error: translate('warranty_claims.errors.invalidInput', 'Invalid input') }, { status: 400 })
+    }
+    logger.error('warranty_claims.portal.orders.get failed', { err })
+    return NextResponse.json({ ok: false, error: translate('warranty_claims.errors.load_failed', 'Failed to load warranty claim data') }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Warranty Claims Portal',
+  summary: 'Customer portal warranty claim order picker',
+  methods: {
+    GET: {
+      summary: 'List authenticated customer orders for portal claim intake',
+      query: querySchema,
+      responses: [
+        {
+          status: 200,
+          description: 'Customer-owned sales orders',
+          schema: responseSchema,
+        },
+      ],
+    },
+  },
+}

package/src/modules/warranty_claims/api/portal/troubleshooting/route.ts

@@ -0,0 +1,151 @@
+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 { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { getCustomerAuthFromRequest, type CustomerAuthContext } from '@open-mercato/core/modules/customer_accounts/lib/customerAuth'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { WarrantyTroubleshootingGuide } from '../../../data/entities'
+import { claimTypeSchema } from '../../../data/validators'
+import {
+  parseGuideSteps,
+  selectBestGuide,
+  type TroubleshootingNode,
+} from '../../../lib/troubleshooting'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('warranty_claims')
+
+const optionalReasonCodeSchema = z.preprocess((value) => {
+  if (typeof value !== 'string') return value
+  const trimmed = value.trim()
+  return trimmed.length ? trimmed : undefined
+}, z.string().max(120).optional())
+
+const optionalClaimTypeSchema = z.preprocess((value) => {
+  if (typeof value !== 'string') return value
+  const trimmed = value.trim()
+  return trimmed.length ? trimmed : undefined
+}, claimTypeSchema.optional())
+
+const querySchema = z
+  .object({
+    claimType: optionalClaimTypeSchema,
+    reasonCode: optionalReasonCodeSchema,
+  })
+  .strict()
+
+const troubleshootingStepsSchema = z.record(z.string(), z.unknown())
+
+const responseSchema = z.object({
+  guide: z.object({
+    id: z.string().uuid(),
+    title: z.string(),
+    steps: troubleshootingStepsSchema,
+  }).nullable(),
+})
+
+type PortalTroubleshootingContext = {
+  auth: CustomerAuthContext
+  tenantId: string
+  organizationId: string
+  em: EntityManager
+}
+
+type PortalTroubleshootingGuide = {
+  id: string
+  title: string
+  claimType: string | null
+  reasonCode: string | null
+  isActive: boolean
+  steps: TroubleshootingNode
+}
+
+export const metadata = {
+  GET: { requireAuth: false },
+}
+
+async function resolvePortalContext(req: Request): Promise<PortalTroubleshootingContext | Response> {
+  const auth = await getCustomerAuthFromRequest(req)
+  const { translate } = await resolveTranslations()
+  if (!auth) {
+    return NextResponse.json({ ok: false, error: translate('warranty_claims.errors.unauthorized', 'Unauthorized') }, { status: 401 })
+  }
+  const container = await createRequestContainer()
+  return {
+    auth,
+    tenantId: auth.tenantId,
+    organizationId: auth.orgId,
+    em: (container.resolve('em') as EntityManager).fork(),
+  }
+}
+
+function serializeGuide(guide: WarrantyTroubleshootingGuide): PortalTroubleshootingGuide | null {
+  const steps = parseGuideSteps(guide.steps)
+  if (!steps) return null
+  return {
+    id: guide.id,
+    title: guide.title,
+    claimType: guide.claimType ?? null,
+    reasonCode: guide.reasonCode ?? null,
+    isActive: guide.isActive,
+    steps,
+  }
+}
+
+export async function GET(req: Request) {
+  try {
+    const url = new URL(req.url)
+    const query = querySchema.parse(Object.fromEntries(url.searchParams))
+    const contextOrResponse = await resolvePortalContext(req)
+    if (contextOrResponse instanceof Response) return contextOrResponse
+    const context = contextOrResponse
+
+    const guides = await context.em.find(
+      WarrantyTroubleshootingGuide,
+      {
+        tenantId: context.tenantId,
+        organizationId: context.organizationId,
+        isActive: true,
+        deletedAt: null,
+      },
+      {
+        orderBy: { updatedAt: 'desc' },
+        limit: 500,
+      },
+    )
+    const candidates = guides
+      .map(serializeGuide)
+      .filter((guide): guide is PortalTroubleshootingGuide => guide !== null)
+    const guide = selectBestGuide(candidates, query.claimType ?? null, query.reasonCode ?? null)
+
+    return NextResponse.json({
+      guide: guide ? { id: guide.id, title: guide.title, steps: guide.steps } : null,
+    })
+  } catch (err) {
+    const { translate } = await resolveTranslations()
+    if (err instanceof z.ZodError) {
+      return NextResponse.json({ ok: false, error: translate('warranty_claims.errors.invalidInput', 'Invalid input') }, { status: 400 })
+    }
+    logger.error('warranty_claims.portal.troubleshooting.get failed', { err })
+    return NextResponse.json({ ok: false, error: translate('warranty_claims.errors.load_failed', 'Failed to load warranty claim data') }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Warranty Claims Portal',
+  summary: 'Customer portal warranty troubleshooting guide',
+  methods: {
+    GET: {
+      summary: 'Load the best matching guided troubleshooting tree for portal claim intake',
+      query: querySchema,
+      responses: [
+        {
+          status: 200,
+          description: 'Matching troubleshooting guide, if configured',
+          schema: responseSchema,
+        },
+      ],
+    },
+  },
+}

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

@@ -0,0 +1,215 @@
+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 {
+  claimConditionGradeSchema,
+  claimLineReceiveSchema,
+  claimLineReleaseQuarantineSchema,
+  type ClaimLineReceiveInput,
+  type ClaimLineReleaseQuarantineInput,
+} from '../../data/validators'
+import { WARRANTY_CLAIM_LINE_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
+}
+
+type ReceivingAction =
+  | { kind: 'receive'; input: ClaimLineReceiveInput }
+  | { kind: 'release'; input: ClaimLineReleaseQuarantineInput }
+
+const uuid = z.string().uuid()
+const optimisticLockTokenSchema = z.string().datetime().nullable().optional()
+
+const receiveBodySchema = z
+  .object({
+    lineId: uuid,
+    conditionGrade: claimConditionGradeSchema,
+    inspectionNotes: z.string().trim().max(4000).optional(),
+    updatedAt: optimisticLockTokenSchema,
+  })
+  .strict()
+
+const releaseBodySchema = z
+  .object({
+    lineId: uuid,
+    action: z.literal('release'),
+    updatedAt: optimisticLockTokenSchema,
+  })
+  .strict()
+
+const receivingBodySchema = z.union([releaseBodySchema, receiveBodySchema])
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['warranty_claims.receiving.manage'] },
+}
+
+function toRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+}
+
+function translateKey(key: string): string {
+  return key
+}
+
+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 toReceivingAction(payload: Record<string, unknown>, context: ActionRouteContext): ReceivingAction {
+  const releaseBody = releaseBodySchema.safeParse(payload)
+  if (releaseBody.success) {
+    const scopedPayload = withScopedPayload({
+      id: releaseBody.data.lineId,
+      updatedAt: releaseBody.data.updatedAt,
+    }, context.ctx, context.translate)
+    return { kind: 'release', input: claimLineReleaseQuarantineSchema.parse(scopedPayload) }
+  }
+  const body = receiveBodySchema.parse(payload)
+  const scopedPayload = withScopedPayload({
+    id: body.lineId,
+    conditionGrade: body.conditionGrade,
+    inspectionNotes: body.inspectionNotes,
+    updatedAt: body.updatedAt,
+  }, context.ctx, context.translate)
+  return { kind: 'receive', input: claimLineReceiveSchema.parse(scopedPayload) }
+}
+
+function toGuardedAction(kind: ReceivingAction['kind'], payload: Record<string, unknown>): ReceivingAction {
+  if (kind === 'release') {
+    return { kind, input: claimLineReleaseQuarantineSchema.parse(payload) }
+  }
+  return { kind, input: claimLineReceiveSchema.parse(payload) }
+}
+
+async function runGuard(
+  req: Request,
+  context: ActionRouteContext,
+  action: ReceivingAction,
+): 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_LINE_RESOURCE_KIND,
+      resourceId: action.input.id,
+      operation: 'custom',
+      mutationPayload: { ...action.input },
+    },
+  })
+}
+
+async function executeReceivingAction(
+  commandBus: CommandBus,
+  action: ReceivingAction,
+  ctx: CommandRuntimeContext,
+): Promise<{ lineId: string; claimId: string }> {
+  if (action.kind === 'release') {
+    const { result } = await commandBus.execute<ClaimLineReleaseQuarantineInput, { lineId: string; claimId: string }>(
+      'warranty_claims.claim_line.release_quarantine',
+      { input: action.input, ctx },
+    )
+    if (!result) throw new CrudHttpError(400, { error: 'warranty_claims.errors.save_failed' })
+    return result
+  }
+  const { result } = await commandBus.execute<ClaimLineReceiveInput, { lineId: string; claimId: string }>(
+    'warranty_claims.claim_line.receive',
+    { input: action.input, ctx },
+  )
+  if (!result) throw new CrudHttpError(400, { error: 'warranty_claims.errors.save_failed' })
+  return result
+}
+
+export async function POST(req: Request) {
+  try {
+    const context = await resolveActionContext(req)
+    const payload = toRecord(await readJsonSafe(req, {}))
+    const action = toReceivingAction(payload, context)
+    const guarded = await runGuard(req, context, action)
+    if (!guarded.ok) {
+      return guarded.response
+    }
+    const commandAction = guarded.modifiedPayload ? toGuardedAction(action.kind, guarded.modifiedPayload) : action
+
+    const commandBus = context.ctx.container.resolve('commandBus') as CommandBus
+    const result = await executeReceivingAction(commandBus, commandAction, context.ctx)
+
+    await guarded.runAfterSuccess()
+
+    return NextResponse.json({ ok: true, lineId: result.lineId, claimId: result.claimId })
+  } 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.receiving.post failed', { err })
+    return NextResponse.json({ error: 'warranty_claims.errors.save_failed' }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Warranty Claims',
+  summary: 'Receive or release a warranty claim line',
+  methods: {
+    POST: {
+      summary: 'Grade a received line or release its quarantine hold',
+      requestBody: { contentType: 'application/json', schema: receivingBodySchema },
+      responses: [
+        {
+          status: 200,
+          description: 'Receiving action applied',
+          schema: z.object({
+            ok: z.boolean(),
+            lineId: z.string().uuid(),
+            claimId: z.string().uuid(),
+          }),
+        },
+      ],
+    },
+  },
+}