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
@@ -22,13 +22,40 @@ export async function readRawBody(req: IncomingMessage): Promise<string> {
22
22
  }
23
23
 
24
24
  export async function readJsonBody(req: IncomingMessage): Promise<unknown> {
25
- const raw = await readRawBody(req);
26
- if (raw.trim() === "") return undefined;
27
- try {
28
- return JSON.parse(raw) as unknown;
29
- } catch {
30
- throw new HttpError(400, "malformed_json");
31
- }
25
+ return new Promise<unknown>((resolve, reject) => {
26
+ // Read as UTF-8 strings directly: avoids the Buffer.concat + toString() copy
27
+ // that readRawBody pays. readRawBody is kept for webhook callers that need
28
+ // raw bytes for HMAC verification.
29
+ if (typeof req.setEncoding === "function") {
30
+ req.setEncoding("utf8");
31
+ }
32
+ let body = "";
33
+ let totalLength = 0;
34
+ const MAX_PAYLOAD_SIZE = 5 * 1024 * 1024;
35
+ req.on("data", (chunk: string | Buffer) => {
36
+ const str = typeof chunk === "string" ? chunk : chunk.toString("utf8");
37
+ totalLength += str.length;
38
+ if (totalLength > MAX_PAYLOAD_SIZE) {
39
+ if (typeof req.destroy === "function") req.destroy();
40
+ reject(new HttpError(413, "payload_too_large"));
41
+ return;
42
+ }
43
+ body += str;
44
+ });
45
+ req.on("end", () => {
46
+ const trimmed = body.trim();
47
+ if (!trimmed) {
48
+ resolve(undefined);
49
+ return;
50
+ }
51
+ try {
52
+ resolve(JSON.parse(trimmed) as unknown);
53
+ } catch {
54
+ reject(new HttpError(400, "malformed_json"));
55
+ }
56
+ });
57
+ req.on("error", reject);
58
+ });
32
59
  }
33
60
 
