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

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

@@ -0,0 +1,192 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+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 type { FilterQuery } from '@mikro-orm/core'
+import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
+import { ProgressJob } from '../../data/entities'
+import { createProgressJobSchema, listProgressJobsSchema } from '../../data/validators'
+import {
+  createProgressCrudOpenApi,
+  createPagedListResponseSchema,
+} from '../openapi'
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['progress.view'] },
+  POST: { requireAuth: true, requireFeatures: ['progress.create'] },
+}
+
+export const metadata = routeMetadata
+
+const listQuerySchema = listProgressJobsSchema
+
+type JobRow = {
+  id: string
+  jobType: string
+  name: string
+  description: string | null
+  status: string
+  progressPercent: number
+  processedCount: number
+  totalCount: number | null
+  etaSeconds: number | null
+  cancellable: boolean
+  startedAt: string | null
+  finishedAt: string | null
+  errorMessage: string | null
+  createdAt: string | null
+  tenantId: string
+  organizationId: string | null
+}
+
+const toRow = (job: ProgressJob): JobRow => ({
+  id: String(job.id),
+  jobType: String(job.jobType),
+  name: String(job.name),
+  description: job.description ?? null,
+  status: job.status,
+  progressPercent: job.progressPercent,
+  processedCount: job.processedCount,
+  totalCount: job.totalCount ?? null,
+  etaSeconds: job.etaSeconds ?? null,
+  cancellable: !!job.cancellable,
+  startedAt: job.startedAt ? job.startedAt.toISOString() : null,
+  finishedAt: job.finishedAt ? job.finishedAt.toISOString() : null,
+  errorMessage: job.errorMessage ?? null,
+  createdAt: job.createdAt ? job.createdAt.toISOString() : null,
+  tenantId: String(job.tenantId),
+  organizationId: job.organizationId ? String(job.organizationId) : null,
+})
+
+export async function GET(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth || !auth.tenantId) {
+    return NextResponse.json({ items: [], total: 0, page: 1, pageSize: 20, totalPages: 1 }, { status: 401 })
+  }
+
+  const url = new URL(req.url)
+  const parsed = listQuerySchema.safeParse({
+    status: url.searchParams.get('status') ?? undefined,
+    jobType: url.searchParams.get('jobType') ?? undefined,
+    parentJobId: url.searchParams.get('parentJobId') ?? undefined,
+    includeCompleted: url.searchParams.get('includeCompleted') ?? undefined,
+    completedSince: url.searchParams.get('completedSince') ?? undefined,
+    page: url.searchParams.get('page') ?? undefined,
+    pageSize: url.searchParams.get('pageSize') ?? undefined,
+    search: url.searchParams.get('search') ?? undefined,
+    sortField: url.searchParams.get('sortField') ?? undefined,
+    sortDir: url.searchParams.get('sortDir') ?? undefined,
+  })
+  if (!parsed.success) {
+    return NextResponse.json({ items: [], total: 0, page: 1, pageSize: 20, totalPages: 1 }, { status: 400 })
+  }
+
+  const container = await createRequestContainer()
+  const em = container.resolve('em') as EntityManager
+
+  const { status, jobType, parentJobId, includeCompleted, completedSince, page, pageSize, search, sortField, sortDir } = parsed.data
+  const filter: FilterQuery<ProgressJob> = {
+    tenantId: auth.tenantId,
+  }
+
+  if (auth.orgId) {
+    filter.organizationId = auth.orgId
+  }
+
+  if (status) {
+    const statusValues = status.split(',')
+    filter.status = statusValues.length > 1 ? { $in: statusValues as never } : status as never
+  } else if (includeCompleted !== 'true') {
+    filter.status = { $in: ['pending', 'running'] }
+  }
+
+  if (jobType) filter.jobType = jobType
+  if (parentJobId) filter.parentJobId = parentJobId
+  if (completedSince) filter.finishedAt = { $gte: new Date(completedSince) }
+
+  if (search) {
+    const escaped = escapeLikePattern(search)
+    filter.$or = [
+      { name: { $ilike: `%${escaped}%` } },
+      { jobType: { $ilike: `%${escaped}%` } },
+    ]
+  }
+
+  const fieldMap: Record<string, string> = {
+    createdAt: 'createdAt',
+    startedAt: 'startedAt',
+    finishedAt: 'finishedAt',
+  }
+  const orderBy: Record<string, 'ASC' | 'DESC'> = {}
+  if (sortField) {
+    const mapped = fieldMap[sortField] || 'createdAt'
+    orderBy[mapped] = sortDir === 'asc' ? 'ASC' : 'DESC'
+  } else {
+    orderBy.createdAt = 'DESC'
+  }
+
+  const [rows, total] = await em.findAndCount(ProgressJob, filter, {
+    orderBy,
+    limit: pageSize,
+    offset: (page - 1) * pageSize,
+  })
+  const items = rows.map(toRow)
+  const totalPages = Math.max(1, Math.ceil(total / pageSize))
+
+  return NextResponse.json({ items, total, page, pageSize, totalPages })
+}
+
+export async function POST(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth || !auth.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const body = await req.json()
+  const parsed = createProgressJobSchema.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 import('../../lib/progressService').ProgressService
+
+  const job = await progressService.createJob(parsed.data, {
+    tenantId: auth.tenantId,
+    organizationId: auth.orgId,
+    userId: auth.sub,
+  })
+
+  return NextResponse.json({ id: job.id }, { status: 201 })
+}
+
+const jobListItemSchema = z.object({
+  id: z.string().uuid(),
+  jobType: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  status: z.string(),
+  progressPercent: z.number(),
+  processedCount: z.number(),
+  totalCount: z.number().nullable(),
+  etaSeconds: z.number().nullable(),
+  cancellable: z.boolean(),
+  startedAt: z.string().nullable(),
+  finishedAt: z.string().nullable(),
+  errorMessage: z.string().nullable(),
+  createdAt: z.string().nullable(),
+  tenantId: z.string().uuid(),
+  organizationId: z.string().uuid().nullable(),
+})
+
+export const openApi = createProgressCrudOpenApi({
+  resourceName: 'ProgressJob',
+  pluralName: 'ProgressJobs',
+  querySchema: listQuerySchema,
+  listResponseSchema: createPagedListResponseSchema(jobListItemSchema),
+  create: {
+    schema: createProgressJobSchema,
+    description: 'Creates a new progress job for tracking a long-running operation.',
+  },
+})

