@bymax-one/nest-notification 1.4.4 → 1.4.5

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.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.4.5] - 2026-11-01
11
+
12
+ ### Added
13
+
14
+ - **A startup warning for an OTP channel whose email template cannot be found.** The OTP email is
15
+ rendered from the `otp_code` template and the default renderer ships none, so a host that enables
16
+ OTP with an email channel and no such template booted cleanly and failed on the first
17
+ `generate()`. When the OTP channel is on, the email provider is configured and the renderer has
18
+ `otp_code` for neither the default locale nor `en`, one line,
19
+ `BYMAX_NOTIFICATION_OTP_TEMPLATE_NOT_RESOLVED`, is logged at startup. It names the way out and
20
+ the hosts it does not apply to: those that pass `emailTemplate` on every call, deliver manually,
21
+ or load templates after startup. The check runs detached, so it never delays or fails boot, even
22
+ for a renderer that throws, rejects or never answers (in the first two cases the line says the
23
+ check could not run and why).
24
+
25
+ ### Changed
26
+
27
+ - **`TEMPLATE_NOT_FOUND` for `otp_code` carries a `remedy`.** `details` gains `remedy`, naming the
28
+ template, `DefaultTemplateRenderer` and the `emailTemplate` option. `template` and `locale` are
29
+ unchanged, and the error for any other template is unchanged.
30
+
10
31
  ## [1.4.4] - 2026-11-01
11
32
 
12
33
  Documentation only: `dist/` is byte-identical to 1.4.3.
@@ -982,7 +1003,8 @@ rejected at startup rather than failing on the first send.
982
1003
 
983
1004
  [1.0.4]: https://github.com/bymaxone/nest-notification/compare/v1.0.3...v1.0.4
984
1005
  [1.0.3]: https://github.com/bymaxone/nest-notification/compare/v1.0.2...v1.0.3
985
- [Unreleased]: https://github.com/bymaxone/nest-notification/compare/v1.4.4...HEAD
1006
+ [Unreleased]: https://github.com/bymaxone/nest-notification/compare/v1.4.5...HEAD
1007
+ [1.4.5]: https://github.com/bymaxone/nest-notification/compare/v1.4.4...v1.4.5
986
1008
  [1.4.4]: https://github.com/bymaxone/nest-notification/compare/v1.4.3...v1.4.4
987
1009
  [1.4.3]: https://github.com/bymaxone/nest-notification/compare/v1.4.2...v1.4.3
988
1010
  [1.4.2]: https://github.com/bymaxone/nest-notification/compare/v1.4.1...v1.4.2
