@hogsend/engine 0.39.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 +301 -0
- package/src/campaigns/reconcile.ts +391 -0
- package/src/campaigns/steps.ts +48 -0
- package/src/connectors/define-action.ts +70 -0
- package/src/container.ts +144 -42
- package/src/destinations/presets/posthog.ts +7 -1
- package/src/env.ts +14 -0
- package/src/index.ts +98 -3
- 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/auth.ts +33 -1
- 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 +341 -0
- package/src/routes/admin/emails.ts +13 -0
- package/src/routes/admin/index.ts +6 -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 +297 -50
- 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 +27 -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 +673 -127
package/src/lib/auth.ts
CHANGED
|
@@ -53,12 +53,44 @@ export function createAuth(opts: {
|
|
|
53
53
|
* better-auth's in-memory store on a bare instance with no Redis.
|
|
54
54
|
*/
|
|
55
55
|
secondaryStorage?: AuthSecondaryStorage;
|
|
56
|
+
/**
|
|
57
|
+
* Cookie-name namespace for THIS engine instance's Better Auth (passed to
|
|
58
|
+
* better-auth `advanced.cookiePrefix`). Better Auth names the session cookie
|
|
59
|
+
* `<__Secure->?<prefix>.session_token`; the default "better-auth" prefix
|
|
60
|
+
* collides with a sibling web app's cross-subdomain SSO cookie of the SAME
|
|
61
|
+
* name (e.g. course/docs on `.hogsend.com`) that the browser also delivers to
|
|
62
|
+
* the Studio host — but which resolves against a DIFFERENT database → null
|
|
63
|
+
* session → Studio login loop. Defaulting to "hogsend" gives the engine its
|
|
64
|
+
* own namespace (`__Secure-hogsend.session_token`) so that sibling cookie is
|
|
65
|
+
* simply ignored here. `cookiePrefix` only affects the cookie NAME — it is
|
|
66
|
+
* orthogonal to `crossSubDomainCookies` (the Domain attribute), which the
|
|
67
|
+
* engine never sets (host-only). `createHogsendClient` wires this from
|
|
68
|
+
* `env.AUTH_COOKIE_PREFIX`; the default is baked in below so every call site
|
|
69
|
+
* (including the headless CLI, which issues no cookie) stays aligned.
|
|
70
|
+
*/
|
|
71
|
+
cookiePrefix?: string;
|
|
56
72
|
}) {
|
|
57
|
-
const {
|
|
73
|
+
const {
|
|
74
|
+
db,
|
|
75
|
+
secret,
|
|
76
|
+
baseURL,
|
|
77
|
+
trustedOrigins,
|
|
78
|
+
sendResetPassword,
|
|
79
|
+
cookiePrefix,
|
|
80
|
+
} = opts;
|
|
58
81
|
return betterAuth({
|
|
59
82
|
basePath: "/api/auth",
|
|
60
83
|
secret,
|
|
61
84
|
baseURL,
|
|
85
|
+
// Namespace the engine's Better Auth cookies so its session cookie no longer
|
|
86
|
+
// shares a NAME with a sibling web app's `.hogsend.com` cross-subdomain SSO
|
|
87
|
+
// cookie that is also delivered to the Studio host (same name, different DB
|
|
88
|
+
// → null session → Studio login loop). Prefix-only; the Domain attribute
|
|
89
|
+
// (crossSubDomainCookies) is left UNSET → host-only cookie. Default
|
|
90
|
+
// "hogsend" → prod cookie `__Secure-hogsend.session_token`.
|
|
91
|
+
advanced: {
|
|
92
|
+
cookiePrefix: cookiePrefix ?? "hogsend",
|
|
93
|
+
},
|
|
62
94
|
...(trustedOrigins && trustedOrigins.length > 0 ? { trustedOrigins } : {}),
|
|
63
95
|
// Passing `secondaryStorage` flips better-auth's rate-limit storage from the
|
|
64
96
|
// per-instance in-memory default to this shared store (see option doc).
|
|
@@ -0,0 +1,576 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Journey Blueprint service layer — the ONE write path for
|
|
3
|
+
* `journey_blueprints`, shared verbatim by the admin routes
|
|
4
|
+
* (`routes/admin/blueprints.ts`) and the agent-facing tools
|
|
5
|
+
* (`mcp/blueprint-tools.ts`). Spec §9's "the MCP tool is a thin wrapper over
|
|
6
|
+
* these — no parallel auth or storage path" is enforced structurally: both
|
|
7
|
+
* surfaces call these functions in-process, so there is nothing to drift.
|
|
8
|
+
*
|
|
9
|
+
* This module is the save-time sandbox boundary of the whole feature
|
|
10
|
+
* (spec §8): a graph is NEVER written without passing
|
|
11
|
+
* {@link validateBlueprintGraphForSave} — `validateBlueprintGraph` (field
|
|
12
|
+
* shapes + structural checks, @hogsend/core) layered with the engine-side
|
|
13
|
+
* registry checks core cannot do (template keys, connector actions).
|
|
14
|
+
*
|
|
15
|
+
* Conventions (shared by both surfaces):
|
|
16
|
+
* - the blueprint id IS the graph's `journeyId` (one id, one namespace —
|
|
17
|
+
* `journeyStates.journeyId` points at it, same as a code journey's meta.id)
|
|
18
|
+
* - `version` bumps on any update that includes `graph` (metadata-only edits
|
|
19
|
+
* don't bump; we deliberately don't deep-diff — jsonb normalizes key order,
|
|
20
|
+
* so equality checks would be unreliable, and a spurious bump is harmless)
|
|
21
|
+
* - a graph-changing update is REJECTED (`in_flight` failure) while the
|
|
22
|
+
* blueprint has any active/waiting `journeyStates` rows — Hatchet's
|
|
23
|
+
* durable sleep/wait primitives are matched positionally on replay, so
|
|
24
|
+
* changing the node sequence out from under a suspended run can desync
|
|
25
|
+
* its replay journal. Code journeys don't have this hazard (their
|
|
26
|
+
* `run()` is immutable compiled code); a blueprint's graph is a mutable
|
|
27
|
+
* row, so this is an explicit gate, not an implicit guarantee
|
|
28
|
+
* - enabling always re-runs validation against the CURRENT registries — a
|
|
29
|
+
* template unregistered since save is caught here, not at 2am mid-run
|
|
30
|
+
* - expected failures are result objects (discriminated on `ok`/`code`)
|
|
31
|
+
* carrying the structured `BlueprintValidationIssue[]` verbatim — never a
|
|
32
|
+
* caught exception's `.message`
|
|
33
|
+
*/
|
|
34
|
+
import {
|
|
35
|
+
type BlueprintGraph,
|
|
36
|
+
type BlueprintValidationIssue,
|
|
37
|
+
type BlueprintValidationResult,
|
|
38
|
+
blueprintGraphSchema,
|
|
39
|
+
type JourneyGraph,
|
|
40
|
+
journeyGraphSchema,
|
|
41
|
+
validateBlueprintGraph,
|
|
42
|
+
} from "@hogsend/core";
|
|
43
|
+
import { propertyConditionSchema } from "@hogsend/core/schemas";
|
|
44
|
+
import { journeyBlueprints, journeyStates } from "@hogsend/db";
|
|
45
|
+
import { getTemplateNames } from "@hogsend/email";
|
|
46
|
+
import { z } from "@hono/zod-openapi";
|
|
47
|
+
import { and, count, eq, inArray, isNull } from "drizzle-orm";
|
|
48
|
+
import type { HogsendClient } from "../container.js";
|
|
49
|
+
|
|
50
|
+
export type BlueprintRow = typeof journeyBlueprints.$inferSelect;
|
|
51
|
+
/** The opaque jsonb type of the `graph` column (db cannot import core). */
|
|
52
|
+
type BlueprintGraphColumn = BlueprintRow["graph"];
|
|
53
|
+
|
|
54
|
+
/** What graph validation needs from the container. */
|
|
55
|
+
export type BlueprintRegistryContainer = Pick<
|
|
56
|
+
HogsendClient,
|
|
57
|
+
"templates" | "connectorActionRegistry"
|
|
58
|
+
>;
|
|
59
|
+
|
|
60
|
+
/** What the write operations need from the container. */
|
|
61
|
+
export type BlueprintServiceContainer = Pick<
|
|
62
|
+
HogsendClient,
|
|
63
|
+
"db" | "registry" | "templates" | "connectorActionRegistry"
|
|
64
|
+
>;
|
|
65
|
+
|
|
66
|
+
// ---------------------------------------------------------------------------
|
|
67
|
+
// Save-time validation — core checks + engine registry checks
|
|
68
|
+
// ---------------------------------------------------------------------------
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* The engine-side half of the save-time sandbox (spec §8): every node input
|
|
72
|
+
* is checked against a KNOWN registry, so a `send` of a template that isn't
|
|
73
|
+
* registered (or a connector action that doesn't exist) fails at save time
|
|
74
|
+
* with a structured issue, not at run time. @hogsend/core cannot do these —
|
|
75
|
+
* the registries live in the container.
|
|
76
|
+
*/
|
|
77
|
+
function findRegistryIssues(
|
|
78
|
+
graph: BlueprintGraph,
|
|
79
|
+
container: BlueprintRegistryContainer,
|
|
80
|
+
): BlueprintValidationIssue[] {
|
|
81
|
+
const issues: BlueprintValidationIssue[] = [];
|
|
82
|
+
const templateKeys = new Set<string>(getTemplateNames(container.templates));
|
|
83
|
+
graph.nodes.forEach((node, index) => {
|
|
84
|
+
if (node.type === "send" && !templateKeys.has(node.meta.template)) {
|
|
85
|
+
issues.push({
|
|
86
|
+
nodeId: node.id,
|
|
87
|
+
path: ["nodes", index, "meta", "template"],
|
|
88
|
+
code: "unknown_template",
|
|
89
|
+
message: `node "${node.id}": "${node.meta.template}" is not a registered template key`,
|
|
90
|
+
});
|
|
91
|
+
}
|
|
92
|
+
if (node.type === "connector") {
|
|
93
|
+
const { connectorId, action } = node.meta;
|
|
94
|
+
if (!container.connectorActionRegistry.get(connectorId, action)) {
|
|
95
|
+
issues.push({
|
|
96
|
+
nodeId: node.id,
|
|
97
|
+
path: ["nodes", index, "meta", "connectorId"],
|
|
98
|
+
code: "unknown_connector_action",
|
|
99
|
+
message: `node "${node.id}": no connector action "${connectorId}:${action}" is registered`,
|
|
100
|
+
});
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
});
|
|
104
|
+
return issues;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* Full save-time validation: `validateBlueprintGraph` (field shapes +
|
|
109
|
+
* structural checks) plus the registry checks above. Used by create, update
|
|
110
|
+
* (when `graph` is present), enable (re-check against CURRENT registries),
|
|
111
|
+
* and every validate surface — one validation story for every write path.
|
|
112
|
+
*
|
|
113
|
+
* When the graph parses field-wise but fails STRUCTURALLY, the registry
|
|
114
|
+
* issues are still appended to the report — an iterating agent gets the whole
|
|
115
|
+
* "what's wrong" list in one round instead of discovering the unknown
|
|
116
|
+
* template only after fixing the cycle.
|
|
117
|
+
*/
|
|
118
|
+
export function validateBlueprintGraphForSave(
|
|
119
|
+
graph: unknown,
|
|
120
|
+
container: BlueprintRegistryContainer,
|
|
121
|
+
): BlueprintValidationResult {
|
|
122
|
+
const result = validateBlueprintGraph(graph);
|
|
123
|
+
if (result.valid) {
|
|
124
|
+
const issues = findRegistryIssues(result.graph, container);
|
|
125
|
+
if (issues.length > 0) return { valid: false, issues };
|
|
126
|
+
return result;
|
|
127
|
+
}
|
|
128
|
+
// Structural failure: the field shapes may still have parsed, in which case
|
|
129
|
+
// the send/connector nodes are inspectable — report registry problems too.
|
|
130
|
+
const parsed = blueprintGraphSchema.safeParse(graph);
|
|
131
|
+
if (!parsed.success) return result;
|
|
132
|
+
return {
|
|
133
|
+
valid: false,
|
|
134
|
+
issues: [
|
|
135
|
+
...result.issues,
|
|
136
|
+
...findRegistryIssues(
|
|
137
|
+
parsed.data as unknown as BlueprintGraph,
|
|
138
|
+
container,
|
|
139
|
+
),
|
|
140
|
+
],
|
|
141
|
+
};
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
// ---------------------------------------------------------------------------
|
|
145
|
+
// Shared input schemas — one source of truth for admin routes AND tools
|
|
146
|
+
// ---------------------------------------------------------------------------
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* Execution-tier duration INPUT: strict keys so `{ days: 3 }` is rejected
|
|
150
|
+
* loudly instead of becoming a silent zero (`durationToMs` ignores unknown
|
|
151
|
+
* keys). Empty `{}` is allowed — for `suppress` it means "disabled", same
|
|
152
|
+
* contract as JourneyMeta.suppress.
|
|
153
|
+
*/
|
|
154
|
+
export const blueprintDurationInputSchema = z.strictObject({
|
|
155
|
+
hours: z.number().nonnegative().optional(),
|
|
156
|
+
minutes: z.number().nonnegative().optional(),
|
|
157
|
+
seconds: z.number().nonnegative().optional(),
|
|
158
|
+
});
|
|
159
|
+
|
|
160
|
+
export const blueprintExitOnInputSchema = z.array(
|
|
161
|
+
z.object({
|
|
162
|
+
event: z.string().min(1),
|
|
163
|
+
where: z.array(propertyConditionSchema).optional(),
|
|
164
|
+
}),
|
|
165
|
+
);
|
|
166
|
+
|
|
167
|
+
export const blueprintStatusSchema = z.enum(["draft", "enabled", "disabled"]);
|
|
168
|
+
export const blueprintEntryLimitSchema = z.enum([
|
|
169
|
+
"once",
|
|
170
|
+
"once_per_period",
|
|
171
|
+
"unlimited",
|
|
172
|
+
]);
|
|
173
|
+
export const blueprintSourceSchema = z.enum(["mcp", "studio", "api"]);
|
|
174
|
+
|
|
175
|
+
// The graph is accepted as `unknown` and validated by
|
|
176
|
+
// validateBlueprintGraphForSave — so a malformed graph ALWAYS yields the
|
|
177
|
+
// structured issue list, never a schema layer's generic error.
|
|
178
|
+
export const blueprintGraphInputSchema = z.unknown();
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* The create payload MINUS `source` — provenance is stamped by the surface
|
|
182
|
+
* (the admin route takes it from the request body; the agent tools hard-code
|
|
183
|
+
* `"mcp"`), never trusted to mean the same thing across surfaces.
|
|
184
|
+
*/
|
|
185
|
+
export const blueprintCreateBaseSchema = z.object({
|
|
186
|
+
name: z.string().min(1),
|
|
187
|
+
description: z.string().optional(),
|
|
188
|
+
/**
|
|
189
|
+
* Defaults to "draft"; a caller MAY create directly enabled (spec §10 —
|
|
190
|
+
* post-hoc oversight, no forced staging step). "disabled" makes no sense
|
|
191
|
+
* at creation and is rejected.
|
|
192
|
+
*/
|
|
193
|
+
status: z.enum(["draft", "enabled"]).default("draft"),
|
|
194
|
+
triggerEvent: z.string().min(1),
|
|
195
|
+
triggerWhere: z.array(propertyConditionSchema).optional(),
|
|
196
|
+
entryLimit: blueprintEntryLimitSchema,
|
|
197
|
+
entryPeriod: blueprintDurationInputSchema.optional(),
|
|
198
|
+
exitOn: blueprintExitOnInputSchema.optional(),
|
|
199
|
+
suppress: blueprintDurationInputSchema,
|
|
200
|
+
graph: blueprintGraphInputSchema,
|
|
201
|
+
createdBy: z.string().min(1).optional(),
|
|
202
|
+
});
|
|
203
|
+
|
|
204
|
+
/**
|
|
205
|
+
* Partial-update fields. `status` is deliberately absent — transitions go
|
|
206
|
+
* through enable/disable so enabling always re-validates. `source`/`createdBy`
|
|
207
|
+
* are provenance and immutable. Nullable fields accept null to clear.
|
|
208
|
+
* Callers layer their own "at least one field" refinement on top (the routes
|
|
209
|
+
* on the body, the tools excluding `id`).
|
|
210
|
+
*/
|
|
211
|
+
export const blueprintPatchFieldsSchema = z.object({
|
|
212
|
+
name: z.string().min(1).optional(),
|
|
213
|
+
description: z.string().nullable().optional(),
|
|
214
|
+
triggerEvent: z.string().min(1).optional(),
|
|
215
|
+
triggerWhere: z.array(propertyConditionSchema).nullable().optional(),
|
|
216
|
+
entryLimit: blueprintEntryLimitSchema.optional(),
|
|
217
|
+
entryPeriod: blueprintDurationInputSchema.nullable().optional(),
|
|
218
|
+
exitOn: blueprintExitOnInputSchema.nullable().optional(),
|
|
219
|
+
suppress: blueprintDurationInputSchema.optional(),
|
|
220
|
+
graph: blueprintGraphInputSchema.optional(),
|
|
221
|
+
});
|
|
222
|
+
|
|
223
|
+
export type CreateBlueprintInput = z.infer<typeof blueprintCreateBaseSchema> & {
|
|
224
|
+
source: z.infer<typeof blueprintSourceSchema>;
|
|
225
|
+
};
|
|
226
|
+
export type UpdateBlueprintPatch = z.infer<typeof blueprintPatchFieldsSchema>;
|
|
227
|
+
|
|
228
|
+
// ---------------------------------------------------------------------------
|
|
229
|
+
// Serialization — flat row shape shared by routes and tools
|
|
230
|
+
// ---------------------------------------------------------------------------
|
|
231
|
+
|
|
232
|
+
// Row serialization is FLAT (column names verbatim: triggerEvent,
|
|
233
|
+
// triggerWhere, …) so a read → edit → update loop round-trips 1:1 with the
|
|
234
|
+
// write inputs above. Stored jsonb is echoed loosely (the strict shapes were
|
|
235
|
+
// enforced at write time).
|
|
236
|
+
export const serializedBlueprintSchema = z.object({
|
|
237
|
+
id: z.string(),
|
|
238
|
+
name: z.string(),
|
|
239
|
+
description: z.string().nullable(),
|
|
240
|
+
status: blueprintStatusSchema,
|
|
241
|
+
version: z.number(),
|
|
242
|
+
triggerEvent: z.string(),
|
|
243
|
+
triggerWhere: z.array(z.record(z.string(), z.unknown())).nullable(),
|
|
244
|
+
entryLimit: blueprintEntryLimitSchema,
|
|
245
|
+
entryPeriod: z.record(z.string(), z.number()).nullable(),
|
|
246
|
+
exitOn: z
|
|
247
|
+
.array(
|
|
248
|
+
z.object({
|
|
249
|
+
event: z.string(),
|
|
250
|
+
where: z.array(z.record(z.string(), z.unknown())).optional(),
|
|
251
|
+
}),
|
|
252
|
+
)
|
|
253
|
+
.nullable(),
|
|
254
|
+
suppress: z.record(z.string(), z.number()),
|
|
255
|
+
graph: journeyGraphSchema,
|
|
256
|
+
source: blueprintSourceSchema,
|
|
257
|
+
createdBy: z.string().nullable(),
|
|
258
|
+
promotedAt: z.string().nullable(),
|
|
259
|
+
promotedToJourneyId: z.string().nullable(),
|
|
260
|
+
createdAt: z.string(),
|
|
261
|
+
updatedAt: z.string(),
|
|
262
|
+
});
|
|
263
|
+
|
|
264
|
+
export type SerializedBlueprint = z.infer<typeof serializedBlueprintSchema>;
|
|
265
|
+
|
|
266
|
+
export function serializeBlueprint(row: BlueprintRow): SerializedBlueprint {
|
|
267
|
+
return {
|
|
268
|
+
id: row.id,
|
|
269
|
+
name: row.name,
|
|
270
|
+
description: row.description,
|
|
271
|
+
status: row.status,
|
|
272
|
+
version: row.version,
|
|
273
|
+
triggerEvent: row.triggerEvent,
|
|
274
|
+
triggerWhere: row.triggerWhere ?? null,
|
|
275
|
+
entryLimit: row.entryLimit,
|
|
276
|
+
entryPeriod: (row.entryPeriod ?? null) as Record<string, number> | null,
|
|
277
|
+
exitOn: row.exitOn ?? null,
|
|
278
|
+
suppress: row.suppress as Record<string, number>,
|
|
279
|
+
graph: row.graph as unknown as JourneyGraph,
|
|
280
|
+
source: row.source,
|
|
281
|
+
createdBy: row.createdBy,
|
|
282
|
+
promotedAt: row.promotedAt?.toISOString() ?? null,
|
|
283
|
+
promotedToJourneyId: row.promotedToJourneyId,
|
|
284
|
+
createdAt: row.createdAt.toISOString(),
|
|
285
|
+
updatedAt: row.updatedAt.toISOString(),
|
|
286
|
+
};
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
// ---------------------------------------------------------------------------
|
|
290
|
+
// Operations — precise per-operation result unions
|
|
291
|
+
// ---------------------------------------------------------------------------
|
|
292
|
+
|
|
293
|
+
export type BlueprintInvalidGraphFailure = {
|
|
294
|
+
ok: false;
|
|
295
|
+
code: "invalid_graph";
|
|
296
|
+
error: string;
|
|
297
|
+
issues: BlueprintValidationIssue[];
|
|
298
|
+
};
|
|
299
|
+
export type BlueprintNotFoundFailure = {
|
|
300
|
+
ok: false;
|
|
301
|
+
code: "not_found";
|
|
302
|
+
error: string;
|
|
303
|
+
};
|
|
304
|
+
|
|
305
|
+
export type CreateBlueprintResult =
|
|
306
|
+
| { ok: true; blueprint: BlueprintRow }
|
|
307
|
+
| { ok: false; code: "conflict"; error: string }
|
|
308
|
+
| BlueprintInvalidGraphFailure;
|
|
309
|
+
|
|
310
|
+
export type UpdateBlueprintResult =
|
|
311
|
+
| { ok: true; blueprint: BlueprintRow }
|
|
312
|
+
| BlueprintNotFoundFailure
|
|
313
|
+
| BlueprintInvalidGraphFailure
|
|
314
|
+
| { ok: false; code: "in_flight"; error: string };
|
|
315
|
+
|
|
316
|
+
export type EnableBlueprintResult =
|
|
317
|
+
| { ok: true; blueprint: BlueprintRow }
|
|
318
|
+
| BlueprintNotFoundFailure
|
|
319
|
+
| { ok: false; code: "promoted"; error: string }
|
|
320
|
+
| BlueprintInvalidGraphFailure;
|
|
321
|
+
|
|
322
|
+
export type DisableBlueprintResult =
|
|
323
|
+
| { ok: true; blueprint: BlueprintRow }
|
|
324
|
+
| BlueprintNotFoundFailure;
|
|
325
|
+
|
|
326
|
+
export async function findBlueprintRow(opts: {
|
|
327
|
+
db: HogsendClient["db"];
|
|
328
|
+
id: string;
|
|
329
|
+
}): Promise<BlueprintRow | null> {
|
|
330
|
+
const rows = await opts.db
|
|
331
|
+
.select()
|
|
332
|
+
.from(journeyBlueprints)
|
|
333
|
+
.where(eq(journeyBlueprints.id, opts.id))
|
|
334
|
+
.limit(1);
|
|
335
|
+
return rows[0] ?? null;
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
function notFound(id: string): BlueprintNotFoundFailure {
|
|
339
|
+
return { ok: false, code: "not_found", error: `Blueprint "${id}" not found` };
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
/**
|
|
343
|
+
* Create a blueprint. The graph is validated (schema + structure +
|
|
344
|
+
* template/connector registries) before anything is written — an invalid
|
|
345
|
+
* graph is never saved. The blueprint id is the graph's `journeyId`.
|
|
346
|
+
*/
|
|
347
|
+
export async function createBlueprint(opts: {
|
|
348
|
+
container: BlueprintServiceContainer;
|
|
349
|
+
input: CreateBlueprintInput;
|
|
350
|
+
}): Promise<CreateBlueprintResult> {
|
|
351
|
+
const { container, input } = opts;
|
|
352
|
+
|
|
353
|
+
const result = validateBlueprintGraphForSave(input.graph, container);
|
|
354
|
+
if (!result.valid) {
|
|
355
|
+
return {
|
|
356
|
+
ok: false,
|
|
357
|
+
code: "invalid_graph",
|
|
358
|
+
error: "Blueprint graph failed validation",
|
|
359
|
+
issues: result.issues,
|
|
360
|
+
};
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
// The graph's journeyId IS the blueprint id — one id, one namespace.
|
|
364
|
+
//
|
|
365
|
+
// KNOWN GAP (documented, not fixed): this only guards the direction where
|
|
366
|
+
// a blueprint is created AFTER a colliding code journey is already
|
|
367
|
+
// registered. The reverse — deploying a NEW code journey whose id matches
|
|
368
|
+
// an EXISTING blueprint's id — isn't guarded anywhere; both would then
|
|
369
|
+
// share journeyStates.journeyId, and exit-condition resolution favors the
|
|
370
|
+
// registered code journey. Closing this needs a boot-time cross-check
|
|
371
|
+
// against journey_blueprints, deliberately left for when this actually
|
|
372
|
+
// bites someone rather than adding DB-dependent boot machinery now.
|
|
373
|
+
const id = result.graph.journeyId;
|
|
374
|
+
if (container.registry.has(id)) {
|
|
375
|
+
return {
|
|
376
|
+
ok: false,
|
|
377
|
+
code: "conflict",
|
|
378
|
+
error: `"${id}" is a registered code journey — blueprint ids share the journey id namespace`,
|
|
379
|
+
};
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
// onConflictDoNothing + returning: the empty result IS the duplicate
|
|
383
|
+
// check, atomically (no read-then-insert race).
|
|
384
|
+
const inserted = await container.db
|
|
385
|
+
.insert(journeyBlueprints)
|
|
386
|
+
.values({
|
|
387
|
+
id,
|
|
388
|
+
name: input.name,
|
|
389
|
+
description: input.description ?? null,
|
|
390
|
+
status: input.status,
|
|
391
|
+
triggerEvent: input.triggerEvent,
|
|
392
|
+
triggerWhere: input.triggerWhere ?? null,
|
|
393
|
+
entryLimit: input.entryLimit,
|
|
394
|
+
entryPeriod: input.entryPeriod ?? null,
|
|
395
|
+
exitOn: input.exitOn ?? null,
|
|
396
|
+
suppress: input.suppress,
|
|
397
|
+
graph: result.graph as unknown as BlueprintGraphColumn,
|
|
398
|
+
source: input.source,
|
|
399
|
+
createdBy: input.createdBy ?? null,
|
|
400
|
+
})
|
|
401
|
+
.onConflictDoNothing({ target: journeyBlueprints.id })
|
|
402
|
+
.returning();
|
|
403
|
+
|
|
404
|
+
const row = inserted[0];
|
|
405
|
+
if (!row) {
|
|
406
|
+
return {
|
|
407
|
+
ok: false,
|
|
408
|
+
code: "conflict",
|
|
409
|
+
error: `Blueprint "${id}" already exists`,
|
|
410
|
+
};
|
|
411
|
+
}
|
|
412
|
+
return { ok: true, blueprint: row };
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
/**
|
|
416
|
+
* Partial update. A `graph` change is re-validated the same way create is
|
|
417
|
+
* and bumps `version` by 1 (in-flight runs stay pinned to the version they
|
|
418
|
+
* enrolled under, spec §12). Metadata-only edits do not bump. Status
|
|
419
|
+
* transitions go through enable/disable, not here.
|
|
420
|
+
*/
|
|
421
|
+
export async function updateBlueprint(opts: {
|
|
422
|
+
container: BlueprintServiceContainer;
|
|
423
|
+
id: string;
|
|
424
|
+
patch: UpdateBlueprintPatch;
|
|
425
|
+
}): Promise<UpdateBlueprintResult> {
|
|
426
|
+
const { container, id, patch } = opts;
|
|
427
|
+
|
|
428
|
+
const existing = await findBlueprintRow({ db: container.db, id });
|
|
429
|
+
if (!existing) return notFound(id);
|
|
430
|
+
|
|
431
|
+
let validatedGraph: BlueprintGraph | undefined;
|
|
432
|
+
if (patch.graph !== undefined) {
|
|
433
|
+
const result = validateBlueprintGraphForSave(patch.graph, container);
|
|
434
|
+
if (!result.valid) {
|
|
435
|
+
return {
|
|
436
|
+
ok: false,
|
|
437
|
+
code: "invalid_graph",
|
|
438
|
+
error: "Blueprint graph failed validation",
|
|
439
|
+
issues: result.issues,
|
|
440
|
+
};
|
|
441
|
+
}
|
|
442
|
+
if (result.graph.journeyId !== id) {
|
|
443
|
+
return {
|
|
444
|
+
ok: false,
|
|
445
|
+
code: "invalid_graph",
|
|
446
|
+
error: "Graph journeyId does not match the blueprint id",
|
|
447
|
+
issues: [
|
|
448
|
+
{
|
|
449
|
+
path: ["journeyId"],
|
|
450
|
+
code: "journey_id_mismatch",
|
|
451
|
+
message: `graph.journeyId "${result.graph.journeyId}" must match the blueprint id "${id}" — the id is immutable`,
|
|
452
|
+
},
|
|
453
|
+
],
|
|
454
|
+
};
|
|
455
|
+
}
|
|
456
|
+
validatedGraph = result.graph;
|
|
457
|
+
|
|
458
|
+
// Graph edits are unsafe while a run is suspended mid-graph (positional
|
|
459
|
+
// replay journal, see module header) — block it outright rather than
|
|
460
|
+
// relying on a version pin that can't actually protect a resume.
|
|
461
|
+
const [inFlight] = await container.db
|
|
462
|
+
.select({ count: count() })
|
|
463
|
+
.from(journeyStates)
|
|
464
|
+
.where(
|
|
465
|
+
and(
|
|
466
|
+
eq(journeyStates.journeyId, id),
|
|
467
|
+
isNull(journeyStates.deletedAt),
|
|
468
|
+
inArray(journeyStates.status, ["active", "waiting"]),
|
|
469
|
+
),
|
|
470
|
+
);
|
|
471
|
+
if (inFlight && inFlight.count > 0) {
|
|
472
|
+
return {
|
|
473
|
+
ok: false,
|
|
474
|
+
code: "in_flight",
|
|
475
|
+
error: `Cannot edit this blueprint's graph while ${inFlight.count} enrollment(s) are active or waiting — editing a live graph can desync Hatchet's replay journal for an in-flight run. Wait for enrollments to drain, or disable the blueprint and let them finish, before editing the graph.`,
|
|
476
|
+
};
|
|
477
|
+
}
|
|
478
|
+
}
|
|
479
|
+
|
|
480
|
+
const set: Partial<typeof journeyBlueprints.$inferInsert> = {
|
|
481
|
+
updatedAt: new Date(),
|
|
482
|
+
};
|
|
483
|
+
if (patch.name !== undefined) set.name = patch.name;
|
|
484
|
+
if (patch.description !== undefined) set.description = patch.description;
|
|
485
|
+
if (patch.triggerEvent !== undefined) set.triggerEvent = patch.triggerEvent;
|
|
486
|
+
if (patch.triggerWhere !== undefined) set.triggerWhere = patch.triggerWhere;
|
|
487
|
+
if (patch.entryLimit !== undefined) set.entryLimit = patch.entryLimit;
|
|
488
|
+
if (patch.entryPeriod !== undefined) set.entryPeriod = patch.entryPeriod;
|
|
489
|
+
if (patch.exitOn !== undefined) set.exitOn = patch.exitOn;
|
|
490
|
+
if (patch.suppress !== undefined) set.suppress = patch.suppress;
|
|
491
|
+
if (validatedGraph !== undefined) {
|
|
492
|
+
set.graph = validatedGraph as unknown as BlueprintGraphColumn;
|
|
493
|
+
// Version bump rule: any update carrying `graph` bumps (documented in
|
|
494
|
+
// the module header). Safe to bump unconditionally here — the in-flight
|
|
495
|
+
// check above already rejected this request if any run could observe
|
|
496
|
+
// the change mid-flight.
|
|
497
|
+
set.version = existing.version + 1;
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
const updated = await container.db
|
|
501
|
+
.update(journeyBlueprints)
|
|
502
|
+
.set(set)
|
|
503
|
+
.where(eq(journeyBlueprints.id, id))
|
|
504
|
+
.returning();
|
|
505
|
+
|
|
506
|
+
const row = updated[0];
|
|
507
|
+
if (!row) return notFound(id);
|
|
508
|
+
return { ok: true, blueprint: row };
|
|
509
|
+
}
|
|
510
|
+
|
|
511
|
+
/**
|
|
512
|
+
* Enable — the moment a graph goes live, so the stored graph is re-validated
|
|
513
|
+
* against the CURRENT registries first (a blueprint whose template/connector
|
|
514
|
+
* vanished since save cannot go live). Idempotent when already enabled. A
|
|
515
|
+
* promoted blueprint cannot be re-enabled — the code journey is the source
|
|
516
|
+
* of truth (spec §11).
|
|
517
|
+
*/
|
|
518
|
+
export async function enableBlueprint(opts: {
|
|
519
|
+
container: BlueprintServiceContainer;
|
|
520
|
+
id: string;
|
|
521
|
+
}): Promise<EnableBlueprintResult> {
|
|
522
|
+
const { container, id } = opts;
|
|
523
|
+
|
|
524
|
+
const existing = await findBlueprintRow({ db: container.db, id });
|
|
525
|
+
if (!existing) return notFound(id);
|
|
526
|
+
if (existing.promotedAt) {
|
|
527
|
+
return {
|
|
528
|
+
ok: false,
|
|
529
|
+
code: "promoted",
|
|
530
|
+
error: `Blueprint "${id}" was promoted to code (${existing.promotedToJourneyId ?? "unknown journey"}) — the code journey is the source of truth; it cannot be re-enabled`,
|
|
531
|
+
};
|
|
532
|
+
}
|
|
533
|
+
|
|
534
|
+
const result = validateBlueprintGraphForSave(existing.graph, container);
|
|
535
|
+
if (!result.valid) {
|
|
536
|
+
return {
|
|
537
|
+
ok: false,
|
|
538
|
+
code: "invalid_graph",
|
|
539
|
+
error:
|
|
540
|
+
"Stored graph no longer passes validation — fix it before enabling",
|
|
541
|
+
issues: result.issues,
|
|
542
|
+
};
|
|
543
|
+
}
|
|
544
|
+
|
|
545
|
+
const updated = await container.db
|
|
546
|
+
.update(journeyBlueprints)
|
|
547
|
+
.set({ status: "enabled", updatedAt: new Date() })
|
|
548
|
+
.where(eq(journeyBlueprints.id, id))
|
|
549
|
+
.returning();
|
|
550
|
+
|
|
551
|
+
const row = updated[0];
|
|
552
|
+
if (!row) return notFound(id);
|
|
553
|
+
return { ok: true, blueprint: row };
|
|
554
|
+
}
|
|
555
|
+
|
|
556
|
+
/**
|
|
557
|
+
* Disable — new enrollments stop on the next event; in-flight runs keep
|
|
558
|
+
* going (spec §12 — matches how code journeys behave when enabled flips
|
|
559
|
+
* off). Idempotent when already disabled.
|
|
560
|
+
*/
|
|
561
|
+
export async function disableBlueprint(opts: {
|
|
562
|
+
container: BlueprintServiceContainer;
|
|
563
|
+
id: string;
|
|
564
|
+
}): Promise<DisableBlueprintResult> {
|
|
565
|
+
const { container, id } = opts;
|
|
566
|
+
|
|
567
|
+
const updated = await container.db
|
|
568
|
+
.update(journeyBlueprints)
|
|
569
|
+
.set({ status: "disabled", updatedAt: new Date() })
|
|
570
|
+
.where(eq(journeyBlueprints.id, id))
|
|
571
|
+
.returning();
|
|
572
|
+
|
|
573
|
+
const row = updated[0];
|
|
574
|
+
if (!row) return notFound(id);
|
|
575
|
+
return { ok: true, blueprint: row };
|
|
576
|
+
}
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The deterministic per-recipient idempotency key a campaign send writes to
|
|
3
|
+
* `email_sends.idempotency_key`. This key is ALSO how a send row is
|
|
4
|
+
* attributed back to its campaign (there is no campaign_id FK on
|
|
5
|
+
* email_sends), so the format is owned here — the send-campaign task mints
|
|
6
|
+
* keys with `campaignSendKey` and the admin campaign-stats/sends routes match
|
|
7
|
+
* them with the pattern helpers.
|
|
8
|
+
*
|
|
9
|
+
* Two formats, chosen by the campaign's step count (NOT per call site):
|
|
10
|
+
*
|
|
11
|
+
* - Single-step campaigns (steps.length === 1 or a NULL steps blob) ALWAYS
|
|
12
|
+
* use the legacy `campaign:<id>:<email>` — behavior, stats queries, and
|
|
13
|
+
* any in-flight campaign at deploy time are byte-for-byte unchanged.
|
|
14
|
+
* - Multi-step campaigns use `campaign:<id>:<step>:<email>` for ALL steps
|
|
15
|
+
* including 0. No ambiguity with the legacy format is possible (no
|
|
16
|
+
* multi-step campaign exists before this ships), and per-step stats
|
|
17
|
+
* filter on the step-scoped pattern.
|
|
18
|
+
*
|
|
19
|
+
* The key deliberately excludes any timezone bucket (phase 3): same
|
|
20
|
+
* recipient + same step = same key, always.
|
|
21
|
+
*/
|
|
22
|
+
export function campaignSendKey(
|
|
23
|
+
campaignId: string,
|
|
24
|
+
email: string,
|
|
25
|
+
step?: number,
|
|
26
|
+
): string {
|
|
27
|
+
return step === undefined
|
|
28
|
+
? `campaign:${campaignId}:${email}`
|
|
29
|
+
: `campaign:${campaignId}:${step}:${email}`;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Escape LIKE metacharacters so an id/step can't widen a pattern match. */
|
|
33
|
+
function escapeLike(value: string): string {
|
|
34
|
+
return value.replace(/([\\%_])/g, "\\$1");
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* SQL LIKE pattern matching every send of one campaign — a correct superset
|
|
39
|
+
* of BOTH key formats (legacy and step-scoped), so campaign-level stats need
|
|
40
|
+
* no format awareness. The id is escaped so LIKE metacharacters in it can't
|
|
41
|
+
* widen the match (ids are UUIDs today, but the route accepts arbitrary
|
|
42
|
+
* strings).
|
|
43
|
+
*/
|
|
44
|
+
export function campaignSendKeyPattern(campaignId: string): string {
|
|
45
|
+
return `campaign:${escapeLike(campaignId)}:%`;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* SQL LIKE pattern matching every send of ONE step of a multi-step campaign
|
|
50
|
+
* (`campaign:<id>:<step>:%`). Meaningless against legacy single-step keys —
|
|
51
|
+
* callers only use it on campaigns with a steps blob.
|
|
52
|
+
*/
|
|
53
|
+
export function campaignStepSendKeyPattern(
|
|
54
|
+
campaignId: string,
|
|
55
|
+
step: number,
|
|
56
|
+
): string {
|
|
57
|
+
return `campaign:${escapeLike(campaignId)}:${step}:%`;
|
|
58
|
+
}
|