@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 +23 -1
- package/README.md +27 -27
- package/dist/server/index.cjs +97 -29
- package/dist/server/index.d.cts +3 -2
- package/dist/server/index.d.ts +3 -2
- package/dist/server/index.mjs +97 -29
- package/package.json +1 -1
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.
|
|
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
|
|
package/dist/server/index.cjs
CHANGED
|
@@ -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
|
-
/**
|
|
1095
|
-
|
|
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
|
-
|
|
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 =
|
|
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
|
-
|
|
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) {
|
package/dist/server/index.d.cts
CHANGED
|
@@ -1133,8 +1133,9 @@ declare class OtpService implements OnModuleInit {
|
|
|
1133
1133
|
*/
|
|
1134
1134
|
private failedOutgoing;
|
|
1135
1135
|
/**
|
|
1136
|
-
*
|
|
1137
|
-
*
|
|
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
|
/**
|
package/dist/server/index.d.ts
CHANGED
|
@@ -1133,8 +1133,9 @@ declare class OtpService implements OnModuleInit {
|
|
|
1133
1133
|
*/
|
|
1134
1134
|
private failedOutgoing;
|
|
1135
1135
|
/**
|
|
1136
|
-
*
|
|
1137
|
-
*
|
|
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
|
/**
|
package/dist/server/index.mjs
CHANGED
|
@@ -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
|
-
/**
|
|
1093
|
-
|
|
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
|
-
|
|
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 =
|
|
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
|
-
|
|
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.
|
|
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",
|