@clubedge/create-clubedge-app 0.44.0 → 0.45.0

package/template/apps/api/.env.example

@@ -20,16 +20,33 @@ DATABASE_URL= # clubedge:only infra=neon
 DATABASE_URL_DIRECT=
 
 # Optional: what /api/app-version tells apps installed on phones, as MAJOR.MINOR.PATCH versions
-# such as 1.4.0. Apps below the minimum must update before they continue; apps below the latest
-# may show an update notice. The update URL is an https:// store listing or download page.
+# such as 1.4.0. Apps below the minimum must update before they continue, and the API refuses
+# their requests; apps below the latest may show an update notice. The update URL is an https://
+# store listing or download page.
 APP_MINIMUM_VERSION=
 APP_LATEST_VERSION=
 APP_UPDATE_URL=
-
+# Optional: a minimum announced for a date and time with its time zone, such as
+# 2026-11-01T00:00:00Z. Until then, older apps keep working and warn their users; from then, the
+# API requires it, with no redeploy.
+APP_NEXT_MINIMUM_VERSION=
+APP_NEXT_MINIMUM_VERSION_FROM=
+# Each APP_* variable can be set for one platform by adding _IOS or _ANDROID to its name, such as
+# APP_UPDATE_URL_IOS for the App Store listing and APP_UPDATE_URL_ANDROID for Google Play.
+
+# clubedge:if framework!=none
 # Where rate limits find each client's address (SETUP.md, "Client addresses"). When only the
 # frontend's server reaches the API, as over a private network, set TRUSTED_PROXY_HOPS=1: it sends
 # the client's address as the one X-Forwarded-For entry. Where clients reach the API through your
 # host instead, set CLIENT_IP_HEADER to the header the host puts their address in.
+# clubedge:end
+# clubedge:if framework=none
+# Where rate limits find each client's address (SETUP.md, "Client addresses"). Behind one proxy
+# that adds it to X-Forwarded-For, such as Caddy with Docker Compose, set TRUSTED_PROXY_HOPS=1,
+# but only when clients reach the API through that proxy alone: one that reaches it directly could
+# claim any address. Where your host puts it in a header of its own, set CLIENT_IP_HEADER to that
+# header instead.
+# clubedge:end
 CLIENT_IP_HEADER=
 TRUSTED_PROXY_HOPS=
 
@@ -41,8 +58,8 @@ SUPABASE_PUBLISHABLE_KEY=
 SUPABASE_SECRET_KEY=
 # clubedge:end
 
-# Firebase Authentication. Private key is a server secret; escape newlines as \\n.
 # clubedge:if auth=firebase
+# Firebase Authentication. Private key is a server secret; escape newlines as \\n.
 FIREBASE_PROJECT_ID=
 FIREBASE_API_KEY=
 FIREBASE_CLIENT_EMAIL=
@@ -50,8 +67,8 @@ FIREBASE_PRIVATE_KEY=
 # FIREBASE_AUTH_EMULATOR_HOST=127.0.0.1:9099
 # clubedge:end
 
-# Appwrite project settings. Use an API key with the minimum required scopes.
 # clubedge:if auth=appwrite
+# Appwrite project settings. Use an API key with the minimum required scopes.
 APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
 APPWRITE_PROJECT_ID=
 # Optional: an API key with the sessions.write and users.write scopes, to delete accounts.

package/template/apps/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/api",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/apps/api/src/app.test.ts

@@ -35,7 +35,13 @@ const queue = createMemoryJobs([sampleJob]);
 const capabilities = ["account"];
 
 // Neither app below is given versions, so /api/app-version answers null for each.
-const appVersion = { minimumVersion: null, latestVersion: null, updateUrl: null };
+const appVersion = {
+  minimumVersion: null,
+  latestVersion: null,
+  updateUrl: null,
+  nextMinimumVersion: null,
+  nextMinimumFrom: null,
+};
 
 // The shared contract suite, in process: the same checks any API stack passes over HTTP.
 describe("the API without a database", () => {
@@ -72,3 +78,20 @@ describe("the API with a database", () => {
     },
   );
 });
