@hogsend/engine 0.40.0 → 0.41.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 (62) hide show
  1. package/package.json +9 -7
  2. package/src/buckets/check-membership.ts +6 -1
  3. package/src/campaigns/cohort-sql.ts +198 -0
  4. package/src/campaigns/define-campaign.ts +207 -28
  5. package/src/campaigns/reconcile.ts +105 -11
  6. package/src/campaigns/steps.ts +48 -0
  7. package/src/connectors/define-action.ts +70 -0
  8. package/src/container.ts +124 -42
  9. package/src/destinations/presets/posthog.ts +7 -1
  10. package/src/index.ts +82 -2
  11. package/src/journeys/constants.ts +10 -0
  12. package/src/journeys/define-journey.ts +14 -405
  13. package/src/journeys/execute-journey-run.ts +608 -0
  14. package/src/journeys/graph/build-graph.ts +212 -56
  15. package/src/journeys/journey-boundary.ts +54 -0
  16. package/src/journeys/journey-context.ts +374 -59
  17. package/src/journeys/record-once.ts +110 -0
  18. package/src/lib/blueprints.ts +576 -0
  19. package/src/lib/campaign-send-key.ts +58 -0
  20. package/src/lib/connector-actions.ts +203 -19
  21. package/src/lib/contacts.ts +54 -0
  22. package/src/lib/email-service-types.ts +4 -1
  23. package/src/lib/email.ts +13 -2
  24. package/src/lib/feed.ts +77 -57
  25. package/src/lib/frequency-cap.ts +45 -15
  26. package/src/lib/hatchet-duration.ts +22 -0
  27. package/src/lib/html.ts +1 -0
  28. package/src/lib/ingestion.ts +145 -4
  29. package/src/lib/journey-suppress.ts +87 -0
  30. package/src/lib/links.ts +204 -18
  31. package/src/lib/outbound.ts +20 -0
  32. package/src/lib/preferences.ts +80 -1
  33. package/src/lib/tracked.ts +44 -29
  34. package/src/lib/tracking-event-names.ts +8 -0
  35. package/src/lib/webhook-signing.ts +6 -1
  36. package/src/lists/channels.ts +75 -0
  37. package/src/lists/define-list.ts +34 -0
  38. package/src/lists/registry.ts +29 -2
  39. package/src/mcp/blueprint-tools.ts +460 -0
  40. package/src/routes/admin/blueprints.ts +711 -0
  41. package/src/routes/admin/campaigns.ts +179 -3
  42. package/src/routes/admin/emails.ts +13 -0
  43. package/src/routes/admin/index.ts +4 -0
  44. package/src/routes/admin/journeys.ts +4 -2
  45. package/src/routes/admin/links.ts +303 -36
  46. package/src/routes/admin/lists.ts +51 -0
  47. package/src/routes/campaigns/index.ts +44 -6
  48. package/src/routes/email/preferences.ts +50 -13
  49. package/src/routes/feed/recipient.ts +2 -43
  50. package/src/routes/index.ts +6 -0
  51. package/src/routes/lists/index.ts +138 -18
  52. package/src/routes/tracking/arrive.ts +260 -0
  53. package/src/routes/tracking/click-pipeline.ts +329 -0
  54. package/src/routes/tracking/click.ts +5 -270
  55. package/src/routes/tracking/index.ts +2 -0
  56. package/src/routes/tracking/vanity.ts +64 -0
  57. package/src/worker.ts +5 -0
  58. package/src/workflows/bucket-backfill.ts +4 -2
  59. package/src/workflows/bucket-reconcile.ts +11 -4
  60. package/src/workflows/check-alerts.ts +130 -1
  61. package/src/workflows/journey-blueprint-interpreter.ts +561 -0
  62. package/src/workflows/send-campaign.ts +574 -180
