@open-mercato/core 0.4.5-develop-995ce486fa → 0.4.5-develop-8a56591995

package/src/modules/progress/__tests__/progressService.test.ts

@@ -0,0 +1,377 @@
+import { createProgressService } from '../lib/progressServiceImpl'
+import { PROGRESS_EVENTS } from '../lib/events'
+import { calculateEta, calculateProgressPercent } from '../lib/progressService'
+import type { ProgressJob } from '../data/entities'
+
+const baseCtx = {
+  tenantId: '7f4c85ef-f8f7-4e53-9df1-42e95bd8d48e',
+  organizationId: null,
+  userId: '2d4a4c33-9c4b-4e39-8e15-0a3cd9a7f432',
+}
+
+const buildEm = () => {
+  const em = {
+    create: jest.fn(),
+    persistAndFlush: jest.fn().mockResolvedValue(undefined),
+    flush: jest.fn().mockResolvedValue(undefined),
+    findOne: jest.fn(),
+    findOneOrFail: jest.fn(),
+    find: jest.fn(),
+  }
+  return em
+}
+
+describe('progress service', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('createJob — creates entity, persists, emits JOB_CREATED', async () => {
+    const em = buildEm()
+    const eventBus = { emit: jest.fn().mockResolvedValue(undefined) }
+
+    em.create.mockImplementation((_entity, data) => ({ id: 'job-1', ...data }))
+
+    const service = createProgressService(em as never, eventBus)
+
+    const input = { jobType: 'import', name: 'Import contacts', totalCount: 100, cancellable: true }
+    const job = await service.createJob(input, baseCtx)
+
+    expect(job.id).toBe('job-1')
+    expect(job.status).toBe('pending')
+    expect(job.jobType).toBe('import')
+    expect(job.cancellable).toBe(true)
+    expect(em.persistAndFlush).toHaveBeenCalledWith(job)
+    expect(eventBus.emit).toHaveBeenCalledWith(
+      PROGRESS_EVENTS.JOB_CREATED,
+      expect.objectContaining({
+        jobId: 'job-1',
+        jobType: 'import',
+        name: 'Import contacts',
+        tenantId: baseCtx.tenantId,
+      })
+    )
+  })
+
+  it('startJob — sets running status, timestamps, emits JOB_STARTED', async () => {
+    const em = buildEm()
+    const eventBus = { emit: jest.fn().mockResolvedValue(undefined) }
+
+    const job = { id: 'job-1', status: 'pending', jobType: 'import' } as ProgressJob
+    em.findOneOrFail.mockResolvedValue(job)
+
+    const service = createProgressService(em as never, eventBus)
+    const result = await service.startJob('job-1', baseCtx)
+
+    expect(result.status).toBe('running')
+    expect(result.startedAt).toBeInstanceOf(Date)
+    expect(result.heartbeatAt).toBeInstanceOf(Date)
+    expect(em.flush).toHaveBeenCalled()
+    expect(eventBus.emit).toHaveBeenCalledWith(
+      PROGRESS_EVENTS.JOB_STARTED,
+      expect.objectContaining({ jobId: 'job-1', jobType: 'import', tenantId: baseCtx.tenantId })
+    )
+  })
+
+  it('updateProgress — auto-calculates progressPercent and ETA', async () => {
+    const em = buildEm()
+    const eventBus = { emit: jest.fn().mockResolvedValue(undefined) }
+
+    const job = {
+      id: 'job-1',
+      jobType: 'import',
+      processedCount: 0,
+      totalCount: 100,
+      progressPercent: 0,
+      startedAt: new Date(Date.now() - 10_000),
+      meta: null,
+    } as unknown as ProgressJob
+    em.findOneOrFail.mockResolvedValue(job)
+
+    const service = createProgressService(em as never, eventBus)
+    const result = await service.updateProgress('job-1', { processedCount: 50 }, baseCtx)
+
+    expect(result.processedCount).toBe(50)
+    expect(result.progressPercent).toBe(50)
+    expect(result.etaSeconds).toBeGreaterThan(0)
+    expect(result.heartbeatAt).toBeInstanceOf(Date)
+    expect(em.flush).toHaveBeenCalled()
+    expect(eventBus.emit).toHaveBeenCalledWith(
+      PROGRESS_EVENTS.JOB_UPDATED,
+      expect.objectContaining({ jobId: 'job-1', processedCount: 50, progressPercent: 50 })
+    )
+  })
+
+  it('updateProgress — uses explicit progressPercent when provided', async () => {
+    const em = buildEm()
+    const eventBus = { emit: jest.fn().mockResolvedValue(undefined) }
+
+    const job = {
+      id: 'job-1',
+      jobType: 'import',
+      processedCount: 0,
+      totalCount: 100,
+      progressPercent: 0,
+      startedAt: new Date(),
+      meta: null,
+    } as unknown as ProgressJob
+    em.findOneOrFail.mockResolvedValue(job)
+
+    const service = createProgressService(em as never, eventBus)
+    const result = await service.updateProgress('job-1', { processedCount: 50, progressPercent: 75 }, baseCtx)
+
+    expect(result.progressPercent).toBe(75)
+  })
+
+  it('updateProgress — merges meta instead of replacing', async () => {
+    const em = buildEm()
+    const eventBus = { emit: jest.fn().mockResolvedValue(undefined) }
+
+    const job = {
+      id: 'job-1',
+      jobType: 'import',
+      processedCount: 0,
+      totalCount: null,
+      progressPercent: 0,
+      startedAt: null,
+      meta: { existing: 'value' },
+    } as unknown as ProgressJob
+    em.findOneOrFail.mockResolvedValue(job)
+
+    const service = createProgressService(em as never, eventBus)
+    await service.updateProgress('job-1', { meta: { added: 'new' } }, baseCtx)
+
+    expect(job.meta).toEqual({ existing: 'value', added: 'new' })
+  })
+
+  it('incrementProgress — adds delta, recalculates percent, emits JOB_UPDATED', async () => {
+    const em = buildEm()
+    const eventBus = { emit: jest.fn().mockResolvedValue(undefined) }
+
+    const job = {
+      id: 'job-1',
+      jobType: 'import',
+      processedCount: 40,
+      totalCount: 100,
+      progressPercent: 40,
+      startedAt: new Date(Date.now() - 10_000),
+    } as unknown as ProgressJob
+    em.findOneOrFail.mockResolvedValue(job)
+
+    const service = createProgressService(em as never, eventBus)
+    const result = await service.incrementProgress('job-1', 10, baseCtx)
+
+    expect(result.processedCount).toBe(50)
+    expect(result.progressPercent).toBe(50)
+    expect(result.heartbeatAt).toBeInstanceOf(Date)
+    expect(em.flush).toHaveBeenCalled()
+    expect(eventBus.emit).toHaveBeenCalledWith(
+      PROGRESS_EVENTS.JOB_UPDATED,
+      expect.objectContaining({ jobId: 'job-1', processedCount: 50, progressPercent: 50 })
+    )
+  })
+
+  it('completeJob — sets completed status, progress 100%, emits JOB_COMPLETED', async () => {
+    const em = buildEm()
+    const eventBus = { emit: jest.fn().mockResolvedValue(undefined) }
+
+    const job = {
+      id: 'job-1',
+      jobType: 'import',
+      status: 'running',
+      progressPercent: 80,
+      etaSeconds: 5,
+      tenantId: baseCtx.tenantId,
+    } as unknown as ProgressJob
+    em.findOne.mockResolvedValue(job)
+
+    const service = createProgressService(em as never, eventBus)
+    const result = await service.completeJob('job-1', { resultSummary: { imported: 100 } }, baseCtx)
+
+    expect(result.status).toBe('completed')
+    expect(result.progressPercent).toBe(100)
+    expect(result.etaSeconds).toBe(0)
+    expect(result.finishedAt).toBeInstanceOf(Date)
+    expect(result.resultSummary).toEqual({ imported: 100 })
+    expect(em.flush).toHaveBeenCalled()
+    expect(em.findOne).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ id: 'job-1', tenantId: baseCtx.tenantId })
+    )
+    expect(eventBus.emit).toHaveBeenCalledWith(
+      PROGRESS_EVENTS.JOB_COMPLETED,
+      expect.objectContaining({ jobId: 'job-1', jobType: 'import', tenantId: baseCtx.tenantId })
+    )
+  })
+
+  it('failJob — sets failed status, records error, emits JOB_FAILED', async () => {
+    const em = buildEm()
+    const eventBus = { emit: jest.fn().mockResolvedValue(undefined) }
+
+    const job = {
+      id: 'job-1',
+      jobType: 'import',
+      status: 'running',
+      tenantId: baseCtx.tenantId,
+    } as unknown as ProgressJob
+    em.findOne.mockResolvedValue(job)
+
+    const service = createProgressService(em as never, eventBus)
+    const result = await service.failJob('job-1', { errorMessage: 'Network error', errorStack: 'stack...' }, baseCtx)
+
+    expect(result.status).toBe('failed')
+    expect(result.finishedAt).toBeInstanceOf(Date)
+    expect(result.errorMessage).toBe('Network error')
+    expect(result.errorStack).toBe('stack...')
+    expect(em.flush).toHaveBeenCalled()
+    expect(em.findOne).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ id: 'job-1', tenantId: baseCtx.tenantId })
+    )
+    expect(eventBus.emit).toHaveBeenCalledWith(
+      PROGRESS_EVENTS.JOB_FAILED,
+      expect.objectContaining({ jobId: 'job-1', errorMessage: 'Network error', tenantId: baseCtx.tenantId })
+    )
+  })
+
+  it('cancelJob (pending) — sets cancelled status immediately', async () => {
+    const em = buildEm()
+    const eventBus = { emit: jest.fn().mockResolvedValue(undefined) }
+
+    const job = {
+      id: 'job-1',
+      jobType: 'import',
+      status: 'pending',
+      cancellable: true,
+    } as unknown as ProgressJob
+    em.findOneOrFail.mockResolvedValue(job)
+
+    const service = createProgressService(em as never, eventBus)
+    const result = await service.cancelJob('job-1', baseCtx)
+
+    expect(result.status).toBe('cancelled')
+    expect(result.finishedAt).toBeInstanceOf(Date)
+    expect(result.cancelRequestedAt).toBeInstanceOf(Date)
+    expect(result.cancelledByUserId).toBe(baseCtx.userId)
+    expect(em.flush).toHaveBeenCalled()
+    expect(eventBus.emit).toHaveBeenCalledWith(
+      PROGRESS_EVENTS.JOB_CANCELLED,
+      expect.objectContaining({ jobId: 'job-1', tenantId: baseCtx.tenantId })
+    )
+  })
+
+  it('cancelJob (running) — sets cancelRequestedAt but keeps running status', async () => {
+    const em = buildEm()
+    const eventBus = { emit: jest.fn().mockResolvedValue(undefined) }
+
+    const job = {
+      id: 'job-1',
+      jobType: 'import',
+      status: 'running',
+      cancellable: true,
+    } as unknown as ProgressJob
+    em.findOneOrFail.mockResolvedValue(job)
+
+    const service = createProgressService(em as never, eventBus)
+    const result = await service.cancelJob('job-1', baseCtx)
+
+    expect(result.status).toBe('running')
+    expect(result.cancelRequestedAt).toBeInstanceOf(Date)
+    expect(result.cancelledByUserId).toBe(baseCtx.userId)
+    expect(result.finishedAt).toBeUndefined()
+    expect(eventBus.emit).toHaveBeenCalledWith(
+      PROGRESS_EVENTS.JOB_CANCELLED,
+      expect.objectContaining({ jobId: 'job-1' })
+    )
+  })
+
+  it('markStaleJobsFailed — marks stale jobs as failed, emits per job', async () => {
+    const em = buildEm()
+    const eventBus = { emit: jest.fn().mockResolvedValue(undefined) }
+
+    const staleJob1 = { id: 'stale-1', jobType: 'export', status: 'running', tenantId: baseCtx.tenantId } as unknown as ProgressJob
+    const staleJob2 = { id: 'stale-2', jobType: 'import', status: 'running', tenantId: baseCtx.tenantId } as unknown as ProgressJob
+    em.find.mockResolvedValue([staleJob1, staleJob2])
+
+    const service = createProgressService(em as never, eventBus)
+    const count = await service.markStaleJobsFailed(baseCtx.tenantId, 60)
+
+    expect(count).toBe(2)
+    expect(staleJob1.status).toBe('failed')
+    expect(staleJob1.finishedAt).toBeInstanceOf(Date)
+    expect(staleJob1.errorMessage).toContain('no heartbeat for 60 seconds')
+    expect(staleJob2.status).toBe('failed')
+    expect(em.flush).toHaveBeenCalled()
+    expect(em.find).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ tenantId: baseCtx.tenantId })
+    )
+    expect(eventBus.emit).toHaveBeenCalledTimes(2)
+    expect(eventBus.emit).toHaveBeenCalledWith(
+      PROGRESS_EVENTS.JOB_FAILED,
+      expect.objectContaining({ jobId: 'stale-1', stale: true })
+    )
+    expect(eventBus.emit).toHaveBeenCalledWith(
+      PROGRESS_EVENTS.JOB_FAILED,
+      expect.objectContaining({ jobId: 'stale-2', stale: true })
+    )
+  })
+
+  it('getRecentlyCompletedJobs — queries completed/failed jobs with tenant scope', async () => {
+    const em = buildEm()
+    const eventBus = { emit: jest.fn().mockResolvedValue(undefined) }
+
+    const completedJob = { id: 'done-1', status: 'completed', tenantId: baseCtx.tenantId } as unknown as ProgressJob
+    em.find.mockResolvedValue([completedJob])
+
+    const service = createProgressService(em as never, eventBus)
+    const result = await service.getRecentlyCompletedJobs(baseCtx)
+
+    expect(result).toEqual([completedJob])
+    expect(em.find).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        tenantId: baseCtx.tenantId,
+        status: { $in: ['completed', 'failed'] },
+        parentJobId: null,
+      }),
+      expect.objectContaining({ orderBy: { finishedAt: 'DESC' }, limit: 10 })
+    )
+  })
+})
+
+describe('calculateProgressPercent', () => {
+  it('returns correct percentage', () => {
+    expect(calculateProgressPercent(50, 100)).toBe(50)
+    expect(calculateProgressPercent(1, 3)).toBe(33)
+    expect(calculateProgressPercent(2, 3)).toBe(67)
+  })
+
+  it('clamps at 100', () => {
+    expect(calculateProgressPercent(150, 100)).toBe(100)
+  })
+
+  it('returns 0 for null or zero totalCount', () => {
+    expect(calculateProgressPercent(50, null)).toBe(0)
+    expect(calculateProgressPercent(50, 0)).toBe(0)
+  })
+})
+
+describe('calculateEta', () => {
+  it('returns null when processedCount is zero', () => {
+    expect(calculateEta(0, 100, new Date())).toBeNull()
+  })
+
+  it('returns null when totalCount is zero', () => {
+    expect(calculateEta(50, 0, new Date())).toBeNull()
+  })
+
+  it('calculates remaining seconds correctly', () => {
+    const startedAt = new Date(Date.now() - 10_000)
+    const eta = calculateEta(50, 100, startedAt)
+
+    expect(eta).not.toBeNull()
+    expect(eta!).toBeGreaterThan(0)
+    expect(eta!).toBeLessThanOrEqual(11)
+  })
+})

