@hogsend/engine 0.41.0 → 0.43.0

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 (43) hide show
  1. package/package.json +12 -9
  2. package/src/container.ts +192 -4
  3. package/src/env.ts +28 -0
  4. package/src/index.ts +53 -0
  5. package/src/journeys/execute-journey-run.ts +50 -17
  6. package/src/journeys/journey-boundary.ts +5 -1
  7. package/src/journeys/journey-context.ts +58 -0
  8. package/src/lib/blueprint-lock.ts +21 -0
  9. package/src/lib/blueprints.ts +273 -46
  10. package/src/lib/event-names.ts +143 -0
  11. package/src/lib/journey-suppress.ts +33 -2
  12. package/src/lib/outbound.ts +58 -0
  13. package/src/lib/phone.ts +19 -0
  14. package/src/lib/preferences.ts +32 -0
  15. package/src/lib/sms-frequency-cap.ts +47 -0
  16. package/src/lib/sms-inbound.ts +200 -0
  17. package/src/lib/sms-link-tracking.ts +160 -0
  18. package/src/lib/sms-mailer.ts +338 -0
  19. package/src/lib/sms-provider-registry.ts +35 -0
  20. package/src/lib/sms-providers-from-env.ts +100 -0
  21. package/src/lib/sms-service-types.ts +169 -0
  22. package/src/lib/sms-tracked.ts +590 -0
  23. package/src/lib/sms.ts +117 -0
  24. package/src/lib/tracking-event-names.ts +6 -0
  25. package/src/lib/tracking-events.ts +107 -1
  26. package/src/lib/tracking.ts +3 -6
  27. package/src/lib/webhook-signing.ts +17 -1
  28. package/src/lists/channels.ts +21 -0
  29. package/src/mcp/authoring-guide.ts +160 -0
  30. package/src/mcp/blueprint-tools.ts +38 -108
  31. package/src/middleware/require-admin.ts +13 -0
  32. package/src/routes/admin/api-keys.ts +72 -0
  33. package/src/routes/admin/blueprints.ts +94 -10
  34. package/src/routes/admin/events.ts +55 -0
  35. package/src/routes/email/unsubscribe.ts +1 -0
  36. package/src/routes/index.ts +6 -0
  37. package/src/routes/lists/index.ts +54 -7
  38. package/src/routes/tracking/click-pipeline.ts +83 -2
  39. package/src/routes/tracking/short.ts +61 -0
  40. package/src/routes/webhooks/index.ts +5 -1
  41. package/src/routes/webhooks/sms-provider.ts +110 -0
  42. package/src/workflows/import-contacts.ts +61 -4
  43. package/src/workflows/journey-blueprint-interpreter.ts +128 -33
@@ -36,8 +36,10 @@ import {
36
36
  type BlueprintValidationIssue,
37
37
  type BlueprintValidationResult,
38
38
  blueprintGraphSchema,
39
+ isReservedEventName,
39
40
  type JourneyGraph,
40
41
  journeyGraphSchema,
42
+ RESERVED_EVENT_NAMESPACES,
41
43
  validateBlueprintGraph,
42
44
  } from "@hogsend/core";
43
45
  import { propertyConditionSchema } from "@hogsend/core/schemas";
@@ -46,6 +48,7 @@ import { getTemplateNames } from "@hogsend/email";
46
48
  import { z } from "@hono/zod-openapi";
47
49
  import { and, count, eq, inArray, isNull } from "drizzle-orm";
48
50
  import type { HogsendClient } from "../container.js";
51
+ import { blueprintGraphLock } from "./blueprint-lock.js";
49
52
 
50
53
  export type BlueprintRow = typeof journeyBlueprints.$inferSelect;
51
54
  /** The opaque jsonb type of the `graph` column (db cannot import core). */
@@ -100,10 +103,41 @@ function findRegistryIssues(
100
103
  });
101
104
  }
102
105
  }
106
+ // Reserved namespaces (email./journey./bucket./contact., dot or colon)
107
+ // are engine-emitted — a trigger node forging one would feed synthetic
108
+ // engine events through the full ingest pipeline. Same rule the semantic
109
+ // link send path enforces; the interpreter re-throws as defense-in-depth.
110
+ if (node.type === "trigger" && isReservedEventName(node.meta.event)) {
111
+ issues.push({
112
+ nodeId: node.id,
113
+ path: ["nodes", index, "meta", "event"],
114
+ code: "reserved_event",
115
+ message: `node "${node.id}": event "${node.meta.event}" uses a reserved namespace (${RESERVED_EVENT_NAMESPACES.join("/")}) — engine-emitted events cannot be forged by a blueprint`,
116
+ });
117
+ }
103
118
  });
