notifkit 0.1.12 → 0.1.14

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 (34) hide show
  1. package/README.md +65 -337
  2. package/dashboard/dist/assets/{index-Bsrmo9LE.js → index-ggpJKZqZ.js} +55 -50
  3. package/dashboard/dist/index.html +1 -1
  4. package/dist/{bootstrap-omGPIBny.mjs → bootstrap-m107TukN.mjs} +1 -1
  5. package/dist/{bulk-C4hTcnLu.mjs → bulk-xAd_biYV.mjs} +1 -1
  6. package/dist/index.d.mts +16 -4
  7. package/dist/index.mjs +2 -2
  8. package/dist/{main-BxAeC_k6.mjs → main-5kVwbbnW.mjs} +157 -76
  9. package/dist/{main-DAXO-MiH.mjs → main-C0MjK1Au.mjs} +3 -3
  10. package/dist/{main-Bes11Ad3.mjs → main-C87TSAqM.mjs} +2 -2
  11. package/dist/{main-B-AZ-xoN.mjs → main-CWIBUEc7.mjs} +2 -2
  12. package/dist/{main-BU27VjDC.mjs → main-DRHL2bst.mjs} +2 -2
  13. package/dist/{main-DYGCl7Ja.mjs → main-D_62f9fH.mjs} +2 -2
  14. package/dist/{main-B5BwjIMu.mjs → main-HT5c6jyf.mjs} +58 -5
  15. package/dist/{main-BtnGmyaT.mjs → main-WkxXwP5q.mjs} +2 -2
  16. package/dist/{src-CIPTzq9i.mjs → src-DYqdD694.mjs} +64 -39
  17. package/drizzle/0008_delivery_outbox_destination_idx.sql +3 -0
  18. package/drizzle/meta/_journal.json +7 -0
  19. package/package.json +5 -2
  20. package/scripts/create-admin.mjs +8 -0
  21. package/scripts/create-project.mjs +1 -0
  22. package/scripts/notifkit.mjs +42 -0
  23. package/src/config/index.ts +6 -3
  24. package/src/contracts/streams.ts +4 -0
  25. package/src/db/schema.ts +3 -0
  26. package/src/queue/index.ts +19 -23
  27. package/src/redis/index.ts +20 -0
  28. package/src/services/api/admin-static.ts +21 -11
  29. package/src/services/api/handlers.ts +51 -43
  30. package/src/services/api/http.ts +12 -9
  31. package/src/services/api/live-events.ts +74 -0
  32. package/src/services/api/main.ts +57 -23
  33. package/src/services/delivery/live-events.ts +68 -0
  34. package/src/services/delivery/main.ts +14 -2
@@ -1,7 +1,56 @@
1
- import { $t as STREAMS, B as ApiRateLimiter, C as ContactRepository, Cn as BatchProcessor, D as TemplateRepository, J as metrics, Jt as CONSUMER_GROUPS, K as StreamProducer, On as globalEmitter, Qt as PUBSUB_CHANNELS, Sn as CircuitBreaker, Tn as getPriorityBucket, X as IdempotencyGuard, Zt as OUTBOUND_STREAMS, _ as TemplateCache, c as BaseWorker, d as startHealthReporter, fn as loadEnv, g as transportRegistry, in as registry, pn as parseConfig, qt as buildStreamEvent, rt as deliveryOutbox, st as scheduledPayloads, u as NonRetryableError, un as baseConfigSchema, x as renderWithTemplate } from "./src-CIPTzq9i.mjs";
2
- import { a as uniqueConsumerId, i as shutdownWorker, n as createStreamConsumer, r as createWorkerRuntime, t as createPriorityProducers } from "./bootstrap-omGPIBny.mjs";
3
- import { n as upsertOutboxProviderIds } from "./bulk-C4hTcnLu.mjs";
1
+ import { $t as PUBSUB_CHANNELS, C as ContactRepository, Cn as CircuitBreaker, D as TemplateRepository, En as getPriorityBucket, Jt as buildStreamEvent, Qt as OUTBOUND_STREAMS, V as ApiRateLimiter, Y as metrics, Yt as CONSUMER_GROUPS, Z as IdempotencyGuard, _ as TemplateCache, an as registry, c as BaseWorker, ct as scheduledPayloads, d as startHealthReporter, dn as baseConfigSchema, en as STREAMS, g as transportRegistry, it as deliveryOutbox, kn as globalEmitter, mn as parseConfig, pn as loadEnv, q as StreamProducer, u as NonRetryableError, wn as BatchProcessor, x as renderWithTemplate } from "./src-DYqdD694.mjs";
2
+ import { a as uniqueConsumerId, i as shutdownWorker, n as createStreamConsumer, r as createWorkerRuntime, t as createPriorityProducers } from "./bootstrap-m107TukN.mjs";
3
+ import { n as upsertOutboxProviderIds } from "./bulk-xAd_biYV.mjs";
4
4
  import { sql } from "drizzle-orm";
