@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
|
@@ -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
|
+
}
|
|
@@ -1,15 +1,23 @@
|
|
|
1
1
|
import { connectorDeliveries, contacts, type Database } from "@hogsend/db";
|
|
2
|
-
import { and, eq, isNull, or } from "drizzle-orm";
|
|
2
|
+
import { and, eq, isNull, or, sql } from "drizzle-orm";
|
|
3
3
|
import { getConnectorActionRegistry } from "../connectors/action-registry-singleton.js";
|
|
4
|
-
import type {
|
|
4
|
+
import type {
|
|
5
|
+
ConnectorActionSkipped,
|
|
6
|
+
DefinedConnectorAction,
|
|
7
|
+
ResolvedActionContact,
|
|
8
|
+
} from "../connectors/define-action.js";
|
|
5
9
|
import { env } from "../env.js";
|
|
6
10
|
import {
|
|
7
11
|
deriveJourneyKey,
|
|
8
12
|
getJourneyBoundary,
|
|
9
13
|
registerKey,
|
|
10
14
|
} from "../journeys/journey-boundary.js";
|
|
15
|
+
import { getListRegistry } from "../lists/registry-singleton.js";
|
|
11
16
|
import { getDb } from "./db.js";
|
|
12
17
|
import { createLogger } from "./logger.js";
|
|
18
|
+
import { readRecipientPreferences } from "./preferences.js";
|
|
19
|
+
|
|
20
|
+
const logger = createLogger(env.LOG_LEVEL);
|
|
13
21
|
|
|
14
22
|
/**
|
|
15
23
|
* Matches the canonical UUID form of `contacts.id` (8-4-4-4-12 hex). Gates the
|
|
@@ -20,6 +28,13 @@ import { createLogger } from "./logger.js";
|
|
|
20
28
|
const CONTACT_ID_UUID =
|
|
21
29
|
/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
22
30
|
|
|
31
|
+
/**
|
|
32
|
+
* Matches a NAMESPACED platform ref (`telegram:<chatId>`, `discord:<id>`, …):
|
|
33
|
+
* a leading `<namespace>:` followed by a non-empty value. Captures the namespace
|
|
34
|
+
* (group 1) and the value (group 2).
|
|
35
|
+
*/
|
|
36
|
+
const NAMESPACED_REF = /^([a-z][a-z0-9_-]*):(.+)$/i;
|
|
37
|
+
|
|
23
38
|
/**
|
|
24
39
|
* Resolve a contact for an outbound action by its canonical key in ANY form:
|
|
25
40
|
* email, external id, a platform id (a Discord snowflake / anonymous id), or —
|
|
@@ -30,12 +45,35 @@ const CONTACT_ID_UUID =
|
|
|
30
45
|
* shape-gated: `contacts.id` is a uuid column and an unguarded `eq(id, ref)`
|
|
31
46
|
* against an email/snowflake text ref throws an invalid-uuid cast. First live
|
|
32
47
|
* match wins.
|
|
48
|
+
*
|
|
49
|
+
* NAMESPACED refs (`telegram:<chatId>`) ADDITIONALLY match the platform metadata
|
|
50
|
+
* under `properties.<namespace>` (the `chat_id`/`id` fields). This is load-bearing
|
|
51
|
+
* for the PRIMARY "reach an existing app user on a chat platform" case: when a
|
|
52
|
+
* platform links onto an ALREADY-identified contact, the engine keeps the row's
|
|
53
|
+
* `external_id = <app id>` and stores the chat id ONLY under
|
|
54
|
+
* `properties.<namespace>` (the DEEP_MERGE_KEYS convention in lib/contacts.ts) —
|
|
55
|
+
* the `telegram:<id>` key is NEVER promoted to `external_id` nor aliased. Without
|
|
56
|
+
* these legs `resolveContact("telegram:<chatId>")` would miss that population and
|
|
57
|
+
* a preference gate would wrongly ALLOW a send to an opted-out user. Both the
|
|
58
|
+
* namespace key and the value are SQL-parameterized (never string-interpolated).
|
|
59
|
+
* PERF: these two legs are un-indexed jsonb reads — acceptable at DM volume; a
|
|
60
|
+
* partial index on `properties -> '<ns>' ->> 'chat_id'` is the follow-up if it
|
|
61
|
+
* ever gets hot.
|
|
33
62
|
*/
|
|
34
63
|
async function resolveContact(
|
|
35
64
|
db: Database,
|
|
36
65
|
ref: string,
|
|
37
66
|
): Promise<ResolvedActionContact | null> {
|
|
38
67
|
if (!ref) return null;
|
|
68
|
+
// A namespaced ref (telegram:<chatId>) additionally matches the platform
|
|
69
|
+
// metadata a link-onto-identified contact stores only in properties.<ns>.
|
|
70
|
+
const nsMatch = NAMESPACED_REF.exec(ref);
|
|
71
|
+
const namespacedLegs = nsMatch
|
|
72
|
+
? [
|
|
73
|
+
sql`${contacts.properties} -> ${nsMatch[1]}::text ->> 'chat_id' = ${nsMatch[2]}`,
|
|
74
|
+
sql`${contacts.properties} -> ${nsMatch[1]}::text ->> 'id' = ${nsMatch[2]}`,
|
|
75
|
+
]
|
|
76
|
+
: [];
|
|
39
77
|
const rows = await db
|
|
40
78
|
.select({
|
|
41
79
|
id: contacts.id,
|
|
@@ -54,6 +92,7 @@ async function resolveContact(
|
|
|
54
92
|
eq(contacts.discordId, ref),
|
|
55
93
|
eq(contacts.anonymousId, ref),
|
|
56
94
|
...(CONTACT_ID_UUID.test(ref) ? [eq(contacts.id, ref)] : []),
|
|
95
|
+
...namespacedLegs,
|
|
57
96
|
),
|
|
58
97
|
),
|
|
59
98
|
)
|
|
@@ -69,6 +108,92 @@ async function resolveContact(
|
|
|
69
108
|
};
|
|
70
109
|
}
|
|
71
110
|
|
|
111
|
+
/**
|
|
112
|
+
* Preference gate for a member-directed outbound action. Returns a
|
|
113
|
+
* {@link ConnectorActionSkipped} verdict when the resolved recipient has opted
|
|
114
|
+
* out, or `null` when the send is allowed.
|
|
115
|
+
*
|
|
116
|
+
* Gating rules:
|
|
117
|
+
* - An action WITHOUT a member audience (`audience?.kind !== "member"`) is
|
|
118
|
+
* ops/channel-directed (grantRole, broadcast, mentions, channel messages) and
|
|
119
|
+
* is NEVER gated — returns null immediately.
|
|
120
|
+
* - The audience extractor is run inside a try/catch: a THROWING extractor
|
|
121
|
+
* FAILS OPEN (`logger.warn` + null) — a bad extractor must never brick a
|
|
122
|
+
* journey that works today.
|
|
123
|
+
* - Candidate refs are tried in order; the FIRST that resolves a live contact
|
|
124
|
+
* wins. A candidate that resolves NO contact (a raw snowflake, a group-chat
|
|
125
|
+
* id, an unlinked ref) means there is NO preference surface to consult — the
|
|
126
|
+
* send is ALLOWED (null). Only once a contact is resolved do preferences gate.
|
|
127
|
+
* - On a resolved contact we read the aggregated {@link readRecipientPreferences}
|
|
128
|
+
* keyed by its email + `externalId ?? id` (the SAME key form preference writes
|
|
129
|
+
* use), then: `unsubscribedAll` → skip `unsubscribed_all`; else channel
|
|
130
|
+
* opt-out (`!getListRegistry().isSubscribed(categories, connectorId)`) → skip
|
|
131
|
+
* `channel_unsubscribed`; else null.
|
|
132
|
+
*
|
|
133
|
+
* Deliberately does NOT consume `prefs.suppressed` — that is an email-transport
|
|
134
|
+
* hard-bounce/complaint signal, irrelevant to a chat channel.
|
|
135
|
+
*/
|
|
136
|
+
async function checkActionAudience(
|
|
137
|
+
db: Database,
|
|
138
|
+
resolveCachedContact: (ref: string) => Promise<ResolvedActionContact | null>,
|
|
139
|
+
action: DefinedConnectorAction,
|
|
140
|
+
connectorId: string,
|
|
141
|
+
actionName: string,
|
|
142
|
+
args: unknown,
|
|
143
|
+
): Promise<ConnectorActionSkipped | null> {
|
|
144
|
+
// Ops/channel-directed actions carry no member audience — never gated.
|
|
145
|
+
if (action.audience?.kind !== "member") return null;
|
|
146
|
+
|
|
147
|
+
// Extract candidate recipient refs. A throwing extractor fails OPEN so a
|
|
148
|
+
// gating bug can never regress a send that works today.
|
|
149
|
+
let candidates: string[];
|
|
150
|
+
try {
|
|
151
|
+
const raw = action.audience.ref(args);
|
|
152
|
+
candidates = (Array.isArray(raw) ? raw : [raw]).filter(
|
|
153
|
+
(r): r is string => typeof r === "string" && r.length > 0,
|
|
154
|
+
);
|
|
155
|
+
} catch (error) {
|
|
156
|
+
logger.warn("connector action audience extractor threw; sending anyway", {
|
|
157
|
+
connectorId,
|
|
158
|
+
action: actionName,
|
|
159
|
+
error: error instanceof Error ? error.message : String(error),
|
|
160
|
+
});
|
|
161
|
+
return null;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
for (const ref of candidates) {
|
|
165
|
+
const contact = await resolveCachedContact(ref);
|
|
166
|
+
// No contact for this candidate → no preference surface → try the next; a
|
|
167
|
+
// fully-unresolved recipient (raw id / group chat) falls through to allow.
|
|
168
|
+
if (!contact) continue;
|
|
169
|
+
|
|
170
|
+
const prefs = await readRecipientPreferences(db, {
|
|
171
|
+
email: contact.email,
|
|
172
|
+
userId: contact.externalId ?? contact.id,
|
|
173
|
+
});
|
|
174
|
+
if (prefs.unsubscribedAll) {
|
|
175
|
+
return {
|
|
176
|
+
skipped: true,
|
|
177
|
+
reason: "unsubscribed_all",
|
|
178
|
+
connectorId,
|
|
179
|
+
action: actionName,
|
|
180
|
+
};
|
|
181
|
+
}
|
|
182
|
+
if (!getListRegistry().isSubscribed(prefs.categories, connectorId)) {
|
|
183
|
+
return {
|
|
184
|
+
skipped: true,
|
|
185
|
+
reason: "channel_unsubscribed",
|
|
186
|
+
connectorId,
|
|
187
|
+
action: actionName,
|
|
188
|
+
};
|
|
189
|
+
}
|
|
190
|
+
return null;
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
// No candidate resolved a contact → allowed (no preference surface).
|
|
194
|
+
return null;
|
|
195
|
+
}
|
|
196
|
+
|
|
72
197
|
export interface SendConnectorActionArgs {
|
|
73
198
|
/** The connector the action belongs to (e.g. "discord"). */
|
|
74
199
|
connectorId: string;
|
|
@@ -100,6 +225,17 @@ export interface SendConnectorActionArgs {
|
|
|
100
225
|
* Independent of any inbound gateway runtime: a deployment with the gateway off
|
|
101
226
|
* (or "Worker Offline") can still send — Discord actions are bot-REST needing
|
|
102
227
|
* only the bot token.
|
|
228
|
+
*
|
|
229
|
+
* MEMBER-DIRECTED actions (those declaring `audience: { kind: "member" }`) are
|
|
230
|
+
* automatically gated on the recipient's channel preferences BEFORE the plugin
|
|
231
|
+
* runs: a resolved contact who unsubscribed globally or opted out of the
|
|
232
|
+
* connector's channel list yields a {@link ConnectorActionSkipped} verdict
|
|
233
|
+
* INSTEAD of a send, and no `connector_deliveries` row is claimed. The gate runs
|
|
234
|
+
* INSIDE the durable memo closure, so its verdict is recorded and replays
|
|
235
|
+
* verbatim (THE LAW: the key derivation, `registerKey`, and the `memoize` call
|
|
236
|
+
* itself stay unconditional). Skips are observable via logs + the returned
|
|
237
|
+
* verdict only — an audit ledger is a future additive migration. Ops/channel-
|
|
238
|
+
* directed actions (no audience) are never gated.
|
|
103
239
|
*/
|
|
104
240
|
export async function sendConnectorAction(
|
|
105
241
|
input: SendConnectorActionArgs,
|
|
@@ -115,17 +251,57 @@ export async function sendConnectorAction(
|
|
|
115
251
|
);
|
|
116
252
|
}
|
|
117
253
|
const db = getDb();
|
|
254
|
+
|
|
255
|
+
// Per-call promise-memoized contact resolver so the preference gate and the
|
|
256
|
+
// plugin share ONE contacts round-trip per ref: `checkActionAudience` and the
|
|
257
|
+
// plugin's `ctx.resolveContact` would otherwise resolve the SAME member ref
|
|
258
|
+
// twice. Scoped to THIS call (never module-level) — a durable replay rebuilds
|
|
259
|
+
// it fresh; it adds/removes no durable calls and lives inside the memoized
|
|
260
|
+
// closure's execution, never moving the gate outside it (THE LAW).
|
|
261
|
+
const contactCache = new Map<string, Promise<ResolvedActionContact | null>>();
|
|
262
|
+
const resolveCached = (ref: string) => {
|
|
263
|
+
let p = contactCache.get(ref);
|
|
264
|
+
if (!p) {
|
|
265
|
+
p = resolveContact(db, ref);
|
|
266
|
+
contactCache.set(ref, p);
|
|
267
|
+
}
|
|
268
|
+
return p;
|
|
269
|
+
};
|
|
270
|
+
|
|
118
271
|
const doRun = () =>
|
|
119
272
|
action.run(input.args, {
|
|
120
273
|
db,
|
|
121
|
-
logger
|
|
122
|
-
resolveContact:
|
|
274
|
+
logger,
|
|
275
|
+
resolveContact: resolveCached,
|
|
123
276
|
});
|
|
124
277
|
|
|
278
|
+
// Preference gate shared by BOTH the no-boundary and memoized paths: consult
|
|
279
|
+
// the recipient's channel preferences and either short-circuit with a skip
|
|
280
|
+
// verdict (memo-recorded so it replays verbatim) or invoke `run`.
|
|
281
|
+
const gate = async (run: () => Promise<unknown>): Promise<unknown> => {
|
|
282
|
+
const skip = await checkActionAudience(
|
|
283
|
+
db,
|
|
284
|
+
resolveCached,
|
|
285
|
+
action,
|
|
286
|
+
input.connectorId,
|
|
287
|
+
input.action,
|
|
288
|
+
input.args,
|
|
289
|
+
);
|
|
290
|
+
if (skip) {
|
|
291
|
+
logger.info("connector action skipped: recipient preferences", {
|
|
292
|
+
connectorId: input.connectorId,
|
|
293
|
+
action: input.action,
|
|
294
|
+
reason: skip.reason,
|
|
295
|
+
});
|
|
296
|
+
return skip;
|
|
297
|
+
}
|
|
298
|
+
return run();
|
|
299
|
+
};
|
|
300
|
+
|
|
125
301
|
// Outside a journey run (an admin/manual send) there is no replay to defend
|
|
126
|
-
// against and no boundary to key from — run the action directly.
|
|
302
|
+
// against and no boundary to key from — gate then run the action directly.
|
|
127
303
|
const boundary = getJourneyBoundary();
|
|
128
|
-
if (!boundary) return doRun
|
|
304
|
+
if (!boundary) return gate(doRun);
|
|
129
305
|
|
|
130
306
|
// The replay-stable, branch-derived key shared by BOTH defense layers. `site`
|
|
131
307
|
// = the explicit `idempotencyLabel` ?? the nearest authored wait/checkpoint
|
|
@@ -145,20 +321,28 @@ export async function sendConnectorAction(
|
|
|
145
321
|
registerKey(boundary, key);
|
|
146
322
|
|
|
147
323
|
// Layer 1 (eviction-gated, FREE) fast path wrapping the Layer-2-backed run.
|
|
148
|
-
// When the engine supports eviction the durable `memo()` skips the
|
|
149
|
-
//
|
|
150
|
-
//
|
|
151
|
-
//
|
|
152
|
-
//
|
|
153
|
-
//
|
|
324
|
+
// When the engine supports eviction the durable `memo()` skips the closure —
|
|
325
|
+
// the preference gate, the action, AND the DB round-trip below — entirely on a
|
|
326
|
+
// replay, replaying whatever the FIRST run recorded (a skip verdict OR the
|
|
327
|
+
// send result). When it does NOT (a pre-eviction / ':latest'-drifted engine),
|
|
328
|
+
// `memoize` falls through to the closure and Layer 2 (the
|
|
329
|
+
// `connector_deliveries` short-circuit) is the version-INDEPENDENT exactly-once
|
|
330
|
+
// guarantee. Belt-and-suspenders, mirroring the email send path (tracked.ts).
|
|
331
|
+
//
|
|
332
|
+
// The gate runs INSIDE the closure so a skip is memo-recorded: a preference
|
|
333
|
+
// flip between run and replay cannot change the recorded verdict. On a skip we
|
|
334
|
+
// never reach `runWithConnectorDelivery`, so NO `connector_deliveries` row is
|
|
335
|
+
// ever claimed for a skipped send (zero migrations; the enum is untouched).
|
|
154
336
|
return boundary.memoize([key], () =>
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
337
|
+
gate(() =>
|
|
338
|
+
runWithConnectorDelivery({
|
|
339
|
+
db,
|
|
340
|
+
connectorId: input.connectorId,
|
|
341
|
+
action: input.action,
|
|
342
|
+
dedupeKey: key,
|
|
343
|
+
run: doRun,
|
|
344
|
+
}),
|
|
345
|
+
),
|
|
162
346
|
);
|
|
163
347
|
}
|
|
164
348
|
|
package/src/lib/contacts.ts
CHANGED
|
@@ -34,6 +34,53 @@ export class PublishableAnonymousMergeError extends Error {
|
|
|
34
34
|
}
|
|
35
35
|
}
|
|
36
36
|
|
|
37
|
+
/**
|
|
38
|
+
* True when `value` is the canonical key of an IDENTIFIED contact — i.e. a
|
|
39
|
+
* live contact's `external_id`, or its `email` when that is its canonical key
|
|
40
|
+
* (no `external_id`). Such a value names an identified person, so a
|
|
41
|
+
* token-less publishable/unauthenticated caller must NOT be allowed to claim
|
|
42
|
+
* it as an "anon id" (the feed-read and arrival-stamp forgery guard).
|
|
43
|
+
*
|
|
44
|
+
* A genuine browser anon id only ever matches a contact via `anonymous_id`
|
|
45
|
+
* whose canonical key is that same anon id (the contact has no `external_id`)
|
|
46
|
+
* — that is the caller's OWN anon contact and is allowed (returns false).
|
|
47
|
+
*
|
|
48
|
+
* Lives here beside `PublishableAnonymousMergeError` because it is the same
|
|
49
|
+
* invariant read-side: consumed by `resolveFeedRecipient` (feed reads) and
|
|
50
|
+
* `POST /v1/t/arrive` (arrival stamps).
|
|
51
|
+
*/
|
|
52
|
+
export async function collidesWithIdentified(
|
|
53
|
+
db: Database,
|
|
54
|
+
value: string,
|
|
55
|
+
): Promise<boolean> {
|
|
56
|
+
const rows = await db
|
|
57
|
+
.select({
|
|
58
|
+
externalId: contacts.externalId,
|
|
59
|
+
email: contacts.email,
|
|
60
|
+
anonymousId: contacts.anonymousId,
|
|
61
|
+
})
|
|
62
|
+
.from(contacts)
|
|
63
|
+
.where(
|
|
64
|
+
and(
|
|
65
|
+
or(
|
|
66
|
+
eq(contacts.externalId, value),
|
|
67
|
+
eq(contacts.email, value),
|
|
68
|
+
eq(contacts.anonymousId, value),
|
|
69
|
+
),
|
|
70
|
+
isNull(contacts.deletedAt),
|
|
71
|
+
),
|
|
72
|
+
);
|
|
73
|
+
for (const row of rows) {
|
|
74
|
+
// The supplied value is this contact's `external_id` → its rows are keyed
|
|
75
|
+
// on it (identified). Reject.
|
|
76
|
+
if (row.externalId === value) return true;
|
|
77
|
+
// The supplied value is this contact's `email` AND that email is its
|
|
78
|
+
// canonical key (no external_id) → identified rows are keyed on it. Reject.
|
|
79
|
+
if (row.email === value && !row.externalId) return true;
|
|
80
|
+
}
|
|
81
|
+
return false;
|
|
82
|
+
}
|
|
83
|
+
|
|
37
84
|
/**
|
|
38
85
|
* Thrown by {@link resolveOrCreateContact}'s engine-internal `contactId` pin when
|
|
39
86
|
* the pinned subject row no longer exists and no merge-alias chain leads to a live
|
|
@@ -150,6 +197,13 @@ export function normalizeEmail(raw: string): string {
|
|
|
150
197
|
return raw.trim().toLowerCase();
|
|
151
198
|
}
|
|
152
199
|
|
|
200
|
+
/** `normalizeEmail` for a maybe-missing address. */
|
|
201
|
+
export function normalizeEmailOrNull(
|
|
202
|
+
email: string | null | undefined,
|
|
203
|
+
): string | null {
|
|
204
|
+
return email ? normalizeEmail(email) : null;
|
|
205
|
+
}
|
|
206
|
+
|
|
153
207
|
// ---------------------------------------------------------------------------
|
|
154
208
|
// Identity resolution
|
|
155
209
|
// ---------------------------------------------------------------------------
|
|
@@ -76,11 +76,14 @@ export interface TrackedSendResult {
|
|
|
76
76
|
/**
|
|
77
77
|
* Present only when `status === "skipped"`:
|
|
78
78
|
* - `"frequency_capped"` — the per-recipient frequency cap was hit.
|
|
79
|
+
* - `"journey_suppressed"` — the enclosing journey's `meta.suppress` min-gap
|
|
80
|
+
* was in force: a non-failed send for this journey to this recipient already
|
|
81
|
+
* went out inside the window, so this one was skipped (no row, no send).
|
|
79
82
|
* - `"test_mode_blocked"` — test mode was active but no redirect address
|
|
80
83
|
* resolved (no `HOGSEND_TEST_EMAIL` / `STUDIO_ADMIN_EMAIL`), so the send was
|
|
81
84
|
* blocked rather than delivered to the real recipient.
|
|
82
85
|
*/
|
|
83
|
-
reason?: "frequency_capped" | "test_mode_blocked";
|
|
86
|
+
reason?: "frequency_capped" | "journey_suppressed" | "test_mode_blocked";
|
|
84
87
|
}
|
|
85
88
|
|
|
86
89
|
/**
|
package/src/lib/email.ts
CHANGED
|
@@ -40,7 +40,13 @@ export interface SendEmailOptions {
|
|
|
40
40
|
* dynamically (e.g. the public `POST /v1/emails`).
|
|
41
41
|
*/
|
|
42
42
|
template: TemplateName;
|
|
43
|
-
|
|
43
|
+
/**
|
|
44
|
+
* The email subject. Optional: when omitted, the tracked mailer falls back
|
|
45
|
+
* to the template registry's `defaultSubject` for {@link template} (the
|
|
46
|
+
* blueprint interpreter's send nodes rely on this — a blueprint send node
|
|
47
|
+
* carries only a template key). Code journeys typically pass it explicitly.
|
|
48
|
+
*/
|
|
49
|
+
subject?: string;
|
|
44
50
|
journeyName?: string;
|
|
45
51
|
journeyStateId?: string;
|
|
46
52
|
props?: Record<string, unknown>;
|
|
@@ -137,7 +143,12 @@ export async function sendEmail(
|
|
|
137
143
|
idempotencyKey: resolvedIdempotencyKey,
|
|
138
144
|
userId: opts.userId,
|
|
139
145
|
userEmail: opts.to,
|
|
140
|
-
category
|
|
146
|
+
// A journey may stamp its own email-preference category (`meta.category`,
|
|
147
|
+
// threaded onto the boundary) — it overrides the template's own category at
|
|
148
|
+
// send time exactly as this hardcoded `"journey"` default did. Outside a
|
|
149
|
+
// journey there is no boundary, so this stays the built-in `journey`
|
|
150
|
+
// category, unchanged.
|
|
151
|
+
category: boundary?.category ?? "journey",
|
|
141
152
|
tags: [
|
|
142
153
|
{ name: "journeyId", value: opts.journeyName ?? opts.template },
|
|
143
154
|
{ name: "templateKey", value: opts.template },
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Event-name vocabulary — the merged observed + declared listing shared by
|
|
3
|
+
* the agent tools (`mcp/blueprint-tools.ts` `list_events`) and the admin
|
|
4
|
+
* route (`GET /v1/admin/events/names`). One runtime implementation (the
|
|
5
|
+
* same lib-delegation pattern the other blueprint tools follow via
|
|
6
|
+
* `lib/blueprints.ts`), so the two surfaces — including the note text —
|
|
7
|
+
* can never drift.
|
|
8
|
+
*
|
|
9
|
+
* Event names are an OPEN vocabulary (no closed registry exists anywhere in
|
|
10
|
+
* the engine — same as code journeys): this merges events actually observed
|
|
11
|
+
* in `user_events` (occurrence counts, most recently seen first) with events
|
|
12
|
+
* referenced as code-journey or blueprint triggers. Any other name is also
|
|
13
|
+
* valid — it just hasn't been seen yet.
|
|
14
|
+
*/
|
|
15
|
+
import { journeyBlueprints, userEvents } from "@hogsend/db";
|
|
16
|
+
import { z } from "@hono/zod-openapi";
|
|
17
|
+
import { count, desc, ilike, inArray, max } from "drizzle-orm";
|
|
18
|
+
import type { HogsendClient } from "../container.js";
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* One merged event-name entry. Canonical shape shared by the helper's return,
|
|
22
|
+
* the `list_events` tool, and the `GET /v1/admin/events/names` OpenAPI response
|
|
23
|
+
* (the route imports this instead of re-declaring it, so they can never drift).
|
|
24
|
+
*/
|
|
25
|
+
export const eventNameEntrySchema = z.object({
|
|
26
|
+
name: z.string(),
|
|
27
|
+
occurrences: z.number(),
|
|
28
|
+
lastSeenAt: z.string().nullable(),
|
|
29
|
+
// Where the name is declared as a trigger: "journey:<id>" for code journeys,
|
|
30
|
+
// "blueprint:<id> (<status>)" for blueprints.
|
|
31
|
+
usedBy: z.array(z.string()),
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
export type EventNameEntry = z.infer<typeof eventNameEntrySchema>;
|
|
35
|
+
|
|
36
|
+
const EVENT_NAMES_NOTE =
|
|
37
|
+
"Event names are an open vocabulary — this is observed + declared usage, not a closed registry. " +
|
|
38
|
+
"Reserved namespaces (email.*, journey.*, bucket.*, contact.*) are engine-emitted; don't use them as blueprint trigger events.";
|
|
39
|
+
|
|
40
|
+
export async function listEventNameVocabulary(opts: {
|
|
41
|
+
db: HogsendClient["db"];
|
|
42
|
+
registry: HogsendClient["registry"];
|
|
43
|
+
/** Case-insensitive substring filter on the event name. */
|
|
44
|
+
search?: string;
|
|
45
|
+
/** Cap on the observed-events scan (the declared merge is uncapped). */
|
|
46
|
+
limit: number;
|
|
47
|
+
}): Promise<{ note: string; events: EventNameEntry[] }> {
|
|
48
|
+
const { db, registry, search, limit } = opts;
|
|
49
|
+
|
|
50
|
+
// Observed vocabulary — grouped scan of user_events, recency-first. ilike
|
|
51
|
+
// special chars are escaped so a search of "100%" matches literally
|
|
52
|
+
// instead of becoming a wildcard. The blueprint-trigger select is
|
|
53
|
+
// independent of it, so both go out in one round-trip.
|
|
54
|
+
const escaped = search?.replace(/[\\%_]/g, (m) => `\\${m}`);
|
|
55
|
+
const lastSeen = max(userEvents.occurredAt);
|
|
56
|
+
const [observed, blueprintRows] = await Promise.all([
|
|
57
|
+
db
|
|
58
|
+
.select({
|
|
59
|
+
name: userEvents.event,
|
|
60
|
+
occurrences: count(),
|
|
61
|
+
lastSeenAt: lastSeen,
|
|
62
|
+
})
|
|
63
|
+
.from(userEvents)
|
|
64
|
+
.where(escaped ? ilike(userEvents.event, `%${escaped}%`) : undefined)
|
|
65
|
+
.groupBy(userEvents.event)
|
|
66
|
+
.orderBy(desc(lastSeen))
|
|
67
|
+
.limit(limit),
|
|
68
|
+
db
|
|
69
|
+
.select({
|
|
70
|
+
id: journeyBlueprints.id,
|
|
71
|
+
triggerEvent: journeyBlueprints.triggerEvent,
|
|
72
|
+
status: journeyBlueprints.status,
|
|
73
|
+
})
|
|
74
|
+
.from(journeyBlueprints),
|
|
75
|
+
]);
|
|
76
|
+
|
|
77
|
+
const byName = new Map<string, EventNameEntry>();
|
|
78
|
+
for (const row of observed) {
|
|
79
|
+
byName.set(row.name, {
|
|
80
|
+
name: row.name,
|
|
81
|
+
occurrences: Number(row.occurrences),
|
|
82
|
+
lastSeenAt: row.lastSeenAt?.toISOString() ?? null,
|
|
83
|
+
usedBy: [],
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
const matches = (name: string) =>
|
|
88
|
+
!search || name.toLowerCase().includes(search.toLowerCase());
|
|
89
|
+
const entryFor = (name: string): EventNameEntry => {
|
|
90
|
+
const existing = byName.get(name);
|
|
91
|
+
if (existing) return existing;
|
|
92
|
+
const created: EventNameEntry = {
|
|
93
|
+
name,
|
|
94
|
+
occurrences: 0,
|
|
95
|
+
lastSeenAt: null,
|
|
96
|
+
usedBy: [],
|
|
97
|
+
};
|
|
98
|
+
byName.set(name, created);
|
|
99
|
+
return created;
|
|
100
|
+
};
|
|
101
|
+
|
|
102
|
+
// Declared vocabulary — code-journey triggers (never observed rows if
|
|
103
|
+
// nothing fired yet) and blueprint triggers, labeled by consumer.
|
|
104
|
+
for (const journey of registry.getAll()) {
|
|
105
|
+
const event = journey.trigger?.event;
|
|
106
|
+
if (!event || !matches(event)) continue;
|
|
107
|
+
entryFor(event).usedBy.push(`journey:${journey.id}`);
|
|
108
|
+
}
|
|
109
|
+
for (const bp of blueprintRows) {
|
|
110
|
+
if (!matches(bp.triggerEvent)) continue;
|
|
111
|
+
entryFor(bp.triggerEvent).usedBy.push(`blueprint:${bp.id} (${bp.status})`);
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
// A declared trigger (registry/blueprint) can have real rows in user_events
|
|
115
|
+
// that fell OUTSIDE the recency-capped observed scan above — it would then
|
|
116
|
+
// read `occurrences: 0 / lastSeenAt: null`, misreporting a busy event as
|
|
117
|
+
// never-fired. Observed rows always count >= 1, so `occurrences === 0` marks
|
|
118
|
+
// exactly the declared-only entries. Backfill their true counts with ONE
|
|
119
|
+
// targeted, bounded query (declared names are few — the code-journey +
|
|
120
|
+
// blueprint trigger set, not the open vocabulary).
|
|
121
|
+
const zeroNames = [...byName.values()]
|
|
122
|
+
.filter((e) => e.occurrences === 0)
|
|
123
|
+
.map((e) => e.name);
|
|
124
|
+
if (zeroNames.length > 0) {
|
|
125
|
+
const backfill = await db
|
|
126
|
+
.select({
|
|
127
|
+
name: userEvents.event,
|
|
128
|
+
occurrences: count(),
|
|
129
|
+
lastSeenAt: max(userEvents.occurredAt),
|
|
130
|
+
})
|
|
131
|
+
.from(userEvents)
|
|
132
|
+
.where(inArray(userEvents.event, zeroNames))
|
|
133
|
+
.groupBy(userEvents.event);
|
|
134
|
+
for (const row of backfill) {
|
|
135
|
+
const entry = byName.get(row.name);
|
|
136
|
+
if (!entry) continue;
|
|
137
|
+
entry.occurrences = Number(row.occurrences);
|
|
138
|
+
entry.lastSeenAt = row.lastSeenAt?.toISOString() ?? null;
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
return { note: EVENT_NAMES_NOTE, events: [...byName.values()] };
|
|
143
|
+
}
|