@wildo-ai/saas-backend-lib 1.1.2 → 1.1.4

package/dist/esm/notifications/email/services/email.backend.service.js

@@ -6,6 +6,23 @@
  * - Context building
  * - React Email rendering (subject fn + body fn → HTML/text)
  * - Provider resolution and HTTP execution
+ *
+ * ## A sent email leaves LOG LINES and nothing else — by decision (#412, 2026-09-08)
+ *
+ * There is no persisted record of a sent email anywhere in the framework: no core resource, no
+ * delivery log, no per-tenant history. **"Did this customer receive it?" is answered with the email
+ * provider's own tooling, never with Wildo.** Say that to anyone who asks for it here, rather than
+ * treating the absence as a gap to be filled.
+ *
+ * It reads as an oversight because the sibling subsystem does the opposite: outbound M2M webhooks
+ * carry a persisted per-tenant delivery log (`ORGANIZATION_M2M_WEBHOOK_DELIVERY_LOG` and its
+ * application twin). The asymmetry is deliberate and the reason is not the table — it is that a
+ * persisted email record is a new per-user personal-data store carrying retention policy, privacy
+ * classification, subject-export and erasure obligations FOR MESSAGE CONTENT. A metadata-only
+ * variant (recipient, template, timestamp, provider id; no body) was on the table and declined too,
+ * because it carries the same set of obligations over a smaller payload.
+ *
+ * Reopening this is legitimate, and it starts with the obligations rather than with the schema.
  */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -19,7 +36,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { injectable, inject } from 'inversify';
+import { injectable, inject, optional } from 'inversify';
 import { render } from '@react-email/render';
 import { randomUUID } from 'node:crypto';
 import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
@@ -27,8 +44,10 @@ import { describeCaughtError } from '../../../errors/utils/error-log-level-class
 import { getConfiguredFallbackLanguage, getConfiguredPrimaryLanguage, } from '../../../config/services/app-configuration.backend.utils.js';
 import { buildEmailBrandTokensFromConfig } from '../../../notifications/email/utils/color-conversion.utils.js';
 import { EmailTemplateType_ToEngineCapability, ErrorCustomMessageReference, ErrorType, isWildoBackendError, WildoHeaderKeys, } from '@wildo-ai/saas-models';
-import { EmailProviderPayloadEncoding, EmailProviderSubmissionClassification, ExternalProvider_ExchangeProtocol_Kind, StandardEmail_SendRequestSchema, StandardEmail_SendResponseSchema, } from '@wildo-ai/external-connectors-models';
+import { EmailProviderPayloadEncoding, EmailProviderSubmissionClassification, ExternalProvider_ExchangeProtocol_Kind, StandardEmail_SendRequestSchema, StandardEmail_SendResponseSchema, ProviderProtocolRuntimeKind, } from '@wildo-ai/external-connectors-models';
 import { EMAIL_PROVIDER_TRANSPORT_TIMEOUT_MS, } from '../../../notifications/email/models/email-transport.backend.definitions.js';
+import { readResponseTextWithinDeadline } from '../../../security/outbound/outbound-request-deadline.backend.utils.js';
+import { withEngineOwnedHeaders } from '../../../security/outbound/outbound-request-headers.backend.utils.js';
 // ─────────────────────────────────────────────────────────────────────────────
 // UTILITIES
 // ─────────────────────────────────────────────────────────────────────────────
