@open-mercato/checkout 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

package/src/modules/checkout/commands/__tests__/update-transaction-status.test.ts

@@ -0,0 +1,363 @@
+/** @jest-environment node */
+
+/**
+ * Tests for the state-machine guard added to updateTransactionStatusCommand.
+ *
+ * Exercises:
+ * 1. A terminal → non-terminal transition is rejected with a 409 before the
+ *    nativeUpdate is even called.
+ * 2. A non-terminal → terminal transition succeeds (nativeUpdate called with
+ *    the correct WHERE clause locking the current status).
+ * 3. When nativeUpdate returns 0 (concurrent write won the race), the command
+ *    throws a 409 (concurrent_status_update) and does NOT proceed to emit
+ *    terminal events.
+ * 4. When nativeUpdate returns 1, the command succeeds and emits the correct
+ *    terminal event.
+ */
+
+import { commandRegistry } from '@open-mercato/shared/lib/commands/registry'
+import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands/types'
+import { CheckoutTransaction } from '../../data/entities'
+
+// Register the transaction commands
+import '../transactions'
+
+jest.mock('../../events', () => ({
+  emitCheckoutEvent: jest.fn(async () => undefined),
+}))
+
+const { emitCheckoutEvent } = jest.requireMock('../../events') as {
+  emitCheckoutEvent: jest.Mock
+}
+
+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 TX_ID = '123e4567-e89b-12d3-a456-426614174020'
+
+function makeTransaction(status: CheckoutTransaction['status']) {
+  return {
+    id: TX_ID,
+    linkId: LINK_ID,
+    organizationId: ORG_ID,
+    tenantId: TENANT_ID,
+    status,
+    paymentStatus: null,
+    gatewayTransactionId: null,
+    amount: '100.00',
+    currencyCode: 'USD',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  }
+}
+
+function makeLink() {
+  return {
+    id: LINK_ID,
+    organizationId: ORG_ID,
+    tenantId: TENANT_ID,
+    slug: 'test-link',
+    templateId: null,
+    gatewayProviderKey: 'stripe',
+    activeReservationCount: 1,
+    completionCount: 0,
+    maxCompletions: null,
+    isLocked: false,
+    deletedAt: null,
+  }
+}
+
+type MockEm = {
+  findOne: jest.Mock
+  nativeUpdate: jest.Mock
+  flush: jest.Mock
+  refresh: jest.Mock
+  transactional: (fn: (tx: MockEm) => Promise<unknown>) => Promise<unknown>
+}
+
+function makeMockEm(
+  transaction: ReturnType<typeof makeTransaction>,
+  nativeUpdateResult = 1,
+  // When nativeUpdate returns 0, the post-CAS findOne should return a
+  // different status to simulate the winning writer's value.
+  postCasStatus?: CheckoutTransaction['status'],
+): MockEm {
+  let findOneCallCount = 0
+  const mockTx: MockEm = {
+    findOne: jest.fn(async (_entity: unknown, filter: Record<string, unknown>) => {
+      findOneCallCount++
+      if (filter.id === TX_ID) {
+        // After a CAS miss (nativeUpdate=0) the command re-reads the row with
+        // refresh:true to fetch the winning writer's status. Return the
+        // post-CAS status on subsequent calls when one is provided.
+        if (findOneCallCount > 1 && postCasStatus !== undefined) {
+          return { ...transaction, status: postCasStatus }
+        }
+        return transaction
+      }
+      if (filter.id === LINK_ID) return makeLink()
+      return null
+    }),
+    nativeUpdate: jest.fn(async () => nativeUpdateResult),
+    flush: jest.fn(async () => undefined),
+    refresh: jest.fn(async () => undefined),
+    transactional: (fn) => fn(mockTx),
+  }
+  return mockTx
+}
+
+function makeContext(em: MockEm): CommandRuntimeContext {
+  return {
+    container: {
+      resolve: (token: string) => {
+        if (token === 'em') return em
+        return null
+      },
+    } as unknown as CommandRuntimeContext['container'],
+    auth: null,
+    organizationScope: null,
+    selectedOrganizationId: ORG_ID,
+    organizationIds: [ORG_ID],
+  }
+}
+
+function baseInput(status: string) {
+  return {
+    id: TX_ID,
+    status,
+    paymentStatus: null,
+    gatewayTransactionId: null,
+    organizationId: ORG_ID,
+    tenantId: TENANT_ID,
+  }
+}
+
+async function runUpdateStatus(em: MockEm, status: string) {
+  const handler = commandRegistry.get('checkout.transaction.updateStatus')
+  if (!handler) throw new Error('checkout.transaction.updateStatus not registered')
+  return handler.execute(baseInput(status), makeContext(em))
+}
+
+describe('updateTransactionStatusCommand — state-machine guard', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  describe('valid transitions', () => {
+    it('processing → completed: calls nativeUpdate with status=processing in the WHERE clause', async () => {
+      const transaction = makeTransaction('processing')
+      const em = makeMockEm(transaction, 1)
+
+      await runUpdateStatus(em, 'completed')
+
+      expect(em.nativeUpdate).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({
+          id: TX_ID,
+          organizationId: ORG_ID,
+          tenantId: TENANT_ID,
+          status: 'processing', // pins the current status for atomicity
+        }),
+        expect.objectContaining({ status: 'completed' }),
+      )
+    })
+
+    it('processing → completed: emits checkout.transaction.completed event', async () => {
+      const transaction = makeTransaction('processing')
+      const em = makeMockEm(transaction, 1)
+
+      await runUpdateStatus(em, 'completed')
+
+      expect(emitCheckoutEvent).toHaveBeenCalledWith(
+        'checkout.transaction.completed',
+        expect.any(Object),
+      )
+    })
+
+    it('pending → processing: nativeUpdate is called with correct WHERE', async () => {
+      const transaction = makeTransaction('pending')
+      const em = makeMockEm(transaction, 1)
+
+      await runUpdateStatus(em, 'processing')
+
+      expect(em.nativeUpdate).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ status: 'pending' }),
+        expect.objectContaining({ status: 'processing' }),
+      )
+    })
+
+    it('pending → processing: does NOT emit a terminal event', async () => {
+      const transaction = makeTransaction('pending')
+      const em = makeMockEm(transaction, 1)
+
+      await runUpdateStatus(em, 'processing')
+
+      expect(emitCheckoutEvent).not.toHaveBeenCalledWith(
+        'checkout.transaction.completed',
+        expect.any(Object),
+      )
+      expect(emitCheckoutEvent).not.toHaveBeenCalledWith(
+        'checkout.transaction.failed',
+        expect.any(Object),
+      )
+    })
+  })
+
+  describe('regression guard — terminal → non-terminal (the race condition)', () => {
+    it('completed → processing: throws 409 with code invalid_status_transition', async () => {
+      expect.assertions(3)
+      const transaction = makeTransaction('completed')
+      const em = makeMockEm(transaction, 1)
+
+      try {
+        await runUpdateStatus(em, 'processing')
+      } catch (err) {
+        const error = err as { status?: number; body?: Record<string, unknown> }
+        expect(error.status).toBe(409)
+        expect(error.body?.code).toBe('invalid_status_transition')
+        expect(em.nativeUpdate).not.toHaveBeenCalled()
+      }
+    })
+
+    it('completed → failed: throws 409', async () => {
+      expect.assertions(2)
+      const transaction = makeTransaction('completed')
+      const em = makeMockEm(transaction, 1)
+
+      try {
+        await runUpdateStatus(em, 'failed')
+      } catch (err) {
+        const error = err as { status?: number; body?: Record<string, unknown> }
+        expect(error.status).toBe(409)
+        expect(em.nativeUpdate).not.toHaveBeenCalled()
+      }
+    })
+
+    it('expired → processing: throws 409', async () => {
+      expect.assertions(2)
+      const transaction = makeTransaction('expired')
+      const em = makeMockEm(transaction, 1)
+
+      try {
+        await runUpdateStatus(em, 'processing')
+      } catch (err) {
+        const error = err as { status?: number; body?: Record<string, unknown> }
+        expect(error.status).toBe(409)
+        expect(em.nativeUpdate).not.toHaveBeenCalled()
+      }
+    })
+
+    it('failed → completed: throws 409', async () => {
+      expect.assertions(2)
+      const transaction = makeTransaction('failed')
+      const em = makeMockEm(transaction, 1)
+
+      try {
+        await runUpdateStatus(em, 'completed')
+      } catch (err) {
+        const error = err as { status?: number; body?: Record<string, unknown> }
+        expect(error.status).toBe(409)
+        expect(em.nativeUpdate).not.toHaveBeenCalled()
+      }
+    })
+  })
+
+  describe('TOCTOU guard — nativeUpdate returns 0 (concurrent write wins)', () => {
+    it('nativeUpdate=0 throws 409 with code concurrent_status_update', async () => {
+      expect.assertions(5)
+      // Transaction is still processing from our read, but another writer won
+      // the race and set status to completed. The post-CAS re-read (refresh:true)
+      // should return the winner's status, not the stale identity-mapped value.
+      const transaction = makeTransaction('processing')
+      const em = makeMockEm(transaction, 0, 'completed')
+
+      try {
+        await runUpdateStatus(em, 'completed')
+      } catch (err) {
+        const error = err as { status?: number; body?: Record<string, unknown> }
+        expect(error.status).toBe(409)
+        expect(error.body?.code).toBe('concurrent_status_update')
+        expect(error.body?.expectedStatus).toBe('processing')
+        // currentStatus must reflect the winning writer's value, not the stale snapshot
+        expect(error.body?.currentStatus).toBe('completed')
+        // The terminal event must NOT be emitted when the update was a no-op
+        expect(emitCheckoutEvent).not.toHaveBeenCalledWith(
+          'checkout.transaction.completed',
+          expect.any(Object),
+        )
+      }
+    })
+
+    it('nativeUpdate=0 does NOT emit any event', async () => {
+      expect.assertions(1)
+      const transaction = makeTransaction('processing')
+      const em = makeMockEm(transaction, 0)
+
+      try {
+        await runUpdateStatus(em, 'completed')
+      } catch {
+        // Expected 409 — assert no events were emitted
+        expect(emitCheckoutEvent).not.toHaveBeenCalled()
+      }
+    })
+  })
+
+  describe('same-state transitions (idempotency support)', () => {
+    it('processing → processing: succeeds and calls nativeUpdate', async () => {
+      const transaction = makeTransaction('processing')
+      const em = makeMockEm(transaction, 1)
+
+      await runUpdateStatus(em, 'processing')
+
+      expect(em.nativeUpdate).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ status: 'processing' }),
+        expect.objectContaining({ status: 'processing' }),
+      )
+    })
+
+    it('completed → completed: succeeds and calls nativeUpdate', async () => {
+      const transaction = makeTransaction('completed')
+      const em = makeMockEm(transaction, 1)
+
+      await runUpdateStatus(em, 'completed')
+
+      expect(em.nativeUpdate).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ status: 'completed' }),
+        expect.objectContaining({ status: 'completed' }),
+      )
+    })
+
+    it('completed → completed: does NOT re-emit checkout.transaction.completed (idempotent redelivery guard)', async () => {
+      const transaction = makeTransaction('completed')
+      const em = makeMockEm(transaction, 1)
+
+      await runUpdateStatus(em, 'completed')
+
+      expect(emitCheckoutEvent).not.toHaveBeenCalledWith(
+        'checkout.transaction.completed',
+        expect.any(Object),
+      )
+    })
+
+    it('authorized → captured (both → completed): CAS succeeds but terminal event is NOT re-emitted', async () => {
+      // Both payment_gateways.payment.authorized and .captured map to 'completed'.
+      // The second delivery (captured) finds the transaction already completed;
+      // the CAS still succeeds (same-state), but checkout.transaction.completed
+      // must NOT fire a second time so the customer does not receive a duplicate notification.
+      const transaction = makeTransaction('completed')
+      const em = makeMockEm(transaction, 1)
+
+      await runUpdateStatus(em, 'completed')
+
+      expect(em.nativeUpdate).toHaveBeenCalledTimes(1)
+      expect(emitCheckoutEvent).not.toHaveBeenCalledWith(
+        'checkout.transaction.completed',
+        expect.any(Object),
+      )
+    })
+  })
+})
+

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

