create-ailk 0.11.1 → 0.11.3

package/templates/apps/web/app/openapi.json/route.ts

@@ -0,0 +1,127 @@
+/**
+ * GET /openapi.json
+ *
+ * The OpenAPI document `/.well-known/ai-plugin.json` advertises as its
+ * `api.url` (#7396). apps/api renders it at `/v1/openapi.json`; this route
+ * serves that same document on the web host, so the URL the manifest names
+ * answers here instead of 404ing. It is read over HTTP — apps/web never
+ * imports apps/api.
+ *
+ * A `servers[]` URL that is relative (apps/api emits `/` when
+ * AILK_PUBLIC_API_URL is unset) is resolved against the API origin before the
+ * document is served. Left relative, it would resolve against THIS host,
+ * which serves none of the API's paths.
+ *
+ * When the API cannot be reached, or answers anything but an OpenAPI
+ * document with a 200, this route answers 502 with a JSON error that names no
+ * upstream origin, and is never cached.
+ */
+
+// Read per request: the document is the running API's, and `next build` has
+// no API to read it from.
+export const dynamic = "force-dynamic";
+
+const UPSTREAM_PATH = "/v1/openapi.json";
+const UPSTREAM_TIMEOUT_MS = 10_000;
+
+const LOCAL_API_ORIGIN = "http://localhost:3001";
+
+/**
+ * The apps/api origin this server reads from — the server-side resolution
+ * order of `getApiBase()` in `@working-theory/api-client`, which the package
+ * root does not export. The deprecated `NEXT_PUBLIC_API_URL` is not read.
+ */
+function apiBase(): string {
+  return stripSlash(
+    process.env["AILK_API_URL"] ||
+      process.env["NEXT_PUBLIC_AILK_API_URL"] ||
+      LOCAL_API_ORIGIN,
+  );
+}
+
+/**
+ * The apps/api origin an agent reading the document calls — the
+ * browser-facing name first, since AILK_API_URL may be a private address.
+ */
+function publicApiBase(): string {
+  return stripSlash(
+    process.env["NEXT_PUBLIC_AILK_API_URL"] ||
+      process.env["AILK_API_URL"] ||
+      LOCAL_API_ORIGIN,
+  );
+}
+
+function stripSlash(url: string): string {
+  return url.replace(/\/+$/, "");
+}
+
+interface OpenApiDocument {
+  openapi: string;
+  servers?: Array<{ url?: unknown; description?: unknown }>;
+}
+
+function isOpenApiDocument(value: unknown): value is OpenApiDocument {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { openapi?: unknown }).openapi === "string"
+  );
+}
+
+/** Resolve every relative `servers[].url` against the public API origin. */
+function withAbsoluteServers(spec: OpenApiDocument): OpenApiDocument {
+  if (!Array.isArray(spec.servers)) return spec;
+  const origin = publicApiBase();
+  return {
+    ...spec,
+    servers: spec.servers.map((server) =>
+      typeof server.url === "string" && !/^[a-z][a-z\d+.-]*:/i.test(server.url)
+        ? {
+            ...server,
+            url: stripSlash(new URL(server.url, `${origin}/`).href),
+            description: "This deployment's API",
+          }
+        : server,
+    ),
+  };
+}
+
+function badGateway(message: string): Response {
+  return Response.json(
+    { error: { code: "upstream_unavailable", message } },
+    { status: 502, headers: { "cache-control": "no-store" } },
+  );
+}
+
+export async function GET(): Promise<Response> {
+  let upstream: Response;
+  try {
+    upstream = await fetch(`${apiBase()}${UPSTREAM_PATH}`, {
+      cache: "no-store",
+      signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
+    });
+  } catch {
+    return badGateway("The API did not answer.");
+  }
+
+  if (upstream.status !== 200) {
+    await upstream.body?.cancel();
+    return badGateway(`The API answered ${upstream.status}.`);
+  }
+
+  let spec: unknown;
+  try {
+    spec = await upstream.json();
+  } catch {
+    return badGateway("The API answered a body that is not JSON.");
+  }
+
+  if (!isOpenApiDocument(spec)) {
+    return badGateway("The API answered JSON that is not an OpenAPI document.");
+  }
+
+  return Response.json(withAbsoluteServers(spec), {
+    status: 200,
+    headers: { "cache-control": "public, max-age=3600" },
+  });
+}

