notifkit 0.1.14 → 0.1.16

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.
Files changed (89) hide show
  1. package/dashboard/dist/assets/index-C-DJYu0_.css +1 -0
  2. package/dashboard/dist/assets/index-CzFZcEon.js +318 -0
  3. package/dashboard/dist/index.html +2 -2
  4. package/dist/{bootstrap-m107TukN.mjs → bootstrap-BMDRPjgp.mjs} +1 -1
  5. package/dist/{bulk-xAd_biYV.mjs → bulk-CJ5QXiPa.mjs} +1 -1
  6. package/dist/index.d.mts +71 -27
  7. package/dist/index.mjs +2 -2
  8. package/dist/{main-CWIBUEc7.mjs → main-6_bXQBDH.mjs} +21 -41
  9. package/dist/{main-WkxXwP5q.mjs → main-8nP3qmCT.mjs} +29 -49
  10. package/dist/{main-HT5c6jyf.mjs → main-B82bsFoy.mjs} +183 -334
  11. package/dist/{main-C87TSAqM.mjs → main-CpaHF1Zw.mjs} +13 -15
  12. package/dist/{main-DRHL2bst.mjs → main-DULD8-th.mjs} +8 -6
  13. package/dist/{main-D_62f9fH.mjs → main-ZW5RaiOK.mjs} +77 -64
  14. package/dist/{main-5kVwbbnW.mjs → main-g1KEcXXp.mjs} +676 -582
  15. package/dist/{main-C0MjK1Au.mjs → main-mGIT8jv4.mjs} +4 -4
  16. package/dist/schedule-or-dispatch-Cd7GLfc3.mjs +52 -0
  17. package/dist/{src-DYqdD694.mjs → src-BE_EUpZ6.mjs} +93 -93
  18. package/package.json +1 -1
  19. package/scripts/create-admin.mjs +0 -0
  20. package/scripts/create-project.mjs +6 -2
  21. package/scripts/migrate.mjs +0 -0
  22. package/scripts/notifkit.mjs +0 -0
  23. package/src/client.ts +3 -3
  24. package/src/config/index.ts +1 -0
  25. package/src/contracts/common.ts +2 -0
  26. package/src/contracts/envelope.ts +1 -1
  27. package/src/contracts/events/notification-created.ts +2 -0
  28. package/src/contracts/events/notification-delivered.ts +1 -1
  29. package/src/contracts/events/notification-failed.ts +1 -1
  30. package/src/contracts/events/notification-requested.ts +3 -2
  31. package/src/contracts/helpers.ts +1 -2
  32. package/src/contracts/index.ts +1 -0
  33. package/src/contracts/registry.ts +1 -0
  34. package/src/contracts/sdk.ts +8 -37
  35. package/src/db/schema.ts +8 -13
  36. package/src/idempotency/index.ts +6 -8
  37. package/src/metrics/index.ts +2 -0
  38. package/src/rate-limiter/api-rate-limiter.ts +208 -0
  39. package/src/rate-limiter/index.ts +3 -411
  40. package/src/rate-limiter/project-settings-cache.ts +99 -0
  41. package/src/rate-limiter/user-throttle.ts +100 -0
  42. package/src/redis/index.ts +10 -3
  43. package/src/repositories/admin-user.ts +83 -0
  44. package/src/repositories/contact.ts +359 -0
  45. package/src/repositories/index.ts +9 -1416
  46. package/src/repositories/preference.ts +35 -0
  47. package/src/repositories/project.ts +110 -0
  48. package/src/repositories/segment.ts +16 -0
  49. package/src/repositories/template.ts +72 -0
  50. package/src/repositories/types.ts +49 -0
  51. package/src/repositories/user.ts +644 -0
  52. package/src/repositories/workflow.ts +64 -0
  53. package/src/services/ai/main.ts +29 -71
  54. package/src/services/api/admin-static.ts +4 -1
  55. package/src/services/api/handlers/auth.ts +109 -0
  56. package/src/services/api/handlers/campaigns.ts +191 -0
  57. package/src/services/api/handlers/events.ts +99 -0
  58. package/src/services/api/handlers/notifications.ts +356 -0
  59. package/src/services/api/handlers/projects.ts +116 -0
  60. package/src/services/api/handlers/shared.ts +262 -0
  61. package/src/services/api/handlers/suppressions.ts +95 -0
  62. package/src/services/api/handlers/system.ts +314 -0
  63. package/src/services/api/handlers/templates.ts +97 -0
  64. package/src/services/api/handlers/unsubscribe.ts +215 -0
  65. package/src/services/api/handlers/users.ts +262 -0
  66. package/src/services/api/handlers/workflows.ts +150 -0
  67. package/src/services/api/handlers.ts +25 -2190
  68. package/src/services/api/health.ts +133 -0
  69. package/src/services/api/http.ts +12 -0
  70. package/src/services/api/main.ts +32 -322
  71. package/src/services/api/router.ts +1 -1
  72. package/src/services/api/webhooks.ts +172 -0
  73. package/src/services/delivery/main.ts +256 -498
  74. package/src/services/engine/main.ts +31 -235
  75. package/src/services/engine/quiet-hours.ts +151 -0
  76. package/src/services/engine/schedule-or-dispatch.ts +104 -0
  77. package/src/services/enricher/main.ts +9 -21
  78. package/src/services/events/main.ts +2 -2
  79. package/src/services/scheduler/main.ts +16 -25
  80. package/src/services/workflow/duration.ts +24 -0
  81. package/src/services/workflow/main.ts +6 -164
  82. package/src/services/workflow/timers.ts +157 -0
  83. package/src/shared/events.ts +3 -2
  84. package/src/templates/render.ts +1 -0
  85. package/src/workers/index.ts +7 -4
  86. package/src/workflows/sdk.ts +1 -0
  87. package/dashboard/README.md +0 -29
  88. package/dashboard/dist/assets/index-ggpJKZqZ.js +0 -315
  89. package/dashboard/dist/assets/index-s-SXGIwv.css +0 -1