104
119
  return issues;
105
120
  }
106
121
 
122
+ /** The structured `invalid_graph` failure for a reserved trigger EVENT (the
123
+ * blueprint-record field, not a graph node) — shared by create and update. */
124
+ function reservedTriggerEventFailure(
125
+ triggerEvent: string,
126
+ ): BlueprintInvalidGraphFailure {
127
+ return {
128
+ ok: false,
129
+ code: "invalid_graph",
130
+ error: "triggerEvent uses a reserved event namespace",
131
+ issues: [
132
+ {
133
+ path: ["triggerEvent"],
134
+ code: "reserved_event",
135
+ message: `triggerEvent "${triggerEvent}" uses a reserved namespace (${RESERVED_EVENT_NAMESPACES.join("/")}) — engine-emitted events cannot trigger a blueprint`,
136
+ },
137
+ ],
138
+ };
139
+ }
140
+
107
141
  /**
108
142
  * Full save-time validation: `validateBlueprintGraph` (field shapes +
109
143
  * structural checks) plus the registry checks above. Used by create, update
@@ -157,6 +191,25 @@ export const blueprintDurationInputSchema = z.strictObject({
157
191
  seconds: z.number().nonnegative().optional(),
158
192
  });
159
193
 
194
+ /**
195
+ * `entryPeriod` variant: requires a POSITIVE duration. Key presence alone is
196
+ * not enough — `{ hours: 0 }` (or `{ seconds: 0 }`) still makes
197
+ * `durationToMs(...) === 0`, which silently turns `once_per_period` into
198
+ * `unlimited` (cutoff === now, so every trigger re-enrolls). That is the one
199
+ * place a zero-length duration is a footgun, not a "disabled" contract
200
+ * (unlike `suppress`, where `{}` is the documented "disabled" sentinel), so
201
+ * refine on the summed value, not on presence. Omitting `entryPeriod` entirely
202
+ * stays legal: `checkEntryLimit` defaults an undefined period to 24h.
203
+ */
204
+ export const blueprintEntryPeriodInputSchema =
205
+ blueprintDurationInputSchema.refine(
206
+ (d) => (d.hours ?? 0) + (d.minutes ?? 0) + (d.seconds ?? 0) > 0,
207
+ {
208
+ message:
209
+ "entryPeriod must be a positive duration (hours/minutes/seconds)",
210
+ },
211
+ );
212
+
160
213
  export const blueprintExitOnInputSchema = z.array(
161
214
  z.object({
162
215
  event: z.string().min(1),
@@ -194,7 +247,7 @@ export const blueprintCreateBaseSchema = z.object({
194
247
  triggerEvent: z.string().min(1),
195
248
  triggerWhere: z.array(propertyConditionSchema).optional(),
196
249
  entryLimit: blueprintEntryLimitSchema,
197
- entryPeriod: blueprintDurationInputSchema.optional(),
250
+ entryPeriod: blueprintEntryPeriodInputSchema.optional(),
198
251
  exitOn: blueprintExitOnInputSchema.optional(),
199
252
  suppress: blueprintDurationInputSchema,
200
253
  graph: blueprintGraphInputSchema,
@@ -214,7 +267,7 @@ export const blueprintPatchFieldsSchema = z.object({
214
267
  triggerEvent: z.string().min(1).optional(),
215
268
  triggerWhere: z.array(propertyConditionSchema).nullable().optional(),
216
269
  entryLimit: blueprintEntryLimitSchema.optional(),
217
- entryPeriod: blueprintDurationInputSchema.nullable().optional(),
270
+ entryPeriod: blueprintEntryPeriodInputSchema.nullable().optional(),
218
271
  exitOn: blueprintExitOnInputSchema.nullable().optional(),
219
272
  suppress: blueprintDurationInputSchema.optional(),
220
273
  graph: blueprintGraphInputSchema.optional(),
@@ -307,22 +360,46 @@ export type CreateBlueprintResult =
307
360
  | { ok: false; code: "conflict"; error: string }
308
361
  | BlueprintInvalidGraphFailure;
309
362
 
363
+ export type BlueprintPromotedFailure = {
364
+ ok: false;
365
+ code: "promoted";
366
+ error: string;
367
+ };
368
+
369
+ /**
370
+ * Optimistic-concurrency loss: a concurrent graph edit committed a version bump
371
+ * between this caller reading the row and its guarded update — retryable (re-read
372
+ * and re-apply the edit onto the new version). Maps to 409, like `in_flight`.
373
+ */
374
+ export type BlueprintVersionConflictFailure = {
375
+ ok: false;
376
+ code: "version_conflict";
377
+ error: string;
378
+ };
379
+
310
380
  export type UpdateBlueprintResult =
311
381
  | { ok: true; blueprint: BlueprintRow }
312
382
  | BlueprintNotFoundFailure
313
383
  | BlueprintInvalidGraphFailure
314
- | { ok: false; code: "in_flight"; error: string };
384
+ | { ok: false; code: "in_flight"; error: string }
385
+ | BlueprintVersionConflictFailure
386
+ | BlueprintPromotedFailure;
315
387
 
316
388
  export type EnableBlueprintResult =
317
389
  | { ok: true; blueprint: BlueprintRow }
318
390
  | BlueprintNotFoundFailure
319
- | { ok: false; code: "promoted"; error: string }
391
+ | BlueprintPromotedFailure
320
392
  | BlueprintInvalidGraphFailure;
321
393
 
322
394
  export type DisableBlueprintResult =
323
395
  | { ok: true; blueprint: BlueprintRow }
324
396
  | BlueprintNotFoundFailure;
325
397
 
398
+ export type PromoteBlueprintResult =
399
+ | { ok: true; blueprint: BlueprintRow }
400
+ | BlueprintNotFoundFailure
401
+ | { ok: false; code: "already_promoted"; error: string };
402
+
326
403
  export async function findBlueprintRow(opts: {
327
404
  db: HogsendClient["db"];
328
405
  id: string;
@@ -339,6 +416,15 @@ function notFound(id: string): BlueprintNotFoundFailure {
339
416
  return { ok: false, code: "not_found", error: `Blueprint "${id}" not found` };
340
417
  }
341
418
 
419
+ /** Shared "already promoted" description for enable's and promote's errors. */
420
+ function describePromotion(
421
+ existing: Pick<BlueprintRow, "promotedAt" | "promotedToJourneyId">,
422
+ ): string {
423
+ const target = existing.promotedToJourneyId ?? "unknown journey";
424
+ const when = existing.promotedAt?.toISOString() ?? "unknown date";
425
+ return `promoted to code journey "${target}" on ${when}`;
426
+ }
427
+
342
428
  /**
343
429
  * Create a blueprint. The graph is validated (schema + structure +
344
430
  * template/connector registries) before anything is written — an invalid
@@ -350,6 +436,10 @@ export async function createBlueprint(opts: {
350
436
  }): Promise<CreateBlueprintResult> {
351
437
  const { container, input } = opts;
352
438
 
439
+ if (isReservedEventName(input.triggerEvent)) {
440
+ return reservedTriggerEventFailure(input.triggerEvent);
441
+ }
442
+
353
443
  const result = validateBlueprintGraphForSave(input.graph, container);
354
444
  if (!result.valid) {
355
445
  return {
@@ -413,10 +503,15 @@ export async function createBlueprint(opts: {
413
503
  }
414
504
 
415
505
  /**
416
- * Partial update. A `graph` change is re-validated the same way create is
417
- * and bumps `version` by 1 (in-flight runs stay pinned to the version they
418
- * enrolled under, spec §12). Metadata-only edits do not bump. Status
419
- * transitions go through enable/disable, not here.
506
+ * Partial update. A `graph` change is re-validated the same way create is and
507
+ * bumps `version` by 1 (in-flight runs stay pinned to the version they enrolled
508
+ * under, spec §12). The graph write runs in a transaction under a
509
+ * blueprint-keyed advisory lock so its in-flight count + update is atomic
510
+ * against a concurrent enrollment insert (which takes the same lock) and is
511
+ * guarded on the version read (`version_conflict` on a concurrent edit) and on
512
+ * `promotedAt IS NULL` (`promoted` on a concurrent promote). Metadata-only edits
513
+ * do not bump, need no lock, and are never blocked. Status transitions go
514
+ * through enable/disable, not here.
420
515
  */
421
516
  export async function updateBlueprint(opts: {
422
517
  container: BlueprintServiceContainer;
@@ -425,8 +520,22 @@ export async function updateBlueprint(opts: {
425
520
  }): Promise<UpdateBlueprintResult> {
426
521
  const { container, id, patch } = opts;
427
522
 
523
+ if (
524
+ patch.triggerEvent !== undefined &&
525
+ isReservedEventName(patch.triggerEvent)
526
+ ) {
527
+ return reservedTriggerEventFailure(patch.triggerEvent);
528
+ }
529
+
428
530
  const existing = await findBlueprintRow({ db: container.db, id });
429
531
  if (!existing) return notFound(id);
532
+ if (existing.promotedAt) {
533
+ return {
534
+ ok: false,
535
+ code: "promoted",
536
+ error: `Blueprint "${id}" was ${describePromotion(existing)} — it is frozen and cannot be edited`,
537
+ };
538
+ }
430
539
 
431
540
  let validatedGraph: BlueprintGraph | undefined;
432
541
  if (patch.graph !== undefined) {
@@ -454,11 +563,62 @@ export async function updateBlueprint(opts: {
454
563
  };
455
564
  }
456
565
  validatedGraph = result.graph;
566
+ }
567
+
568
+ const set: Partial<typeof journeyBlueprints.$inferInsert> = {
569
+ updatedAt: new Date(),
570
+ };
571
+ if (patch.name !== undefined) set.name = patch.name;
572
+ if (patch.description !== undefined) set.description = patch.description;
573
+ if (patch.triggerEvent !== undefined) set.triggerEvent = patch.triggerEvent;
574
+ if (patch.triggerWhere !== undefined) set.triggerWhere = patch.triggerWhere;
575
+ if (patch.entryLimit !== undefined) set.entryLimit = patch.entryLimit;
576
+ if (patch.entryPeriod !== undefined) set.entryPeriod = patch.entryPeriod;
577
+ if (patch.exitOn !== undefined) set.exitOn = patch.exitOn;
578
+ if (patch.suppress !== undefined) set.suppress = patch.suppress;
579
+
580
+ // Metadata-only edit: no graph, no version bump, no in-flight hazard (the
581
+ // node sequence is untouched, so no suspended run can desync). One guarded
582
+ // update on `promotedAt IS NULL` closes the promote race the early check
583
+ // above cannot (registry validation / reads happen in between).
584
+ if (validatedGraph === undefined) {
585
+ const updated = await container.db
586
+ .update(journeyBlueprints)
587
+ .set(set)
588
+ .where(
589
+ and(eq(journeyBlueprints.id, id), isNull(journeyBlueprints.promotedAt)),
590
+ )
591
+ .returning();
592
+ const row = updated[0];
593
+ if (row) return { ok: true, blueprint: row };
594
+ const raced = await findBlueprintRow({ db: container.db, id });
595
+ if (!raced) return notFound(id);
596
+ return {
597
+ ok: false,
598
+ code: "promoted",
599
+ error: `Blueprint "${id}" was ${describePromotion(raced)} — it is frozen and cannot be edited`,
600
+ };
601
+ }
457
602
 
458
- // Graph edits are unsafe while a run is suspended mid-graph (positional
459
- // replay journal, see module header) — block it outright rather than
460
- // relying on a version pin that can't actually protect a resume.
461
- const [inFlight] = await container.db
603
+ // Graph edit. Two hazards, both closed inside one transaction under a
604
+ // blueprint-keyed advisory lock (the enrollment insert path takes the SAME
605
+ // lock — blueprint-lock.ts):
606
+ // 1. in-flight: a run must not become active/waiting BETWEEN the count and
607
+ // the write, or a graph edit lands under a just-started run and desyncs
608
+ // its positional Hatchet replay journal. The lock serializes the
609
+ // count+update against enrollment inserts, so the count is authoritative.
610
+ // 2. lost update: two concurrent graph edits serialize on the lock, and the
611
+ // `version = existing.version` predicate makes the loser (whose read
612
+ // predates the winner's bump) match zero rows and return
613
+ // `version_conflict` instead of overwriting the winner's graph.
614
+ // The `promotedAt IS NULL` predicate additionally closes the promote race.
615
+ set.graph = validatedGraph as unknown as BlueprintGraphColumn;
616
+ set.version = existing.version + 1;
617
+
618
+ return container.db.transaction(async (tx) => {
619
+ await tx.execute(blueprintGraphLock(id));
620
+
621
+ const [inFlight] = await tx
462
622
  .select({ count: count() })
463
623
  .from(journeyStates)
464
624
  .where(
@@ -475,37 +635,44 @@ export async function updateBlueprint(opts: {
475
635
  error: `Cannot edit this blueprint's graph while ${inFlight.count} enrollment(s) are active or waiting — editing a live graph can desync Hatchet's replay journal for an in-flight run. Wait for enrollments to drain, or disable the blueprint and let them finish, before editing the graph.`,
476
636
  };
477
637
  }
478
- }
479
638
 
480
- const set: Partial<typeof journeyBlueprints.$inferInsert> = {
481
- updatedAt: new Date(),
482
- };
483
- if (patch.name !== undefined) set.name = patch.name;
484
- if (patch.description !== undefined) set.description = patch.description;
485
- if (patch.triggerEvent !== undefined) set.triggerEvent = patch.triggerEvent;
486
- if (patch.triggerWhere !== undefined) set.triggerWhere = patch.triggerWhere;
487
- if (patch.entryLimit !== undefined) set.entryLimit = patch.entryLimit;
488
- if (patch.entryPeriod !== undefined) set.entryPeriod = patch.entryPeriod;
489
- if (patch.exitOn !== undefined) set.exitOn = patch.exitOn;
490
- if (patch.suppress !== undefined) set.suppress = patch.suppress;
491
- if (validatedGraph !== undefined) {
492
- set.graph = validatedGraph as unknown as BlueprintGraphColumn;
493
- // Version bump rule: any update carrying `graph` bumps (documented in
494
- // the module header). Safe to bump unconditionally here — the in-flight
495
- // check above already rejected this request if any run could observe
496
- // the change mid-flight.
497
- set.version = existing.version + 1;
498
- }
499
-
500
- const updated = await container.db
501
- .update(journeyBlueprints)
502
- .set(set)
503
- .where(eq(journeyBlueprints.id, id))
504
- .returning();
505
-
506
- const row = updated[0];
507
- if (!row) return notFound(id);
508
- return { ok: true, blueprint: row };
639
+ const updated = await tx
640
+ .update(journeyBlueprints)
641
+ .set(set)
642
+ .where(
643
+ and(
644
+ eq(journeyBlueprints.id, id),
645
+ isNull(journeyBlueprints.promotedAt),
646
+ eq(journeyBlueprints.version, existing.version),
647
+ ),
648
+ )
649
+ .returning();
650
+ const row = updated[0];
651
+ if (row) return { ok: true, blueprint: row };
652
+
653
+ // Zero rows: blueprints are never hard-deleted, so the id still exists —
654
+ // the guard that failed is `promotedAt` (a concurrent promote) or `version`
655
+ // (a concurrent graph edit committed its bump). Re-read inside the txn
656
+ // (READ COMMITTED sees the committed winner) to return the precise code.
657
+ const [raced] = await tx
658
+ .select()
659
+ .from(journeyBlueprints)
660
+ .where(eq(journeyBlueprints.id, id))
661
+ .limit(1);
662
+ if (!raced) return notFound(id);
663
+ if (raced.promotedAt) {
664
+ return {
665
+ ok: false,
666
+ code: "promoted",
667
+ error: `Blueprint "${id}" was ${describePromotion(raced)} — it is frozen and cannot be edited`,
668
+ };
669
+ }
670
+ return {
671
+ ok: false,
672
+ code: "version_conflict",
673
+ error: `Blueprint "${id}" changed under you (version ${existing.version} → ${raced.version}) — re-read it and re-apply your edit onto the current graph.`,
674
+ };
675
+ });
509
676
  }
510
677
 
511
678
  /**
@@ -527,7 +694,7 @@ export async function enableBlueprint(opts: {
527
694
  return {
528
695
  ok: false,
529
696
  code: "promoted",
530
- error: `Blueprint "${id}" was promoted to code (${existing.promotedToJourneyId ?? "unknown journey"}) — the code journey is the source of truth; it cannot be re-enabled`,
697
+ error: `Blueprint "${id}" was ${describePromotion(existing)} — the code journey is the source of truth; it cannot be re-enabled`,
531
698
  };
532
699
  }
533
700
 
@@ -542,15 +709,30 @@ export async function enableBlueprint(opts: {
542
709
  };
543
710
  }
544
711
 
712
+ // Guarded on promotedAt IS NULL to close the window between the check
713
+ // above and this write — a concurrent promote can land while
714
+ // validateBlueprintGraphForSave is awaited, and without this guard the
715
+ // blind UPDATE below would silently re-enable a blueprint that just got
716
+ // promoted, leaving status="enabled" alongside promotedAt/
717
+ // promotedToJourneyId set.
545
718
  const updated = await container.db
546
719
  .update(journeyBlueprints)
547
720
  .set({ status: "enabled", updatedAt: new Date() })
548
- .where(eq(journeyBlueprints.id, id))
721
+ .where(
722
+ and(eq(journeyBlueprints.id, id), isNull(journeyBlueprints.promotedAt)),
723
+ )
549
724
  .returning();
550
725
 
551
726
  const row = updated[0];
552
- if (!row) return notFound(id);
553
- return { ok: true, blueprint: row };
727
+ if (row) return { ok: true, blueprint: row };
728
+
729
+ const raced = await findBlueprintRow({ db: container.db, id });
730
+ if (!raced) return notFound(id);
731
+ return {
732
+ ok: false,
733
+ code: "promoted",
734
+ error: `Blueprint "${id}" was ${describePromotion(raced)} — the code journey is the source of truth; it cannot be re-enabled`,
735
+ };
554
736
  }
555
737
 
556
738
  /**
@@ -574,3 +756,48 @@ export async function disableBlueprint(opts: {
574
756
  if (!row) return notFound(id);
575
757
  return { ok: true, blueprint: row };
576
758
  }
759
+
760
+ /**
761
+ * Promote — record that a generated code journey is now the source of truth
762
+ * for this blueprint (spec §11). Stamps `promotedAt`/`promotedToJourneyId`
763
+ * and disables the blueprint in one update; `enableBlueprint` refuses a
764
+ * promoted blueprint from then on. This is ONLY the DB state transition —
765
+ * codegen (blueprint → `defineJourney()` file) lives in the CLI, not here.
766
+ * NOT idempotent: a second promote is `already_promoted` (the caller decides
767
+ * whether that's fine or a mistake — the first promotion's target stands).
768
+ */
769
+ export async function promoteBlueprint(opts: {
770
+ container: BlueprintServiceContainer;
771
+ id: string;
772
+ journeyId: string;
773
+ }): Promise<PromoteBlueprintResult> {
774
+ const { container, id, journeyId } = opts;
775
+
776
+ // A single conditional UPDATE covers both "does it exist" and "is it
777
+ // already promoted" atomically — no separate pre-fetch on the (common)
778
+ // success path. The fallback lookup below only runs to tell the two
779
+ // failure cases apart and build the right error message.
780
+ const updated = await container.db
781
+ .update(journeyBlueprints)
782
+ .set({
783
+ status: "disabled",
784
+ promotedAt: new Date(),
785
+ promotedToJourneyId: journeyId,
786
+ updatedAt: new Date(),
787
+ })
788
+ .where(
789
+ and(eq(journeyBlueprints.id, id), isNull(journeyBlueprints.promotedAt)),
790
+ )
791
+ .returning();
792
+
793
+ const row = updated[0];
794
+ if (row) return { ok: true, blueprint: row };
795
+
796
+ const existing = await findBlueprintRow({ db: container.db, id });
797
+ if (!existing) return notFound(id);
798
+ return {
799
+ ok: false,
800
+ code: "already_promoted",
801
+ error: `Blueprint "${id}" was already ${describePromotion(existing)}`,
802
+ };
803
+ }
@@ -0,0 +1,143 @@
1
+ /**
2
+ * Event-name vocabulary — the merged observed + declared listing shared by
3
+ * the agent tools (`mcp/blueprint-tools.ts` `list_events`) and the admin
4
+ * route (`GET /v1/admin/events/names`). One runtime implementation (the
5
+ * same lib-delegation pattern the other blueprint tools follow via
6
+ * `lib/blueprints.ts`), so the two surfaces — including the note text —
7
+ * can never drift.
8
+ *
9
+ * Event names are an OPEN vocabulary (no closed registry exists anywhere in
10
+ * the engine — same as code journeys): this merges events actually observed
11
+ * in `user_events` (occurrence counts, most recently seen first) with events
12
+ * referenced as code-journey or blueprint triggers. Any other name is also
13
+ * valid — it just hasn't been seen yet.
14
+ */
15
+ import { journeyBlueprints, userEvents } from "@hogsend/db";
16
+ import { z } from "@hono/zod-openapi";
17
+ import { count, desc, ilike, inArray, max } from "drizzle-orm";
18
+ import type { HogsendClient } from "../container.js";
19
+
20
+ /**
21
+ * One merged event-name entry. Canonical shape shared by the helper's return,
22
+ * the `list_events` tool, and the `GET /v1/admin/events/names` OpenAPI response
23
+ * (the route imports this instead of re-declaring it, so they can never drift).
24
+ */
25
+ export const eventNameEntrySchema = z.object({
26
+ name: z.string(),
27
+ occurrences: z.number(),
28
+ lastSeenAt: z.string().nullable(),
29
+ // Where the name is declared as a trigger: "journey:<id>" for code journeys,
30
+ // "blueprint:<id> (<status>)" for blueprints.
31
+ usedBy: z.array(z.string()),
32
+ });
33
+
34
+ export type EventNameEntry = z.infer<typeof eventNameEntrySchema>;
35
+
36
+ const EVENT_NAMES_NOTE =
37
+ "Event names are an open vocabulary — this is observed + declared usage, not a closed registry. " +
38
+ "Reserved namespaces (email.*, journey.*, bucket.*, contact.*) are engine-emitted; don't use them as blueprint trigger events.";
39
+
40
+ export async function listEventNameVocabulary(opts: {
41
+ db: HogsendClient["db"];
42
+ registry: HogsendClient["registry"];
43
+ /** Case-insensitive substring filter on the event name. */
44
+ search?: string;
45
+ /** Cap on the observed-events scan (the declared merge is uncapped). */
46
+ limit: number;
47
+ }): Promise<{ note: string; events: EventNameEntry[] }> {
48
+ const { db, registry, search, limit } = opts;
49
+
50
+ // Observed vocabulary — grouped scan of user_events, recency-first. ilike
51
+ // special chars are escaped so a search of "100%" matches literally
52
+ // instead of becoming a wildcard. The blueprint-trigger select is
53
+ // independent of it, so both go out in one round-trip.
54
+ const escaped = search?.replace(/[\\%_]/g, (m) => `\\${m}`);
55
+ const lastSeen = max(userEvents.occurredAt);
56
+ const [observed, blueprintRows] = await Promise.all([
57
+ db
58
+ .select({
59
+ name: userEvents.event,
60
+ occurrences: count(),
61
+ lastSeenAt: lastSeen,
62
+ })
63
+ .from(userEvents)
64
+ .where(escaped ? ilike(userEvents.event, `%${escaped}%`) : undefined)
65
+ .groupBy(userEvents.event)
66
+ .orderBy(desc(lastSeen))
67
+ .limit(limit),
68
+ db
69
+ .select({
70
+ id: journeyBlueprints.id,
71
+ triggerEvent: journeyBlueprints.triggerEvent,
72
+ status: journeyBlueprints.status,
73
+ })
74
+ .from(journeyBlueprints),
75
+ ]);
76
+
77
+ const byName = new Map<string, EventNameEntry>();
78
+ for (const row of observed) {
79
+ byName.set(row.name, {
80
+ name: row.name,
81
+ occurrences: Number(row.occurrences),
82
+ lastSeenAt: row.lastSeenAt?.toISOString() ?? null,
83
+ usedBy: [],
84
+ });
85
+ }
86
+
87
+ const matches = (name: string) =>
88
+ !search || name.toLowerCase().includes(search.toLowerCase());
89
+ const entryFor = (name: string): EventNameEntry => {
90
+ const existing = byName.get(name);
91
+ if (existing) return existing;
92
+ const created: EventNameEntry = {
93
+ name,
94
+ occurrences: 0,
95
+ lastSeenAt: null,
96
+ usedBy: [],
97
+ };
98
+ byName.set(name, created);
99
+ return created;
100
+ };
101
+
102
+ // Declared vocabulary — code-journey triggers (never observed rows if
103
+ // nothing fired yet) and blueprint triggers, labeled by consumer.
104
+ for (const journey of registry.getAll()) {
105
+ const event = journey.trigger?.event;
106
+ if (!event || !matches(event)) continue;
107
+ entryFor(event).usedBy.push(`journey:${journey.id}`);
108
+ }
109
+ for (const bp of blueprintRows) {
110
+ if (!matches(bp.triggerEvent)) continue;
111
+ entryFor(bp.triggerEvent).usedBy.push(`blueprint:${bp.id} (${bp.status})`);
112
+ }
113
+
114
+ // A declared trigger (registry/blueprint) can have real rows in user_events
115
+ // that fell OUTSIDE the recency-capped observed scan above — it would then
116
+ // read `occurrences: 0 / lastSeenAt: null`, misreporting a busy event as
117
+ // never-fired. Observed rows always count >= 1, so `occurrences === 0` marks
118
+ // exactly the declared-only entries. Backfill their true counts with ONE
119
+ // targeted, bounded query (declared names are few — the code-journey +
120
+ // blueprint trigger set, not the open vocabulary).
121
+ const zeroNames = [...byName.values()]
122
+ .filter((e) => e.occurrences === 0)
123
+ .map((e) => e.name);
124
+ if (zeroNames.length > 0) {
125
+ const backfill = await db
126
+ .select({
127
+ name: userEvents.event,
128
+ occurrences: count(),
129
+ lastSeenAt: max(userEvents.occurredAt),
130
+ })
131
+ .from(userEvents)
132
+ .where(inArray(userEvents.event, zeroNames))
133
+ .groupBy(userEvents.event);
134
+ for (const row of backfill) {
135
+ const entry = byName.get(row.name);
136
+ if (!entry) continue;
137
+ entry.occurrences = Number(row.occurrences);
138
+ entry.lastSeenAt = row.lastSeenAt?.toISOString() ?? null;
139
+ }
140
+ }
141
+
142
+ return { note: EVENT_NAMES_NOTE, events: [...byName.values()] };
143
+ }
@@ -1,5 +1,5 @@
1
1
  import type { Database } from "@hogsend/db";
2
- import { emailSends, journeyStates } from "@hogsend/db";
2
+ import { emailSends, journeyStates, smsSends } from "@hogsend/db";
3
3
  import { and, eq, gte, ne } from "drizzle-orm";
4
4
  import type { JourneyBoundary } from "../journeys/journey-boundary.js";
5
5
  import { recordOnce } from "../journeys/record-once.js";
@@ -36,6 +36,33 @@ export async function hasRecentJourneySend(opts: {
36
36
  return rows.length > 0;
37
37
  }
38
38
 
39
+ /**
40
+ * The SMS leg of {@link hasRecentJourneySend}: same cross-enrollment EXISTS
41
+ * over `sms_sends` keyed by recipient phone. `meta.suppress` is a per-journey,
42
+ * per-recipient min-gap — it must gap SMS exactly as it gaps email.
43
+ */
44
+ export async function hasRecentJourneySmsSend(opts: {
45
+ db: Database;
46
+ journeyId: string;
47
+ to: string;
48
+ since: Date;
49
+ }): Promise<boolean> {
50
+ const rows = await opts.db
51
+ .select({ id: smsSends.id })
52
+ .from(smsSends)
53
+ .innerJoin(journeyStates, eq(smsSends.journeyStateId, journeyStates.id))
54
+ .where(
55
+ and(
56
+ eq(journeyStates.journeyId, opts.journeyId),
57
+ eq(smsSends.toPhone, opts.to),
58
+ gte(smsSends.createdAt, opts.since),
59
+ ne(smsSends.status, "failed"),
60
+ ),
61
+ )
62
+ .limit(1);
63
+ return rows.length > 0;
64
+ }
65
+
39
66
  /**
40
67
  * The RECORDED-once journey-suppress verdict for a boundary send. Returns
41
68
  * `{ suppressed }` — `true` means the tracked mailer must skip the send
@@ -58,6 +85,8 @@ export async function checkJourneySuppress(opts: {
58
85
  boundary: JourneyBoundary | undefined;
59
86
  to: string;
60
87
  idempotencyKey: string | undefined;
88
+ /** Which channel's send history the min-gap EXISTS runs against. */
89
+ channel?: "email" | "sms";
61
90
  /** Injectable clock for tests; defaults to the live wall clock. */
62
91
  now?: number;
63
92
  }): Promise<{ suppressed: boolean }> {
@@ -79,8 +108,10 @@ export async function checkJourneySuppress(opts: {
79
108
  key: `suppress:${idempotencyKey}`,
80
109
  compute: async () => {
81
110
  const since = new Date((opts.now ?? Date.now()) - suppressMs);
111
+ const hasRecent =
112
+ opts.channel === "sms" ? hasRecentJourneySmsSend : hasRecentJourneySend;
82
113
  return {
83
- suppressed: await hasRecentJourneySend({ db, journeyId, to, since }),
114
+ suppressed: await hasRecent({ db, journeyId, to, since }),
84
115
  };
85
116
  },
86
117
  });