@hogsend/engine 0.59.0 → 0.61.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/bucket-access.ts +34 -11
- package/src/buckets/check-membership.ts +74 -10
- package/src/buckets/membership-epoch.ts +11 -1
- package/src/campaigns/cohort-sql.ts +10 -0
- package/src/index.ts +10 -6
- package/src/journeys/execute-journey-run.ts +139 -70
- package/src/journeys/journey-context.ts +43 -7
- package/src/lib/agent/tools.ts +29 -4
- package/src/lib/attribution-backfill.ts +35 -4
- package/src/lib/attribution.ts +22 -3
- package/src/lib/connector-actions.ts +17 -17
- package/src/lib/contacts.ts +541 -175
- package/src/lib/conversion-dispatch.ts +16 -2
- package/src/lib/enrollment-guards.ts +19 -12
- package/src/lib/feed.ts +5 -5
- package/src/lib/flags.ts +26 -9
- package/src/lib/ingestion.ts +14 -2
- package/src/lib/journey-lift.ts +17 -5
- package/src/lib/preferences.ts +78 -29
- package/src/lib/recipient-preferences.ts +16 -2
- package/src/lib/refine.ts +16 -10
- package/src/lib/revenue.ts +20 -5
- package/src/lib/sms-inbound.ts +6 -1
- package/src/lib/sms-tracked.ts +18 -1
- package/src/lib/timezone.ts +11 -1
- package/src/lib/tracked.ts +19 -8
- package/src/lib/tracking-events.ts +28 -0
- package/src/lib/unique-violation.ts +44 -0
- package/src/routes/admin/buckets.ts +21 -1
- package/src/routes/admin/bulk.ts +14 -2
- package/src/routes/admin/contacts.ts +20 -7
- package/src/routes/admin/conversions.ts +20 -4
- package/src/routes/admin/emails.ts +17 -2
- package/src/routes/admin/events.ts +32 -41
- package/src/routes/admin/funnels.ts +6 -1
- package/src/routes/admin/groups.ts +4 -0
- package/src/routes/admin/impact.ts +30 -10
- package/src/routes/admin/journey-impact.ts +18 -9
- package/src/routes/admin/journeys.ts +8 -1
- package/src/routes/admin/maintenance.ts +7 -1
- package/src/routes/admin/preferences.ts +85 -46
- package/src/routes/admin/reporting.ts +25 -5
- package/src/routes/admin/targeting.ts +1 -0
- package/src/routes/admin/timeline.ts +16 -10
- package/src/routes/email/preferences.ts +18 -1
- package/src/routes/feed/recipient.ts +5 -0
- package/src/routes/lists/index.ts +6 -6
- package/src/workflows/backfill-contact-id.ts +210 -30
- package/src/workflows/bucket-backfill.ts +145 -67
- package/src/workflows/bucket-reconcile.ts +164 -51
- package/src/workflows/check-alerts.ts +4 -0
- package/src/workflows/impact-digest.ts +10 -3
- package/src/workflows/journey-blueprint-interpreter.ts +8 -1
- package/src/workflows/send-campaign.ts +18 -11
|
@@ -3,7 +3,7 @@ import type {
|
|
|
3
3
|
ConversionDestination,
|
|
4
4
|
ConversionDispatchInput,
|
|
5
5
|
} from "@hogsend/core";
|
|
6
|
-
import { CLICK_ID_PARAM_NAMES } from "@hogsend/core";
|
|
6
|
+
import { bySubject, CLICK_ID_PARAM_NAMES } from "@hogsend/core";
|
|
7
7
|
import {
|
|
8
8
|
contacts,
|
|
9
9
|
conversionDispatches,
|
|
@@ -98,6 +98,16 @@ export async function createConversionDispatches(opts: {
|
|
|
98
98
|
export async function recoverClickContext(opts: {
|
|
99
99
|
db: Database;
|
|
100
100
|
userKey: string;
|
|
101
|
+
/**
|
|
102
|
+
* The trusted owner uuid. REQUIRED (not optional) for the same reason the
|
|
103
|
+
* enrollment guards' is: an optional field silently defaults a new caller
|
|
104
|
+
* onto the mutable text key, and an arrival recorded under the visitor's
|
|
105
|
+
* anon-era key would then be invisible — the click id the ad platform needs
|
|
106
|
+
* to match the conversion goes missing exactly when it matters (the click
|
|
107
|
+
* IS the anonymous era). Pass `null` explicitly for a subject with no
|
|
108
|
+
* contact; `userKey` still serves that case.
|
|
109
|
+
*/
|
|
110
|
+
contactId: string | null;
|
|
101
111
|
before: Date;
|
|
102
112
|
}): Promise<ConversionDispatchInput["clicks"]> {
|
|
103
113
|
const rows = await opts.db
|
|
@@ -108,7 +118,10 @@ export async function recoverClickContext(opts: {
|
|
|
108
118
|
.from(userEvents)
|
|
109
119
|
.where(
|
|
110
120
|
and(
|
|
111
|
-
|
|
121
|
+
bySubject(userEvents, {
|
|
122
|
+
contactId: opts.contactId,
|
|
123
|
+
userKey: opts.userKey,
|
|
124
|
+
}),
|
|
112
125
|
eq(userEvents.event, "campaign.arrived"),
|
|
113
126
|
lte(userEvents.occurredAt, opts.before),
|
|
114
127
|
),
|
|
@@ -209,6 +222,7 @@ export async function deliverConversionDispatch(opts: {
|
|
|
209
222
|
const clicks = await recoverClickContext({
|
|
210
223
|
db,
|
|
211
224
|
userKey: row.conversion.userKey,
|
|
225
|
+
contactId: row.conversion.contactId,
|
|
212
226
|
before: row.conversion.occurredAt,
|
|
213
227
|
});
|
|
214
228
|
|
|
@@ -1,22 +1,30 @@
|
|
|
1
|
-
import { durationToMs, hours } from "@hogsend/core";
|
|
1
|
+
import { bySubject, durationToMs, hours } from "@hogsend/core";
|
|
2
2
|
import type { JourneyMeta } from "@hogsend/core/types";
|
|
3
3
|
import { type Database, emailPreferences, journeyStates } from "@hogsend/db";
|
|
4
4
|
import { and, eq } from "drizzle-orm";
|
|
5
5
|
|
|
6
|
+
/**
|
|
7
|
+
* The subject these guards read history for. `contactId` is REQUIRED (not
|
|
8
|
+
* optional) for the same reason `ConditionContext.contactId` is: an optional
|
|
9
|
+
* field silently defaults a new caller onto the mutable text key, which is
|
|
10
|
+
* exactly the entry-limit miss this batch exists to close. Pass `null`
|
|
11
|
+
* explicitly for a subject with no contact — a permanent, supported state (the
|
|
12
|
+
* engine refuses to mint a contact on observation).
|
|
13
|
+
*/
|
|
6
14
|
export async function checkEntryLimit(opts: {
|
|
7
15
|
db: Database;
|
|
8
16
|
journey: JourneyMeta;
|
|
9
17
|
userId: string;
|
|
18
|
+
contactId: string | null;
|
|
10
19
|
}): Promise<{ allowed: boolean; reason?: string }> {
|
|
11
|
-
const { db, journey, userId } = opts;
|
|
20
|
+
const { db, journey, userId, contactId } = opts;
|
|
12
21
|
if (journey.entryLimit === "unlimited") return { allowed: true };
|
|
13
22
|
|
|
23
|
+
const subject = bySubject(journeyStates, { contactId, userKey: userId });
|
|
24
|
+
|
|
14
25
|
if (journey.entryLimit === "once") {
|
|
15
26
|
const existing = await db.query.journeyStates.findFirst({
|
|
16
|
-
where: and(
|
|
17
|
-
eq(journeyStates.userId, userId),
|
|
18
|
-
eq(journeyStates.journeyId, journey.id),
|
|
19
|
-
),
|
|
27
|
+
where: and(subject, eq(journeyStates.journeyId, journey.id)),
|
|
20
28
|
});
|
|
21
29
|
return existing
|
|
22
30
|
? { allowed: false, reason: "already_entered_once" }
|
|
@@ -28,10 +36,7 @@ export async function checkEntryLimit(opts: {
|
|
|
28
36
|
const cutoff = new Date(Date.now() - periodMs);
|
|
29
37
|
|
|
30
38
|
const existing = await db.query.journeyStates.findFirst({
|
|
31
|
-
where: and(
|
|
32
|
-
eq(journeyStates.userId, userId),
|
|
33
|
-
eq(journeyStates.journeyId, journey.id),
|
|
34
|
-
),
|
|
39
|
+
where: and(subject, eq(journeyStates.journeyId, journey.id)),
|
|
35
40
|
orderBy: (states, { desc }) => [desc(states.createdAt)],
|
|
36
41
|
});
|
|
37
42
|
|
|
@@ -43,13 +48,15 @@ export async function checkEntryLimit(opts: {
|
|
|
43
48
|
return { allowed: true };
|
|
44
49
|
}
|
|
45
50
|
|
|
51
|
+
/** See {@link checkEntryLimit} for why `contactId` is required. */
|
|
46
52
|
export async function checkEmailPreferences(opts: {
|
|
47
53
|
db: Database;
|
|
48
54
|
userId: string;
|
|
55
|
+
contactId: string | null;
|
|
49
56
|
}): Promise<{ unsubscribed: boolean }> {
|
|
50
|
-
const { db, userId } = opts;
|
|
57
|
+
const { db, userId, contactId } = opts;
|
|
51
58
|
const prefs = await db.query.emailPreferences.findFirst({
|
|
52
|
-
where:
|
|
59
|
+
where: bySubject(emailPreferences, { contactId, userKey: userId }),
|
|
53
60
|
});
|
|
54
61
|
|
|
55
62
|
return { unsubscribed: prefs?.unsubscribedAll ?? false };
|
package/src/lib/feed.ts
CHANGED
|
@@ -312,7 +312,7 @@ export async function sendFeedItem(
|
|
|
312
312
|
// channel list regardless of the item's own category.
|
|
313
313
|
//
|
|
314
314
|
// The preference read is the UNIFIED aggregated `readRecipientPreferences`
|
|
315
|
-
// keyed by BOTH the recipient's `
|
|
315
|
+
// keyed by BOTH the recipient's resolved `contact_id` AND its email —
|
|
316
316
|
// NOT the old single-row `(extId, email)` lookup. This is a deliberate,
|
|
317
317
|
// suppression-conservative behaviour change: an `unsubscribed_all` (or category
|
|
318
318
|
// opt-out) imported before the contact existed and keyed `(email, email)` now
|
|
@@ -333,12 +333,12 @@ export async function sendFeedItem(
|
|
|
333
333
|
userId: recipient.userId,
|
|
334
334
|
email: recipient.email,
|
|
335
335
|
});
|
|
336
|
-
//
|
|
337
|
-
//
|
|
338
|
-
|
|
336
|
+
// PRD 05 T6 — contact-scoped read (the resolved contact id IS the subject);
|
|
337
|
+
// the old `external_id ?? contact_id` string derivation is retired. Null
|
|
338
|
+
// for an anon recipient: email leg only, same as before.
|
|
339
339
|
const prefs = await readRecipientPreferences(db, {
|
|
340
340
|
email: recip?.email,
|
|
341
|
-
|
|
341
|
+
contactId: recip?.contactId ?? null,
|
|
342
342
|
});
|
|
343
343
|
// `unsubscribed_all` on an IDENTIFIED recipient suppresses (consistent with
|
|
344
344
|
// the email mailer's `checkEmailPreferences`); guarded on `recip` so an
|
package/src/lib/flags.ts
CHANGED
|
@@ -6,7 +6,11 @@ import type {
|
|
|
6
6
|
FlagVariant,
|
|
7
7
|
PropertyCondition,
|
|
8
8
|
} from "@hogsend/core";
|
|
9
|
-
import {
|
|
9
|
+
import {
|
|
10
|
+
bySubject,
|
|
11
|
+
evaluateCondition,
|
|
12
|
+
evaluatePropertyConditions,
|
|
13
|
+
} from "@hogsend/core";
|
|
10
14
|
import {
|
|
11
15
|
bucketMemberships,
|
|
12
16
|
contacts,
|
|
@@ -72,12 +76,13 @@ export function emptySnapshot(
|
|
|
72
76
|
}
|
|
73
77
|
|
|
74
78
|
/**
|
|
75
|
-
* Load the FIXED ~4-query targeting snapshot for a contact. `
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
79
|
+
* Load the FIXED ~4-query targeting snapshot for a contact. `contactId` is the
|
|
80
|
+
* trusted uuid: it scopes the property + deal reads (see
|
|
81
|
+
* `evaluateFlagsForContact`'s security note) AND, via `bySubject`, the bucket +
|
|
82
|
+
* journey history reads. `contactKey` (`external_id ?? anonymous_id ?? id`) is
|
|
83
|
+
* the fallback those two history reads use when NO contact is resolved — an
|
|
84
|
+
* anonymous visitor, whose rows are still text-keyed. An anon contact with no
|
|
85
|
+
* rows yields empty sets — correct (targeting-gated flags fall to default).
|
|
81
86
|
*/
|
|
82
87
|
export async function loadTargetingSnapshot(opts: {
|
|
83
88
|
db: Database;
|
|
@@ -99,7 +104,7 @@ export async function loadTargetingSnapshot(opts: {
|
|
|
99
104
|
.from(bucketMemberships)
|
|
100
105
|
.where(
|
|
101
106
|
and(
|
|
102
|
-
|
|
107
|
+
bySubject(bucketMemberships, { contactId, userKey: contactKey }),
|
|
103
108
|
eq(bucketMemberships.status, "active"),
|
|
104
109
|
isNull(bucketMemberships.deletedAt),
|
|
105
110
|
),
|
|
@@ -110,7 +115,7 @@ export async function loadTargetingSnapshot(opts: {
|
|
|
110
115
|
status: journeyStates.status,
|
|
111
116
|
})
|
|
112
117
|
.from(journeyStates)
|
|
113
|
-
.where(
|
|
118
|
+
.where(bySubject(journeyStates, { contactId, userKey: contactKey })),
|
|
114
119
|
contactId
|
|
115
120
|
? db
|
|
116
121
|
.select({
|
|
@@ -183,6 +188,14 @@ export interface TargetingEvalContext {
|
|
|
183
188
|
mode: "browser" | "server";
|
|
184
189
|
db?: Database;
|
|
185
190
|
userId?: string;
|
|
191
|
+
/**
|
|
192
|
+
* The SERVER-TRUSTED `contacts.id` for `userId`, forwarded verbatim to
|
|
193
|
+
* `ConditionContext.contactId` so a scan leaf reads the PERSON's history
|
|
194
|
+
* rather than whatever the mutable `userId` text key happens to name. Absent
|
|
195
|
+
* / null for a subject with no contact (an anonymous visitor), which keeps
|
|
196
|
+
* the scan on the text key exactly as before.
|
|
197
|
+
*/
|
|
198
|
+
contactId?: string | null;
|
|
186
199
|
}
|
|
187
200
|
|
|
188
201
|
/**
|
|
@@ -272,6 +285,7 @@ export async function evaluateTargeting(
|
|
|
272
285
|
ctx: {
|
|
273
286
|
db: ctx.db,
|
|
274
287
|
userId: ctx.userId,
|
|
288
|
+
contactId: ctx.contactId ?? null,
|
|
275
289
|
// `email_engagement` leaves look up `email_sends.to_email` — key it on the
|
|
276
290
|
// contact's ACTUAL email (from the loaded snapshot), never the contactKey
|
|
277
291
|
// (which is external_id/anonymous_id/id, never an address).
|
|
@@ -426,6 +440,7 @@ async function evaluateFlagResolved(
|
|
|
426
440
|
mode: "browser" | "server";
|
|
427
441
|
db?: Database;
|
|
428
442
|
userId?: string;
|
|
443
|
+
contactId?: string | null;
|
|
429
444
|
},
|
|
430
445
|
): Promise<unknown> {
|
|
431
446
|
if (!flag.enabled) return flag.defaultValue;
|
|
@@ -435,6 +450,7 @@ async function evaluateFlagResolved(
|
|
|
435
450
|
mode: ctx.mode,
|
|
436
451
|
db: ctx.db,
|
|
437
452
|
userId: ctx.userId,
|
|
453
|
+
contactId: ctx.contactId,
|
|
438
454
|
};
|
|
439
455
|
const sets = resolveConditionSets(flag);
|
|
440
456
|
for (let i = 0; i < sets.length; i++) {
|
|
@@ -492,6 +508,7 @@ export async function evaluateFlagsForContact(opts: {
|
|
|
492
508
|
mode,
|
|
493
509
|
db: mode === "server" ? db : undefined,
|
|
494
510
|
userId: mode === "server" ? contactKey : undefined,
|
|
511
|
+
contactId: mode === "server" ? (contactId ?? null) : null,
|
|
495
512
|
});
|
|
496
513
|
}
|
|
497
514
|
return result;
|
package/src/lib/ingestion.ts
CHANGED
|
@@ -5,7 +5,7 @@ import type {
|
|
|
5
5
|
GroupsAssociation,
|
|
6
6
|
PropertyCondition,
|
|
7
7
|
} from "@hogsend/core";
|
|
8
|
-
import { evaluatePropertyConditions } from "@hogsend/core";
|
|
8
|
+
import { bySubject, evaluatePropertyConditions } from "@hogsend/core";
|
|
9
9
|
import type { JourneyRegistry } from "@hogsend/core/registry";
|
|
10
10
|
import type { JourneyMeta } from "@hogsend/core/types";
|
|
11
11
|
import {
|
|
@@ -728,6 +728,7 @@ export async function ingestEvent(opts: {
|
|
|
728
728
|
}),
|
|
729
729
|
checkExits(db, registry, hatchet, logger, {
|
|
730
730
|
userId: resolvedKey,
|
|
731
|
+
contactId,
|
|
731
732
|
eventName: event.event,
|
|
732
733
|
properties: event.eventProperties,
|
|
733
734
|
}),
|
|
@@ -854,6 +855,7 @@ export async function ingestEvent(opts: {
|
|
|
854
855
|
logger,
|
|
855
856
|
conversionId: firedConversion.conversionId,
|
|
856
857
|
userKey: resolvedKey,
|
|
858
|
+
contactId,
|
|
857
859
|
value: firedConversion.value,
|
|
858
860
|
currency: firedConversion.currency,
|
|
859
861
|
occurredAt: insertedRow.occurredAt,
|
|
@@ -998,6 +1000,13 @@ async function checkExits(
|
|
|
998
1000
|
logger: Logger,
|
|
999
1001
|
event: {
|
|
1000
1002
|
userId: string;
|
|
1003
|
+
/**
|
|
1004
|
+
* The subject's resolved `contacts.id`, or `null` when the resolve refused
|
|
1005
|
+
* to mint one (an anonymous visitor — a permanent supported state). The
|
|
1006
|
+
* scan MUST still exit that population's journeys, which is why this goes
|
|
1007
|
+
* through `bySubject` rather than a bare `contact_id` predicate.
|
|
1008
|
+
*/
|
|
1009
|
+
contactId: string | null;
|
|
1001
1010
|
eventName: string;
|
|
1002
1011
|
properties: Record<string, unknown>;
|
|
1003
1012
|
},
|
|
@@ -1006,7 +1015,10 @@ async function checkExits(
|
|
|
1006
1015
|
|
|
1007
1016
|
const activeStates = await db.query.journeyStates.findMany({
|
|
1008
1017
|
where: and(
|
|
1009
|
-
|
|
1018
|
+
bySubject(journeyStates, {
|
|
1019
|
+
contactId: event.contactId,
|
|
1020
|
+
userKey: event.userId,
|
|
1021
|
+
}),
|
|
1010
1022
|
inArray(journeyStates.status, ["active", "waiting"]),
|
|
1011
1023
|
isNull(journeyStates.deletedAt),
|
|
1012
1024
|
),
|
package/src/lib/journey-lift.ts
CHANGED
|
@@ -61,22 +61,34 @@ export async function computeJourneyLift(
|
|
|
61
61
|
|
|
62
62
|
// Outcome: the contact fired ≥1 qualifying conversion AFTER their state
|
|
63
63
|
// row was created (post-assignment — the intent-to-treat clock) and at
|
|
64
|
-
// or before the asOf snapshot instant.
|
|
64
|
+
// or before the asOf snapshot instant. Joined on the contact FK, not the
|
|
65
|
+
// text key: `conversions.contact_id` is NOT NULL, so a conversion always
|
|
66
|
+
// belongs to a resolved contact and no text fallback is needed — a
|
|
67
|
+
// contactless enrollment has no contact, therefore no conversion, and the
|
|
68
|
+
// NULL comparison correctly matches nothing. The old `c.user_key =
|
|
69
|
+
// js.user_id` string compare missed every conversion recorded under a key
|
|
70
|
+
// the person moved off after enrolling, under-counting converters.
|
|
65
71
|
const convertedSql = sql`exists (
|
|
66
72
|
select 1 from conversions c
|
|
67
|
-
where c.
|
|
73
|
+
where c.contact_id = ${journeyStates.contactId}
|
|
68
74
|
and c.occurred_at >= ${journeyStates.createdAt}
|
|
69
75
|
and c.occurred_at <= ${asOfTs}${definitionSql}
|
|
70
76
|
)`;
|
|
71
77
|
|
|
78
|
+
// WHO a row is about — the owning contact when stamped, else the mutable
|
|
79
|
+
// text key. The coalesce is load-bearing: `count(distinct …)` skips NULLs,
|
|
80
|
+
// so a bare `contact_id` would silently drop every contactless enrollment
|
|
81
|
+
// from the denominator and read as a quiet journey rather than a bug.
|
|
82
|
+
const subjectSql = sql`coalesce(${journeyStates.contactId}::text, ${journeyStates.userId})`;
|
|
83
|
+
|
|
72
84
|
const cohort = async (control: boolean): Promise<LiftCohort> => {
|
|
73
85
|
const statusFilter = control
|
|
74
86
|
? eq(journeyStates.status, "held_out")
|
|
75
87
|
: sql`${journeyStates.status} != 'held_out'`;
|
|
76
88
|
const [row] = await db
|
|
77
89
|
.select({
|
|
78
|
-
contacts: sql<number>`count(distinct ${
|
|
79
|
-
converters: sql<number>`(count(distinct ${
|
|
90
|
+
contacts: sql<number>`count(distinct ${subjectSql})::int`,
|
|
91
|
+
converters: sql<number>`(count(distinct ${subjectSql}) filter (where ${convertedSql}))::int`,
|
|
80
92
|
})
|
|
81
93
|
.from(journeyStates)
|
|
82
94
|
.where(
|
|
@@ -125,7 +137,7 @@ export async function computeLiftValues(opts: LiftQueryOpts): Promise<{
|
|
|
125
137
|
and js.created_at >= ${sinceTs}
|
|
126
138
|
and js.created_at < ${asOfTs}
|
|
127
139
|
and ${control ? sql`js.status = 'held_out'` : sql`js.status != 'held_out'`}
|
|
128
|
-
and js.
|
|
140
|
+
and js.contact_id = c.contact_id
|
|
129
141
|
and c.occurred_at >= js.created_at
|
|
130
142
|
)${definitionSql}
|
|
131
143
|
group by c.currency
|
package/src/lib/preferences.ts
CHANGED
|
@@ -1,10 +1,14 @@
|
|
|
1
1
|
import type { Database } from "@hogsend/db";
|
|
2
2
|
import { emailPreferences } from "@hogsend/db";
|
|
3
|
-
import { sql } from "drizzle-orm";
|
|
3
|
+
import { and, eq, sql } from "drizzle-orm";
|
|
4
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";
|
|
8
|
+
import {
|
|
9
|
+
isUniqueViolationOn,
|
|
10
|
+
UQ_CONTACT_EMAIL_PREFERENCES,
|
|
11
|
+
} from "./unique-violation.js";
|
|
8
12
|
|
|
9
13
|
export {
|
|
10
14
|
type RecipientPreferences,
|
|
@@ -113,34 +117,79 @@ export async function upsertEmailPreference(opts: {
|
|
|
113
117
|
setClause.categories = sql`jsonb_set(COALESCE(${emailPreferences.categories}, '{}'::jsonb), ${`{${update.categoryKey}}`}, ${jsonValue}::jsonb)`;
|
|
114
118
|
}
|
|
115
119
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
120
|
+
const upsertOnStringKey = () =>
|
|
121
|
+
db
|
|
122
|
+
.insert(emailPreferences)
|
|
123
|
+
.values({
|
|
124
|
+
userId: externalId,
|
|
125
|
+
email,
|
|
126
|
+
contactId,
|
|
127
|
+
...(update.unsubscribedAll !== undefined
|
|
128
|
+
? { unsubscribedAll: update.unsubscribedAll }
|
|
129
|
+
: {}),
|
|
130
|
+
...(update.suppressed !== undefined
|
|
131
|
+
? { suppressed: update.suppressed }
|
|
132
|
+
: {}),
|
|
133
|
+
...(update.suppressedAt !== undefined
|
|
134
|
+
? { suppressedAt: update.suppressedAt }
|
|
135
|
+
: {}),
|
|
136
|
+
...(update.recordBounce
|
|
137
|
+
? { bounceCount: 1, lastBounceAt: new Date() }
|
|
138
|
+
: {}),
|
|
139
|
+
...(update.categoryKey !== undefined
|
|
140
|
+
? {
|
|
141
|
+
categories: {
|
|
142
|
+
[update.categoryKey]: update.categoryValue ?? false,
|
|
143
|
+
},
|
|
144
|
+
}
|
|
145
|
+
: {}),
|
|
146
|
+
})
|
|
147
|
+
.onConflictDoUpdate({
|
|
148
|
+
target: [emailPreferences.userId, emailPreferences.email],
|
|
149
|
+
set: setClause,
|
|
150
|
+
});
|
|
151
|
+
|
|
152
|
+
try {
|
|
153
|
+
await upsertOnStringKey();
|
|
154
|
+
} catch (err) {
|
|
155
|
+
// PRD 05 T3 — the arbiter STAYS on (user_id, email); the contact-scoped
|
|
156
|
+
// index is a pure constraint (drizzle targets columns only, and a bare
|
|
157
|
+
// (contact_id, email) arbiter would never fire for the contactless
|
|
158
|
+
// population — a D6-degraded NULL resolve is legal and permanent). So the
|
|
159
|
+
// one collision the string arbiter cannot see — SAME contact, SAME address,
|
|
160
|
+
// DIFFERENT `user_id` string, which is exactly what adoption produces when
|
|
161
|
+
// it stamps `contact_id` without rewriting `user_id` — arrives here as a
|
|
162
|
+
// 23505 and is converted into the update path by hand.
|
|
163
|
+
if (!contactId || !isUniqueViolationOn(err, UQ_CONTACT_EMAIL_PREFERENCES)) {
|
|
164
|
+
throw err;
|
|
165
|
+
}
|
|
166
|
+
// `contactId` is dropped from the set: it only existed to carry the
|
|
167
|
+
// `excluded.contact_id` coalesce, which has no meaning outside ON CONFLICT,
|
|
168
|
+
// and the row we are about to update already holds THIS id (that is how it
|
|
169
|
+
// collided). Every other entry references the table column, which is legal
|
|
170
|
+
// on the right-hand side of a plain UPDATE.
|
|
171
|
+
const { contactId: _excludedCoalesce, ...contactScopedSet } = setClause;
|
|
172
|
+
const converted = await db
|
|
173
|
+
.update(emailPreferences)
|
|
174
|
+
.set(contactScopedSet)
|
|
175
|
+
.where(
|
|
176
|
+
and(
|
|
177
|
+
eq(emailPreferences.contactId, contactId),
|
|
178
|
+
eq(emailPreferences.email, email),
|
|
179
|
+
),
|
|
180
|
+
)
|
|
181
|
+
.returning({ id: emailPreferences.id });
|
|
182
|
+
|
|
183
|
+
// ZERO rows means the conflicting row vanished between the INSERT and this
|
|
184
|
+
// UPDATE — a concurrent merge folded it away (`foldEmailPreferences` hard-
|
|
185
|
+
// deletes the row it absorbed) or re-pointed its `contact_id`. Accepting
|
|
186
|
+
// that silently DROPS the write while the emit below still announces an
|
|
187
|
+
// opt-out that never landed. The conflicting row is gone, so the original
|
|
188
|
+
// arbiter INSERT now has somewhere to go: retry it ONCE. A second 23505
|
|
189
|
+
// means another writer re-created the row in this same gap — that throws,
|
|
190
|
+
// which is the loud answer, not a silent loss.
|
|
191
|
+
if (converted.length === 0) await upsertOnStringKey();
|
|
192
|
+
}
|
|
144
193
|
|
|
145
194
|
// OUTBOUND `contact.unsubscribed` — this is the SINGLE choke for ALL preference
|
|
146
195
|
// writes (token unsub, preference center, list-membership flips), so the emit
|
|
@@ -15,16 +15,30 @@ export interface RecipientPreferences {
|
|
|
15
15
|
* Read the conservative preference verdict shared by email, feed, and
|
|
16
16
|
* connector delivery. This module intentionally contains no Hatchet/runtime
|
|
17
17
|
* imports so journey authoring modules remain safe to load in unit tests.
|
|
18
|
+
*
|
|
19
|
+
* The subject leg follows the `bySubject` law (PRD 05): when `contactId` is
|
|
20
|
+
* known, rows are matched by ownership stamp ONLY — never OR'd with the
|
|
21
|
+
* mutable string key, which goes stale the moment the contact adopts a new
|
|
22
|
+
* canonical key. `contactId` is REQUIRED (pass `null` explicitly for a
|
|
23
|
+
* contactless subject) so a new caller cannot silently default onto the
|
|
24
|
+
* string key. The email leg is orthogonal: address-scoped suppression
|
|
25
|
+
* (imports, bounces) predates the contact and stays an OR leg.
|
|
18
26
|
*/
|
|
19
27
|
export async function readRecipientPreferences(
|
|
20
28
|
db: Database,
|
|
21
|
-
keys: {
|
|
29
|
+
keys: {
|
|
30
|
+
email?: string | null;
|
|
31
|
+
userId?: string | null;
|
|
32
|
+
contactId: string | null;
|
|
33
|
+
},
|
|
22
34
|
): Promise<RecipientPreferences> {
|
|
23
35
|
const legs = [];
|
|
24
36
|
if (typeof keys.email === "string" && keys.email.length > 0) {
|
|
25
37
|
legs.push(eq(emailPreferences.email, keys.email));
|
|
26
38
|
}
|
|
27
|
-
if (
|
|
39
|
+
if (keys.contactId) {
|
|
40
|
+
legs.push(eq(emailPreferences.contactId, keys.contactId));
|
|
41
|
+
} else if (typeof keys.userId === "string" && keys.userId.length > 0) {
|
|
28
42
|
legs.push(eq(emailPreferences.userId, keys.userId));
|
|
29
43
|
}
|
|
30
44
|
|
package/src/lib/refine.ts
CHANGED
|
@@ -1,7 +1,11 @@
|
|
|
1
1
|
import { contacts, type Database } from "@hogsend/db";
|
|
2
2
|
import { and, eq, isNull, type SQL } from "drizzle-orm";
|
|
3
3
|
import { getJourneyRegistrySingleton } from "../journeys/registry-singleton.js";
|
|
4
|
-
import {
|
|
4
|
+
import {
|
|
5
|
+
contactKey,
|
|
6
|
+
lookupContactIdByKey,
|
|
7
|
+
normalizeEmail,
|
|
8
|
+
} from "./contacts.js";
|
|
5
9
|
import { getDb } from "./db.js";
|
|
6
10
|
import {
|
|
7
11
|
countEnrichmentLookups,
|
|
@@ -240,15 +244,17 @@ async function findContactRow(
|
|
|
240
244
|
if (row) return row;
|
|
241
245
|
}
|
|
242
246
|
if (keys.userId) {
|
|
243
|
-
// `userId` is the canonical key — external_id ?? anonymous_id ?? id —
|
|
244
|
-
//
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
247
|
+
// `userId` is the canonical key — external_id ?? anonymous_id ?? id — and
|
|
248
|
+
// `lookupContactIdByKey` owns that whole precedence: the three identity
|
|
249
|
+
// columns (uuid leg regex-guarded) and then the identity table. The alias
|
|
250
|
+
// leg is the new behaviour: a MERGED-AWAY key refines the SURVIVOR instead
|
|
251
|
+
// of missing (the loser's row is soft-deleted, invisible to any column
|
|
252
|
+
// probe). A key nothing owns still resolves nothing — the caller's
|
|
253
|
+
// email-only fallback above is untouched.
|
|
254
|
+
const contactId = await lookupContactIdByKey(db, keys.userId);
|
|
255
|
+
if (contactId) {
|
|
256
|
+
const row = await live(eq(contacts.id, contactId));
|
|
257
|
+
if (row) return row;
|
|
252
258
|
}
|
|
253
259
|
}
|
|
254
260
|
return null;
|
package/src/lib/revenue.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
+
import { bySubject } from "@hogsend/core";
|
|
1
2
|
import { type Database, userEvents } from "@hogsend/db";
|
|
2
3
|
import {
|
|
3
4
|
and,
|
|
4
5
|
count,
|
|
5
|
-
eq,
|
|
6
6
|
isNotNull,
|
|
7
7
|
isNull,
|
|
8
8
|
max,
|
|
@@ -77,13 +77,20 @@ export interface ContactRevenue {
|
|
|
77
77
|
}
|
|
78
78
|
|
|
79
79
|
/**
|
|
80
|
-
* Sum a contact's valued events, per currency. `
|
|
81
|
-
*
|
|
82
|
-
*
|
|
80
|
+
* Sum a contact's valued events, per currency. `contactId` is the trusted
|
|
81
|
+
* owner uuid and is REQUIRED (not optional) for the same reason the
|
|
82
|
+
* enrollment guards' is: an optional field silently defaults a new caller
|
|
83
|
+
* onto the mutable text key, so a contact whose valued events were ingested
|
|
84
|
+
* under an earlier key reports zero revenue. Pass `null` explicitly for a
|
|
85
|
+
* subject with no contact — a permanent, supported state (the engine refuses
|
|
86
|
+
* to mint a contact on observation), and the case `key` still serves. `key`
|
|
87
|
+
* is the canonical event key (`external_id ?? anonymous_id ?? id`) — the same
|
|
88
|
+
* key `ingestEvent` stamps on `user_events.user_id`.
|
|
83
89
|
*/
|
|
84
90
|
export async function getContactRevenue(opts: {
|
|
85
91
|
db: Database;
|
|
86
92
|
key: string;
|
|
93
|
+
contactId: string | null;
|
|
87
94
|
}): Promise<ContactRevenue> {
|
|
88
95
|
const rows = await opts.db
|
|
89
96
|
.select({
|
|
@@ -93,7 +100,15 @@ export async function getContactRevenue(opts: {
|
|
|
93
100
|
lastAt: max(userEvents.occurredAt),
|
|
94
101
|
})
|
|
95
102
|
.from(userEvents)
|
|
96
|
-
.where(
|
|
103
|
+
.where(
|
|
104
|
+
and(
|
|
105
|
+
bySubject(userEvents, {
|
|
106
|
+
contactId: opts.contactId,
|
|
107
|
+
userKey: opts.key,
|
|
108
|
+
}),
|
|
109
|
+
trustedValuedEventFilter(),
|
|
110
|
+
),
|
|
111
|
+
)
|
|
97
112
|
.groupBy(userEvents.currency);
|
|
98
113
|
|
|
99
114
|
let lastValuedAt: Date | null = null;
|
package/src/lib/sms-inbound.ts
CHANGED
|
@@ -167,6 +167,7 @@ async function flipContactChannel(
|
|
|
167
167
|
.select({
|
|
168
168
|
id: contacts.id,
|
|
169
169
|
externalId: contacts.externalId,
|
|
170
|
+
anonymousId: contacts.anonymousId,
|
|
170
171
|
email: contacts.email,
|
|
171
172
|
})
|
|
172
173
|
.from(contacts)
|
|
@@ -174,10 +175,14 @@ async function flipContactChannel(
|
|
|
174
175
|
.limit(1);
|
|
175
176
|
const contact = rows[0];
|
|
176
177
|
if (!contact?.email) return;
|
|
178
|
+
// PRD 07 T7: ownership rides `contactId`; the string key is a D9 echo of
|
|
179
|
+
// the full canonical derivation (the old inline `externalId ?? id` skipped
|
|
180
|
+
// `anonymousId`, mis-keying anon-only contacts onto their row uuid).
|
|
177
181
|
await upsertEmailPreference({
|
|
178
182
|
db,
|
|
179
|
-
externalId: contact.externalId ?? contact.id,
|
|
183
|
+
externalId: contact.externalId ?? contact.anonymousId ?? contact.id,
|
|
180
184
|
email: contact.email,
|
|
185
|
+
contactId: contact.id,
|
|
181
186
|
update: { categoryKey: SMS_CHANNEL_ID, categoryValue: subscribed },
|
|
182
187
|
source,
|
|
183
188
|
});
|
package/src/lib/sms-tracked.ts
CHANGED
|
@@ -17,6 +17,7 @@ import {
|
|
|
17
17
|
} from "../journeys/journey-boundary.js";
|
|
18
18
|
import { logTransition } from "../journeys/journey-log.js";
|
|
19
19
|
import { getListRegistry } from "../lists/registry-singleton.js";
|
|
20
|
+
import { lookupContactIdByKey } from "./contacts.js";
|
|
20
21
|
import type { FrequencyCapConfig } from "./email-service-types.js";
|
|
21
22
|
import { hatchet } from "./hatchet.js";
|
|
22
23
|
import { isGlobalControl } from "./holdout.js";
|
|
@@ -582,8 +583,24 @@ async function checkSmsSuppression(
|
|
|
582
583
|
if (phoneRow && phoneRow.resubscribedAt === null) return "suppressed";
|
|
583
584
|
const phoneConsent = phoneRow != null;
|
|
584
585
|
|
|
586
|
+
// PRD 05 T6 — resolve the subject's contact so the preference read follows
|
|
587
|
+
// the contact when the string key has gone stale (`sms_sends` carries no
|
|
588
|
+
// dual-write stamp, so the resolve happens here). D6-wrapped: a bookkeeping
|
|
589
|
+
// probe may never fail the suppression gate it rides on — a throw degrades
|
|
590
|
+
// to the string-key leg, never to an unchecked send.
|
|
591
|
+
let prefContactId: string | null = null;
|
|
592
|
+
if (opts.userId) {
|
|
593
|
+
try {
|
|
594
|
+
prefContactId = await lookupContactIdByKey(db, opts.userId);
|
|
595
|
+
} catch {
|
|
596
|
+
prefContactId = null;
|
|
597
|
+
}
|
|
598
|
+
}
|
|
585
599
|
const prefs = opts.userId
|
|
586
|
-
? await readRecipientPreferences(db, {
|
|
600
|
+
? await readRecipientPreferences(db, {
|
|
601
|
+
userId: opts.userId,
|
|
602
|
+
contactId: prefContactId,
|
|
603
|
+
})
|
|
587
604
|
: null;
|
|
588
605
|
if (prefs?.unsubscribedAll) return "unsubscribed";
|
|
589
606
|
|