@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
@@ -20,3 +20,9 @@ export const LINK_CLICKED = "link.clicked" as const;
20
20
  // "did a known user scan this QR?". Bus + outbound both define `linkId` as the
21
21
  // managed `links.id` and carry `trackedLinkId` separately (no legacy split).
22
22
  export const LINK_ARRIVED = "link.arrived" as const;
23
+
24
+ // First-party BUS event for an SMS short-link click (`/s/:code`) — the SMS
25
+ // sibling of `email.link_clicked`, re-ingested through `ingestEvent` so
26
+ // journeys can trigger / `ctx.waitForEvent` on a click of a link texted to
27
+ // THIS user. The per-hit OUTBOUND counterpart is `sms.clicked`.
28
+ export const SMS_LINK_CLICKED = "sms.link_clicked" as const;
@@ -1,6 +1,11 @@
1
1
  import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
2
2
  import type { JourneyRegistry } from "@hogsend/core/registry";
3
- import { type Database, emailSends, journeyStates } from "@hogsend/db";
3
+ import {
4
+ type Database,
5
+ emailSends,
6
+ journeyStates,
7
+ smsSends,
8
+ } from "@hogsend/db";
4
9
  import { eq } from "drizzle-orm";
5
10
  import { type IngestResult, ingestEvent } from "./ingestion.js";
6
11
  import type { Logger } from "./logger.js";
@@ -252,3 +257,104 @@ export async function pushLinkClickEvent(
252
257
  },
253
258
  });
254
259
  }
260
+
261
+ export interface SmsSendContext {
262
+ /**
263
+ * The resolved contact key: the enrollment's userId, else the send row's
264
+ * denormalized userId, else NULL. Deliberately NO phone fallback — phone is
265
+ * not a merge-participating contact `Kind`, so a phone-keyed ingest would
266
+ * fork an orphan contact.
267
+ */
268
+ userId: string | null;
269
+ userEmail: string | null;
270
+ templateKey: string | null;
271
+ messageId: string | null;
272
+ to: string;
273
+ }
274
+
275
+ /**
276
+ * The SMS sibling of {@link resolveEmailSendContext}: one LEFT JOIN from
277
+ * `sms_sends` to `journey_states` giving the click pipeline the identity +
278
+ * template context for the bus re-ingest and the `sms.clicked` outbound emit.
279
+ */
280
+ export async function resolveSmsSendContext(
281
+ db: Database,
282
+ smsSendId: string | null,
283
+ ): Promise<SmsSendContext | null> {
284
+ if (!smsSendId) return null;
285
+ const rows = await db
286
+ .select({
287
+ toPhone: smsSends.toPhone,
288
+ templateKey: smsSends.templateKey,
289
+ messageId: smsSends.messageId,
290
+ sendUserId: smsSends.userId,
291
+ userId: journeyStates.userId,
292
+ userEmail: journeyStates.userEmail,
293
+ })
294
+ .from(smsSends)
295
+ .leftJoin(journeyStates, eq(smsSends.journeyStateId, journeyStates.id))
296
+ .where(eq(smsSends.id, smsSendId))
297
+ .limit(1);
298
+
299
+ const row = rows[0];
300
+ if (!row) return null;
301
+
302
+ return {
303
+ userId: row.userId ?? row.sendUserId ?? null,
304
+ userEmail: row.userEmail ?? null,
305
+ templateKey: row.templateKey,
306
+ messageId: row.messageId,
307
+ to: row.toPhone,
308
+ };
309
+ }
310
+
311
+ export interface PushSmsTrackingEventOpts {
312
+ db: Database;
313
+ hatchet: HatchetClient;
314
+ registry: JourneyRegistry;
315
+ logger: Logger;
316
+ event: string;
317
+ smsSendId: string;
318
+ properties?: Record<string, unknown>;
319
+ /** Pre-resolved send context (including null) skips the duplicate read. */
320
+ resolvedContext?: SmsSendContext | null;
321
+ idempotencyKey?: string;
322
+ }
323
+
324
+ /**
325
+ * Re-push a first-party SMS tracking event (short-link click) onto the
326
+ * INTERNAL bus for journey routing + `userEvents` persistence — the SMS
327
+ * sibling of {@link pushTrackingEvent}. Returns undefined without ingesting
328
+ * when the send has no resolvable contact key (`ingestEvent` throws on a
329
+ * zero-key event, and phone is not a contact key).
330
+ */
331
+ export async function pushSmsTrackingEvent(
332
+ opts: PushSmsTrackingEventOpts,
333
+ ): Promise<IngestResult | undefined> {
334
+ const { db, hatchet, registry, logger, event, smsSendId } = opts;
335
+
336
+ const ctx =
337
+ opts.resolvedContext !== undefined
338
+ ? opts.resolvedContext
339
+ : await resolveSmsSendContext(db, smsSendId);
340
+ if (!ctx?.userId) return undefined;
341
+
342
+ return await ingestEvent({
343
+ db,
344
+ registry,
345
+ hatchet,
346
+ logger,
347
+ event: {
348
+ event,
349
+ userId: ctx.userId,
350
+ userEmail: ctx.userEmail ?? undefined,
351
+ eventProperties: {
352
+ smsSendId,
353
+ templateKey: ctx.templateKey,
354
+ ...opts.properties,
355
+ },
356
+ source: "tracking",
357
+ idempotencyKey: opts.idempotencyKey,
358
+ },
359
+ });
360
+ }
@@ -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,16 +26,12 @@ 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;
36
32
 
