notifkit 0.1.15 → 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 (85) 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-BOmT69OH.mjs → bootstrap-BMDRPjgp.mjs} +1 -1
  5. package/dist/{bulk-ZPiOJRx-.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-CCqcFDDe.mjs → main-6_bXQBDH.mjs} +21 -41
  9. package/dist/{main-BdZvBgV7.mjs → main-8nP3qmCT.mjs} +22 -48
  10. package/dist/{main-C0m9-Eos.mjs → main-B82bsFoy.mjs} +183 -334
  11. package/dist/{main-CTjaZ7ZD.mjs → main-CpaHF1Zw.mjs} +13 -15
  12. package/dist/{main-JEXBLP2A.mjs → main-DULD8-th.mjs} +8 -6
  13. package/dist/{main-C6S3EsJ3.mjs → main-ZW5RaiOK.mjs} +77 -64
  14. package/dist/{main-g33jpia4.mjs → main-g1KEcXXp.mjs} +676 -582
  15. package/dist/{main-24J4U8yP.mjs → main-mGIT8jv4.mjs} +4 -4
  16. package/dist/schedule-or-dispatch-Cd7GLfc3.mjs +52 -0
  17. package/dist/{src-9LXITcNi.mjs → src-BE_EUpZ6.mjs} +93 -93
  18. package/package.json +1 -1
  19. package/scripts/create-project.mjs +6 -2
  20. package/src/client.ts +3 -3
  21. package/src/config/index.ts +1 -0
  22. package/src/contracts/common.ts +2 -0
  23. package/src/contracts/envelope.ts +1 -1
  24. package/src/contracts/events/notification-created.ts +2 -0
  25. package/src/contracts/events/notification-delivered.ts +1 -1
  26. package/src/contracts/events/notification-failed.ts +1 -1
  27. package/src/contracts/events/notification-requested.ts +3 -2
  28. package/src/contracts/helpers.ts +1 -2
  29. package/src/contracts/index.ts +1 -0
  30. package/src/contracts/registry.ts +1 -0
  31. package/src/contracts/sdk.ts +8 -37
  32. package/src/db/schema.ts +8 -13
  33. package/src/idempotency/index.ts +6 -8
  34. package/src/metrics/index.ts +2 -0
  35. package/src/rate-limiter/api-rate-limiter.ts +208 -0
  36. package/src/rate-limiter/index.ts +3 -411
  37. package/src/rate-limiter/project-settings-cache.ts +99 -0
  38. package/src/rate-limiter/user-throttle.ts +100 -0
  39. package/src/redis/index.ts +10 -3
  40. package/src/repositories/admin-user.ts +83 -0
  41. package/src/repositories/contact.ts +359 -0
  42. package/src/repositories/index.ts +9 -1416
  43. package/src/repositories/preference.ts +35 -0
  44. package/src/repositories/project.ts +110 -0
  45. package/src/repositories/segment.ts +16 -0
  46. package/src/repositories/template.ts +72 -0
  47. package/src/repositories/types.ts +49 -0
  48. package/src/repositories/user.ts +644 -0
  49. package/src/repositories/workflow.ts +64 -0
  50. package/src/services/ai/main.ts +29 -71
  51. package/src/services/api/admin-static.ts +4 -1
  52. package/src/services/api/handlers/auth.ts +109 -0
  53. package/src/services/api/handlers/campaigns.ts +191 -0
  54. package/src/services/api/handlers/events.ts +99 -0
  55. package/src/services/api/handlers/notifications.ts +356 -0
  56. package/src/services/api/handlers/projects.ts +116 -0
  57. package/src/services/api/handlers/shared.ts +262 -0
  58. package/src/services/api/handlers/suppressions.ts +95 -0
  59. package/src/services/api/handlers/system.ts +314 -0
  60. package/src/services/api/handlers/templates.ts +97 -0
  61. package/src/services/api/handlers/unsubscribe.ts +215 -0
  62. package/src/services/api/handlers/users.ts +262 -0
  63. package/src/services/api/handlers/workflows.ts +150 -0
  64. package/src/services/api/handlers.ts +25 -2190
  65. package/src/services/api/health.ts +133 -0
  66. package/src/services/api/http.ts +12 -0
  67. package/src/services/api/main.ts +32 -322
  68. package/src/services/api/router.ts +1 -1
  69. package/src/services/api/webhooks.ts +172 -0
  70. package/src/services/delivery/main.ts +256 -498
  71. package/src/services/engine/main.ts +31 -247
  72. package/src/services/engine/quiet-hours.ts +151 -0
  73. package/src/services/engine/schedule-or-dispatch.ts +104 -0
  74. package/src/services/enricher/main.ts +9 -21
  75. package/src/services/events/main.ts +2 -2
  76. package/src/services/scheduler/main.ts +16 -25
  77. package/src/services/workflow/duration.ts +24 -0
  78. package/src/services/workflow/main.ts +6 -164
  79. package/src/services/workflow/timers.ts +157 -0
  80. package/src/shared/events.ts +3 -2
  81. package/src/templates/render.ts +1 -0
  82. package/src/workers/index.ts +7 -4
  83. package/src/workflows/sdk.ts +1 -0
  84. package/dashboard/dist/assets/index-ggpJKZqZ.js +0 -315
  85. package/dashboard/dist/assets/index-s-SXGIwv.css +0 -1
