@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.
- package/package.json +11 -8
- 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 +96 -2
- package/src/journeys/constants.ts +10 -0
- package/src/journeys/define-journey.ts +14 -405
- package/src/journeys/execute-journey-run.ts +641 -0
- package/src/journeys/graph/build-graph.ts +212 -56
- package/src/journeys/journey-boundary.ts +54 -0
- package/src/journeys/journey-context.ts +406 -59
- package/src/journeys/record-once.ts +110 -0
- package/src/lib/blueprint-lock.ts +21 -0
- package/src/lib/blueprints.ts +803 -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/event-names.ts +143 -0
- 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/tracking.ts +1 -5
- 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/authoring-guide.ts +160 -0
- package/src/mcp/blueprint-tools.ts +390 -0
- package/src/middleware/require-admin.ts +13 -0
- package/src/routes/admin/api-keys.ts +72 -0
- package/src/routes/admin/blueprints.ts +795 -0
- package/src/routes/admin/campaigns.ts +179 -3
- package/src/routes/admin/emails.ts +13 -0
- package/src/routes/admin/events.ts +55 -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 +656 -0
- package/src/workflows/send-campaign.ts +574 -180
package/src/lib/feed.ts
CHANGED
|
@@ -1,14 +1,15 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { and, eq } from "drizzle-orm";
|
|
1
|
+
import { type FeedBlock, feedItems } from "@hogsend/db";
|
|
3
2
|
import {
|
|
4
3
|
deriveJourneyKey,
|
|
5
4
|
getJourneyBoundary,
|
|
6
5
|
registerKey,
|
|
7
6
|
} from "../journeys/journey-boundary.js";
|
|
7
|
+
import { IN_APP_LIST_ID } from "../lists/channels.js";
|
|
8
8
|
import { getListRegistry } from "../lists/registry-singleton.js";
|
|
9
9
|
import { resolveOrCreateContact, resolveRecipient } from "./contacts.js";
|
|
10
10
|
import { getDb } from "./db.js";
|
|
11
11
|
import { createLogger } from "./logger.js";
|
|
12
|
+
import { readRecipientPreferences } from "./preferences.js";
|
|
12
13
|
import { getRedis } from "./redis.js";
|
|
13
14
|
|
|
14
15
|
const logger = createLogger(process.env.LOG_LEVEL);
|
|
@@ -16,9 +17,11 @@ const logger = createLogger(process.env.LOG_LEVEL);
|
|
|
16
17
|
/**
|
|
17
18
|
* Reserved list id governing in-app feed suppression (mirrors the built-in
|
|
18
19
|
* `transactional` / `journey` categories). A recipient unsubscribed from
|
|
19
|
-
* `in_app` (or `unsubscribed_all`) gets no feed items.
|
|
20
|
+
* `in_app` (or `unsubscribed_all`) gets no feed items. Canonically defined in
|
|
21
|
+
* `../lists/channels.js` (where the in-app channel is synthesized); re-exported
|
|
22
|
+
* here so the engine's existing export surface stays stable.
|
|
20
23
|
*/
|
|
21
|
-
export
|
|
24
|
+
export { IN_APP_LIST_ID };
|
|
22
25
|
|
|
23
26
|
export interface SendFeedItemOptions {
|
|
24
27
|
recipient: { userId?: string; email?: string; anonymousId?: string };
|
|
@@ -88,55 +91,23 @@ export async function sendFeedItem(
|
|
|
88
91
|
});
|
|
89
92
|
const recipientKey = resolvedKey;
|
|
90
93
|
|
|
91
|
-
// (2)
|
|
92
|
-
//
|
|
93
|
-
// `(user_id, email)`-keyed; an anon-only recipient has no pref row → categories
|
|
94
|
-
// = {} → opt-in default → not suppressed (you cannot suppress what has no
|
|
95
|
-
// preference surface yet). `unsubscribed_all` on an identified recipient DOES
|
|
96
|
-
// suppress, consistent with the email mailer's `checkEmailPreferences`.
|
|
97
|
-
let categories: Record<string, boolean> = {};
|
|
98
|
-
const recip = await resolveRecipient({
|
|
99
|
-
db,
|
|
100
|
-
userId: recipient.userId,
|
|
101
|
-
email: recipient.email,
|
|
102
|
-
});
|
|
103
|
-
if (recip) {
|
|
104
|
-
const extId = recip.externalId ?? recip.contactId;
|
|
105
|
-
const rows = await db
|
|
106
|
-
.select()
|
|
107
|
-
.from(emailPreferences)
|
|
108
|
-
.where(
|
|
109
|
-
and(
|
|
110
|
-
eq(emailPreferences.userId, extId),
|
|
111
|
-
eq(emailPreferences.email, recip.email),
|
|
112
|
-
),
|
|
113
|
-
)
|
|
114
|
-
.limit(1);
|
|
115
|
-
const row = rows[0];
|
|
116
|
-
if (row) {
|
|
117
|
-
if (row.unsubscribedAll) {
|
|
118
|
-
return {
|
|
119
|
-
feedItemId: null,
|
|
120
|
-
recipientKey,
|
|
121
|
-
suppressed: true,
|
|
122
|
-
createdAt: null,
|
|
123
|
-
};
|
|
124
|
-
}
|
|
125
|
-
categories = (row.categories ?? {}) as Record<string, boolean>;
|
|
126
|
-
}
|
|
127
|
-
}
|
|
128
|
-
if (!getListRegistry().isSubscribed(categories, IN_APP_LIST_ID)) {
|
|
129
|
-
return {
|
|
130
|
-
feedItemId: null,
|
|
131
|
-
recipientKey,
|
|
132
|
-
suppressed: true,
|
|
133
|
-
createdAt: null,
|
|
134
|
-
};
|
|
135
|
-
}
|
|
136
|
-
|
|
137
|
-
// (3) Replay-safe idempotency key (mirrors `sendEmail`). The `feed:`-namespaced
|
|
94
|
+
// (2) Replay-safe idempotency key (mirrors `sendEmail`), derived
|
|
95
|
+
// UNCONDITIONALLY — BEFORE any preference decision. The `feed:`-namespaced
|
|
138
96
|
// discriminant realizes the plan's `feedSend:<runAnchor>:<site>:<type>` shape
|
|
139
97
|
// through the SAME branch-stable key engine (one primitive, not a fork).
|
|
98
|
+
//
|
|
99
|
+
// THE LAW: the Hatchet journal is positional, and `boundary.memoize` (step 4)
|
|
100
|
+
// is a durable call, so its issuance must never be conditional on a live
|
|
101
|
+
// preference read. A recipient's `in_app`/`unsubscribed_all` state can flip
|
|
102
|
+
// between an original run and a replay-from-top; the OLD code early-returned on
|
|
103
|
+
// that read HERE, before the key derivation + `registerKey` + `memoize`, so a
|
|
104
|
+
// flip made the replay conditionally skip (or add) the memoize durable call →
|
|
105
|
+
// positional journal shift → the run is killed with a non-determinism error.
|
|
106
|
+
// The fix (mirroring the connector gate in lib/connector-actions.ts): derive +
|
|
107
|
+
// register the key and issue the memoize UNCONDITIONALLY, and fold the whole
|
|
108
|
+
// preference verdict INSIDE the memo closure (step 3) so the skip/allow verdict
|
|
109
|
+
// is RECORDED by the durable memo and replays verbatim — the live-flipped
|
|
110
|
+
// preference is never re-read on a replay.
|
|
140
111
|
const boundary = getJourneyBoundary();
|
|
141
112
|
let key: string | undefined = opts.idempotencyKey;
|
|
142
113
|
if (!key && boundary) {
|
|
@@ -222,12 +193,61 @@ export async function sendFeedItem(
|
|
|
222
193
|
};
|
|
223
194
|
};
|
|
224
195
|
|
|
225
|
-
//
|
|
226
|
-
//
|
|
227
|
-
//
|
|
228
|
-
//
|
|
196
|
+
// (3) `in_app` suppression gate + insert/publish, folded into ONE closure so
|
|
197
|
+
// the whole verdict (skip OR insert) is recorded by the durable memo (step 4)
|
|
198
|
+
// and replays byte-identically. Suppression is governed by the `in_app`
|
|
199
|
+
// channel list regardless of the item's own category.
|
|
200
|
+
//
|
|
201
|
+
// The preference read is the UNIFIED aggregated `readRecipientPreferences`
|
|
202
|
+
// keyed by BOTH the recipient's `external_id ?? contact_id` AND its email —
|
|
203
|
+
// NOT the old single-row `(extId, email)` lookup. This is a deliberate,
|
|
204
|
+
// suppression-conservative behaviour change: an `unsubscribed_all` (or category
|
|
205
|
+
// opt-out) imported before the contact existed and keyed `(email, email)` now
|
|
206
|
+
// suppresses the feed too, exactly as it already suppresses email. An anon-only
|
|
207
|
+
// recipient has no preference surface (`resolveRecipient` → null), so
|
|
208
|
+
// `unsubscribed_all` is not consulted (you cannot suppress what has no pref row
|
|
209
|
+
// yet); the `in_app` channel check still runs, but empty categories → opt-in
|
|
210
|
+
// default → subscribed, so an anon recipient is never suppressed here.
|
|
211
|
+
const doGatedInsertAndPublish = async (): Promise<SendFeedItemResult> => {
|
|
212
|
+
const suppressedResult: SendFeedItemResult = {
|
|
213
|
+
feedItemId: null,
|
|
214
|
+
recipientKey,
|
|
215
|
+
suppressed: true,
|
|
216
|
+
createdAt: null,
|
|
217
|
+
};
|
|
218
|
+
const recip = await resolveRecipient({
|
|
219
|
+
db,
|
|
220
|
+
userId: recipient.userId,
|
|
221
|
+
email: recipient.email,
|
|
222
|
+
});
|
|
223
|
+
// `external_id ?? contact_id` — the SAME identity key the old single-row read
|
|
224
|
+
// used (and that preference writes key on). Undefined for an anon recipient.
|
|
225
|
+
const extId = recip ? (recip.externalId ?? recip.contactId) : undefined;
|
|
226
|
+
const prefs = await readRecipientPreferences(db, {
|
|
227
|
+
email: recip?.email,
|
|
228
|
+
userId: extId,
|
|
229
|
+
});
|
|
230
|
+
// `unsubscribed_all` on an IDENTIFIED recipient suppresses (consistent with
|
|
231
|
+
// the email mailer's `checkEmailPreferences`); guarded on `recip` so an
|
|
232
|
+
// anon recipient with no preference surface is never blocked.
|
|
233
|
+
if (recip && prefs.unsubscribedAll) {
|
|
234
|
+
return suppressedResult;
|
|
235
|
+
}
|
|
236
|
+
if (!getListRegistry().isSubscribed(prefs.categories, IN_APP_LIST_ID)) {
|
|
237
|
+
return suppressedResult;
|
|
238
|
+
}
|
|
239
|
+
return doInsertAndPublish();
|
|
240
|
+
};
|
|
241
|
+
|
|
242
|
+
// (4) Layer 1 (eviction-gated, FREE) fast path. When inside a journey on an
|
|
243
|
+
// eviction-capable engine, a replay returns the recorded result (a skip verdict
|
|
244
|
+
// OR the insert result) WITHOUT re-reading preferences or re-hitting the DB;
|
|
245
|
+
// Layer 2 (`onConflictDoNothing`) is the version-independent backstop. Outside
|
|
246
|
+
// a journey, run directly. The key derivation, `registerKey`, and this
|
|
247
|
+
// `memoize` call all stay UNCONDITIONAL (THE LAW) — the preference verdict
|
|
248
|
+
// lives inside the closure, never gating the durable call itself.
|
|
229
249
|
if (boundary && key) {
|
|
230
|
-
return boundary.memoize([key],
|
|
250
|
+
return boundary.memoize([key], doGatedInsertAndPublish);
|
|
231
251
|
}
|
|
232
|
-
return
|
|
252
|
+
return doGatedInsertAndPublish();
|
|
233
253
|
}
|
package/src/lib/frequency-cap.ts
CHANGED
|
@@ -6,6 +6,42 @@ import type { FrequencyCapConfig } from "./email-service-types.js";
|
|
|
6
6
|
|
|
7
7
|
const DEFAULT_EXEMPT = ["transactional"];
|
|
8
8
|
|
|
9
|
+
/**
|
|
10
|
+
* The windowed non-failed send count for a recipient — the COUNT behind
|
|
11
|
+
* {@link isFrequencyCapped}, shared with `ctx.throttle` (and later the suppress
|
|
12
|
+
* guard). Served by the `email_sends_freq_cap_idx (to_email, created_at,
|
|
13
|
+
* category)` index. Never-dispatched / failed rows (`status = 'failed'`) are
|
|
14
|
+
* excluded; a `category` narrows the count to that category.
|
|
15
|
+
*
|
|
16
|
+
* NOTE: NO exemption semantics live here — unlike {@link isFrequencyCapped}
|
|
17
|
+
* (which short-circuits an exempt "transactional" category), a `category` passed
|
|
18
|
+
* here genuinely counts that category's sends.
|
|
19
|
+
*/
|
|
20
|
+
export async function countRecentSends(opts: {
|
|
21
|
+
db: Database;
|
|
22
|
+
to: string;
|
|
23
|
+
since: Date;
|
|
24
|
+
category?: string;
|
|
25
|
+
}): Promise<number> {
|
|
26
|
+
const { db, to, since, category } = opts;
|
|
27
|
+
|
|
28
|
+
const conditions = [
|
|
29
|
+
eq(emailSends.toEmail, to),
|
|
30
|
+
gte(emailSends.createdAt, since),
|
|
31
|
+
ne(emailSends.status, "failed"),
|
|
32
|
+
];
|
|
33
|
+
if (category !== undefined) {
|
|
34
|
+
conditions.push(eq(emailSends.category, category));
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const [row] = await db
|
|
38
|
+
.select({ n: count() })
|
|
39
|
+
.from(emailSends)
|
|
40
|
+
.where(and(...conditions));
|
|
41
|
+
|
|
42
|
+
return row?.n ?? 0;
|
|
43
|
+
}
|
|
44
|
+
|
|
9
45
|
/**
|
|
10
46
|
* True if this recipient has hit the configured send cap within the window.
|
|
11
47
|
*
|
|
@@ -35,20 +71,14 @@ export async function isFrequencyCapped(opts: {
|
|
|
35
71
|
|
|
36
72
|
const since = new Date(Date.now() - durationToMs(rule.window));
|
|
37
73
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
}
|
|
47
|
-
|
|
48
|
-
const [row] = await db
|
|
49
|
-
.select({ n: count() })
|
|
50
|
-
.from(emailSends)
|
|
51
|
-
.where(and(...conditions));
|
|
74
|
+
// The byCategory branch counts only sends in that category; the global rule
|
|
75
|
+
// counts ALL of the recipient's non-failed sends in the window.
|
|
76
|
+
const n = await countRecentSends({
|
|
77
|
+
db,
|
|
78
|
+
to,
|
|
79
|
+
since,
|
|
80
|
+
...(override && category ? { category } : {}),
|
|
81
|
+
});
|
|
52
82
|
|
|
53
|
-
return
|
|
83
|
+
return n >= rule.count;
|
|
54
84
|
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { type DurationObject, durationToMs } from "@hogsend/core";
|
|
2
|
+
|
|
3
|
+
/** Normalize any duration to a SINGLE-UNIT whole-seconds Go string ("120s")
|
|
4
|
+
* before it reaches a Hatchet durable sleep (`sleepFor` or a `SleepCondition`).
|
|
5
|
+
* The SDK renders ms numbers as multi-unit strings ("1m59s"), which some
|
|
6
|
+
* hatchet-lite versions silently fail to honor as sleep conditions (the wait
|
|
7
|
+
* resolves instantly with no match) — pinned empirically 2026-07-10. Whole
|
|
8
|
+
* seconds match the SDK's own `sleepUntil` normalization. EVERY engine call
|
|
9
|
+
* site that hands Hatchet a sleep duration must route through this — a raw ms
|
|
10
|
+
* number reopens the instant-wake bug.
|
|
11
|
+
*
|
|
12
|
+
* Lives beside (not inside) `lib/hatchet.ts` because tests `vi.mock` that
|
|
13
|
+
* module to stub the client singleton; this helper must survive the mock. */
|
|
14
|
+
export const toSleepDuration = (
|
|
15
|
+
durationOrMs: DurationObject | number,
|
|
16
|
+
): `${number}s` => {
|
|
17
|
+
const ms =
|
|
18
|
+
typeof durationOrMs === "number"
|
|
19
|
+
? durationOrMs
|
|
20
|
+
: durationToMs(durationOrMs);
|
|
21
|
+
return `${Math.max(1, Math.ceil(ms / 1000))}s`;
|
|
22
|
+
};
|
package/src/lib/html.ts
CHANGED
|
@@ -12,6 +12,7 @@ export function htmlPage(opts: { title: string; body: string }): string {
|
|
|
12
12
|
p { color: #555; line-height: 1.6; }
|
|
13
13
|
a { color: #2563eb; text-decoration: none; }
|
|
14
14
|
a:hover { text-decoration: underline; }
|
|
15
|
+
.pref-section { font-size: 0.75rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.06em; color: #6b7280; margin: 28px 0 4px; }
|
|
15
16
|
.pref-row { display: flex; justify-content: space-between; align-items: center; padding: 12px 0; border-bottom: 1px solid #e5e7eb; }
|
|
16
17
|
.pref-label { font-weight: 500; }
|
|
17
18
|
.pref-status { font-size: 0.875rem; }
|
package/src/lib/ingestion.ts
CHANGED
|
@@ -2,12 +2,20 @@ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
|
|
|
2
2
|
import type {
|
|
3
3
|
AnalyticsEventMirrorConfig,
|
|
4
4
|
AnalyticsProvider,
|
|
5
|
+
PropertyCondition,
|
|
5
6
|
} from "@hogsend/core";
|
|
6
7
|
import { evaluatePropertyConditions } from "@hogsend/core";
|
|
7
8
|
import type { JourneyRegistry } from "@hogsend/core/registry";
|
|
8
|
-
import
|
|
9
|
+
import type { JourneyMeta } from "@hogsend/core/types";
|
|
10
|
+
import {
|
|
11
|
+
type Database,
|
|
12
|
+
journeyBlueprints,
|
|
13
|
+
journeyStates,
|
|
14
|
+
userEvents,
|
|
15
|
+
} from "@hogsend/db";
|
|
9
16
|
import { and, eq, inArray, isNull } from "drizzle-orm";
|
|
10
17
|
import { checkBucketMembership } from "../buckets/check-membership.js";
|
|
18
|
+
import { BLUEPRINT_RUN_EVENT } from "../journeys/constants.js";
|
|
11
19
|
import { logTransition } from "../journeys/journey-log.js";
|
|
12
20
|
import {
|
|
13
21
|
logResidualTwins,
|
|
@@ -157,6 +165,80 @@ function shouldMirrorEvent(
|
|
|
157
165
|
return true;
|
|
158
166
|
}
|
|
159
167
|
|
|
168
|
+
/**
|
|
169
|
+
* Blueprint dispatch (spec §5) — the DB-lookup counterpart of the static
|
|
170
|
+
* `onEvents` registration code journeys get at boot. Code journeys can't gain
|
|
171
|
+
* a trigger without a worker redeploy; a blueprint row created at 3pm must
|
|
172
|
+
* fire at 3:01. So on every ingested event this queries the enabled
|
|
173
|
+
* `journey_blueprints` whose `triggerEvent` matches (served by the
|
|
174
|
+
* `(trigger_event, status)` index), applies `triggerWhere` with the SAME
|
|
175
|
+
* `evaluatePropertyConditions` the interpreter's enrollment guard re-checks
|
|
176
|
+
* with (dispatch and guard must agree, and both see the serializable-scalar
|
|
177
|
+
* payload), and pushes one `blueprint:run` per match to the single
|
|
178
|
+
* statically-registered `journey-blueprint-interpreter` task.
|
|
179
|
+
*
|
|
180
|
+
* Returns the number of dispatched enrollment attempts.
|
|
181
|
+
*/
|
|
182
|
+
export async function checkBlueprintTriggers(opts: {
|
|
183
|
+
db: Database;
|
|
184
|
+
hatchet: HatchetClient;
|
|
185
|
+
logger: Logger;
|
|
186
|
+
event: {
|
|
187
|
+
name: string;
|
|
188
|
+
userId: string;
|
|
189
|
+
userEmail: string;
|
|
190
|
+
/** The serializable-scalar subset that will reach the interpreter. */
|
|
191
|
+
properties: Record<string, string | number | boolean | null>;
|
|
192
|
+
};
|
|
193
|
+
}): Promise<number> {
|
|
194
|
+
const { db, hatchet, logger, event } = opts;
|
|
195
|
+
|
|
196
|
+
const candidates = await db
|
|
197
|
+
.select({
|
|
198
|
+
id: journeyBlueprints.id,
|
|
199
|
+
version: journeyBlueprints.version,
|
|
200
|
+
triggerWhere: journeyBlueprints.triggerWhere,
|
|
201
|
+
})
|
|
202
|
+
.from(journeyBlueprints)
|
|
203
|
+
.where(
|
|
204
|
+
and(
|
|
205
|
+
eq(journeyBlueprints.triggerEvent, event.name),
|
|
206
|
+
eq(journeyBlueprints.status, "enabled"),
|
|
207
|
+
),
|
|
208
|
+
);
|
|
209
|
+
|
|
210
|
+
let dispatched = 0;
|
|
211
|
+
for (const bp of candidates) {
|
|
212
|
+
const where = (bp.triggerWhere ?? []) as unknown as PropertyCondition[];
|
|
213
|
+
if (
|
|
214
|
+
where.length > 0 &&
|
|
215
|
+
!evaluatePropertyConditions({
|
|
216
|
+
conditions: where,
|
|
217
|
+
properties: event.properties,
|
|
218
|
+
})
|
|
219
|
+
) {
|
|
220
|
+
continue;
|
|
221
|
+
}
|
|
222
|
+
await hatchet.events.push(BLUEPRINT_RUN_EVENT, {
|
|
223
|
+
blueprintId: bp.id,
|
|
224
|
+
blueprintVersion: bp.version,
|
|
225
|
+
userId: event.userId,
|
|
226
|
+
userEmail: event.userEmail,
|
|
227
|
+
triggerProperties: event.properties,
|
|
228
|
+
});
|
|
229
|
+
dispatched += 1;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
if (dispatched > 0) {
|
|
233
|
+
logger.info("Blueprint runs dispatched", {
|
|
234
|
+
event: event.name,
|
|
235
|
+
userId: event.userId,
|
|
236
|
+
dispatched,
|
|
237
|
+
});
|
|
238
|
+
}
|
|
239
|
+
return dispatched;
|
|
240
|
+
}
|
|
241
|
+
|
|
160
242
|
export async function ingestEvent(opts: {
|
|
161
243
|
db: Database;
|
|
162
244
|
registry: JourneyRegistry;
|
|
@@ -402,6 +484,34 @@ export async function ingestEvent(opts: {
|
|
|
402
484
|
}
|
|
403
485
|
const exits = exitsResult.value;
|
|
404
486
|
|
|
487
|
+
// (5b) Blueprint dispatch (spec §5) — the DB-driven twin of the Hatchet
|
|
488
|
+
// push in (4): one `blueprint:run` per enabled matching blueprint. Runs
|
|
489
|
+
// AFTER the main push settled, so a dispatched blueprint never observes an
|
|
490
|
+
// event code journeys were not notified of. Best-effort by design: the
|
|
491
|
+
// event row + code-journey push are already committed, so throwing here
|
|
492
|
+
// could not be retried into a redelivery (the idempotency claim survives) —
|
|
493
|
+
// it would only fail the caller for work that half-happened. Mirrors the
|
|
494
|
+
// bucket-membership stance below.
|
|
495
|
+
try {
|
|
496
|
+
await checkBlueprintTriggers({
|
|
497
|
+
db,
|
|
498
|
+
hatchet,
|
|
499
|
+
logger,
|
|
500
|
+
event: {
|
|
501
|
+
name: event.event,
|
|
502
|
+
userId: resolvedKey,
|
|
503
|
+
userEmail: event.userEmail ?? "",
|
|
504
|
+
properties: serializableProperties,
|
|
505
|
+
},
|
|
506
|
+
});
|
|
507
|
+
} catch (err) {
|
|
508
|
+
logger.warn("Blueprint trigger dispatch failed", {
|
|
509
|
+
event: event.event,
|
|
510
|
+
userId: resolvedKey,
|
|
511
|
+
error: err instanceof Error ? err.message : String(err),
|
|
512
|
+
});
|
|
513
|
+
}
|
|
514
|
+
|
|
405
515
|
// (6) Real-time bucket membership re-evaluation (Section 6.1). NOT part of the
|
|
406
516
|
// Promise.all above: its property eval reads contact state ⊕ this-ingest
|
|
407
517
|
// contactProperties patch, and its bucket:entered/left emissions recurse back
|
|
@@ -458,14 +568,45 @@ async function checkExits(
|
|
|
458
568
|
),
|
|
459
569
|
});
|
|
460
570
|
|
|
571
|
+
// Blueprint enrollments share journeyStates but are NOT in the code-journey
|
|
572
|
+
// registry — their exitOn lives on the journey_blueprints row (spec §4).
|
|
573
|
+
// Resolve exitOn for any active state whose journeyId the registry doesn't
|
|
574
|
+
// know, in one batched read. Deliberately status-agnostic: disabling a
|
|
575
|
+
// blueprint stops NEW enrollments, but an in-flight run keeps honoring its
|
|
576
|
+
// exit rules (spec §10/§12).
|
|
577
|
+
const unregisteredIds = [
|
|
578
|
+
...new Set(
|
|
579
|
+
activeStates
|
|
580
|
+
.map((state) => state.journeyId)
|
|
581
|
+
.filter((journeyId) => !registry.get(journeyId)),
|
|
582
|
+
),
|
|
583
|
+
];
|
|
584
|
+
const blueprintExitOn = new Map<string, NonNullable<JourneyMeta["exitOn"]>>();
|
|
585
|
+
if (unregisteredIds.length > 0) {
|
|
586
|
+
const rows = await db
|
|
587
|
+
.select({ id: journeyBlueprints.id, exitOn: journeyBlueprints.exitOn })
|
|
588
|
+
.from(journeyBlueprints)
|
|
589
|
+
.where(inArray(journeyBlueprints.id, unregisteredIds));
|
|
590
|
+
for (const row of rows) {
|
|
591
|
+
if (row.exitOn?.length) {
|
|
592
|
+
blueprintExitOn.set(
|
|
593
|
+
row.id,
|
|
594
|
+
row.exitOn as NonNullable<JourneyMeta["exitOn"]>,
|
|
595
|
+
);
|
|
596
|
+
}
|
|
597
|
+
}
|
|
598
|
+
}
|
|
599
|
+
|
|
461
600
|
const statesToExit: string[] = [];
|
|
462
601
|
const runIdsToCancel: string[] = [];
|
|
463
602
|
|
|
464
603
|
for (const state of activeStates) {
|
|
465
|
-
const
|
|
466
|
-
|
|
604
|
+
const exitOn =
|
|
605
|
+
registry.get(state.journeyId)?.exitOn ??
|
|
606
|
+
blueprintExitOn.get(state.journeyId);
|
|
607
|
+
if (!exitOn) continue;
|
|
467
608
|
|
|
468
|
-
const shouldExit =
|
|
609
|
+
const shouldExit = exitOn.some((exitCondition) => {
|
|
469
610
|
if (exitCondition.event !== event.eventName) return false;
|
|
470
611
|
if (!exitCondition.where?.length) return true;
|
|
471
612
|
return evaluatePropertyConditions({
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import type { Database } from "@hogsend/db";
|
|
2
|
+
import { emailSends, journeyStates } from "@hogsend/db";
|
|
3
|
+
import { and, eq, gte, ne } from "drizzle-orm";
|
|
4
|
+
import type { JourneyBoundary } from "../journeys/journey-boundary.js";
|
|
5
|
+
import { recordOnce } from "../journeys/record-once.js";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* True if a non-failed `email_sends` row exists for THIS journey — across ALL
|
|
9
|
+
* of its enrollments — to THIS recipient within the suppress window. The
|
|
10
|
+
* INNER JOIN to `journey_states` on `journey_state_id`, filtered by
|
|
11
|
+
* `journey_id`, is what crosses enrollments: `meta.suppress` is a per-JOURNEY
|
|
12
|
+
* min-gap, not per-enrollment, so a re-enrollment inside the window is still
|
|
13
|
+
* gapped. Failed rows (`status = 'failed'`, never dispatched) are excluded,
|
|
14
|
+
* mirroring {@link countRecentSends}. EXISTS semantics only — `limit(1)`, no
|
|
15
|
+
* count needed.
|
|
16
|
+
*/
|
|
17
|
+
export async function hasRecentJourneySend(opts: {
|
|
18
|
+
db: Database;
|
|
19
|
+
journeyId: string;
|
|
20
|
+
to: string;
|
|
21
|
+
since: Date;
|
|
22
|
+
}): Promise<boolean> {
|
|
23
|
+
const rows = await opts.db
|
|
24
|
+
.select({ id: emailSends.id })
|
|
25
|
+
.from(emailSends)
|
|
26
|
+
.innerJoin(journeyStates, eq(emailSends.journeyStateId, journeyStates.id))
|
|
27
|
+
.where(
|
|
28
|
+
and(
|
|
29
|
+
eq(journeyStates.journeyId, opts.journeyId),
|
|
30
|
+
eq(emailSends.toEmail, opts.to),
|
|
31
|
+
gte(emailSends.createdAt, opts.since),
|
|
32
|
+
ne(emailSends.status, "failed"),
|
|
33
|
+
),
|
|
34
|
+
)
|
|
35
|
+
.limit(1);
|
|
36
|
+
return rows.length > 0;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* The RECORDED-once journey-suppress verdict for a boundary send. Returns
|
|
41
|
+
* `{ suppressed }` — `true` means the tracked mailer must skip the send
|
|
42
|
+
* (`journey_suppressed`, no provider call, no `email_sends` row).
|
|
43
|
+
*
|
|
44
|
+
* REPLAY STABILITY (non-negotiable): the live EXISTS check diverges on replay —
|
|
45
|
+
* the run's OWN send lands in the window, so an originally-ALLOWED send would
|
|
46
|
+
* re-check as suppressed (a late duplicate), and an originally-SUPPRESSED send
|
|
47
|
+
* could re-check as allowed if the blocking row was purged. So the verdict is
|
|
48
|
+
* frozen set-once under `context.__throttle__` keyed by the send's resolved
|
|
49
|
+
* idempotency key (already per-run-unique via `registerKey`, so it needs no
|
|
50
|
+
* extra registration) and replayed verbatim thereafter — durable on ANY engine.
|
|
51
|
+
*
|
|
52
|
+
* The guard is INERT (returns `{ suppressed: false }` without touching the DB)
|
|
53
|
+
* when there is no boundary, no `journeyId`, a zero `suppressMs`, or no resolved
|
|
54
|
+
* idempotency key — i.e. every non-journey / transactional send is unaffected.
|
|
55
|
+
*/
|
|
56
|
+
export async function checkJourneySuppress(opts: {
|
|
57
|
+
db: Database;
|
|
58
|
+
boundary: JourneyBoundary | undefined;
|
|
59
|
+
to: string;
|
|
60
|
+
idempotencyKey: string | undefined;
|
|
61
|
+
/** Injectable clock for tests; defaults to the live wall clock. */
|
|
62
|
+
now?: number;
|
|
63
|
+
}): Promise<{ suppressed: boolean }> {
|
|
64
|
+
const { db, boundary, to, idempotencyKey } = opts;
|
|
65
|
+
if (
|
|
66
|
+
!boundary?.journeyId ||
|
|
67
|
+
!boundary.suppressMs ||
|
|
68
|
+
boundary.suppressMs <= 0 ||
|
|
69
|
+
!idempotencyKey
|
|
70
|
+
) {
|
|
71
|
+
return { suppressed: false };
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
const { journeyId, suppressMs, stateId } = boundary;
|
|
75
|
+
return recordOnce<{ suppressed: boolean }>({
|
|
76
|
+
db,
|
|
77
|
+
stateId,
|
|
78
|
+
namespace: "__throttle__",
|
|
79
|
+
key: `suppress:${idempotencyKey}`,
|
|
80
|
+
compute: async () => {
|
|
81
|
+
const since = new Date((opts.now ?? Date.now()) - suppressMs);
|
|
82
|
+
return {
|
|
83
|
+
suppressed: await hasRecentJourneySend({ db, journeyId, to, since }),
|
|
84
|
+
};
|
|
85
|
+
},
|
|
86
|
+
});
|
|
87
|
+
}
|