import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"; import { JOB_PRIORITY_CRITICAL, JOB_PRIORITY_HIGH, JOB_PRIORITY_LOW, JOB_PRIORITY_NORMAL, buildBrowserSessionCleanupJob, buildBrowserSessionRunJob, buildBrowserUsageFlushJob, buildCleanupJob, buildExportJob, buildFileScanJob, buildIdempotentJobId, buildImportJob, buildAdminSalesContactsImportJob, buildAdminSalesContactsExportJob, buildKwpArchiveDiscoveryJob, buildKwpArchiveFileSyncJob, buildKwpContractSentinelJob, buildKwpProjectCatalogSyncJob, buildKwpProjectSyncJob, buildNotificationJob, buildPlatformNotificationJob, buildPlatformNotificationRequestedOutboxEvent, buildPluginInvokeJob, buildPortalDocumentReadyOutboxEvent, buildRetryJobOptions, buildTransactionalMailJob, buildWebhookDeliveryJob, buildWorkflowExecutionContinueRequestedOutboxEvent, buildWorkflowExecutionRequestedOutboxEvent, buildWorkflowTriggerOutboxEvent, enqueueJob, queueNames, setEnqueueObserver, setTenantPlanLookup, } from "./index.js"; import type { JobsOptions, TypedQueue } from "./types.js"; describe("queue producers", () => { test("builds transactional mail descriptors", () => { expect( buildTransactionalMailJob({ to: ["user@example.com"], subject: "Welcome", templateId: "welcome", templateData: { firstName: "Ada" }, tenantId: "tenant_1", }) ).toEqual({ queueName: queueNames.email, jobName: "send-transactional-email", payload: { kind: "mail.transactional", to: ["user@example.com"], subject: "Welcome", templateId: "welcome", templateData: { firstName: "Ada" }, tenantId: "tenant_1", }, }); }); test("builds webhook delivery descriptors", () => { expect( buildWebhookDeliveryJob({ url: "https://example.com/webhook", eventName: "entity.created", method: "PUT", headers: { authorization: "Bearer token" }, body: { id: "row_1" }, }) ).toEqual({ queueName: queueNames.email, jobName: "deliver-webhook", payload: { kind: "webhook.deliver", url: "https://example.com/webhook", eventName: "entity.created", method: "PUT", headers: { authorization: "Bearer token" }, body: { id: "row_1" }, }, }); }); test("builds notification descriptors", () => { expect( buildNotificationJob({ userId: "user_1", channel: "email", messageKey: "billing.invoice-ready", tenantId: "tenant_1", category: "billing", email: "user@example.com", subject: "Invoice ready", text: "Your invoice is ready.", html: "

Your invoice is ready.

", templateId: "invoice-ready", templateData: { invoiceId: "inv_1" }, metadata: { requestId: "req_1", idempotencyKey: "notification:req_1" }, }) ).toEqual({ queueName: queueNames.notifications, jobName: "send-notification", payload: { kind: "notification.send", userId: "user_1", channel: "email", messageKey: "billing.invoice-ready", tenantId: "tenant_1", category: "billing", email: "user@example.com", subject: "Invoice ready", text: "Your invoice is ready.", html: "

Your invoice is ready.