@@ -0,0 +1,262 @@
1
+ import type { Logger } from "@/logger/index.js";
2
+ import type { RedisClient } from "@/redis/index.js";
3
+ import type { StreamProducer } from "@/queue/index.js";
4
+ import type {
5
+ UserRepository,
6
+ ContactRepository,
7
+ TemplateRepository,
8
+ ProjectRepository,
9
+ WorkflowRepository,
10
+ SegmentRepository,
11
+ AdminUserRepository,
12
+ } from "@/repositories/index.js";
13
+ import type { Preferences, UserContactInput, ContactChannel } from "@/contracts/index.js";
14
+ import type { RouteContext } from "../router.js";
15
+ import type { LiveDeliveryEvents } from "../live-events.js";
16
+ import type { Db } from "@/db/index.js";
17
+
18
+ export interface Deps {
19
+ logger: Logger;
20
+ redis: RedisClient;
21
+ producers: Record<string, StreamProducer>;
22
+ userRepo: UserRepository;
23
+ contactRepo: ContactRepository;
24
+ templateRepo: TemplateRepository;
25
+ projectRepo: ProjectRepository;
26
+ workflowRepo: WorkflowRepository;
27
+ segmentRepo: SegmentRepository;
28
+ adminUserRepo?: AdminUserRepository;
29
+ db: Db;
30
+ /** Delivery outcomes for GET /v1/events/stream. */
31
+ liveEvents: LiveDeliveryEvents;
32
+ }
33
+
34
+ // Inline user shape (email/phone/pushToken already normalised to string[] by Zod).
35
+ export interface InlineUserLike {
36
+ id: string;
37
+ language?: string;
38
+ timezone?: string;
39
+ contacts?: UserContactInput[];
40
+ email?: string[];
41
+ phone?: string[];
42
+ pushToken?: string[];
43
+ segments?: string[];
44
+ preferences?: Preferences;
45
+ }
46
+
47
+ interface ResolvedContact {
48
+ channel: ContactChannel;
49
+ target: string;
50
+ label?: string;
51
+ isPrimary?: boolean;
52
+ enabled?: boolean;
53
+ preferences?: Preferences;
54
+ }
55
+
56
+ /** Map an inline or user input's contacts and legacy arrays into resolved contact records. */
57
+ export function contactsOf(user: InlineUserLike): ResolvedContact[] {
58
+ const list: ResolvedContact[] = [];
59
+
60
+ if (user.contacts && Array.isArray(user.contacts)) {
61
+ for (const c of user.contacts) {
62
+ list.push({
63
+ channel: c.channel,
64
+ target: c.target,
65
+ label: c.label,
66
+ isPrimary: c.isPrimary,
67
+ enabled: c.enabled,
68
+ preferences: c.preferences,
69
+ });
70
+ }
71
+ }
72
+
73
+ if (user.email) {
74
+ for (const target of user.email) {
75
+ list.push({ channel: "email", target });
76
+ }
77
+ }
78
+ if (user.phone) {
79
+ for (const target of user.phone) {
80
+ list.push({ channel: "sms", target });
81
+ }
82
+ }
83
+ if (user.pushToken) {
84
+ for (const target of user.pushToken) {
85
+ list.push({ channel: "push", target });
86
+ }
87
+ }
88
+
89
+ return list;
90
+ }
91
+
92
+ /** Persist user records + their contacts in bulk. Shared by addUser and inline notify. */
93
+ export async function persistUsers(
94
+ deps: Deps,
95
+ users: InlineUserLike[],
96
+ projectId: string,
97
+ ): Promise<void> {
98
+ const usersList = users.map((u) => {
99
+ const primaryEmail = u.email?.[0] ?? u.contacts?.find((c) => c.channel === "email")?.target;
100
+
101
+ // Omitted fields stay omitted: the upsert merges what is given into the
102
+ // stored profile, so an inline `{ id, phone }` on notify must not reset the
103
+ // user's timezone, language or email. Defaults are applied when read.
104
+ return {
105
+ userId: u.id,
106
+ language: u.language,
107
+ timezone: u.timezone,
108
+ email: primaryEmail,
109
+ segments: u.segments ?? [],
110
+ preferences: u.preferences ?? {},
111
+ };
112
+ });
113
+
114
+ const contactsList: any[] = [];
115
+ for (const u of users) {
116
+ for (const c of contactsOf(u)) {
117
+ contactsList.push({
118
+ userId: u.id,
119
+ channel: c.channel,
120
+ target: c.target,
121
+ preferences: c.preferences ?? {},
122
+ });
123
+ }
124
+ }
125
+
126
+ await deps.db.transaction(async (tx) => {
127
+ await deps.userRepo.withTx(tx as Db).upsertManyFull(projectId, usersList);
128
+ await deps.contactRepo.withTx(tx as Db).upsertMany(projectId, contactsList);
129
+ });
130
+ }
131
+
132
+ /**
133
+ * A dead-letter entry, read the way StreamConsumer writes it: the original
134
+ * event JSON under `data`, carrying a `dlq` block that records which stream it
135
+ * failed on. Flat `payload`/`eventType` fields are accepted for entries written
136
+ * by hand or by older versions.
137
+ */
138
+ export interface DlqEntry {
139
+ id: string;
140
+ eventType: string;
141
+ payload: any;
142
+ projectId?: string;
143
+ error: string;
144
+ timestamp: string;
145
+ /** The event as it was published, without its `dlq` block. */
146
+ event: Record<string, any> | null;
147
+ originalStream?: string;
148
+ fields: Record<string, string>;
149
+ }
150
+
151
+ export function parseDlqEntry(id: string, rawFields: string[]): DlqEntry {
152
+ const fields: Record<string, string> = {};
153
+ for (let i = 0; i < rawFields.length; i += 2) {
154
+ fields[rawFields[i]!] = rawFields[i + 1]!;
155
+ }
156
+
157
+ let parsed: Record<string, any> | null = null;
158
+ if (fields.data) {
159
+ try {
160
+ parsed = JSON.parse(fields.data);
161
+ } catch {
162
+ parsed = null;
163
+ }
164
+ }
165
+ const { dlq, ...event } = parsed ?? {};
166
+
167
+ let payload: any = fields;
168
+ if (parsed) {
169
+ payload = event.payload;
170
+ } else if (fields.payload) {
171
+ try {
172
+ payload = JSON.parse(fields.payload);
173
+ } catch {
174
+ payload = fields.payload;
175
+ }
176
+ }
177
+
178
+ const ms = Number(id.split("-")[0]);
179
+ return {
180
+ id,
181
+ eventType: event.type ?? fields.eventType ?? fields.event_type ?? "unknown",
182
+ payload,
183
+ projectId: payload?.projectId ?? payload?.project_id ?? fields.projectId,
184
+ error: dlq?.reason ?? fields.error ?? fields.reason ?? "Dead letter payload",
185
+ timestamp:
186
+ dlq?.ackedAt ??
187
+ fields.timestamp ??
188
+ (Number.isFinite(ms) ? new Date(ms).toISOString() : new Date().toISOString()),
189
+ event: parsed ? event : null,
190
+ originalStream: dlq?.originalStream,
191
+ fields,
192
+ };
193
+ }
194
+
195
+ /**
196
+ * Ids that live in uuid columns. Anything else can match no row, and passing it
197
+ * to Postgres fails the query outright — a 500 for what is simply not found.
198
+ */
199
+ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
200
+ export const isUuid = (v: string | undefined): v is string =>
201
+ typeof v === "string" && UUID_RE.test(v);
202
+
203
+ /** Opaque position in the delivery log: a row's full-precision timestamp and id. */
204
+ export function encodeLogCursor(ts: string, id: string): string {
205
+ return Buffer.from(JSON.stringify([ts, id])).toString("base64url");
206
+ }
207
+
208
+ export function decodeLogCursor(
209
+ cursor: string | null | undefined,
210
+ ): { ts: string; id: string } | null {
211
+ if (!cursor) return null;
212
+ // Cursors handed out before this format were a millisecond timestamp.
213
+ if (/^\d+$/.test(cursor)) {
214
+ return {
215
+ ts: new Date(Number(cursor)).toISOString(),
216
+ id: "ffffffff-ffff-ffff-ffff-ffffffffffff",
217
+ };
218
+ }
219
+ try {
220
+ const [ts, id] = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
221
+ if (
222
+ typeof ts === "string" &&
223
+ typeof id === "string" &&
224
+ !Number.isNaN(Date.parse(ts)) &&
225
+ /^[0-9a-f-]{36}$/i.test(id)
226
+ ) {
227
+ return { ts, id };
228
+ }
229
+ } catch {
230
+ // fall through
231
+ }
232
+ return null;
233
+ }
234
+
235
+ /**
236
+ * A LIKE pattern matching `term` anywhere, with the term's own `%`, `_` and
237
+ * `\` taken literally rather than as wildcards.
238
+ */
239
+ export function contains(term: string): string {
240
+ return `%${term.replace(/[\\%_]/g, "\\$&")}%`;
241
+ }
242
+
243
+ export function getQueryParam(ctx: RouteContext, key: string): string | undefined {
244
+ if (!ctx.query) return undefined;
245
+ if (typeof ctx.query.get === "function") {
246
+ return ctx.query.get(key) ?? undefined;
247
+ }
248
+ return (ctx.query as any)[key] ?? undefined;
249
+ }
250
+
251
+ /**
252
+ * Page size from `?limit=`, clamped to [1, max]. Missing or non-numeric
253
+ * values fall back to `fallback`; `undefined` there means "no limit".
254
+ */
255
+ export function parseLimit<F extends number | undefined>(
256
+ ctx: RouteContext,
257
+ fallback: F,
258
+ max = 100,
259
+ ): number | F {
260
+ const n = parseInt(getQueryParam(ctx, "limit") ?? "", 10);
261
+ return Number.isNaN(n) ? fallback : Math.min(Math.max(n, 1), max);
262
+ }
@@ -0,0 +1,95 @@
1
+ import type { IncomingMessage, ServerResponse } from "node:http";
2
+ import { ContactChannelSchema } from "@/contracts/index.js";
3
+ import { readJsonBody, sendJson, sendNoContent, sendValidationError } from "../http.js";
4
+ import type { RouteContext } from "../router.js";
5
+ import { normaliseTarget } from "@/shared/index.js";
6
+ import { eq, desc, and, like } from "drizzle-orm";
7
+ import { suppressions } from "@/db/schema.js";
8
+ import { z } from "zod";
9
+ import { type Deps, contains, getQueryParam, parseLimit } from "./shared.js";
10
+
11
+ export function createSuppressionsHandlers(deps: Deps) {
12
+ async function listSuppressions(
13
+ _req: IncomingMessage,
14
+ res: ServerResponse,
15
+ ctx: RouteContext,
16
+ ): Promise<void> {
17
+ const limit = parseLimit(ctx, 100, 500);
18
+ const channel = getQueryParam(ctx, "channel");
19
+ const reason = getQueryParam(ctx, "reason");
20
+ const target = getQueryParam(ctx, "target");
21
+
22
+ const conditions = [eq(suppressions.projectId, ctx.projectId!)];
23
+ if (channel) conditions.push(eq(suppressions.channel, channel as any));
24
+ if (reason) conditions.push(eq(suppressions.reason, reason));
25
+ if (target) conditions.push(like(suppressions.target, contains(target.toLowerCase().trim())));
26
+
27
+ const rows = await deps.db
28
+ .select()
29
+ .from(suppressions)
30
+ .where(and(...conditions))
31
+ .orderBy(desc(suppressions.createdAt))
32
+ .limit(limit);
33
+
34
+ sendJson(res, 200, { suppressions: rows });
35
+ }
36
+
37
+ async function createSuppression(
38
+ req: IncomingMessage,
39
+ res: ServerResponse,
40
+ ctx: RouteContext,
41
+ ): Promise<void> {
42
+ const parsed = z
43
+ .object({
44
+ channel: ContactChannelSchema,
45
+ target: z.string().min(1),
46
+ reason: z.enum(["unsubscribed", "complained", "bounced", "manual"]).default("manual"),
47
+ })
48
+ .safeParse(await readJsonBody(req));
49
+ if (!parsed.success) return sendValidationError(res, parsed.error);
50
+
51
+ const { channel, target, reason } = parsed.data;
52
+ await deps.db
53
+ .insert(suppressions)
54
+ .values({
55
+ projectId: ctx.projectId!,
56
+ channel,
57
+ target: normaliseTarget(target),
58
+ reason,
59
+ source: "api",
60
+ })
61
+ .onConflictDoNothing();
62
+
63
+ sendJson(res, 201, { channel, target: normaliseTarget(target), reason });
64
+ }
65
+
66
+ // Re-enables sending to an address. Intentionally manual: a suppression
67
+ // records that somebody asked not to be contacted, and undoing that should be
68
+ // a decision rather than a retry.
69
+ async function deleteSuppression(
70
+ _req: IncomingMessage,
71
+ res: ServerResponse,
72
+ ctx: RouteContext,
73
+ ): Promise<void> {
74
+ const { channel, target } = ctx.params;
75
+ if (!channel || !target) return sendJson(res, 400, { error: "missing_channel_or_target" });
76
+
77
+ await deps.db
78
+ .delete(suppressions)
79
+ .where(
80
+ and(
81
+ eq(suppressions.projectId, ctx.projectId!),
82
+ eq(suppressions.channel, channel as any),
83
+ eq(suppressions.target, normaliseTarget(target)),
84
+ ),
85
+ );
86
+
87
+ sendNoContent(res);
88
+ }
89
+
90
+ return {
91
+ listSuppressions,
92
+ createSuppression,
93
+ deleteSuppression,
94
+ };
95
+ }
@@ -0,0 +1,314 @@
1
+ import type { IncomingMessage, ServerResponse } from "node:http";
2
+ import { STREAMS, CONSUMER_GROUPS } from "@/contracts/index.js";
3
+ import { readJsonBody, sendJson } from "../http.js";
4
+ import type { RouteContext } from "../router.js";
5
+ import { getPriorityBucket } from "@/shared/index.js";
6
+ import { eq, and, sql } from "drizzle-orm";
7
+ import { messageLogs } from "@/db/schema.js";
8
+ import { type Deps, type DlqEntry, parseDlqEntry } from "./shared.js";
9
+
10
+ export function createSystemHandlers(deps: Deps) {
11
+ const { logger } = deps;
12
+
13
+ async function getSystemHealth(
14
+ _req: IncomingMessage,
15
+ res: ServerResponse,
16
+ _ctx: RouteContext,
17
+ ): Promise<void> {
18
+ const keys = ["enricher", "engine", "scheduler", "delivery", "ai", "workflow", "events"];
19
+ const workers: Record<string, any> = {};
20
+ let redisOk = false;
21
+ let dbOk = false;
22
+ let redisLatency = 0;
23
+ let dbLatency = 0;
24
+
25
+ const startRedis = Date.now();
26
+ try {
27
+ await deps.redis.native.ping();
28
+ redisOk = true;
29
+ redisLatency = Date.now() - startRedis;
30
+ } catch {
31
+ redisOk = false;
32
+ }
33
+
34
+ const startDb = Date.now();
35
+ try {
36
+ await deps.db.execute(sql`SELECT 1`);
37
+ dbOk = true;
38
+ dbLatency = Date.now() - startDb;
39
+ } catch {
40
+ dbOk = false;
41
+ }
42
+
43
+ if (redisOk) {
44
+ try {
45
+ const vals = await deps.redis.native.mget(keys.map((k) => `notif:health:${k}`));
46
+ for (let i = 0; i < keys.length; i++) {
47
+ const key = keys[i] as string;
48
+ const val = vals[i];
49
+ if (val) {
50
+ workers[key] = JSON.parse(val);
51
+ } else {
52
+ workers[key] = { status: "unknown", message: "No heartbeat" };
53
+ }
54
+ }
55
+ } catch (err: any) {
56
+ for (const key of keys) {
57
+ workers[key] = { status: "error", error: err.message };
58
+ }
59
+ }
60
+ }
61
+
62
+ sendJson(res, 200, {
63
+ status: redisOk && dbOk ? "healthy" : "degraded",
64
+ redis: { ok: redisOk, latencyMs: redisLatency },
65
+ db: { ok: dbOk, latencyMs: dbLatency },
66
+ workers,
67
+ });
68
+ }
69
+
70
+ // Helper to resolve true unconsumed backlog (consumer group lag + pending entries)
71
+ async function getStreamBacklog(
72
+ redis: any,
73
+ streamKey: string,
74
+ targetGroup?: string,
75
+ ): Promise<number> {
76
+ if (!targetGroup) {
77
+ return await redis.xlen(streamKey);
78
+ }
79
+
80
+ if (typeof redis.xinfo === "function") {
81
+ try {
82
+ const groups = await redis.xinfo("GROUPS", streamKey);
83
+ if (Array.isArray(groups) && groups.length > 0) {
84
+ for (const item of groups) {
85
+ const groupData: Record<string, any> = {};
86
+ if (Array.isArray(item)) {
87
+ for (let i = 0; i < item.length; i += 2) {
88
+ groupData[String(item[i])] = item[i + 1];
89
+ }
90
+ } else if (item && typeof item === "object") {
91
+ Object.assign(groupData, item);
92
+ }
93
+
94
+ if (groupData.name === targetGroup) {
95
+ const pending = typeof groupData.pending === "number" ? groupData.pending : 0;
96
+ if (typeof groupData.lag === "number") {
97
+ return groupData.lag + pending;
98
+ }
99
+ if (groupData["last-delivered-id"] === "0-0") {
100
+ const totalLen = await redis.xlen(streamKey);
101
+ return totalLen + pending;
102
+ }
103
+ return pending;
104
+ }
105
+ }
106
+ }
107
+ } catch {
108
+ // Group or stream may not exist yet, fallback to xlen
109
+ }
110
+ }
111
+
112
+ return await redis.xlen(streamKey);
113
+ }
114
+
115
+ async function getSystemMetrics(
116
+ _req: IncomingMessage,
117
+ res: ServerResponse,
118
+ ctx: RouteContext,
119
+ ): Promise<void> {
120
+ const streamMap: Record<string, { key: string; group?: string }> = {
121
+ INBOUND_CRITICAL: { key: STREAMS.INBOUND_CRITICAL, group: CONSUMER_GROUPS.ENRICHER },
122
+ INBOUND_NORMAL: { key: STREAMS.INBOUND_NORMAL, group: CONSUMER_GROUPS.ENRICHER },
123
+ INBOUND_LOW: { key: STREAMS.INBOUND_LOW, group: CONSUMER_GROUPS.ENRICHER },
124
+ ENRICHED_NORMAL: { key: STREAMS.ENRICHED_NORMAL, group: CONSUMER_GROUPS.ENGINE },
125
+ OUTBOUND_CRITICAL: { key: STREAMS.OUTBOUND_CRITICAL, group: CONSUMER_GROUPS.DELIVERY },
126
+ OUTBOUND_NORMAL: { key: STREAMS.OUTBOUND_NORMAL, group: CONSUMER_GROUPS.DELIVERY },
127
+ OUTBOUND_LOW: { key: STREAMS.OUTBOUND_LOW, group: CONSUMER_GROUPS.DELIVERY },
128
+ WORKFLOW_INBOUND: { key: STREAMS.WORKFLOW_INBOUND, group: CONSUMER_GROUPS.WORKFLOW },
129
+ EVENTS_INBOUND: { key: STREAMS.EVENTS_INBOUND, group: CONSUMER_GROUPS.EVENTS },
130
+ DEAD_LETTER: { key: STREAMS.DEAD_LETTER },
131
+ };
132
+
133
+ const streamDepths: Record<string, number> = {};
134
+ if (ctx.isAdmin !== false) {
135
+ for (const [key, { key: realRedisKey, group }] of Object.entries(streamMap)) {
136
+ try {
137
+ const depth = await getStreamBacklog(deps.redis.native, realRedisKey, group);
138
+ streamDepths[key] = depth;
139
+ } catch {
140
+ streamDepths[key] = 0;
141
+ }
142
+ }
143
+ }
144
+
145
+ // Scoped to the caller's project if provided, otherwise aggregate across all projects
146
+ let total = 0;
147
+ let delivered = 0;
148
+
149
+ if (ctx.projectId) {
150
+ const totalTasksRes = await deps.db
151
+ .select({ count: sql<number>`count(distinct ${messageLogs.taskId})` })
152
+ .from(messageLogs)
153
+ .where(eq(messageLogs.projectId, ctx.projectId));
154
+ const deliveredTasksRes = await deps.db
155
+ .select({ count: sql<number>`count(distinct ${messageLogs.taskId})` })
156
+ .from(messageLogs)
157
+ .where(and(eq(messageLogs.projectId, ctx.projectId), eq(messageLogs.status, "delivered")));
158
+
159
+ total = Number(totalTasksRes[0]?.count ?? 0);
160
+ delivered = Number(deliveredTasksRes[0]?.count ?? 0);
161
+ } else {
162
+ const totalTasksRes = await deps.db
163
+ .select({ count: sql<number>`count(distinct ${messageLogs.taskId})` })
164
+ .from(messageLogs);
165
+ const deliveredTasksRes = await deps.db
166
+ .select({ count: sql<number>`count(distinct ${messageLogs.taskId})` })
167
+ .from(messageLogs)
168
+ .where(eq(messageLogs.status, "delivered"));
169
+
170
+ total = Number(totalTasksRes[0]?.count ?? 0);
171
+ delivered = Number(deliveredTasksRes[0]?.count ?? 0);
172
+ }
173
+
174
+ // Project-scoped calls compute failure against their own task count;
175
+ // cluster-wide administrative calls read the global dead letter queue length.
176
+ const failed = ctx.projectId ? Math.max(0, total - delivered) : streamDepths.DEAD_LETTER || 0;
177
+ const successRate = total > 0 ? Number(((delivered / total) * 100).toFixed(2)) : 100;
178
+
179
+ sendJson(res, 200, {
180
+ streams: streamDepths,
181
+ deliveryStats: {
182
+ total,
183
+ delivered,
184
+ failed,
185
+ successRate,
186
+ },
187
+ });
188
+ }
189
+
190
+ async function getDLQMessages(
191
+ _req: IncomingMessage,
192
+ res: ServerResponse,
193
+ ctx: RouteContext,
194
+ ): Promise<void> {
195
+ try {
196
+ const rawEntries = await deps.redis.native.xrevrange(
197
+ STREAMS.DEAD_LETTER,
198
+ "+",
199
+ "-",
200
+ "COUNT",
201
+ "100",
202
+ );
203
+ const allMessages = (rawEntries || []).map(([id, fields]: [string, string[]]) =>
204
+ parseDlqEntry(id, fields),
205
+ );
206
+
207
+ const messages = ctx.projectId
208
+ ? allMessages.filter((m) => m.projectId === ctx.projectId)
209
+ : allMessages;
210
+
211
+ sendJson(res, 200, {
212
+ messages: messages.slice(0, 50).map((m) => ({
213
+ id: m.id,
214
+ eventType: m.eventType,
215
+ payload: m.payload,
216
+ error: m.error,
217
+ timestamp: m.timestamp,
218
+ originalStream: m.originalStream,
219
+ })),
220
+ });
221
+ } catch {
222
+ sendJson(res, 200, { messages: [] });
223
+ }
224
+ }
225
+
226
+ /** The entry, or null when it does not exist or belongs to another project. */
227
+ async function findDlqEntry(ctx: RouteContext, messageId: string): Promise<DlqEntry | null> {
228
+ // Redis rejects a malformed stream id rather than matching nothing.
229
+ if (!/^\d+-\d+$/.test(messageId)) return null;
230
+ const rawEntries = await deps.redis.native.xrange(STREAMS.DEAD_LETTER, messageId, messageId);
231
+ if (!rawEntries || rawEntries.length === 0 || !rawEntries[0]) return null;
232
+ const entry = parseDlqEntry(rawEntries[0][0], rawEntries[0][1]);
233
+ if (ctx.projectId && entry.projectId !== ctx.projectId) return null;
234
+ return entry;
235
+ }
236
+
237
+ async function replayDLQMessage(
238
+ req: IncomingMessage,
239
+ res: ServerResponse,
240
+ ctx: RouteContext,
241
+ ): Promise<void> {
242
+ const body = (await readJsonBody(req)) as any;
243
+ const messageId = body?.id;
244
+
245
+ if (!messageId) {
246
+ sendJson(res, 400, { error: "missing_message_id" });
247
+ return;
248
+ }
249
+
250
+ try {
251
+ const entry = await findDlqEntry(ctx, messageId);
252
+ if (!entry) {
253
+ sendJson(res, 404, { error: "dlq_message_not_found" });
254
+ return;
255
+ }
256
+
257
+ // Back onto the stream it failed on: a failed send belongs with delivery,
258
+ // not at the start of the pipeline, where its payload does not parse.
259
+ const replayable = new Set<string>(Object.values(STREAMS));
260
+ replayable.delete(STREAMS.DEAD_LETTER);
261
+ const inbound =
262
+ STREAMS[
263
+ `INBOUND_${getPriorityBucket(entry.payload?.priority ?? entry.fields.priority).toUpperCase()}` as keyof typeof STREAMS
264
+ ] ?? STREAMS.INBOUND_NORMAL;
265
+ const targetStream =
266
+ entry.originalStream && replayable.has(entry.originalStream)
267
+ ? entry.originalStream
268
+ : inbound;
269
+
270
+ const xaddArgs: string[] = [];
271
+ if (entry.event) {
272
+ xaddArgs.push("data", JSON.stringify(entry.event));
273
+ } else {
274
+ for (const [k, v] of Object.entries(entry.fields)) xaddArgs.push(k, v);
275
+ }
276
+ await deps.redis.native.xadd(targetStream, "*", ...xaddArgs);
277
+ await deps.redis.native.xdel(STREAMS.DEAD_LETTER, messageId);
278
+
279
+ sendJson(res, 200, { success: true, replayedId: messageId, stream: targetStream });
280
+ } catch (err) {
281
+ logger.error({ err, messageId }, "DLQ replay failed");
282
+ sendJson(res, 500, { error: "replay_failed" });
283
+ }
284
+ }
285
+
286
+ async function deleteDLQMessage(
287
+ _req: IncomingMessage,
288
+ res: ServerResponse,
289
+ ctx: RouteContext,
290
+ ): Promise<void> {
291
+ const messageId = ctx.params.id;
292
+ if (!messageId) return sendJson(res, 400, { error: "missing_id" });
293
+
294
+ try {
295
+ if (!(await findDlqEntry(ctx, messageId))) {
296
+ sendJson(res, 404, { error: "dlq_message_not_found" });
297
+ return;
298
+ }
299
+ await deps.redis.native.xdel(STREAMS.DEAD_LETTER, messageId);
300
+ sendJson(res, 200, { success: true });
301
+ } catch (err) {
302
+ logger.error({ err, messageId }, "DLQ delete failed");
303
+ sendJson(res, 500, { error: "delete_failed" });
304
+ }
305
+ }
306
+
307
+ return {
308
+ getSystemHealth,
309
+ getSystemMetrics,
310
+ getDLQMessages,
311
+ replayDLQMessage,
312
+ deleteDLQMessage,
313
+ };
314
+ }