@@ -1,411 +1,3 @@
1
- import type { Redis } from "@/index.js";
2
- import { LRUCache } from "@/shared/index.js";
3
- import type { Logger } from "@/logger/index.js";
4
-
5
- import { randomUUID } from "crypto";
6
-
7
- export interface ThrottleResult {
8
- allowed: boolean;
9
- count: number;
10
- limit: number;
11
- }
12
-
13
- // ─── Per-project overrides ──────────────────────────────────────────────────
14
-
15
- /**
16
- * Throttle overrides stored on the project row. `null` on either field means
17
- * "no override" — fall back to the process-wide default.
18
- */
19
- export interface ProjectThrottleSettings {
20
- throttleLimit: number | null;
21
- throttleWindowHours: number | null;
22
- }
23
-
24
- const NO_OVERRIDES: ProjectThrottleSettings = {
25
- throttleLimit: null,
26
- throttleWindowHours: null,
27
- };
28
-
29
- export interface ProjectSettingsCacheOptions {
30
- maxSize?: number;
31
- ttlMs?: number;
32
- }
33
-
34
- /**
35
- * Caches per-project throttle overrides for the engine.
36
- *
37
- * The throttle check runs once per notification, so an uncached lookup here
38
- * would put a Postgres round trip on the hot path. Projects with no overrides
39
- * are cached as well — the common case must not cost a query per message.
40
- *
41
- * The TTL bounds staleness on its own; `invalidate()` exists so a settings
42
- * change published over pub/sub applies immediately rather than at expiry.
43
- */
44
- export class ProjectSettingsCache {
45
- private readonly cache: LRUCache<string, ProjectThrottleSettings>;
46
- /**
47
- * Lookups already on the wire, keyed by project.
48
- *
49
- * The cache only fills once a query has come back, so without this a cold
50
- * project at the start of a campaign puts one query per in-flight message on
51
- * Postgres before the first answer lands — exactly when the database is
52
- * busiest. Followers wait on the leader's promise instead.
53
- */
54
- private readonly inFlight = new Map<string, Promise<ProjectThrottleSettings>>();
55
-
56
- constructor(
57
- private readonly load: (projectId: string) => Promise<ProjectThrottleSettings | null>,
58
- { maxSize = 1000, ttlMs = 60_000 }: ProjectSettingsCacheOptions = {},
59
- ) {
60
- this.cache = new LRUCache<string, ProjectThrottleSettings>(maxSize, ttlMs);
61
- }
62
-
63
- /**
64
- * Throws whatever the loader throws. The caller decides whether a settings
65
- * lookup failure should drop the message or fall back to defaults.
66
- */
67
- async get(projectId: string): Promise<ProjectThrottleSettings> {
68
- const cached = this.cache.get(projectId);
69
- if (cached) return cached;
70
-
71
- const existing = this.inFlight.get(projectId);
72
- if (existing) return existing;
73
-
74
- // Assigned before any callback below can run, since `load` cannot settle
75
- // within this synchronous block.
76
- let pending!: Promise<ProjectThrottleSettings>;
77
- pending = this.load(projectId)
78
- .then((settings) => {
79
- const resolved = settings ?? NO_OVERRIDES;
80
- // Only cache while this is still the current lookup: an invalidate()
81
- // that landed while the query was on the wire means the answer in hand
82
- // already describes the old settings.
83
- if (this.inFlight.get(projectId) === pending) {
84
- this.cache.set(projectId, resolved);
85
- }
86
- return resolved;
87
- })
88
- .finally(() => {
89
- // Cleared on failure too, so one bad lookup does not pin every later
90
- // caller to the same rejection.
91
- if (this.inFlight.get(projectId) === pending) {
92
- this.inFlight.delete(projectId);
93
- }
94
- });
95
-
96
- this.inFlight.set(projectId, pending);
97
- return pending;
98
- }
99
-
100
- invalidate(projectId: string): void {
101
- this.cache.delete(projectId);
102
- // A lookup that started before the change would write a stale value on
103
- // arrival; dropping it here sends the next caller back to the database.
104
- this.inFlight.delete(projectId);
105
- }
106
-
107
- clear(): void {
108
- this.cache.clear();
109
- this.inFlight.clear();
110
- }
111
- }
112
-
113
- // ─── UserThrottle ──────────────────────────────────────────────────────────
114
- // True sliding window counter using Redis ZSET: max N sends per window per user.
115
-
116
- export interface UserThrottleOptions {
117
- redis: Redis;
118
- maxPerHour?: number;
119
- windowHours?: number;
120
- }
121
-
122
- export interface ThrottleCheckOptions {
123
- /** Per-project cap for this window. `0` blocks every non-critical send. */
124
- limit?: number | null;
125
- /** Per-project window length in hours. */
126
- windowHours?: number | null;
127
- /** Future send time. The window is evaluated at that instant, not at now. */
128
- scheduledAt?: string;
129
- /**
130
- * Stable id of the message being counted. A retry of the same message is
131
- * then counted once, not once per attempt. Random when omitted.
132
- */
133
- messageId?: string;
134
- }
135
-
136
- /** Reject stored values that would make the window meaningless. */
137
- function positiveOrNull(value: number | null | undefined): number | null {
138
- return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
139
- }
140
-
141
- /** A limit of 0 is a legitimate kill switch, so zero is allowed here. */
142
- function nonNegativeOrNull(value: number | null | undefined): number | null {
143
- return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
144
- }
145
-
146
- export class UserThrottle {
147
- private readonly redis: Redis;
148
- private readonly maxPerHour: number;
149
- private readonly windowHours: number;
150
-
151
- constructor({ redis, maxPerHour = 3, windowHours = 1 }: UserThrottleOptions) {
152
- this.redis = redis;
153
- this.maxPerHour = maxPerHour;
154
- this.windowHours = windowHours;
155
- }
156
-
157
- /**
158
- * @param projectId Tenant that owns `userId`. User ids are caller-supplied
159
- * external ids, so they collide across tenants and MUST be namespaced —
160
- * otherwise one tenant's traffic throttles another's.
161
- * @param options Per-project overrides. Values that are absent, null, or
162
- * nonsensical fall back to this instance's defaults.
163
- */
164
- async check(
165
- projectId: string,
166
- userId: string,
167
- priority?: string,
168
- options: ThrottleCheckOptions = {},
169
- ): Promise<ThrottleResult> {
170
- const limit = nonNegativeOrNull(options.limit) ?? this.maxPerHour;
171
- const windowHours = positiveOrNull(options.windowHours) ?? this.windowHours;
172
-
173
- if (priority === "critical") {
174
- return { allowed: true, count: 0, limit };
175
- }
176
-
177
- const windowMs = windowHours * 3600_000;
178
- const key = `throttle:${projectId}:user:${userId}`;
179
- const targetTime = options.scheduledAt ? new Date(options.scheduledAt).getTime() : Date.now();
180
- const windowStart = targetTime - windowMs;
181
- const memberId = options.messageId ?? randomUUID();
182
-
183
- // The key must outlive the window it is counting. For a future-dated send
184
- // that means surviving until targetTime plus one more window, so a task
185
- // scheduled for next week still counts against the right bucket.
186
- const windowSeconds = Math.ceil(windowMs / 1000);
187
- const ttlSeconds = Math.max(
188
- windowSeconds,
189
- Math.ceil((targetTime - Date.now()) / 1000) + windowSeconds,
190
- );
191
-
192
- const count = await this.redis.throttleUser(
193
- key,
194
- windowStart,
195
- limit,
196
- targetTime,
197
- memberId,
198
- ttlSeconds,
199
- Date.now() - windowMs,
200
- );
201
-
202
- return { allowed: count <= limit, count, limit };
203
- }
204
- }
205
-
206
- // ─── ApiRateLimiter (In-Memory Token Leasing) ──────────────────────────────
207
- // Leases token chunks from Redis sliding-window counters into local memory.
208
- // Eliminates per-request Redis network roundtrips on API ingress.
209
-
210
- export interface ApiRateLimiterOptions {
211
- redis: Redis;
212
- windowMs?: number;
213
- maxBatchSize?: number;
214
- logger?: Logger;
215
- /** Redis key namespace. Distinct limiters must not share one. */
216
- keyPrefix?: string;
217
- }
218
-
219
- /**
220
- * Computes dynamic token lease batch size based on RPM.
221
- * Targets ~5s of limit capacity so Redis is contacted at most ~12 times/min
222
- * regardless of instantaneous request rate. Bounded between 1 and maxBatchSize.
223
- */
224
- export function calculateTokenBatchSize(limitRpm: number, maxBatchSize = 500): number {
225
- if (limitRpm <= 0) return 0;
226
- if (limitRpm <= 10) return 1;
227
- if (limitRpm <= 60) return 5;
228
- const perSecond = limitRpm / 60;
229
- // 5 s window = perSecond * 5; at least 10 to absorb jitter.
230
- return Math.min(Math.max(Math.ceil(perSecond * 5), 10), maxBatchSize);
231
- }
232
-
233
- interface ProjectTokenLeaseState {
234
- bucketIndex: number;
235
- tokens: number;
236
- batchSize: number;
237
- inFlightLease: Promise<number> | null;
238
- }
239
-
240
- export class ApiRateLimiter {
241
- private readonly redis: Redis;
242
- private readonly windowMs: number;
243
- private readonly maxBatchSize: number;
244
- private readonly logger?: Logger;
245
- private readonly keyPrefix: string;
246
- private readonly leases = new Map<string, ProjectTokenLeaseState>();
247
-
248
- constructor({
249
- redis,
250
- windowMs = 60_000,
251
- maxBatchSize = 500,
252
- logger,
253
- keyPrefix = "rate-limit:api:req",
254
- }: ApiRateLimiterOptions) {
255
- this.redis = redis;
256
- this.windowMs = windowMs;
257
- this.maxBatchSize = maxBatchSize;
258
- this.logger = logger;
259
- this.keyPrefix = keyPrefix;
260
- }
261
-
262
- /**
263
- * Evaluates if a request for `projectId` is allowed within its `limitRpm`.
264
- * Fast-path uses local in-memory token lease (0ms Redis network latency).
265
- * Refills in the background before tokens are depleted.
266
- */
267
- async check(projectId: string, limitRpm: number): Promise<boolean> {
268
- if (limitRpm <= 0) return false;
269
-
270
- const nowMs = Date.now();
271
- const currentBucket = Math.floor(nowMs / this.windowMs);
272
-
273
- let state = this.leases.get(projectId);
274
- if (!state) {
275
- state = {
276
- bucketIndex: currentBucket,
277
- tokens: 0,
278
- batchSize: calculateTokenBatchSize(limitRpm, this.maxBatchSize),
279
- inFlightLease: null,
280
- };
281
- this.leases.set(projectId, state);
282
- this.maybePrune(currentBucket);
283
- }
284
-
285
- // Rollover to new bucket window when minute boundary elapses.
286
- // Kick off a prefill immediately so the first request of the new window
287
- // doesn't have to wait — it will land before tokens hit 0 again.
288
- if (state.bucketIndex !== currentBucket) {
289
- state.bucketIndex = currentBucket;
290
- state.tokens = 0;
291
- state.batchSize = calculateTokenBatchSize(limitRpm, this.maxBatchSize);
292
- state.inFlightLease = null;
293
- // Fire the first lease for the new window now, don't await it here.
294
- this.refill(projectId, state, limitRpm, nowMs, currentBucket).catch(() => {});
295
- }
296
-
297
- // 1. Fast Path: Local token available in memory (0ms network latency)
298
- if (state.tokens > 0) {
299
- state.tokens--;
300
-
301
- // Background refill when tokens drop below 25% of batch size
302
- const refillThreshold = Math.max(1, Math.floor(state.batchSize * 0.25));
303
- if (state.tokens <= refillThreshold && !state.inFlightLease) {
304
- this.refill(projectId, state, limitRpm, nowMs, currentBucket).catch(() => {});
305
- }
306
-
307
- return true;
308
- }
309
-
310
- // 2. Slow Path: tokens are depleted, block on the in-flight lease or start one.
311
- // Concurrent requests racing here all join the *same* promise so one Redis
312
- // round trip serves them. A lease only grants `batchSize` tokens, so a
313
- // burst larger than that leases again rather than rejecting requests the
314
- // window still has room for: a request is refused only once Redis itself
315
- // reports the window spent.
316
- for (;;) {
317
- if (!state.inFlightLease) {
318
- this.refill(projectId, state, limitRpm, nowMs, currentBucket).catch(() => {});
319
- }
320
- const granted = state.inFlightLease ? await state.inFlightLease : 0;
321
-
322
- // Only claim a token if the lease came back for the same bucket we waited on.
323
- if (state.bucketIndex !== currentBucket) return false;
324
- if (state.tokens > 0) {
325
- state.tokens--;
326
- return true;
327
- }
328
- if (granted <= 0) return false;
329
- }
330
- }
331
-
332
- private async refill(
333
- projectId: string,
334
- state: ProjectTokenLeaseState,
335
- limitRpm: number,
336
- nowMs: number,
337
- bucketIndex: number,
338
- ): Promise<number> {
339
- if (state.inFlightLease) {
340
- return state.inFlightLease;
341
- }
342
-
343
- const prevBucket = bucketIndex - 1;
344
- const rlTag = `{${this.keyPrefix}:${projectId || "global"}}`;
345
- const currentKey = `${rlTag}:${bucketIndex}`;
346
- const prevKey = `${rlTag}:${prevBucket}`;
347
- const requested = state.batchSize;
348
- let inFlightRef: Promise<number> | null = null;
349
- const executeLease = async (): Promise<number> => {
350
- try {
351
- let granted = await this.redis.leaseApiRateLimit(
352
- currentKey,
353
- prevKey,
354
- nowMs,
355
- this.windowMs,
356
- limitRpm,
357
- requested,
358
- );
359
-
360
- // On invalid return or negative, fail-open
361
- if (typeof granted !== "number" || granted < 0) {
362
- granted = requested;
363
- }
364
-
365
- if (state.bucketIndex === bucketIndex) {
366
- state.tokens += granted;
367
- }
368
- return granted;
369
- } catch (err) {
370
- this.logger?.warn(
371
- { err, projectId },
372
- "project rate limit lease failed — allowing request (fail-open)",
373
- );
374
- // Fail-open: credit requested tokens locally to prevent tight retry loops during Redis hiccups
375
- if (state.bucketIndex === bucketIndex) {
376
- state.tokens += requested;
377
- }
378
- return requested;
379
- } finally {
380
- if (state.inFlightLease === inFlightRef) {
381
- state.inFlightLease = null;
382
- }
383
- }
384
- };
385
-
386
- const promise = executeLease();
387
- inFlightRef = promise;
388
- state.inFlightLease = promise;
389
- return promise;
390
- }
391
-
392
- private maybePrune(currentBucket: number): void {
393
- if (this.leases.size > 2000) {
394
- for (const [id, s] of this.leases) {
395
- if (currentBucket - s.bucketIndex > 1) {
396
- this.leases.delete(id);
397
- }
398
- }
399
- }
400
- }
401
-
402
- /** Reset all local cached leases */
403
- clear(): void {
404
- this.leases.clear();
405
- }
406
-
407
- /** Invalidate local lease for a specific project */
408
- invalidate(projectId: string): void {
409
- this.leases.delete(projectId);
410
- }
411
- }
1
+ export * from "./project-settings-cache.js";
2
+ export * from "./user-throttle.js";
3
+ export * from "./api-rate-limiter.js";
@@ -0,0 +1,99 @@
1
+ import { LRUCache } from "@/shared/index.js";
2
+
3
+ /**
4
+ * Throttle overrides stored on the project row. `null` on either field means
5
+ * "no override" — fall back to the process-wide default.
6
+ */
7
+ export interface ProjectThrottleSettings {
8
+ throttleLimit: number | null;
9
+ throttleWindowHours: number | null;
10
+ }
11
+
12
+ const NO_OVERRIDES: ProjectThrottleSettings = {
13
+ throttleLimit: null,
14
+ throttleWindowHours: null,
15
+ };
16
+
17
+ export interface ProjectSettingsCacheOptions {
18
+ maxSize?: number;
19
+ ttlMs?: number;
20
+ }
21
+
22
+ /**
23
+ * Caches per-project throttle overrides for the engine.
24
+ *
25
+ * The throttle check runs once per notification, so an uncached lookup here
26
+ * would put a Postgres round trip on the hot path. Projects with no overrides
27
+ * are cached as well — the common case must not cost a query per message.
28
+ *
29
+ * The TTL bounds staleness on its own; `invalidate()` exists so a settings
30
+ * change published over pub/sub applies immediately rather than at expiry.
31
+ */
32
+ export class ProjectSettingsCache {
33
+ private readonly cache: LRUCache<string, ProjectThrottleSettings>;
34
+ /**
35
+ * Lookups already on the wire, keyed by project.
36
+ *
37
+ * The cache only fills once a query has come back, so without this a cold
38
+ * project at the start of a campaign puts one query per in-flight message on
39
+ * Postgres before the first answer lands — exactly when the database is
40
+ * busiest. Followers wait on the leader's promise instead.
41
+ */
42
+ private readonly inFlight = new Map<string, Promise<ProjectThrottleSettings>>();
43
+
44
+ constructor(
45
+ private readonly load: (projectId: string) => Promise<ProjectThrottleSettings | null>,
46
+ { maxSize = 1000, ttlMs = 60_000 }: ProjectSettingsCacheOptions = {},
47
+ ) {
48
+ this.cache = new LRUCache<string, ProjectThrottleSettings>(maxSize, ttlMs);
49
+ }
50
+
51
+ /**
52
+ * Throws whatever the loader throws. The caller decides whether a settings
53
+ * lookup failure should drop the message or fall back to defaults.
54
+ */
55
+ async get(projectId: string): Promise<ProjectThrottleSettings> {
56
+ const cached = this.cache.get(projectId);
57
+ if (cached) return cached;
58
+
59
+ const existing = this.inFlight.get(projectId);
60
+ if (existing) return existing;
61
+
62
+ // Assigned before any callback below can run, since `load` cannot settle
63
+ // within this synchronous block.
64
+ let pending!: Promise<ProjectThrottleSettings>;
65
+ pending = this.load(projectId)
66
+ .then((settings) => {
67
+ const resolved = settings ?? NO_OVERRIDES;
68
+ // Only cache while this is still the current lookup: an invalidate()
69
+ // that landed while the query was on the wire means the answer in hand
70
+ // already describes the old settings.
71
+ if (this.inFlight.get(projectId) === pending) {
72
+ this.cache.set(projectId, resolved);
73
+ }
74
+ return resolved;
75
+ })
76
+ .finally(() => {
77
+ // Cleared on failure too, so one bad lookup does not pin every later
78
+ // caller to the same rejection.
79
+ if (this.inFlight.get(projectId) === pending) {
80
+ this.inFlight.delete(projectId);
81
+ }
82
+ });
83
+
84
+ this.inFlight.set(projectId, pending);
85
+ return pending;
86
+ }
87
+
88
+ invalidate(projectId: string): void {
89
+ this.cache.delete(projectId);
90
+ // A lookup that started before the change would write a stale value on
91
+ // arrival; dropping it here sends the next caller back to the database.
92
+ this.inFlight.delete(projectId);
93
+ }
94
+
95
+ clear(): void {
96
+ this.cache.clear();
97
+ this.inFlight.clear();
98
+ }
99
+ }
@@ -0,0 +1,100 @@
1
+ import type { Redis } from "@/index.js";
2
+ import { randomUUID } from "crypto";
3
+
4
+ export interface ThrottleResult {
5
+ allowed: boolean;
6
+ count: number;
7
+ limit: number;
8
+ }
9
+
10
+ // True sliding window counter using Redis ZSET: max N sends per window per user.
11
+
12
+ export interface UserThrottleOptions {
13
+ redis: Redis;
14
+ maxPerHour?: number;
15
+ windowHours?: number;
16
+ }
17
+
18
+ export interface ThrottleCheckOptions {
19
+ /** Per-project cap for this window. `0` blocks every non-critical send. */
20
+ limit?: number | null;
21
+ /** Per-project window length in hours. */
22
+ windowHours?: number | null;
23
+ /** Future send time. The window is evaluated at that instant, not at now. */
24
+ scheduledAt?: string;
25
+ /**
26
+ * Stable id of the message being counted. A retry of the same message is
27
+ * then counted once, not once per attempt. Random when omitted.
28
+ */
29
+ messageId?: string;
30
+ }
31
+
32
+ /** Reject stored values that would make the window meaningless. */
33
+ function positiveOrNull(value: number | null | undefined): number | null {
34
+ return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
35
+ }
36
+
37
+ /** A limit of 0 is a legitimate kill switch, so zero is allowed here. */
38
+ function nonNegativeOrNull(value: number | null | undefined): number | null {
39
+ return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
40
+ }
41
+
42
+ export class UserThrottle {
43
+ private readonly redis: Redis;
44
+ private readonly maxPerHour: number;
45
+ private readonly windowHours: number;
46
+
47
+ constructor({ redis, maxPerHour = 3, windowHours = 1 }: UserThrottleOptions) {
48
+ this.redis = redis;
49
+ this.maxPerHour = maxPerHour;
50
+ this.windowHours = windowHours;
51
+ }
52
+
53
+ /**
54
+ * @param projectId Tenant that owns `userId`. User ids are caller-supplied
55
+ * external ids, so they collide across tenants and MUST be namespaced —
56
+ * otherwise one tenant's traffic throttles another's.
57
+ * @param options Per-project overrides. Values that are absent, null, or
58
+ * nonsensical fall back to this instance's defaults.
59
+ */
60
+ async check(
61
+ projectId: string,
62
+ userId: string,
63
+ priority?: string,
64
+ options: ThrottleCheckOptions = {},
65
+ ): Promise<ThrottleResult> {
66
+ const limit = nonNegativeOrNull(options.limit) ?? this.maxPerHour;
67
+ const windowHours = positiveOrNull(options.windowHours) ?? this.windowHours;
68
+
69
+ if (priority === "critical") {
70
+ return { allowed: true, count: 0, limit };
71
+ }
72
+
73
+ const windowMs = windowHours * 3600_000;
74
+ const key = `throttle:${projectId}:user:${userId}`;
75
+ const targetTime = options.scheduledAt ? new Date(options.scheduledAt).getTime() : Date.now();
76
+ const windowStart = targetTime - windowMs;
77
+ const memberId = options.messageId ?? randomUUID();
78
+
79
+ // The key must outlive the window it is counting. For a future-dated send
80
+ // that means surviving until targetTime plus one more window, so a task
81
+ // scheduled for next week still counts against the right bucket.
82
+ const windowSeconds = Math.ceil(windowMs / 1000);
83
+ const ttlSeconds = Math.max(
84
+ windowSeconds,
85
+ Math.ceil((targetTime - Date.now()) / 1000) + windowSeconds,
86
+ );
87
+
88
+ const count = await this.redis.throttleUser(
89
+ key,
90
+ windowStart,
91
+ limit,
92
+ targetTime,
93
+ memberId,
94
+ ttlSeconds,
95
+ Date.now() - windowMs,
96
+ );
97
+
98
+ return { allowed: count <= limit, count, limit };
99
+ }
100
+ }
@@ -170,7 +170,10 @@ export const LUA_COUNT_REQUEST = `
170
170
  return count
171
171
  `;