5
+ //#region src/services/delivery/live-events.ts
6
+ /**
7
+ * How long to stop publishing after a publish nobody was subscribed to. Only
8
+ * a fallback: an API that starts listening says so on DELIVERY_EVENTS_WANTED,
9
+ * which ends the quiet straight away.
10
+ */
11
+ const QUIET_MS = 5e3;
12
+ /**
13
+ * Forwards the delivery worker's `delivery:*` events to Redis.
14
+ *
15
+ * The API subscribes only while a client has the stream open, so most of the
16
+ * time a publish reaches nobody. PUBLISH says how many received it; after a 0
17
+ * this goes quiet rather than paying a round trip per delivery for no one,
18
+ * until an API announces it is listening.
19
+ */
20
+ function publishDeliveryEvents(redis, emitter) {
21
+ let quietUntil = 0;
22
+ const wanted = redis.duplicate({ enableAutoPipelining: false });
23
+ wanted.on("message", () => quietUntil = 0);
24
+ wanted.subscribe(PUBSUB_CHANNELS.DELIVERY_EVENTS_WANTED).catch(() => {});
25
+ const publish = (message) => {
26
+ if (Date.now() < quietUntil) return;
27
+ redis.publish(PUBSUB_CHANNELS.DELIVERY_EVENTS, JSON.stringify(message)).then((receivers) => {
28
+ if (receivers === 0) quietUntil = Date.now() + QUIET_MS;
29
+ }).catch(() => {});
30
+ };
31
+ const onDelivered = (taskId, providerMessageId, channel, projectId) => publish({
32
+ event: "delivery:delivered",
33
+ taskId,
34
+ providerMessageId,
35
+ channel,
36
+ projectId
37
+ });
38
+ const onFailed = (taskId, error, channel, projectId) => publish({
39
+ event: "delivery:failed",
40
+ taskId,
41
+ error,
42
+ channel,
43
+ projectId
44
+ });
45
+ emitter.on("delivery:delivered", onDelivered);
46
+ emitter.on("delivery:failed", onFailed);
47
+ return () => {
48
+ emitter.off("delivery:delivered", onDelivered);
49
+ emitter.off("delivery:failed", onFailed);
50
+ wanted.disconnect();
51
+ };
52
+ }
53
+ //#endregion
5
54
  //#region src/services/delivery/throttle.ts
6
55
  /**
7
56
  * Provider rate limit enforced through locally leased tokens.
@@ -66,6 +115,7 @@ let scheduledProducer;
66
115
  let enrichedProducers;
67
116
  let healthInterval = null;
68
117
  let subscriber = null;
118
+ let stopLiveEvents = null;
69
119
  global._telemetry = global._telemetry || {
70
120
  count: 0,
71
121
  insert: 0,
@@ -476,7 +526,7 @@ var DeliveryWorker = class extends BaseWorker {
476
526
  if (controller.signal.aborted) return reject(controller.signal.reason);
477
527
  controller.signal.addEventListener("abort", () => reject(controller.signal.reason));
478
528
  })]);
479
- if (!res.success && !res.invalidToken) throw providerFailure(res);
529
+ if (!res.success && !res.invalidToken && res.retryable !== false) throw providerFailure(res);
480
530
  return res;
481
531
  } finally {
482
532
  clearTimeout(timeout);
@@ -613,7 +663,7 @@ var DeliveryWorker = class extends BaseWorker {
613
663
  if (controller.signal.aborted) return reject(controller.signal.reason);
614
664
  controller.signal.addEventListener("abort", () => reject(controller.signal.reason));
615
665
  })]);
616
- if (!res.success) throw providerFailure(res);
666
+ if (!res.success && res.retryable !== false) throw providerFailure(res);
617
667
  return res;
618
668
  } finally {
619
669
  clearTimeout(timeout);
@@ -785,6 +835,7 @@ async function startDeliveryWorker() {
785
835
  subscriber = redis.native.duplicate({ enableAutoPipelining: false });
786
836
  await subscriber.subscribe(PUBSUB_CHANNELS.TEMPLATE_INVALIDATED);
787
837
  subscriber.on("message", (_channel, key) => templateCache.invalidateKey(key));
838
+ stopLiveEvents = publishDeliveryEvents(redis.native, globalEmitter);
788
839
  healthInterval = startHealthReporter("delivery", worker, redis, logger);
789
840
  logger.info({
790
841
  env: config.NODE_ENV,
@@ -806,6 +857,8 @@ async function stopDeliveryWorker() {
806
857
  });
807
858
  healthInterval = null;
808
859
  subscriber = null;
860
+ stopLiveEvents?.();
861
+ stopLiveEvents = null;
809
862
  }
810
863
  //#endregion
811
864
  export { DeliveryWorker, MAX_THROTTLE_DEFERRALS, getDeliveryWorker, retryDelayMs, startDeliveryWorker, stopDeliveryWorker };
@@ -1,5 +1,5 @@
1
- import { $t as STREAMS, C as ContactRepository, D as TemplateRepository, Dn as LRUCache, En as normaliseTarget, H as UserThrottle, Jt as CONSUMER_GROUPS, K as StreamProducer, On as globalEmitter, Qt as PUBSUB_CHANNELS, T as ProjectRepository, Tn as getPriorityBucket, V as ProjectSettingsCache, X as IdempotencyGuard, Yt as ENRICHED_STREAMS, _ as TemplateCache, c as BaseWorker, ct as suppressions, d as startHealthReporter, f as buildUnsubscribeHeaders, fn as loadEnv, in as registry, mn as readBaseConfig, qt as buildStreamEvent, st as scheduledPayloads, xn as DataLoader } from "./src-CIPTzq9i.mjs";
2
- import { a as uniqueConsumerId, i as shutdownWorker, n as createStreamConsumer, r as createWorkerRuntime, t as createPriorityProducers } from "./bootstrap-omGPIBny.mjs";
1
+ import { $t as PUBSUB_CHANNELS, C as ContactRepository, D as TemplateRepository, Dn as normaliseTarget, En as getPriorityBucket, H as ProjectSettingsCache, Jt as buildStreamEvent, On as LRUCache, Sn as DataLoader, T as ProjectRepository, U as UserThrottle, Xt as ENRICHED_STREAMS, Yt as CONSUMER_GROUPS, Z as IdempotencyGuard, _ as TemplateCache, an as registry, c as BaseWorker, ct as scheduledPayloads, d as startHealthReporter, en as STREAMS, f as buildUnsubscribeHeaders, hn as readBaseConfig, kn as globalEmitter, lt as suppressions, pn as loadEnv, q as StreamProducer } from "./src-DYqdD694.mjs";
2
+ import { a as uniqueConsumerId, i as shutdownWorker, n as createStreamConsumer, r as createWorkerRuntime, t as createPriorityProducers } from "./bootstrap-m107TukN.mjs";
3
3
  import { randomUUID } from "node:crypto";
4
4
  import { and, eq } from "drizzle-orm";
5
5
  //#region src/services/engine/main.ts
@@ -397,10 +397,13 @@ const baseConfigSchema = z.object({
397
397
  */
398
398
  UNSUBSCRIBE_SECRET: z.string().min(16).optional(),