package/src/modules/progress/api/openapi.ts

@@ -0,0 +1,28 @@
+import { type ZodTypeAny } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import {
+  createCrudOpenApiFactory,
+  createPagedListResponseSchema as createSharedPagedListResponseSchema,
+  defaultCreateResponseSchema as sharedDefaultCreateResponseSchema,
+  defaultOkResponseSchema as sharedDefaultOkResponseSchema,
+  type CrudOpenApiOptions,
+} from '@open-mercato/shared/lib/openapi/crud'
+
+export const defaultCreateResponseSchema = sharedDefaultCreateResponseSchema
+export const defaultOkResponseSchema = sharedDefaultOkResponseSchema
+
+export function createPagedListResponseSchema(itemSchema: ZodTypeAny) {
+  return createSharedPagedListResponseSchema(itemSchema, { paginationMetaOptional: true })
+}
+
+const buildProgressCrudOpenApi = createCrudOpenApiFactory({
+  defaultTag: 'Progress',
+  defaultCreateResponseSchema,
+  defaultOkResponseSchema,
+  makeListDescription: ({ pluralLower }) =>
+    `Returns a paginated collection of ${pluralLower} scoped to the authenticated tenant.`,
+})
+
+export function createProgressCrudOpenApi(options: CrudOpenApiOptions): OpenApiRouteDoc {
+  return buildProgressCrudOpenApi(options)
+}

package/src/modules/progress/data/entities.ts

