@open-mercato/core 0.6.6-develop.6257.1.6d0af84d26 → 0.6.6-develop.6290.1.4bb5a8ba3f

package/src/modules/resources/api/resource-types.ts

@@ -3,11 +3,10 @@ import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { resolveCrudRecordId, parseScopedCommandInput } from '@open-mercato/shared/lib/api/scoped'
 import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
-import type { EntityManager } from '@mikro-orm/postgresql'
-import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
-import { ResourcesResource, ResourcesResourceType } from '../data/entities'
+import { ResourcesResourceType } from '../data/entities'
 import { resourcesResourceTypeCreateSchema, resourcesResourceTypeUpdateSchema } from '../data/validators'
 import { sanitizeSearchTerm } from './helpers'
+import { attachResourceTypeCounts } from './resourceTypeCounts'
 import { E } from '#generated/entities.ids.generated'
 import { createResourcesCrudOpenApi, createPagedListResponseSchema, defaultOkResponseSchema } from './openapi'
 
@@ -47,6 +46,7 @@ const listSchema = z
     ids: z.string().optional(),
     sortField: z.string().optional(),
     sortDir: z.enum(['asc', 'desc']).optional(),
+    withResourceCounts: z.string().optional(),
   })
   .passthrough()
 
@@ -131,47 +131,7 @@ const crud = makeCrudRoute({
     },
   },
   hooks: {
-    afterList: async (payload, ctx) => {
-      const items: Array<Record<string, unknown>> = Array.isArray(payload?.items)
-        ? (payload.items as Array<Record<string, unknown>>)
-        : []
-      if (!items.length) return
-      const typeIds = items
-        .map((item) => (typeof item.id === 'string' ? item.id : null))
-        .filter((id): id is string => typeof id === 'string' && id.length > 0)
-      if (!typeIds.length) return
-      const em = (ctx.container.resolve('em') as EntityManager).fork()
-      const tenantId = ctx.organizationScope?.tenantId ?? ctx.auth?.tenantId ?? null
-      const orgIds = ctx.organizationIds ?? ctx.organizationScope?.filterIds ?? null
-      const orgFilter =
-        Array.isArray(orgIds) && orgIds.length > 0
-          ? { $in: orgIds }
-          : ctx.selectedOrganizationId ?? ctx.organizationScope?.selectedId ?? null
-      const scope = { tenantId, organizationId: ctx.selectedOrganizationId ?? ctx.organizationScope?.selectedId ?? null }
-      const resources = await findWithDecryption(
-        em,
-        ResourcesResource,
-        {
-          resourceTypeId: { $in: typeIds },
-          deletedAt: null,
-          ...(tenantId ? { tenantId } : {}),
-          ...(orgFilter ? { organizationId: orgFilter } : {}),
-        },
-        { fields: ['id', 'resourceTypeId'] },
-        scope,
-      )
-      const countMap = new Map<string, number>()
-      resources.forEach((resource) => {
-        const typeId = resource.resourceTypeId ?? null
-        if (!typeId) return
-        countMap.set(typeId, (countMap.get(typeId) ?? 0) + 1)
-      })
-      items.forEach((item) => {
-        const id = typeof item.id === 'string' ? item.id : null
-        if (!id) return
-        item.resourceCount = countMap.get(id) ?? 0
-      })
-    },
+    afterList: (payload, ctx) => attachResourceTypeCounts(payload, ctx),
   },
 })
 

package/src/modules/resources/api/resourceTypeCounts.ts

