notifkit 0.1.16 → 0.1.18

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 (59) hide show
  1. package/README.md +5 -1
  2. package/dist/{bootstrap-BMDRPjgp.mjs → bootstrap-Cs1XIp6b.mjs} +1 -1
  3. package/dist/{bulk-CJ5QXiPa.mjs → bulk-4pRIiG2o.mjs} +1 -1
  4. package/dist/index.d.mts +37 -106
  5. package/dist/index.mjs +2 -2
  6. package/dist/{main-8nP3qmCT.mjs → main-BN7ZfvxN.mjs} +5 -14
  7. package/dist/{main-6_bXQBDH.mjs → main-Bl0S4GDd.mjs} +3 -3
  8. package/dist/{main-mGIT8jv4.mjs → main-C5DiM7_r.mjs} +3 -3
  9. package/dist/{main-B82bsFoy.mjs → main-DVzp0DLn.mjs} +8 -58
  10. package/dist/{main-ZW5RaiOK.mjs → main-O9iZ6iz2.mjs} +4 -9
  11. package/dist/{main-CpaHF1Zw.mjs → main-Ppr7Pq1g.mjs} +35 -16
  12. package/dist/{main-DULD8-th.mjs → main-yL5VinQ5.mjs} +5 -12
  13. package/dist/{main-g1KEcXXp.mjs → main-zgxAlH3l.mjs} +23 -94
  14. package/dist/{schedule-or-dispatch-Cd7GLfc3.mjs → schedule-or-dispatch-BwCZWS_P.mjs} +1 -1
  15. package/dist/{src-BE_EUpZ6.mjs → src-C38w4jR4.mjs} +88 -170
  16. package/drizzle/0009_retention_time_indexes.sql +4 -0
  17. package/drizzle/meta/_journal.json +7 -0
  18. package/package.json +1 -1
  19. package/src/client.ts +6 -6
  20. package/src/config/index.ts +9 -11
  21. package/src/contracts/sdk.ts +9 -9
  22. package/src/db/bulk.ts +3 -10
  23. package/src/db/schema.ts +3 -0
  24. package/src/idempotency/index.ts +12 -53
  25. package/src/queue/index.ts +9 -12
  26. package/src/rate-limiter/api-rate-limiter.ts +8 -27
  27. package/src/rate-limiter/project-settings-cache.ts +4 -16
  28. package/src/redis/index.ts +3 -51
  29. package/src/repositories/contact.ts +0 -2
  30. package/src/server.ts +1 -4
  31. package/src/services/api/handlers/auth.ts +3 -11
  32. package/src/services/api/handlers/campaigns.ts +4 -15
  33. package/src/services/api/handlers/events.ts +1 -2
  34. package/src/services/api/handlers/notifications.ts +6 -16
  35. package/src/services/api/handlers/projects.ts +1 -3
  36. package/src/services/api/handlers/shared.ts +7 -29
  37. package/src/services/api/handlers/system.ts +1 -1
  38. package/src/services/api/handlers/unsubscribe.ts +7 -30
  39. package/src/services/api/handlers/users.ts +1 -2
  40. package/src/services/api/http.ts +5 -10
  41. package/src/services/api/main.ts +27 -63
  42. package/src/services/api/webhooks.ts +8 -19
  43. package/src/services/auth/index.ts +2 -21
  44. package/src/services/delivery/main.ts +25 -89
  45. package/src/services/engine/main.ts +33 -69
  46. package/src/services/engine/schedule-or-dispatch.ts +7 -4
  47. package/src/services/enricher/main.ts +19 -49
  48. package/src/services/events/main.ts +3 -12
  49. package/src/services/scheduler/main.ts +26 -32
  50. package/src/services/scheduler/retention.ts +47 -0
  51. package/src/services/scheduler/send-gate.ts +6 -17
  52. package/src/services/workflow/duration.ts +1 -6
  53. package/src/services/workflow/main.ts +3 -9
  54. package/src/services/workflow/timers.ts +2 -1
  55. package/src/shared/batch-processor.ts +3 -7
  56. package/src/shared/utils.ts +2 -8
  57. package/src/transport/index.ts +0 -4
  58. package/src/unsubscribe/index.ts +3 -11
  59. package/src/workers/index.ts +30 -23
@@ -1,7 +1,7 @@
1
1
  import { z } from "zod";
