@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
|
@@ -15,16 +15,24 @@
|
|
|
15
15
|
* and warn loudly. A late deploy NEVER fires a surprise blast; bump
|
|
16
16
|
* `sendAt` (or delete the file) to resolve.
|
|
17
17
|
* - Row exists and is still `scheduled` → sync mutable fields (name,
|
|
18
|
-
* audience, template, props, subject, from, sendAt) so editing the
|
|
19
|
-
* redeploying updates the pending broadcast — the git-ops loop. A
|
|
20
|
-
* `sendAt` gets a fresh scheduled run; the stale run no-ops via the
|
|
21
|
-
* task's early-fire guard.
|
|
18
|
+
* audience, template, props, subject, from, sendAt, steps) so editing the
|
|
19
|
+
* file and redeploying updates the pending broadcast — the git-ops loop. A
|
|
20
|
+
* moved `sendAt` gets a fresh scheduled run; the stale run no-ops via the
|
|
21
|
+
* send task's early-fire guard.
|
|
22
22
|
* - Row exists in any other status (`sent`/`canceled`/`expired`/`failed`/
|
|
23
|
-
* in-flight) → no-op. `sent` is the natural "retired" end state;
|
|
24
|
-
* operator `canceled` is never resurrected by a redeploy.
|
|
23
|
+
* in-flight/`waiting`) → no-op. `sent` is the natural "retired" end state;
|
|
24
|
+
* an operator `canceled` is never resurrected by a redeploy. Editing steps
|
|
25
|
+
* mid-flight is deliberately unsupported in v1 — once the campaign leaves
|
|
26
|
+
* `scheduled` (running or waiting between waves), the row is the source of
|
|
27
|
+
* truth.
|
|
25
28
|
*/
|
|
29
|
+
import type { CampaignSendStep } from "@hogsend/core";
|
|
26
30
|
import { campaigns } from "@hogsend/db";
|
|
27
|
-
import {
|
|
31
|
+
import {
|
|
32
|
+
getTemplateDefinition,
|
|
33
|
+
getTemplateNames,
|
|
34
|
+
type TemplateName,
|
|
35
|
+
} from "@hogsend/email";
|
|
28
36
|
import { and, eq, sql } from "drizzle-orm";
|
|
29
37
|
import type { HogsendClient } from "../container.js";
|
|
30
38
|
import { sendCampaignTask } from "../workflows/send-campaign.js";
|
|
@@ -100,15 +108,72 @@ export async function reconcileDefinedCampaigns(opts: {
|
|
|
100
108
|
result.skipped++;
|
|
101
109
|
continue;
|
|
102
110
|
}
|
|
103
|
-
|
|
111
|
+
// A list-audience campaign resolves recipients by SUBSCRIPTION. A channel
|
|
112
|
+
// preference list (`kind:"channel"`) gates a delivery transport (the in-app
|
|
113
|
+
// feed, a connector), not an email topic — a channel audience would EMAIL
|
|
114
|
+
// everyone not opted out of e.g. the discord channel. Mirror the unknown-
|
|
115
|
+
// audience config-error path: warn + skip, never throw (one bad definition
|
|
116
|
+
// must not take down worker boot for every campaign).
|
|
117
|
+
if (audienceKind === "list" && listRegistry.isChannel(audienceId)) {
|
|
118
|
+
logger.error(
|
|
119
|
+
"campaigns: channel-list audience — skipping definition (a channel preference list cannot be a campaign audience)",
|
|
120
|
+
{ campaignId: meta.id, audienceId },
|
|
121
|
+
);
|
|
122
|
+
result.skipped++;
|
|
123
|
+
continue;
|
|
124
|
+
}
|
|
125
|
+
// Validate EVERY send step's template, not just the mirrored first-step
|
|
126
|
+
// `meta.template` — a broken template on step 3 must be caught at deploy
|
|
127
|
+
// time, not mid-campaign two days into a wait.
|
|
128
|
+
const sendSteps = meta.steps.filter(
|
|
129
|
+
(s): s is CampaignSendStep => s.kind === "send",
|
|
130
|
+
);
|
|
131
|
+
const unknownTemplates = sendSteps
|
|
132
|
+
.map((s) => s.template)
|
|
133
|
+
.filter((t) => !templateNames.has(t));
|
|
134
|
+
if (unknownTemplates.length > 0) {
|
|
104
135
|
logger.error("campaigns: unknown template — skipping definition", {
|
|
105
136
|
campaignId: meta.id,
|
|
106
|
-
|
|
137
|
+
templates: unknownTemplates,
|
|
107
138
|
});
|
|
108
139
|
result.skipped++;
|
|
109
140
|
continue;
|
|
110
141
|
}
|
|
111
142
|
|
|
143
|
+
// A bucket campaign borrows consent from each template's declared
|
|
144
|
+
// category (a bucket is behavior, not consent — docs/audience-model.md).
|
|
145
|
+
// A categoryless template leaves suppression + List-Unsubscribe with
|
|
146
|
+
// nothing beyond unsubscribedAll/suppressed, so its compliance story is
|
|
147
|
+
// only as good as the template's category. Warn, don't skip — the send is
|
|
148
|
+
// legal-by-default, just weaker than it should be.
|
|
149
|
+
if (audienceKind === "bucket") {
|
|
150
|
+
for (const s of sendSteps) {
|
|
151
|
+
const definition = getTemplateDefinition({
|
|
152
|
+
key: s.template as TemplateName,
|
|
153
|
+
registry: templates,
|
|
154
|
+
});
|
|
155
|
+
if (!definition.category) {
|
|
156
|
+
logger.warn(
|
|
157
|
+
"campaigns: bucket-audience campaign template has no category — consent/unsubscribe fall back to the global opt-out only",
|
|
158
|
+
{ campaignId: meta.id, template: s.template },
|
|
159
|
+
);
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
// The stored steps blob: multi-step definitions persist `{ v: 1, steps }`;
|
|
165
|
+
// a single-step definition stores NULL — the legacy row shape — so its
|
|
166
|
+
// per-send idempotency keys stay byte-for-byte legacy (campaignSendKey
|
|
167
|
+
// contract). The cast crosses the db package's opaque element type (db
|
|
168
|
+
// cannot import @hogsend/core; the engine narrows at read time).
|
|
169
|
+
const stepsBlob =
|
|
170
|
+
meta.steps.length > 1
|
|
171
|
+
? {
|
|
172
|
+
v: 1 as const,
|
|
173
|
+
steps: meta.steps as unknown as Array<Record<string, unknown>>,
|
|
174
|
+
}
|
|
175
|
+
: null;
|
|
176
|
+
|
|
112
177
|
const idempotencyKey = `${DEFINED_CAMPAIGN_KEY_PREFIX}${meta.id}`;
|
|
113
178
|
const existingRows = await db
|
|
114
179
|
.select({
|
|
@@ -121,6 +186,7 @@ export async function reconcileDefinedCampaigns(opts: {
|
|
|
121
186
|
props: campaigns.props,
|
|
122
187
|
fromEmail: campaigns.fromEmail,
|
|
123
188
|
subject: campaigns.subject,
|
|
189
|
+
steps: campaigns.steps,
|
|
124
190
|
scheduledAt: campaigns.scheduledAt,
|
|
125
191
|
})
|
|
126
192
|
.from(campaigns)
|
|
@@ -143,6 +209,7 @@ export async function reconcileDefinedCampaigns(opts: {
|
|
|
143
209
|
props: meta.props ?? {},
|
|
144
210
|
fromEmail: meta.from ?? null,
|
|
145
211
|
subject: meta.subject ?? null,
|
|
212
|
+
steps: stepsBlob,
|
|
146
213
|
scheduledAt: meta.sendAt,
|
|
147
214
|
idempotencyKey,
|
|
148
215
|
});
|
|
@@ -169,6 +236,7 @@ export async function reconcileDefinedCampaigns(opts: {
|
|
|
169
236
|
props: meta.props ?? {},
|
|
170
237
|
fromEmail: meta.from ?? null,
|
|
171
238
|
subject: meta.subject ?? null,
|
|
239
|
+
steps: stepsBlob,
|
|
172
240
|
scheduledAt: meta.sendAt,
|
|
173
241
|
idempotencyKey,
|
|
174
242
|
})
|
|
@@ -210,10 +278,10 @@ export async function reconcileDefinedCampaigns(opts: {
|
|
|
210
278
|
existing.audienceKind !== audienceKind ||
|
|
211
279
|
existing.audienceId !== audienceId ||
|
|
212
280
|
existing.templateKey !== meta.template ||
|
|
213
|
-
|
|
214
|
-
JSON.stringify(meta.props ?? {}) ||
|
|
281
|
+
canonicalJson(existing.props ?? {}) !== canonicalJson(meta.props ?? {}) ||
|
|
215
282
|
(existing.fromEmail ?? null) !== (meta.from ?? null) ||
|
|
216
283
|
(existing.subject ?? null) !== (meta.subject ?? null) ||
|
|
284
|
+
canonicalJson(existing.steps ?? null) !== canonicalJson(stepsBlob) ||
|
|
217
285
|
existing.scheduledAt?.getTime() !== meta.sendAt.getTime();
|
|
218
286
|
|
|
219
287
|
if (!changed) {
|
|
@@ -236,6 +304,7 @@ export async function reconcileDefinedCampaigns(opts: {
|
|
|
236
304
|
props: meta.props ?? {},
|
|
237
305
|
fromEmail: meta.from ?? null,
|
|
238
306
|
subject: meta.subject ?? null,
|
|
307
|
+
steps: stepsBlob,
|
|
239
308
|
scheduledAt: meta.sendAt,
|
|
240
309
|
updatedAt: new Date(),
|
|
241
310
|
})
|
|
@@ -266,6 +335,31 @@ export async function reconcileDefinedCampaigns(opts: {
|
|
|
266
335
|
return result;
|
|
267
336
|
}
|
|
268
337
|
|
|
338
|
+
/**
|
|
339
|
+
* Key-order-canonical JSON for the changed-comparison. `existing.props` /
|
|
340
|
+
* `existing.steps` round-trip through Postgres jsonb, which does NOT preserve
|
|
341
|
+
* object key order (jsonb canonicalizes it), so a plain `JSON.stringify`
|
|
342
|
+
* comparison against the freshly-authored definition would report a permanent
|
|
343
|
+
* phantom "changed" for any multi-key object — an unchanged definition
|
|
344
|
+
* rewritten (and logged as updated) on every worker boot. Arrays keep their
|
|
345
|
+
* order; only object keys are sorted.
|
|
346
|
+
*/
|
|
347
|
+
function canonicalJson(value: unknown): string {
|
|
348
|
+
return JSON.stringify(sortKeysDeep(value));
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
function sortKeysDeep(value: unknown): unknown {
|
|
352
|
+
if (Array.isArray(value)) return value.map(sortKeysDeep);
|
|
353
|
+
if (value !== null && typeof value === "object") {
|
|
354
|
+
return Object.fromEntries(
|
|
355
|
+
Object.entries(value as Record<string, unknown>)
|
|
356
|
+
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
|
|
357
|
+
.map(([key, entry]) => [key, sortKeysDeep(entry)]),
|
|
358
|
+
);
|
|
359
|
+
}
|
|
360
|
+
return value;
|
|
361
|
+
}
|
|
362
|
+
|
|
269
363
|
/**
|
|
270
364
|
* Create the punctual trigger for a scheduled row: a Hatchet scheduled run at
|
|
271
365
|
* `sendAt`, or an immediate enqueue when already due (within grace).
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Authoring sugar for campaign steps ({@link defineCampaign} `steps:`).
|
|
3
|
+
* Each helper returns the plain stored POJO ({@link CampaignStep} —
|
|
4
|
+
* `campaigns.steps` blob entries): `step.send` normalizes a `where` builder
|
|
5
|
+
* to `ConditionEval[]` HERE, at authoring time (the same
|
|
6
|
+
* normalize-at-definition pattern as `trigger.where` in `defineJourney`), so
|
|
7
|
+
* the stored form is always introspectable data. Channel steps
|
|
8
|
+
* (`step.discord.post` / `.dm`, …) are phase 2.
|
|
9
|
+
*/
|
|
10
|
+
import {
|
|
11
|
+
type CampaignSendStep,
|
|
12
|
+
type CampaignWaitStep,
|
|
13
|
+
type CampaignWhere,
|
|
14
|
+
type DurationObject,
|
|
15
|
+
normalizeCampaignWhere,
|
|
16
|
+
} from "@hogsend/core";
|
|
17
|
+
import type { TemplateName } from "@hogsend/email";
|
|
18
|
+
|
|
19
|
+
export const step = {
|
|
20
|
+
/**
|
|
21
|
+
* A per-recipient email wave. `where` filters the campaign's cohort
|
|
22
|
+
* (builder or declarative conditions — engagement terminals with no
|
|
23
|
+
* template scope to "any prior send of this campaign"); only valid on
|
|
24
|
+
* steps after the first (validated by `defineCampaign`).
|
|
25
|
+
*/
|
|
26
|
+
send(opts: {
|
|
27
|
+
template: TemplateName;
|
|
28
|
+
props?: Record<string, unknown>;
|
|
29
|
+
subject?: string;
|
|
30
|
+
from?: string;
|
|
31
|
+
where?: CampaignWhere;
|
|
32
|
+
}): CampaignSendStep {
|
|
33
|
+
const where = normalizeCampaignWhere(opts.where);
|
|
34
|
+
return {
|
|
35
|
+
kind: "send",
|
|
36
|
+
template: opts.template,
|
|
37
|
+
...(opts.props !== undefined ? { props: opts.props } : {}),
|
|
38
|
+
...(opts.subject !== undefined ? { subject: opts.subject } : {}),
|
|
39
|
+
...(opts.from !== undefined ? { from: opts.from } : {}),
|
|
40
|
+
...(where !== undefined ? { where } : {}),
|
|
41
|
+
};
|
|
42
|
+
},
|
|
43
|
+
|
|
44
|
+
/** A durable gap between waves. Minimum 5 minutes (validated). */
|
|
45
|
+
wait(duration: DurationObject): CampaignWaitStep {
|
|
46
|
+
return { kind: "wait", duration };
|
|
47
|
+
},
|
|
48
|
+
};
|
|
@@ -36,6 +36,27 @@ export interface ConnectorActionCtx {
|
|
|
36
36
|
resolveContact(ref: string): Promise<ResolvedActionContact | null>;
|
|
37
37
|
}
|
|
38
38
|
|
|
39
|
+
/**
|
|
40
|
+
* Declares an action MEMBER-DIRECTED — aimed at an individual recipient rather
|
|
41
|
+
* than a channel/ops surface. Its presence gates the action on the recipient's
|
|
42
|
+
* channel preferences (the auto-registered per-connector opt-out list) before
|
|
43
|
+
* the plugin runs; enforcement lands in a later phase. Absent audience =
|
|
44
|
+
* ops/channel-directed = never gated.
|
|
45
|
+
*/
|
|
46
|
+
export interface MemberAudience<A = unknown> {
|
|
47
|
+
kind: "member";
|
|
48
|
+
/**
|
|
49
|
+
* Candidate recipient refs (email | externalId | platform id | namespaced key
|
|
50
|
+
* like "telegram:<chatId>"), tried in order; first resolving contact wins.
|
|
51
|
+
* Returning undefined (or throwing) fails OPEN — the send proceeds.
|
|
52
|
+
*
|
|
53
|
+
* Method shorthand (bivariant) so a `DefinedConnectorAction<DmArgs, …>` stays
|
|
54
|
+
* assignable to the erased `DefinedConnectorAction[]` the registry/plugin
|
|
55
|
+
* index files use (same reason `run` is method shorthand).
|
|
56
|
+
*/
|
|
57
|
+
ref(args: A): string | string[] | undefined;
|
|
58
|
+
}
|
|
59
|
+
|
|
39
60
|
export interface DefinedConnectorAction<A = unknown, R = unknown> {
|
|
40
61
|
/** The connector this action belongs to (e.g. "discord"). Keys the registry. */
|
|
41
62
|
connectorId: string;
|
|
@@ -43,6 +64,12 @@ export interface DefinedConnectorAction<A = unknown, R = unknown> {
|
|
|
43
64
|
name: string;
|
|
44
65
|
/** Optional human description (Studio enumeration / docs). */
|
|
45
66
|
description?: string;
|
|
67
|
+
/**
|
|
68
|
+
* When set, declares the action member-directed: the engine will gate it on
|
|
69
|
+
* the recipient's channel preferences before the plugin runs (enforcement
|
|
70
|
+
* lands in a later phase). Absent = ops/channel-directed = never gated.
|
|
71
|
+
*/
|
|
72
|
+
audience?: MemberAudience<A>;
|
|
46
73
|
/** Perform the outbound action. Single-object-in, result-out. */
|
|
47
74
|
run(args: A, ctx: ConnectorActionCtx): Promise<R>;
|
|
48
75
|
}
|
|
@@ -53,3 +80,46 @@ export function defineConnectorAction<A, R>(
|
|
|
53
80
|
): DefinedConnectorAction<A, R> {
|
|
54
81
|
return def;
|
|
55
82
|
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* The verdict returned when the engine SKIPS a member-directed connector action
|
|
86
|
+
* because the resolved recipient opted out — either the global master opt-out
|
|
87
|
+
* (`unsubscribed_all`) or the per-connector channel list (`channel_unsubscribed`).
|
|
88
|
+
*
|
|
89
|
+
* A plain JSON-safe POJO so it is memo-recordable and replays VERBATIM through
|
|
90
|
+
* both the Hatchet durable `memo` (Layer 1) AND the `connector_deliveries.result`
|
|
91
|
+
* jsonb round-trip (Layer 2) — although a skip in practice NEVER writes a
|
|
92
|
+
* delivery row (the gate runs BEFORE the ledger claim), so a skip is observable
|
|
93
|
+
* only via logs + this returned value.
|
|
94
|
+
*
|
|
95
|
+
* The shape DELIBERATELY does NOT mimic per-action result shapes (it carries no
|
|
96
|
+
* `messageId`/`delivered`): the `skipped: true` discriminant must be
|
|
97
|
+
* unambiguous. An existing consumer reading `result.delivered` gets `undefined`
|
|
98
|
+
* (falsy) on a skip — which degrades in the correct direction (treated as "not
|
|
99
|
+
* delivered").
|
|
100
|
+
*/
|
|
101
|
+
export interface ConnectorActionSkipped {
|
|
102
|
+
skipped: true;
|
|
103
|
+
reason: "unsubscribed_all" | "channel_unsubscribed";
|
|
104
|
+
connectorId: string;
|
|
105
|
+
action: string;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Narrow an outbound-action result to a {@link ConnectorActionSkipped} verdict.
|
|
110
|
+
* Checks a non-null object with `skipped === true` plus string
|
|
111
|
+
* `reason`/`connectorId`/`action` — enough to disambiguate from every per-action
|
|
112
|
+
* result shape.
|
|
113
|
+
*/
|
|
114
|
+
export function isConnectorActionSkipped(
|
|
115
|
+
r: unknown,
|
|
116
|
+
): r is ConnectorActionSkipped {
|
|
117
|
+
if (typeof r !== "object" || r === null) return false;
|
|
118
|
+
const v = r as Record<string, unknown>;
|
|
119
|
+
return (
|
|
120
|
+
v.skipped === true &&
|
|
121
|
+
typeof v.reason === "string" &&
|
|
122
|
+
typeof v.connectorId === "string" &&
|
|
123
|
+
typeof v.action === "string"
|
|
124
|
+
);
|
|
125
|
+
}
|
package/src/container.ts
CHANGED
|
@@ -79,6 +79,7 @@ import { createRedisSecondaryStorage, getRedis } from "./lib/redis.js";
|
|
|
79
79
|
import { sendResetPasswordEmail } from "./lib/reset-email.js";
|
|
80
80
|
import { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
|
|
81
81
|
import { prepareTrackedHtml } from "./lib/tracking.js";
|
|
82
|
+
import { synthesizeChannelLists } from "./lists/channels.js";
|
|
82
83
|
import {
|
|
83
84
|
type DefinedList,
|
|
84
85
|
isReservedListId,
|
|
@@ -407,6 +408,96 @@ export interface HogsendClientOptions {
|
|
|
407
408
|
};
|
|
408
409
|
}
|
|
409
410
|
|
|
411
|
+
/**
|
|
412
|
+
* Boot-validate ONE email-preference `category` against the resolvable list
|
|
413
|
+
* namespace — shared by both the template loop and the journey loop below so a
|
|
414
|
+
* category typo/consent-flip is caught fail-CLOSED wherever a category is
|
|
415
|
+
* declared. `owner` is the human-readable prefix naming the offending
|
|
416
|
+
* declaration (e.g. `Email template "welcome"` / `Journey "my-journey"`), so the
|
|
417
|
+
* throw/warn messages read naturally for either source.
|
|
418
|
+
*
|
|
419
|
+
* A `category` IS the `email_preferences.categories` key: at send time
|
|
420
|
+
* `lib/tracked.ts` resolves the effective category and `checkSuppression` gates
|
|
421
|
+
* it through `ListRegistry.isSubscribed`, whose legacy fallback is
|
|
422
|
+
* `this.get(id)?.defaultOptIn ?? true`. So an UNKNOWN/typo'd id resolves to the
|
|
423
|
+
* `?? true` opt-in default → treated as subscribed → NOT suppressed → an opt-in/
|
|
424
|
+
* consent email delivered to everyone (CAN-SPAM/GDPR-grade). This guard makes a
|
|
425
|
+
* mismatched category a loud boot failure so it can never reach that fallback.
|
|
426
|
+
*
|
|
427
|
+
* Branch semantics (preserved from the original inline template loop):
|
|
428
|
+
* - CHANNEL list (`kind:"channel"`) → THROW. A channel gates a delivery
|
|
429
|
+
* transport, not an email topic; using one as an email category is a category
|
|
430
|
+
* error (it would also opt-out-gate the send by the connector's channel).
|
|
431
|
+
* - reserved built-in (`transactional`/`journey`) → OK.
|
|
432
|
+
* - registered topic list → OK.
|
|
433
|
+
* - DEFINED but registry-EXCLUDED (ENABLED_LISTS) → THROW for an opt-in list
|
|
434
|
+
* (excluding it un-gates consent), WARN for an opt-out list (behavior-
|
|
435
|
+
* preserving, but the preference-center entry is hidden while excluded).
|
|
436
|
+
* - unknown → THROW.
|
|
437
|
+
*/
|
|
438
|
+
function validateListCategory(opts: {
|
|
439
|
+
owner: string;
|
|
440
|
+
category: string;
|
|
441
|
+
listRegistry: ListRegistry;
|
|
442
|
+
/** id → `defaultOptIn` for every DEFINED list (`opts.lists`), enabled or not. */
|
|
443
|
+
definedLists: Map<string, boolean>;
|
|
444
|
+
logger: Logger;
|
|
445
|
+
}): void {
|
|
446
|
+
const { owner, category, listRegistry, definedLists, logger } = opts;
|
|
447
|
+
|
|
448
|
+
// A channel list is a registered list (so `has()`/`isSubscribed` treat it as
|
|
449
|
+
// known), which means the reserved/registered OK branches below would wave it
|
|
450
|
+
// through. Reject it FIRST: a channel gates a delivery transport (the in-app
|
|
451
|
+
// feed, a connector), never an email topic.
|
|
452
|
+
if (listRegistry.isChannel(category)) {
|
|
453
|
+
throw new Error(
|
|
454
|
+
`${owner} uses category "${category}": a channel preference list gates a delivery transport, not an email topic — pick a topic list or a built-in category.`,
|
|
455
|
+
);
|
|
456
|
+
}
|
|
457
|
+
// Reserved built-in category (transactional / journey) — never a list, but a
|
|
458
|
+
// legitimate `email_preferences.categories` key. OK.
|
|
459
|
+
if (isReservedListId(category)) return;
|
|
460
|
+
// Category names a REGISTERED topic list ⇒ suppression/preferences gate
|
|
461
|
+
// correctly. (A `defineList({ enabled:false })` is STILL registered — the
|
|
462
|
+
// registry filters on ENABLED_LISTS only, never `meta.enabled` — so it lands
|
|
463
|
+
// here, not in the excluded branch below.)
|
|
464
|
+
if (listRegistry.has(category)) return;
|
|
465
|
+
// Category names a DEFINED list that is EXCLUDED from the registry by an
|
|
466
|
+
// ENABLED_LISTS allowlist that doesn't name it. Excluding it makes the
|
|
467
|
+
// send-time check fall back to the legacy `?? true` opt-in default, which
|
|
468
|
+
// FLIPS the gate by polarity:
|
|
469
|
+
// • opt-IN list (`defaultOptIn:false`, consent required): enabled →
|
|
470
|
+
// `categories[id] === true` (never-consented = NOT subscribed =
|
|
471
|
+
// suppressed); excluded → `categories[id] !== false` (never-consented =
|
|
472
|
+
// SUBSCRIBED = NOT suppressed) → the consent email SHIPS to someone who
|
|
473
|
+
// never opted in. Disabling un-gates consent → THROW (fail closed).
|
|
474
|
+
// • opt-OUT list (`defaultOptIn:true`): both enabled and excluded compute
|
|
475
|
+
// `categories[id] !== false` — IDENTICAL, behavior-preserving → WARN.
|
|
476
|
+
const definedOptIn = definedLists.get(category);
|
|
477
|
+
if (definedOptIn !== undefined) {
|
|
478
|
+
if (definedOptIn === false) {
|
|
479
|
+
throw new Error(
|
|
480
|
+
`${owner} has category "${category}", an OPT-IN email list (defaultOptIn:false) that is DEFINED but EXCLUDED from the active registry by ENABLED_LISTS. At send time an excluded list falls back to the legacy opt-in default, which UN-GATES consent — the opt-in email would ship to recipients who never subscribed. Re-enable the list in ENABLED_LISTS (or change the category) — disabling an opt-in list must not silently flip its consent gate open.`,
|
|
481
|
+
);
|
|
482
|
+
}
|
|
483
|
+
logger.warn(
|
|
484
|
+
`${owner} has category "${category}", a DEFINED email list EXCLUDED from the active registry by ENABLED_LISTS. It is an opt-out list (defaultOptIn:true), so send-time gating is behavior-preserving — but its preference center entry is hidden while excluded. Re-enable the list in ENABLED_LISTS or change the category.`,
|
|
485
|
+
);
|
|
486
|
+
return;
|
|
487
|
+
}
|
|
488
|
+
// Unknown category: neither a reserved built-in nor a defined list. At send
|
|
489
|
+
// time this resolves to the `?? true` opt-in default, bypassing suppression/
|
|
490
|
+
// consent. Fail CLOSED with an actionable message.
|
|
491
|
+
const knownLists = [...definedLists.keys()];
|
|
492
|
+
throw new Error(
|
|
493
|
+
`${owner} has category "${category}", which is neither a reserved built-in category (${[
|
|
494
|
+
...RESERVED_LIST_IDS,
|
|
495
|
+
].join(", ")}) nor a defined email list (${
|
|
496
|
+
knownLists.length ? knownLists.join(", ") : "none"
|
|
497
|
+
}). A category is its email-preferences list key, so it MUST match a list id (defineList) or a reserved built-in — otherwise an unknown/typo'd category silently defaults to opt-in and un-gates suppression/consent. Fix the category or define the list.`,
|
|
498
|
+
);
|
|
499
|
+
}
|
|
500
|
+
|
|
410
501
|
export function createHogsendClient(
|
|
411
502
|
opts: HogsendClientOptions = {},
|
|
412
503
|
): HogsendClient {
|
|
@@ -466,9 +557,17 @@ export function createHogsendClient(
|
|
|
466
557
|
// worker (both call createHogsendClient), so `getListRegistry()` resolves the
|
|
467
558
|
// wired lists in the mailer's suppression check and the preference center in
|
|
468
559
|
// either process. `buildListRegistry` installs the process singleton.
|
|
560
|
+
//
|
|
561
|
+
// Channel lists (the in-app feed + one per connector exposing member-directed
|
|
562
|
+
// actions) are synthesized from the raw `opts.connectorActions` array — which
|
|
563
|
+
// is available here before the connector-action registry is built, and is
|
|
564
|
+
// identical in both the API and worker processes — then registered
|
|
565
|
+
// unconditionally (bypassing ENABLED_LISTS) after the user lists.
|
|
566
|
+
const channelLists = synthesizeChannelLists(opts.connectorActions ?? []);
|
|
469
567
|
const listRegistry = buildListRegistry(
|
|
470
568
|
opts.lists ?? [],
|
|
471
569
|
opts.enabledLists ?? env.ENABLED_LISTS,
|
|
570
|
+
channelLists,
|
|
472
571
|
);
|
|
473
572
|
|
|
474
573
|
// Build the email provider registry, then resolve the single active provider
|
|
@@ -573,48 +672,31 @@ export function createHogsendClient(
|
|
|
573
672
|
const category = (def as TemplateDefinition | undefined)?.category;
|
|
574
673
|
// No category ⇒ no per-list gating for this template; nothing to validate.
|
|
575
674
|
if (!category) continue;
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
}
|
|
602
|
-
logger.warn(
|
|
603
|
-
`Email template "${templateKey}" has category "${category}", a DEFINED email list EXCLUDED from the active registry by ENABLED_LISTS. It is an opt-out list (defaultOptIn:true), so send-time gating is behavior-preserving — but its preference center entry is hidden while excluded. Re-enable the list in ENABLED_LISTS or change the template's category.`,
|
|
604
|
-
);
|
|
605
|
-
continue;
|
|
606
|
-
}
|
|
607
|
-
// Unknown category: neither a reserved built-in nor a defined list. At send
|
|
608
|
-
// time this resolves to the `?? true` opt-in default, bypassing
|
|
609
|
-
// suppression/consent. Fail CLOSED with an actionable message.
|
|
610
|
-
const knownLists = [...definedLists.keys()];
|
|
611
|
-
throw new Error(
|
|
612
|
-
`Email template "${templateKey}" has category "${category}", which is neither a reserved built-in category (${[
|
|
613
|
-
...RESERVED_LIST_IDS,
|
|
614
|
-
].join(", ")}) nor a defined email list (${
|
|
615
|
-
knownLists.length ? knownLists.join(", ") : "none"
|
|
616
|
-
}). A template's category is its email-preferences list key, so it MUST match a list id (defineList) or a reserved built-in — otherwise an unknown/typo'd category silently defaults to opt-in and un-gates suppression/consent. Fix the category or define the list.`,
|
|
617
|
-
);
|
|
675
|
+
validateListCategory({
|
|
676
|
+
owner: `Email template "${templateKey}"`,
|
|
677
|
+
category,
|
|
678
|
+
listRegistry,
|
|
679
|
+
definedLists,
|
|
680
|
+
logger,
|
|
681
|
+
});
|
|
682
|
+
}
|
|
683
|
+
|
|
684
|
+
// Boot-validate every journey's `meta.category` through the SAME helper (same
|
|
685
|
+
// fail-closed branch semantics as templates). A journey stamps its category on
|
|
686
|
+
// every `sendEmail` at send time (overriding the template's own category), so
|
|
687
|
+
// a typo/channel/consent-flip here is exactly as dangerous as on a template.
|
|
688
|
+
// Bucket-reaction journeys never carry a `category`, so `opts.journeys` is the
|
|
689
|
+
// complete set to check. Placed right beside the template loop.
|
|
690
|
+
for (const journey of opts.journeys ?? []) {
|
|
691
|
+
const category = journey.meta.category;
|
|
692
|
+
if (!category) continue;
|
|
693
|
+
validateListCategory({
|
|
694
|
+
owner: `Journey "${journey.meta.id}"`,
|
|
695
|
+
category,
|
|
696
|
+
listRegistry,
|
|
697
|
+
definedLists,
|
|
698
|
+
logger,
|
|
699
|
+
});
|
|
618
700
|
}
|
|
619
701
|
|
|
620
702
|
const emailService =
|
|
@@ -162,8 +162,14 @@ export const posthogDestination = defineDestination({
|
|
|
162
162
|
userId?: string | null;
|
|
163
163
|
to?: string | null;
|
|
164
164
|
userEmail?: string | null;
|
|
165
|
+
anonymousId?: string | null;
|
|
165
166
|
};
|
|
166
|
-
|
|
167
|
+
// `anonymousId` covers anon-tier arrivals (`link.arrived`): a raw browser
|
|
168
|
+
// anon id IS a legitimate PostHog distinct_id, and without it the capture
|
|
169
|
+
// would ship no distinct_id at all — PostHog 400s and the delivery
|
|
170
|
+
// dead-letters (<500 = non-retryable).
|
|
171
|
+
const distinctId =
|
|
172
|
+
data.userId ?? data.anonymousId ?? data.to ?? data.userEmail ?? undefined;
|
|
167
173
|
// `email.action` is the semantic-link envelope: the CONSUMER's event name
|
|
168
174
|
// (data.event, e.g. "nps.submitted") is what PostHog should capture, with
|
|
169
175
|
// the author's properties flattened to the top level. Other catalog events
|