@@ -0,0 +1,94 @@
+import { Entity, PrimaryKey, Property, Index, OptionalProps } from '@mikro-orm/core'
+
+export type ProgressJobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+
+// No deleted_at column: terminal statuses (completed, failed, cancelled) serve as logical soft-delete.
+// Old jobs should be purged via scheduled cleanup rather than soft-deleted individually.
+@Entity({ tableName: 'progress_jobs' })
+@Index({ name: 'progress_jobs_status_tenant_idx', properties: ['status', 'tenantId'] })
+@Index({ name: 'progress_jobs_type_tenant_idx', properties: ['jobType', 'tenantId'] })
+@Index({ name: 'progress_jobs_parent_idx', properties: ['parentJobId'] })
+export class ProgressJob {
+  [OptionalProps]?: 'status' | 'progressPercent' | 'processedCount' | 'cancellable' | 'createdAt' | 'updatedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'job_type', type: 'text' })
+  jobType!: string
+
+  @Property({ name: 'name', type: 'text' })
+  name!: string
+
+  @Property({ name: 'description', type: 'text', nullable: true })
+  description?: string | null
+
+  @Property({ name: 'status', type: 'text' })
+  status: ProgressJobStatus = 'pending'
+
+  @Property({ name: 'progress_percent', type: 'smallint' })
+  progressPercent: number = 0
+
+  @Property({ name: 'processed_count', type: 'int' })
+  processedCount: number = 0
+
+  @Property({ name: 'total_count', type: 'int', nullable: true })
+  totalCount?: number | null
+
+  @Property({ name: 'eta_seconds', type: 'int', nullable: true })
+  etaSeconds?: number | null
+
+  @Property({ name: 'started_by_user_id', type: 'uuid', nullable: true })
+  startedByUserId?: string | null
+
+  @Property({ name: 'started_at', type: Date, nullable: true })
+  startedAt?: Date | null
+
+  @Property({ name: 'heartbeat_at', type: Date, nullable: true })
+  heartbeatAt?: Date | null
+
+  @Property({ name: 'finished_at', type: Date, nullable: true })
+  finishedAt?: Date | null
+
+  @Property({ name: 'result_summary', type: 'json', nullable: true })
+  resultSummary?: Record<string, unknown> | null
+
+  @Property({ name: 'error_message', type: 'text', nullable: true })
+  errorMessage?: string | null
+
+  @Property({ name: 'error_stack', type: 'text', nullable: true })
+  errorStack?: string | null
+
+  @Property({ name: 'meta', type: 'json', nullable: true })
+  meta?: Record<string, unknown> | null
+
+  @Property({ name: 'cancellable', type: 'boolean' })
+  cancellable: boolean = false
+
+  @Property({ name: 'cancelled_by_user_id', type: 'uuid', nullable: true })
+  cancelledByUserId?: string | null
+
+  @Property({ name: 'cancel_requested_at', type: Date, nullable: true })
+  cancelRequestedAt?: Date | null
+
+  @Property({ name: 'parent_job_id', type: 'uuid', nullable: true })
+  parentJobId?: string | null
+
+  @Property({ name: 'partition_index', type: 'int', nullable: true })
+  partitionIndex?: number | null
+
+  @Property({ name: 'partition_count', type: 'int', nullable: true })
+  partitionCount?: number | null
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'organization_id', type: 'uuid', nullable: true })
+  organizationId?: string | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}