package/README.md CHANGED
@@ -184,7 +184,7 @@ import {
184
184
  export class AppModule {}
185
185
  ```
186
186
 
187
- The OTP email is rendered from the `otp_code` template, and the default renderer ships none, so register one as above (the same template as in step 3). Without it the first `generate()` throws `TEMPLATE_NOT_FOUND`.
187
+ The OTP email is rendered from the `otp_code` template, and the default renderer ships none, so register one as above (the same template as in step 3). Without it the first `generate()` throws `TEMPLATE_NOT_FOUND` (its details carry a `remedy` for this case), and one warning, `BYMAX_NOTIFICATION_OTP_TEMPLATE_NOT_RESOLVED`, is logged at startup. Ignore that line if every `generate()` passes `emailTemplate`, if you deliver manually, or if your renderer loads its templates after startup.
188
188
 
189
189
  Inject `OtpService` anywhere and the two-step flow is complete:
190
190
 
@@ -838,32 +838,32 @@ Error codes are namespaced (`notification.otp_invalid_code`, `notification.otp_c
838
838
 
839
839
  A code marked **reserved** is part of the catalog but is never thrown by the library, so a consumer can map it without the library ever raising it behind their back. The four OTP verify outcomes are the notable ones: `verify()` returns its failure as a result (`{ valid: false, reason }`) and never throws it, so your controller maps `reason` to the code it wants to answer with. The SMS and push codes stay reserved until those channels exist.
840
840
 
841
- | Code | Status | Raised by |
842
- | ------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------ |
843
- | `notification.email_provider_not_configured` | 500 | `EmailService` — the provider reports `isConfigured() === false` |
844
- | `notification.email_send_failed` | 502 | `EmailService` — the provider rejected the send |
845
- | `notification.email_attachments_too_large` | 413 | `EmailService` — the attachments exceed `maxAttachmentBytes` |
846
- | `notification.email_invalid_recipient` | 400 | reserved — `to` is not validated; a bad address surfaces as `email_send_failed` |
847
- | `notification.email_missing_body` | 400 | `NotificationService.dispatch` — neither a template nor a subject and body |
848
- | `notification.template_not_found` | 500 | `EmailService.sendTemplate` — no template for the locale or the fallback |
849
- | `notification.template_render_failed` | 500 | `EmailService.sendTemplate` — the renderer threw |
850
- | `notification.otp_storage_not_configured` | 500 | `OtpService` — the OTP channel is absent |
851
- | `notification.otp_email_delivery_not_configured` | 500 | `OtpService.generate` — email delivery without an email channel |
852
- | `notification.otp_manual_delivery_unavailable` | 400 | `OtpService.generate` — manual delivery while `otp.codeSecret` is set |
853
- | `notification.otp_cooldown_active` | 429 | `OtpService.generate` and `resend` — inside the resend cooldown |
854
- | `notification.otp_not_found` | 404 | reserved — `verify()` returns `{ valid: false, reason: 'not_found' }` |
855
- | `notification.otp_expired` | 410 | reserved — an expired code is reported as `not_found` |
856
- | `notification.otp_max_attempts_exceeded` | 429 | reserved — `verify()` returns `{ valid: false, reason: 'max_attempts' }` |
857
- | `notification.otp_invalid_code` | 401 | reserved — `verify()` returns `{ valid: false, reason: 'invalid_code' }` |
858
- | `notification.otp_invalid_length` | 400 | module options validation and the code generator |
859
- | `notification.sms_provider_not_configured` | 500 | reserved — the SMS channel is not implemented |
860
- | `notification.sms_send_failed` | 502 | reserved — the SMS channel is not implemented |
861
- | `notification.sms_invalid_recipient` | 400 | reserved — the SMS channel is not implemented |
862
- | `notification.push_provider_not_configured` | 500 | reserved — the push channel is not implemented |
863
- | `notification.push_send_failed` | 502 | reserved — the push channel is not implemented |
864
- | `notification.audit_log_failed` | 500 | `EmailService`, `OtpService` and `NotificationAuditInterceptor` — only with `audit.swallowErrors: false` |
865
- | `notification.channel_disabled` | 501 | `NotificationService` — the channel is absent, or its provider or storage is not usable |
866
- | `notification.invalid_scope_identifier` | 400 | `OtpService`, `EmailService` and `NotificationAuditInterceptor` — a blank or control-character tenant or recipient |
841
+ | Code | Status | Raised by |
842
+ | ------------------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
843
+ | `notification.email_provider_not_configured` | 500 | `EmailService` — the provider reports `isConfigured() === false` |
844
+ | `notification.email_send_failed` | 502 | `EmailService` — the provider rejected the send |
845
+ | `notification.email_attachments_too_large` | 413 | `EmailService` — the attachments exceed `maxAttachmentBytes` |
846
+ | `notification.email_invalid_recipient` | 400 | reserved — `to` is not validated; a bad address surfaces as `email_send_failed` |
847
+ | `notification.email_missing_body` | 400 | `NotificationService.dispatch` — neither a template nor a subject and body |
848
+ | `notification.template_not_found` | 500 | `EmailService.sendTemplate` — no template for the locale or the fallback (for `otp_code`, `details.remedy` says how to register it) |
849
+ | `notification.template_render_failed` | 500 | `EmailService.sendTemplate` — the renderer threw |
850
+ | `notification.otp_storage_not_configured` | 500 | `OtpService` — the OTP channel is absent |
851
+ | `notification.otp_email_delivery_not_configured` | 500 | `OtpService.generate` — email delivery without an email channel |
852
+ | `notification.otp_manual_delivery_unavailable` | 400 | `OtpService.generate` — manual delivery while `otp.codeSecret` is set |
853
+ | `notification.otp_cooldown_active` | 429 | `OtpService.generate` and `resend` — inside the resend cooldown |
854
+ | `notification.otp_not_found` | 404 | reserved — `verify()` returns `{ valid: false, reason: 'not_found' }` |
855
+ | `notification.otp_expired` | 410 | reserved — an expired code is reported as `not_found` |
856
+ | `notification.otp_max_attempts_exceeded` | 429 | reserved — `verify()` returns `{ valid: false, reason: 'max_attempts' }` |
857
+ | `notification.otp_invalid_code` | 401 | reserved — `verify()` returns `{ valid: false, reason: 'invalid_code' }` |
858
+ | `notification.otp_invalid_length` | 400 | module options validation and the code generator |
859
+ | `notification.sms_provider_not_configured` | 500 | reserved — the SMS channel is not implemented |
860
+ | `notification.sms_send_failed` | 502 | reserved — the SMS channel is not implemented |
861
+ | `notification.sms_invalid_recipient` | 400 | reserved — the SMS channel is not implemented |
862
+ | `notification.push_provider_not_configured` | 500 | reserved — the push channel is not implemented |
863
+ | `notification.push_send_failed` | 502 | reserved — the push channel is not implemented |
864
+ | `notification.audit_log_failed` | 500 | `EmailService`, `OtpService` and `NotificationAuditInterceptor` — only with `audit.swallowErrors: false` |
865
+ | `notification.channel_disabled` | 501 | `NotificationService` — the channel is absent, or its provider or storage is not usable |
866
+ | `notification.invalid_scope_identifier` | 400 | `OtpService`, `EmailService` and `NotificationAuditInterceptor` — a blank or control-character tenant or recipient |
867
867
 
868
868
  Failures raised by the library carry the underlying error as the native `Error.cause` — a provider's `connect ECONNREFUSED` sits on `exception.cause`, where cause-walking log serializers (e.g. pino's `err`) print it alongside the stable code. The cause is stored as a **log-safe copy**: `name`, `message`, `stack`, and the nested `cause` chain survive (depth-bounded); every other property is dropped, because SDK errors routinely retain the request payload (an axios-style `config.data`) and for an OTP email that payload contains the code. The cause never enters the HTTP response body either: `details` stays reserved for the structured, client-safe context shown above. To attach a cause in your own code, pass the options bag as the third constructor argument — `new NotificationException('EMAIL_SEND_FAILED', { providerName }, { cause: error })`; the positional `(key, details, status, message)` form keeps working.