package/templates/apps/web/auth.ts

@@ -29,9 +29,11 @@ import type { PrismaClient } from "@working-theory/database";
 import { betterAuth } from "better-auth";
 import { prismaAdapter } from "better-auth/adapters/prisma";
 import { nextCookies } from "better-auth/next-js";
+import { magicLink } from "better-auth/plugins";
 
 import {
   authEmailTransport,
+  makeMagicLinkOptions,
   makeSendPasswordChangedNotice,
   makeSendResetPassword,
   makeSendVerificationEmail,
@@ -59,16 +61,76 @@ const RESET_TOKEN_TTL_SECONDS = 3600;
  */
 const VERIFY_TOKEN_TTL_SECONDS = 86_400;
 
-// Lazy-load prisma-for-auth: import is deferred until createAuth() is called
-// without an explicit `prisma` dep. This prevents the PrismaClient singleton
-// from initialising (and calling @working-theory/database) at module-load time, which
-// lets tests import `createAuth` without triggering a DB connection.
-function getDefaultPrisma(): PrismaClient {
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const { prismaForAuth } = require("./lib/prisma-for-auth") as {
-    prismaForAuth: PrismaClient;
-  };
-  return prismaForAuth;
+let prismaForAuthLoad: Promise<PrismaClient> | undefined;
+
+/**
+ * The `prismaForAuth` singleton, loaded once through `import()`. A failed load
+ * is not cached, so the next call retries — as the old in-`createAuth()`
+ * require did.
+ */
+function loadPrismaForAuth(): Promise<PrismaClient> {
+  prismaForAuthLoad ??= import("./lib/prisma-for-auth").then(
+    (mod) => mod.prismaForAuth,
+    (err: unknown) => {
+      prismaForAuthLoad = undefined;
+      throw err;
+    },
+  );
+  return prismaForAuthLoad;
+}
+
+/**
+ * The default client: every member resolves the singleton before it runs.
+ *
+ * NEVER a synchronous `require()` of `./lib/prisma-for-auth` (#7401).
+ * `next build --webpack` compiles that module as an ASYNC module — it imports
+ * ESM (`@prisma/adapter-pg`, the generated client) — and a synchronous
+ * `require()` of an async webpack module returns a pending namespace, not its
+ * exports. `prismaAdapter()` received `undefined`, and every social sign-in
+ * 500'd on `Cannot read properties of undefined (reading 'verification')`.
+ * `import()` is the ESM-correct load: webpack awaits the module.
+ *
+ * Deferred rather than imported statically so the module still loads WITHOUT
+ * the generated client — `createAuth({ prisma })` tests import this file under
+ * CommonJS Jest, which cannot parse that client. Nothing is lost by the
+ * deferral: Better Auth, `onPasswordReset` and the reset mailer only touch the
+ * client inside request-time async calls. Each member is a function, so the
+ * adapter's `typeof db.$transaction === "function"` check holds and
+ * `$transaction(cb)` runs on the real client, handing `cb` a real transaction
+ * client. (The array form of `$transaction` needs real PrismaPromises; nothing
+ * here uses it.)
+ */
+function deferredPrismaForAuth(): PrismaClient {
+  return new Proxy({} as PrismaClient, {
+    get(_, member) {
+      // Not a thenable, and no symbol-keyed members (inspection, tags).
+      if (typeof member !== "string" || member === "then") return undefined;
+      return new Proxy(() => undefined, {
+        // `$transaction(cb)`, `$connect()` and the other client methods.
+        apply: (_target, _this, args: unknown[]) =>
+          loadPrismaForAuth().then((client) =>
+            Reflect.apply(Reflect.get(client, member), client, args),
+          ),
+        // Model delegates: `verification.create(args)`, `user.findFirst(args)`.
+        // A delegate is not a thenable either.
+        get: (_target, method) =>
+          typeof method === "string" && method !== "then"
+            ? (...args: unknown[]) =>
+                loadPrismaForAuth().then((client) => {
+                  const delegate: unknown = Reflect.get(client, member);
+                  // Every member passes the adapter's `if (!db[model])` check,
+                  // so name a missing model here instead of a bare TypeError.
+                  if (typeof delegate !== "object" || delegate === null) {
+                    throw new Error(
+                      `prismaForAuth has no model delegate "${member}" — regenerate the Prisma client`,
+                    );
+                  }
+                  return Reflect.apply(Reflect.get(delegate, method), delegate, args);
+                })
+            : undefined,
+      });
+    },
+  });
 }
 
 /**
@@ -104,10 +166,9 @@ function buildSocialProviders(): SocialProviders {
     };
   }
 
-  // "email" is reported by getActiveProviderIds when AUTH_EMAIL_SERVER +
-  // AUTH_EMAIL_FROM are set, but Better Auth core does not ship a built-in
-  // magic-link provider — that wiring is deferred to a follow-up
-  // (see spec §7 "Out of Scope").
+  // "email" (the password method) and "magic-link" (the emailed sign-in
+  // link, #7435) are not social providers: `createAuth()` wires them as
+  // `emailAndPassword` and the `magicLink` plugin respectively.
 
   return providers;
 }
@@ -215,7 +276,7 @@ export interface CreateAuthDeps {
  * existing callers (`import { auth }`) are unchanged.
  */
 export function createAuth(deps: CreateAuthDeps = {}) {
-  const prisma = deps.prisma ?? getDefaultPrisma();
+  const prisma = deps.prisma ?? deferredPrismaForAuth();
 
   /**
    * ONE predicate, read in ONE place (#5962 § D2).
@@ -240,6 +301,12 @@ export function createAuth(deps: CreateAuthDeps = {}) {
    */
   const resetConfigured = resetSendConfigured();
 
+  /**
+   * The emailed sign-in link (#7435 § D1). The SAME predicate `/sign-in` and
+   * the `(authed)` gate read, so the form renders iff the endpoint exists.
+   */
+  const magicLinkActive = getActiveProviderIds().includes("magic-link");
+
   const trustedProxies = resolveTrustedProxies();
 
   /** Plain assignment, no cast — see `VerificationStore`. */
@@ -457,6 +524,11 @@ export function createAuth(deps: CreateAuthDeps = {}) {
               "/request-password-reset": { window: 900, max: 5 },
               "/reset-password": { window: 900, max: 10 },
               "/send-verification-email": { window: 900, max: 5 },
+              // #7435 § D6. Without a resolvable IP the plugin's own
+              // 5 / 60 s rule applies — for the shared-bucket reason above.
+              ...(magicLinkActive
+                ? { "/sign-in/magic-link": { window: 900, max: 5 } }
+                : {}),
             },
           }
         : {}),
@@ -526,13 +598,25 @@ export function createAuth(deps: CreateAuthDeps = {}) {
       expiresIn: 60 * 60 * 24 * 7, // 7 days
       updateAge: 60 * 60 * 24, // refresh in DB once per day
     },
-    plugins: [nextCookies()],
+    /**
+     * `magicLink` only when its predicate holds (#7435 § D2): absent, its
+     * `/sign-in/magic-link` and `/magic-link/verify` endpoints do not exist.
+     * Sign-in only — the callback mails existing users and nobody else, and
+     * `disableSignUp` refuses to create one even for a live token
+     * (lib/auth-email.ts).
+     */
+    plugins: magicLinkActive
+      ? [
+          nextCookies(),
+          magicLink(makeMagicLinkOptions({ send: authEmailTransport })),
+        ]
+      : [nextCookies()],
   });
 }
 
 // Lazy singleton: resolved on first access, not at module-load time.
