@open-mercato/checkout 0.6.7-develop.6842.1.8cd8a8883c → 0.6.7-develop.6859.1.e4727b568a

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/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/lib/__tests__/transaction-status-machine.test.ts

@@ -0,0 +1,152 @@
+/** @jest-environment node */
+
+import {
+  VALID_CHECKOUT_TRANSITIONS,
+  assertValidCheckoutStatusTransition,
+  isValidCheckoutStatusTransition,
+} from '../transaction-status-machine'
+
+describe('VALID_CHECKOUT_TRANSITIONS', () => {
+  it('pending can transition to processing, completed, failed, cancelled, expired', () => {
+    expect(VALID_CHECKOUT_TRANSITIONS.pending).toEqual(
+      expect.arrayContaining(['processing', 'completed', 'failed', 'cancelled', 'expired']),
+    )
+  })
+
+  it('processing can transition to completed, failed, cancelled, expired', () => {
+    expect(VALID_CHECKOUT_TRANSITIONS.processing).toEqual(
+      expect.arrayContaining(['completed', 'failed', 'cancelled', 'expired']),
+    )
+  })
+
+  it('terminal states have no allowed transitions', () => {
+    expect(VALID_CHECKOUT_TRANSITIONS.completed).toHaveLength(0)
+    expect(VALID_CHECKOUT_TRANSITIONS.failed).toHaveLength(0)
+    expect(VALID_CHECKOUT_TRANSITIONS.cancelled).toHaveLength(0)
+    expect(VALID_CHECKOUT_TRANSITIONS.expired).toHaveLength(0)
+  })
+})
+
+describe('isValidCheckoutStatusTransition', () => {
+  it('pending -> processing is valid', () => {
+    expect(isValidCheckoutStatusTransition('pending', 'processing')).toBe(true)
+  })
+
+  it('pending -> completed is valid (captured webhook arrives before processing)', () => {
+    expect(isValidCheckoutStatusTransition('pending', 'completed')).toBe(true)
+  })
+
+  it('pending -> failed is valid', () => {
+    expect(isValidCheckoutStatusTransition('pending', 'failed')).toBe(true)
+  })
+
+  it('pending -> cancelled is valid', () => {
+    expect(isValidCheckoutStatusTransition('pending', 'cancelled')).toBe(true)
+  })
+
+  it('pending -> expired is valid', () => {
+    expect(isValidCheckoutStatusTransition('pending', 'expired')).toBe(true)
+  })
+
+  it('processing -> completed is valid', () => {
+    expect(isValidCheckoutStatusTransition('processing', 'completed')).toBe(true)
+  })
+
+  it('processing -> failed is valid', () => {
+    expect(isValidCheckoutStatusTransition('processing', 'failed')).toBe(true)
+  })
+
+  it('processing -> cancelled is valid', () => {
+    expect(isValidCheckoutStatusTransition('processing', 'cancelled')).toBe(true)
+  })
+
+  it('processing -> expired is valid', () => {
+    expect(isValidCheckoutStatusTransition('processing', 'expired')).toBe(true)
+  })
+
+  it('completed -> processing is INVALID (regression guard)', () => {
+    expect(isValidCheckoutStatusTransition('completed', 'processing')).toBe(false)
+  })
+
+  it('completed -> failed is INVALID', () => {
+    expect(isValidCheckoutStatusTransition('completed', 'failed')).toBe(false)
+  })
+
+  it('completed -> pending is INVALID', () => {
+    expect(isValidCheckoutStatusTransition('completed', 'pending')).toBe(false)
+  })
+
+  it('failed -> processing is INVALID', () => {
+    expect(isValidCheckoutStatusTransition('failed', 'processing')).toBe(false)
+  })
+
+  it('failed -> completed is INVALID', () => {
+    expect(isValidCheckoutStatusTransition('failed', 'completed')).toBe(false)
+  })
+
+  it('cancelled -> processing is INVALID', () => {
+    expect(isValidCheckoutStatusTransition('cancelled', 'processing')).toBe(false)
+  })
+
+  it('expired -> processing is INVALID', () => {
+    expect(isValidCheckoutStatusTransition('expired', 'processing')).toBe(false)
+  })
+
+  it('expired -> completed is INVALID', () => {
+    expect(isValidCheckoutStatusTransition('expired', 'completed')).toBe(false)
+  })
+
+  it('pending -> pending is valid', () => {
+    expect(isValidCheckoutStatusTransition('pending', 'pending')).toBe(true)
+  })
+
+  it('processing -> processing is valid', () => {
+    expect(isValidCheckoutStatusTransition('processing', 'processing')).toBe(true)
+  })
+
+  it('completed -> completed is valid', () => {
+    expect(isValidCheckoutStatusTransition('completed', 'completed')).toBe(true)
+  })
+})
+
+describe('assertValidCheckoutStatusTransition', () => {
+  it('does not throw for a valid transition (pending -> processing)', () => {
+    expect(() => assertValidCheckoutStatusTransition('pending', 'processing')).not.toThrow()
+  })
+
+  it('does not throw for a valid transition (pending -> completed)', () => {
+    expect(() => assertValidCheckoutStatusTransition('pending', 'completed')).not.toThrow()
+  })
+
+  it('does not throw for a valid transition (processing -> completed)', () => {
+    expect(() => assertValidCheckoutStatusTransition('processing', 'completed')).not.toThrow()
+  })
+
+  it('throws a 409 CrudHttpError for completed -> processing', () => {
+    expect.assertions(3)
+    try {
+      assertValidCheckoutStatusTransition('completed', '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(error.body?.currentStatus).toBe('completed')
+    }
+  })
+
+  it('throws a 409 CrudHttpError for expired -> completed', () => {
+    expect.assertions(3)
+    try {
+      assertValidCheckoutStatusTransition('expired', 'completed')
+    } 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(error.body?.requestedStatus).toBe('completed')
+    }
+  })
+
+  it('does not throw for same-state transition (processing -> processing)', () => {
+    expect(() => assertValidCheckoutStatusTransition('processing', 'processing')).not.toThrow()
+  })
+})