@@ -520,5 +520,9 @@ registerCommand(updateLinkCommand)
 registerCommand(deleteLinkCommand)
 
 export function serializeLinkRecord(record: CheckoutLink) {
-  return serializeTemplateOrLink(record)
+  // completionCount is link-only state (templates have no completions), so it is
+  // added here rather than in the shared template/link serializer. It is the
+  // observable proof that a terminal transaction was applied exactly once, which
+  // TC-CHKT-043 asserts and could not previously read from any API.
+  return { ...serializeTemplateOrLink(record), completionCount: record.completionCount ?? 0 }
 }

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

@@ -12,6 +12,7 @@ import {
   parseCheckoutInput,
   toMoneyString,
 } from '../lib/utils'
+import { assertValidCheckoutStatusTransition } from '../lib/transaction-status-machine'
 
 function resolveTransactionScope(input: { tenantId?: string | null; organizationId?: string | null }) {
   if (!input.organizationId || !input.tenantId) {
@@ -168,11 +169,63 @@ const updateTransactionStatusCommand: CommandHandler<Record<string, unknown>, {
       const previousTerminal = isTerminalCheckoutStatus(previousStatus)
       const nextTerminal = isTerminalCheckoutStatus(nextStatus)
 
-      transaction.status = nextStatus
-      transaction.paymentStatus = parsed.paymentStatus ?? transaction.paymentStatus ?? null
-      transaction.gatewayTransactionId = parsed.gatewayTransactionId ?? transaction.gatewayTransactionId ?? null
-      await tx.flush()
+      // State-machine guard: reject any transition not permitted by the
+      // VALID_CHECKOUT_TRANSITIONS map (e.g. completed → processing).
+      // This runs inside the DB transaction so the check and the write share
+      // the same serialisable snapshot.
+      assertValidCheckoutStatusTransition(previousStatus, nextStatus)
+
+      // Resolve the new field values before the write.
+      const newPaymentStatus = parsed.paymentStatus ?? transaction.paymentStatus ?? null
+      const newGatewayTransactionId = parsed.gatewayTransactionId ?? transaction.gatewayTransactionId ?? null
+
+      // Atomic compare-and-swap: the WHERE clause pins the current status so
+      // a concurrent writer that already advanced the status to a terminal
+      // state will cause this update to match 0 rows — eliminating the TOCTOU
+      // window between the findOne above and this write.
+      const affected = await tx.nativeUpdate(
+        CheckoutTransaction,
+        {
+          id: parsed.id,
+          organizationId: scope.organizationId,
+          tenantId: scope.tenantId,
+          status: previousStatus,
+        },
+        {
+          status: nextStatus,
+          paymentStatus: newPaymentStatus,
+          gatewayTransactionId: newGatewayTransactionId,
+          updatedAt: new Date(),
+        },
+      )
+
+      if (affected === 0) {
+        // A concurrent writer already advanced the status. Force a DB round-trip
+        // (refresh: true bypasses the MikroORM identity map) so the reported
+        // currentStatus reflects the winning writer's value, not the stale snapshot.
+        const actualTx = await tx.findOne(
+          CheckoutTransaction,
+          { id: parsed.id, organizationId: scope.organizationId, tenantId: scope.tenantId },
+          { fields: ['status'], refresh: true },
+        )
+        throw new CrudHttpError(409, {
+          error: `[internal] Transaction status was already updated by a concurrent process (expected "${previousStatus}", actual "${actualTx?.status ?? 'unknown'}")`,
+          code: 'concurrent_status_update',
+          expectedStatus: previousStatus,
+          currentStatus: actualTx?.status ?? 'unknown',
+          requestedStatus: nextStatus,
+        })
+      }
 
+      // Sync the entity state in the unit of work by refreshing it.
+      // This loads the updated values (status, paymentStatus, gatewayTransactionId)
+      // from the DB and marks the entity as clean, avoiding a redundant second write
+      // during the subsequent tx.flush().
+      await tx.refresh(transaction)
+
+      // Only apply terminal link state and emit the terminal event when the
+      // status actually changes — prevents double-notification on idempotent
+      // redeliveries (e.g. authorized → captured, both mapping to 'completed').
       if (!previousTerminal && nextTerminal) {
         const { usageLimitReached } = applyTerminalTransactionState(link, nextStatus)
         await tx.flush()
@@ -182,7 +235,7 @@ const updateTransactionStatusCommand: CommandHandler<Record<string, unknown>, {
           usageLimitReachedLinkSlug = link.slug
         }
       }
-      if (nextTerminal) {
+      if (nextTerminal && previousStatus !== nextStatus) {
         terminalEventPayload = {
           transactionId: transaction.id,
           linkId: transaction.linkId,
@@ -200,14 +253,16 @@ const updateTransactionStatusCommand: CommandHandler<Record<string, unknown>, {
         }
       }
     })
-    if (parsed.status === 'completed') {
-      await emitCheckoutEvent('checkout.transaction.completed', terminalEventPayload ?? {}).catch(() => undefined)
-    } else if (parsed.status === 'failed') {
-      await emitCheckoutEvent('checkout.transaction.failed', terminalEventPayload ?? {}).catch(() => undefined)
-    } else if (parsed.status === 'cancelled') {
-      await emitCheckoutEvent('checkout.transaction.cancelled', terminalEventPayload ?? {}).catch(() => undefined)
-    } else if (parsed.status === 'expired') {
-      await emitCheckoutEvent('checkout.transaction.expired', terminalEventPayload ?? {}).catch(() => undefined)
+    if (terminalEventPayload !== null) {
+      if (parsed.status === 'completed') {
+        await emitCheckoutEvent('checkout.transaction.completed', terminalEventPayload).catch(() => undefined)
+      } else if (parsed.status === 'failed') {
+        await emitCheckoutEvent('checkout.transaction.failed', terminalEventPayload).catch(() => undefined)
+      } else if (parsed.status === 'cancelled') {
+        await emitCheckoutEvent('checkout.transaction.cancelled', terminalEventPayload).catch(() => undefined)
+      } else if (parsed.status === 'expired') {
+        await emitCheckoutEvent('checkout.transaction.expired', terminalEventPayload).catch(() => undefined)
+      }
     }
     if (emitUsageLimitReached && usageLimitReachedLinkId && usageLimitReachedLinkSlug) {
       await emitCheckoutEvent('checkout.link.usageLimitReached', {

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

@@ -139,7 +139,7 @@ export function CustomerFieldsEditor({ value, onChange, errors }: Props) {
 
   return (
     <div className="space-y-4">
-      <Alert variant="info">
+      <Alert status="information">
         <AlertDescription>
           {t('checkout.customerFieldsEditor.notices.defaultFields')}
         </AlertDescription>
@@ -328,7 +328,7 @@ export function CustomerFieldsEditor({ value, onChange, errors }: Props) {
           </div>
         ) : (
           <div className="px-4 py-8">
-            <Alert variant="info">
+            <Alert status="information">
               <AlertDescription>
                 {t('checkout.customerFieldsEditor.notices.empty')}
               </AlertDescription>

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

@@ -84,7 +84,7 @@ export function GatewaySettingsFields({ providerKey, value, onChange }: Props) {
   const fields = descriptor?.sessionConfig?.fields ?? []
   if (!providerKey) {
     return (
-      <Alert variant="info">
+      <Alert status="information">
         <AlertDescription>
           {t('checkout.gatewaySettings.notices.chooseProvider')}
         </AlertDescription>
@@ -93,7 +93,7 @@ export function GatewaySettingsFields({ providerKey, value, onChange }: Props) {
   }
   if (!fields.length) {
     return (
-      <Alert variant="info">
+      <Alert status="information">
         <AlertDescription>
           {t('checkout.gatewaySettings.notices.noSettings')}
         </AlertDescription>

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

@@ -408,7 +408,7 @@ function PriceListEditor({
 
   return (
     <div className="space-y-4">
-      <Alert variant="info">
+      <Alert status="information">
         <AlertDescription>
           {t('checkout.linkTemplateForm.priceList.notices.singleCurrency')}
         </AlertDescription>
@@ -486,7 +486,7 @@ function PriceListEditor({
           </div>
         ) : (
           <div className="px-4 py-8">
-            <Alert variant="info">
+            <Alert status="information">
               <AlertDescription>
                 {t('checkout.linkTemplateForm.priceList.notices.empty')}
               </AlertDescription>
@@ -946,7 +946,7 @@ function CustomerDetailsSection({ values, setValue, errors }: CrudFormGroupCompo
 
       {collectCustomerDetails ? (
         <>
-          <Alert variant="info">
+          <Alert status="information">
             <AlertDescription>
               {t('checkout.linkTemplateForm.customerDetails.notices.simpleLink')}
             </AlertDescription>
@@ -959,7 +959,7 @@ function CustomerDetailsSection({ values, setValue, errors }: CrudFormGroupCompo
           />
         </>
       ) : (
-        <Alert variant="info">
+        <Alert status="information">
           <AlertDescription>
             {t('checkout.linkTemplateForm.customerDetails.notices.disabled')}
           </AlertDescription>
@@ -993,7 +993,7 @@ function LegalSection({ values, setValue, errors }: CrudFormGroupComponentProps)
 
   return (
     <div className="space-y-4">
-      <Alert variant="info">
+      <Alert status="information">
         <AlertDescription>
           {t('checkout.linkTemplateForm.legal.notice')}
         </AlertDescription>
@@ -1103,7 +1103,7 @@ function MessagesSection({ values, setValue, errors }: CrudFormGroupComponentPro
 
   return (
     <div className="space-y-4">
-      <Alert variant="info">
+      <Alert status="information">
         <AlertDescription>
           {t('checkout.linkTemplateForm.messages.notice')}
         </AlertDescription>
@@ -1202,7 +1202,7 @@ function EmailsSection({ values, setValue, errors }: CrudFormGroupComponentProps
 
   return (
     <div className="space-y-4">
-      <Alert variant="info">
+      <Alert status="information">
         <AlertDescription>
           {t('checkout.linkTemplateForm.emails.notice')}
         </AlertDescription>
@@ -1557,7 +1557,7 @@ export function LinkTemplateForm({ mode, recordId }: Props) {
     [mode, recordId],
   )
   const lockedNotice = isLocked ? (
-    <Alert variant="warning">
+    <Alert status="warning">
       <AlertTitle>{t('checkout.linkTemplateForm.locked.title')}</AlertTitle>
       <AlertDescription>{t('checkout.linkTemplateForm.locked.description')}</AlertDescription>
     </Alert>

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

@@ -175,7 +175,7 @@ export function LogoUploadField({ entityId, recordId, attachmentId, logoUrl, err
       </div>
 
       {attachmentId ? (
-        <Alert variant="info">
+        <Alert status="information">
           <AlertDescription>
             {t('checkout.logoUpload.notices.attachmentWins')}
           </AlertDescription>