+
+// With a minimum version, the suite also checks that apps below it get 426 update_required.
+describe("the API with a minimum app version", () => {
+  const versions = { ...appVersion, minimumVersion: "1.2.0", latestVersion: "1.4.0" };
+  const app = createApp({
+    serviceId: "my-product",
+    isReady: async () => true,
+    getCurrentUser: async () => null,
+    appVersion: () => versions,
+    jobs: { runner: () => "worker", queue: () => queue }, // clubedge:only jobs!=none
+  });
+  describeApiConformance(
+    "hono (minimum app version)",
+    () => ({ request: (path, init) => app.request(path, init) }),
+    { ready: true, appVersion: versions, modules, capabilities },
+  );
+});

package/template/apps/api/src/app.ts

@@ -1,6 +1,17 @@
 import { Hono } from "hono";
 import { cors } from "hono/cors";
-import type { AppVersion, Health, Ready, Session, User } from "@clubedge/contract";
+import {
+  APP_PLATFORM_HEADER,
+  APP_VERSION_HEADER,
+  appPlatform,
+  updateStatus,
+  type AppPlatform,
+  type AppVersion,
+  type Health,
+  type Ready,
+  type Session,
+  type User,
+} from "@clubedge/contract";
 import { reportError, type ClientIpSettings } from "@clubedge/core";
 import { getClientIp } from "@clubedge/core"; // clubedge:only framework=none && auth=better-auth
 import { apiError } from "@/http";
@@ -36,8 +47,11 @@ export interface ApiDependencies {
   getCurrentUser(request: Request): Promise<User | null>;
   /** Limits for routes anyone can call (src/server/cache); process memory when absent. */
   createRateLimiter?: CreateRateLimiter;
-  /** The app versions installed apps check (src/server/app-version); all null when absent. */
-  appVersion?(): AppVersion;
+  /**
+   * The app versions installed apps check, for their platform (src/server/app-version); all
+   * null when absent, and then no app is refused.
+   */
+  appVersion?(platform: AppPlatform | null): AppVersion;
   /** Where those limits find the client's address; the connection's own when absent. */
   clientIpSettings?: ClientIpSettings;
   // clubedge:if auth!=none
@@ -62,6 +76,9 @@ export interface ApiDependencies {
   // clubedge:end
 }
 
+/** What an app below the minimum version can still ask: whether the API runs, and where to update. */
+const servedWhileOutdated = new Set(["/api/health", "/api/ready", "/api/app-version"]);
+
 /** The API, implementing packages/contract/openapi.yaml. */
 export function createApp(dependencies: ApiDependencies) {
   const app = new Hono();
@@ -76,6 +93,31 @@ export function createApp(dependencies: ApiDependencies) {
     }),
   );
 
