notifkit 0.1.13 → 0.1.15

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 (35) hide show
  1. package/README.md +4 -0
  2. package/dist/{bootstrap-omGPIBny.mjs → bootstrap-BOmT69OH.mjs} +1 -1
  3. package/dist/{bulk-C4hTcnLu.mjs → bulk-ZPiOJRx-.mjs} +1 -1
  4. package/dist/index.d.mts +16 -4
  5. package/dist/index.mjs +2 -2
  6. package/dist/{main-DAXO-MiH.mjs → main-24J4U8yP.mjs} +3 -3
  7. package/dist/{main-BtnGmyaT.mjs → main-BdZvBgV7.mjs} +9 -3
  8. package/dist/{main-B5BwjIMu.mjs → main-C0m9-Eos.mjs} +58 -5
  9. package/dist/{main-DYGCl7Ja.mjs → main-C6S3EsJ3.mjs} +2 -2
  10. package/dist/{main-B-AZ-xoN.mjs → main-CCqcFDDe.mjs} +2 -2
  11. package/dist/{main-Bes11Ad3.mjs → main-CTjaZ7ZD.mjs} +2 -2
  12. package/dist/{main-BU27VjDC.mjs → main-JEXBLP2A.mjs} +2 -2
  13. package/dist/{main-BxAeC_k6.mjs → main-g33jpia4.mjs} +157 -76
  14. package/dist/{src-CIPTzq9i.mjs → src-9LXITcNi.mjs} +64 -39
  15. package/drizzle/0008_delivery_outbox_destination_idx.sql +3 -0
  16. package/drizzle/meta/_journal.json +7 -0
  17. package/package.json +3 -2
  18. package/scripts/create-admin.mjs +8 -0
  19. package/scripts/create-project.mjs +0 -0
  20. package/scripts/migrate.mjs +0 -0
  21. package/scripts/notifkit.mjs +0 -0
  22. package/src/config/index.ts +6 -3
  23. package/src/contracts/streams.ts +4 -0
  24. package/src/db/schema.ts +3 -0
  25. package/src/queue/index.ts +19 -23
  26. package/src/redis/index.ts +20 -0
  27. package/src/services/api/admin-static.ts +21 -11
  28. package/src/services/api/handlers.ts +51 -43
  29. package/src/services/api/http.ts +12 -9
  30. package/src/services/api/live-events.ts +74 -0
  31. package/src/services/api/main.ts +57 -23
  32. package/src/services/delivery/live-events.ts +68 -0
  33. package/src/services/delivery/main.ts +14 -2
  34. package/src/services/engine/main.ts +13 -1
  35. package/dashboard/README.md +0 -29
@@ -18,6 +18,7 @@ import { readJsonBody, readRawBody, sendJson, HttpError } from "./http.js";
18
18
  import { Router } from "./router.js";
19
19
  import { createHandlers } from "./handlers.js";
20
20
  import { handleAdminRequest } from "./admin-static.js";
21
+ import { RedisLiveDeliveryEvents } from "./live-events.js";
21
22
  import { getAdminSession, hashPassword } from "@/services/auth/index.js";
22
23
  import { projects, messageLogs, projectApiKeys, suppressions } from "@/db/schema.js";
23
24
  import { eq, inArray } from "drizzle-orm";
@@ -61,6 +62,7 @@ let authCache = new LRUCache<string, CachedAuthKey>(1000, AUTH_CACHE_TTL_MS);
61
62
  let tokenHashToToken = new Map<string, string>();
62
63
  let authSubscriber: Redis | null = null;
63
64
  let router: Router;
65
+ let liveEvents: RedisLiveDeliveryEvents | null = null;
64
66
  let apiRateLimiter: ApiRateLimiter;
65
67
 
66
68
  export function extractAuthToken(req: Pick<IncomingMessage, "headers">): string | undefined {
@@ -76,17 +78,34 @@ export function extractAuthToken(req: Pick<IncomingMessage, "headers">): string
76
78
  }
77
79
 
