@bymax-one/nest-notification 1.4.2 → 1.4.4

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,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.4.4] - 2026-11-01
11
+
12
+ Documentation only: `dist/` is byte-identical to 1.4.3.
13
+
14
+ ### Fixed
15
+
16
+ - **The development Quick Start now runs.** Step 2 registered `NoOpEmailProvider` and
17
+ `InMemoryOtpStorage` but no template renderer, and the OTP email is rendered from the `otp_code`
18
+ template, which the default renderer does not ship. The module booted, and the first
19
+ `generate()` threw `TEMPLATE_NOT_FOUND`. Step 2 now registers a `DefaultTemplateRenderer` with
20
+ the same `otp_code::en` template as step 3, and says why it is needed.
21
+
22
+ ### Tests
23
+
24
+ - The README development Quick Start is executed as written: the module and the service are
25
+ compiled from the README text and run against a Nest testing graph, with a stand-in email
26
+ provider. A second case fails if the `otp_code::en` template in steps 2 and 3 drifts apart.
27
+
28
+ ## [1.4.3] - 2026-11-01
29
+
30
+ ### ⚠️ Apply before upgrading
31
+
32
+ - **The address the OTP email is delivered to is now trimmed.** A caller that passed a recipient
33
+ with surrounding whitespace used to have the provider receive it as typed; the provider now
34
+ receives it without the whitespace, with its case unchanged. A test that asserts the `to` of
35
+ the delivered message against an untrimmed fixture has to expect the trimmed value. The OTP
36
+ state key is unchanged, so no live code or cooldown is lost.
37
+
38
+ ### Fixed
39
+
40
+ - **The OTP email goes to the trimmed address.** The scope key was already trimmed and folded, but
41
+ the provider still received the address as typed, so `" Jane.Doe@Example.COM "` reached it with
42
+ its surrounding spaces. Delivery now trims the address and keeps its case (RFC 5321 §2.4); the
43
+ key is unchanged.
44
+ - **A thrown value is described without throwing, and by shape.** A caught value was turned
45
+ into text with `error instanceof Error ? error.message : String(error)`. That throws on a value
46
+ with no prototype or a hostile `toString`, and it printed `[object Object]` (or `Error: …`) for
47
+ an error from another realm and for a plain `{ message }` object, which many SDKs reject with.
48
+ They now read a string `message`, fall back to `String()` inside a `try`, and finally to a fixed
49
+ phrase. Redaction is applied exactly where it was.
50
+
10
51
  ## [1.4.2] - 2026-10-31
11
52
 
12
53
  ### Security
@@ -941,7 +982,9 @@ rejected at startup rather than failing on the first send.
941
982
 
942
983
  [1.0.4]: https://github.com/bymaxone/nest-notification/compare/v1.0.3...v1.0.4
943
984
  [1.0.3]: https://github.com/bymaxone/nest-notification/compare/v1.0.2...v1.0.3
944
- [Unreleased]: https://github.com/bymaxone/nest-notification/compare/v1.4.2...HEAD
985
+ [Unreleased]: https://github.com/bymaxone/nest-notification/compare/v1.4.4...HEAD
986
+ [1.4.4]: https://github.com/bymaxone/nest-notification/compare/v1.4.3...v1.4.4
987
+ [1.4.3]: https://github.com/bymaxone/nest-notification/compare/v1.4.2...v1.4.3
945
988
  [1.4.2]: https://github.com/bymaxone/nest-notification/compare/v1.4.1...v1.4.2
946
989
  [1.4.1]: https://github.com/bymaxone/nest-notification/compare/v1.4.0...v1.4.1
947
990
  [1.4.0]: https://github.com/bymaxone/nest-notification/compare/v1.3.1...v1.4.0
package/README.md CHANGED
@@ -151,7 +151,8 @@ import { Module } from '@nestjs/common'
151
151
  import {
152
152
  BymaxNotificationModule,
153
153
  NoOpEmailProvider,
154
- InMemoryOtpStorage
154
+ InMemoryOtpStorage,
155
+ DefaultTemplateRenderer
155
156
  } from '@bymax-one/nest-notification'
156
157
 
