create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/routes/project-listings/patch.ts

@@ -0,0 +1,136 @@
+// oss: false
+/**
+ * PATCH /v1/project-listings/:id
+ *
+ * Tenant-scoped listing mutation (#4998 AC3, reshaped by #5033). The body is
+ * `.strict()` and carries at most two optional fields, at least one:
+ *
+ *   - `status` — `active` | `rejected`, the only transition there is. The
+ *     lifecycle collapsed to five states with `closed` COMPUTED (#5033 D3),
+ *     so `approved -> live` and `live -> closed` no longer exist and `closed`
+ *     is not a value this route (or any route) can write. Routed through
+ *     `decideListing` — the SAME function `POST /v1/slack/actions` calls — so
+ *     the stamp, the window end and the "already decided" idempotency live in
+ *     one place. On a changed decision the founder is emailed once via
+ *     `sendListingDecisionEmail`.
+ *   - `featured` — the operator's shelf flag (#5033 D6), through
+ *     `setListingFeatured`. Whether it reaches the public read at all is the
+ *     site's `featuredEnabled` config, read server-side; this route sets the
+ *     row's own flag and never the config.
+ *
+ * Sent together, the featured write lands first and the decision's response
+ * is what the caller gets back, so one call cannot return a row that
+ * contradicts either write.
+ *
+ * `:id` is validated at the boundary the same way `get.ts` does; a foreign or
+ * missing id is `404`. An operator re-PATCHing an already-decided listing
+ * gets `200` with the row unchanged (`decideListing`'s idempotent "second
+ * click" branch — #4999 AC).
+ */
+import { zProjectListingId } from "@working-theory/ids";
+import { projectListingPatchSchema, projectListingSchema } from "@working-theory/validation";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+
+import {
+  decideListing,
+  sendListingDecisionEmail,
+} from "../../services/project-listing-decision.js";
+import { setListingFeatured, PROJECT_LISTING_ROLES } from "../../services/project-listings.js";
+
+import { sendValidated } from "./respond.js";
+
+const paramsSchema = z.object({ id: zProjectListingId });
+
+function unauthorized(reply: FastifyReply) {
+  return reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required" },
+  });
+}
+
+function forbidden(reply: FastifyReply) {
+  return reply.status(403).send({
+    ok: false,
+    error: { code: "forbidden", message: "Forbidden" },
+  });
+}
+
+function invalidParams(reply: FastifyReply) {
+  return reply.status(400).send({
+    ok: false,
+    error: { code: "validation_failed", message: "Invalid project listing id" },
+  });
+}
+
+function invalidBody(reply: FastifyReply, message: string) {
+  return reply.status(400).send({
+    ok: false,
+    error: { code: "invalid_input", message },
+  });
+}
+
+function notFound(reply: FastifyReply) {
+  return reply.status(404).send({
+    ok: false,
+    error: { code: "not_found", message: "Project listing not found" },
+  });
+}
+
+export async function patchProjectListingHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const tenant = request.tenant;
+  if (!tenant) return unauthorized(reply);
+  if (!PROJECT_LISTING_ROLES.has(tenant.role)) {
+    request.log.warn(
+      { method: request.method, path: request.url, status: 403 },
+      "[project-listings] patch denied; insufficient role",
+    );
+    return forbidden(reply);
+  }
+
+  const parsedParams = paramsSchema.safeParse(request.params);
+  if (!parsedParams.success) return invalidParams(reply);
+
+  const parsedBody = projectListingPatchSchema.safeParse(request.body);
+  if (!parsedBody.success) {
+    return invalidBody(reply, parsedBody.error.issues[0]?.message ?? "invalid input");
+  }
+
+  const { status, featured } = parsedBody.data;
+
+  if (featured !== undefined) {
+    const featuredResult = await setListingFeatured(
+      tenant.workspaceId,
+      parsedParams.data.id,
+      featured,
+    );
+    if (!featuredResult.ok) return notFound(reply);
+    if (status === undefined) {
+      return sendValidated(reply, projectListingSchema, featuredResult.value, "patch");
+    }
+  }
+
+  if (status === undefined) {
+    // Unreachable — the body schema refuses an empty object — but the
+    // narrowing has to be discharged before `decideListing`.
+    return invalidBody(reply, "patch body must carry at least one of 'status' or 'featured'");
+  }
+
+  const decisionResult = await decideListing({
+    id: parsedParams.data.id,
+    decision: status,
+    decidedBy: tenant.userId,
+    siteId: tenant.workspaceId,
+  });
+  if (!decisionResult.ok) {
+    if (decisionResult.error.kind === "not_found") return notFound(reply);
+    return invalidBody(reply, decisionResult.error.message);
+  }
+  if (decisionResult.changed) {
+    await sendListingDecisionEmail(decisionResult.value, status);
+  }
+  return sendValidated(reply, projectListingSchema, decisionResult.value, "patch");
+}

