notifkit 0.1.10 → 0.1.12

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 (81) hide show
  1. package/README.md +37 -1
  2. package/dashboard/dist/assets/{index-7mvXb4bS.js → index-Bsrmo9LE.js} +1 -1
  3. package/dashboard/dist/assets/index-s-SXGIwv.css +1 -0
  4. package/dashboard/dist/index.html +2 -2
  5. package/dist/bootstrap-omGPIBny.mjs +89 -0
  6. package/dist/bulk-C4hTcnLu.mjs +77 -0
  7. package/dist/index.d.mts +1160 -8886
  8. package/dist/index.mjs +2 -38
  9. package/dist/{main-C9s-2ArH.mjs → main-B-AZ-xoN.mjs} +49 -75
  10. package/dist/main-B5BwjIMu.mjs +811 -0
  11. package/dist/{main-B3iQrl3t.mjs → main-BU27VjDC.mjs} +149 -134
  12. package/dist/main-Bes11Ad3.mjs +312 -0
  13. package/dist/{main-BiFiOX9D.mjs → main-BtnGmyaT.mjs} +119 -112
  14. package/dist/{main-39DtKrX4.mjs → main-BxAeC_k6.mjs} +395 -184
  15. package/dist/{main-Dz2sUh3c.mjs → main-DAXO-MiH.mjs} +57 -54
  16. package/dist/{main-BgmT1MPe.mjs → main-DYGCl7Ja.mjs} +135 -79
  17. package/dist/{src-QiTu5e_a.mjs → src-CIPTzq9i.mjs} +1351 -661
  18. package/drizzle/0006_message_logs_redundant_indexes.sql +7 -0
  19. package/drizzle/0007_workflow_status_canceled.sql +3 -0
  20. package/drizzle/meta/_journal.json +14 -0
  21. package/package.json +21 -18
  22. package/scripts/create-admin.mjs +8 -1
  23. package/scripts/migrate.mjs +43 -0
  24. package/src/client.ts +15 -5
  25. package/src/config/index.ts +37 -3
  26. package/src/contracts/events/notification-ai-pending.ts +12 -0
  27. package/src/contracts/events/notification-delivered.ts +7 -0
  28. package/src/contracts/events/notification-dispatched.ts +21 -2
  29. package/src/contracts/events/notification-enriched.ts +16 -0
  30. package/src/contracts/events/notification-failed.ts +2 -0
  31. package/src/contracts/events/notification-requested.ts +2 -0
  32. package/src/contracts/registry.ts +2 -2
  33. package/src/contracts/sdk.ts +77 -29
  34. package/src/db/bulk.ts +132 -0
  35. package/src/db/index.ts +174 -7
  36. package/src/db/schema.ts +3 -50
  37. package/src/idempotency/index.ts +60 -6
  38. package/src/logger/index.ts +0 -12
  39. package/src/queue/index.ts +255 -76
  40. package/src/rate-limiter/index.ts +217 -16
  41. package/src/redis/index.ts +265 -0
  42. package/src/repositories/index.ts +171 -82
  43. package/src/server.ts +64 -41
  44. package/src/services/ai/main.ts +83 -70
  45. package/src/services/api/admin-static.ts +41 -12
  46. package/src/services/api/handlers.ts +357 -159
  47. package/src/services/api/http.ts +34 -7
  48. package/src/services/api/main.ts +104 -67
  49. package/src/services/api/router.ts +18 -5
  50. package/src/services/delivery/main.ts +495 -230
  51. package/src/services/delivery/throttle.ts +42 -59
  52. package/src/services/engine/main.ts +206 -152
  53. package/src/services/enricher/main.ts +155 -107
  54. package/src/services/events/main.ts +100 -55
  55. package/src/services/scheduler/main.ts +151 -79
  56. package/src/services/scheduler/send-gate.ts +117 -0
  57. package/src/services/workflow/main.ts +220 -100
  58. package/src/shared/batch-processor.ts +65 -34
  59. package/src/shared/dataloader.ts +58 -22
  60. package/src/shared/events.ts +3 -0
  61. package/src/shared/index.ts +0 -1
  62. package/src/shared/utils.ts +2 -47
  63. package/src/templates/index.ts +0 -67
  64. package/src/transport/index.ts +6 -0
  65. package/src/workers/bootstrap.ts +124 -0
  66. package/src/workers/index.ts +99 -24
  67. package/src/workflows/sdk.ts +2 -0
  68. package/dashboard/dist/assets/index-o7L-f3-c.css +0 -1
  69. package/dist/index.d.mts.map +0 -1
  70. package/dist/index.mjs.map +0 -1
  71. package/dist/main-39DtKrX4.mjs.map +0 -1
  72. package/dist/main-B3iQrl3t.mjs.map +0 -1
  73. package/dist/main-BM8DH3v3.mjs +0 -632
  74. package/dist/main-BM8DH3v3.mjs.map +0 -1
  75. package/dist/main-BgmT1MPe.mjs.map +0 -1
  76. package/dist/main-BiFiOX9D.mjs.map +0 -1
  77. package/dist/main-C9s-2ArH.mjs.map +0 -1
  78. package/dist/main-Cqo3rSb5.mjs +0 -224
  79. package/dist/main-Cqo3rSb5.mjs.map +0 -1
  80. package/dist/main-Dz2sUh3c.mjs.map +0 -1
  81. package/dist/src-QiTu5e_a.mjs.map +0 -1
@@ -1,4 +1,4 @@
1
- import { randomUUID } from "node:crypto";
1
+ import { randomUUID, randomBytes, createHash } from "node:crypto";
2
2
  import type { IncomingMessage, ServerResponse } from "node:http";
3
3
  import type { Logger } from "@/logger/index.js";
4
4
  import type { RedisClient } from "@/redis/index.js";
