@hogsend/engine 0.40.0 → 0.42.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/package.json +11 -8
  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 +96 -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 +641 -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 +406 -59
  17. package/src/journeys/record-once.ts +110 -0
  18. package/src/lib/blueprint-lock.ts +21 -0
  19. package/src/lib/blueprints.ts +803 -0
  20. package/src/lib/campaign-send-key.ts +58 -0
  21. package/src/lib/connector-actions.ts +203 -19
  22. package/src/lib/contacts.ts +54 -0
  23. package/src/lib/email-service-types.ts +4 -1
  24. package/src/lib/email.ts +13 -2
  25. package/src/lib/event-names.ts +143 -0
  26. package/src/lib/feed.ts +77 -57
  27. package/src/lib/frequency-cap.ts +45 -15
  28. package/src/lib/hatchet-duration.ts +22 -0
  29. package/src/lib/html.ts +1 -0
  30. package/src/lib/ingestion.ts +145 -4
  31. package/src/lib/journey-suppress.ts +87 -0
  32. package/src/lib/links.ts +204 -18
  33. package/src/lib/outbound.ts +20 -0
  34. package/src/lib/preferences.ts +80 -1
  35. package/src/lib/tracked.ts +44 -29
  36. package/src/lib/tracking-event-names.ts +8 -0
  37. package/src/lib/tracking.ts +1 -5
  38. package/src/lib/webhook-signing.ts +6 -1
  39. package/src/lists/channels.ts +75 -0
  40. package/src/lists/define-list.ts +34 -0
  41. package/src/lists/registry.ts +29 -2
  42. package/src/mcp/authoring-guide.ts +160 -0
  43. package/src/mcp/blueprint-tools.ts +390 -0
  44. package/src/middleware/require-admin.ts +13 -0
  45. package/src/routes/admin/api-keys.ts +72 -0
  46. package/src/routes/admin/blueprints.ts +795 -0
  47. package/src/routes/admin/campaigns.ts +179 -3
  48. package/src/routes/admin/emails.ts +13 -0
  49. package/src/routes/admin/events.ts +55 -0
  50. package/src/routes/admin/index.ts +4 -0
  51. package/src/routes/admin/journeys.ts +4 -2
  52. package/src/routes/admin/links.ts +303 -36
  53. package/src/routes/admin/lists.ts +51 -0
  54. package/src/routes/campaigns/index.ts +44 -6
  55. package/src/routes/email/preferences.ts +50 -13
  56. package/src/routes/feed/recipient.ts +2 -43
  57. package/src/routes/index.ts +6 -0
  58. package/src/routes/lists/index.ts +138 -18
  59. package/src/routes/tracking/arrive.ts +260 -0
  60. package/src/routes/tracking/click-pipeline.ts +329 -0
  61. package/src/routes/tracking/click.ts +5 -270
  62. package/src/routes/tracking/index.ts +2 -0
  63. package/src/routes/tracking/vanity.ts +64 -0
  64. package/src/worker.ts +5 -0
  65. package/src/workflows/bucket-backfill.ts +4 -2
  66. package/src/workflows/bucket-reconcile.ts +11 -4
  67. package/src/workflows/check-alerts.ts +130 -1
  68. package/src/workflows/journey-blueprint-interpreter.ts +656 -0
  69. package/src/workflows/send-campaign.ts +574 -180
@@ -6,10 +6,15 @@
6
6
  * Studio. The list/get/cancel semantics mirror `routes/campaigns/index.ts`
7
7
  * exactly (same serializer, same cancel CAS).
8
8
  */
9
- import { campaigns } from "@hogsend/db";
9
+ import { type CampaignStep, durationToMs } from "@hogsend/core";
10
+ import { campaigns, emailSends } from "@hogsend/db";
10
11
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
11
- import { and, desc, eq, inArray } from "drizzle-orm";
12
+ import { and, count, desc, eq, inArray, like, max, sql } from "drizzle-orm";
12
13
  import type { AppEnv } from "../../app.js";
14
+ import {
15
+ campaignSendKeyPattern,
16
+ campaignStepSendKeyPattern,
17
+ } from "../../lib/campaign-send-key.js";
13
18
  import { errorSchema } from "../../lib/schemas.js";
