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

package/src/modules/warranty_claims/subscribers/return-shipment-tracking.ts

@@ -0,0 +1,226 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AwilixContainer } from 'awilix'
+import type { Kysely } from 'kysely'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { TransitionClaimInput } from '../data/validators'
+
+const logger = createLogger('warranty_claims')
+const SYSTEM_USER_ID = '00000000-0000-0000-0000-000000000000'
+
+export const metadata = {
+  event: 'shipping_carriers.shipment.delivered',
+  persistent: true,
+  id: 'warranty_claims:return-shipment-tracking',
+}
+
+type ResolverContainer = {
+  resolve: <T = unknown>(name: string) => T
+}
+
+type SubscriberContext = ResolverContainer & {
+  container?: ResolverContainer
+  tenantId?: string | null
+  organizationId?: string | null
+}
+
+type ReturnTrackingDb = {
+  carrier_shipments: {
+    id: string
+    tracking_number: string | null
+    tenant_id: string | null
+    organization_id: string | null
+    deleted_at: Date | null
+  }
+  warranty_claims: {
+    id: string
+    claim_number: string
+    updated_at: Date | null
+    status: string
+    return_tracking_number: string | null
+    tenant_id: string
+    organization_id: string
+    deleted_at: Date | null
+  }
+}
+
+function toRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+}
+
+function readString(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key]
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null
+}
+
+function resolveContainer(ctx: SubscriberContext): ResolverContainer {
+  return ctx.container ?? { resolve: ctx.resolve }
+}
+
+function isMissingReferenceTableError(error: unknown): boolean {
+  const candidate = toRecord(error)
+  return candidate.code === '42P01'
+    || (typeof candidate.message === 'string' && /relation "[^"]*" does not exist/.test(candidate.message))
+}
+
+function isInvalidTransitionError(error: unknown): boolean {
+  if (isCrudHttpError(error)) {
+    return error.status === 400 && error.body.error === 'warranty_claims.errors.invalidTransition'
+  }
+  const candidate = toRecord(error)
+  const body = toRecord(candidate.body)
+  return candidate.status === 400 && body.error === 'warranty_claims.errors.invalidTransition'
+}
+
+export default async function handle(payload: unknown, ctx: SubscriberContext): Promise<void> {
+  const record = toRecord(payload)
+  const shipmentId = readString(record, 'shipmentId') ?? readString(record, 'shipment_id')
+  const tenantId = ctx.tenantId ?? null
+  const organizationId = ctx.organizationId ?? null
+
+  if (!shipmentId || !tenantId || !organizationId) {
+    logger.debug('[warranty_claims:return-shipment-tracking] skipped incomplete delivered payload', {
+      hasShipmentId: Boolean(shipmentId),
+      hasTrustedTenantId: Boolean(tenantId),
+      hasTrustedOrganizationId: Boolean(organizationId),
+    })
+    return
+  }
+
+  const container = resolveContainer(ctx)
+  let db: Kysely<ReturnTrackingDb>
+  try {
+    const em = container.resolve<EntityManager>('em').fork()
+    db = em.getKysely<ReturnTrackingDb>()
+  } catch (error) {
+    logger.error('[warranty_claims:return-shipment-tracking] failed to initialize persistence', {
+      err: error,
+      shipmentId,
+      tenantId,
+      organizationId,
+    })
+    throw error
+  }
+  let shipment: { tracking_number: string | null } | undefined
+  try {
+    shipment = await db
+      .selectFrom('carrier_shipments')
+      .select('tracking_number')
+      .where('id', '=', shipmentId)
+      .where('tenant_id', '=', tenantId)
+      .where('organization_id', '=', organizationId)
+      .where('deleted_at', 'is', null)
+      .executeTakeFirst()
+  } catch (error) {
+    if (isMissingReferenceTableError(error)) {
+      logger.debug('[warranty_claims:return-shipment-tracking] carrier shipment table unavailable', {
+        shipmentId,
+        tenantId,
+        organizationId,
+      })
+      return
+    }
+    logger.error('[warranty_claims:return-shipment-tracking] failed to load carrier shipment', {
+      err: error,
+      shipmentId,
+      tenantId,
+      organizationId,
+    })
+    throw error
+  }
+
+  const trackingNumber = readString(toRecord(shipment), 'tracking_number')
+  if (!shipment || !trackingNumber) {
+    logger.debug('[warranty_claims:return-shipment-tracking] shipment or tracking number not found', {
+      shipmentId,
+      tenantId,
+      organizationId,
+    })
+    return
+  }
+
+  let claims: Array<{ id: string; claim_number: string; updated_at: Date | null }>
+  try {
+    claims = await db
+      .selectFrom('warranty_claims')
+      .select(['id', 'claim_number', 'updated_at'])
+      .where('tenant_id', '=', tenantId)
+      .where('organization_id', '=', organizationId)
+      .where('deleted_at', 'is', null)
+      .where('status', '=', 'awaiting_return')
+      .where('return_tracking_number', '=', trackingNumber)
+      .limit(2)
+      .execute()
+  } catch (error) {
+    logger.error('[warranty_claims:return-shipment-tracking] failed to find matching warranty claims', {
+      err: error,
+      shipmentId,
+      tenantId,
+      organizationId,
+    })
+    throw error
+  }
+
+  if (claims.length === 0) {
+    logger.debug('[warranty_claims:return-shipment-tracking] no awaiting-return claim matched shipment', {
+      shipmentId,
+      tenantId,
+      organizationId,
+    })
+    return
+  }
+  if (claims.length > 1) {
+    logger.warn('[warranty_claims:return-shipment-tracking] multiple claims matched return shipment', {
+      shipmentId,
+      tenantId,
+      organizationId,
+      claimNumbers: claims.map((claim) => claim.claim_number),
+    })
+    return
+  }
+
+  const commandCtx: CommandRuntimeContext = {
+    container: container as unknown as AwilixContainer,
+    auth: {
+      sub: SYSTEM_USER_ID,
+      tenantId,
+      orgId: organizationId,
+    },
+    organizationScope: null,
+    selectedOrganizationId: organizationId,
+    organizationIds: [organizationId],
+    systemActor: true,
+  }
+  const input: TransitionClaimInput = {
+    id: claims[0].id,
+    toStatus: 'received',
+    systemNote: 'warranty_claims.timeline.autoReceivedFromTracking',
+  }
+
+  try {
+    const commandBus = container.resolve<CommandBus>('commandBus')
+    await commandBus.execute<TransitionClaimInput, { claimId: string }>(
+      'warranty_claims.claim.transition',
+      { input, ctx: commandCtx },
+    )
+  } catch (error) {
+    if (isInvalidTransitionError(error)) {
+      logger.debug('[warranty_claims:return-shipment-tracking] claim no longer accepts received transition', {
+        claimId: claims[0].id,
+        shipmentId,
+        tenantId,
+        organizationId,
+      })
+      return
+    }
+    logger.error('[warranty_claims:return-shipment-tracking] failed to transition matching warranty claim', {
+      err: error,
+      claimId: claims[0].id,
+      shipmentId,
+      tenantId,
+      organizationId,
+    })
+    throw error
+  }
+}

