Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,476 @@
|
||||
import { MailProviderError, type MailAddress, type MailAddressInput, type MailProvider, type SendMailInput, type SendMailResult } from "./types.js";
|
||||
|
||||
export const mailjetApiBaseUrl = "https://api.mailjet.com";
|
||||
const DEFAULT_MAILJET_TIMEOUT_MS = 10_000;
|
||||
const DEFAULT_RESPONSE_BODY_LIMIT_BYTES = 4_096;
|
||||
|
||||
type Fetch = typeof fetch;
|
||||
|
||||
type MailjetAddress = {
|
||||
Email: string;
|
||||
Name?: string;
|
||||
};
|
||||
|
||||
type MailjetAttachment = {
|
||||
ContentType: string;
|
||||
Filename: string;
|
||||
Base64Content: string;
|
||||
ContentID?: string;
|
||||
};
|
||||
|
||||
type MailjetMessage = {
|
||||
From: MailjetAddress;
|
||||
To: MailjetAddress[];
|
||||
Cc?: MailjetAddress[];
|
||||
Bcc?: MailjetAddress[];
|
||||
ReplyTo?: MailjetAddress;
|
||||
Subject?: string;
|
||||
TextPart?: string;
|
||||
HTMLPart?: string;
|
||||
TemplateID?: number;
|
||||
TemplateLanguage?: boolean;
|
||||
Variables?: Record<string, unknown>;
|
||||
Attachments?: MailjetAttachment[];
|
||||
InlinedAttachments?: MailjetAttachment[];
|
||||
Headers?: Record<string, string>;
|
||||
CustomCampaign?: string;
|
||||
TrackOpens?: "enabled" | "disabled";
|
||||
TrackClicks?: "enabled" | "disabled";
|
||||
CustomID?: string;
|
||||
};
|
||||
|
||||
type MailjetSendRequest = {
|
||||
Messages: MailjetMessage[];
|
||||
SandboxMode?: boolean;
|
||||
};
|
||||
|
||||
export type MailMetricsHook = (input: { provider: "mailjet"; status: "delivered" | "failed" }) => void;
|
||||
|
||||
export type MailjetProviderOptions = {
|
||||
apiKey: string;
|
||||
secretKey: string;
|
||||
fromEmail: string;
|
||||
fromName?: string;
|
||||
baseUrl?: string;
|
||||
fetch?: Fetch;
|
||||
timeoutMs?: number;
|
||||
responseBodyLimitBytes?: number;
|
||||
/**
|
||||
* When true, the request is sent with Mailjet's `SandboxMode` flag so the
|
||||
* payload is validated (auth, addresses, mapping) without actually
|
||||
* delivering mail. Wire this to a staging/test toggle — never enable in
|
||||
* production paths.
|
||||
*/
|
||||
sandbox?: boolean;
|
||||
/**
|
||||
* Optional hook invoked once per send (`status: "delivered"` on HTTP 2xx
|
||||
* with all messages accepted, `"failed"` otherwise). The hook MUST NOT throw
|
||||
* — the provider wraps it in a try/catch so a misbehaving hook can't block
|
||||
* mail delivery. Wire to mail_sent_total in the host app's metrics package.
|
||||
*/
|
||||
onMetric?: MailMetricsHook;
|
||||
};
|
||||
|
||||
export type MailjetEnv = Record<string, string | undefined> & {
|
||||
MAILJET_API_KEY?: string;
|
||||
MAILJET_SECRET_KEY?: string;
|
||||
MAILJET_FROM_EMAIL?: string;
|
||||
MAILJET_FROM_NAME?: string;
|
||||
};
|
||||
|
||||
export class MailjetProvider implements MailProvider {
|
||||
readonly id = "mailjet" as const;
|
||||
|
||||
private readonly authorization: string;
|
||||
private readonly defaultFrom: MailAddress;
|
||||
private readonly baseUrl: string;
|
||||
private readonly fetchImpl: Fetch;
|
||||
private readonly timeoutMs: number;
|
||||
private readonly responseBodyLimitBytes: number;
|
||||
private readonly sandbox: boolean;
|
||||
private readonly onMetric: MailMetricsHook | undefined;
|
||||
|
||||
constructor(options: MailjetProviderOptions) {
|
||||
const apiKey = requireNonEmpty(options.apiKey, "MAILJET_API_KEY");
|
||||
const secretKey = requireNonEmpty(options.secretKey, "MAILJET_SECRET_KEY");
|
||||
this.authorization = `Basic ${Buffer.from(`${apiKey}:${secretKey}`, "utf8").toString("base64")}`;
|
||||
this.defaultFrom = {
|
||||
email: requireNonEmpty(options.fromEmail, "MAILJET_FROM_EMAIL"),
|
||||
...(options.fromName ? { name: options.fromName } : {}),
|
||||
};
|
||||
this.baseUrl = (options.baseUrl ?? mailjetApiBaseUrl).replace(/\/+$/, "");
|
||||
this.fetchImpl = options.fetch ?? fetch;
|
||||
this.timeoutMs = normalizePositiveInteger(options.timeoutMs, DEFAULT_MAILJET_TIMEOUT_MS);
|
||||
this.responseBodyLimitBytes = normalizePositiveInteger(options.responseBodyLimitBytes, DEFAULT_RESPONSE_BODY_LIMIT_BYTES);
|
||||
this.sandbox = options.sandbox ?? false;
|
||||
this.onMetric = options.onMetric;
|
||||
}
|
||||
|
||||
private emitMetric(status: "delivered" | "failed"): void {
|
||||
if (!this.onMetric) return;
|
||||
try {
|
||||
this.onMetric({ provider: "mailjet", status });
|
||||
} catch {
|
||||
// Metric hook must never abort the send flow.
|
||||
}
|
||||
}
|
||||
|
||||
async send(input: SendMailInput): Promise<SendMailResult> {
|
||||
const payload = toMailjetSendRequest(input, this.defaultFrom, this.sandbox);
|
||||
let response: Response;
|
||||
try {
|
||||
response = await fetchWithTimeout(
|
||||
this.fetchImpl,
|
||||
`${this.baseUrl}/v3.1/send`,
|
||||
{
|
||||
method: "POST",
|
||||
headers: {
|
||||
Authorization: this.authorization,
|
||||
"Content-Type": "application/json",
|
||||
Accept: "application/json",
|
||||
},
|
||||
body: JSON.stringify(payload),
|
||||
},
|
||||
this.timeoutMs,
|
||||
);
|
||||
} catch (error) {
|
||||
this.emitMetric("failed");
|
||||
if (isAbortError(error)) {
|
||||
throw new MailProviderError("Mailjet email request timed out.", { provider: this.id });
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
|
||||
const responseBody = await parseResponseBody(response, this.responseBodyLimitBytes);
|
||||
|
||||
if (!response.ok) {
|
||||
this.emitMetric("failed");
|
||||
throw new MailProviderError(`Mailjet email request failed with ${response.status}.`, {
|
||||
provider: this.id,
|
||||
statusCode: response.status,
|
||||
responseBody,
|
||||
});
|
||||
}
|
||||
|
||||
// Mailjet returns HTTP 200 even when individual messages fail; the
|
||||
// per-message Status carries the real outcome.
|
||||
const messages = extractMessages(responseBody);
|
||||
const rejected = messages.find((message) => typeof message.Status === "string" && message.Status.toLowerCase() !== "success");
|
||||
if (rejected) {
|
||||
this.emitMetric("failed");
|
||||
throw new MailProviderError("Mailjet rejected at least one message.", {
|
||||
provider: this.id,
|
||||
statusCode: response.status,
|
||||
responseBody,
|
||||
});
|
||||
}
|
||||
|
||||
this.emitMetric("delivered");
|
||||
return {
|
||||
provider: this.id,
|
||||
status: "queued",
|
||||
messageId: extractMessageId(messages),
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
export function createMailjetProvider(options: MailjetProviderOptions): MailProvider {
|
||||
return new MailjetProvider(options);
|
||||
}
|
||||
|
||||
export function createMailjetProviderFromEnv(env: MailjetEnv, options?: { onMetric?: MailMetricsHook; sandbox?: boolean }): MailProvider {
|
||||
return new MailjetProvider({
|
||||
apiKey: requireNonEmpty(env.MAILJET_API_KEY, "MAILJET_API_KEY"),
|
||||
secretKey: requireNonEmpty(env.MAILJET_SECRET_KEY, "MAILJET_SECRET_KEY"),
|
||||
fromEmail: requireNonEmpty(env.MAILJET_FROM_EMAIL, "MAILJET_FROM_EMAIL"),
|
||||
fromName: env.MAILJET_FROM_NAME,
|
||||
...(options?.onMetric ? { onMetric: options.onMetric } : {}),
|
||||
...(options?.sandbox ? { sandbox: options.sandbox } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
function toMailjetSendRequest(input: SendMailInput, defaultFrom: MailAddress, sandbox: boolean): MailjetSendRequest {
|
||||
if (input.to.length === 0) {
|
||||
throw new MailProviderError("At least one recipient is required.", { provider: "mailjet" });
|
||||
}
|
||||
|
||||
if (!input.text && !input.html && !input.templateId) {
|
||||
throw new MailProviderError("Email text, html or templateId is required.", { provider: "mailjet" });
|
||||
}
|
||||
|
||||
const template = normalizeTemplateId(input.templateId);
|
||||
const { attachments, inlined } = normalizeAttachments(input.attachments);
|
||||
const headers = buildHeaders(input);
|
||||
|
||||
const baseMessage = compactObject<MailjetMessage>({
|
||||
From: normalizeAddress(input.from ?? defaultFrom),
|
||||
To: [],
|
||||
Cc: input.cc?.map(normalizeAddress),
|
||||
Bcc: input.bcc?.map(normalizeAddress),
|
||||
ReplyTo: input.replyTo ? normalizeAddress(input.replyTo) : undefined,
|
||||
Subject: input.subject,
|
||||
TextPart: input.text,
|
||||
HTMLPart: input.html,
|
||||
TemplateID: template,
|
||||
TemplateLanguage: template !== undefined ? true : undefined,
|
||||
Attachments: attachments,
|
||||
InlinedAttachments: inlined,
|
||||
Headers: headers,
|
||||
CustomCampaign: input.tags?.[0],
|
||||
TrackOpens: toTrackingFlag(input.settings?.trackOpens),
|
||||
TrackClicks: toTrackingFlag(input.settings?.trackClicks),
|
||||
CustomID: normalizeCustomId(input.idempotencyKey),
|
||||
});
|
||||
|
||||
const personalization = new Map((input.personalization ?? []).map((entry) => [entry.email, entry.data]));
|
||||
|
||||
let messages: MailjetMessage[];
|
||||
if (personalization.size > 1) {
|
||||
// Per-recipient Variables require one Mailjet message each. Cc/Bcc are
|
||||
// attached only to the first message so shared recipients aren't copied
|
||||
// once per personalized message.
|
||||
messages = input.to.map((addr, index) => {
|
||||
const recipient = normalizeAddress(addr);
|
||||
const variables = personalization.get(recipient.Email);
|
||||
return compactObject<MailjetMessage>({
|
||||
...baseMessage,
|
||||
...(index > 0 ? { Cc: undefined, Bcc: undefined } : {}),
|
||||
To: [recipient],
|
||||
Variables: variables,
|
||||
});
|
||||
});
|
||||
} else {
|
||||
messages = [
|
||||
compactObject<MailjetMessage>({
|
||||
...baseMessage,
|
||||
To: input.to.map(normalizeAddress),
|
||||
Variables: input.personalization?.[0]?.data,
|
||||
}),
|
||||
];
|
||||
}
|
||||
|
||||
return compactObject<MailjetSendRequest>({
|
||||
Messages: messages,
|
||||
SandboxMode: sandbox ? true : undefined,
|
||||
});
|
||||
}
|
||||
|
||||
function normalizeAddress(address: MailAddressInput): MailjetAddress {
|
||||
if (typeof address === "string") {
|
||||
return { Email: address };
|
||||
}
|
||||
|
||||
return compactObject<MailjetAddress>({
|
||||
Email: address.email,
|
||||
Name: address.name,
|
||||
});
|
||||
}
|
||||
|
||||
function normalizeTemplateId(templateId: string | undefined): number | undefined {
|
||||
if (templateId === undefined) {
|
||||
return undefined;
|
||||
}
|
||||
|
||||
const numeric = Number(templateId);
|
||||
if (!Number.isFinite(numeric)) {
|
||||
throw new MailProviderError("Mailjet TemplateID must be numeric.", { provider: "mailjet" });
|
||||
}
|
||||
|
||||
return numeric;
|
||||
}
|
||||
|
||||
function normalizeAttachments(attachments: SendMailInput["attachments"]): { attachments?: MailjetAttachment[]; inlined?: MailjetAttachment[] } {
|
||||
if (!attachments?.length) {
|
||||
return {};
|
||||
}
|
||||
|
||||
const regular: MailjetAttachment[] = [];
|
||||
const inlined: MailjetAttachment[] = [];
|
||||
|
||||
for (const attachment of attachments) {
|
||||
const mapped = compactObject<MailjetAttachment>({
|
||||
ContentType: guessContentType(attachment.filename),
|
||||
Filename: attachment.filename,
|
||||
Base64Content: attachment.content,
|
||||
ContentID: attachment.disposition === "inline" ? attachment.id ?? attachment.filename : undefined,
|
||||
});
|
||||
|
||||
if (attachment.disposition === "inline") {
|
||||
inlined.push(mapped);
|
||||
} else {
|
||||
regular.push(mapped);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
...(regular.length ? { attachments: regular } : {}),
|
||||
...(inlined.length ? { inlined } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
function buildHeaders(input: SendMailInput): Record<string, string> | undefined {
|
||||
const headers: Record<string, string> = {};
|
||||
|
||||
for (const header of input.headers ?? []) {
|
||||
headers[header.name] = header.value;
|
||||
}
|
||||
|
||||
if (input.inReplyTo) {
|
||||
headers["In-Reply-To"] = input.inReplyTo;
|
||||
}
|
||||
|
||||
if (input.references?.length) {
|
||||
headers["References"] = input.references.join(" ");
|
||||
}
|
||||
|
||||
if (input.listUnsubscribe) {
|
||||
headers["List-Unsubscribe"] = input.listUnsubscribe;
|
||||
}
|
||||
|
||||
if (input.precedenceBulk) {
|
||||
headers["Precedence"] = "bulk";
|
||||
}
|
||||
|
||||
return Object.keys(headers).length > 0 ? headers : undefined;
|
||||
}
|
||||
|
||||
function toTrackingFlag(value: boolean | undefined): "enabled" | "disabled" | undefined {
|
||||
if (value === undefined) {
|
||||
return undefined;
|
||||
}
|
||||
return value ? "enabled" : "disabled";
|
||||
}
|
||||
|
||||
function normalizeCustomId(idempotencyKey: string | undefined): string | undefined {
|
||||
if (!idempotencyKey) {
|
||||
return undefined;
|
||||
}
|
||||
// Mailjet caps CustomID at 100 characters.
|
||||
return idempotencyKey.slice(0, 100);
|
||||
}
|
||||
|
||||
type MailjetResponseMessage = {
|
||||
Status?: string;
|
||||
To?: Array<{ MessageUUID?: string; MessageID?: number; MessageHref?: string }>;
|
||||
};
|
||||
|
||||
function extractMessages(responseBody: unknown): MailjetResponseMessage[] {
|
||||
if (responseBody && typeof responseBody === "object" && "Messages" in responseBody) {
|
||||
const messages = (responseBody as { Messages?: unknown }).Messages;
|
||||
if (Array.isArray(messages)) {
|
||||
return messages as MailjetResponseMessage[];
|
||||
}
|
||||
}
|
||||
return [];
|
||||
}
|
||||
|
||||
function extractMessageId(messages: MailjetResponseMessage[]): string | undefined {
|
||||
const recipient = messages[0]?.To?.[0];
|
||||
if (!recipient) {
|
||||
return undefined;
|
||||
}
|
||||
return recipient.MessageUUID ?? (recipient.MessageID !== undefined ? String(recipient.MessageID) : undefined);
|
||||
}
|
||||
|
||||
function guessContentType(filename: string): string {
|
||||
const extension = filename.includes(".") ? filename.slice(filename.lastIndexOf(".") + 1).toLowerCase() : "";
|
||||
return CONTENT_TYPE_BY_EXTENSION[extension] ?? "application/octet-stream";
|
||||
}
|
||||
|
||||
const CONTENT_TYPE_BY_EXTENSION: Record<string, string> = {
|
||||
pdf: "application/pdf",
|
||||
png: "image/png",
|
||||
jpg: "image/jpeg",
|
||||
jpeg: "image/jpeg",
|
||||
gif: "image/gif",
|
||||
svg: "image/svg+xml",
|
||||
csv: "text/csv",
|
||||
txt: "text/plain",
|
||||
html: "text/html",
|
||||
ics: "text/calendar",
|
||||
json: "application/json",
|
||||
xml: "application/xml",
|
||||
zip: "application/zip",
|
||||
doc: "application/msword",
|
||||
docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
|
||||
xls: "application/vnd.ms-excel",
|
||||
xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
|
||||
};
|
||||
|
||||
function requireNonEmpty(value: string | undefined, name: string): string {
|
||||
if (!value?.trim()) {
|
||||
throw new MailProviderError(`${name} is required for Mailjet email delivery.`, { provider: "mailjet" });
|
||||
}
|
||||
|
||||
return value;
|
||||
}
|
||||
|
||||
function compactObject<T extends Record<string, unknown>>(value: T): T {
|
||||
return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as T;
|
||||
}
|
||||
|
||||
async function parseResponseBody(response: Response, limitBytes: number): Promise<unknown> {
|
||||
const text = await readLimitedResponseText(response, limitBytes);
|
||||
|
||||
if (!text) {
|
||||
return undefined;
|
||||
}
|
||||
|
||||
try {
|
||||
return JSON.parse(text);
|
||||
} catch {
|
||||
return text;
|
||||
}
|
||||
}
|
||||
|
||||
async function fetchWithTimeout(fetchImpl: Fetch, input: Parameters<Fetch>[0], init: RequestInit, timeoutMs: number): Promise<Response> {
|
||||
const controller = new AbortController();
|
||||
const timeout = setTimeout(() => controller.abort(), timeoutMs);
|
||||
|
||||
try {
|
||||
return await fetchImpl(input, { ...init, signal: controller.signal });
|
||||
} finally {
|
||||
clearTimeout(timeout);
|
||||
}
|
||||
}
|
||||
|
||||
async function readLimitedResponseText(response: Response, limitBytes: number): Promise<string> {
|
||||
if (!response.body) {
|
||||
return "";
|
||||
}
|
||||
|
||||
const reader = response.body.getReader();
|
||||
const decoder = new TextDecoder();
|
||||
const chunks: string[] = [];
|
||||
let bytes = 0;
|
||||
|
||||
while (bytes < limitBytes) {
|
||||
const result = await reader.read();
|
||||
if (result.done) {
|
||||
chunks.push(decoder.decode());
|
||||
return chunks.join("");
|
||||
}
|
||||
|
||||
const chunk = result.value;
|
||||
const remaining = limitBytes - bytes;
|
||||
const slice = chunk.byteLength > remaining ? chunk.slice(0, remaining) : chunk;
|
||||
chunks.push(decoder.decode(slice, { stream: chunk.byteLength <= remaining }));
|
||||
bytes += slice.byteLength;
|
||||
|
||||
if (chunk.byteLength > remaining) {
|
||||
await reader.cancel();
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
chunks.push(decoder.decode());
|
||||
return chunks.join("");
|
||||
}
|
||||
|
||||
function normalizePositiveInteger(value: number | undefined, fallback: number): number {
|
||||
return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : fallback;
|
||||
}
|
||||
|
||||
function isAbortError(error: unknown) {
|
||||
return error instanceof Error && error.name === "AbortError";
|
||||
}
|
||||
Reference in new issue
Block a user