@hogsend/engine 0.46.1 → 0.51.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/campaigns/cohort-sql.ts +8 -9
- package/src/connectors/presets/index.ts +8 -2
- package/src/container.ts +150 -8
- package/src/destinations/define-destination.ts +2 -2
- 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 +200 -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/campaign-send-key.ts +9 -18
- 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 +9 -1
- package/src/lib/crm-deals.ts +1 -1
- package/src/lib/crm-ingest.ts +1 -1
- package/src/lib/email.ts +23 -2
- package/src/lib/enrollment-policy.ts +51 -0
- package/src/lib/event-names.ts +7 -1
- 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/frequency-cap.ts +4 -2
- package/src/lib/funnel-progress.ts +1 -1
- 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/holdout.ts +1 -1
- package/src/lib/ingestion.ts +38 -0
- package/src/lib/journey-lift.ts +142 -0
- package/src/lib/journey-suppress.ts +4 -2
- package/src/lib/lift-stats.ts +2 -2
- 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/tracked.ts +9 -2
- 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/attribution.ts +1 -2
- package/src/routes/admin/campaigns.ts +84 -45
- package/src/routes/admin/contacts.ts +53 -4
- package/src/routes/admin/conversions.ts +138 -1
- package/src/routes/admin/deals.ts +43 -34
- package/src/routes/admin/emails.ts +4 -6
- package/src/routes/admin/events.ts +128 -1
- package/src/routes/admin/flags.ts +369 -0
- package/src/routes/admin/groups.ts +900 -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/settings.ts +145 -0
- package/src/routes/admin/targeting.ts +259 -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/crm-reconcile.ts +1 -1
- package/src/workflows/impact-digest.ts +761 -0
- package/src/workflows/journey-blueprint-interpreter.ts +18 -1
- package/src/middleware/auth.ts +0 -24
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import { z } from "@hono/zod-openapi";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Shared wire schemas for the lift/impact admin surfaces (impact
|
|
5
|
+
* experiments D4.2) — hoisted once so the journeys router (/lift, phase
|
|
6
|
+
* 2a) and the /impact + /overview routers (phase 2b) import the SAME
|
|
7
|
+
* shapes, never ad-hoc duplicates. Frozen as the Studio contract at the
|
|
8
|
+
* end of phase 2b.
|
|
9
|
+
*
|
|
10
|
+
* FROZEN CONTRACT (phase 2b, impact-experiments): liftVerdictSchema,
|
|
11
|
+
* countsSchema, and cohortSchema are embedded in the /impact and
|
|
12
|
+
* /impact/overview wire shapes that Studio mirrors mechanically.
|
|
13
|
+
* Additive-only from here; renames/retypes need a coordinated
|
|
14
|
+
* Studio + docs change.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
/** LiftVerdict on the wire — matches lib/lift-stats.ts:86-95 exactly. */
|
|
18
|
+
export const liftVerdictSchema = z.object({
|
|
19
|
+
liftPercent: z.number().nullable(),
|
|
20
|
+
winProbability: z.number().nullable(),
|
|
21
|
+
suppressed: z.boolean(),
|
|
22
|
+
smallSample: z.boolean(),
|
|
23
|
+
});
|
|
24
|
+
|
|
25
|
+
export const countsSchema = z.object({
|
|
26
|
+
contacts: z.number(),
|
|
27
|
+
converters: z.number(),
|
|
28
|
+
rate: z.number(),
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
/** Counts + per-currency value (never summed across currencies). */
|
|
32
|
+
export const cohortSchema = countsSchema.extend({
|
|
33
|
+
value: z.array(
|
|
34
|
+
z.object({ currency: z.string().nullable(), value: z.number() }),
|
|
35
|
+
),
|
|
36
|
+
});
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Where an effective definitionId came from: explicit query param, the
|
|
40
|
+
* journey's meta.goal, or neither (any-conversion scope). Hoisted so /lift
|
|
41
|
+
* (2a) and /impact + the Studio mirror (2b/3a) share one source enum.
|
|
42
|
+
*/
|
|
43
|
+
export const definitionSourceSchema = z.enum(["query", "goal", "none"]);
|
|
44
|
+
export type DefinitionSource = z.infer<typeof definitionSourceSchema>;
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import { test } from "node:test";
|
|
3
|
+
// Importing these modules IS the construction smoke: on zod 4.4.3 a
|
|
4
|
+
// discriminated union with a duplicated literal discriminator throws at
|
|
5
|
+
// CONSTRUCTION time, which would fail these imports (the landmine the
|
|
6
|
+
// `state` discriminator avoids).
|
|
7
|
+
import {
|
|
8
|
+
globalControlSchema,
|
|
9
|
+
journeyRowSchema,
|
|
10
|
+
overviewResponseSchema,
|
|
11
|
+
} from "./impact.js";
|
|
12
|
+
import {
|
|
13
|
+
impactResponseSchema,
|
|
14
|
+
variantArmSchema,
|
|
15
|
+
versionSchema,
|
|
16
|
+
} from "./journey-impact.js";
|
|
17
|
+
|
|
18
|
+
const verdict = {
|
|
19
|
+
liftPercent: 12.5,
|
|
20
|
+
winProbability: 0.9,
|
|
21
|
+
suppressed: false,
|
|
22
|
+
smallSample: true,
|
|
23
|
+
};
|
|
24
|
+
const counts = { contacts: 10, converters: 2, rate: 0.2 };
|
|
25
|
+
const cohort = { ...counts, value: [{ currency: "USD", value: 100 }] };
|
|
26
|
+
|
|
27
|
+
test("globalControlSchema parses all three states", () => {
|
|
28
|
+
assert.equal(globalControlSchema.safeParse({ state: "off" }).success, true);
|
|
29
|
+
assert.equal(
|
|
30
|
+
globalControlSchema.safeParse({
|
|
31
|
+
state: "skipped",
|
|
32
|
+
reason: "too_many_contacts",
|
|
33
|
+
percent: 5,
|
|
34
|
+
contactCount: 600000,
|
|
35
|
+
}).success,
|
|
36
|
+
true,
|
|
37
|
+
);
|
|
38
|
+
assert.equal(
|
|
39
|
+
globalControlSchema.safeParse({
|
|
40
|
+
state: "computed",
|
|
41
|
+
causal: true,
|
|
42
|
+
percent: 5,
|
|
43
|
+
contactsScanned: 1000,
|
|
44
|
+
treatment: counts,
|
|
45
|
+
control: counts,
|
|
46
|
+
...verdict,
|
|
47
|
+
}).success,
|
|
48
|
+
true,
|
|
49
|
+
);
|
|
50
|
+
// a fourth state is rejected
|
|
51
|
+
assert.equal(
|
|
52
|
+
globalControlSchema.safeParse({ state: "unknown" }).success,
|
|
53
|
+
false,
|
|
54
|
+
);
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
test("impactResponseSchema parses a full fixture", () => {
|
|
58
|
+
const fixture = {
|
|
59
|
+
journeyId: "j",
|
|
60
|
+
days: 90,
|
|
61
|
+
goal: { definitionId: "revenue", source: "goal", name: "Revenue" },
|
|
62
|
+
holdout: { percent: 10 },
|
|
63
|
+
currentVersionHash: "abcdefabcdef",
|
|
64
|
+
currentVersionLabel: "v1",
|
|
65
|
+
overall: { causal: true, treatment: cohort, control: cohort, verdict },
|
|
66
|
+
versions: [
|
|
67
|
+
{
|
|
68
|
+
hash: "abcdefabcdef",
|
|
69
|
+
label: "v1",
|
|
70
|
+
firstEnrolledAt: "2026-07-01T00:00:00.000Z",
|
|
71
|
+
lastEnrolledAt: "2026-07-10T00:00:00.000Z",
|
|
72
|
+
enrollments: 10,
|
|
73
|
+
converters: 2,
|
|
74
|
+
rate: 0.2,
|
|
75
|
+
liftVsControl: { causal: true, control: counts, ...verdict },
|
|
76
|
+
},
|
|
77
|
+
],
|
|
78
|
+
variants: [
|
|
79
|
+
{
|
|
80
|
+
key: "subject",
|
|
81
|
+
arms: [
|
|
82
|
+
{
|
|
83
|
+
arm: "setup",
|
|
84
|
+
enrollments: 5,
|
|
85
|
+
converters: 1,
|
|
86
|
+
rate: 0.2,
|
|
87
|
+
engagement: { causal: false, sends: 5, opened: 2, clicked: 1 },
|
|
88
|
+
liftVsControl: { causal: true, ...verdict },
|
|
89
|
+
},
|
|
90
|
+
],
|
|
91
|
+
},
|
|
92
|
+
],
|
|
93
|
+
};
|
|
94
|
+
assert.equal(impactResponseSchema.safeParse(fixture).success, true);
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
test("causal-language law is structural, not editorial", () => {
|
|
98
|
+
const journeyRow = {
|
|
99
|
+
journeyId: "j",
|
|
100
|
+
name: null,
|
|
101
|
+
registered: false,
|
|
102
|
+
versionLabel: null,
|
|
103
|
+
goalDefinitionId: null,
|
|
104
|
+
holdoutPercent: null,
|
|
105
|
+
observational: {
|
|
106
|
+
causal: false,
|
|
107
|
+
enrollments: 1,
|
|
108
|
+
converters: 0,
|
|
109
|
+
rate: 0,
|
|
110
|
+
},
|
|
111
|
+
attributed: { causal: false, model: "linear", values: [] },
|
|
112
|
+
lift: { causal: true, control: counts, ...verdict },
|
|
113
|
+
};
|
|
114
|
+
assert.equal(journeyRowSchema.safeParse(journeyRow).success, true);
|
|
115
|
+
// observational block can NEVER claim causality
|
|
116
|
+
assert.equal(
|
|
117
|
+
journeyRowSchema.safeParse({
|
|
118
|
+
...journeyRow,
|
|
119
|
+
observational: { ...journeyRow.observational, causal: true },
|
|
120
|
+
}).success,
|
|
121
|
+
false,
|
|
122
|
+
);
|
|
123
|
+
// the holdout-backed lift block can NEVER be labeled observational
|
|
124
|
+
assert.equal(
|
|
125
|
+
journeyRowSchema.safeParse({
|
|
126
|
+
...journeyRow,
|
|
127
|
+
lift: { ...journeyRow.lift, causal: false },
|
|
128
|
+
}).success,
|
|
129
|
+
false,
|
|
130
|
+
);
|
|
131
|
+
// variant engagement is observational by type
|
|
132
|
+
assert.equal(
|
|
133
|
+
variantArmSchema.safeParse({
|
|
134
|
+
arm: "a",
|
|
135
|
+
enrollments: 1,
|
|
136
|
+
converters: 0,
|
|
137
|
+
rate: 0,
|
|
138
|
+
engagement: { causal: true, sends: 0, opened: 0, clicked: 0 },
|
|
139
|
+
liftVsControl: null,
|
|
140
|
+
}).success,
|
|
141
|
+
false,
|
|
142
|
+
);
|
|
143
|
+
// version liftVsControl is causal by type
|
|
144
|
+
assert.equal(
|
|
145
|
+
versionSchema.safeParse({
|
|
146
|
+
hash: null,
|
|
147
|
+
label: null,
|
|
148
|
+
firstEnrolledAt: null,
|
|
149
|
+
lastEnrolledAt: null,
|
|
150
|
+
enrollments: 0,
|
|
151
|
+
converters: 0,
|
|
152
|
+
rate: 0,
|
|
153
|
+
liftVsControl: { causal: false, control: counts, ...verdict },
|
|
154
|
+
}).success,
|
|
155
|
+
false,
|
|
156
|
+
);
|
|
157
|
+
// the campaigns SECTION is correlational-only by type
|
|
158
|
+
const overview = {
|
|
159
|
+
days: 90,
|
|
160
|
+
model: "linear",
|
|
161
|
+
rankedBy: "converters",
|
|
162
|
+
journeys: [],
|
|
163
|
+
campaigns: { causal: false, rows: [] },
|
|
164
|
+
globalControl: { state: "off" },
|
|
165
|
+
};
|
|
166
|
+
assert.equal(overviewResponseSchema.safeParse(overview).success, true);
|
|
167
|
+
assert.equal(
|
|
168
|
+
overviewResponseSchema.safeParse({
|
|
169
|
+
...overview,
|
|
170
|
+
campaigns: { causal: true, rows: [] },
|
|
171
|
+
}).success,
|
|
172
|
+
false,
|
|
173
|
+
);
|
|
174
|
+
assert.equal(
|
|
175
|
+
overviewResponseSchema.safeParse({
|
|
176
|
+
...overview,
|
|
177
|
+
rankedBy: "enrollments",
|
|
178
|
+
}).success,
|
|
179
|
+
false,
|
|
180
|
+
);
|
|
181
|
+
});
|
|
@@ -0,0 +1,486 @@
|
|
|
1
|
+
import { ATTRIBUTION_MODELS } from "@hogsend/attribution";
|
|
2
|
+
import { campaigns } from "@hogsend/db";
|
|
3
|
+
import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
|
|
4
|
+
import { inArray, sql } from "drizzle-orm";
|
|
5
|
+
import type { AppEnv } from "../../app.js";
|
|
6
|
+
import { computeGlobalControlReadout } from "../../lib/global-control-readout.js";
|
|
7
|
+
import { computeLift } from "../../lib/lift-stats.js";
|
|
8
|
+
import { countsSchema, liftVerdictSchema } from "./impact-schemas.js";
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* GET /v1/admin/impact/overview — the program-level impact readout
|
|
12
|
+
* (impact-experiments spec D4.5).
|
|
13
|
+
*
|
|
14
|
+
* FROZEN CONTRACT (phase 2b): these wire shapes ARE the Studio contract —
|
|
15
|
+
* Studio mirror types are written mechanically from them. Additive-only
|
|
16
|
+
* from here; any rename/retype needs a coordinated Studio + docs change.
|
|
17
|
+
*
|
|
18
|
+
* Causal-language law (routes/admin/funnels.ts:16): `causal` is nested per
|
|
19
|
+
* BLOCK, never per row — `observational`/`attributed`/campaigns carry
|
|
20
|
+
* `causal: false`; only holdout-backed `lift` and the computed global
|
|
21
|
+
* control carry `causal: true`.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
export const overviewLiftSchema = z
|
|
25
|
+
.object({
|
|
26
|
+
causal: z.literal(true),
|
|
27
|
+
control: countsSchema,
|
|
28
|
+
})
|
|
29
|
+
.extend(liftVerdictSchema.shape);
|
|
30
|
+
|
|
31
|
+
export const journeyRowSchema = z.object({
|
|
32
|
+
journeyId: z.string(),
|
|
33
|
+
/** Registry name; null for blueprint/removed-journey ids observed only
|
|
34
|
+
* in journey_states or the credit ledger. */
|
|
35
|
+
name: z.string().nullable(),
|
|
36
|
+
registered: z.boolean(),
|
|
37
|
+
versionLabel: z.string().nullable(), // latest-by-created_at in window
|
|
38
|
+
goalDefinitionId: z.string().nullable(),
|
|
39
|
+
/** Authored holdout percent from registry meta; null when none or
|
|
40
|
+
* unregistered. Lets consumers distinguish "no holdout configured" from
|
|
41
|
+
* "holdout configured, no held-out contacts in window yet". */
|
|
42
|
+
holdoutPercent: z.number().nullable(),
|
|
43
|
+
/** OBSERVATIONAL — enrollment funnel of the TREATED cohort only
|
|
44
|
+
* (status != 'held_out'), matching the lift route's cohort split.
|
|
45
|
+
* Nested so `causal` is unambiguous per block, never per row. */
|
|
46
|
+
observational: z.object({
|
|
47
|
+
causal: z.literal(false),
|
|
48
|
+
enrollments: z.number(),
|
|
49
|
+
converters: z.number(),
|
|
50
|
+
rate: z.number(),
|
|
51
|
+
}),
|
|
52
|
+
/** OBSERVATIONAL — fractional credit from the ledger, one model. */
|
|
53
|
+
attributed: z.object({
|
|
54
|
+
causal: z.literal(false),
|
|
55
|
+
model: z.enum(ATTRIBUTION_MODELS),
|
|
56
|
+
values: z.array(
|
|
57
|
+
z.object({
|
|
58
|
+
currency: z.string().nullable(),
|
|
59
|
+
value: z.number(), // sum(credit.value)
|
|
60
|
+
conversions: z.number(), // sum(credit.weight)
|
|
61
|
+
}),
|
|
62
|
+
),
|
|
63
|
+
}),
|
|
64
|
+
/** CAUSAL — present only where a held-out cohort exists in the window. */
|
|
65
|
+
lift: overviewLiftSchema.nullable(),
|
|
66
|
+
});
|
|
67
|
+
|
|
68
|
+
export const campaignRowSchema = z.object({
|
|
69
|
+
campaignId: z.string(),
|
|
70
|
+
name: z.string(),
|
|
71
|
+
status: z.string(),
|
|
72
|
+
sends: z.number(),
|
|
73
|
+
delivered: z.number(),
|
|
74
|
+
opened: z.number(),
|
|
75
|
+
clicked: z.number(),
|
|
76
|
+
attributed: z.array(
|
|
77
|
+
z.object({
|
|
78
|
+
currency: z.string().nullable(),
|
|
79
|
+
value: z.number(),
|
|
80
|
+
conversions: z.number(),
|
|
81
|
+
}),
|
|
82
|
+
),
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
/** Zod-4-safe: discriminated on `state` (single distinct key), NOT on a
|
|
86
|
+
* duplicated `enabled: true` literal — z.discriminatedUnion("enabled",
|
|
87
|
+
* [..two true branches..]) THROWS at construction on zod 4.4.3. */
|
|
88
|
+
export const globalControlSchema = z.discriminatedUnion("state", [
|
|
89
|
+
z.object({ state: z.literal("off") }),
|
|
90
|
+
z.object({
|
|
91
|
+
/** Assignment is ON and suppressing sends, but the readout was skipped:
|
|
92
|
+
* contact population exceeds the in-request scan ceiling. Visibly
|
|
93
|
+
* distinct from "off" — assignment-active-readout-absent must never
|
|
94
|
+
* render as disabled. */
|
|
95
|
+
state: z.literal("skipped"),
|
|
96
|
+
reason: z.literal("too_many_contacts"),
|
|
97
|
+
percent: z.number(),
|
|
98
|
+
contactCount: z.number(),
|
|
99
|
+
}),
|
|
100
|
+
z
|
|
101
|
+
.object({
|
|
102
|
+
state: z.literal("computed"),
|
|
103
|
+
causal: z.literal(true),
|
|
104
|
+
percent: z.number(), // globalControlPercent() (holdout.ts:42-46)
|
|
105
|
+
contactsScanned: z.number(),
|
|
106
|
+
treatment: countsSchema,
|
|
107
|
+
control: countsSchema,
|
|
108
|
+
})
|
|
109
|
+
.extend(liftVerdictSchema.shape),
|
|
110
|
+
]);
|
|
111
|
+
|
|
112
|
+
export const overviewResponseSchema = z.object({
|
|
113
|
+
days: z.number(),
|
|
114
|
+
model: z.enum(ATTRIBUTION_MODELS),
|
|
115
|
+
rankedBy: z.literal("converters"),
|
|
116
|
+
journeys: z.array(journeyRowSchema),
|
|
117
|
+
campaigns: z.object({
|
|
118
|
+
causal: z.literal(false), // correlational-only, whole section
|
|
119
|
+
rows: z.array(campaignRowSchema),
|
|
120
|
+
}),
|
|
121
|
+
globalControl: globalControlSchema,
|
|
122
|
+
});
|
|
123
|
+
|
|
124
|
+
const overviewRoute = createRoute({
|
|
125
|
+
method: "get",
|
|
126
|
+
path: "/overview",
|
|
127
|
+
tags: ["Admin — Impact"],
|
|
128
|
+
summary: "Program-level impact: journeys, campaigns, global control",
|
|
129
|
+
description:
|
|
130
|
+
"Journeys union in-window journey_states with in-window attribution " +
|
|
131
|
+
"credits (a journey with credits but no fresh enrollments still " +
|
|
132
|
+
"appears). Campaigns are correlational-only — no lift, no win " +
|
|
133
|
+
"probability, ever. The computed global-control block is a " +
|
|
134
|
+
"cross-sectional randomized comparison: outcome window " +
|
|
135
|
+
"occurred_at >= since for BOTH buckets — random assignment keeps it " +
|
|
136
|
+
"causal, window symmetry keeps it fair.",
|
|
137
|
+
request: {
|
|
138
|
+
query: z.object({
|
|
139
|
+
days: z.coerce.number().min(1).max(365).default(90),
|
|
140
|
+
model: z.enum(ATTRIBUTION_MODELS).default("linear"),
|
|
141
|
+
}),
|
|
142
|
+
},
|
|
143
|
+
responses: {
|
|
144
|
+
200: {
|
|
145
|
+
content: { "application/json": { schema: overviewResponseSchema } },
|
|
146
|
+
description: "Program-level readout with per-block causal labeling",
|
|
147
|
+
},
|
|
148
|
+
},
|
|
149
|
+
});
|
|
150
|
+
|
|
151
|
+
/** Bounded concurrency for the per-journey goal-refinement queries. */
|
|
152
|
+
const LIFT_CONCURRENCY = 5;
|
|
153
|
+
|
|
154
|
+
function chunk<T>(items: T[], size: number): T[][] {
|
|
155
|
+
const out: T[][] = [];
|
|
156
|
+
for (let i = 0; i < items.length; i += size) {
|
|
157
|
+
out.push(items.slice(i, i + size));
|
|
158
|
+
}
|
|
159
|
+
return out;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
type BaseRollupRow = {
|
|
163
|
+
journey_id: string;
|
|
164
|
+
version_label: string | null;
|
|
165
|
+
enrollments: number;
|
|
166
|
+
converters: number;
|
|
167
|
+
control_contacts: number;
|
|
168
|
+
control_converters: number;
|
|
169
|
+
};
|
|
170
|
+
|
|
171
|
+
export const impactOverviewRouter = new OpenAPIHono<AppEnv>().openapi(
|
|
172
|
+
overviewRoute,
|
|
173
|
+
async (c) => {
|
|
174
|
+
const { db, registry } = c.get("container");
|
|
175
|
+
const { days, model } = c.req.valid("query");
|
|
176
|
+
const since = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
|
|
177
|
+
const sinceTs = sql`${since.toISOString()}::timestamptz`;
|
|
178
|
+
|
|
179
|
+
// (a) Journey base rollup — one grouped query, any-definition outcome,
|
|
180
|
+
// latest-by-created_at version label. No deleted_at filter (matches the
|
|
181
|
+
// /lift cohort SQL precedent).
|
|
182
|
+
const baseRows = await db.execute<BaseRollupRow>(sql`
|
|
183
|
+
select
|
|
184
|
+
js.journey_id,
|
|
185
|
+
(array_agg(js.journey_version_label order by js.created_at desc)
|
|
186
|
+
filter (where js.journey_version_label is not null))[1]
|
|
187
|
+
as version_label,
|
|
188
|
+
count(distinct js.user_id)
|
|
189
|
+
filter (where js.status != 'held_out')::int as enrollments,
|
|
190
|
+
(count(distinct js.user_id) filter (where js.status != 'held_out'
|
|
191
|
+
and exists (
|
|
192
|
+
select 1 from conversions c
|
|
193
|
+
where c.user_key = js.user_id
|
|
194
|
+
and c.occurred_at >= js.created_at
|
|
195
|
+
)))::int as converters,
|
|
196
|
+
count(distinct js.user_id)
|
|
197
|
+
filter (where js.status = 'held_out')::int as control_contacts,
|
|
198
|
+
(count(distinct js.user_id) filter (where js.status = 'held_out'
|
|
199
|
+
and exists (
|
|
200
|
+
select 1 from conversions c
|
|
201
|
+
where c.user_key = js.user_id
|
|
202
|
+
and c.occurred_at >= js.created_at
|
|
203
|
+
)))::int as control_converters
|
|
204
|
+
from journey_states js
|
|
205
|
+
where js.created_at >= ${sinceTs}
|
|
206
|
+
group by js.journey_id
|
|
207
|
+
`);
|
|
208
|
+
const baseById = new Map<string, BaseRollupRow>(
|
|
209
|
+
[...baseRows].map((r) => [r.journey_id, r]),
|
|
210
|
+
);
|
|
211
|
+
|
|
212
|
+
// (c) Attributed value — one grouped ledger query, ONE model.
|
|
213
|
+
const creditRows = await db.execute<{
|
|
214
|
+
journey_id: string;
|
|
215
|
+
currency: string | null;
|
|
216
|
+
value: number;
|
|
217
|
+
conversions: number;
|
|
218
|
+
}>(sql`
|
|
219
|
+
select journey_id, currency,
|
|
220
|
+
coalesce(sum(value), 0)::float8 as value,
|
|
221
|
+
sum(weight)::float8 as conversions
|
|
222
|
+
from attribution_credits
|
|
223
|
+
where model = ${model}
|
|
224
|
+
and converted_at >= ${sinceTs}
|
|
225
|
+
and journey_id is not null
|
|
226
|
+
group by journey_id, currency
|
|
227
|
+
`);
|
|
228
|
+
const creditsByJourney = new Map<
|
|
229
|
+
string,
|
|
230
|
+
Array<{ currency: string | null; value: number; conversions: number }>
|
|
231
|
+
>();
|
|
232
|
+
for (const r of [...creditRows]) {
|
|
233
|
+
const list = creditsByJourney.get(r.journey_id) ?? [];
|
|
234
|
+
list.push({
|
|
235
|
+
currency: r.currency,
|
|
236
|
+
value: Number(r.value),
|
|
237
|
+
conversions: Number(r.conversions),
|
|
238
|
+
});
|
|
239
|
+
creditsByJourney.set(r.journey_id, list);
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
// Union of journey ids from (a) AND (c) — a journey with in-window
|
|
243
|
+
// credits but zero in-window state rows still appears.
|
|
244
|
+
const journeyIds = [
|
|
245
|
+
...new Set([...baseById.keys(), ...creditsByJourney.keys()]),
|
|
246
|
+
];
|
|
247
|
+
|
|
248
|
+
// (b) Goal refinement — for ids whose registry meta declares a goal,
|
|
249
|
+
// re-run the aggregate WITH `js.journey_id = id` in the WHERE (per
|
|
250
|
+
// journey, never a full re-scan) and the goal's definition_id in both
|
|
251
|
+
// EXISTS. Goal-scoped converters REPLACE the any-definition counts for
|
|
252
|
+
// that row only; enrollments/control_contacts are definition-free.
|
|
253
|
+
const goalIds = journeyIds.filter((jid) => registry.get(jid)?.goal);
|
|
254
|
+
const refined = new Map<
|
|
255
|
+
string,
|
|
256
|
+
{ converters: number; control_converters: number }
|
|
257
|
+
>();
|
|
258
|
+
for (const group of chunk(goalIds, LIFT_CONCURRENCY)) {
|
|
259
|
+
await Promise.all(
|
|
260
|
+
group.map(async (jid) => {
|
|
261
|
+
const goal = registry.get(jid)?.goal;
|
|
262
|
+
if (!goal) return;
|
|
263
|
+
const rows = await db.execute<{
|
|
264
|
+
converters: number;
|
|
265
|
+
control_converters: number;
|
|
266
|
+
}>(sql`
|
|
267
|
+
select
|
|
268
|
+
(count(distinct js.user_id)
|
|
269
|
+
filter (where js.status != 'held_out' and exists (
|
|
270
|
+
select 1 from conversions c
|
|
271
|
+
where c.user_key = js.user_id
|
|
272
|
+
and c.occurred_at >= js.created_at
|
|
273
|
+
and c.definition_id = ${goal}
|
|
274
|
+
)))::int as converters,
|
|
275
|
+
(count(distinct js.user_id)
|
|
276
|
+
filter (where js.status = 'held_out' and exists (
|
|
277
|
+
select 1 from conversions c
|
|
278
|
+
where c.user_key = js.user_id
|
|
279
|
+
and c.occurred_at >= js.created_at
|
|
280
|
+
and c.definition_id = ${goal}
|
|
281
|
+
)))::int as control_converters
|
|
282
|
+
from journey_states js
|
|
283
|
+
where js.journey_id = ${jid}
|
|
284
|
+
and js.created_at >= ${sinceTs}
|
|
285
|
+
`);
|
|
286
|
+
const row = [...rows][0];
|
|
287
|
+
if (row) {
|
|
288
|
+
refined.set(jid, {
|
|
289
|
+
converters: Number(row.converters),
|
|
290
|
+
control_converters: Number(row.control_converters),
|
|
291
|
+
});
|
|
292
|
+
}
|
|
293
|
+
}),
|
|
294
|
+
);
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
const journeyRows = journeyIds.map((jid) => {
|
|
298
|
+
const meta = registry.get(jid);
|
|
299
|
+
const base = baseById.get(jid);
|
|
300
|
+
const goalCounts = refined.get(jid);
|
|
301
|
+
const enrollments = Number(base?.enrollments ?? 0);
|
|
302
|
+
const converters =
|
|
303
|
+
goalCounts?.converters ?? Number(base?.converters ?? 0);
|
|
304
|
+
const controlContacts = Number(base?.control_contacts ?? 0);
|
|
305
|
+
const controlConverters =
|
|
306
|
+
goalCounts?.control_converters ?? Number(base?.control_converters ?? 0);
|
|
307
|
+
return {
|
|
308
|
+
journeyId: jid,
|
|
309
|
+
name: meta?.name ?? null,
|
|
310
|
+
registered: meta !== undefined,
|
|
311
|
+
versionLabel: base?.version_label ?? null,
|
|
312
|
+
goalDefinitionId: meta?.goal ?? null,
|
|
313
|
+
holdoutPercent: meta?.holdout?.percent ?? null,
|
|
314
|
+
observational: {
|
|
315
|
+
causal: false as const,
|
|
316
|
+
enrollments,
|
|
317
|
+
converters,
|
|
318
|
+
rate: enrollments > 0 ? converters / enrollments : 0,
|
|
319
|
+
},
|
|
320
|
+
attributed: {
|
|
321
|
+
causal: false as const,
|
|
322
|
+
model,
|
|
323
|
+
values: creditsByJourney.get(jid) ?? [],
|
|
324
|
+
},
|
|
325
|
+
lift:
|
|
326
|
+
controlContacts > 0
|
|
327
|
+
? {
|
|
328
|
+
causal: true as const,
|
|
329
|
+
control: {
|
|
330
|
+
contacts: controlContacts,
|
|
331
|
+
converters: controlConverters,
|
|
332
|
+
rate:
|
|
333
|
+
controlContacts > 0
|
|
334
|
+
? controlConverters / controlContacts
|
|
335
|
+
: 0,
|
|
336
|
+
},
|
|
337
|
+
...computeLift({
|
|
338
|
+
treatment: { contacts: enrollments, converters },
|
|
339
|
+
control: {
|
|
340
|
+
contacts: controlContacts,
|
|
341
|
+
converters: controlConverters,
|
|
342
|
+
},
|
|
343
|
+
}),
|
|
344
|
+
}
|
|
345
|
+
: null,
|
|
346
|
+
};
|
|
347
|
+
});
|
|
348
|
+
journeyRows.sort(
|
|
349
|
+
(a, b) =>
|
|
350
|
+
b.observational.converters - a.observational.converters ||
|
|
351
|
+
b.observational.enrollments - a.observational.enrollments ||
|
|
352
|
+
(a.journeyId < b.journeyId ? -1 : a.journeyId > b.journeyId ? 1 : 0),
|
|
353
|
+
);
|
|
354
|
+
|
|
355
|
+
// (d) Campaigns — correlational only, ACTIVITY-windowed enumeration:
|
|
356
|
+
// ids come from the in-window email_sends campaign_id rollup ∪ in-window
|
|
357
|
+
// attribution_credits.campaign_id (NOT "newest 50 created in window" —
|
|
358
|
+
// that drops older-but-active multi-step/scheduled campaigns whose
|
|
359
|
+
// sends fall inside the window). Cap 50 by send volume desc. The
|
|
360
|
+
// indexed campaign_id column is the attribution (stamped at send time,
|
|
361
|
+
// backfilled from legacy idempotency keys by migration 0051) — never
|
|
362
|
+
// key parsing. Policy-suppressed rows (status 'suppressed') carry the FK
|
|
363
|
+
// but were never dispatched, so they stay out of the funnel; provider
|
|
364
|
+
// failures (status 'failed', key released) stay IN it as attempts.
|
|
365
|
+
const [campaignSendRows, campaignCreditRows] = await Promise.all([
|
|
366
|
+
db.execute<{
|
|
367
|
+
campaign_id: string;
|
|
368
|
+
sends: number;
|
|
369
|
+
delivered: number;
|
|
370
|
+
opened: number;
|
|
371
|
+
clicked: number;
|
|
372
|
+
}>(sql`
|
|
373
|
+
select campaign_id::text as campaign_id,
|
|
374
|
+
count(*)::int as sends,
|
|
375
|
+
count(delivered_at)::int as delivered,
|
|
376
|
+
count(opened_at)::int as opened,
|
|
377
|
+
count(clicked_at)::int as clicked
|
|
378
|
+
from email_sends
|
|
379
|
+
where campaign_id is not null
|
|
380
|
+
and status <> 'suppressed'
|
|
381
|
+
and created_at >= ${sinceTs}
|
|
382
|
+
group by 1
|
|
383
|
+
`),
|
|
384
|
+
db.execute<{
|
|
385
|
+
campaign_id: string;
|
|
386
|
+
currency: string | null;
|
|
387
|
+
value: number;
|
|
388
|
+
conversions: number;
|
|
389
|
+
}>(sql`
|
|
390
|
+
select campaign_id::text as campaign_id, currency,
|
|
391
|
+
coalesce(sum(value), 0)::float8 as value,
|
|
392
|
+
sum(weight)::float8 as conversions
|
|
393
|
+
from attribution_credits
|
|
394
|
+
where model = ${model}
|
|
395
|
+
and converted_at >= ${sinceTs}
|
|
396
|
+
and campaign_id is not null
|
|
397
|
+
group by campaign_id, currency
|
|
398
|
+
`),
|
|
399
|
+
]);
|
|
400
|
+
|
|
401
|
+
const sendsByCampaign = new Map(
|
|
402
|
+
[...campaignSendRows].map((r) => [
|
|
403
|
+
r.campaign_id,
|
|
404
|
+
{
|
|
405
|
+
sends: Number(r.sends),
|
|
406
|
+
delivered: Number(r.delivered),
|
|
407
|
+
opened: Number(r.opened),
|
|
408
|
+
clicked: Number(r.clicked),
|
|
409
|
+
},
|
|
410
|
+
]),
|
|
411
|
+
);
|
|
412
|
+
const creditsByCampaign = new Map<
|
|
413
|
+
string,
|
|
414
|
+
Array<{ currency: string | null; value: number; conversions: number }>
|
|
415
|
+
>();
|
|
416
|
+
for (const r of [...campaignCreditRows]) {
|
|
417
|
+
const list = creditsByCampaign.get(r.campaign_id) ?? [];
|
|
418
|
+
list.push({
|
|
419
|
+
currency: r.currency,
|
|
420
|
+
value: Number(r.value),
|
|
421
|
+
conversions: Number(r.conversions),
|
|
422
|
+
});
|
|
423
|
+
creditsByCampaign.set(r.campaign_id, list);
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
const campaignIds = [
|
|
427
|
+
...new Set([...sendsByCampaign.keys(), ...creditsByCampaign.keys()]),
|
|
428
|
+
]
|
|
429
|
+
.sort(
|
|
430
|
+
(a, b) =>
|
|
431
|
+
(sendsByCampaign.get(b)?.sends ?? 0) -
|
|
432
|
+
(sendsByCampaign.get(a)?.sends ?? 0),
|
|
433
|
+
)
|
|
434
|
+
.slice(0, 50);
|
|
435
|
+
|
|
436
|
+
const campaignInfo =
|
|
437
|
+
campaignIds.length > 0
|
|
438
|
+
? await db
|
|
439
|
+
.select({
|
|
440
|
+
id: campaigns.id,
|
|
441
|
+
name: campaigns.name,
|
|
442
|
+
status: campaigns.status,
|
|
443
|
+
})
|
|
444
|
+
.from(campaigns)
|
|
445
|
+
.where(inArray(campaigns.id, campaignIds))
|
|
446
|
+
: [];
|
|
447
|
+
const infoById = new Map(campaignInfo.map((r) => [r.id, r]));
|
|
448
|
+
|
|
449
|
+
// Ids with no campaigns row (hard-deleted) are dropped — name/status
|
|
450
|
+
// are unknowable and the wire contract requires both.
|
|
451
|
+
const campaignRows = campaignIds.flatMap((cid) => {
|
|
452
|
+
const info = infoById.get(cid);
|
|
453
|
+
if (!info) return [];
|
|
454
|
+
const funnel = sendsByCampaign.get(cid) ?? {
|
|
455
|
+
sends: 0,
|
|
456
|
+
delivered: 0,
|
|
457
|
+
opened: 0,
|
|
458
|
+
clicked: 0,
|
|
459
|
+
};
|
|
460
|
+
return [
|
|
461
|
+
{
|
|
462
|
+
campaignId: cid,
|
|
463
|
+
name: info.name,
|
|
464
|
+
status: info.status,
|
|
465
|
+
...funnel,
|
|
466
|
+
attributed: creditsByCampaign.get(cid) ?? [],
|
|
467
|
+
},
|
|
468
|
+
];
|
|
469
|
+
});
|
|
470
|
+
// (e) Global control — JS re-hash, batched keyset pagination; the
|
|
471
|
+
// three-state result is the wire block verbatim.
|
|
472
|
+
const globalControl = await computeGlobalControlReadout({ db, since });
|
|
473
|
+
|
|
474
|
+
return c.json(
|
|
475
|
+
{
|
|
476
|
+
days,
|
|
477
|
+
model,
|
|
478
|
+
rankedBy: "converters" as const,
|
|
479
|
+
journeys: journeyRows,
|
|
480
|
+
campaigns: { causal: false as const, rows: campaignRows },
|
|
481
|
+
globalControl,
|
|
482
|
+
},
|
|
483
|
+
200,
|
|
484
|
+
);
|
|
485
|
+
},
|
|
486
|
+
);
|