@bymax-one/nest-notification 1.4.0 → 1.4.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.
@@ -1,5 +1,202 @@
1
1
  import { randomUUID } from 'crypto';
2
2
 
3
+ // src/testing/otp-storage-contract.ts
4
+
5
+ // src/testing/otp-storage-contract.shared.ts
6
+ var RACERS = 25;
7
+ function check(condition, message) {
8
+ if (!condition) {
9
+ throw new Error(`IOtpStorage contract violated: ${message}`);
10
+ }
11
+ }
12
+ function wait(ms) {
13
+ return new Promise((resolve) => {
14
+ setTimeout(resolve, ms);
15
+ });
16
+ }
17
+
18
+ // src/testing/otp-storage-contract.failures.ts
19
+ function hasFailureMethods(storage) {
20
+ return storage.getFailures !== void 0 && storage.recordFailure !== void 0 && storage.clearFailures !== void 0;
21
+ }
22
+ var FAILURE_TTL_SECONDS = 60;
23
+ function failureCountCase({ scope, withStorage }) {
24
+ return {
25
+ name: "counts failures per scope (optional: getFailures, recordFailure, clearFailures)",
26
+ run: () => withStorage(async (storage) => {
27
+ if (!hasFailureMethods(storage)) {
28
+ return;
29
+ }
30
+ const counts = [
31
+ await storage.recordFailure(
32
+ scope.tenantA,
33
+ scope.recipient,
34
+ scope.purpose,
35
+ FAILURE_TTL_SECONDS
36
+ ),
37
+ await storage.recordFailure(
38
+ scope.tenantA,
39
+ scope.recipient,
40
+ scope.purpose,
41
+ FAILURE_TTL_SECONDS
42
+ ),
43
+ await storage.recordFailure(
44
+ scope.tenantA,
45
+ scope.recipient,
46
+ scope.purpose,
47
+ FAILURE_TTL_SECONDS
48
+ )
49
+ ];
50
+ const read = await storage.getFailures(scope.tenantA, scope.recipient, scope.purpose);
51
+ const none = await storage.getFailures(scope.tenantA, scope.absentRecipient, scope.purpose);
52
+ check(
53
+ counts.join() === "1,2,3",
54
+ `recordFailure returned ${counts.join()} for three failures instead of 1,2,3`
55
+ );
56
+ check(read === 3, `getFailures returned ${String(read)} after three failures`);
57
+ check(none === 0, "getFailures returned a count for a scope that never failed");
58
+ })
59
+ };
60
+ }
61
+ function failureScopeCase({ scope, withStorage }) {
62
+ return {
63
+ name: "scopes the failure counter by tenant, recipient and purpose",
64
+ run: () => withStorage(async (storage) => {
65
+ if (!hasFailureMethods(storage)) {
66
+ return;
67
+ }
68
+ await storage.recordFailure(
69
+ scope.tenantA,
70
+ scope.recipient,
71
+ scope.purpose,
72
+ FAILURE_TTL_SECONDS
73
+ );
74
+ const otherTenant = await storage.getFailures(scope.tenantB, scope.recipient, scope.purpose);
75
+ const otherRecipient = await storage.getFailures(
76
+ scope.tenantA,
77
+ scope.absentRecipient,
78
+ scope.purpose
79
+ );
80
+ const otherPurpose = await storage.getFailures(
81
+ scope.tenantA,
82
+ scope.recipient,
83
+ scope.otherPurpose
84
+ );
85
+ check(otherTenant === 0, "a failure recorded for one tenant counted against another");
86
+ check(otherRecipient === 0, "a failure recorded for one recipient counted against another");
87
+ check(otherPurpose === 0, "a failure recorded for one purpose counted against another");
88
+ })
89
+ };
90
+ }
91
+ function failureBoundaryCase({
92
+ scope,
93
+ withStorage
94
+ }) {
95
+ return {
96
+ name: "keeps the tenant and recipient boundary when composing a failure-counter key",
97
+ run: () => withStorage(async (storage) => {
98
+ if (!hasFailureMethods(storage)) {
99
+ return;
100
+ }
101
+ for (const { left, right } of scope.boundaryShifts) {
102
+ await storage.recordFailure(left[0], left[1], scope.purpose, FAILURE_TTL_SECONDS);
103
+ const bled = await storage.getFailures(right[0], right[1], scope.purpose);
104
+ check(
105
+ bled === 0,
106
+ "a failure recorded for one tenant counted against another whose id and recipient differ only in where the boundary falls \u2014 the counter key concatenates the two fields without encoding the split, so one tenant can lock another out. The entry key, the cooldown key and the counter key are composed separately and all need this"
107
+ );
108
+ }
109
+ })
110
+ };
111
+ }
112
+ function failureClearCase({ scope, withStorage }) {
113
+ return {
114
+ name: "clearFailures removes only its own counter and is idempotent",
115
+ run: () => withStorage(async (storage) => {
116
+ if (!hasFailureMethods(storage)) {
117
+ return;
118
+ }
119
+ await storage.recordFailure(
120
+ scope.tenantA,
121
+ scope.recipient,
122
+ scope.purpose,
123
+ FAILURE_TTL_SECONDS
124
+ );
125
+ await storage.recordFailure(
126
+ scope.tenantA,
127
+ scope.absentRecipient,
128
+ scope.purpose,
129
+ FAILURE_TTL_SECONDS
130
+ );
131
+ await storage.clearFailures(scope.tenantA, scope.recipient, scope.purpose);
132
+ await storage.clearFailures(scope.tenantA, scope.recipient, scope.purpose);
133
+ check(
134
+ await storage.getFailures(scope.tenantA, scope.recipient, scope.purpose) === 0,
135
+ "getFailures still counted failures after clearFailures"
136
+ );
137
+ check(
138
+ await storage.getFailures(scope.tenantA, scope.absentRecipient, scope.purpose) === 1,
139
+ "clearFailures removed the counter of another recipient"
140
+ );
141
+ })
142
+ };
143
+ }
144
+ function failureTtlCase({
145
+ scope,
146
+ withStorage,
147
+ expiryWaitMs
148
+ }) {
149
+ return {
150
+ name: "a failure counter lapses after its lifetime",
151
+ run: () => withStorage(async (storage) => {
152
+ if (!hasFailureMethods(storage)) {
153
+ return;
154
+ }
155
+ await storage.recordFailure(scope.tenantA, scope.recipient, scope.purpose, 1e-3);
156
+ await wait(expiryWaitMs);
157
+ check(
158
+ await storage.getFailures(scope.tenantA, scope.recipient, scope.purpose) === 0,
159
+ "getFailures counted a failure whose lifetime had passed \u2014 a counter that never lapses locks a recipient out for good"
160
+ );
161
+ check(
162
+ await storage.recordFailure(
163
+ scope.tenantA,
164
+ scope.recipient,
165
+ scope.purpose,
166
+ FAILURE_TTL_SECONDS
167
+ ) === 1,
168
+ "a lapsed counter did not start again from one"
169
+ );
170
+ })
171
+ };
172
+ }
173
+ function failureAtomicCase({ scope, withStorage }) {
174
+ return {
175
+ name: "recordFailure is ATOMIC under concurrency",
176
+ run: () => withStorage(async (storage) => {
177
+ if (!hasFailureMethods(storage)) {
178
+ return;
179
+ }
180
+ const counts = await Promise.all(
181
+ Array.from(
182
+ { length: RACERS },
183
+ () => storage.recordFailure(
184
+ scope.tenantA,
185
+ scope.recipient,
186
+ scope.purpose,
187
+ FAILURE_TTL_SECONDS
188
+ )
189
+ )
190
+ );
191
+ const distinct = new Set(counts).size;
192
+ check(
193
+ distinct === RACERS,
194
+ `${String(RACERS)} concurrent failures produced only ${String(distinct)} distinct counts \u2014 the read and the write are not one step, so concurrent wrong guesses are lost and the attempt ceiling can be exceeded`
195
+ );
196
+ })
197
+ };
198
+ }
199
+
3
200
  // src/testing/otp-storage-contract.ts