-// Defers the `require("./lib/prisma-for-auth")` call until auth is actually
-// used, so tests can `import { createAuth }` without triggering a DB connection.
+// Defers `createAuth()` — and `resolveSecret()`'s production check — until
+// auth is actually used.
 let _auth: ReturnType<typeof createAuth> | undefined;
 
 export const auth: ReturnType<typeof createAuth> = new Proxy(

package/templates/apps/web/components/sign-out-trigger.tsx

@@ -1,11 +1,12 @@
 "use client"; // Better Auth's client signOut + router navigation need the browser
 
 /**
- * SignOutTrigger — the one client child of the server-rendered Nav (#4984).
+ * SignOutTrigger — wraps the signed-in Nav's "Sign out" trigger (#4984).
  *
  * The locale layout (RSC) reads the session and authors the "Sign out" nav
  * action as `kind: "flow"`; Nav hands the rendered trigger `<Button>` back
- * through `renderFlowTrigger`, and this component clones it with the real
+ * through `renderFlowTrigger` — composed in `SignedInNav`, on the client side
+ * of the RSC boundary (#7402) — and this component clones it with the real
  * sign-out handler. Same `createAuthClient()` idiom as `SignInGate`.
  */
 

package/templates/apps/web/components/signed-in-nav.tsx

@@ -0,0 +1,58 @@
+"use client"; // owns renderFlowTrigger + navItems — functions that cannot cross the RSC boundary (#7402)
+
+/**
+ * SignedInNav — the site Nav for a signed-in visitor (#7402).
+ *
+ * Signed in, the locale layout (RSC) authors two `kind: "flow"` Nav actions —
+ * the visitor's name and "Sign out" — and Nav hands their rendered triggers
+ * back through `renderFlowTrigger`. That composer is a function, and Nav
+ * forwards it into NavMobileMenu ("use client"), so a Server Component that
+ * passes it crashes every signed-in page with "Functions cannot be passed
+ * directly to Client Components". Composing Nav HERE keeps the function on the
+ * client side of the boundary.
+ *
+ * `navItems` is owned here for the same reason: a generated nav inventory
+ * carries Lucide icon components on its flyout entries, and a component is a
+ * function too. The layout passes only serializable props (labels, actions,
+ * the brand elements); everything callable is imported or defined below.
+ *
+ * Signed out, the layout keeps rendering Nav as a Server Component — it has
+ * no flow action, so nothing callable needs to cross.
+ */
+
+import { Nav, type NavProps } from "@working-theory/ui/chrome";
+import type { ReactElement } from "react";
+
+import { navItems } from "../lib/nav-config";
+import { siteChrome } from "../lib/site-chrome";
+
+import { SignOutTrigger } from "./sign-out-trigger";
+
+/** Nav's props minus every function-typed one — this type IS the boundary. */
+export type SignedInNavProps = Omit<
+  NavProps,
+  "navItems" | "renderFlowTrigger" | "translate" | "onSearchOpen"
+>;
+
+export function SignedInNav(props: SignedInNavProps): ReactElement {
+  return (
+    <Nav
+      {...props}
+      navItems={siteChrome.nav === "mark-only" ? [] : navItems}
+      // Both signed-in actions are flows with no lightbox: Sign out becomes a
+      // SignOutTrigger, the account action a non-navigating name label.
+      renderFlowTrigger={(action, trigger) =>
+        action.labelKey === "signOut" ? (
+          <SignOutTrigger>{trigger}</SignOutTrigger>
+        ) : (
+          <span
+            className="text-body-sm text-(--color-text-muted)"
+            data-testid="nav-account-name"
+          >
+            {props.labels?.items.account}
+          </span>
+        )
+      }
+    />
+  );
+}

package/templates/apps/web/jest.config.cjs

@@ -60,6 +60,11 @@ module.exports = {
       "<rootDir>/node_modules/@working-theory/sections-registry/dist/index.js",
     "^@working-theory/templates/shells$":
       "<rootDir>/node_modules/@working-theory/templates/dist/shells/index.js",
+    // The account-area subpath (#7429, spec 7423 D7) — the contribution
+    // contract `lib/account-config.ts` types against, and the Inbox pieces
+    // the /account routes render.
+    "^@working-theory/templates/account$":
+      "<rootDir>/node_modules/@working-theory/templates/dist/account/index.js",
     // Pure-data routes-map subpath (#5572 U2) — mapped directly to source so
     // a consumer of the lightweight `./routes` export (routes.ts,
     // next.config.mjs, this suite) never pulls in the templates package's

package/templates/apps/web/lib/__tests__/account-config.test.ts

@@ -0,0 +1,285 @@
+/**
+ * Tests for lib/account-config.ts — the base account area's contributions
+ * (#7429, spec 7423 U3 · AC-6; amended by #7448, U5 · D6a/D8a/D9).
+ *
+ * Covers:
+ *   1. The three contribution arrays are exported; the base area ships no
+ *      Settings section (modules add those).
+ *   2. The base Inbox kinds are exactly `result` and `purchase` — rows of
+ *      the Recents and All tabs; none fills Scheduled (the old Upcoming).
+ *   3. `email-unverified` and `payment-due` are For-you sources — needs-you
+ *      items with an Open action to User settings, never Inbox rows.
+ *   4. Each contribution maps its existing read: the session for
+ *      `email-unverified`, `waitlistSignups.me` per configured key for
+ *      `result`, `flowCheckouts.me` for `purchase`, and `subscription.me`'s
+ *      own `actionRequired` for `payment-due`.
+ *   5. A 404 — or a 401/403 while the email is unverified — is "nothing for
+ *      this caller" (`[]`); any other failed read rejects, a 401/403 for a
+ *      verified email included, so the Inbox can show an error row (D12).
+ */
+
+const mockSignupMe = jest.fn();
+const mockCheckoutsMe = jest.fn();
+const mockSubscriptionMe = jest.fn();
+jest.mock("@working-theory/api-client", () => ({
+  __esModule: true,
+  waitlistSignups: { me: (...args: unknown[]) => mockSignupMe(...args) },
+  flowCheckouts: { me: (...args: unknown[]) => mockCheckoutsMe(...args) },
+  subscription: { me: (...args: unknown[]) => mockSubscriptionMe(...args) },
+}));
+
+import type {
+  AccountContext,
+  AccountForYouSource,
+  AccountInboxKind,
+} from "@working-theory/templates/account";
+
+import {
+  accountExperimentKeys,
+  accountForYouSources,
+  accountInboxKinds,
+  accountSettingsSections,
+} from "../account-config";
+
+const INIT = { headers: { cookie: "session=abc" } };
+
+function ctx(overrides: Partial<AccountContext["user"]> = {}): AccountContext {
+  return {
+    locale: "en",
+    user: {
+      name: "Ada",
+      email: "ada@example.com",
+      emailVerified: true,
+      ...overrides,
+    },
+    t: (key) => `t:${key}`,
+    init: INIT,
+  };
+}
+
+function kind(id: string): AccountInboxKind {
+  const found = accountInboxKinds.find((k) => k.kind === id);
+  if (!found) throw new Error(`no base kind ${id}`);
+  return found;
+}
+
+function source(id: string): AccountForYouSource {
+  const found = accountForYouSources.find((s) => s.id === id);
+  if (!found) throw new Error(`no base For-you source ${id}`);
+  return found;
+}
+
+const SIGNUP = {
+  experimentKey: "diag",
+  waitlistKey: "early",
+  completedAt: "2026-09-01T10:00:00.000Z",
+  tier: "gold",
+  score: 42,
+  aeoScore: null,
+  answers: { q3: null },
+};
+
+const CHECKOUT = {
+  id: "flchk_1",
+  flowSlug: "buy",
+  experimentKey: "diag",
+  offerKey: "pro",
+  status: "completed",
+  amountMinor: 4900,
+  currency: "USD",
+  period: "month",
+  completedAt: "2026-09-02T10:00:00.000Z",
+  createdAt: "2026-09-02T09:00:00.000Z",
+};
+
+const ok = <T>(body: T) => ({ ok: true as const, body });
+const fail = (status: number) => ({ ok: false as const, status, body: null });
+
+afterEach(() => {
+  jest.clearAllMocks();
+  accountExperimentKeys.length = 0;
+});
+
+describe("account-config exports (AC-6)", () => {
+  it("exports the three contribution arrays", () => {
+    expect(Array.isArray(accountInboxKinds)).toBe(true);
+    expect(accountSettingsSections).toEqual([]);
+    expect(Array.isArray(accountForYouSources)).toBe(true);
+  });
+
+  it("ships exactly the two base Inbox kinds, both Recents rows (D6a, D9)", () => {
+    expect(accountInboxKinds.map((k) => [k.kind, k.section])).toEqual([
+      ["result", "updates"],
+      ["purchase", "updates"],
+    ]);
+    // Nothing in the base area fills Scheduled (the old Upcoming), and no
+    // Inbox row asks for a decision — that is the For-you panel's job.
+    expect(accountInboxKinds.some((k) => k.section === "upcoming")).toBe(false);
+    expect(accountInboxKinds.some((k) => k.section === "needs-you")).toBe(false);
+  });
+
+  it("ships email-unverified and payment-due as For-you sources, not Inbox kinds (D9 as amended)", () => {
+    expect(accountForYouSources.map((s) => s.id)).toEqual([
+      "email-unverified",
+      "payment-due",
+    ]);
+    const kinds = accountInboxKinds.map((k) => k.kind);
+    expect(kinds).not.toContain("email-unverified");
+    expect(kinds).not.toContain("payment-due");
+  });
+
+  it("gives every kind a unique id — the `[kind]` route segment", () => {
+    const ids = accountInboxKinds.map((k) => k.kind);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it("names every kind by a message key, never a literal", () => {
+    for (const k of accountInboxKinds)
+      expect(k.label).toMatch(/^[a-z]+(\.[A-Za-z]+)+$/);
+  });
+});
+
+describe("email-unverified — a For-you item from the session", () => {
+  it("is one needs-you item, opening User settings › General", async () => {
+    const items = await source("email-unverified").load(
+      ctx({ emailVerified: false }),
+    );
+    expect(items).toHaveLength(1);
+    expect(items[0]).toMatchObject({
+      id: "email-unverified",
+      type: { id: "email", label: "t:profile.email", tone: "needs-you" },
+      title: "t:profile.unverified",
+      action: { kind: "open", href: "/account/settings#general" },
+      dismissible: true,
+    });
+  });
+
+  it("is empty when the email is verified, and reads no API", async () => {
+    await expect(source("email-unverified").load(ctx())).resolves.toEqual([]);
+    expect(mockSignupMe).not.toHaveBeenCalled();
+    expect(mockCheckoutsMe).not.toHaveBeenCalled();
+    expect(mockSubscriptionMe).not.toHaveBeenCalled();
+  });
+});
+
+describe("result — waitlistSignups.me per accountExperimentKeys", () => {
+  it("reads each configured key with the forwarded init, skipping a 404", async () => {
+    accountExperimentKeys.push("diag", "other");
+    mockSignupMe.mockImplementation(async (key: string) =>
+      key === "diag" ? ok(SIGNUP) : fail(404),
+    );
+    const items = await kind("result").load(ctx());
+    expect(mockSignupMe).toHaveBeenCalledWith("diag", INIT);
+    expect(mockSignupMe).toHaveBeenCalledWith("other", INIT);
+    expect(items).toEqual([
+      { id: "diag", title: "diag", at: SIGNUP.completedAt, data: SIGNUP },
+    ]);
+  });
+
+  it("is empty with no configured key", async () => {
+    await expect(kind("result").load(ctx())).resolves.toEqual([]);
+    expect(mockSignupMe).not.toHaveBeenCalled();
+  });
+
+  it("rejects on a failed read", async () => {
+    accountExperimentKeys.push("diag");
+    mockSignupMe.mockResolvedValue(fail(500));
+    await expect(kind("result").load(ctx())).rejects.toThrow();
+  });
+});
+
+describe("purchase — flowCheckouts.me", () => {
+  it("is one item per checkout, at its completion time", async () => {
+    mockCheckoutsMe.mockResolvedValue(ok([CHECKOUT]));
+    const items = await kind("purchase").load(ctx());
+    expect(mockCheckoutsMe).toHaveBeenCalledWith(INIT);
+    expect(items).toEqual([
+      { id: "flchk_1", title: "pro", at: CHECKOUT.completedAt, data: CHECKOUT },
+    ]);
+  });
+
+  it("is empty on a 404", async () => {
+    mockCheckoutsMe.mockResolvedValue(fail(404));
+    await expect(kind("purchase").load(ctx())).resolves.toEqual([]);
+  });
+
+  it.each([401, 403])(
+    "is empty on a %i while the email is unverified",
+    async (status) => {
+      mockCheckoutsMe.mockResolvedValue(fail(status));
+      await expect(
+        kind("purchase").load(ctx({ emailVerified: false })),
+      ).resolves.toEqual([]);
+    },
+  );
+
+  it.each([401, 403])(
+    "rejects on a %i for a verified email",
+    async (status) => {
+      mockCheckoutsMe.mockResolvedValue(fail(status));
+      await expect(kind("purchase").load(ctx())).rejects.toMatchObject({
+        status,
+      });
+    },
+  );
+
+  it("rejects on a failed read", async () => {
+    mockCheckoutsMe.mockResolvedValue(fail(503));
+    await expect(kind("purchase").load(ctx())).rejects.toThrow();
+  });
+
+  it("details the checkout's fields", () => {
+    const item = {
+      id: "flchk_1",
+      title: "pro",
+      at: CHECKOUT.completedAt,
+      data: CHECKOUT,
+    };
+    const detail = kind("purchase").renderDetail(item, ctx());
+    expect(detail.status).toBe("completed");
+    expect(detail.fields?.items.map((i) => i.label)).toEqual([
+      "t:purchases.offer",
+      "t:purchases.amount",
+      "t:purchases.period",
+      "t:purchases.date",
+    ]);
+  });
+});
+
+describe("payment-due — a For-you item from subscription.me's actionRequired", () => {
+  const SUB = {
+    actionRequired: true,
+    status: "past_due",
+    accessRevokesAt: null,
+    portalAvailable: true,
+  };
+
+  it("is one needs-you item, opening User settings › Billing, when the API says action is required", async () => {
+    mockSubscriptionMe.mockResolvedValue(ok(SUB));
+    const items = await source("payment-due").load(ctx());
+    expect(mockSubscriptionMe).toHaveBeenCalledWith(INIT);
+    expect(items).toHaveLength(1);
+    expect(items[0]).toMatchObject({
+      id: "payment-due",
+      type: { id: "payment", label: "t:subscription.action", tone: "needs-you" },
+      title: "t:subscription.headline",
+      action: { kind: "open", href: "/account/settings#billing" },
+      dismissible: true,
+    });
+  });
+
+  it("is empty when it is not — the status is never re-derived", async () => {
+    mockSubscriptionMe.mockResolvedValue(ok({ ...SUB, actionRequired: false }));
+    await expect(source("payment-due").load(ctx())).resolves.toEqual([]);
+  });
+
+  it("is empty on a 404 (the commerce-disabled build)", async () => {
+    mockSubscriptionMe.mockResolvedValue(fail(404));
+    await expect(source("payment-due").load(ctx())).resolves.toEqual([]);
+  });
+
+  it("rejects on a failed read", async () => {
+    mockSubscriptionMe.mockResolvedValue(fail(500));
+    await expect(source("payment-due").load(ctx())).rejects.toThrow();
+  });
+});