@@ -0,0 +1,74 @@
+import type { Kysely } from 'kysely'
+import { sql } from 'kysely'
+import { parseBooleanFromUnknown } from '@open-mercato/shared/lib/boolean'
+import type { CrudCtx } from '@open-mercato/shared/lib/crud/factory'
+
+type ResourceCountDatabase = {
+  resources_resources: {
+    resource_type_id: string | null
+    deleted_at: Date | null
+    tenant_id: string | null
+    organization_id: string | null
+  }
+}
+
+type KyselyCapableEntityManager = { getKysely: () => Kysely<ResourceCountDatabase> }
+
+type ResourceTypeCountContext = Pick<
+  CrudCtx,
+  'container' | 'auth' | 'organizationScope' | 'organizationIds' | 'selectedOrganizationId'
+> & { query?: { withResourceCounts?: unknown } }
+
+type ResourceTypeListPayload = { items?: unknown } | null | undefined
+
+type ResourceCountRow = { resource_type_id: string | null; count: string | number }
+
+export async function attachResourceTypeCounts(
+  payload: ResourceTypeListPayload,
+  ctx: ResourceTypeCountContext,
+): Promise<void> {
+  // Resource counts are opt-in: only callers that render the count (the
+  // resource-types admin table and its delete gate) pass `withResourceCounts`.
+  // Select/filter callers (resource dropdowns, group labels) skip the scan
+  // entirely so ordinary type lookups no longer pay an O(resources) cost.
+  if (!parseBooleanFromUnknown(ctx.query?.withResourceCounts)) return
+
+  const items = Array.isArray(payload?.items)
+    ? (payload!.items as Array<Record<string, unknown>>)
+    : []
+  if (!items.length) return
+
+  const typeIds = items
+    .map((item) => (typeof item.id === 'string' ? item.id : null))
+    .filter((id): id is string => typeof id === 'string' && id.length > 0)
+  if (!typeIds.length) return
+
+  const tenantId = ctx.organizationScope?.tenantId ?? ctx.auth?.tenantId ?? null
+  const orgIds = ctx.organizationIds ?? ctx.organizationScope?.filterIds ?? null
+  const singleOrgId = ctx.selectedOrganizationId ?? ctx.organizationScope?.selectedId ?? null
+
+  const db = (ctx.container.resolve('em') as unknown as KyselyCapableEntityManager).getKysely()
+  let query = db
+    .selectFrom('resources_resources')
+    .select(['resource_type_id', sql<string>`count(*)`.as('count')])
+    .where('resource_type_id', 'in', typeIds)
+    .where('deleted_at', 'is', null)
+  if (tenantId) query = query.where('tenant_id', '=', tenantId)
+  if (Array.isArray(orgIds) && orgIds.length > 0) {
+    query = query.where('organization_id', 'in', orgIds)
+  } else if (singleOrgId) {
+    query = query.where('organization_id', '=', singleOrgId)
+  }
+  const rows = (await query.groupBy('resource_type_id').execute()) as ResourceCountRow[]
+
+  const countMap = new Map<string, number>()
+  for (const row of rows) {
+    if (typeof row.resource_type_id !== 'string') continue
+    const count = typeof row.count === 'string' ? Number.parseInt(row.count, 10) : Number(row.count)
+    countMap.set(row.resource_type_id, Number.isFinite(count) ? count : 0)
+  }
+  for (const item of items) {
+    if (typeof item.id !== 'string') continue
+    item.resourceCount = countMap.get(item.id) ?? 0
+  }
+}

package/src/modules/resources/backend/resources/resource-types/[id]/edit/page.tsx