78
80
  /**
79
- * Resolves client IP address, respecting reverse proxy headers only when TRUST_PROXY is enabled.
81
+ * What a dashboard user's role may do. `admin_users.role` is free text (the
82
+ * create-admin script takes any value), so only the roles known to grant
83
+ * writes do; anything else, `read_only` included, is read-only.
80
84
  */
81
- export function getClientIp(req: IncomingMessage, trustProxy: boolean): string {
82
- if (trustProxy) {
83
- const forwarded = req.headers["x-forwarded-for"];
84
- if (typeof forwarded === "string") {
85
- const first = forwarded.split(",")[0]?.trim();
86
- if (first) return first;
87
- }
88
- }
89
- return req.socket.remoteAddress || "unknown";
85
+ export function sessionKeyRole(role: string): "admin" | "read_only" {
86
+ return role === "superadmin" || role === "admin" ? "admin" : "read_only";
87
+ }
88
+
89
+ /**
90
+ * Resolves the client address, given how many proxies (TRUST_PROXY) are in
91
+ * front of the API. Each one appends the address it saw to X-Forwarded-For,
92
+ * so the client is `trustedHops` back from the connecting peer. The leftmost
93
+ * entry is the one a client can write itself, so it is used only when the
94
+ * chain is shorter than the configured hops.
95
+ */
96
+ export function getClientIp(req: IncomingMessage, trustedHops: number): string {
97
+ const peer = req.socket.remoteAddress || "unknown";
98
+ const forwarded = req.headers["x-forwarded-for"];
99
+ if (trustedHops <= 0 || typeof forwarded !== "string") return peer;
100
+
101
+ const chain = [
102
+ ...forwarded
103
+ .split(",")
104
+ .map((s) => s.trim())
105
+ .filter(Boolean),
106
+ peer,
107
+ ];
108
+ return chain[Math.max(chain.length - 1 - trustedHops, 0)]!;
90
109
  }
91
110
 
92
111
  async function handleCreateProject(req: IncomingMessage, res: ServerResponse): Promise<void> {
@@ -277,9 +296,11 @@ export async function startApiServer() {
277
296
  }
278
297
  }
279
298
 
299
+ liveEvents = new RedisLiveDeliveryEvents(redis.native, logger);
280
300
  deps = {
281
301
  logger,
282
302
  redis,
303
+ liveEvents,
283
304
  producers,
284
305
  userRepo: new UserRepository(db),
285
306
  contactRepo: new ContactRepository(db),
@@ -443,7 +464,7 @@ export async function startApiServer() {
443
464
  const session = await getAdminSession(redis.native, token);
444
465
  if (session) {
445
466
  isAdminToken = true;
446
- keyRole = session.role === "superadmin" ? "admin" : (session.role as any);
467
+ keyRole = sessionKeyRole(session.role);
447
468
  }
448
469
  } else if (config.ADMIN_API_KEY) {
449
470
  const expectedBuffer = Buffer.from(config.ADMIN_API_KEY);
@@ -559,7 +580,15 @@ export async function startApiServer() {
559
580
  let authorized = false;
560
581
  if (token.startsWith("nk_sess_")) {
561
582
  const session = await getAdminSession(redis.native, token);
562
- if (session) authorized = true;
583
+ if (session) {
584
+ // Creating projects and minting keys hands out admin credentials, so
585
+ // a read-only dashboard user gets to look and nothing more.
586
+ if (sessionKeyRole(session.role) === "read_only" && req.method !== "GET") {
587
+ sendJson(res, 403, { error: "forbidden", message: "Session is read-only" });
588
+ return;
589
+ }
590
+ authorized = true;
591
+ }
563
592
  } else if (config.ADMIN_API_KEY) {
564
593
  const expectedBuffer = Buffer.from(config.ADMIN_API_KEY);
565
594
  const providedBuffer = Buffer.from(token);
@@ -583,11 +612,10 @@ export async function startApiServer() {
583
612
  // an open endpoint cannot be used to hammer the process. Generous, because
584
613
  // a shared corporate egress IP can legitimately produce a burst.
585
614
  if (isPublicUnsubscribe) {
586
- const clientIp = getClientIp(req, Boolean(config.TRUST_PROXY));
615
+ const clientIp = getClientIp(req, config.TRUST_PROXY);
587
616
  try {
588
617
  const key = `rate-limit:api:unsub:${clientIp}`;
589
- const count = await redis.native.incr(key);
590
- if (count === 1) await redis.native.expire(key, 60);
618
+ const count = await redis.native.countRequest(key, 60);
591
619
  if (count > 60) {
592
620
  res.setHeader("Retry-After", "60");
593
621
  sendJson(res, 429, { error: "too_many_requests" });
@@ -603,11 +631,10 @@ export async function startApiServer() {
603
631
  // The login route is unauthenticated and CPU-intensive due to password hashing (scrypt).
604
632
  // Throttle login attempts per IP to prevent credential brute-forcing and CPU exhaustion.
605
633
  if (isPublicAuth) {
606
- const clientIp = getClientIp(req, Boolean(config.TRUST_PROXY));
634
+ const clientIp = getClientIp(req, config.TRUST_PROXY);
607
635
  try {
608
636
  const key = `rate-limit:api:auth:${clientIp}`;
609
- const count = await redis.native.incr(key);
610
- if (count === 1) await redis.native.expire(key, 60);
637
+ const count = await redis.native.countRequest(key, 60);
611
638
  if (count > 10) {
612
639
  res.setHeader("Retry-After", "60");
613
640
  sendJson(res, 429, {
@@ -694,6 +721,7 @@ export async function startApiServer() {
694
721
 
695
722
  if (transport.parseWebhook) {
696
723
  router.post(transport.webhookPath, async (req, res) => {
724
+ let deadline: NodeJS.Timeout | undefined;
697
725
  try {
698
726
  await Promise.race([
699
727
  (async () => {
@@ -835,15 +863,19 @@ export async function startApiServer() {
835
863
  }
836
864
  if (!res.headersSent) sendJson(res, 200, { success: true });
837
865
  })(),
838
- new Promise((_, reject) =>
839
- setTimeout(() => reject(new Error("Webhook processing timeout")), 15000),
840
- ),
866
+ new Promise((_, reject) => {
867
+ deadline = setTimeout(() => reject(new Error("Webhook processing timeout")), 15000);
868
+ }),
841
869
  ]);
842
- } catch (err: any) {
870
+ } catch (err) {
871
+ // The detail is ours to log, not the provider's: providers keep
872
+ // response bodies in their delivery logs.
843
873
  logger.error({ err, channel }, "webhook processing error or timeout");
844
874
  if (!res.headersSent) {
845
- sendJson(res, 500, { error: "internal_error", message: err.message });
875
+ sendJson(res, 500, { error: "internal_error" });
846
876
  }
877
+ } finally {
878
+ clearTimeout(deadline);
847
879
  }
848
880
  });
849
881
  logger.info(`Mounted webhook for ${channel} at ${transport.webhookPath}`);
@@ -873,6 +905,8 @@ export async function stopApiServer(): Promise<void> {
873
905
  authSubscriber.disconnect();
874
906
  authSubscriber = null;
875
907
  }
908
+ await liveEvents?.close();
909
+ liveEvents = null;
876
910
  // These are module-scoped, so a restart in the same process must not inherit
877
911
  // the previous instance's cached auth or health.
878
912
  authCache = new LRUCache<string, CachedAuthKey>(1000, AUTH_CACHE_TTL_MS);
@@ -0,0 +1,68 @@
1
+ import type { EventEmitter } from "node:events";
2
+ import type { Redis } from "@/redis/index.js";
3
+ import { PUBSUB_CHANNELS } from "@/contracts/index.js";
4
+
5
+ /**
6
+ * Delivery outcomes as GET /v1/events/stream relays them. They cross from the
7
+ * delivery worker to the API over Redis pub/sub because the two are separate
8
+ * processes in any deployment that scales them apart; an in-process emitter
9
+ * only ever reached an API that happened to share the delivery's process.
10
+ */
11
+ export type LiveDeliveryEvent =
12
+ | {
13
+ event: "delivery:delivered";
14
+ taskId: string;
15
+ providerMessageId: string;
16
+ channel: string;
17
+ projectId: string;
18
+ }
19
+ | { event: "delivery:failed"; taskId: string; error: string; channel: string; projectId: string };
20
+
21
+ /**
22
+ * How long to stop publishing after a publish nobody was subscribed to. Only
23
+ * a fallback: an API that starts listening says so on DELIVERY_EVENTS_WANTED,
24
+ * which ends the quiet straight away.
25
+ */
26
+ const QUIET_MS = 5_000;
27
+
28
+ /**
29
+ * Forwards the delivery worker's `delivery:*` events to Redis.
30
+ *
31
+ * The API subscribes only while a client has the stream open, so most of the
32
+ * time a publish reaches nobody. PUBLISH says how many received it; after a 0
33
+ * this goes quiet rather than paying a round trip per delivery for no one,
34
+ * until an API announces it is listening.
35
+ */
36
+ export function publishDeliveryEvents(redis: Redis, emitter: EventEmitter): () => void {
37
+ let quietUntil = 0;
38
+ const wanted = redis.duplicate({ enableAutoPipelining: false });
39
+ wanted.on("message", () => (quietUntil = 0));
40
+ wanted.subscribe(PUBSUB_CHANNELS.DELIVERY_EVENTS_WANTED).catch(() => {});
41
+
42
+ const publish = (message: LiveDeliveryEvent) => {
43
+ if (Date.now() < quietUntil) return;
44
+ redis
45
+ .publish(PUBSUB_CHANNELS.DELIVERY_EVENTS, JSON.stringify(message))
46
+ .then((receivers) => {
47
+ if (receivers === 0) quietUntil = Date.now() + QUIET_MS;
48
+ })
49
+ .catch(() => {});
50
+ };
51
+
52
+ const onDelivered = (
53
+ taskId: string,
54
+ providerMessageId: string,
55
+ channel: string,
56
+ projectId: string,
57
+ ) => publish({ event: "delivery:delivered", taskId, providerMessageId, channel, projectId });
58
+ const onFailed = (taskId: string, error: string, channel: string, projectId: string) =>
59
+ publish({ event: "delivery:failed", taskId, error, channel, projectId });
60
+
61
+ emitter.on("delivery:delivered", onDelivered);
62
+ emitter.on("delivery:failed", onFailed);
63
+ return () => {
64
+ emitter.off("delivery:delivered", onDelivered);
65
+ emitter.off("delivery:failed", onFailed);
66
+ wanted.disconnect();
67
+ };
68
+ }
@@ -35,6 +35,7 @@ import {
35
35
  uniqueConsumerId,
36
36
  } from "@/workers/bootstrap.js";
37
37
  import { BatchProcessor, CircuitBreaker } from "@/shared/index.js";
38
+ import { publishDeliveryEvents } from "./live-events.js";
38
39
  import { ProviderThrottle } from "./throttle.js";
39
40
  import { metrics } from "@/metrics/index.js";
40
41
 
@@ -59,6 +60,7 @@ let scheduledProducer: StreamProducer;
59
60
  let enrichedProducers: Record<string, StreamProducer>;
60
61
  let healthInterval: NodeJS.Timeout | null = null;
61
62
  let subscriber: Redis | null = null;
63
+ let stopLiveEvents: (() => void) | null = null;
62
64
 
63
65
  (global as any)._telemetry = (global as any)._telemetry || {
64
66
  count: 0,
@@ -620,7 +622,9 @@ export class DeliveryWorker extends BaseWorker {
620
622
  );
621
623
  }),
622
624
  ]);
623
- if (!res.success && !res.invalidToken) {
625
+ // A permanent rejection is the provider working: returned, not
626
+ // thrown, so the breaker does not count it.
627
+ if (!res.success && !res.invalidToken && res.retryable !== false) {
624
628
  throw providerFailure(res);
625
629
  }
626
630
  return res;
@@ -833,7 +837,10 @@ export class DeliveryWorker extends BaseWorker {
833
837
  );
834
838
  }),
835
839
  ]);
836
- if (!res.success) {
840
+ // A permanent rejection (a bad address) is the provider working:
841
+ // returned, not thrown, so the breaker does not count it. A run
842
+ // of them in one list used to open it for every project.
843
+ if (!res.success && res.retryable !== false) {
837
844
  throw providerFailure(res);
838
845
  }
839
846
  return res;
@@ -1078,6 +1085,9 @@ export async function startDeliveryWorker() {
1078
1085
 
1079
1086
  // ─── Health check interval ──────────────────────────────────────────────────
1080
1087
 
1088
+ // Outcomes for the API's live event stream, which may be in another process.
1089
+ stopLiveEvents = publishDeliveryEvents(redis.native, globalEmitter);
1090
+
1081
1091
  healthInterval = startHealthReporter("delivery", worker, redis, logger);
1082
1092
 
1083
1093
  logger.info(
@@ -1104,4 +1114,6 @@ export async function stopDeliveryWorker(): Promise<void> {
1104
1114
  });
1105
1115
  healthInterval = null;
1106
1116
  subscriber = null;
1117
+ stopLiveEvents?.();
1118
+ stopLiveEvents = null;
1107
1119
  }
@@ -147,7 +147,7 @@ export function isInQuietHours(
147
147
  targetDay = nextDay.getUTCDate();
148
148
  }
149
149
 
150
- const nextActive = localTimeToUtc(
150
+ let nextActive = localTimeToUtc(
151
151
  targetYear,
152
152
  targetMonth,
153
153
  targetDay,
@@ -156,6 +156,18 @@ export function isInQuietHours(
156
156
  0,
157
157
  timezone,
158
158
  );
159
+ // In a DST fall-back hour the end time occurs twice and localTimeToUtc
160
+ // picks the first, which can already be behind us; use the current
161
+ // UTC offset to land on the second occurrence instead.
162
+ if (nextActive.getTime() <= date.getTime()) {
163
+ const currentSec = parseInt(parts.find((p) => p.type === "second")?.value ?? "0", 10);
164
+ const offsetMs =
165
+ Date.UTC(year, month - 1, day, currentHour, currentMin, currentSec) -
166
+ Math.floor(date.getTime() / 1000) * 1000;
167
+ nextActive = new Date(
168
+ Date.UTC(targetYear, targetMonth - 1, targetDay, endH, endM, 0) - offsetMs,
169
+ );
170
+ }
159
171
  return { inQuietHours: true, nextActiveTime: nextActive };
160
172
  }
161
173
  }
@@ -1,29 +0,0 @@
1
- # Notifkit Admin & Observability Dashboard
2
-
3
- This is the single-page application (SPA) admin console and real-time delivery observability dashboard for **Notifkit**, built with **Vite**, **React 19**, **React Router**, **Tailwind CSS v4**, and **shadcn/ui**.
4
-
5
- ## Development
6
-
7
- ```bash
8
- # Start Vite development server
9
- npm run dev
10
-
11
- # Build production bundle to dist/
12
- npm run build
13
-
14
- # Preview built production bundle
15
- npm run preview
16
- ```
17
-
18
- ## Features
19
-
20
- - **Live Activity Feed**: Real-time SSE streaming of delivery statuses and handoffs.
21
- - **Historical Audit Logs**: Queryable, paginated notification lifecycle trails and payload inspector.
22
- - **System Health**: PostgreSQL and Redis latencies and worker heartbeat monitoring.
23
- - **Analytics & Queues**: Real-time Redis Streams queue depth gauges and delivery SLA metrics.
24
- - **Dead Letter Queue (DLQ)**: Poison message diagnostics with stream replay and purge capabilities.
25
- - **Scheduled Pipeline**: Future dispatch scheduling and quiet hours deferrals.
26
- - **Workflows**: Multi-step notification sequence diagrams and instance step execution tracing.
27
- - **Templates**: Channel bindings, dynamic variables, and prompt previewing.
28
- - **User Directory**: Contact channels and opt-out preferences.
29
- - **Projects & API Keys**: Tenant workspace configuration and scoped token provisioning.