@hogsend/engine 0.43.0 → 0.45.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 +12 -9
- package/src/container.ts +289 -13
- package/src/destinations/define-destination.ts +7 -3
- package/src/destinations/presets/posthog.ts +31 -0
- package/src/index.ts +99 -0
- package/src/journeys/execute-journey-run.ts +93 -0
- package/src/journeys/journey-context.ts +4 -0
- package/src/lib/analytics-providers-from-env.ts +106 -43
- package/src/lib/attribution-backfill.ts +285 -0
- package/src/lib/attribution.ts +239 -0
- package/src/lib/contacts.ts +71 -0
- package/src/lib/conversion-dispatch.ts +326 -0
- package/src/lib/conversions.ts +197 -0
- package/src/lib/crm-deals.ts +320 -0
- package/src/lib/crm-ingest.ts +341 -0
- package/src/lib/crm-provider-registry.ts +41 -0
- package/src/lib/crm-registry-singleton.ts +22 -0
- package/src/lib/deal-money-events.ts +85 -0
- package/src/lib/email-service-types.ts +16 -1
- package/src/lib/event-names.ts +1 -1
- package/src/lib/funnel-progress.ts +76 -0
- package/src/lib/funnel-registry.ts +108 -0
- package/src/lib/funnel-transitions.ts +280 -0
- package/src/lib/holdout.ts +62 -0
- package/src/lib/ingestion.ts +218 -9
- package/src/lib/lift-stats.ts +125 -0
- package/src/lib/mailer.ts +1 -0
- package/src/lib/operator.ts +31 -0
- package/src/lib/outbound.ts +51 -0
- package/src/lib/posthog-scopes.ts +30 -6
- package/src/lib/revenue.ts +116 -0
- package/src/lib/sms-service-types.ts +7 -1
- package/src/lib/sms-tracked.ts +35 -0
- package/src/lib/tracked.ts +40 -0
- package/src/lib/tracking-events.ts +26 -0
- package/src/lib/unconfigured-email-provider.ts +45 -0
- package/src/lib/webhook-signing.ts +7 -0
- package/src/routes/admin/analytics.ts +14 -5
- package/src/routes/admin/attribution.ts +414 -0
- package/src/routes/admin/contacts.ts +71 -11
- package/src/routes/admin/conversions.ts +247 -0
- package/src/routes/admin/deals.ts +472 -0
- package/src/routes/admin/funnels.ts +228 -0
- package/src/routes/admin/index.ts +8 -0
- package/src/routes/admin/journeys.ts +158 -1
- package/src/routes/admin/readiness.ts +97 -2
- package/src/routes/admin/templates.ts +28 -1
- package/src/routes/events/index.ts +12 -0
- package/src/routes/tracking/click-pipeline.ts +26 -18
- package/src/routes/webhooks/crm-provider.ts +117 -0
- package/src/routes/webhooks/index.ts +5 -1
- package/src/sources/define-contact-source.ts +159 -0
- package/src/sources/registry.ts +71 -0
- package/src/sources/webhook-source.ts +109 -0
- package/src/worker.ts +4 -0
- package/src/workflows/crm-reconcile.ts +129 -0
- package/src/workflows/dispatch-conversion.ts +31 -0
- package/src/workflows/send-campaign.ts +5 -0
|
@@ -0,0 +1,414 @@
|
|
|
1
|
+
import { attributionCredits, campaigns, conversions } from "@hogsend/db";
|
|
2
|
+
import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
|
|
3
|
+
import { and, count, eq, gte, isNotNull, sql } from "drizzle-orm";
|
|
4
|
+
import type { AppEnv } from "../../app.js";
|
|
5
|
+
import { backfillAttributionBatch } from "../../lib/attribution-backfill.js";
|
|
6
|
+
import { getConversionRegistry } from "../../lib/conversions.js";
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Admin attribution API (docs/revenue-attribution-plan.md §6.2, extended by
|
|
10
|
+
* docs/attribution-impact-plan.md §1.5) — reads over the credit ledger.
|
|
11
|
+
* Every model was persisted at conversion time, so model comparison is a
|
|
12
|
+
* GROUP BY, not a re-computation — and since the ledger carries
|
|
13
|
+
* journey/campaign/template scope, "revenue by journey" is too.
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
const GROUP_DIMENSIONS = [
|
|
17
|
+
"channel",
|
|
18
|
+
"journey",
|
|
19
|
+
"campaign",
|
|
20
|
+
"template",
|
|
21
|
+
] as const;
|
|
22
|
+
type GroupDimension = (typeof GROUP_DIMENSIONS)[number];
|
|
23
|
+
|
|
24
|
+
const rowSchema = z.object({
|
|
25
|
+
model: z.string(),
|
|
26
|
+
/**
|
|
27
|
+
* The grouped dimension's value — channel name, journey id, campaign id,
|
|
28
|
+
* or template key. Null = credits carrying no scope on that dimension
|
|
29
|
+
* (e.g. a transactional-send click under groupBy=journey).
|
|
30
|
+
*/
|
|
31
|
+
key: z.string().nullable(),
|
|
32
|
+
/** Human label where the key is opaque (campaign name); else null. */
|
|
33
|
+
label: z.string().nullable(),
|
|
34
|
+
/** Back-compat mirror of `key`, present only when groupBy=channel. */
|
|
35
|
+
channel: z.string().optional(),
|
|
36
|
+
currency: z.string().nullable(),
|
|
37
|
+
/** Sum of credited value (weight × conversion value), this currency. */
|
|
38
|
+
value: z.number(),
|
|
39
|
+
/** Sum of weights — "how many conversions" this key earned. */
|
|
40
|
+
conversions: z.number(),
|
|
41
|
+
/** Number of credited touchpoints. */
|
|
42
|
+
touches: z.number(),
|
|
43
|
+
});
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Coverage — the ledger only divides conversions that HAD a touchpoint path,
|
|
47
|
+
* so credited value is a subset of fired conversion value. Reporting both
|
|
48
|
+
* keeps the delta (direct / imported / pre-tracking conversions) explicit
|
|
49
|
+
* instead of silently missing. Scoped by `definitionId` only — the
|
|
50
|
+
* journeyId/campaignId row filters do NOT narrow totals (a conversion is not
|
|
51
|
+
* "inside" a journey; its touches are).
|
|
52
|
+
*/
|
|
53
|
+
const totalsSchema = z.object({
|
|
54
|
+
currency: z.string().nullable(),
|
|
55
|
+
/** Total fired conversion value in the window (this currency). */
|
|
56
|
+
value: z.number(),
|
|
57
|
+
conversions: z.number(),
|
|
58
|
+
/** Subset with at least one credit row — i.e. a touchpoint path. */
|
|
59
|
+
attributedValue: z.number(),
|
|
60
|
+
attributedConversions: z.number(),
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Influenced (impact plan §3.1) — the model-invariant COVERAGE number
|
|
65
|
+
* (Dreamdata semantics): a conversion is influenced by a scope when the
|
|
66
|
+
* contact had ≥1 touchpoint from it inside the window. Deliberately
|
|
67
|
+
* multi-counted across scopes — it answers "which conversions did this
|
|
68
|
+
* journey touch at all", never sums to total, and is presented as reach,
|
|
69
|
+
* not credit.
|
|
70
|
+
*/
|
|
71
|
+
const influencedSchema = z.object({
|
|
72
|
+
key: z.string(),
|
|
73
|
+
/** Human label where the key is opaque (campaign name); else null. */
|
|
74
|
+
label: z.string().nullable(),
|
|
75
|
+
currency: z.string().nullable(),
|
|
76
|
+
/** Conversions with ≥1 touch from this scope (full count, not weighted). */
|
|
77
|
+
conversions: z.number(),
|
|
78
|
+
/** FULL value of those conversions (not fractional credit). */
|
|
79
|
+
value: z.number(),
|
|
80
|
+
});
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* Overlap transparency (impact plan §2.3, the anti-Braze): no incumbent
|
|
84
|
+
* dedupes credit across journeys/campaigns — Braze documents conversion
|
|
85
|
+
* rates over 100%. Our fractional models already sum to 1 per conversion
|
|
86
|
+
* (that IS the dedup); this block additionally SHOWS the overlap: how many
|
|
87
|
+
* scope-claimed conversions were claimed by more than one value of the
|
|
88
|
+
* grouped dimension, and what per-scope single-credit totals would add up
|
|
89
|
+
* to (`scopeSummedValue` vs the real `value`).
|
|
90
|
+
*/
|
|
91
|
+
const overlapSchema = z.object({
|
|
92
|
+
currency: z.string().nullable(),
|
|
93
|
+
/** Conversions claimed by ≥1 non-null scope on this dimension. */
|
|
94
|
+
conversions: z.number(),
|
|
95
|
+
/** Subset claimed by MORE THAN ONE distinct scope. */
|
|
96
|
+
multiScopeConversions: z.number(),
|
|
97
|
+
/** Real conversion value across the claimed set. */
|
|
98
|
+
value: z.number(),
|
|
99
|
+
/** What "each scope takes full credit" reporting would sum to. */
|
|
100
|
+
scopeSummedValue: z.number(),
|
|
101
|
+
});
|
|
102
|
+
|
|
103
|
+
const summaryRoute = createRoute({
|
|
104
|
+
method: "get",
|
|
105
|
+
path: "/",
|
|
106
|
+
tags: ["Admin"],
|
|
107
|
+
summary: "Attribution credit rollup (model × dimension × currency)",
|
|
108
|
+
request: {
|
|
109
|
+
query: z.object({
|
|
110
|
+
days: z.coerce.number().min(1).max(365).default(90),
|
|
111
|
+
/** Scope to one conversion point. */
|
|
112
|
+
definitionId: z.string().optional(),
|
|
113
|
+
/** The dimension credits are grouped by (impact plan §1.5). */
|
|
114
|
+
groupBy: z.enum(GROUP_DIMENSIONS).default("channel"),
|
|
115
|
+
/** Only credits whose touchpoint belongs to this journey. */
|
|
116
|
+
journeyId: z.string().optional(),
|
|
117
|
+
/** Only credits whose touchpoint belongs to this campaign. */
|
|
118
|
+
campaignId: z.string().optional(),
|
|
119
|
+
}),
|
|
120
|
+
},
|
|
121
|
+
responses: {
|
|
122
|
+
200: {
|
|
123
|
+
content: {
|
|
124
|
+
"application/json": {
|
|
125
|
+
schema: z.object({
|
|
126
|
+
days: z.number(),
|
|
127
|
+
groupBy: z.enum(GROUP_DIMENSIONS),
|
|
128
|
+
rows: z.array(rowSchema),
|
|
129
|
+
totals: z.array(totalsSchema),
|
|
130
|
+
overlap: z.array(overlapSchema),
|
|
131
|
+
influenced: z.array(influencedSchema),
|
|
132
|
+
}),
|
|
133
|
+
},
|
|
134
|
+
},
|
|
135
|
+
description:
|
|
136
|
+
"Flat rollup rows — clients pivot into per-model breakdowns and model-comparison matrices",
|
|
137
|
+
},
|
|
138
|
+
},
|
|
139
|
+
});
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* Backfill (impact plan §5.1) — batch-shaped replay of history through the
|
|
143
|
+
* idempotent conversion + ledger machinery. Loop until `nextCursor` is null
|
|
144
|
+
* (`hogsend attribution backfill` does exactly that). Lives here because
|
|
145
|
+
* the code-first conversion registry only exists inside the API process.
|
|
146
|
+
*/
|
|
147
|
+
const backfillRoute = createRoute({
|
|
148
|
+
method: "post",
|
|
149
|
+
path: "/backfill",
|
|
150
|
+
tags: ["Admin"],
|
|
151
|
+
summary: "Backfill conversions + attribution credits from event history",
|
|
152
|
+
request: {
|
|
153
|
+
body: {
|
|
154
|
+
content: {
|
|
155
|
+
"application/json": {
|
|
156
|
+
schema: z.object({
|
|
157
|
+
definitionId: z.string().optional(),
|
|
158
|
+
/** Only events/conversions at or after this instant. */
|
|
159
|
+
since: z.string().datetime().optional(),
|
|
160
|
+
/** Opaque batch cursor from the previous response. */
|
|
161
|
+
cursor: z.string().optional(),
|
|
162
|
+
limit: z.number().min(1).max(2000).default(500),
|
|
163
|
+
/**
|
|
164
|
+
* Delete-then-refill the definition's credits under CURRENT
|
|
165
|
+
* window config. Requires definitionId; logged loudly.
|
|
166
|
+
*/
|
|
167
|
+
recompute: z.boolean().default(false),
|
|
168
|
+
}),
|
|
169
|
+
},
|
|
170
|
+
},
|
|
171
|
+
},
|
|
172
|
+
},
|
|
173
|
+
responses: {
|
|
174
|
+
200: {
|
|
175
|
+
content: {
|
|
176
|
+
"application/json": {
|
|
177
|
+
schema: z.object({
|
|
178
|
+
stage: z.enum(["events", "credits"]),
|
|
179
|
+
processed: z.number(),
|
|
180
|
+
conversionsFired: z.number(),
|
|
181
|
+
creditsWritten: z.number(),
|
|
182
|
+
/** Null = backfill complete. */
|
|
183
|
+
nextCursor: z.string().nullable(),
|
|
184
|
+
}),
|
|
185
|
+
},
|
|
186
|
+
},
|
|
187
|
+
description: "One processed batch; loop until nextCursor is null",
|
|
188
|
+
},
|
|
189
|
+
400: {
|
|
190
|
+
content: {
|
|
191
|
+
"application/json": { schema: z.object({ error: z.string() }) },
|
|
192
|
+
},
|
|
193
|
+
description: "recompute without definitionId",
|
|
194
|
+
},
|
|
195
|
+
},
|
|
196
|
+
});
|
|
197
|
+
|
|
198
|
+
export const adminAttributionRouter = new OpenAPIHono<AppEnv>()
|
|
199
|
+
.openapi(summaryRoute, async (c) => {
|
|
200
|
+
const { db } = c.get("container");
|
|
201
|
+
const { days, definitionId, groupBy, journeyId, campaignId } =
|
|
202
|
+
c.req.valid("query");
|
|
203
|
+
const since = new Date(
|
|
204
|
+
Date.now() - days * 24 * 60 * 60 * 1000,
|
|
205
|
+
).toISOString();
|
|
206
|
+
const sinceTs = sql`${since}::timestamptz`;
|
|
207
|
+
const definitionFilter = definitionId
|
|
208
|
+
? [eq(conversions.definitionId, definitionId)]
|
|
209
|
+
: [];
|
|
210
|
+
const scopeFilters = [
|
|
211
|
+
...(journeyId ? [eq(attributionCredits.journeyId, journeyId)] : []),
|
|
212
|
+
...(campaignId ? [eq(attributionCredits.campaignId, campaignId)] : []),
|
|
213
|
+
];
|
|
214
|
+
|
|
215
|
+
const groupColumns = {
|
|
216
|
+
channel: attributionCredits.channel,
|
|
217
|
+
journey: attributionCredits.journeyId,
|
|
218
|
+
campaign: attributionCredits.campaignId,
|
|
219
|
+
template: attributionCredits.templateKey,
|
|
220
|
+
} satisfies Record<GroupDimension, unknown>;
|
|
221
|
+
const groupCol = groupColumns[groupBy];
|
|
222
|
+
|
|
223
|
+
const rows = await db
|
|
224
|
+
.select({
|
|
225
|
+
model: attributionCredits.model,
|
|
226
|
+
key: sql<string | null>`${groupCol}::text`,
|
|
227
|
+
currency: attributionCredits.currency,
|
|
228
|
+
value: sql<number>`coalesce(sum(${attributionCredits.value}), 0)::float8`,
|
|
229
|
+
conversions: sql<number>`coalesce(sum(${attributionCredits.weight}), 0)::float8`,
|
|
230
|
+
touches: count(),
|
|
231
|
+
})
|
|
232
|
+
.from(attributionCredits)
|
|
233
|
+
.innerJoin(
|
|
234
|
+
conversions,
|
|
235
|
+
eq(attributionCredits.conversionId, conversions.id),
|
|
236
|
+
)
|
|
237
|
+
.where(
|
|
238
|
+
and(
|
|
239
|
+
gte(attributionCredits.convertedAt, sinceTs),
|
|
240
|
+
...definitionFilter,
|
|
241
|
+
...scopeFilters,
|
|
242
|
+
),
|
|
243
|
+
)
|
|
244
|
+
.groupBy(
|
|
245
|
+
attributionCredits.model,
|
|
246
|
+
sql`${groupCol}`,
|
|
247
|
+
attributionCredits.currency,
|
|
248
|
+
);
|
|
249
|
+
|
|
250
|
+
// Influenced (§3.1): one row per (scope key, conversion) via DISTINCT,
|
|
251
|
+
// then full conversion count + value per key. Any single model
|
|
252
|
+
// enumerates the credited path; weight is ignored by construction.
|
|
253
|
+
const influencedClaims = db.$with("influenced_claims").as(
|
|
254
|
+
db
|
|
255
|
+
.selectDistinct({
|
|
256
|
+
conversionId: attributionCredits.conversionId,
|
|
257
|
+
key: sql<string>`${groupCol}::text`.as("key"),
|
|
258
|
+
})
|
|
259
|
+
.from(attributionCredits)
|
|
260
|
+
.where(
|
|
261
|
+
and(
|
|
262
|
+
eq(attributionCredits.model, "linear"),
|
|
263
|
+
gte(attributionCredits.convertedAt, sinceTs),
|
|
264
|
+
isNotNull(groupCol),
|
|
265
|
+
),
|
|
266
|
+
),
|
|
267
|
+
);
|
|
268
|
+
const influenced = await db
|
|
269
|
+
.with(influencedClaims)
|
|
270
|
+
.select({
|
|
271
|
+
key: influencedClaims.key,
|
|
272
|
+
currency: conversions.currency,
|
|
273
|
+
conversions: count(),
|
|
274
|
+
value: sql<number>`coalesce(sum(${conversions.value}), 0)::float8`,
|
|
275
|
+
})
|
|
276
|
+
.from(influencedClaims)
|
|
277
|
+
.innerJoin(conversions, eq(conversions.id, influencedClaims.conversionId))
|
|
278
|
+
.where(and(...definitionFilter))
|
|
279
|
+
.groupBy(influencedClaims.key, conversions.currency);
|
|
280
|
+
|
|
281
|
+
// Campaign keys are opaque uuids — resolve names server-side so every
|
|
282
|
+
// client renders the same labels. Other dimensions are already readable.
|
|
283
|
+
const labels = new Map<string, string>();
|
|
284
|
+
if (groupBy === "campaign") {
|
|
285
|
+
const ids = [
|
|
286
|
+
...new Set(
|
|
287
|
+
[...rows.map((r) => r.key), ...influenced.map((r) => r.key)].filter(
|
|
288
|
+
(k): k is string => !!k,
|
|
289
|
+
),
|
|
290
|
+
),
|
|
291
|
+
];
|
|
292
|
+
if (ids.length > 0) {
|
|
293
|
+
const named = await db
|
|
294
|
+
.select({ id: campaigns.id, name: campaigns.name })
|
|
295
|
+
.from(campaigns)
|
|
296
|
+
.where(
|
|
297
|
+
sql`${campaigns.id} in (${sql.join(
|
|
298
|
+
ids.map((id) => sql`${id}::uuid`),
|
|
299
|
+
sql`, `,
|
|
300
|
+
)})`,
|
|
301
|
+
);
|
|
302
|
+
for (const row of named) labels.set(row.id, row.name);
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
// Overlap (§2.3): per conversion, how many distinct non-null values of
|
|
307
|
+
// the grouped dimension claimed it (any single model enumerates the
|
|
308
|
+
// credited path — `linear` includes every in-window touch). Unfiltered
|
|
309
|
+
// by journeyId/campaignId: overlap is about the whole claiming set.
|
|
310
|
+
const claims = db.$with("claims").as(
|
|
311
|
+
db
|
|
312
|
+
.select({
|
|
313
|
+
conversionId: attributionCredits.conversionId,
|
|
314
|
+
scopeCount: sql<number>`count(distinct ${groupCol})`.as(
|
|
315
|
+
"scope_count",
|
|
316
|
+
),
|
|
317
|
+
})
|
|
318
|
+
.from(attributionCredits)
|
|
319
|
+
.where(
|
|
320
|
+
and(
|
|
321
|
+
eq(attributionCredits.model, "linear"),
|
|
322
|
+
gte(attributionCredits.convertedAt, sinceTs),
|
|
323
|
+
isNotNull(groupCol),
|
|
324
|
+
),
|
|
325
|
+
)
|
|
326
|
+
.groupBy(attributionCredits.conversionId),
|
|
327
|
+
);
|
|
328
|
+
const overlap = await db
|
|
329
|
+
.with(claims)
|
|
330
|
+
.select({
|
|
331
|
+
currency: conversions.currency,
|
|
332
|
+
conversions: count(),
|
|
333
|
+
multiScopeConversions: sql<number>`(count(*) filter (where ${claims.scopeCount} > 1))::int`,
|
|
334
|
+
value: sql<number>`coalesce(sum(${conversions.value}), 0)::float8`,
|
|
335
|
+
scopeSummedValue: sql<number>`coalesce(sum(${conversions.value} * ${claims.scopeCount}), 0)::float8`,
|
|
336
|
+
})
|
|
337
|
+
.from(claims)
|
|
338
|
+
.innerJoin(conversions, eq(conversions.id, claims.conversionId))
|
|
339
|
+
.where(and(...definitionFilter))
|
|
340
|
+
.groupBy(conversions.currency);
|
|
341
|
+
|
|
342
|
+
const credited = sql`exists (select 1 from ${attributionCredits} where ${attributionCredits.conversionId} = ${conversions.id})`;
|
|
343
|
+
const totals = await db
|
|
344
|
+
.select({
|
|
345
|
+
currency: conversions.currency,
|
|
346
|
+
value: sql<number>`coalesce(sum(${conversions.value}), 0)::float8`,
|
|
347
|
+
conversions: count(),
|
|
348
|
+
attributedValue: sql<number>`coalesce(sum(${conversions.value}) filter (where ${credited}), 0)::float8`,
|
|
349
|
+
attributedConversions: sql<number>`(count(*) filter (where ${credited}))::int`,
|
|
350
|
+
})
|
|
351
|
+
.from(conversions)
|
|
352
|
+
.where(and(gte(conversions.occurredAt, sinceTs), ...definitionFilter))
|
|
353
|
+
.groupBy(conversions.currency);
|
|
354
|
+
|
|
355
|
+
return c.json(
|
|
356
|
+
{
|
|
357
|
+
days,
|
|
358
|
+
groupBy,
|
|
359
|
+
rows: rows.map((row) => ({
|
|
360
|
+
model: row.model,
|
|
361
|
+
key: row.key,
|
|
362
|
+
label: (row.key ? labels.get(row.key) : undefined) ?? null,
|
|
363
|
+
...(groupBy === "channel" && row.key ? { channel: row.key } : {}),
|
|
364
|
+
currency: row.currency,
|
|
365
|
+
value: row.value,
|
|
366
|
+
conversions: row.conversions,
|
|
367
|
+
touches: Number(row.touches),
|
|
368
|
+
})),
|
|
369
|
+
totals: totals.map((row) => ({
|
|
370
|
+
currency: row.currency,
|
|
371
|
+
value: row.value,
|
|
372
|
+
conversions: Number(row.conversions),
|
|
373
|
+
attributedValue: row.attributedValue,
|
|
374
|
+
attributedConversions: Number(row.attributedConversions),
|
|
375
|
+
})),
|
|
376
|
+
overlap: overlap.map((row) => ({
|
|
377
|
+
currency: row.currency,
|
|
378
|
+
conversions: Number(row.conversions),
|
|
379
|
+
multiScopeConversions: row.multiScopeConversions,
|
|
380
|
+
value: row.value,
|
|
381
|
+
scopeSummedValue: row.scopeSummedValue,
|
|
382
|
+
})),
|
|
383
|
+
influenced: influenced.map((row) => ({
|
|
384
|
+
key: row.key,
|
|
385
|
+
label: labels.get(row.key) ?? null,
|
|
386
|
+
currency: row.currency,
|
|
387
|
+
conversions: Number(row.conversions),
|
|
388
|
+
value: row.value,
|
|
389
|
+
})),
|
|
390
|
+
},
|
|
391
|
+
200,
|
|
392
|
+
);
|
|
393
|
+
})
|
|
394
|
+
.openapi(backfillRoute, async (c) => {
|
|
395
|
+
const { db, logger } = c.get("container");
|
|
396
|
+
const body = c.req.valid("json");
|
|
397
|
+
if (body.recompute && !body.definitionId) {
|
|
398
|
+
return c.json(
|
|
399
|
+
{ error: "recompute requires a definitionId — never blanket" },
|
|
400
|
+
400,
|
|
401
|
+
);
|
|
402
|
+
}
|
|
403
|
+
const result = await backfillAttributionBatch({
|
|
404
|
+
db,
|
|
405
|
+
logger,
|
|
406
|
+
registry: getConversionRegistry(),
|
|
407
|
+
definitionId: body.definitionId,
|
|
408
|
+
since: body.since ? new Date(body.since) : undefined,
|
|
409
|
+
cursor: body.cursor,
|
|
410
|
+
limit: body.limit,
|
|
411
|
+
recompute: body.recompute,
|
|
412
|
+
});
|
|
413
|
+
return c.json(result, 200);
|
|
414
|
+
});
|
|
@@ -10,6 +10,7 @@ import {
|
|
|
10
10
|
serializePrefs,
|
|
11
11
|
} from "../../lib/contacts.js";
|
|
12
12
|
import { emitOutbound } from "../../lib/outbound.js";
|
|
13
|
+
import { getContactRevenue, revenueExcludedEvents } from "../../lib/revenue.js";
|
|
13
14
|
|
|
14
15
|
const contactSchema = z.object({
|
|
15
16
|
id: z.string(),
|
|
@@ -35,6 +36,19 @@ const preferencesSchema = z
|
|
|
35
36
|
})
|
|
36
37
|
.nullable();
|
|
37
38
|
|
|
39
|
+
// Revenue rollup over the contact's valued events (`user_events.value`),
|
|
40
|
+
// grouped per currency — never summed across currencies.
|
|
41
|
+
const revenueSchema = z.object({
|
|
42
|
+
totals: z.array(
|
|
43
|
+
z.object({
|
|
44
|
+
currency: z.string().nullable(),
|
|
45
|
+
total: z.number(),
|
|
46
|
+
count: z.number(),
|
|
47
|
+
}),
|
|
48
|
+
),
|
|
49
|
+
lastValuedAt: z.string().nullable(),
|
|
50
|
+
});
|
|
51
|
+
|
|
38
52
|
const listRoute = createRoute({
|
|
39
53
|
method: "get",
|
|
40
54
|
path: "/",
|
|
@@ -45,6 +59,11 @@ const listRoute = createRoute({
|
|
|
45
59
|
limit: z.coerce.number().min(1).max(100).default(50),
|
|
46
60
|
offset: z.coerce.number().min(0).default(0),
|
|
47
61
|
search: z.string().optional(),
|
|
62
|
+
// Long-tail value filters (plan §4b.3): the "find my value customers"
|
|
63
|
+
// query surface.
|
|
64
|
+
minRevenue: z.coerce.number().optional(),
|
|
65
|
+
// Plain string: valid stages are the deployment's configured ladder.
|
|
66
|
+
dealStage: z.string().optional(),
|
|
48
67
|
}),
|
|
49
68
|
},
|
|
50
69
|
responses: {
|
|
@@ -79,10 +98,11 @@ const getRoute = createRoute({
|
|
|
79
98
|
schema: z.object({
|
|
80
99
|
contact: contactSchema,
|
|
81
100
|
preferences: preferencesSchema,
|
|
101
|
+
revenue: revenueSchema,
|
|
82
102
|
}),
|
|
83
103
|
},
|
|
84
104
|
},
|
|
85
|
-
description: "Contact with preferences",
|
|
105
|
+
description: "Contact with preferences and revenue rollup",
|
|
86
106
|
},
|
|
87
107
|
404: {
|
|
88
108
|
content: {
|
|
@@ -209,13 +229,45 @@ const serializeContact = (row: typeof contacts.$inferSelect) =>
|
|
|
209
229
|
export const contactsRouter = new OpenAPIHono<AppEnv>()
|
|
210
230
|
.openapi(listRoute, async (c) => {
|
|
211
231
|
const { db } = c.get("container");
|
|
212
|
-
const { limit, offset, search } =
|
|
232
|
+
const { limit, offset, search, minRevenue, dealStage } =
|
|
233
|
+
c.req.valid("query");
|
|
213
234
|
|
|
214
235
|
const searchFilter = search ? contactSearchFilter(search) : undefined;
|
|
215
236
|
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
237
|
+
// Valued events are keyed by the contact's canonical event key
|
|
238
|
+
// (external_id ?? anonymous_id ?? id) — same precedence ingestEvent
|
|
239
|
+
// resolves. Served by the partial user_events_valued_user_idx.
|
|
240
|
+
// Exclusions come from lib/revenue.ts (static machinery events + funnel
|
|
241
|
+
// milestone triggers + the browser trust gate): one deal's value rides
|
|
242
|
+
// several rows, and pk_-minted values are forgeable.
|
|
243
|
+
const revenueFilter =
|
|
244
|
+
minRevenue !== undefined
|
|
245
|
+
? sql`(
|
|
246
|
+
select coalesce(sum(ue.value), 0)
|
|
247
|
+
from user_events ue
|
|
248
|
+
where ue.user_id = coalesce(${contacts.externalId}, ${contacts.anonymousId}, ${contacts.id}::text)
|
|
249
|
+
and ue.value is not null
|
|
250
|
+
and ue.event not in (${sql.join(
|
|
251
|
+
revenueExcludedEvents().map((e) => sql`${e}`),
|
|
252
|
+
sql`, `,
|
|
253
|
+
)})
|
|
254
|
+
and (ue.source is null or ue.source <> 'inapp')
|
|
255
|
+
) >= ${minRevenue}`
|
|
256
|
+
: undefined;
|
|
257
|
+
const dealStageFilter = dealStage
|
|
258
|
+
? sql`exists (
|
|
259
|
+
select 1 from deals d
|
|
260
|
+
where d.contact_id = ${contacts.id}
|
|
261
|
+
and d.canonical_stage = ${dealStage}
|
|
262
|
+
)`
|
|
263
|
+
: undefined;
|
|
264
|
+
|
|
265
|
+
const where = and(
|
|
266
|
+
isNull(contacts.deletedAt),
|
|
267
|
+
...(searchFilter ? [searchFilter] : []),
|
|
268
|
+
...(revenueFilter ? [revenueFilter] : []),
|
|
269
|
+
...(dealStageFilter ? [dealStageFilter] : []),
|
|
270
|
+
);
|
|
219
271
|
|
|
220
272
|
const [rows, totalRows] = await Promise.all([
|
|
221
273
|
db
|
|
@@ -249,16 +301,24 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
|
|
|
249
301
|
|
|
250
302
|
// email_preferences.user_id uses external_id when present, else the contact
|
|
251
303
|
// uuid as the deterministic fallback (risk 10 — email-only contacts).
|
|
252
|
-
const prefRows = await
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
304
|
+
const [prefRows, revenue] = await Promise.all([
|
|
305
|
+
db
|
|
306
|
+
.select()
|
|
307
|
+
.from(emailPreferences)
|
|
308
|
+
.where(eq(emailPreferences.userId, contact.externalId ?? contact.id))
|
|
309
|
+
.limit(1),
|
|
310
|
+
// Valued events are keyed by the contact's canonical event key — the
|
|
311
|
+
// same precedence ingestEvent resolves (`external ?? anon ?? id`).
|
|
312
|
+
getContactRevenue({
|
|
313
|
+
db,
|
|
314
|
+
key: contact.externalId ?? contact.anonymousId ?? contact.id,
|
|
315
|
+
}),
|
|
316
|
+
]);
|
|
257
317
|
|
|
258
318
|
const prefs = prefRows[0] ? serializePrefs(prefRows[0]) : null;
|
|
259
319
|
|
|
260
320
|
return c.json(
|
|
261
|
-
{ contact: serializeContact(contact), preferences: prefs },
|
|
321
|
+
{ contact: serializeContact(contact), preferences: prefs, revenue },
|
|
262
322
|
200,
|
|
263
323
|
);
|
|
264
324
|
})
|