@fabrika/email 0.8.0 → 0.8.2

package/src/smartemailing.ts

@@ -2,83 +2,66 @@
 // verified only against a stubbed fetch. It has no idempotency key, and a 201 only queues the request.
 
 import { z } from 'zod'
-import { type EmailProvider, type EmailSenderIdentity, parseProviderVariables } from './config.js'
+import { type EmailProvider, parseProviderVariables } from './config.js'
+import { EmailDeliveryError, type EmailMessage, type EmailSenderCapabilities } from './email.js'
 import {
-	EmailDeliveryError,
-	type EmailDeliveryResult,
-	type EmailFetch,
-	type EmailMessage,
-	type EmailSender,
-	type EmailSenderCapabilities,
-} from './email.js'
-import { parseTimeout, postToProvider } from './http.js'
-import { isValidEmailSenderIdentity, isVisibleAscii, validateEmailAttachments, validateEmailMessage } from './validation.js'
+	credentialVariable,
+	type HttpEmailRequest,
+	HttpEmailSender,
+	type HttpEmailSenderOptions,
+	isCredential,
+	optionalVariable,
+} from './http-sender.js'
+import type { ProviderResponse } from './http.js'
 
 const SMARTEMAILING_SEND_URL = 'https://app.smartemailing.cz/api/v3/send/transactional-emails-bulk'
-const LABEL = 'SmartEmailing'
 const DEFAULT_TAG = 'fabrika'
 const TAG_PATTERN = /^[A-Za-z0-9_-]{1,64}$/
-const smartEmailingSuccessSchema = z.object({ data: z.tuple([z.object({ id: z.string().min(1) })]) })
+const smartEmailingSuccessSchema = z.object({ data: z.tuple([z.object({ id: z.string() })]) })
 