package/src/modules/warranty_claims/subscribers/vendor-recovery-reconciliation-undo.ts

@@ -0,0 +1,28 @@
+import { reconcileVendorRecoverySourceClaim } from '../commands/shared'
+
+export const metadata = {
+  event: 'warranty_claims.claim.updated',
+  persistent: true,
+  id: 'warranty_claims:vendor-recovery-reconciliation-undo',
+}
+
+type HandlerContext = {
+  resolve: <T = unknown>(name: string) => T
+  tenantId?: string | null
+  organizationId?: string | null
+}
+
+function readString(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key]
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null
+}
+
+export default async function handle(payload: unknown, ctx: HandlerContext): Promise<void> {
+  const record = payload && typeof payload === 'object' ? payload as Record<string, unknown> : {}
+  if (readString(record, 'claimType') !== 'vendor_recovery') return
+  const claimId = readString(record, 'claimId') ?? readString(record, 'id')
+  const tenantId = ctx.tenantId ?? null
+  const organizationId = ctx.organizationId ?? null
+  if (!claimId || !tenantId || !organizationId) return
+  await reconcileVendorRecoverySourceClaim(ctx, { claimId, tenantId, organizationId })
+}

package/src/modules/warranty_claims/subscribers/vendor-recovery-reconciliation.ts