package/templates/apps/api/src/routes/project-listings/public.ts

@@ -0,0 +1,52 @@
+/**
+ * GET /v1/project-listings/public?siteKey=
+ *
+ * The anonymous page-render read (#4998 AC4, reshaped by #5033). Every
+ * `active` row for the site, ordered: the three newest by `decidedAt` among
+ * them first, then the rest by `waitlistCount` desc, then `decidedAt` desc.
+ * A row whose window has elapsed comes back with a COMPUTED `closed` status —
+ * no job runs, nothing is stored, and a consumer partitions its shelves on
+ * what it is handed. `featured` surfaces only where the site's
+ * `SiteListingConfig` enables it. `founderEmail` never leaves this route —
+ * `projectListingPublicSchema` (`.omit({founderEmail})`) is what the response
+ * is re-parsed against before send.
+ */
+import {
+  projectListingPublicListResponseSchema,
+  publicSiteKeySchema,
+} from "@working-theory/validation";
+import type { FastifyPluginAsync } from "fastify";
+import { z } from "zod";
+
+import { siteIdForPublicKey } from "../../services/listing-config.js";
+import { publicProjectListings } from "../../services/project-listings.js";
+
+import { sendValidated } from "./respond.js";
+
+const querySchema = z.object({ siteKey: publicSiteKeySchema });
+
+export const publicProjectListingsRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.get("/v1/project-listings/public", async (request, reply) => {
+    const parsedQuery = querySchema.safeParse(request.query);
+    if (!parsedQuery.success) {
+      return reply.status(400).send({
+        ok: false,
+        error: { code: "validation_failed", message: "Invalid siteKey" },
+      });
+    }
+
+    // #5048 D2 — one identifier for the whole mountable contract. The shelves
+    // and the application form are configured with the same public key, so a
+    // site never has to hold two different names for itself.
+    const siteId = await siteIdForPublicKey(parsedQuery.data.siteKey);
+    if (siteId === null) {
+      return reply.status(400).send({
+        ok: false,
+        error: { code: "unknown_site_key", message: "Unknown site key" },
+      });
+    }
+
+    const data = await publicProjectListings(siteId);
+    return sendValidated(reply, projectListingPublicListResponseSchema, data, "public");
+  });
+};

package/templates/apps/api/src/routes/project-listings/respond.ts

@@ -0,0 +1,37 @@
+/**
+ * Response-schema validation for the project-listings routes (#4998),
+ * mirroring `waitlist-experiments/respond.ts`'s discipline: response schemas
+ * are contract-only unless re-parsed against their own `.strict()` schema
+ * before the value leaves the process. A shape drift here is a genuine
+ * internal error (the service layer already guards every field), never a
+ * client-facing 4xx.
+ */
+import { logger } from "@working-theory/observability";
+import type { FastifyReply } from "fastify";
+import type { z } from "zod";
+
+/**
+ * Parse `data` against `schema`; on success send the ORIGINAL `data` object
+ * (not the parsed clone) at `200`, matching the waitlist-experiments
+ * envelope. On failure, log the zod issues (never the raw `data`, which may
+ * carry founder PII) and reply `500`.
+ */
+export function sendValidated<T>(
+  reply: FastifyReply,
+  schema: z.ZodType<T>,
+  data: T,
+  routeName: string,
+): FastifyReply {
+  const parsed = schema.safeParse(data);
+  if (!parsed.success) {
+    logger.error(
+      { route: routeName, issues: parsed.error.issues },
+      "[project-listings] response failed its own contract schema",
+    );
+    return reply.status(500).send({
+      ok: false,
+      error: { code: "internal_error", message: "Response failed contract validation" },
+    });
+  }
+  return reply.status(200).send({ ok: true, data });
+}

package/templates/apps/api/src/routes/project-listings/resume-token.ts

@@ -0,0 +1,22 @@
+/**
+ * The resume token's transport (#5036 D1).
+ *
+ * `start` hands the client an opaque token; `patch` and `submit` present it
+ * back. It travels in the `Authorization: Bearer` header rather than in the
+ * body or the query string for two reasons that matter on an anonymous
+ * surface: a query parameter lands in access logs, proxy logs and
+ * `Referer` headers, and a body field cannot be sent on a future GET. The
+ * header is where a credential belongs, and these routes sit in `leadsScope`
+ * where no auth preHandler runs, so nothing else in the stack reads it.
+ */
+import type { FastifyRequest } from "fastify";
+
+const BEARER = /^Bearer (.+)$/;
+
+/** The presented token, or null when the header is absent or malformed. */
+export function resumeTokenFrom(request: FastifyRequest): string | null {
+  const header = request.headers.authorization;
+  if (typeof header !== "string") return null;
+  const match = BEARER.exec(header.trim());
+  return match ? match[1]! : null;
+}