172
172
 
173
- /** Two-phase idempotency lease acquisition. Checks sent/legacy, then attempts SET NX lock. */
173
+ /**
174
+ * Two-phase idempotency lease acquisition. Checks sent/legacy, then attempts SET NX lock.
175
+ * @deprecated Nothing calls the `acquireLease` command; removed in the next minor version.
176
+ */
174
177
  export const LUA_ACQUIRE_LEASE = `
175
178
  if redis.call('EXISTS', KEYS[1]) == 1 or redis.call('EXISTS', KEYS[3]) == 1 then
176
179
  return 'completed'
@@ -185,7 +188,10 @@ export const LUA_ACQUIRE_LEASE = `
185
188
  return 'locked'
186
189
  `;
187
190
 
188
- /** Two-phase idempotency completion marker. Atomically sets completed + legacy and deletes lock. */
191
+ /**
192
+ * Two-phase idempotency completion marker. Atomically sets completed + legacy and deletes lock.
193
+ * @deprecated Nothing calls the `markProcessed` command; removed in the next minor version.
194
+ */
189
195
  export const LUA_MARK_PROCESSED = `
190
196
  redis.call('SET', KEYS[1], '1', 'EX', ARGV[1])
191
197
  redis.call('SET', KEYS[2], '1', 'EX', ARGV[1])
@@ -224,6 +230,7 @@ export function registerCustomCommands(redis: Redis): void {
224
230
  lua: LUA_SCHEDULER_POLL,
225
231
  });
226
232
 
233
+ // Deprecated: nothing calls acquireLease or markProcessed. Remove both in the next minor.
227
234
  redis.defineCommand("acquireLease", {
228
235
  numberOfKeys: 3,
229
236
  lua: LUA_ACQUIRE_LEASE,
@@ -361,7 +368,7 @@ export class RedisClient {
361
368
  }
362
369
  }
363
370
 
364
- function redactUrl(url: string): string {
371
+ export function redactUrl(url: string): string {
365
372
  try {
366
373
  const parsed = new URL(url);
367
374
  if (parsed.password) parsed.password = "***";