package/src/modules/progress/data/validators.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod'
+
+export const progressJobStatusSchema = z.enum(['pending', 'running', 'completed', 'failed', 'cancelled'])
+
+export const createProgressJobSchema = z.object({
+  jobType: z.string().min(1).max(100),
+  name: z.string().min(1).max(255),
+  description: z.string().max(1000).optional(),
+  totalCount: z.number().int().positive().optional(),
+  cancellable: z.boolean().optional().default(false),
+  meta: z.record(z.string(), z.unknown()).optional(),
+  parentJobId: z.string().uuid().optional(),
+  partitionIndex: z.number().int().min(0).optional(),
+  partitionCount: z.number().int().positive().optional(),
+})
+
+export const updateProgressSchema = z.object({
+  processedCount: z.number().int().min(0).optional(),
+  progressPercent: z.number().int().min(0).max(100).optional(),
+  totalCount: z.number().int().positive().optional(),
+  etaSeconds: z.number().int().min(0).optional(),
+  meta: z.record(z.string(), z.unknown()).optional(),
+})
+
+export const completeJobSchema = z.object({
+  resultSummary: z.record(z.string(), z.unknown()).optional(),
+})
+
+export const failJobSchema = z.object({
+  errorMessage: z.string().max(2000),
+  errorStack: z.string().max(10000).optional(),
+})
+
+export const listProgressJobsSchema = z.object({
+  status: z.string().optional(),
+  jobType: z.string().optional(),
+  parentJobId: z.string().uuid().optional(),
+  includeCompleted: z.enum(['true', 'false']).optional(),
+  completedSince: z.string().optional(),
+  page: z.coerce.number().min(1).default(1),
+  pageSize: z.coerce.number().min(1).max(100).default(20),
+  search: z.string().optional(),
+  sortField: z.enum(['createdAt', 'startedAt', 'finishedAt']).optional(),
+  sortDir: z.enum(['asc', 'desc']).optional(),
+})
+
+export type CreateProgressJobInput = z.infer<typeof createProgressJobSchema>
+export type UpdateProgressInput = z.infer<typeof updateProgressSchema>
+export type CompleteJobInput = z.infer<typeof completeJobSchema>
+export type FailJobInput = z.infer<typeof failJobSchema>
+export type ListProgressJobsInput = z.infer<typeof listProgressJobsSchema>

package/src/modules/progress/di.ts

@@ -0,0 +1,15 @@
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import type { EntityManager } from '@mikro-orm/core'
+import { createProgressService } from './lib/progressServiceImpl'
+
+export function register(container: AppContainer) {
+  container.register({
+    progressService: {
+      resolve: (c) => {
+        const em = c.resolve<EntityManager>('em')
+        const eventBus = c.resolve('eventBus') as { emit: (event: string, payload: Record<string, unknown>) => Promise<void> }
+        return createProgressService(em, eventBus)
+      },
+    },
+  })
+}

package/src/modules/progress/events.ts

@@ -0,0 +1,21 @@
+import { createModuleEvents } from '@open-mercato/shared/modules/events'
+
+export const events = [
+  { id: 'progress.job.created', label: 'Job Created', entity: 'job', category: 'crud' },
+  { id: 'progress.job.started', label: 'Job Started', entity: 'job', category: 'lifecycle' },
+  { id: 'progress.job.updated', label: 'Job Updated', entity: 'job', category: 'lifecycle' },
+  { id: 'progress.job.completed', label: 'Job Completed', entity: 'job', category: 'lifecycle' },
+  { id: 'progress.job.failed', label: 'Job Failed', entity: 'job', category: 'lifecycle' },
+  { id: 'progress.job.cancelled', label: 'Job Cancelled', entity: 'job', category: 'lifecycle' },
+] as const
+
+export const eventsConfig = createModuleEvents({
+  moduleId: 'progress',
+  events,
+})
+
+export const emitProgressEvent = eventsConfig.emit
+
+export type ProgressEventId = typeof events[number]['id']
+
+export default eventsConfig

package/src/modules/progress/i18n/de.json

@@ -0,0 +1,20 @@
+{
+  "progress.actions.cancel": "Abbrechen",
+  "progress.actions.dismiss": "Verwerfen",
+  "progress.actions.retry": "Wiederholen",
+  "progress.activeCount": "{count} Vorgänge laufen",
+  "progress.errors.alreadyFinished": "Vorgang ist bereits abgeschlossen",
+  "progress.errors.cannotCancel": "Dieser Vorgang kann nicht abgebrochen werden",
+  "progress.errors.notFound": "Vorgang nicht gefunden",
+  "progress.eta.hoursMinutes": "noch {hours}h {minutes}m",
+  "progress.eta.minutes": "noch {count}m",
+  "progress.eta.seconds": "noch {count}s",
+  "progress.processed": "verarbeitet",
+  "progress.recentlyCompleted": "{count} Vorgänge abgeschlossen",
+  "progress.status.cancelled": "Abgebrochen",
+  "progress.status.completed": "Abgeschlossen",
+  "progress.status.failed": "Fehlgeschlagen",
+  "progress.status.pending": "Ausstehend",
+  "progress.status.running": "Läuft",
+  "progress.title": "Fortschritt"
+}