869
869
 
@@ -602,6 +602,30 @@ exports.NoOpNotificationLogRepository = __decorateClass([
602
602
  common.Injectable()
603
603
  ], exports.NoOpNotificationLogRepository);
604
604
 
605
+ // src/server/constants/canonical-templates.ts
606
+ var CANONICAL_EMAIL_TEMPLATES = {
607
+ /** OTP for email verification — variables: `code`, `expiresInMinutes`, `purpose`, `name`, `appName`. */
608
+ OTP_CODE: "otp_code",
609
+ /** OTP for password reset (distinct copy; may carry a deep link) — variables: `code`, `expiresInMinutes`, `name`, `appName`, `verificationLink`. */
610
+ OTP_PASSWORD_RESET: "otp_password_reset",
611
+ /** OTP resend — same variables as the originating OTP template. */
612
+ OTP_RESENT: "otp_resent",
613
+ /** Welcome after email verification — variables: `name`, `appName`, `appUrl`. */
614
+ WELCOME: "welcome",
615
+ /** Password reset success — variables: `name`, `appName`, `supportEmail`. */
616
+ PASSWORD_RESET_SUCCESS: "password_reset_success",
617
+ /** Trial ending soon — variables: `name`, `appName`, `trialPlanName`, `daysLeft`, `appUrl`. */
618
+ TRIAL_EXPIRING: "trial_expiring",
619
+ /** Trial ended — variables: `name`, `appName`, `trialPlanName`, `durationDays`, `appUrl`. */
620
+ TRIAL_EXPIRED: "trial_expired",
621
+ /** New device login — variables: `device`, `ip`, `timestamp`, `name`, `appName`. */
622
+ NEW_LOGIN_ALERT: "new_login_alert",
623
+ /** MFA enabled — variables: `name`, `appName`. */
624
+ MFA_ENABLED: "mfa_enabled",
625
+ /** MFA disabled — variables: `name`, `appName`. */
626
+ MFA_DISABLED: "mfa_disabled"
627
+ };
628
+
605
629
  // src/server/utils/delivery-status.ts
606
630
  var MAX_SUBFIELD_DIGITS = 3;
607
631
  var BASIC_STATUS = /(?<![\d.])([245]\d\d)(?![\d.])/g;