2
2
  import { NotificationChannelSchema, NotificationPrioritySchema } from "./common.js";
3
3
 
4
- // ─── Preferences ──────────────────────────────────────────────────────────────
4
+ // Preferences
5
5
  //
6
6
  // Preferences are stored as JSONB and are intentionally open-ended so new
7
7
  // channels/topics can be added without a migration. `channels` and `topics`
@@ -21,7 +21,7 @@ export const PreferencesSchema = z.object({
21
21
  });
22
22
  export type Preferences = z.infer<typeof PreferencesSchema>;
23
23
 
24
- // ─── Contacts ─────────────────────────────────────────────────────────────────
24
+ // Contacts
25
25
 
26
26
  /** Channels that carry an addressable target (email address, phone, push token, url, chat id). */
27
27
  export const ContactChannelSchema = NotificationChannelSchema;
@@ -42,7 +42,7 @@ export const UserContactInputSchema = z.object({
42
42
  });
43
43
  export type UserContactInput = z.infer<typeof UserContactInputSchema>;
44
44
 
45
- // ─── Users ────────────────────────────────────────────────────────────────────
45
+ // Users
46
46
 
47
47
  /**
48
48
  * addUser({ id, contacts, email, phone, pushToken, segments, preferences })
@@ -82,7 +82,7 @@ export type AddContactInput = z.infer<typeof AddContactSchema>;
82
82
  export const BatchAddContactsSchema = z.union([AddContactSchema, z.array(AddContactSchema).min(1)]);
83
83
  export type BatchAddContactsInput = z.infer<typeof BatchAddContactsSchema>;
84
84
 
85
- // ─── Templates ────────────────────────────────────────────────────────────────
85
+ // Templates
86
86
 
87
87
  export const TemplateSchema = z.object({
88
88
  id: z.string().min(1),
@@ -98,7 +98,7 @@ export const SyncTemplatesSchema = z.object({
98
98
  });
99
99
  export type SyncTemplatesInput = z.input<typeof SyncTemplatesSchema>;
100
100
 
101
- // ─── notify() ─────────────────────────────────────────────────────────────────
101
+ // notify()
102
102
 
103
103
  /** Inline user object accepted by notify({ user: {...} }). */
104
104
  export const InlineUserSchema = AddUserSchema;
@@ -180,7 +180,7 @@ export const WorkflowNotifyPayloadSchema = NotifyRequestFields.superRefine((val,
180
180
  });
181
181
  export type WorkflowNotifyInput = z.input<typeof WorkflowNotifyPayloadSchema>;
182
182
 
183
- // ─── Workflows ────────────────────────────────────────────────────────────────
183
+ // Workflows
184
184
 
