@hogsend/engine 0.40.0 → 0.42.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +11 -8
- package/src/buckets/check-membership.ts +6 -1
- package/src/campaigns/cohort-sql.ts +198 -0
- package/src/campaigns/define-campaign.ts +207 -28
- package/src/campaigns/reconcile.ts +105 -11
- package/src/campaigns/steps.ts +48 -0
- package/src/connectors/define-action.ts +70 -0
- package/src/container.ts +124 -42
- package/src/destinations/presets/posthog.ts +7 -1
- package/src/index.ts +96 -2
- package/src/journeys/constants.ts +10 -0
- package/src/journeys/define-journey.ts +14 -405
- package/src/journeys/execute-journey-run.ts +641 -0
- package/src/journeys/graph/build-graph.ts +212 -56
- package/src/journeys/journey-boundary.ts +54 -0
- package/src/journeys/journey-context.ts +406 -59
- package/src/journeys/record-once.ts +110 -0
- package/src/lib/blueprint-lock.ts +21 -0
- package/src/lib/blueprints.ts +803 -0
- package/src/lib/campaign-send-key.ts +58 -0
- package/src/lib/connector-actions.ts +203 -19
- package/src/lib/contacts.ts +54 -0
- package/src/lib/email-service-types.ts +4 -1
- package/src/lib/email.ts +13 -2
- package/src/lib/event-names.ts +143 -0
- package/src/lib/feed.ts +77 -57
- package/src/lib/frequency-cap.ts +45 -15
- package/src/lib/hatchet-duration.ts +22 -0
- package/src/lib/html.ts +1 -0
- package/src/lib/ingestion.ts +145 -4
- package/src/lib/journey-suppress.ts +87 -0
- package/src/lib/links.ts +204 -18
- package/src/lib/outbound.ts +20 -0
- package/src/lib/preferences.ts +80 -1
- package/src/lib/tracked.ts +44 -29
- package/src/lib/tracking-event-names.ts +8 -0
- package/src/lib/tracking.ts +1 -5
- package/src/lib/webhook-signing.ts +6 -1
- package/src/lists/channels.ts +75 -0
- package/src/lists/define-list.ts +34 -0
- package/src/lists/registry.ts +29 -2
- package/src/mcp/authoring-guide.ts +160 -0
- package/src/mcp/blueprint-tools.ts +390 -0
- package/src/middleware/require-admin.ts +13 -0
- package/src/routes/admin/api-keys.ts +72 -0
- package/src/routes/admin/blueprints.ts +795 -0
- package/src/routes/admin/campaigns.ts +179 -3
- package/src/routes/admin/emails.ts +13 -0
- package/src/routes/admin/events.ts +55 -0
- package/src/routes/admin/index.ts +4 -0
- package/src/routes/admin/journeys.ts +4 -2
- package/src/routes/admin/links.ts +303 -36
- package/src/routes/admin/lists.ts +51 -0
- package/src/routes/campaigns/index.ts +44 -6
- package/src/routes/email/preferences.ts +50 -13
- package/src/routes/feed/recipient.ts +2 -43
- package/src/routes/index.ts +6 -0
- package/src/routes/lists/index.ts +138 -18
- package/src/routes/tracking/arrive.ts +260 -0
- package/src/routes/tracking/click-pipeline.ts +329 -0
- package/src/routes/tracking/click.ts +5 -270
- package/src/routes/tracking/index.ts +2 -0
- package/src/routes/tracking/vanity.ts +64 -0
- package/src/worker.ts +5 -0
- package/src/workflows/bucket-backfill.ts +4 -2
- package/src/workflows/bucket-reconcile.ts +11 -4
- package/src/workflows/check-alerts.ts +130 -1
- package/src/workflows/journey-blueprint-interpreter.ts +656 -0
- package/src/workflows/send-campaign.ts +574 -180
package/src/lib/links.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { randomUUID } from "node:crypto";
|
|
2
2
|
import { type Database, links, trackedLinks } from "@hogsend/db";
|
|
3
|
+
import { and, eq, isNull, ne, or, sql } from "drizzle-orm";
|
|
3
4
|
|
|
4
5
|
/**
|
|
5
6
|
* The channel-agnostic MANAGED tracked-link mint — the counterpart to the email
|
|
@@ -31,6 +32,11 @@ export interface MintLinkOptions {
|
|
|
31
32
|
type?: LinkType;
|
|
32
33
|
/** Operator-facing name (Studio list). */
|
|
33
34
|
label?: string;
|
|
35
|
+
/**
|
|
36
|
+
* Longer operator note — what/where this link or its printed QR actually is
|
|
37
|
+
* ("sticker on the workshop door"), for telling codes apart in bulk.
|
|
38
|
+
*/
|
|
39
|
+
description?: string;
|
|
34
40
|
/** UTM-style campaign grouping (public links). */
|
|
35
41
|
campaign?: string;
|
|
36
42
|
/**
|
|
@@ -40,6 +46,19 @@ export interface MintLinkOptions {
|
|
|
40
46
|
distinctId?: string;
|
|
41
47
|
/** The admin actor who minted it (Studio). */
|
|
42
48
|
createdBy?: string;
|
|
49
|
+
/**
|
|
50
|
+
* Optional vanity slug — the `/l/:slug` short path layered over the UUID
|
|
51
|
+
* redirect. Normalized lowercase; unique per instance (SlugTakenError on
|
|
52
|
+
* conflict). Managed links only — email's per-send links stay UUID.
|
|
53
|
+
*/
|
|
54
|
+
slug?: string;
|
|
55
|
+
/**
|
|
56
|
+
* Arrival attribution opt-in: append `hs_ref=<click id>` to every redirect
|
|
57
|
+
* from this link so the landing page can report the visitor back to
|
|
58
|
+
* `POST /v1/t/arrive`. Off by default — an appended param breaks strict
|
|
59
|
+
* OAuth redirect_uri destinations.
|
|
60
|
+
*/
|
|
61
|
+
appendRef?: boolean;
|
|
43
62
|
}
|
|
44
63
|
|
|
45
64
|
export interface MintedLink {
|
|
@@ -49,6 +68,157 @@ export interface MintedLink {
|
|
|
49
68
|
trackedLinkId: string;
|
|
50
69
|
/** The short redirect URL: `${baseUrl}/v1/t/c/:id`. */
|
|
51
70
|
url: string;
|
|
71
|
+
/** The normalized vanity slug, if one was minted. */
|
|
72
|
+
slug: string | null;
|
|
73
|
+
/** The vanity short URL (`${baseUrl}/l/:slug`), if a slug was minted. */
|
|
74
|
+
vanityUrl: string | null;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
// ---------------------------------------------------------------------------
|
|
78
|
+
// Vanity slugs
|
|
79
|
+
// ---------------------------------------------------------------------------
|
|
80
|
+
|
|
81
|
+
/** 1–64 chars of lowercase [a-z0-9-], no leading/trailing hyphen. */
|
|
82
|
+
const SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
|
|
83
|
+
|
|
84
|
+
/** Thrown when a requested slug is already held by another link → HTTP 409. */
|
|
85
|
+
export class SlugTakenError extends Error {
|
|
86
|
+
constructor(slug: string) {
|
|
87
|
+
super(`Slug "${slug}" is already taken`);
|
|
88
|
+
this.name = "SlugTakenError";
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* Lowercase-normalize + validate a requested vanity slug. Throws on an
|
|
94
|
+
* invalid shape (→ HTTP 400). Case-insensitivity comes from normalizing at
|
|
95
|
+
* every write — the DB unique index then only ever sees lowercase.
|
|
96
|
+
*/
|
|
97
|
+
export function normalizeSlug(raw: string): string {
|
|
98
|
+
const slug = raw.trim().toLowerCase();
|
|
99
|
+
if (!SLUG_RE.test(slug)) {
|
|
100
|
+
throw new Error(
|
|
101
|
+
`Invalid slug "${raw}": 1-64 lowercase letters/digits/hyphens, no leading/trailing hyphen`,
|
|
102
|
+
);
|
|
103
|
+
}
|
|
104
|
+
return slug;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* True when a DB error is the Postgres unique_violation on the slug index.
|
|
109
|
+
* Walks the cause chain — drizzle wraps the driver's PostgresError in a
|
|
110
|
+
* DrizzleQueryError whose `cause` carries the actual code/constraint.
|
|
111
|
+
*/
|
|
112
|
+
export function isSlugUniqueViolation(err: unknown): boolean {
|
|
113
|
+
for (let e = err, depth = 0; e && depth < 5; depth++) {
|
|
114
|
+
const candidate = e as {
|
|
115
|
+
code?: string;
|
|
116
|
+
constraint_name?: string;
|
|
117
|
+
message?: string;
|
|
118
|
+
cause?: unknown;
|
|
119
|
+
};
|
|
120
|
+
if (
|
|
121
|
+
candidate.code === "23505" &&
|
|
122
|
+
(candidate.constraint_name === "links_slug_unique" ||
|
|
123
|
+
(candidate.message?.includes("links_slug_unique") ?? false))
|
|
124
|
+
) {
|
|
125
|
+
return true;
|
|
126
|
+
}
|
|
127
|
+
e = candidate.cause;
|
|
128
|
+
}
|
|
129
|
+
return false;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
export function vanityUrlFor(baseUrl: string, slug: string): string {
|
|
133
|
+
return `${baseUrl}/l/${slug}`;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** The `tracked_links.source` marker of a link's per-link QR scan row. */
|
|
137
|
+
export const QR_TRACKED_SOURCE = "qr";
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* Lazily mint (or fetch) a managed link's QR scan row — the SECOND
|
|
141
|
+
* `tracked_links` row for the link, `source: "qr"`. The QR code encodes
|
|
142
|
+
* `/v1/t/c/<this row>` (the durable UID URL, never the slug), so scans are
|
|
143
|
+
* attributable separately from link clicks while a PATCH re-target (which
|
|
144
|
+
* updates every tracked row scoped by `link_id`) keeps a printed code
|
|
145
|
+
* pointing at the current destination.
|
|
146
|
+
*
|
|
147
|
+
* Race-safe via the partial unique index `tracked_links(link_id) WHERE
|
|
148
|
+
* source = 'qr'`: a concurrent double-mint loses the insert cleanly and
|
|
149
|
+
* re-reads the winner's row. Returns null when the link doesn't exist.
|
|
150
|
+
*/
|
|
151
|
+
export async function ensureQrTrackedLink(opts: {
|
|
152
|
+
db: Database;
|
|
153
|
+
linkId: string;
|
|
154
|
+
}): Promise<{ trackedLinkId: string; created: boolean } | null> {
|
|
155
|
+
const { db, linkId } = opts;
|
|
156
|
+
|
|
157
|
+
const qrRowFilter = and(
|
|
158
|
+
eq(trackedLinks.linkId, linkId),
|
|
159
|
+
eq(trackedLinks.source, QR_TRACKED_SOURCE),
|
|
160
|
+
);
|
|
161
|
+
|
|
162
|
+
const [existing] = await db
|
|
163
|
+
.select({ id: trackedLinks.id })
|
|
164
|
+
.from(trackedLinks)
|
|
165
|
+
.where(qrRowFilter)
|
|
166
|
+
.limit(1);
|
|
167
|
+
if (existing) return { trackedLinkId: existing.id, created: false };
|
|
168
|
+
|
|
169
|
+
const [link] = await db
|
|
170
|
+
.select({
|
|
171
|
+
originalUrl: links.originalUrl,
|
|
172
|
+
distinctId: links.distinctId,
|
|
173
|
+
})
|
|
174
|
+
.from(links)
|
|
175
|
+
.where(eq(links.id, linkId))
|
|
176
|
+
.limit(1);
|
|
177
|
+
if (!link) return null;
|
|
178
|
+
|
|
179
|
+
// distinctId copied from the link so a PERSONAL link's scans stitch the same
|
|
180
|
+
// subject as its clicks; public links stay identity-free (NULL).
|
|
181
|
+
const [inserted] = await db
|
|
182
|
+
.insert(trackedLinks)
|
|
183
|
+
.values({
|
|
184
|
+
id: randomUUID(),
|
|
185
|
+
linkId,
|
|
186
|
+
emailSendId: null,
|
|
187
|
+
distinctId: link.distinctId,
|
|
188
|
+
source: QR_TRACKED_SOURCE,
|
|
189
|
+
originalUrl: link.originalUrl,
|
|
190
|
+
})
|
|
191
|
+
.onConflictDoNothing({
|
|
192
|
+
target: [trackedLinks.linkId],
|
|
193
|
+
// The arbiter predicate matching the partial unique index
|
|
194
|
+
// `tracked_links_qr_per_link_unique` (… WHERE source = 'qr').
|
|
195
|
+
where: sql`${trackedLinks.source} = ${QR_TRACKED_SOURCE}`,
|
|
196
|
+
})
|
|
197
|
+
.returning({ id: trackedLinks.id });
|
|
198
|
+
|
|
199
|
+
if (inserted) return { trackedLinkId: inserted.id, created: true };
|
|
200
|
+
|
|
201
|
+
// Lost the race — the concurrent mint's row is the QR row.
|
|
202
|
+
const [winner] = await db
|
|
203
|
+
.select({ id: trackedLinks.id })
|
|
204
|
+
.from(trackedLinks)
|
|
205
|
+
.where(qrRowFilter)
|
|
206
|
+
.limit(1);
|
|
207
|
+
return winner ? { trackedLinkId: winner.id, created: false } : null;
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/**
|
|
211
|
+
* SQL predicate selecting a link's CANONICAL tracked row — the redirect row
|
|
212
|
+
* minted alongside the link, as opposed to the lazily-minted per-link QR scan
|
|
213
|
+
* row (`source = 'qr'`). The ONE definition of "which tracked row is the
|
|
214
|
+
* link's redirect row"; every consumer (vanity resolver, admin aggregates)
|
|
215
|
+
* must use it rather than re-deriving QR-awareness.
|
|
216
|
+
*/
|
|
217
|
+
export function canonicalTrackedRowFilter() {
|
|
218
|
+
return or(
|
|
219
|
+
isNull(trackedLinks.source),
|
|
220
|
+
ne(trackedLinks.source, QR_TRACKED_SOURCE),
|
|
221
|
+
);
|
|
52
222
|
}
|
|
53
223
|
|
|
54
224
|
/**
|
|
@@ -75,32 +245,48 @@ export async function mintLink(opts: MintLinkOptions): Promise<MintedLink> {
|
|
|
75
245
|
const type: LinkType = opts.type ?? "public";
|
|
76
246
|
// A public link must NEVER carry a person token — drop any distinctId.
|
|
77
247
|
const distinctId = type === "personal" ? (opts.distinctId ?? null) : null;
|
|
248
|
+
const slug = opts.slug !== undefined ? normalizeSlug(opts.slug) : null;
|
|
78
249
|
|
|
79
250
|
const linkId = randomUUID();
|
|
80
251
|
const trackedLinkId = randomUUID();
|
|
81
252
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
253
|
+
// ONE transaction: a half-failed mint would otherwise strand a `links` row
|
|
254
|
+
// that reserves a globally-unique slug with no tracked row — `/l/<slug>`
|
|
255
|
+
// dead (inner join misses) yet the slug 409s every re-mint.
|
|
256
|
+
try {
|
|
257
|
+
await opts.db.transaction(async (tx) => {
|
|
258
|
+
await tx.insert(links).values({
|
|
259
|
+
id: linkId,
|
|
260
|
+
originalUrl: opts.url,
|
|
261
|
+
type,
|
|
262
|
+
slug,
|
|
263
|
+
label: opts.label ?? null,
|
|
264
|
+
description: opts.description ?? null,
|
|
265
|
+
appendRef: opts.appendRef ?? false,
|
|
266
|
+
campaign: opts.campaign ?? null,
|
|
267
|
+
source: opts.source,
|
|
268
|
+
distinctId,
|
|
269
|
+
createdBy: opts.createdBy ?? null,
|
|
270
|
+
});
|
|
271
|
+
await tx.insert(trackedLinks).values({
|
|
272
|
+
id: trackedLinkId,
|
|
273
|
+
linkId,
|
|
274
|
+
emailSendId: null,
|
|
275
|
+
distinctId,
|
|
276
|
+
source: opts.source,
|
|
277
|
+
originalUrl: opts.url,
|
|
278
|
+
});
|
|
279
|
+
});
|
|
280
|
+
} catch (err) {
|
|
281
|
+
if (slug && isSlugUniqueViolation(err)) throw new SlugTakenError(slug);
|
|
282
|
+
throw err;
|
|
283
|
+
}
|
|
100
284
|
|
|
101
285
|
return {
|
|
102
286
|
linkId,
|
|
103
287
|
trackedLinkId,
|
|
104
288
|
url: `${opts.baseUrl}/v1/t/c/${trackedLinkId}`,
|
|
289
|
+
slug,
|
|
290
|
+
vanityUrl: slug ? vanityUrlFor(opts.baseUrl, slug) : null,
|
|
105
291
|
};
|
|
106
292
|
}
|
package/src/lib/outbound.ts
CHANGED
|
@@ -107,6 +107,26 @@ export interface OutboundPayloads {
|
|
|
107
107
|
linkUrl: string;
|
|
108
108
|
at: string;
|
|
109
109
|
};
|
|
110
|
+
/**
|
|
111
|
+
* A visitor CONFIRMED landing from a tracked hit (opt-in `hs_ref` +
|
|
112
|
+
* POST /v1/t/arrive). Subset of `link.clicked` — fires only when the link
|
|
113
|
+
* opts in AND the landing page reports back. Unlike `link.clicked`, `linkId`
|
|
114
|
+
* here is the MANAGED `links.id` (`trackedLinkId` rides separately — no
|
|
115
|
+
* legacy split), and the identity fields are the VISITOR's: `userId` only
|
|
116
|
+
* when token-verified, `anonymousId` for a clamped anon arrival.
|
|
117
|
+
*/
|
|
118
|
+
"link.arrived": {
|
|
119
|
+
linkId: string;
|
|
120
|
+
trackedLinkId: string;
|
|
121
|
+
ref: string;
|
|
122
|
+
source: string | null;
|
|
123
|
+
campaign: string | null;
|
|
124
|
+
userId: string | null;
|
|
125
|
+
anonymousId: string | null;
|
|
126
|
+
visitorKind: "token" | "anon";
|
|
127
|
+
linkUrl: string | null;
|
|
128
|
+
at: string;
|
|
129
|
+
};
|
|
110
130
|
/**
|
|
111
131
|
* A SEMANTIC link answered — the in-email action event (consumer-named, e.g.
|
|
112
132
|
* "nps.submitted"). Emitted at most once per (send, event name): first
|
package/src/lib/preferences.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { Database } from "@hogsend/db";
|
|
2
2
|
import { emailPreferences } from "@hogsend/db";
|
|
3
|
-
import { sql } from "drizzle-orm";
|
|
3
|
+
import { eq, or, sql } from "drizzle-orm";
|
|
4
4
|
import { resolveRecipient } from "./contacts.js";
|
|
5
5
|
import { hatchet } from "./hatchet.js";
|
|
6
6
|
import { createLogger } from "./logger.js";
|
|
@@ -121,6 +121,85 @@ export async function upsertEmailPreference(opts: {
|
|
|
121
121
|
}
|
|
122
122
|
}
|
|
123
123
|
|
|
124
|
+
/**
|
|
125
|
+
* Aggregated preference verdict for a recipient, folded across EVERY matching
|
|
126
|
+
* `email_preferences` row. See {@link readRecipientPreferences}.
|
|
127
|
+
*/
|
|
128
|
+
export interface RecipientPreferences {
|
|
129
|
+
/** true when ANY matching row has unsubscribed_all (global master opt-out). */
|
|
130
|
+
unsubscribedAll: boolean;
|
|
131
|
+
/**
|
|
132
|
+
* true when ANY matching row is suppressed (hard bounce / complaint).
|
|
133
|
+
* Email-transport-specific — channel checks must NOT consume this.
|
|
134
|
+
*/
|
|
135
|
+
suppressed: boolean;
|
|
136
|
+
/** Category map merged across ALL matching rows, explicit false winning. */
|
|
137
|
+
categories: Record<string, boolean>;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* The ONE aggregated preference READ shared by the email mailer (checkSuppression),
|
|
142
|
+
* the in-app feed, and connector-send gating. Selects EVERY `email_preferences`
|
|
143
|
+
* row matching the given identity keys and folds them into a single verdict.
|
|
144
|
+
*
|
|
145
|
+
* An address can legitimately have MORE THAN ONE row: the `(user_id, email)`
|
|
146
|
+
* composite PK means a suppression imported before the contact existed is keyed
|
|
147
|
+
* (email, email) while later interactive writes key (external_id, email). We
|
|
148
|
+
* aggregate across ALL matching rows — any suppression signal on ANY row must
|
|
149
|
+
* win — so an imported unsubscribe/bounce can never be shadowed by a newer clean
|
|
150
|
+
* row for the same address.
|
|
151
|
+
*
|
|
152
|
+
* Rows are selected `WHERE email = keys.email OR user_id = keys.userId`, each leg
|
|
153
|
+
* included ONLY when its key is a non-empty string. With NEITHER key provided we
|
|
154
|
+
* do NOT query and return the empty/clean default.
|
|
155
|
+
*
|
|
156
|
+
* Category maps are merged with explicit FALSE winning: `categories[key] =
|
|
157
|
+
* (categories[key] ?? true) && value` over every row's map — an opt-out recorded
|
|
158
|
+
* on any row blocks, matching the conservative aggregation above. (In the common
|
|
159
|
+
* single-row case this is identical to reading the row's map directly.)
|
|
160
|
+
*/
|
|
161
|
+
export async function readRecipientPreferences(
|
|
162
|
+
db: Database,
|
|
163
|
+
keys: { email?: string | null; userId?: string | null },
|
|
164
|
+
): Promise<RecipientPreferences> {
|
|
165
|
+
// Build the OR legs conditionally — an empty/absent key contributes NO leg, so
|
|
166
|
+
// a `{ email }`-only read never matches every `user_id = ''` row and vice versa.
|
|
167
|
+
const legs = [];
|
|
168
|
+
if (typeof keys.email === "string" && keys.email.length > 0) {
|
|
169
|
+
legs.push(eq(emailPreferences.email, keys.email));
|
|
170
|
+
}
|
|
171
|
+
if (typeof keys.userId === "string" && keys.userId.length > 0) {
|
|
172
|
+
legs.push(eq(emailPreferences.userId, keys.userId));
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
// Neither key: do NOT query — a bare `.where()`/`or()` with no legs would match
|
|
176
|
+
// the whole table. Return the clean default instead.
|
|
177
|
+
if (legs.length === 0) {
|
|
178
|
+
return { unsubscribedAll: false, suppressed: false, categories: {} };
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
const rows = await db
|
|
182
|
+
.select()
|
|
183
|
+
.from(emailPreferences)
|
|
184
|
+
.where(or(...legs));
|
|
185
|
+
|
|
186
|
+
// Merge category maps across rows with explicit FALSE winning (see JSDoc). This
|
|
187
|
+
// always runs — an absent/empty map contributes nothing, so the result is `{}`.
|
|
188
|
+
const categories: Record<string, boolean> = {};
|
|
189
|
+
for (const prefs of rows) {
|
|
190
|
+
const map = (prefs.categories ?? {}) as Record<string, boolean>;
|
|
191
|
+
for (const [key, value] of Object.entries(map)) {
|
|
192
|
+
categories[key] = (categories[key] ?? true) && value;
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
return {
|
|
197
|
+
unsubscribedAll: rows.some((r) => r.unsubscribedAll),
|
|
198
|
+
suppressed: rows.some((r) => r.suppressed),
|
|
199
|
+
categories,
|
|
200
|
+
};
|
|
201
|
+
}
|
|
202
|
+
|
|
124
203
|
/**
|
|
125
204
|
* D3 list-membership write. Resolves the caller's identity to the deterministic
|
|
126
205
|
* `(externalId | contactId fallback, email)` pair via `resolveRecipient`, then
|
package/src/lib/tracked.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { EmailProvider } from "@hogsend/core";
|
|
2
2
|
import type { Database } from "@hogsend/db";
|
|
3
|
-
import {
|
|
3
|
+
import { emailSends } from "@hogsend/db";
|
|
4
4
|
import type {
|
|
5
5
|
EmailSuppressionError,
|
|
6
6
|
RetryOptions,
|
|
@@ -30,8 +30,10 @@ import {
|
|
|
30
30
|
} from "./email-service-types.js";
|
|
31
31
|
import { isFrequencyCapped } from "./frequency-cap.js";
|
|
32
32
|
import { hatchet } from "./hatchet.js";
|
|
33
|
+
import { checkJourneySuppress } from "./journey-suppress.js";
|
|
33
34
|
import { createLogger, type Logger } from "./logger.js";
|
|
34
35
|
import { emitOutbound } from "./outbound.js";
|
|
36
|
+
import { readRecipientPreferences } from "./preferences.js";
|
|
35
37
|
import {
|
|
36
38
|
buildRedirect,
|
|
37
39
|
isUnaddressable,
|
|
@@ -257,6 +259,38 @@ async function sendTrackedEmailInner<K extends TemplateName>(
|
|
|
257
259
|
});
|
|
258
260
|
}
|
|
259
261
|
}
|
|
262
|
+
|
|
263
|
+
// Journey suppress (`meta.suppress`) — a per-recipient min-gap flooding
|
|
264
|
+
// guard, enforced ONLY for journey-bound sends (a JourneyBoundary is
|
|
265
|
+
// present) whose journey sets suppress > 0. Slotted ADJACENT to the
|
|
266
|
+
// frequency cap so the skip mirrors it exactly: on a hit there is no
|
|
267
|
+
// provider call, no `email_sends` row, and no throw — the journey run
|
|
268
|
+
// continues. It MUST run AFTER the idempotency short-circuit above: a replay
|
|
269
|
+
// of an already-dispatched send has to return that dup (from its prior
|
|
270
|
+
// `sent` row) BEFORE any suppress evaluation, or the second drive would
|
|
271
|
+
// wrongly re-evaluate suppression for a send that already went out. The
|
|
272
|
+
// verdict itself is RECORDED set-once (see checkJourneySuppress) so it is
|
|
273
|
+
// replay-stable. Non-journey sends (no boundary: transactional API /
|
|
274
|
+
// password-reset flows) are inert here.
|
|
275
|
+
const boundary = getJourneyBoundary();
|
|
276
|
+
const suppress = await checkJourneySuppress({
|
|
277
|
+
db,
|
|
278
|
+
boundary,
|
|
279
|
+
to: options.to,
|
|
280
|
+
idempotencyKey: options.idempotencyKey,
|
|
281
|
+
});
|
|
282
|
+
if (suppress.suppressed) {
|
|
283
|
+
logger?.info("send skipped: journey_suppressed", {
|
|
284
|
+
to: options.to,
|
|
285
|
+
journeyId: boundary?.journeyId,
|
|
286
|
+
});
|
|
287
|
+
return trackedSendResult({
|
|
288
|
+
emailSendId: "",
|
|
289
|
+
messageId: "",
|
|
290
|
+
status: "skipped",
|
|
291
|
+
reason: "journey_suppressed",
|
|
292
|
+
});
|
|
293
|
+
}
|
|
260
294
|
}
|
|
261
295
|
|
|
262
296
|
// Unsubscribe surface (RFC 8058 / CAN-SPAM): generate the per-recipient
|
|
@@ -553,19 +587,13 @@ async function checkSuppression(
|
|
|
553
587
|
email: string,
|
|
554
588
|
category?: string,
|
|
555
589
|
): Promise<SuppressionReason> {
|
|
556
|
-
//
|
|
557
|
-
//
|
|
558
|
-
//
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
.select()
|
|
564
|
-
.from(emailPreferences)
|
|
565
|
-
.where(eq(emailPreferences.email, email));
|
|
566
|
-
|
|
567
|
-
if (rows.some((prefs) => prefs.suppressed)) return "suppressed";
|
|
568
|
-
if (rows.some((prefs) => prefs.unsubscribedAll)) return "unsubscribed";
|
|
590
|
+
// Aggregated across ALL `email_preferences` rows for this address by the shared
|
|
591
|
+
// reader — an address can legitimately have MORE THAN ONE row (multi-row
|
|
592
|
+
// (user_id, email) aggregation rationale lives in readRecipientPreferences).
|
|
593
|
+
const prefs = await readRecipientPreferences(db, { email });
|
|
594
|
+
|
|
595
|
+
if (prefs.suppressed) return "suppressed";
|
|
596
|
+
if (prefs.unsubscribedAll) return "unsubscribed";
|
|
569
597
|
|
|
570
598
|
// Registry-aware polarity (§2.6, D3) — applied through the SINGLE source of
|
|
571
599
|
// truth `ListRegistry.isSubscribed` so it matches the preference center EXACTLY
|
|
@@ -575,21 +603,8 @@ async function checkSuppression(
|
|
|
575
603
|
// so absence-of-true (the common "never opted in" case) MUST block — otherwise
|
|
576
604
|
// a contact the preference center shows as "Unsubscribed" would still receive
|
|
577
605
|
// the mail (the two surfaces would disagree, which §2.6 forbids).
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
// above. (In the common single-row case this is identical to reading the
|
|
581
|
-
// row's map directly.)
|
|
582
|
-
if (category) {
|
|
583
|
-
const categories: Record<string, boolean> = {};
|
|
584
|
-
for (const prefs of rows) {
|
|
585
|
-
const map = (prefs.categories ?? {}) as Record<string, boolean>;
|
|
586
|
-
for (const [key, value] of Object.entries(map)) {
|
|
587
|
-
categories[key] = (categories[key] ?? true) && value;
|
|
588
|
-
}
|
|
589
|
-
}
|
|
590
|
-
if (!getListRegistry().isSubscribed(categories, category)) {
|
|
591
|
-
return "category_unsubscribed";
|
|
592
|
-
}
|
|
606
|
+
if (category && !getListRegistry().isSubscribed(prefs.categories, category)) {
|
|
607
|
+
return "category_unsubscribed";
|
|
593
608
|
}
|
|
594
609
|
|
|
595
610
|
return null;
|
|
@@ -12,3 +12,11 @@ export const EMAIL_LINK_CLICKED = "email.link_clicked" as const;
|
|
|
12
12
|
// raw mint distinctId; the BUS event carries the MANAGED `links.id` as `linkId`
|
|
13
13
|
// + the RESOLVED survivor contact key (see `pushLinkClickEvent`).
|
|
14
14
|
export const LINK_CLICKED = "link.clicked" as const;
|
|
15
|
+
|
|
16
|
+
// A visitor CONFIRMED landing from a tracked hit (POST /v1/t/arrive, opt-in
|
|
17
|
+
// `hs_ref`). Subset of `link.clicked`: fires only when the link opts in AND
|
|
18
|
+
// the landing page integrates. Unlike `link.clicked`, it carries the VISITOR's
|
|
19
|
+
// identity (token-verified userId or clamped anon id) — which is what answers
|
|
20
|
+
// "did a known user scan this QR?". Bus + outbound both define `linkId` as the
|
|
21
|
+
// managed `links.id` and carry `trackedLinkId` separately (no legacy split).
|
|
22
|
+
export const LINK_ARRIVED = "link.arrived" as const;
|
package/src/lib/tracking.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { randomUUID } from "node:crypto";
|
|
2
|
+
import { RESERVED_EVENT_NAME_RE } from "@hogsend/core";
|
|
2
3
|
import type { Database } from "@hogsend/db";
|
|
3
4
|
import { trackedLinks } from "@hogsend/db";
|
|
4
5
|
import {
|
|
@@ -25,11 +26,6 @@ const STRIP_SEMANTIC_ATTRS_RE = new RegExp(
|
|
|
25
26
|
|
|
26
27
|
const SKIP_PATTERNS = ["/v1/email/unsubscribe", "/v1/email/preferences"];
|
|
27
28
|
|
|
28
|
-
// Engine-owned event vocabularies (both `email.opened` dot-style and
|
|
29
|
-
// `journey:completed` colon-style exist) — a consumer semantic event in these
|
|
30
|
-
// namespaces would corrupt insights or trigger engine-internal logic.
|
|
31
|
-
const RESERVED_EVENT_NAME_RE = /^(?:email|journey|bucket|contact)[.:]/;
|
|
32
|
-
|
|
33
29
|
// Semantic payloads re-emit on every answer and persist indefinitely — keep
|
|
34
30
|
// them small and scalar (non-scalars don't survive the Hatchet wire anyway).
|
|
35
31
|
const MAX_PROPS_JSON_LENGTH = 2048;
|
|
@@ -25,7 +25,7 @@ import { Webhook } from "svix";
|
|
|
25
25
|
*/
|
|
26
26
|
|
|
27
27
|
/**
|
|
28
|
-
* The
|
|
28
|
+
* The 16-event catalog — the SINGLE source of truth (schema, routes, client,
|
|
29
29
|
* CLI all derive from this). The `webhook.test` sentinel is intentionally NOT a
|
|
30
30
|
* member (it is delivered out-of-band regardless of an endpoint's `eventTypes`).
|
|
31
31
|
*
|
|
@@ -33,6 +33,10 @@ import { Webhook } from "svix";
|
|
|
33
33
|
* has no email send (Discord/referral/ad-hoc `createTrackedLink`). It is the
|
|
34
34
|
* deliberate counterpart to `email.clicked` so a non-email click never fires a
|
|
35
35
|
* malformed `email.clicked` (MF-missing #3).
|
|
36
|
+
*
|
|
37
|
+
* `link.arrived` is the landing-confirmed subset of `link.clicked`: the
|
|
38
|
+
* visitor reported back from the destination (opt-in `hs_ref` +
|
|
39
|
+
* POST /v1/t/arrive) with identity evidence.
|
|
36
40
|
*/
|
|
37
41
|
export const WEBHOOK_EVENT_TYPES = [
|
|
38
42
|
"contact.created",
|
|
@@ -50,6 +54,7 @@ export const WEBHOOK_EVENT_TYPES = [
|
|
|
50
54
|
"bucket.entered",
|
|
51
55
|
"bucket.left",
|
|
52
56
|
"link.clicked",
|
|
57
|
+
"link.arrived",
|
|
53
58
|
] as const;
|
|
54
59
|
|
|
55
60
|
export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Channel lists — engine-synthesized delivery channels layered on the SAME
|
|
3
|
+
* `email_preferences.categories` JSONB namespace as author-defined lists (D3).
|
|
4
|
+
* A channel is an auto-registered opt-out list: `in_app` (the notification
|
|
5
|
+
* feed) plus one per connector that exposes member-directed actions (discord,
|
|
6
|
+
* telegram). There is no new table and no authoring surface — channels are
|
|
7
|
+
* derived from the registered connector actions at container build time.
|
|
8
|
+
*
|
|
9
|
+
* POLARITY (zero behaviour flip): every channel is `defaultOptIn: true`, so
|
|
10
|
+
* `ListRegistry.isSubscribed(categories, id)` returns `categories[id] !== false`
|
|
11
|
+
* — subscribed unless the recipient explicitly set the category to `false`.
|
|
12
|
+
* That is EXACTLY the unknown-id fallback an UNregistered channel already
|
|
13
|
+
* resolved to (`isSubscribedByDefault` → `?? true`), so registering these lists
|
|
14
|
+
* flips zero existing behaviour; it only makes the channels visible in the
|
|
15
|
+
* catalog and (in a later phase) enforceable in `sendConnectorAction`.
|
|
16
|
+
*/
|
|
17
|
+
import type { DefinedConnectorAction } from "../connectors/define-action.js";
|
|
18
|
+
import type { ListMeta } from "./define-list.js";
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Reserved list id for the engine's in-app channel (the notification feed).
|
|
22
|
+
* Always synthesized first by {@link synthesizeChannelLists}; also the
|
|
23
|
+
* suppression key consulted by `sendFeedItem`.
|
|
24
|
+
*/
|
|
25
|
+
export const IN_APP_LIST_ID = "in_app";
|
|
26
|
+
|
|
27
|
+
/** Uppercase the first character of a connector id for the channel's display name. */
|
|
28
|
+
function capitalize(id: string): string {
|
|
29
|
+
return id.length === 0 ? id : id.charAt(0).toUpperCase() + id.slice(1);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Synthesize the engine-owned channel {@link ListMeta}s from the registered
|
|
34
|
+
* connector actions.
|
|
35
|
+
*
|
|
36
|
+
* Always yields the `in_app` channel first. Then one channel per DISTINCT
|
|
37
|
+
* `connectorId` among actions declaring a member audience
|
|
38
|
+
* (`action.audience?.kind === "member"`), de-duplicated via a `Set` in stable
|
|
39
|
+
* first-appearance order. Actions WITHOUT a member audience (ops/channel-
|
|
40
|
+
* directed) never mint a channel. Channel display name = the connector id with
|
|
41
|
+
* its first letter capitalized ("discord" → "Discord").
|
|
42
|
+
*
|
|
43
|
+
* Every channel shares the opt-out polarity shape `{ defaultOptIn: true,
|
|
44
|
+
* enabled: true, kind: "channel" }` — see the module docblock for why this
|
|
45
|
+
* flips no existing behaviour.
|
|
46
|
+
*/
|
|
47
|
+
export function synthesizeChannelLists(
|
|
48
|
+
actions: DefinedConnectorAction[],
|
|
49
|
+
): ListMeta[] {
|
|
50
|
+
const channels: ListMeta[] = [
|
|
51
|
+
{
|
|
52
|
+
id: IN_APP_LIST_ID,
|
|
53
|
+
name: "In-app feed",
|
|
54
|
+
defaultOptIn: true,
|
|
55
|
+
enabled: true,
|
|
56
|
+
kind: "channel",
|
|
57
|
+
},
|
|
58
|
+
];
|
|
59
|
+
|
|
60
|
+
const seen = new Set<string>();
|
|
61
|
+
for (const action of actions) {
|
|
62
|
+
if (action.audience?.kind !== "member") continue;
|
|
63
|
+
if (seen.has(action.connectorId)) continue;
|
|
64
|
+
seen.add(action.connectorId);
|
|
65
|
+
channels.push({
|
|
66
|
+
id: action.connectorId,
|
|
67
|
+
name: capitalize(action.connectorId),
|
|
68
|
+
defaultOptIn: true,
|
|
69
|
+
enabled: true,
|
|
70
|
+
kind: "channel",
|
|
71
|
+
});
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
return channels;
|
|
75
|
+
}
|