+  // Apps installed on phones send their version with each request: one below the minimum gets
+  // 426 update_required on every route but those it needs to learn that, and where to update,
+  // so it shows its update screen whatever it asked.
+  app.use("/api/*", async (c, next) => {
+    const installed = c.req.header(APP_VERSION_HEADER);
+    if (!installed || !dependencies.appVersion || servedWhileOutdated.has(c.req.path)) {
+      return next();
+    }
+    let versions: AppVersion | null = null;
+    try {
+      versions = dependencies.appVersion(appPlatform(c.req.header(APP_PLATFORM_HEADER)));
+    } catch {
+      // A mistake in the APP_* variables refuses no app: /api/app-version reports it.
+    }
+    if (updateStatus(installed, versions) === "required") {
+      return apiError(
+        c,
+        426,
+        "update_required",
+        "This version of the app is no longer supported: update it to continue.",
+      );
+    }
+    return next();
+  });
+
   app.get("/api/health", (c) =>
     c.json<Health>({
       status: "ok",

package/template/apps/api/src/config/site.json

@@ -6,6 +6,8 @@
   "workspaceLabel": "Starter workspace",
   "links": {
     "repository": "https://github.com/Clubedge/clubedge-starter",
-    "setupGuide": "https://github.com/Clubedge/clubedge-starter/blob/main/SETUP.md"
+    "setupGuide": "https://github.com/Clubedge/clubedge-starter/blob/main/SETUP.md",
+    "terms": "https://example.com/terms",
+    "privacy": "https://example.com/privacy"
   }
 }

package/template/apps/api/src/routes/app-version.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from "vitest";
-import type { AppVersion } from "@clubedge/contract";
+import type { AppPlatform, AppVersion } from "@clubedge/contract";
 import { createApp } from "@/app";
 
-const app = (appVersion?: () => AppVersion) =>
+const app = (appVersion?: (platform: AppPlatform | null) => AppVersion) =>
   createApp({
     serviceId: "my-product",
     isReady: async () => true,
@@ -10,6 +10,14 @@ const app = (appVersion?: () => AppVersion) =>
     appVersion,
   });
 
+const versions: AppVersion = {
+  minimumVersion: "1.2.0",
+  latestVersion: "1.4.1",
+  updateUrl: "https://apps.example.com/my-product",
+  nextMinimumVersion: "1.3.0",
+  nextMinimumFrom: "2026-11-01T00:00:00.000Z",
+};
+
 describe("/api/app-version", () => {
   it("answers null versions until the composition root sets them, never cached", async () => {
     const response = await app().request("/api/app-version");
@@ -19,17 +27,70 @@ describe("/api/app-version", () => {
       minimumVersion: null,
       latestVersion: null,
       updateUrl: null,
+      nextMinimumVersion: null,
+      nextMinimumFrom: null,
     });
   });
 
   it("serves the versions from the composition root", async () => {
-    const versions: AppVersion = {
-      minimumVersion: "1.2.0",
-      latestVersion: "1.4.1",
-      updateUrl: "https://apps.example.com/my-product",
-    };
     const response = await app(() => versions).request("/api/app-version");
     expect(response.status).toBe(200);
     expect(await response.json()).toEqual(versions);
   });
+
+  it("serves the platform the app names its versions", async () => {
+    const platforms: Array<AppPlatform | null> = [];
+    const api = app((platform) => {
+      platforms.push(platform);
+      return versions;
+    });
+    await api.request("/api/app-version", { headers: { "X-App-Platform": "ios" } });
+    await api.request("/api/app-version", { headers: { "X-App-Platform": "web" } });
+    await api.request("/api/app-version");
+    expect(platforms).toEqual(["ios", null, null]);
+  });
+});
+
+describe("apps below the minimum", () => {
+  const api = app(() => versions);
+  const from = (version: string) => ({ headers: { "X-App-Version": version } });
+
+  it("are answered 426 update_required", async () => {
+    const response = await api.request("/api/session", from("1.1.9"));
+    expect(response.status).toBe(426);
+    expect(await response.json()).toEqual({
+      error: { code: "update_required", message: expect.any(String) },
+    });
+  });
+
+  it("are refused by the minimum of the platform they name", async () => {
+    const byPlatform = app((platform) => ({
+      ...versions,
+      minimumVersion: platform === "ios" ? "1.3.0" : "1.2.0",
+    }));
+    const on = (platform: string) => ({
+      headers: { "X-App-Version": "1.2.5", "X-App-Platform": platform },
+    });
+    expect((await byPlatform.request("/api/session", on("ios"))).status).toBe(426);
+    expect((await byPlatform.request("/api/session", on("android"))).status).toBe(200);
+  });
+
+  it("can still learn whether to update, and where", async () => {
+    for (const path of ["/api/health", "/api/ready", "/api/app-version"]) {
+      expect((await api.request(path, from("1.1.9"))).status).toBe(200);
+    }
+  });
+
+  it("are the only ones refused: apps below an announced minimum are still served", async () => {
+    expect((await api.request("/api/session", from("1.2.0"))).status).toBe(200);
+    expect((await api.request("/api/session")).status).toBe(200);
+    expect((await api.request("/api/session", from("beta"))).status).toBe(200);
+  });
+
+  it("are served while the APP_* variables have a mistake, which /api/app-version reports", async () => {
+    const broken = app(() => {
+      throw new Error("App version environment validation failed.");
+    });
+    expect((await broken.request("/api/session", from("1.1.9"))).status).toBe(200);
+  });
 });

package/template/apps/api/src/routes/app-version.ts

@@ -1,16 +1,23 @@
 // The app versions the API serves, for apps installed on phones: they keep calling the API long
 // after a release, so they ask here whether they must update, or may.
 import { Hono } from "hono";
-import type { AppVersion } from "@clubedge/contract";
+import { APP_PLATFORM_HEADER, appPlatform, type AppVersion } from "@clubedge/contract";
 import type { ApiDependencies } from "@/app";
 
 /** No version set: no app is asked to update. */
-const unset: AppVersion = { minimumVersion: null, latestVersion: null, updateUrl: null };
+const unset: AppVersion = {
+  minimumVersion: null,
+  latestVersion: null,
+  updateUrl: null,
+  nextMinimumVersion: null,
+  nextMinimumFrom: null,
+};
 
 export function appVersionRoutes(dependencies: ApiDependencies) {
   return new Hono().get("/api/app-version", (c) => {
     // Never cached, so a new minimum version applies on the app's next check.
     c.header("Cache-Control", "no-store");
-    return c.json<AppVersion>(dependencies.appVersion?.() ?? unset);
+    const platform = appPlatform(c.req.header(APP_PLATFORM_HEADER));
+    return c.json<AppVersion>(dependencies.appVersion?.(platform) ?? unset);
   });
 }

package/template/apps/api/src/server/app-version.test.ts

@@ -8,12 +8,27 @@ afterEach(() => {
 
 const notAVersion = (key: string) => `${key} is not MAJOR.MINOR.PATCH, such as 1.4.0`;
 
+const unset = {
+  minimumVersion: null,
+  latestVersion: null,
+  updateUrl: null,
+  nextMinimumVersion: null,
+  nextMinimumFrom: null,
+};
+
+const stub = (variables: Record<string, string>) => {
+  for (const [key, value] of Object.entries(variables)) vi.stubEnv(key, value);
+};
+
 describe("appVersion", () => {
   it("reads the versions and where to get the update", () => {
-    vi.stubEnv("APP_MINIMUM_VERSION", "1.2.0");
-    vi.stubEnv("APP_LATEST_VERSION", "1.10.0");
-    vi.stubEnv("APP_UPDATE_URL", "https://apps.example.com/my-product");
+    stub({
+      APP_MINIMUM_VERSION: "1.2.0",
+      APP_LATEST_VERSION: "1.10.0",
+      APP_UPDATE_URL: "https://apps.example.com/my-product",
+    });
     expect(appVersion()).toEqual({
+      ...unset,
       minimumVersion: "1.2.0",
       latestVersion: "1.10.0",
       updateUrl: "https://apps.example.com/my-product",
@@ -21,10 +36,66 @@ describe("appVersion", () => {
   });
 
   it("answers null for each empty variable, as in a copied .env.example", () => {
-    vi.stubEnv("APP_MINIMUM_VERSION", "");
-    vi.stubEnv("APP_LATEST_VERSION", "");
-    vi.stubEnv("APP_UPDATE_URL", "");
-    expect(appVersion()).toEqual({ minimumVersion: null, latestVersion: null, updateUrl: null });
+    stub({ APP_MINIMUM_VERSION: "", APP_LATEST_VERSION: "", APP_UPDATE_URL: "" });
+    expect(appVersion()).toEqual(unset);
+  });
+
+  it("gives a platform its own variables, and the shared ones otherwise", () => {
+    stub({
+      APP_MINIMUM_VERSION: "1.2.0",
+      APP_LATEST_VERSION: "1.4.0",
+      APP_LATEST_VERSION_IOS: "1.3.0",
+      APP_UPDATE_URL: "https://example.com/download",
+      APP_UPDATE_URL_IOS: "https://apps.apple.com/app/id1",
+      APP_UPDATE_URL_ANDROID: "https://play.google.com/store/apps/details?id=com.example",
+    });
+    expect(appVersion("ios")).toMatchObject({
+      minimumVersion: "1.2.0",
+      latestVersion: "1.3.0",
+      updateUrl: "https://apps.apple.com/app/id1",
+    });
+    expect(appVersion("android")).toMatchObject({
+      latestVersion: "1.4.0",
+      updateUrl: "https://play.google.com/store/apps/details?id=com.example",
+    });
+    expect(appVersion(null)).toMatchObject({
+      latestVersion: "1.4.0",
+      updateUrl: "https://example.com/download",
+    });
+  });
+
+  describe("an announced minimum", () => {
+    const announced = {
+      APP_MINIMUM_VERSION: "1.0.0",
+      APP_NEXT_MINIMUM_VERSION: "1.2.0",
+      APP_NEXT_MINIMUM_VERSION_FROM: "2026-11-01T01:00:00+01:00",
+    };
+    const deadline = new Date("2026-11-01T00:00:00Z");
+
+    it("is announced until its date, in UTC", () => {
+      stub(announced);
+      expect(appVersion(null, new Date(deadline.getTime() - 1))).toEqual({
+        ...unset,
+        minimumVersion: "1.0.0",
+        nextMinimumVersion: "1.2.0",
+        nextMinimumFrom: "2026-11-01T00:00:00.000Z",
+      });
+    });
+
+    it("becomes the minimum on its date, with no redeploy", () => {
+      stub(announced);
+      expect(appVersion(null, deadline)).toEqual({ ...unset, minimumVersion: "1.2.0" });
+    });
+
+    it("can be one platform's", () => {
+      stub({
+        APP_MINIMUM_VERSION: "1.0.0",
+        APP_NEXT_MINIMUM_VERSION_ANDROID: "1.2.0",
+        APP_NEXT_MINIMUM_VERSION_FROM_ANDROID: "2026-11-01T00:00:00Z",
+      });
+      expect(appVersion("android", deadline).minimumVersion).toBe("1.2.0");
+      expect(appVersion("ios", deadline).minimumVersion).toBe("1.0.0");
+    });
   });
 
   // The route then fails, and is reported, rather than telling the apps something wrong.
@@ -47,11 +118,15 @@ describe("appVersionProblems", () => {
         APP_MINIMUM_VERSION: "1.2",
         APP_LATEST_VERSION: "v1.4.0",
         APP_UPDATE_URL: "http://apps.example.com/my-product",
+        APP_LATEST_VERSION_IOS: "1.4",
+        APP_NEXT_MINIMUM_VERSION_FROM: "2026-11-01",
       }),
     ).toEqual([
       notAVersion("APP_MINIMUM_VERSION"),
       notAVersion("APP_LATEST_VERSION"),
+      "APP_NEXT_MINIMUM_VERSION_FROM is not a date and time with its time zone, such as 2026-11-01T00:00:00Z",
       "APP_UPDATE_URL is not an https:// URL",
+      notAVersion("APP_LATEST_VERSION_IOS"),
     ]);
   });
 
@@ -64,4 +139,31 @@ describe("appVersionProblems", () => {
       "APP_LATEST_VERSION is older than APP_MINIMUM_VERSION",
     ]);
   });
+
+  it("checks a platform's own versions against the ones it shares", () => {
+    expect(
+      appVersionProblems({ APP_MINIMUM_VERSION: "1.2.0", APP_LATEST_VERSION_IOS: "1.1.0" }),
+    ).toEqual(["APP_LATEST_VERSION_IOS is older than APP_MINIMUM_VERSION"]);
+  });
+
+  it("checks an announced minimum", () => {
+    const from = "2026-11-01T00:00:00Z";
+    expect(appVersionProblems({ APP_NEXT_MINIMUM_VERSION: "1.2.0" })).toEqual([
+      "APP_NEXT_MINIMUM_VERSION and APP_NEXT_MINIMUM_VERSION_FROM go together: set both, or neither",
+    ]);
+    expect(
+      appVersionProblems({
+        APP_MINIMUM_VERSION: "1.2.0",
+        APP_NEXT_MINIMUM_VERSION: "1.2.0",
+        APP_NEXT_MINIMUM_VERSION_FROM: from,
+      }),
+    ).toEqual(["APP_NEXT_MINIMUM_VERSION is not newer than APP_MINIMUM_VERSION"]);
+    expect(
+      appVersionProblems({
+        APP_LATEST_VERSION: "1.1.0",
+        APP_NEXT_MINIMUM_VERSION: "1.2.0",
+        APP_NEXT_MINIMUM_VERSION_FROM: from,
+      }),
+    ).toEqual(["APP_LATEST_VERSION is older than APP_NEXT_MINIMUM_VERSION"]);
+  });
 });

package/template/apps/api/src/server/app-version.ts

@@ -1,57 +1,107 @@
 import { z } from "zod";
-import type { AppVersion } from "@clubedge/contract";
-import { optional, parseEnv } from "@/env";
+import { appPlatforms, isOlder, type AppPlatform, type AppVersion } from "@clubedge/contract";
+import { optional } from "@/env";
+
+// What /api/app-version tells the apps installed on phones, from the APP_* variables. Each can
+// be set for one platform by adding _IOS or _ANDROID to its name: that platform's value then
+// wins, for apps that name it (X-App-Platform). Unset, each is null.
 
-/** The variable `key`, holding a MAJOR.MINOR.PATCH version such as 1.4.0. */
 const versionVariable = (key: string) =>
   optional(z.string().regex(/^\d+\.\d+\.\d+$/, `${key} is not MAJOR.MINOR.PATCH, such as 1.4.0`));
+const urlVariable = (key: string) =>
+  optional(z.url({ protocol: /^https$/, error: `${key} is not an https:// URL` }));
+const dateVariable = (key: string) =>
+  optional(
+    z.iso.datetime({
+      offset: true,
+      error: `${key} is not a date and time with its time zone, such as 2026-11-01T00:00:00Z`,
+    }),
+  );
 
-/** Whether `version` is older than `than`, number by number: 1.9.0 is older than 1.10.0. */
-function isOlder(version: string, than: string): boolean {
-  const a = version.split(".").map(Number);
-  const b = than.split(".").map(Number);
-  const index = a.findIndex((part, i) => part !== b[i]);
-  return index !== -1 && a[index] < b[index];
-}
+const fields = {
+  // The oldest version the API still serves: older apps must update before they continue.
+  APP_MINIMUM_VERSION: versionVariable,
+  // The newest released version: older apps may say an update is out.
+  APP_LATEST_VERSION: versionVariable,
+  // A minimum announced for a date: older apps keep working until then, and warn their users.
+  APP_NEXT_MINIMUM_VERSION: versionVariable,
+  APP_NEXT_MINIMUM_VERSION_FROM: dateVariable,
+  // Where apps get the update, such as their store listing.
+  APP_UPDATE_URL: urlVariable,
+};
+type Field = keyof typeof fields;
 
-// What /api/app-version tells the apps installed on phones. Unset, each is null.
-const appVersionEnvSchema = z
-  .object({
-    // The oldest version the API still serves: older apps must update before they continue.
-    APP_MINIMUM_VERSION: versionVariable("APP_MINIMUM_VERSION"),
-    // The newest released version: older apps may show an update notice.
-    APP_LATEST_VERSION: versionVariable("APP_LATEST_VERSION"),
-    // Where apps get the update, such as their store listing.
-    APP_UPDATE_URL: optional(
-      z.url({ protocol: /^https$/, error: "APP_UPDATE_URL is not an https:// URL" }),
+const suffixes = ["", ...appPlatforms.map((platform) => `_${platform.toUpperCase()}`)];
+const formats = z.object(
+  Object.fromEntries(
+    suffixes.flatMap((suffix) =>
+      Object.entries(fields).map(([key, schema]) => [key + suffix, schema(key + suffix)]),
     ),
-  })
-  .refine(
-    ({ APP_MINIMUM_VERSION: minimum, APP_LATEST_VERSION: latest }) =>
-      !minimum || !latest || !isOlder(latest, minimum),
-    {
-      path: ["APP_LATEST_VERSION"],
-      error: "APP_LATEST_VERSION is older than APP_MINIMUM_VERSION",
-      // Checked once the rest is valid, so it compares two versions.
-      when: ({ issues }) => issues.length === 0,
-    },
-  );
+  ),
+);
+
+type Env = Record<string, string | undefined>;
+
+/** A variable's value for `platform`, its own when set, else the shared one, and its name. */
+function setting(env: Env, field: Field, platform: AppPlatform | null) {
+  const own = platform && `${field}_${platform.toUpperCase()}`;
+  const ownValue = own ? env[own]?.trim() : "";
+  if (own && ownValue) return { key: own, value: ownValue };
+  return { key: field, value: env[field]?.trim() || null };
+}
+
+/** The versions that contradict each other, for each platform and for apps that name none. */
+function inconsistencies(env: Env): string[] {
+  const problems = new Set<string>();
+  for (const platform of [null, ...appPlatforms]) {
+    const minimum = setting(env, "APP_MINIMUM_VERSION", platform);
+    const latest = setting(env, "APP_LATEST_VERSION", platform);
+    const next = setting(env, "APP_NEXT_MINIMUM_VERSION", platform);
+    const from = setting(env, "APP_NEXT_MINIMUM_VERSION_FROM", platform);
+    if (minimum.value && latest.value && isOlder(latest.value, minimum.value)) {
+      problems.add(`${latest.key} is older than ${minimum.key}`);
+    }
+    if (!next.value !== !from.value) {
+      problems.add(`${next.key} and ${from.key} go together: set both, or neither`);
+    }
+    if (next.value && minimum.value && !isOlder(minimum.value, next.value)) {
+      problems.add(`${next.key} is not newer than ${minimum.key}`);
+    }
+    if (next.value && latest.value && isOlder(latest.value, next.value)) {
+      problems.add(`${latest.key} is older than ${next.key}`);
+    }
+  }
+  return [...problems];
+}
+
+/** The mistakes in the APP_* variables of `env`, which `pnpm check:env` lists before a deploy. */
+export function appVersionProblems(env: Env): string[] {
+  const parsed = formats.safeParse(env);
+  if (!parsed.success) return parsed.error.issues.map(({ message }) => message);
+  // Checked once each is valid, so they compare versions.
+  return inconsistencies(env);
+}
 
 /**
- * The versions, read on each request: a mistake in the variables fails the request, and is
- * reported, rather than telling the apps something wrong.
+ * The versions for apps on `platform` at `now`, read on each request: a mistake in the
+ * variables fails the request, and is reported, rather than telling the apps something wrong.
+ * On its date, the announced minimum becomes the one the API requires, with no redeploy.
  */
-export function appVersion(): AppVersion {
-  const env = parseEnv(appVersionEnvSchema, "App version");
+export function appVersion(platform: AppPlatform | null = null, now = new Date()): AppVersion {
+  const problems = appVersionProblems(process.env);
+  if (problems.length > 0) {
+    console.error("Invalid App version environment:", problems);
+    throw new Error("App version environment validation failed. Check your .env.local file.");
+  }
+  const value = (field: Field) => setting(process.env, field, platform).value;
+  const next = value("APP_NEXT_MINIMUM_VERSION");
+  const from = value("APP_NEXT_MINIMUM_VERSION_FROM");
+  const due = !!next && !!from && Date.parse(from) <= now.getTime();
   return {
-    minimumVersion: env.APP_MINIMUM_VERSION || null,
-    latestVersion: env.APP_LATEST_VERSION || null,
-    updateUrl: env.APP_UPDATE_URL || null,
+    minimumVersion: due ? next : value("APP_MINIMUM_VERSION"),
+    latestVersion: value("APP_LATEST_VERSION"),
+    updateUrl: value("APP_UPDATE_URL"),
+    nextMinimumVersion: due ? null : next,
+    nextMinimumFrom: due || !from ? null : new Date(from).toISOString(),
   };
 }
-
-/** The mistakes in the APP_* variables of `env`, which `pnpm check:env` lists before a deploy. */
-export function appVersionProblems(env: Record<string, string | undefined>): string[] {
-  const parsed = appVersionEnvSchema.safeParse(env);
-  return parsed.success ? [] : parsed.error.issues.map(({ message }) => message);
-}