4
201
  var KEY_PREFIX = "nest_notification_contract";
5
202
  var TENANT_A = "tenant_a";
@@ -20,26 +217,18 @@ function makeScope() {
20
217
  purpose: `${KEY_PREFIX}_${run}_${PURPOSE_MAIN}`,
21
218
  otherPurpose: `${KEY_PREFIX}_${run}_${PURPOSE_OTHER}`,
22
219
  // Same characters, two different (tenant, recipient) splits. A key built by
23
- // joining the raw values around `:` maps both onto one string.
24
- shiftedLeft: [`${KEY_PREFIX}_${run}_x:y`, "z"],
25
- shiftedRight: [`${KEY_PREFIX}_${run}_x`, "y:z"]
220
+ // joining the raw values around `:` maps both onto one string, and so does one
221
+ // built around `::`, which the single-colon pair alone does not expose.
222
+ boundaryShifts: [
223
+ { left: [`${KEY_PREFIX}_${run}_x:y`, "z"], right: [`${KEY_PREFIX}_${run}_x`, "y:z"] },
224
+ { left: [`${KEY_PREFIX}_${run}_x::y`, "z"], right: [`${KEY_PREFIX}_${run}_x`, "y::z"] }
225
+ ]
26
226
  };
27
227
  }
28
228
  var DEFAULT_EXPIRY_WAIT_MS = 1500;
