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

package/src/modules/checkout/lib/transaction-status-machine.ts

@@ -0,0 +1,71 @@
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import type { CheckoutTransaction } from '../data/entities'
+
+/**
+ * Allowed status transitions for a CheckoutTransaction.
+ *
+ * Terminal states (completed, failed, cancelled, expired) have an empty
+ * allowed-set, meaning NO transition out of them is permitted.  This prevents
+ * the race condition where the submit route's late `updateStatus('processing')`
+ * call overwrites a `'completed'` status that the gateway webhook set first.
+ *
+ * Allowed path:
+ *   pending     ──► processing  (transaction created, payment session initiated)
+ *   pending     ──► completed   (captured webhook arrives before processing state)
+ *   processing  ──► completed   (webhook: payment captured)
+ *   processing  ──► failed      (webhook or session error)
+ *   processing  ──► cancelled   (customer or merchant cancellation)
+ *   processing  ──► expired     (expiry worker)
+ *
+ * Rejected (regression guard):
+ *   completed ──► *   REJECTED
+ *   failed    ──► *   REJECTED
+ *   cancelled ──► *   REJECTED
+ *   expired   ──► *   REJECTED
+ */
+export const VALID_CHECKOUT_TRANSITIONS: Record<CheckoutTransaction['status'], CheckoutTransaction['status'][]> = {
+  pending: ['processing', 'completed', 'failed', 'cancelled', 'expired'],
+  processing: ['completed', 'failed', 'cancelled', 'expired'],
+  // Terminal states — no transitions out
+  completed: [],
+  failed: [],
+  cancelled: [],
+  expired: [],
+}
+
+/**
+ * Returns `true` when transitioning from `from` to `to` is allowed by the
+ * state machine. Same-state transitions are allowed as safe no-ops to support
+ * idempotency.
+ */
+export function isValidCheckoutStatusTransition(
+  from: CheckoutTransaction['status'],
+  to: CheckoutTransaction['status'],
+): boolean {
+  if (from === to) return true
+  const allowed = VALID_CHECKOUT_TRANSITIONS[from]
+  if (!allowed) return false
+  return allowed.includes(to)
+}
+
+/**
+ * Throws a structured 409 Conflict when the requested status transition is
+ * not allowed by the state machine.  The error body is compatible with the
+ * `conflict` error shape that the frontend handles.
+ *
+ * This must be called **inside** a database transaction so that the check and
+ * the subsequent write are atomic.  The atomic `nativeUpdate` WHERE-clause
+ * provides the TOCTOU safety net; this function is the human-readable guard.
+ */
+export function assertValidCheckoutStatusTransition(
+  from: CheckoutTransaction['status'],
+  to: CheckoutTransaction['status'],
+): void {
+  if (isValidCheckoutStatusTransition(from, to)) return
+  throw new CrudHttpError(409, {
+    error: `[internal] Cannot transition payment from "${from}" to "${to}"`,
+    code: 'invalid_status_transition',
+    currentStatus: from,
+    requestedStatus: to,
+  })
+}

package/src/modules/checkout/search.ts