37
- function shouldSkipUrl(url: string): boolean {
33
+ /** Never rewrite unsubscribe/preference URLs (shared with the SMS rewriter). */
34
+ export function shouldSkipUrl(url: string): boolean {
38
35
  return SKIP_PATTERNS.some((pattern) => url.includes(pattern));
39
36
  }
40
37
 
@@ -25,10 +25,21 @@ import { Webhook } from "svix";
25
25
  */
26
26
 
27
27
  /**
28
- * The 16-event catalog — the SINGLE source of truth (schema, routes, client,
28
+ * The 21-event catalog — the SINGLE source of truth (schema, routes, client,
29
29
  * CLI all derive from this). The `webhook.test` sentinel is intentionally NOT a
30
30
  * member (it is delivered out-of-band regardless of an endpoint's `eventTypes`).
31
31
  *
32
+ * `contact.subscribed` mirrors `contact.unsubscribed` for a genuine opt-IN
33
+ * (resubscribe-all or a category/channel grant), emitted from the single
34
+ * preference-write choke with `source` provenance — the consent audit signal
35
+ * for the explicit-opt-in SMS channel (grants were previously silent).
36
+ *
37
+ * The `sms.*` family mirrors the email lifecycle for the SMS channel:
38
+ * `sms.sent` (provider-accepted, first-party), `sms.delivered` / `sms.failed`
39
+ * (provider status webhook — the single source, no first-party signal), and
40
+ * `sms.clicked` (first-party, per-hit, from the `/s/:code` short-link
41
+ * redirect — the SMS sibling of `email.clicked`).
42
+ *
32
43
  * `link.clicked` is the NON-email click event: a click on a tracked link that
33
44
  * has no email send (Discord/referral/ad-hoc `createTrackedLink`). It is the
34
45
  * deliberate counterpart to `email.clicked` so a non-email click never fires a
@@ -43,6 +54,7 @@ export const WEBHOOK_EVENT_TYPES = [
43
54
  "contact.updated",
44
55
  "contact.deleted",
45
56
  "contact.unsubscribed",
57
+ "contact.subscribed",
46
58
  "email.sent",
47
59
  "email.delivered",
48
60
  "email.opened",
@@ -50,6 +62,10 @@ export const WEBHOOK_EVENT_TYPES = [
50
62
  "email.action",
51
63
  "email.bounced",
52
64
  "email.complained",
65
+ "sms.sent",
66
+ "sms.delivered",
67
+ "sms.failed",
68
+ "sms.clicked",
53
69
  "journey.completed",
54
70
  "bucket.entered",
55
71
  "bucket.left",
@@ -46,6 +46,7 @@ function capitalize(id: string): string {
46
46
  */
47
47
  export function synthesizeChannelLists(
48
48
  actions: DefinedConnectorAction[],
49
+ opts?: { sms?: boolean },
49
50
  ): ListMeta[] {
50
51
  const channels: ListMeta[] = [
51
52
  {
@@ -71,5 +72,25 @@ export function synthesizeChannelLists(
71
72
  });
72
73
  }
73
74
 
75
+ // The SMS channel is minted when an SMS provider is configured (SMS is NOT a
76
+ // connector). UNLIKE every other channel it is OPT-IN polarity
77
+ // (`defaultOptIn: false`, not configurable): TCPA/CASL/PECR all require prior
78
+ // EXPRESS consent for marketing SMS, so a contact is textable only with an
79
+ // explicit `categories.sms === true` grant (API/SDK/preference-center) or
80
+ // phone-track consent (an inbound START). The tracked SMS sender fails closed
81
+ // (`no_consent`) without one; transactional sends are exempt from the consent
82
+ // gate but never from the STOP list. De-duped via `seen` in case a connector
83
+ // also happened to use the id "sms".
84
+ if (opts?.sms && !seen.has("sms")) {
85
+ seen.add("sms");
86
+ channels.push({
87
+ id: "sms",
88
+ name: "SMS",
89
+ defaultOptIn: false,
90
+ enabled: true,
91
+ kind: "channel",
92
+ });
93
+ }
94
+
74
95
  return channels;
75
96
  }
@@ -0,0 +1,160 @@
1
+ /**
2
+ * Journey Blueprint authoring vocabulary — the shared description text for
3
+ * every agent-facing surface (the in-process tools in `blueprint-tools.ts`
4
+ * and the `@hogsend/mcp` server's authoring-guide resource). One source of
5
+ * truth, so the tool descriptions and the MCP resource can never drift.
6
+ *
7
+ * Two tiers:
8
+ * - `GRAPH_FORMAT` / `ISSUE_LOOP_HINT` — compact one-liners embedded in tool
9
+ * descriptions, paid for on every turn (keep terse).
10
+ * - `BLUEPRINT_AUTHORING_GUIDE` — the full markdown reference, loaded on
11
+ * demand (an MCP resource fetch), so the complete vocabulary doesn't tax
12
+ * every conversation turn.
13
+ *
14
+ * Every factual claim below is cross-checked against the execution-tier
15
+ * schema (`blueprintGraphSchema` + the structural checks,
16
+ * `@hogsend/core/src/journey-graph/blueprint.ts`) and the service-layer input
17
+ * schemas (`lib/blueprints.ts`). Update THIS file when the vocabulary grows.
18
+ */
19
+
20
+ /**
21
+ * The closed executable vocabulary (spec §6/§7), summarized for the model.
22
+ * Kept in the descriptions of every graph-accepting tool so an agent can
23
+ * author without a docs round-trip.
24
+ */
25
+ export const GRAPH_FORMAT =
26
+ "Graph format: { journeyId, nodes[], edges[] }. journeyId IS the blueprint id. " +
27
+ 'Node: { id, type, title, meta? }. Executable node types (closed vocabulary): "start" (exactly one; the entry point), ' +
28
+ '"sleep" (meta.duration: { hours?, minutes?, seconds? }), ' +
29
+ '"wait" (meta: { event, timeout } — wait for the user\'s event or time out; fork with edge kinds "answered"/"timedOut", or use a single unconditional edge), ' +
30
+ '"send" (meta: { template, idempotencyLabel? } — template MUST be a key from list_email_templates), ' +
31
+ '"connector" (meta: { connectorId, action } — must be a registered connector action), ' +
32
+ '"checkpoint", "trigger" (meta: { event } — fires an event through the ingest pipeline), ' +
33
+ '"decision"/"branch" (meta.conditions: ConditionEval[]; exactly two outgoing edges, kinds "conditional-true" and "conditional-false"), ' +
34
+ 'and terminals "end-completed"/"end-exited"/"end-failed". ' +
35
+ 'Edge: { id, source, target, kind? }. The graph must be acyclic, have exactly one start, and every node must be reachable from start; non-forking nodes have at most one outgoing edge. "sleepUntil", "capture", "digest", and "unknown" nodes are NOT executable in a blueprint. ' +
36
+ "Trigger/entryLimit/exitOn/suppress live on the blueprint record, not in the graph.";
37
+
38
+ export const ISSUE_LOOP_HINT =
39
+ "On validation failure you get structured issues [{ nodeId?, edgeId?, path, code, message }] naming exactly what is wrong and where — fix and retry. " +
40
+ "Tip: iterate with validate_journey_blueprint until valid before writing.";
41
+
42
+ /**
43
+ * The full authoring reference — `GRAPH_FORMAT` expanded into a readable
44
+ * markdown document. Served on demand (e.g. as the
45
+ * `hogsend://blueprint-authoring-guide` MCP resource) instead of inlined
46
+ * into every tool description.
47
+ */
48
+ export const BLUEPRINT_AUTHORING_GUIDE = `# Journey Blueprint authoring guide
49
+
50
+ A Journey Blueprint is a lifecycle automation authored as a JSON graph,
51
+ stored in the database, and executed by the engine's generic interpreter —
52
+ no deploy in the loop. The graph is fully validated at save time (schema +
53
+ structure + template/connector registries); an invalid graph is never saved.
54
+
55
+ ## Graph shape
56
+
57
+ \`\`\`
58
+ { "journeyId": "<blueprint id>", "nodes": [...], "edges": [...] }
59
+ \`\`\`
60
+
61
+ - \`journeyId\` IS the blueprint id — one id, one namespace (it must not
62
+ collide with a registered code journey's id, and it is immutable after
63
+ create: an updated graph's \`journeyId\` must equal the blueprint id).
64
+ - Every node: \`{ id, type, title, subtitle?, meta? }\` — \`id\` and
65
+ \`title\` are required strings; \`meta\` requirements depend on \`type\`.
66
+ - Every edge: \`{ id, source, target, label?, kind? }\` — \`source\`/
67
+ \`target\` are node ids. \`kind\` is one of \`"default"\` (same as
68
+ omitted), \`"answered"\`, \`"timedOut"\`, \`"conditional-true"\`,
69
+ \`"conditional-false"\`.
70
+
71
+ ## Node types (closed executable vocabulary)
72
+
73
+ | Type | Required meta | Semantics |
74
+ |---|---|---|
75
+ | \`start\` | — | Exactly one per graph; the entry point. |
76
+ | \`sleep\` | \`duration\` | Durable sleep for a fixed duration. |
77
+ | \`wait\` | \`event\`, \`timeout\` (a duration) | Wait until THIS user emits \`event\` OR \`timeout\` elapses. Fork with one \`answered\` + one \`timedOut\` edge, or use a single unconditional edge. |
78
+ | \`send\` | \`template\`, optional \`idempotencyLabel\` | Send an email. \`template\` MUST be a registered template key (list them first); an unregistered key is rejected at save time. |
79
+ | \`connector\` | \`connectorId\`, \`action\` | Fire a registered connector action (e.g. Discord/Telegram). Rejected at save time if the action isn't registered. |
80
+ | \`checkpoint\` | — | Observability marker; the node id is the label. |
81
+ | \`trigger\` | \`event\` | Push an event through the full ingest pipeline (can enroll other journeys). |
82
+ | \`decision\` / \`branch\` | \`conditions\` (non-empty \`ConditionEval[]\`) | Binary fork: exactly one \`conditional-true\` + one \`conditional-false\` outgoing edge. The conditions array is ANDed — use a single \`composite\` condition for OR. |
83
+ | \`end-completed\` / \`end-exited\` / \`end-failed\` | — | Terminals; no outgoing edges. |
84
+
85
+ NOT executable in a blueprint (display-tier only, rejected with a named
86
+ issue): \`sleepUntil\`, \`capture\`, \`digest\`, \`unknown\`.
87
+
88
+ ## Durations
89
+
90
+ Everywhere a duration appears (\`sleep.meta.duration\`, \`wait.meta.timeout\`,
91
+ \`entryPeriod\`, \`suppress\`):
92
+
93
+ \`\`\`
94
+ { "hours"?: number, "minutes"?: number, "seconds"?: number }
95
+ \`\`\`
96
+
97
+ Keys are strict and values non-negative. At least one key is required
98
+ (except \`suppress\`, where \`{}\` means "disabled"). There is NO \`days\`
99
+ key — \`{ "days": 3 }\` is rejected loudly (write \`{ "hours": 72 }\`).
100
+
101
+ ## Conditions (\`ConditionEval\`)
102
+
103
+ Used by \`decision\`/\`branch\` nodes. Discriminated on \`type\`:
104
+
105
+ - **property** — \`{ type: "property", property, operator, value? }\`.
106
+ Operators: \`eq | neq | gt | gte | lt | lte | exists | not_exists |
107
+ contains\`. \`value\` is a string/number/boolean (omit for
108
+ \`exists\`/\`not_exists\`).
109
+ - **event** — \`{ type: "event", eventName, check, operator?, value?,
110
+ within? }\`. \`check\`: \`exists | not_exists | count\`; for \`count\`,
111
+ pair \`operator\` (\`gt | gte | lt | lte | eq\`) with a numeric \`value\`.
112
+ \`within\` is an optional duration window.
113
+ - **email_engagement** — \`{ type: "email_engagement", templateKey,
114
+ check }\`. \`check\`: \`opened | clicked | not_opened | not_clicked\`.
115
+ - **composite** — \`{ type: "composite", operator: "and" | "or",
116
+ conditions: ConditionEval[] }\` (nestable).
117
+
118
+ \`triggerWhere\` and \`exitOn[].where\` accept ONLY property conditions
119
+ (they evaluate against the incoming event's properties).
120
+
121
+ ## Structural rules (all validated at save time)
122
+
123
+ - Node and edge ids are unique; every edge connects two existing nodes.
124
+ - Exactly one \`start\` node; every node is reachable from it.
125
+ - The graph is acyclic (no loop constructs in v1).
126
+ - Fan-out is unambiguous: only \`decision\`/\`branch\` (one true + one false
127
+ edge) and \`wait\` (one answered + one timedOut, or a single unconditional
128
+ edge) fork; every other node has at most one outgoing edge; \`end-*\`
129
+ nodes have none.
130
+
131
+ ## Record-level fields (on the blueprint, NOT in the graph)
132
+
133
+ - \`name\` (required), \`description?\`.
134
+ - \`status\` — \`draft\` (default) | \`enabled\` | \`disabled\`. Create
135
+ accepts \`draft\`/\`enabled\`; afterwards transitions go through the
136
+ enable/disable operations (enable re-validates the stored graph against
137
+ the CURRENT template/connector registries).
138
+ - \`triggerEvent\` (required) — the event name that enrolls users.
139
+ - \`triggerWhere?\` — property conditions the trigger event's properties
140
+ must satisfy for enrollment.
141
+ - \`entryLimit\` (required) — \`once | once_per_period | unlimited\`; pair
142
+ \`once_per_period\` with \`entryPeriod\` (a duration).
143
+ - \`exitOn?\` — \`[{ event, where? }]\`: events that abort in-flight runs.
144
+ - \`suppress\` (required) — quiet-period duration after a completed run;
145
+ \`{}\` disables suppression.
146
+
147
+ Reserved namespaces \`email.*\`, \`journey.*\`, \`bucket.*\`, \`contact.*\`
148
+ are engine-emitted — do not use them as blueprint trigger events.
149
+
150
+ ## Workflow: validate, iterate, then write
151
+
152
+ Validation returns structured issues \`[{ nodeId?, edgeId?, path, code,
153
+ message }]\` naming exactly what is wrong and where — fix and retry.
154
+ Iterate with the validate (dry-run) surface until the graph is valid, then
155
+ create/update; the same checks run on every write, so nothing invalid is
156
+ ever saved. A \`valid: false\` report is a successful call, not an error.
157
+ Event names are an open vocabulary (prefer an observed/declared name over
158
+ inventing a near-duplicate); template keys and connector actions are closed
159
+ registries — list them before referencing them.
160
+ `;
@@ -26,9 +26,7 @@
26
26
  * down, …) still throw and are the host's problem.
