create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/flow-aggregate.ts

@@ -0,0 +1,232 @@
+/**
+ * @file flow-aggregate.ts
+ * @description The anonymous aggregate-response service (#4771 D1/D2/D3).
+ *
+ * Read-only (no write verb is reachable from this module — the same
+ * `prisma\.[a-zA-Z]+\.(create|update|upsert|delete|deleteMany|updateMany|createMany)`
+ * probe `waitlist-dashboard.ts` asserts of itself returns 0 here too).
+ *
+ * Three scoped reads, each carrying `siteId`:
+ *   1. `flowDefinition.findUnique` — existence only, mirroring `serveFlow`'s
+ *      own lookup (`flow-engine.ts`). A slug with no `FlowDefinition` is
+ *      `flow_not_found` (FR6).
+ *   2. `waitlistExperiment.findMany` — resolves the slug to its backing
+ *      register (D2), for question metadata + the `resultsReveal` flag. A
+ *      flow with no backing register is legal (D2) — the response then
+ *      carries an empty `questions[]`.
+ *   3. `flowSession.findMany` — the respondent set: **completed** sessions
+ *      for `(siteId, flowSlug)`, `completedAt` non-null, regardless of
+ *      whether a `Lead` was ever created (D1 — a recommending-mode
+ *      respondent has no Lead until the email moment, which the reveal is
+ *      shown before).
+ *
+ * Per-question bucketing is the shared `computeAnswerDistributions`
+ * (`./answer-distributions.js`, D4) — the same module `waitlist-dashboard.ts`
+ * imports, fed `sessions.map((s) => flattenSessionState(s.state))` rather
+ * than `leads.map((l) => l.payload)`.
+ */
+import type { Prisma } from "@working-theory/database";
+import { logger } from "@working-theory/observability";
+import {
+  waitlistExperimentConfigSchema,
+  type FlowAggregate,
+  type FlowAggregateAnswerType,
+  type WaitlistExperimentConfig,
+} from "@working-theory/validation";
+
+import { prisma } from "../lib/prisma.js";
+
+import {
+  computeAnswerDistributions,
+  logAggregationCapHit,
+  MAX_AGGREGATION_ROWS,
+} from "./answer-distributions.js";
+import type { FlowEngineError } from "./flow-engine.js";
+
+export type GetFlowAggregateResult =
+  { ok: true; data: FlowAggregate } | { ok: false; error: FlowEngineError };
+
+// ─── DB-required guard ──────────────────────────────────────────────────────
+// Mirrors flow-engine.ts's own private `requireDb` (#3956 D5) — not exported
+// there, so re-declared here rather than widening that module's surface for
+// one boolean check (the same engine-local-helper convention `flow-engine.ts`
+// already documents for `flattenFlowState`, below).
+
+const FLOWS_NOT_CONFIGURED_ERROR: FlowEngineError = {
+  kind: "flows_not_configured",
+  message: "Flows are not configured.",
+};
+
+function requireDb(): FlowEngineError | null {
+  if (!process.env.DATABASE_URL) return FLOWS_NOT_CONFIGURED_ERROR;
+  return null;
+}
+
+// ─── flattenSessionState ────────────────────────────────────────────────────
+// Mirrors flow-engine.ts's private `flattenFlowState` (:682-689) — collapses
+// FlowSession.state's step-keyed two-level shape (`{ [stepKey]: { [field]:
+// value } }`) into the flat `{ [field]: value }` map `readPayloadAnswer`
+// expects. Not imported: `flattenFlowState` is engine-local and unexported,
+// the exact "mirrors ... engine-local, since that one isn't exported"
+// convention flow-engine.ts's own doc comment already states for its
+// sibling helper. Behaviour is byte-identical to the mirrored function.
+
+function flattenSessionState(state: unknown): Record<string, unknown> {
+  const flat: Record<string, unknown> = {};
+  if (!state || typeof state !== "object") return flat;
+  for (const stepKey of Object.keys(state as Record<string, unknown>)) {
+    const stepData = (state as Record<string, unknown>)[stepKey];
+    if (stepData && typeof stepData === "object") Object.assign(flat, stepData);
+  }
+  return flat;
+}
+
+// ─── Row shapes ──────────────────────────────────────────────────────────────
+
+const FLOW_DEFINITION_EXISTS_SELECT = {
+  id: true,
+} as const satisfies Prisma.FlowDefinitionSelect;
+
+const EXPERIMENT_CONFIG_SELECT = {
+  id: true,
+  config: true,
+} as const satisfies Prisma.WaitlistExperimentSelect;
+type ExperimentConfigRow = Omit<
+  Prisma.WaitlistExperimentGetPayload<{
+    select: typeof EXPERIMENT_CONFIG_SELECT;
+  }>,
+  "config"
+> & { config: unknown };
+
+const FLOW_SESSION_STATE_SELECT = {
+  state: true,
+} as const satisfies Prisma.FlowSessionSelect;
+type FlowSessionStateRow = Omit<
+  Prisma.FlowSessionGetPayload<{ select: typeof FLOW_SESSION_STATE_SELECT }>,
+  "state"
+> & { state: unknown };
+
+// ─── getFlowAggregate ────────────────────────────────────────────────────────
+
+export async function getFlowAggregate(
+  siteId: string,
+  slug: string,
+): Promise<GetFlowAggregateResult> {
+  const dbError = requireDb();
+  if (dbError) return { ok: false, error: dbError };
+
+  // Existence check only — mirrors serveFlow's own FlowDefinition lookup
+  // (flow-engine.ts), so "unknown slug" resolves identically for both
+  // routes (FR6).
+  const definition = await prisma.flowDefinition.findUnique({
+    where: { siteId_slug: { siteId, slug } },
+    select: FLOW_DEFINITION_EXISTS_SELECT,
+  });
+  if (!definition) {
+    return {
+      ok: false,
+      error: { kind: "flow_not_found", message: "Flow not found." },
+    };
+  }
+
+  // D2 — question metadata + the resultsReveal flag come from the register,
+  // not the compiled flow. A flow with no backing register is legal (D2) —
+  // `matches` is then empty and `flaggedQuestions` stays [].
+  const experiments: ExperimentConfigRow[] =
+    await prisma.waitlistExperiment.findMany({
+      where: { siteId },
+      select: EXPERIMENT_CONFIG_SELECT,
+      // Deterministic read order (code-review finding, #4771) — without an
+      // explicit orderBy, Postgres does not guarantee row order, which
+      // would make the matches.length > 1 fallback below pick a genuinely
+      // arbitrary row rather than a defined "oldest wins" policy.
+      orderBy: { createdAt: "asc" },
+      // Bounds this anonymous read the same way the sibling
+      // flowSession.findMany read below is bounded (#5109).
+      take: MAX_AGGREGATION_ROWS,
+    });
+
+  const matches: WaitlistExperimentConfig[] = [];
+  for (const row of experiments) {
+    const parsed = waitlistExperimentConfigSchema.safeParse(row.config);
+    if (!parsed.success) {
+      // A corrupted register row must not abort an anonymous read — the
+      // same "skip, don't throw" posture waitlist-dashboard.ts's
+      // `listExperiments` applies to a corrupt config under kind:"all".
+      logger.warn(
+        { siteId, experimentId: row.id },
+        "[flow-aggregate] experiment config failed to parse — skipped",
+      );
+      continue;
+    }
+    if (parsed.data.waitlists.some((w) => w.flowSlug === slug)) {
+      matches.push(parsed.data);
+    }
+  }
+  if (matches.length > 1) {
+    // Spec §5.3 escalation boundary — a duplicate flowSlug across
+    // experiments for one site is a register-integrity question this
+    // service does not resolve arbitrarily. Logged rather than thrown so
+    // the anonymous read still degrades (first match, by the oldest
+    // `createdAt` per the orderBy above) instead of 500ing a public
+    // endpoint.
+    logger.warn(
+      { siteId, slug, matchCount: matches.length },
+      "[flow-aggregate] slug resolves to more than one WaitlistExperiment — using the first",
+    );
+  }
+  const config = matches[0];
+  const flaggedQuestions = (config?.questionSet.questions ?? []).filter(
+    (q) => q.resultsReveal === true,
+  );
+
+  // D1 — respondents are completed FlowSession rows, not Leads.
+  const sessions: FlowSessionStateRow[] = await prisma.flowSession.findMany({
+    where: { siteId, flowSlug: slug, completedAt: { not: null } },
+    select: FLOW_SESSION_STATE_SELECT,
+    // Deterministic read order (code-review finding, #4771) — earliest
+    // completions first, so a flow that exceeds MAX_AGGREGATION_ROWS drops
+    // its most recent respondents consistently rather than an arbitrary set.
+    orderBy: { completedAt: "asc" },
+    take: MAX_AGGREGATION_ROWS,
+  });
+  logAggregationCapHit(`flow-aggregate.${slug}`, sessions.length);
+
+  const answerSets = sessions.map((session) =>
+    flattenSessionState(session.state),
+  );
+  const distributions = computeAnswerDistributions(
+    flaggedQuestions,
+    answerSets,
+  );
+
+  const questions: FlowAggregate["questions"] = distributions.map((d, i) => {
+    const question = flaggedQuestions[i]!;
+    const labelsByValue = new Map(
+      (question.options ?? []).map((o) => [o.value, o.label]),
+    );
+    return {
+      id: d.questionId,
+      // Safe: flaggedQuestions is filtered to resultsReveal === true, and
+      // waitlist.ts's own superRefine only permits that flag on single/multi
+      // questions (D3) — no other answerType is reachable here.
+      answerType: d.answerType as FlowAggregateAnswerType,
+      answered: d.answered,
+      // Declared options only — an off-register "(other)" bucket has no
+      // register label to ship, and this schema's `label` is required
+      // (never fabricated). Still counted in `answered` above.
+      options: d.options
+        .filter((o) => labelsByValue.has(o.value))
+        .map((o) => ({
+          value: o.value,
+          label: labelsByValue.get(o.value)!,
+          count: o.count,
+        })),
+    };
+  });
+
+  return {
+    ok: true,
+    data: { slug, respondents: sessions.length, questions },
+  };
+}

