@open-mercato/core 0.6.6-develop.6257.1.6d0af84d26 → 0.6.6-develop.6286.1.d985c5c374

package/src/modules/shipping_carriers/api/shipments/route.ts

@@ -7,6 +7,7 @@ import {
   validateCrudMutationGuard,
 } from '@open-mercato/shared/lib/crud/mutation-guard'
 import type { ShippingCarrierService } from '../../lib/shipping-service'
+import { isShipmentIdempotencyConflictError } from '../../lib/shipment-idempotency'
 import { createShipmentSchema } from '../../data/validators'
 import { shippingCarriersTag } from '../openapi'
 
@@ -83,6 +84,12 @@ export async function POST(req: Request) {
       labelUrl: shipment.labelUrl,
     }, { status: 201 })
   } catch (error: unknown) {
+    if (isShipmentIdempotencyConflictError(error)) {
+      return NextResponse.json(
+        { error: 'Shipment idempotency conflict', code: 'idempotency_conflict' },
+        { status: 409 },
+      )
+    }
     const message = error instanceof Error ? error.message : 'Failed to create shipment'
     return NextResponse.json({ error: message }, { status: 502 })
   }
@@ -97,6 +104,7 @@ export const openApi = {
       tags: [shippingCarriersTag],
       responses: [
         { status: 201, description: 'Shipment created' },
+        { status: 409, description: 'Idempotency conflict: the idempotency key was reused with a different payload' },
         { status: 422, description: 'Validation failed' },
         { status: 502, description: 'Provider upstream error' },
       ],

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

@@ -89,3 +89,36 @@ export class CarrierWebhookProcessedEvent {
   @Property({ name: 'processed_at', type: Date, onCreate: () => new Date() })
   processedAt: Date = new Date()
 }
+
+@Entity({ tableName: 'carrier_shipment_idempotency_keys' })
+@Unique({
+  name: 'carrier_shipment_idempotency_keys_unique',
+  properties: ['idempotencyKey', 'providerKey', 'organizationId', 'tenantId'],
+})
+export class CarrierShipmentIdempotencyKey {
+  [OptionalProps]?: 'shipmentId' | 'createdAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'provider_key', type: 'text' })
+  providerKey!: string
+
+  @Property({ name: 'idempotency_key', type: 'text' })
+  idempotencyKey!: string
+
+  @Property({ name: 'request_hash', type: 'text' })
+  requestHash!: string
+
+  @Property({ name: 'shipment_id', type: 'uuid', nullable: true })
+  shipmentId?: string | null
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+}

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

@@ -44,6 +44,7 @@ export const createShipmentSchema = z.object({
   receiverEmail: emailField,
   targetPoint: z.string().optional(),
   c2cSendingMethod: z.enum(['parcel_locker', 'dispatch_order', 'pop', 'any_point']).optional(),
+  idempotencyKey: z.string().min(1).max(255).optional(),
 })
 
 export const trackingQuerySchema = z.object({

package/src/modules/shipping_carriers/i18n/de.json

@@ -14,6 +14,7 @@
   "shipping_carriers.create.error.create": "Sendung konnte nicht erstellt werden.",
   "shipping_carriers.create.error.fetchDropOffPoints": "Abgabepunkte konnten nicht abgerufen werden.",
   "shipping_carriers.create.error.fetchRates": "Preise konnten nicht abgerufen werden.",
+  "shipping_carriers.create.error.idempotencyConflict": "Diese Sendung wurde bereits übermittelt. Aktualisieren Sie die Seite, bevor Sie es erneut versuchen.",
   "shipping_carriers.create.error.invalidEmail": "Ungültige E-Mail-Adresse.",
   "shipping_carriers.create.error.invalidPhone": "Ungültige Telefonnummer.",
   "shipping_carriers.create.error.loadProviders": "Transporteure konnten nicht geladen werden.",

package/src/modules/shipping_carriers/i18n/en.json

@@ -14,6 +14,7 @@
   "shipping_carriers.create.error.create": "Failed to create shipment.",
   "shipping_carriers.create.error.fetchDropOffPoints": "Failed to fetch drop-off points.",
   "shipping_carriers.create.error.fetchRates": "Failed to fetch shipping rates.",
+  "shipping_carriers.create.error.idempotencyConflict": "This shipment was already submitted. Refresh the page before retrying.",
   "shipping_carriers.create.error.invalidEmail": "Invalid email address.",
   "shipping_carriers.create.error.invalidPhone": "Invalid phone number.",
   "shipping_carriers.create.error.loadProviders": "Failed to load shipping providers.",

package/src/modules/shipping_carriers/i18n/es.json

@@ -14,6 +14,7 @@
   "shipping_carriers.create.error.create": "Error al crear el envio.",
   "shipping_carriers.create.error.fetchDropOffPoints": "Error al obtener los puntos de entrega.",
   "shipping_carriers.create.error.fetchRates": "Error al obtener las tarifas.",
+  "shipping_carriers.create.error.idempotencyConflict": "Este envío ya fue enviado. Actualiza la página antes de volver a intentarlo.",
   "shipping_carriers.create.error.invalidEmail": "Dirección de correo electrónico no válida.",
   "shipping_carriers.create.error.invalidPhone": "Número de teléfono no válido.",
   "shipping_carriers.create.error.loadProviders": "Error al cargar los transportistas.",

package/src/modules/shipping_carriers/i18n/pl.json

@@ -14,6 +14,7 @@
   "shipping_carriers.create.error.create": "Nie udało się utworzyć przesyłki.",
   "shipping_carriers.create.error.fetchDropOffPoints": "Nie udało się pobrać punktów nadania.",
   "shipping_carriers.create.error.fetchRates": "Nie udało się pobrać stawek.",
+  "shipping_carriers.create.error.idempotencyConflict": "Ta przesyłka została już wysłana. Odśwież stronę przed ponowną próbą.",
   "shipping_carriers.create.error.invalidEmail": "Nieprawidłowy adres e-mail.",
   "shipping_carriers.create.error.invalidPhone": "Nieprawidłowy numer telefonu.",
   "shipping_carriers.create.error.loadProviders": "Nie udało się załadować przewoźników.",

package/src/modules/shipping_carriers/lib/shipment-idempotency.ts

@@ -0,0 +1,119 @@
+import { createHash } from 'node:crypto'
+import { UniqueConstraintViolationException } from '@mikro-orm/core'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { CarrierShipmentIdempotencyKey } from '../data/entities'
+
+type Scope = { organizationId: string; tenantId: string }
+
+// Use Symbol.for so the marker survives module duplication across bundle boundaries — an
+// `instanceof` check returns false when the API route and the service load separate copies of
+// this class in the production build, which would silently downgrade the 409 conflict to a 502.
+const SHIPMENT_IDEMPOTENCY_CONFLICT_MARKER = Symbol.for('@open-mercato/ShipmentIdempotencyConflictError')
+
+export class ShipmentIdempotencyConflictError extends Error {
+  readonly [SHIPMENT_IDEMPOTENCY_CONFLICT_MARKER] = true
+  readonly idempotencyKey: string
+  constructor(idempotencyKey: string) {
+    super(`[internal] Shipment idempotency conflict for key "${idempotencyKey}"`)
+    this.name = 'ShipmentIdempotencyConflictError'
+    this.idempotencyKey = idempotencyKey
+  }
+}
+
+export function isShipmentIdempotencyConflictError(error: unknown): error is ShipmentIdempotencyConflictError {
+  return (
+    !!error &&
+    typeof error === 'object' &&
+    (error as Record<symbol, unknown>)[SHIPMENT_IDEMPOTENCY_CONFLICT_MARKER] === true
+  )
+}
+
+function stableSerialize(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'
+  if (Array.isArray(value)) return `[${value.map(stableSerialize).join(',')}]`
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, entryValue]) => entryValue !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+  return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${stableSerialize(entryValue)}`).join(',')}}`
+}
+
+/**
+ * Deterministic fingerprint of a shipment-create request so that reusing the same
+ * idempotency key with a conflicting payload can be detected. Key order is
+ * normalized and `undefined` values are dropped so semantically equal requests
+ * hash identically.
+ */
+export function computeShipmentRequestHash(fingerprint: unknown): string {
+  return createHash('sha256').update(stableSerialize(fingerprint)).digest('hex')
+}
+
+export async function findShipmentIdempotencyClaim(
+  em: EntityManager,
+  idempotencyKey: string,
+  providerKey: string,
+  scope: Scope,
+): Promise<CarrierShipmentIdempotencyKey | null> {
+  return findOneWithDecryption(
+    em,
+    CarrierShipmentIdempotencyKey,
+    {
+      idempotencyKey,
+      providerKey,
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+    },
+    undefined,
+    scope,
+  )
+}
+
+/**
+ * Atomically claims an idempotency key by inserting the dedup row. Returns the
+ * managed claim on success, or `null` when a concurrent request already inserted
+ * the same scoped key (the unique constraint fires), mirroring the webhook-event
+ * claim idiom.
+ */
+export async function claimShipmentIdempotency(
+  em: EntityManager,
+  idempotencyKey: string,
+  providerKey: string,
+  requestHash: string,
+  scope: Scope,
+): Promise<CarrierShipmentIdempotencyKey | null> {
+  const record = em.create(CarrierShipmentIdempotencyKey, {
+    idempotencyKey,
+    providerKey,
+    requestHash,
+    shipmentId: null,
+    organizationId: scope.organizationId,
+    tenantId: scope.tenantId,
+  })
+  try {
+    await em.persist(record).flush()
+    return record
+  } catch (error: unknown) {
+    if (error instanceof UniqueConstraintViolationException) return null
+    throw error
+  }
+}
+
+export async function resolveShipmentIdempotency(
+  em: EntityManager,
+  claim: CarrierShipmentIdempotencyKey,
+  shipmentId: string,
+): Promise<void> {
+  claim.shipmentId = shipmentId
+  await em.flush()
+}
+
+export async function releaseShipmentIdempotency(
+  em: EntityManager,
+  idempotencyKey: string,
+  providerKey: string,
+  scope: Scope,
+): Promise<void> {
+  const existing = await findShipmentIdempotencyClaim(em, idempotencyKey, providerKey, scope)
+  if (!existing) return
+  await em.remove(existing).flush()
+}

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

@@ -37,11 +37,12 @@ export type CreateShipmentParams = {
   receiverEmail?: string
   targetPoint?: string
   c2cSendingMethod?: string
+  idempotencyKey?: string
 }
 
 export type CreateShipmentResult =
   | { ok: true }
-  | { ok: false; error: string }
+  | { ok: false; error: string; code?: string }
 
 export type FetchDropOffPointsParams = {
   providerKey: string
@@ -126,6 +127,7 @@ export const createShipment = async (params: CreateShipmentParams): Promise<Crea
     .otherwise(({ result }) => ({
       ok: false as const,
       error: (result as { error?: string } | null)?.error ?? 'Failed to create shipment.',
+      code: (result as { code?: string } | null)?.code,
     }))
 }
 

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

@@ -194,6 +194,9 @@ export const useShipmentWizard = (): ShipmentWizard => {
     setIsFetchingRates(false)
   }
 
+  const idempotencyKeyRef = React.useRef<string | null>(null)
+  const idempotencySignatureRef = React.useRef<string | null>(null)
+
   const handleSubmit = async () => {
     if (!selectedProvider || !selectedRate || !orderId) return
     setIsSubmitting(true)
@@ -212,20 +215,39 @@ export const useShipmentWizard = (): ShipmentWizard => {
       ...(targetPoint ? { targetPoint } : {}),
       ...(c2cSendingMethod ? { c2cSendingMethod } : {}),
     }
+    // Reuse one idempotency key per confirmed payload so a double-submit or a
+    // network-timeout retry de-duplicates server-side; regenerate it when the
+    // payload changes so an edited shipment is not rejected as a conflict.
+    const signature = JSON.stringify(payload)
+    if (idempotencyKeyRef.current === null || idempotencySignatureRef.current !== signature) {
+      idempotencyKeyRef.current = crypto.randomUUID()
+      idempotencySignatureRef.current = signature
+    }
+    const submitPayload: CreateShipmentParams = { ...payload, idempotencyKey: idempotencyKeyRef.current }
     try {
       const result = await runMutation({
-        operation: () => createShipment(payload),
+        operation: () => createShipment(submitPayload),
         context: {
           operation: 'create',
           resourceKind: 'shipping_carriers.shipment',
           resourceId: orderId,
           retryLastMutation,
         },
-        mutationPayload: payload as unknown as Record<string, unknown>,
+        mutationPayload: submitPayload as unknown as Record<string, unknown>,
       })
       if (result.ok) {
+        idempotencyKeyRef.current = null
+        idempotencySignatureRef.current = null
         flash(t('shipping_carriers.create.success', 'Shipment created successfully.'), 'success')
         router.push(backHref)
+      } else if (result.code === 'idempotency_conflict') {
+        flash(
+          t(
+            'shipping_carriers.create.error.idempotencyConflict',
+            'This shipment was already submitted. Refresh the page before retrying.',
+          ),
+          'error',
+        )
       } else {
         flash(t('shipping_carriers.create.error.create', result.error), 'error')
       }

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

@@ -1,10 +1,19 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import type { CredentialsService } from '../../integrations/lib/credentials-service'
-import { CarrierShipment } from '../data/entities'
+import { CarrierShipment, type CarrierShipmentIdempotencyKey } from '../data/entities'
 import { emitShippingEvent } from '../events'
 import { getShippingAdapter } from './adapter-registry'
 import type { UnifiedShipmentStatus } from './adapter'
+import {
+  claimShipmentIdempotency,
+  computeShipmentRequestHash,
+  findShipmentIdempotencyClaim,
+  isShipmentIdempotencyConflictError,
+  releaseShipmentIdempotency,
+  resolveShipmentIdempotency,
+  ShipmentIdempotencyConflictError,
+} from './shipment-idempotency'
 import {
   getTerminalShippingEvent,
   isValidShippingTransition,
@@ -90,52 +99,87 @@ export function createShippingCarrierService(deps: {
       receiverEmail?: string
       targetPoint?: string
       c2cSendingMethod?: string
+      idempotencyKey?: string
       organizationId: string
       tenantId: string
     }) {
-      const { adapter, credentials } = await resolveAdapter(input.providerKey, {
-        organizationId: input.organizationId,
-        tenantId: input.tenantId,
-      })
-      const mergedCredentials = {
-        ...credentials,
-        ...(input.senderPhone !== undefined ? { senderPhone: input.senderPhone } : {}),
-        ...(input.senderEmail !== undefined ? { senderEmail: input.senderEmail } : {}),
-        ...(input.receiverPhone !== undefined ? { receiverPhone: input.receiverPhone } : {}),
-        ...(input.receiverEmail !== undefined ? { receiverEmail: input.receiverEmail } : {}),
-        ...(input.targetPoint !== undefined ? { targetPoint: input.targetPoint } : {}),
-        ...(input.c2cSendingMethod !== undefined ? { c2cSendingMethod: input.c2cSendingMethod } : {}),
+      const scope = { organizationId: input.organizationId, tenantId: input.tenantId }
+      let claim: CarrierShipmentIdempotencyKey | null = null
+      if (input.idempotencyKey) {
+        const { idempotencyKey: _idempotencyKey, ...fingerprint } = input
+        const requestHash = computeShipmentRequestHash(fingerprint)
+        const existing = await findShipmentIdempotencyClaim(em, input.idempotencyKey, input.providerKey, scope)
+        if (existing) {
+          if (existing.requestHash !== requestHash) {
+            throw new ShipmentIdempotencyConflictError(input.idempotencyKey)
+          }
+          if (existing.shipmentId) {
+            return findShipmentOrThrow(existing.shipmentId, scope)
+          }
+          // Claim exists but the original request has not resolved yet (concurrent in-flight).
+          throw new ShipmentIdempotencyConflictError(input.idempotencyKey)
+        }
+        claim = await claimShipmentIdempotency(em, input.idempotencyKey, input.providerKey, requestHash, scope)
+        if (!claim) {
+          // Lost the claim race with a concurrent request creating the same shipment.
+          throw new ShipmentIdempotencyConflictError(input.idempotencyKey)
+        }
+      }
+      let carrierShipmentCreated = false
+      try {
+        const { adapter, credentials } = await resolveAdapter(input.providerKey, scope)
+        const mergedCredentials = {
+          ...credentials,
+          ...(input.senderPhone !== undefined ? { senderPhone: input.senderPhone } : {}),
+          ...(input.senderEmail !== undefined ? { senderEmail: input.senderEmail } : {}),
+          ...(input.receiverPhone !== undefined ? { receiverPhone: input.receiverPhone } : {}),
+          ...(input.receiverEmail !== undefined ? { receiverEmail: input.receiverEmail } : {}),
+          ...(input.targetPoint !== undefined ? { targetPoint: input.targetPoint } : {}),
+          ...(input.c2cSendingMethod !== undefined ? { c2cSendingMethod: input.c2cSendingMethod } : {}),
+        }
+        const created = await adapter.createShipment({
+          orderId: input.orderId,
+          origin: input.origin,
+          destination: input.destination,
+          packages: input.packages,
+          serviceCode: input.serviceCode,
+          credentials: mergedCredentials,
+          labelFormat: input.labelFormat,
+        })
+        carrierShipmentCreated = true
+        const shipment = em.create(CarrierShipment, {
+          orderId: input.orderId,
+          providerKey: input.providerKey,
+          carrierShipmentId: created.shipmentId,
+          trackingNumber: created.trackingNumber,
+          unifiedStatus: 'label_created',
+          labelUrl: created.labelUrl ?? null,
+          labelData: created.labelData ?? null,
+          organizationId: input.organizationId,
+          tenantId: input.tenantId,
+        })
+        await em.persist(shipment).flush()
+        if (claim) {
+          await resolveShipmentIdempotency(em, claim, shipment.id)
+        }
+        await emitShippingEvent('shipping_carriers.shipment.created', {
+          shipmentId: shipment.id,
+          orderId: input.orderId,
+          providerKey: input.providerKey,
+          trackingNumber: created.trackingNumber,
+          organizationId: input.organizationId,
+          tenantId: input.tenantId,
+        })
+        return shipment
+      } catch (error: unknown) {
+        // Release the claim only when the carrier was NOT successfully called, so a retry can
+        // proceed. If the carrier already created the shipment, keep the claim so a retry does
+        // not produce a duplicate upstream shipment.
+        if (claim && !carrierShipmentCreated && input.idempotencyKey && !isShipmentIdempotencyConflictError(error)) {
+          await releaseShipmentIdempotency(em, input.idempotencyKey, input.providerKey, scope).catch(() => {})
+        }
+        throw error
       }
-      const created = await adapter.createShipment({
-        orderId: input.orderId,
-        origin: input.origin,
-        destination: input.destination,
-        packages: input.packages,
-        serviceCode: input.serviceCode,
-        credentials: mergedCredentials,
-        labelFormat: input.labelFormat,
-      })
-      const shipment = em.create(CarrierShipment, {
-        orderId: input.orderId,
-        providerKey: input.providerKey,
-        carrierShipmentId: created.shipmentId,
-        trackingNumber: created.trackingNumber,
-        unifiedStatus: 'label_created',
-        labelUrl: created.labelUrl ?? null,
-        labelData: created.labelData ?? null,
-        organizationId: input.organizationId,
-        tenantId: input.tenantId,
-      })
-      await em.persist(shipment).flush()
-      await emitShippingEvent('shipping_carriers.shipment.created', {
-        shipmentId: shipment.id,
-        orderId: input.orderId,
-        providerKey: input.providerKey,
-        trackingNumber: created.trackingNumber,
-        organizationId: input.organizationId,
-        tenantId: input.tenantId,
-      })
-      return shipment
     },
 
     async getTracking(input: {