package/src/modules/progress/acl.ts

@@ -0,0 +1,29 @@
+export const features = [
+  {
+    id: 'progress.view',
+    title: 'View progress jobs',
+    module: 'progress',
+  },
+  {
+    id: 'progress.create',
+    title: 'Create progress jobs',
+    module: 'progress',
+  },
+  {
+    id: 'progress.update',
+    title: 'Update progress jobs',
+    module: 'progress',
+  },
+  {
+    id: 'progress.cancel',
+    title: 'Cancel progress jobs',
+    module: 'progress',
+  },
+  {
+    id: 'progress.manage',
+    title: 'Manage all progress jobs',
+    module: 'progress',
+  },
+]
+
+export default features

package/src/modules/progress/api/active/route.ts

@@ -0,0 +1,61 @@
+import { NextResponse } from 'next/server'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { ProgressJob } from '../../data/entities'
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['progress.view'] },
+}
+
+export const metadata = routeMetadata
+
+export async function GET(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth || !auth.tenantId) {
+    return NextResponse.json({ active: [], recentlyCompleted: [] }, { status: 401 })
+  }
+
+  const container = await createRequestContainer()
+  const progressService = container.resolve('progressService') as import('../../lib/progressService').ProgressService
+
+  const ctx = { tenantId: auth.tenantId, organizationId: auth.orgId }
+
+  const [jobs, recentlyCompleted] = await Promise.all([
+    progressService.getActiveJobs(ctx),
+    progressService.getRecentlyCompletedJobs(ctx),
+  ])
+
+  return NextResponse.json({
+    active: jobs.map(formatJob),
+    recentlyCompleted: recentlyCompleted.map(formatJob),
+  })
+}
+
+function formatJob(job: ProgressJob) {
+  return {
+    id: job.id,
+    jobType: job.jobType,
+    name: job.name,
+    description: job.description,
+    status: job.status,
+    progressPercent: job.progressPercent,
+    processedCount: job.processedCount,
+    totalCount: job.totalCount,
+    etaSeconds: job.etaSeconds,
+    cancellable: job.cancellable,
+    startedAt: job.startedAt?.toISOString() ?? null,
+    finishedAt: job.finishedAt?.toISOString() ?? null,
+    errorMessage: job.errorMessage,
+  }
+}
+
+export const openApi = {
+  GET: {
+    summary: 'Get active progress jobs',
+    description: 'Returns currently running jobs and recently completed jobs for the progress top bar.',
+    tags: ['Progress'],
+    responses: {
+      200: { description: 'Active and recently completed jobs' },
+    },
+  },
+}