package/templates/apps/api/src/routes/project-listings/start.ts

@@ -0,0 +1,106 @@
+/**
+ * POST /v1/project-listings
+ *
+ * `start` — step one of the application (#5036 D1). Anonymous, registered in
+ * the same rate-limited `leadsScope` as `/v1/leads/*`. Validates with
+ * `projectListingStartSchema` (the founder's name, email and consent, and
+ * optionally a requested window) and writes the `ProjectListing` row at
+ * `status: "draft"`. Returns 201 `{ ok: true, data: { id, resumeToken } }`.
+ *
+ * NO Lead is written here. The founder's contact details are already captured
+ * on the listing row itself at step one, so a Lead would add no capture — and
+ * `routeLead` sends an operator notification, which on an anonymous route
+ * means a stranger could mail the operator by opening a draft they never
+ * finish (PR #5042 security review, finding 4). `submit` writes the Lead.
+ *
+ * This route REPLACES the single anonymous create. The application became a
+ * ten-step form that saves on every advance, so the create had to split into
+ * start / patch / submit; validation moved with it, from write-time to
+ * submit-time. Nothing here asserts the application is complete, because at
+ * step one it never is.
+ *
+ * The response body is the ONLY place the resume token is ever readable: the
+ * server stores a digest of it. A client that loses it has lost the draft.
+ *
+ * NO `siteId` (#5048 D2). The payload names the site by its PUBLIC KEY and
+ * this route resolves the id through `siteIdForPublicKey` — a body-supplied
+ * tenant identifier is exactly what the consuming site's proxy route existed
+ * to prevent, and the resolution moving here is what lets that route go away.
+ * An unknown key is a 400; it never falls back to the deployment's own site.
+ *
+ * NO `slug`, and no site config values (#5033 D1/D2): the slug is derived from
+ * `name` at submit, and the site's window bounds are read server-side. The
+ * applicant may REQUEST a window; the server clamps it rather than rejecting
+ * the application, because a founder who could post their own bound could post
+ * an unbounded one.
+ *
+ * PII-safe logging (mirrors `routes/leads/index.ts`): routing metadata only —
+ * never founderEmail, founderName, or the resume token.
+ *
+ * The response uses the API's own `{ ok, data }` / `{ ok, error }` envelope
+ * (`apps/api/CLAUDE.md`) on BOTH the success and the failure path — the
+ * anonymous create it replaces answered bare on success and enveloped on
+ * failure, so a client branching on `body.ok` read a success as a failure.
+ */
+import {
+  projectListingStartResponseSchema,
+  projectListingStartSchema,
+} from "@working-theory/validation";
+import type { FastifyPluginAsync } from "fastify";
+
+import { siteIdForPublicKey } from "../../services/listing-config.js";
+import { startProjectListingDraft } from "../../services/project-listings.js";
+
+export const startProjectListingRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.post("/v1/project-listings", async (request, reply) => {
+    const parsed = projectListingStartSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.status(400).send({
+        ok: false,
+        error: {
+          code: "invalid_input",
+          message: parsed.error.issues[0]?.message ?? "invalid input",
+        },
+      });
+    }
+
+    // #5048 D2 — the site is resolved SERVER-SIDE from the payload's public
+    // key. The body never carries a `siteId`, and `projectListingStartSchema`
+    // is `.strict()`, so a body that still does is the 400 above naming the
+    // unrecognised key rather than a silently-honoured tenant override. This
+    // is the one property the consuming site's proxy route existed to
+    // guarantee, and resolving it here is what lets that route go away.
+    //
+    // An unknown key is a 400 and never falls back to the deployment's own
+    // site: a typo would otherwise file one site's applications against
+    // another with nothing to notice it.
+    const siteId = await siteIdForPublicKey(parsed.data.siteKey);
+    if (siteId === null) {
+      return reply.status(400).send({
+        ok: false,
+        error: { code: "unknown_site_key", message: "Unknown site key" },
+      });
+    }
+
+    const result = await startProjectListingDraft(siteId, parsed.data);
+    // #5275 — a `consents` map declining a REQUIRED purpose contradicts the
+    // body's own `consent: true`; no row was created.
+    if (!result.ok) {
+      return reply.status(400).send({
+        ok: false,
+        error: { code: result.error.kind, message: result.error.message },
+      });
+    }
+
+    request.log.info(
+      { siteId, listingId: result.id, ip: request.ip },
+      "project listing draft started",
+    );
+
+    const body = projectListingStartResponseSchema.parse({
+      id: result.id,
+      resumeToken: result.resumeToken,
+    });
+    return reply.status(201).send({ ok: true, data: body });
+  });
+};