package/src/modules/progress/i18n/en.json

@@ -0,0 +1,20 @@
+{
+  "progress.actions.cancel": "Cancel",
+  "progress.actions.dismiss": "Dismiss",
+  "progress.actions.retry": "Retry",
+  "progress.activeCount": "{count} operations running",
+  "progress.errors.alreadyFinished": "Job has already finished",
+  "progress.errors.cannotCancel": "This job cannot be cancelled",
+  "progress.errors.notFound": "Job not found",
+  "progress.eta.hoursMinutes": "{hours}h {minutes}m remaining",
+  "progress.eta.minutes": "{count}m remaining",
+  "progress.eta.seconds": "{count}s remaining",
+  "progress.processed": "processed",
+  "progress.recentlyCompleted": "{count} operations completed",
+  "progress.status.cancelled": "Cancelled",
+  "progress.status.completed": "Completed",
+  "progress.status.failed": "Failed",
+  "progress.status.pending": "Pending",
+  "progress.status.running": "Running",
+  "progress.title": "Progress"
+}

package/src/modules/progress/i18n/es.json

@@ -0,0 +1,20 @@
+{
+  "progress.actions.cancel": "Cancelar",
+  "progress.actions.dismiss": "Descartar",
+  "progress.actions.retry": "Reintentar",
+  "progress.activeCount": "{count} operaciones en curso",
+  "progress.errors.alreadyFinished": "La operación ya ha finalizado",
+  "progress.errors.cannotCancel": "Esta operación no se puede cancelar",
+  "progress.errors.notFound": "Operación no encontrada",
+  "progress.eta.hoursMinutes": "{hours}h {minutes}m restantes",
+  "progress.eta.minutes": "{count}m restantes",
+  "progress.eta.seconds": "{count}s restantes",
+  "progress.processed": "procesados",
+  "progress.recentlyCompleted": "{count} operaciones completadas",
+  "progress.status.cancelled": "Cancelado",
+  "progress.status.completed": "Completado",
+  "progress.status.failed": "Fallido",
+  "progress.status.pending": "Pendiente",
+  "progress.status.running": "En curso",
+  "progress.title": "Progreso"
+}

package/src/modules/progress/i18n/pl.json

@@ -0,0 +1,20 @@
+{
+  "progress.actions.cancel": "Anuluj",
+  "progress.actions.dismiss": "Odrzuć",
+  "progress.actions.retry": "Ponów",
+  "progress.activeCount": "{count} operacji w toku",
+  "progress.errors.alreadyFinished": "Zadanie zostało już zakończone",
+  "progress.errors.cannotCancel": "Tego zadania nie można anulować",
+  "progress.errors.notFound": "Nie znaleziono zadania",
+  "progress.eta.hoursMinutes": "pozostało {hours}h {minutes}m",
+  "progress.eta.minutes": "pozostało {count}m",
+  "progress.eta.seconds": "pozostało {count}s",
+  "progress.processed": "przetworzonych",
+  "progress.recentlyCompleted": "{count} operacji zakończonych",
+  "progress.status.cancelled": "Anulowane",
+  "progress.status.completed": "Zakończone",
+  "progress.status.failed": "Niepowodzenie",
+  "progress.status.pending": "Oczekuje",
+  "progress.status.running": "W toku",
+  "progress.title": "Postęp"
+}

package/src/modules/progress/index.ts

@@ -0,0 +1,11 @@
+import type { ModuleInfo } from '@open-mercato/shared/modules/registry'
+
+export const metadata: ModuleInfo = {
+  name: 'progress',
+  title: 'Progress',
+  version: '0.1.0',
+  description: 'Generic server-side progress tracking for long-running operations',
+  author: 'Open Mercato Team',
+  license: 'Proprietary',
+  ejectable: true,
+}

package/src/modules/progress/lib/events.ts