package/src/modules/progress/api/jobs/[id]/route.ts

@@ -0,0 +1,136 @@
+import { NextResponse } from 'next/server'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { ProgressJob } from '../../../data/entities'
+import { updateProgressSchema } from '../../../data/validators'
+import type { ProgressService } from '../../../lib/progressService'
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['progress.view'] },
+  PUT: { requireAuth: true, requireFeatures: ['progress.update'] },
+  DELETE: { requireAuth: true, requireFeatures: ['progress.cancel'] },
+}
+
+export const metadata = routeMetadata
+
+export async function GET(req: Request, { params }: { params: { id: string } }) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth || !auth.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const container = await createRequestContainer()
+  const em = container.resolve('em') as EntityManager
+
+  const job = await em.findOne(ProgressJob, {
+    id: params.id,
+    tenantId: auth.tenantId,
+  })
+
+  if (!job) {
+    return NextResponse.json({ error: 'Not found' }, { status: 404 })
+  }
+
+  return NextResponse.json({
+    id: job.id,
+    jobType: job.jobType,
+    name: job.name,
+    description: job.description,
+    status: job.status,
+    progressPercent: job.progressPercent,
+    processedCount: job.processedCount,
+    totalCount: job.totalCount,
+    etaSeconds: job.etaSeconds,
+    cancellable: job.cancellable,
+    meta: job.meta,
+    resultSummary: job.resultSummary,
+    errorMessage: job.errorMessage,
+    startedByUserId: job.startedByUserId,
+    startedAt: job.startedAt?.toISOString() ?? null,
+    heartbeatAt: job.heartbeatAt?.toISOString() ?? null,
+    finishedAt: job.finishedAt?.toISOString() ?? null,
+    parentJobId: job.parentJobId,
+    partitionIndex: job.partitionIndex,
+    partitionCount: job.partitionCount,
+    createdAt: job.createdAt.toISOString(),
+    updatedAt: job.updatedAt.toISOString(),
+    tenantId: job.tenantId,
+    organizationId: job.organizationId,
+  })
+}
+
+export async function PUT(req: Request, { params }: { params: { id: string } }) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth || !auth.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const body = await req.json()
+  const parsed = updateProgressSchema.safeParse(body)
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid input', details: parsed.error.flatten() }, { status: 400 })
+  }
+
+  const container = await createRequestContainer()
+  const progressService = container.resolve('progressService') as ProgressService
+
+  const job = await progressService.updateProgress(params.id, parsed.data, {
+    tenantId: auth.tenantId,
+    organizationId: auth.orgId,
+    userId: auth.sub,
+  })
+
+  return NextResponse.json({ ok: true, progressPercent: job.progressPercent })
+}
+
+export async function DELETE(req: Request, { params }: { params: { id: string } }) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth || !auth.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const container = await createRequestContainer()
+  const progressService = container.resolve('progressService') as ProgressService
+
+  try {
+    await progressService.cancelJob(params.id, {
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+      userId: auth.sub,
+    })
+    return NextResponse.json({ ok: true })
+  } catch {
+    return NextResponse.json({ error: 'Cannot cancel this job' }, { status: 400 })
+  }
+}
+
+export const openApi = {
+  GET: {
+    summary: 'Get progress job details',
+    description: 'Returns full details of a specific progress job by ID.',
+    tags: ['Progress'],
+    responses: {
+      200: { description: 'Progress job details' },
+      404: { description: 'Job not found' },
+    },
+  },
+  PUT: {
+    summary: 'Update progress job',
+    description: 'Updates progress metrics and heartbeat for a running job.',
+    tags: ['Progress'],
+    responses: {
+      200: { description: 'Progress updated' },
+      400: { description: 'Invalid input' },
+    },
+  },
+  DELETE: {
+    summary: 'Cancel progress job',
+    description: 'Requests cancellation of a running or pending job.',
+    tags: ['Progress'],
+    responses: {
+      200: { description: 'Cancellation requested' },
+      400: { description: 'Cannot cancel this job' },
+    },
+  },
+}