@hogsend/engine 0.58.0 → 0.60.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 +19 -10
- package/src/buckets/check-membership.ts +61 -8
- package/src/buckets/membership-epoch.ts +11 -1
- package/src/campaigns/cohort-sql.ts +3 -0
- package/src/index.ts +26 -6
- package/src/journeys/execute-journey-run.ts +180 -29
- package/src/journeys/journey-context.ts +43 -7
- package/src/lib/agent/tools.ts +29 -4
- package/src/lib/attribution-backfill.ts +27 -4
- package/src/lib/attribution.ts +22 -3
- package/src/lib/connector-actions.ts +4 -1
- package/src/lib/contacts.ts +518 -148
- 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 +23 -2
- package/src/lib/journey-lift.ts +17 -5
- package/src/lib/preferences.ts +116 -30
- package/src/lib/recipient-preferences.ts +16 -2
- package/src/lib/revenue.ts +20 -5
- package/src/lib/sms-tracked.ts +18 -1
- package/src/lib/tracked.ts +50 -8
- package/src/lib/tracking-events.ts +28 -0
- package/src/lib/unique-violation.ts +44 -0
- package/src/routes/admin/buckets.ts +20 -2
- package/src/routes/admin/bulk.ts +18 -2
- package/src/routes/admin/contacts.ts +4 -3
- 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/index.ts +2 -0
- package/src/routes/admin/journey-impact.ts +18 -9
- package/src/routes/admin/journeys.ts +8 -1
- package/src/routes/admin/maintenance.ts +216 -0
- package/src/routes/admin/preferences.ts +85 -38
- 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/lists/index.ts +11 -6
- package/src/worker.ts +20 -0
- package/src/workflows/backfill-contact-id.ts +951 -0
- package/src/workflows/bucket-backfill.ts +145 -59
- package/src/workflows/bucket-reconcile.ts +154 -50
- 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 {
|
|
@@ -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 });
|
|
@@ -719,6 +728,7 @@ export async function ingestEvent(opts: {
|
|
|
719
728
|
}),
|
|
720
729
|
checkExits(db, registry, hatchet, logger, {
|
|
721
730
|
userId: resolvedKey,
|
|
731
|
+
contactId,
|
|
722
732
|
eventName: event.event,
|
|
723
733
|
properties: event.eventProperties,
|
|
724
734
|
}),
|
|
@@ -845,6 +855,7 @@ export async function ingestEvent(opts: {
|
|
|
845
855
|
logger,
|
|
846
856
|
conversionId: firedConversion.conversionId,
|
|
847
857
|
userKey: resolvedKey,
|
|
858
|
+
contactId,
|
|
848
859
|
value: firedConversion.value,
|
|
849
860
|
currency: firedConversion.currency,
|
|
850
861
|
occurredAt: insertedRow.occurredAt,
|
|
@@ -989,6 +1000,13 @@ async function checkExits(
|
|
|
989
1000
|
logger: Logger,
|
|
990
1001
|
event: {
|
|
991
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;
|
|
992
1010
|
eventName: string;
|
|
993
1011
|
properties: Record<string, unknown>;
|
|
994
1012
|
},
|
|
@@ -997,7 +1015,10 @@ async function checkExits(
|
|
|
997
1015
|
|
|
998
1016
|
const activeStates = await db.query.journeyStates.findMany({
|
|
999
1017
|
where: and(
|
|
1000
|
-
|
|
1018
|
+
bySubject(journeyStates, {
|
|
1019
|
+
contactId: event.contactId,
|
|
1020
|
+
userKey: event.userId,
|
|
1021
|
+
}),
|
|
1001
1022
|
inArray(journeyStates.status, ["active", "waiting"]),
|
|
1002
1023
|
isNull(journeyStates.deletedAt),
|
|
1003
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";
|
|
4
|
-
import { resolveRecipient } from "./contacts.js";
|
|
3
|
+
import { and, eq, sql } from "drizzle-orm";
|
|
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,
|
|
@@ -54,10 +58,46 @@ export async function upsertEmailPreference(opts: {
|
|
|
54
58
|
* TCPA record-keeping is the "how" as much as the "when".
|
|
55
59
|
*/
|
|
56
60
|
source?: string;
|
|
61
|
+
/**
|
|
62
|
+
* PRD 04 dual-write: the `contacts.id` owning `externalId`.
|
|
63
|
+
*
|
|
64
|
+
* `undefined` (the default, and every caller that has nothing in hand) ⇒ this
|
|
65
|
+
* function does ONE D6-wrapped lookup itself. An EXPLICIT value — including
|
|
66
|
+
* an explicit `null` — is used verbatim, so a caller that already resolved
|
|
67
|
+
* the contact (the lists route, one line after `resolveOrCreateContact`) pays
|
|
68
|
+
* no second query and cannot disagree with itself.
|
|
69
|
+
*/
|
|
70
|
+
contactId?: string | null;
|
|
57
71
|
}): Promise<void> {
|
|
58
72
|
const { db, externalId, email, update } = opts;
|
|
59
73
|
|
|
60
|
-
|
|
74
|
+
// D6 — the resolve may never fail the preference write it rides on: a throw
|
|
75
|
+
// degrades to NULL + a warn. The probe is paid ONLY when the caller supplied
|
|
76
|
+
// nothing; the discriminant is `undefined` (not falsiness), so an EXPLICIT
|
|
77
|
+
// null stays an explicit null rather than triggering a lookup.
|
|
78
|
+
let contactId: string | null = null;
|
|
79
|
+
if (opts.contactId !== undefined) {
|
|
80
|
+
contactId = opts.contactId;
|
|
81
|
+
} else {
|
|
82
|
+
try {
|
|
83
|
+
contactId = await lookupContactIdByKey(db, externalId);
|
|
84
|
+
} catch (err) {
|
|
85
|
+
logger.warn("email_preferences contact_id dual-write resolve failed", {
|
|
86
|
+
externalId,
|
|
87
|
+
error: err instanceof Error ? err.message : String(err),
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
const setClause: Record<string, unknown> = {
|
|
93
|
+
updatedAt: new Date(),
|
|
94
|
+
// FILL-IF-KNOWN, NEVER NULL-OUT (house precedent: the fill-if-absent
|
|
95
|
+
// refinement, PR #615). The conflict arm takes the incoming id when there is
|
|
96
|
+
// one and otherwise KEEPS what the row already carries — so a failed or
|
|
97
|
+
// impossible resolve on a later write can never erase a `contact_id` an
|
|
98
|
+
// earlier write successfully stamped.
|
|
99
|
+
contactId: sql`coalesce(excluded.contact_id, ${emailPreferences.contactId})`,
|
|
100
|
+
};
|
|
61
101
|
|
|
62
102
|
if (update.unsubscribedAll !== undefined) {
|
|
63
103
|
setClause.unsubscribedAll = update.unsubscribedAll;
|
|
@@ -77,33 +117,79 @@ export async function upsertEmailPreference(opts: {
|
|
|
77
117
|
setClause.categories = sql`jsonb_set(COALESCE(${emailPreferences.categories}, '{}'::jsonb), ${`{${update.categoryKey}}`}, ${jsonValue}::jsonb)`;
|
|
78
118
|
}
|
|
79
119
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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
|
+
}
|
|
107
193
|
|
|
108
194
|
// OUTBOUND `contact.unsubscribed` — this is the SINGLE choke for ALL preference
|
|
109
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/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-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
|
|