create-ailk 0.4.0 → 0.5.0

package/templates/apps/api/src/routes/leads/__tests__/list.test.ts

@@ -0,0 +1,171 @@
+/**
+ * @file list.test.ts
+ * Route-level inject tests for `GET /v1/leads` (#5678).
+ *
+ * The scoping proof lives one layer down, in
+ * `src/services/__tests__/leads-inbox.test.ts` — it seeds two sites against a
+ * realistically filtering prisma mock and asserts a caller for one reads none
+ * of the other's. This file covers what only the HTTP boundary can show: that
+ * an unauthenticated caller is refused before the service is ever reached,
+ * that the scope cannot be widened from the query string, and that the
+ * envelope and the 400 mapping are what `apps/api/CLAUDE.md` specifies.
+ */
+
+// eslint-disable-next-line no-restricted-syntax -- the service is this route's own collaborator; mocking it keeps these tests on the HTTP boundary (the scoping proof is the service's own test).
+jest.mock("../../../services/leads-inbox.js", () => ({
+  listOwnedLeads: jest.fn(),
+}));
+
+import type { FastifyInstance } from "fastify";
+
+import { listOwnedLeads } from "../../../services/leads-inbox.js";
+import { leadListRoute } from "../list";
+
+const listOwnedLeadsMock = listOwnedLeads as jest.Mock;
+
+const USER_ID = "user_00000000-0000-7000-8000-0000000000a1";
+const PAGE = {
+  items: [
+    {
+      id: "lead_00000000-0000-7000-8000-0000000000d1",
+      name: "Ada Lovelace",
+      email: "ada@example.com",
+      source: "web",
+      createdAt: "2026-09-15T12:00:00.000Z",
+    },
+  ],
+  nextCursor: null,
+};
+
+/**
+ * Builds the route with `request.userId` pre-set, standing in for the
+ * `authPreHandlerPlugin` that decorates it in `server.ts`'s `authScope`.
+ * `userId: undefined` is the anonymous case — the same state the decorator
+ * leaves behind when no session resolves.
+ */
+async function buildApp(userId: string | undefined): Promise<FastifyInstance> {
+  const fastify = require("fastify")();
+  fastify.decorateRequest("userId", undefined);
+  fastify.addHook("onRequest", (request: { userId?: string }, _reply: unknown, done: () => void) => {
+    request.userId = userId;
+    done();
+  });
+  await fastify.register(leadListRoute);
+  return fastify;
+}
+
+describe("GET /v1/leads", () => {
+  let app: FastifyInstance;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    listOwnedLeadsMock.mockResolvedValue({ ok: true, value: PAGE });
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it("401s an unauthenticated caller without touching the read service", async () => {
+    app = await buildApp(undefined);
+
+    const res = await app.inject({ method: "GET", url: "/v1/leads" });
+
+    expect(res.statusCode).toBe(401);
+    expect(res.json()).toEqual({
+      ok: false,
+      error: { code: "unauthorized", message: "Authentication required" },
+    });
+    expect(listOwnedLeadsMock).not.toHaveBeenCalled();
+  });
+
+  it("returns the page in the { ok: true, data } envelope", async () => {
+    app = await buildApp(USER_ID);
+
+    const res = await app.inject({ method: "GET", url: "/v1/leads" });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ ok: true, data: PAGE });
+    expect(listOwnedLeadsMock).toHaveBeenCalledWith({
+      userId: USER_ID,
+      cursor: undefined,
+      limit: 50,
+    });
+  });
+
+  it("ignores a caller-supplied siteId — the scope cannot be widened from the wire", async () => {
+    app = await buildApp(USER_ID);
+
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/leads?siteId=someone-elses-site&workspaceId=another",
+    });
+
+    expect(res.statusCode).toBe(200);
+    // The service is called with the caller's identity and the paging
+    // parameters only — no site, org or workspace value reaches it.
+    expect(listOwnedLeadsMock).toHaveBeenCalledWith({
+      userId: USER_ID,
+      cursor: undefined,
+      limit: 50,
+    });
+  });
+
+  it("400s a malformed cursor before any read", async () => {
+    app = await buildApp(USER_ID);
+
+    const res = await app.inject({ method: "GET", url: "/v1/leads?cursor=not-a-lead-id" });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error.code).toBe("validation_failed");
+    expect(listOwnedLeadsMock).not.toHaveBeenCalled();
+  });
+
+  it("400s a limit above the 200 ceiling", async () => {
+    app = await buildApp(USER_ID);
+
+    const res = await app.inject({ method: "GET", url: "/v1/leads?limit=1000" });
+
+    expect(res.statusCode).toBe(400);
+    expect(listOwnedLeadsMock).not.toHaveBeenCalled();
+  });
+
+  it("maps the service's invalid_cursor to a 400, not a 404 or a silent page 1", async () => {
+    app = await buildApp(USER_ID);
+    listOwnedLeadsMock.mockResolvedValue({
+      ok: false,
+      error: { kind: "invalid_cursor", message: "cursor does not resolve within this scope" },
+    });
+
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/leads?cursor=lead_00000000-0000-7000-8000-0000000000d9",
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json()).toEqual({
+      ok: false,
+      error: {
+        code: "validation_failed",
+        message: "cursor does not resolve within this scope",
+      },
+    });
+  });
+
+  it("500s an internal error without surfacing its detail", async () => {
+    app = await buildApp(USER_ID);
+    listOwnedLeadsMock.mockResolvedValue({
+      ok: false,
+      error: { kind: "internal_error", message: "connect ECONNREFUSED 127.0.0.1:5432" },
+    });
+
+    const res = await app.inject({ method: "GET", url: "/v1/leads" });
+
+    expect(res.statusCode).toBe(500);
+    expect(res.json()).toEqual({
+      ok: false,
+      error: { code: "internal_error", message: "Failed to read leads" },
+    });
+    expect(res.body).not.toContain("ECONNREFUSED");
+  });
+});

