@hogsend/engine 0.38.1 → 0.39.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.
@@ -1,3 +1,4 @@
1
+ import { type JourneyGraph, journeyGraphSchema } from "@hogsend/core";
1
2
  import {
2
3
  type Database,
3
4
  emailSends,
@@ -5,6 +6,7 @@ import {
5
6
  journeyLogs,
6
7
  journeyStates,
7
8
  } from "@hogsend/db";
9
+ import { getTemplateNames } from "@hogsend/email";
8
10
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
9
11
  import {
10
12
  and,
@@ -17,8 +19,16 @@ import {
17
19
  sql,
18
20
  } from "drizzle-orm";
19
21
  import type { AppEnv } from "../../app.js";
22
+ import { buildJourneyGraph } from "../../journeys/graph/build-graph.js";
20
23
  import { ingestEvent } from "../../lib/ingestion.js";
21
24
 
25
+ /**
26
+ * Per-process cache of the built {@link JourneyGraph}. A journey's `runSource`
27
+ * (and its `meta`) is static for the life of the process, so the AST extraction
28
+ * only needs to run once per journey id. Keyed by journey id.
29
+ */
30
+ const journeyGraphCache = new Map<string, JourneyGraph>();
31
+
22
32
  const journeySchema = z.object({
23
33
  id: z.string(),
24
34
  name: z.string(),
@@ -403,6 +413,57 @@ const templatesRoute = createRoute({
403
413
  },
404
414
  });
405
415
 
416
+ const graphRoute = createRoute({
417
+ method: "get",
418
+ path: "/{id}/graph",
419
+ tags: ["Admin — Journeys"],
420
+ summary: "Journey visual workflow graph with per-node live/failed metrics",
421
+ request: {
422
+ params: z.object({ id: z.string() }),
423
+ },
424
+ responses: {
425
+ 200: {
426
+ content: {
427
+ "application/json": {
428
+ schema: z.object({
429
+ graph: journeyGraphSchema,
430
+ metrics: z.object({
431
+ enrolled: z.number(),
432
+ terminals: z.object({
433
+ completed: z.number(),
434
+ failed: z.number(),
435
+ exited: z.number(),
436
+ }),
437
+ // Keyed by graph node id. `live` = people currently sitting at
438
+ // that node (status active/waiting), `failed` = instances whose
439
+ // last durable node was this one when they failed. `templateKey`
440
+ // is the resolved email template key for `send` nodes (for the
441
+ // Studio side-panel preview) — present only when resolvable.
442
+ // `templatePath` is that template component's source file (for the
443
+ // Studio "open in editor" affordance) — present only in dev where
444
+ // the registry carries source paths.
445
+ nodes: z.record(
446
+ z.string(),
447
+ z.object({
448
+ live: z.number(),
449
+ failed: z.number(),
450
+ templateKey: z.string().optional(),
451
+ templatePath: z.string().optional(),
452
+ }),
453
+ ),
454
+ }),
455
+ }),
456
+ },
457
+ },
458
+ description: "Journey graph (IR) plus retroactive per-node metrics",
459
+ },
460
+ 404: {
461
+ content: { "application/json": { schema: errorSchema } },
462
+ description: "Journey not found",
463
+ },
464
+ },
465
+ });
466
+
406
467
  export const journeysRouter = new OpenAPIHono<AppEnv>()
407
468
  .openapi(listRoute, async (c) => {
408
469
  const { db, registry } = c.get("container");
@@ -770,4 +831,221 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
770
831
  },
771
832
  200,
772
833
  );
834
+ })
835
+ .openapi(graphRoute, async (c) => {
836
+ const { db, registry, journeySources, journeySourceLocations, templates } =
837
+ c.get("container");
838
+ const { id } = c.req.valid("param");
839
+
840
+ const meta = registry.get(id);
841
+ if (!meta) {
842
+ return c.json({ error: "Journey not found" }, 404);
843
+ }
844
+
845
+ // Build (and cache) the IR — runSource is static per process, so a repeat
846
+ // request re-uses the parse rather than re-walking the AST. The captured
847
+ // call-site (also static per process) is baked into the cached graph.
848
+ let graph = journeyGraphCache.get(id);
849
+ if (!graph) {
850
+ graph = buildJourneyGraph({ runSource: journeySources.get(id), meta });
851
+ const source = journeySourceLocations.get(id);
852
+ if (source) graph.source = source;
853
+ journeyGraphCache.set(id, graph);
854
+ }
855
+
856
+ // One grouped query gives us BOTH per-node live/failed AND the status
857
+ // totals for enrolled + terminals (sum across all node ids per status).
858
+ const perNode = await db
859
+ .select({
860
+ nodeId: journeyStates.currentNodeId,
861
+ status: journeyStates.status,
862
+ count: count(),
863
+ })
864
+ .from(journeyStates)
865
+ .where(
866
+ and(eq(journeyStates.journeyId, id), isNull(journeyStates.deletedAt)),
867
+ )
868
+ .groupBy(journeyStates.currentNodeId, journeyStates.status);
869
+
870
+ // Default every graph node to zero, then overlay the observed counts. Only
871
+ // start/sleep/wait/checkpoint node ids ever appear as `current_node_id`;
872
+ // instantaneous nodes (send/trigger/capture/connector) correctly stay 0.
873
+ const nodeMetrics: Record<
874
+ string,
875
+ {
876
+ live: number;
877
+ failed: number;
878
+ templateKey?: string;
879
+ templatePath?: string;
880
+ }
881
+ > = {};
882
+ for (const node of graph.nodes) {
883
+ nodeMetrics[node.id] = { live: 0, failed: 0 };
884
+ }
885
+
886
+ const statusTotals: Record<string, number> = {};
887
+ for (const row of perNode) {
888
+ const n = Number(row.count);
889
+ statusTotals[row.status] = (statusTotals[row.status] ?? 0) + n;
890
+ const nodeId = row.nodeId;
891
+ if (!nodeId) continue;
892
+ const entry = nodeMetrics[nodeId] ?? { live: 0, failed: 0 };
893
+ if (row.status === "active" || row.status === "waiting") {
894
+ entry.live += n;
895
+ } else if (row.status === "failed") {
896
+ entry.failed += n;
897
+ }
898
+ nodeMetrics[nodeId] = entry;
899
+ }
900
+
901
+ const enrolled = Object.values(statusTotals).reduce((a, b) => a + b, 0);
902
+
903
+ // Resolve a real email template key per `send` node for the Studio
904
+ // side-panel preview. The preview only needs the registry key (it renders
905
+ // the React Email component — no send data), so STATIC resolution is the
906
+ // primary mechanism and a never-sent journey still previews. Priority:
907
+ // (1) literal `meta.template` — already the registry key.
908
+ // (2) STATIC exact: the node's `subtitle` is the Templates const name for
909
+ // member-expr sends (`FEEDBACK_NPS_SURVEY`); lowercase + `_`→`-`
910
+ // (`feedback-nps-survey`) and use it IFF that key is in the registry.
911
+ // (2b) STATIC prefix: else the single LONGEST registry key that is a
912
+ // segment-prefix of the kebab'd const name (`activation-nudge-series`
913
+ // → `activation-nudge`). Only when that longest prefix is unique — a
914
+ // wrong preview is worse than none, so an ambiguous tie stays unresolved.
915
+ // (3) journey_logs rows (action='send') whose `to_node_id` is this send
916
+ // node's site id (`send:<site>`), reading `detail.template` — site-
917
+ // keyed, so two sends of one template on different branches stay
918
+ // distinct.
919
+ // (4) observed email_sends template keys (join via journeyStateId) mapped
920
+ // onto still-unresolved send nodes in source order.
921
+ // The resolved key rides on `metrics.nodes[id].templateKey` (NOT the cached
922
+ // graph, which stays immutable + DB-independent).
923
+ const sendNodes = graph.nodes.filter((node) => node.type === "send");
924
+ if (sendNodes.length > 0) {
925
+ const sendIds = new Set(sendNodes.map((node) => node.id));
926
+ const setTemplate = (nodeId: string, key: string) => {
927
+ const entry = nodeMetrics[nodeId] ?? { live: 0, failed: 0 };
928
+ if (!entry.templateKey) {
929
+ entry.templateKey = key;
930
+ // Best-effort source path (dev-only; see `withSources`) for the
931
+ // Studio "open template in editor" affordance.
932
+ const def = (templates as Record<string, { sourcePath?: string }>)[
933
+ key
934
+ ];
935
+ if (def?.sourcePath) entry.templatePath = def.sourcePath;
936
+ }
937
+ nodeMetrics[nodeId] = entry;
938
+ };
939
+
940
+ // (1) literal templates already carry the real key in the IR.
941
+ for (const node of sendNodes) {
942
+ if (node.meta?.template) setTemplate(node.id, node.meta.template);
943
+ }
944
+
945
+ // (2/2b) static const-name → registry key (no runtime data needed):
946
+ // exact kebab match, else the unique longest segment-prefix key.
947
+ const registryKeys = getTemplateNames(templates) as string[];
948
+ const registeredKeys = new Set<string>(registryKeys);
949
+ const resolveStatic = (constName: string): string | undefined => {
950
+ const kebab = constName.toLowerCase().replace(/_/g, "-");
951
+ if (registeredKeys.has(kebab)) return kebab;
952
+ // Longest registry key that is a segment-prefix of the kebab'd name.
953
+ let best: string | undefined;
954
+ let bestLen = -1;
955
+ let ambiguous = false;
956
+ for (const key of registryKeys) {
957
+ if (!kebab.startsWith(`${key}-`)) continue;
958
+ if (key.length > bestLen) {
959
+ best = key;
960
+ bestLen = key.length;
961
+ ambiguous = false;
962
+ } else if (key.length === bestLen) {
963
+ ambiguous = true;
964
+ }
965
+ }
966
+ return ambiguous ? undefined : best;
967
+ };
968
+ for (const node of sendNodes) {
969
+ if (nodeMetrics[node.id]?.templateKey || !node.subtitle) continue;
970
+ const key = resolveStatic(node.subtitle);
971
+ if (key) setTemplate(node.id, key);
972
+ }
973
+
974
+ // (3) journey_logs site-join (only if something is still unresolved).
975
+ if (sendNodes.some((node) => !nodeMetrics[node.id]?.templateKey)) {
976
+ const logRows = await db
977
+ .select({
978
+ toNodeId: journeyLogs.toNodeId,
979
+ template: sql<string | null>`${journeyLogs.detail} ->> 'template'`,
980
+ })
981
+ .from(journeyLogs)
982
+ .innerJoin(
983
+ journeyStates,
984
+ eq(journeyLogs.journeyStateId, journeyStates.id),
985
+ )
986
+ .where(
987
+ and(
988
+ eq(journeyStates.journeyId, id),
989
+ isNull(journeyStates.deletedAt),
990
+ eq(journeyLogs.action, "send"),
991
+ ),
992
+ );
993
+ for (const row of logRows) {
994
+ const nodeId = row.toNodeId;
995
+ if (!nodeId || !row.template || !sendIds.has(nodeId)) continue;
996
+ setTemplate(nodeId, row.template);
997
+ }
998
+ }
999
+
1000
+ // (4) email_sends fallback, mapped in source order.
1001
+ const unresolved = sendNodes.filter(
1002
+ (node) => !nodeMetrics[node.id]?.templateKey,
1003
+ );
1004
+ if (unresolved.length > 0) {
1005
+ const observedRows = await db
1006
+ .select({
1007
+ templateKey: emailSends.templateKey,
1008
+ firstSeen: sql<string | null>`min(${emailSends.createdAt})`,
1009
+ })
1010
+ .from(emailSends)
1011
+ .innerJoin(
1012
+ journeyStates,
1013
+ eq(emailSends.journeyStateId, journeyStates.id),
1014
+ )
1015
+ .where(
1016
+ and(
1017
+ eq(journeyStates.journeyId, id),
1018
+ isNull(journeyStates.deletedAt),
1019
+ isNotNull(emailSends.templateKey),
1020
+ ),
1021
+ )
1022
+ .groupBy(emailSends.templateKey);
1023
+ const observed = observedRows
1024
+ .filter((r): r is { templateKey: string; firstSeen: string | null } =>
1025
+ Boolean(r.templateKey),
1026
+ )
1027
+ .sort((a, b) => (a.firstSeen ?? "").localeCompare(b.firstSeen ?? ""))
1028
+ .map((r) => r.templateKey);
1029
+ unresolved.forEach((node, i) => {
1030
+ const key = observed[i];
1031
+ if (key) setTemplate(node.id, key);
1032
+ });
1033
+ }
1034
+ }
1035
+
1036
+ return c.json(
1037
+ {
1038
+ graph,
1039
+ metrics: {
1040
+ enrolled,
1041
+ terminals: {
1042
+ completed: statusTotals.completed ?? 0,
1043
+ failed: statusTotals.failed ?? 0,
1044
+ exited: statusTotals.exited ?? 0,
1045
+ },
1046
+ nodes: nodeMetrics,
1047
+ },
1048
+ },
1049
+ 200,
1050
+ );
773
1051
  });
@@ -0,0 +1,106 @@
1
+ import { existsSync } from "node:fs";
2
+ import { createRequire } from "node:module";
3
+ import { OpenAPIHono } from "@hono/zod-openapi";
4
+ import { z } from "zod";
5
+ import type { AppEnv } from "../../app.js";
6
+ import { createLogger } from "../../lib/logger.js";
7
+
8
+ /**
9
+ * Dev-only "open in editor" endpoint. The Studio SPA can't spawn a process, so
10
+ * it POSTs a source path here and the engine — running on the SAME machine as
11
+ * the developer in local dev — opens it in whatever editor they use.
12
+ *
13
+ * Editor AUTO-DETECTION is delegated to `launch-editor` (the mechanism behind
14
+ * Vite/CRA error overlays): it honours `$LAUNCH_EDITOR`/`$VISUAL`/`$EDITOR`,
15
+ * else scans running processes for a known editor (Cursor, VS Code, Windsurf,
16
+ * WebStorm, …). So there is no editor picker — it just opens "your editor".
17
+ *
18
+ * Safety envelope (this spawns a process on the host):
19
+ * - DEV ONLY: hard 404 when NODE_ENV=production.
20
+ * - Admin-authed: mounted under the admin router (requireAdmin).
21
+ * - Path allowlist: absolute path, a known source extension, and it must exist.
22
+ * - `launch-editor` spawns argv (never a shell string), so a crafted path can't
23
+ * inject a command.
24
+ */
25
+
26
+ const require = createRequire(import.meta.url);
27
+
28
+ // launch-editor is CommonJS and ships no types. Signature:
29
+ // launch(file, [specifiedEditor], [onErrorCallback]) — no editor => auto-guess.
30
+ type LaunchEditor = (
31
+ file: string,
32
+ editor?: string,
33
+ onError?: (fileName: string, errorMsg: string) => void,
34
+ ) => void;
35
+
36
+ // Loaded LAZILY, only on the dev-only code path below, so a production build
37
+ // never `require`s it — keeps launch-editor out of the prod dependency graph
38
+ // (and away from the CJS-in-ESM bundling gotcha for npm consumers).
39
+ let launchEditor: LaunchEditor | undefined;
40
+ function getLaunchEditor(): LaunchEditor {
41
+ if (!launchEditor) {
42
+ launchEditor = require("launch-editor") as LaunchEditor;
43
+ }
44
+ return launchEditor;
45
+ }
46
+
47
+ const logger = createLogger(process.env.LOG_LEVEL);
48
+
49
+ const bodySchema = z.object({
50
+ path: z.string().min(1),
51
+ line: z.number().int().positive().optional(),
52
+ });
53
+
54
+ /** Source files the Studio can deep-link (journeys + email templates + kin). */
55
+ const SOURCE_EXT = /\.(tsx?|jsx?|mjs|cjs)$/;
56
+
57
+ /**
58
+ * Editor to spawn when none is running and no `$HS_EDITOR`/`$VISUAL`/`$EDITOR`
59
+ * is set. `cursor`/`code`/`windsurf` all accept the `file:line` target.
60
+ */
61
+ const DEFAULT_EDITOR = "cursor";
62
+
63
+ export const openEditorRouter = new OpenAPIHono<AppEnv>().post(
64
+ "/",
65
+ async (c) => {
66
+ if (process.env.NODE_ENV === "production") {
67
+ return c.json({ error: "not available" }, 404);
68
+ }
69
+
70
+ let body: z.infer<typeof bodySchema>;
71
+ try {
72
+ body = bodySchema.parse(await c.req.json());
73
+ } catch {
74
+ return c.json({ error: "invalid body" }, 400);
75
+ }
76
+
77
+ const { path, line } = body;
78
+ if (!path.startsWith("/") || !SOURCE_EXT.test(path)) {
79
+ return c.json({ error: "path not allowed" }, 403);
80
+ }
81
+ if (!existsSync(path)) {
82
+ return c.json({ error: "file not found" }, 404);
83
+ }
84
+
85
+ const target = line ? `${path}:${line}` : path;
86
+ const launch = getLaunchEditor();
87
+ const onErr = (fileName: string, errorMsg: string) => {
88
+ logger.warn(`open-in-editor failed for ${fileName}: ${errorMsg}`);
89
+ };
90
+
91
+ // `launch-editor` auto-detects a RUNNING editor (or $VISUAL/$EDITOR), but
92
+ // launches nothing when the editor is closed and no env var is set. So:
93
+ // 1. `HS_EDITOR` (explicit override) → spawn it directly, open or not.
94
+ // 2. else auto-detect a running editor.
95
+ // 3. if that finds nothing, fall back to a default editor and spawn it —
96
+ // this is what makes "open in IDE" work even when it isn't running yet.
97
+ const forced = process.env.HS_EDITOR?.trim();
98
+ if (forced) {
99
+ launch(target, forced, onErr);
100
+ } else {
101
+ launch(target, undefined, () => launch(target, DEFAULT_EDITOR, onErr));
102
+ }
103
+
104
+ return c.json({ ok: true, target }, 200);
105
+ },
106
+ );
@@ -3,6 +3,7 @@ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
3
  import type { AppEnv } from "../../app.js";
4
4
  import { resolveRecipient } from "../../lib/contacts.js";
5
5
  import { errorSchema } from "../../lib/schemas.js";
6
+ import { isReservedListId } from "../../lists/define-list.js";
6
7
  import { hasScope } from "../../middleware/api-key.js";
7
8
  import { requireIdentity } from "../_shared.js";
8
9
 
@@ -64,7 +65,7 @@ const sendRoute = createRoute({
64
65
  export const emailsRouter = new OpenAPIHono<AppEnv>().openapi(
65
66
  sendRoute,
66
67
  async (c) => {
67
- const { db, emailService, templates } = c.get("container");
68
+ const { db, emailService, templates, listRegistry } = c.get("container");
68
69
  const apiKey = c.get("apiKey");
69
70
  const body = c.req.valid("json");
70
71
 
@@ -91,6 +92,29 @@ export const emailsRouter = new OpenAPIHono<AppEnv>().openapi(
91
92
  return c.json({ error: `Unknown template: ${body.template}` }, 400);
92
93
  }
93
94
 
95
+ // Validate a caller-supplied `category` server-side (request-time twin of
96
+ // the boot-time template-category guard). A caller `category` OVERRIDES the
97
+ // template's category at send time; an unknown/registry-excluded category
98
+ // silently defaults to opt-in (ListRegistry.isSubscribedByDefault returns
99
+ // `true` for an id it doesn't hold) → the send would bypass
100
+ // suppression/consent. Valid iff it's a reserved built-in or an ENABLED
101
+ // registered list (fail-closed — the route can't see excluded lists, and
102
+ // honoring an excluded opt-in list would re-open the same consent flip).
103
+ // Only checked when present; an absent category uses the boot-validated
104
+ // template default.
105
+ if (
106
+ body.category !== undefined &&
107
+ !isReservedListId(body.category) &&
108
+ !listRegistry.has(body.category)
109
+ ) {
110
+ return c.json(
111
+ {
112
+ error: `Unknown category: ${body.category} — not a reserved built-in or a registered email list. An unknown category silently defaults to opt-in and bypasses suppression/consent.`,
113
+ },
114
+ 400,
115
+ );
116
+ }
117
+
94
118
  const recipient = await resolveRecipient({
95
119
  db,
96
120
  userId: body.userId,
package/src/worker.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import type { DefinedBucket } from "./buckets/define-bucket.js";
2
2
  import {
3
+ collectBucketReactionJourneys,
3
4
  selectBucketReactionTasks,
4
5
  selectBucketTasks,
5
6
  } from "./buckets/registry.js";
@@ -63,7 +64,20 @@ export interface Worker {
63
64
  export function createWorker(opts: CreateWorkerOptions): Worker {
64
65
  const { container, journeys } = opts;
65
66
  const enabled = opts.enabledJourneys ?? container.env.ENABLED_JOURNEYS;
66
- const journeyTasks = selectJourneyTasks(journeys, enabled);
67
+ const enabledBuckets = opts.enabledBuckets ?? container.env.ENABLED_BUCKETS;
68
+ // Bucket-reaction journey ids (`bucket-<id>-on-<kind>`) are registered
69
+ // separately (via selectBucketReactionTasks) bypassing ENABLED_JOURNEYS, but
70
+ // they ARE registered journeys — include them in the known set so listing a
71
+ // real reaction id in ENABLED_JOURNEYS is not rejected as an unknown-id typo.
72
+ const reactionJourneyIds = collectBucketReactionJourneys(
73
+ opts.buckets ?? [],
74
+ enabledBuckets,
75
+ ).map((r) => r.meta.id);
76
+ const journeyTasks = selectJourneyTasks(
77
+ journeys,
78
+ enabled,
79
+ reactionJourneyIds,
80
+ );
67
81
  // The enabled journey IDs, logged at startup so a stale worker (one missing a
68
82
  // newly added journey because the dev watcher never restarted it) is visible
69
83
  // at a glance — counts alone can't show WHICH journeys are registered.
@@ -72,7 +86,6 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
72
86
  .filter((j) => journeyFilter === "*" || journeyFilter.has(j.meta.id))
73
87
  .map((j) => j.meta.id);
74
88
 
75
- const enabledBuckets = opts.enabledBuckets ?? container.env.ENABLED_BUCKETS;
76
89
  // The single place a bucket's per-user fast-expiry timer task is constructed
77
90
  // (Section 9.4): the shared `bucket:arm-expiry` durableTask, registered once iff
78
91
  // any enabled bucket opts into fastExpiry. The engine-wide time-based-leave