@@ -36,6 +55,72 @@ function validateEmailAddresses(emails) {
     const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
     return emails.filter(email => !emailRegex.test(email.trim()));
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Total size ceiling for the attachments of ONE email, applied after the bytes are resolved (#429).
+ *
+ * 10 MB, deliberately below every provider ceiling this framework talks to, so an over-size send is
+ * refused HERE — naming the files and the measured total — instead of at a vendor whose rejection an
+ * application cannot act on. Base64 also inflates the wire payload by roughly a third, so a limit set
+ * AT a provider's number would still fail there.
+ *
+ * ## That claim is now CHECKED, and it used to be three numbers from memory
+ *
+ * This paragraph named "SendGrid 30 MB, Mailgun 25 MB, SES 40 MB" with no source — and this framework
+ * ships no SES provider, so one of the three was about a vendor nothing here talks to. Each shipped
+ * email provider now DECLARES its vendor's published envelope beside a mandatory `source`
+ * (`BackendProviderModule.emailEnvelope`), and `email-provider-envelope-ceiling.test.ts` asserts this
+ * constant is strictly below every declared ceiling.
+ *
+ * So the sentence above is an invariant rather than a recollection: adding a provider whose vendor
+ * publishes a tighter envelope than 10 MB fails a test here, instead of failing at that vendor on a
+ * customer's send.
+ *
+ * A constant rather than a config key, until an application needs a different number: a configurable
+ * limit that nothing reads is the exact defect this issue closed, and adding the reader is the
+ * cheaper half of that change.
+ */
+export const OUTBOUND_ATTACHMENT_TOTAL_BYTES_LIMIT = 10 * 1024 * 1024;
+/**
+ * The attachment ceiling for one resolved provider: the tighter of the engine default and the
+ * vendor's own published envelope.
+ *
+ * ## Why this is not simply the engine default
+ *
+ * The default's whole purpose is that an over-size send is refused HERE rather than at a vendor
+ * whose rejection an application cannot act on — and that only holds while the number is genuinely
+ * under every vendor's ceiling. It was not. `OUTBOUND_ATTACHMENT_TOTAL_BYTES_LIMIT` is 10 MB and
+ * **Brevo publishes 4 MB**, so an application on Brevo could pass the engine's check and be refused
+ * by the vendor: precisely the outcome the constant exists to prevent, for as long as the constant
+ * was calibrated against three vendors named from memory in a comment.
+ *
+ * Lowering the flat number to Brevo's would have punished every other provider for one vendor's
+ * envelope, so the ceiling is per-provider and the default is the FLOOR under providers that
+ * publish nothing.
+ *
+ * ## Both published ceilings are considered
+ *
+ * A vendor may document a whole-message ceiling, an attachment ceiling, both, or neither, and the
+ * two are independent facts rather than derivations of each other — Postmark publishes a 50 MB
+ * payload and no attachment ceiling; Resend publishes a 40 MB attachment ceiling and no message
+ * ceiling. Taking the minimum of whatever is declared is the only reading that is correct for all
+ * four shapes.
+ *
+ * A message ceiling is a ceiling on MORE than the attachments (headers and body count against it),
+ * so using it as an attachment ceiling is deliberately conservative rather than exact — which is
+ * the right direction for a refusal that exists to avoid a vendor round trip.
+ */
+export function resolveOutboundAttachmentCeiling(envelope) {
+    const declared = [envelope?.maxMessageSizeMB, envelope?.maxAttachmentSizeMB]
+        .filter((value) => typeof value === 'number' && value > 0)
+        .map((megabytes) => megabytes * 1024 * 1024);
+    // An absent envelope, or one publishing no ceiling at all, keeps the engine default. That is the
+    // honest answer rather than "unlimited": the default exists precisely for the provider whose
+    // vendor says nothing.
+    return Math.min(OUTBOUND_ATTACHMENT_TOTAL_BYTES_LIMIT, ...declared);
+}
 export var EmailSubmissionOutcome;
 (function (EmailSubmissionOutcome) {
     EmailSubmissionOutcome["NOT_SUBMITTED"] = "not_submitted";
@@ -50,17 +135,17 @@ let EmailBackendService = class EmailBackendService {
     logger;
     errorBuilder;
     templateRegistry;
-    contextProviderRegistry;
     configService;
     externalProvidersRegistry;
+    filesService;
     logDebug;
-    constructor(logger, errorBuilder, templateRegistry, contextProviderRegistry, configService, externalProvidersRegistry) {
+    constructor(logger, errorBuilder, templateRegistry, configService, externalProvidersRegistry, filesService) {
         this.logger = logger;
         this.errorBuilder = errorBuilder;
         this.templateRegistry = templateRegistry;
-        this.contextProviderRegistry = contextProviderRegistry;
         this.configService = configService;
         this.externalProvidersRegistry = externalProvidersRegistry;
+        this.filesService = filesService;
         this.logDebug = this.logger.debugByType('EmailBackendService');
         this.logger.setDebugTypeLogging('EmailBackendService', false);
     }
@@ -101,20 +186,13 @@ let EmailBackendService = class EmailBackendService {
             const resolved = this.templateRegistry.resolve(request.templateRef, request.locale, defaultLocale, this.getFallbackLocale());
             // 2. Get design tokens
             const brandTokens = this.getDesignTokens();
-            // 3. Build additional context from providers
-            const additionalContext = await this.contextProviderRegistry.buildAdditionalContext({
-                templateRef: request.templateRef,
-                locale: request.locale,
-                baseContext: request.context,
-            }, this.createProviderUtils());
-            // 4. Build full context
+            // 3. Build full context
             const fullContext = {
                 currentObject: request.context.currentObject,
                 objectContext: request.context.objectContext,
                 userContext: request.context.userContext,
                 additionalContext: {
                     ...(request.context.additionalContext || {}),
-                    ...additionalContext,
                 },
             };
             // 5. Render subject and body from definition functions
@@ -127,8 +205,12 @@ let EmailBackendService = class EmailBackendService {
             const emailType = resolved.definition.type ?? request.type;
             const engineCapability = EmailTemplateType_ToEngineCapability[emailType];
             const providerConfig = this.resolveEmailProvider(engineCapability);
+            // 6b. Resolve caller-supplied attachments to bytes (#429). Before the request is built,
+            // because a file that cannot be served must refuse the send rather than produce an email
+            // that silently lacks what the caller attached.
+            const attachments = await this.resolveAttachments(request, providerConfig.outboundAttachmentCeilingBytes);
             // 7. Build email request
-            const emailRequest = this.buildEmailRequest(request, submissionId, { subject, bodyHtml, bodyText }, providerConfig, recipients);
+            const emailRequest = this.buildEmailRequest(request, submissionId, { subject, bodyHtml, bodyText }, providerConfig, recipients, attachments);
             const providerRequest = providerConfig.delivery === 'network'
                 ? providerConfig.buildSendRequest({
                     request: emailRequest,
@@ -252,7 +334,7 @@ let EmailBackendService = class EmailBackendService {
             throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, { context: { message: `Email provider is disabled by external provider configuration: ${providerId}`, providerId, capability } });
         }
         const emailContract = this.externalProvidersRegistry.getProviderConfiguration(providerId, ExternalProvider_ExchangeProtocol_Kind.EMAIL_PROVIDER)?.runtimeContract;
-        if (emailContract?.kind !== 'email') {
+        if (emailContract?.kind !== ProviderProtocolRuntimeKind.EMAIL) {
             throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, { context: { message: `No EMAIL_PROVIDER runtime contract found for provider: ${providerId}`, providerId, capability } });
         }
         const appConfig = this.configService.config;
@@ -267,6 +349,9 @@ let EmailBackendService = class EmailBackendService {
         if (emailContract.delivery === 'log') {
             return {
                 providerId,
+                // Per-provider, because the engine default is NOT below every vendor's envelope — Brevo
+                // publishes 4 MB against the default's 10 MB. See `resolveOutboundAttachmentCeiling`.
+                outboundAttachmentCeilingBytes: resolveOutboundAttachmentCeiling(emailContract.publishedEnvelope),
                 delivery: 'log',
                 fromAddress: providerConfig?.fromAddress,
                 fromName: providerConfig?.fromName,
@@ -289,6 +374,9 @@ let EmailBackendService = class EmailBackendService {
         }
         return {
             providerId,
+            // Per-provider, because the engine default is NOT below every vendor's envelope — Brevo
+            // publishes 4 MB against the default's 10 MB. See `resolveOutboundAttachmentCeiling`.
+            outboundAttachmentCeilingBytes: resolveOutboundAttachmentCeiling(emailContract.publishedEnvelope),
             delivery: 'network',
             apiKey,
             endpoint: this.composeEmailSendEndpoint(emailContract.baseUrl, emailContract.sendEndpointPath, configuredDomain),
@@ -305,7 +393,73 @@ let EmailBackendService = class EmailBackendService {
             parseSendResponse: emailContract.parseSendResponse,
         };
     }
-    buildEmailRequest(request, submissionId, rendered, providerConfig, recipients) {
+    /**
+     * Resolve `attachmentFileIds` to the vendor-neutral `attachments` array several provider adapters
+     * already map (#429).
+     *
+     * Until this existed the field was declared and read by nothing, so a caller supplying an
+     * attachment got a successful send and an attachment-less email. Every refusal below therefore
+     * THROWS: a silent drop is the defect, and error handling that drops quietly is the same defect.
+     *
+     * ## The size cap is the framework's, not a provider's
+     *
+     * {@link OUTBOUND_ATTACHMENT_TOTAL_BYTES_LIMIT} is deliberately below every provider limit this
+     * framework talks to, so the refusal happens HERE — with the file ids and the measured total in
+     * the error — rather than at a vendor that answers with a rejected submission and a message the
+     * application cannot act on. It is a named constant rather than a config key on purpose: an
+     * authored limit nothing read is precisely the class of defect this issue came from, and a
+     * config surface can be added the day an application needs a different number.
+     *
+     * ## What is NOT checked here, and why
+     *
+     * The file TYPE. A file reaching this point has already passed upload-time validation and, where
+     * the field opts into scanning, the scanner — and the status gate inside
+     * `readFilesForOutboundAttachment` admits only what the download route would serve, which
+     * excludes INFECTED. Re-deciding admissible types at send time would be a second policy that can
+     * disagree with the first.
+     */
+    async resolveAttachments(request, ceilingBytes) {
+        const fileIds = request.attachmentFileIds ?? [];
+        if (fileIds.length === 0) {
+            return [];
+        }
+        if (!this.filesService) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message: 'Email attachments were requested but the files service is not bound',
+                    attachmentCount: fileIds.length,
+                },
+            });
+        }
+        const resolved = await this.filesService.readFilesForOutboundAttachment(fileIds, {
+            applicationId: this.configService.applicationId ?? undefined,
+            // The tenancy confinement. An organization-scoped send reaches only that organization's
+            // files; a send without one reaches only application-scoped files.
+            ...(request.organizationId ? { organizationId: request.organizationId } : {}),
+        });
+        const totalBytes = resolved.reduce((total, file) => total + file.bytes.byteLength, 0);
+        if (totalBytes > ceilingBytes) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: {
+                    message: 'Email attachments exceed the outbound total-size limit',
+                    totalBytes,
+                    limitBytes: ceilingBytes,
+                    // Both numbers, because "which limit refused me" is the first question an application asks
+                    // and the answer differs by provider: the engine default, or a tighter vendor envelope.
+                    engineDefaultLimitBytes: OUTBOUND_ATTACHMENT_TOTAL_BYTES_LIMIT,
+                    fileIds: resolved.map((file) => file.fileId),
+                },
+            });
+        }
+        return resolved.map((file) => ({
+            filename: file.filename,
+            content: file.bytes.toString('base64'),
+            contentType: file.mimeType,
+        }));
+    }
+    buildEmailRequest(request, submissionId, rendered, providerConfig, recipients, attachments) {
         const toAddresses = recipients.map(email => ({ email }));
         // From-address precedence: per-send override → per-provider config
         // (`providerConfigurations.<provider>.EMAIL_PROVIDER.fromAddress`) → the
@@ -330,6 +484,9 @@ let EmailBackendService = class EmailBackendService {
             subject: rendered.subject,
             html: rendered.bodyHtml,
             text: rendered.bodyText,
+            // Omitted rather than sent empty: the field is optional on the vendor-neutral contract and
+            // several adapters branch on its presence.
+            ...(attachments.length > 0 ? { attachments } : {}),
         });
     }
     async executeProviderRequest(providerConfig, request, providerRequest, onTransportStart) {
@@ -349,6 +506,34 @@ let EmailBackendService = class EmailBackendService {
                 bcc: request.bcc?.map(recipient => recipient.email),
                 subject: request.subject,
                 textPreview: request.text?.slice(0, 2000),
+                /*
+                 * DERIVED FACTS ABOUT THE HTML, never the HTML itself (#522).
+                 *
+                 * This provider is how a developer sees a local send, and it surfaced a TEXT preview only —
+                 * so anything that exists only in the HTML was invisible here. A brand logo is an `<img>`,
+                 * which is a fair part of why ninety-five templates rendered none without anyone noticing.
+                 *
+                 * The body is not logged. That is the same rule the attachment line below already follows —
+                 * names, never the bytes — and a full HTML email in a log line would be both unreadable and
+                 * a place for personal data to accumulate. `imageCount` is the smallest fact that tells the
+                 * two cases apart, which is all the dev loop needs: 0 where a logo did not resolve, 1 where
+                 * it did.
+                 *
+                 * Writing the rendered HTML to a FILE a developer can open is the better surface and is a
+                 * real decision — where it lives, who removes it, and which environments produce it — so it
+                 * is recorded rather than invented inside a provider branch.
+                 */
+                htmlBytes: request.html === undefined ? undefined : Buffer.byteLength(request.html, 'utf8'),
+                imageCount: request.html === undefined ? undefined : (request.html.match(/<img\b/gi) ?? []).length,
+                // Names only, never the bytes (#429). The log-delivery provider is how a developer sees a
+                // local send, so an attachment that resolved has to be visible here — otherwise the dev
+                // loop looks identical whether the resolution worked or silently produced nothing, which
+                // is the failure this whole path exists to remove.
+                attachments: request.attachments?.map((attachment) => ({
+                    filename: attachment.filename,
+                    contentType: attachment.contentType,
+                    bytes: Buffer.from(attachment.content, 'base64').byteLength,
+                })),
             });
             return {
                 outcome: EmailSubmissionOutcome.PROVIDER_ACCEPTED,
@@ -364,10 +549,20 @@ let EmailBackendService = class EmailBackendService {
         if (!providerRequest) {
             throw new Error('Network email submission is missing its provider request');
         }
-        const headers = {
-            ...this.buildProviderEmailHeaders(providerConfig),
-            ...providerRequest.transportHeaders,
-        };
+        /*
+         * The engine's credential is authoritative, and the provider's headers cannot reach it.
+         *
+         * This merge previously spread `transportHeaders` LAST, which is the strongest form of the
+         * defect corrected across the outbound arms on 2026-09-09: an identical spelling let a provider
+         * REPLACE the engine's `Authorization` outright, and a differing one produced two object keys
+         * that `fetch` combines into `authorization: <provider>, <engine>` — a request that
+         * authenticates with neither. Neither outcome is one a provider function should be able to
+         * cause; it never receives a credential in the first place.
+         *
+         * Nothing legitimate is lost: the shipped providers contribute `Accept` (Postmark) and
+         * `Idempotency-Key` (Resend), and both still reach the wire untouched.
+         */
+        const headers = withEngineOwnedHeaders(providerRequest.transportHeaders, this.buildProviderEmailHeaders(providerConfig));
         const body = this.serializeProviderEmailPayload(providerConfig, providerRequest.payload);
         const abortController = new AbortController();
         const timeoutHandle = setTimeout(() => abortController.abort(new Error(`Email provider request exceeded ${EMAIL_PROVIDER_TRANSPORT_TIMEOUT_MS}ms`)), EMAIL_PROVIDER_TRANSPORT_TIMEOUT_MS);
@@ -556,29 +751,9 @@ let EmailBackendService = class EmailBackendService {
      * headers and body consumption and can never outlive the durable lease.
      */
     async readResponseTextWithAbort(response, signal) {
-        if (signal.aborted) {
-            throw this.abortReasonToError(signal.reason);
-        }
-        let abortListener;
-        const aborted = new Promise((_resolve, reject) => {
-            abortListener = () => reject(this.abortReasonToError(signal.reason));
-            signal.addEventListener('abort', abortListener, { once: true });
-        });
-        try {
-            return await Promise.race([response.text(), aborted]);
-        }
-        finally {
-            if (abortListener) {
-                signal.removeEventListener('abort', abortListener);
-            }
-        }
-    }
-    abortReasonToError(reason) {
-        return reason instanceof Error
-            ? reason
-            : new Error(typeof reason === 'string'
-                ? reason
-                : 'Email provider request was aborted');
+        // The race itself is shared with every other substitutable outbound transport, so the property
+        // has one implementation rather than one per subsystem.
+        return readResponseTextWithinDeadline(response, signal);
     }
     describeRejectedRecipients(rejectedRecipients) {
         if (!rejectedRecipients?.length) {
@@ -644,39 +819,16 @@ let EmailBackendService = class EmailBackendService {
             ? { ...payload, key: providerConfig.apiKey }
             : payload);
     }
-    // Per-provider payload building lives in the provider module's
-    // `runtimeContract.buildSendRequest` (one of the six EMAIL_PROVIDER
-    // backend modules). The email service no longer branches on provider id.
-    createProviderUtils() {
-        return {
-            getRepository: (resourceType) => {
-                throw new Error(`getRepository('${resourceType}') is not available in the email context provider. Inject repository data via additionalContext instead.`);
-            },
-            logger: {
-                debug: (message, meta) => this.logger.debug(message, meta),
-                info: (message, meta) => this.logger.info(message, meta),
-                warn: (message, meta) => this.logger.warn(message, meta),
-                error: (message, meta) => this.logger.error(message, meta),
-            },
-            errorBuilder: {
-                buildError: (type, message, details) => {
-                    const err = new Error(message);
-                    err.type = type;
-                    err.details = details;
-                    return err;
-                },
-            },
-        };
-    }
 };
 EmailBackendService = __decorate([
     injectable(),
     __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
     __param(1, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
     __param(2, inject(SAAS_SERVICE_TYPES.EmailTemplateRegistry)),
-    __param(3, inject(SAAS_SERVICE_TYPES.EmailContextProviderRegistry)),
-    __param(4, inject(SAAS_SERVICE_TYPES.AppConfigService)),
-    __param(5, inject(SAAS_SERVICE_TYPES.ExternalProvidersRegistryService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.AppConfigService)),
+    __param(4, inject(SAAS_SERVICE_TYPES.ExternalProvidersRegistryService)),
+    __param(5, inject(SAAS_SERVICE_TYPES.FilesBackendService)),
+    __param(5, optional()),
     __metadata("design:paramtypes", [Function, Function, Function, Function, Function, Function])
 ], EmailBackendService);
 export { EmailBackendService };