@hogsend/engine 0.40.0 → 0.42.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/package.json +11 -8
  2. package/src/buckets/check-membership.ts +6 -1
  3. package/src/campaigns/cohort-sql.ts +198 -0
  4. package/src/campaigns/define-campaign.ts +207 -28
  5. package/src/campaigns/reconcile.ts +105 -11
  6. package/src/campaigns/steps.ts +48 -0
  7. package/src/connectors/define-action.ts +70 -0
  8. package/src/container.ts +124 -42
  9. package/src/destinations/presets/posthog.ts +7 -1
  10. package/src/index.ts +96 -2
  11. package/src/journeys/constants.ts +10 -0
  12. package/src/journeys/define-journey.ts +14 -405
  13. package/src/journeys/execute-journey-run.ts +641 -0
  14. package/src/journeys/graph/build-graph.ts +212 -56
  15. package/src/journeys/journey-boundary.ts +54 -0
  16. package/src/journeys/journey-context.ts +406 -59
  17. package/src/journeys/record-once.ts +110 -0
  18. package/src/lib/blueprint-lock.ts +21 -0
  19. package/src/lib/blueprints.ts +803 -0
  20. package/src/lib/campaign-send-key.ts +58 -0
  21. package/src/lib/connector-actions.ts +203 -19
  22. package/src/lib/contacts.ts +54 -0
  23. package/src/lib/email-service-types.ts +4 -1
  24. package/src/lib/email.ts +13 -2
  25. package/src/lib/event-names.ts +143 -0
  26. package/src/lib/feed.ts +77 -57
  27. package/src/lib/frequency-cap.ts +45 -15
  28. package/src/lib/hatchet-duration.ts +22 -0
  29. package/src/lib/html.ts +1 -0
  30. package/src/lib/ingestion.ts +145 -4
  31. package/src/lib/journey-suppress.ts +87 -0
  32. package/src/lib/links.ts +204 -18
  33. package/src/lib/outbound.ts +20 -0
  34. package/src/lib/preferences.ts +80 -1
  35. package/src/lib/tracked.ts +44 -29
  36. package/src/lib/tracking-event-names.ts +8 -0
  37. package/src/lib/tracking.ts +1 -5
  38. package/src/lib/webhook-signing.ts +6 -1
  39. package/src/lists/channels.ts +75 -0
  40. package/src/lists/define-list.ts +34 -0
  41. package/src/lists/registry.ts +29 -2
  42. package/src/mcp/authoring-guide.ts +160 -0
  43. package/src/mcp/blueprint-tools.ts +390 -0
  44. package/src/middleware/require-admin.ts +13 -0
  45. package/src/routes/admin/api-keys.ts +72 -0
  46. package/src/routes/admin/blueprints.ts +795 -0
  47. package/src/routes/admin/campaigns.ts +179 -3
  48. package/src/routes/admin/emails.ts +13 -0
  49. package/src/routes/admin/events.ts +55 -0
  50. package/src/routes/admin/index.ts +4 -0
  51. package/src/routes/admin/journeys.ts +4 -2
  52. package/src/routes/admin/links.ts +303 -36
  53. package/src/routes/admin/lists.ts +51 -0
  54. package/src/routes/campaigns/index.ts +44 -6
  55. package/src/routes/email/preferences.ts +50 -13
  56. package/src/routes/feed/recipient.ts +2 -43
  57. package/src/routes/index.ts +6 -0
  58. package/src/routes/lists/index.ts +138 -18
  59. package/src/routes/tracking/arrive.ts +260 -0
  60. package/src/routes/tracking/click-pipeline.ts +329 -0
  61. package/src/routes/tracking/click.ts +5 -270
  62. package/src/routes/tracking/index.ts +2 -0
  63. package/src/routes/tracking/vanity.ts +64 -0
  64. package/src/worker.ts +5 -0
  65. package/src/workflows/bucket-backfill.ts +4 -2
  66. package/src/workflows/bucket-reconcile.ts +11 -4
  67. package/src/workflows/check-alerts.ts +130 -1
  68. package/src/workflows/journey-blueprint-interpreter.ts +656 -0
  69. package/src/workflows/send-campaign.ts +574 -180
@@ -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 { ResolvedActionContact } from "../connectors/define-action.js";
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: createLogger(env.LOG_LEVEL),
122
- resolveContact: (ref: string) => resolveContact(db, ref),
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 action —
149
- // and the DB round-trip below — entirely on a replay. When it does NOT (a
150
- // pre-eviction / ':latest'-drifted engine), `memoize` falls through to the
151
- // closure and Layer 2 (the `connector_deliveries` short-circuit) is the
152
- // version-INDEPENDENT exactly-once guarantee. Belt-and-suspenders, mirroring
153
- // the email send path (tracked.ts).
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
- runWithConnectorDelivery({
156
- db,
157
- connectorId: input.connectorId,
158
- action: input.action,
159
- dedupeKey: key,
160
- run: doRun,
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
 
@@ -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
- subject: string;
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: "journey",
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
+ }