399
399
  /**
400
- * When true, trusts X-Forwarded-For headers from reverse proxies for client IP resolution.
401
- * Defaults to false to prevent client-spoofed headers from bypassing rate limits.
400
+ * How many reverse proxies sit in front of the API, for reading the client
401
+ * address out of X-Forwarded-For. `true` means one. Each proxy appends the
402
+ * address it saw, so the client is that many entries from the right; the
403
+ * entries further left are whatever the client sent. Defaults to 0, which
404
+ * ignores the header so it cannot be used to get around rate limits.
402
405
  */
403
- TRUST_PROXY: z.string().optional().transform((v) => v === "true" || v === "1"),
406
+ TRUST_PROXY: z.string().optional().transform((v) => v === "true" ? 1 : v && /^\d+$/.test(v) ? Number(v) : 0),
404
407
  /**
405
408
  * Comma-separated list of allowed origins for CORS on session-authenticated admin routes.
406
409
  */
@@ -567,7 +570,11 @@ const PUBSUB_CHANNELS = {
567
570
  /** Payload: `{projectId}`. Published when project settings change. */
568
571
  PROJECT_INVALIDATED: "project.invalidated",
569
572
  /** Payload: a token hash, or `*` for the whole cache. */
570
- API_KEY_INVALIDATED: "apikey.invalidated"
573
+ API_KEY_INVALIDATED: "apikey.invalidated",
574
+ /** Delivery outcomes for GET /v1/events/stream; see services/delivery/live-events. */
575
+ DELIVERY_EVENTS: "delivery.events",
576
+ /** An API began listening on DELIVERY_EVENTS: delivery workers resume publishing. */
577
+ DELIVERY_EVENTS_WANTED: "delivery.events.wanted"
571
578
  };
