@open-mercato/core 0.6.6-develop.6205.1.109e4b6a84 → 0.6.6-develop.6227.1.2695efff30

package/src/modules/shipping_carriers/api/tracking/refresh/route.ts

@@ -0,0 +1,53 @@
+import { NextResponse } from 'next/server'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import type { ShippingCarrierService } from '../../../lib/shipping-service'
+import { trackingRefreshSchema } from '../../../data/validators'
+import { shippingCarriersTag } from '../../openapi'
+
+export const metadata = {
+  path: '/shipping-carriers/tracking/refresh',
+  POST: { requireAuth: true, requireFeatures: ['shipping_carriers.manage'] },
+}
+
+export async function POST(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+  const payload = await readJsonSafe<unknown>(req)
+  const parsed = trackingRefreshSchema.safeParse(payload)
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 422 })
+  }
+  const container = await createRequestContainer()
+  const service = container.resolve('shippingCarrierService') as ShippingCarrierService
+  try {
+    const tracking = await service.refreshTracking({
+      ...parsed.data,
+      organizationId: auth.orgId as string,
+      tenantId: auth.tenantId,
+    })
+    return NextResponse.json(tracking)
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : 'Failed to refresh tracking'
+    return NextResponse.json({ error: message }, { status: 502 })
+  }
+}
+
+export const openApi = {
+  tags: [shippingCarriersTag],
+  summary: 'Refresh tracking',
+  methods: {
+    POST: {
+      summary: 'Refresh tracking and persist the latest shipment status',
+      tags: [shippingCarriersTag],
+      responses: [
+        { status: 200, description: 'Tracking refreshed and shipment status persisted' },
+        { status: 422, description: 'Validation failed' },
+        { status: 502, description: 'Provider upstream error' },
+      ],
+    },
+  },
+}

package/src/modules/shipping_carriers/data/validators.ts

@@ -55,6 +55,11 @@ export const trackingQuerySchema = z.object({
   path: ['shipmentId'],
 })
 