@@ -0,0 +1,31 @@
+import { reconcileVendorRecoverySourceClaim } from '../commands/shared'
+
+export const metadata = {
+  event: 'warranty_claims.claim.status_changed',
+  persistent: true,
+  id: 'warranty_claims:vendor-recovery-reconciliation',
+}
+
+type HandlerContext = {
+  resolve: <T = unknown>(name: string) => T
+  tenantId?: string | null
+  organizationId?: string | null
+}
+
+function readString(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key]
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null
+}
+
+export default async function handle(payload: unknown, ctx: HandlerContext): Promise<void> {
+  const record = payload && typeof payload === 'object' ? payload as Record<string, unknown> : {}
+  const claimId = readString(record, 'claimId') ?? readString(record, 'id')
+  const tenantId = ctx.tenantId ?? null
+  const organizationId = ctx.organizationId ?? null
+  const claimType = readString(record, 'claimType')
+  const toStatus = readString(record, 'toStatus') ?? readString(record, 'status')
+  if (!claimId || !tenantId || !organizationId) return
+  if (claimType !== 'vendor_recovery' || (toStatus !== 'resolved' && toStatus !== 'closed')) return
+
+  await reconcileVendorRecoverySourceClaim(ctx, { claimId, tenantId, organizationId })
+}

package/src/modules/warranty_claims/widgets/dashboard/claims-queue/config.ts

@@ -0,0 +1,15 @@
+export type WarrantyClaimsQueueSettings = {
+  showStatusBreakdown: boolean
+}
+
+export const DEFAULT_SETTINGS: WarrantyClaimsQueueSettings = {
+  showStatusBreakdown: true,
+}
+
+export function hydrateWarrantyClaimsQueueSettings(raw: unknown): WarrantyClaimsQueueSettings {
+  if (!raw || typeof raw !== 'object') return { ...DEFAULT_SETTINGS }
+  const input = raw as Partial<WarrantyClaimsQueueSettings>
+  return {
+    showStatusBreakdown: input.showStatusBreakdown === false ? false : DEFAULT_SETTINGS.showStatusBreakdown,
+  }
+}

package/src/modules/warranty_claims/widgets/dashboard/claims-queue/widget.client.tsx

