@open-mercato/checkout 0.6.5-develop.4534.1.b459babe6d → 0.6.5-develop.4544.1.71c003c861

package/src/modules/checkout/__integration__/TC-CHKT-039-stale-delete-lock.spec.ts

@@ -0,0 +1,98 @@
+import { expect, test } from '@playwright/test'
+import { getAuthToken } from '@open-mercato/core/modules/core/__integration__/helpers/api'
+import { createFixedTemplateInput, createLinkFixture, readLink } from './helpers/fixtures'
+
+/**
+ * TC-CHKT-039: OSS optimistic locking now guards the pay-link/template DELETE.
+ *
+ * QA round-6 (PR #2055): after a save conflict surfaced the unified conflict
+ * bar, clicking Delete still removed the stale record. The pay-link/template
+ * delete path was unguarded — the client sent no version header and the
+ * `checkout.link.delete` / `checkout.template.delete` commands never called
+ * `enforceCommandOptimisticLock` (only the *.update commands did).
+ *
+ * This spec proves the server contract the UI relies on:
+ *   - GET detail exposes `updatedAt`.
+ *   - DELETE without the header succeeds (strictly additive).
+ *   - DELETE with a stale header returns 409 with the structured conflict body.
+ *   - DELETE with a fresh header deletes the record.
+ *
+ * Requires `OM_OPTIMISTIC_LOCK=all` (CI default).
+ */
+const OPTIMISTIC_LOCK_HEADER = 'x-om-ext-optimistic-lock-expected-updated-at'
+
+function readUpdatedAt(record: Record<string, unknown>): string {
+  const raw = record.updatedAt ?? record.updated_at
+  expect(typeof raw, 'link detail should expose updatedAt as a string').toBe('string')
+  return new Date(Date.parse(raw as string)).toISOString()
+}
+
+test.describe('TC-CHKT-039: pay-link stale DELETE optimistic-lock guard', () => {
+  test('stale DELETE returns 409; fresh DELETE succeeds; header-less stays backward-compatible', async ({ request }) => {
+    const token = await getAuthToken(request)
+
+    // Two links: one to prove the stale→409→fresh path, one to prove the
+    // strictly-additive header-less delete still works.
+    const guarded = await createLinkFixture(request, token, createFixedTemplateInput())
+    const additive = await createLinkFixture(request, token, createFixedTemplateInput())
+    let guardedDeleted = false
+    let additiveDeleted = false
+
+    try {
+      const detail = await readLink(request, token, guarded.id)
+      const t0 = readUpdatedAt(detail as Record<string, unknown>)
+
+      // A save advances the version, making t0 stale.
+      const bump = await request.fetch(`/api/checkout/links/${encodeURIComponent(guarded.id)}`, {
+        method: 'PUT',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        data: { subtitle: 'bumped for stale-delete test' },
+      })
+      expect(bump.status(), 'PUT bump should succeed').toBeLessThan(300)
+
+      // Stale DELETE → 409 with the structured conflict body; record survives.
+      const staleDelete = await request.fetch(`/api/checkout/links/${encodeURIComponent(guarded.id)}`, {
+        method: 'DELETE',
+        headers: { Authorization: `Bearer ${token}`, [OPTIMISTIC_LOCK_HEADER]: t0 },
+      })
+      expect(staleDelete.status(), 'DELETE with a stale header should return 409').toBe(409)
+      expect((await staleDelete.json()) as Record<string, unknown>).toMatchObject({
+        code: 'optimistic_lock_conflict',
+        expectedUpdatedAt: t0,
+      })
+
+      const stillThere = await readLink(request, token, guarded.id)
+      const t1 = readUpdatedAt(stillThere as Record<string, unknown>)
+      expect(t1, 'stale delete must NOT have removed the record').not.toBe(t0)
+
+      // Fresh DELETE → succeeds.
+      const freshDelete = await request.fetch(`/api/checkout/links/${encodeURIComponent(guarded.id)}`, {
+        method: 'DELETE',
+        headers: { Authorization: `Bearer ${token}`, [OPTIMISTIC_LOCK_HEADER]: t1 },
+      })
+      expect(freshDelete.status(), 'DELETE with a fresh header should succeed').toBeLessThan(300)
+      guardedDeleted = true
+
+      // Header-less DELETE still works (strictly additive).
+      const nohdrDelete = await request.fetch(`/api/checkout/links/${encodeURIComponent(additive.id)}`, {
+        method: 'DELETE',
+        headers: { Authorization: `Bearer ${token}` },
+      })
+      expect(nohdrDelete.status(), 'DELETE without a header should succeed').toBeLessThan(300)
+      additiveDeleted = true
+    } finally {
+      if (!guardedDeleted) {
+        await request.fetch(`/api/checkout/links/${encodeURIComponent(guarded.id)}`, {
+          method: 'DELETE',
+          headers: { Authorization: `Bearer ${token}` },
+        }).catch(() => undefined)
+      }
+      if (!additiveDeleted) {
+        await request.fetch(`/api/checkout/links/${encodeURIComponent(additive.id)}`, {
+          method: 'DELETE',
+          headers: { Authorization: `Bearer ${token}` },
+        }).catch(() => undefined)
+      }
+    }
+  })
+})

