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

package/src/modules/warranty_claims/backend/components/ReturnLabelPanel.tsx

@@ -0,0 +1,292 @@
+"use client"
+
+import * as React from 'react'
+import type { TranslateFn } from '@open-mercato/shared/lib/i18n/context'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { Input } from '@open-mercato/ui/primitives/input'
+import { Label } from '@open-mercato/ui/primitives/label'
+import { StatusBadge } from '@open-mercato/ui/primitives/status-badge'
+import { Spinner } from '@open-mercato/ui/primitives/spinner'
+import { ErrorMessage } from '@open-mercato/ui/backend/detail'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
+
+type ReturnLabelClaim = {
+  id: string
+  status: string | null
+  updatedAt: string | null
+  returnLabelUrl: string | null
+  returnTrackingNumber: string | null
+  returnCarrier: string | null
+}
+
+type ReturnLabelResponse =
+  | {
+    status: 'created'
+    labelUrl: string | null
+    trackingNumber: string | null
+    carrier: string | null
+  }
+  | { status: 'notConfigured' }
+
+type MutationContext = {
+  formId: string
+  resourceKind: string
+  resourceId?: string
+  retryLastMutation: () => Promise<boolean>
+}
+
+type ReturnLabelPanelProps = {
+  claim: ReturnLabelClaim
+  canManage: boolean
+  onRefresh: () => Promise<void>
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function readErrorKey(value: unknown): string | null {
+  if (!isRecord(value)) return null
+  return typeof value.error === 'string' && value.error.trim().length ? value.error.trim() : null
+}
+
+function toApiError(status: number, result: unknown, fallbackKey: string, t: TranslateFn): Error & { status?: number } {
+  const key = readErrorKey(result) ?? fallbackKey
+  return Object.assign(new Error(t(key, key)), { status })
+}
+
+function isReturnLabelStatus(value: unknown): value is ReturnLabelResponse {
+  return isRecord(value) && (value.status === 'created' || value.status === 'notConfigured')
+}
+
+function cleanText(value: string): string | undefined {
+  const trimmed = value.trim()
+  return trimmed.length ? trimmed : undefined
+}
+
+export function ReturnLabelPanel({ claim, canManage, onRefresh }: ReturnLabelPanelProps) {
+  const t = useT()
+  const [manualVisible, setManualVisible] = React.useState(false)
+  const [autoHidden, setAutoHidden] = React.useState(false)
+  const [labelUrl, setLabelUrl] = React.useState(claim.returnLabelUrl ?? '')
+  const [trackingNumber, setTrackingNumber] = React.useState(claim.returnTrackingNumber ?? '')
+  const [carrier, setCarrier] = React.useState(claim.returnCarrier ?? '')
+  const [busy, setBusy] = React.useState<'generate' | 'manual' | null>(null)
+  const [error, setError] = React.useState<string | null>(null)
+  const { runMutation, retryLastMutation } = useGuardedMutation<MutationContext>({
+    contextId: `warranty-claim-return-label:${claim.id}`,
+    blockedMessage: t('warranty_claims.common.saveBlocked', 'Save blocked by a mutation guard.'),
+  })
+
+  React.useEffect(() => {
+    setLabelUrl(claim.returnLabelUrl ?? '')
+    setTrackingNumber(claim.returnTrackingNumber ?? '')
+    setCarrier(claim.returnCarrier ?? '')
+  }, [claim.returnCarrier, claim.returnLabelUrl, claim.returnTrackingNumber])
+
+  if (claim.status !== 'approved' && claim.status !== 'awaiting_return') return null
+
+  const hasLabel = Boolean(claim.returnLabelUrl || claim.returnTrackingNumber || claim.returnCarrier)
+
+  const runReturnLabelMutation = async (
+    payload: Record<string, unknown>,
+    mode: 'generate' | 'manual',
+  ): Promise<ReturnLabelResponse | null> => {
+    setBusy(mode)
+    setError(null)
+    try {
+      const result = await runMutation({
+        operation: async () => {
+          const call = await withScopedApiRequestHeaders(
+            buildOptimisticLockHeader(claim.updatedAt),
+            () => apiCall<ReturnLabelResponse>('/api/warranty_claims/return-label', {
+              method: 'POST',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify({ ...payload, updatedAt: claim.updatedAt }),
+            }),
+          )
+          if (!call.ok) throw toApiError(call.status, call.result, 'warranty_claims.returnLabel.error.save', t)
+          if (!isReturnLabelStatus(call.result)) {
+            throw new Error(t('warranty_claims.returnLabel.error.save', 'Failed to save return label.'))
+          }
+          return call.result
+        },
+        context: {
+          formId: `warranty-claim-return-label:${claim.id}`,
+          resourceKind: 'warranty_claims.claim',
+          resourceId: claim.id,
+          retryLastMutation,
+        },
+        mutationPayload: payload,
+      })
+      return result
+    } catch (err) {
+      if (surfaceRecordConflict(err, t, { onRefresh })) return null
+      const message = err instanceof Error && err.message
+        ? err.message
+        : t('warranty_claims.returnLabel.error.save', 'Failed to save return label.')
+      setError(message)
+      flash(message, 'error')
+      return null
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  const generateLabel = async () => {
+    const result = await runReturnLabelMutation({ claimId: claim.id }, 'generate')
+    if (!result) return
+    if (result.status === 'notConfigured') {
+      setAutoHidden(true)
+      setManualVisible(true)
+      flash(t('warranty_claims.returnLabel.flash.notConfigured', 'No return label provider is configured. Enter label details manually.'), 'info')
+      return
+    }
+    flash(t('warranty_claims.returnLabel.flash.created', 'Return label created.'), 'success')
+    await onRefresh()
+  }
+
+  const submitManual = async () => {
+    const payload = {
+      claimId: claim.id,
+      manual: true,
+      labelUrl: cleanText(labelUrl),
+      trackingNumber: cleanText(trackingNumber),
+      carrier: cleanText(carrier),
+    }
+    if (!payload.labelUrl && !payload.trackingNumber && !payload.carrier) {
+      const message = t('warranty_claims.returnLabel.error.manualRequired', 'Enter at least one return label detail.')
+      setError(message)
+      flash(message, 'error')
+      return
+    }
+    const result = await runReturnLabelMutation(payload, 'manual')
+    if (!result || result.status !== 'created') return
+    setManualVisible(false)
+    flash(t('warranty_claims.returnLabel.flash.saved', 'Return label details saved.'), 'success')
+    await onRefresh()
+  }
+
+  return (
+    <div className="rounded-lg border border-border bg-card p-4 shadow-sm">
+      <div className="flex flex-wrap items-start justify-between gap-3">
+        <div>
+          <h3 className="text-sm font-semibold">{t('warranty_claims.returnLabel.title', 'Return label')}</h3>
+          <p className="text-xs text-muted-foreground">
+            {t('warranty_claims.returnLabel.description', 'Generate or record customer return shipping details.')}
+          </p>
+        </div>
+        {hasLabel ? (
+          <StatusBadge variant="success">{t('warranty_claims.returnLabel.status.created', 'Label recorded')}</StatusBadge>
+        ) : (
+          <StatusBadge variant="neutral">{t('warranty_claims.returnLabel.status.missing', 'No label')}</StatusBadge>
+        )}
+      </div>
+
+      {error ? (
+        <div className="mt-3">
+          <ErrorMessage label={error} />
+        </div>
+      ) : null}
+
+      {hasLabel ? (
+        <div className="mt-3 grid gap-3 sm:grid-cols-3">
+          <div className="rounded-md border border-border p-3">
+            <div className="text-xs text-muted-foreground">{t('warranty_claims.returnLabel.fields.carrier', 'Carrier')}</div>
+            <div className="text-sm font-medium">{claim.returnCarrier ?? t('warranty_claims.common.noValue', 'No value')}</div>
+          </div>
+          <div className="rounded-md border border-border p-3">
+            <div className="text-xs text-muted-foreground">{t('warranty_claims.returnLabel.fields.trackingNumber', 'Tracking number')}</div>
+            <div className="text-sm font-medium">{claim.returnTrackingNumber ?? t('warranty_claims.common.noValue', 'No value')}</div>
+          </div>
+          <div className="rounded-md border border-border p-3">
+            <div className="text-xs text-muted-foreground">{t('warranty_claims.returnLabel.fields.labelUrl', 'Label')}</div>
+            {claim.returnLabelUrl ? (
+              <a
+                href={claim.returnLabelUrl}
+                target="_blank"
+                rel="noreferrer"
+                className="text-sm font-medium text-foreground underline-offset-4 hover:underline"
+              >
+                {t('warranty_claims.returnLabel.actions.openLabel', 'Open label')}
+              </a>
+            ) : (
+              <div className="text-sm font-medium">{t('warranty_claims.common.noValue', 'No value')}</div>
+            )}
+          </div>
+        </div>
+      ) : null}
+
+      {canManage ? (
+        <div className="mt-4 flex flex-wrap items-center gap-2">
+          {!autoHidden ? (
+            <Button type="button" variant="outline" disabled={busy !== null} onClick={() => { void generateLabel() }}>
+              {busy === 'generate' ? <Spinner size="sm" /> : null}
+              {t('warranty_claims.returnLabel.actions.generate', 'Generate return label')}
+            </Button>
+          ) : null}
+          <Button type="button" variant="outline" disabled={busy !== null} onClick={() => setManualVisible((value) => !value)}>
+            {manualVisible
+              ? t('warranty_claims.returnLabel.actions.hideManual', 'Hide manual entry')
+              : t('warranty_claims.returnLabel.actions.manual', 'Enter manually')}
+          </Button>
+        </div>
+      ) : null}
+
+      {canManage && manualVisible ? (
+        <div
+          className="mt-4 grid gap-3 sm:grid-cols-3"
+          onKeyDown={(event) => {
+            if ((event.metaKey || event.ctrlKey) && event.key === 'Enter') {
+              event.preventDefault()
+              void submitManual()
+            }
+            if (event.key === 'Escape') {
+              event.preventDefault()
+              setManualVisible(false)
+            }
+          }}
+        >
+          <div className="space-y-2">
+            <Label htmlFor="warranty-return-label-url">{t('warranty_claims.returnLabel.fields.labelUrl', 'Label URL')}</Label>
+            <Input
+              id="warranty-return-label-url"
+              value={labelUrl}
+              onChange={(event) => setLabelUrl(event.target.value)}
+            />
+          </div>
+          <div className="space-y-2">
+            <Label htmlFor="warranty-return-tracking-number">{t('warranty_claims.returnLabel.fields.trackingNumber', 'Tracking number')}</Label>
+            <Input
+              id="warranty-return-tracking-number"
+              value={trackingNumber}
+              onChange={(event) => setTrackingNumber(event.target.value)}
+            />
+          </div>
+          <div className="space-y-2">
+            <Label htmlFor="warranty-return-carrier">{t('warranty_claims.returnLabel.fields.carrier', 'Carrier')}</Label>
+            <Input
+              id="warranty-return-carrier"
+              value={carrier}
+              onChange={(event) => setCarrier(event.target.value)}
+            />
+          </div>
+          <div className="flex flex-wrap items-center gap-2 sm:col-span-3">
+            <Button type="button" disabled={busy !== null} onClick={() => { void submitManual() }}>
+              {busy === 'manual' ? <Spinner size="sm" /> : null}
+              {t('warranty_claims.returnLabel.actions.saveManual', 'Save return label')}
+            </Button>
+            <Button type="button" variant="outline" onClick={() => setManualVisible(false)}>
+              {t('common.cancel', 'Cancel')}
+            </Button>
+          </div>
+        </div>
+      ) : null}
+    </div>
+  )
+}

package/src/modules/warranty_claims/backend/components/TroubleshootingWalker.tsx

@@ -0,0 +1,125 @@
+"use client"
+
+import * as React from 'react'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import {
+  walkGuide,
+  type TroubleshootingNode,
+} from '../../lib/troubleshooting'
+
+export type TroubleshootingWalkerGuide = {
+  title: string
+  steps: TroubleshootingNode | null
+}
+
+export type TroubleshootingWalkerProps = {
+  guide: TroubleshootingWalkerGuide | null
+  onResolve?: (result: { resolution?: string; reasonCode?: string }) => void
+  onTraversedPathChange?: (path: number[]) => void
+}
+
+export function TroubleshootingWalker({
+  guide,
+  onResolve,
+  onTraversedPathChange,
+}: TroubleshootingWalkerProps) {
+  const t = useT()
+  const root = guide?.steps ?? null
+  const [path, setPath] = React.useState<number[]>([])
+  const state = React.useMemo(() => walkGuide(root, path), [path, root])
+  const onTraversedPathChangeRef = React.useRef(onTraversedPathChange)
+
+  React.useEffect(() => {
+    onTraversedPathChangeRef.current = onTraversedPathChange
+  }, [onTraversedPathChange])
+
+  React.useEffect(() => {
+    setPath([])
+    onTraversedPathChangeRef.current?.([])
+  }, [guide?.title, root])
+
+  const chooseOption = React.useCallback((optionIndex: number) => {
+    const nextPath = [...path, optionIndex]
+    const nextState = walkGuide(root, nextPath)
+    setPath(nextPath)
+    onTraversedPathChange?.(nextPath)
+    if (nextState.terminal) onResolve?.(nextState.terminal)
+  }, [onResolve, onTraversedPathChange, path, root])
+
+  const reset = React.useCallback(() => {
+    setPath([])
+    onTraversedPathChange?.([])
+  }, [onTraversedPathChange])
+
+  if (!guide || !root) {
+    return (
+      <div className="space-y-2">
+        <p className="text-sm font-medium text-foreground">
+          {t('warranty_claims.troubleshootingWalker.empty.title', 'No troubleshooting guide')}
+        </p>
+        <p className="text-sm text-muted-foreground">
+          {t('warranty_claims.troubleshootingWalker.empty.description', 'No matching guided steps are configured for this claim.')}
+        </p>
+      </div>
+    )
+  }
+
+  if (state.terminal) {
+    return (
+      <div className="space-y-4">
+        <div className="space-y-2">
+          <p className="text-sm font-medium text-foreground">{guide.title}</p>
+          {state.terminal.resolution ? (
+            <p className="text-sm text-foreground">{state.terminal.resolution}</p>
+          ) : null}
+          {state.terminal.reasonCode ? (
+            <p className="text-xs text-muted-foreground">
+              {t('warranty_claims.troubleshootingWalker.result.reasonCode', 'Reason code: {code}', { code: state.terminal.reasonCode })}
+            </p>
+          ) : null}
+        </div>
+        <Button type="button" variant="outline" onClick={reset}>
+          {t('warranty_claims.troubleshootingWalker.actions.restart', 'Restart')}
+        </Button>
+      </div>
+    )
+  }
+
+  if (!state.node) {
+    return (
+      <div className="space-y-4">
+        <p className="text-sm text-muted-foreground">
+          {t('warranty_claims.troubleshootingWalker.invalidPath', 'This troubleshooting path is no longer available.')}
+        </p>
+        <Button type="button" variant="outline" onClick={reset}>
+          {t('warranty_claims.troubleshootingWalker.actions.restart', 'Restart')}
+        </Button>
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="space-y-1">
+        <p className="text-sm font-medium text-foreground">{guide.title}</p>
+        <p className="text-sm text-muted-foreground">{state.node.prompt}</p>
+      </div>
+      <div className="grid gap-2">
+        {state.node.options.map((option, index) => (
+          <Button
+            key={`${index}-${option.label}`}
+            type="button"
+            variant="outline"
+            className="justify-start text-left"
+            onClick={() => chooseOption(index)}
+          >
+            {option.label}
+          </Button>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+export default TroubleshootingWalker

package/src/modules/warranty_claims/backend/components/VendorRecoverySuggestionsPanel.tsx

@@ -0,0 +1,217 @@
+"use client"
+
+import * as React from 'react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { StatusBadge } from '@open-mercato/ui/primitives/status-badge'
+import { Spinner } from '@open-mercato/ui/primitives/spinner'
+import { ErrorMessage } from '@open-mercato/ui/backend/detail'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+
+type VendorRecoveryClaim = {
+  id: string
+  claimType: string | null
+  status: string | null
+}
+
+type VendorRecoverySuggestion = {
+  lineId: string
+  lineNo: number
+  productName: string | null
+  sku: string | null
+  vendorName: string
+  policyId: string
+  recoveryRatePct: string | null
+  causalFault: string | null
+  estimatedRecovery: string | null
+}
+
+type SuggestionsResponse = {
+  ok?: boolean
+  result?: {
+    claimId?: string
+    suggestions?: VendorRecoverySuggestion[]
+  }
+}
+
+type SuggestionGroup = {
+  id: string
+  vendorName: string
+  suggestions: VendorRecoverySuggestion[]
+}
+
+type VendorRecoverySuggestionsPanelProps = {
+  claim: VendorRecoveryClaim
+  canManage: boolean
+  onGenerateSupplierRecovery: (input: { lineIds: string[]; vendorName: string }) => Promise<void>
+}
+
+function groupSuggestions(suggestions: VendorRecoverySuggestion[]): SuggestionGroup[] {
+  const byVendor = new Map<string, SuggestionGroup>()
+  for (const suggestion of suggestions) {
+    const key = suggestion.vendorName.trim()
+    if (!key) continue
+    const current = byVendor.get(key)
+    if (current) {
+      current.suggestions.push(suggestion)
+      continue
+    }
+    byVendor.set(key, {
+      id: key,
+      vendorName: key,
+      suggestions: [suggestion],
+    })
+  }
+  return Array.from(byVendor.values())
+}
+
+export function VendorRecoverySuggestionsPanel({
+  claim,
+  canManage,
+  onGenerateSupplierRecovery,
+}: VendorRecoverySuggestionsPanelProps) {
+  const t = useT()
+  const [suggestions, setSuggestions] = React.useState<VendorRecoverySuggestion[]>([])
+  const [loading, setLoading] = React.useState(false)
+  const [error, setError] = React.useState<string | null>(null)
+  const [generatingVendor, setGeneratingVendor] = React.useState<string | null>(null)
+
+  const eligible = canManage
+    && claim.claimType === 'warranty'
+    && (claim.status === 'resolved' || claim.status === 'closed')
+
+  React.useEffect(() => {
+    if (!eligible) {
+      setSuggestions([])
+      setError(null)
+      return
+    }
+    let cancelled = false
+    setLoading(true)
+    setError(null)
+    readApiResultOrThrow<SuggestionsResponse>(
+      `/api/warranty_claims/vendor-recovery-suggestions?claimId=${encodeURIComponent(claim.id)}`,
+      undefined,
+      {
+        fallback: { ok: true, result: { claimId: claim.id, suggestions: [] } },
+        errorMessage: t('warranty_claims.vendorRecoverySuggestions.error.load', 'Failed to load supplier recovery suggestions.'),
+      },
+    )
+      .then((payload) => {
+        if (cancelled) return
+        setSuggestions(Array.isArray(payload.result?.suggestions) ? payload.result.suggestions : [])
+      })
+      .catch((err) => {
+        if (cancelled) return
+        const message = err instanceof Error && err.message
+          ? err.message
+          : t('warranty_claims.vendorRecoverySuggestions.error.load', 'Failed to load supplier recovery suggestions.')
+        setError(message)
+        flash(message, 'error')
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [claim.id, eligible, t])
+
+  if (!eligible) return null
+
+  const groups = groupSuggestions(suggestions)
+
+  if (loading) {
+    return (
+      <div className="rounded-lg border border-border bg-card p-4 shadow-sm">
+        <div className="flex items-center gap-2 text-sm text-muted-foreground">
+          <Spinner size="sm" />
+          {t('warranty_claims.vendorRecoverySuggestions.loading', 'Loading supplier recovery suggestions...')}
+        </div>
+      </div>
+    )
+  }
+
+  if (error) {
+    return (
+      <div className="rounded-lg border border-border bg-card p-4 shadow-sm">
+        <ErrorMessage label={error} />
+      </div>
+    )
+  }
+
+  if (!groups.length) return null
+
+  return (
+    <div className="rounded-lg border border-border bg-card p-4 shadow-sm">
+      <div className="flex flex-wrap items-start justify-between gap-3">
+        <div>
+          <h3 className="text-sm font-semibold">
+            {t('warranty_claims.vendorRecoverySuggestions.title', 'Supplier recovery suggestions')}
+          </h3>
+          <p className="text-xs text-muted-foreground">
+            {t('warranty_claims.vendorRecoverySuggestions.description', 'Resolved warranty lines match active supplier recovery policies.')}
+          </p>
+        </div>
+        <StatusBadge variant="info">
+          {t('warranty_claims.vendorRecoverySuggestions.count', '{count} suggested', { count: suggestions.length })}
+        </StatusBadge>
+      </div>
+      <div className="mt-3 space-y-3">
+        {groups.map((group) => (
+          <div key={group.id} className="rounded-md border border-border p-3">
+            <div className="flex flex-wrap items-start justify-between gap-3">
+              <div className="min-w-0">
+                <div className="text-sm font-medium">{group.vendorName}</div>
+                <div className="mt-2 space-y-2">
+                  {group.suggestions.map((suggestion) => (
+                    <div key={`${suggestion.policyId}:${suggestion.lineId}`} className="text-xs text-muted-foreground">
+                      <span className="font-medium text-foreground">
+                        {suggestion.productName ?? suggestion.sku
+                          ? `#${suggestion.lineNo} — ${suggestion.productName ?? suggestion.sku}`
+                          : t('warranty_claims.vendorRecoverySuggestions.lineFallback', 'Line {lineNo}', { lineNo: suggestion.lineNo })}
+                      </span>
+                      {suggestion.causalFault ? (
+                        <span>
+                          {' '}
+                          {t('warranty_claims.vendorRecoverySuggestions.causalFault', 'Fault: {fault}', {
+                            fault: suggestion.causalFault,
+                          })}
+                        </span>
+                      ) : null}
+                      {suggestion.estimatedRecovery ? (
+                        <span>
+                          {' '}
+                          {t('warranty_claims.vendorRecoverySuggestions.estimatedRecovery', 'Estimated recovery: {amount}', {
+                            amount: suggestion.estimatedRecovery,
+                          })}
+                        </span>
+                      ) : null}
+                    </div>
+                  ))}
+                </div>
+              </div>
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                disabled={generatingVendor !== null}
+                onClick={() => {
+                  setGeneratingVendor(group.vendorName)
+                  void onGenerateSupplierRecovery({
+                    lineIds: group.suggestions.map((suggestion) => suggestion.lineId),
+                    vendorName: group.vendorName,
+                  }).finally(() => setGeneratingVendor(null))
+                }}
+              >
+                {generatingVendor === group.vendorName ? <Spinner size="sm" /> : null}
+                {t('warranty_claims.vendorRecoverySuggestions.actions.generate', 'Generate supplier recovery')}
+              </Button>
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}