572
579
  const CONSUMER_GROUPS = {
573
580
  ENRICHER: "notifkit:group:enricher",
@@ -1280,11 +1287,14 @@ const deliveryOutbox = pgTable("delivery_outbox", {
1280
1287
  destination: text("destination").notNull(),
1281
1288
  providerMessageId: varchar("provider_message_id"),
1282
1289
  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull()
1283
- }, (table) => ({ pk: primaryKey({ columns: [
1284
- table.taskId,
1285
- table.channel,
1286
- table.destination
1287
- ] }) }));
1290
+ }, (table) => ({
1291
+ pk: primaryKey({ columns: [
1292
+ table.taskId,
1293
+ table.channel,
1294
+ table.destination
1295
+ ] }),
1296
+ destinationIdx: index("delivery_outbox_destination_idx").on(table.destination)
1297
+ }));
1288
1298
  const scheduledPayloads = pgTable("scheduled_payloads", {
1289
1299
  taskId: varchar("task_id").primaryKey(),
1290
1300
  payload: jsonb("payload").notNull(),
@@ -1672,11 +1682,7 @@ var StreamProducer = class {
1672
1682
  try {
1673
1683
  if (typeof this.redis.pipeline === "function") {
1674
1684
  const pipeline = this.redis.pipeline();
1675
- for (let i = 0; i < batch.length; i++) {
1676
- const item = batch[i];
1677
- if (i === batch.length - 1) pipeline.xadd(this.stream, "MAXLEN", "~", String(this.maxLen), "*", "data", JSON.stringify(item.event));
1678
- else pipeline.xadd(this.stream, "*", "data", JSON.stringify(item.event));
1679
- }
1685
+ for (const item of batch) pipeline.xadd(this.stream, "*", "data", JSON.stringify(item.event));
1680
1686
  const results = await pipeline.exec();
1681
1687
  if (!results) throw new Error(`Pipeline execution failed for ${this.stream}`);
1682
1688
  for (let i = 0; i < results.length; i++) {
@@ -1687,7 +1693,7 @@ var StreamProducer = class {
1687
1693
  } else for (let i = 0; i < batch.length; i++) {
1688
1694
  const item = batch[i];
1689
1695
  try {
1690
- const msgId = await this.redis.xadd(this.stream, "MAXLEN", "~", String(this.maxLen), "*", "data", JSON.stringify(item.event));
1696
+ const msgId = await this.redis.xadd(this.stream, "*", "data", JSON.stringify(item.event));
1691
1697
  if (!msgId) throw new Error(`XADD to ${this.stream} returned null`);
1692
1698
  item.resolve(msgId);
1693
1699
  } catch (err) {
@@ -1710,7 +1716,7 @@ var StreamProducer = class {
1710
1716
  stream,
1711
1717
  len,
1712
1718
  maxLen: this.maxLen
1713
- }, "stream is nearing MAXLEN limit (80%+)");
1719
+ }, "stream backlog is past 80% of QUEUE_MAX_LEN — consumers are falling behind");
1714
1720
  const dlqLen = await this.redis.xlen(STREAMS.DEAD_LETTER);
1715
1721
  metrics.queueSize.set({ stream: STREAMS.DEAD_LETTER }, dlqLen);
1716
1722
  } catch (err) {
@@ -1804,8 +1810,10 @@ var StreamConsumer = class {
1804
1810
  })]);
1805
1811
  } catch (err) {
1806
1812
  if (err.message === "XREADGROUP_TIMEOUT_DEAD_CONNECTION") {
1807
- this.logger?.warn("XREADGROUP took too long, assuming dead connection. Disconnecting...");
1808
- this.blockingRedis.disconnect();
1813
+ this.logger?.warn("XREADGROUP took too long, assuming dead connection. Reconnecting...");
1814
+ const dead = this.blockingRedis;
1815
+ this.blockingRedis = this.redis.duplicate({ enableAutoPipelining: false });
1816
+ dead.disconnect();
1809
1817
  throw err;
1810
1818
  }
1811
1819
  throw err;
@@ -1871,7 +1879,7 @@ var StreamConsumer = class {
1871
1879
  /**
1872
1880
  * Acks and then deletes the entries. Every stream is read by exactly one
1873
1881
  * consumer group, so an acked entry is never read again; leaving it in place
1874
- * holds Redis memory until MAXLEN trims it, and a group recreated from "0"
1882
+ * holds Redis memory for good, and a group recreated from "0"
1875
1883
  * (ensureGroup) would process it a second time. Both commands are issued
1876
1884
  * before either is awaited, so auto-pipelining sends them in one round trip,
1877
1885
  * and Redis runs them in order.
@@ -2360,6 +2368,19 @@ const LUA_SCHEDULER_POLL = `
2360
2368
  end
2361
2369
  return tasks
2362
2370
  `;
2371
+ /**
2372
+ * Fixed-window request counter: INCR, and an expiry whenever the key has none.
2373
+ * One script so the two cannot come apart. With INCR and EXPIRE sent
2374
+ * separately, a failure between them left a counter with no expiry, and the
2375
+ * address it counted stayed over its limit for good.
2376
+ */
2377
+ const LUA_COUNT_REQUEST = `
2378
+ local count = redis.call('INCR', KEYS[1])
2379
+ if redis.call('TTL', KEYS[1]) < 0 then
2380
+ redis.call('EXPIRE', KEYS[1], ARGV[1])
2381
+ end
2382
+ return count
2383
+ `;
2363
2384
  /** Two-phase idempotency lease acquisition. Checks sent/legacy, then attempts SET NX lock. */
2364
2385
  const LUA_ACQUIRE_LEASE = `
2365
2386
  if redis.call('EXISTS', KEYS[1]) == 1 or redis.call('EXISTS', KEYS[3]) == 1 then
@@ -2411,6 +2432,10 @@ function registerCustomCommands(redis) {
2411
2432
  numberOfKeys: 3,
2412
2433
  lua: LUA_ACQUIRE_LEASE
2413
2434
  });
2435
+ redis.defineCommand("countRequest", {
2436
+ numberOfKeys: 1,
2437
+ lua: LUA_COUNT_REQUEST
2438
+ });
2414
2439
  redis.defineCommand("markProcessed", {
2415
2440
  numberOfKeys: 3,
2416
2441
  lua: LUA_MARK_PROCESSED
@@ -4169,35 +4194,35 @@ var NotifkitServer = class extends EventEmitter {
4169
4194
  }
4170
4195
  const startupPromises = [];
4171
4196
  if (services.includes("api")) {
4172
- const { startApiServer } = await import("./main-BxAeC_k6.mjs");
4197
+ const { startApiServer } = await import("./main-5kVwbbnW.mjs");
4173
4198
  startupPromises.push(startApiServer());
4174
4199
  }
4175
4200
  if (services.includes("delivery")) {
4176
- const { startDeliveryWorker } = await import("./main-B5BwjIMu.mjs");
4201
+ const { startDeliveryWorker } = await import("./main-HT5c6jyf.mjs");
4177
4202
  startupPromises.push(startDeliveryWorker());
4178
4203
  }
4179
4204
  if (services.includes("engine")) {
4180
- const { startEngineWorker } = await import("./main-BtnGmyaT.mjs");
4205
+ const { startEngineWorker } = await import("./main-WkxXwP5q.mjs");
4181
4206
  startupPromises.push(startEngineWorker());
4182
4207
  }
4183
4208
  if (services.includes("enricher")) {
4184
- const { startEnricherWorker } = await import("./main-BU27VjDC.mjs");
4209
+ const { startEnricherWorker } = await import("./main-DRHL2bst.mjs");
4185
4210
  startupPromises.push(startEnricherWorker());
4186
4211
  }
4187
4212
  if (services.includes("scheduler")) {
4188
- const { startSchedulerWorker } = await import("./main-Bes11Ad3.mjs");
4213
+ const { startSchedulerWorker } = await import("./main-C87TSAqM.mjs");
4189
4214
  startupPromises.push(startSchedulerWorker());
4190
4215
  }
4191
4216
  if (services.includes("ai")) {
4192
- const { startAiWorker } = await import("./main-B-AZ-xoN.mjs");
4217
+ const { startAiWorker } = await import("./main-CWIBUEc7.mjs");
4193
4218
  startupPromises.push(startAiWorker());
4194
4219
  }
4195
4220
  if (services.includes("workflow")) {
4196
- const { startWorkflowWorker } = await import("./main-DYGCl7Ja.mjs");
4221
+ const { startWorkflowWorker } = await import("./main-D_62f9fH.mjs");
4197
4222
  startupPromises.push(startWorkflowWorker());
4198
4223
  }
4199
4224
  if (services.includes("events")) {
4200
- const { startEventWorker } = await import("./main-DAXO-MiH.mjs");
4225
+ const { startEventWorker } = await import("./main-C0MjK1Au.mjs");
4201
4226
  startupPromises.push(startEventWorker());
4202
4227
  }
4203
4228
  const handleSignal = async (signal) => {
@@ -4219,9 +4244,9 @@ var NotifkitServer = class extends EventEmitter {
4219
4244
  await Promise.all(startupPromises);
4220
4245
  if (readBaseConfig().PIPELINE_FUSED && services.includes("enricher") && services.includes("engine") && services.includes("delivery")) {
4221
4246
  const [{ getEnricherWorker }, { getEngineWorker }, { getDeliveryWorker }] = await Promise.all([
4222
- import("./main-BU27VjDC.mjs"),
4223
- import("./main-BtnGmyaT.mjs"),
4224
- import("./main-B5BwjIMu.mjs")
4247
+ import("./main-DRHL2bst.mjs"),
4248
+ import("./main-WkxXwP5q.mjs"),
4249
+ import("./main-HT5c6jyf.mjs")
4225
4250
  ]);
4226
4251
  const enricher = getEnricherWorker();
4227
4252
  const engine = getEngineWorker();
@@ -4252,14 +4277,14 @@ var NotifkitServer = class extends EventEmitter {
4252
4277
  "events"
4253
4278
  ] : this.options.services;
4254
4279
  const shutdownOrder = [
4255
- ["api", async () => (await import("./main-BxAeC_k6.mjs")).stopApiServer()],
4256
- ["workflow", async () => (await import("./main-DYGCl7Ja.mjs")).stopWorkflowWorker()],
4257
- ["enricher", async () => (await import("./main-BU27VjDC.mjs")).stopEnricherWorker()],
4258
- ["ai", async () => (await import("./main-B-AZ-xoN.mjs")).stopAiWorker()],
4259
- ["engine", async () => (await import("./main-BtnGmyaT.mjs")).stopEngineWorker()],
4260
- ["scheduler", async () => (await import("./main-Bes11Ad3.mjs")).stopSchedulerWorker()],
4261
- ["delivery", async () => (await import("./main-B5BwjIMu.mjs")).stopDeliveryWorker()],
4262
- ["events", async () => (await import("./main-DAXO-MiH.mjs")).stopEventWorker()]
4280
+ ["api", async () => (await import("./main-5kVwbbnW.mjs")).stopApiServer()],
4281
+ ["workflow", async () => (await import("./main-D_62f9fH.mjs")).stopWorkflowWorker()],
4282
+ ["enricher", async () => (await import("./main-DRHL2bst.mjs")).stopEnricherWorker()],
4283
+ ["ai", async () => (await import("./main-CWIBUEc7.mjs")).stopAiWorker()],
4284
+ ["engine", async () => (await import("./main-WkxXwP5q.mjs")).stopEngineWorker()],
4285
+ ["scheduler", async () => (await import("./main-C87TSAqM.mjs")).stopSchedulerWorker()],
4286
+ ["delivery", async () => (await import("./main-HT5c6jyf.mjs")).stopDeliveryWorker()],
4287
+ ["events", async () => (await import("./main-C0MjK1Au.mjs")).stopEventWorker()]
4263
4288
  ];
4264
4289
  for (const [name, stop] of shutdownOrder) if (services.includes(name)) await stop();
4265
4290
  if (this.pgContainer) {
@@ -4273,4 +4298,4 @@ var NotifkitServer = class extends EventEmitter {
4273
4298
  }
4274
4299
  };
4275
4300
  //#endregion
4276
- export { migrateDatabase as $, STREAMS as $t, LUA_ACQUIRE_LEASE as A, AddUserSchema as At, ApiRateLimiter as B, TemplateSchema as Bt, ContactRepository as C, BatchProcessor as Cn, NotificationScheduledPayloadSchema as Ct, TemplateRepository as D, LRUCache as Dn, NotificationRequestedPayloadSchema as Dt, SegmentRepository as E, normaliseTarget as En, NotificationCreatedPayloadSchema as Et, LUA_SCHEDULER_POLL as F, InlineUserSchema as Ft, StreamConsumer as G, WorkflowNotifyPayloadSchema as Gt, UserThrottle as H, UpdateProjectSchema as Ht, LUA_USER_THROTTLE as I, NotifyRequestSchema as It, metrics as J, CONSUMER_GROUPS as Jt, StreamProducer as K, WorkflowStepSchema as Kt, Redis as L, PreferencesSchema as Lt, LUA_MARK_PROCESSED as M, ContactChannelSchema as Mt, LUA_RELEASE_LOCK as N, CreateWorkflowSchema as Nt, UserRepository as O, globalEmitter as On, NotificationTargetSchema as Ot, LUA_RENEW_LOCK as P, IngestEventSchema as Pt, createDatabase as Q, PUBSUB_CHANNELS as Qt, RedisClient as R, QuietHoursSchema as Rt, AdminUserRepository as S, CircuitBreaker as Sn, RenderedContentSchema as St, ProjectRepository as T, getPriorityBucket as Tn, RecipientProfileSchema as Tt, calculateTokenBatchSize as U, UpdateUserSchema as Ut, ProjectSettingsCache as V, TriggerWorkflowSchema as Vt, PendingMessageScanner as W, UserContactInputSchema as Wt, IdempotencyGuard as X, INBOUND_STREAMS as Xt, createLogger as Y, ENRICHED_STREAMS as Yt, assertTablesInSchema as Z, OUTBOUND_STREAMS as Zt, TemplateCache as _, AppError as _n, NotificationSkippedPayloadSchema as _t, SuspendExecutionError as a, EventMetadataSchema as an, projectApiKeys as at, interpolate as b, sleep as bn, DeliveryOptionsSchema as bt, BaseWorker as c, NotificationStatusSchema as cn, suppressions as ct, startHealthReporter as d, getAiConfig as dn, workflowDefinitions as dt, EventEnvelopeSchema as en, notifkitTableNames as et, buildUnsubscribeHeaders as f, loadEnv as fn, workflowInstances as ft, transportRegistry as g, setGlobalConfig as gn, NotificationCanceledPayloadSchema as gt, registerTransport as h, setAiConfig as hn, NotificationAiPendingPayloadSchema as ht, workflowRegistry as i, registry as in, messageLogs as it, LUA_LEASE_API_RATE_LIMIT as j, BatchAddContactsSchema as jt, WorkflowRepository as k, AddContactSchema as kt, LockHeldError as l, AI_DEFAULTS as ln, userTopicPreferences as lt, verifyUnsubscribeToken as m, readBaseConfig as mn, workflowWaiters as mt, NotifkitClient as n, StreamEventSchema as nn, runMigrations as nt, buildStepNotifyPayload as o, NotificationChannelSchema as on, projects as ot, signUnsubscribeToken as p, parseConfig as pn, workflowSteps as pt, getMetricsRegistry as q, buildStreamEvent as qt, workflow as r, EventRegistry as rn, deliveryOutbox as rt, resolveStepTarget as s, NotificationPrioritySchema as sn, scheduledPayloads as st, NotifkitServer as t, StreamEventMetadataSchema as tn, qualifyMigrationSql as tt, NonRetryableError as u, baseConfigSchema as un, users as ut, escapeHeader as v, ValidationError as vn, NotificationFailedPayloadSchema as vt, PreferenceRepository as w, AsyncSemaphore as wn, NotificationEnrichedPayloadSchema as wt, renderWithTemplate as x, DataLoader as xn, NotificationDispatchedPayloadSchema as xt, escapeHtml as y, generateId as yn, NotificationDeliveredPayloadSchema as yt, registerCustomCommands as z, SyncTemplatesSchema as zt };
4301
+ export { createDatabase as $, PUBSUB_CHANNELS as $t, LUA_ACQUIRE_LEASE as A, AddContactSchema as At, registerCustomCommands as B, SyncTemplatesSchema as Bt, ContactRepository as C, CircuitBreaker as Cn, RenderedContentSchema as Ct, TemplateRepository as D, normaliseTarget as Dn, NotificationCreatedPayloadSchema as Dt, SegmentRepository as E, getPriorityBucket as En, RecipientProfileSchema as Et, LUA_RENEW_LOCK as F, IngestEventSchema as Ft, PendingMessageScanner as G, UserContactInputSchema as Gt, ProjectSettingsCache as H, TriggerWorkflowSchema as Ht, LUA_SCHEDULER_POLL as I, InlineUserSchema as It, getMetricsRegistry as J, buildStreamEvent as Jt, StreamConsumer as K, WorkflowNotifyPayloadSchema as Kt, LUA_USER_THROTTLE as L, NotifyRequestSchema as Lt, LUA_LEASE_API_RATE_LIMIT as M, BatchAddContactsSchema as Mt, LUA_MARK_PROCESSED as N, ContactChannelSchema as Nt, UserRepository as O, LRUCache as On, NotificationRequestedPayloadSchema as Ot, LUA_RELEASE_LOCK as P, CreateWorkflowSchema as Pt, assertTablesInSchema as Q, OUTBOUND_STREAMS as Qt, Redis as R, PreferencesSchema as Rt, AdminUserRepository as S, DataLoader as Sn, NotificationDispatchedPayloadSchema as St, ProjectRepository as T, AsyncSemaphore as Tn, NotificationEnrichedPayloadSchema as Tt, UserThrottle as U, UpdateProjectSchema as Ut, ApiRateLimiter as V, TemplateSchema as Vt, calculateTokenBatchSize as W, UpdateUserSchema as Wt, createLogger as X, ENRICHED_STREAMS as Xt, metrics as Y, CONSUMER_GROUPS as Yt, IdempotencyGuard as Z, INBOUND_STREAMS as Zt, TemplateCache as _, setGlobalConfig as _n, NotificationCanceledPayloadSchema as _t, SuspendExecutionError as a, registry as an, messageLogs as at, interpolate as b, generateId as bn, NotificationDeliveredPayloadSchema as bt, BaseWorker as c, NotificationPrioritySchema as cn, scheduledPayloads as ct, startHealthReporter as d, baseConfigSchema as dn, users as dt, STREAMS as en, migrateDatabase as et, buildUnsubscribeHeaders as f, getAiConfig as fn, workflowDefinitions as ft, transportRegistry as g, setAiConfig as gn, NotificationAiPendingPayloadSchema as gt, registerTransport as h, readBaseConfig as hn, workflowWaiters as ht, workflowRegistry as i, EventRegistry as in, deliveryOutbox as it, LUA_COUNT_REQUEST as j, AddUserSchema as jt, WorkflowRepository as k, globalEmitter as kn, NotificationTargetSchema as kt, LockHeldError as l, NotificationStatusSchema as ln, suppressions as lt, verifyUnsubscribeToken as m, parseConfig as mn, workflowSteps as mt, NotifkitClient as n, StreamEventMetadataSchema as nn, qualifyMigrationSql as nt, buildStepNotifyPayload as o, EventMetadataSchema as on, projectApiKeys as ot, signUnsubscribeToken as p, loadEnv as pn, workflowInstances as pt, StreamProducer as q, WorkflowStepSchema as qt, workflow as r, StreamEventSchema as rn, runMigrations as rt, resolveStepTarget as s, NotificationChannelSchema as sn, projects as st, NotifkitServer as t, EventEnvelopeSchema as tn, notifkitTableNames as tt, NonRetryableError as u, AI_DEFAULTS as un, userTopicPreferences as ut, escapeHeader as v, AppError as vn, NotificationSkippedPayloadSchema as vt, PreferenceRepository as w, BatchProcessor as wn, NotificationScheduledPayloadSchema as wt, renderWithTemplate as x, sleep as xn, DeliveryOptionsSchema as xt, escapeHtml as y, ValidationError as yn, NotificationFailedPayloadSchema as yt, RedisClient as z, QuietHoursSchema as zt };
@@ -0,0 +1,3 @@
1
+ -- delivery_outbox's key leads with task_id, so GET /v1/users/:id/details,
2
+ -- which looks up the sends to a user's addresses, scanned the whole table.
3
+ CREATE INDEX IF NOT EXISTS "delivery_outbox_destination_idx" ON "delivery_outbox" USING btree ("destination");
@@ -57,6 +57,13 @@
57
57
  "when": 1790700000000,
58
58
  "tag": "0007_workflow_status_canceled",
59
59
  "breakpoints": true
60
+ },
61
+ {
62
+ "idx": 8,
63
+ "version": "7",
64
+ "when": 1790800000000,
65
+ "tag": "0008_delivery_outbox_destination_idx",
66
+ "breakpoints": true
60
67
  }
61
68
  ]
62
69
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "notifkit",
3
- "version": "0.1.12",
3
+ "version": "0.1.14",
4
4
  "description": "Self-hosted notification infrastructure. One call delivers to email, SMS, push, and webhook — routed by preference, quiet hours, and consent.",
5
5
  "license": "MIT",
6
6
  "author": "devkitshq",
@@ -49,6 +49,7 @@
49
49
  "src",
50
50
  "drizzle",
51
51
  "dashboard/dist",
52
+ "scripts/notifkit.mjs",
52
53
  "scripts/create-project.mjs",
53
54
  "scripts/create-admin.mjs",
54
55
  "scripts/migrate.mjs",
@@ -56,6 +57,7 @@
56
57
  "LICENSE"
57
58
  ],
58
59
  "bin": {
60
+ "notifkit": "./scripts/notifkit.mjs",
59
61
  "notifkit-create-project": "./scripts/create-project.mjs",
60
62
  "notifkit-create-admin": "./scripts/create-admin.mjs",
61
63
  "notifkit-migrate": "./scripts/migrate.mjs"
@@ -69,7 +71,8 @@
69
71
  "build:dashboard": "npm --prefix dashboard run build",
70
72
  "test": "vitest run --coverage",
71
73
  "test:watch": "vitest",
72
- "lint": "eslint . --fix",
74
+ "lint": "eslint .",
75
+ "lint:fix": "eslint . --fix",
73
76
  "typecheck": "tsc --noEmit",
74
77
  "typecheck:workspaces": "npm run typecheck --workspaces --if-present",
75
78
  "prepare": "husky",
@@ -34,6 +34,14 @@ if (!email || !password) {
34
34
  process.exit(1);
35
35
  }
36
36
 
37
+ // The API grants writes to superadmin and admin and treats every other value
38
+ // as read-only, so a typo would quietly produce a user who cannot do anything.
39
+ const ROLES = ["superadmin", "admin", "read_only"];
40
+ if (!ROLES.includes(role)) {
41
+ console.error(`Unknown role "${role}". Use one of: ${ROLES.join(", ")}.`);
42
+ process.exit(1);
43
+ }
44
+
37
45
  const databaseUrl =
38
46
  process.env.DATABASE_URL || "postgres://platform:platform@localhost:5432/notifkit";
39
47
  const schema = (process.env.DB_SCHEMA || "public").trim();
@@ -59,3 +59,4 @@ const { id, apiKey } = await res.json();
59
59
  console.log(`\nProject "${name}" created. Save the API key now — it is not recoverable.\n`);
60
60
  console.log(`NOTIFKIT_PROJECT_ID=${id}`);
61
61
  console.log(`NOTIFKIT_API_KEY=${apiKey}\n`);
62
+ console.log("✓ Project created. If notifkit saved you time: github.com/devkitshq/notifkit ⭐");
@@ -0,0 +1,42 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * The `notifkit` command. Today it has one subcommand, which hands off to
4
+ * create-notifkit so both spellings scaffold the same app:
5
+ *
6
+ * npx notifkit create my-app
7
+ * npm create notifkit@latest my-app
8
+ */
9
+
10
+ import { spawn } from "node:child_process";
11
+
12
+ const [command, ...args] = process.argv.slice(2);
13
+
14
+ if (command !== "create") {
15
+ console.error(
16
+ "Usage: notifkit create [name] [options]\n\n" +
17
+ "Scaffolds a new notifkit app. Run `notifkit create --help` for options.",
18
+ );
19
+ process.exit(command ? 1 : 0);
20
+ }
21
+
22
+ const npmArgs = [
23
+ "exec",
24
+ "--yes",
25
+ "--package=create-notifkit@latest",
26
+ "--",
27
+ "create-notifkit",
28
+ ...args,
29
+ ];
30
+
31
+ // npm is a .cmd shim on Windows, which only runs through a shell.
32
+ const quote = (a) => (/[\s"]/.test(a) ? `"${a.replace(/"/g, '""')}"` : a);
33
+ const child =
34
+ process.platform === "win32"
35
+ ? spawn(["npm", ...npmArgs].map(quote).join(" "), { stdio: "inherit", shell: true })
36
+ : spawn("npm", npmArgs, { stdio: "inherit" });
37
+
38
+ child.on("error", (err) => {
39
+ console.error(`notifkit create: could not run npm (${err.message})`);
40
+ process.exit(1);
41
+ });
42
+ child.on("exit", (code) => process.exit(code ?? 1));
@@ -97,13 +97,16 @@ export const baseConfigSchema = z.object({
97
97
  */
98
98
  UNSUBSCRIBE_SECRET: z.string().min(16).optional(),
99
99
  /**
100
- * When true, trusts X-Forwarded-For headers from reverse proxies for client IP resolution.
101
- * Defaults to false to prevent client-spoofed headers from bypassing rate limits.
100
+ * How many reverse proxies sit in front of the API, for reading the client
101
+ * address out of X-Forwarded-For. `true` means one. Each proxy appends the
102
+ * address it saw, so the client is that many entries from the right; the
103
+ * entries further left are whatever the client sent. Defaults to 0, which
104
+ * ignores the header so it cannot be used to get around rate limits.
102
105
  */
103
106
  TRUST_PROXY: z
104
107
  .string()
105
108
  .optional()
106
- .transform((v) => v === "true" || v === "1"),
109
+ .transform((v) => (v === "true" ? 1 : v && /^\d+$/.test(v) ? Number(v) : 0)),
107
110
  /**
108
111
  * Comma-separated list of allowed origins for CORS on session-authenticated admin routes.
109
112
  */
@@ -47,6 +47,10 @@ export const PUBSUB_CHANNELS = {
47
47
  PROJECT_INVALIDATED: "project.invalidated",
48
48
  /** Payload: a token hash, or `*` for the whole cache. */
49
49
  API_KEY_INVALIDATED: "apikey.invalidated",
50
+ /** Delivery outcomes for GET /v1/events/stream; see services/delivery/live-events. */
51
+ DELIVERY_EVENTS: "delivery.events",
52
+ /** An API began listening on DELIVERY_EVENTS: delivery workers resume publishing. */
53
+ DELIVERY_EVENTS_WANTED: "delivery.events.wanted",
50
54
  } as const;
51
55
  export type PubSubChannel = (typeof PUBSUB_CHANNELS)[keyof typeof PUBSUB_CHANNELS];
52
56
 
package/src/db/schema.ts CHANGED
@@ -358,6 +358,9 @@ export const deliveryOutbox = pgTable(
358
358
  },
359
359
  (table) => ({
360
360
  pk: primaryKey({ columns: [table.taskId, table.channel, table.destination] }),
361
+ // The key leads with task_id, so looking up what an address was sent
362
+ // (a user's details) read the whole table.
363
+ destinationIdx: index("delivery_outbox_destination_idx").on(table.destination),
361
364
  }),
362
365
  );
363
366
 
@@ -123,24 +123,15 @@ export class StreamProducer {
123
123
  this.pendingQueue = [];
124
124
  if (batch.length === 0) return;
125
125
 
126
+ // No MAXLEN trimming. Consumers delete entries as they ack them, so a
127
+ // stream only ever holds work that has not been done; trimming it threw
128
+ // away unsent notifications whenever the backlog passed maxLen. maxLen is
129
+ // the threshold monitorMaxLen warns at instead.
126
130
  try {
127
131
  if (typeof this.redis.pipeline === "function") {
128
132
  const pipeline = this.redis.pipeline();
129
- for (let i = 0; i < batch.length; i++) {
130
- const item = batch[i]!;
131
- if (i === batch.length - 1) {
132
- pipeline.xadd(
133
- this.stream,
134
- "MAXLEN",
135
- "~",
136
- String(this.maxLen),
137
- "*",
138
- "data",
139
- JSON.stringify(item.event),
140
- );
141
- } else {
142
- pipeline.xadd(this.stream, "*", "data", JSON.stringify(item.event));
143
- }
133
+ for (const item of batch) {
134
+ pipeline.xadd(this.stream, "*", "data", JSON.stringify(item.event));
144
135
  }
145
136
 
146
137
  const results = await pipeline.exec();
@@ -160,9 +151,6 @@ export class StreamProducer {
160
151
  try {
161
152
  const msgId = await this.redis.xadd(
162
153
  this.stream,
163
- "MAXLEN",
164
- "~",
165
- String(this.maxLen),
166
154
  "*",
167
155
  "data",
168
156
  JSON.stringify(item.event),
@@ -195,7 +183,7 @@ export class StreamProducer {
195
183
  if (len > this.maxLen * 0.8) {
196
184
  this.logger?.warn(
197
185
  { stream, len, maxLen: this.maxLen },
198
- "stream is nearing MAXLEN limit (80%+)",
186
+ "stream backlog is past 80% of QUEUE_MAX_LEN — consumers are falling behind",
199
187
  );
200
188
  }
201
189
 
@@ -253,7 +241,7 @@ type XReadGroupResult = Array<[string, Array<[string, string[] | null]>]> | null
253
241
 
254
242
  export class StreamConsumer {
255
243
  readonly redis: Redis;
256
- private readonly blockingRedis: Redis;
244
+ private blockingRedis: Redis;
257
245
  private readonly streams: StreamName[];
258
246
  private readonly group: ConsumerGroup;
259
247
  private readonly consumer: string;
@@ -355,9 +343,17 @@ export class StreamConsumer {
355
343
  } catch (err: any) {
356
344
  if (err.message === "XREADGROUP_TIMEOUT_DEAD_CONNECTION") {
357
345
  this.logger?.warn(
358
- "XREADGROUP took too long, assuming dead connection. Disconnecting...",
346
+ "XREADGROUP took too long, assuming dead connection. Reconnecting...",
359
347
  );
360
- this.blockingRedis.disconnect();
348
+ // Read on a fresh connection and close the old one for good. The
349
+ // abandoned read is still queued on it (on the wire, or in the
350
+ // offline queue if the connection never came up), and reconnecting
351
+ // the same client would run it later, claiming messages into this
352
+ // consumer's pending list with nobody left to receive them. A
353
+ // closed client rejects what it still holds instead.
354
+ const dead = this.blockingRedis;
355
+ this.blockingRedis = this.redis.duplicate({ enableAutoPipelining: false });
356
+ dead.disconnect();
361
357
  throw err;
362
358
  }
363
359
  throw err;
@@ -452,7 +448,7 @@ export class StreamConsumer {
452
448
  /**
453
449
  * Acks and then deletes the entries. Every stream is read by exactly one
454
450
  * consumer group, so an acked entry is never read again; leaving it in place
455
- * holds Redis memory until MAXLEN trims it, and a group recreated from "0"
451
+ * holds Redis memory for good, and a group recreated from "0"
456
452
  * (ensureGroup) would process it a second time. Both commands are issued
457
453
  * before either is awaited, so auto-pipelining sends them in one round trip,
458
454
  * and Redis runs them in order.
@@ -13,6 +13,7 @@ declare module "ioredis" {
13
13
  ttl?: number | string,
14
14
  ): Promise<number>;
15
15
  releaseLock(lockKey: string, lockToken: string): Promise<number>;
16
+ countRequest(key: string, ttlSeconds: number | string): Promise<number>;
16
17
  renewLock(lockKey: string, lockToken: string, ttlSeconds: number | string): Promise<number>;
17
18
  throttleUser(
18
19
  key: string,
@@ -155,6 +156,20 @@ export const LUA_SCHEDULER_POLL = `
155
156
  return tasks
156
157
  `;
157
158
 
159
+ /**
160
+ * Fixed-window request counter: INCR, and an expiry whenever the key has none.
161
+ * One script so the two cannot come apart. With INCR and EXPIRE sent
162
+ * separately, a failure between them left a counter with no expiry, and the
163
+ * address it counted stayed over its limit for good.
164
+ */
165
+ export const LUA_COUNT_REQUEST = `
166
+ local count = redis.call('INCR', KEYS[1])
167
+ if redis.call('TTL', KEYS[1]) < 0 then
168
+ redis.call('EXPIRE', KEYS[1], ARGV[1])
169
+ end
170
+ return count
171
+ `;
172
+
158
173
  /** Two-phase idempotency lease acquisition. Checks sent/legacy, then attempts SET NX lock. */
159
174
  export const LUA_ACQUIRE_LEASE = `
160
175
  if redis.call('EXISTS', KEYS[1]) == 1 or redis.call('EXISTS', KEYS[3]) == 1 then
@@ -214,6 +229,11 @@ export function registerCustomCommands(redis: Redis): void {
214
229
  lua: LUA_ACQUIRE_LEASE,
215
230
  });
216
231
 
232
+ redis.defineCommand("countRequest", {
233
+ numberOfKeys: 1,
234
+ lua: LUA_COUNT_REQUEST,
235
+ });
236
+
217
237
  redis.defineCommand("markProcessed", {
218
238
  numberOfKeys: 3,
219
239
  lua: LUA_MARK_PROCESSED,