@@ -0,0 +1,576 @@
1
+ /**
2
+ * Journey Blueprint service layer — the ONE write path for
3
+ * `journey_blueprints`, shared verbatim by the admin routes
4
+ * (`routes/admin/blueprints.ts`) and the agent-facing tools
5
+ * (`mcp/blueprint-tools.ts`). Spec §9's "the MCP tool is a thin wrapper over
6
+ * these — no parallel auth or storage path" is enforced structurally: both
7
+ * surfaces call these functions in-process, so there is nothing to drift.
8
+ *
9
+ * This module is the save-time sandbox boundary of the whole feature
10
+ * (spec §8): a graph is NEVER written without passing
11
+ * {@link validateBlueprintGraphForSave} — `validateBlueprintGraph` (field
12
+ * shapes + structural checks, @hogsend/core) layered with the engine-side
13
+ * registry checks core cannot do (template keys, connector actions).
14
+ *
15
+ * Conventions (shared by both surfaces):
16
+ * - the blueprint id IS the graph's `journeyId` (one id, one namespace —
17
+ * `journeyStates.journeyId` points at it, same as a code journey's meta.id)
18
+ * - `version` bumps on any update that includes `graph` (metadata-only edits
19
+ * don't bump; we deliberately don't deep-diff — jsonb normalizes key order,
20
+ * so equality checks would be unreliable, and a spurious bump is harmless)
21
+ * - a graph-changing update is REJECTED (`in_flight` failure) while the
22
+ * blueprint has any active/waiting `journeyStates` rows — Hatchet's
23
+ * durable sleep/wait primitives are matched positionally on replay, so
24
+ * changing the node sequence out from under a suspended run can desync
25
+ * its replay journal. Code journeys don't have this hazard (their
26
+ * `run()` is immutable compiled code); a blueprint's graph is a mutable
27
+ * row, so this is an explicit gate, not an implicit guarantee
28
+ * - enabling always re-runs validation against the CURRENT registries — a
29
+ * template unregistered since save is caught here, not at 2am mid-run
30
+ * - expected failures are result objects (discriminated on `ok`/`code`)
31
+ * carrying the structured `BlueprintValidationIssue[]` verbatim — never a
32
+ * caught exception's `.message`
33
+ */
34
+ import {
35
+ type BlueprintGraph,
36
+ type BlueprintValidationIssue,
37
+ type BlueprintValidationResult,
38
+ blueprintGraphSchema,
39
+ type JourneyGraph,
40
+ journeyGraphSchema,
41
+ validateBlueprintGraph,
42
+ } from "@hogsend/core";
43
+ import { propertyConditionSchema } from "@hogsend/core/schemas";
44
+ import { journeyBlueprints, journeyStates } from "@hogsend/db";
45
+ import { getTemplateNames } from "@hogsend/email";
46
+ import { z } from "@hono/zod-openapi";
47
+ import { and, count, eq, inArray, isNull } from "drizzle-orm";
48
+ import type { HogsendClient } from "../container.js";
49
+
50
+ export type BlueprintRow = typeof journeyBlueprints.$inferSelect;
51
+ /** The opaque jsonb type of the `graph` column (db cannot import core). */
52
+ type BlueprintGraphColumn = BlueprintRow["graph"];
53
+
54
+ /** What graph validation needs from the container. */
55
+ export type BlueprintRegistryContainer = Pick<
56
+ HogsendClient,
57
+ "templates" | "connectorActionRegistry"
58
+ >;
59
+
60
+ /** What the write operations need from the container. */
61
+ export type BlueprintServiceContainer = Pick<
62
+ HogsendClient,
63
+ "db" | "registry" | "templates" | "connectorActionRegistry"
64
+ >;
65
+
66
+ // ---------------------------------------------------------------------------
67
+ // Save-time validation — core checks + engine registry checks
68
+ // ---------------------------------------------------------------------------
69
+
70
+ /**
71
+ * The engine-side half of the save-time sandbox (spec §8): every node input
72
+ * is checked against a KNOWN registry, so a `send` of a template that isn't
73
+ * registered (or a connector action that doesn't exist) fails at save time
74
+ * with a structured issue, not at run time. @hogsend/core cannot do these —
75
+ * the registries live in the container.
76
+ */
77
+ function findRegistryIssues(
78
+ graph: BlueprintGraph,
79
+ container: BlueprintRegistryContainer,
80
+ ): BlueprintValidationIssue[] {
81
+ const issues: BlueprintValidationIssue[] = [];
82
+ const templateKeys = new Set<string>(getTemplateNames(container.templates));
83
+ graph.nodes.forEach((node, index) => {
84
+ if (node.type === "send" && !templateKeys.has(node.meta.template)) {
85
+ issues.push({
86
+ nodeId: node.id,
87
+ path: ["nodes", index, "meta", "template"],
88
+ code: "unknown_template",
89
+ message: `node "${node.id}": "${node.meta.template}" is not a registered template key`,
90
+ });
91
+ }
92
+ if (node.type === "connector") {
93
+ const { connectorId, action } = node.meta;
94
+ if (!container.connectorActionRegistry.get(connectorId, action)) {
95
+ issues.push({
96
+ nodeId: node.id,
97
+ path: ["nodes", index, "meta", "connectorId"],
98
+ code: "unknown_connector_action",
99
+ message: `node "${node.id}": no connector action "${connectorId}:${action}" is registered`,
100
+ });
101
+ }
102
+ }
103
+ });
104
+ return issues;
105
+ }
106
+
107
+ /**
108
+ * Full save-time validation: `validateBlueprintGraph` (field shapes +
109
+ * structural checks) plus the registry checks above. Used by create, update
110
+ * (when `graph` is present), enable (re-check against CURRENT registries),
111
+ * and every validate surface — one validation story for every write path.
112
+ *
113
+ * When the graph parses field-wise but fails STRUCTURALLY, the registry
114
+ * issues are still appended to the report — an iterating agent gets the whole
115
+ * "what's wrong" list in one round instead of discovering the unknown
116
+ * template only after fixing the cycle.
117
+ */
118
+ export function validateBlueprintGraphForSave(
119
+ graph: unknown,
120
+ container: BlueprintRegistryContainer,
121
+ ): BlueprintValidationResult {
122
+ const result = validateBlueprintGraph(graph);
123
+ if (result.valid) {
124
+ const issues = findRegistryIssues(result.graph, container);
125
+ if (issues.length > 0) return { valid: false, issues };
126
+ return result;
127
+ }
128
+ // Structural failure: the field shapes may still have parsed, in which case
129
+ // the send/connector nodes are inspectable — report registry problems too.
130
+ const parsed = blueprintGraphSchema.safeParse(graph);
131
+ if (!parsed.success) return result;
132
+ return {
133
+ valid: false,
134
+ issues: [
135
+ ...result.issues,
136
+ ...findRegistryIssues(
137
+ parsed.data as unknown as BlueprintGraph,
138
+ container,
139
+ ),
140
+ ],
141
+ };
142
+ }
143
+
144
+ // ---------------------------------------------------------------------------
145
+ // Shared input schemas — one source of truth for admin routes AND tools
146
+ // ---------------------------------------------------------------------------
147
+
148
+ /**
149
+ * Execution-tier duration INPUT: strict keys so `{ days: 3 }` is rejected
150
+ * loudly instead of becoming a silent zero (`durationToMs` ignores unknown
151
+ * keys). Empty `{}` is allowed — for `suppress` it means "disabled", same
152
+ * contract as JourneyMeta.suppress.
153
+ */
154
+ export const blueprintDurationInputSchema = z.strictObject({
155
+ hours: z.number().nonnegative().optional(),
156
+ minutes: z.number().nonnegative().optional(),
157
+ seconds: z.number().nonnegative().optional(),
158
+ });
159
+
160
+ export const blueprintExitOnInputSchema = z.array(
161
+ z.object({
162
+ event: z.string().min(1),
163
+ where: z.array(propertyConditionSchema).optional(),
164
+ }),
165
+ );
166
+
167
+ export const blueprintStatusSchema = z.enum(["draft", "enabled", "disabled"]);
168
+ export const blueprintEntryLimitSchema = z.enum([
169
+ "once",
170
+ "once_per_period",
171
+ "unlimited",
172
+ ]);
173
+ export const blueprintSourceSchema = z.enum(["mcp", "studio", "api"]);
174
+
175
+ // The graph is accepted as `unknown` and validated by
176
+ // validateBlueprintGraphForSave — so a malformed graph ALWAYS yields the
177
+ // structured issue list, never a schema layer's generic error.
178
+ export const blueprintGraphInputSchema = z.unknown();
179
+
180
+ /**
181
+ * The create payload MINUS `source` — provenance is stamped by the surface
182
+ * (the admin route takes it from the request body; the agent tools hard-code
183
+ * `"mcp"`), never trusted to mean the same thing across surfaces.
184
+ */
185
+ export const blueprintCreateBaseSchema = z.object({
186
+ name: z.string().min(1),
187
+ description: z.string().optional(),
188
+ /**
189
+ * Defaults to "draft"; a caller MAY create directly enabled (spec §10 —
190
+ * post-hoc oversight, no forced staging step). "disabled" makes no sense
191
+ * at creation and is rejected.
192
+ */
193
+ status: z.enum(["draft", "enabled"]).default("draft"),
194
+ triggerEvent: z.string().min(1),
195
+ triggerWhere: z.array(propertyConditionSchema).optional(),
196
+ entryLimit: blueprintEntryLimitSchema,
197
+ entryPeriod: blueprintDurationInputSchema.optional(),
198
+ exitOn: blueprintExitOnInputSchema.optional(),
199
+ suppress: blueprintDurationInputSchema,
200
+ graph: blueprintGraphInputSchema,
201
+ createdBy: z.string().min(1).optional(),
202
+ });
203
+
204
+ /**
205
+ * Partial-update fields. `status` is deliberately absent — transitions go
206
+ * through enable/disable so enabling always re-validates. `source`/`createdBy`
207
+ * are provenance and immutable. Nullable fields accept null to clear.
208
+ * Callers layer their own "at least one field" refinement on top (the routes
209
+ * on the body, the tools excluding `id`).
210
+ */
211
+ export const blueprintPatchFieldsSchema = z.object({
212
+ name: z.string().min(1).optional(),
213
+ description: z.string().nullable().optional(),
214
+ triggerEvent: z.string().min(1).optional(),
215
+ triggerWhere: z.array(propertyConditionSchema).nullable().optional(),
216
+ entryLimit: blueprintEntryLimitSchema.optional(),
217
+ entryPeriod: blueprintDurationInputSchema.nullable().optional(),
218
+ exitOn: blueprintExitOnInputSchema.nullable().optional(),
219
+ suppress: blueprintDurationInputSchema.optional(),
220
+ graph: blueprintGraphInputSchema.optional(),
221
+ });
222
+
223
+ export type CreateBlueprintInput = z.infer<typeof blueprintCreateBaseSchema> & {
224
+ source: z.infer<typeof blueprintSourceSchema>;
225
+ };
226
+ export type UpdateBlueprintPatch = z.infer<typeof blueprintPatchFieldsSchema>;
227
+
228
+ // ---------------------------------------------------------------------------
229
+ // Serialization — flat row shape shared by routes and tools
230
+ // ---------------------------------------------------------------------------
231
+
232
+ // Row serialization is FLAT (column names verbatim: triggerEvent,
233
+ // triggerWhere, …) so a read → edit → update loop round-trips 1:1 with the
234
+ // write inputs above. Stored jsonb is echoed loosely (the strict shapes were
235
+ // enforced at write time).
236
+ export const serializedBlueprintSchema = z.object({
237
+ id: z.string(),
238
+ name: z.string(),
239
+ description: z.string().nullable(),
240
+ status: blueprintStatusSchema,
241
+ version: z.number(),
242
+ triggerEvent: z.string(),
243
+ triggerWhere: z.array(z.record(z.string(), z.unknown())).nullable(),
244
+ entryLimit: blueprintEntryLimitSchema,
245
+ entryPeriod: z.record(z.string(), z.number()).nullable(),
246
+ exitOn: z
247
+ .array(
248
+ z.object({
249
+ event: z.string(),
250
+ where: z.array(z.record(z.string(), z.unknown())).optional(),
251
+ }),
252
+ )
253
+ .nullable(),
254
+ suppress: z.record(z.string(), z.number()),
255
+ graph: journeyGraphSchema,
256
+ source: blueprintSourceSchema,
257
+ createdBy: z.string().nullable(),
258
+ promotedAt: z.string().nullable(),
259
+ promotedToJourneyId: z.string().nullable(),
260
+ createdAt: z.string(),
261
+ updatedAt: z.string(),
262
+ });
263
+
264
+ export type SerializedBlueprint = z.infer<typeof serializedBlueprintSchema>;
265
+
266
+ export function serializeBlueprint(row: BlueprintRow): SerializedBlueprint {
267
+ return {
268
+ id: row.id,
269
+ name: row.name,
270
+ description: row.description,
271
+ status: row.status,
272
+ version: row.version,
273
+ triggerEvent: row.triggerEvent,
274
+ triggerWhere: row.triggerWhere ?? null,
275
+ entryLimit: row.entryLimit,
276
+ entryPeriod: (row.entryPeriod ?? null) as Record<string, number> | null,
277
+ exitOn: row.exitOn ?? null,
278
+ suppress: row.suppress as Record<string, number>,
279
+ graph: row.graph as unknown as JourneyGraph,
280
+ source: row.source,
281
+ createdBy: row.createdBy,
282
+ promotedAt: row.promotedAt?.toISOString() ?? null,
283
+ promotedToJourneyId: row.promotedToJourneyId,
284
+ createdAt: row.createdAt.toISOString(),
285
+ updatedAt: row.updatedAt.toISOString(),
286
+ };
287
+ }
288
+
289
+ // ---------------------------------------------------------------------------
290
+ // Operations — precise per-operation result unions
291
+ // ---------------------------------------------------------------------------
292
+
293
+ export type BlueprintInvalidGraphFailure = {
294
+ ok: false;
295
+ code: "invalid_graph";
296
+ error: string;
297
+ issues: BlueprintValidationIssue[];
298
+ };
299
+ export type BlueprintNotFoundFailure = {
300
+ ok: false;
301
+ code: "not_found";
302
+ error: string;
303
+ };
304
+
305
+ export type CreateBlueprintResult =
306
+ | { ok: true; blueprint: BlueprintRow }
307
+ | { ok: false; code: "conflict"; error: string }
308
+ | BlueprintInvalidGraphFailure;
309
+
310
+ export type UpdateBlueprintResult =
311
+ | { ok: true; blueprint: BlueprintRow }
312
+ | BlueprintNotFoundFailure
313
+ | BlueprintInvalidGraphFailure
314
+ | { ok: false; code: "in_flight"; error: string };
315
+
316
+ export type EnableBlueprintResult =
317
+ | { ok: true; blueprint: BlueprintRow }
318
+ | BlueprintNotFoundFailure
319
+ | { ok: false; code: "promoted"; error: string }
320
+ | BlueprintInvalidGraphFailure;
321
+
322
+ export type DisableBlueprintResult =
323
+ | { ok: true; blueprint: BlueprintRow }
324
+ | BlueprintNotFoundFailure;
325
+
326
+ export async function findBlueprintRow(opts: {
327
+ db: HogsendClient["db"];
328
+ id: string;
329
+ }): Promise<BlueprintRow | null> {
330
+ const rows = await opts.db
331
+ .select()
332
+ .from(journeyBlueprints)
333
+ .where(eq(journeyBlueprints.id, opts.id))
334
+ .limit(1);
335
+ return rows[0] ?? null;
336
+ }
337
+
338
+ function notFound(id: string): BlueprintNotFoundFailure {
339
+ return { ok: false, code: "not_found", error: `Blueprint "${id}" not found` };
340
+ }
341
+
342
+ /**
343
+ * Create a blueprint. The graph is validated (schema + structure +
344
+ * template/connector registries) before anything is written — an invalid
345
+ * graph is never saved. The blueprint id is the graph's `journeyId`.
346
+ */
347
+ export async function createBlueprint(opts: {
348
+ container: BlueprintServiceContainer;
349
+ input: CreateBlueprintInput;
350
+ }): Promise<CreateBlueprintResult> {
351
+ const { container, input } = opts;
352
+
353
+ const result = validateBlueprintGraphForSave(input.graph, container);
354
+ if (!result.valid) {
355
+ return {
356
+ ok: false,
357
+ code: "invalid_graph",
358
+ error: "Blueprint graph failed validation",
359
+ issues: result.issues,
360
+ };
361
+ }
362
+
363
+ // The graph's journeyId IS the blueprint id — one id, one namespace.
364
+ //
365
+ // KNOWN GAP (documented, not fixed): this only guards the direction where
366
+ // a blueprint is created AFTER a colliding code journey is already
367
+ // registered. The reverse — deploying a NEW code journey whose id matches
368
+ // an EXISTING blueprint's id — isn't guarded anywhere; both would then
369
+ // share journeyStates.journeyId, and exit-condition resolution favors the
370
+ // registered code journey. Closing this needs a boot-time cross-check
371
+ // against journey_blueprints, deliberately left for when this actually
372
+ // bites someone rather than adding DB-dependent boot machinery now.
373
+ const id = result.graph.journeyId;
374
+ if (container.registry.has(id)) {
375
+ return {
376
+ ok: false,
377
+ code: "conflict",
378
+ error: `"${id}" is a registered code journey — blueprint ids share the journey id namespace`,
379
+ };
380
+ }
381
+
382
+ // onConflictDoNothing + returning: the empty result IS the duplicate
383
+ // check, atomically (no read-then-insert race).
384
+ const inserted = await container.db
385
+ .insert(journeyBlueprints)
386
+ .values({
387
+ id,
388
+ name: input.name,
389
+ description: input.description ?? null,
390
+ status: input.status,
391
+ triggerEvent: input.triggerEvent,
392
+ triggerWhere: input.triggerWhere ?? null,
393
+ entryLimit: input.entryLimit,
394
+ entryPeriod: input.entryPeriod ?? null,
395
+ exitOn: input.exitOn ?? null,
396
+ suppress: input.suppress,
397
+ graph: result.graph as unknown as BlueprintGraphColumn,
398
+ source: input.source,
399
+ createdBy: input.createdBy ?? null,
400
+ })
401
+ .onConflictDoNothing({ target: journeyBlueprints.id })
402
+ .returning();
403
+
404
+ const row = inserted[0];
405
+ if (!row) {
406
+ return {
407
+ ok: false,
408
+ code: "conflict",
409
+ error: `Blueprint "${id}" already exists`,
410
+ };
411
+ }
412
+ return { ok: true, blueprint: row };
413
+ }
414
+
415
+ /**
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.
420
+ */
421
+ export async function updateBlueprint(opts: {
422
+ container: BlueprintServiceContainer;
423
+ id: string;
424
+ patch: UpdateBlueprintPatch;
425
+ }): Promise<UpdateBlueprintResult> {
426
+ const { container, id, patch } = opts;
427
+
428
+ const existing = await findBlueprintRow({ db: container.db, id });
429
+ if (!existing) return notFound(id);
430
+
431
+ let validatedGraph: BlueprintGraph | undefined;
432
+ if (patch.graph !== undefined) {
433
+ const result = validateBlueprintGraphForSave(patch.graph, container);
434
+ if (!result.valid) {
435
+ return {
436
+ ok: false,
437
+ code: "invalid_graph",
438
+ error: "Blueprint graph failed validation",
439
+ issues: result.issues,
440
+ };
441
+ }
442
+ if (result.graph.journeyId !== id) {
443
+ return {
444
+ ok: false,
445
+ code: "invalid_graph",
446
+ error: "Graph journeyId does not match the blueprint id",
447
+ issues: [
448
+ {
449
+ path: ["journeyId"],
450
+ code: "journey_id_mismatch",
451
+ message: `graph.journeyId "${result.graph.journeyId}" must match the blueprint id "${id}" — the id is immutable`,
452
+ },
453
+ ],
454
+ };
455
+ }
456
+ validatedGraph = result.graph;
457
+
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
462
+ .select({ count: count() })
463
+ .from(journeyStates)
464
+ .where(
465
+ and(
466
+ eq(journeyStates.journeyId, id),
467
+ isNull(journeyStates.deletedAt),
468
+ inArray(journeyStates.status, ["active", "waiting"]),
469
+ ),
470
+ );
471
+ if (inFlight && inFlight.count > 0) {
472
+ return {
473
+ ok: false,
474
+ code: "in_flight",
475
+ 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
+ };
477
+ }
478
+ }
479
+
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 };
509
+ }
510
+
511
+ /**
512
+ * Enable — the moment a graph goes live, so the stored graph is re-validated
513
+ * against the CURRENT registries first (a blueprint whose template/connector
514
+ * vanished since save cannot go live). Idempotent when already enabled. A
515
+ * promoted blueprint cannot be re-enabled — the code journey is the source
516
+ * of truth (spec §11).
517
+ */
518
+ export async function enableBlueprint(opts: {
519
+ container: BlueprintServiceContainer;
520
+ id: string;
521
+ }): Promise<EnableBlueprintResult> {
522
+ const { container, id } = opts;
523
+
524
+ const existing = await findBlueprintRow({ db: container.db, id });
525
+ if (!existing) return notFound(id);
526
+ if (existing.promotedAt) {
527
+ return {
528
+ ok: false,
529
+ 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`,
531
+ };
532
+ }
533
+
534
+ const result = validateBlueprintGraphForSave(existing.graph, container);
535
+ if (!result.valid) {
536
+ return {
537
+ ok: false,
538
+ code: "invalid_graph",
539
+ error:
540
+ "Stored graph no longer passes validation — fix it before enabling",
541
+ issues: result.issues,
542
+ };
543
+ }
544
+
545
+ const updated = await container.db
546
+ .update(journeyBlueprints)
547
+ .set({ status: "enabled", updatedAt: new Date() })
548
+ .where(eq(journeyBlueprints.id, id))
549
+ .returning();
550
+
551
+ const row = updated[0];
552
+ if (!row) return notFound(id);
553
+ return { ok: true, blueprint: row };
554
+ }
555
+
556
+ /**
557
+ * Disable — new enrollments stop on the next event; in-flight runs keep
558
+ * going (spec §12 — matches how code journeys behave when enabled flips
559
+ * off). Idempotent when already disabled.
560
+ */
561
+ export async function disableBlueprint(opts: {
562
+ container: BlueprintServiceContainer;
563
+ id: string;
564
+ }): Promise<DisableBlueprintResult> {
565
+ const { container, id } = opts;
566
+
567
+ const updated = await container.db
568
+ .update(journeyBlueprints)
569
+ .set({ status: "disabled", updatedAt: new Date() })
570
+ .where(eq(journeyBlueprints.id, id))
571
+ .returning();
572
+
573
+ const row = updated[0];
574
+ if (!row) return notFound(id);
575
+ return { ok: true, blueprint: row };
576
+ }
@@ -0,0 +1,58 @@
1
+ /**
2
+ * The deterministic per-recipient idempotency key a campaign send writes to
3
+ * `email_sends.idempotency_key`. This key is ALSO how a send row is
4
+ * attributed back to its campaign (there is no campaign_id FK on
5
+ * email_sends), so the format is owned here — the send-campaign task mints
6
+ * keys with `campaignSendKey` and the admin campaign-stats/sends routes match
7
+ * them with the pattern helpers.
8
+ *
9
+ * Two formats, chosen by the campaign's step count (NOT per call site):
10
+ *
11
+ * - Single-step campaigns (steps.length === 1 or a NULL steps blob) ALWAYS
12
+ * use the legacy `campaign:<id>:<email>` — behavior, stats queries, and
13
+ * any in-flight campaign at deploy time are byte-for-byte unchanged.
14
+ * - Multi-step campaigns use `campaign:<id>:<step>:<email>` for ALL steps
15
+ * including 0. No ambiguity with the legacy format is possible (no
16
+ * multi-step campaign exists before this ships), and per-step stats
17
+ * filter on the step-scoped pattern.
18
+ *
19
+ * The key deliberately excludes any timezone bucket (phase 3): same
20
+ * recipient + same step = same key, always.
21
+ */
22
+ export function campaignSendKey(
23
+ campaignId: string,
24
+ email: string,
25
+ step?: number,
26
+ ): string {
27
+ return step === undefined
28
+ ? `campaign:${campaignId}:${email}`
29
+ : `campaign:${campaignId}:${step}:${email}`;
30
+ }
31
+
32
+ /** Escape LIKE metacharacters so an id/step can't widen a pattern match. */
33
+ function escapeLike(value: string): string {
34
+ return value.replace(/([\\%_])/g, "\\$1");
35
+ }
36
+
37
+ /**
38
+ * SQL LIKE pattern matching every send of one campaign — a correct superset
39
+ * of BOTH key formats (legacy and step-scoped), so campaign-level stats need
40
+ * no format awareness. The id is escaped so LIKE metacharacters in it can't
41
+ * widen the match (ids are UUIDs today, but the route accepts arbitrary
42
+ * strings).
43
+ */
44
+ export function campaignSendKeyPattern(campaignId: string): string {
45
+ return `campaign:${escapeLike(campaignId)}:%`;
46
+ }
47
+
48
+ /**
49
+ * SQL LIKE pattern matching every send of ONE step of a multi-step campaign
50
+ * (`campaign:<id>:<step>:%`). Meaningless against legacy single-step keys —
51
+ * callers only use it on campaigns with a steps blob.
52
+ */
53
+ export function campaignStepSendKeyPattern(
54
+ campaignId: string,
55
+ step: number,
56
+ ): string {
57
+ return `campaign:${escapeLike(campaignId)}:${step}:%`;
58
+ }