@hogsend/engine 0.50.0 → 0.52.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.
@@ -9,9 +9,11 @@ export type RecordNamespace =
9
9
  | "__once__"
10
10
  | "__digest__"
11
11
  | "__throttle__"
12
- | "__variants__";
12
+ | "__variants__"
13
+ | "__groupKeys__"
14
+ | "__waits__";
13
15
 
14
- // Closed-union → validated path token. NOT user input: only these four literals
16
+ // Closed-union → validated path token. NOT user input: only these six literals
15
17
  // reach the interpolated jsonb path below, so it is injection-safe. `key` and the
16
18
  // JSON-stringified value are ALWAYS bound parameters regardless.
17
19
  const NAMESPACE_TOKEN: Record<RecordNamespace, string> = {
@@ -19,6 +21,8 @@ const NAMESPACE_TOKEN: Record<RecordNamespace, string> = {
19
21
  __digest__: "__digest__",
20
22
  __throttle__: "__throttle__",
21
23
  __variants__: "__variants__",
24
+ __groupKeys__: "__groupKeys__",
25
+ __waits__: "__waits__",
22
26
  };
23
27
 
24
28
  /** Extract the `(namespace)` sub-bag from an already-fetched context, `{}` when
@@ -114,6 +118,27 @@ export async function recordOnce<T>(opts: {
114
118
  return value;
115
119
  }
116
120
 
121
+ /**
122
+ * Read an already-recorded `(stateId, namespace, key)` value WITHOUT computing
123
+ * or writing — `undefined` when nothing is recorded. The read-only companion
124
+ * to {@link recordOnce} for call sites whose compute would issue durable work
125
+ * (recordOnce's `compute` must never add journal nodes).
126
+ */
127
+ export async function readRecordedValue(opts: {
128
+ db: Database;
129
+ stateId: string;
130
+ namespace: RecordNamespace;
131
+ key: string;
132
+ }): Promise<unknown> {
133
+ const { db, stateId, namespace, key } = opts;
134
+ const row = await db.query.journeyStates.findFirst({
135
+ where: eq(journeyStates.id, stateId),
136
+ columns: { context: true },
137
+ });
138
+ const bag = namespaceBag(row?.context, namespace);
139
+ return Object.hasOwn(bag, key) ? bag[key] : undefined;
140
+ }
141
+
117
142
  /**
118
143
  * Drop ALL reserved record-once namespace keys from an event-properties bag.
119
144
  * Enrollment seeds `journey_states.context` from trigger-event properties
@@ -1,16 +1,18 @@
1
1
  /**
2
2
  * The deterministic per-recipient idempotency key a campaign send writes to
3
- * `email_sends.idempotency_key`. This key is ALSO how a send row is
4
- * attributed back to its campaign (there is no campaign_id FK on
5
- * email_sends), so the format is owned here — the send-campaign task mints
6
- * keys with `campaignSendKey` and the admin campaign-stats/sends routes match
7
- * them with the pattern helpers.
3
+ * `email_sends.idempotency_key`. The key exists for DEDUP; campaign
4
+ * attribution is the `email_sends.campaign_id` column (stamped on every
5
+ * campaign-dispatched row including suppressed sends, which write no key at
6
+ * all; legacy rows backfilled by migration 0051). The one thing the key
7
+ * still uniquely carries is the STEP NUMBER of a multi-step campaign, which
8
+ * is why the per-step stats breakdown matches `campaignStepSendKeyPattern`
9
+ * (scoped to the campaign_id FK first).
8
10
  *
9
11
  * Two formats, chosen by the campaign's step count (NOT per call site):
10
12
  *
11
13
  * - Single-step campaigns (steps.length === 1 or a NULL steps blob) ALWAYS
12
- * use the legacy `campaign:<id>:<email>` — behavior, stats queries, and
13
- * any in-flight campaign at deploy time are byte-for-byte unchanged.
14
+ * use the legacy `campaign:<id>:<email>` — behavior and any in-flight
15
+ * campaign at deploy time are byte-for-byte unchanged.
14
16
  * - Multi-step campaigns use `campaign:<id>:<step>:<email>` for ALL steps
15
17
  * including 0. No ambiguity with the legacy format is possible (no
16
18
  * multi-step campaign exists before this ships), and per-step stats
@@ -34,17 +36,6 @@ function escapeLike(value: string): string {
34
36
  return value.replace(/([\\%_])/g, "\\$1");
35
37
  }
36
38
 
37
- /**
38
- * SQL LIKE pattern matching every send of one campaign — a correct superset
39
- * of BOTH key formats (legacy and step-scoped), so campaign-level stats need
40
- * no format awareness. The id is escaped so LIKE metacharacters in it can't
41
- * widen the match (ids are UUIDs today, but the route accepts arbitrary
42
- * strings).
43
- */
44
- export function campaignSendKeyPattern(campaignId: string): string {
45
- return `campaign:${escapeLike(campaignId)}:%`;
46
- }
47
-
48
39
  /**
49
40
  * SQL LIKE pattern matching every send of ONE step of a multi-step campaign
50
41
  * (`campaign:<id>:<step>:%`). Meaningless against legacy single-step keys —
@@ -12,7 +12,7 @@ import { REVENUE_EXCLUDED_EVENTS } from "./revenue.js";
12
12
  import { createOptionalSingleton } from "./singleton.js";
13
13
 
14
14
  /**
15
- * Conversion evaluation at ingest (docs/revenue-attribution-plan.md §5.1) —
15
+ * Conversion evaluation at ingest —
16
16
  * the hook `ingestEvent` calls after a FRESH event insert. Definitions are
17
17
  * code-first (`createHogsendClient({ conversions })`); a fired instance is
18
18
  * recorded once per (definition, event row) — the unique index makes a
@@ -10,7 +10,7 @@ import type { Logger } from "./logger.js";
10
10
 
11
11
  /**
12
12
  * The deals projection + external-id alias map
13
- * (docs/revenue-attribution-plan.md §4.2). Events stay the append-only truth;
13
+ *. Events stay the append-only truth;
14
14
  * this module materializes current deal state with the MONOTONIC stage rule:
15
15
  * a change applies only when it advances the canonical rank (heals
16
16
  * webhook+poll double-detection and out-of-order delivery), `lost` applies
@@ -20,7 +20,7 @@ import { emitOutbound } from "./outbound.js";
20
20
  /**
21
21
  * Land normalized {@link CrmStageEvent}s on the spine — the shared sink of
22
22
  * BOTH the webhook route and the reconciliation poll
23
- * (docs/revenue-attribution-plan.md §4).
23
+ *.
24
24
  *
25
25
  * Per event: (1) resolve the contact — `crm_links` alias first (works with
26
26
  * zero PII in the payload), else the payload email (minting the links so the
@@ -14,7 +14,7 @@
14
14
  */
15
15
  import { journeyBlueprints, userEvents } from "@hogsend/db";
16
16
  import { z } from "@hono/zod-openapi";
17
- import { count, desc, ilike, inArray, max } from "drizzle-orm";
17
+ import { count, desc, ilike, inArray, max, min } from "drizzle-orm";
18
18
  import type { HogsendClient } from "../container.js";
19
19
 
20
20
  /**
@@ -25,6 +25,7 @@ import type { HogsendClient } from "../container.js";
25
25
  export const eventNameEntrySchema = z.object({
26
26
  name: z.string(),
27
27
  occurrences: z.number(),
28
+ firstSeenAt: z.string().nullable(),
28
29
  lastSeenAt: z.string().nullable(),
29
30
  // Where the name is declared as a trigger: "journey:<id>" for code journeys,
30
31
  // "blueprint:<id> (<status>)" for blueprints.
@@ -58,6 +59,7 @@ export async function listEventNameVocabulary(opts: {
58
59
  .select({
59
60
  name: userEvents.event,
60
61
  occurrences: count(),
62
+ firstSeenAt: min(userEvents.occurredAt),
61
63
  lastSeenAt: lastSeen,
62
64
  })
63
65
  .from(userEvents)
@@ -79,6 +81,7 @@ export async function listEventNameVocabulary(opts: {
79
81
  byName.set(row.name, {
80
82
  name: row.name,
81
83
  occurrences: Number(row.occurrences),
84
+ firstSeenAt: row.firstSeenAt?.toISOString() ?? null,
82
85
  lastSeenAt: row.lastSeenAt?.toISOString() ?? null,
83
86
  usedBy: [],
84
87
  });
@@ -92,6 +95,7 @@ export async function listEventNameVocabulary(opts: {
92
95
  const created: EventNameEntry = {
93
96
  name,
94
97
  occurrences: 0,
98
+ firstSeenAt: null,
95
99
  lastSeenAt: null,
96
100
  usedBy: [],
97
101
  };
@@ -126,6 +130,7 @@ export async function listEventNameVocabulary(opts: {
126
130
  .select({
127
131
  name: userEvents.event,
128
132
  occurrences: count(),
133
+ firstSeenAt: min(userEvents.occurredAt),
129
134
  lastSeenAt: max(userEvents.occurredAt),
130
135
  })
131
136
  .from(userEvents)
@@ -135,6 +140,7 @@ export async function listEventNameVocabulary(opts: {
135
140
  const entry = byName.get(row.name);
136
141
  if (!entry) continue;
137
142
  entry.occurrences = Number(row.occurrences);
143
+ entry.firstSeenAt = row.firstSeenAt?.toISOString() ?? null;
138
144
  entry.lastSeenAt = row.lastSeenAt?.toISOString() ?? null;
139
145
  }
140
146
  }
@@ -1,7 +1,7 @@
1
1
  import { durationToMs } from "@hogsend/core";
2
2
  import type { Database } from "@hogsend/db";
3
3
  import { emailSends } from "@hogsend/db";
4
- import { and, count, eq, gte, ne } from "drizzle-orm";
4
+ import { and, count, eq, gte, notInArray } from "drizzle-orm";
5
5
  import type { FrequencyCapConfig } from "./email-service-types.js";
6
6
 
7
7
  const DEFAULT_EXEMPT = ["transactional"];
@@ -28,7 +28,9 @@ export async function countRecentSends(opts: {
28
28
  const conditions = [
29
29
  eq(emailSends.toEmail, to),
30
30
  gte(emailSends.createdAt, since),
31
- ne(emailSends.status, "failed"),
31
+ // Neither dispatch failures nor policy-suppressed rows reached the inbox,
32
+ // so neither consumes cap budget.
33
+ notInArray(emailSends.status, ["failed", "suppressed"]),
32
34
  ];
33
35
  if (category !== undefined) {
34
36
  conditions.push(eq(emailSends.category, category));
@@ -5,7 +5,7 @@ import { resolveFunnelTargets } from "./funnel-transitions.js";
5
5
  import type { Logger } from "./logger.js";
6
6
 
7
7
  /**
8
- * Event-funnel REPORTING projection (docs/attribution-impact-plan.md §3.3) —
8
+ * Event-funnel REPORTING projection —
9
9
  * one first-reach row per (contact, funnel, stage), the raw material for
10
10
  * progression counts ("how many reached activated") and velocity ("median
11
11
  * time signed_up → activated"). Complements the deals projection the
@@ -1,7 +1,7 @@
1
1
  import { createHash } from "node:crypto";
2
2
 
3
3
  /**
4
- * Deterministic holdout assignment (docs/attribution-impact-plan.md §4.1).
4
+ * Deterministic holdout assignment.
5
5
  * NO RNG and NO clock — the replay law: journey tasks replay-from-top on
6
6
  * eviction/crash, so the same (userId, journeyId, salt) must bucket
7
7
  * identically on every evaluation, forever. sha256's first 4 bytes give a
@@ -563,6 +563,12 @@ export async function ingestEvent(opts: {
563
563
  // (folds, never mints a twin). Additive/optional — consumers ignoring it
564
564
  // are unaffected.
565
565
  contactId,
566
+ // The event's group association map (groupType → groupKey), so a
567
+ // group-scoped wait can match on membership straight off the wire.
568
+ // Always present ({} when the event carries none) so downstream CEL
569
+ // filters never key on an absent field. Additive — existing consumers
570
+ // ignore it.
571
+ groups: event.groups ?? {},
566
572
  }),
567
573
  checkExits(db, registry, hatchet, logger, {
568
574
  userId: resolvedKey,
@@ -1,6 +1,6 @@
1
1
  import type { Database } from "@hogsend/db";
2
2
  import { emailSends, journeyStates, smsSends } from "@hogsend/db";
3
- import { and, eq, gte, ne } from "drizzle-orm";
3
+ import { and, eq, gte, ne, notInArray } from "drizzle-orm";
4
4
  import type { JourneyBoundary } from "../journeys/journey-boundary.js";
5
5
  import { recordOnce } from "../journeys/record-once.js";
6
6
 
@@ -29,7 +29,9 @@ export async function hasRecentJourneySend(opts: {
29
29
  eq(journeyStates.journeyId, opts.journeyId),
30
30
  eq(emailSends.toEmail, opts.to),
31
31
  gte(emailSends.createdAt, opts.since),
32
- ne(emailSends.status, "failed"),
32
+ // Failed and policy-suppressed rows never reached the inbox — neither
33
+ // counts as a recent journey touch for the min-gap.
34
+ notInArray(emailSends.status, ["failed", "suppressed"]),
33
35
  ),
34
36
  )
35
37
  .limit(1);
@@ -1,6 +1,6 @@
1
1
  /**
2
- * Holdout lift statistics (docs/attribution-impact-plan.md §4.2, open Q1
3
- * resolved): Bayesian beta-binomial with a uniform Beta(1,1) prior — the
2
+ * Holdout lift statistics: Bayesian beta-binomial with a uniform Beta(1,1)
3
+ * prior — the
4
4
  * lean, honest method at self-hosted volumes. Win probability is
5
5
  * P(treatment rate > control rate) under independent posteriors
6
6
  * Beta(k+1, n−k+1), computed by DETERMINISTIC numeric integration (no
@@ -213,7 +213,12 @@ async function sendTrackedEmailInner<K extends TemplateName>(
213
213
  campaignId: options.campaignId,
214
214
  userId: options.userId,
215
215
  userEmail: options.userEmail ?? options.to,
216
- status: "failed",
216
+ // First-class "suppressed" status: a provider dispatch failure
217
+ // releases its idempotency key (catch block below), making it
218
+ // byte-identical to this row EXCEPT for the status — so campaign
219
+ // stats can only tell "gated by policy" from "failed at dispatch"
220
+ // if suppression names itself here.
221
+ status: "suppressed",
217
222
  // A suppressed send does NOT consume the idempotency key — leaving it
218
223
  // unset lets a later retry (e.g. after the recipient re-subscribes)
219
224
  // actually attempt the send rather than dedup to the suppressed row.
@@ -398,7 +403,9 @@ async function sendTrackedEmailInner<K extends TemplateName>(
398
403
  campaignId: options.campaignId,
399
404
  userId: options.userId,
400
405
  userEmail: options.userEmail ?? options.to,
401
- status: "failed",
406
+ // Policy-gated like suppression (the provider is never reached), so it
407
+ // shares the "suppressed" status; metadata.testMode marks the cause.
408
+ status: "suppressed",
402
409
  metadata: { testMode: true, originalTo: options.to },
403
410
  })
404
411
  .returning({ id: emailSends.id });
@@ -6,8 +6,7 @@ import { backfillAttributionBatch } from "../../lib/attribution-backfill.js";
6
6
  import { getConversionRegistry } from "../../lib/conversions.js";
7
7
 
8
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.
9
+ * Admin attribution API — reads over the credit ledger.
11
10
  * Every model was persisted at conversion time, so model comparison is a
12
11
  * GROUP BY, not a re-computation — and since the ledger carries
13
12
  * journey/campaign/template scope, "revenue by journey" is too.
@@ -9,12 +9,19 @@
9
9
  import { type CampaignStep, durationToMs } from "@hogsend/core";
10
10
  import { campaigns, emailSends } from "@hogsend/db";
11
11
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
12
- import { and, count, desc, eq, inArray, like, max, sql } from "drizzle-orm";
13
- import type { AppEnv } from "../../app.js";
14
12
  import {
15
- campaignSendKeyPattern,
16
- campaignStepSendKeyPattern,
17
- } from "../../lib/campaign-send-key.js";
13
+ and,
14
+ count,
15
+ desc,
16
+ eq,
17
+ inArray,
18
+ like,
19
+ max,
20
+ type SQL,
21
+ sql,
22
+ } from "drizzle-orm";
23
+ import type { AppEnv } from "../../app.js";
24
+ import { campaignStepSendKeyPattern } from "../../lib/campaign-send-key.js";
18
25
  import { errorSchema } from "../../lib/schemas.js";
19
26
  import { campaignSchema, serializeCampaign } from "../campaigns/index.js";
20
27
 
@@ -68,9 +75,12 @@ const getRouteDef = createRoute({
68
75
  /**
69
76
  * One row of the per-step breakdown for a multi-step campaign: the step's
70
77
  * identity (`kind` + `templateKey` for send steps, `durationMs` for wait
71
- * steps) plus the same engagement aggregate as the campaign level, scoped to
72
- * the step's `campaign:<id>:<step>:%` idempotency-key pattern. Wait steps
73
- * deliver nothing, so their counts are zeroed.
78
+ * steps) plus the same engagement aggregate as the campaign level. The step
79
+ * number only lives in the `campaign:<id>:<step>:%` idempotency-key format,
80
+ * so step rows anchor on that pattern (scoped to the campaign_id FK first) —
81
+ * which also means suppressed sends (no key) can never attribute to a step,
82
+ * so step rows carry no `skipped` (it lives at the campaign level only).
83
+ * Wait steps deliver nothing, so their counts are zeroed.
74
84
  */
75
85
  const campaignStepStatsSchema = z.object({
76
86
  index: z.number(),
@@ -89,13 +99,16 @@ const campaignStepStatsSchema = z.object({
89
99
 
90
100
  /**
91
101
  * Post-dispatch engagement for one campaign, aggregated from the `email_sends`
92
- * rows the blast wrote (attributed via the `campaign:<id>:…` idempotency
93
- * key — there is no campaign FK on email_sends). Complements the counters on
94
- * the campaign row itself: the row knows sent/skipped/failed at dispatch time,
95
- * this knows what happened to the mail AFTERWARDS (delivered/opened/clicked/
96
- * bounced/complained via first-party tracking + provider webhooks). Multi-step
97
- * campaigns additionally carry `steps` — one entry per step, in step order
98
- * (the campaign-level numbers are a superset of every step's).
102
+ * rows the blast wrote — attributed via the indexed `campaign_id` column
103
+ * (stamped at send time, backfilled from legacy idempotency keys by migration
104
+ * 0051), NOT by parsing the key: suppressed sends write no key at all, so a
105
+ * key scan can never see them. Complements the counters on the campaign row
106
+ * itself: the row knows sent/skipped/failed at dispatch time, this knows what
107
+ * happened to the mail AFTERWARDS (delivered/opened/clicked/bounced/complained
108
+ * via first-party tracking + provider webhooks) plus the policy-suppressed
109
+ * rows (status `suppressed`) as `skipped`. Multi-step campaigns additionally
110
+ * carry `steps` — one entry per step, in step order (the campaign-level
111
+ * numbers are a superset of every step's).
99
112
  */
100
113
  const campaignStatsSchema = z.object({
101
114
  sends: z.number(),
@@ -105,6 +118,7 @@ const campaignStatsSchema = z.object({
105
118
  bounced: z.number(),
106
119
  complained: z.number(),
107
120
  failed: z.number(),
121
+ skipped: z.number(),
108
122
  lastSentAt: z.string().nullable(),
109
123
  steps: z.array(campaignStepStatsSchema).optional(),
110
124
  });
@@ -213,15 +227,22 @@ export const adminCampaignsRouter = new OpenAPIHono<AppEnv>()
213
227
  }
214
228
 
215
229
  // count(column) counts non-NULL values, so each engagement timestamp
216
- // doubles as its own tally. No campaign FK on email_sends — the LIKE on the
217
- // deterministic idempotency key is the attribution (admin-plane traffic, so
218
- // the prefix scan is acceptable without a dedicated index). Shared by the
230
+ // doubles as its own tally. Attribution is the indexed `campaign_id`
231
+ // column (stamped on every campaign row including suppressed sends;
232
+ // legacy rows backfilled by migration 0051). The status column carries
233
+ // the dispatch verdict: policy-gated rows are `suppressed` (the `skipped`
234
+ // bucket), everything else was a dispatch attempt (`sends`), and `failed`
235
+ // means failed AT dispatch — a provider failure releases its idempotency
236
+ // key, so key-nullness deliberately plays no part here. Shared by the
219
237
  // campaign-level aggregate and the per-step breakdown.
220
- const aggregate = async (pattern: string) => {
238
+ const aggregate = async (where: SQL | undefined) => {
221
239
  const agg = (
222
240
  await db
223
241
  .select({
224
- sends: count(),
242
+ sends:
243
+ sql<number>`count(*) filter (where ${emailSends.status} <> 'suppressed')`.mapWith(
244
+ Number,
245
+ ),
225
246
  delivered: count(emailSends.deliveredAt),
226
247
  opened: count(emailSends.openedAt),
227
248
  clicked: count(emailSends.clickedAt),
@@ -231,10 +252,14 @@ export const adminCampaignsRouter = new OpenAPIHono<AppEnv>()
231
252
  sql<number>`count(*) filter (where ${emailSends.status} = 'failed')`.mapWith(
232
253
  Number,
233
254
  ),
255
+ skipped:
256
+ sql<number>`count(*) filter (where ${emailSends.status} = 'suppressed')`.mapWith(
257
+ Number,
258
+ ),
234
259
  lastSentAt: max(emailSends.sentAt),
235
260
  })
236
261
  .from(emailSends)
237
- .where(like(emailSends.idempotencyKey, pattern))
262
+ .where(where)
238
263
  )[0];
239
264
  return {
240
265
  sends: agg?.sends ?? 0,
@@ -244,21 +269,23 @@ export const adminCampaignsRouter = new OpenAPIHono<AppEnv>()
244
269
  bounced: agg?.bounced ?? 0,
245
270
  complained: agg?.complained ?? 0,
246
271
  failed: agg?.failed ?? 0,
272
+ skipped: agg?.skipped ?? 0,
247
273
  lastSentAt: agg?.lastSentAt ? agg.lastSentAt.toISOString() : null,
248
274
  };
249
275
  };
250
276
 
251
- // The campaign-level pattern (`campaign:<id>:%`) is a superset of both
252
- // key formats, so these numbers are format-agnostic and unchanged for
253
- // legacy single-send rows.
254
- const campaignLevel = await aggregate(campaignSendKeyPattern(id));
277
+ // Campaign-level: the FK matches every row of both key formats AND the
278
+ // keyless suppressed rows, so these numbers are format-agnostic and
279
+ // unchanged for legacy single-send rows.
280
+ const campaignLevel = await aggregate(eq(emailSends.campaignId, id));
255
281
 
256
282
  // Per-step breakdown, only when the row carries a steps blob (NULL =
257
- // legacy single-send — no `steps` in the response). Send-step aggregates
258
- // filter on the step-scoped pattern (`campaign:<id>:<k>:%` — multi-step
259
- // campaigns key ALL steps including 0 that way); wait steps deliver
260
- // nothing. One query per step is fine at the ≤10-step cap on the
261
- // admin plane.
283
+ // legacy single-send — no `steps` in the response). The step number only
284
+ // exists inside the key, so send-step aggregates still filter on the
285
+ // step-scoped pattern (`campaign:<id>:<k>:%` — multi-step campaigns key
286
+ // ALL steps including 0 that way), anchored on the indexed FK first; wait
287
+ // steps deliver nothing. The step queries are independent, so they run
288
+ // concurrently.
262
289
  const blob = row.steps;
263
290
  if (!blob) {
264
291
  return c.json(campaignLevel, 200);
@@ -267,18 +294,30 @@ export const adminCampaignsRouter = new OpenAPIHono<AppEnv>()
267
294
  // db cannot import @hogsend/core, so the blob's elements are opaque
268
295
  // Record<string, unknown> there; the engine owns the narrowing.
269
296
  const defs = blob.steps as unknown as CampaignStep[];
270
- const steps: z.infer<typeof campaignStepStatsSchema>[] = [];
271
- for (const [index, step] of defs.entries()) {
272
- if (step.kind === "send") {
273
- steps.push({
274
- index,
275
- kind: step.kind,
276
- templateKey: step.template,
277
- durationMs: null,
278
- ...(await aggregate(campaignStepSendKeyPattern(id, index))),
279
- });
280
- } else {
281
- steps.push({
297
+ const steps: z.infer<typeof campaignStepStatsSchema>[] = await Promise.all(
298
+ defs.map(async (step, index) => {
299
+ if (step.kind === "send") {
300
+ // Suppressed rows write no key, so they can never match the
301
+ // step-scoped pattern — the always-zero `skipped` is dropped from
302
+ // step rows rather than reported as a dead field.
303
+ const { skipped: _campaignOnly, ...stepStats } = await aggregate(
304
+ and(
305
+ eq(emailSends.campaignId, id),
306
+ like(
307
+ emailSends.idempotencyKey,
308
+ campaignStepSendKeyPattern(id, index),
309
+ ),
310
+ ),
311
+ );
312
+ return {
313
+ index,
314
+ kind: step.kind,
315
+ templateKey: step.template,
316
+ durationMs: null,
317
+ ...stepStats,
318
+ };
319
+ }
320
+ return {
282
321
  index,
283
322
  kind: step.kind,
284
323
  templateKey: null,
@@ -291,9 +330,9 @@ export const adminCampaignsRouter = new OpenAPIHono<AppEnv>()
291
330
  complained: 0,
292
331
  failed: 0,
293
332
  lastSentAt: null,
294
- });
295
- }
296
- }
333
+ };
334
+ }),
335
+ );
297
336
 
298
337
  return c.json({ ...campaignLevel, steps }, 200);
299
338
  })
@@ -4,7 +4,7 @@ import { and, asc, count, desc, eq, sql } from "drizzle-orm";
4
4
  import type { AppEnv } from "../../app.js";
5
5
 
6
6
  /**
7
- * Admin conversions API (docs/revenue-attribution-plan.md §5b.2) — fired
7
+ * Admin conversions API — fired
8
8
  * conversion points and their per-destination delivery state. Answers the
9
9
  * operator question "did the ad platform actually receive the sale?".
10
10
  */
@@ -17,7 +17,7 @@ import type { AnyPgColumn } from "drizzle-orm/pg-core";
17
17
  import type { AppEnv } from "../../app.js";
18
18
 
19
19
  /**
20
- * Admin deals API (docs/revenue-attribution-plan.md §4b.1) — the ledger view
20
+ * Admin deals API — the ledger view
21
21
  * over the `deals` projection: filterable list for the Studio pipeline board
22
22
  * + the revenue stats block (per-currency, never cross-summed). Stages are
23
23
  * per-funnel ladders (`client.funnels`), not a fixed enum; the `funnel`
@@ -140,6 +140,8 @@ const statsSchema = z.object({
140
140
  ),
141
141
  /** Mean sold-deal cycle time in hours (created → soldAt), lifetime. */
142
142
  avgTimeToCloseHours: z.number().nullable(),
143
+ /** Distinct deal providers in this funnel — the list filter's vocabulary. */
144
+ providers: z.array(z.string()),
143
145
  });
144
146
 
145
147
  const statsRoute = createRoute({
@@ -389,39 +391,45 @@ export const adminDealsRouter = new OpenAPIHono<AppEnv>()
389
391
  Date.now() - 30 * 24 * 60 * 60 * 1000,
390
392
  ).toISOString();
391
393
 
392
- const [stageRows, rankRows, currencyRows, cycleRows] = await Promise.all([
393
- db
394
- .select({ stage: deals.canonicalStage, n: count() })
395
- .from(deals)
396
- .where(scopeWhere)
397
- .groupBy(deals.canonicalStage),
398
- db
399
- .select({ rank: deals.stageRank, n: count() })
400
- .from(deals)
401
- .where(scopeWhere)
402
- .groupBy(deals.stageRank),
403
- db
404
- .select({
405
- currency: deals.currency,
406
- soldRevenue30d: sql<number>`coalesce(sum(${deals.value}) filter (where ${deals.soldAt} >= ${thirtyDaysAgo}::timestamptz), 0)::float8`,
407
- soldRevenueLifetime: sql<number>`coalesce(sum(${deals.value}) filter (where ${deals.soldAt} is not null), 0)::float8`,
408
- soldCount30d: sql<number>`count(*) filter (where ${deals.soldAt} >= ${thirtyDaysAgo}::timestamptz)::int`,
409
- soldCountLifetime: sql<number>`count(*) filter (where ${deals.soldAt} is not null)::int`,
410
- openPipelineValue: sql<number>`coalesce(sum(${deals.value}) filter (where ${deals.soldAt} is null and ${deals.canonicalStage} != 'lost'), 0)::float8`,
411
- openPipelineCount: sql<number>`count(*) filter (where ${deals.soldAt} is null and ${deals.canonicalStage} != 'lost')::int`,
412
- })
413
- .from(deals)
414
- .where(scopeWhere)
415
- .groupBy(deals.currency),
416
- db
417
- .select({
418
- avgHours: sql<
419
- number | null
420
- >`avg(extract(epoch from (${deals.soldAt} - ${deals.createdAt})) / 3600)::float8`,
421
- })
422
- .from(deals)
423
- .where(and(sql`${deals.soldAt} is not null`, ...scope)),
424
- ]);
394
+ const [stageRows, rankRows, currencyRows, cycleRows, providerRows] =
395
+ await Promise.all([
396
+ db
397
+ .select({ stage: deals.canonicalStage, n: count() })
398
+ .from(deals)
399
+ .where(scopeWhere)
400
+ .groupBy(deals.canonicalStage),
401
+ db
402
+ .select({ rank: deals.stageRank, n: count() })
403
+ .from(deals)
404
+ .where(scopeWhere)
405
+ .groupBy(deals.stageRank),
406
+ db
407
+ .select({
408
+ currency: deals.currency,
409
+ soldRevenue30d: sql<number>`coalesce(sum(${deals.value}) filter (where ${deals.soldAt} >= ${thirtyDaysAgo}::timestamptz), 0)::float8`,
410
+ soldRevenueLifetime: sql<number>`coalesce(sum(${deals.value}) filter (where ${deals.soldAt} is not null), 0)::float8`,
411
+ soldCount30d: sql<number>`count(*) filter (where ${deals.soldAt} >= ${thirtyDaysAgo}::timestamptz)::int`,
412
+ soldCountLifetime: sql<number>`count(*) filter (where ${deals.soldAt} is not null)::int`,
413
+ openPipelineValue: sql<number>`coalesce(sum(${deals.value}) filter (where ${deals.soldAt} is null and ${deals.canonicalStage} != 'lost'), 0)::float8`,
414
+ openPipelineCount: sql<number>`count(*) filter (where ${deals.soldAt} is null and ${deals.canonicalStage} != 'lost')::int`,
415
+ })
416
+ .from(deals)
417
+ .where(scopeWhere)
418
+ .groupBy(deals.currency),
419
+ db
420
+ .select({
421
+ avgHours: sql<
422
+ number | null
423
+ >`avg(extract(epoch from (${deals.soldAt} - ${deals.createdAt})) / 3600)::float8`,
424
+ })
425
+ .from(deals)
426
+ .where(and(sql`${deals.soldAt} is not null`, ...scope)),
427
+ db
428
+ .selectDistinct({ provider: deals.provider })
429
+ .from(deals)
430
+ .where(scopeWhere)
431
+ .orderBy(asc(deals.provider)),
432
+ ]);
425
433
 
426
434
  const stageOrder = [...ladder.stages, "lost"];
427
435
  const stages: Record<string, number> = {};
@@ -466,6 +474,7 @@ export const adminDealsRouter = new OpenAPIHono<AppEnv>()
466
474
  }))
467
475
  .sort((a, b) => b.soldRevenueLifetime - a.soldRevenueLifetime),
468
476
  avgTimeToCloseHours: cycleRows[0]?.avgHours ?? null,
477
+ providers: providerRows.map((row) => row.provider),
469
478
  },
470
479
  200,
471
480
  );