@hogsend/engine 0.58.0 → 0.59.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 -11
- package/src/buckets/check-membership.ts +6 -0
- package/src/index.ts +16 -0
- package/src/journeys/execute-journey-run.ts +83 -1
- package/src/lib/contacts.ts +114 -0
- package/src/lib/ingestion.ts +9 -0
- package/src/lib/preferences.ts +39 -2
- package/src/lib/tracked.ts +31 -0
- package/src/routes/admin/bulk.ts +4 -0
- package/src/routes/admin/index.ts +2 -0
- package/src/routes/admin/maintenance.ts +210 -0
- package/src/routes/admin/preferences.ts +9 -1
- package/src/routes/lists/index.ts +5 -0
- package/src/worker.ts +20 -0
- package/src/workflows/backfill-contact-id.ts +771 -0
- package/src/workflows/bucket-backfill.ts +9 -1
- package/src/workflows/bucket-reconcile.ts +4 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hogsend/engine",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.59.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -53,18 +53,18 @@
|
|
|
53
53
|
"svix": "^1.95.1",
|
|
54
54
|
"winston": "^3.19.0",
|
|
55
55
|
"zod": "^4.4.3",
|
|
56
|
-
"@hogsend/attribution": "^0.
|
|
57
|
-
"@hogsend/core": "^0.
|
|
58
|
-
"@hogsend/db": "^0.
|
|
59
|
-
"@hogsend/email": "^0.
|
|
60
|
-
"@hogsend/plugin-posthog": "^0.
|
|
61
|
-
"@hogsend/plugin-resend": "^0.
|
|
62
|
-
"@hogsend/sms": "^0.
|
|
56
|
+
"@hogsend/attribution": "^0.59.0",
|
|
57
|
+
"@hogsend/core": "^0.59.0",
|
|
58
|
+
"@hogsend/db": "^0.59.0",
|
|
59
|
+
"@hogsend/email": "^0.59.0",
|
|
60
|
+
"@hogsend/plugin-posthog": "^0.59.0",
|
|
61
|
+
"@hogsend/plugin-resend": "^0.59.0",
|
|
62
|
+
"@hogsend/sms": "^0.59.0"
|
|
63
63
|
},
|
|
64
64
|
"optionalDependencies": {
|
|
65
|
-
"@hogsend/plugin-apollo": "^0.
|
|
66
|
-
"@hogsend/plugin-postmark": "^0.
|
|
67
|
-
"@hogsend/plugin-twilio": "^0.
|
|
65
|
+
"@hogsend/plugin-apollo": "^0.59.0",
|
|
66
|
+
"@hogsend/plugin-postmark": "^0.59.0",
|
|
67
|
+
"@hogsend/plugin-twilio": "^0.59.0"
|
|
68
68
|
},
|
|
69
69
|
"devDependencies": {
|
|
70
70
|
"@types/node": "^22.15.3",
|
|
@@ -346,6 +346,12 @@ async function handleJoin(opts: {
|
|
|
346
346
|
expiresAt,
|
|
347
347
|
maxDwellAt,
|
|
348
348
|
lastEvaluatedAt: new Date(),
|
|
349
|
+
// PRD 04 dual-write. `contactId` is already a documented param of this
|
|
350
|
+
// function (`ingestEvent` resolved the subject before calling us), so this
|
|
351
|
+
// is ZERO new queries and has no failure mode to wrap: `undefined` — a
|
|
352
|
+
// pin-less caller or a refused resolve — stamps NULL and the join is
|
|
353
|
+
// recorded exactly as before (memberships are text-keyed, no contact FK).
|
|
354
|
+
contactId: contactId ?? null,
|
|
349
355
|
})
|
|
350
356
|
.onConflictDoNothing()
|
|
351
357
|
.returning({ id: bucketMemberships.id });
|
package/src/index.ts
CHANGED
|
@@ -916,6 +916,22 @@ export {
|
|
|
916
916
|
createWorker,
|
|
917
917
|
type Worker,
|
|
918
918
|
} from "./worker.js";
|
|
919
|
+
// --- History contact_id backfill (PRD 04): periodic reconcile sweep + enqueue,
|
|
920
|
+
// --- plus T6's invariant probe (`flipReady` = the read-flip entry gate) ---
|
|
921
|
+
export {
|
|
922
|
+
CONTACT_ID_BACKFILL_FORMAT,
|
|
923
|
+
type ContactIdBackfillCounts,
|
|
924
|
+
type ContactIdBackfillInput,
|
|
925
|
+
type ContactIdBackfillResult,
|
|
926
|
+
type ContactIdBackfillTable,
|
|
927
|
+
type ContactIdVerifyCounts,
|
|
928
|
+
type ContactIdVerifyResult,
|
|
929
|
+
contactIdBackfillTask,
|
|
930
|
+
contactIdResweepIntervalMs,
|
|
931
|
+
enqueueContactIdBackfill,
|
|
932
|
+
runContactIdBackfill,
|
|
933
|
+
verifyContactIdBackfill,
|
|
934
|
+
} from "./workflows/backfill-contact-id.js";
|
|
919
935
|
export {
|
|
920
936
|
type BucketBackfillInput,
|
|
921
937
|
bucketBackfillTask,
|
|
@@ -15,7 +15,7 @@ import {
|
|
|
15
15
|
import { and, eq, inArray, isNull, notInArray, or, sql } from "drizzle-orm";
|
|
16
16
|
import { getAnalytics } from "../lib/analytics-singleton.js";
|
|
17
17
|
import { blueprintGraphLock } from "../lib/blueprint-lock.js";
|
|
18
|
-
import { ALL_IDENTITY_KINDS } from "../lib/contacts.js";
|
|
18
|
+
import { ALL_IDENTITY_KINDS, lookupContactIdByKey } from "../lib/contacts.js";
|
|
19
19
|
import { getDb } from "../lib/db.js";
|
|
20
20
|
import {
|
|
21
21
|
checkEmailPreferences,
|
|
@@ -102,6 +102,55 @@ export interface JourneyDurableCtx {
|
|
|
102
102
|
/** The `journey_states` row an enrollment insert returns. */
|
|
103
103
|
export type JourneyStateRow = typeof journeyStates.$inferSelect;
|
|
104
104
|
|
|
105
|
+
/**
|
|
106
|
+
* PRD 04 dual-write resolve for the two `journey_states` insert sites (the
|
|
107
|
+
* enrollment row and the held_out row).
|
|
108
|
+
*
|
|
109
|
+
* D6 — a bookkeeping resolve may NEVER fail the operation it rides on: every
|
|
110
|
+
* failure degrades to NULL plus a warn, because a missing `contact_id` is a
|
|
111
|
+
* NULL a backfill fills later while a throwing enrollment is an outage.
|
|
112
|
+
*
|
|
113
|
+
* The pushed `input.contactId` is preferred — `ingestEvent` already resolved the
|
|
114
|
+
* subject before routing the event here — but it is VALIDATED, not trusted. The
|
|
115
|
+
* pin was computed at INGEST time and then crossed an unbounded Hatchet queue
|
|
116
|
+
* delay; a contact MERGE inside that window soft-deletes the pinned loser and
|
|
117
|
+
* re-aliases its key onto the survivor. Stamping the pin blindly would write a
|
|
118
|
+
* TOMBSTONE id, and that stamp is PERMANENT: the backfill only fills NULLs (it
|
|
119
|
+
* is not a repair tool) and T3's merge re-point ran before this row existed.
|
|
120
|
+
* Worse, the pin-ABSENT path would have got it right — `lookupContactIdByKey`'s
|
|
121
|
+
* alias probe refuses soft-deleted targets and follows the key to the survivor.
|
|
122
|
+
*
|
|
123
|
+
* So: ONE indexed live-PK probe on the pin, and on a miss FALL THROUGH to the
|
|
124
|
+
* ordinary key probe (survivor, or null). Any failure degrades to NULL per D6.
|
|
125
|
+
*/
|
|
126
|
+
async function resolveEnrollmentContactId(opts: {
|
|
127
|
+
db: Database;
|
|
128
|
+
userId: string;
|
|
129
|
+
journeyId: string;
|
|
130
|
+
pushed?: string;
|
|
131
|
+
}): Promise<string | null> {
|
|
132
|
+
try {
|
|
133
|
+
if (opts.pushed) {
|
|
134
|
+
const live = await opts.db
|
|
135
|
+
.select({ id: contacts.id })
|
|
136
|
+
.from(contacts)
|
|
137
|
+
.where(and(eq(contacts.id, opts.pushed), isNull(contacts.deletedAt)))
|
|
138
|
+
.limit(1);
|
|
139
|
+
if (live[0]) return live[0].id;
|
|
140
|
+
// Pin went stale between ingest and execution (merged away, or hard
|
|
141
|
+
// deleted). Fall through rather than stamping the tombstone.
|
|
142
|
+
}
|
|
143
|
+
return await lookupContactIdByKey(opts.db, opts.userId);
|
|
144
|
+
} catch (err) {
|
|
145
|
+
logger.warn("journey_states contact_id dual-write resolve failed", {
|
|
146
|
+
journeyId: opts.journeyId,
|
|
147
|
+
userId: opts.userId,
|
|
148
|
+
error: err instanceof Error ? err.message : String(err),
|
|
149
|
+
});
|
|
150
|
+
return null;
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
|
|
105
154
|
/**
|
|
106
155
|
* Insert the enrollment row, tolerating the partial-unique-index race.
|
|
107
156
|
*
|
|
@@ -148,6 +197,15 @@ export async function insertEnrollment(opts: {
|
|
|
148
197
|
*/
|
|
149
198
|
journeyVersionHash?: string | null;
|
|
150
199
|
journeyVersionLabel?: string | null;
|
|
200
|
+
/**
|
|
201
|
+
* PRD 04 dual-write: the `contacts.id` owning `userId`, stamped alongside the
|
|
202
|
+
* canonical string key. OPTIONAL and defaulting to NULL — this is public API
|
|
203
|
+
* (index.ts) and bookkeeping, so a caller that omits it (dogfood tests, any
|
|
204
|
+
* pre-PRD-04 consumer) behaves exactly as before. The RESOLVE lives in the
|
|
205
|
+
* caller, never here: `executeJourneyRun` already holds the pushed
|
|
206
|
+
* `input.contactId` and only pays for a lookup when it doesn't.
|
|
207
|
+
*/
|
|
208
|
+
contactId?: string | null;
|
|
151
209
|
}): Promise<JourneyStateRow | undefined> {
|
|
152
210
|
const values = {
|
|
153
211
|
userId: opts.userId,
|
|
@@ -159,6 +217,7 @@ export async function insertEnrollment(opts: {
|
|
|
159
217
|
hatchetRunId: opts.hatchetRunId,
|
|
160
218
|
journeyVersionHash: opts.journeyVersionHash ?? null,
|
|
161
219
|
journeyVersionLabel: opts.journeyVersionLabel ?? null,
|
|
220
|
+
contactId: opts.contactId ?? null,
|
|
162
221
|
};
|
|
163
222
|
const onConflict = {
|
|
164
223
|
target: [journeyStates.userId, journeyStates.journeyId],
|
|
@@ -355,6 +414,19 @@ export async function executeJourneyRun(
|
|
|
355
414
|
});
|
|
356
415
|
if (!priorHoldout) {
|
|
357
416
|
const heldOutAt = new Date();
|
|
417
|
+
// PRD 04 dual-write. This is deliberately its OWN D6-wrapped resolve
|
|
418
|
+
// rather than a hoist of the `subjectContactId` compute below: that
|
|
419
|
+
// compute lives INSIDE the ingest try/catch, and lifting it out would
|
|
420
|
+
// change which failures skip the `journey.heldout` re-emit — a
|
|
421
|
+
// control-flow change to the identity-provenance path, made for
|
|
422
|
+
// bookkeeping. Cost on this once-ever-per-(user, journey) path: one
|
|
423
|
+
// live-PK validation probe with a pushed pin, 1-2 probes without.
|
|
424
|
+
const heldOutContactId = await resolveEnrollmentContactId({
|
|
425
|
+
db,
|
|
426
|
+
userId,
|
|
427
|
+
journeyId: meta.id,
|
|
428
|
+
pushed: input.contactId,
|
|
429
|
+
});
|
|
358
430
|
const inserted = await db
|
|
359
431
|
.insert(journeyStates)
|
|
360
432
|
.values({
|
|
@@ -363,6 +435,7 @@ export async function executeJourneyRun(
|
|
|
363
435
|
journeyId: meta.id,
|
|
364
436
|
currentNodeId: "held-out",
|
|
365
437
|
status: "held_out",
|
|
438
|
+
contactId: heldOutContactId,
|
|
366
439
|
// Reserved record-once namespaces are STRIPPED from event
|
|
367
440
|
// properties before seeding (injection fix): a publishable-key
|
|
368
441
|
// event must never pre-fill __once__/__digest__/__throttle__/
|
|
@@ -519,6 +592,15 @@ export async function executeJourneyRun(
|
|
|
519
592
|
hatchetRunId: workflowRunId,
|
|
520
593
|
journeyVersionHash: meta.versionHash ?? null,
|
|
521
594
|
journeyVersionLabel: meta.version ?? null,
|
|
595
|
+
// PRD 04 dual-write — the pushed pin when ingest resolved one, else one
|
|
596
|
+
// D6-wrapped probe. NULL (unknown subject / refused resolve) is a legal
|
|
597
|
+
// stamp: the enrollment proceeds exactly as before.
|
|
598
|
+
contactId: await resolveEnrollmentContactId({
|
|
599
|
+
db,
|
|
600
|
+
userId,
|
|
601
|
+
journeyId: meta.id,
|
|
602
|
+
pushed: input.contactId,
|
|
603
|
+
}),
|
|
522
604
|
serializeWithGraphLock: options.serializeEnrollment,
|
|
523
605
|
});
|
|
524
606
|
if (!state) {
|
package/src/lib/contacts.ts
CHANGED
|
@@ -1673,6 +1673,37 @@ async function mergeContacts(
|
|
|
1673
1673
|
.set({ contactId: survivor.id })
|
|
1674
1674
|
.where(eq(crmLinks.contactId, loser.id));
|
|
1675
1675
|
|
|
1676
|
+
// (vi-b-hist) the five HISTORY tables' `contact_id` re-point (PRD 04 T3).
|
|
1677
|
+
// Same shape and same reasoning as the deals/crm_links repoints above: a
|
|
1678
|
+
// uuid column the string-key rewrites never touch, and no unique index
|
|
1679
|
+
// involves `contact_id`, so plain UPDATEs suffice (no fold needed — unlike
|
|
1680
|
+
// the (vi)/(vi-c) folds, which exist only to respect a unique index).
|
|
1681
|
+
// Deliberately lands AHEAD of the dual-write that populates the column
|
|
1682
|
+
// (PRD 04 D9/D10): while every row is still NULL this is a pure no-op, and
|
|
1683
|
+
// the moment the dual-write starts, merges are already correct. Shipped in
|
|
1684
|
+
// the other order, every merge in between would strand history rows
|
|
1685
|
+
// pointing at a soft-deleted loser contact.
|
|
1686
|
+
await tx
|
|
1687
|
+
.update(userEvents)
|
|
1688
|
+
.set({ contactId: survivor.id })
|
|
1689
|
+
.where(eq(userEvents.contactId, loser.id));
|
|
1690
|
+
await tx
|
|
1691
|
+
.update(journeyStates)
|
|
1692
|
+
.set({ contactId: survivor.id })
|
|
1693
|
+
.where(eq(journeyStates.contactId, loser.id));
|
|
1694
|
+
await tx
|
|
1695
|
+
.update(bucketMemberships)
|
|
1696
|
+
.set({ contactId: survivor.id })
|
|
1697
|
+
.where(eq(bucketMemberships.contactId, loser.id));
|
|
1698
|
+
await tx
|
|
1699
|
+
.update(emailSends)
|
|
1700
|
+
.set({ contactId: survivor.id })
|
|
1701
|
+
.where(eq(emailSends.contactId, loser.id));
|
|
1702
|
+
await tx
|
|
1703
|
+
.update(emailPreferences)
|
|
1704
|
+
.set({ contactId: survivor.id })
|
|
1705
|
+
.where(eq(emailPreferences.contactId, loser.id));
|
|
1706
|
+
|
|
1676
1707
|
// (vi-c) group_memberships FOLD: another contact_id uuid FK the key
|
|
1677
1708
|
// rewrites never touch. The loser is SOFT-deleted, so `onDelete: cascade`
|
|
1678
1709
|
// never fires — without this the loser's memberships are stranded on a dead
|
|
@@ -2624,6 +2655,89 @@ export async function resolveRecipient(opts: {
|
|
|
2624
2655
|
};
|
|
2625
2656
|
}
|
|
2626
2657
|
|
|
2658
|
+
/**
|
|
2659
|
+
* Resolve the live contact that OWNS a canonical history key, for the PRD 04
|
|
2660
|
+
* `contact_id` DUAL-WRITE and nothing else.
|
|
2661
|
+
*
|
|
2662
|
+
* WHAT IT IS FOR. Every history row (`user_events`, `journey_states`,
|
|
2663
|
+
* `bucket_memberships`, `email_sends`, `email_preferences`) is stored under a
|
|
2664
|
+
* canonical STRING key (`external_id ?? anonymous_id ?? id`). The dual-write
|
|
2665
|
+
* stamps the owning `contacts.id` alongside it at insert time, so this must
|
|
2666
|
+
* resolve EXACTLY the key the row is stored under — no widening, no minting.
|
|
2667
|
+
* A miss is a legal, expected `null`: the column is nullable bookkeeping and a
|
|
2668
|
+
* later backfill fills what this could not see. Callers wrap it per D6 (a
|
|
2669
|
+
* bookkeeping resolve may never fail the operation it rides on).
|
|
2670
|
+
*
|
|
2671
|
+
* WHY ALIAS-AWARE. Since PRD 03 a second device's anonymous id can live ONLY in
|
|
2672
|
+
* `contact_aliases` (the contact row already carries a different
|
|
2673
|
+
* `anonymous_id`), so a column-only probe would stamp NULL for that visitor
|
|
2674
|
+
* FOREVER — the backfill reads the same columns and would miss it too. The
|
|
2675
|
+
* alias probe is restricted to kinds `external`/`anonymous` because those are
|
|
2676
|
+
* the only kinds a CANONICAL key can be: folding in an `email`/`discord` alias
|
|
2677
|
+
* would resolve history that today resolves to nothing, which is a read-shape
|
|
2678
|
+
* change smuggled in through a write. When both kinds carry the value,
|
|
2679
|
+
* `external` wins — mirroring the canonical-key precedence `external_id ??
|
|
2680
|
+
* anonymous_id` so the answer is deterministic rather than index-order luck.
|
|
2681
|
+
*
|
|
2682
|
+
* WHY NOT {@link findByKey}. That one takes a `(kind, value)` pair, probes
|
|
2683
|
+
* aliases FIRST across every kind, and carries a uuid-as-external fallback with
|
|
2684
|
+
* merge/mint semantics attached — resolution for a WRITE that may change the
|
|
2685
|
+
* identity graph. This is a read-only ownership question about one already-fixed
|
|
2686
|
+
* string, so it stays a separate, narrower probe.
|
|
2687
|
+
*/
|
|
2688
|
+
export async function lookupContactIdByKey(
|
|
2689
|
+
db: Database,
|
|
2690
|
+
key: string,
|
|
2691
|
+
): Promise<string | null> {
|
|
2692
|
+
const value = key?.trim();
|
|
2693
|
+
if (!value) return null;
|
|
2694
|
+
|
|
2695
|
+
// (1) COLUMN probe — one statement over the three indexed identity columns a
|
|
2696
|
+
// canonical key can occupy (Postgres serves the OR as a BitmapOr). The uuid
|
|
2697
|
+
// leg is REGEX-GUARDED rather than cast (`id::text = $1`): a bare cast is
|
|
2698
|
+
// unindexed AND an unguarded `id = $1` throws 22P02 on a non-uuid key.
|
|
2699
|
+
const direct = await db
|
|
2700
|
+
.select({ id: contacts.id })
|
|
2701
|
+
.from(contacts)
|
|
2702
|
+
.where(
|
|
2703
|
+
and(
|
|
2704
|
+
isNull(contacts.deletedAt),
|
|
2705
|
+
or(
|
|
2706
|
+
eq(contacts.externalId, value),
|
|
2707
|
+
eq(contacts.anonymousId, value),
|
|
2708
|
+
UUID_REGEX.test(value) ? eq(contacts.id, value) : undefined,
|
|
2709
|
+
),
|
|
2710
|
+
),
|
|
2711
|
+
)
|
|
2712
|
+
.limit(1);
|
|
2713
|
+
if (direct[0]) return direct[0].id;
|
|
2714
|
+
|
|
2715
|
+
// (2) ALIAS probe — only reached on a column miss. `deleted_at IS NULL` lives
|
|
2716
|
+
// INSIDE the join (the live-target rule, as in `findByKey`): an alias whose
|
|
2717
|
+
// target is soft-deleted must produce NO row rather than stamp a tombstone.
|
|
2718
|
+
const viaAlias = await db
|
|
2719
|
+
.select({ id: contacts.id })
|
|
2720
|
+
.from(contactAliases)
|
|
2721
|
+
.innerJoin(
|
|
2722
|
+
contacts,
|
|
2723
|
+
and(
|
|
2724
|
+
eq(contacts.id, contactAliases.contactId),
|
|
2725
|
+
isNull(contacts.deletedAt),
|
|
2726
|
+
),
|
|
2727
|
+
)
|
|
2728
|
+
.where(
|
|
2729
|
+
and(
|
|
2730
|
+
eq(contactAliases.aliasValue, value),
|
|
2731
|
+
inArray(contactAliases.aliasKind, ["external", "anonymous"]),
|
|
2732
|
+
),
|
|
2733
|
+
)
|
|
2734
|
+
.orderBy(
|
|
2735
|
+
sql`case when ${contactAliases.aliasKind} = 'external' then 0 else 1 end`,
|
|
2736
|
+
)
|
|
2737
|
+
.limit(1);
|
|
2738
|
+
return viaAlias[0]?.id ?? null;
|
|
2739
|
+
}
|
|
2740
|
+
|
|
2627
2741
|
/** Alias-aware lookup helper (mirrors findByKey's alias probe but on the
|
|
2628
2742
|
* top-level db handle, no tx). Engine-internal export: `resolveRecipient`
|
|
2629
2743
|
* below and the feed's anonymous-recipient resolver (PRD 03 T5 — a second
|
package/src/lib/ingestion.ts
CHANGED
|
@@ -530,6 +530,12 @@ export async function ingestEvent(opts: {
|
|
|
530
530
|
currency,
|
|
531
531
|
source: event.source ?? null,
|
|
532
532
|
idempotencyKey: event.idempotencyKey,
|
|
533
|
+
// PRD 04 dual-write. The resolve ABOVE already produced this — zero new
|
|
534
|
+
// queries, and no D6 wrapper is needed because there is no new failure
|
|
535
|
+
// mode to swallow. A REFUSED resolve stamps NULL here BY DESIGN: the
|
|
536
|
+
// observation is kept (same canonical key, same row) while the CRM row
|
|
537
|
+
// it would point at deliberately does not exist.
|
|
538
|
+
contactId,
|
|
533
539
|
...(occurredAt ? { occurredAt } : {}),
|
|
534
540
|
})
|
|
535
541
|
.onConflictDoNothing({
|
|
@@ -553,6 +559,9 @@ export async function ingestEvent(opts: {
|
|
|
553
559
|
value,
|
|
554
560
|
currency,
|
|
555
561
|
source: event.source ?? null,
|
|
562
|
+
// PRD 04 dual-write — same already-resolved value as the idempotent
|
|
563
|
+
// branch above, NULL on a refused resolve by design.
|
|
564
|
+
contactId,
|
|
556
565
|
...(occurredAt ? { occurredAt } : {}),
|
|
557
566
|
})
|
|
558
567
|
.returning({ id: userEvents.id, occurredAt: userEvents.occurredAt });
|
package/src/lib/preferences.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { Database } from "@hogsend/db";
|
|
2
2
|
import { emailPreferences } from "@hogsend/db";
|
|
3
3
|
import { sql } from "drizzle-orm";
|
|
4
|
-
import { resolveRecipient } from "./contacts.js";
|
|
4
|
+
import { lookupContactIdByKey, resolveRecipient } from "./contacts.js";
|
|
5
5
|
import { hatchet } from "./hatchet.js";
|
|
6
6
|
import { createLogger } from "./logger.js";
|
|
7
7
|
import { emitOutbound } from "./outbound.js";
|
|
@@ -54,10 +54,46 @@ export async function upsertEmailPreference(opts: {
|
|
|
54
54
|
* TCPA record-keeping is the "how" as much as the "when".
|
|
55
55
|
*/
|
|
56
56
|
source?: string;
|
|
57
|
+
/**
|
|
58
|
+
* PRD 04 dual-write: the `contacts.id` owning `externalId`.
|
|
59
|
+
*
|
|
60
|
+
* `undefined` (the default, and every caller that has nothing in hand) ⇒ this
|
|
61
|
+
* function does ONE D6-wrapped lookup itself. An EXPLICIT value — including
|
|
62
|
+
* an explicit `null` — is used verbatim, so a caller that already resolved
|
|
63
|
+
* the contact (the lists route, one line after `resolveOrCreateContact`) pays
|
|
64
|
+
* no second query and cannot disagree with itself.
|
|
65
|
+
*/
|
|
66
|
+
contactId?: string | null;
|
|
57
67
|
}): Promise<void> {
|
|
58
68
|
const { db, externalId, email, update } = opts;
|
|
59
69
|
|
|
60
|
-
|
|
70
|
+
// D6 — the resolve may never fail the preference write it rides on: a throw
|
|
71
|
+
// degrades to NULL + a warn. The probe is paid ONLY when the caller supplied
|
|
72
|
+
// nothing; the discriminant is `undefined` (not falsiness), so an EXPLICIT
|
|
73
|
+
// null stays an explicit null rather than triggering a lookup.
|
|
74
|
+
let contactId: string | null = null;
|
|
75
|
+
if (opts.contactId !== undefined) {
|
|
76
|
+
contactId = opts.contactId;
|
|
77
|
+
} else {
|
|
78
|
+
try {
|
|
79
|
+
contactId = await lookupContactIdByKey(db, externalId);
|
|
80
|
+
} catch (err) {
|
|
81
|
+
logger.warn("email_preferences contact_id dual-write resolve failed", {
|
|
82
|
+
externalId,
|
|
83
|
+
error: err instanceof Error ? err.message : String(err),
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
const setClause: Record<string, unknown> = {
|
|
89
|
+
updatedAt: new Date(),
|
|
90
|
+
// FILL-IF-KNOWN, NEVER NULL-OUT (house precedent: the fill-if-absent
|
|
91
|
+
// refinement, PR #615). The conflict arm takes the incoming id when there is
|
|
92
|
+
// one and otherwise KEEPS what the row already carries — so a failed or
|
|
93
|
+
// impossible resolve on a later write can never erase a `contact_id` an
|
|
94
|
+
// earlier write successfully stamped.
|
|
95
|
+
contactId: sql`coalesce(excluded.contact_id, ${emailPreferences.contactId})`,
|
|
96
|
+
};
|
|
61
97
|
|
|
62
98
|
if (update.unsubscribedAll !== undefined) {
|
|
63
99
|
setClause.unsubscribedAll = update.unsubscribedAll;
|
|
@@ -82,6 +118,7 @@ export async function upsertEmailPreference(opts: {
|
|
|
82
118
|
.values({
|
|
83
119
|
userId: externalId,
|
|
84
120
|
email,
|
|
121
|
+
contactId,
|
|
85
122
|
...(update.unsubscribedAll !== undefined
|
|
86
123
|
? { unsubscribedAll: update.unsubscribedAll }
|
|
87
124
|
: {}),
|
package/src/lib/tracked.ts
CHANGED
|
@@ -21,6 +21,7 @@ import {
|
|
|
21
21
|
} from "../journeys/journey-boundary.js";
|
|
22
22
|
import { logTransition } from "../journeys/journey-log.js";
|
|
23
23
|
import { getListRegistry } from "../lists/registry-singleton.js";
|
|
24
|
+
import { lookupContactIdByKey } from "./contacts.js";
|
|
24
25
|
import type { TestModeState } from "./domain-status.js";
|
|
25
26
|
import {
|
|
26
27
|
type FrequencyCapConfig,
|
|
@@ -180,6 +181,33 @@ async function sendTrackedEmailInner<K extends TemplateName>(
|
|
|
180
181
|
}
|
|
181
182
|
}
|
|
182
183
|
|
|
184
|
+
// PRD 04 dual-write — resolved ONCE here and reused by all three
|
|
185
|
+
// `email_sends` insert sites below (suppressed, test-mode-blocked, real).
|
|
186
|
+
//
|
|
187
|
+
// D7 — keyed on `options.userId` ONLY, never on `options.to`. A raw send
|
|
188
|
+
// (public /v1/emails, password reset, any journeyless dispatch) carries no
|
|
189
|
+
// userId, so its row stamps NULL. Resolving by recipient ADDRESS instead
|
|
190
|
+
// would make that send visible to per-contact queries that cannot see it
|
|
191
|
+
// today — a read-shape change smuggled in through a write.
|
|
192
|
+
//
|
|
193
|
+
// D6 — wrapped: a bookkeeping resolve may never fail the send it rides on.
|
|
194
|
+
// Placed AFTER the idempotency short-circuit so a deduped retry pays nothing.
|
|
195
|
+
let sendContactId: string | null = null;
|
|
196
|
+
if (options.userId) {
|
|
197
|
+
try {
|
|
198
|
+
sendContactId = await lookupContactIdByKey(db, options.userId);
|
|
199
|
+
} catch (err) {
|
|
200
|
+
(logger ?? emitLogger).warn(
|
|
201
|
+
"email_sends contact_id dual-write resolve failed",
|
|
202
|
+
{
|
|
203
|
+
userId: options.userId,
|
|
204
|
+
templateKey: String(options.templateKey),
|
|
205
|
+
error: err instanceof Error ? err.message : String(err),
|
|
206
|
+
},
|
|
207
|
+
);
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
|
|
183
211
|
// Resolve the template ONCE up front so its default category is available to
|
|
184
212
|
// the suppression check (a public /v1/emails send may omit `category`, in
|
|
185
213
|
// which case the per-category suppression must still consult the template's
|
|
@@ -213,6 +241,7 @@ async function sendTrackedEmailInner<K extends TemplateName>(
|
|
|
213
241
|
campaignId: options.campaignId,
|
|
214
242
|
userId: options.userId,
|
|
215
243
|
userEmail: options.userEmail ?? options.to,
|
|
244
|
+
contactId: sendContactId,
|
|
216
245
|
// First-class "suppressed" status: a provider dispatch failure
|
|
217
246
|
// releases its idempotency key (catch block below), making it
|
|
218
247
|
// byte-identical to this row EXCEPT for the status — so campaign
|
|
@@ -403,6 +432,7 @@ async function sendTrackedEmailInner<K extends TemplateName>(
|
|
|
403
432
|
campaignId: options.campaignId,
|
|
404
433
|
userId: options.userId,
|
|
405
434
|
userEmail: options.userEmail ?? options.to,
|
|
435
|
+
contactId: sendContactId,
|
|
406
436
|
// Policy-gated like suppression (the provider is never reached), so it
|
|
407
437
|
// shares the "suppressed" status; metadata.testMode marks the cause.
|
|
408
438
|
status: "suppressed",
|
|
@@ -460,6 +490,7 @@ async function sendTrackedEmailInner<K extends TemplateName>(
|
|
|
460
490
|
campaignId: options.campaignId,
|
|
461
491
|
userId: options.userId,
|
|
462
492
|
userEmail: options.userEmail ?? options.to,
|
|
493
|
+
contactId: sendContactId,
|
|
463
494
|
status: "queued",
|
|
464
495
|
idempotencyKey: options.idempotencyKey,
|
|
465
496
|
...(redirect
|
package/src/routes/admin/bulk.ts
CHANGED
|
@@ -488,6 +488,10 @@ export const bulkRouter = new OpenAPIHono<AppEnv>()
|
|
|
488
488
|
toEmail: email.toEmail,
|
|
489
489
|
subject: email.subject,
|
|
490
490
|
category: email.category,
|
|
491
|
+
// PRD 04 dual-write: copied verbatim off the source row (the full row
|
|
492
|
+
// is already selected above) — zero queries, and a resend of a send
|
|
493
|
+
// that stamped NULL correctly stays NULL rather than resolving anew.
|
|
494
|
+
contactId: email.contactId,
|
|
491
495
|
status: "queued",
|
|
492
496
|
})
|
|
493
497
|
.returning();
|
|
@@ -31,6 +31,7 @@ import { journeyLogsRouter } from "./journey-logs.js";
|
|
|
31
31
|
import { journeysRouter } from "./journeys.js";
|
|
32
32
|
import { linksRouter } from "./links.js";
|
|
33
33
|
import { adminListsRouter } from "./lists.js";
|
|
34
|
+
import { maintenanceRouter } from "./maintenance.js";
|
|
34
35
|
import { metricsRouter } from "./metrics.js";
|
|
35
36
|
import { openEditorRouter } from "./open-editor.js";
|
|
36
37
|
import { preferencesRouter } from "./preferences.js";
|
|
@@ -87,4 +88,5 @@ adminRouter.route("/alerts", alertsRouter);
|
|
|
87
88
|
adminRouter.route("/dlq", dlqRouter);
|
|
88
89
|
adminRouter.route("/domain", domainRouter);
|
|
89
90
|
adminRouter.route("/readiness", readinessRouter);
|
|
91
|
+
adminRouter.route("/maintenance", maintenanceRouter);
|
|
90
92
|
adminRouter.route("/agent", agentRouter);
|