@@ -1,4 +1,5 @@
 import type { SearchModuleConfig } from '@open-mercato/shared/modules/search'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { CHECKOUT_ENTITY_IDS } from './lib/constants'
 
 function asSearchText(value: unknown): string {
@@ -34,15 +35,52 @@ export const searchConfig: SearchModuleConfig = {
         searchable: ['name', 'title'],
         excluded: ['passwordHash', 'gatewaySettings', 'customerFieldsSchema'],
       },
+      buildSource: async (ctx) => {
+        const { t } = await resolveTranslations()
+        const linkTemplate = t('checkout.search.subtitle.linkTemplate', 'Link Template')
+        return {
+          text: [`${asSearchText(ctx.record.name)}: ${asSearchText(ctx.record.title)}`],
+          presenter: { title: asSearchText(ctx.record.name), subtitle: linkTemplate },
+          checksumSource: { record: ctx.record, customFields: ctx.customFields },
+        }
+      },
+      formatResult: async (ctx) => {
+        const { t } = await resolveTranslations()
+        return {
+          title: asSearchText(ctx.record.name),
+          subtitle: t('checkout.search.subtitle.linkTemplate', 'Link Template'),
+          icon: 'lucide:file-text',
+        }
+      },
+    },
+    {
+      entityId: CHECKOUT_ENTITY_IDS.transaction,
+      enabled: true,
+      priority: 6,
+      fieldPolicy: {
+        searchable: ['email', 'firstName', 'lastName'],
+      },
       buildSource: async (ctx) => ({
-        text: [`${asSearchText(ctx.record.name)}: ${asSearchText(ctx.record.title)}`],
-        presenter: { title: asSearchText(ctx.record.name), subtitle: 'Link Template' },
-        checksumSource: { record: ctx.record, customFields: ctx.customFields },
+        text: [
+          asSearchText(ctx.record.email),
+          asSearchText(ctx.record.firstName),
+          asSearchText(ctx.record.lastName),
+        ],
+        fields: {
+          email: ctx.record.email,
+          first_name: ctx.record.firstName,
+          last_name: ctx.record.lastName,
+        },
+        presenter: {
+          title: asSearchText(ctx.record.email),
+          subtitle: `${asSearchText(ctx.record.firstName)} ${asSearchText(ctx.record.lastName)}`.trim(),
+        },
+        checksumSource: { record: ctx.record },
       }),
       formatResult: async (ctx) => ({
-        title: asSearchText(ctx.record.name),
-        subtitle: 'Link Template',
-        icon: 'lucide:file-text',
+        title: asSearchText(ctx.record.email),
+        subtitle: `${asSearchText(ctx.record.firstName)} ${asSearchText(ctx.record.lastName)}`.trim(),
+        icon: 'lucide:receipt',
       }),
     },
   ],

package/src/modules/checkout/setup.ts

@@ -1,14 +1,65 @@
 import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+import { createHash } from 'node:crypto'
 import { ensureCheckoutFieldsetsAndDefinitions } from './seed/customFields'
 import { seedCheckoutExamples } from './seed/examples'
+import { CHECKOUT_EXPIRY_QUEUE } from './workers/transaction-expiry.worker'
 export { DEFAULT_CHECKOUT_CUSTOMER_FIELDS } from './lib/defaults'
 