package/templates/apps/api/src/routes/leads/list.ts

@@ -0,0 +1,104 @@
+/**
+ * The leads INBOX read (#5678).
+ *
+ * Routes:
+ *   GET /v1/leads?cursor=&limit=  — the caller's own sites' leads, newest first
+ *
+ * Registered INSIDE `server.ts`'s `authScope` (auth only — NOT the inner
+ * `tenantScope`, which the multi-tenant module owns), beside
+ * `/v1/waitlist-signups/me` and `/v1/project-listings/me`. Lead capture is a
+ * never-gate surface at every level, so reading a lead back must be too: this
+ * route is registered unconditionally, not behind an `isModuleEnabled()` gate.
+ * Registering everywhere is not the same as RETURNING a row everywhere —
+ * `services/leads-inbox.ts` § "What it takes for this to return anything"
+ * names the two deployment preconditions, both of which fail empty, never
+ * wide.
+ *
+ * Identity is `request.userId` ONLY. There is no site, org or workspace
+ * parameter — the query schema declares `cursor` and `limit` and nothing else
+ * — so the scope cannot be widened from the wire. `services/leads-inbox.ts`
+ * resolves it from the caller's own memberships through
+ * `services/owner-workspaces.ts`'s `resolveOwnerWorkspaces` and filters every
+ * read on `siteId ∈ workspaceIds`.
+ *
+ * Envelope per apps/api/CLAUDE.md: `{ ok: true, data }` /
+ * `{ ok: false, error: { code, message } }`, real HTTP status codes:
+ *   400 validation_failed · 401 unauthorized · 500 internal_error.
+ *
+ * No response-contract re-parse (the `waitlist-experiments/respond.ts`
+ * `sendValidated` net): the five fields of a row are assembled one by one in
+ * `leads-inbox.ts` from five explicitly selected columns, with no
+ * pass-through of a stored value that could carry an unexpected shape — so
+ * there is no drift for that net to catch.
+ *
+ * API↔MCP parity: identity-bound (the session IS the scope; the OSS MCP
+ * surface is identity-blind) — no MCP twin (#3591 exception, the same shape as
+ * `/v1/workspaces/*`, `/v1/billing/*` and `/v1/waitlist-experiments/*`).
+ */
+import { zLeadId } from "@working-theory/ids";
+import type { FastifyPluginAsync, FastifyReply } from "fastify";
+import { z } from "zod";
+
+import { listOwnedLeads } from "../../services/leads-inbox.js";
+
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+
+const emptyToUndefined = (val: unknown) => (val === "" ? undefined : val);
+
+/** Boundary validation, mirroring `waitlist-experiments/signups.ts`'s query schema. */
+const listQuerySchema = z.object({
+  cursor: z.preprocess(emptyToUndefined, zLeadId.optional()),
+  limit: z.preprocess(
+    emptyToUndefined,
+    z.coerce.number().int().min(1).max(MAX_LIMIT).optional(),
+  ),
+});
+
+function unauthorized(reply: FastifyReply) {
+  return reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required" },
+  });
+}
+
+function invalidQuery(reply: FastifyReply, message: string) {
+  return reply.status(400).send({
+    ok: false,
+    error: { code: "validation_failed", message },
+  });
+}
+
+export const leadListRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.get("/v1/leads", async (request, reply) => {
+    const userId = request.userId;
+    if (!userId) return unauthorized(reply);
+
+    const query = listQuerySchema.safeParse(request.query);
+    if (!query.success) return invalidQuery(reply, "Invalid query parameters");
+
+    const result = await listOwnedLeads({
+      userId,
+      cursor: query.data.cursor,
+      limit: query.data.limit ?? DEFAULT_LIMIT,
+    });
+
+    if (!result.ok) {
+      if (result.error.kind === "invalid_cursor") {
+        return invalidQuery(reply, result.error.message);
+      }
+      // Do not surface internal error detail — log it server-side only, and
+      // with no lead field in the log line (the leads PII boundary).
+      request.log.error(
+        { route: "leads/list", error: result.error.message },
+        "leads list failed",
+      );
+      return reply.status(500).send({
+        ok: false,
+        error: { code: "internal_error", message: "Failed to read leads" },
+      });
+    }
+
+    return reply.status(200).send({ ok: true, data: result.value });
+  });
+};

