@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.
- package/package.json +12 -9
- package/src/container.ts +192 -4
- package/src/env.ts +28 -0
- package/src/index.ts +53 -0
- package/src/journeys/execute-journey-run.ts +50 -17
- package/src/journeys/journey-boundary.ts +5 -1
- package/src/journeys/journey-context.ts +58 -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/journey-suppress.ts +33 -2
- package/src/lib/outbound.ts +58 -0
- package/src/lib/phone.ts +19 -0
- package/src/lib/preferences.ts +32 -0
- package/src/lib/sms-frequency-cap.ts +47 -0
- package/src/lib/sms-inbound.ts +200 -0
- package/src/lib/sms-link-tracking.ts +160 -0
- package/src/lib/sms-mailer.ts +338 -0
- package/src/lib/sms-provider-registry.ts +35 -0
- package/src/lib/sms-providers-from-env.ts +100 -0
- package/src/lib/sms-service-types.ts +169 -0
- package/src/lib/sms-tracked.ts +590 -0
- package/src/lib/sms.ts +117 -0
- package/src/lib/tracking-event-names.ts +6 -0
- package/src/lib/tracking-events.ts +107 -1
- package/src/lib/tracking.ts +3 -6
- package/src/lib/webhook-signing.ts +17 -1
- package/src/lists/channels.ts +21 -0
- 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/routes/email/unsubscribe.ts +1 -0
- package/src/routes/index.ts +6 -0
- package/src/routes/lists/index.ts +54 -7
- package/src/routes/tracking/click-pipeline.ts +83 -2
- package/src/routes/tracking/short.ts +61 -0
- package/src/routes/webhooks/index.ts +5 -1
- package/src/routes/webhooks/sms-provider.ts +110 -0
- package/src/workflows/import-contacts.ts +61 -4
- 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 {
|
|
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
|
+
}
|
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,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
|
-
|
|
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
|
|
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",
|
package/src/lists/channels.ts
CHANGED
|
@@ -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
|
-
|
|
135
|
-
|
|
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
|
|
160
|
-
//
|
|
161
|
-
|
|
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`
|
|
201
|
-
*
|
|
202
|
-
*
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
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,
|