create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/project-listing-decision.ts

@@ -0,0 +1,510 @@
+/**
+ * @file project-listing-decision.ts
+ * @description The one Approve/Reject transition for a `ProjectListing`
+ * (#4999) — the SAME function `PATCH /v1/project-listings/:id` (tenant-scoped,
+ * via `routes/project-listings/patch.ts`) and `POST /v1/slack/actions` (the
+ * Slack button click, no tenant context) both call, so the stamp + backlink
+ * logic exists in exactly one place.
+ *
+ * `siteId` is optional: the tenant-scoped PATCH route passes it (so a foreign
+ * listing id 404s, matching every other tenant-scoped read/write in this
+ * service group); the Slack handler omits it (the button's `value` carries
+ * only the listing id — no tenant context to check).
+ *
+ * Approve stamps `windowEndsAt = decidedAt + the row's windowDays`, the
+ * applicant's requested window already clamped at create against the site's
+ * `SiteListingConfig` (#5033 D4). The ninety days this used to hardcode were
+ * one site's commercial terms; there is no duration constant here now. A row
+ * already decided (`status` already `active` or `rejected`) is idempotent —
+ * `{ ok: true, changed: false }`, the row untouched, no second stamp — the
+ * "second click" AC (#4999): both the PATCH route (an operator re-submitting
+ * the same decision) and the Slack route (a stale button click after the
+ * message has already updated) see the same 200/no-op shape. Only a listing
+ * still `requested` can transition; anything else (an already-decided row
+ * asking for a DIFFERENT decision, or a `draft` asking to be decided) is
+ * `invalid_transition`.
+ *
+ * `value` is a strict `ProjectListing` (safe to pass straight through
+ * `routes/project-listings/respond.ts#sendValidated`, which re-parses
+ * against `projectListingSchema.strict()`); `slackChannel`/`slackTs` live
+ * OUTSIDE it, in the sibling `slack` field, so an unexpected key never
+ * reaches that contract check. The row shape/select and the `waitlistCount`
+ * join still mirror `services/project-listings.ts` rather than importing it,
+ * but the one piece that MUST NOT drift — the computed `closed` state — is
+ * now imported from there (`computeListingStatus`), so both modules resolve a
+ * row's lifecycle status through the same function.
+ *
+ * Also exports `sendListingDecisionEmail` — the founder email dispatch
+ * `routes/slack/actions.ts` (on a changed Slack decision) and
+ * `routes/project-listings/patch.ts` (on a changed PATCH decision) both
+ * call, so the founder is emailed exactly once regardless of which channel
+ * decided. See that function's own doc comment for the env-var reuse this
+ * issue makes (no new email-specific env var beyond the three Slack ones).
+ * On an APPROVE, it also fires `fileListingIssue` (#5000,
+ * `project-listing-issue.ts`) fire-and-forget after the email — the one
+ * work-order GitHub issue for the row, on the site's own repo. Both
+ * callers reach it through this one function, so the filing (like the
+ * email) fires exactly once per changed decision, never per caller.
+ *
+ * Also exports `onListingDecided` — the approve-path side-effect seam (#5001):
+ * a `requested` → `active` transition projects the row into its live
+ * diagnostic (`generateListingFlow`). `decideListing` calls it after a CHANGED
+ * approve, and since #5033 collapsed the lifecycle that is the ONLY caller —
+ * `requested → active | rejected` is the only transition there is, and both
+ * the PATCH route and the Slack click reach it through `decideListing`.
+ * Fail-soft by construction — a projection failure is logged
+ * and swallowed; the decision has already committed. #5000 (the build issue)
+ * joins the same seam.
+ *
+ * PII boundary: `decideListing` never logs (the DB mutation only).
+ * `sendListingDecisionEmail` logs `listingId`/`decision`/an error KIND only —
+ * never founderEmail/founderName/questions (mirrors
+ * `services/project-listings.ts` and `services/lead-routing.ts`'s
+ * discipline).
+ */
+
+import type { Prisma } from "@working-theory/database";
+import { sendListingApprovedEmail, sendListingRejectedEmail } from "@working-theory/email";
+import { logger } from "@working-theory/observability";
+import {
+  clampWindowDays,
+  projectListingQuestionsSchema,
+  type ProjectListing,
+  type ProjectListingFaqs,
+  type ProjectListingQuestions,
+} from "@working-theory/validation";
+
+import { config } from "../config/index.js";
+import { prisma } from "../lib/prisma.js";
+
+import { listingConfigFor } from "./listing-config.js";
+import { generateListingFlow } from "./project-listing-flow.js";
+import { fileListingIssue } from "./project-listing-issue.js";
+import {
+  addressPartsFromRow,
+  computeListingStatus,
+  siteAnswersFromRow,
+} from "./project-listings.js";
+
+export type ListingDecision = "active" | "rejected";
+
+/** Days to milliseconds. A unit conversion, not a policy duration. */
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+const SELECT = {
+  id: true,
+  siteId: true,
+  leadId: true,
+  slug: true,
+  name: true,
+  oneLiner: true,
+  problem: true,
+  url: true,
+  product: true,
+  commitment: true,
+  teamComposition: true,
+  faqs: true,
+  anythingElse: true,
+  address: true,
+  // #5279 — the structured parts beside the display string.
+  addressLine1: true,
+  addressLine2: true,
+  addressCity: true,
+  addressRegion: true,
+  addressPostalCode: true,
+  addressCountry: true,
+  questions: true,
+  // #5285 — the operator's review payload carries EVERY site answer, the
+  // `operator-only` ones included. That visibility is what it is for: an
+  // answer a site asked for its own triage reaches the reviewer and stops
+  // short of the public read, which narrows through `publicSiteAnswers`.
+  siteAnswers: true,
+  founderName: true,
+  founderEmail: true,
+  founderCompany: true,
+  headline: true,
+  logoMarkUrl: true,
+  logoWordmarkUrl: true,
+  featured: true,
+  status: true,
+  consentAt: true,
+  decidedAt: true,
+  decidedBy: true,
+  issueUrl: true,
+  experimentKey: true,
+  windowDays: true,
+  windowEndsAt: true,
+  slackChannel: true,
+  slackTs: true,
+  createdAt: true,
+  updatedAt: true,
+} as const satisfies Prisma.ProjectListingSelect;
+
+type Row = Prisma.ProjectListingGetPayload<{ select: typeof SELECT }>;
+
+/**
+ * Mirrors `project-listings.ts#attachWaitlistCounts`'s join shape for the
+ * single row this module ever handles.
+ *
+ * Since #5036 D6d the listing stores the experiment's KEY, so this is one
+ * count against `WaitlistScore.experimentKey` — the `WaitlistExperiment` read
+ * that existed only to translate an id into that key is gone from both
+ * modules.
+ */
+async function waitlistCountFor(row: Row): Promise<number> {
+  if (!row.experimentKey) return 0;
+  return prisma.waitlistScore.count({
+    where: { siteId: row.siteId, experimentKey: row.experimentKey },
+  });
+}
+
+function toListing(row: Row, waitlistCount: number): ProjectListing {
+  return {
+    id: row.id,
+    siteId: row.siteId,
+    leadId: row.leadId,
+    slug: row.slug,
+    name: row.name,
+    headline: row.headline,
+    oneLiner: row.oneLiner,
+    problem: row.problem,
+    url: row.url,
+    product: row.product as ProjectListing["product"],
+    commitment: row.commitment as ProjectListing["commitment"],
+    teamComposition: row.teamComposition as ProjectListing["teamComposition"],
+    faqs: row.faqs as unknown as ProjectListingFaqs | null,
+    anythingElse: row.anythingElse,
+    address: row.address,
+    // #5279 — one reader of the parts, shared with `project-listings.ts`, so
+    // the two row renderers cannot drift on what "has parts" means.
+    addressParts: addressPartsFromRow(row),
+    founderName: row.founderName,
+    founderEmail: row.founderEmail,
+    founderCompany: row.founderCompany,
+    questions: row.questions as unknown as ProjectListingQuestions | null,
+    siteAnswers: siteAnswersFromRow(row.siteAnswers),
+    logoMarkUrl: row.logoMarkUrl,
+    logoWordmarkUrl: row.logoWordmarkUrl,
+    featured: row.featured,
+    status: computeListingStatus(row.status, row.windowEndsAt, new Date(), row.featured),
+    consentAt: row.consentAt.toISOString(),
+    decidedAt: row.decidedAt ? row.decidedAt.toISOString() : null,
+    decidedBy: row.decidedBy,
+    issueUrl: row.issueUrl,
+    experimentKey: row.experimentKey,
+    windowEndsAt: row.windowEndsAt ? row.windowEndsAt.toISOString() : null,
+    waitlistCount,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
+export type DecideListingInput = {
+  id: string;
+  decision: ListingDecision;
+  decidedBy: string;
+  /** Tenant scope for the PATCH route; omitted by the Slack handler (no tenant context on a button click). */
+  siteId?: string;
+};
+
+export type DecideListingResult =
+  | {
+      ok: true;
+      changed: boolean;
+      value: ProjectListing;
+      /** The row's posted-message coordinates, for the Slack route's `chat.update` — never part of `value`. */
+      slack: { channel: string | null; ts: string | null };
+    }
+  | {
+      ok: false;
+      error: { kind: "not_found" | "invalid_transition"; message: string };
+    };
+
+const DECIDED_STATUSES: ReadonlySet<string> = new Set(["active", "rejected"]);
+
+/**
+ * The window, in whole days, to stamp on an approve. The row's own
+ * `windowDays` (the applicant's request, clamped at create against the site's
+ * terms) when it has one; otherwise the site's configured default clamped the
+ * same way, for a row that was already pending when the column shipped.
+ * `null` when the row does not exist — the caller's fresh read reports that.
+ */
+async function windowDaysFor(id: string, siteId: string | undefined): Promise<number | null> {
+  const row = await prisma.projectListing.findFirst({
+    where: siteId !== undefined ? { id, siteId } : { id },
+    select: { siteId: true, windowDays: true },
+  });
+  if (!row) return null;
+  if (row.windowDays !== null) return row.windowDays;
+  return clampWindowDays(undefined, await listingConfigFor(row.siteId));
+}
+
+/**
+ * The transition write is a GUARDED `updateMany` — `where` includes
+ * `status: "applied"`, so the write only lands if the row is STILL `applied`
+ * at the moment Postgres evaluates it (row-level locking makes this atomic;
+ * mirrors the compare-and-swap shape `routes/webhooks/stripe.ts#stampFlowCheckout`
+ * uses on `FlowCheckout.status`). `count === 1` means THIS call made the
+ * transition; `count === 0` means it didn't — either the row was never
+ * `applied` to begin with, or a CONCURRENT call already decided it between
+ * this call's own read and write (security review, PR #4999: a plain
+ * read-then-write here would let two racing calls — e.g. Slack's own retry,
+ * or a Slack click racing an operator's PATCH — both observe `applied` and
+ * both "succeed", double-sending the founder email and possibly leaving the
+ * row in whichever decision wrote last). Either way, a fresh read after the
+ * guarded write tells the caller which: already decided (idempotent
+ * `changed: false`) or a genuinely invalid transition (`live`/`closed`).
+ */
+export async function decideListing({
+  id,
+  decision,
+  decidedBy,
+  siteId,
+}: DecideListingInput): Promise<DecideListingResult> {
+  const decidedAt = new Date();
+
+  // #5033 — the window this listing was granted, resolved BEFORE the guarded
+  // write because a `updateMany` cannot read a column it is also setting.
+  // `windowDays` is immutable once stamped at create, so reading it outside
+  // the guard is not part of the compare-and-swap. A row that predates the
+  // column (an application still pending when this shipped) has none, and
+  // takes the site's configured default instead.
+  const windowDays = await windowDaysFor(id, siteId);
+
+  const updateResult = await prisma.projectListing.updateMany({
+    where: siteId !== undefined ? { id, siteId, status: "requested" } : { id, status: "requested" },
+    data: {
+      status: decision,
+      decidedAt,
+      decidedBy,
+      ...(decision === "active" &&
+        windowDays !== null && {
+          windowEndsAt: new Date(decidedAt.getTime() + windowDays * MS_PER_DAY),
+        }),
+    },
+  });
+
+  const current = await prisma.projectListing.findFirst({
+    where: siteId !== undefined ? { id, siteId } : { id },
+    select: SELECT,
+  });
+  if (!current) {
+    return { ok: false, error: { kind: "not_found", message: "Project listing not found" } };
+  }
+
+  if (updateResult.count === 1) {
+    // #5001 — the approve's downstream effects (the diagnostic projection).
+    // Never throws; a failure is logged and the decision stands. Re-read
+    // afterwards so `value.experimentKey` reflects the projection.
+    await onListingDecided(current.siteId, current.id, decision);
+    const projected =
+      (await prisma.projectListing.findFirst({ where: { id: current.id }, select: SELECT })) ?? current;
+    const waitlistCount = await waitlistCountFor(projected);
+    return {
+      ok: true,
+      changed: true,
+      value: toListing(projected, waitlistCount),
+      slack: { channel: projected.slackChannel, ts: projected.slackTs },
+    };
+  }
+
+  // The guarded write matched nothing — the row wasn't `applied` when
+  // Postgres evaluated the guard. Read its CURRENT status to tell an
+  // already-decided idempotent no-op from a genuinely invalid transition.
+  if (DECIDED_STATUSES.has(current.status)) {
+    const waitlistCount = await waitlistCountFor(current);
+    return {
+      ok: true,
+      changed: false,
+      value: toListing(current, waitlistCount),
+      slack: { channel: current.slackChannel, ts: current.slackTs },
+    };
+  }
+
+  return {
+    ok: false,
+    error: {
+      kind: "invalid_transition",
+      message: `cannot transition from '${current.status}' to '${decision}'`,
+    },
+  };
+}
+
+/**
+ * Sends the founder's approve/reject email for a just-decided listing
+ * (#4999 step 5).
+ *
+ * Reasonable-call env-var reuse (this issue's footprint is the three Slack
+ * vars only — no new email-specific var): `fromAddress` reads the existing
+ * `AILK_LEAD_NOTIFICATION_FROM` (already the site's configured "From:" for
+ * lead-facing system email, per `services/lead-routing.ts`); the Working
+ * Session and diagnostic links are derived from the existing
+ * `config.FRONTEND_URL` + fixed paths. The diagnostic page itself is #5001's
+ * build — this link is a forward reference to a route that doesn't exist
+ * yet. `brand` is left unset (the template's clean, unbranded default) since
+ * no per-site branding source is wired into `apps/api` today.
+ *
+ * Never throws; a missing `AILK_LEAD_NOTIFICATION_FROM` no-ops (logs
+ * `listing-email-skipped`, id + decision only) rather than failing the
+ * decision that has already landed.
+ *
+ * On an APPROVE, also fires `fileListingIssue` (#5000) after the email —
+ * fire-and-forget, `.catch`-guarded on top of that function's own internal
+ * try/catch, so neither a slow GitHub call nor a filing failure can delay or
+ * reach the approve path that has already committed. Runs regardless of the
+ * email's own outcome (a Resend failure and a GitHub failure are independent
+ * best-effort side effects of the same committed decision).
+ */
+export async function sendListingDecisionEmail(
+  listing: ProjectListing,
+  decision: ListingDecision,
+): Promise<void> {
+  const fromAddress = process.env["AILK_LEAD_NOTIFICATION_FROM"];
+  if (!fromAddress) {
+    logger.info({ listingId: listing.id, decision }, "listing-email-skipped");
+    fileIssueOnApprove(listing, decision);
+    return;
+  }
+
+  const workingSession = `${config.FRONTEND_URL}/working-session`;
+  // #5036 D1 — `name` and `slug` are nullable at rest so a half-filled draft
+  // is storable, but a decision only ever lands on a SUBMITTED row, which
+  // proved both. The fallbacks discharge the type, they do not paper over a
+  // reachable state.
+  const projectName = listing.name ?? listing.founderName;
+  const diagnosticSlug = listing.slug ?? listing.id;
+
+  const result =
+    decision === "active"
+      ? await sendListingApprovedEmail({
+          to: listing.founderEmail,
+          fromAddress,
+          founderName: listing.founderName,
+          projectName,
+          links: { workingSession },
+        })
+      : await sendListingRejectedEmail({
+          to: listing.founderEmail,
+          fromAddress,
+          founderName: listing.founderName,
+          projectName,
+          links: { workingSession, diagnostic: `${config.FRONTEND_URL}/diagnostic/${diagnosticSlug}` },
+        });
+
+  if (!result.ok) {
+    logger.warn(
+      { listingId: listing.id, decision, errorKind: result.error.kind },
+      "listing email send failed",
+    );
+  }
+
+  fileIssueOnApprove(listing, decision);
+}
+
+/**
+ * Fire-and-forget entry to `fileListingIssue` (#5000) — a no-op on
+ * `rejected`. `fileListingIssue` already never throws (its own try/catch
+ * around the fetch + DB write); this `.catch` is a second boundary for the
+ * one thing outside that try — `renderListingIssue` running before it — so
+ * NOTHING from this call can ever propagate into `sendListingDecisionEmail`'s
+ * caller.
+ */
+function fileIssueOnApprove(listing: ProjectListing, decision: ListingDecision): void {
+  if (decision !== "active") return;
+  fileListingIssue(listing).catch((err: unknown) => {
+    logger.warn(
+      { listingId: listing.id, errName: err instanceof Error ? err.name : "UnknownError" },
+      "listing issue filing rejected unexpectedly",
+    );
+  });
+}
+
+// ─── #5001 — the approve-path side-effect seam ─────────────────────────────
+
+/** The status whose arrival triggers the projection — the approved state. */
+const APPROVED = "active";
+
+/**
+ * Run the decision's downstream effects for one listing. Called by
+ * `patchProjectListing` immediately after a successful transition write;
+ * never throws.
+ */
+export async function onListingDecided(
+  siteId: string,
+  listingId: string,
+  toStatus: string,
+): Promise<void> {
+  if (toStatus !== APPROVED) return;
+
+  try {
+    const row = await prisma.projectListing.findFirst({
+      where: { id: listingId, siteId },
+      select: {
+        id: true,
+        siteId: true,
+        slug: true,
+        name: true,
+        oneLiner: true,
+        questions: true,
+      },
+    });
+    if (!row) return;
+
+    // The stored `questions` blob is validated on write (#4998's POST route)
+    // — re-parsing here is defense in depth, and the one place a row that
+    // predates or drifts from the template is skipped rather than projected
+    // into a malformed flow.
+    // #5036 D1 — `slug`/`name`/`oneLiner` are nullable at rest so a half-filled
+    // draft is storable. A row can only reach `active` through `submit`, which
+    // asserts all three, so this discharges a type-level possibility rather
+    // than a reachable state — and skips rather than throwing, matching the
+    // fail-soft contract this whole seam carries.
+    if (row.slug === null || row.name === null || row.oneLiner === null) {
+      logger.warn(
+        { siteId, listingId, kind: "incomplete_listing" },
+        "[project-listing-decision] skipping flow generation — an approved listing is missing submit-time fields",
+      );
+      return;
+    }
+
+    const questions = projectListingQuestionsSchema.safeParse(row.questions);
+    if (!questions.success) {
+      logger.warn(
+        { siteId, listingId, slug: row.slug, kind: "invalid_questions" },
+        "[project-listing-decision] skipping flow generation — stored questions failed schema validation",
+      );
+      return;
+    }
+
+    const result = await generateListingFlow({
+      id: row.id,
+      siteId: row.siteId,
+      slug: row.slug,
+      name: row.name,
+      oneLiner: row.oneLiner,
+      questions: questions.data,
+    });
+
+    if (!result.ok) {
+      logger.error(
+        { siteId, listingId, slug: row.slug, kind: result.error.kind },
+        "[project-listing-decision] flow generation failed — the listing is approved but has no diagnostic",
+      );
+      return;
+    }
+
+    logger.info(
+      { siteId, listingId, slug: row.slug, kind: "generated" },
+      "[project-listing-decision] diagnostic flow + experiment generated",
+    );
+  } catch (err) {
+    logger.error(
+      {
+        siteId,
+        listingId,
+        errKind: err instanceof Error ? err.constructor.name : typeof err,
+      },
+      "[project-listing-decision] approve hook failed — the transition still succeeded",
+    );
+  }
+}