+function stableUuidFromString(input: string): string {
+  const bytes = createHash('sha256').update(input).digest().subarray(0, 16)
+  bytes[6] = (bytes[6] & 0x0f) | 0x50
+  bytes[8] = (bytes[8] & 0x3f) | 0x80
+  const hex = Buffer.from(bytes).toString('hex')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`
+}
+
+type SchedulerServiceLike = {
+  register: (registration: {
+    id: string
+    name: string
+    description?: string
+    scopeType: 'organization'
+    organizationId: string
+    tenantId: string
+    scheduleType: 'cron' | 'interval'
+    scheduleValue: string
+    timezone?: string
+    targetType: 'queue'
+    targetQueue: string
+    targetPayload?: Record<string, unknown>
+    sourceType: 'module'
+    sourceModule: string
+    isEnabled?: boolean
+  }) => Promise<void>
+}
+
 export const setup: ModuleSetupConfig = {
   async seedDefaults(ctx) {
     await ensureCheckoutFieldsetsAndDefinitions(ctx.em, {
       tenantId: ctx.tenantId,
       organizationId: ctx.organizationId,
     })
+
+    const cradle = ctx.container as { hasRegistration?: (name: string) => boolean }
+    if (typeof cradle.hasRegistration !== 'function' || !cradle.hasRegistration('schedulerService')) return
+
+    const schedulerService = ctx.container.resolve('schedulerService') as SchedulerServiceLike
+    await schedulerService.register({
+      id: stableUuidFromString(`checkout:transaction-expiry:${ctx.tenantId}:${ctx.organizationId}`),
+      name: 'Checkout transaction expiry',
+      description: 'Marks stale checkout transactions as expired and runs usage limit updates.',
+      scopeType: 'organization',
+      organizationId: ctx.organizationId,
+      tenantId: ctx.tenantId,
+      scheduleType: 'interval',
+      scheduleValue: '10m',
+      timezone: 'UTC',
+      targetType: 'queue',
+      targetQueue: CHECKOUT_EXPIRY_QUEUE,
+      sourceType: 'module',
+      sourceModule: 'checkout',
+      isEnabled: true,
+    })
   },
 
   defaultRoleFeatures: {

package/src/modules/checkout/subscribers/__tests__/search-reindex-transaction-created.test.ts

@@ -0,0 +1,29 @@
+import handle from '../search-reindex-transaction-created'
+
+const emitEvent = jest.fn(async () => undefined)
+const context = { resolve: jest.fn(() => ({ emitEvent })) }
+
+describe('checkout transaction search reindex subscriber', () => {
+  beforeEach(() => jest.clearAllMocks())
+
+  it('bridges transaction creation to the query index', async () => {
+    await handle({ transactionId: 'transaction-1', tenantId: 'tenant-1', organizationId: 'org-1' }, context)
+
+    expect(emitEvent).toHaveBeenCalledWith('query_index.upsert_one', {
+      entityType: 'checkout:checkout_transaction',
+      recordId: 'transaction-1',
+      organizationId: 'org-1',
+      tenantId: 'tenant-1',
+      crudAction: 'created',
+      coverageBaseDelta: 1,
+    }, { tenantId: 'tenant-1', organizationId: 'org-1' })
+  })
+
+  it('skips incomplete payloads and unavailable event buses', async () => {
+    await handle({ transactionId: 'transaction-1' }, context)
+    await handle({ transactionId: 'transaction-1', tenantId: 'tenant-1' }, {
+      resolve: () => { throw new Error('unavailable') },
+    })
+    expect(emitEvent).not.toHaveBeenCalled()
+  })
+})

package/src/modules/checkout/subscribers/search-reindex-transaction-created.ts

@@ -0,0 +1,39 @@
+export const metadata = {
+  event: 'checkout.transaction.created',
+  persistent: false,
+  id: 'checkout:query-index-reindex-transaction-created',
+}
+
+type Payload = {
+  transactionId?: string
+  tenantId?: string | null
+  organizationId?: string | null
+}
+
+type EventBus = { emitEvent: (name: string, body: unknown, options?: unknown) => Promise<void> }
+type HandlerContext = { resolve: <T = unknown>(name: string) => T }
+
+export default async function handle(payload: Payload, ctx: HandlerContext): Promise<void> {
+  const recordId = typeof payload.transactionId === 'string' ? payload.transactionId : null
+  const tenantId = typeof payload.tenantId === 'string' ? payload.tenantId : null
+  if (!recordId || !tenantId) return
+
+  let eventBus: EventBus | null = null
+  try {
+    eventBus = ctx.resolve<EventBus>('eventBus')
+  } catch {
+    return
+  }
+
+  await eventBus.emitEvent('query_index.upsert_one', {
+    entityType: 'checkout:checkout_transaction',
+    recordId,
+    organizationId: payload.organizationId ?? null,
+    tenantId,
+    crudAction: 'created',
+    coverageBaseDelta: 1,
+  }, {
+    tenantId,
+    organizationId: payload.organizationId ?? null,
+  }).catch(() => undefined)
+}

package/src/modules/checkout/workers/__tests__/transaction-expiry.worker.test.ts

@@ -0,0 +1,124 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals'
+import type { JobContext, QueuedJob } from '@open-mercato/queue'
+import { CheckoutTransaction } from '../../data/entities'
+import type { CheckoutExpiryJob } from '../transaction-expiry.worker'
+
+const findWithDecryption = jest.fn()
+jest.mock('@open-mercato/shared/lib/encryption/find', () => ({
+  findWithDecryption: (...args: unknown[]) => findWithDecryption(...args),
+}))
+
+describe('checkout transaction-expiry worker', () => {
+  const mockCommandBus = {
+    execute: jest.fn().mockResolvedValue({ ok: true }),
+  }
+
+  type MockEntityManager = {
+    fork: () => MockEntityManager
+  }
+
+  const mockEm: MockEntityManager = {
+    fork: () => mockEm,
+  }
+
+  const resolve = <ResolvedValue = unknown>(name: string): ResolvedValue => {
+    if (name === 'em') return mockEm as ResolvedValue
+    if (name === 'commandBus') return mockCommandBus as ResolvedValue
+    throw new Error(`[internal] Missing dependency: ${name}`)
+  }
+
+  const mockContext: JobContext & { resolve: typeof resolve } = {
+    resolve,
+    jobId: 'job-1',
+    attemptNumber: 1,
+    queueName: 'checkout-transaction-expiry',
+  }
+
+  const baseJob = {
+    id: 'job-1',
+    createdAt: '2026-08-01T00:00:00.000Z',
+  }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('throws an error if tenantId or organizationId is missing', async () => {
+    const { default: handle } = await import('../transaction-expiry.worker')
+
+    await expect(
+      handle(
+        {
+          ...baseJob,
+          payload: { batchSize: 10 },
+        } as unknown as QueuedJob<CheckoutExpiryJob>,
+        mockContext,
+      ),
+    ).rejects.toThrow('[internal] tenantId and organizationId are required in CheckoutExpiryJob')
+
+    expect(findWithDecryption).not.toHaveBeenCalled()
+  })
+
+  it('queries only transactions matching the payload tenantId and organizationId and passes decryption scope', async () => {
+    const { default: handle } = await import('../transaction-expiry.worker')
+
+    const mockTransactions = [
+      {
+        id: 'txn-1',
+        organizationId: 'org-123',
+        tenantId: 'tenant-456',
+      },
+      {
+        id: 'txn-2',
+        organizationId: 'org-123',
+        tenantId: 'tenant-456',
+      },
+    ]
+
+    findWithDecryption.mockResolvedValueOnce(mockTransactions)
+
+    await handle(
+      {
+        ...baseJob,
+        payload: {
+          batchSize: 50,
+          tenantId: 'tenant-456',
+          organizationId: 'org-123',
+        },
+      } satisfies QueuedJob<CheckoutExpiryJob>,
+      mockContext,
+    )
+
+    expect(findWithDecryption).toHaveBeenCalledWith(
+      mockEm,
+      CheckoutTransaction,
+      expect.objectContaining({
+        status: 'processing',
+        tenantId: 'tenant-456',
+        organizationId: 'org-123',
+      }),
+      expect.objectContaining({
+        limit: 50,
+      }),
+      {
+        tenantId: 'tenant-456',
+        organizationId: 'org-123',
+      },
+    )
+
+    expect(mockCommandBus.execute).toHaveBeenCalledTimes(2)
+    expect(mockCommandBus.execute).toHaveBeenNthCalledWith(
+      1,
+      'checkout.transaction.updateStatus',
+      expect.objectContaining({
+        input: {
+          id: 'txn-1',
+          status: 'expired',
+          paymentStatus: 'expired',
+          organizationId: 'org-123',
+          tenantId: 'tenant-456',
+        },
+      }),
+    )
+  })
+})

package/src/modules/checkout/workers/transaction-expiry.worker.ts

@@ -14,6 +14,8 @@ const EXPIRY_TIMEOUT_MS = 2 * 60 * 60 * 1000 // 2 hours
 
 export type CheckoutExpiryJob = {
   batchSize?: number
+  tenantId: string
+  organizationId: string
 }
 
 export const metadata: WorkerMeta = {
@@ -32,14 +34,23 @@ export default async function handle(job: QueuedJob<CheckoutExpiryJob>, ctx: Han
   const batchSize = job.payload?.batchSize ?? 100
   const cutoff = new Date(Date.now() - EXPIRY_TIMEOUT_MS)
 
+  if (!job.payload?.tenantId || !job.payload?.organizationId) {
+    throw new Error('[internal] tenantId and organizationId are required in CheckoutExpiryJob')
+  }
+
+  const { tenantId, organizationId } = job.payload
+
   const staleTransactions = await findWithDecryption(
     em,
     CheckoutTransaction,
     {
       status: 'processing',
       createdAt: { $lt: cutoff },
+      tenantId,
+      organizationId,
     },
     { limit: batchSize, orderBy: { createdAt: 'ASC' } },
+    { tenantId, organizationId },
   )
 
   for (const transaction of staleTransactions) {