@email-service/email-service/dist/esm/models/esp.d.ts

email-service is a versatile npm package designed to simplify the integration and standardization of email communications across multiple Email Service Providers (ESPs).

import { EmailPayload, FromInput, IEmailService, Recipient, RecipientInput, StandardResponse, WebHookResponse } from "../types/email.type.js";
import type { Config } from "../types/emailServiceSelector.type.js";
import type { BulkPayload, BulkReport, EmailServiceHooks } from "../types/bulk.type.js";
import { TokenBucket, CompositeBucket } from "../utils/rateLimit.js";
export type ESPOptions = {
    /**
     * Hooks optionnels branchés sur l'instance. Utilisés exclusivement par
     * `sendBulk` pour la suppression list + observabilité campagne. Si
     * absents, `sendBulk` fonctionne quand même (aucun check, aucun callback).
     */
    hooks?: EmailServiceHooks;
};
export declare class ESP<T extends Config> implements IEmailService {
    mailMultiple?: boolean;
    transporter: T;
    /**
     * Rate limiter scopé par instance. Acquis avant chaque `sendMail`
     * pour éviter que le consommateur déclenche des 429 côté ESP.
     * `null` uniquement pour un ESP inconnu (ne devrait pas arriver).
     */
    protected rateLimiter: TokenBucket | CompositeBucket | null;
    /**
     * Hooks fournis à l'instanciation. Consommés par `sendBulk`. `sendMail`
     * unitaire ne les utilise pas — c'est une décision : les hooks sont liés
     * au contexte campagne, pas aux appels transactionnels unitaires.
     */
    protected hooks?: EmailServiceHooks;
    constructor(service: T, opts?: ESPOptions);
    checkRecipients(to: RecipientInput): Recipient[];
    checkFrom(from: FromInput): Recipient | undefined;
    /**
     * Envoi public : applique le rate limit puis délègue à `doSendMail`
     * implémenté par chaque ESP concret (template method). Les ESP
     * concrets ne doivent PAS override `sendMail` directement, sinon
     * ils contourneraient le throttle.
     */
    sendMail(options: EmailPayload): Promise<StandardResponse>;
    /**
     * Envoi en lot avec suppression list, stream (transactional|marketing),
     * templating par destinataire et hooks de persistance.
     *
     * Implémentation unique sur la classe de base — réutilise `sendMail()`
     * pour chaque destinataire, ce qui fait bénéficier chaque envoi du
     * rate limit automatiquement.
     *
     * Les règles de blocage (transactional vs marketing) sont appliquées
     * par `runBulk` en interne — le consommateur implémente juste un
     * `checkSuppression` qui retourne la reason brute.
     */
    sendBulk(payload: BulkPayload): Promise<BulkReport>;
    /** À implémenter par chaque ESP concret. */
    protected doSendMail(options: EmailPayload): Promise<StandardResponse>;
    webHookManagement(req: any): Promise<WebHookResponse>;
    sendMailMultiple(options: EmailPayload[]): Promise<StandardResponse[]>;
}