29
- var RACERS = 25;
30
229
  function makeEntry(ttlMs, maxAttempts = 3, code = ANY_CODE) {
31
230
  return { code, expiresAt: Date.now() + ttlMs, attempts: 0, maxAttempts };
32
231
  }
33
- function check(condition, message) {
34
- if (!condition) {
35
- throw new Error(`IOtpStorage contract violated: ${message}`);
36
- }
37
- }
38
- function wait(ms) {
39
- return new Promise((resolve) => {
40
- setTimeout(resolve, ms);
41
- });
42
- }
43
232
  async function cleanUp(storage, scope) {
44
233
  const keys = [
45
234
  [scope.tenantA, scope.purpose],
@@ -51,10 +240,13 @@ async function cleanUp(storage, scope) {
51
240
  await storage.clearCooldown(tenant, scope.recipient, purpose);
52
241
  await storage.delete(tenant, scope.absentRecipient, purpose);
53
242
  await storage.clearCooldown(tenant, scope.absentRecipient, purpose);
243
+ await storage.clearFailures?.(tenant, scope.recipient, purpose);
244
+ await storage.clearFailures?.(tenant, scope.absentRecipient, purpose);
54
245
  }
55
- for (const [tenant, recipient] of [scope.shiftedLeft, scope.shiftedRight]) {
246
+ for (const [tenant, recipient] of scope.boundaryShifts.flatMap((s) => [s.left, s.right])) {
56
247
  await storage.delete(tenant, recipient, scope.purpose);
57
248
  await storage.clearCooldown(tenant, recipient, scope.purpose);
249
+ await storage.clearFailures?.(tenant, recipient, scope.purpose);
58
250
  }
59
251
  }
60
252
  function roundTripCase({ scope, withStorage }) {
@@ -380,14 +572,14 @@ function keyBoundaryCase({ scope, withStorage }) {
380
572
  return {
381
573
  name: "keeps the tenant and recipient boundary when composing a key",
382
574
  run: () => withStorage(async (storage) => {
383
- const [leftTenant, leftRecipient] = scope.shiftedLeft;
384
- const [rightTenant, rightRecipient] = scope.shiftedRight;
385
- await storage.set(leftTenant, leftRecipient, scope.purpose, makeEntry(6e4));
386
- const bled = await storage.get(rightTenant, rightRecipient, scope.purpose);
387
- check(
388
- bled === null,
389
- "an entry written for one tenant was readable by another whose id and recipient differ only in where the boundary falls \u2014 the key concatenates the two fields without encoding the split, so one tenant can read and consume another OTP. Hash or length-prefix each field before joining; no digest strength repairs it"
390
- );
575
+ for (const { left, right } of scope.boundaryShifts) {
576
+ await storage.set(left[0], left[1], scope.purpose, makeEntry(6e4));
577
+ const bled = await storage.get(right[0], right[1], scope.purpose);
578
+ check(
579
+ bled === null,
580
+ "an entry written for one tenant was readable by another whose id and recipient differ only in where the boundary falls \u2014 the key concatenates the two fields without encoding the split, so one tenant can read and consume another OTP. Hash or length-prefix each field before joining; no digest strength repairs it"
581
+ );
582
+ }
391
583
  })
392
584
  };
393
585
  }
@@ -395,23 +587,18 @@ function cooldownKeyBoundaryCase({ scope, withStorage }) {
395
587
  return {
396
588
  name: "keeps the tenant and recipient boundary when composing a cooldown key",
397
589
  run: () => withStorage(async (storage) => {
398
- const [leftTenant, leftRecipient] = scope.shiftedLeft;
399
- const [rightTenant, rightRecipient] = scope.shiftedRight;
400
- const held = await storage.tryAcquireCooldown(leftTenant, leftRecipient, scope.purpose, 60);
401
- check(
402
- held,
403
- "the first cooldown could not be acquired, so this case proves nothing about boundary encoding \u2014 a case that cannot fail is decoration"
404
- );
405
- const other = await storage.tryAcquireCooldown(
406
- rightTenant,
407
- rightRecipient,
408
- scope.purpose,
409
- 60
410
- );
411
- check(
412
- other,
413
- "a cooldown held for one tenant blocked another whose id and recipient differ only in where the boundary falls \u2014 the cooldown key concatenates the two fields without encoding the split, so one tenant can suppress another resends. The entry key and the cooldown key are composed separately and both need this"
414
- );
590
+ for (const { left, right } of scope.boundaryShifts) {
591
+ const held = await storage.tryAcquireCooldown(left[0], left[1], scope.purpose, 60);
592
+ check(
593
+ held,
594
+ "the first cooldown could not be acquired, so this case proves nothing about boundary encoding \u2014 a case that cannot fail is decoration"
595
+ );
596
+ const other = await storage.tryAcquireCooldown(right[0], right[1], scope.purpose, 60);
597
+ check(
598
+ other,
599
+ "a cooldown held for one tenant blocked another whose id and recipient differ only in where the boundary falls \u2014 the cooldown key concatenates the two fields without encoding the split, so one tenant can suppress another resends. The entry key and the cooldown key are composed separately and both need this"
600
+ );
601
+ }
415
602
  })
416
603
  };
417
604
  }
@@ -436,7 +623,13 @@ var CASE_BUILDERS = [
436
623
  cooldownPurposeScopeCase,
437
624
  cooldownAtomicCase,
438
625
  keyBoundaryCase,
439
- cooldownKeyBoundaryCase
626
+ cooldownKeyBoundaryCase,
627
+ failureCountCase,
628
+ failureScopeCase,
629
+ failureBoundaryCase,
630
+ failureClearCase,
631
+ failureTtlCase,
632
+ failureAtomicCase
440
633
  ];
441
634
  function otpStorageContract(factory, options = {}) {
442
635
  const scope = makeScope();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-notification",
3
- "version": "1.4.0",
3
+ "version": "1.4.2",
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",
@@ -101,6 +101,7 @@
101
101
  "test:cov": "jest --coverage",
102
102
  "test:cov:all": "jest --config jest.coverage.config.ts --coverage",
103
103
  "test:e2e": "jest --config jest.e2e.config.ts --runInBand",
104
+ "test:e2e:redis": "jest --config jest.redis-e2e.config.ts --runInBand",
104
105
  "test:types": "tsc --noEmit -p tsconfig.typetest.json",
105
106
  "test:watch": "jest --watch",
106
107
  "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.server.json"
@@ -113,21 +114,7 @@
113
114
  "rxjs": "^7.8.0",
114
115
  "ioredis": "^6.0.0",
115
116
  "resend": "^4.0.0 || ^5.0.0 || ^6.0.0",
116
- "@sendgrid/mail": "^8.0.0",
117
- "@aws-sdk/client-ses": "^3.0.0",
118
- "@aws-sdk/client-sns": "^3.0.0",
119
- "mailgun.js": "^11.0.0 || ^12.0.0 || ^13.0.0",
120
- "nodemailer": "^9.0.1",
121
- "twilio": "^5.0.0 || ^6.0.0",
122
- "firebase-admin": "^13.0.0 || ^14.0.0",
123
- "@aws-sdk/client-dynamodb": "^3.0.0",
124
- "handlebars": "^4.7.9",
125
- "@react-email/render": "^1.0.0 || ^2.0.0",
126
- "mjml": "^5.0.0",
127
- "class-validator": "^0.14.0 || ^0.15.0",
128
- "class-transformer": "^0.5.0",
129
- "express": "^5.0.0",
130
- "@types/express": "^5.0.0",
117
+ "nodemailer": "^10.1.4",
131
118
  "react": "^19.0.0"
132
119
  },
133
120
  "peerDependenciesMeta": {
@@ -137,51 +124,9 @@
137
124
  "resend": {
138
125
  "optional": true
139
126
  },
140
- "@sendgrid/mail": {
141
- "optional": true
142
- },
143
- "@aws-sdk/client-ses": {
144
- "optional": true
145
- },
146
- "@aws-sdk/client-sns": {
147
- "optional": true
148
- },
149
- "mailgun.js": {
150
- "optional": true
151
- },
152
127
  "nodemailer": {
153
128
  "optional": true
154
129
  },
155
- "twilio": {
156
- "optional": true
157
- },
158
- "firebase-admin": {
159
- "optional": true
160
- },
161
- "@aws-sdk/client-dynamodb": {
162
- "optional": true
163
- },
164
- "handlebars": {
165
- "optional": true
166
- },
167
- "@react-email/render": {
168
- "optional": true
169
- },
170
- "mjml": {
171
- "optional": true
172
- },
173
- "class-validator": {
174
- "optional": true
175
- },
176
- "class-transformer": {
177
- "optional": true
178
- },
179
- "express": {
180
- "optional": true
181
- },
182
- "@types/express": {
183
- "optional": true
184
- },
185
130
  "react": {
186
131
  "optional": true
187
132
  }
@@ -212,6 +157,7 @@
212
157
  "eslint-plugin-security": "^4.0.0",
213
158
  "globals": "^17.6.0",
214
159
  "husky": "^9.1.7",
160
+ "ioredis": "^6.0.0",
215
161
  "jest": "^30.4.2",
216
162
  "jest-environment-jsdom": "^30",
217
163
  "lint-staged": "^17.2.0",
@@ -220,9 +166,10 @@
220
166
  "react-dom": "^19",
221
167
  "reflect-metadata": "^0.2.2",
222
168
  "rxjs": "^7.8.0",
169
+ "testcontainers": "^12.2.1",
223
170
  "ts-jest": "^29.4.11",
224
171
  "ts-node": "^10.9.2",
225
- "tsup": "^8.5.1",
172
+ "tsup": "^9.0.0",
226
173
  "typescript": "^5.9.3"
227
174
  },
228
175
  "keywords": [