@@ -0,0 +1,60 @@
+import { events } from '../events'
+
+type EventEntry = typeof events[number]
+type EventMap = { [K in EventEntry['id'] as Uppercase<K extends `progress.job.${infer A}` ? `JOB_${A}` : never>]: K }
+
+function buildEventMap<T extends readonly { id: string }[]>(defs: T) {
+  const map: Record<string, string> = {}
+  for (const def of defs) {
+    const suffix = def.id.replace('progress.job.', '')
+    map[`JOB_${suffix.toUpperCase()}`] = def.id
+  }
+  return map as EventMap
+}
+
+export const PROGRESS_EVENTS = buildEventMap(events)
+
+export type ProgressJobCreatedPayload = {
+  jobId: string
+  jobType: string
+  name: string
+  tenantId: string
+  organizationId?: string | null
+}
+
+export type ProgressJobStartedPayload = {
+  jobId: string
+  jobType: string
+  tenantId: string
+}
+
+export type ProgressJobUpdatedPayload = {
+  jobId: string
+  jobType?: string
+  progressPercent: number
+  processedCount: number
+  totalCount?: number | null
+  etaSeconds?: number | null
+  tenantId: string
+}
+
+export type ProgressJobCompletedPayload = {
+  jobId: string
+  jobType: string
+  resultSummary?: Record<string, unknown> | null
+  tenantId: string
+}
+
+export type ProgressJobFailedPayload = {
+  jobId: string
+  jobType: string
+  errorMessage: string
+  tenantId: string
+  stale?: boolean
+}
+
+export type ProgressJobCancelledPayload = {
+  jobId: string
+  jobType: string
+  tenantId: string
+}

package/src/modules/progress/lib/progressService.ts

@@ -0,0 +1,47 @@
+import type { ProgressJob } from '../data/entities'
+import type { CreateProgressJobInput, UpdateProgressInput, CompleteJobInput, FailJobInput } from '../data/validators'
+
+export interface ProgressServiceContext {
+  tenantId: string
+  organizationId?: string | null
+  userId?: string | null
+}
+
+export interface ProgressService {
+  createJob(input: CreateProgressJobInput, ctx: ProgressServiceContext): Promise<ProgressJob>
+  startJob(jobId: string, ctx: ProgressServiceContext): Promise<ProgressJob>
+  updateProgress(jobId: string, input: UpdateProgressInput, ctx: ProgressServiceContext): Promise<ProgressJob>
+  incrementProgress(jobId: string, delta: number, ctx: ProgressServiceContext): Promise<ProgressJob>
+  completeJob(jobId: string, input: CompleteJobInput | undefined, ctx: ProgressServiceContext): Promise<ProgressJob>
+  failJob(jobId: string, input: FailJobInput, ctx: ProgressServiceContext): Promise<ProgressJob>
+  cancelJob(jobId: string, ctx: ProgressServiceContext): Promise<ProgressJob>
+  isCancellationRequested(jobId: string): Promise<boolean>
+  getActiveJobs(ctx: ProgressServiceContext): Promise<ProgressJob[]>
+  getRecentlyCompletedJobs(ctx: ProgressServiceContext, sinceSeconds?: number): Promise<ProgressJob[]>
+  getJob(jobId: string, ctx: ProgressServiceContext): Promise<ProgressJob | null>
+  markStaleJobsFailed(tenantId: string, timeoutSeconds?: number): Promise<number>
+}
+
+export const HEARTBEAT_INTERVAL_MS = 5000
+export const STALE_JOB_TIMEOUT_SECONDS = 60
+
+export function calculateEta(
+  processedCount: number,
+  totalCount: number,
+  startedAt: Date,
+): number | null {
+  if (processedCount === 0 || totalCount === 0) return null
+
+  const elapsedMs = Date.now() - startedAt.getTime()
+  const rate = processedCount / elapsedMs
+  const remaining = totalCount - processedCount
+
+  if (rate <= 0) return null
+
+  return Math.ceil(remaining / rate / 1000)
+}
+
+export function calculateProgressPercent(processedCount: number, totalCount: number | null): number {
+  if (!totalCount || totalCount <= 0) return 0
+  return Math.min(100, Math.round((processedCount / totalCount) * 100))
+}