@bymax-one/nest-notification 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1490,6 +1490,319 @@ declare class ResendEmailProvider implements IEmailProvider {
1490
1490
  private loadResendConstructor;
1491
1491
  }
1492
1492
 
1493
+ /**
1494
+ * @fileoverview Reference `IEmailProvider` adapter speaking SMTP through Nodemailer.
1495
+ * @layer infrastructure
1496
+ *
1497
+ * SMTP is the protocol every relay, Postfix, corporate gateway, SES-via-SMTP and
1498
+ * mail-capture server (Mailpit, MailHog) understands, so this adapter serves both
1499
+ * production delivery and the end-to-end tests a consumer needs to exercise its
1500
+ * email flows.
1501
+ *
1502
+ * `nodemailer` is an OPTIONAL peer dependency: it is loaded lazily via a dynamic
1503
+ * `import()` the first time `send()` runs, so a consumer who picks a different
1504
+ * transport never has to install it. The adapter forward-declares the slim shape it
1505
+ * needs instead of importing `nodemailer` at compile time, keeping the library free
1506
+ * of a hard dependency on its types.
1507
+ *
1508
+ * Security: the email body (`html` / `text`) may carry OTP codes or PII — it is
1509
+ * NEVER logged. The SMTP password is held in an ECMAScript private field so it
1510
+ * cannot be walked by a serializer, and is scrubbed from any transport error before
1511
+ * that error is logged or re-thrown.
1512
+ */
1513
+
1514
+ /** TLS knobs forwarded to the transport, for relays using a private CA. */
1515
+ interface SmtpTlsOptions {
1516
+ /**
1517
+ * Whether to reject a certificate that does not validate against the trust store.
1518
+ * Defaults to Node's `true`. Setting it to `false` disables certificate
1519
+ * verification and exposes the connection to interception — prefer supplying the
1520
+ * relay's CA via {@link SmtpTlsOptions.ca}.
1521
+ */
1522
+ rejectUnauthorized?: boolean;
1523
+ /** SNI server name, when it differs from `host`. */
1524
+ servername?: string;
1525
+ /** Additional trusted CA certificate(s), in PEM form. */
1526
+ ca?: string | string[];
1527
+ }
1528
+ /**
1529
+ * Login credentials for the SMTP session (the protocol's `AUTH` command, RFC 4954).
1530
+ * Both fields must be non-empty for the provider to be configured.
1531
+ */
1532
+ interface SmtpCredentials {
1533
+ /**
1534
+ * Login user. Explicitly `| undefined` — not merely optional — so a consumer can
1535
+ * pass `process.env.SMTP_USER` straight through under `exactOptionalPropertyTypes`.
1536
+ * A missing variable then makes `isConfigured()` answer `false` instead of forcing
1537
+ * a non-null assertion at the call site or logging in as `undefined`.
1538
+ */
1539
+ user?: string | undefined;
1540
+ /** Login password (or app/API secret). See {@link SmtpCredentials.user}. */
1541
+ pass?: string | undefined;
1542
+ }
1543
+ /** Construction options for {@link SmtpEmailProvider}. */
1544
+ interface SmtpEmailProviderOptions {
1545
+ /**
1546
+ * Relay hostname or IP. Required — without it the provider is not configured.
1547
+ * Explicitly `| undefined` so `process.env.SMTP_HOST` can be passed straight
1548
+ * through; see {@link SmtpCredentials.user}.
1549
+ */
1550
+ host?: string | undefined;
1551
+ /** TCP port. Defaults to `587` (submission). */
1552
+ port?: number;
1553
+ /**
1554
+ * Whether TLS wraps the connection from the first byte (implicit TLS, port 465).
1555
+ * Defaults to `true` only when `port` is `465`. Leave `false` for submission and
1556
+ * plaintext capture servers; the connection is still upgraded through STARTTLS
1557
+ * when the relay advertises it. Use {@link SmtpEmailProviderOptions.requireTls}
1558
+ * to make that upgrade mandatory.
1559
+ */
1560
+ secure?: boolean;
1561
+ /**
1562
+ * Whether to require a STARTTLS upgrade on a non-implicit-TLS connection, failing
1563
+ * the send when the relay does not offer it.
1564
+ *
1565
+ * **Defaults to `true` for any non-loopback host**, and to `false` for
1566
+ * `localhost` / `127.0.0.1` / `::1` (the local capture-server case) and whenever
1567
+ * `secure` is already on. Without it, whether the session is encrypted at all is
1568
+ * decided by the plaintext EHLO banner: an attacker with network position strips
1569
+ * the `250-STARTTLS` line, the transport never upgrades, and the credentials and
1570
+ * the body — which carries OTP codes — cross the network in the clear. Set it to
1571
+ * `false` explicitly for a relay you know cannot upgrade.
1572
+ */
1573
+ requireTls?: boolean;
1574
+ /** Login credentials. Omit entirely for an open relay (e.g. Mailpit). */
1575
+ credentials?: SmtpCredentials;
1576
+ /** TLS knobs, for a relay presenting a certificate from a private CA. */
1577
+ tls?: SmtpTlsOptions;
1578
+ /** TCP connection timeout in milliseconds. Defaults to `10000`. */
1579
+ connectionTimeout?: number;
1580
+ /** Server-greeting timeout in milliseconds. Defaults to `10000`. */
1581
+ greetingTimeout?: number;
1582
+ /** Idle-socket timeout in milliseconds. Defaults to `20000`. */
1583
+ socketTimeout?: number;
1584
+ }
1585
+ /**
1586
+ * Reference {@link IEmailProvider} speaking SMTP.
1587
+ *
1588
+ * @example Local capture server (Mailpit / MailHog)
1589
+ * ```ts
1590
+ * new SmtpEmailProvider({ host: 'localhost', port: 1025, secure: false })
1591
+ * ```
1592
+ *
1593
+ * @example Authenticated production relay
1594
+ * ```ts
1595
+ * BymaxNotificationModule.forRoot({
1596
+ * email: {
1597
+ * provider: new SmtpEmailProvider({
1598
+ * host: process.env.SMTP_HOST,
1599
+ * port: 587,
1600
+ * requireTls: true,
1601
+ * credentials: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS }
1602
+ * }),
1603
+ * defaultFrom: 'noreply@acme.com'
1604
+ * }
1605
+ * })
1606
+ * ```
1607
+ *
1608
+ * @remarks `EmailSendOptions.tags` are not forwarded: SMTP has no tag facility.
1609
+ * They still reach the audit log through `EmailService`.
1610
+ */
1611
+ declare class SmtpEmailProvider implements IEmailProvider {
1612
+ #private;
1613
+ readonly name = "smtp";
1614
+ private readonly logger;
1615
+ /**
1616
+ * @param options - Adapter options; `host` is required to actually send, and
1617
+ * `credentials` must be complete whenever supplied at all.
1618
+ */
1619
+ constructor(options?: SmtpEmailProviderOptions);
1620
+ /**
1621
+ * Whether the relay is fully described. Does not open a connection nor load
1622
+ * Nodemailer.
1623
+ *
1624
+ * A host is always required. Credentials are required only when the consumer
1625
+ * supplied a `credentials` object at all — which is how a deployment declares that
1626
+ * it logs in. That makes an open capture server configured, while a production
1627
+ * relay whose `SMTP_PASS` variable failed to load is *not*, instead of silently
1628
+ * attempting an anonymous send.
1629
+ *
1630
+ * @returns `true` when the provider can attempt a send.
1631
+ */
1632
+ isConfigured(): boolean;
1633
+ /**
1634
+ * Sends one transactional email over SMTP.
1635
+ *
1636
+ * @param options - The message envelope and body.
1637
+ * @returns The RFC-5322 `Message-ID` assigned to the message, angle brackets
1638
+ * included — the value that also appears in the delivered message's headers,
1639
+ * so an audit entry correlates with what the recipient received.
1640
+ * @throws Error When an address or custom header carries a line break, the
1641
+ * configuration is incomplete, no sender address is available, the `nodemailer`
1642
+ * package is not installed, the transport rejects the message, or no message id
1643
+ * comes back. `EmailService` maps any thrown `Error` to `EMAIL_SEND_FAILED`.
1644
+ */
1645
+ send(options: EmailSendOptions): Promise<EmailSendResult>;
1646
+ /**
1647
+ * Hands the payload to the transport, converting a transport failure into a plain
1648
+ * `Error` whose message has the SMTP password scrubbed out. The email body is
1649
+ * never part of what is logged.
1650
+ *
1651
+ * @param transport - The initialized transport.
1652
+ * @param payload - The message to send.
1653
+ * @returns The transport's send info.
1654
+ * @throws Error When the transport rejects the message.
1655
+ */
1656
+ private dispatch;
1657
+ /**
1658
+ * Replaces every occurrence of either configured credential with a placeholder.
1659
+ *
1660
+ * A relay can echo the failing command back in its response, and a socket error
1661
+ * can carry the connection options — either would otherwise put the credential
1662
+ * into a log line and into the audit entry `EmailService` writes from the thrown
1663
+ * message.
1664
+ *
1665
+ * The **user** is scrubbed alongside the password because it is not always a
1666
+ * public login: an SES SMTP username, for one, is itself generated secret
1667
+ * material. Matching is literal and unconditional, so a short credential
1668
+ * over-redacts a message rather than risking a miss — the safe direction for a
1669
+ * control whose other failure mode is persisting a secret.
1670
+ *
1671
+ * @param message - The raw error message.
1672
+ * @returns The message with both credentials removed, unchanged when none is set.
1673
+ */
1674
+ private redact;
1675
+ /**
1676
+ * Rejects a line break in any caller-supplied value that becomes a message header.
1677
+ *
1678
+ * Nodemailer's MIME layer already strips `CR`/`LF` from header names and values and
1679
+ * derives the envelope from parsed address objects rather than raw strings, so this
1680
+ * is defence in depth rather than the only barrier — but header injection is the
1681
+ * one place where trusting a peer dependency's current behaviour would be the whole
1682
+ * security boundary. The subject is left out on purpose: a stray trailing newline
1683
+ * from a template is plausible there, and Nodemailer's strip handles it without a
1684
+ * hard failure.
1685
+ *
1686
+ * @param options - The message envelope.
1687
+ * @throws Error When a line break appears in an address or a custom header.
1688
+ */
1689
+ private guardHeaderInjection;
1690
+ /**
1691
+ * Throws when a value carries a `CR` or `LF`.
1692
+ *
1693
+ * @param field - The field name, for the error message.
1694
+ * @param value - The value to check; `undefined` passes.
1695
+ * @throws Error When the value contains a line break.
1696
+ */
1697
+ private rejectLineBreak;
1698
+ /**
1699
+ * Builds the sender in Nodemailer's structured address form.
1700
+ *
1701
+ * Never concatenates the display name into `"Name <address>"` — see
1702
+ * {@link SmtpSender} for why that hands the sender away to whoever controls the
1703
+ * name.
1704
+ *
1705
+ * @param from - The sender address, if any.
1706
+ * @param fromName - The sender display name, if any.
1707
+ * @returns The sender; `name` is `''` when no display name was supplied.
1708
+ * @throws Error When no sender address is available — SMTP needs an envelope
1709
+ * sender, so an absent `from` and `defaultFrom` is a configuration bug worth
1710
+ * reporting plainly rather than a cryptic transport rejection.
1711
+ */
1712
+ private buildSender;
1713
+ /**
1714
+ * Maps the library's attachments onto Nodemailer's shape.
1715
+ *
1716
+ * `EmailAttachment.content` is documented as a `Buffer` **or a base64 string**, so
1717
+ * a string is tagged `encoding: 'base64'` — left untagged, Nodemailer would treat
1718
+ * the base64 text as the literal body and deliver a corrupt file.
1719
+ *
1720
+ * @param attachments - The attachments to map, if any.
1721
+ * @returns The mapped attachments, or `undefined` when there are none.
1722
+ */
1723
+ private mapAttachments;
1724
+ /**
1725
+ * Returns the cached transport, lazily importing `nodemailer` on first use.
1726
+ * Concurrent first calls share one in-flight initialization promise so the dynamic
1727
+ * import and creation run exactly once; a failed init is dropped from the cache so
1728
+ * a later call can retry instead of being permanently bricked.
1729
+ *
1730
+ * @returns The initialized transport.
1731
+ * @throws Error When the configuration is incomplete or `nodemailer` is missing.
1732
+ */
1733
+ private getTransport;
1734
+ /**
1735
+ * Builds a fresh transport, resetting the cached promise on any failure so the
1736
+ * provider is not permanently bricked by a transient init error.
1737
+ *
1738
+ * @returns The initialized transport.
1739
+ * @throws Error When the configuration is incomplete or `nodemailer` is missing.
1740
+ */
1741
+ private createTransport;
1742
+ /**
1743
+ * Calls into Nodemailer to build the transport, scrubbing the password out of a
1744
+ * failure.
1745
+ *
1746
+ * Redaction is applied here and in {@link SmtpEmailProvider.dispatch} rather than
1747
+ * around the whole initialization, because those two are the only calls that cross
1748
+ * into foreign code. This adapter's own errors — a missing host, incomplete
1749
+ * credentials — never contain the password, and running them through a substring
1750
+ * scrub would corrupt them: a one-character password rewrites every occurrence of
1751
+ * that character in the sentence.
1752
+ *
1753
+ * @param nodemailer - The loaded module surface.
1754
+ * @param config - The resolved transport configuration.
1755
+ * @returns The initialized transport.
1756
+ * @throws Error When the transport rejects its configuration.
1757
+ */
1758
+ private instantiate;
1759
+ /**
1760
+ * Scrubs the password out of an initialization failure.
1761
+ *
1762
+ * `dispatch()` covers the send path, but this one covers the build path — a
1763
+ * transport implementation that validates its configuration eagerly could throw
1764
+ * with the credential pair stringified into the message, and this `catch` is the
1765
+ * only thing between that and the audit entry. An error whose message needs no
1766
+ * change is returned untouched, so its type and stack survive.
1767
+ *
1768
+ * Always an `Error`, because `IEmailProvider.send` documents that it throws one
1769
+ * and a direct caller is entitled to rely on that. Identity is preserved only for
1770
+ * an `Error` whose message needed no change — there its type and stack are worth
1771
+ * keeping; anything else is wrapped.
1772
+ *
1773
+ * @param error - The raw failure.
1774
+ * @returns The original `Error` when nothing needed scrubbing, otherwise a plain
1775
+ * `Error` carrying the scrubbed message.
1776
+ */
1777
+ private redactError;
1778
+ /**
1779
+ * Resolves the transport configuration, applying defaults and validating that the
1780
+ * relay is fully described.
1781
+ *
1782
+ * @returns The resolved configuration.
1783
+ * @throws Error When `host` is missing, or `credentials` were supplied incomplete.
1784
+ */
1785
+ private buildTransportConfig;
1786
+ /**
1787
+ * Resolves the credential pair to hand the transport.
1788
+ *
1789
+ * @returns The credential pair, or `undefined` for an open relay.
1790
+ * @throws Error When `credentials` were supplied but are missing `user` or `pass`
1791
+ * — that is a deployment declaring it logs in while its secrets failed to load, so
1792
+ * it must fail closed rather than fall back to an anonymous send.
1793
+ */
1794
+ private resolveCredentials;
1795
+ /**
1796
+ * Dynamically imports the optional `nodemailer` peer dependency, tolerating both
1797
+ * shapes the specifier can resolve to — a namespace carrying `createTransport` as
1798
+ * a named export, and one where the CommonJS module lands under `default`.
1799
+ *
1800
+ * @returns The module's callable surface.
1801
+ * @throws Error When the package is not installed in the consumer app.
1802
+ */
1803
+ private loadNodemailer;
1804
+ }
1805
+
1493
1806
  /**
1494
1807
  * @fileoverview In-memory `IOtpStorage` for development and unit tests.
1495
1808
  * @layer infrastructure
@@ -2145,4 +2458,4 @@ declare const DEFAULT_TTLS: {
2145
2458
  readonly OTP_GENERIC_SECONDS: 600;
2146
2459
  };
2147
2460
 
2148
- export { type AuditOptions, BYMAX_NOTIFICATION_EMAIL_PROVIDER, BYMAX_NOTIFICATION_LOG_REPOSITORY, BYMAX_NOTIFICATION_OPTIONS, BYMAX_NOTIFICATION_OTP_STORAGE, BYMAX_NOTIFICATION_PUSH_PROVIDER, BYMAX_NOTIFICATION_SMS_PROVIDER, BYMAX_NOTIFICATION_TEMPLATE_RENDERER, BymaxNotificationModule, type BymaxNotificationModuleAsyncOptions, type BymaxNotificationModuleOptions, type BymaxNotificationModuleOptionsFactory, CANONICAL_EMAIL_TEMPLATES, type CanonicalEmailTemplate, type CanonicalNotificationPurpose, type ConsumeAttemptResult, DEFAULT_TTLS, DefaultTemplateRenderer, type DefaultTemplateRendererOptions, type DispatchInput, type DispatchResult, type EmailAttachment, type EmailChannelOptions, type EmailDispatchPayload, type EmailSendInput, type EmailSendOptions, type EmailSendResult, type EmailSendTemplateInput, EmailService, type GlobalOptions, type IEmailProvider, type IEmailTemplateRenderer, type INotificationLogRepository, type IOtpStorage, type IPushProvider, type ISmsProvider, InMemoryOtpStorage, type InMemoryStorageSize, type MissingVariableMode, NOTIFICATION_ERROR_CODES, NOTIFICATION_ERROR_DEFINITIONS, NOTIFICATION_PURPOSES, NoOpEmailProvider, NoOpNotificationLogRepository, NotificationAuditInterceptor, type NotificationChannel, type NotificationErrorCode, type NotificationErrorDefinition, type NotificationErrorKey, type NotificationErrorResponse, NotificationException, type NotificationLogEntry, type NotificationLogVerb, type NotificationRequest, NotificationService, type OtpChannelOptions, type OtpConsumeInput, type OtpDispatchPayload, type OtpEntry, type OtpGenerateInput, type OtpGenerateResult, type OtpPurpose, type OtpPurposeConfig, OtpService, type OtpStatusInput, type OtpStatusResult, type OtpVerifyInput, type OtpVerifyResult, type PushChannelOptions, type PushSendOptions, type PushSendResult, type RedisLike, RedisOtpStorage, type RedisOtpStorageOptions, type RenderedEmail, ResendEmailProvider, type ResendEmailProviderOptions, type ResolvedAuditOptions, type ResolvedEmailOptions, type ResolvedGlobalOptions, type ResolvedNotificationOptions, type ResolvedOtpOptions, type SmsChannelOptions, type SmsSendOptions, type SmsSendResult, type TemplateDefinition, cooldownExpiresAt, formatCooldown, generateOtpCode, hashTenantRecipient, safeCompare, toRetryAfterHeader };
2461
+ export { type AuditOptions, BYMAX_NOTIFICATION_EMAIL_PROVIDER, BYMAX_NOTIFICATION_LOG_REPOSITORY, BYMAX_NOTIFICATION_OPTIONS, BYMAX_NOTIFICATION_OTP_STORAGE, BYMAX_NOTIFICATION_PUSH_PROVIDER, BYMAX_NOTIFICATION_SMS_PROVIDER, BYMAX_NOTIFICATION_TEMPLATE_RENDERER, BymaxNotificationModule, type BymaxNotificationModuleAsyncOptions, type BymaxNotificationModuleOptions, type BymaxNotificationModuleOptionsFactory, CANONICAL_EMAIL_TEMPLATES, type CanonicalEmailTemplate, type CanonicalNotificationPurpose, type ConsumeAttemptResult, DEFAULT_TTLS, DefaultTemplateRenderer, type DefaultTemplateRendererOptions, type DispatchInput, type DispatchResult, type EmailAttachment, type EmailChannelOptions, type EmailDispatchPayload, type EmailSendInput, type EmailSendOptions, type EmailSendResult, type EmailSendTemplateInput, EmailService, type GlobalOptions, type IEmailProvider, type IEmailTemplateRenderer, type INotificationLogRepository, type IOtpStorage, type IPushProvider, type ISmsProvider, InMemoryOtpStorage, type InMemoryStorageSize, type MissingVariableMode, NOTIFICATION_ERROR_CODES, NOTIFICATION_ERROR_DEFINITIONS, NOTIFICATION_PURPOSES, NoOpEmailProvider, NoOpNotificationLogRepository, NotificationAuditInterceptor, type NotificationChannel, type NotificationErrorCode, type NotificationErrorDefinition, type NotificationErrorKey, type NotificationErrorResponse, NotificationException, type NotificationLogEntry, type NotificationLogVerb, type NotificationRequest, NotificationService, type OtpChannelOptions, type OtpConsumeInput, type OtpDispatchPayload, type OtpEntry, type OtpGenerateInput, type OtpGenerateResult, type OtpPurpose, type OtpPurposeConfig, OtpService, type OtpStatusInput, type OtpStatusResult, type OtpVerifyInput, type OtpVerifyResult, type PushChannelOptions, type PushSendOptions, type PushSendResult, type RedisLike, RedisOtpStorage, type RedisOtpStorageOptions, type RenderedEmail, ResendEmailProvider, type ResendEmailProviderOptions, type ResolvedAuditOptions, type ResolvedEmailOptions, type ResolvedGlobalOptions, type ResolvedNotificationOptions, type ResolvedOtpOptions, type SmsChannelOptions, type SmsSendOptions, type SmsSendResult, type SmtpCredentials, SmtpEmailProvider, type SmtpEmailProviderOptions, type SmtpTlsOptions, type TemplateDefinition, cooldownExpiresAt, formatCooldown, generateOtpCode, hashTenantRecipient, safeCompare, toRetryAfterHeader };
@@ -1490,6 +1490,319 @@ declare class ResendEmailProvider implements IEmailProvider {
1490
1490
  private loadResendConstructor;
1491
1491
  }
1492
1492
 
1493
+ /**
1494
+ * @fileoverview Reference `IEmailProvider` adapter speaking SMTP through Nodemailer.
1495
+ * @layer infrastructure
1496
+ *
1497
+ * SMTP is the protocol every relay, Postfix, corporate gateway, SES-via-SMTP and
1498
+ * mail-capture server (Mailpit, MailHog) understands, so this adapter serves both
1499
+ * production delivery and the end-to-end tests a consumer needs to exercise its
1500
+ * email flows.
1501
+ *
1502
+ * `nodemailer` is an OPTIONAL peer dependency: it is loaded lazily via a dynamic
1503
+ * `import()` the first time `send()` runs, so a consumer who picks a different
1504
+ * transport never has to install it. The adapter forward-declares the slim shape it
1505
+ * needs instead of importing `nodemailer` at compile time, keeping the library free
1506
+ * of a hard dependency on its types.
1507
+ *
1508
+ * Security: the email body (`html` / `text`) may carry OTP codes or PII — it is
1509
+ * NEVER logged. The SMTP password is held in an ECMAScript private field so it
1510
+ * cannot be walked by a serializer, and is scrubbed from any transport error before
1511
+ * that error is logged or re-thrown.
1512
+ */
1513
+
1514
+ /** TLS knobs forwarded to the transport, for relays using a private CA. */
1515
+ interface SmtpTlsOptions {
1516
+ /**
1517
+ * Whether to reject a certificate that does not validate against the trust store.
1518
+ * Defaults to Node's `true`. Setting it to `false` disables certificate
1519
+ * verification and exposes the connection to interception — prefer supplying the
1520
+ * relay's CA via {@link SmtpTlsOptions.ca}.
1521
+ */
1522
+ rejectUnauthorized?: boolean;
1523
+ /** SNI server name, when it differs from `host`. */
1524
+ servername?: string;
1525
+ /** Additional trusted CA certificate(s), in PEM form. */
1526
+ ca?: string | string[];
1527
+ }
1528
+ /**
1529
+ * Login credentials for the SMTP session (the protocol's `AUTH` command, RFC 4954).
1530
+ * Both fields must be non-empty for the provider to be configured.
1531
+ */
1532
+ interface SmtpCredentials {
1533
+ /**
1534
+ * Login user. Explicitly `| undefined` — not merely optional — so a consumer can
1535
+ * pass `process.env.SMTP_USER` straight through under `exactOptionalPropertyTypes`.
1536
+ * A missing variable then makes `isConfigured()` answer `false` instead of forcing
1537
+ * a non-null assertion at the call site or logging in as `undefined`.
1538
+ */
1539
+ user?: string | undefined;
1540
+ /** Login password (or app/API secret). See {@link SmtpCredentials.user}. */
1541
+ pass?: string | undefined;
1542
+ }
1543
+ /** Construction options for {@link SmtpEmailProvider}. */
1544
+ interface SmtpEmailProviderOptions {
1545
+ /**
1546
+ * Relay hostname or IP. Required — without it the provider is not configured.
1547
+ * Explicitly `| undefined` so `process.env.SMTP_HOST` can be passed straight
1548
+ * through; see {@link SmtpCredentials.user}.
1549
+ */
1550
+ host?: string | undefined;
1551
+ /** TCP port. Defaults to `587` (submission). */
1552
+ port?: number;
1553
+ /**
1554
+ * Whether TLS wraps the connection from the first byte (implicit TLS, port 465).
1555
+ * Defaults to `true` only when `port` is `465`. Leave `false` for submission and
1556
+ * plaintext capture servers; the connection is still upgraded through STARTTLS
1557
+ * when the relay advertises it. Use {@link SmtpEmailProviderOptions.requireTls}
1558
+ * to make that upgrade mandatory.
1559
+ */
1560
+ secure?: boolean;
1561
+ /**
1562
+ * Whether to require a STARTTLS upgrade on a non-implicit-TLS connection, failing
1563
+ * the send when the relay does not offer it.
1564
+ *
1565
+ * **Defaults to `true` for any non-loopback host**, and to `false` for
1566
+ * `localhost` / `127.0.0.1` / `::1` (the local capture-server case) and whenever
1567
+ * `secure` is already on. Without it, whether the session is encrypted at all is
1568
+ * decided by the plaintext EHLO banner: an attacker with network position strips
1569
+ * the `250-STARTTLS` line, the transport never upgrades, and the credentials and
1570
+ * the body — which carries OTP codes — cross the network in the clear. Set it to
1571
+ * `false` explicitly for a relay you know cannot upgrade.
1572
+ */
1573
+ requireTls?: boolean;
1574
+ /** Login credentials. Omit entirely for an open relay (e.g. Mailpit). */
1575
+ credentials?: SmtpCredentials;
1576
+ /** TLS knobs, for a relay presenting a certificate from a private CA. */
1577
+ tls?: SmtpTlsOptions;
1578
+ /** TCP connection timeout in milliseconds. Defaults to `10000`. */
1579
+ connectionTimeout?: number;
1580
+ /** Server-greeting timeout in milliseconds. Defaults to `10000`. */
1581
+ greetingTimeout?: number;
1582
+ /** Idle-socket timeout in milliseconds. Defaults to `20000`. */
1583
+ socketTimeout?: number;
1584
+ }
1585
+ /**
1586
+ * Reference {@link IEmailProvider} speaking SMTP.
1587
+ *
1588
+ * @example Local capture server (Mailpit / MailHog)
1589
+ * ```ts
1590
+ * new SmtpEmailProvider({ host: 'localhost', port: 1025, secure: false })
1591
+ * ```
1592
+ *
1593
+ * @example Authenticated production relay
1594
+ * ```ts
1595
+ * BymaxNotificationModule.forRoot({
1596
+ * email: {
1597
+ * provider: new SmtpEmailProvider({
1598
+ * host: process.env.SMTP_HOST,
1599
+ * port: 587,
1600
+ * requireTls: true,
1601
+ * credentials: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS }
1602
+ * }),
1603
+ * defaultFrom: 'noreply@acme.com'
1604
+ * }
1605
+ * })
1606
+ * ```
1607
+ *
1608
+ * @remarks `EmailSendOptions.tags` are not forwarded: SMTP has no tag facility.
1609
+ * They still reach the audit log through `EmailService`.
1610
+ */
1611
+ declare class SmtpEmailProvider implements IEmailProvider {
1612
+ #private;
1613
+ readonly name = "smtp";
1614
+ private readonly logger;
1615
+ /**
1616
+ * @param options - Adapter options; `host` is required to actually send, and
1617
+ * `credentials` must be complete whenever supplied at all.
1618
+ */
1619
+ constructor(options?: SmtpEmailProviderOptions);
1620
+ /**
1621
+ * Whether the relay is fully described. Does not open a connection nor load
1622
+ * Nodemailer.
1623
+ *
1624
+ * A host is always required. Credentials are required only when the consumer
1625
+ * supplied a `credentials` object at all — which is how a deployment declares that
1626
+ * it logs in. That makes an open capture server configured, while a production
1627
+ * relay whose `SMTP_PASS` variable failed to load is *not*, instead of silently
1628
+ * attempting an anonymous send.
1629
+ *
1630
+ * @returns `true` when the provider can attempt a send.
1631
+ */
1632
+ isConfigured(): boolean;
1633
+ /**
1634
+ * Sends one transactional email over SMTP.
1635
+ *
1636
+ * @param options - The message envelope and body.
1637
+ * @returns The RFC-5322 `Message-ID` assigned to the message, angle brackets
1638
+ * included — the value that also appears in the delivered message's headers,
1639
+ * so an audit entry correlates with what the recipient received.
1640
+ * @throws Error When an address or custom header carries a line break, the
1641
+ * configuration is incomplete, no sender address is available, the `nodemailer`
1642
+ * package is not installed, the transport rejects the message, or no message id
1643
+ * comes back. `EmailService` maps any thrown `Error` to `EMAIL_SEND_FAILED`.
1644
+ */
1645
+ send(options: EmailSendOptions): Promise<EmailSendResult>;
1646
+ /**
1647
+ * Hands the payload to the transport, converting a transport failure into a plain
1648
+ * `Error` whose message has the SMTP password scrubbed out. The email body is
1649
+ * never part of what is logged.
1650
+ *
1651
+ * @param transport - The initialized transport.
1652
+ * @param payload - The message to send.
1653
+ * @returns The transport's send info.
1654
+ * @throws Error When the transport rejects the message.
1655
+ */
1656
+ private dispatch;
1657
+ /**
1658
+ * Replaces every occurrence of either configured credential with a placeholder.
1659
+ *
1660
+ * A relay can echo the failing command back in its response, and a socket error
1661
+ * can carry the connection options — either would otherwise put the credential
1662
+ * into a log line and into the audit entry `EmailService` writes from the thrown
1663
+ * message.
1664
+ *
1665
+ * The **user** is scrubbed alongside the password because it is not always a
1666
+ * public login: an SES SMTP username, for one, is itself generated secret
1667
+ * material. Matching is literal and unconditional, so a short credential
1668
+ * over-redacts a message rather than risking a miss — the safe direction for a
1669
+ * control whose other failure mode is persisting a secret.
1670
+ *
1671
+ * @param message - The raw error message.
1672
+ * @returns The message with both credentials removed, unchanged when none is set.
1673
+ */
1674
+ private redact;
1675
+ /**
1676
+ * Rejects a line break in any caller-supplied value that becomes a message header.
1677
+ *
1678
+ * Nodemailer's MIME layer already strips `CR`/`LF` from header names and values and
1679
+ * derives the envelope from parsed address objects rather than raw strings, so this
1680
+ * is defence in depth rather than the only barrier — but header injection is the
1681
+ * one place where trusting a peer dependency's current behaviour would be the whole
1682
+ * security boundary. The subject is left out on purpose: a stray trailing newline
1683
+ * from a template is plausible there, and Nodemailer's strip handles it without a
1684
+ * hard failure.
1685
+ *
1686
+ * @param options - The message envelope.
1687
+ * @throws Error When a line break appears in an address or a custom header.
1688
+ */
1689
+ private guardHeaderInjection;
1690
+ /**
1691
+ * Throws when a value carries a `CR` or `LF`.
1692
+ *
1693
+ * @param field - The field name, for the error message.
1694
+ * @param value - The value to check; `undefined` passes.
1695
+ * @throws Error When the value contains a line break.
1696
+ */
1697
+ private rejectLineBreak;
1698
+ /**
1699
+ * Builds the sender in Nodemailer's structured address form.
1700
+ *
1701
+ * Never concatenates the display name into `"Name <address>"` — see
1702
+ * {@link SmtpSender} for why that hands the sender away to whoever controls the
1703
+ * name.
1704
+ *
1705
+ * @param from - The sender address, if any.
1706
+ * @param fromName - The sender display name, if any.
1707
+ * @returns The sender; `name` is `''` when no display name was supplied.
1708
+ * @throws Error When no sender address is available — SMTP needs an envelope
1709
+ * sender, so an absent `from` and `defaultFrom` is a configuration bug worth
1710
+ * reporting plainly rather than a cryptic transport rejection.
1711
+ */
1712
+ private buildSender;
1713
+ /**
1714
+ * Maps the library's attachments onto Nodemailer's shape.
1715
+ *
1716
+ * `EmailAttachment.content` is documented as a `Buffer` **or a base64 string**, so
1717
+ * a string is tagged `encoding: 'base64'` — left untagged, Nodemailer would treat
1718
+ * the base64 text as the literal body and deliver a corrupt file.
1719
+ *
1720
+ * @param attachments - The attachments to map, if any.
1721
+ * @returns The mapped attachments, or `undefined` when there are none.
1722
+ */
1723
+ private mapAttachments;
1724
+ /**
1725
+ * Returns the cached transport, lazily importing `nodemailer` on first use.
1726
+ * Concurrent first calls share one in-flight initialization promise so the dynamic
1727
+ * import and creation run exactly once; a failed init is dropped from the cache so
1728
+ * a later call can retry instead of being permanently bricked.
1729
+ *
1730
+ * @returns The initialized transport.
1731
+ * @throws Error When the configuration is incomplete or `nodemailer` is missing.
1732
+ */
1733
+ private getTransport;
1734
+ /**
1735
+ * Builds a fresh transport, resetting the cached promise on any failure so the
1736
+ * provider is not permanently bricked by a transient init error.
1737
+ *
1738
+ * @returns The initialized transport.
1739
+ * @throws Error When the configuration is incomplete or `nodemailer` is missing.
1740
+ */
1741
+ private createTransport;
1742
+ /**
1743
+ * Calls into Nodemailer to build the transport, scrubbing the password out of a
1744
+ * failure.
1745
+ *
1746
+ * Redaction is applied here and in {@link SmtpEmailProvider.dispatch} rather than
1747
+ * around the whole initialization, because those two are the only calls that cross
1748
+ * into foreign code. This adapter's own errors — a missing host, incomplete
1749
+ * credentials — never contain the password, and running them through a substring
1750
+ * scrub would corrupt them: a one-character password rewrites every occurrence of
1751
+ * that character in the sentence.
1752
+ *
1753
+ * @param nodemailer - The loaded module surface.
1754
+ * @param config - The resolved transport configuration.
1755
+ * @returns The initialized transport.
1756
+ * @throws Error When the transport rejects its configuration.
1757
+ */
1758
+ private instantiate;
1759
+ /**
1760
+ * Scrubs the password out of an initialization failure.
1761
+ *
1762
+ * `dispatch()` covers the send path, but this one covers the build path — a
1763
+ * transport implementation that validates its configuration eagerly could throw
1764
+ * with the credential pair stringified into the message, and this `catch` is the
1765
+ * only thing between that and the audit entry. An error whose message needs no
1766
+ * change is returned untouched, so its type and stack survive.
1767
+ *
1768
+ * Always an `Error`, because `IEmailProvider.send` documents that it throws one
1769
+ * and a direct caller is entitled to rely on that. Identity is preserved only for
1770
+ * an `Error` whose message needed no change — there its type and stack are worth
1771
+ * keeping; anything else is wrapped.
1772
+ *
1773
+ * @param error - The raw failure.
1774
+ * @returns The original `Error` when nothing needed scrubbing, otherwise a plain
1775
+ * `Error` carrying the scrubbed message.
1776
+ */
1777
+ private redactError;
1778
+ /**
1779
+ * Resolves the transport configuration, applying defaults and validating that the
1780
+ * relay is fully described.
1781
+ *
1782
+ * @returns The resolved configuration.
1783
+ * @throws Error When `host` is missing, or `credentials` were supplied incomplete.
1784
+ */
1785
+ private buildTransportConfig;
1786
+ /**
1787
+ * Resolves the credential pair to hand the transport.
1788
+ *
1789
+ * @returns The credential pair, or `undefined` for an open relay.
1790
+ * @throws Error When `credentials` were supplied but are missing `user` or `pass`
1791
+ * — that is a deployment declaring it logs in while its secrets failed to load, so
1792
+ * it must fail closed rather than fall back to an anonymous send.
1793
+ */
1794
+ private resolveCredentials;
1795
+ /**
1796
+ * Dynamically imports the optional `nodemailer` peer dependency, tolerating both
1797
+ * shapes the specifier can resolve to — a namespace carrying `createTransport` as
1798
+ * a named export, and one where the CommonJS module lands under `default`.
1799
+ *
1800
+ * @returns The module's callable surface.
1801
+ * @throws Error When the package is not installed in the consumer app.
1802
+ */
1803
+ private loadNodemailer;
1804
+ }
1805
+
1493
1806
  /**
1494
1807
  * @fileoverview In-memory `IOtpStorage` for development and unit tests.
1495
1808
  * @layer infrastructure
@@ -2145,4 +2458,4 @@ declare const DEFAULT_TTLS: {
2145
2458
  readonly OTP_GENERIC_SECONDS: 600;
2146
2459
  };
2147
2460
 
2148
- export { type AuditOptions, BYMAX_NOTIFICATION_EMAIL_PROVIDER, BYMAX_NOTIFICATION_LOG_REPOSITORY, BYMAX_NOTIFICATION_OPTIONS, BYMAX_NOTIFICATION_OTP_STORAGE, BYMAX_NOTIFICATION_PUSH_PROVIDER, BYMAX_NOTIFICATION_SMS_PROVIDER, BYMAX_NOTIFICATION_TEMPLATE_RENDERER, BymaxNotificationModule, type BymaxNotificationModuleAsyncOptions, type BymaxNotificationModuleOptions, type BymaxNotificationModuleOptionsFactory, CANONICAL_EMAIL_TEMPLATES, type CanonicalEmailTemplate, type CanonicalNotificationPurpose, type ConsumeAttemptResult, DEFAULT_TTLS, DefaultTemplateRenderer, type DefaultTemplateRendererOptions, type DispatchInput, type DispatchResult, type EmailAttachment, type EmailChannelOptions, type EmailDispatchPayload, type EmailSendInput, type EmailSendOptions, type EmailSendResult, type EmailSendTemplateInput, EmailService, type GlobalOptions, type IEmailProvider, type IEmailTemplateRenderer, type INotificationLogRepository, type IOtpStorage, type IPushProvider, type ISmsProvider, InMemoryOtpStorage, type InMemoryStorageSize, type MissingVariableMode, NOTIFICATION_ERROR_CODES, NOTIFICATION_ERROR_DEFINITIONS, NOTIFICATION_PURPOSES, NoOpEmailProvider, NoOpNotificationLogRepository, NotificationAuditInterceptor, type NotificationChannel, type NotificationErrorCode, type NotificationErrorDefinition, type NotificationErrorKey, type NotificationErrorResponse, NotificationException, type NotificationLogEntry, type NotificationLogVerb, type NotificationRequest, NotificationService, type OtpChannelOptions, type OtpConsumeInput, type OtpDispatchPayload, type OtpEntry, type OtpGenerateInput, type OtpGenerateResult, type OtpPurpose, type OtpPurposeConfig, OtpService, type OtpStatusInput, type OtpStatusResult, type OtpVerifyInput, type OtpVerifyResult, type PushChannelOptions, type PushSendOptions, type PushSendResult, type RedisLike, RedisOtpStorage, type RedisOtpStorageOptions, type RenderedEmail, ResendEmailProvider, type ResendEmailProviderOptions, type ResolvedAuditOptions, type ResolvedEmailOptions, type ResolvedGlobalOptions, type ResolvedNotificationOptions, type ResolvedOtpOptions, type SmsChannelOptions, type SmsSendOptions, type SmsSendResult, type TemplateDefinition, cooldownExpiresAt, formatCooldown, generateOtpCode, hashTenantRecipient, safeCompare, toRetryAfterHeader };
2461
+ export { type AuditOptions, BYMAX_NOTIFICATION_EMAIL_PROVIDER, BYMAX_NOTIFICATION_LOG_REPOSITORY, BYMAX_NOTIFICATION_OPTIONS, BYMAX_NOTIFICATION_OTP_STORAGE, BYMAX_NOTIFICATION_PUSH_PROVIDER, BYMAX_NOTIFICATION_SMS_PROVIDER, BYMAX_NOTIFICATION_TEMPLATE_RENDERER, BymaxNotificationModule, type BymaxNotificationModuleAsyncOptions, type BymaxNotificationModuleOptions, type BymaxNotificationModuleOptionsFactory, CANONICAL_EMAIL_TEMPLATES, type CanonicalEmailTemplate, type CanonicalNotificationPurpose, type ConsumeAttemptResult, DEFAULT_TTLS, DefaultTemplateRenderer, type DefaultTemplateRendererOptions, type DispatchInput, type DispatchResult, type EmailAttachment, type EmailChannelOptions, type EmailDispatchPayload, type EmailSendInput, type EmailSendOptions, type EmailSendResult, type EmailSendTemplateInput, EmailService, type GlobalOptions, type IEmailProvider, type IEmailTemplateRenderer, type INotificationLogRepository, type IOtpStorage, type IPushProvider, type ISmsProvider, InMemoryOtpStorage, type InMemoryStorageSize, type MissingVariableMode, NOTIFICATION_ERROR_CODES, NOTIFICATION_ERROR_DEFINITIONS, NOTIFICATION_PURPOSES, NoOpEmailProvider, NoOpNotificationLogRepository, NotificationAuditInterceptor, type NotificationChannel, type NotificationErrorCode, type NotificationErrorDefinition, type NotificationErrorKey, type NotificationErrorResponse, NotificationException, type NotificationLogEntry, type NotificationLogVerb, type NotificationRequest, NotificationService, type OtpChannelOptions, type OtpConsumeInput, type OtpDispatchPayload, type OtpEntry, type OtpGenerateInput, type OtpGenerateResult, type OtpPurpose, type OtpPurposeConfig, OtpService, type OtpStatusInput, type OtpStatusResult, type OtpVerifyInput, type OtpVerifyResult, type PushChannelOptions, type PushSendOptions, type PushSendResult, type RedisLike, RedisOtpStorage, type RedisOtpStorageOptions, type RenderedEmail, ResendEmailProvider, type ResendEmailProviderOptions, type ResolvedAuditOptions, type ResolvedEmailOptions, type ResolvedGlobalOptions, type ResolvedNotificationOptions, type ResolvedOtpOptions, type SmsChannelOptions, type SmsSendOptions, type SmsSendResult, type SmtpCredentials, SmtpEmailProvider, type SmtpEmailProviderOptions, type SmtpTlsOptions, type TemplateDefinition, cooldownExpiresAt, formatCooldown, generateOtpCode, hashTenantRecipient, safeCompare, toRetryAfterHeader };