@@ -0,0 +1,237 @@
+"use client"
+
+import * as React from 'react'
+import Link from 'next/link'
+import type { DashboardWidgetComponentProps } from '@open-mercato/shared/modules/dashboard/widgets'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { Checkbox } from '@open-mercato/ui/primitives/checkbox'
+import { Spinner } from '@open-mercato/ui/primitives/spinner'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { cn } from '@open-mercato/shared/lib/utils'
+import type { WarrantyClaimsStats } from '../../../backend/components/ClaimsKpiStrip'
+import { DEFAULT_SETTINGS, hydrateWarrantyClaimsQueueSettings, type WarrantyClaimsQueueSettings } from './config'
+
+type ClaimsStatsResponse = {
+  ok?: boolean
+  result?: WarrantyClaimsStats
+  error?: string
+}
+
+const OPEN_STATUS_ORDER = [
+  'submitted',
+  'in_review',
+  'info_requested',
+  'approved',
+  'awaiting_return',
+  'received',
+  'inspecting',
+] as const
+
+const STATUS_FALLBACK_LABELS: Record<(typeof OPEN_STATUS_ORDER)[number], string> = {
+  submitted: 'Submitted',
+  in_review: 'In review',
+  info_requested: 'Info requested',
+  approved: 'Approved',
+  awaiting_return: 'Awaiting return',
+  received: 'Received',
+  inspecting: 'Inspecting',
+}
+
+const CLAIMS_LIST_PATH = '/backend/warranty_claims'
+
+function buildOpenClaimsHref(): string {
+  return `${CLAIMS_LIST_PATH}?status=${OPEN_STATUS_ORDER.join(',')}`
+}
+
+function buildOverdueHref(): string {
+  return `${CLAIMS_LIST_PATH}?overdueOnly=true`
+}
+
+function buildAtRiskHref(): string {
+  return `${CLAIMS_LIST_PATH}?slaAtRiskOnly=true`
+}
+
+function buildStatusHref(status: string): string {
+  return `${CLAIMS_LIST_PATH}?status=${encodeURIComponent(status)}`
+}
+
+async function loadClaimsStats(): Promise<WarrantyClaimsStats> {
+  const call = await apiCall<ClaimsStatsResponse>('/api/warranty_claims/stats')
+  if (!call.ok) {
+    const message = typeof call.result?.error === 'string'
+      ? call.result.error
+      : `[internal] Request failed with status ${call.status}`
+    throw new Error(message)
+  }
+  const payload = call.result
+  if (payload?.ok !== true || !payload.result) {
+    throw new Error('[internal] Malformed warranty claims stats response')
+  }
+  return payload.result
+}
+
+function formatCount(value: number): string {
+  return new Intl.NumberFormat(undefined).format(value)
+}
+
+const WarrantyClaimsQueueWidget: React.FC<DashboardWidgetComponentProps<WarrantyClaimsQueueSettings>> = ({
+  mode,
+  settings = DEFAULT_SETTINGS,
+  onSettingsChange,
+  refreshToken,
+  onRefreshStateChange,
+}) => {
+  const t = useT()
+  const hydrated = React.useMemo(() => hydrateWarrantyClaimsQueueSettings(settings), [settings])
+  const [stats, setStats] = React.useState<WarrantyClaimsStats | null>(null)
+  const [loading, setLoading] = React.useState(true)
+  const [error, setError] = React.useState<string | null>(null)
+
+  const refresh = React.useCallback(async () => {
+    onRefreshStateChange?.(true)
+    setLoading(true)
+    setError(null)
+    try {
+      const data = await loadClaimsStats()
+      setStats(data)
+    } catch {
+      setError(t('warranty_claims.widgets.queue.error', 'Failed to load warranty claims'))
+    } finally {
+      setLoading(false)
+      onRefreshStateChange?.(false)
+    }
+  }, [onRefreshStateChange, t])
+
+  React.useEffect(() => {
+    refresh().catch(() => {})
+  }, [refresh, refreshToken])
+
+  if (mode === 'settings') {
+    return (
+      <div className="space-y-4 text-sm">
+        <div className="flex items-center gap-2">
+          <Checkbox
+            id="warranty-claims-queue-show-breakdown"
+            checked={hydrated.showStatusBreakdown}
+            onCheckedChange={(checked) => {
+              onSettingsChange({ ...hydrated, showStatusBreakdown: checked === true })
+            }}
+          />
+          <label htmlFor="warranty-claims-queue-show-breakdown" className="text-sm">
+            {t('warranty_claims.widgets.queue.settings.showStatusBreakdown', 'Show status breakdown')}
+          </label>
+        </div>
+        <p className="text-xs text-muted-foreground">
+          {t(
+            'warranty_claims.widgets.queue.settings.help',
+            'Toggle the per-status rows shown under the headline counts.',
+          )}
+        </p>
+      </div>
+    )
+  }
+
+  if (error) {
+    return <p className="text-sm text-status-error-text">{error}</p>
+  }
+
+  if (loading && !stats) {
+    return (
+      <div className="flex h-32 items-center justify-center">
+        <Spinner className="h-6 w-6 text-muted-foreground" />
+      </div>
+    )
+  }
+
+  if (!stats) {
+    return <p className="text-sm text-muted-foreground">{t('warranty_claims.widgets.queue.empty', 'No open claims')}</p>
+  }
+
+  const openClaims = OPEN_STATUS_ORDER.reduce((sum, status) => sum + (stats.openByStatus[status] ?? 0), 0)
+
+  if (openClaims === 0 && stats.overdue === 0) {
+    return <p className="text-sm text-muted-foreground">{t('warranty_claims.widgets.queue.empty', 'No open claims')}</p>
+  }
+
+  const breakdown = OPEN_STATUS_ORDER
+    .map((status) => ({ status, count: stats.openByStatus[status] ?? 0 }))
+    .filter((entry) => entry.count > 0)
+
+  const atRisk = typeof stats.slaAtRisk === 'number' ? stats.slaAtRisk : null
+
+  return (
+    <div className="space-y-3">
+      <div className={cn('grid divide-x divide-border border-y border-border', atRisk !== null ? 'grid-cols-3' : 'grid-cols-2')}>
+        <Link
+          href={buildOpenClaimsHref()}
+          className="flex flex-col px-3 py-3 transition-colors hover:bg-accent"
+        >
+          <span className="text-xs text-muted-foreground">
+            {t('warranty_claims.widgets.queue.open', 'Open')}
+          </span>
+          <span className="mt-1 text-xl font-bold tabular-nums text-foreground">
+            {formatCount(openClaims)}
+          </span>
+        </Link>
+        {atRisk !== null ? (
+          <Link
+            href={buildAtRiskHref()}
+            className="flex flex-col px-3 py-3 transition-colors hover:bg-accent"
+          >
+            <span className="text-xs text-muted-foreground">
+              {t('warranty_claims.widgets.queue.atRisk', 'At risk')}
+            </span>
+            <span
+              className={cn(
+                'mt-1 text-xl font-bold tabular-nums',
+                atRisk > 0 ? 'text-status-warning-text' : 'text-foreground',
+              )}
+            >
+              {formatCount(atRisk)}
+            </span>
+          </Link>
+        ) : null}
+        <Link
+          href={buildOverdueHref()}
+          className="flex flex-col px-3 py-3 transition-colors hover:bg-accent"
+        >
+          <span className="text-xs text-muted-foreground">
+            {t('warranty_claims.kpi.overdue', 'Overdue')}
+          </span>
+          <span
+            className={cn(
+              'mt-1 text-xl font-bold tabular-nums',
+              stats.overdue > 0 ? 'text-status-error-text' : 'text-foreground',
+            )}
+          >
+            {formatCount(stats.overdue)}
+          </span>
+        </Link>
+      </div>
+      {hydrated.showStatusBreakdown && breakdown.length > 0 ? (
+        <div className="space-y-1 px-4 pb-2">
+          <p className="text-xs font-medium text-muted-foreground">
+            {t('warranty_claims.widgets.queue.byStatus', 'Open by status')}
+          </p>
+          <ul>
+            {breakdown.map(({ status, count }) => (
+              <li key={status}>
+                <Link
+                  href={buildStatusHref(status)}
+                  className="flex items-center justify-between gap-2 py-1.5 text-sm transition-colors hover:text-foreground"
+                >
+                  <span className="text-foreground">
+                    {t(`warranty_claims.status.${status}`, STATUS_FALLBACK_LABELS[status])}
+                  </span>
+                  <span className="tabular-nums text-muted-foreground">{formatCount(count)}</span>
+                </Link>
+              </li>
+            ))}
+          </ul>
+        </div>
+      ) : null}
+    </div>
+  )
+}
+
+export default WarrantyClaimsQueueWidget