27
27
  */
28
28
  import type { BlueprintValidationIssue } from "@hogsend/core";
29
- import { journeyBlueprints, userEvents } from "@hogsend/db";
30
29
  import { getTemplateNames } from "@hogsend/email";
31
- import { count, desc, ilike, max } from "drizzle-orm";
32
30
  import { z } from "zod";
33
31
  import {
34
32
  type BlueprintServiceContainer,
@@ -43,6 +41,8 @@ import {
43
41
  updateBlueprint,
44
42
  validateBlueprintGraphForSave,
45
43
  } from "../lib/blueprints.js";
44
+ import { listEventNameVocabulary } from "../lib/event-names.js";
45
+ import { GRAPH_FORMAT, ISSUE_LOOP_HINT } from "./authoring-guide.js";
46
46
 
47
47
  // ---------------------------------------------------------------------------
48
48
  // Tool shape
@@ -118,6 +118,11 @@ type ToolNotFound = { ok: false; code: "not_found"; error: string };
118
118
  type ToolConflict = { ok: false; code: "conflict"; error: string };
119
119
  type ToolPromoted = { ok: false; code: "promoted"; error: string };
120
120
  type ToolInFlight = { ok: false; code: "in_flight"; error: string };
121
+ type ToolVersionConflict = {
122
+ ok: false;
123
+ code: "version_conflict";
124
+ error: string;
125
+ };
121
126
  type ToolInvalidGraph = {
122
127
  ok: false;
123
128
  code: "invalid_graph";
@@ -130,35 +135,19 @@ const okWrite = (blueprint: SerializedBlueprint): ToolWriteSuccess => ({
130
135
  blueprint,
131
136
  });
132
137
 
133
- /**
134
- * The closed executable vocabulary (spec §6/§7), summarized for the model.
135
- * Kept in the descriptions of every graph-accepting tool so an agent can
136
- * author without a docs round-trip.
137
- */
138
- const GRAPH_FORMAT =
139
- "Graph format: { journeyId, nodes[], edges[] }. journeyId IS the blueprint id. " +
140
- 'Node: { id, type, title, meta? }. Executable node types (closed vocabulary): "start" (exactly one; the entry point), ' +
141
- '"sleep" (meta.duration: { hours?, minutes?, seconds? }), ' +
142
- '"wait" (meta: { event, timeout } — wait for the user\'s event or time out; fork with edge kinds "answered"/"timedOut", or use a single unconditional edge), ' +
143
- '"send" (meta: { template, idempotencyLabel? } — template MUST be a key from list_email_templates), ' +
144
- '"connector" (meta: { connectorId, action } — must be a registered connector action), ' +
145
- '"checkpoint", "trigger" (meta: { event } — fires an event through the ingest pipeline), ' +
146
- '"decision"/"branch" (meta.conditions: ConditionEval[]; exactly two outgoing edges, kinds "conditional-true" and "conditional-false"), ' +
147
- 'and terminals "end-completed"/"end-exited"/"end-failed". ' +
148
- 'Edge: { id, source, target, kind? }. The graph must be acyclic, have exactly one start, and every node must be reachable from start; non-forking nodes have at most one outgoing edge. "sleepUntil", "capture", "digest", and "unknown" nodes are NOT executable in a blueprint. ' +
149
- "Trigger/entryLimit/exitOn/suppress live on the blueprint record, not in the graph.";
150
-
151
- const ISSUE_LOOP_HINT =
152
- "On validation failure you get structured issues [{ nodeId?, edgeId?, path, code, message }] naming exactly what is wrong and where — fix and retry. " +
153
- "Tip: iterate with validate_journey_blueprint until valid before writing.";
138
+ // The closed executable vocabulary summary (GRAPH_FORMAT) and the
139
+ // iterate-on-issues hint live in ./authoring-guide.js — shared verbatim with
140
+ // the @hogsend/mcp resource so the two surfaces can never drift.
154
141
 
155
142
  // ---------------------------------------------------------------------------
156
143
  // Input schemas
157
144
  // ---------------------------------------------------------------------------
158
145
 
159
- // `source` is NOT an input — this surface stamps "mcp" itself, so provenance
160
- // (spec §10 Studio oversight) can't be spoofed by a prompt.
161
- const createInputSchema = blueprintCreateBaseSchema;
146
+ // Neither `source` NOR `createdBy` is an input — this surface stamps "mcp"
147
+ // itself and binds `createdBy` to the mount identity, so provenance (spec §10
148
+ // Studio oversight) can't be spoofed by a prompt attributing a blueprint to
149
+ // someone else.
150
+ const createInputSchema = blueprintCreateBaseSchema.omit({ createdBy: true });
162
151
 
163
152
  const updateInputSchema = blueprintPatchFieldsSchema
164
153
  .extend({ id: z.string().min(1) })
@@ -197,9 +186,11 @@ export interface JourneyBlueprintToolsOptions {
197
186
  /** The DI client (or a Pick of db/registry/templates/connectorActionRegistry). */
198
187
  container: BlueprintServiceContainer;
199
188
  /**
200
- * Actor label stamped into `journey_blueprints.createdBy` when a call
201
- * doesn't provide one — bind the mounting session's identity here (e.g.
202
- * an MCP session id or operator email) for Studio's post-hoc oversight.
189
+ * Actor label stamped into `journey_blueprints.createdBy` for every create —
190
+ * bind the mounting session's identity here (e.g. an MCP session id or
191
+ * operator email) for Studio's post-hoc oversight. It is NOT a tool input:
192
+ * a model cannot attribute a blueprint to anyone, exactly as `source` is
193
+ * stamped by the surface.
203
194
  */
204
195
  createdBy?: string;
205
196
  }
@@ -233,7 +224,8 @@ export function createJourneyBlueprintTools(
233
224
  input: {
234
225
  ...input,
235
226
  source: "mcp",
236
- createdBy: input.createdBy ?? defaultCreatedBy,
227
+ // Mount-bound identity always wins — `createdBy` is not a tool input.
228
+ createdBy: defaultCreatedBy,
237
229
  },
238
230
  });
239
231
  if (!result.ok) return result;
@@ -250,6 +242,7 @@ export function createJourneyBlueprintTools(
250
242
  "Metadata-only edits (name, triggerEvent, exitOn, …) don't bump and are never blocked. " +
251
243
  "The id is immutable — graph.journeyId must equal `id`. Status cannot be set here: use enable_journey_blueprint / disable_journey_blueprint. " +
252
244
  "Nullable fields (description, triggerWhere, entryPeriod, exitOn) accept null to clear. " +
245
+ "A blueprint promoted to code is frozen and rejects every update — the code journey is the source of truth. " +
253
246
  GRAPH_FORMAT +
254
247
  " " +
255
248
  ISSUE_LOOP_HINT,
@@ -258,7 +251,12 @@ export function createJourneyBlueprintTools(
258
251
  id,
259
252
  ...patch
260
253
  }): Promise<
261
- ToolWriteSuccess | ToolNotFound | ToolInvalidGraph | ToolInFlight
254
+ | ToolWriteSuccess
255
+ | ToolNotFound
256
+ | ToolInvalidGraph
257
+ | ToolInFlight
258
+ | ToolVersionConflict
259
+ | ToolPromoted
262
260
  > => {
263
261
  const result = await updateBlueprint({ container, id, patch });
264
262
  if (!result.ok) return result;
@@ -332,83 +330,15 @@ export function createJourneyBlueprintTools(
332
330
  "Any other event name is also valid — it just hasn't been seen yet. Prefer a listed name over inventing a near-duplicate.",
333
331
  inputSchema: listEventsInputSchema,
334
332
  run: async ({ search, limit }) => {
335
- type EventEntry = {
336
- name: string;
337
- occurrences: number;
338
- lastSeenAt: string | null;
339
- usedBy: string[];
340
- };
341
-
342
- // Observed vocabulary — grouped scan of user_events, recency-first.
343
- // ilike special chars are escaped so a search of "100%" matches
344
- // literally instead of becoming a wildcard.
345
- const escaped = search?.replace(/[\\%_]/g, (m) => `\\${m}`);
346
- const lastSeen = max(userEvents.occurredAt);
347
- const observed = await container.db
348
- .select({
349
- name: userEvents.event,
350
- occurrences: count(),
351
- lastSeenAt: lastSeen,
352
- })
353
- .from(userEvents)
354
- .where(escaped ? ilike(userEvents.event, `%${escaped}%`) : undefined)
355
- .groupBy(userEvents.event)
356
- .orderBy(desc(lastSeen))
357
- .limit(limit);
358
-
359
- const byName = new Map<string, EventEntry>();
360
- for (const row of observed) {
361
- byName.set(row.name, {
362
- name: row.name,
363
- occurrences: Number(row.occurrences),
364
- lastSeenAt: row.lastSeenAt?.toISOString() ?? null,
365
- usedBy: [],
366
- });
367
- }
368
-
369
- const matches = (name: string) =>
370
- !search || name.toLowerCase().includes(search.toLowerCase());
371
- const entryFor = (name: string): EventEntry => {
372
- const existing = byName.get(name);
373
- if (existing) return existing;
374
- const created: EventEntry = {
375
- name,
376
- occurrences: 0,
377
- lastSeenAt: null,
378
- usedBy: [],
379
- };
380
- byName.set(name, created);
381
- return created;
382
- };
383
-
384
- // Declared vocabulary — code-journey triggers (never observed rows if
385
- // nothing fired yet) and blueprint triggers, labeled by consumer.
386
- for (const journey of container.registry.getAll()) {
387
- const event = journey.trigger?.event;
388
- if (!event || !matches(event)) continue;
389
- entryFor(event).usedBy.push(`journey:${journey.id}`);
390
- }
391
- const blueprintRows = await container.db
392
- .select({
393
- id: journeyBlueprints.id,
394
- triggerEvent: journeyBlueprints.triggerEvent,
395
- status: journeyBlueprints.status,
396
- })
397
- .from(journeyBlueprints);
398
- for (const bp of blueprintRows) {
399
- if (!matches(bp.triggerEvent)) continue;
400
- entryFor(bp.triggerEvent).usedBy.push(
401
- `blueprint:${bp.id} (${bp.status})`,
402
- );
403
- }
404
-
405
- return {
406
- ok: true as const,
407
- note:
408
- "Event names are an open vocabulary — this is observed + declared usage, not a closed registry. " +
409
- "Reserved namespaces (email.*, journey.*, bucket.*, contact.*) are engine-emitted; don't use them as blueprint trigger events.",
410
- events: [...byName.values()],
411
- };
333
+ // Delegates to the shared vocabulary helper (lib/event-names.ts) —
334
+ // the same implementation GET /v1/admin/events/names serves.
335
+ const { note, events } = await listEventNameVocabulary({
336
+ db: container.db,
337
+ registry: container.registry,
338
+ search,
339
+ limit,
340
+ });
341
+ return { ok: true as const, note, events };
412
342
  },
413
343
  });
414
344
 
@@ -9,6 +9,19 @@ import { hasScope, requireApiKey } from "./api-key.js";
9
9
  // path is closed signup (only the first user can register; see app.ts), so any
10
10
  // authenticated session is an intended admin in this single-tenant model.
11
11
  export const requireAdmin = createMiddleware<AppEnv>(async (c, next) => {
12
+ // The Bearer path delegates to requireApiKey, which reads `env`/`db` off the
13
+ // container — and the session path reads `auth`. Now that requireAdmin is a
14
+ // public export a consumer can mount on their own app, a missing container
15
+ // would otherwise surface as an opaque `Cannot destructure 'env' of
16
+ // undefined` 500. Fail loud and named at mount-misuse time instead (this is
17
+ // NOT an auth outcome — do not turn it into a 401).
18
+ if (!c.get("container")) {
19
+ throw new Error(
20
+ "requireAdmin requires the Hogsend container context — mount it on an " +
21
+ "app built by createApp, or set the container variable first",
22
+ );
23
+ }
24
+
12
25
  const header = c.req.header("authorization");
13
26
  if (header?.startsWith("Bearer ")) {
14
27
  // Authenticate the key, then REQUIRE `full-admin` scope. Without this,