Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -1,17 +1,31 @@
import type { JobsOptions, TypedQueue } from "./types.js";
import { toBullMqJobId } from "./job-id.js";
import { queueNames, type QueueName } from "./names.js";
import type {
AdminSalesContactsExportJob,
AdminSalesContactsImportJob,
BrowserAutomationJob,
CleanupJob,
ExportJob,
FileImportJob,
FilePreviewJob,
FileScanJob,
ImportJob,
KwpImportJob,
KwpArchiveDiscoveryJob,
KwpArchiveFileSyncJob,
KwpContractSentinelJob,
KwpProjectCatalogSyncJob,
KwpProjectSyncJob,
NotificationJob,
PlatformNotificationJob,
PlatformNotificationRequestedOutboxEvent,
PlatformNotificationSafeMetadata,
PluginInvokeJob,
QueueJobDescriptor,
QueueJsonValue,
TransactionalMailJob,
TenantNotificationJob,
WebhookDeliveryJob,
WorkflowExecutionContinueRequestedOutboxEvent,
WorkflowExecutionRequestedOutboxEvent,
@@ -19,11 +33,15 @@ import type {
} from "./payloads.js";
import { JOB_PRIORITY_CRITICAL, priorityFromOverride, priorityLabel, resolveJobPriorityForTenant, type PriorityOverride } from "./priority.js";
/** Keep idempotency effective without allowing completed BullMQ jobs to grow forever. */
export const IDEMPOTENT_JOB_RETENTION_COUNT = 10_000;
type BrowserAutomationJobForKind<Kind extends BrowserAutomationJob["kind"]> = BrowserAutomationJob & { kind: Kind };
export type TransactionalMailJobInput = Omit<TransactionalMailJob, "kind">;
export type WebhookDeliveryJobInput = Omit<WebhookDeliveryJob, "kind">;
export type NotificationJobInput = Omit<NotificationJob, "kind">;
export type NotificationJobInput = Omit<TenantNotificationJob, "kind">;
export type PlatformNotificationJobInput = Omit<PlatformNotificationJob, "kind" | "tenantId">;
export type CleanupJobInput = Omit<CleanupJob, "kind">;
export type BrowserSessionRunJobInput = Omit<BrowserAutomationJobForKind<"browser.session-run">, "kind">;
export type BrowserSessionCleanupJobInput = Omit<BrowserAutomationJobForKind<"browser.session-cleanup">, "kind">;
@@ -31,7 +49,20 @@ export type BrowserUsageFlushJobInput = Omit<BrowserAutomationJobForKind<"usage.
export type FileScanJobInput = Omit<FileScanJob, "kind">;
export type FilePreviewJobInput = Omit<FilePreviewJob, "kind">;
export type ExportJobInput = Omit<ExportJob, "kind">;
export type ImportJobInput = Omit<ImportJob, "kind">;
export type ImportJobInput = Omit<FileImportJob, "kind">;
export type AdminSalesContactsImportJobInput = Omit<
AdminSalesContactsImportJob,
"kind"
>;
export type AdminSalesContactsExportJobInput = Omit<
AdminSalesContactsExportJob,
"kind"
>;
export type KwpProjectSyncJobInput = Omit<KwpProjectSyncJob, "kind">;
export type KwpProjectCatalogSyncJobInput = Omit<KwpProjectCatalogSyncJob, "kind">;
export type KwpContractSentinelJobInput = Omit<KwpContractSentinelJob, "kind">;
export type KwpArchiveDiscoveryJobInput = Omit<KwpArchiveDiscoveryJob, "kind">;
export type KwpArchiveFileSyncJobInput = Omit<KwpArchiveFileSyncJob, "kind">;
export type PluginInvokeJobInput = Omit<PluginInvokeJob, "kind">;
export type WorkflowTriggerOutboxEventInput = {
tenantId: string | null;
@@ -41,6 +72,17 @@ export type WorkflowTriggerOutboxEventInput = {
sourceId: string;
};
export const PORTAL_DOCUMENT_READY_EVENT = "portal.document_ready" as const;
export type PortalDocumentReadyOutboxEventInput = {
tenantId: string;
projectId: string;
fileId: string;
fileEntityLinkId: string;
linkVersion: Date;
userId: string | null;
};
export type WorkflowExecutionRequestedOutboxEventInput = {
tenantId: string | null;
workflowId: string;
@@ -53,7 +95,14 @@ export type WorkflowExecutionRequestedOutboxEventInput = {
export type WorkflowExecutionContinueRequestedOutboxEventInput = WorkflowExecutionRequestedOutboxEventInput;
export type PlatformNotificationRequestedOutboxEventInput = Omit<PlatformNotificationRequestedOutboxEvent["payload"], "metadata"> & {
metadata?: PlatformNotificationSafeMetadata;
};
const WORKFLOW_OUTBOX_SOURCE_ID_PATTERN = /^[A-Za-z0-9._:-]{1,234}$/u;
const PLATFORM_NOTIFICATION_IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/u;
const PLATFORM_NOTIFICATION_MESSAGE_KEY_PATTERN = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/u;
const PLATFORM_NOTIFICATION_DEEPLINK_PATTERN = /^\/[A-Za-z0-9/_-]{1,239}$/u;
function requireWorkflowOutboxText(value: string, fieldName: string, eventType: string): string {
const trimmed = value.trim();
@@ -71,6 +120,50 @@ function requireWorkflowOutboxSourceId(value: string, eventType: string): string
return sourceId;
}
function requirePlatformNotificationIdentifier(value: string, field: string): string {
const normalized = value?.trim();
if (!normalized || !PLATFORM_NOTIFICATION_IDENTIFIER_PATTERN.test(normalized)) {
throw new Error(`Platform notifications require ${field} to be a stable non-secret identifier.`);
}
return normalized;
}
function requirePlatformNotificationMessageKey(value: string): string {
const normalized = value?.trim();
if (!normalized || !PLATFORM_NOTIFICATION_MESSAGE_KEY_PATTERN.test(normalized)) {
throw new Error("Platform notifications require a valid messageKey.");
}
return normalized;
}
function normalizePlatformNotificationChannel(value: string): "email" | "in-app" {
if (value === "email" || value === "in-app") {
return value;
}
throw new Error(`Unsupported platform notification channel: ${value}`);
}
function sanitizePlatformNotificationMetadata(metadata?: PlatformNotificationSafeMetadata): PlatformNotificationSafeMetadata | undefined {
if (!metadata) return undefined;
const sanitized: PlatformNotificationSafeMetadata = {};
for (const key of ["deliveryId", "eventId", "leadId", "taskId", "requestId", "sourceId"] as const) {
const value = metadata[key];
if (typeof value === "string" && PLATFORM_NOTIFICATION_IDENTIFIER_PATTERN.test(value.trim())) {
sanitized[key] = value.trim();
}
}
if (typeof metadata.eventType === "string" && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/u.test(metadata.eventType.trim())) {
sanitized.eventType = metadata.eventType.trim();
}
if (typeof metadata.deeplink === "string" && PLATFORM_NOTIFICATION_DEEPLINK_PATTERN.test(metadata.deeplink.trim())) {
sanitized.deeplink = metadata.deeplink.trim();
}
if (typeof metadata.replay === "boolean") {
sanitized.replay = metadata.replay;
}
return Object.keys(sanitized).length > 0 ? sanitized : undefined;
}
export type TransactionalMailJobDescriptor = QueueJobDescriptor<typeof queueNames.email> & {
jobName: "send-transactional-email";
payload: TransactionalMailJob;
@@ -126,6 +219,11 @@ export type ImportJobDescriptor = QueueJobDescriptor<typeof queueNames.imports>
payload: ImportJob;
};
export type KwpImportJobDescriptor = QueueJobDescriptor<typeof queueNames.kwpImports> & {
jobName: "run-kwp-import";
payload: KwpImportJob;
};
export type PluginInvokeJobDescriptor = QueueJobDescriptor<typeof queueNames.pluginInvoke> & {
jobName: "invoke-plugin";
payload: PluginInvokeJob;
@@ -143,6 +241,7 @@ export type ProducerJobDescriptor =
| FilePreviewJobDescriptor
| ExportJobDescriptor
| ImportJobDescriptor
| KwpImportJobDescriptor
| PluginInvokeJobDescriptor;
const retryJobOptionsByQueueAndJobName: {
@@ -162,6 +261,15 @@ const retryJobOptionsByQueueAndJobName: {
// one retry on transient Prisma/Redis hiccups before letting the
// next 24h tick recover the run.
"dsgvo-grace-period-scan": { attempts: 2, backoff: { type: "fixed", delay: 30_000 } },
// AK-P21 tenant hard-delete scan: idempotent per tick (only overdue
// pending requests match); one retry for transient infra hiccups.
"privacy-tenant-deletion-scan": { attempts: 2, backoff: { type: "fixed", delay: 30_000 } },
// VA-P26b portal lifecycle scan: every mutation is claimed/idempotent and
// the daily scheduler provides the long-stop retry. One near-term retry
// covers transient database or object-storage failures.
"portal-lifecycle-scan": { attempts: 2, backoff: { type: "fixed", delay: 30_000 } },
"product-acquisition-reconcile": { attempts: 2, backoff: { type: "fixed", delay: 5_000 } },
"telephony-webhook-maintenance": { attempts: 2, backoff: { type: "fixed", delay: 5_000 } },
},
[queueNames.browserAutomation]: {
"browser-session-run": { attempts: 2, backoff: { type: "exponential", delay: 5_000 } },
@@ -183,6 +291,9 @@ const retryJobOptionsByQueueAndJobName: {
[queueNames.imports]: {
"run-import": { attempts: 2, backoff: { type: "exponential", delay: 10_000 } },
},
[queueNames.kwpImports]: {
"run-kwp-import": { attempts: 5, backoff: { type: "exponential", delay: 30_000 } },
},
[queueNames.pluginInvoke]: {
"invoke-plugin": { attempts: 3, backoff: { type: "exponential", delay: 2_000 } },
},
@@ -241,6 +352,45 @@ export function buildNotificationJob(input: NotificationJobInput): NotificationJ
};
}
export function buildPlatformNotificationJob(input: PlatformNotificationJobInput): NotificationJobDescriptor {
const userId = input.userId
? requirePlatformNotificationIdentifier(input.userId, "userId")
: undefined;
const adminUserId = input.adminUserId
? requirePlatformNotificationIdentifier(input.adminUserId, "adminUserId")
: undefined;
if (Boolean(userId) === Boolean(adminUserId)) {
throw new Error(
"Platform notification jobs require exactly one recipient identity."
);
}
const sourceKey = requirePlatformNotificationIdentifier(input.sourceKey, "sourceKey");
const channel = normalizePlatformNotificationChannel(input.channel);
const messageKey = requirePlatformNotificationMessageKey(input.messageKey);
const metadata = sanitizePlatformNotificationMetadata(input.metadata);
return {
queueName: queueNames.notifications,
jobName: "send-notification",
payload: {
kind: "notification.platform.send",
tenantId: null,
...(userId ? { userId } : { adminUserId }),
sourceKey,
channel,
messageKey,
...(input.category?.trim() ? { category: input.category.trim().toLowerCase() } : {}),
...(input.email?.trim() ? { email: input.email.trim() } : {}),
...(input.subject ? { subject: input.subject } : {}),
...(input.text ? { text: input.text } : {}),
...(input.html ? { html: input.html } : {}),
...(input.templateId ? { templateId: input.templateId } : {}),
...(input.templateData ? { templateData: input.templateData } : {}),
...(metadata ? { metadata } : {}),
},
};
}
export function buildCleanupJob(input: CleanupJobInput): CleanupJobDescriptor {
return {
queueName: queueNames.maintenance,
@@ -335,6 +485,124 @@ export function buildImportJob(input: ImportJobInput): ImportJobDescriptor {
};
}
export function buildAdminSalesContactsImportJob(
input: AdminSalesContactsImportJobInput
): ImportJobDescriptor {
requireAdminSalesDataJobInput(
input.importJobId,
input.requestedByAdminUserId,
"import"
);
return {
queueName: queueNames.imports,
jobName: "run-import",
payload: { kind: "admin-sales.contacts-import", ...input },
};
}
export function buildAdminSalesContactsExportJob(
input: AdminSalesContactsExportJobInput
): ImportJobDescriptor {
requireAdminSalesDataJobInput(
input.exportJobId,
input.requestedByAdminUserId,
"export"
);
return {
queueName: queueNames.imports,
jobName: "run-import",
payload: { kind: "admin-sales.contacts-export", ...input },
};
}
function requireAdminSalesDataJobInput(
jobId: string,
requestedByAdminUserId: string,
operation: "import" | "export"
): void {
if (!jobId?.trim() || !requestedByAdminUserId?.trim()) {
throw new Error(
`Admin sales contacts ${operation} jobs require stable job and operator identifiers.`
);
}
}
export function buildKwpProjectSyncJob(input: KwpProjectSyncJobInput): KwpImportJobDescriptor {
if (!input.tenantId.trim() || !input.bindingId.trim() || !input.dataConnectionId.trim() || !input.cadenceBucket.trim()) {
throw new Error("KWP project sync jobs require stable tenant, binding, connection and cadence identifiers.");
}
return {
queueName: queueNames.kwpImports,
jobName: "run-kwp-import",
payload: { kind: "kwp.project-sync", ...input },
};
}
export function buildKwpProjectCatalogSyncJob(input: KwpProjectCatalogSyncJobInput): KwpImportJobDescriptor {
if (!input.tenantId.trim() || !input.dataConnectionId.trim() || !input.cadenceBucket.trim()) {
throw new Error("KWP project catalog jobs require stable tenant, connection and cadence identifiers.");
}
return {
queueName: queueNames.kwpImports,
jobName: "run-kwp-import",
payload: { kind: "kwp.project-catalog-sync", ...input },
};
}
export function buildKwpContractSentinelJob(input: KwpContractSentinelJobInput): KwpImportJobDescriptor {
if (!input.tenantId.trim() || !input.dataConnectionId.trim() || !input.cadenceBucket.trim()) {
throw new Error("KWP contract sentinel jobs require stable tenant, connection and cadence identifiers.");
}
return {
queueName: queueNames.kwpImports,
jobName: "run-kwp-import",
payload: { kind: "kwp.contract-sentinel", ...input },
};
}
export function buildKwpArchiveDiscoveryJob(input: KwpArchiveDiscoveryJobInput): KwpImportJobDescriptor {
const folderIds = input.cursor
? [...input.cursor.pendingFolderIds, ...input.cursor.visitedFolderIds]
: [];
if (
!input.tenantId.trim()
|| !input.bindingId.trim()
|| !input.dataConnectionId.trim()
|| !input.cadenceBucket.trim()
|| !Number.isInteger(input.batchNumber)
|| input.batchNumber < 0
|| folderIds.length > 1_000
|| folderIds.some((folderId) => !Number.isInteger(folderId) || folderId < -2_147_483_648 || folderId > 2_147_483_647)
|| (input.cursor !== undefined && input.cursor.pendingFolderIds.length === 0)
) {
throw new Error("KWP archive discovery jobs require a stable project binding and a bounded folder cursor.");
}
return {
queueName: queueNames.kwpImports,
jobName: "run-kwp-import",
payload: { kind: "kwp.archive-discovery", ...input },
};
}
export function buildKwpArchiveFileSyncJob(input: KwpArchiveFileSyncJobInput): KwpImportJobDescriptor {
if (
!input.tenantId.trim()
|| !input.bindingId.trim()
|| !input.dataConnectionId.trim()
|| !input.cadenceBucket.trim()
|| !input.archiveFile.externalId.trim()
|| !input.archiveFile.displayName.trim()
|| !Number.isInteger(input.archiveFile.revisionId)
) {
throw new Error("KWP archive file jobs require stable tenant, binding, connection, cadence and revision identifiers.");
}
return {
queueName: queueNames.kwpImports,
jobName: "run-kwp-import",
payload: { kind: "kwp.archive-file-sync", ...input },
};
}
export function buildPluginInvokeJob(input: PluginInvokeJobInput): PluginInvokeJobDescriptor {
return {
queueName: queueNames.pluginInvoke,
@@ -362,6 +630,25 @@ export function buildWorkflowTriggerOutboxEvent(input: WorkflowTriggerOutboxEven
};
}
/**
* Internal, DB-backed producer contract for customer-portal auto release.
* It deliberately carries no document type; the consumer must resolve the
* authoritative FileEntityLink.linkRole inside its tenant transaction.
*/
export function buildPortalDocumentReadyOutboxEvent(input: PortalDocumentReadyOutboxEventInput): WorkflowTriggerOutboxEvent {
return buildWorkflowTriggerOutboxEvent({
tenantId: input.tenantId,
event: PORTAL_DOCUMENT_READY_EVENT,
data: {
projectId: input.projectId,
fileId: input.fileId,
fileEntityLinkId: input.fileEntityLinkId,
},
userId: input.userId,
sourceId: `portal-document-ready:${input.fileEntityLinkId}:${input.linkVersion.getTime()}`,
});
}
export function buildWorkflowExecutionRequestedOutboxEvent(input: WorkflowExecutionRequestedOutboxEventInput): WorkflowExecutionRequestedOutboxEvent {
const eventType = "workflow.execution.requested";
const workflowId = requireWorkflowOutboxText(input.workflowId, "workflowId", eventType);
@@ -402,6 +689,44 @@ export function buildWorkflowExecutionContinueRequestedOutboxEvent(
};
}
export function buildPlatformNotificationRequestedOutboxEvent(input: PlatformNotificationRequestedOutboxEventInput): PlatformNotificationRequestedOutboxEvent {
const deliveryId = requirePlatformNotificationIdentifier(input.deliveryId, "deliveryId");
const userId = input.userId
? requirePlatformNotificationIdentifier(input.userId, "userId")
: undefined;
const adminUserId = input.adminUserId
? requirePlatformNotificationIdentifier(input.adminUserId, "adminUserId")
: undefined;
if (Boolean(userId) === Boolean(adminUserId)) {
throw new Error(
"Platform notification outbox events require exactly one recipient identity."
);
}
const sourceKey = requirePlatformNotificationIdentifier(input.sourceKey, "sourceKey");
const channel = normalizePlatformNotificationChannel(input.channel);
const messageKey = requirePlatformNotificationMessageKey(input.messageKey);
const metadata = sanitizePlatformNotificationMetadata(input.metadata);
const outboxMetadata = { ...(metadata ?? {}) };
delete outboxMetadata.deliveryId;
return {
tenantId: null,
type: "notification.platform.requested.v1",
payload: {
deliveryId,
...(userId ? { userId } : { adminUserId }),
sourceKey,
channel,
messageKey,
...(input.category?.trim() ? { category: input.category.trim().toLowerCase() } : {}),
...(Object.keys(outboxMetadata).length > 0 ? { metadata: outboxMetadata } : {}),
},
// The delivery id is stable across replay and distinct per recipient, while
// sourceKey may intentionally be shared by multiple configured recipients.
dispatchKey: `platform-notification:${deliveryId}`,
};
}
export type QueueEnqueueOptions = JobsOptions & {
idempotencyKey?: string;
/**
@@ -439,24 +764,24 @@ export function getEnqueueObserver(): EnqueueObserver | null {
export function buildIdempotentJobId(descriptor: ProducerJobDescriptor, options?: QueueEnqueueOptions): string | undefined {
if (typeof options?.jobId === "string") {
return options.jobId;
return toBullMqJobId(options.jobId);
}
if (typeof options?.idempotencyKey === "string") {
return options.idempotencyKey;
return toBullMqJobId(options.idempotencyKey);
}
if (descriptor.payload.kind === "export.run") {
return descriptor.payload.exportJobId;
return toBullMqJobId(descriptor.payload.exportJobId);
}
if (descriptor.payload.kind === "import.run") {
return descriptor.payload.importJobId;
return toBullMqJobId(descriptor.payload.importJobId);
}
const metadata = descriptor.payload.metadata;
const metadata = descriptor.payload.metadata as Record<string, unknown> | undefined;
if (metadata && typeof metadata.idempotencyKey === "string") {
return metadata.idempotencyKey;
return toBullMqJobId(metadata.idempotencyKey);
}
return undefined;
@@ -495,7 +820,7 @@ export async function enqueueJob<Name extends QueueName>(queue: TypedQueue<Name>
delete (callerOptions as QueueEnqueueOptions).priorityOverride;
const jobId = buildIdempotentJobId(producerDescriptor, options);
const idempotentCompletionRetention: Pick<JobsOptions, "removeOnComplete"> =
jobId && callerOptions.removeOnComplete === undefined ? { removeOnComplete: false } : {};
jobId && callerOptions.removeOnComplete === undefined ? { removeOnComplete: IDEMPOTENT_JOB_RETENTION_COUNT } : {};
const resolvedPriority = await resolvePriorityForEnqueue(options);
const priorityOptions: Pick<JobsOptions, "priority"> = resolvedPriority !== undefined ? { priority: resolvedPriority } : {};
const enqueueOptions: JobsOptions = {