14
19
  import { campaignSchema, serializeCampaign } from "../campaigns/index.js";
15
20
 
@@ -60,6 +65,71 @@ const getRouteDef = createRoute({
60
65
  },
61
66
  });
62
67
 
68
+ /**
69
+ * One row of the per-step breakdown for a multi-step campaign: the step's
70
+ * identity (`kind` + `templateKey` for send steps, `durationMs` for wait
71
+ * steps) plus the same engagement aggregate as the campaign level, scoped to
72
+ * the step's `campaign:<id>:<step>:%` idempotency-key pattern. Wait steps
73
+ * deliver nothing, so their counts are zeroed.
74
+ */
75
+ const campaignStepStatsSchema = z.object({
76
+ index: z.number(),
77
+ kind: z.string(),
78
+ templateKey: z.string().nullable(),
79
+ durationMs: z.number().nullable(),
80
+ sends: z.number(),
81
+ delivered: z.number(),
82
+ opened: z.number(),
83
+ clicked: z.number(),
84
+ bounced: z.number(),
85
+ complained: z.number(),
86
+ failed: z.number(),
87
+ lastSentAt: z.string().nullable(),
88
+ });
89
+
90
+ /**
91
+ * Post-dispatch engagement for one campaign, aggregated from the `email_sends`
92
+ * rows the blast wrote (attributed via the `campaign:<id>:…` idempotency
93
+ * key — there is no campaign FK on email_sends). Complements the counters on
94
+ * the campaign row itself: the row knows sent/skipped/failed at dispatch time,
95
+ * this knows what happened to the mail AFTERWARDS (delivered/opened/clicked/
96
+ * bounced/complained via first-party tracking + provider webhooks). Multi-step
97
+ * campaigns additionally carry `steps` — one entry per step, in step order
98
+ * (the campaign-level numbers are a superset of every step's).
99
+ */
100
+ const campaignStatsSchema = z.object({
101
+ sends: z.number(),
102
+ delivered: z.number(),
103
+ opened: z.number(),
104
+ clicked: z.number(),
105
+ bounced: z.number(),
106
+ complained: z.number(),
107
+ failed: z.number(),
108
+ lastSentAt: z.string().nullable(),
109
+ steps: z.array(campaignStepStatsSchema).optional(),
110
+ });
111
+
112
+ const statsRouteDef = createRoute({
113
+ method: "get",
114
+ path: "/{id}/stats",
115
+ tags: ["Admin"],
116
+ summary: "Get a campaign's delivery + engagement stats (Studio)",
117
+ request: {
118
+ params: z.object({ id: z.string() }),
119
+ },
120
+ responses: {
121
+ 200: {
122
+ content: { "application/json": { schema: campaignStatsSchema } },
123
+ description:
124
+ "Engagement aggregated from the campaign's email sends, plus a per-step breakdown for multi-step campaigns",
125
+ },
126
+ 404: {
127
+ content: { "application/json": { schema: errorSchema } },
128
+ description: "Unknown campaign id",
129
+ },
130
+ },
131
+ });
132
+
63
133
  const cancelRouteDef = createRoute({
64
134
  method: "post",
65
135
  path: "/{id}/cancel",
@@ -128,10 +198,111 @@ export const adminCampaignsRouter = new OpenAPIHono<AppEnv>()
128
198
  }
129
199
  return c.json(serializeCampaign(rows[0]), 200);
130
200
  })
