import type { JobsOptions } from "./types.js"; /** Queue contract shared by the Aircall ingress and telephony webhook worker. */ export const TELEPHONY_WEBHOOK_QUEUE_NAME = "hivegrid.telephony-webhooks" as const; export const TELEPHONY_WEBHOOK_JOB_NAME = "process-telephony-webhook" as const; export type TelephonyWebhookProcessJob = { readonly kind: "telephony.webhook.process"; readonly tenantId: string; readonly connectionId: string; readonly webhookEventId: string; }; export type TelephonyWebhookJobDescriptor = { readonly queueName: typeof TELEPHONY_WEBHOOK_QUEUE_NAME; readonly jobName: typeof TELEPHONY_WEBHOOK_JOB_NAME; readonly payload: TelephonyWebhookProcessJob; }; export type TelephonyWebhookQueue = { add(jobName: typeof TELEPHONY_WEBHOOK_JOB_NAME, payload: TelephonyWebhookProcessJob, options?: JobsOptions): Promise<{ id?: string }>; close(): Promise; }; export type TelephonyWebhookRetainedJob = { readonly id?: string; getState(): Promise; retry(state?: "failed" | "completed", options?: { resetAttemptsMade?: boolean; resetAttemptsStarted?: boolean }): Promise; }; export type TelephonyWebhookRecoveryQueue = TelephonyWebhookQueue & { getJob(jobId: string): Promise; }; export type TelephonyWebhookJobInput = Omit; const MAX_IDENTIFIER_LENGTH = 191; function requireIdentifier(value: string, name: keyof TelephonyWebhookJobInput): string { const normalized = value.trim(); if (!normalized || normalized.length > MAX_IDENTIFIER_LENGTH || normalized.includes("\u0000")) { throw new Error(`Telephony webhook jobs require a valid ${name}.`); } return normalized; } export function buildTelephonyWebhookJob(input: TelephonyWebhookJobInput): TelephonyWebhookJobDescriptor { return { queueName: TELEPHONY_WEBHOOK_QUEUE_NAME, jobName: TELEPHONY_WEBHOOK_JOB_NAME, payload: { kind: "telephony.webhook.process", tenantId: requireIdentifier(input.tenantId, "tenantId"), connectionId: requireIdentifier(input.connectionId, "connectionId"), webhookEventId: requireIdentifier(input.webhookEventId, "webhookEventId"), }, }; } /** Enqueue by persisted event id so webhook retries collapse into one job. */ export async function enqueueTelephonyWebhookJob(queue: TelephonyWebhookQueue, descriptor: TelephonyWebhookJobDescriptor): Promise<{ id?: string }> { const jobId = `telephony-webhook-${descriptor.payload.webhookEventId}`; return queue.add(descriptor.jobName, descriptor.payload, { attempts: 5, backoff: { type: "exponential", delay: 2_000 }, jobId, removeOnComplete: 10_000, removeOnFail: 1_000, }); } /** * Requeue an event whose retained BullMQ job exhausted its attempts. * * A plain add with the stable event job id returns the retained failed job and * never schedules work. Manual retry keeps that idempotency key, while the * persisted webhook row remains the source of failure diagnostics. */ export async function recoverFailedTelephonyWebhookJob( queue: TelephonyWebhookRecoveryQueue, descriptor: TelephonyWebhookJobDescriptor ): Promise<{ id?: string }> { const jobId = `telephony-webhook-${descriptor.payload.webhookEventId}`; const retainedJob = await queue.getJob(jobId); if (retainedJob && (await retainedJob.getState()) === "failed") { await retainedJob.retry("failed", { resetAttemptsMade: true, resetAttemptsStarted: true }); return { id: retainedJob.id ?? jobId }; } return enqueueTelephonyWebhookJob(queue, descriptor); }