157
158
  @Module({
@@ -159,7 +160,16 @@ import {
159
160
  BymaxNotificationModule.forRoot({
160
161
  email: {
161
162
  provider: new NoOpEmailProvider(),
162
- defaultFrom: 'no-reply@dev.local'
163
+ defaultFrom: 'no-reply@dev.local',
164
+ templateRenderer: new DefaultTemplateRenderer({
165
+ templates: {
166
+ 'otp_code::en': {
167
+ subject: 'Your Acme verification code',
168
+ html: '<p>Your code is <strong>{{code}}</strong>. It expires in {{expiresInMinutes}} minutes.</p>',
169
+ text: 'Your code is {{code}}. It expires in {{expiresInMinutes}} minutes.'
170
+ }
171
+ }
172
+ })
163
173
  },
164
174
  otp: {
165
175
  storage: new InMemoryOtpStorage(),
@@ -174,6 +184,8 @@ import {
174
184
  export class AppModule {}
175
185
  ```
176
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`.
188
+
177
189
  Inject `OtpService` anywhere and the two-step flow is complete:
178
190
 
179
191
  ```typescript
@@ -305,6 +305,17 @@ var NOTIFICATION_ERROR_DEFINITION_MAP = new Map(
305
305
  Object.entries(NOTIFICATION_ERROR_DEFINITIONS)
306
306
  );
307
307
 
308
+ // src/server/utils/describe-error.ts
309
+ var UNPRINTABLE_ERROR = "unprintable error";
310
+ function describeError(reason, fallback = UNPRINTABLE_ERROR) {
311
+ try {
312
+ const message = reason?.message;
313
+ return typeof message === "string" ? message : String(reason);
314
+ } catch {
315
+ return fallback;
316
+ }
317
+ }
318
+
308
319
  // src/server/errors/notification-exception.ts
309
320
  var FALLBACK_DEFINITION = {
310
321
  code: "notification.unknown_error",
@@ -335,7 +346,7 @@ function copyLogSafeCause(cause, depth) {
335
346
  }
336
347
  return safe;
337
348
  }
338
- return typeof cause === "object" && cause !== null ? String(cause) : cause;
349
+ return typeof cause === "object" && cause !== null ? describeError(cause, UNREADABLE_CAUSE_MESSAGE) : cause;
339
350
  }
340
351
  var NotificationException = class extends common.HttpException {
341
352
  /**
@@ -663,12 +674,8 @@ function coerceRedacted(value, values) {
663
674
  }
664
675
  }
665
676
  function readRedactedMessage(error, values) {
666
- try {
667
- const message = error instanceof Error ? error.message : String(error);
668
- return values ? redactValues(message, values) : message;
669
- } catch {
670
- return REDACTED_VALUE;
671
- }
677
+ const message = describeError(error, REDACTED_VALUE);
678
+ return values ? redactValues(message, values) : message;
672
679
  }
673
680
  function collectErrorChainText(error) {
674
681
  return walkChain(error, true);
@@ -1572,7 +1579,7 @@ exports.OtpService = class OtpService {
1572
1579
  const expiresInMinutes = Math.ceil(cfg.ttlSeconds / SECONDS_PER_MINUTE2);
1573
1580
  return {
1574
1581
  tenantId: input.tenantId,
1575
- to: input.recipient,
1582
+ to: input.recipient.trim(),
1576
1583
  template: input.emailTemplate ?? DEFAULT_OTP_TEMPLATE,
1577
1584
  data: { ...input.emailData, code, expiresInMinutes, purpose: input.purpose },
1578
1585
  // The provider receives the code inside the rendered body and may echo it
@@ -1615,8 +1622,8 @@ exports.OtpService = class OtpService {
1615
1622
  * Returns the input with its recipient replaced by the value the OTP state is keyed on.
1616
1623
  *
1617
1624
  * Every storage call and audit entry takes the result, so two spellings of one mailbox
1618
- * share a cooldown and an attempt counter. Delivery takes the original input: the
1619
- * message is addressed exactly as the caller wrote it.
1625
+ * share a cooldown and an attempt counter. Delivery takes the original input, trimmed:
1626
+ * the message keeps the caller's case but never its surrounding whitespace.
1620
1627
  */
1621
1628
  keyed(input) {
1622
1629
  return { ...input, recipient: normalizeRecipient(input.recipient) };
@@ -2103,7 +2110,7 @@ function instantiate(valueOrClass) {
2103
2110
  var INTERCEPTOR_NAME = "NotificationAuditInterceptor";
2104
2111
  var INTERCEPTOR_PROVIDER_NAME = "__interceptor__";
2105
2112
  function toErrorMessage(error) {
2106
- return error instanceof Error ? error.message : String(error);
2113
+ return describeError(error);
2107
2114
  }
2108
2115
  exports.NotificationAuditInterceptor = class NotificationAuditInterceptor {
2109
2116
  /**
@@ -2337,7 +2344,7 @@ async function loadOptionalPeer(moduleName) {
2337
2344
  { cause: error }
2338
2345
  );
2339
2346
  }
2340
- const reason = error instanceof Error ? error.message : String(error);
2347
+ const reason = describeError(error);
2341
2348
  throw new Error(`Failed to load \`${moduleName}\`: ${reason}`, { cause: error });
2342
2349
  }
2343
2350
  }
@@ -2867,11 +2874,9 @@ exports.SmtpEmailProvider = class SmtpEmailProvider {
2867
2874
  * `Error` carrying the scrubbed message.
2868
2875
  */
2869
2876
  redactError(error) {
2870
- if (error instanceof Error) {
2871
- const message = this.redact(error.message);
2872
- return message === error.message ? error : new Error(message);
2873
- }
2874
- return new Error(this.redact(String(error)));
2877
+ const text = describeError(error);
2878
+ const message = this.redact(text);
2879
+ return error instanceof Error && message === text && text !== UNPRINTABLE_ERROR ? error : new Error(message);
2875
2880
  }
2876
2881
  /**
2877
2882
  * Resolves the transport configuration, applying defaults and validating that the
@@ -1176,8 +1176,8 @@ declare class OtpService implements OnModuleInit {
1176
1176
  * Returns the input with its recipient replaced by the value the OTP state is keyed on.
1177
1177
  *
1178
1178
  * Every storage call and audit entry takes the result, so two spellings of one mailbox
1179
- * share a cooldown and an attempt counter. Delivery takes the original input: the
1180
- * message is addressed exactly as the caller wrote it.
1179
+ * share a cooldown and an attempt counter. Delivery takes the original input, trimmed:
1180
+ * the message keeps the caller's case but never its surrounding whitespace.
1181
1181
  */
1182
1182
  private keyed;
1183
1183
  /**
@@ -1176,8 +1176,8 @@ declare class OtpService implements OnModuleInit {
1176
1176
  * Returns the input with its recipient replaced by the value the OTP state is keyed on.
1177
1177
  *
1178
1178
  * Every storage call and audit entry takes the result, so two spellings of one mailbox
1179
- * share a cooldown and an attempt counter. Delivery takes the original input: the
1180
- * message is addressed exactly as the caller wrote it.
1179
+ * share a cooldown and an attempt counter. Delivery takes the original input, trimmed:
1180
+ * the message keeps the caller's case but never its surrounding whitespace.
1181
1181
  */
1182
1182
  private keyed;
1183
1183
  /**
@@ -303,6 +303,17 @@ var NOTIFICATION_ERROR_DEFINITION_MAP = new Map(
303
303
  Object.entries(NOTIFICATION_ERROR_DEFINITIONS)
304
304
  );
305
305
 
306
+ // src/server/utils/describe-error.ts
307
+ var UNPRINTABLE_ERROR = "unprintable error";
308
+ function describeError(reason, fallback = UNPRINTABLE_ERROR) {
309
+ try {
310
+ const message = reason?.message;
311
+ return typeof message === "string" ? message : String(reason);
312
+ } catch {
313
+ return fallback;
314
+ }
315
+ }
316
+
306
317
  // src/server/errors/notification-exception.ts
307
318
  var FALLBACK_DEFINITION = {
308
319
  code: "notification.unknown_error",
@@ -333,7 +344,7 @@ function copyLogSafeCause(cause, depth) {
333
344
  }
334
345
  return safe;
335
346
  }
336
- return typeof cause === "object" && cause !== null ? String(cause) : cause;
347
+ return typeof cause === "object" && cause !== null ? describeError(cause, UNREADABLE_CAUSE_MESSAGE) : cause;
337
348
  }
338
349
  var NotificationException = class extends HttpException {
339
350
  /**
@@ -661,12 +672,8 @@ function coerceRedacted(value, values) {
661
672
  }
662
673
  }
663
674
  function readRedactedMessage(error, values) {
664
- try {
665
- const message = error instanceof Error ? error.message : String(error);
666
- return values ? redactValues(message, values) : message;
667
- } catch {
668
- return REDACTED_VALUE;
669
- }
675
+ const message = describeError(error, REDACTED_VALUE);
676
+ return values ? redactValues(message, values) : message;
670
677
  }
671
678
  function collectErrorChainText(error) {
672
679
  return walkChain(error, true);
@@ -1570,7 +1577,7 @@ var OtpService = class {
1570
1577
  const expiresInMinutes = Math.ceil(cfg.ttlSeconds / SECONDS_PER_MINUTE2);
1571
1578
  return {
1572
1579
  tenantId: input.tenantId,
1573
- to: input.recipient,
1580
+ to: input.recipient.trim(),
1574
1581
  template: input.emailTemplate ?? DEFAULT_OTP_TEMPLATE,
1575
1582
  data: { ...input.emailData, code, expiresInMinutes, purpose: input.purpose },
1576
1583
  // The provider receives the code inside the rendered body and may echo it
@@ -1613,8 +1620,8 @@ var OtpService = class {
1613
1620
  * Returns the input with its recipient replaced by the value the OTP state is keyed on.
1614
1621
  *
1615
1622
  * Every storage call and audit entry takes the result, so two spellings of one mailbox
1616
- * share a cooldown and an attempt counter. Delivery takes the original input: the
1617
- * message is addressed exactly as the caller wrote it.
1623
+ * share a cooldown and an attempt counter. Delivery takes the original input, trimmed:
1624
+ * the message keeps the caller's case but never its surrounding whitespace.
1618
1625
  */
1619
1626
  keyed(input) {
1620
1627
  return { ...input, recipient: normalizeRecipient(input.recipient) };
@@ -2101,7 +2108,7 @@ function instantiate(valueOrClass) {
2101
2108
  var INTERCEPTOR_NAME = "NotificationAuditInterceptor";
2102
2109
  var INTERCEPTOR_PROVIDER_NAME = "__interceptor__";
2103
2110
  function toErrorMessage(error) {
2104
- return error instanceof Error ? error.message : String(error);
2111
+ return describeError(error);
2105
2112
  }
2106
2113
  var NotificationAuditInterceptor = class {
2107
2114
  /**
@@ -2335,7 +2342,7 @@ async function loadOptionalPeer(moduleName) {
2335
2342
  { cause: error }
2336
2343
  );
2337
2344
  }
2338
- const reason = error instanceof Error ? error.message : String(error);
2345
+ const reason = describeError(error);
2339
2346
  throw new Error(`Failed to load \`${moduleName}\`: ${reason}`, { cause: error });
2340
2347
  }
2341
2348
  }
@@ -2865,11 +2872,9 @@ var SmtpEmailProvider = class {
2865
2872
  * `Error` carrying the scrubbed message.
2866
2873
  */
2867
2874
  redactError(error) {
2868
- if (error instanceof Error) {
2869
- const message = this.redact(error.message);
2870
- return message === error.message ? error : new Error(message);
2871
- }
2872
- return new Error(this.redact(String(error)));
2875
+ const text = describeError(error);
2876
+ const message = this.redact(text);
2877
+ return error instanceof Error && message === text && text !== UNPRINTABLE_ERROR ? error : new Error(message);
2873
2878
  }
2874
2879
  /**
2875
2880
  * Resolves the transport configuration, applying defaults and validating that the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-notification",
3
- "version": "1.4.2",
3
+ "version": "1.4.4",
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",