201
+ .openapi(statsRouteDef, async (c) => {
202
+ const { db } = c.get("container");
203
+ const { id } = c.req.valid("param");
204
+
205
+ const rows = await db
206
+ .select({ id: campaigns.id, steps: campaigns.steps })
207
+ .from(campaigns)
208
+ .where(eq(campaigns.id, id))
209
+ .limit(1);
210
+ const row = rows[0];
211
+ if (!row) {
212
+ return c.json({ error: `Unknown campaign: ${id}` }, 404);
213
+ }
214
+
215
+ // count(column) counts non-NULL values, so each engagement timestamp
216
+ // doubles as its own tally. No campaign FK on email_sends — the LIKE on the
217
+ // deterministic idempotency key is the attribution (admin-plane traffic, so
218
+ // the prefix scan is acceptable without a dedicated index). Shared by the
219
+ // campaign-level aggregate and the per-step breakdown.
220
+ const aggregate = async (pattern: string) => {
221
+ const agg = (
222
+ await db
223
+ .select({
224
+ sends: count(),
225
+ delivered: count(emailSends.deliveredAt),
226
+ opened: count(emailSends.openedAt),
227
+ clicked: count(emailSends.clickedAt),
228
+ bounced: count(emailSends.bouncedAt),
229
+ complained: count(emailSends.complainedAt),
230
+ failed:
231
+ sql<number>`count(*) filter (where ${emailSends.status} = 'failed')`.mapWith(
232
+ Number,
233
+ ),
234
+ lastSentAt: max(emailSends.sentAt),
235
+ })
236
+ .from(emailSends)
237
+ .where(like(emailSends.idempotencyKey, pattern))
238
+ )[0];
239
+ return {
240
+ sends: agg?.sends ?? 0,
241
+ delivered: agg?.delivered ?? 0,
242
+ opened: agg?.opened ?? 0,
243
+ clicked: agg?.clicked ?? 0,
244
+ bounced: agg?.bounced ?? 0,
245
+ complained: agg?.complained ?? 0,
246
+ failed: agg?.failed ?? 0,
247
+ lastSentAt: agg?.lastSentAt ? agg.lastSentAt.toISOString() : null,
248
+ };
249
+ };
250
+
251
+ // The campaign-level pattern (`campaign:<id>:%`) is a superset of both
252
+ // key formats, so these numbers are format-agnostic and unchanged for
253
+ // legacy single-send rows.
254
+ const campaignLevel = await aggregate(campaignSendKeyPattern(id));
255
+
256
+ // Per-step breakdown, only when the row carries a steps blob (NULL =
257
+ // legacy single-send — no `steps` in the response). Send-step aggregates
258
+ // filter on the step-scoped pattern (`campaign:<id>:<k>:%` — multi-step
259
+ // campaigns key ALL steps including 0 that way); wait steps deliver
260
+ // nothing. One query per step is fine at the ≤10-step cap on the
261
+ // admin plane.
262
+ const blob = row.steps;
263
+ if (!blob) {
264
+ return c.json(campaignLevel, 200);
265
+ }
266
+
267
+ // db cannot import @hogsend/core, so the blob's elements are opaque
268
+ // Record<string, unknown> there; the engine owns the narrowing.
269
+ const defs = blob.steps as unknown as CampaignStep[];
270
+ const steps: z.infer<typeof campaignStepStatsSchema>[] = [];
271
+ for (const [index, step] of defs.entries()) {
272
+ if (step.kind === "send") {
273
+ steps.push({
274
+ index,
275
+ kind: step.kind,
276
+ templateKey: step.template,
277
+ durationMs: null,
278
+ ...(await aggregate(campaignStepSendKeyPattern(id, index))),
279
+ });
280
+ } else {
281
+ steps.push({
282
+ index,
283
+ kind: step.kind,
284
+ templateKey: null,
285
+ durationMs: durationToMs(step.duration),
286
+ sends: 0,
287
+ delivered: 0,
288
+ opened: 0,
289
+ clicked: 0,
290
+ bounced: 0,
291
+ complained: 0,
292
+ failed: 0,
293
+ lastSentAt: null,
294
+ });
295
+ }
296
+ }
297
+
298
+ return c.json({ ...campaignLevel, steps }, 200);
299
+ })
131
300
  .openapi(cancelRouteDef, async (c) => {
132
301
  const { db } = c.get("container");
133
302
  const { id } = c.req.valid("param");
134
303
 
304
+ // CAS mirroring the data-plane cancel exactly — allowed from
305
+ // scheduled/queued/sending/waiting.
135
306
  const canceled = await db
136
307
  .update(campaigns)
137
308
  .set({
@@ -142,7 +313,12 @@ export const adminCampaignsRouter = new OpenAPIHono<AppEnv>()
142
313
  .where(
143
314
  and(
144
315
  eq(campaigns.id, id),
145
- inArray(campaigns.status, ["scheduled", "queued", "sending"]),
316
+ inArray(campaigns.status, [
317
+ "scheduled",
318
+ "queued",
319
+ "sending",
320
+ "waiting",
321
+ ]),
146
322
  ),
147
323
  )
148
324
  .returning();
@@ -17,10 +17,12 @@ import {
17
17
  inArray,
18
18
  isNotNull,
19
19
  isNull,
20
+ like,
20
21
  lte,
21
22
  or,
22
23
  } from "drizzle-orm";
23
24
  import type { AppEnv } from "../../app.js";
25
+ import { campaignSendKeyPattern } from "../../lib/campaign-send-key.js";
24
26
 
25
27
  const emailSchema = z.object({
26
28
  id: z.string(),
@@ -136,6 +138,11 @@ const listRoute = createRoute({
136
138
  ])
137
139
  .optional(),
138
140
  journeyId: z.string().optional(),
141
+ /**
142
+ * Only the sends of one campaign — matched on the deterministic
143
+ * `campaign:<id>:<email>` idempotency key the blast wrote per recipient.
144
+ */
145
+ campaignId: z.string().optional(),
139
146
  userId: z.string().optional(),
140
147
  category: z.string().optional(),
141
148
  engagement: z
@@ -241,6 +248,7 @@ export const emailsRouter = new OpenAPIHono<AppEnv>()
241
248
  templateKey,
242
249
  status,
243
250
  journeyId,
251
+ campaignId,
244
252
  userId,
245
253
  category,
246
254
  engagement,
@@ -270,6 +278,11 @@ export const emailsRouter = new OpenAPIHono<AppEnv>()
270
278
  if (status) conditions.push(eq(emailSends.status, status));
271
279
  if (category) conditions.push(eq(emailSends.category, category));
272
280
  if (journeyId) conditions.push(eq(journeyStates.journeyId, journeyId));
281
+ if (campaignId) {
282
+ conditions.push(
283
+ like(emailSends.idempotencyKey, campaignSendKeyPattern(campaignId)),
284
+ );
285
+ }
273
286
  // Match the denormalized identity OR the journey-state join, so journeyless
274
287
  // sends (which only carry the denormalized userId) are still filterable.
275
288
  if (userId) {
@@ -2,6 +2,10 @@ import { contacts, userEvents } from "@hogsend/db";
2
2
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
3
  import { and, count, desc, eq, gte, isNull, lte, or, sql } from "drizzle-orm";
4
4
  import type { AppEnv } from "../../app.js";
5
+ import {
6
+ eventNameEntrySchema,
7
+ listEventNameVocabulary,
8
+ } from "../../lib/event-names.js";
5
9
  import { ingestEvent } from "../../lib/ingestion.js";
6
10
 
7
11
  const eventSchema = z.object({
@@ -114,6 +118,41 @@ const getRoute = createRoute({
114
118
  },
115
119
  });
116
120
 
121
+ const namesRoute = createRoute({
122
+ method: "get",
123
+ path: "/names",
124
+ tags: ["Admin — Events"],
125
+ summary: "List event names (observed + declared)",
126
+ description:
127
+ "Best-effort event-name vocabulary for authoring triggers, waits, and " +
128
+ "exitOn rules. Event names are an OPEN vocabulary (no closed registry " +
129
+ "exists anywhere in the engine), so this merges: events actually " +
130
+ "observed in the event store (with occurrence counts, most recently " +
131
+ "seen first) and events referenced as code-journey or blueprint " +
132
+ "triggers. Any other event name is also valid — it just hasn't been " +
133
+ "seen yet.",
134
+ request: {
135
+ query: z.object({
136
+ // Case-insensitive substring filter on the event name.
137
+ search: z.string().min(1).optional(),
138
+ limit: z.coerce.number().int().min(1).max(200).default(100),
139
+ }),
140
+ },
141
+ responses: {
142
+ 200: {
143
+ content: {
144
+ "application/json": {
145
+ schema: z.object({
146
+ note: z.string(),
147
+ events: z.array(eventNameEntrySchema),
148
+ }),
149
+ },
150
+ },
151
+ description: "Merged observed + declared event-name vocabulary",
152
+ },
153
+ },
154
+ });
155
+
117
156
  const exitSchema = z.object({
118
157
  journeyId: z.string(),
119
158
  stateId: z.string(),
@@ -217,6 +256,22 @@ export const eventsRouter = new OpenAPIHono<AppEnv>()
217
256
  200,
218
257
  );
219
258
  })
259
+ // Registered before getRoute so the literal "names" is never captured as
260
+ // an {id}. Delegates to the shared vocabulary helper (lib/event-names.ts)
261
+ // — the same implementation the blueprint tools' `list_events` serves, so
262
+ // the HTTP surface and the in-process tool can never drift.
263
+ .openapi(namesRoute, async (c) => {
264
+ const { db, registry } = c.get("container");
265
+ const { search, limit } = c.req.valid("query");
266
+
267
+ const { note, events } = await listEventNameVocabulary({
268
+ db,
269
+ registry,
270
+ search,
271
+ limit,
272
+ });
273
+ return c.json({ note, events }, 200);
274
+ })
220
275
  .openapi(getRoute, async (c) => {
221
276
  const { db } = c.get("container");
222
277
  const { id } = c.req.valid("param");
@@ -8,6 +8,7 @@ import { alertsRouter } from "./alerts.js";
8
8
  import { analyticsAdminRouter } from "./analytics.js";
9
9
  import { apiKeysRouter } from "./api-keys.js";
10
10
  import { auditLogsRouter } from "./audit-logs.js";
11
+ import { blueprintsRouter } from "./blueprints.js";
11
12
  import { bucketsRouter } from "./buckets.js";
12
13
  import { bulkRouter } from "./bulk.js";
13
14
  import { adminCampaignsRouter } from "./campaigns.js";
@@ -20,6 +21,7 @@ import { eventsRouter } from "./events.js";
20
21
  import { journeyLogsRouter } from "./journey-logs.js";
21
22
  import { journeysRouter } from "./journeys.js";
22
23
  import { linksRouter } from "./links.js";
24
+ import { adminListsRouter } from "./lists.js";
23
25
  import { metricsRouter } from "./metrics.js";
24
26
  import { openEditorRouter } from "./open-editor.js";
25
27
  import { preferencesRouter } from "./preferences.js";
@@ -40,8 +42,10 @@ adminRouter.route("/contacts", contactsRouter);
40
42
  adminRouter.route("/contacts", preferencesRouter);
41
43
  adminRouter.route("/contacts", timelineRouter);
42
44
  adminRouter.route("/journeys", journeysRouter);
45
+ adminRouter.route("/blueprints", blueprintsRouter);
43
46
  adminRouter.route("/open-in-editor", openEditorRouter);
44
47
  adminRouter.route("/buckets", bucketsRouter);
48
+ adminRouter.route("/lists", adminListsRouter);
45
49
  adminRouter.route("/campaigns", adminCampaignsRouter);
46
50
  adminRouter.route("/events", eventsRouter);
47
51
  adminRouter.route("/emails", emailsRouter);
@@ -47,7 +47,9 @@ const journeySchema = z.object({
47
47
  }),
48
48
  });
49
49
 
50
- const stateSchema = z.object({
50
+ /** Shared with the blueprint admin routes — a blueprint enrollment is the
51
+ * same `journey_states` row shape (journeyId = the blueprint id). */
52
+ export const stateSchema = z.object({
51
53
  id: z.string(),
52
54
  userId: z.string(),
53
55
  userEmail: z.string(),
@@ -66,7 +68,7 @@ const stateSchema = z.object({
66
68
 
67
69
  const errorSchema = z.object({ error: z.string() });
68
70
 
69
- function serializeState(row: typeof journeyStates.$inferSelect) {
71
+ export function serializeState(row: typeof journeyStates.$inferSelect) {
70
72
  return {
71
73
  ...row,
72
74
  context: (row.context ?? {}) as Record<string, unknown>,