@bymax-one/nest-notification 1.1.0 → 1.1.2

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