package/src/modules/warranty_claims/widgets/dashboard/claims-queue/widget.ts

@@ -0,0 +1,27 @@
+import { lazyDashboardWidget, type DashboardWidgetModule } from '@open-mercato/shared/modules/dashboard/widgets'
+import { DEFAULT_SETTINGS, hydrateWarrantyClaimsQueueSettings, type WarrantyClaimsQueueSettings } from './config'
+
+const WarrantyClaimsQueueWidget = lazyDashboardWidget(() => import('./widget.client'))
+
+const widget: DashboardWidgetModule<WarrantyClaimsQueueSettings> = {
+  metadata: {
+    id: 'warranty_claims.dashboard.claimsQueue',
+    title: 'Warranty Claims Queue',
+    description: 'Shows open warranty claims and overdue counts with quick links into the claims list.',
+    features: ['dashboards.view', 'warranty_claims.claim.view'],
+    defaultSize: 'md',
+    defaultEnabled: true,
+    defaultSettings: DEFAULT_SETTINGS,
+    tags: ['warranty_claims', 'claims'],
+    category: 'warranty_claims',
+    icon: 'shield-check',
+    supportsRefresh: true,
+  },
+  Widget: WarrantyClaimsQueueWidget,
+  hydrateSettings: hydrateWarrantyClaimsQueueSettings,
+  dehydrateSettings: (settings) => ({
+    showStatusBreakdown: settings.showStatusBreakdown,
+  }),
+}
+
+export default widget