Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/mail/src/queue.ts
T
2026-07-08 16:15:37 +02:00

163 lines
5.1 KiB
TypeScript

import {
buildTransactionalMailJob,
enqueueJob,
queueNames,
resolveRedisConnectionOptions,
type QueueEnqueueOptions,
type ConnectionOptions,
type RedisConnectionEnv,
type TypedQueue,
} from "@hivegrid/queue";
import { MailProviderError, type MailPersonalization, type MailProvider, type SendMailInput, type SendMailResult } from "./types.js";
export type QueueMailProviderWarning = {
code: "missing_redis_connection";
message: string;
requiredEnv: readonly ["BULLMQ_REDIS_URL", "REDIS_URL"];
};
export type QueueMailProviderOptions = {
queue: TypedQueue<typeof queueNames.email>;
enqueueOptions?: QueueEnqueueOptions;
};
export type QueueMailProviderEnv = RedisConnectionEnv;
export type QueueMailProviderFromEnvOptions = {
env?: QueueMailProviderEnv;
enqueueOptions?: QueueEnqueueOptions;
};
type QueueJobResult = Awaited<ReturnType<TypedQueue<typeof queueNames.email>["add"]>>;
export class QueuedMailProvider implements MailProvider {
readonly id = "queue" as const;
private readonly queue: TypedQueue<typeof queueNames.email>;
private readonly enqueueOptions?: QueueEnqueueOptions;
constructor(options: QueueMailProviderOptions) {
this.queue = options.queue;
this.enqueueOptions = options.enqueueOptions;
}
async send(input: SendMailInput): Promise<SendMailResult> {
const descriptor = toTransactionalMailJob(input);
const enqueueOptions: QueueEnqueueOptions = {
...(this.enqueueOptions ?? {}),
...(input.tenantId !== undefined ? { tenantId: input.tenantId } : {}),
...(input.priorityOverride !== undefined ? { priorityOverride: input.priorityOverride } : {}),
};
const job = (await enqueueJob(this.queue, descriptor, enqueueOptions)) as QueueJobResult;
return {
provider: this.id,
status: "queued",
messageId: job.id,
warnings: {
queueName: descriptor.queueName,
jobName: descriptor.jobName,
},
};
}
}
export function createQueuedMailProvider(options: QueueMailProviderOptions): MailProvider {
return new QueuedMailProvider(options);
}
export function createQueuedMailProviderFromEnv(options: QueueMailProviderFromEnvOptions = {}): MailProvider {
const connection = resolveRedisConnectionOptions({ env: options.env });
if (!connection) {
return new MissingRedisQueuedMailProvider();
}
return new LazyQueuedMailProvider(connection, options.enqueueOptions);
}
class LazyQueuedMailProvider implements MailProvider {
readonly id = "queue" as const;
constructor(
private readonly connection: ConnectionOptions,
private readonly enqueueOptions?: QueueEnqueueOptions
) {}
async send(input: SendMailInput): Promise<SendMailResult> {
const { createQueue } = await import("@hivegrid/queue/runtime");
const queue = createQueue(queueNames.email, { connection: this.connection });
try {
return await new QueuedMailProvider({ queue, enqueueOptions: this.enqueueOptions }).send(input);
} finally {
await queue.close();
}
}
}
class MissingRedisQueuedMailProvider implements MailProvider {
readonly id = "queue" as const;
async send(): Promise<SendMailResult> {
const warning = missingRedisWarning();
throw new MailProviderError(warning.message, { provider: this.id, responseBody: warning });
}
}
function toTransactionalMailJob(input: SendMailInput) {
if (input.to.length === 0) {
throw new MailProviderError("At least one recipient is required.", { provider: "queue" });
}
if (!input.text && !input.html && !input.templateId) {
throw new MailProviderError("Email text, html or templateId is required.", { provider: "queue" });
}
return buildTransactionalMailJob({
from: input.from,
to: input.to,
cc: input.cc,
bcc: input.bcc,
replyTo: input.replyTo,
subject: input.subject,
text: input.text,
html: input.html,
templateId: input.templateId,
attachments: input.attachments,
tags: input.tags,
precedenceBulk: input.precedenceBulk,
sendAt: normalizeQueuedSendAt(input.sendAt),
inReplyTo: input.inReplyTo,
references: input.references,
settings: input.settings,
headers: input.headers,
listUnsubscribe: input.listUnsubscribe,
...(input.tenantId !== undefined && input.tenantId !== null ? { tenantId: input.tenantId } : {}),
templateData: personalizationToTemplateData(input.personalization),
metadata: input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : undefined,
});
}
function personalizationToTemplateData(personalization: readonly MailPersonalization[] | undefined): Record<string, unknown> | undefined {
if (!personalization?.length) {
return undefined;
}
return Object.fromEntries(personalization.map((entry) => [entry.email, entry.data]));
}
function normalizeQueuedSendAt(sendAt: SendMailInput["sendAt"]): number | undefined {
if (sendAt instanceof Date) {
return Math.floor(sendAt.getTime() / 1000);
}
return sendAt;
}
function missingRedisWarning(): QueueMailProviderWarning {
return {
code: "missing_redis_connection",
message: "Set BULLMQ_REDIS_URL or REDIS_URL to enqueue transactional email jobs.",
requiredEnv: ["BULLMQ_REDIS_URL", "REDIS_URL"],
};
}