@@ -910,6 +934,7 @@ function assertIdentifies(owner, label, value) {
910
934
 
911
935
  // src/server/services/email.service.ts
912
936
  var FALLBACK_LOCALE = "en";
937
+ var OTP_TEMPLATE_REMEDY = "register an 'otp_code' template (for example 'otp_code::en') in your template renderer, such as DefaultTemplateRenderer, or pass emailTemplate to generate()";
913
938
  var WITHHELD_PROVIDER_TEXT = "[provider text withheld]";
914
939
  function readAttachedStatus(error) {
915
940
  try {
@@ -1091,15 +1116,43 @@ exports.EmailService = class EmailService {
1091
1116
  ...input.publishProviderText !== void 0 ? { publishProviderText: input.publishProviderText } : {}
1092
1117
  };
1093
1118
  }
1094
- /** Picks the locale that has a template, falling back to `en`, else throws `TEMPLATE_NOT_FOUND`. */
1095
- async resolveTemplateLocale(template, locale) {
1119
+ /**
1120
+ * Picks the locale that has a template: the requested one, else `en`. Answers `undefined` when
1121
+ * neither has it. The one probe behind both a send and the startup check, so the two cannot
1122
+ * disagree.
1123
+ * @internal
1124
+ */
1125
+ async findTemplateLocale(template, locale) {
1096
1126
  if (await this.renderer.hasTemplate(template, locale)) {
1097
1127
  return locale;
1098
1128
  }
1099
1129
  if (await this.renderer.hasTemplate(template, FALLBACK_LOCALE)) {
1100
1130
  return FALLBACK_LOCALE;
1101
1131
  }
1102
- throw new NotificationException("TEMPLATE_NOT_FOUND", { template, locale });
1132
+ return void 0;
1133
+ }
1134
+ /**
1135
+ * Whether a send of `template` for `locale` would find it: the requested locale, else `en`,
1136
+ * probed in that order exactly as {@link EmailService.sendTemplate} does.
1137
+ *
1138
+ * @param template - The template name.
1139
+ * @param locale - The requested locale.
1140
+ * @returns `true` when the renderer has the template for the locale or for `en`.
1141
+ * @internal
1142
+ */
1143
+ async resolvesTemplate(template, locale) {
1144
+ return await this.findTemplateLocale(template, locale) !== void 0;
1145
+ }
1146
+ /** Picks the locale that has a template, falling back to `en`, else throws `TEMPLATE_NOT_FOUND`. */
1147
+ async resolveTemplateLocale(template, locale) {
1148
+ const found = await this.findTemplateLocale(template, locale);
1149
+ if (found !== void 0) {
1150
+ return found;
1151
+ }
1152
+ throw new NotificationException(
1153
+ "TEMPLATE_NOT_FOUND",
1154
+ template === CANONICAL_EMAIL_TEMPLATES.OTP_CODE ? { template, locale, remedy: OTP_TEMPLATE_REMEDY } : { template, locale }
1155
+ );
1103
1156
  }
1104
1157
  /** Renders the template, mapping a renderer failure to `TEMPLATE_RENDER_FAILED`. */
1105
1158
  async renderTemplate(template, data, locale, redactValues2) {
@@ -1284,7 +1337,8 @@ function safeCompare(expected, actual) {
1284
1337
  // src/server/services/otp.service.ts
1285
1338
  var MS_PER_SECOND2 = 1e3;
1286
1339
  var SECONDS_PER_MINUTE2 = 60;
1287
- var DEFAULT_OTP_TEMPLATE = "otp_code";
1340
+ var DEFAULT_OTP_TEMPLATE = CANONICAL_EMAIL_TEMPLATES.OTP_CODE;
1341
+ var TEMPLATE_WARNING_CODE = "BYMAX_NOTIFICATION_OTP_TEMPLATE_NOT_RESOLVED";
1288
1342
  function carriesFailures(storage) {
1289
1343
  return storage.getFailures !== void 0 && storage.recordFailure !== void 0 && storage.clearFailures !== void 0;
1290
1344
  }
@@ -1302,6 +1356,8 @@ exports.OtpService = class OtpService {
1302
1356
  this.emailService = emailService;
1303
1357
  this.logger = new common.Logger(exports.OtpService.name);
1304
1358
  this.warnedFailuresNotCarried = false;
1359
+ /** @internal */
1360
+ this.warnedTemplate = false;
1305
1361
  }
1306
1362
  /**
1307
1363
  * Whether the OTP channel is configured and its storage is ready.
@@ -1510,11 +1566,21 @@ exports.OtpService = class OtpService {
1510
1566
  );
1511
1567
  return outgoing;
1512
1568
  }
1569
+ /**
1570
+ * Runs the two startup checks. Neither depends on the other, and neither can fail or delay
1571
+ * boot: the template check is started detached, so a renderer that never answers holds
1572
+ * nothing.
1573
+ */
1574
+ onModuleInit() {
1575
+ this.warnFailuresNotCarried();
1576
+ void this.warnUnresolvedDefaultTemplate();
1577
+ }
1513
1578
  /**
1514
1579
  * Warns once when the storage cannot carry failed attempts across a re-issue, naming the
1515
1580
  * deviation from NIST SP 800-63B-4 §3.1.3.2 and the methods that remove it.
1581
+ * @internal
1516
1582
  */
1517
- onModuleInit() {
1583
+ warnFailuresNotCarried() {
1518
1584
  const storage = this.storage;
1519
1585
  if (carriesFailures(storage) || this.warnedFailuresNotCarried) {
1520
1586
  return;
@@ -1524,6 +1590,32 @@ exports.OtpService = class OtpService {
1524
1590
  `[BYMAX_NOTIFICATION_OTP_FAILURES_NOT_CARRIED] The ${storage.name} OTP storage does not implement getFailures, recordFailure and clearFailures, so issuing a new code gives it a fresh attempt budget; NIST SP 800-63B-4 \xA73.1.3.2 says generating a new secret SHALL NOT reset the failed authentication count. Implement the three optional methods to carry the count across re-issues.`
1525
1591
  );
1526
1592
  }
1593
+ /**
1594
+ * Warns once when the OTP email would fail on its first use because the renderer has no
1595
+ * `otp_code` template for the default locale or `en`. It only ever logs: it catches
1596
+ * everything, so it cannot reject, and a renderer that answers late or never leaves boot
1597
+ * untouched because the caller does not wait for it.
1598
+ * @internal
1599
+ */
1600
+ async warnUnresolvedDefaultTemplate() {
1601
+ if (this.warnedTemplate || !this.options.otp || !this.emailService) {
1602
+ return;
1603
+ }
1604
+ this.warnedTemplate = true;
1605
+ const locale = this.options.global.defaultLocale;
1606
+ try {
1607
+ if (!this.emailService.isConfigured() || await this.emailService.resolvesTemplate(DEFAULT_OTP_TEMPLATE, locale)) {
1608
+ return;
1609
+ }
1610
+ this.logger.warn(
1611
+ `[${TEMPLATE_WARNING_CODE}] The email template '${DEFAULT_OTP_TEMPLATE}' resolves for neither '${locale}' nor 'en', so the first generate() that delivers by email fails with TEMPLATE_NOT_FOUND. Register '${DEFAULT_OTP_TEMPLATE}' in your template renderer (DefaultTemplateRenderer takes it under 'otp_code::en'). Ignore this line if every generate() call passes emailTemplate, if you deliver manually, or if your renderer loads its templates after startup.`
1612
+ );
1613
+ } catch (error) {
1614
+ this.logger.warn(
1615
+ `[${TEMPLATE_WARNING_CODE}] Could not check whether the email template '${DEFAULT_OTP_TEMPLATE}' resolves (${describeError(error)}); if it does not, the first generate() that delivers by email fails with TEMPLATE_NOT_FOUND.`
1616
+ );
1617
+ }
1618
+ }
1527
1619
  /**
1528
1620
  * Counts one verification attempt against the recipient. Returns `undefined` when the storage
1529
1621
  * does not carry failures, and `null` when no code is live: a verification with no code guesses
@@ -2263,30 +2355,6 @@ var NOTIFICATION_PURPOSES = {
2263
2355
  PHONE_VERIFICATION: "phone_verification",
2264
2356
  MAGIC_LINK: "magic_link"
2265
2357
  };
2266
-
2267
- // src/server/constants/canonical-templates.ts
2268
- var CANONICAL_EMAIL_TEMPLATES = {
2269
- /** OTP for email verification — variables: `code`, `expiresInMinutes`, `purpose`, `name`, `appName`. */
2270
- OTP_CODE: "otp_code",
2271
- /** OTP for password reset (distinct copy; may carry a deep link) — variables: `code`, `expiresInMinutes`, `name`, `appName`, `verificationLink`. */
2272
- OTP_PASSWORD_RESET: "otp_password_reset",
2273
- /** OTP resend — same variables as the originating OTP template. */
2274
- OTP_RESENT: "otp_resent",
2275
- /** Welcome after email verification — variables: `name`, `appName`, `appUrl`. */
2276
- WELCOME: "welcome",
2277
- /** Password reset success — variables: `name`, `appName`, `supportEmail`. */
2278
- PASSWORD_RESET_SUCCESS: "password_reset_success",
2279
- /** Trial ending soon — variables: `name`, `appName`, `trialPlanName`, `daysLeft`, `appUrl`. */
2280
- TRIAL_EXPIRING: "trial_expiring",
2281
- /** Trial ended — variables: `name`, `appName`, `trialPlanName`, `durationDays`, `appUrl`. */
2282
- TRIAL_EXPIRED: "trial_expired",
2283
- /** New device login — variables: `device`, `ip`, `timestamp`, `name`, `appName`. */
2284
- NEW_LOGIN_ALERT: "new_login_alert",
2285
- /** MFA enabled — variables: `name`, `appName`. */
2286
- MFA_ENABLED: "mfa_enabled",
2287
- /** MFA disabled — variables: `name`, `appName`. */
2288
- MFA_DISABLED: "mfa_disabled"
2289
- };
2290
2358
  function maskEmail(address) {
2291
2359
  const at = address.lastIndexOf("@");
2292
2360
  if (at <= 0) {
@@ -1133,8 +1133,9 @@ declare class OtpService implements OnModuleInit {
1133
1133
  */
1134
1134
  private failedOutgoing;
1135
1135
  /**
1136
- * Warns once when the storage cannot carry failed attempts across a re-issue, naming the
1137
- * deviation from NIST SP 800-63B-4 §3.1.3.2 and the methods that remove it.
1136
+ * Runs the two startup checks. Neither depends on the other, and neither can fail or delay
1137
+ * boot: the template check is started detached, so a renderer that never answers holds
1138
+ * nothing.
1138
1139
  */
1139
1140
  onModuleInit(): void;
1140
1141
  /**
@@ -1133,8 +1133,9 @@ declare class OtpService implements OnModuleInit {
1133
1133
  */
1134
1134
  private failedOutgoing;
1135
1135
  /**
1136
- * Warns once when the storage cannot carry failed attempts across a re-issue, naming the
1137
- * deviation from NIST SP 800-63B-4 §3.1.3.2 and the methods that remove it.
1136
+ * Runs the two startup checks. Neither depends on the other, and neither can fail or delay
1137
+ * boot: the template check is started detached, so a renderer that never answers holds
1138
+ * nothing.
1138
1139
  */
1139
1140
  onModuleInit(): void;
1140
1141
  /**
@@ -600,6 +600,30 @@ NoOpNotificationLogRepository = __decorateClass([
600
600
  Injectable()
601
601
  ], NoOpNotificationLogRepository);
602
602
 
603
+ // src/server/constants/canonical-templates.ts
604
+ var CANONICAL_EMAIL_TEMPLATES = {
605
+ /** OTP for email verification — variables: `code`, `expiresInMinutes`, `purpose`, `name`, `appName`. */
606
+ OTP_CODE: "otp_code",
607
+ /** OTP for password reset (distinct copy; may carry a deep link) — variables: `code`, `expiresInMinutes`, `name`, `appName`, `verificationLink`. */
608
+ OTP_PASSWORD_RESET: "otp_password_reset",
609
+ /** OTP resend — same variables as the originating OTP template. */
610
+ OTP_RESENT: "otp_resent",
611
+ /** Welcome after email verification — variables: `name`, `appName`, `appUrl`. */
612
+ WELCOME: "welcome",
613
+ /** Password reset success — variables: `name`, `appName`, `supportEmail`. */
614
+ PASSWORD_RESET_SUCCESS: "password_reset_success",
615
+ /** Trial ending soon — variables: `name`, `appName`, `trialPlanName`, `daysLeft`, `appUrl`. */
616
+ TRIAL_EXPIRING: "trial_expiring",
617
+ /** Trial ended — variables: `name`, `appName`, `trialPlanName`, `durationDays`, `appUrl`. */
618
+ TRIAL_EXPIRED: "trial_expired",
619
+ /** New device login — variables: `device`, `ip`, `timestamp`, `name`, `appName`. */
620
+ NEW_LOGIN_ALERT: "new_login_alert",
621
+ /** MFA enabled — variables: `name`, `appName`. */
622
+ MFA_ENABLED: "mfa_enabled",
623
+ /** MFA disabled — variables: `name`, `appName`. */
624
+ MFA_DISABLED: "mfa_disabled"
625
+ };
626
+
603
627
  // src/server/utils/delivery-status.ts
604
628
  var MAX_SUBFIELD_DIGITS = 3;
605
629
  var BASIC_STATUS = /(?<![\d.])([245]\d\d)(?![\d.])/g;
@@ -908,6 +932,7 @@ function assertIdentifies(owner, label, value) {
908
932
 
909
933
  // src/server/services/email.service.ts
910
934
  var FALLBACK_LOCALE = "en";
935
+ var OTP_TEMPLATE_REMEDY = "register an 'otp_code' template (for example 'otp_code::en') in your template renderer, such as DefaultTemplateRenderer, or pass emailTemplate to generate()";
911
936
  var WITHHELD_PROVIDER_TEXT = "[provider text withheld]";
912
937
  function readAttachedStatus(error) {
913
938
  try {
@@ -1089,15 +1114,43 @@ var EmailService = class {
1089
1114
  ...input.publishProviderText !== void 0 ? { publishProviderText: input.publishProviderText } : {}
1090
1115
  };
1091
1116
  }
1092
- /** Picks the locale that has a template, falling back to `en`, else throws `TEMPLATE_NOT_FOUND`. */
1093
- async resolveTemplateLocale(template, locale) {
1117
+ /**
1118
+ * Picks the locale that has a template: the requested one, else `en`. Answers `undefined` when
1119
+ * neither has it. The one probe behind both a send and the startup check, so the two cannot
1120
+ * disagree.
1121
+ * @internal
1122
+ */
1123
+ async findTemplateLocale(template, locale) {
1094
1124
  if (await this.renderer.hasTemplate(template, locale)) {
1095
1125
  return locale;
1096
1126
  }
1097
1127
  if (await this.renderer.hasTemplate(template, FALLBACK_LOCALE)) {
1098
1128
  return FALLBACK_LOCALE;
1099
1129
  }
1100
- throw new NotificationException("TEMPLATE_NOT_FOUND", { template, locale });
1130
+ return void 0;
1131
+ }
1132
+ /**
1133
+ * Whether a send of `template` for `locale` would find it: the requested locale, else `en`,
1134
+ * probed in that order exactly as {@link EmailService.sendTemplate} does.
1135
+ *
1136
+ * @param template - The template name.
1137
+ * @param locale - The requested locale.
1138
+ * @returns `true` when the renderer has the template for the locale or for `en`.
1139
+ * @internal
1140
+ */
1141
+ async resolvesTemplate(template, locale) {
1142
+ return await this.findTemplateLocale(template, locale) !== void 0;
1143
+ }
1144
+ /** Picks the locale that has a template, falling back to `en`, else throws `TEMPLATE_NOT_FOUND`. */
1145
+ async resolveTemplateLocale(template, locale) {
1146
+ const found = await this.findTemplateLocale(template, locale);
1147
+ if (found !== void 0) {
1148
+ return found;
1149
+ }
1150
+ throw new NotificationException(
1151
+ "TEMPLATE_NOT_FOUND",
1152
+ template === CANONICAL_EMAIL_TEMPLATES.OTP_CODE ? { template, locale, remedy: OTP_TEMPLATE_REMEDY } : { template, locale }
1153
+ );
1101
1154
  }
1102
1155
  /** Renders the template, mapping a renderer failure to `TEMPLATE_RENDER_FAILED`. */
1103
1156
  async renderTemplate(template, data, locale, redactValues2) {
@@ -1282,7 +1335,8 @@ function safeCompare(expected, actual) {
1282
1335
  // src/server/services/otp.service.ts
1283
1336
  var MS_PER_SECOND2 = 1e3;
1284
1337
  var SECONDS_PER_MINUTE2 = 60;
1285
- var DEFAULT_OTP_TEMPLATE = "otp_code";
1338
+ var DEFAULT_OTP_TEMPLATE = CANONICAL_EMAIL_TEMPLATES.OTP_CODE;
1339
+ var TEMPLATE_WARNING_CODE = "BYMAX_NOTIFICATION_OTP_TEMPLATE_NOT_RESOLVED";
1286
1340
  function carriesFailures(storage) {
1287
1341
  return storage.getFailures !== void 0 && storage.recordFailure !== void 0 && storage.clearFailures !== void 0;
1288
1342
  }
@@ -1300,6 +1354,8 @@ var OtpService = class {
1300
1354
  this.emailService = emailService;
1301
1355
  this.logger = new Logger(OtpService.name);
1302
1356
  this.warnedFailuresNotCarried = false;
1357
+ /** @internal */
1358
+ this.warnedTemplate = false;
1303
1359
  }
1304
1360
  /**
1305
1361
  * Whether the OTP channel is configured and its storage is ready.
@@ -1508,11 +1564,21 @@ var OtpService = class {
1508
1564
  );
1509
1565
  return outgoing;
1510
1566
  }
1567
+ /**
1568
+ * Runs the two startup checks. Neither depends on the other, and neither can fail or delay
1569
+ * boot: the template check is started detached, so a renderer that never answers holds
1570
+ * nothing.
1571
+ */
1572
+ onModuleInit() {
1573
+ this.warnFailuresNotCarried();
1574
+ void this.warnUnresolvedDefaultTemplate();
1575
+ }
1511
1576
  /**
1512
1577
  * Warns once when the storage cannot carry failed attempts across a re-issue, naming the
1513
1578
  * deviation from NIST SP 800-63B-4 §3.1.3.2 and the methods that remove it.
1579
+ * @internal
1514
1580
  */
1515
- onModuleInit() {
1581
+ warnFailuresNotCarried() {
1516
1582
  const storage = this.storage;
1517
1583
  if (carriesFailures(storage) || this.warnedFailuresNotCarried) {
1518
1584
  return;
@@ -1522,6 +1588,32 @@ var OtpService = class {
1522
1588
  `[BYMAX_NOTIFICATION_OTP_FAILURES_NOT_CARRIED] The ${storage.name} OTP storage does not implement getFailures, recordFailure and clearFailures, so issuing a new code gives it a fresh attempt budget; NIST SP 800-63B-4 \xA73.1.3.2 says generating a new secret SHALL NOT reset the failed authentication count. Implement the three optional methods to carry the count across re-issues.`
1523
1589
  );
1524
1590
  }
1591
+ /**
1592
+ * Warns once when the OTP email would fail on its first use because the renderer has no
1593
+ * `otp_code` template for the default locale or `en`. It only ever logs: it catches
1594
+ * everything, so it cannot reject, and a renderer that answers late or never leaves boot
1595
+ * untouched because the caller does not wait for it.
1596
+ * @internal
1597
+ */
1598
+ async warnUnresolvedDefaultTemplate() {
1599
+ if (this.warnedTemplate || !this.options.otp || !this.emailService) {
1600
+ return;
1601
+ }
1602
+ this.warnedTemplate = true;
1603
+ const locale = this.options.global.defaultLocale;
1604
+ try {
1605
+ if (!this.emailService.isConfigured() || await this.emailService.resolvesTemplate(DEFAULT_OTP_TEMPLATE, locale)) {
1606
+ return;
1607
+ }
1608
+ this.logger.warn(
1609
+ `[${TEMPLATE_WARNING_CODE}] The email template '${DEFAULT_OTP_TEMPLATE}' resolves for neither '${locale}' nor 'en', so the first generate() that delivers by email fails with TEMPLATE_NOT_FOUND. Register '${DEFAULT_OTP_TEMPLATE}' in your template renderer (DefaultTemplateRenderer takes it under 'otp_code::en'). Ignore this line if every generate() call passes emailTemplate, if you deliver manually, or if your renderer loads its templates after startup.`
1610
+ );
1611
+ } catch (error) {
1612
+ this.logger.warn(
1613
+ `[${TEMPLATE_WARNING_CODE}] Could not check whether the email template '${DEFAULT_OTP_TEMPLATE}' resolves (${describeError(error)}); if it does not, the first generate() that delivers by email fails with TEMPLATE_NOT_FOUND.`
1614
+ );
1615
+ }
1616
+ }
1525
1617
  /**
1526
1618
  * Counts one verification attempt against the recipient. Returns `undefined` when the storage
1527
1619
  * does not carry failures, and `null` when no code is live: a verification with no code guesses
@@ -2261,30 +2353,6 @@ var NOTIFICATION_PURPOSES = {
2261
2353
  PHONE_VERIFICATION: "phone_verification",
2262
2354
  MAGIC_LINK: "magic_link"
2263
2355
  };
2264
-
2265
- // src/server/constants/canonical-templates.ts
2266
- var CANONICAL_EMAIL_TEMPLATES = {
2267
- /** OTP for email verification — variables: `code`, `expiresInMinutes`, `purpose`, `name`, `appName`. */
2268
- OTP_CODE: "otp_code",
2269
- /** OTP for password reset (distinct copy; may carry a deep link) — variables: `code`, `expiresInMinutes`, `name`, `appName`, `verificationLink`. */
2270
- OTP_PASSWORD_RESET: "otp_password_reset",
2271
- /** OTP resend — same variables as the originating OTP template. */
2272
- OTP_RESENT: "otp_resent",
2273
- /** Welcome after email verification — variables: `name`, `appName`, `appUrl`. */
2274
- WELCOME: "welcome",
2275
- /** Password reset success — variables: `name`, `appName`, `supportEmail`. */
2276
- PASSWORD_RESET_SUCCESS: "password_reset_success",
2277
- /** Trial ending soon — variables: `name`, `appName`, `trialPlanName`, `daysLeft`, `appUrl`. */
2278
- TRIAL_EXPIRING: "trial_expiring",
2279
- /** Trial ended — variables: `name`, `appName`, `trialPlanName`, `durationDays`, `appUrl`. */
2280
- TRIAL_EXPIRED: "trial_expired",
2281
- /** New device login — variables: `device`, `ip`, `timestamp`, `name`, `appName`. */
2282
- NEW_LOGIN_ALERT: "new_login_alert",
2283
- /** MFA enabled — variables: `name`, `appName`. */
2284
- MFA_ENABLED: "mfa_enabled",
2285
- /** MFA disabled — variables: `name`, `appName`. */
2286
- MFA_DISABLED: "mfa_disabled"
2287
- };
2288
2356
  function maskEmail(address) {
2289
2357
  const at = address.lastIndexOf("@");
2290
2358
  if (at <= 0) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-notification",
3
- "version": "1.4.4",
3
+ "version": "1.4.5",
4
4
  "description": "Multi-channel notification library for NestJS — email, OTP, SMS, push — with pluggable providers and storage, multi-tenant by design, zero runtime dependencies.",
5
5
  "author": "Bymax One <support@bymax.one>",
6
6
  "license": "MIT",