34
61
  export function sendJson(res: ServerResponse, status: number, body: unknown): void {
@@ -23,13 +23,18 @@ import { projects, messageLogs, projectApiKeys, suppressions } from "@/db/schema
23
23
  import { eq, inArray } from "drizzle-orm";
24
24
  import { randomBytes, timingSafeEqual, createHash } from "node:crypto";
25
25
  import { LRUCache, normaliseTarget } from "@/shared/index.js";
26
+ import { transportRegistry } from "@/transport/index.js";
26
27
  import type { Redis } from "@/redis/index.js";
27
28
  import { z } from "zod";
28
29
  import { getMetricsRegistry } from "@/metrics/index.js";
30
+ import { ApiRateLimiter } from "@/rate-limiter/index.js";
29
31
 
30
32
  /** Pub/sub channel used to drop a cached API key across every API process. */
31
33
  export const API_KEY_INVALIDATION_CHANNEL = "apikey.invalidated";
32
34
 
35
+ /** Default window length in milliseconds for API rate limiting (1 minute). */
36
+ export const API_RATE_LIMIT_WINDOW_MS = 60_000;
37
+
33
38
  // ─── Bootstrap ─────────────────────────────────────────────────────────────
34
39
 
35
40
  loadEnv();
@@ -44,10 +49,19 @@ let deps: any;
44
49
  let h: any;
45
50
  // Short-TTL LRU so a hot key does not hit the DB on every request. Kept small
46
51
  // and invalidated on key change so a revoked key stops working promptly.
52
+ interface CachedAuthKey {
53
+ projectId: string;
54
+ projectRateLimitRpm: number;
55
+ keyRole: "admin" | "read_only";
56
+ tokenHash: string;
57
+ }
58
+
47
59
  const AUTH_CACHE_TTL_MS = 60_000;
48
- let authCache = new LRUCache<string, string>(1000, AUTH_CACHE_TTL_MS);
60
+ let authCache = new LRUCache<string, CachedAuthKey>(1000, AUTH_CACHE_TTL_MS);
61
+ let tokenHashToToken = new Map<string, string>();
49
62
  let authSubscriber: Redis | null = null;
50
63
  let router: Router;
64
+ let apiRateLimiter: ApiRateLimiter;
51
65
 
52
66
  export function extractAuthToken(req: Pick<IncomingMessage, "headers">): string | undefined {
53
67
  const authHeader = req.headers["authorization"];
@@ -225,7 +239,12 @@ export async function startApiServer() {
225
239
  process.exit(1);
226
240
  }
227
241
 
228
- redis = new RedisClient({ url: config.REDIS_URL, name: "api", logger });
242
+ redis = RedisClient.shared({ url: config.REDIS_URL, name: "api", logger });
243
+ apiRateLimiter = new ApiRateLimiter({
244
+ redis: redis.native,
245
+ windowMs: API_RATE_LIMIT_WINDOW_MS,
246
+ logger,
247
+ });
229
248
  const dbData = createDatabase({ url: config.DATABASE_URL, applicationName: "api", logger });
230
249
  sql = dbData.sql;
231
250
  db = dbData.db;
@@ -331,25 +350,39 @@ export async function startApiServer() {
331
350
  .get("/ready", handleReady);
332
351
 
333
352
  server = createServer((req, res) => {
334
- void handleRequest(req, res);
353
+ void handleRequest(req, res).catch((err) => {
354
+ logger.error({ err }, "unhandled api request error");
355
+ if (!res.headersSent) {
356
+ sendJson(res, 500, { error: "internal_error" });
357
+ }
358
+ });
335
359
  });
336
360
  server.requestTimeout = 30_000;
337
361
  server.headersTimeout = 10_000;
338
362
  server.keepAliveTimeout = 5_000;
339
363
 
340
364
  async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
341
- const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
365
+ // Fast pathname extraction: avoid allocating a full WHATWG URL object on every
366
+ // request. `new URL()` parses scheme, host, port, path, and query — most of
367
+ // which we never use on the hot path. URLSearchParams is built lazily and only
368
+ // materialises when a handler or the auth block actually needs it.
369
+ const rawUrl = req.url ?? "/";
370
+ const qIdx = rawUrl.indexOf("?");
371
+ const pathname = qIdx === -1 ? rawUrl : rawUrl.slice(0, qIdx);
372
+ let _lazyUrl: URL | null = null;
373
+ const getUrl = (): URL => (_lazyUrl ??= new URL(rawUrl, "http://n"));
374
+ const searchParams = (): URLSearchParams => getUrl().searchParams;
342
375
  const origin = req.headers["origin"] as string | undefined;
343
376
  const allowedOrigins = (config.CORS_ORIGIN ?? "")
344
377
  .split(",")
345
378
  .map((s) => s.trim())
346
379
  .filter(Boolean);
347
380
  const isSessionRoute =
348
- url.pathname.startsWith("/v1/auth/") ||
349
- url.pathname === "/v1/projects" ||
350
- url.pathname.startsWith("/v1/projects/") ||
351
- url.pathname.startsWith("/v1/system/") ||
352
- url.pathname.startsWith("/v1/dlq");
381
+ pathname.startsWith("/v1/auth/") ||
382
+ pathname === "/v1/projects" ||
383
+ pathname.startsWith("/v1/projects/") ||
384
+ pathname.startsWith("/v1/system/") ||
385
+ pathname.startsWith("/v1/dlq");
353
386
 
354
387
  if (isSessionRoute) {
355
388
  if (origin && allowedOrigins.includes(origin)) {
@@ -363,7 +396,7 @@ export async function startApiServer() {
363
396
  res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS");
364
397
  res.setHeader(
365
398
  "Access-Control-Allow-Headers",
366
- "Content-Type, Authorization, x-api-key, x-project-id",
399
+ "Content-Type, Authorization, x-api-key, x-project-id, x-idempotency-key",
367
400
  );
368
401
 
369
402
  if (req.method === "OPTIONS") {
@@ -372,8 +405,8 @@ export async function startApiServer() {
372
405
  return;
373
406
  }
374
407
 
375
- if (url.pathname === "/admin" || url.pathname.startsWith("/admin/")) {
376
- const handled = await handleAdminRequest(req, res, url);
408
+ if (pathname === "/admin" || pathname.startsWith("/admin/")) {
409
+ const handled = await handleAdminRequest(req, res, getUrl());
377
410
  if (handled) return;
378
411
  }
379
412
 
@@ -382,24 +415,23 @@ export async function startApiServer() {
382
415
  let keyRole: "admin" | "read_only" = "admin";
383
416
  let isAdminToken = false;
384
417
 
385
- const isProjectManagement =
386
- url.pathname === "/v1/projects" || url.pathname.startsWith("/v1/projects/");
418
+ const isProjectManagement = pathname === "/v1/projects" || pathname.startsWith("/v1/projects/");
387
419
 
388
420
  // Unsubscribe is reached from a mail client, which has no API key and never
389
421
  // will. The signed token in the URL is the credential, and it authorises
390
422
  // exactly one action for one address.
391
- const isPublicUnsubscribe = url.pathname === "/v1/unsubscribe";
392
- const isPublicAuth = url.pathname === "/v1/auth/login";
423
+ const isPublicUnsubscribe = pathname === "/v1/unsubscribe";
424
+ const isPublicAuth = pathname === "/v1/auth/login";
393
425
 
394
426
  if (
395
- url.pathname.startsWith("/v1/") &&
427
+ pathname.startsWith("/v1/") &&
396
428
  !isProjectManagement &&
397
429
  !isPublicUnsubscribe &&
398
430
  !isPublicAuth
399
431
  ) {
400
432
  let token = extractAuthToken(req);
401
- if (!token && url.searchParams.has("token")) {
402
- token = url.searchParams.get("token") || undefined;
433
+ if (!token && searchParams().has("token")) {
434
+ token = searchParams().get("token") || undefined;
403
435
  }
404
436
 
405
437
  if (!token) {
@@ -427,12 +459,12 @@ export async function startApiServer() {
427
459
  if (isAdminToken) {
428
460
  const headerProjectId =
429
461
  (req.headers["x-project-id"] as string | undefined) ||
430
- url.searchParams.get("projectId") ||
462
+ searchParams().get("projectId") ||
431
463
  undefined;
432
464
  const isProjectAgnostic =
433
- url.pathname.startsWith("/v1/auth/") ||
434
- url.pathname.startsWith("/v1/system/") ||
435
- url.pathname.startsWith("/v1/dlq");
465
+ pathname.startsWith("/v1/auth/") ||
466
+ pathname.startsWith("/v1/system/") ||
467
+ pathname.startsWith("/v1/dlq");
436
468
  if (!headerProjectId && !isProjectAgnostic) {
437
469
  sendJson(res, 400, {
438
470
  error: "bad_request",
@@ -446,14 +478,13 @@ export async function startApiServer() {
446
478
  keyRole = "admin";
447
479
  }
448
480
  } else {
449
- const tokenHash = createHash("sha256").update(token).digest("hex");
450
- const cached = authCache.get(tokenHash);
481
+ const cached = authCache.get(token);
451
482
  if (cached) {
452
- const parts = cached.split(":");
453
- projectId = parts[0];
454
- projectRateLimitRpm = parseInt(parts[1] || "600", 10);
455
- keyRole = parts[2] as "admin" | "read_only";
483
+ projectId = cached.projectId;
484
+ projectRateLimitRpm = cached.projectRateLimitRpm;
485
+ keyRole = cached.keyRole;
456
486
  } else {
487
+ const tokenHash = createHash("sha256").update(token).digest("hex");
457
488
  const rows = await db
458
489
  .select({
459
490
  id: projects.id,
@@ -468,10 +499,20 @@ export async function startApiServer() {
468
499
  sendJson(res, 401, { error: "unauthorized", message: "Invalid or missing API key" });
469
500
  return;
470
501
  }
471
- projectId = rows[0]!.id;
502
+ const matchedProjectId = rows[0]!.id;
503
+ projectId = matchedProjectId;
472
504
  projectRateLimitRpm = rows[0]!.rateLimitRpm ?? 600;
473
505
  keyRole = rows[0]!.role;
474
- authCache.set(tokenHash, `${projectId}:${projectRateLimitRpm}:${keyRole}`);
506
+ authCache.set(token, {
507
+ projectId: matchedProjectId,
508
+ projectRateLimitRpm,
509
+ keyRole,
510
+ tokenHash,
511
+ });
512
+ tokenHashToToken.set(tokenHash, token);
513
+ if (tokenHashToToken.size > 2000) {
514
+ tokenHashToToken.clear();
515
+ }
475
516
  }
476
517
  }
477
518
 
@@ -484,34 +525,20 @@ export async function startApiServer() {
484
525
  }
485
526
  }
486
527
 
487
- // Project rate limit - Sliding Window
488
- const LUA_LIMIT = `
489
- local key = KEYS[1]
490
- local now = tonumber(ARGV[1])
491
- local window = tonumber(ARGV[2])
492
- local maxReqs = tonumber(ARGV[3])
493
- local cutoff = now - window
494
- redis.call("ZREMRANGEBYSCORE", key, "-inf", cutoff)
495
- local count = redis.call("ZCARD", key)
496
- if count < maxReqs then
497
- redis.call("ZADD", key, now, now .. "-" .. ARGV[4])
498
- redis.call("EXPIRE", key, math.ceil(window / 1000))
499
- return count + 1
500
- end
501
- return -1
502
- `;
503
- const rlKey = `rate-limit:api:req:${projectId || "global"}`;
504
- const nowMs = Date.now();
505
- const count = (await redis.native.eval(
506
- LUA_LIMIT,
507
- 1,
508
- rlKey,
509
- nowMs,
510
- 60000,
511
- projectRateLimitRpm,
512
- randomBytes(4).toString("hex"),
513
- )) as number;
514
- if (count === -1) {
528
+ // Project rate limit - In-Memory Token Leasing with Redis Sliding Window
529
+ if (!apiRateLimiter && redis?.native) {
530
+ apiRateLimiter = new ApiRateLimiter({
531
+ redis: redis.native,
532
+ windowMs: API_RATE_LIMIT_WINDOW_MS,
533
+ logger,
534
+ });
535
+ }
536
+
537
+ const allowed = apiRateLimiter
538
+ ? await apiRateLimiter.check(projectId || "global", projectRateLimitRpm)
539
+ : true;
540
+
541
+ if (!allowed) {
515
542
  if (!res.headersSent) {
516
543
  res.setHeader("Retry-After", "60");
517
544
  sendJson(res, 429, {
@@ -594,7 +621,7 @@ export async function startApiServer() {
594
621
  }
595
622
  }
596
623
 
597
- const route = router.match(req.method ?? "GET", url.pathname);
624
+ const route = router.match(req.method ?? "GET", pathname);
598
625
 
599
626
  if (!route) {
600
627
  sendJson(res, 404, { error: "not_found" });
@@ -603,7 +630,7 @@ export async function startApiServer() {
603
630
 
604
631
  const ctx = {
605
632
  params: route.params,
606
- query: url.searchParams,
633
+ query: searchParams(),
607
634
  projectId,
608
635
  role: keyRole,
609
636
  isAdmin: isAdminToken,
@@ -614,22 +641,31 @@ export async function startApiServer() {
614
641
  if (!res.headersSent) sendJson(res, err.status, { error: err.code, message: err.message });
615
642
  return;
616
643
  }
617
- logger.error({ err, path: url.pathname }, "unhandled request error");
644
+ logger.error({ err, path: pathname }, "unhandled request error");
618
645
  if (!res.headersSent) sendJson(res, 500, { error: "internal_error" });
619
646
  });
620
647
  }
621
648
 
622
649
  // Let key rotation take effect immediately instead of waiting out the TTL.
623
- authSubscriber = redis.native.duplicate();
650
+ authSubscriber = redis.native.duplicate({ enableAutoPipelining: false });
624
651
  await authSubscriber.subscribe(API_KEY_INVALIDATION_CHANNEL);
625
652
  authSubscriber.on("message", (channel: string, tokenHash: string) => {
626
653
  if (channel !== API_KEY_INVALIDATION_CHANNEL) return;
627
- if (tokenHash === "*") authCache.clear();
628
- else authCache.delete(tokenHash);
654
+ if (tokenHash === "*") {
655
+ authCache.clear();
656
+ tokenHashToToken.clear();
657
+ apiRateLimiter?.clear();
658
+ } else {
659
+ const token = tokenHashToToken.get(tokenHash);
660
+ if (token) {
661
+ authCache.delete(token);
662
+ tokenHashToToken.delete(tokenHash);
663
+ }
664
+ authCache.delete(tokenHash);
665
+ }
629
666
  logger.info({ tokenHash }, "api key cache invalidated");
630
667
  });
631
668
 
632
- const { transportRegistry } = await import("../../transport/index.js");
633
669
  for (const channel of transportRegistry.registeredChannels()) {
634
670
  const transport = transportRegistry.get(channel as any);
635
671
  if (!transport?.webhookPath) continue;
@@ -839,7 +875,8 @@ export async function stopApiServer(): Promise<void> {
839
875
  }
840
876
  // These are module-scoped, so a restart in the same process must not inherit
841
877
  // the previous instance's cached auth or health.
842
- authCache = new LRUCache<string, string>(1000, AUTH_CACHE_TTL_MS);
878
+ authCache = new LRUCache<string, CachedAuthKey>(1000, AUTH_CACHE_TTL_MS);
879
+ tokenHashToToken.clear();
843
880
  cachedHealth = null;
844
881
  if (sql) await sql.end();
845
882
  if (redis) await redis.disconnect();
@@ -25,12 +25,24 @@ interface Route {
25
25
  /**
26
26
  * Minimal path router with `:param` capture — enough for the REST surface here
27
27
  * without pulling in a framework. First match wins.
28
+ *
29
+ * Routes are indexed by `"METHOD:segmentCount"` so `match()` only inspects the
30
+ * small bucket of routes that share the same method and path depth, instead of
31
+ * scanning all ~35 registered routes on every request.
28
32
  */
29
33
  export class Router {
30
- private readonly routes: Route[] = [];
34
+ /** Indexed buckets: key is `"METHOD:segmentCount"`. */
35
+ private readonly index = new Map<string, Route[]>();
31
36
 
32
37
  add(method: Method, pattern: string, handler: RouteHandler): this {
33
- this.routes.push({ method, segments: split(pattern), handler });
38
+ const route: Route = { method, segments: split(pattern), handler };
39
+ const key = `${method}:${route.segments.length}`;
40
+ let bucket = this.index.get(key);
41
+ if (!bucket) {
42
+ bucket = [];
43
+ this.index.set(key, bucket);
44
+ }
45
+ bucket.push(route);
34
46
  return this;
35
47
  }
36
48
 
@@ -56,10 +68,11 @@ export class Router {
56
68
  pathname: string,
57
69
  ): { handler: RouteHandler; params: Record<string, string> } | null {
58
70
  const parts = split(pathname);
59
- for (const route of this.routes) {
60
- if (route.method !== method) continue;
61
- if (route.segments.length !== parts.length) continue;
71
+ const key = `${method}:${parts.length}`;
72
+ const candidates = this.index.get(key);
73
+ if (!candidates) return null;
62
74
 
75
+ for (const route of candidates) {
63
76
  const params: Record<string, string> = {};
64
77
  let ok = true;
65
78
  for (let i = 0; i < route.segments.length; i++) {