@hogsend/engine 0.41.0 → 0.42.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.
- package/package.json +10 -9
- package/src/index.ts +14 -0
- package/src/journeys/execute-journey-run.ts +50 -17
- package/src/journeys/journey-context.ts +32 -0
- package/src/lib/blueprint-lock.ts +21 -0
- package/src/lib/blueprints.ts +273 -46
- package/src/lib/event-names.ts +143 -0
- package/src/lib/tracking.ts +1 -5
- package/src/mcp/authoring-guide.ts +160 -0
- package/src/mcp/blueprint-tools.ts +38 -108
- package/src/middleware/require-admin.ts +13 -0
- package/src/routes/admin/api-keys.ts +72 -0
- package/src/routes/admin/blueprints.ts +94 -10
- package/src/routes/admin/events.ts +55 -0
- package/src/workflows/journey-blueprint-interpreter.ts +128 -33
package/src/lib/blueprints.ts
CHANGED
|
@@ -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:
|
|
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:
|
|
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
|
-
|
|
|
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
|
-
*
|
|
418
|
-
*
|
|
419
|
-
*
|
|
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
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
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
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
//
|
|
495
|
-
//
|
|
496
|
-
//
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
.
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
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
|
|
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(
|
|
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 (
|
|
553
|
-
|
|
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
|
+
}
|
package/src/lib/tracking.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { randomUUID } from "node:crypto";
|
|
2
|
+
import { RESERVED_EVENT_NAME_RE } from "@hogsend/core";
|
|
2
3
|
import type { Database } from "@hogsend/db";
|
|
3
4
|
import { trackedLinks } from "@hogsend/db";
|
|
4
5
|
import {
|
|
@@ -25,11 +26,6 @@ const STRIP_SEMANTIC_ATTRS_RE = new RegExp(
|
|
|
25
26
|
|
|
26
27
|
const SKIP_PATTERNS = ["/v1/email/unsubscribe", "/v1/email/preferences"];
|
|
27
28
|
|
|
28
|
-
// Engine-owned event vocabularies (both `email.opened` dot-style and
|
|
29
|
-
// `journey:completed` colon-style exist) — a consumer semantic event in these
|
|
30
|
-
// namespaces would corrupt insights or trigger engine-internal logic.
|
|
31
|
-
const RESERVED_EVENT_NAME_RE = /^(?:email|journey|bucket|contact)[.:]/;
|
|
32
|
-
|
|
33
29
|
// Semantic payloads re-emit on every answer and persist indefinitely — keep
|
|
34
30
|
// them small and scalar (non-scalars don't survive the Hatchet wire anyway).
|
|
35
31
|
const MAX_PROPS_JSON_LENGTH = 2048;
|