@hogsend/engine 0.40.0 → 0.41.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 +9 -7
- 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 +82 -2
- package/src/journeys/constants.ts +10 -0
- package/src/journeys/define-journey.ts +14 -405
- package/src/journeys/execute-journey-run.ts +608 -0
- package/src/journeys/graph/build-graph.ts +212 -56
- package/src/journeys/journey-boundary.ts +54 -0
- package/src/journeys/journey-context.ts +374 -59
- package/src/journeys/record-once.ts +110 -0
- package/src/lib/blueprints.ts +576 -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/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/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/blueprint-tools.ts +460 -0
- package/src/routes/admin/blueprints.ts +711 -0
- package/src/routes/admin/campaigns.ts +179 -3
- package/src/routes/admin/emails.ts +13 -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 +561 -0
- package/src/workflows/send-campaign.ts +574 -180
package/src/lib/html.ts
CHANGED
|
@@ -12,6 +12,7 @@ export function htmlPage(opts: { title: string; body: string }): string {
|
|
|
12
12
|
p { color: #555; line-height: 1.6; }
|
|
13
13
|
a { color: #2563eb; text-decoration: none; }
|
|
14
14
|
a:hover { text-decoration: underline; }
|
|
15
|
+
.pref-section { font-size: 0.75rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.06em; color: #6b7280; margin: 28px 0 4px; }
|
|
15
16
|
.pref-row { display: flex; justify-content: space-between; align-items: center; padding: 12px 0; border-bottom: 1px solid #e5e7eb; }
|
|
16
17
|
.pref-label { font-weight: 500; }
|
|
17
18
|
.pref-status { font-size: 0.875rem; }
|
package/src/lib/ingestion.ts
CHANGED
|
@@ -2,12 +2,20 @@ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
|
|
|
2
2
|
import type {
|
|
3
3
|
AnalyticsEventMirrorConfig,
|
|
4
4
|
AnalyticsProvider,
|
|
5
|
+
PropertyCondition,
|
|
5
6
|
} from "@hogsend/core";
|
|
6
7
|
import { evaluatePropertyConditions } from "@hogsend/core";
|
|
7
8
|
import type { JourneyRegistry } from "@hogsend/core/registry";
|
|
8
|
-
import
|
|
9
|
+
import type { JourneyMeta } from "@hogsend/core/types";
|
|
10
|
+
import {
|
|
11
|
+
type Database,
|
|
12
|
+
journeyBlueprints,
|
|
13
|
+
journeyStates,
|
|
14
|
+
userEvents,
|
|
15
|
+
} from "@hogsend/db";
|
|
9
16
|
import { and, eq, inArray, isNull } from "drizzle-orm";
|
|
10
17
|
import { checkBucketMembership } from "../buckets/check-membership.js";
|
|
18
|
+
import { BLUEPRINT_RUN_EVENT } from "../journeys/constants.js";
|
|
11
19
|
import { logTransition } from "../journeys/journey-log.js";
|
|
12
20
|
import {
|
|
13
21
|
logResidualTwins,
|
|
@@ -157,6 +165,80 @@ function shouldMirrorEvent(
|
|
|
157
165
|
return true;
|
|
158
166
|
}
|
|
159
167
|
|
|
168
|
+
/**
|
|
169
|
+
* Blueprint dispatch (spec §5) — the DB-lookup counterpart of the static
|
|
170
|
+
* `onEvents` registration code journeys get at boot. Code journeys can't gain
|
|
171
|
+
* a trigger without a worker redeploy; a blueprint row created at 3pm must
|
|
172
|
+
* fire at 3:01. So on every ingested event this queries the enabled
|
|
173
|
+
* `journey_blueprints` whose `triggerEvent` matches (served by the
|
|
174
|
+
* `(trigger_event, status)` index), applies `triggerWhere` with the SAME
|
|
175
|
+
* `evaluatePropertyConditions` the interpreter's enrollment guard re-checks
|
|
176
|
+
* with (dispatch and guard must agree, and both see the serializable-scalar
|
|
177
|
+
* payload), and pushes one `blueprint:run` per match to the single
|
|
178
|
+
* statically-registered `journey-blueprint-interpreter` task.
|
|
179
|
+
*
|
|
180
|
+
* Returns the number of dispatched enrollment attempts.
|
|
181
|
+
*/
|
|
182
|
+
export async function checkBlueprintTriggers(opts: {
|
|
183
|
+
db: Database;
|
|
184
|
+
hatchet: HatchetClient;
|
|
185
|
+
logger: Logger;
|
|
186
|
+
event: {
|
|
187
|
+
name: string;
|
|
188
|
+
userId: string;
|
|
189
|
+
userEmail: string;
|
|
190
|
+
/** The serializable-scalar subset that will reach the interpreter. */
|
|
191
|
+
properties: Record<string, string | number | boolean | null>;
|
|
192
|
+
};
|
|
193
|
+
}): Promise<number> {
|
|
194
|
+
const { db, hatchet, logger, event } = opts;
|
|
195
|
+
|
|
196
|
+
const candidates = await db
|
|
197
|
+
.select({
|
|
198
|
+
id: journeyBlueprints.id,
|
|
199
|
+
version: journeyBlueprints.version,
|
|
200
|
+
triggerWhere: journeyBlueprints.triggerWhere,
|
|
201
|
+
})
|
|
202
|
+
.from(journeyBlueprints)
|
|
203
|
+
.where(
|
|
204
|
+
and(
|
|
205
|
+
eq(journeyBlueprints.triggerEvent, event.name),
|
|
206
|
+
eq(journeyBlueprints.status, "enabled"),
|
|
207
|
+
),
|
|
208
|
+
);
|
|
209
|
+
|
|
210
|
+
let dispatched = 0;
|
|
211
|
+
for (const bp of candidates) {
|
|
212
|
+
const where = (bp.triggerWhere ?? []) as unknown as PropertyCondition[];
|
|
213
|
+
if (
|
|
214
|
+
where.length > 0 &&
|
|
215
|
+
!evaluatePropertyConditions({
|
|
216
|
+
conditions: where,
|
|
217
|
+
properties: event.properties,
|
|
218
|
+
})
|
|
219
|
+
) {
|
|
220
|
+
continue;
|
|
221
|
+
}
|
|
222
|
+
await hatchet.events.push(BLUEPRINT_RUN_EVENT, {
|
|
223
|
+
blueprintId: bp.id,
|
|
224
|
+
blueprintVersion: bp.version,
|
|
225
|
+
userId: event.userId,
|
|
226
|
+
userEmail: event.userEmail,
|
|
227
|
+
triggerProperties: event.properties,
|
|
228
|
+
});
|
|
229
|
+
dispatched += 1;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
if (dispatched > 0) {
|
|
233
|
+
logger.info("Blueprint runs dispatched", {
|
|
234
|
+
event: event.name,
|
|
235
|
+
userId: event.userId,
|
|
236
|
+
dispatched,
|
|
237
|
+
});
|
|
238
|
+
}
|
|
239
|
+
return dispatched;
|
|
240
|
+
}
|
|
241
|
+
|
|
160
242
|
export async function ingestEvent(opts: {
|
|
161
243
|
db: Database;
|
|
162
244
|
registry: JourneyRegistry;
|
|
@@ -402,6 +484,34 @@ export async function ingestEvent(opts: {
|
|
|
402
484
|
}
|
|
403
485
|
const exits = exitsResult.value;
|
|
404
486
|
|
|
487
|
+
// (5b) Blueprint dispatch (spec §5) — the DB-driven twin of the Hatchet
|
|
488
|
+
// push in (4): one `blueprint:run` per enabled matching blueprint. Runs
|
|
489
|
+
// AFTER the main push settled, so a dispatched blueprint never observes an
|
|
490
|
+
// event code journeys were not notified of. Best-effort by design: the
|
|
491
|
+
// event row + code-journey push are already committed, so throwing here
|
|
492
|
+
// could not be retried into a redelivery (the idempotency claim survives) —
|
|
493
|
+
// it would only fail the caller for work that half-happened. Mirrors the
|
|
494
|
+
// bucket-membership stance below.
|
|
495
|
+
try {
|
|
496
|
+
await checkBlueprintTriggers({
|
|
497
|
+
db,
|
|
498
|
+
hatchet,
|
|
499
|
+
logger,
|
|
500
|
+
event: {
|
|
501
|
+
name: event.event,
|
|
502
|
+
userId: resolvedKey,
|
|
503
|
+
userEmail: event.userEmail ?? "",
|
|
504
|
+
properties: serializableProperties,
|
|
505
|
+
},
|
|
506
|
+
});
|
|
507
|
+
} catch (err) {
|
|
508
|
+
logger.warn("Blueprint trigger dispatch failed", {
|
|
509
|
+
event: event.event,
|
|
510
|
+
userId: resolvedKey,
|
|
511
|
+
error: err instanceof Error ? err.message : String(err),
|
|
512
|
+
});
|
|
513
|
+
}
|
|
514
|
+
|
|
405
515
|
// (6) Real-time bucket membership re-evaluation (Section 6.1). NOT part of the
|
|
406
516
|
// Promise.all above: its property eval reads contact state ⊕ this-ingest
|
|
407
517
|
// contactProperties patch, and its bucket:entered/left emissions recurse back
|
|
@@ -458,14 +568,45 @@ async function checkExits(
|
|
|
458
568
|
),
|
|
459
569
|
});
|
|
460
570
|
|
|
571
|
+
// Blueprint enrollments share journeyStates but are NOT in the code-journey
|
|
572
|
+
// registry — their exitOn lives on the journey_blueprints row (spec §4).
|
|
573
|
+
// Resolve exitOn for any active state whose journeyId the registry doesn't
|
|
574
|
+
// know, in one batched read. Deliberately status-agnostic: disabling a
|
|
575
|
+
// blueprint stops NEW enrollments, but an in-flight run keeps honoring its
|
|
576
|
+
// exit rules (spec §10/§12).
|
|
577
|
+
const unregisteredIds = [
|
|
578
|
+
...new Set(
|
|
579
|
+
activeStates
|
|
580
|
+
.map((state) => state.journeyId)
|
|
581
|
+
.filter((journeyId) => !registry.get(journeyId)),
|
|
582
|
+
),
|
|
583
|
+
];
|
|
584
|
+
const blueprintExitOn = new Map<string, NonNullable<JourneyMeta["exitOn"]>>();
|
|
585
|
+
if (unregisteredIds.length > 0) {
|
|
586
|
+
const rows = await db
|
|
587
|
+
.select({ id: journeyBlueprints.id, exitOn: journeyBlueprints.exitOn })
|
|
588
|
+
.from(journeyBlueprints)
|
|
589
|
+
.where(inArray(journeyBlueprints.id, unregisteredIds));
|
|
590
|
+
for (const row of rows) {
|
|
591
|
+
if (row.exitOn?.length) {
|
|
592
|
+
blueprintExitOn.set(
|
|
593
|
+
row.id,
|
|
594
|
+
row.exitOn as NonNullable<JourneyMeta["exitOn"]>,
|
|
595
|
+
);
|
|
596
|
+
}
|
|
597
|
+
}
|
|
598
|
+
}
|
|
599
|
+
|
|
461
600
|
const statesToExit: string[] = [];
|
|
462
601
|
const runIdsToCancel: string[] = [];
|
|
463
602
|
|
|
464
603
|
for (const state of activeStates) {
|
|
465
|
-
const
|
|
466
|
-
|
|
604
|
+
const exitOn =
|
|
605
|
+
registry.get(state.journeyId)?.exitOn ??
|
|
606
|
+
blueprintExitOn.get(state.journeyId);
|
|
607
|
+
if (!exitOn) continue;
|
|
467
608
|
|
|
468
|
-
const shouldExit =
|
|
609
|
+
const shouldExit = exitOn.some((exitCondition) => {
|
|
469
610
|
if (exitCondition.event !== event.eventName) return false;
|
|
470
611
|
if (!exitCondition.where?.length) return true;
|
|
471
612
|
return evaluatePropertyConditions({
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import type { Database } from "@hogsend/db";
|
|
2
|
+
import { emailSends, journeyStates } from "@hogsend/db";
|
|
3
|
+
import { and, eq, gte, ne } from "drizzle-orm";
|
|
4
|
+
import type { JourneyBoundary } from "../journeys/journey-boundary.js";
|
|
5
|
+
import { recordOnce } from "../journeys/record-once.js";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* True if a non-failed `email_sends` row exists for THIS journey — across ALL
|
|
9
|
+
* of its enrollments — to THIS recipient within the suppress window. The
|
|
10
|
+
* INNER JOIN to `journey_states` on `journey_state_id`, filtered by
|
|
11
|
+
* `journey_id`, is what crosses enrollments: `meta.suppress` is a per-JOURNEY
|
|
12
|
+
* min-gap, not per-enrollment, so a re-enrollment inside the window is still
|
|
13
|
+
* gapped. Failed rows (`status = 'failed'`, never dispatched) are excluded,
|
|
14
|
+
* mirroring {@link countRecentSends}. EXISTS semantics only — `limit(1)`, no
|
|
15
|
+
* count needed.
|
|
16
|
+
*/
|
|
17
|
+
export async function hasRecentJourneySend(opts: {
|
|
18
|
+
db: Database;
|
|
19
|
+
journeyId: string;
|
|
20
|
+
to: string;
|
|
21
|
+
since: Date;
|
|
22
|
+
}): Promise<boolean> {
|
|
23
|
+
const rows = await opts.db
|
|
24
|
+
.select({ id: emailSends.id })
|
|
25
|
+
.from(emailSends)
|
|
26
|
+
.innerJoin(journeyStates, eq(emailSends.journeyStateId, journeyStates.id))
|
|
27
|
+
.where(
|
|
28
|
+
and(
|
|
29
|
+
eq(journeyStates.journeyId, opts.journeyId),
|
|
30
|
+
eq(emailSends.toEmail, opts.to),
|
|
31
|
+
gte(emailSends.createdAt, opts.since),
|
|
32
|
+
ne(emailSends.status, "failed"),
|
|
33
|
+
),
|
|
34
|
+
)
|
|
35
|
+
.limit(1);
|
|
36
|
+
return rows.length > 0;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* The RECORDED-once journey-suppress verdict for a boundary send. Returns
|
|
41
|
+
* `{ suppressed }` — `true` means the tracked mailer must skip the send
|
|
42
|
+
* (`journey_suppressed`, no provider call, no `email_sends` row).
|
|
43
|
+
*
|
|
44
|
+
* REPLAY STABILITY (non-negotiable): the live EXISTS check diverges on replay —
|
|
45
|
+
* the run's OWN send lands in the window, so an originally-ALLOWED send would
|
|
46
|
+
* re-check as suppressed (a late duplicate), and an originally-SUPPRESSED send
|
|
47
|
+
* could re-check as allowed if the blocking row was purged. So the verdict is
|
|
48
|
+
* frozen set-once under `context.__throttle__` keyed by the send's resolved
|
|
49
|
+
* idempotency key (already per-run-unique via `registerKey`, so it needs no
|
|
50
|
+
* extra registration) and replayed verbatim thereafter — durable on ANY engine.
|
|
51
|
+
*
|
|
52
|
+
* The guard is INERT (returns `{ suppressed: false }` without touching the DB)
|
|
53
|
+
* when there is no boundary, no `journeyId`, a zero `suppressMs`, or no resolved
|
|
54
|
+
* idempotency key — i.e. every non-journey / transactional send is unaffected.
|
|
55
|
+
*/
|
|
56
|
+
export async function checkJourneySuppress(opts: {
|
|
57
|
+
db: Database;
|
|
58
|
+
boundary: JourneyBoundary | undefined;
|
|
59
|
+
to: string;
|
|
60
|
+
idempotencyKey: string | undefined;
|
|
61
|
+
/** Injectable clock for tests; defaults to the live wall clock. */
|
|
62
|
+
now?: number;
|
|
63
|
+
}): Promise<{ suppressed: boolean }> {
|
|
64
|
+
const { db, boundary, to, idempotencyKey } = opts;
|
|
65
|
+
if (
|
|
66
|
+
!boundary?.journeyId ||
|
|
67
|
+
!boundary.suppressMs ||
|
|
68
|
+
boundary.suppressMs <= 0 ||
|
|
69
|
+
!idempotencyKey
|
|
70
|
+
) {
|
|
71
|
+
return { suppressed: false };
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
const { journeyId, suppressMs, stateId } = boundary;
|
|
75
|
+
return recordOnce<{ suppressed: boolean }>({
|
|
76
|
+
db,
|
|
77
|
+
stateId,
|
|
78
|
+
namespace: "__throttle__",
|
|
79
|
+
key: `suppress:${idempotencyKey}`,
|
|
80
|
+
compute: async () => {
|
|
81
|
+
const since = new Date((opts.now ?? Date.now()) - suppressMs);
|
|
82
|
+
return {
|
|
83
|
+
suppressed: await hasRecentJourneySend({ db, journeyId, to, since }),
|
|
84
|
+
};
|
|
85
|
+
},
|
|
86
|
+
});
|
|
87
|
+
}
|
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
|