-export interface SmartEmailingEmailSenderOptions {
+export interface SmartEmailingEmailSenderOptions extends HttpEmailSenderOptions {
 	/** The account's user name or e-mail: the first half of the Basic credential. */
 	readonly username: string
 	readonly apiKey: string
-	readonly from: EmailSenderIdentity
 	/** Groups the messages in SmartEmailing's statistics. */
 	readonly tag?: string
-	readonly fetch?: EmailFetch
-	readonly timeoutMs?: number
 }
 
-export class SmartEmailingEmailSender implements EmailSender {
-	/** The API takes up to five tasks a request, but `send` carries one. */
+/** Its error body's `message` is free text that may quote the request, so a refusal is classified by status alone. */
+export class SmartEmailingEmailSender extends HttpEmailSender {
+	/**
+	 * The API takes up to five tasks a request, but `send` carries one. Its API documents no message headers, so a
+	 * one-click unsubscribe is refused rather than sent without one.
+	 */
 	readonly capabilities: EmailSenderCapabilities = { idempotent: false, confirmation: 'queued', maxBatch: 1 }
 	readonly #authorization: string
-	readonly #from: EmailSenderIdentity
 	readonly #tag: string
-	readonly #fetch: EmailFetch
-	readonly #timeoutMs: number
 
 	constructor(options: SmartEmailingEmailSenderOptions) {
 		if (!validUsername(options.username)) {
 			throw new EmailDeliveryError('SmartEmailing username is invalid', { code: 'invalid_configuration' })
 		}
-		if (!validApiKey(options.apiKey)) {
+		if (!isCredential(options.apiKey)) {
 			throw new EmailDeliveryError('SmartEmailing API key is invalid', { code: 'invalid_configuration' })
 		}
-		if (!isValidEmailSenderIdentity(options.from)) {
-			throw new EmailDeliveryError('SmartEmailing sender is invalid', { code: 'invalid_configuration' })
-		}
+		super({ label: 'SmartEmailing', provider: 'smartemailing' }, options)
 		const tag = options.tag ?? DEFAULT_TAG
 		if (!TAG_PATTERN.test(tag)) {
 			throw new EmailDeliveryError('SmartEmailing tag is invalid', { code: 'invalid_configuration' })
 		}
 
 		this.#authorization = `Basic ${btoa(`${options.username}:${options.apiKey}`)}`
-		this.#from = options.from
 		this.#tag = tag
-		this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init))
-		this.#timeoutMs = parseTimeout(LABEL, options.timeoutMs)
 	}
 
-	async send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult> {
-		validateEmailMessage(message)
-		// Its API documents no message headers, so a one-click unsubscribe is refused rather than sent without one.
-		if (message.unsubscribeUrl !== undefined) {
-			throw new EmailDeliveryError('SmartEmailing cannot write the List-Unsubscribe headers', { code: 'invalid_message' })
-		}
-		validateEmailAttachments(message, this.capabilities, LABEL)
-
-		const senderName = message.fromName ?? this.#from.name
-		const response = await postToProvider({
-			label: LABEL,
-			fetch: this.#fetch,
+	protected request(message: EmailMessage): HttpEmailRequest {
+		const senderName = message.fromName ?? this.from.name
+		return {
 			url: SMARTEMAILING_SEND_URL,
 			headers: { Authorization: this.#authorization },
 			body: {
 				sender_credentials: {
-					from: this.#from.address,
+					from: this.from.address,
 					...(senderName === undefined ? {} : { sender_name: senderName }),
 					...(message.replyTo === undefined ? {} : { reply_to: message.replyTo }),
 				},
@@ -91,28 +74,18 @@ export class SmartEmailingEmailSender implements EmailSender {
 				},
 				tasks: [{ recipient: { emailaddress: message.to } }],
 			},
-			signal,
-			timeoutMs: this.#timeoutMs,
-		})
-
-		// The error body's `message` is free text that may quote the request, so only the status is classified.
-		if (!response.ok) throw responseError(response.status)
-
-		const parsed = smartEmailingSuccessSchema.safeParse(response.body)
-		if (!parsed.success) {
-			throw new EmailDeliveryError('SmartEmailing returned an invalid success response', { code: 'malformed_response', httpStatus: response.status })
 		}
+	}
 
-		return { status: 'accepted', provider: 'smartemailing', messageId: parsed.data.data[0].id }
+	protected messageId(response: ProviderResponse): string | undefined {
+		return smartEmailingSuccessSchema.safeParse(response.body).data?.data[0].id
 	}
 }
 
 const smartEmailingVariablesSchema = z.object({
 	FABRIKA_EMAIL_SMARTEMAILING_USERNAME: z.string().refine(validUsername),
-	FABRIKA_EMAIL_SMARTEMAILING_API_KEY: z.string().refine(validApiKey),
-	FABRIKA_EMAIL_SMARTEMAILING_TAG: z.string().optional().transform((value) => (value === '' ? undefined : value)).refine((value) =>
-		value === undefined || TAG_PATTERN.test(value)
-	),
+	FABRIKA_EMAIL_SMARTEMAILING_API_KEY: credentialVariable,
+	FABRIKA_EMAIL_SMARTEMAILING_TAG: optionalVariable((value) => TAG_PATTERN.test(value)),
 })
 
 export const smartEmailingEmailProvider: EmailProvider = {
@@ -133,23 +106,6 @@ export const smartEmailingEmailProvider: EmailProvider = {
 	},
 }
 
-function responseError(status: number): EmailDeliveryError {
-	if (status === 401 || status === 403) {
-		return new EmailDeliveryError(`SmartEmailing refused the credentials (${status})`, { code: 'provider_unauthorized', httpStatus: status })
-	}
-	if (status === 429) {
-		return new EmailDeliveryError('SmartEmailing rate limit exceeded', { code: 'rate_limited', httpStatus: status })
-	}
-	if (status >= 500) {
-		return new EmailDeliveryError('SmartEmailing is unavailable', { code: 'provider_unavailable', httpStatus: status })
-	}
-	return new EmailDeliveryError(`SmartEmailing rejected the request (${status})`, { code: 'provider_rejected', httpStatus: status })
-}
-
 function validUsername(value: string): boolean {
-	return validApiKey(value) && !value.includes(':')
-}
-
-function validApiKey(value: string): boolean {
-	return value.length > 0 && isVisibleAscii(value)
+	return isCredential(value) && !value.includes(':')
 }

package/src/validation.ts

@@ -64,6 +64,7 @@ export function validateEmailMessage(message: EmailMessage): void {
 	if (message.replyTo !== undefined && !isValidEmailAddress(message.replyTo)) throw invalidMessage('Email reply-to address is invalid')
 	if (message.fromName !== undefined && !isValidEmailDisplayName(message.fromName)) throw invalidMessage('Email sender name is invalid')
 	if (message.unsubscribeUrl !== undefined && !isUnsubscribeUrl(message.unsubscribeUrl)) throw invalidMessage('Email unsubscribe URL is invalid')
+	if (message.broadcast === true && message.unsubscribeUrl === undefined) throw invalidMessage('A broadcast email needs an unsubscribe URL')
 	const attachments = message.attachments ?? []
 	if (attachments.length > MAX_EMAIL_ATTACHMENTS) throw invalidMessage(`Email has more than ${MAX_EMAIL_ATTACHMENTS} attachments`)
 	for (const attachment of attachments) {
@@ -73,15 +74,42 @@ export function validateEmailMessage(message: EmailMessage): void {
 }
 
 /**
- * Refuses a message whose attachments `capabilities` does not carry: any attachment where the transport sends none, or
- * more bytes together than its `maxAttachmentBytes`. `label` names the transport in the message.
+ * Refuses a message whose attachments `capabilities` does not carry: any attachment where the transport sends none,
+ * more bytes together than its `maxAttachmentBytes`, or a file whose extension it refuses. `label` names the transport
+ * in the message.
  */
 export function validateEmailAttachments(message: EmailMessage, capabilities: EmailSenderCapabilities, label: string): void {
-	if ((message.attachments ?? []).length === 0) return
+	const attachments = message.attachments ?? []
+	if (attachments.length === 0) return
 	const limit = capabilities.maxAttachmentBytes
 	if (limit === undefined) throw invalidMessage(`${label} sends no attachments`)
 	const bytes = attachmentBytes(message)
 	if (bytes > limit) throw invalidMessage(`Email attachments have ${bytes} bytes, more than the ${limit} ${label} sends`)
+	const refused = capabilities.refusedAttachmentExtensions ?? []
+	if (refused.length > 0 && attachments.some((attachment) => refused.includes(extensionOf(attachment.filename)))) {
+		throw invalidMessage(`${label} sends no attachment of this file type`)
+	}
+}
+
+/** Refuses a `broadcast` message where the transport sends none. */
+export function validateEmailBroadcast(message: EmailMessage, capabilities: EmailSenderCapabilities, label: string): void {
+	if (message.broadcast === true && capabilities.broadcast !== true) throw invalidMessage(`${label} sends no broadcast email`)
+}
+
+/** Refuses a text or HTML body shorter than the transport's `minBodyLength`, counted in characters once trimmed. */
+export function validateEmailBodies(message: EmailMessage, capabilities: EmailSenderCapabilities, label: string): void {
+	const min = capabilities.minBodyLength
+	if (min === undefined) return
+	const short = (body: string): boolean => [...body.trim()].length < min
+	if (short(message.text) || (message.html !== undefined && short(message.html))) {
+		throw invalidMessage(`${label} sends no body shorter than ${min} characters`)
+	}
+}
+
+/** The extension after the last dot, lowercase; empty without one. */
+function extensionOf(filename: string): string {
+	const dot = filename.lastIndexOf('.')
+	return dot < 0 ? '' : filename.slice(dot + 1).toLowerCase()
 }
 
 /** The most files one message carries. */