package/src/modules/checkout/commands/__tests__/optimistic-lock.test.ts

@@ -0,0 +1,261 @@
+/** @jest-environment node */
+
+import { commandRegistry } from '@open-mercato/shared/lib/commands/registry'
+import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands/types'
+import { OPTIMISTIC_LOCK_HEADER_NAME } from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+
+const ORG_ID = '123e4567-e89b-12d3-a456-426614174000'
+const TENANT_ID = '123e4567-e89b-12d3-a456-426614174001'
+const LINK_ID = '123e4567-e89b-12d3-a456-426614174010'
+const TEMPLATE_ID = '123e4567-e89b-12d3-a456-426614174020'
+const CURRENT_VERSION = '2026-06-01T10:00:00.000Z'
+const STALE_VERSION = '2026-06-01T09:00:00.000Z'
+
+const FLUSH_SENTINEL = 'FLUSH_REACHED_AFTER_LOCK'
+
+const mockFindOneWithDecryption = jest.fn()
+
+jest.mock('@open-mercato/shared/lib/encryption/find', () => ({
+  findOneWithDecryption: jest.fn((...args: unknown[]) => mockFindOneWithDecryption(...args)),
+}))
+
+jest.mock('../../lib/gatewayProviderAvailability', () => ({
+  ensureGatewayProviderConfigured: jest.fn(async () => undefined),
+  getGatewayProviderConfigurationMessageKey: jest.fn(() => null),
+}))
+
+jest.mock('@open-mercato/shared/lib/commands/helpers', () => ({
+  setCustomFieldsIfAny: jest.fn(async () => undefined),
+}))
+
+jest.mock('@open-mercato/shared/lib/commands/customFieldSnapshots', () => ({
+  loadCustomFieldSnapshot: jest.fn(async () => ({})),
+  buildCustomFieldResetMap: jest.fn(() => ({})),
+}))
+
+jest.mock('@open-mercato/shared/lib/crud/custom-fields', () => ({
+  loadCustomFieldValues: jest.fn(async () => ({})),
+}))
+
+jest.mock('../../events', () => ({
+  emitCheckoutEvent: jest.fn(async () => undefined),
+}))
+
+// Importing the command modules registers the handlers via registerCommand.
+import '../links'
+import '../templates'
+
+// flush runs immediately AFTER the lock guard in both update commands. Throwing
+// a recognizable sentinel here lets the match / no-header cases prove the lock
+// guard PASSED, without mocking the full post-flush path (custom fields, events).
+const mockEm = {
+  flush: jest.fn(async () => {
+    throw new Error(FLUSH_SENTINEL)
+  }),
+  // delete commands count active transactions before flushing; 0 lets the
+  // happy path reach the flush sentinel so we can prove the lock guard passed.
+  count: jest.fn(async () => 0),
+}
+
+const mockDataEngine = {}
+
+function makeContext(headerVersion: string | null): CommandRuntimeContext {
+  const headers = new Headers()
+  if (headerVersion) headers.set(OPTIMISTIC_LOCK_HEADER_NAME, headerVersion)
+  const request = new Request('http://localhost/api/checkout/links/x', { method: 'PUT', headers })
+  return {
+    container: {
+      resolve: (token: string) => {
+        if (token === 'em') return mockEm
+        if (token === 'dataEngine') return mockDataEngine
+        if (token === 'paymentGatewayDescriptorService') return {}
+        return null
+      },
+    } as unknown as CommandRuntimeContext['container'],
+    auth: { orgId: ORG_ID, tenantId: TENANT_ID } as CommandRuntimeContext['auth'],
+    organizationScope: null,
+    selectedOrganizationId: ORG_ID,
+    organizationIds: [ORG_ID],
+    request,
+  }
+}
+
+function linkRecord() {
+  return {
+    id: LINK_ID,
+    organizationId: ORG_ID,
+    tenantId: TENANT_ID,
+    name: 'Pay link',
+    title: null,
+    slug: 'pay-link',
+    templateId: null,
+    status: 'draft',
+    isLocked: false,
+    pricingMode: 'fixed',
+    gatewayProviderKey: null,
+    gatewaySettings: {},
+    fixedPriceAmount: null,
+    fixedPriceOriginalAmount: null,
+    customAmountMin: null,
+    customAmountMax: null,
+    passwordHash: null,
+    updatedAt: new Date(CURRENT_VERSION),
+  }
+}
+
+function templateRecord() {
+  return {
+    id: TEMPLATE_ID,
+    organizationId: ORG_ID,
+    tenantId: TENANT_ID,
+    name: 'Template',
+    title: null,
+    status: 'draft',
+    pricingMode: 'fixed',
+    gatewayProviderKey: null,
+    gatewaySettings: {},
+    fixedPriceAmount: null,
+    fixedPriceOriginalAmount: null,
+    customAmountMin: null,
+    customAmountMax: null,
+    passwordHash: null,
+    updatedAt: new Date(CURRENT_VERSION),
+  }
+}
+
+async function runUpdate(commandId: string, input: Record<string, unknown>, headerVersion: string | null) {
+  const handler = commandRegistry.get(commandId)
+  if (!handler) throw new Error(`Command ${commandId} not registered`)
+  return handler.execute(input, makeContext(headerVersion))
+}
+
+describe('checkout command optimistic locking', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    delete process.env.OM_OPTIMISTIC_LOCK
+  })
+
+  describe('checkout.link.update', () => {
+    beforeEach(() => {
+      mockFindOneWithDecryption.mockResolvedValue(linkRecord())
+    })
+
+    it('rejects a stale expected version with a structured 409 conflict', async () => {
+      expect.assertions(4)
+      try {
+        await runUpdate('checkout.link.update', { id: LINK_ID, status: 'draft' }, STALE_VERSION)
+      } catch (error) {
+        const httpError = error as { status?: number; body?: Record<string, unknown> }
+        expect(httpError.status).toBe(409)
+        expect(httpError.body?.code).toBe('optimistic_lock_conflict')
+        expect(httpError.body?.currentUpdatedAt).toBe(CURRENT_VERSION)
+        expect(mockEm.flush).not.toHaveBeenCalled()
+      }
+    })
+
+    it('passes the lock guard when the expected version matches', async () => {
+      await expect(
+        runUpdate('checkout.link.update', { id: LINK_ID, status: 'draft' }, CURRENT_VERSION),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+
+    it('passes the lock guard when no expected-version header is sent (strictly additive)', async () => {
+      await expect(
+        runUpdate('checkout.link.update', { id: LINK_ID, status: 'draft' }, null),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+  })
+
+  describe('checkout.template.update', () => {
+    beforeEach(() => {
+      mockFindOneWithDecryption.mockResolvedValue(templateRecord())
+    })
+
+    it('rejects a stale expected version with a structured 409 conflict', async () => {
+      expect.assertions(3)
+      try {
+        await runUpdate('checkout.template.update', { id: TEMPLATE_ID, status: 'draft' }, STALE_VERSION)
+      } catch (error) {
+        const httpError = error as { status?: number; body?: Record<string, unknown> }
+        expect(httpError.status).toBe(409)
+        expect(httpError.body?.code).toBe('optimistic_lock_conflict')
+        expect(mockEm.flush).not.toHaveBeenCalled()
+      }
+    })
+
+    it('passes the lock guard when the expected version matches', async () => {
+      await expect(
+        runUpdate('checkout.template.update', { id: TEMPLATE_ID, status: 'draft' }, CURRENT_VERSION),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+
+    it('passes the lock guard when no expected-version header is sent', async () => {
+      await expect(
+        runUpdate('checkout.template.update', { id: TEMPLATE_ID, status: 'draft' }, null),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+  })
+
+  // QA round-6 (#2055): a stale DELETE after a conflict still deleted the
+  // record because the delete commands did not enforce the lock. These guard
+  // that the header now produces a 409 on a stale delete.
+  describe('checkout.link.delete', () => {
+    beforeEach(() => {
+      mockFindOneWithDecryption.mockResolvedValue(linkRecord())
+    })
+
+    it('rejects a stale expected version with a structured 409 conflict', async () => {
+      expect.assertions(3)
+      try {
+        await runUpdate('checkout.link.delete', { id: LINK_ID }, STALE_VERSION)
+      } catch (error) {
+        const httpError = error as { status?: number; body?: Record<string, unknown> }
+        expect(httpError.status).toBe(409)
+        expect(httpError.body?.code).toBe('optimistic_lock_conflict')
+        expect(mockEm.flush).not.toHaveBeenCalled()
+      }
+    })
+
+    it('passes the lock guard when the expected version matches', async () => {
+      await expect(
+        runUpdate('checkout.link.delete', { id: LINK_ID }, CURRENT_VERSION),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+
+    it('passes the lock guard when no expected-version header is sent (strictly additive)', async () => {
+      await expect(
+        runUpdate('checkout.link.delete', { id: LINK_ID }, null),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+  })
+
+  describe('checkout.template.delete', () => {
+    beforeEach(() => {
+      mockFindOneWithDecryption.mockResolvedValue(templateRecord())
+    })
+
+    it('rejects a stale expected version with a structured 409 conflict', async () => {
+      expect.assertions(3)
+      try {
+        await runUpdate('checkout.template.delete', { id: TEMPLATE_ID }, STALE_VERSION)
+      } catch (error) {
+        const httpError = error as { status?: number; body?: Record<string, unknown> }
+        expect(httpError.status).toBe(409)
+        expect(httpError.body?.code).toBe('optimistic_lock_conflict')
+        expect(mockEm.flush).not.toHaveBeenCalled()
+      }
+    })
+
+    it('passes the lock guard when the expected version matches', async () => {
+      await expect(
+        runUpdate('checkout.template.delete', { id: TEMPLATE_ID }, CURRENT_VERSION),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+
+    it('passes the lock guard when no expected-version header is sent', async () => {
+      await expect(
+        runUpdate('checkout.template.delete', { id: TEMPLATE_ID }, null),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+  })
+})

package/src/modules/checkout/commands/links.ts

@@ -6,6 +6,7 @@ import { buildCustomFieldResetMap, loadCustomFieldSnapshot } from '@open-mercato
 import { setCustomFieldsIfAny } from '@open-mercato/shared/lib/commands/helpers'
 import { loadCustomFieldValues } from '@open-mercato/shared/lib/crud/custom-fields'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { CheckoutLink, CheckoutLinkTemplate, CheckoutTransaction } from '../data/entities'
@@ -234,6 +235,12 @@ const updateLinkCommand: CommandHandler<Record<string, unknown>, { ok: true; slu
       deletedAt: null,
     }, undefined, scope)
     if (!link) throw new CrudHttpError(404, { error: 'Link not found' })
+    enforceCommandOptimisticLock({
+      resourceKind: 'checkout.link',
+      resourceId: link.id,
+      current: link.updatedAt ?? null,
+      request: ctx.request ?? null,
+    })
     if (link.isLocked) {
       throw new CrudHttpError(422, { error: 'This link has active transactions and cannot be edited' })
     }
@@ -380,6 +387,12 @@ const deleteLinkCommand: CommandHandler<Record<string, unknown>, { ok: true }> =
       deletedAt: null,
     }, undefined, scope)
     if (!link) throw new CrudHttpError(404, { error: 'Link not found' })
+    enforceCommandOptimisticLock({
+      resourceKind: 'checkout.link',
+      resourceId: link.id,
+      current: link.updatedAt ?? null,
+      request: ctx.request ?? null,
+    })
     const activeCount = await em.count(CheckoutTransaction, {
       linkId: link.id,
       organizationId: scope.organizationId,

package/src/modules/checkout/commands/templates.ts

@@ -5,6 +5,7 @@ import { registerCommand } from '@open-mercato/shared/lib/commands'
 import { buildCustomFieldResetMap, loadCustomFieldSnapshot } from '@open-mercato/shared/lib/commands/customFieldSnapshots'
 import { setCustomFieldsIfAny } from '@open-mercato/shared/lib/commands/helpers'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { CheckoutLink, CheckoutLinkTemplate } from '../data/entities'
@@ -226,6 +227,12 @@ const updateTemplateCommand: CommandHandler<Record<string, unknown>, { ok: true
       deletedAt: null,
     }, undefined, scope)
     if (!template) throw new CrudHttpError(404, { error: 'Template not found' })
+    enforceCommandOptimisticLock({
+      resourceKind: 'checkout.template',
+      resourceId: template.id,
+      current: template.updatedAt ?? null,
+      request: ctx.request ?? null,
+    })
     const beforeCustom = await loadCustomFieldSnapshot(em, {
       entityId: CHECKOUT_ENTITY_IDS.template,
       recordId: template.id,
@@ -376,6 +383,12 @@ const deleteTemplateCommand: CommandHandler<Record<string, unknown>, { ok: true
       deletedAt: null,
     }, undefined, scope)
     if (!template) throw new CrudHttpError(404, { error: 'Template not found' })
+    enforceCommandOptimisticLock({
+      resourceKind: 'checkout.template',
+      resourceId: template.id,
+      current: template.updatedAt ?? null,
+      request: ctx.request ?? null,
+    })
     template.deletedAt = new Date()
     await em.flush()
     await emitCheckoutEvent('checkout.template.deleted', {

package/src/modules/checkout/components/LinkTemplateForm.tsx

@@ -24,7 +24,9 @@ import { CrudForm, type CrudField, type CrudFormGroup, type CrudFormGroupCompone
 import { ComboboxInput, type ComboboxOption } from '@open-mercato/ui/backend/inputs'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { SwitchableMarkdownInput } from '@open-mercato/ui/backend/inputs'
-import { apiCall, apiCallOrThrow, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, apiCallOrThrow, readApiResultOrThrow, 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'
 import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { ColorPicker } from '@open-mercato/ui/primitives/color-picker'
@@ -1638,11 +1640,20 @@ export function LinkTemplateForm({ mode, recordId }: Props) {
                 customFields: collectCustomFieldValues(values),
               }
               const endpoint = `/api/checkout/${mode === 'link' ? 'links' : 'templates'}${recordId ? `/${encodeURIComponent(recordId)}` : ''}`
-              const response = await readApiResultOrThrow<{ id?: string; slug?: string; ok?: boolean }>(endpoint, {
-                method: recordId ? 'PUT' : 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify(payload),
-              })
+              let response: { id?: string; slug?: string; ok?: boolean }
+              try {
+                response = await withScopedApiRequestHeaders(
+                  recordId ? buildOptimisticLockHeader(readString(initialValues?.updatedAt) || null) : {},
+                  () => readApiResultOrThrow<{ id?: string; slug?: string; ok?: boolean }>(endpoint, {
+                    method: recordId ? 'PUT' : 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(payload),
+                  }),
+                )
+              } catch (error) {
+                if (surfaceRecordConflict(error, t)) return
+                throw error
+              }
               const targetId = recordId ?? (typeof response?.id === 'string' ? response.id : null)
               const logoAttachmentId = readString(values.logoAttachmentId)
               if (
@@ -1687,7 +1698,15 @@ export function LinkTemplateForm({ mode, recordId }: Props) {
                 : `/backend/checkout/templates?flash=${encodeURIComponent(t('checkout.common.flash.saved'))}&type=success`
             }}
             onDelete={recordId ? async () => {
-              await apiCallOrThrow(`/api/checkout/${mode === 'link' ? 'links' : 'templates'}/${encodeURIComponent(recordId)}`, { method: 'DELETE' })
+              try {
+                await withScopedApiRequestHeaders(
+                  buildOptimisticLockHeader(readString(initialValues?.updatedAt) || null),
+                  () => apiCallOrThrow(`/api/checkout/${mode === 'link' ? 'links' : 'templates'}/${encodeURIComponent(recordId)}`, { method: 'DELETE' }),
+                )
+              } catch (error) {
+                if (surfaceRecordConflict(error, t)) return
+                throw error
+              }
               window.location.href = mode === 'link'
                 ? `/backend/checkout/pay-links?flash=${encodeURIComponent(t('checkout.common.flash.deleted'))}&type=success`
                 : `/backend/checkout/templates?flash=${encodeURIComponent(t('checkout.common.flash.deleted'))}&type=success`