package/templates/apps/api/src/services/flow-checkouts.ts

@@ -0,0 +1,123 @@
+/**
+ * @file flow-checkouts.ts
+ * @description The respondent checkouts read (#4984) — `readMyCheckouts`,
+ * the ONLY read path behind `GET /v1/flow-checkouts/me`: a signed-in,
+ * email-verified user lists their OWN flow checkouts. Nothing here
+ * enumerates, nothing accepts an email, nothing reads across sites.
+ *
+ * Mirrors `lead-promotion.ts` (ADR 0009 D3 service-layer pattern): the same
+ * `User {id, email, emailVerified}` read, the same verified-email refusal
+ * (D2 there — the consent basis for linking anonymous-lead PII to a user;
+ * here a hard 403, evaluated BEFORE any Lead read), and a scalar-only join
+ * to the inbox namespace — `Lead` carries no `@relation` (ADR 0009
+ * invariant #1), so the read is three narrow queries, each scoped to
+ * `currentSiteId()` (#4665 D3: the scope is a parameter of every query,
+ * never a post-filter).
+ *
+ * The join is the promotion link and ONLY the promotion link:
+ * `Lead.promotedUserId === userId`, the scalar `lead-promotion.ts` stamps once
+ * the user's email is verified. A Lead is NEVER matched by email at read time
+ * — an un-promoted lead that happens to carry the caller's address is not
+ * theirs until promotion says so (the #4984 security fence; contrast
+ * `waitlist-signups.ts`, whose contract is a single experiment-scoped row).
+ *
+ * PII boundary: logs carry only `{ siteId, userId, kind }` — never email,
+ * a Stripe id, a quote, or a permalink; the row select is the ten contract
+ * fields and nothing else.
+ */
+
+import type { FlowCheckoutMeResponse } from "@working-theory/validation";
+
+import { prisma } from "../lib/prisma.js";
+import { currentSiteId } from "../lib/site.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type ReadMyCheckoutsResult =
+  | { ok: true; value: FlowCheckoutMeResponse }
+  | {
+      ok: false;
+      error: {
+        kind: "not_found_user" | "email_unverified";
+        message: string;
+      };
+    };
+
+// ─── Main export ──────────────────────────────────────────────────────────────
+
+/**
+ * List the calling user's flow checkouts at the current site, newest first.
+ * `userId` is the auth preHandler's `request.userId` — the ONLY identity
+ * input; there is no other parameter.
+ *
+ * Result kinds (the route maps them to HTTP):
+ *   - `not_found_user`   — no `User` row for `userId` (404 on the wire).
+ *   - `email_unverified` — `User.emailVerified !== true`; refused BEFORE any
+ *                          Lead read (403).
+ * A verified user with no promoted lead (or no checkout) is `ok` with an
+ * empty list — an empty list is not an error.
+ */
+export async function readMyCheckouts(userId: string): Promise<ReadMyCheckoutsResult> {
+  const siteId = currentSiteId();
+
+  // D2 — the exact read lead-promotion.ts performs, mirrored not forked.
+  const user = await prisma.user.findUnique({
+    where: { id: userId },
+    select: { id: true, email: true, emailVerified: true },
+  });
+  if (!user) {
+    return { ok: false, error: { kind: "not_found_user", message: "User not found" } };
+  }
+
+  // D2 — the verified-email gate is a service-level invariant: an unverified
+  // address never reaches a Lead read, whatever the call site.
+  if (user.emailVerified !== true) {
+    return {
+      ok: false,
+      error: { kind: "email_unverified", message: "Verify your email to view your checkouts" },
+    };
+  }
+
+  // The promotion link is the ONLY join — never `email` — and the scope is
+  // ANDed in, never a post-filter.
+  const leads = await prisma.lead.findMany({
+    where: { siteId, promotedUserId: userId },
+    select: { id: true },
+  });
+  if (leads.length === 0) return { ok: true, value: [] };
+
+  const rows = await prisma.flowCheckout.findMany({
+    where: { siteId, leadId: { in: leads.map((lead) => lead.id) } },
+    orderBy: { createdAt: "desc" },
+    select: {
+      id: true,
+      flowSlug: true,
+      experimentKey: true,
+      offerKey: true,
+      status: true,
+      amountMinor: true,
+      currency: true,
+      period: true,
+      completedAt: true,
+      createdAt: true,
+    },
+  });
+
+  // Ten fields per row, nothing more — no Stripe id, quote, permalink,
+  // session id, or lead id leaves the row.
+  return {
+    ok: true,
+    value: rows.map((row) => ({
+      id: row.id,
+      flowSlug: row.flowSlug,
+      experimentKey: row.experimentKey,
+      offerKey: row.offerKey,
+      status: row.status,
+      amountMinor: row.amountMinor,
+      currency: row.currency,
+      period: row.period,
+      completedAt: row.completedAt?.toISOString() ?? null,
+      createdAt: row.createdAt.toISOString(),
+    })),
+  };
+}