@@ -34,7 +34,7 @@ export default function ResourcesResourceTypeEditPage({ params }: { params?: { i
       setIsNotFound(false)
       try {
         const payload = await readApiResultOrThrow<ResourceTypesResponse>(
-          `/api/resources/resource-types?ids=${encodeURIComponent(resourceTypeId)}&page=1&pageSize=1`,
+          `/api/resources/resource-types?ids=${encodeURIComponent(resourceTypeId)}&page=1&pageSize=1&withResourceCounts=true`,
           undefined,
           { errorMessage: t('resources.resourceTypes.errors.load', 'Failed to load resource types.') },
         )

package/src/modules/resources/backend/resources/resource-types/page.tsx

@@ -208,6 +208,7 @@ export default function ResourcesResourceTypesPage() {
       const params = new URLSearchParams({
         page: String(page),
         pageSize: String(PAGE_SIZE),
+        withResourceCounts: 'true',
       })
       const sort = sorting[0]
       if (sort?.id) {

package/src/modules/sales/components/documents/ReturnDialog.tsx

@@ -11,6 +11,7 @@ import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { apiCallOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { normalizeCrudServerError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { computeAvailableReturnQuantity } from '@open-mercato/core/modules/sales/lib/returnQuantity'
 import { handleSectionMutationError } from './optimisticLock'
@@ -136,7 +137,9 @@ export function ReturnDialog({ open, orderId, lines, documentUpdatedAt, onClose,
         onClose()
         return
       }
-      flash(t('sales.returns.errors.create', 'Failed to create return.'), 'error')
+      const normalized = normalizeCrudServerError(err)
+      const fallback = t('sales.returns.errors.create', 'Failed to create return.')
+      flash(normalized.message || fallback, 'error')
     } finally {
       setSaving(false)
     }

package/src/modules/sales/components/documents/ShipmentDialog.tsx

@@ -255,6 +255,20 @@ const extractShipmentAddressSnapshot = (
   return normalizeAddressSnapshot(raw as Record<string, unknown>)
 }
 
+const addressOptionsSignature = (options: ShipmentAddressOption[]): string =>
+  options.map((option) => `${snapshotKey(option.snapshot) ?? ''}::${option.id}`).join('||')
+
+function useStableAddressOptions(options: ShipmentAddressOption[]): ShipmentAddressOption[] {
+  const signature = addressOptionsSignature(options)
+  const stableRef = React.useRef(options)
+  const signatureRef = React.useRef(signature)
+  if (signatureRef.current !== signature) {
+    signatureRef.current = signature
+    stableRef.current = options
+  }
+  return stableRef.current
+}
+
 export function ShipmentDialog({
   open,
   mode,
@@ -323,7 +337,7 @@ export function ShipmentDialog({
     [shipmentAddressSnapshot, t],
   )
 
-  const baseAddressOptions = React.useMemo(
+  const computedBaseAddressOptions = React.useMemo(
     () =>
       dedupeAddressOptions(
         [shippingAddressOption, shipmentAddressOption].filter(
@@ -332,6 +346,7 @@ export function ShipmentDialog({
       ),
     [shipmentAddressOption, shippingAddressOption],
   )
+  const baseAddressOptions = useStableAddressOptions(computedBaseAddressOptions)
 
   const preferredAddressId = React.useMemo(() => {
     const shipmentKey = snapshotKey(shipmentAddressSnapshot)
@@ -452,7 +467,10 @@ export function ShipmentDialog({
 
   const mergeAddressOptions = React.useCallback(
     (options: ShipmentAddressOption[]) =>
-      setAddressOptions((prev) => dedupeAddressOptions([...prev, ...options])),
+      setAddressOptions((prev) => {
+        const next = dedupeAddressOptions([...prev, ...options])
+        return next.length === prev.length ? prev : next
+      }),
     [],
   )
 

package/src/modules/sales/di.ts

@@ -7,6 +7,7 @@ import { registerOptimisticLockReaders } from '@open-mercato/shared/lib/crud/opt
 import { DefaultSalesCalculationService } from './services/salesCalculationService'
 import { DefaultTaxCalculationService } from './services/taxCalculationService'
 import { SalesDocumentNumberGenerator } from './services/salesDocumentNumberGenerator'
+import { DefaultSalesOrderService } from './services/salesOrderService'
 import {
   SalesOrder,
   SalesOrderLine,
@@ -85,6 +86,11 @@ export function register(container: AppContainer) {
     })
       .singleton()
       .proxy(),
+    salesOrderService: asFunction(({ em }: AppCradle) => {
+      return new DefaultSalesOrderService(em)
+    })
+      .singleton()
+      .proxy(),
     SalesOrder: asValue(SalesOrder),
     SalesOrderLine: asValue(SalesOrderLine),
     SalesOrderAdjustment: asValue(SalesOrderAdjustment),

package/src/modules/sales/services/salesOrderService.ts

@@ -0,0 +1,38 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { SalesOrder } from '../data/entities'
+
+export type SalesOrderLookupScope = {
+  organizationId: string
+  tenantId: string
+}
+
+export interface SalesOrderService {
+  findByExternalReference(
+    externalReference: string,
+    scope: SalesOrderLookupScope,
+  ): Promise<SalesOrder | null>
+}
+
+export class DefaultSalesOrderService implements SalesOrderService {
+  constructor(private readonly em: EntityManager) {}
+
+  async findByExternalReference(
+    externalReference: string,
+    scope: SalesOrderLookupScope,
+  ): Promise<SalesOrder | null> {
+    if (!externalReference) return null
+    return findOneWithDecryption(
+      this.em,
+      SalesOrder,
+      {
+        externalReference,
+        organizationId: scope.organizationId,
+        tenantId: scope.tenantId,
+        deletedAt: null,
+      },
+      undefined,
+      { tenantId: scope.tenantId, organizationId: scope.organizationId },
+    )
+  }
+}

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')
       }