@hogsend/engine 0.40.0 → 0.41.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +9 -7
- package/src/buckets/check-membership.ts +6 -1
- package/src/campaigns/cohort-sql.ts +198 -0
- package/src/campaigns/define-campaign.ts +207 -28
- package/src/campaigns/reconcile.ts +105 -11
- package/src/campaigns/steps.ts +48 -0
- package/src/connectors/define-action.ts +70 -0
- package/src/container.ts +124 -42
- package/src/destinations/presets/posthog.ts +7 -1
- package/src/index.ts +82 -2
- package/src/journeys/constants.ts +10 -0
- package/src/journeys/define-journey.ts +14 -405
- package/src/journeys/execute-journey-run.ts +608 -0
- package/src/journeys/graph/build-graph.ts +212 -56
- package/src/journeys/journey-boundary.ts +54 -0
- package/src/journeys/journey-context.ts +374 -59
- package/src/journeys/record-once.ts +110 -0
- package/src/lib/blueprints.ts +576 -0
- package/src/lib/campaign-send-key.ts +58 -0
- package/src/lib/connector-actions.ts +203 -19
- package/src/lib/contacts.ts +54 -0
- package/src/lib/email-service-types.ts +4 -1
- package/src/lib/email.ts +13 -2
- package/src/lib/feed.ts +77 -57
- package/src/lib/frequency-cap.ts +45 -15
- package/src/lib/hatchet-duration.ts +22 -0
- package/src/lib/html.ts +1 -0
- package/src/lib/ingestion.ts +145 -4
- package/src/lib/journey-suppress.ts +87 -0
- package/src/lib/links.ts +204 -18
- package/src/lib/outbound.ts +20 -0
- package/src/lib/preferences.ts +80 -1
- package/src/lib/tracked.ts +44 -29
- package/src/lib/tracking-event-names.ts +8 -0
- package/src/lib/webhook-signing.ts +6 -1
- package/src/lists/channels.ts +75 -0
- package/src/lists/define-list.ts +34 -0
- package/src/lists/registry.ts +29 -2
- package/src/mcp/blueprint-tools.ts +460 -0
- package/src/routes/admin/blueprints.ts +711 -0
- package/src/routes/admin/campaigns.ts +179 -3
- package/src/routes/admin/emails.ts +13 -0
- package/src/routes/admin/index.ts +4 -0
- package/src/routes/admin/journeys.ts +4 -2
- package/src/routes/admin/links.ts +303 -36
- package/src/routes/admin/lists.ts +51 -0
- package/src/routes/campaigns/index.ts +44 -6
- package/src/routes/email/preferences.ts +50 -13
- package/src/routes/feed/recipient.ts +2 -43
- package/src/routes/index.ts +6 -0
- package/src/routes/lists/index.ts +138 -18
- package/src/routes/tracking/arrive.ts +260 -0
- package/src/routes/tracking/click-pipeline.ts +329 -0
- package/src/routes/tracking/click.ts +5 -270
- package/src/routes/tracking/index.ts +2 -0
- package/src/routes/tracking/vanity.ts +64 -0
- package/src/worker.ts +5 -0
- package/src/workflows/bucket-backfill.ts +4 -2
- package/src/workflows/bucket-reconcile.ts +11 -4
- package/src/workflows/check-alerts.ts +130 -1
- package/src/workflows/journey-blueprint-interpreter.ts +561 -0
- 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 {
|
|
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, [
|
|
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) {
|
|
@@ -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
|
-
|
|
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>,
|