@@ -36,13 +36,14 @@ import {
36
36
  CreateWorkflowSchema,
37
37
  TriggerWorkflowSchema,
38
38
  STREAMS,
39
+ CONSUMER_GROUPS,
39
40
  PUBSUB_CHANNELS,
40
41
  } from "@/contracts/index.js";
41
42
  import { readJsonBody, sendJson, sendNoContent, sendValidationError } from "./http.js";
42
43
  import type { RouteContext } from "./router.js";
43
44
  import { globalEmitter, getPriorityBucket, normaliseTarget } from "@/shared/index.js";
44
45
  import { metrics } from "@/metrics/index.js";
45
- import { eq, desc, and, lt, lte, gte, sql, like, or, isNotNull, inArray } from "drizzle-orm";
46
+ import { eq, desc, and, lte, gte, sql, like, or, isNotNull, inArray } from "drizzle-orm";
46
47
  import {
47
48
  messageLogs,
48
49
  workflowDefinitions,
@@ -137,13 +138,15 @@ function contactsOf(user: InlineUserLike): ResolvedContact[] {
137
138
  /** Persist user records + their contacts in bulk. Shared by addUser and inline notify. */
138
139
  async function persistUsers(deps: Deps, users: InlineUserLike[], projectId: string): Promise<void> {
139
140
  const usersList = users.map((u) => {
140
- const primaryEmail =
141
- u.email?.[0] ?? u.contacts?.find((c) => c.channel === "email")?.target ?? null;
141
+ const primaryEmail = u.email?.[0] ?? u.contacts?.find((c) => c.channel === "email")?.target;
142
142
 
143
+ // Omitted fields stay omitted: the upsert merges what is given into the
144
+ // stored profile, so an inline `{ id, phone }` on notify must not reset the
145
+ // user's timezone, language or email. Defaults are applied when read.
143
146
  return {
144
147
  userId: u.id,
145
- language: u.language ?? "en",
146
- timezone: u.timezone ?? "UTC",
148
+ language: u.language,
149
+ timezone: u.timezone,
147
150
  email: primaryEmail,
148
151
  segments: u.segments ?? [],
149
152
  preferences: u.preferences ?? {},
@@ -176,6 +179,114 @@ async function persistUsers(deps: Deps, users: InlineUserLike[], projectId: stri
176
179
  });
177
180
  }
178
181
 
182
+ /**
183
+ * A dead-letter entry, read the way StreamConsumer writes it: the original
184
+ * event JSON under `data`, carrying a `dlq` block that records which stream it
185
+ * failed on. Flat `payload`/`eventType` fields are accepted for entries written
186
+ * by hand or by older versions.
187
+ */
188
+ interface DlqEntry {
189
+ id: string;
190
+ eventType: string;
191
+ payload: any;
192
+ projectId?: string;
193
+ error: string;
194
+ timestamp: string;
195
+ /** The event as it was published, without its `dlq` block. */
196
+ event: Record<string, any> | null;
197
+ originalStream?: string;
198
+ fields: Record<string, string>;
199
+ }
200
+
201
+ function parseDlqEntry(id: string, rawFields: string[]): DlqEntry {
202
+ const fields: Record<string, string> = {};
203
+ for (let i = 0; i < rawFields.length; i += 2) {
204
+ fields[rawFields[i]!] = rawFields[i + 1]!;
205
+ }
206
+
207
+ let parsed: Record<string, any> | null = null;
208
+ if (fields.data) {
209
+ try {
210
+ parsed = JSON.parse(fields.data);
211
+ } catch {
212
+ parsed = null;
213
+ }
214
+ }
215
+ const { dlq, ...event } = parsed ?? {};
216
+
217
+ let payload: any = fields;
218
+ if (parsed) {
219
+ payload = event.payload;
220
+ } else if (fields.payload) {
221
+ try {
222
+ payload = JSON.parse(fields.payload);
223
+ } catch {
224
+ payload = fields.payload;
225
+ }
226
+ }
227
+
228
+ const ms = Number(id.split("-")[0]);
229
+ return {
230
+ id,
231
+ eventType: event.type ?? fields.eventType ?? fields.event_type ?? "unknown",
232
+ payload,
233
+ projectId: payload?.projectId ?? payload?.project_id ?? fields.projectId,
234
+ error: dlq?.reason ?? fields.error ?? fields.reason ?? "Dead letter payload",
235
+ timestamp:
236
+ dlq?.ackedAt ??
237
+ fields.timestamp ??
238
+ (Number.isFinite(ms) ? new Date(ms).toISOString() : new Date().toISOString()),
239
+ event: parsed ? event : null,
240
+ originalStream: dlq?.originalStream,
241
+ fields,
242
+ };
243
+ }
244
+
245
+ /**
246
+ * Ids that live in uuid columns. Anything else can match no row, and passing it
247
+ * to Postgres fails the query outright — a 500 for what is simply not found.
248
+ */
249
+ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
250
+ const isUuid = (v: string | undefined): v is string => typeof v === "string" && UUID_RE.test(v);
251
+
252
+ /** Opaque position in the delivery log: a row's full-precision timestamp and id. */
253
+ function encodeLogCursor(ts: string, id: string): string {
254
+ return Buffer.from(JSON.stringify([ts, id])).toString("base64url");
255
+ }
256
+
257
+ function decodeLogCursor(cursor: string | null | undefined): { ts: string; id: string } | null {
258
+ if (!cursor) return null;
259
+ // Cursors handed out before this format were a millisecond timestamp.
260
+ if (/^\d+$/.test(cursor)) {
261
+ return {
262
+ ts: new Date(Number(cursor)).toISOString(),
263
+ id: "ffffffff-ffff-ffff-ffff-ffffffffffff",
264
+ };
265
+ }
266
+ try {
267
+ const [ts, id] = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
268
+ if (
269
+ typeof ts === "string" &&
270
+ typeof id === "string" &&
271
+ !Number.isNaN(Date.parse(ts)) &&
272
+ /^[0-9a-f-]{36}$/i.test(id)
273
+ ) {
274
+ return { ts, id };
275
+ }
276
+ } catch {
277
+ // fall through
278
+ }
279
+ return null;
280
+ }
281
+
282
+ /**
283
+ * A LIKE pattern matching `term` anywhere, with the term's own `%`, `_` and
284
+ * `\` taken literally rather than as wildcards.
285
+ */
286
+ function contains(term: string): string {
287
+ return `%${term.replace(/[\\%_]/g, "\\$&")}%`;
288
+ }
289
+
179
290
  function getQueryParam(ctx: RouteContext, key: string): string | undefined {
180
291
  if (!ctx.query) return undefined;
181
292
  if (typeof ctx.query.get === "function") {
@@ -184,6 +295,19 @@ function getQueryParam(ctx: RouteContext, key: string): string | undefined {
184
295
  return (ctx.query as any)[key] ?? undefined;
185
296
  }
186
297
 
298
+ /**
299
+ * Page size from `?limit=`, clamped to [1, max]. Missing or non-numeric
300
+ * values fall back to `fallback`; `undefined` there means "no limit".
301
+ */
302
+ function parseLimit<F extends number | undefined>(
303
+ ctx: RouteContext,
304
+ fallback: F,
305
+ max = 100,
306
+ ): number | F {
307
+ const n = parseInt(getQueryParam(ctx, "limit") ?? "", 10);
308
+ return Number.isNaN(n) ? fallback : Math.min(Math.max(n, 1), max);
309
+ }
310
+
187
311
  export function createHandlers(deps: Deps) {
188
312
  const { logger } = deps;
189
313
 
@@ -343,15 +467,17 @@ export function createHandlers(deps: Deps) {
343
467
  res: ServerResponse,
344
468
  ctx: RouteContext,
345
469
  ): Promise<void> {
346
- const parsed = NotifyRequestSchema.safeParse(await readJsonBody(req));
470
+ const rawBody = await readJsonBody(req);
471
+ const parsed = NotifyRequestSchema.safeParse(rawBody);
472
+
347
473
  if (!parsed.success) return sendValidationError(res, parsed.error);
348
474
  const body = parsed.data;
349
475
 
350
476
  // Resolve the (unresolved) target. Inline users are synced first.
351
477
  let targets: NotificationTarget[] = [];
478
+ const inlineUsersToSync: InlineUserLike[] = [];
352
479
  if (body.user !== undefined) {
353
480
  const users = Array.isArray(body.user) ? body.user : [body.user];
354
- const inlineUsersToSync: InlineUserLike[] = [];
355
481
  for (const u of users) {
356
482
  if (typeof u === "string") {
357
483
  targets.push({ type: "user", userId: u });
@@ -403,7 +529,9 @@ export function createHandlers(deps: Deps) {
403
529
  aiPrompts: body.aiPrompts,
404
530
  fallback: body.fallback ?? false,
405
531
  scheduledAt: body.sendAt,
406
- idempotencyKey: notificationId,
532
+ // Only a caller's own key: the enricher keeps those for the full
533
+ // 24-hour window, and dedupes everything else on the event id.
534
+ ...(req.headers["x-idempotency-key"] ? { idempotencyKey: notificationId } : {}),
407
535
  campaignId: body.campaign,
408
536
  };
409
537
 
@@ -419,7 +547,7 @@ export function createHandlers(deps: Deps) {
419
547
  messageIds.push(...chunkMessageIds);
420
548
  }
421
549
 
422
- logger.info({ count: targets.length, priority: p }, "notification requested");
550
+ logger.debug({ count: targets.length, priority: p }, "notification requested");
423
551
  metrics.messagesPublished.inc({ channel: "api", priority: p }, targets.length);
424
552
 
425
553
  if (targets.length === 1) {
@@ -547,6 +675,15 @@ export function createHandlers(deps: Deps) {
547
675
  const eventTime = new Date(tsStr as string).getTime();
548
676
  const expMs = parseInt(expiryStr as string, 10) * 1000;
549
677
 
678
+ // An unreadable timestamp or expiry made every comparison false, which
679
+ // let the event through unchecked.
680
+ if (Number.isNaN(eventTime) || Number.isNaN(expMs)) {
681
+ sendJson(res, 400, {
682
+ error: "invalid_timestamp",
683
+ message: "x-timestamp and x-expiry must be a date and a number of seconds",
684
+ });
685
+ return;
686
+ }
550
687
  if (now > eventTime + expMs) {
551
688
  sendJson(res, 400, { error: "event_expired", message: "Webhook event is expired" });
552
689
  return;
@@ -617,8 +754,7 @@ export function createHandlers(deps: Deps) {
617
754
  res: ServerResponse,
618
755
  ctx: RouteContext,
619
756
  ): Promise<void> {
620
- const limitParam = parseInt(ctx.query.get("limit") || "50", 10);
621
- const limit = isNaN(limitParam) ? 50 : Math.min(limitParam, 100);
757
+ const limit = parseLimit(ctx, 50);
622
758
  const cursor = ctx.query.get("cursor");
623
759
 
624
760
  const templateId = getQueryParam(ctx, "templateId");
@@ -639,42 +775,90 @@ export function createHandlers(deps: Deps) {
639
775
  if (search) {
640
776
  conditions.push(
641
777
  or(
642
- like(messageLogs.taskId, `%${search}%`),
643
- like(messageLogs.templateId, `%${search}%`),
644
- like(messageLogs.providerMessageId, `%${search}%`),
645
- like(messageLogs.campaignId, `%${search}%`),
778
+ like(messageLogs.taskId, contains(search)),
779
+ like(messageLogs.templateId, contains(search)),
780
+ like(messageLogs.providerMessageId, contains(search)),
781
+ like(messageLogs.campaignId, contains(search)),
646
782
  )!,
647
783
  );
648
784
  }
649
785
 
650
- if (cursor) {
651
- const cursorDate = new Date(parseInt(cursor, 10));
652
- conditions.push(lt(messageLogs.timestamp, cursorDate));
653
- }
786
+ // One entry per task, newest activity first. Rows are scanned in
787
+ // (timestamp, id) order — a batch of deliveries shares one timestamp, so
788
+ // the timestamp alone cannot mark a place — and a task is listed at its
789
+ // newest row. The cursor is that row for the first task of the next page,
790
+ // and any task with a row newer than the cursor was listed on an earlier
791
+ // page. Paging on a millisecond timestamp over `limit * 2` rows skipped
792
+ // tasks that shared a timestamp and dropped any that did not fit the slice.
793
+ const start = decodeLogCursor(cursor);
794
+ const tsText = sql<string>`${messageLogs.timestamp}::text`;
795
+ const position = (ts: string, id: string) => sql`(${ts}::timestamptz, ${id}::uuid)`;
796
+ const rowKey = sql`(${messageLogs.timestamp}, ${messageLogs.id})`;
797
+
798
+ const order: string[] = [];
799
+ const rowsByTask = new Map<string, (typeof messageLogs.$inferSelect)[]>();
800
+ let nextCursor: string | null = null;
801
+ let scanFrom = start;
802
+ let inclusive = true;
803
+ const batchSize = Math.max(limit * 4, 50);
804
+
805
+ for (let round = 0; round < 50 && nextCursor === null; round++) {
806
+ const batch = await deps.db
807
+ .select({ row: messageLogs, ts: tsText })
808
+ .from(messageLogs)
809
+ .where(
810
+ and(
811
+ ...conditions,
812
+ scanFrom
813
+ ? sql`${rowKey} ${inclusive ? sql`<=` : sql`<`} ${position(scanFrom.ts, scanFrom.id)}`
814
+ : undefined,
815
+ ),
816
+ )
817
+ .orderBy(desc(messageLogs.timestamp), desc(messageLogs.id))
818
+ .limit(batchSize);
819
+
820
+ const fresh = [...new Set(batch.map((b) => b.row.taskId))].filter((t) => !rowsByTask.has(t));
821
+ const listedEarlier = new Set<string>();
822
+ if (start && fresh.length > 0) {
823
+ const newer = await deps.db
824
+ .selectDistinct({ taskId: messageLogs.taskId })
825
+ .from(messageLogs)
826
+ .where(
827
+ and(
828
+ ...conditions,
829
+ inArray(messageLogs.taskId, fresh),
830
+ sql`${rowKey} > ${position(start.ts, start.id)}`,
831
+ ),
832
+ );
833
+ for (const r of newer) listedEarlier.add(r.taskId);
834
+ }
654
835
 
655
- const logs = await deps.db
656
- .select()
657
- .from(messageLogs)
658
- .where(and(...conditions))
659
- .orderBy(desc(messageLogs.timestamp))
660
- .limit(limit * 2);
661
-
662
- // Deduplicate by taskId preserving the latest status per taskId
663
- const deduplicatedMap = new Map<string, (typeof logs)[0]>();
664
- for (const log of logs) {
665
- if (!deduplicatedMap.has(log.taskId)) {
666
- deduplicatedMap.set(log.taskId, log);
667
- } else {
668
- const existing = deduplicatedMap.get(log.taskId)!;
669
- if (existing.status === "dispatched" && log.status !== "dispatched") {
670
- deduplicatedMap.set(log.taskId, log);
836
+ for (const { row, ts } of batch) {
837
+ if (listedEarlier.has(row.taskId)) continue;
838
+ let rows = rowsByTask.get(row.taskId);
839
+ if (!rows) {
840
+ if (order.length === limit) {
841
+ nextCursor = encodeLogCursor(ts, row.id);
842
+ break;
843
+ }
844
+ rows = [];
845
+ order.push(row.taskId);
846
+ rowsByTask.set(row.taskId, rows);
671
847
  }
848
+ rows.push(row);
672
849
  }
850
+
851
+ if (batch.length < batchSize) break;
852
+ const last = batch[batch.length - 1]!;
853
+ scanFrom = { ts: last.ts, id: last.row.id };
854
+ inclusive = false;
673
855
  }
674
- const deduplicatedLogs = Array.from(deduplicatedMap.values()).slice(0, limit);
675
856
 
676
- const nextCursor =
677
- logs.length === limit * 2 ? logs[logs.length - 1]!.timestamp.getTime().toString() : null;
857
+ // The latest outcome, rather than the dispatch that preceded it.
858
+ const deduplicatedLogs = order.map((taskId) => {
859
+ const rows = rowsByTask.get(taskId)!;
860
+ return rows.find((r) => r.status !== "dispatched") ?? rows[0]!;
861
+ });
678
862
 
679
863
  sendJson(res, 200, { logs: deduplicatedLogs, nextCursor });
680
864
  }
@@ -791,8 +975,7 @@ export function createHandlers(deps: Deps) {
791
975
  res: ServerResponse,
792
976
  ctx: RouteContext,
793
977
  ): Promise<void> {
794
- const limitParam = getQueryParam(ctx, "limit");
795
- const limit = limitParam ? Math.min(parseInt(limitParam, 10), 100) : undefined;
978
+ const limit = parseLimit(ctx, undefined);
796
979
  const channel = getQueryParam(ctx, "channel");
797
980
  const topic = getQueryParam(ctx, "topic");
798
981
  let templates = await deps.templateRepo.list(ctx.projectId!);
@@ -842,8 +1025,7 @@ export function createHandlers(deps: Deps) {
842
1025
  res: ServerResponse,
843
1026
  ctx: RouteContext,
844
1027
  ): Promise<void> {
845
- const limitParam = getQueryParam(ctx, "limit");
846
- const limit = limitParam ? Math.min(parseInt(limitParam, 10), 100) : undefined;
1028
+ const limit = parseLimit(ctx, undefined);
847
1029
  const search = getQueryParam(ctx, "search")?.trim().toLowerCase();
848
1030
  let workflows = await deps.workflowRepo.listDefinitions(ctx.projectId!);
849
1031
  if (search) {
@@ -862,7 +1044,9 @@ export function createHandlers(deps: Deps) {
862
1044
  ctx: RouteContext,
863
1045
  ): Promise<void> {
864
1046
  const instanceId = ctx.params.id!;
865
- const workflow = await deps.workflowRepo.getInstance(ctx.projectId!, instanceId);
1047
+ const workflow = isUuid(instanceId)
1048
+ ? await deps.workflowRepo.getInstance(ctx.projectId!, instanceId)
1049
+ : null;
866
1050
  if (!workflow) return sendJson(res, 404, { error: "workflow_not_found", id: instanceId });
867
1051
 
868
1052
  sendJson(res, 200, workflow);
@@ -875,7 +1059,8 @@ export function createHandlers(deps: Deps) {
875
1059
  ctx: RouteContext,
876
1060
  ): Promise<void> {
877
1061
  const instanceId = ctx.params.id!;
878
- const canceled = await deps.workflowRepo.cancelInstance(ctx.projectId!, instanceId);
1062
+ const canceled =
1063
+ isUuid(instanceId) && (await deps.workflowRepo.cancelInstance(ctx.projectId!, instanceId));
879
1064
  if (!canceled) return sendJson(res, 400, { error: "workflow_not_cancelable", id: instanceId });
880
1065
 
881
1066
  logger.info({ instanceId }, "workflow canceled");
@@ -888,8 +1073,7 @@ export function createHandlers(deps: Deps) {
888
1073
  res: ServerResponse,
889
1074
  ctx: RouteContext,
890
1075
  ): Promise<void> {
891
- const limitParam = parseInt(getQueryParam(ctx, "limit") || "50", 10);
892
- const limit = isNaN(limitParam) ? 50 : Math.min(limitParam, 100);
1076
+ const limit = parseLimit(ctx, 50);
893
1077
  const cursor = getQueryParam(ctx, "cursor");
894
1078
  const search = getQueryParam(ctx, "search");
895
1079
  const segment = getQueryParam(ctx, "segment");
@@ -944,7 +1128,7 @@ export function createHandlers(deps: Deps) {
944
1128
  ctx: RouteContext,
945
1129
  ): Promise<void> {
946
1130
  const id = ctx.params.id!;
947
- const deleted = await deps.projectRepo.delete(id);
1131
+ const deleted = isUuid(id) && (await deps.projectRepo.delete(id));
948
1132
  if (!deleted) return sendJson(res, 404, { error: "project_not_found" });
949
1133
 
950
1134
  sendNoContent(res);
@@ -967,7 +1151,7 @@ export function createHandlers(deps: Deps) {
967
1151
 
968
1152
  if (!parsed.success) return sendValidationError(res, parsed.error);
969
1153
 
970
- const updated = await deps.projectRepo.updateSettings(id, parsed.data);
1154
+ const updated = isUuid(id) && (await deps.projectRepo.updateSettings(id, parsed.data));
971
1155
  if (!updated) return sendJson(res, 404, { error: "project_not_found" });
972
1156
 
973
1157
  // Drop the engine's cached throttle overrides so the change applies to the
@@ -997,7 +1181,11 @@ export function createHandlers(deps: Deps) {
997
1181
  .safeParse(await readJsonBody(req));
998
1182
  const role = parsed.success ? parsed.data.role : "admin";
999
1183
 
1000
- const { randomBytes, createHash } = await import("node:crypto");
1184
+ // A key for a project that does not exist would fail the foreign key.
1185
+ if (!isUuid(id) || !(await deps.projectRepo.findThrottleSettings(id))) {
1186
+ return sendJson(res, 404, { error: "project_not_found" });
1187
+ }
1188
+
1001
1189
  const apiKey = `nk_live_${randomBytes(32).toString("hex")}`;
1002
1190
  const apiKeyHash = createHash("sha256").update(apiKey).digest("hex");
1003
1191
 
@@ -1012,6 +1200,7 @@ export function createHandlers(deps: Deps) {
1012
1200
  ctx: RouteContext,
1013
1201
  ): Promise<void> {
1014
1202
  const id = ctx.params.id!;
1203
+ if (!isUuid(id)) return sendJson(res, 404, { error: "project_not_found" });
1015
1204
  const keys = await deps.projectRepo.listApiKeys(id);
1016
1205
  sendJson(res, 200, { keys });
1017
1206
  }
@@ -1023,11 +1212,11 @@ export function createHandlers(deps: Deps) {
1023
1212
  ctx: RouteContext,
1024
1213
  ): Promise<void> {
1025
1214
  const { id, keyId } = ctx.params;
1026
- const deleted = await deps.projectRepo.deleteApiKey(id!, keyId!);
1215
+ const deleted = isUuid(id) && isUuid(keyId) && (await deps.projectRepo.deleteApiKey(id, keyId));
1027
1216
  if (!deleted) return sendJson(res, 404, { error: "key_not_found" });
1028
1217
 
1029
1218
  await deps.redis.native.publish("apikey.invalidated", "*");
1030
- sendJson(res, 204, {});
1219
+ sendNoContent(res);
1031
1220
  }
1032
1221
 
1033
1222
  // ── GET /v1/system/health — getSystemHealth ──────────────────────────────
@@ -1088,31 +1277,76 @@ export function createHandlers(deps: Deps) {
1088
1277
  });
1089
1278
  }
1090
1279
 
1280
+ // Helper to resolve true unconsumed backlog (consumer group lag + pending entries)
1281
+ async function getStreamBacklog(
1282
+ redis: any,
1283
+ streamKey: string,
1284
+ targetGroup?: string,
1285
+ ): Promise<number> {
1286
+ if (!targetGroup) {
1287
+ return await redis.xlen(streamKey);
1288
+ }
1289
+
1290
+ if (typeof redis.xinfo === "function") {
1291
+ try {
1292
+ const groups = await redis.xinfo("GROUPS", streamKey);
1293
+ if (Array.isArray(groups) && groups.length > 0) {
1294
+ for (const item of groups) {
1295
+ const groupData: Record<string, any> = {};
1296
+ if (Array.isArray(item)) {
1297
+ for (let i = 0; i < item.length; i += 2) {
1298
+ groupData[String(item[i])] = item[i + 1];
1299
+ }
1300
+ } else if (item && typeof item === "object") {
1301
+ Object.assign(groupData, item);
1302
+ }
1303
+
1304
+ if (groupData.name === targetGroup) {
1305
+ const pending = typeof groupData.pending === "number" ? groupData.pending : 0;
1306
+ if (typeof groupData.lag === "number") {
1307
+ return groupData.lag + pending;
1308
+ }
1309
+ if (groupData["last-delivered-id"] === "0-0") {
1310
+ const totalLen = await redis.xlen(streamKey);
1311
+ return totalLen + pending;
1312
+ }
1313
+ return pending;
1314
+ }
1315
+ }
1316
+ }
1317
+ } catch {
1318
+ // Group or stream may not exist yet, fallback to xlen
1319
+ }
1320
+ }
1321
+
1322
+ return await redis.xlen(streamKey);
1323
+ }
1324
+
1091
1325
  // ── GET /v1/system/metrics — getSystemMetrics ────────────────────────────
1092
1326
  async function getSystemMetrics(
1093
1327
  _req: IncomingMessage,
1094
1328
  res: ServerResponse,
1095
1329
  ctx: RouteContext,
1096
1330
  ): Promise<void> {
1097
- const streamMap: Record<string, string> = {
1098
- INBOUND_CRITICAL: STREAMS.INBOUND_CRITICAL,
1099
- INBOUND_NORMAL: STREAMS.INBOUND_NORMAL,
1100
- INBOUND_LOW: STREAMS.INBOUND_LOW,
1101
- ENRICHED_NORMAL: STREAMS.ENRICHED_NORMAL,
1102
- OUTBOUND_CRITICAL: STREAMS.OUTBOUND_CRITICAL,
1103
- OUTBOUND_NORMAL: STREAMS.OUTBOUND_NORMAL,
1104
- OUTBOUND_LOW: STREAMS.OUTBOUND_LOW,
1105
- WORKFLOW_INBOUND: STREAMS.WORKFLOW_INBOUND,
1106
- EVENTS_INBOUND: STREAMS.EVENTS_INBOUND,
1107
- DEAD_LETTER: STREAMS.DEAD_LETTER,
1331
+ const streamMap: Record<string, { key: string; group?: string }> = {
1332
+ INBOUND_CRITICAL: { key: STREAMS.INBOUND_CRITICAL, group: CONSUMER_GROUPS.ENRICHER },
1333
+ INBOUND_NORMAL: { key: STREAMS.INBOUND_NORMAL, group: CONSUMER_GROUPS.ENRICHER },
1334
+ INBOUND_LOW: { key: STREAMS.INBOUND_LOW, group: CONSUMER_GROUPS.ENRICHER },
1335
+ ENRICHED_NORMAL: { key: STREAMS.ENRICHED_NORMAL, group: CONSUMER_GROUPS.ENGINE },
1336
+ OUTBOUND_CRITICAL: { key: STREAMS.OUTBOUND_CRITICAL, group: CONSUMER_GROUPS.DELIVERY },
1337
+ OUTBOUND_NORMAL: { key: STREAMS.OUTBOUND_NORMAL, group: CONSUMER_GROUPS.DELIVERY },
1338
+ OUTBOUND_LOW: { key: STREAMS.OUTBOUND_LOW, group: CONSUMER_GROUPS.DELIVERY },
1339
+ WORKFLOW_INBOUND: { key: STREAMS.WORKFLOW_INBOUND, group: CONSUMER_GROUPS.WORKFLOW },
1340
+ EVENTS_INBOUND: { key: STREAMS.EVENTS_INBOUND, group: CONSUMER_GROUPS.EVENTS },
1341
+ DEAD_LETTER: { key: STREAMS.DEAD_LETTER },
1108
1342
  };
1109
1343
 
1110
1344
  const streamDepths: Record<string, number> = {};
1111
1345
  if (ctx.isAdmin !== false) {
1112
- for (const [key, realRedisKey] of Object.entries(streamMap)) {
1346
+ for (const [key, { key: realRedisKey, group }] of Object.entries(streamMap)) {
1113
1347
  try {
1114
- const len = await deps.redis.native.xlen(realRedisKey);
1115
- streamDepths[key] = len;
1348
+ const depth = await getStreamBacklog(deps.redis.native, realRedisKey, group);
1349
+ streamDepths[key] = depth;
1116
1350
  } catch {
1117
1351
  streamDepths[key] = 0;
1118
1352
  }
@@ -1178,41 +1412,40 @@ export function createHandlers(deps: Deps) {
1178
1412
  "COUNT",
1179
1413
  "100",
1180
1414
  );
1181
- const allMessages = (rawEntries || []).map(([id, fields]: [string, string[]]) => {
1182
- const fieldMap: Record<string, string> = {};
1183
- for (let i = 0; i < fields.length; i += 2) {
1184
- fieldMap[fields[i]!] = fields[i + 1]!;
1185
- }
1186
- let payload: any = fieldMap;
1187
- if (fieldMap.payload) {
1188
- try {
1189
- payload = JSON.parse(fieldMap.payload);
1190
- } catch {
1191
- payload = fieldMap.payload;
1192
- }
1193
- }
1194
- return {
1195
- id,
1196
- eventType: fieldMap.eventType || fieldMap.event_type || "unknown",
1197
- payload,
1198
- error: fieldMap.error || fieldMap.reason || "Dead letter payload",
1199
- timestamp: fieldMap.timestamp || new Date().toISOString(),
1200
- };
1201
- });
1415
+ const allMessages = (rawEntries || []).map(([id, fields]: [string, string[]]) =>
1416
+ parseDlqEntry(id, fields),
1417
+ );
1202
1418
 
1203
1419
  const messages = ctx.projectId
1204
- ? allMessages.filter((m) => {
1205
- const pId = m.payload?.projectId ?? m.payload?.project_id ?? (m as any).projectId;
1206
- return pId === ctx.projectId;
1207
- })
1420
+ ? allMessages.filter((m) => m.projectId === ctx.projectId)
1208
1421
  : allMessages;
1209
1422
 
1210
- sendJson(res, 200, { messages: messages.slice(0, 50) });
1423
+ sendJson(res, 200, {
1424
+ messages: messages.slice(0, 50).map((m) => ({
1425
+ id: m.id,
1426
+ eventType: m.eventType,
1427
+ payload: m.payload,
1428
+ error: m.error,
1429
+ timestamp: m.timestamp,
1430
+ originalStream: m.originalStream,
1431
+ })),
1432
+ });
1211
1433
  } catch {
1212
1434
  sendJson(res, 200, { messages: [] });
1213
1435
  }
1214
1436
  }
1215
1437
 
1438
+ /** The entry, or null when it does not exist or belongs to another project. */
1439
+ async function findDlqEntry(ctx: RouteContext, messageId: string): Promise<DlqEntry | null> {
1440
+ // Redis rejects a malformed stream id rather than matching nothing.
1441
+ if (!/^\d+-\d+$/.test(messageId)) return null;
1442
+ const rawEntries = await deps.redis.native.xrange(STREAMS.DEAD_LETTER, messageId, messageId);
1443
+ if (!rawEntries || rawEntries.length === 0 || !rawEntries[0]) return null;
1444
+ const entry = parseDlqEntry(rawEntries[0][0], rawEntries[0][1]);
1445
+ if (ctx.projectId && entry.projectId !== ctx.projectId) return null;
1446
+ return entry;
1447
+ }
1448
+
1216
1449
  // ── POST /v1/dlq/replay — replayDLQMessage ────────────────────────────────
1217
1450
  async function replayDLQMessage(
1218
1451
  req: IncomingMessage,
@@ -1228,46 +1461,35 @@ export function createHandlers(deps: Deps) {
1228
1461
  }
1229
1462
 
1230
1463
  try {
1231
- const rawEntries = await deps.redis.native.xrange(STREAMS.DEAD_LETTER, messageId, messageId);
1232
- if (!rawEntries || rawEntries.length === 0 || !rawEntries[0]) {
1464
+ const entry = await findDlqEntry(ctx, messageId);
1465
+ if (!entry) {
1233
1466
  sendJson(res, 404, { error: "dlq_message_not_found" });
1234
1467
  return;
1235
1468
  }
1236
1469
 
1237
- const fields = rawEntries[0][1];
1238
- const fieldMap: Record<string, string> = {};
1239
- for (let i = 0; i < fields.length; i += 2) {
1240
- fieldMap[fields[i]!] = fields[i + 1]!;
1241
- }
1242
-
1243
- let payload: any = null;
1244
- if (fieldMap.payload) {
1245
- try {
1246
- payload = JSON.parse(fieldMap.payload);
1247
- } catch {}
1248
- }
1249
-
1250
- if (ctx.projectId) {
1251
- const pId = payload?.projectId ?? payload?.project_id ?? (fieldMap as any).projectId;
1252
- if (pId !== ctx.projectId) {
1253
- sendJson(res, 404, { error: "dlq_message_not_found" });
1254
- return;
1255
- }
1256
- }
1257
-
1258
- const priority = fieldMap.priority || "normal";
1259
- const p = getPriorityBucket(priority);
1470
+ // Back onto the stream it failed on: a failed send belongs with delivery,
1471
+ // not at the start of the pipeline, where its payload does not parse.
1472
+ const replayable = new Set<string>(Object.values(STREAMS));
1473
+ replayable.delete(STREAMS.DEAD_LETTER);
1474
+ const inbound =
1475
+ STREAMS[
1476
+ `INBOUND_${getPriorityBucket(entry.payload?.priority ?? entry.fields.priority).toUpperCase()}` as keyof typeof STREAMS
1477
+ ] ?? STREAMS.INBOUND_NORMAL;
1260
1478
  const targetStream =
1261
- STREAMS[`INBOUND_${p.toUpperCase()}` as keyof typeof STREAMS] || STREAMS.INBOUND_NORMAL;
1479
+ entry.originalStream && replayable.has(entry.originalStream)
1480
+ ? entry.originalStream
1481
+ : inbound;
1262
1482
 
1263
1483
  const xaddArgs: string[] = [];
1264
- for (const [k, v] of Object.entries(fieldMap)) {
1265
- xaddArgs.push(k, v);
1484
+ if (entry.event) {
1485
+ xaddArgs.push("data", JSON.stringify(entry.event));
1486
+ } else {
1487
+ for (const [k, v] of Object.entries(entry.fields)) xaddArgs.push(k, v);
1266
1488
  }
1267
1489
  await deps.redis.native.xadd(targetStream, "*", ...xaddArgs);
1268
1490
  await deps.redis.native.xdel(STREAMS.DEAD_LETTER, messageId);
1269
1491
 
1270
- sendJson(res, 200, { success: true, replayedId: messageId });
1492
+ sendJson(res, 200, { success: true, replayedId: messageId, stream: targetStream });
1271
1493
  } catch (err: any) {
1272
1494
  sendJson(res, 500, { error: "replay_failed", message: err.message });
1273
1495
  }
@@ -1283,34 +1505,10 @@ export function createHandlers(deps: Deps) {
1283
1505
  if (!messageId) return sendJson(res, 400, { error: "missing_id" });
1284
1506
 
1285
1507
  try {
1286
- if (ctx.projectId) {
1287
- const rawEntries = await deps.redis.native.xrange(
1288
- STREAMS.DEAD_LETTER,
1289
- messageId,
1290
- messageId,
1291
- );
1292
- if (!rawEntries || rawEntries.length === 0 || !rawEntries[0]) {
1293
- sendJson(res, 404, { error: "dlq_message_not_found" });
1294
- return;
1295
- }
1296
- const fields = rawEntries[0][1];
1297
- const fieldMap: Record<string, string> = {};
1298
- for (let i = 0; i < fields.length; i += 2) {
1299
- fieldMap[fields[i]!] = fields[i + 1]!;
1300
- }
1301
- let payload: any = null;
1302
- if (fieldMap.payload) {
1303
- try {
1304
- payload = JSON.parse(fieldMap.payload);
1305
- } catch {}
1306
- }
1307
- const pId = payload?.projectId ?? payload?.project_id ?? (fieldMap as any).projectId;
1308
- if (pId !== ctx.projectId) {
1309
- sendJson(res, 404, { error: "dlq_message_not_found" });
1310
- return;
1311
- }
1508
+ if (!(await findDlqEntry(ctx, messageId))) {
1509
+ sendJson(res, 404, { error: "dlq_message_not_found" });
1510
+ return;
1312
1511
  }
1313
-
1314
1512
  await deps.redis.native.xdel(STREAMS.DEAD_LETTER, messageId);
1315
1513
  sendJson(res, 200, { success: true });
1316
1514
  } catch (err: any) {
@@ -1324,8 +1522,7 @@ export function createHandlers(deps: Deps) {
1324
1522
  res: ServerResponse,
1325
1523
  ctx: RouteContext,
1326
1524
  ): Promise<void> {
1327
- const limitParam = getQueryParam(ctx, "limit");
1328
- const limit = limitParam ? Math.min(parseInt(limitParam, 10), 100) : 50;
1525
+ const limit = parseLimit(ctx, 50);
1329
1526
  const cursor = getQueryParam(ctx, "cursor");
1330
1527
  const channel = getQueryParam(ctx, "channel");
1331
1528
 
@@ -1595,8 +1792,7 @@ code{background:#f4f4f5;padding:.1rem .35rem;border-radius:4px}</style>
1595
1792
  res: ServerResponse,
1596
1793
  ctx: RouteContext,
1597
1794
  ): Promise<void> {
1598
- const limitParam = parseInt(getQueryParam(ctx, "limit") || "20", 10);
1599
- const limit = isNaN(limitParam) ? 20 : Math.min(Math.max(limitParam, 1), 100);
1795
+ const limit = parseLimit(ctx, 20);
1600
1796
  const search = getQueryParam(ctx, "search")?.trim();
1601
1797
  const channel = getQueryParam(ctx, "channel")?.trim();
1602
1798
  const since = getQueryParam(ctx, "since")?.trim();
@@ -1610,7 +1806,7 @@ code{background:#f4f4f5;padding:.1rem .35rem;border-radius:4px}</style>
1610
1806
  ];
1611
1807
 
1612
1808
  if (search) {
1613
- conditions.push(like(messageLogs.campaignId, `%${search}%`));
1809
+ conditions.push(like(messageLogs.campaignId, contains(search)));
1614
1810
  }
1615
1811
  if (channel) {
1616
1812
  conditions.push(eq(messageLogs.channel, channel as any));
@@ -1712,10 +1908,13 @@ code{background:#f4f4f5;padding:.1rem .35rem;border-radius:4px}</style>
1712
1908
 
1713
1909
  if (ENGAGEMENT.includes(row.kind as Engagement)) {
1714
1910
  bucket[row.kind as Engagement] += n;
1715
- } else {
1716
- // A delivery row. `sent` is every task that reached a provider at all,
1717
- // which is the denominator a bounce rate is measured against.
1911
+ } else if (row.kind === "dispatched") {
1912
+ // `sent` is every task that reached a provider at all, which is the
1913
+ // denominator a bounce rate is measured against. Each attempt logs a
1914
+ // dispatched row besides its outcome row, and the two are grouped
1915
+ // separately, so counting both counted every message twice.
1718
1916
  bucket.sent += n;
1917
+ } else {
1719
1918
  if (row.status === "delivered") bucket.delivered += n;
1720
1919
  if (row.status === "failed") bucket.failed += n;
1721
1920
  }
@@ -1772,8 +1971,7 @@ code{background:#f4f4f5;padding:.1rem .35rem;border-radius:4px}</style>
1772
1971
  res: ServerResponse,
1773
1972
  ctx: RouteContext,
1774
1973
  ): Promise<void> {
1775
- const limitParam = parseInt(getQueryParam(ctx, "limit") || "100", 10);
1776
- const limit = isNaN(limitParam) ? 100 : Math.min(Math.max(limitParam, 1), 500);
1974
+ const limit = parseLimit(ctx, 100, 500);
1777
1975
  const channel = getQueryParam(ctx, "channel");
1778
1976
  const reason = getQueryParam(ctx, "reason");
1779
1977
  const target = getQueryParam(ctx, "target");
@@ -1781,7 +1979,7 @@ code{background:#f4f4f5;padding:.1rem .35rem;border-radius:4px}</style>
1781
1979
  const conditions = [eq(suppressions.projectId, ctx.projectId!)];
1782
1980
  if (channel) conditions.push(eq(suppressions.channel, channel as any));
1783
1981
  if (reason) conditions.push(eq(suppressions.reason, reason));
1784
- if (target) conditions.push(like(suppressions.target, `%${target.toLowerCase().trim()}%`));
1982
+ if (target) conditions.push(like(suppressions.target, contains(target.toLowerCase().trim())));
1785
1983
 
1786
1984
  const rows = await deps.db
1787
1985
  .select()