package/templates/apps/api/src/server.ts

@@ -20,6 +20,7 @@ import { registerErrorSerializer } from "./lib/error-serializer.js";
 import { validateLeadCaptureDir } from "./lib/lead-capture-store.js";
 import { loadSlice } from "./lib/slice-load.js";
 import { authPreHandlerPlugin } from "./middleware/auth.js";
+import { defaultTenantPreHandlerPlugin } from "./middleware/default-tenant.js";
 import {
   rateLimitMiddleware,
   DEFAULT_PER_IP_PER_MINUTE_STRICT,
@@ -49,6 +50,7 @@ import {
   leadSubmitRoute,
   leadSubscribeRoute,
 } from "./routes/leads/index.js";
+import { leadListRoute } from "./routes/leads/list.js";
 import {
   registerTestAuthRoute,
   shouldMountTestAuth,
@@ -334,6 +336,27 @@ async function tenantPreHandlerSlicePlugin(): Promise<FastifyPluginCallback> {
   return plugin;
 }
 
+/**
+ * The tenant guard THIS build runs (#5677). Exactly one of the two, never
+ * both: the multi-tenant module's `resolveActiveTenant` guard when the module
+ * is enabled, and the base-build default-workspace guard
+ * (`middleware/default-tenant.ts`) otherwise.
+ *
+ * Precedence, not parallelism. On a build WITH the module this returns the
+ * identical plugin every tenant scope registered before, so multi-tenant
+ * resolution and behavior are unchanged. On a build without it, the base guard
+ * resolves the seeded default Workspace (`database/tenancy.ts`) under the same
+ * default-deny posture — which is what makes the already-built review
+ * dashboard reachable at Pro instead of leaving its routes unregistered.
+ *
+ * The base guard is a STATIC import, not a slice load: it always ships.
+ */
+async function tenantPreHandlerForBuild(): Promise<FastifyPluginCallback> {
+  return isModuleEnabled("multi-tenant")
+    ? await tenantPreHandlerSlicePlugin()
+    : defaultTenantPreHandlerPlugin;
+}
+
 /**
  * The commerce boot-time sandbox guard — the one other slice entry that is
  * not a route plugin, mirroring `tenantPreHandlerSlicePlugin()` above (D3).
@@ -527,6 +550,18 @@ export async function build() {
       );
     }
 
+    // The leads INBOX read (#5678) — auth only, NOT tenant-guarded, for the
+    // same reason as the three reads below: the tenant scope is registered
+    // only when the multi-tenant module is present, and lead capture is a
+    // never-gate surface at EVERY level, so reading a lead back cannot be
+    // gated on a module either. Registered unconditionally — it is the one
+    // route in this scope with no `isModuleEnabled()` gate. Identity is
+    // `request.userId`; the scope is resolved from the caller's own
+    // memberships by `services/leads-inbox.ts` through
+    // `services/owner-workspaces.ts`'s `resolveOwnerWorkspaces`, never from a
+    // request parameter.
+    await authScope.register(leadListRoute);
+
     // Respondent signup read (#4731) — auth only, NOT tenant-guarded: a
     // respondent has no workspace membership and the tenant guard is
     // default-deny. Identity is request.userId; the service re-checks
@@ -580,6 +615,35 @@ export async function build() {
         await tenantScope.register(await sliceRoutePlugin("sessionRoutes"));
         // Org-billing routes (#3701) — org-scoped read + Stripe customer-portal.
         await tenantScope.register(await sliceRoutePlugin("billingRoutes"));
+      });
+    }
+
+    // REVIEW-SURFACE routes — a sibling tenant scope, gated on EITHER module
+    // (#5677). The waitlist operator dashboard and the project-listings
+    // dashboard were registered inside the multi-tenant scope above, which was
+    // too narrow: `signal-collectors` (Pro) is the module that SELLS the
+    // instruments these routes read back — flows, deliverables, project
+    // listings, waitlist experiments — so a Pro customer could collect
+    // submissions and not read them. That was an accident of registration
+    // scope, not a pricing decision (#5677). Widening the gate is the
+    // correction.
+    //
+    // This is a REGISTRATION change, not a tenant-isolation change. The scope
+    // registers `tenantPreHandlerForBuild()`, which on a multi-tenant build is
+    // byte-for-byte the guard these two route plugins already ran behind, and
+    // on a build without the module is the base-build guard with the same
+    // default-deny posture over the seeded default Workspace. Each plugin
+    // registers exactly once — they live here and nowhere else, so the scopes
+    // cannot collide on a path — and every OTHER route in the scope above
+    // (workspaceSessionRoutes, sessionRoutes, billingRoutes) stays
+    // multi-tenant-only: those are Organization/Workspace administration, not
+    // a site's own submissions.
+    if (
+      isModuleEnabled("multi-tenant") ||
+      isModuleEnabled("signal-collectors")
+    ) {
+      await authScope.register(async (tenantScope) => {
+        await tenantScope.register(await tenantPreHandlerForBuild());
         // Waitlist operator-dashboard read API (#4665 D7, B0) — tenant-scoped
         // list/comparison/signups reads over A1's waitlist-experiment rows.
         await tenantScope.register(
@@ -603,18 +667,30 @@ export async function build() {
     // original mis-scoping twice.
     //
     // This is a REGISTRATION change, not a tenant-isolation change: the scope
-    // registers its own `tenantPreHandlerSlicePlugin()`, the same default-deny
-    // guard the scope above uses, with the same `resolveActiveTenant` behind
-    // it. Every other route in that scope (workspaceSessionRoutes,
-    // sessionRoutes, billingRoutes, waitlistExperimentRoutes, the
-    // project-listings tenant routes) stays multi-tenant-only.
+    // registers its own `tenantPreHandlerForBuild()`, the same default-deny
+    // guard the scopes above use. The remaining routes in the multi-tenant
+    // scope above (workspaceSessionRoutes, sessionRoutes, billingRoutes) stay
+    // multi-tenant-only.
+    //
+    // #5677's selector fixes ONE of this scope's two stripped-scaffold
+    // problems and not the other, so do not read it as making a
+    // `--modules workspace` scaffold work. It removes the guard's dependency
+    // on `./middleware/tenant.js` (a multi-tenant slice file, which threw
+    // ERR_MODULE_NOT_FOUND during construction). The three route plugins
+    // below are still reached through slice loads, and
+    // `routes/workspaces/config.ts` remains a multi-tenant `ownedFiles` entry
+    // — `general.ts` and `members.ts` are workspace-owned, `config.ts` is not
+    // — so that scaffold still has no `routes/workspaces/` directory and
+    // still throws here. Fixing it is the same one-line class of change #5677
+    // made for the review surface: co-own `config.ts` under `workspace` in
+    // MODULE_SLICES. Out of scope for #5677, which owns the review surface.
     //
     // A build with BOTH modules enabled registers each of the three route
     // plugins exactly once: they live here and nowhere else, so the two
     // scopes cannot collide on a path.
     if (isModuleEnabled("workspace") || isModuleEnabled("multi-tenant")) {
       await authScope.register(async (tenantScope) => {
-        await tenantScope.register(await tenantPreHandlerSlicePlugin());
+        await tenantScope.register(await tenantPreHandlerForBuild());
         await tenantScope.register(
           await sliceRoutePlugin("workspaceConfigRoutes"),
         );