@hogsend/engine 0.46.0 → 0.50.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/README.md +6 -0
- package/package.json +13 -10
- package/src/connectors/presets/index.ts +8 -2
- package/src/container.ts +149 -7
- package/src/destinations/presets/posthog.ts +7 -0
- package/src/destinations/presets/segment.ts +5 -0
- package/src/env.ts +38 -0
- package/src/flags/reconcile.ts +195 -0
- package/src/index.ts +79 -0
- package/src/journeys/authoring.ts +32 -0
- package/src/journeys/define-journey.ts +45 -40
- package/src/journeys/execute-journey-run.ts +73 -32
- package/src/journeys/journey-boundary.ts +76 -0
- package/src/journeys/journey-context.ts +128 -70
- package/src/journeys/journey-task-factory.ts +31 -0
- package/src/journeys/journey-task-runtime.ts +31 -0
- package/src/journeys/journey-version.test.ts +236 -0
- package/src/journeys/journey-version.ts +158 -0
- package/src/journeys/record-once.ts +28 -2
- package/src/lib/connector-actions.test.ts +36 -0
- package/src/lib/connector-actions.ts +42 -4
- package/src/lib/contacts.ts +49 -0
- package/src/lib/conversions.test.ts +33 -0
- package/src/lib/conversions.ts +8 -0
- package/src/lib/email.ts +23 -2
- package/src/lib/enrollment-policy.ts +51 -0
- package/src/lib/feed.ts +55 -3
- package/src/lib/flags-registry.ts +48 -0
- package/src/lib/flags.ts +498 -0
- package/src/lib/fx.ts +374 -0
- package/src/lib/global-control-readout.ts +166 -0
- package/src/lib/groups.ts +362 -0
- package/src/lib/ingestion.ts +38 -0
- package/src/lib/journey-lift.ts +142 -0
- package/src/lib/operator-settings.ts +71 -0
- package/src/lib/outbound.ts +147 -0
- package/src/lib/preferences.ts +6 -80
- package/src/lib/recipient-preferences.ts +53 -0
- package/src/lib/sms.ts +21 -2
- package/src/lib/stable-stringify.test.ts +42 -0
- package/src/lib/stable-stringify.ts +23 -0
- package/src/lib/variant.ts +99 -0
- package/src/lib/webhook-signing.ts +16 -1
- package/src/lists/registry.ts +6 -2
- package/src/lists/subscription.ts +13 -0
- package/src/routes/admin/contacts.ts +53 -4
- package/src/routes/admin/conversions.ts +137 -0
- package/src/routes/admin/flags.ts +369 -0
- package/src/routes/admin/groups.ts +866 -0
- package/src/routes/admin/impact-schemas.ts +44 -0
- package/src/routes/admin/impact-wire.test.ts +181 -0
- package/src/routes/admin/impact.ts +486 -0
- package/src/routes/admin/index.ts +12 -0
- package/src/routes/admin/journey-impact.ts +446 -0
- package/src/routes/admin/journeys.ts +70 -100
- package/src/routes/admin/readiness.ts +8 -8
- package/src/routes/admin/settings.ts +145 -0
- package/src/routes/admin/targeting.ts +256 -0
- package/src/routes/events/index.ts +11 -0
- package/src/routes/flags/index.ts +120 -0
- package/src/routes/groups/index.ts +417 -0
- package/src/routes/index.ts +23 -1
- package/src/testing.ts +25 -0
- package/src/webhook-sources/presets/index.ts +5 -1
- package/src/webhook-sources/presets/intercom.ts +230 -0
- package/src/webhook-sources/presets/segment.ts +56 -4
- package/src/worker.ts +3 -0
- package/src/workflows/bucket-backfill.ts +1 -14
- package/src/workflows/impact-digest.ts +761 -0
- package/src/workflows/journey-blueprint-interpreter.ts +18 -1
|
@@ -0,0 +1,362 @@
|
|
|
1
|
+
import type { AnalyticsProvider, Group, GroupMembership } from "@hogsend/core";
|
|
2
|
+
import { contacts, type Database, groupMemberships, groups } from "@hogsend/db";
|
|
3
|
+
import { and, desc, eq, isNull, sql } from "drizzle-orm";
|
|
4
|
+
import { getAnalytics } from "./analytics-singleton.js";
|
|
5
|
+
import type { Logger } from "./logger.js";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Sovereign, DB-first group helpers — Hogsend's standalone answer to PostHog
|
|
9
|
+
* group analytics. Every function is single-object-in / result-object-out with
|
|
10
|
+
* `db` injected, mirroring the house style in {@link file://./contacts.ts}.
|
|
11
|
+
*
|
|
12
|
+
* A group is identified by its `(groupType, groupKey)` natural key. The `groups`
|
|
13
|
+
* unique index is PARTIAL (`WHERE deleted_at IS NULL`), so every upsert MUST
|
|
14
|
+
* name that predicate as the conflict arbiter — see {@link identifyGroup}.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Thrown by {@link addGroupMember} when the target contact does not exist (or is
|
|
19
|
+
* soft-deleted). Signalled BEFORE the group is resolve-or-created, so a bad
|
|
20
|
+
* contact id never mints an orphan group; the route catches it → 404. Mirrors
|
|
21
|
+
* the typed-error pattern in {@link file://./contacts.ts}
|
|
22
|
+
* (`PublishableAnonymousMergeError`).
|
|
23
|
+
*/
|
|
24
|
+
export class GroupContactNotFoundError extends Error {
|
|
25
|
+
constructor(public readonly contactId: string) {
|
|
26
|
+
super(`Contact not found: ${contactId}`);
|
|
27
|
+
this.name = "GroupContactNotFoundError";
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** Rows returned by drizzle's select match the portable `Group` shape 1:1. */
|
|
32
|
+
type GroupRow = typeof groups.$inferSelect;
|
|
33
|
+
|
|
34
|
+
/** Clamp a caller-supplied page size to a sane default + hard cap. */
|
|
35
|
+
function clampLimit(
|
|
36
|
+
limit: number | undefined,
|
|
37
|
+
fallback = 50,
|
|
38
|
+
cap = 200,
|
|
39
|
+
): number {
|
|
40
|
+
if (limit === undefined || !Number.isFinite(limit) || limit <= 0) {
|
|
41
|
+
return fallback;
|
|
42
|
+
}
|
|
43
|
+
return Math.min(Math.floor(limit), cap);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** Non-negative page offset. */
|
|
47
|
+
function clampOffset(offset: number | undefined): number {
|
|
48
|
+
if (offset === undefined || !Number.isFinite(offset) || offset <= 0) return 0;
|
|
49
|
+
return Math.floor(offset);
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* Identify (upsert) a group by its `(groupType, groupKey)` natural key and,
|
|
54
|
+
* best-effort, mirror the property WRITE to the active analytics provider
|
|
55
|
+
* (PostHog `groupIdentify`).
|
|
56
|
+
*
|
|
57
|
+
* CRITICAL — the `groups_type_key_unique_idx` unique index is PARTIAL
|
|
58
|
+
* (`WHERE deleted_at IS NULL`). For `onConflictDoUpdate` the arbiter predicate
|
|
59
|
+
* matching that partial index goes in **`targetWhere`** (NOT `where`, which is
|
|
60
|
+
* ambiguous and silently misbehaves → duplicate rows / 42P10). On conflict we
|
|
61
|
+
* MERGE properties with the exact jsonb idiom `contacts.ts` uses
|
|
62
|
+
* (`coalesce(existing,'{}'::jsonb) || <new>::jsonb`, new wins), COALESCE the
|
|
63
|
+
* displayName (a caller who omits it never nulls an existing name), and bump
|
|
64
|
+
* `lastSeenAt` + `updatedAt`; `firstSeenAt` is preserved.
|
|
65
|
+
*/
|
|
66
|
+
export async function identifyGroup(opts: {
|
|
67
|
+
db: Database;
|
|
68
|
+
groupType: string;
|
|
69
|
+
groupKey: string;
|
|
70
|
+
displayName?: string;
|
|
71
|
+
properties?: Record<string, unknown>;
|
|
72
|
+
organizationId?: string;
|
|
73
|
+
analytics?: AnalyticsProvider;
|
|
74
|
+
logger?: Logger;
|
|
75
|
+
}): Promise<{ group: Group }> {
|
|
76
|
+
const { db, groupType, groupKey, displayName, properties, organizationId } =
|
|
77
|
+
opts;
|
|
78
|
+
const now = new Date();
|
|
79
|
+
|
|
80
|
+
const updateSet: Record<string, unknown> = {
|
|
81
|
+
lastSeenAt: now,
|
|
82
|
+
updatedAt: now,
|
|
83
|
+
};
|
|
84
|
+
// Merge only when properties were supplied — an association-only upsert
|
|
85
|
+
// (associateGroups / resolveGroupId) must not rewrite the property bag.
|
|
86
|
+
if (properties) {
|
|
87
|
+
updateSet.properties = sql`coalesce(${groups.properties}, '{}'::jsonb) || ${JSON.stringify(properties)}::jsonb`;
|
|
88
|
+
}
|
|
89
|
+
// COALESCE displayName: only set when the caller supplied one, so an omitted
|
|
90
|
+
// name never clobbers an existing one.
|
|
91
|
+
if (displayName !== undefined) {
|
|
92
|
+
updateSet.displayName = displayName;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
const inserted = await db
|
|
96
|
+
.insert(groups)
|
|
97
|
+
.values({
|
|
98
|
+
groupType,
|
|
99
|
+
groupKey,
|
|
100
|
+
displayName: displayName ?? null,
|
|
101
|
+
properties: properties ?? {},
|
|
102
|
+
organizationId: organizationId ?? null,
|
|
103
|
+
firstSeenAt: now,
|
|
104
|
+
lastSeenAt: now,
|
|
105
|
+
})
|
|
106
|
+
.onConflictDoUpdate({
|
|
107
|
+
target: [groups.groupType, groups.groupKey],
|
|
108
|
+
targetWhere: sql`${groups.deletedAt} is null`,
|
|
109
|
+
set: updateSet,
|
|
110
|
+
})
|
|
111
|
+
.returning();
|
|
112
|
+
|
|
113
|
+
const row = inserted[0];
|
|
114
|
+
if (!row) throw new Error("Group upsert returned no row");
|
|
115
|
+
|
|
116
|
+
// Best-effort analytics group-property WRITE (the PostHog groupIdentify path).
|
|
117
|
+
// Association-only upserts pass no properties, so this stays a no-op there.
|
|
118
|
+
const analytics = opts.analytics ?? getAnalytics();
|
|
119
|
+
if (properties && analytics?.capabilities.groups && analytics.groupIdentify) {
|
|
120
|
+
try {
|
|
121
|
+
analytics.groupIdentify({ groupType, groupKey, properties });
|
|
122
|
+
} catch (err) {
|
|
123
|
+
opts.logger?.debug("groupIdentify failed (non-fatal)", {
|
|
124
|
+
err,
|
|
125
|
+
groupType,
|
|
126
|
+
groupKey,
|
|
127
|
+
});
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
return { group: row };
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* Resolve-or-create the LIVE group for `(groupType, groupKey)` WITHOUT touching
|
|
136
|
+
* its property bag or firing analytics (association context only). Reuses
|
|
137
|
+
* {@link identifyGroup}'s atomic partial-index upsert — passing no `properties`
|
|
138
|
+
* skips the merge AND the groupIdentify wire — so the select-then-insert race
|
|
139
|
+
* the campaigns route guards against never arises (the upsert is one statement).
|
|
140
|
+
*/
|
|
141
|
+
async function resolveGroupId(
|
|
142
|
+
db: Database,
|
|
143
|
+
groupType: string,
|
|
144
|
+
groupKey: string,
|
|
145
|
+
): Promise<string> {
|
|
146
|
+
const { group } = await identifyGroup({ db, groupType, groupKey });
|
|
147
|
+
return group.id;
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* INGEST helper (Phase 2.2): associate a contact with each group in a
|
|
152
|
+
* `groupType → groupKey` map. Ensures every group row exists (association only,
|
|
153
|
+
* NO property write, NO analytics) then upserts a `group_memberships` row per
|
|
154
|
+
* group via `onConflictDoNothing` (its unique index is NOT partial, so no
|
|
155
|
+
* arbiter predicate is needed). No-ops cleanly on an empty map. Returns the
|
|
156
|
+
* number of groups whose membership is now in place.
|
|
157
|
+
*/
|
|
158
|
+
export async function associateGroups(opts: {
|
|
159
|
+
db: Database;
|
|
160
|
+
contactId: string;
|
|
161
|
+
groups: Record<string, string>;
|
|
162
|
+
}): Promise<{ associated: number }> {
|
|
163
|
+
const { db, contactId } = opts;
|
|
164
|
+
const entries = Object.entries(opts.groups ?? {});
|
|
165
|
+
if (entries.length === 0) return { associated: 0 };
|
|
166
|
+
|
|
167
|
+
let associated = 0;
|
|
168
|
+
for (const [groupType, groupKey] of entries) {
|
|
169
|
+
if (!groupType || !groupKey) continue;
|
|
170
|
+
const groupId = await resolveGroupId(db, groupType, groupKey);
|
|
171
|
+
await db
|
|
172
|
+
.insert(groupMemberships)
|
|
173
|
+
.values({ groupId, contactId })
|
|
174
|
+
.onConflictDoNothing({
|
|
175
|
+
target: [groupMemberships.groupId, groupMemberships.contactId],
|
|
176
|
+
});
|
|
177
|
+
associated += 1;
|
|
178
|
+
}
|
|
179
|
+
return { associated };
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* Add a contact to a group. FIRST assert the contact exists (else the FK-bound
|
|
184
|
+
* membership insert would 23503 AFTER the group was resolve-or-created, minting
|
|
185
|
+
* an orphan group and 500-ing) — a missing/soft-deleted contact throws
|
|
186
|
+
* {@link GroupContactNotFoundError} BEFORE any group is touched. Then
|
|
187
|
+
* resolve-or-create the live group (association only) and INSERT the membership
|
|
188
|
+
* via `onConflictDoNothing`; when nothing is returned the contact is already a
|
|
189
|
+
* member, so we read the existing row. `created` reflects whether THIS call
|
|
190
|
+
* inserted the membership.
|
|
191
|
+
*/
|
|
192
|
+
export async function addGroupMember(opts: {
|
|
193
|
+
db: Database;
|
|
194
|
+
groupType: string;
|
|
195
|
+
groupKey: string;
|
|
196
|
+
contactId: string;
|
|
197
|
+
role?: string;
|
|
198
|
+
}): Promise<{ membership: GroupMembership; created: boolean }> {
|
|
199
|
+
const { db, groupType, groupKey, contactId, role } = opts;
|
|
200
|
+
|
|
201
|
+
// Contact-existence guard — BEFORE `resolveGroupId` so a bad id never creates
|
|
202
|
+
// an orphan group. The route validated `contactId` is a well-formed uuid, so
|
|
203
|
+
// this select cannot 22P02. Only live (non-deleted) contacts qualify.
|
|
204
|
+
const contactRows = await db
|
|
205
|
+
.select({ id: contacts.id })
|
|
206
|
+
.from(contacts)
|
|
207
|
+
.where(and(eq(contacts.id, contactId), isNull(contacts.deletedAt)))
|
|
208
|
+
.limit(1);
|
|
209
|
+
if (!contactRows[0]) {
|
|
210
|
+
throw new GroupContactNotFoundError(contactId);
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
const groupId = await resolveGroupId(db, groupType, groupKey);
|
|
214
|
+
|
|
215
|
+
const inserted = await db
|
|
216
|
+
.insert(groupMemberships)
|
|
217
|
+
.values({ groupId, contactId, role: role ?? null })
|
|
218
|
+
.onConflictDoNothing({
|
|
219
|
+
target: [groupMemberships.groupId, groupMemberships.contactId],
|
|
220
|
+
})
|
|
221
|
+
.returning();
|
|
222
|
+
|
|
223
|
+
if (inserted[0]) {
|
|
224
|
+
return { membership: inserted[0], created: true };
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
// Already a member — the conflict swallowed the insert; read the live row.
|
|
228
|
+
const existing = await db
|
|
229
|
+
.select()
|
|
230
|
+
.from(groupMemberships)
|
|
231
|
+
.where(
|
|
232
|
+
and(
|
|
233
|
+
eq(groupMemberships.groupId, groupId),
|
|
234
|
+
eq(groupMemberships.contactId, contactId),
|
|
235
|
+
),
|
|
236
|
+
)
|
|
237
|
+
.limit(1);
|
|
238
|
+
|
|
239
|
+
const row = existing[0];
|
|
240
|
+
if (!row) throw new Error("Membership upsert returned no row");
|
|
241
|
+
return { membership: row, created: false };
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
/**
|
|
245
|
+
* Remove a contact from a group. Hard-deletes the membership row (memberships
|
|
246
|
+
* have no soft-delete column). Resolves the LIVE group first; a missing group or
|
|
247
|
+
* absent membership yields `{ removed: false }`.
|
|
248
|
+
*/
|
|
249
|
+
export async function removeGroupMember(opts: {
|
|
250
|
+
db: Database;
|
|
251
|
+
groupType: string;
|
|
252
|
+
groupKey: string;
|
|
253
|
+
contactId: string;
|
|
254
|
+
}): Promise<{ removed: boolean }> {
|
|
255
|
+
const { db, groupType, groupKey, contactId } = opts;
|
|
256
|
+
const { group } = await getGroup({ db, groupType, groupKey });
|
|
257
|
+
if (!group) return { removed: false };
|
|
258
|
+
|
|
259
|
+
const deleted = await db
|
|
260
|
+
.delete(groupMemberships)
|
|
261
|
+
.where(
|
|
262
|
+
and(
|
|
263
|
+
eq(groupMemberships.groupId, group.id),
|
|
264
|
+
eq(groupMemberships.contactId, contactId),
|
|
265
|
+
),
|
|
266
|
+
)
|
|
267
|
+
.returning({ id: groupMemberships.id });
|
|
268
|
+
|
|
269
|
+
return { removed: deleted.length > 0 };
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
/** Fetch the single LIVE group for `(groupType, groupKey)`, or null. */
|
|
273
|
+
export async function getGroup(opts: {
|
|
274
|
+
db: Database;
|
|
275
|
+
groupType: string;
|
|
276
|
+
groupKey: string;
|
|
277
|
+
}): Promise<{ group: Group | null }> {
|
|
278
|
+
const { db, groupType, groupKey } = opts;
|
|
279
|
+
const rows = await db
|
|
280
|
+
.select()
|
|
281
|
+
.from(groups)
|
|
282
|
+
.where(
|
|
283
|
+
and(
|
|
284
|
+
eq(groups.groupType, groupType),
|
|
285
|
+
eq(groups.groupKey, groupKey),
|
|
286
|
+
isNull(groups.deletedAt),
|
|
287
|
+
),
|
|
288
|
+
)
|
|
289
|
+
.limit(1);
|
|
290
|
+
const row: GroupRow | undefined = rows[0];
|
|
291
|
+
return { group: row ?? null };
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/**
|
|
295
|
+
* List LIVE groups, newest-seen first, with an optional `groupType` filter and
|
|
296
|
+
* clamped pagination (default 50, hard cap 200).
|
|
297
|
+
*/
|
|
298
|
+
export async function listGroups(opts: {
|
|
299
|
+
db: Database;
|
|
300
|
+
groupType?: string;
|
|
301
|
+
limit?: number;
|
|
302
|
+
offset?: number;
|
|
303
|
+
}): Promise<{ groups: Group[] }> {
|
|
304
|
+
const { db, groupType } = opts;
|
|
305
|
+
const where = groupType
|
|
306
|
+
? and(eq(groups.groupType, groupType), isNull(groups.deletedAt))
|
|
307
|
+
: isNull(groups.deletedAt);
|
|
308
|
+
|
|
309
|
+
const rows = await db
|
|
310
|
+
.select()
|
|
311
|
+
.from(groups)
|
|
312
|
+
.where(where)
|
|
313
|
+
.orderBy(desc(groups.lastSeenAt))
|
|
314
|
+
.limit(clampLimit(opts.limit))
|
|
315
|
+
.offset(clampOffset(opts.offset));
|
|
316
|
+
|
|
317
|
+
return { groups: rows };
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
/**
|
|
321
|
+
* List the members of a LIVE group (joining `group_memberships → contacts`),
|
|
322
|
+
* newest-joined first, with clamped pagination. Only live contacts are
|
|
323
|
+
* surfaced. Returns `[]` when the group does not exist.
|
|
324
|
+
*/
|
|
325
|
+
export async function listGroupMembers(opts: {
|
|
326
|
+
db: Database;
|
|
327
|
+
groupType: string;
|
|
328
|
+
groupKey: string;
|
|
329
|
+
limit?: number;
|
|
330
|
+
offset?: number;
|
|
331
|
+
}): Promise<{
|
|
332
|
+
members: Array<{
|
|
333
|
+
contactId: string;
|
|
334
|
+
email: string | null;
|
|
335
|
+
externalId: string | null;
|
|
336
|
+
role: string | null;
|
|
337
|
+
joinedAt: Date;
|
|
338
|
+
}>;
|
|
339
|
+
}> {
|
|
340
|
+
const { db, groupType, groupKey } = opts;
|
|
341
|
+
const { group } = await getGroup({ db, groupType, groupKey });
|
|
342
|
+
if (!group) return { members: [] };
|
|
343
|
+
|
|
344
|
+
const members = await db
|
|
345
|
+
.select({
|
|
346
|
+
contactId: groupMemberships.contactId,
|
|
347
|
+
email: contacts.email,
|
|
348
|
+
externalId: contacts.externalId,
|
|
349
|
+
role: groupMemberships.role,
|
|
350
|
+
joinedAt: groupMemberships.joinedAt,
|
|
351
|
+
})
|
|
352
|
+
.from(groupMemberships)
|
|
353
|
+
.innerJoin(contacts, eq(groupMemberships.contactId, contacts.id))
|
|
354
|
+
.where(
|
|
355
|
+
and(eq(groupMemberships.groupId, group.id), isNull(contacts.deletedAt)),
|
|
356
|
+
)
|
|
357
|
+
.orderBy(desc(groupMemberships.joinedAt))
|
|
358
|
+
.limit(clampLimit(opts.limit))
|
|
359
|
+
.offset(clampOffset(opts.offset));
|
|
360
|
+
|
|
361
|
+
return { members };
|
|
362
|
+
}
|
package/src/lib/ingestion.ts
CHANGED
|
@@ -2,6 +2,7 @@ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
|
|
|
2
2
|
import type {
|
|
3
3
|
AnalyticsEventMirrorConfig,
|
|
4
4
|
AnalyticsProvider,
|
|
5
|
+
GroupsAssociation,
|
|
5
6
|
PropertyCondition,
|
|
6
7
|
} from "@hogsend/core";
|
|
7
8
|
import { evaluatePropertyConditions } from "@hogsend/core";
|
|
@@ -41,6 +42,7 @@ import {
|
|
|
41
42
|
import { getCrmSyncConfig } from "./crm-registry-singleton.js";
|
|
42
43
|
import { recordFunnelProgressAtIngest } from "./funnel-progress.js";
|
|
43
44
|
import { applyFunnelTransitionsAtIngest } from "./funnel-transitions.js";
|
|
45
|
+
import { associateGroups } from "./groups.js";
|
|
44
46
|
import type { Logger } from "./logger.js";
|
|
45
47
|
|
|
46
48
|
export interface IngestEvent {
|
|
@@ -69,6 +71,14 @@ export interface IngestEvent {
|
|
|
69
71
|
eventProperties: Record<string, unknown>;
|
|
70
72
|
/** D2: → `contacts.properties` merge ONLY. */
|
|
71
73
|
contactProperties?: Record<string, unknown>;
|
|
74
|
+
/**
|
|
75
|
+
* The groupType→groupKey association map for this event — persisted on
|
|
76
|
+
* `user_events.groups`, drives group membership (each group row is ensured +
|
|
77
|
+
* a `group_memberships` row upserted for the resolved contact), and forwards
|
|
78
|
+
* to analytics as `$groups` alongside the mirrored capture. Optional (null on
|
|
79
|
+
* `user_events` when unset).
|
|
80
|
+
*/
|
|
81
|
+
groups?: GroupsAssociation;
|
|
72
82
|
/**
|
|
73
83
|
* The event's own monetary worth (deal value, order total). Stored on the
|
|
74
84
|
* first-class `user_events.value` column — the revenue spine every rollup,
|
|
@@ -393,6 +403,7 @@ export async function ingestEvent(opts: {
|
|
|
393
403
|
userId: resolvedKey,
|
|
394
404
|
event: event.event,
|
|
395
405
|
properties: event.eventProperties,
|
|
406
|
+
groups: event.groups ?? null,
|
|
396
407
|
value,
|
|
397
408
|
currency,
|
|
398
409
|
source: event.source ?? null,
|
|
@@ -416,6 +427,7 @@ export async function ingestEvent(opts: {
|
|
|
416
427
|
userId: resolvedKey,
|
|
417
428
|
event: event.event,
|
|
418
429
|
properties: event.eventProperties,
|
|
430
|
+
groups: event.groups ?? null,
|
|
419
431
|
value,
|
|
420
432
|
currency,
|
|
421
433
|
source: event.source ?? null,
|
|
@@ -476,6 +488,10 @@ export async function ingestEvent(opts: {
|
|
|
476
488
|
mirrorProvider.capture({
|
|
477
489
|
distinctId: resolvedKey,
|
|
478
490
|
event: event.event,
|
|
491
|
+
// Group context rides the mirrored capture as `$groups` so PostHog (et
|
|
492
|
+
// al.) can attribute the event to its account/team. Undefined when the
|
|
493
|
+
// event carries no group association.
|
|
494
|
+
groups: event.groups,
|
|
479
495
|
// The revenue spine fans out with the event: `value`/`currency` ride as
|
|
480
496
|
// plain properties so the analytics tool (PostHog et al.) can sum
|
|
481
497
|
// revenue without a Hogsend round-trip. Property-bag keys of the same
|
|
@@ -495,6 +511,28 @@ export async function ingestEvent(opts: {
|
|
|
495
511
|
}
|
|
496
512
|
}
|
|
497
513
|
|
|
514
|
+
// (2d) Sovereign group association — the STANDALONE (DB-first) path, run on
|
|
515
|
+
// every ingest regardless of the analytics mirror config above. Ensures each
|
|
516
|
+
// group row exists and upserts a `group_memberships` row for the resolved
|
|
517
|
+
// contact (idempotent, no property write, no analytics). Placed on the
|
|
518
|
+
// fresh-insert side of the idempotency guard (the duplicate path returned at
|
|
519
|
+
// the early `stored:false`), so a same-key replay never re-associates.
|
|
520
|
+
// Best-effort: the `user_events` row is already durably stored (the plain
|
|
521
|
+
// path has NO idempotency key, so a thrown error + ingest retry would
|
|
522
|
+
// DOUBLE-insert the event) — a group-write hiccup must never fail an
|
|
523
|
+
// already-stored event.
|
|
524
|
+
if (event.groups && Object.keys(event.groups).length > 0) {
|
|
525
|
+
try {
|
|
526
|
+
await associateGroups({ db, contactId, groups: event.groups });
|
|
527
|
+
} catch (err) {
|
|
528
|
+
logger.warn("group association failed (non-fatal)", {
|
|
529
|
+
event: event.event,
|
|
530
|
+
userId: resolvedKey,
|
|
531
|
+
error: err instanceof Error ? err.message : String(err),
|
|
532
|
+
});
|
|
533
|
+
}
|
|
534
|
+
}
|
|
535
|
+
|
|
498
536
|
// (3) Build the JSON-serializable subset of eventProperties for the Hatchet
|
|
499
537
|
// push payload (scalars only — the SDK serializes the envelope).
|
|
500
538
|
const serializableProperties = Object.fromEntries(
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
import { type Database, journeyStates } from "@hogsend/db";
|
|
2
|
+
import { and, eq, sql } from "drizzle-orm";
|
|
3
|
+
import { computeLift, type LiftVerdict } from "./lift-stats.js";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Counts-only cohort: the /lift route merges per-currency values back in
|
|
7
|
+
* (computeLiftValues); the phase-2b /impact overall block and the phase-3b
|
|
8
|
+
* digest consume counts as-is.
|
|
9
|
+
*/
|
|
10
|
+
export interface LiftCohort {
|
|
11
|
+
contacts: number;
|
|
12
|
+
converters: number;
|
|
13
|
+
rate: number;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export interface JourneyLiftResult {
|
|
17
|
+
treatment: LiftCohort;
|
|
18
|
+
control: LiftCohort;
|
|
19
|
+
verdict: LiftVerdict;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
interface LiftQueryOpts {
|
|
23
|
+
db: Database;
|
|
24
|
+
journeyId: string;
|
|
25
|
+
since: Date;
|
|
26
|
+
/** Snapshot instant; defaults to now (both bounds become no-ops). */
|
|
27
|
+
asOf?: Date;
|
|
28
|
+
/** Scope the outcome to one conversion definition; default any. */
|
|
29
|
+
definitionId?: string;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Shared SQL fragments for one (journeyId, since, asOf, definitionId). */
|
|
33
|
+
function liftFragments(opts: LiftQueryOpts) {
|
|
34
|
+
const asOf = opts.asOf ?? new Date();
|
|
35
|
+
return {
|
|
36
|
+
sinceTs: sql`${opts.since.toISOString()}::timestamptz`,
|
|
37
|
+
asOfTs: sql`${asOf.toISOString()}::timestamptz`,
|
|
38
|
+
definitionSql: opts.definitionId
|
|
39
|
+
? sql` and c.definition_id = ${opts.definitionId}`
|
|
40
|
+
: sql``,
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Holdout lift for one journey — the ONE implementation of the causal math
|
|
46
|
+
* (routes/admin/funnels.ts:16 law). Treatment = status != 'held_out';
|
|
47
|
+
* control = status = 'held_out'; outcome = ≥1 qualifying conversions row
|
|
48
|
+
* with occurred_at >= the state row's created_at (intent-to-treat clock).
|
|
49
|
+
*
|
|
50
|
+
* `asOf` (default: now) snapshots the read: cohort rows require
|
|
51
|
+
* created_at < asOf and conversions require occurred_at <= asOf. With
|
|
52
|
+
* asOf = now both bounds are no-ops (future-dated rows cannot exist), so
|
|
53
|
+
* the /lift route's behavior is unchanged by the extraction — pinned by a
|
|
54
|
+
* regression fixture (apps/api journey-lift.test.ts).
|
|
55
|
+
*/
|
|
56
|
+
export async function computeJourneyLift(
|
|
57
|
+
opts: LiftQueryOpts,
|
|
58
|
+
): Promise<JourneyLiftResult> {
|
|
59
|
+
const { db, journeyId } = opts;
|
|
60
|
+
const { sinceTs, asOfTs, definitionSql } = liftFragments(opts);
|
|
61
|
+
|
|
62
|
+
// Outcome: the contact fired ≥1 qualifying conversion AFTER their state
|
|
63
|
+
// row was created (post-assignment — the intent-to-treat clock) and at
|
|
64
|
+
// or before the asOf snapshot instant.
|
|
65
|
+
const convertedSql = sql`exists (
|
|
66
|
+
select 1 from conversions c
|
|
67
|
+
where c.user_key = ${journeyStates.userId}
|
|
68
|
+
and c.occurred_at >= ${journeyStates.createdAt}
|
|
69
|
+
and c.occurred_at <= ${asOfTs}${definitionSql}
|
|
70
|
+
)`;
|
|
71
|
+
|
|
72
|
+
const cohort = async (control: boolean): Promise<LiftCohort> => {
|
|
73
|
+
const statusFilter = control
|
|
74
|
+
? eq(journeyStates.status, "held_out")
|
|
75
|
+
: sql`${journeyStates.status} != 'held_out'`;
|
|
76
|
+
const [row] = await db
|
|
77
|
+
.select({
|
|
78
|
+
contacts: sql<number>`count(distinct ${journeyStates.userId})::int`,
|
|
79
|
+
converters: sql<number>`(count(distinct ${journeyStates.userId}) filter (where ${convertedSql}))::int`,
|
|
80
|
+
})
|
|
81
|
+
.from(journeyStates)
|
|
82
|
+
.where(
|
|
83
|
+
and(
|
|
84
|
+
eq(journeyStates.journeyId, journeyId),
|
|
85
|
+
sql`${journeyStates.createdAt} >= ${sinceTs}`,
|
|
86
|
+
sql`${journeyStates.createdAt} < ${asOfTs}`,
|
|
87
|
+
statusFilter,
|
|
88
|
+
),
|
|
89
|
+
);
|
|
90
|
+
const contacts = Number(row?.contacts ?? 0);
|
|
91
|
+
const converters = row?.converters ?? 0;
|
|
92
|
+
return {
|
|
93
|
+
contacts,
|
|
94
|
+
converters,
|
|
95
|
+
rate: contacts > 0 ? converters / contacts : 0,
|
|
96
|
+
};
|
|
97
|
+
};
|
|
98
|
+
|
|
99
|
+
const [treatment, control] = await Promise.all([cohort(false), cohort(true)]);
|
|
100
|
+
return { treatment, control, verdict: computeLift({ treatment, control }) };
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Per-currency qualifying conversion value for both cohorts (full value,
|
|
105
|
+
* not fractional credit). Kept SEPARATE from the counts helper: /lift
|
|
106
|
+
* composes it into its wire shape; the digest and overview never need it.
|
|
107
|
+
*/
|
|
108
|
+
export async function computeLiftValues(opts: LiftQueryOpts): Promise<{
|
|
109
|
+
treatment: Array<{ currency: string | null; value: number }>;
|
|
110
|
+
control: Array<{ currency: string | null; value: number }>;
|
|
111
|
+
}> {
|
|
112
|
+
const { db, journeyId } = opts;
|
|
113
|
+
const { sinceTs, asOfTs, definitionSql } = liftFragments(opts);
|
|
114
|
+
|
|
115
|
+
const values = async (control: boolean) => {
|
|
116
|
+
const rows = await db.execute<{ currency: string | null; value: number }>(
|
|
117
|
+
sql`
|
|
118
|
+
select c.currency, coalesce(sum(c.value), 0)::float8 as value
|
|
119
|
+
from conversions c
|
|
120
|
+
where c.value is not null
|
|
121
|
+
and c.occurred_at <= ${asOfTs}
|
|
122
|
+
and exists (
|
|
123
|
+
select 1 from journey_states js
|
|
124
|
+
where js.journey_id = ${journeyId}
|
|
125
|
+
and js.created_at >= ${sinceTs}
|
|
126
|
+
and js.created_at < ${asOfTs}
|
|
127
|
+
and ${control ? sql`js.status = 'held_out'` : sql`js.status != 'held_out'`}
|
|
128
|
+
and js.user_id = c.user_key
|
|
129
|
+
and c.occurred_at >= js.created_at
|
|
130
|
+
)${definitionSql}
|
|
131
|
+
group by c.currency
|
|
132
|
+
`,
|
|
133
|
+
);
|
|
134
|
+
return [...rows].map((r) => ({
|
|
135
|
+
currency: r.currency,
|
|
136
|
+
value: Number(r.value),
|
|
137
|
+
}));
|
|
138
|
+
};
|
|
139
|
+
|
|
140
|
+
const [treatment, control] = await Promise.all([values(false), values(true)]);
|
|
141
|
+
return { treatment, control };
|
|
142
|
+
}
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
import type { Database } from "@hogsend/db";
|
|
2
|
+
import { operatorSettings } from "@hogsend/db";
|
|
3
|
+
import { eq } from "drizzle-orm";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Typed access to `operator_settings` — the generic overlay for GLOBAL
|
|
7
|
+
* operator choices made in Studio (the `journey_configs` DB-config-overlay
|
|
8
|
+
* pattern generalized to a KV keyed by setting name). An ABSENT row means
|
|
9
|
+
* "the operator made no choice" and env/boot defaults decide; a PRESENT row
|
|
10
|
+
* is the operator's explicit word and overlays env — including an explicit
|
|
11
|
+
* "off".
|
|
12
|
+
*
|
|
13
|
+
* Deliberately NO cache (lean-first): every reader is a low-QPS admin/lens
|
|
14
|
+
* surface where a primary-key lookup is nothing, and a cache would only add
|
|
15
|
+
* an invalidation story across the API + worker processes for zero felt win.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/** The `"fx"` operator setting — the Studio-chosen base currency. */
|
|
19
|
+
export const FX_SETTINGS_KEY = "fx";
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Value shape under {@link FX_SETTINGS_KEY}. `baseCurrency: null` is the
|
|
23
|
+
* operator EXPLICITLY turning the lens off (beats env `BASE_CURRENCY`);
|
|
24
|
+
* "fall back to env" is expressed by DELETING the row, never by a value.
|
|
25
|
+
*/
|
|
26
|
+
export interface FxSetting {
|
|
27
|
+
baseCurrency: string | null;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** Read one operator setting's value, or null when the row doesn't exist. */
|
|
31
|
+
export async function getOperatorSetting<T>(
|
|
32
|
+
db: Database,
|
|
33
|
+
key: string,
|
|
34
|
+
): Promise<T | null> {
|
|
35
|
+
const [row] = await db
|
|
36
|
+
.select({ value: operatorSettings.value })
|
|
37
|
+
.from(operatorSettings)
|
|
38
|
+
.where(eq(operatorSettings.key, key))
|
|
39
|
+
.limit(1);
|
|
40
|
+
return row ? (row.value as T) : null;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** Upsert one operator setting (create and update are the same write). */
|
|
44
|
+
export async function putOperatorSetting(
|
|
45
|
+
db: Database,
|
|
46
|
+
key: string,
|
|
47
|
+
value: unknown,
|
|
48
|
+
): Promise<void> {
|
|
49
|
+
await db
|
|
50
|
+
.insert(operatorSettings)
|
|
51
|
+
.values({ key, value })
|
|
52
|
+
.onConflictDoUpdate({
|
|
53
|
+
target: operatorSettings.key,
|
|
54
|
+
set: { value, updatedAt: new Date() },
|
|
55
|
+
});
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Remove one operator setting — "clear the override, fall back to env".
|
|
60
|
+
* Returns whether a row was actually deleted (idempotent either way).
|
|
61
|
+
*/
|
|
62
|
+
export async function deleteOperatorSetting(
|
|
63
|
+
db: Database,
|
|
64
|
+
key: string,
|
|
65
|
+
): Promise<boolean> {
|
|
66
|
+
const deleted = await db
|
|
67
|
+
.delete(operatorSettings)
|
|
68
|
+
.where(eq(operatorSettings.key, key))
|
|
69
|
+
.returning({ key: operatorSettings.key });
|
|
70
|
+
return deleted.length > 0;
|
|
71
|
+
}
|