", templateId: "invoice-ready", templateData: { invoiceId: "inv_1" }, metadata: { requestId: "req_1", idempotencyKey: "notification:req_1" }, }, }); }); test("rejects unsupported notification channels before building descriptors", () => { expect(() => buildNotificationJob({ tenantId: "tenant_1", userId: "user_1", channel: "sms", messageKey: "billing.invoice-ready", } as unknown as Parameters[0]) ).toThrow("Unsupported notification channel: sms"); }); test("rejects notification descriptors without tenant scope", () => { expect(() => buildNotificationJob({ userId: "user_1", channel: "in-app", messageKey: "message.ready", } as unknown as Parameters[0]) ).toThrow("Notification jobs require tenantId."); }); test("builds a strictly tenantless platform notification descriptor", () => { expect( buildPlatformNotificationJob({ userId: " user_haris ", sourceKey: " platform-lead:lead_1:email ", channel: "email", messageKey: "platform.leads.captured", category: "Leads", email: "haris@example.test", subject: "Neuer Lead in HiveGrid", text: "Ein neuer Lead ist eingegangen.", metadata: { deliveryId: "delivery_1", leadId: "lead_1", sourceId: "hivegrid-website", deeplink: "/leads/lead_1", }, }) ).toEqual({ queueName: queueNames.notifications, jobName: "send-notification", payload: { kind: "notification.platform.send", tenantId: null, userId: "user_haris", sourceKey: "platform-lead:lead_1:email", channel: "email", messageKey: "platform.leads.captured", category: "leads", email: "haris@example.test", subject: "Neuer Lead in HiveGrid", text: "Ein neuer Lead ist eingegangen.", metadata: { deliveryId: "delivery_1", leadId: "lead_1", sourceId: "hivegrid-website", deeplink: "/leads/lead_1", }, }, }); }); test("preserves a safe task subject for platform reminder jobs", () => { expect( buildPlatformNotificationJob({ adminUserId: "admin_1", sourceKey: "admin-sales:task-reminder:task_1:2026-07-25", channel: "in-app", messageKey: "admin.sales.notifications.taskreminder", metadata: { taskId: "task_1", deeplink: "/sales/tasks/today" }, }).payload ).toMatchObject({ adminUserId: "admin_1", metadata: { taskId: "task_1", deeplink: "/sales/tasks/today", }, }); }); test("requires exactly one tenant or admin recipient identity", () => { expect(() => buildPlatformNotificationJob({ sourceKey: "admin-email-open:event_1", channel: "in-app", messageKey: "admin.sales.email.notifications.opened", }) ).toThrow("exactly one recipient identity"); expect(() => buildPlatformNotificationRequestedOutboxEvent({ deliveryId: "delivery_1", userId: "user_1", adminUserId: "admin_1", sourceKey: "admin-email-open:event_1", channel: "in-app", messageKey: "admin.sales.email.notifications.opened", }) ).toThrow("exactly one recipient identity"); }); test("rejects invalid platform scope and strips non-allowlisted queue metadata", () => { expect(() => buildPlatformNotificationJob({ userId: " ", sourceKey: "platform-lead:lead_1:email", channel: "email", messageKey: "platform.leads.captured", }) ).toThrow("userId to be a stable non-secret identifier"); expect(() => buildPlatformNotificationJob({ userId: "user_haris", sourceKey: "Bearer secret/value", channel: "email", messageKey: "platform.leads.captured", }) ).toThrow("sourceKey to be a stable non-secret identifier"); const descriptor = buildPlatformNotificationJob({ tenantId: "tenant_escape", userId: "user_haris", sourceKey: "platform-lead:lead_1:in-app", channel: "in-app", messageKey: "platform.leads.captured", metadata: { leadId: "lead_1", email: "lead@example.test", phone: "+491701234567", message: "private message", token: "secret-token", }, } as never); expect(descriptor.payload.tenantId).toBeNull(); expect(descriptor.payload.metadata).toEqual({ leadId: "lead_1" }); expect(JSON.stringify(descriptor)).not.toContain("lead@example.test"); expect(JSON.stringify(descriptor)).not.toContain("private message"); expect(JSON.stringify(descriptor)).not.toContain("secret-token"); }); test("builds a PII-minimized platform notification outbox event", () => { const event = buildPlatformNotificationRequestedOutboxEvent({ deliveryId: "delivery_1", userId: "user_haris", sourceKey: "platform-lead:lead_1:email", channel: "email", messageKey: "platform.leads.captured", category: "leads", metadata: { deliveryId: "must_not_be_nested", leadId: "lead_1", sourceId: "hivegrid-website", deeplink: "/leads/lead_1", email: "lead@example.test", }, } as never); expect(event).toEqual({ tenantId: null, type: "notification.platform.requested.v1", payload: { deliveryId: "delivery_1", userId: "user_haris", sourceKey: "platform-lead:lead_1:email", channel: "email", messageKey: "platform.leads.captured", category: "leads", metadata: { leadId: "lead_1", sourceId: "hivegrid-website", deeplink: "/leads/lead_1", }, }, dispatchKey: "platform-notification:delivery_1", }); expect(JSON.stringify(event)).not.toContain("lead@example.test"); }); test("uses the recipient-specific delivery id for platform outbox dispatch dedupe", () => { const common = { sourceKey: "platform-lead:lead_1:email", channel: "email" as const, messageKey: "platform.leads.captured", }; const first = buildPlatformNotificationRequestedOutboxEvent({ ...common, deliveryId: "delivery_user_1", userId: "user_1" }); const second = buildPlatformNotificationRequestedOutboxEvent({ ...common, deliveryId: "delivery_user_2", userId: "user_2" }); expect(first.dispatchKey).toBe("platform-notification:delivery_user_1"); expect(second.dispatchKey).toBe("platform-notification:delivery_user_2"); }); test("builds maintenance cleanup descriptors", () => { expect( buildCleanupJob({ task: "expired-sessions", olderThanHours: 24, requestedBy: "system", metadata: { requestId: "req_maintenance_1" }, }) ).toEqual({ queueName: queueNames.maintenance, jobName: "run-cleanup", payload: { kind: "cleanup.run", task: "expired-sessions", olderThanHours: 24, requestedBy: "system", metadata: { requestId: "req_maintenance_1" }, }, }); }); test("builds dsgvo grace-period scan descriptors on the maintenance queue", () => { const descriptor = buildCleanupJob({ task: "dsgvo-grace-period-scan" }); expect(descriptor).toEqual({ queueName: queueNames.maintenance, jobName: "run-cleanup", payload: { kind: "cleanup.run", task: "dsgvo-grace-period-scan", }, }); }); test("builds outbox DONE retention descriptors on the maintenance queue", () => { const descriptor = buildCleanupJob({ task: "outbox-done-retention", olderThanHours: 720, take: 1000, metadata: { requestId: "req_outbox_done_retention_1" }, }); expect(descriptor).toEqual({ queueName: queueNames.maintenance, jobName: "run-cleanup", payload: { kind: "cleanup.run", task: "outbox-done-retention", olderThanHours: 720, take: 1000, metadata: { requestId: "req_outbox_done_retention_1" }, }, }); }); test("builds workflow stalled execution reconcile descriptors on the maintenance queue", () => { const descriptor = buildCleanupJob({ task: "workflow-execution-stalled-reconcile", olderThanMinutes: 30, take: 100, metadata: { requestId: "req_workflow_stalled_reconcile_1" }, }); expect(descriptor).toEqual({ queueName: queueNames.maintenance, jobName: "run-cleanup", payload: { kind: "cleanup.run", task: "workflow-execution-stalled-reconcile", olderThanMinutes: 30, take: 100, metadata: { requestId: "req_workflow_stalled_reconcile_1" }, }, }); }); test("builds telephony webhook maintenance descriptors on the maintenance queue", () => { const descriptor = buildCleanupJob({ task: "telephony-webhook-maintenance" }); expect(descriptor).toEqual({ queueName: queueNames.maintenance, jobName: "run-cleanup", payload: { kind: "cleanup.run", task: "telephony-webhook-maintenance", }, }); }); test("builds product acquisition reconciliation descriptors on the maintenance queue", () => { const descriptor = buildCleanupJob({ task: "product-acquisition-reconcile", take: 50 }); expect(descriptor).toEqual({ queueName: queueNames.maintenance, jobName: "run-cleanup", payload: { kind: "cleanup.run", task: "product-acquisition-reconcile", take: 50, }, }); }); test("builds expired export artifact retention descriptors on the maintenance queue", () => { const descriptor = buildCleanupJob({ task: "expired-export-artifacts", olderThanHours: 168, metadata: { requestId: "req_export_artifact_retention_1" }, }); expect(descriptor).toEqual({ queueName: queueNames.maintenance, jobName: "run-cleanup", payload: { kind: "cleanup.run", task: "expired-export-artifacts", olderThanHours: 168, metadata: { requestId: "req_export_artifact_retention_1" }, }, }); expect(descriptor.queueName).not.toBe(queueNames.exports); expect(descriptor.jobName).not.toBe("run-export"); }); test("builds browser automation session run descriptors on the browser automation queue", () => { expect( buildBrowserSessionRunJob({ tenantId: "tenant_browser_1", userId: "user_browser_1", sessionId: "session_1", policyId: "policy_1", allowedOrigins: ["https://example.test"], task: { action: "capture", url: "https://example.test/dashboard" }, metadata: { requestId: "req_browser_run_1" }, }) ).toEqual({ queueName: queueNames.browserAutomation, jobName: "browser-session-run", payload: { kind: "browser.session-run", tenantId: "tenant_browser_1", userId: "user_browser_1", sessionId: "session_1", policyId: "policy_1", allowedOrigins: ["https://example.test"], task: { action: "capture", url: "https://example.test/dashboard" }, metadata: { requestId: "req_browser_run_1" }, }, }); }); test("builds browser automation session cleanup descriptors", () => { expect( buildBrowserSessionCleanupJob({ tenantId: "tenant_browser_2", sessionId: "session_2", metadata: { reason: "expired" }, }) ).toEqual({ queueName: queueNames.browserAutomation, jobName: "browser-session-cleanup", payload: { kind: "browser.session-cleanup", tenantId: "tenant_browser_2", sessionId: "session_2", metadata: { reason: "expired" }, }, }); }); test("builds browser automation usage flush descriptors", () => { expect( buildBrowserUsageFlushJob({ tenantId: "tenant_browser_3", userId: "user_browser_3", sessionId: "session_3", metadata: { batchId: "usage_batch_1" }, }) ).toEqual({ queueName: queueNames.browserAutomation, jobName: "usage-flush", payload: { kind: "usage.flush", tenantId: "tenant_browser_3", userId: "user_browser_3", sessionId: "session_3", metadata: { batchId: "usage_batch_1" }, }, }); }); test("builds file scan descriptors on the file scan queue", () => { expect( buildFileScanJob({ bucket: "uploads", key: "tenant_1/upload_1/file.pdf", tenantId: "tenant_1", uploadId: "upload_1", contentType: "application/pdf", metadata: { requestId: "req_scan_1", nested: { value: true } }, }) ).toEqual({ queueName: queueNames.fileScan, jobName: "scan-file", payload: { kind: "scan.file", bucket: "uploads", key: "tenant_1/upload_1/file.pdf", tenantId: "tenant_1", uploadId: "upload_1", contentType: "application/pdf", metadata: { requestId: "req_scan_1", nested: { value: true } }, }, }); }); test("builds export descriptors on the exports queue", () => { expect( buildExportJob({ exportJobId: "export_job_1", tenantId: "tenant_export_1", requestedByUserId: "user_export_1", exportType: "members", format: "csv", requestId: "req_export_1", complianceGate: { state: "active", resumedAt: "2026-01-01T00:00:00.000Z", requestId: "req_export_resume_1", }, metadata: { requestId: "req_export_1", source: "members-page" }, filters: { status: "active", tags: ["beta"] }, }) ).toEqual({ queueName: queueNames.exports, jobName: "run-export", payload: { kind: "export.run", exportJobId: "export_job_1", tenantId: "tenant_export_1", requestedByUserId: "user_export_1", exportType: "members", format: "csv", requestId: "req_export_1", complianceGate: { state: "active", resumedAt: "2026-01-01T00:00:00.000Z", requestId: "req_export_resume_1", }, metadata: { requestId: "req_export_1", source: "members-page" }, filters: { status: "active", tags: ["beta"] }, }, }); }); test("preserves paused export gates on the exports queue", () => { const descriptor = buildExportJob({ exportJobId: "export_job_paused_1", tenantId: "tenant_export_1", requestedByUserId: "user_export_1", exportType: "members", format: "json", requestId: "req_export_paused_1", complianceGate: { state: "paused", reason: "workspace-retention-pause", requestId: "req_pause_1", }, }); expect(descriptor).toEqual({ queueName: queueNames.exports, jobName: "run-export", payload: { kind: "export.run", exportJobId: "export_job_paused_1", tenantId: "tenant_export_1", requestedByUserId: "user_export_1", exportType: "members", format: "json", requestId: "req_export_paused_1", complianceGate: { state: "paused", reason: "workspace-retention-pause", requestId: "req_pause_1", }, }, }); expect(descriptor.queueName).toBe(queueNames.exports); expect(descriptor.queueName).not.toBe(queueNames.email); expect(descriptor.queueName).not.toBe(queueNames.maintenance); expect(descriptor.jobName).toBe("run-export"); }); test("keeps export descriptors off email and maintenance queues", () => { const descriptor = buildExportJob({ exportJobId: "export_job_queue_guard_1", tenantId: "tenant_export_1", requestedByUserId: "user_export_1", exportType: "members", format: "json", requestId: "req_export_queue_guard_1", }); expect(descriptor.queueName).toBe(queueNames.exports); expect(descriptor.queueName).not.toBe(queueNames.email); expect(descriptor.queueName).not.toBe(queueNames.maintenance); expect(descriptor.jobName).toBe("run-export"); expect(descriptor.payload.requestId).toBe("req_export_queue_guard_1"); }); test("builds import descriptors on the imports queue", () => { expect( buildImportJob({ importJobId: "import_job_1", tenantId: "tenant_import_1", requestedByUserId: "user_import_1", importType: "members", format: "csv", sourceBucket: "imports", sourceKey: "tenant_import_1/import_job_1/members.csv", requestId: "req_import_1", fileName: "members.csv", contentType: "text/csv", mappings: { email: "Email", name: "Name" }, metadata: { requestId: "req_import_1", attemptsMade: 0 }, }) ).toEqual({ queueName: queueNames.imports, jobName: "run-import", payload: { kind: "import.run", importJobId: "import_job_1", tenantId: "tenant_import_1", requestedByUserId: "user_import_1", importType: "members", format: "csv", sourceBucket: "imports", sourceKey: "tenant_import_1/import_job_1/members.csv", requestId: "req_import_1", fileName: "members.csv", contentType: "text/csv", mappings: { email: "Email", name: "Name" }, metadata: { requestId: "req_import_1", attemptsMade: 0 }, }, }); }); test("builds tenant-less admin sales data jobs on the imports queue", () => { expect( buildAdminSalesContactsImportJob({ importJobId: "admin_import_1", requestedByAdminUserId: "admin_1", requestId: "request_1", }) ).toEqual({ queueName: queueNames.imports, jobName: "run-import", payload: { kind: "admin-sales.contacts-import", importJobId: "admin_import_1", requestedByAdminUserId: "admin_1", requestId: "request_1", }, }); expect( buildAdminSalesContactsExportJob({ exportJobId: "admin_export_1", requestedByAdminUserId: "admin_1", }) ).toEqual({ queueName: queueNames.imports, jobName: "run-import", payload: { kind: "admin-sales.contacts-export", exportJobId: "admin_export_1", requestedByAdminUserId: "admin_1", }, }); }); test("keeps import descriptors off export and email queues", () => { const descriptor = buildImportJob({ importJobId: "import_job_queue_guard_1", tenantId: "tenant_import_1", requestedByUserId: "user_import_1", importType: "members", format: "json", sourceBucket: "imports", sourceKey: "tenant_import_1/import_job_queue_guard_1/members.json", requestId: "req_import_queue_guard_1", }); expect(descriptor.queueName).toBe(queueNames.imports); expect(descriptor.queueName).not.toBe(queueNames.exports); expect(descriptor.queueName).not.toBe(queueNames.email); expect(descriptor.jobName).toBe("run-import"); expect(descriptor.payload.requestId).toBe("req_import_queue_guard_1"); }); test("rejects every unstable KWP project-sync identifier", () => { const valid = { tenantId: "tenant_1", bindingId: "binding_1", dataConnectionId: "connection_1", cadenceBucket: "2026-07-23T11:30Z", }; expect(buildKwpProjectSyncJob(valid)).toMatchObject({ queueName: queueNames.kwpImports, jobName: "run-kwp-import", payload: { kind: "kwp.project-sync", ...valid }, }); for (const field of ["tenantId", "bindingId", "dataConnectionId", "cadenceBucket"] as const) { expect(() => buildKwpProjectSyncJob({ ...valid, [field]: " " })) .toThrow("KWP project sync jobs require stable tenant, binding, connection and cadence identifiers."); } }); test("rejects every unstable KWP contract-sentinel identifier", () => { const valid = { tenantId: "tenant_1", dataConnectionId: "connection_1", cadenceBucket: "2026-07-23", }; expect(buildKwpContractSentinelJob(valid)).toMatchObject({ queueName: queueNames.kwpImports, jobName: "run-kwp-import", payload: { kind: "kwp.contract-sentinel", ...valid }, }); for (const field of ["tenantId", "dataConnectionId", "cadenceBucket"] as const) { expect(() => buildKwpContractSentinelJob({ ...valid, [field]: " " })) .toThrow("KWP contract sentinel jobs require stable tenant, connection and cadence identifiers."); } }); test("builds a stable KWP project-catalog descriptor and rejects unstable identifiers", () => { const valid = { tenantId: "tenant_1", dataConnectionId: "connection_1", cadenceBucket: "2026-07-23T11:30Z", }; expect(buildKwpProjectCatalogSyncJob(valid)).toMatchObject({ queueName: queueNames.kwpImports, jobName: "run-kwp-import", payload: { kind: "kwp.project-catalog-sync", ...valid }, }); for (const field of ["tenantId", "dataConnectionId", "cadenceBucket"] as const) { expect(() => buildKwpProjectCatalogSyncJob({ ...valid, [field]: " " })) .toThrow("KWP project catalog jobs require stable tenant, connection and cadence identifiers."); } }); test("builds a stable KWP archive-file descriptor and rejects an unstable revision", () => { const input = { tenantId: "tenant_1", bindingId: "binding_1", dataConnectionId: "connection_1", cadenceBucket: "2026-07-23T11:30Z", archiveFile: { externalId: "1:2:3", headerId: 1, revisionId: 3, revision: 1, folderId: 0, displayName: "plan.pdf", documentType: null, providerFileType: "PDF", providerSizeBytes: 123, lastModifiedAt: null, }, }; expect(buildKwpArchiveFileSyncJob(input)).toEqual({ queueName: queueNames.kwpImports, jobName: "run-kwp-import", payload: { kind: "kwp.archive-file-sync", ...input }, }); expect(() => buildKwpArchiveFileSyncJob({ ...input, archiveFile: { ...input.archiveFile, revisionId: 1.5 }, })).toThrow("KWP archive file jobs require stable tenant, binding, connection, cadence and revision identifiers."); }); test("builds bounded resumable KWP archive-discovery descriptors", () => { const input = { tenantId: "tenant_1", bindingId: "binding_1", dataConnectionId: "connection_1", cadenceBucket: "2026-07-23T11:30Z", batchNumber: 2, cursor: { pendingFolderIds: [-5, 6], visitedFolderIds: [0, -2, -1, 3, 4] }, }; expect(buildKwpArchiveDiscoveryJob(input)).toEqual({ queueName: queueNames.kwpImports, jobName: "run-kwp-import", payload: { kind: "kwp.archive-discovery", ...input }, }); expect(() => buildKwpArchiveDiscoveryJob({ ...input, cursor: { pendingFolderIds: [], visitedFolderIds: [0] }, })).toThrow("KWP archive discovery jobs require a stable project binding and a bounded folder cursor."); expect(() => buildKwpArchiveDiscoveryJob({ ...input, cursor: { pendingFolderIds: [2_147_483_648], visitedFolderIds: [0] }, })).toThrow("KWP archive discovery jobs require a stable project binding and a bounded folder cursor."); }); test("builds plugin invoke descriptors for the isolated plugin queue", () => { expect( buildPluginInvokeJob({ tenantId: "tenant_1", pluginId: "com.acme.audit", version: "1.0.0", hookName: "tenant.created", input: { tenantId: "tenant_1" }, metadata: { outboxEventId: "evt_1" }, }) ).toEqual({ queueName: queueNames.pluginInvoke, jobName: "invoke-plugin", payload: { kind: "plugin.invoke", tenantId: "tenant_1", pluginId: "com.acme.audit", version: "1.0.0", hookName: "tenant.created", input: { tenantId: "tenant_1" }, metadata: { outboxEventId: "evt_1" }, }, }); }); test("builds workflow trigger outbox events for application event fanout", () => { expect( buildWorkflowTriggerOutboxEvent({ tenantId: "tenant_1", event: "row.created", data: { rowId: "row_1", values: { status: "open" } }, userId: "user_1", sourceId: "event_1", }) ).toEqual({ tenantId: "tenant_1", type: "workflow.trigger.event", payload: { event: "row.created", data: { rowId: "row_1", values: { status: "open" } }, userId: "user_1", }, dispatchKey: "workflow-trigger:event_1", }); }); test("builds DB-authoritative portal document-ready events without a caller-supplied document type", () => { expect( buildPortalDocumentReadyOutboxEvent({ tenantId: "tenant_1", projectId: "project_1", fileId: "file_1", fileEntityLinkId: "link_1", linkVersion: new Date("2026-07-16T10:00:00.000Z"), userId: "user_1", }) ).toEqual({ tenantId: "tenant_1", type: "workflow.trigger.event", payload: { event: "portal.document_ready", data: { projectId: "project_1", fileId: "file_1", fileEntityLinkId: "link_1" }, userId: "user_1", }, dispatchKey: "workflow-trigger:portal-document-ready:link_1:1784196000000", }); }); test("builds workflow execution request outbox events for queued manual runs", () => { expect( buildWorkflowExecutionRequestedOutboxEvent({ tenantId: "tenant_1", workflowId: "workflow_1", executionId: "execution_1", type: "manual", input: { approved: true }, userId: "user_1", sourceId: "execution_1", }) ).toEqual({ tenantId: "tenant_1", type: "workflow.execution.requested", payload: { workflowId: "workflow_1", executionId: "execution_1", type: "manual", input: { approved: true }, userId: "user_1", }, dispatchKey: "workflow-execution:execution_1", }); }); test("builds workflow execution request outbox events for queued API runs", () => { expect( buildWorkflowExecutionRequestedOutboxEvent({ tenantId: "tenant_1", workflowId: "workflow_1", executionId: "execution_api_1", type: "api", input: { name: "Ada" }, userId: "user_1", sourceId: "execution_api_1", }) ).toEqual({ tenantId: "tenant_1", type: "workflow.execution.requested", payload: { workflowId: "workflow_1", executionId: "execution_api_1", type: "api", input: { name: "Ada" }, userId: "user_1", }, dispatchKey: "workflow-execution:execution_api_1", }); }); test("builds workflow continuation request outbox events for queued API continuations", () => { expect( buildWorkflowExecutionContinueRequestedOutboxEvent({ tenantId: "tenant_1", workflowId: "workflow_1", executionId: "execution_waiting_1", type: "api", input: { approved: true }, userId: "user_1", sourceId: "execution_waiting_1", }) ).toEqual({ tenantId: "tenant_1", type: "workflow.execution.continue.requested", payload: { workflowId: "workflow_1", executionId: "execution_waiting_1", type: "api", input: { approved: true }, userId: "user_1", }, dispatchKey: "workflow-continuation:execution_waiting_1", }); }); test("rejects malformed workflow trigger outbox event keys before publishing", () => { const input = { tenantId: "tenant_1", event: "row.created", data: { rowId: "row_1" }, userId: "user_1", sourceId: "event_1", }; expect(() => buildWorkflowTriggerOutboxEvent({ ...input, event: " " })).toThrow("workflow.trigger.event outbox events require event."); expect(() => buildWorkflowTriggerOutboxEvent({ ...input, sourceId: "" })).toThrow("workflow.trigger.event outbox events require sourceId."); expect(() => buildWorkflowTriggerOutboxEvent({ ...input, sourceId: "event 1" })).toThrow("workflow.trigger.event outbox events require sourceId to match"); }); test("rejects malformed workflow execution request outbox event keys before publishing", () => { const input = { tenantId: "tenant_1", workflowId: "workflow_1", executionId: "execution_1", type: "manual" as const, input: { approved: true }, userId: "user_1", sourceId: "execution_1", }; expect(() => buildWorkflowExecutionRequestedOutboxEvent({ ...input, workflowId: "" })).toThrow( "workflow.execution.requested outbox events require workflowId." ); expect(() => buildWorkflowExecutionRequestedOutboxEvent({ ...input, executionId: " " })).toThrow( "workflow.execution.requested outbox events require executionId." ); expect(() => buildWorkflowExecutionRequestedOutboxEvent({ ...input, sourceId: "execution/1" })).toThrow( "workflow.execution.requested outbox events require sourceId to match" ); }); test("rejects malformed workflow continuation outbox event keys before publishing", () => { const input = { tenantId: "tenant_1", workflowId: "workflow_1", executionId: "execution_waiting_1", type: "api" as const, input: { approved: true }, userId: "user_1", sourceId: "execution_waiting_1", }; expect(() => buildWorkflowExecutionContinueRequestedOutboxEvent({ ...input, workflowId: " " })).toThrow( "workflow.execution.continue.requested outbox events require workflowId." ); expect(() => buildWorkflowExecutionContinueRequestedOutboxEvent({ ...input, executionId: "" })).toThrow( "workflow.execution.continue.requested outbox events require executionId." ); expect(() => buildWorkflowExecutionContinueRequestedOutboxEvent({ ...input, sourceId: "execution#1" })).toThrow( "workflow.execution.continue.requested outbox events require sourceId to match" ); }); test("preserves requestId metadata on every producer descriptor", () => { const descriptors = [ buildTransactionalMailJob({ to: ["user@example.com"], templateId: "welcome", metadata: { requestId: "req_mail_1" }, }), buildWebhookDeliveryJob({ url: "https://example.com/webhook", eventName: "entity.created", headers: { authorization: "Bearer token" }, body: { id: "row_1" }, metadata: { requestId: "req_webhook_1" }, }), buildNotificationJob({ tenantId: "tenant_1", userId: "user_1", channel: "in-app", messageKey: "message.ready", metadata: { requestId: "req_notification_1" }, }), buildCleanupJob({ task: "expired-sessions", metadata: { requestId: "req_cleanup_1" } }), buildBrowserSessionRunJob({ tenantId: "tenant_1", sessionId: "session_1", task: { action: "capture" }, metadata: { requestId: "req_browser_run_1" }, }), buildBrowserSessionCleanupJob({ tenantId: "tenant_1", sessionId: "session_1", metadata: { requestId: "req_browser_cleanup_1" }, }), buildBrowserUsageFlushJob({ tenantId: "tenant_1", sessionId: "session_1", metadata: { requestId: "req_browser_usage_1" }, }), buildExportJob({ exportJobId: "export_job_request_1", tenantId: "tenant_1", requestedByUserId: "user_1", exportType: "members", format: "csv", metadata: { requestId: "req_export_1" }, }), ]; for (const descriptor of descriptors) { expect(descriptor.payload.metadata?.requestId, `${descriptor.queueName}:${descriptor.jobName} requestId`).toEqual(expect.stringMatching(/^req_/)); } }); test("builds explicit retry options for every producer descriptor", () => { const descriptors = [ buildTransactionalMailJob({ to: ["user@example.com"], templateId: "welcome" }), buildWebhookDeliveryJob({ url: "https://example.com/webhook", eventName: "entity.created", headers: { authorization: "Bearer token" }, body: { id: "row_1" }, }), buildNotificationJob({ tenantId: "tenant_1", userId: "user_1", channel: "in-app", messageKey: "message.ready" }), buildCleanupJob({ task: "expired-sessions" }), buildBrowserSessionRunJob({ tenantId: "tenant_1", sessionId: "session_1", task: { action: "capture" } }), buildBrowserSessionCleanupJob({ tenantId: "tenant_1", sessionId: "session_1" }), buildBrowserUsageFlushJob({ tenantId: "tenant_1", sessionId: "session_1" }), buildFileScanJob({ bucket: "uploads", key: "tenant_1/upload_1/file.pdf" }), buildExportJob({ exportJobId: "export_job_retry_1", tenantId: "tenant_1", requestedByUserId: "user_1", exportType: "members", format: "json", }), buildImportJob({ importJobId: "import_job_retry_1", tenantId: "tenant_1", requestedByUserId: "user_1", importType: "members", format: "json", sourceBucket: "imports", sourceKey: "tenant_1/import_job_retry_1/members.json", }), ]; for (const descriptor of descriptors) { const options = buildRetryJobOptions(descriptor); expect(options.attempts, `${descriptor.queueName}:${descriptor.jobName} attempts`).toEqual(expect.any(Number)); expect(options.attempts).toBeGreaterThan(0); expect(options.backoff, `${descriptor.queueName}:${descriptor.jobName} backoff`).toEqual({ type: expect.stringMatching(/^(exponential|fixed)$/), delay: expect.any(Number), }); expect(options.removeOnComplete).toBe(true); expect(options.removeOnFail).toEqual(expect.any(Number)); } }); test("enqueues descriptors with default retry options", async () => { const add = vi.fn(async () => ({ id: "job_1" })); const queue = { add } as unknown as TypedQueue; const descriptor = buildWebhookDeliveryJob({ url: "https://example.com/webhook", eventName: "entity.created", }); await expect(enqueueJob(queue, descriptor)).resolves.toEqual({ id: "job_1" }); expect(add).toHaveBeenCalledWith("deliver-webhook", descriptor.payload, buildRetryJobOptions(descriptor)); }); test("preserves queue.add receiver binding for BullMQ queues", async () => { const descriptor = buildWebhookDeliveryJob({ url: "https://example.com/webhook", eventName: "entity.created", }); const queue = { async add(this: unknown, jobName: string, payload: unknown, options?: JobsOptions) { expect(this).toBe(queue); expect(jobName).toBe("deliver-webhook"); expect(payload).toBe(descriptor.payload); expect(options).toEqual(buildRetryJobOptions(descriptor)); return { id: "job_bound" }; }, } as unknown as TypedQueue; await expect(enqueueJob(queue, descriptor)).resolves.toEqual({ id: "job_bound" }); }); test("lets explicit enqueue options override retry defaults", async () => { const add = vi.fn(async () => ({ id: "job_2" })); const queue = { add } as unknown as TypedQueue; const descriptor = buildWebhookDeliveryJob({ url: "https://example.com/webhook", eventName: "entity.created", }); const options = { attempts: 9, backoff: { type: "fixed", delay: 250 }, removeOnComplete: 10, removeOnFail: false, }; await enqueueJob(queue, descriptor, options); expect(add).toHaveBeenCalledWith("deliver-webhook", descriptor.payload, { ...buildRetryJobOptions(descriptor), ...options, }); }); test("uses explicit jobId before idempotencyKey", async () => { const add = vi.fn(async (...args: [string, { metadata?: Record }, unknown?]) => { expect(args.length).toBeGreaterThan(0); return { id: "job_3" }; }); const queue = { add } as unknown as TypedQueue; const metadata = { requestId: "req_enqueue_1", idempotencyKey: "metadata-key" }; const descriptor = buildWebhookDeliveryJob({ url: "https://example.com/webhook", eventName: "entity.created", metadata, }); await enqueueJob(queue, descriptor, { idempotencyKey: "safe-key", jobId: "explicit-job-id" }); expect(add).toHaveBeenCalledWith("deliver-webhook", descriptor.payload, { ...buildRetryJobOptions(descriptor), removeOnComplete: 10_000, jobId: "explicit-job-id", }); const enqueuedPayload = add.mock.calls[0]?.[1]; expect(enqueuedPayload).toBeDefined(); expect(enqueuedPayload?.metadata).toBe(metadata); expect(enqueuedPayload?.metadata).toEqual({ requestId: "req_enqueue_1", idempotencyKey: "metadata-key" }); }); test("derives jobId from explicit and metadata idempotency keys", () => { const descriptor = buildNotificationJob({ tenantId: "tenant_1", userId: "user_1", channel: "in-app", messageKey: "message.ready", metadata: { idempotencyKey: "metadata-key" }, }); expect(buildIdempotentJobId(descriptor, { idempotencyKey: "option-key" })).toBe("option-key"); expect(buildIdempotentJobId(descriptor)).toBe("metadata-key"); }); test("encodes BullMQ-reserved custom job id characters without collisions", () => { const descriptor = buildNotificationJob({ tenantId: "tenant_1", userId: "user_1", channel: "in-app", messageKey: "message.ready", metadata: { idempotencyKey: "notification:delivery%3A1" }, }); expect(buildIdempotentJobId(descriptor)).toBe("notification%3Adelivery%253A1"); expect(buildIdempotentJobId(descriptor, { idempotencyKey: "123" })).toBe("job-123"); expect(buildIdempotentJobId(descriptor, { idempotencyKey: "notification%3Adelivery%253A1" })).not.toBe(buildIdempotentJobId(descriptor)); }); test("bounds completed idempotent jobs unless callers override completion retention", async () => { const add = vi.fn(async () => ({ id: "job_idempotent" })); const queue = { add } as unknown as TypedQueue; const descriptor = buildNotificationJob({ tenantId: "tenant_1", userId: "user_1", channel: "in-app", messageKey: "message.ready", metadata: { idempotencyKey: "metadata-key" }, }); await enqueueJob(queue, descriptor); expect(add).toHaveBeenLastCalledWith("send-notification", descriptor.payload, { ...buildRetryJobOptions(descriptor), removeOnComplete: 10_000, jobId: "metadata-key", }); await enqueueJob(queue, descriptor, { removeOnComplete: 10 }); expect(add).toHaveBeenLastCalledWith("send-notification", descriptor.payload, { ...buildRetryJobOptions(descriptor), removeOnComplete: 10, jobId: "metadata-key", }); }); test("derives file scan jobId from metadata idempotency key", () => { const descriptor = buildFileScanJob({ bucket: "uploads", key: "tenant_1/upload_1/file.pdf", metadata: { idempotencyKey: "scan-key", malformed: ["kept", "unknown"] }, }); expect(buildIdempotentJobId(descriptor)).toBe("scan-key"); expect(descriptor.payload.metadata?.malformed).toEqual(["kept", "unknown"]); }); test("derives export jobId from persisted exportJobId before metadata", () => { const descriptor = buildExportJob({ exportJobId: "export_job_idempotent_1", tenantId: "tenant_1", requestedByUserId: "user_1", exportType: "members", format: "csv", requestId: "req_export_idempotent_1", metadata: { idempotencyKey: "metadata-key", requestId: "req_export_idempotent_1" }, }); expect(buildIdempotentJobId(descriptor)).toBe("export_job_idempotent_1"); expect(buildIdempotentJobId(descriptor, { idempotencyKey: "option-key" })).toBe("option-key"); expect(descriptor.payload.requestId).toBe("req_export_idempotent_1"); expect(descriptor.payload.metadata?.requestId).toBe("req_export_idempotent_1"); }); test("enqueues export jobs with exportJobId idempotency", async () => { const add = vi.fn(async () => ({ id: "export_job_enqueue_1" })); const queue = { add } as unknown as TypedQueue; const descriptor = buildExportJob({ exportJobId: "export_job_enqueue_1", tenantId: "tenant_1", requestedByUserId: "user_1", exportType: "members", format: "json", requestId: "req_export_enqueue_1", }); await enqueueJob(queue, descriptor); expect(add).toHaveBeenCalledWith("run-export", descriptor.payload, { ...buildRetryJobOptions(descriptor), removeOnComplete: 10_000, jobId: "export_job_enqueue_1", }); }); test("derives import jobId from persisted importJobId before metadata", () => { const descriptor = buildImportJob({ importJobId: "import_job_idempotent_1", tenantId: "tenant_1", requestedByUserId: "user_1", importType: "members", format: "csv", sourceBucket: "imports", sourceKey: "tenant_1/import_job_idempotent_1/members.csv", requestId: "req_import_idempotent_1", metadata: { idempotencyKey: "metadata-key", requestId: "req_import_idempotent_1" }, }); expect(buildIdempotentJobId(descriptor)).toBe("import_job_idempotent_1"); expect(buildIdempotentJobId(descriptor, { idempotencyKey: "option-key" })).toBe("option-key"); expect(descriptor.payload.requestId).toBe("req_import_idempotent_1"); expect(descriptor.payload.metadata?.requestId).toBe("req_import_idempotent_1"); }); test("enqueues import jobs with importJobId idempotency and export retry policy", async () => { const add = vi.fn(async () => ({ id: "import_job_enqueue_1" })); const queue = { add } as unknown as TypedQueue; const descriptor = buildImportJob({ importJobId: "import_job_enqueue_1", tenantId: "tenant_1", requestedByUserId: "user_1", importType: "members", format: "json", sourceBucket: "imports", sourceKey: "tenant_1/import_job_enqueue_1/members.json", requestId: "req_import_enqueue_1", }); expect(buildRetryJobOptions(descriptor)).toMatchObject({ attempts: 2, backoff: { type: "exponential", delay: 10_000 }, }); await enqueueJob(queue, descriptor); expect(add).toHaveBeenCalledWith("run-import", descriptor.payload, { ...buildRetryJobOptions(descriptor), removeOnComplete: 10_000, jobId: "import_job_enqueue_1", }); }); test("does not generate jobId without a safe key", async () => { const add = vi.fn(async () => ({ id: "job_4" })); const queue = { add } as unknown as TypedQueue; const descriptor = buildWebhookDeliveryJob({ url: "https://example.com/webhook", eventName: "entity.created", body: { unsafe: "not-a-job-id" }, }); expect(buildIdempotentJobId(descriptor)).toBeUndefined(); await enqueueJob(queue, descriptor); expect(add).toHaveBeenCalledWith("deliver-webhook", descriptor.payload, buildRetryJobOptions(descriptor)); }); }); describe("enqueueJob priority resolution", () => { beforeEach(() => { setTenantPlanLookup(null); setEnqueueObserver(null); }); afterEach(() => { setTenantPlanLookup(null); setEnqueueObserver(null); }); test("explicit priorityOverride maps to the correct numeric priority", async () => { const add = vi.fn(async (...args: [string, unknown, unknown?]) => { expect(args.length).toBeGreaterThan(0); return { id: "job_priority_1" }; }); const queue = { add } as unknown as TypedQueue; const descriptor = buildWebhookDeliveryJob({ url: "https://example.com/wh", eventName: "evt" }); await enqueueJob(queue, descriptor, { priorityOverride: "critical" }); expect(add.mock.calls[0]?.[2]).toMatchObject({ priority: JOB_PRIORITY_CRITICAL }); add.mockClear(); await enqueueJob(queue, descriptor, { priorityOverride: "high" }); expect(add.mock.calls[0]?.[2]).toMatchObject({ priority: JOB_PRIORITY_HIGH }); add.mockClear(); await enqueueJob(queue, descriptor, { priorityOverride: "low" }); expect(add.mock.calls[0]?.[2]).toMatchObject({ priority: JOB_PRIORITY_LOW }); }); test("null tenantId means internal job → CRITICAL", async () => { const add = vi.fn(async (...args: [string, unknown, unknown?]) => { expect(args.length).toBeGreaterThan(0); return { id: "job_priority_internal" }; }); const queue = { add } as unknown as TypedQueue; const descriptor = buildCleanupJob({ task: "expired-sessions" }); await enqueueJob(queue, descriptor, { tenantId: null }); expect(add.mock.calls[0]?.[2]).toMatchObject({ priority: JOB_PRIORITY_CRITICAL }); }); test("tenantId without registered lookup falls back to NORMAL", async () => { const add = vi.fn(async (...args: [string, unknown, unknown?]) => { expect(args.length).toBeGreaterThan(0); return { id: "job_priority_normal" }; }); const queue = { add } as unknown as TypedQueue; const descriptor = buildWebhookDeliveryJob({ url: "https://example.com/wh", eventName: "evt" }); await enqueueJob(queue, descriptor, { tenantId: "tenant_unknown" }); expect(add.mock.calls[0]?.[2]).toMatchObject({ priority: JOB_PRIORITY_NORMAL }); }); test("registered plan lookup drives plan-based priority", async () => { setTenantPlanLookup(async (tenantId) => { if (tenantId === "tenant_ent") return "enterprise"; if (tenantId === "tenant_pro") return "pro"; return "free"; }); const add = vi.fn(async (...args: [string, unknown, unknown?]) => { expect(args.length).toBeGreaterThan(0); return { id: "job_priority_plan" }; }); const queue = { add } as unknown as TypedQueue; const descriptor = buildWebhookDeliveryJob({ url: "https://example.com/wh", eventName: "evt" }); await enqueueJob(queue, descriptor, { tenantId: "tenant_ent" }); expect(add.mock.calls[0]?.[2]).toMatchObject({ priority: JOB_PRIORITY_CRITICAL }); add.mockClear(); await enqueueJob(queue, descriptor, { tenantId: "tenant_pro" }); expect(add.mock.calls[0]?.[2]).toMatchObject({ priority: JOB_PRIORITY_NORMAL }); add.mockClear(); await enqueueJob(queue, descriptor, { tenantId: "tenant_free" }); expect(add.mock.calls[0]?.[2]).toMatchObject({ priority: JOB_PRIORITY_LOW }); }); test("priorityOverride beats tenant-plan lookup", async () => { setTenantPlanLookup(async () => "free"); const add = vi.fn(async (...args: [string, unknown, unknown?]) => { expect(args.length).toBeGreaterThan(0); return { id: "job_priority_override" }; }); const queue = { add } as unknown as TypedQueue; const descriptor = buildTransactionalMailJob({ to: ["user@example.com"], templateId: "password-reset" }); await enqueueJob(queue, descriptor, { tenantId: "tenant_free", priorityOverride: "critical" }); expect(add.mock.calls[0]?.[2]).toMatchObject({ priority: JOB_PRIORITY_CRITICAL }); }); test("explicit numeric priority wins over tenantId / override", async () => { setTenantPlanLookup(async () => "free"); const add = vi.fn(async (...args: [string, unknown, unknown?]) => { expect(args.length).toBeGreaterThan(0); return { id: "job_priority_numeric" }; }); const queue = { add } as unknown as TypedQueue; const descriptor = buildWebhookDeliveryJob({ url: "https://example.com/wh", eventName: "evt" }); await enqueueJob(queue, descriptor, { tenantId: "tenant_free", priorityOverride: "high", priority: 42 }); expect(add.mock.calls[0]?.[2]).toMatchObject({ priority: 42 }); }); test("priorityOverride and tenantId are stripped from forwarded BullMQ options", async () => { const add = vi.fn(async (...args: [string, unknown, unknown?]) => { expect(args.length).toBeGreaterThan(0); return { id: "job_priority_strip" }; }); const queue = { add } as unknown as TypedQueue; const descriptor = buildWebhookDeliveryJob({ url: "https://example.com/wh", eventName: "evt" }); await enqueueJob(queue, descriptor, { tenantId: "tenant_1", priorityOverride: "low" }); const forwarded = add.mock.calls[0]?.[2]; expect(forwarded).not.toHaveProperty("tenantId"); expect(forwarded).not.toHaveProperty("priorityOverride"); expect(forwarded).toMatchObject({ priority: JOB_PRIORITY_LOW }); }); test("no priority set when neither tenantId nor override provided", async () => { const add = vi.fn(async (...args: [string, unknown, unknown?]) => { expect(args.length).toBeGreaterThan(0); return { id: "job_priority_none" }; }); const queue = { add } as unknown as TypedQueue; const descriptor = buildWebhookDeliveryJob({ url: "https://example.com/wh", eventName: "evt" }); await enqueueJob(queue, descriptor); expect(add.mock.calls[0]?.[2]).not.toHaveProperty("priority"); }); test("invokes registered enqueue observer with priority label", async () => { const observer = vi.fn(); setEnqueueObserver(observer); const add = vi.fn(async (...args: [string, unknown, unknown?]) => { expect(args.length).toBeGreaterThan(0); return { id: "job_observer" }; }); const queue = { add } as unknown as TypedQueue; const descriptor = buildWebhookDeliveryJob({ url: "https://example.com/wh", eventName: "evt" }); await enqueueJob(queue, descriptor, { tenantId: null }); expect(observer).toHaveBeenCalledWith({ queueName: queueNames.email, jobName: "deliver-webhook", priority: JOB_PRIORITY_CRITICAL, priorityLabel: "critical", }); }); test("observer throw never blocks enqueue", async () => { setEnqueueObserver(() => { throw new Error("metrics broken"); }); const add = vi.fn(async (...args: [string, unknown, unknown?]) => { expect(args.length).toBeGreaterThan(0); return { id: "job_observer_err" }; }); const queue = { add } as unknown as TypedQueue; const descriptor = buildWebhookDeliveryJob({ url: "https://example.com/wh", eventName: "evt" }); await expect(enqueueJob(queue, descriptor, { tenantId: null })).resolves.toEqual({ id: "job_observer_err" }); expect(add).toHaveBeenCalledTimes(1); }); });