create-ailk 0.1.0 → 0.1.1

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,98 @@
+/**
+ * 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);
+
+    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 });
+  });
+};