package/templates/apps/api/src/routes/project-listings/submit.ts

@@ -0,0 +1,122 @@
+/**
+ * POST /v1/project-listings/drafts/:id/submit
+ *
+ * `submit` — the moment an application stops being a draft (#5036 D1).
+ * Anonymous, token-gated, registered in the rate-limited `leadsScope`.
+ *
+ * It carries NO body. Everything it validates is already on the row, put
+ * there by ten steps of `patch`, and the server assembles and validates it
+ * against `projectListingSubmitSchema`. An incomplete draft comes back `422`
+ * with the offending fields NAMED, so the form can send the founder back to
+ * the step that owns each one rather than saying "something is missing".
+ *
+ * Three server-side rules bind here and only here: completeness; the
+ * concurrent-listing limit (`409 listing_limit_reached` — at most two
+ * non-terminal listings per founder, drafts included, #5036 D7); and the
+ * slug, derived from `name` at last (#5033 D2) and returned in the response,
+ * which is the only place a caller learns it.
+ *
+ * The Lead write also happens here rather than at step one, via `routeLead` —
+ * so an anonymous stranger cannot cause an operator notification by opening a
+ * draft they never finish (PR #5042 security review, finding 4). The Slack
+ * notification fires AFTER the transition, never before, and never fails a
+ * submit that already succeeded (`postListingApplication` never throws). Both
+ * moved here from the old create route because this — not step one — is the
+ * moment an operator has an application worth looking at.
+ *
+ * Every response uses the API's own `{ ok, data }` / `{ ok, error }` envelope
+ * (`apps/api/CLAUDE.md`), success included.
+ */
+import { zProjectListingId } from "@working-theory/ids";
+import { projectListingSubmitResponseSchema } from "@working-theory/validation";
+import type { FastifyPluginAsync } from "fastify";
+import { z } from "zod";
+
+import { submitProjectListingDraft } from "../../services/project-listings.js";
+import { postListingApplication } from "../../services/slack-notify.js";
+
+import { resumeTokenFrom } from "./resume-token.js";
+
+const paramsSchema = z.object({ id: zProjectListingId });
+
+export const submitProjectListingRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.post("/v1/project-listings/drafts/:id/submit", async (request, reply) => {
+    const parsedParams = paramsSchema.safeParse(request.params);
+    if (!parsedParams.success) {
+      return reply.status(400).send({
+        ok: false,
+        error: { code: "validation_failed", message: "Invalid project listing id" },
+      });
+    }
+
+    const resumeToken = resumeTokenFrom(request);
+    if (resumeToken === null) {
+      return reply.status(401).send({
+        ok: false,
+        error: { code: "unauthorized", message: "A resume token is required" },
+      });
+    }
+
+    const sourceMeta = {
+      ip: request.ip,
+      userAgent: request.headers["user-agent"],
+      receivedAt: new Date().toISOString(),
+    };
+
+    const result = await submitProjectListingDraft(
+      parsedParams.data.id,
+      resumeToken,
+      sourceMeta,
+    );
+
+    if (!result.ok) {
+      if (result.error.kind === "not_found") {
+        return reply.status(404).send({
+          ok: false,
+          error: { code: "not_found", message: "Draft not found" },
+        });
+      }
+      if (result.error.kind === "incomplete") {
+        return reply.status(422).send({
+          ok: false,
+          error: {
+            code: "incomplete_application",
+            message: result.error.message,
+            missingFields: result.error.missingFields,
+          },
+        });
+      }
+      if (result.error.kind === "listing_limit_reached") {
+        return reply.status(409).send({
+          ok: false,
+          error: { code: "listing_limit_reached", message: result.error.message },
+        });
+      }
+      return reply.status(409).send({
+        ok: false,
+        error: { code: "slug_taken", message: result.error.message },
+      });
+    }
+
+    request.log.info(
+      { siteId: result.listing.siteId, slug: result.slug, ip: request.ip },
+      "project listing applied",
+    );
+
+    // Awaited (not fire-and-forget) so it can't be killed mid-flight by a
+    // serverless runtime tearing down after the response.
+    await postListingApplication({
+      id: result.listing.id,
+      name: result.listing.name,
+      oneLiner: result.listing.oneLiner,
+      problem: result.listing.problem,
+      url: result.listing.url,
+      product: result.listing.product,
+      founderName: result.listing.founderName,
+      founderCompany: result.listing.founderCompany,
+    });
+
+    const body = projectListingSubmitResponseSchema.parse({ id: result.id, slug: result.slug });
+    return reply.status(200).send({ ok: true, data: body });
+  });
+};