185
185
  export const TriggerWorkflowSchema = z.object({
186
186
  name: z.string().min(1),
@@ -189,7 +189,7 @@ export const TriggerWorkflowSchema = z.object({
189
189
  });
190
190
  export type TriggerWorkflowInput = z.input<typeof TriggerWorkflowSchema>;
191
191
 
192
- // ─── Events ───────────────────────────────────────────────────────────────────
192
+ // Events
193
193
 
194
194
  export const IngestEventSchema = z.object({
195
195
  name: z.string().min(1),
@@ -230,7 +230,7 @@ export const CreateWorkflowSchema = z.object({
230
230
  });
231
231
  export type CreateWorkflowInput = z.input<typeof CreateWorkflowSchema>;
232
232
 
233
- // ─── Projects ─────────────────────────────────────────────────────────────────
233
+ // Projects
234
234
 
235
235
  export const UpdateProjectSchema = z.object({
236
236
  rateLimitRpm: z.number().nullable().optional(),
@@ -239,7 +239,7 @@ export const UpdateProjectSchema = z.object({
239
239
  });
240
240
  export type UpdateProjectInput = z.infer<typeof UpdateProjectSchema>;
241
241
 
242
- // ─── Response Entities ────────────────────────────────────────────────────────
242
+ // Response Entities
243
243
 
244
244
  export interface UserContactResponse {
245
245
  id: string;
package/src/db/bulk.ts CHANGED
@@ -2,16 +2,9 @@ import { sql as drizzleSql } from "drizzle-orm";
2
2
  import { deliveryOutbox, messageLogs } from "./schema.js";
3
3
 
4
4
  /**
5
- * Bulk writes for the two tables every delivered notification touches.
6
- *
7
- * Drizzle rebuilds the statement for each call and walks every parameter as it
8
- * does, which for a few hundred rows per batch was the largest single CPU cost
9
- * in a worker. These send one fixed statement over `unnest()`d arrays instead,
10
- * so Postgres prepares it once and the client serialises a handful of arrays
11
- * rather than thousands of parameters.
12
- *
13
- * Handles that are not postgres.js-backed Drizzle instances (tests, other
14
- * drivers) fall back to the equivalent Drizzle query.
5
+ * Bulk writes for the tables every delivery touches. One fixed `unnest()`
6
+ * statement instead of Drizzle's per-row parameters, which was a worker's
7
+ * biggest CPU cost. Non-postgres.js handles fall back to plain Drizzle.
15
8
  */
16
9
 
17
10
  interface RawClient {
package/src/db/schema.ts CHANGED
@@ -210,6 +210,8 @@ export const messageLogs = pgTable(
210
210
  projectIdTaskIdIdx: index("message_logs_project_task_idx").on(table.projectId, table.taskId),
211
211
  providerMsgIdx: index("provider_msg_idx").on(table.providerMessageId),
212
212
  projectTimeIdx: index("msg_log_proj_time_idx").on(table.projectId, table.timestamp),
213
+ // For the retention prune, which deletes by age across all projects.
214
+ timeIdx: index("msg_log_time_idx").on(table.timestamp),
213
215
  templateIdx: index("msg_log_template_idx").on(table.projectId, table.templateId),
214
216
  workflowIdx: index("msg_log_workflow_idx").on(table.projectId, table.workflowInstanceId),
215
217
  campaignIdx: index("msg_log_campaign_idx").on(table.projectId, table.campaignId),
@@ -356,6 +358,7 @@ export const deliveryOutbox = pgTable(
356
358
  // The key leads with task_id, so looking up what an address was sent
357
359
  // (a user's details) read the whole table.
358
360
  destinationIdx: index("delivery_outbox_destination_idx").on(table.destination),
361
+ createdIdx: index("delivery_outbox_created_idx").on(table.createdAt),
359
362
  }),
360
363
  );
361
364
 
@@ -8,10 +8,7 @@ export interface IdempotencyOptions {
8
8
 
9
9
  export type LeaseResult = "acquired" | "locked" | "completed";
10
10
 
11
- /**
12
- * SET NX-based idempotency guard.
13
- * One key per id: `L` while leased, `1` once processed.
14
- */
11
+ /** One Redis key per id: `L` while a worker holds it, `1` once processed. */
15
12
  export class IdempotencyGuard {
16
13
  private readonly redis: Redis;
17
14
  private readonly keyPrefix: string;
@@ -27,60 +24,27 @@ export class IdempotencyGuard {
27
24
  return `${this.keyPrefix}:${id}`;
28
25
  }
29
26
 
30
- /** @deprecated Nothing writes `:lock` keys any more; read only for markers from older versions. Remove in the next minor. */
31
- private lockKey(id: string): string {
32
- return `${this.keyPrefix}:${id}:lock`;
33
- }
34
-
35
- /** @deprecated Nothing writes `:sent` keys any more; read only for markers from older versions. Remove in the next minor. */
36
- private completedKey(id: string): string {
37
- return `${this.keyPrefix}:${id}:sent`;
38
- }
39
-
40
- /**
41
- * Leases the id with SET NX. One key per id: `L` while leased, `1` once processed.
42
- * Returns "completed" if already processed, "locked" if another worker holds the lease.
43
- */
44
27
  async acquireLease(id: string, lockTtlSeconds: number = 30): Promise<LeaseResult> {
45
- const mainKey = this.key(id);
46
- const lockKey = this.lockKey(id);
47
-
48
- // Fast path: attempt native atomic SET NX
49
- const acquired = await this.redis.set(mainKey, "L", "EX", lockTtlSeconds, "NX");
50
- if (acquired === "OK") {
51
- return "acquired";
52
- }
53
-
54
- // Key exists — check whether it's completed ("S" / "1" / :sent) or in-flight ("L" / :lock)
55
- const [val, sent, lockVal] = await Promise.all([
56
- this.redis.get(mainKey),
57
- this.redis.get(this.completedKey(id)),
58
- this.redis.get(lockKey),
59
- ]);
60
-
61
- if (val === "S" || val === "1" || sent !== null) {
62
- return "completed";
63
- }
64
-
65
- if (val === "L" || lockVal !== null) {
66
- return "locked";
67
- }
28
+ const key = this.key(id);
29
+ if ((await this.redis.set(key, "L", "EX", lockTtlSeconds, "NX")) === "OK") return "acquired";
68
30
 
69
- // Key may have expired between initial SET NX and GETs; retry once
70
- const retryAcquired = await this.redis.set(mainKey, "L", "EX", lockTtlSeconds, "NX");
71
- if (retryAcquired === "OK") return "acquired";
31
+ const val = await this.redis.get(key);
32
+ if (val === "1") return "completed";
33
+ if (val === "L") return "locked";
72
34
 
73
- return "locked";
35
+ // The key expired between the SET and the GET.
36
+ const retry = await this.redis.set(key, "L", "EX", lockTtlSeconds, "NX");
37
+ return retry === "OK" ? "acquired" : "locked";
74
38
  }
75
39
 
76
- /** Atomically mark id as processed. Returns true on first call; false if already seen. */
40
+ /** Marks the id processed. Returns false if it was already seen. */
77
41
  async checkAndMark(id: string, customTtlSeconds?: number): Promise<boolean> {
78
42
  const ttl = customTtlSeconds ?? this.ttlSeconds;
79
43
  const result = await this.redis.set(this.key(id), "1", "EX", ttl, "NX");
80
44
  return result === "OK";
81
45
  }
82
46
 
83
- /** Unconditionally mark id as processed (upgrades lock to completed "1" with full TTL). */
47
+ /** Marks the id processed, replacing a lease with the full TTL. */
84
48
  async markProcessed(id: string, customTtlSeconds?: number): Promise<void> {
85
49
  const ttl = customTtlSeconds ?? this.ttlSeconds;
86
50
  await this.redis.set(this.key(id), "1", "EX", ttl);
@@ -91,12 +55,7 @@ export class IdempotencyGuard {
91
55
  return val !== null && val !== undefined;
92
56
  }
93
57
 
94
- /** Remove the idempotency marker (useful in tests or manual rollbacks). */
95
58
  async unmark(id: string): Promise<void> {
96
- await Promise.all([
97
- this.redis.del(this.key(id)),
98
- this.redis.del(this.lockKey(id)),
99
- this.redis.del(this.completedKey(id)),
100
- ]);
59
+ await this.redis.del(this.key(id));
101
60
  }
102
61
  }
@@ -10,8 +10,6 @@ import {
10
10
  } from "@/index.js";
11
11
  import { metrics } from "@/metrics/index.js";
12
12
 
13
- // ─── Types ─────────────────────────────────────────────────────────────────
14
-
15
13
  export interface StreamMessage {
16
14
  id: string;
17
15
  event: StreamEvent;
@@ -36,8 +34,6 @@ export interface PendingEntry {
36
34
  stream: StreamName;
37
35
  }
38
36
 
39
- // ─── Internal helpers ──────────────────────────────────────────────────────
40
-
41
37
  function parseMessage(id: string, fields: string[] | null, logger?: Logger): StreamMessage | null {
42
38
  if (!fields) return null;
43
39
 
@@ -64,8 +60,6 @@ function parseMessage(id: string, fields: string[] | null, logger?: Logger): Str
64
60
  return { id, event: parsed.data };
65
61
  }
66
62
 
67
- // ─── StreamProducer ────────────────────────────────────────────────────────
68
-
69
63
  export interface StreamProducerOptions {
70
64
  redis: Redis;
71
65
  stream: StreamName;
@@ -215,8 +209,6 @@ export class StreamProducer {
215
209
  }
216
210
  }
217
211
 
218
- // ─── StreamConsumer ────────────────────────────────────────────────────────
219
-
220
212
  export interface StreamConsumerOptions {
221
213
  redis: Redis;
222
214
  stream: StreamName | StreamName[];
@@ -308,8 +300,7 @@ export class StreamConsumer {
308
300
  while (this.running) {
309
301
  try {
310
302
  let currentStreams = [...this.streams];
311
- // Weighted fair queuing: 10% of the time, rotate the priority order
312
- // to prevent starvation of low priority queues.
303
+ // One read in ten starts from a lower-priority stream, so it can't starve.
313
304
  if (currentStreams.length > 1 && Math.random() < 0.1) {
314
305
  const offset = Math.floor(Math.random() * (currentStreams.length - 1)) + 1;
315
306
  for (let i = 0; i < offset; i++) {
@@ -557,8 +548,6 @@ export class StreamConsumer {
557
548
  }
558
549
  }
559
550
 
560
- // ─── PendingMessageScanner ─────────────────────────────────────────────────
561
-
562
551
  export interface PendingMessageScannerOptions {
563
552
  redis: Redis;
564
553
  stream: StreamName | StreamName[];
@@ -582,6 +571,14 @@ export class PendingMessageScanner {
582
571
  this.logger = logger;
583
572
  }
584
573
 
574
+ /**
575
+ * Resets a held entry's idle time so no scanner reclaims it while its
576
+ * handler is still running. JUSTID leaves the delivery count alone.
577
+ */
578
+ async touch(id: string, stream: string): Promise<void> {
579
+ await this.redis.xclaim(stream, this.group, this.consumer, 0, id, "JUSTID");
580
+ }
581
+
585
582
  async getPendingCount(): Promise<number> {
586
583
  let total = 0;
587
584
  for (const s of this.streams) {
@@ -1,8 +1,8 @@
1
1
  import type { Redis } from "@/index.js";
2
2
  import type { Logger } from "@/logger/index.js";
3
3
 
4
- // Leases token chunks from Redis sliding-window counters into local memory.
5
- // Eliminates per-request Redis network roundtrips on API ingress.
4
+ // Takes tokens from a Redis sliding window in batches, so most requests never
5
+ // wait on Redis.
6
6
 
7
7
  export interface ApiRateLimiterOptions {
8
8
  redis: Redis;
@@ -13,11 +13,7 @@ export interface ApiRateLimiterOptions {
13
13
  keyPrefix?: string;
14
14
  }
15
15
 
16
- /**
17
- * Computes dynamic token lease batch size based on RPM.
18
- * Targets ~5s of limit capacity so Redis is contacted at most ~12 times/min
19
- * regardless of instantaneous request rate. Bounded between 1 and maxBatchSize.
20
- */
16
+ /** About five seconds' worth of the limit, so Redis is asked ~12 times a minute. */
21
17
  export function calculateTokenBatchSize(limitRpm: number, maxBatchSize = 500): number {
22
18
  if (limitRpm <= 0) return 0;
23
19
  if (limitRpm <= 10) return 1;
@@ -56,11 +52,6 @@ export class ApiRateLimiter {
56
52
  this.keyPrefix = keyPrefix;
57
53
  }
58
54
 
59
- /**
60
- * Evaluates if a request for `projectId` is allowed within its `limitRpm`.
61
- * Fast-path uses local in-memory token lease (0ms Redis network latency).
62
- * Refills in the background before tokens are depleted.
63
- */
64
55
  async check(projectId: string, limitRpm: number): Promise<boolean> {
65
56
  if (limitRpm <= 0) return false;
66
57
 
@@ -79,23 +70,19 @@ export class ApiRateLimiter {
79
70
  this.maybePrune(currentBucket);
80
71
  }
81
72
 
82
- // Rollover to new bucket window when minute boundary elapses.
83
- // Kick off a prefill immediately so the first request of the new window
84
- // doesn't have to wait — it will land before tokens hit 0 again.
73
+ // New window: start leasing now so the next request doesn't wait.
85
74
  if (state.bucketIndex !== currentBucket) {
86
75
  state.bucketIndex = currentBucket;
87
76
  state.tokens = 0;
88
77
  state.batchSize = calculateTokenBatchSize(limitRpm, this.maxBatchSize);
89
78
  state.inFlightLease = null;
90
- // Fire the first lease for the new window now, don't await it here.
91
79
  this.refill(projectId, state, limitRpm, nowMs, currentBucket).catch(() => {});
92
80
  }
93
81
 
94
- // 1. Fast Path: Local token available in memory (0ms network latency)
95
82
  if (state.tokens > 0) {
96
83
  state.tokens--;
97
84
 
98
- // Background refill when tokens drop below 25% of batch size
85
+ // Refill in the background once a quarter of the batch is left.
99
86
  const refillThreshold = Math.max(1, Math.floor(state.batchSize * 0.25));
100
87
  if (state.tokens <= refillThreshold && !state.inFlightLease) {
101
88
  this.refill(projectId, state, limitRpm, nowMs, currentBucket).catch(() => {});
@@ -104,12 +91,8 @@ export class ApiRateLimiter {
104
91
  return true;
105
92
  }
106
93
 
107
- // 2. Slow Path: tokens are depleted, block on the in-flight lease or start one.
108
- // Concurrent requests racing here all join the *same* promise so one Redis
109
- // round trip serves them. A lease only grants `batchSize` tokens, so a
110
- // burst larger than that leases again rather than rejecting requests the
111
- // window still has room for: a request is refused only once Redis itself
112
- // reports the window spent.
94
+ // Out of tokens: wait on the shared lease. Refuse only once Redis says the
95
+ // window is spent, not just because one batch ran out.
113
96
  for (;;) {
114
97
  if (!state.inFlightLease) {
115
98
  this.refill(projectId, state, limitRpm, nowMs, currentBucket).catch(() => {});
@@ -168,7 +151,7 @@ export class ApiRateLimiter {
168
151
  { err, projectId },
169
152
  "project rate limit lease failed — allowing request (fail-open)",
170
153
  );
171
- // Fail-open: credit requested tokens locally to prevent tight retry loops during Redis hiccups
154
+ // Fail open, and credit the batch so a Redis outage doesn't turn into a retry loop.
172
155
  if (state.bucketIndex === bucketIndex) {
173
156
  state.tokens += requested;
174
157
  }
@@ -196,12 +179,10 @@ export class ApiRateLimiter {
196
179
  }
197
180
  }
198
181
 
199
- /** Reset all local cached leases */
200
182
  clear(): void {
201
183
  this.leases.clear();
202
184
  }
203
185
 
204
- /** Invalidate local lease for a specific project */
205
186
  invalidate(projectId: string): void {
206
187
  this.leases.delete(projectId);
207
188
  }
@@ -20,25 +20,13 @@ export interface ProjectSettingsCacheOptions {
20
20
  }
21
21
 
22
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.
23
+ * Per-project throttle overrides, read once per notification. Projects with no
24
+ * overrides are cached too. `invalidate()` lets a settings change apply before
25
+ * the TTL runs out.
31
26
  */
32
27
  export class ProjectSettingsCache {
33
28
  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
- */
29
+ /** Lookups in flight, so a cold project at the start of a campaign costs one query. */
42
30
  private readonly inFlight = new Map<string, Promise<ProjectThrottleSettings>>();
43
31
 
44
32
  constructor(
@@ -170,35 +170,6 @@ export const LUA_COUNT_REQUEST = `
170
170
  return count
171
171
  `;
172
172
 
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
- */
177
- export const LUA_ACQUIRE_LEASE = `
178
- if redis.call('EXISTS', KEYS[1]) == 1 or redis.call('EXISTS', KEYS[3]) == 1 then
179
- return 'completed'
180
- end
181
- local lockAcquired = redis.call('SET', KEYS[2], '1', 'EX', ARGV[1], 'NX')
182
- if lockAcquired then
183
- return 'acquired'
184
- end
185
- if redis.call('EXISTS', KEYS[1]) == 1 or redis.call('EXISTS', KEYS[3]) == 1 then
186
- return 'completed'
187
- end
188
- return 'locked'
189
- `;
190
-
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
- */
195
- export const LUA_MARK_PROCESSED = `
196
- redis.call('SET', KEYS[1], '1', 'EX', ARGV[1])
197
- redis.call('SET', KEYS[2], '1', 'EX', ARGV[1])
198
- redis.call('DEL', KEYS[3])
199
- return 1
200
- `;
201
-
202
173
  /**
203
174
  * Registers pre-compiled custom commands on an ioredis instance.
204
175
  * Calls defineCommand so ioredis uses EVALSHA rather than re-transmitting
@@ -230,21 +201,10 @@ export function registerCustomCommands(redis: Redis): void {
230
201
  lua: LUA_SCHEDULER_POLL,
231
202
  });
232
203
 
233
- // Deprecated: nothing calls acquireLease or markProcessed. Remove both in the next minor.
234
- redis.defineCommand("acquireLease", {
235
- numberOfKeys: 3,
236
- lua: LUA_ACQUIRE_LEASE,
237
- });
238
-
239
204
  redis.defineCommand("countRequest", {
240
205
  numberOfKeys: 1,
241
206
  lua: LUA_COUNT_REQUEST,
242
207
  });
243
-
244
- redis.defineCommand("markProcessed", {
245
- numberOfKeys: 3,
246
- lua: LUA_MARK_PROCESSED,
247
- });
248
208
  }
249
209
 
250
210
  export interface RedisClientOptions {
@@ -260,17 +220,9 @@ export class RedisClient {
260
220
  readonly native: Redis;
261
221
 
262
222
  /**
263
- * One command connection per Redis URL for every service in this process.
264
- *
265
- * Each service used to open its own, so a single notification's commands
266
- * reached Redis over three or four sockets, one round trip each. Sharing a
267
- * connection lets auto-pipelining merge whatever the services issue in the
268
- * same tick into one write, and Redis spends most of its time per round trip
269
- * rather than per command. Blocking reads and subscribers still duplicate
270
- * their own connections.
271
- *
272
- * The handle's `disconnect()` releases this caller's reference; the
273
- * connection closes when the last service lets go.
223
+ * One command connection per URL for every service in the process, so
224
+ * auto-pipelining can batch what they send in the same tick. `disconnect()`
225
+ * drops this caller's reference; the last one closes the connection.
274
226
  */
275
227
  static shared(options: RedisClientOptions): RedisClient {
276
228
  let entry = sharedClients.get(options.url);
@@ -180,8 +180,6 @@ export class ContactRepository {
180
180
  const contactId = inserted[0]?.id;
181
181
  if (!contactId) return;
182
182
 
183
- // Contact-level topic preferences were previously accepted by the API and
184
- // silently discarded.
185
183
  const topics = Object.entries(preferences.topics ?? {});
186
184
  if (topics.length > 0) {
187
185
  await this.db
package/src/server.ts CHANGED
@@ -85,7 +85,6 @@ export class NotifkitServer extends EventEmitter {
85
85
  }
86
86
 
87
87
  async start() {
88
- // 1. Initial configuration setup for environment overrides
89
88
  if (this.options.port) process.env.PORT = String(this.options.port);
90
89
  if (this.options.logLevel) process.env.LOG_LEVEL = this.options.logLevel;
91
90
  if (this.options.nodeEnv) process.env.NODE_ENV = this.options.nodeEnv;
@@ -108,7 +107,7 @@ export class NotifkitServer extends EventEmitter {
108
107
 
109
108
  const isProduction = process.env.NODE_ENV === "production";
110
109
 
111
- // 2. Spin up test containers if needed (only in development/test)
110
+ // Outside production, a missing Redis or Postgres URL starts a container.
112
111
  if (!this.options.redisUrl) {
113
112
  if (process.env.REDIS_URL) {
114
113
  this.options.redisUrl = process.env.REDIS_URL;
@@ -146,14 +145,12 @@ export class NotifkitServer extends EventEmitter {
146
145
  if (this.options.redisUrl) process.env.REDIS_URL = this.options.redisUrl;
147
146
  if (this.options.databaseUrl) process.env.DATABASE_URL = this.options.databaseUrl;
148
147
 
149
- // 3. Set global config overrides
150
148
  const finalConfig = readBaseConfig();
151
149
  setGlobalConfig(finalConfig);
152
150
  if (this.options.aiModel) {
153
151
  setAiConfig({ aiModel: this.options.aiModel });
154
152
  }
155
153
 
156
- // 4. Run database migrations if enabled
157
154
  if (this.options.autoMigrate !== false) {
158
155
  this.logger.info("Running database migrations...");
159
156
  const { db, sql } = createDatabase({ url: this.options.databaseUrl! });
@@ -6,7 +6,7 @@ import {
6
6
  getAdminSession,
7
7
  DUMMY_PASSWORD_HASH,
8
8
  } from "@/services/auth/index.js";
9
- import { readJsonBody, sendJson, sendValidationError } from "../http.js";
9
+ import { extractAuthToken, readJsonBody, sendJson, sendValidationError } from "../http.js";
10
10
  import { z } from "zod";
11
11
  import { type Deps } from "./shared.js";
12
12
 
@@ -63,11 +63,7 @@ export function createAuthHandlers(deps: Deps) {
63
63
  }
64
64
 
65
65
  async function logout(req: IncomingMessage, res: ServerResponse): Promise<void> {
66
- const authHeader = req.headers["authorization"];
67
- let token: string | undefined;
68
- if (typeof authHeader === "string" && authHeader.toLowerCase().startsWith("bearer ")) {
69
- token = authHeader.slice(7).trim();
70
- }
66
+ const token = extractAuthToken(req);
71
67
  if (token) {
72
68
  await revokeAdminSession(deps.redis.native, token);
73
69
  }
@@ -75,11 +71,7 @@ export function createAuthHandlers(deps: Deps) {
75
71
  }
76
72
 
77
73
  async function getMe(req: IncomingMessage, res: ServerResponse): Promise<void> {
78
- const authHeader = req.headers["authorization"];
79
- let token: string | undefined;
80
- if (typeof authHeader === "string" && authHeader.toLowerCase().startsWith("bearer ")) {
81
- token = authHeader.slice(7).trim();
82
- }
74
+ const token = extractAuthToken(req);
83
75
  if (!token) {
84
76
  sendJson(res, 401, { error: "unauthorized", message: "Missing token" });
85
77
  return;
@@ -6,8 +6,6 @@ import { messageLogs } from "@/db/schema.js";
6
6
  import { type Deps, contains, getQueryParam, parseLimit } from "./shared.js";
7
7
 
8
8
  export function createCampaignsHandlers(deps: Deps) {
9
- // One row per campaign label, newest activity first, with support for filtering
10
- // by search keyword, channel, date range, and minimum message counts.
11
9
  async function listCampaigns(
12
10
  _req: IncomingMessage,
13
11
  res: ServerResponse,
@@ -74,12 +72,8 @@ export function createCampaignsHandlers(deps: Deps) {
74
72
  });
75
73
  }
76
74
 
77
- // The delivery funnel for one campaign, in a single grouped scan.
78
- //
79
- // Every figure counts *distinct tasks*, not rows: a task accumulates a
80
- // dispatch row, an attempt row, and any number of engagement rows, so
81
- // counting rows would inflate every number by a different factor. Opening the
82
- // same email twice is one person who opened it.
75
+ // Every figure counts distinct tasks, not rows: one task has a dispatch row,
76
+ // an attempt row and any number of engagement rows.
83
77
  async function getCampaignStats(
84
78
  _req: IncomingMessage,
85
79
  res: ServerResponse,
@@ -128,10 +122,7 @@ export function createCampaignsHandlers(deps: Deps) {
128
122
  if (ENGAGEMENT.includes(row.kind as Engagement)) {
129
123
  bucket[row.kind as Engagement] += n;
130
124
  } else if (row.kind === "dispatched") {
131
- // `sent` is every task that reached a provider at all, which is the
132
- // denominator a bounce rate is measured against. Each attempt logs a
133
- // dispatched row besides its outcome row, and the two are grouped
134
- // separately, so counting both counted every message twice.
125
+ // Every task that reached a provider: the denominator for bounce rate.
135
126
  bucket.sent += n;
136
127
  } else {
137
128
  if (row.status === "delivered") bucket.delivered += n;
@@ -149,9 +140,7 @@ export function createCampaignsHandlers(deps: Deps) {
149
140
 
150
141
  const pct = (n: number, d: number) => (d > 0 ? Number(((n / d) * 100).toFixed(2)) : null);
151
142
 
152
- // Engagement only exists where a provider reports it back. Saying "0% open
153
- // rate" for an SMS blast, or for email with no webhook wired, reads as a
154
- // failed campaign rather than an untracked one.
143
+ // No engagement data means untracked, not 0%: SMS, or email without a webhook.
155
144
  const channels = [...byChannel.keys()];
156
145
  const engagementCapable = channels.some((c) => c === "email");
157
146
  const sawEngagement = ENGAGEMENT.some((k) => total[k] > 0);
@@ -21,8 +21,7 @@ export function createEventsHandlers(deps: Deps) {
21
21
  const eventTime = new Date(tsStr as string).getTime();
22
22
  const expMs = parseInt(expiryStr as string, 10) * 1000;
23
23
 
24
- // An unreadable timestamp or expiry made every comparison false, which
25
- // let the event through unchecked.
24
+ // An unreadable date would make every comparison false and let the event through.
26
25
  if (Number.isNaN(eventTime) || Number.isNaN(expMs)) {
27
26
  sendJson(res, 400, {
28
27
  error: "invalid_timestamp",