+export const trackingRefreshSchema = z.object({
+  providerKey: z.string().min(1),
+  shipmentId: z.string().uuid(),
+})
+
 export const cancelShipmentSchema = z.object({
   providerKey: z.string().min(1),
   shipmentId: z.string().uuid(),

package/src/modules/shipping_carriers/lib/shipment-wizard/hooks/useShipmentWizard.ts

@@ -1,6 +1,7 @@
 import * as React from 'react'
 import { useRouter, useSearchParams } from 'next/navigation'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import {
   fetchProviders,
@@ -9,6 +10,7 @@ import {
   createShipment,
   fetchDropOffPoints,
 } from './shipmentApi'
+import type { CreateShipmentParams } from './shipmentApi'
 import type {
   WizardStep,
   Provider,
@@ -105,6 +107,9 @@ export const useShipmentWizard = (): ShipmentWizard => {
   const t = useT()
   const router = useRouter()
   const searchParams = useSearchParams()
+  const { runMutation, retryLastMutation } = useGuardedMutation({
+    contextId: 'shipping_carriers.shipment.create',
+  })
   const orderId = searchParams?.get('orderId') ?? null
 
   const [step, setStep] = React.useState<WizardStep>('provider')
@@ -192,7 +197,7 @@ export const useShipmentWizard = (): ShipmentWizard => {
   const handleSubmit = async () => {
     if (!selectedProvider || !selectedRate || !orderId) return
     setIsSubmitting(true)
-    const result = await createShipment({
+    const payload: CreateShipmentParams = {
       providerKey: selectedProvider,
       orderId,
       origin,
@@ -206,13 +211,29 @@ export const useShipmentWizard = (): ShipmentWizard => {
       ...(receiverContact.email ? { receiverEmail: receiverContact.email } : {}),
       ...(targetPoint ? { targetPoint } : {}),
       ...(c2cSendingMethod ? { c2cSendingMethod } : {}),
-    })
-    setIsSubmitting(false)
-    if (result.ok) {
-      flash(t('shipping_carriers.create.success', 'Shipment created successfully.'), 'success')
-      router.push(backHref)
-    } else {
-      flash(t('shipping_carriers.create.error.create', result.error), 'error')
+    }
+    try {
+      const result = await runMutation({
+        operation: () => createShipment(payload),
+        context: {
+          operation: 'create',
+          resourceKind: 'shipping_carriers.shipment',
+          resourceId: orderId,
+          retryLastMutation,
+        },
+        mutationPayload: payload as unknown as Record<string, unknown>,
+      })
+      if (result.ok) {
+        flash(t('shipping_carriers.create.success', 'Shipment created successfully.'), 'success')
+        router.push(backHref)
+      } else {
+        flash(t('shipping_carriers.create.error.create', result.error), 'error')
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : t('shipping_carriers.create.error.create', 'Failed to create shipment.')
+      flash(t('shipping_carriers.create.error.create', message), 'error')
+    } finally {
+      setIsSubmitting(false)
     }
   }
 

package/src/modules/shipping_carriers/lib/shipping-service.ts

@@ -5,7 +5,13 @@ import { CarrierShipment } from '../data/entities'
 import { emitShippingEvent } from '../events'
 import { getShippingAdapter } from './adapter-registry'
 import type { UnifiedShipmentStatus } from './adapter'
-import { isValidShippingTransition, ShipmentCancelNotAllowedError } from './status-sync'
+import {
+  getTerminalShippingEvent,
+  isValidShippingTransition,
+  ShipmentCancelNotAllowedError,
+  syncShipmentStatus,
+  TERMINAL_SHIPPING_STATUSES,
+} from './status-sync'
 
 export function createShippingCarrierService(deps: {
   em: EntityManager
@@ -160,16 +166,46 @@ export function createShippingCarrierService(deps: {
           },
         )
         : null
-      const tracking = await adapter.getTracking({
+      return adapter.getTracking({
         shipmentId: shipment?.carrierShipmentId ?? input.shipmentId,
         trackingNumber: input.trackingNumber ?? shipment?.trackingNumber,
         credentials,
       })
-      if (shipment) {
-        shipment.unifiedStatus = tracking.status
-        shipment.trackingEvents = tracking.events
-        shipment.lastPolledAt = new Date()
-        await em.flush()
+    },
+
+    async refreshTracking(input: {
+      providerKey: string
+      shipmentId: string
+      organizationId: string
+      tenantId: string
+    }) {
+      const scope = { organizationId: input.organizationId, tenantId: input.tenantId }
+      const shipment = await findShipmentOrThrow(input.shipmentId, scope)
+      const { adapter, credentials } = await resolveAdapter(input.providerKey, scope)
+      const tracking = await adapter.getTracking({
+        shipmentId: shipment.carrierShipmentId,
+        trackingNumber: shipment.trackingNumber,
+        credentials,
+      })
+      const previousStatus = shipment.unifiedStatus
+      shipment.trackingEvents = tracking.events
+      shipment.lastPolledAt = new Date()
+      const transitionApplied = syncShipmentStatus(shipment, tracking.status)
+      await em.flush()
+      if (transitionApplied) {
+        const eventPayload = {
+          shipmentId: shipment.id,
+          providerKey: input.providerKey,
+          previousStatus,
+          newStatus: tracking.status,
+          organizationId: input.organizationId,
+          tenantId: input.tenantId,
+        }
+        await emitShippingEvent('shipping_carriers.shipment.status_changed', eventPayload)
+        if (TERMINAL_SHIPPING_STATUSES.has(tracking.status)) {
+          const terminalEvent = getTerminalShippingEvent(tracking.status)
+          if (terminalEvent) await emitShippingEvent(terminalEvent, eventPayload)
+        }
       }
       return tracking
     },

package/src/modules/shipping_carriers/workers/status-poller.ts

@@ -23,7 +23,7 @@ export const metadata: WorkerMeta = {
 export default async function handle(job: QueuedJob<PollerJobPayload>, ctx: HandlerContext): Promise<void> {
   const service = ctx.resolve<ShippingCarrierService>('shippingCarrierService')
   for (const shipmentId of job.payload.shipmentIds) {
-    await service.getTracking({
+    await service.refreshTracking({
       providerKey: job.payload.providerKey,
       shipmentId,
       organizationId: job.payload.scope.organizationId,

package/src/modules/translations/components/TranslationManager.tsx

@@ -9,6 +9,7 @@ import { LoadingMessage, ErrorMessage } from '@open-mercato/ui/backend/detail'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { useCustomFieldDefs } from '@open-mercato/ui/backend/utils/customFieldDefs'
 import { Save, Plus, X } from 'lucide-react'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
@@ -19,6 +20,9 @@ import { formatEntityLabel, buildEntityListUrl, getRecordLabel, resolveBaseValue
 import { resolveFieldList } from '../lib/resolve-field-list'
 import type { ResolvedField } from '../lib/resolve-field-list'
 
+const TRANSLATION_MUTATION_CONTEXT_ID = 'translations.entity-translations'
+const SUPPORTED_LOCALES_MUTATION_CONTEXT_ID = 'translations.supported-locales'
+
 type TranslationManagerProps = {
   entityType?: string
   recordId?: string
@@ -218,6 +222,16 @@ export function TranslationManager({
     }
   }, [translationSignature, translationData])
 
+  const { runMutation, retryLastMutation } = useGuardedMutation<{
+    formId: string
+    entityType: string
+    recordId: string
+    resourceKind: string
+    resourceId: string
+    data: TranslationsResponse | null
+    retryLastMutation: () => Promise<boolean>
+  }>({ contextId: TRANSLATION_MUTATION_CONTEXT_ID })
+
   const mutation = useMutation({
     mutationFn: async () => {
       if (!entityType || !recordId) {
@@ -239,21 +253,35 @@ export function TranslationManager({
         console.warn('[translations] Save skipped: payload is empty — no locale contains any non-empty field')
         throw new Error(t('translations.manager.errors.nothingToSave', 'Nothing to save — enter a translation first'))
       }
-      const res = await withScopedApiRequestHeaders(
-        buildOptimisticLockHeader(translationData?.updatedAt),
-        () => apiCall(
-          `/api/translations/${encodeURIComponent(entityType)}/${encodeURIComponent(recordId)}`,
-          {
-            method: 'PUT',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify(body),
-          },
-        ),
-      )
-      if (!res.ok) {
-        throw new Error(t('translations.manager.errors.save', 'Failed to save translations'))
-      }
-      return true
+      return runMutation({
+        operation: async () => {
+          const res = await withScopedApiRequestHeaders(
+            buildOptimisticLockHeader(translationData?.updatedAt),
+            () => apiCall(
+              `/api/translations/${encodeURIComponent(entityType)}/${encodeURIComponent(recordId)}`,
+              {
+                method: 'PUT',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+              },
+            ),
+          )
+          if (!res.ok) {
+            throw new Error(t('translations.manager.errors.save', 'Failed to save translations'))
+          }
+          return true
+        },
+        context: {
+          formId: TRANSLATION_MUTATION_CONTEXT_ID,
+          entityType,
+          recordId,
+          resourceKind: 'translation',
+          resourceId: recordId,
+          data: translationData ?? null,
+          retryLastMutation,
+        },
+        mutationPayload: body,
+      })
     },
     onSuccess: () => {
       flash(t('translations.manager.flash.saved', 'Translations saved'), 'success')
@@ -541,16 +569,32 @@ export function LocaleManager() {
   const { data: locales = [], isLoading } = useTranslationLocales()
   const [newLocale, setNewLocale] = React.useState('')
 
+  const { runMutation, retryLastMutation } = useGuardedMutation<{
+    formId: string
+    resourceKind: string
+    retryLastMutation: () => Promise<boolean>
+  }>({ contextId: SUPPORTED_LOCALES_MUTATION_CONTEXT_ID })
+
   const mutation = useMutation({
     mutationFn: async (updatedLocales: string[]) => {
       // optimistic-lock-exempt: single-row tenant supported-locales settings list — no per-record version / concurrent record edit
-      const res = await apiCall<{ locales: string[] }>('/api/translations/locales', {
-        method: 'PUT',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ locales: updatedLocales }),
+      return runMutation({
+        operation: async () => {
+          const res = await apiCall<{ locales: string[] }>('/api/translations/locales', {
+            method: 'PUT',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ locales: updatedLocales }),
+          })
+          if (!res.ok) throw new Error('Failed to save locales')
+          return res.result?.locales ?? updatedLocales
+        },
+        context: {
+          formId: SUPPORTED_LOCALES_MUTATION_CONTEXT_ID,
+          resourceKind: 'translation-locales',
+          retryLastMutation,
+        },
+        mutationPayload: { locales: updatedLocales },
       })
-      if (!res.ok) throw new Error('Failed to save locales')
-      return res.result?.locales ?? updatedLocales
     },
     onSuccess: (result) => {
       queryClient.setQueryData(['translation-locales'], result)