@marktiderman/genesis-native 0.1.0 → 0.3.0

package/src/updates/checker.ts

@@ -0,0 +1,190 @@
+/**
+ * The update banner's engine: ask expo-updates for a newer update, download
+ * it, and reload only when the person taps and nothing is mid-edit.
+ *
+ * - It never reloads on its own. A downloaded update also applies on the next
+ *   cold start, so dismissing the banner loses nothing.
+ * - The reload guard says no while any `useBlockReload(true)` is mounted (a
+ *   form with unsaved changes) or your `canReload()` returns false (or
+ *   throws). The banner then asks the person to finish first.
+ * - expo-updates only serves updates built for this binary's runtime
+ *   version; an update whose manifest names another runtime is ignored too.
+ */
+import { createStore, type Store } from "./store";
+import { manifestField, toError, type UpdatesModuleLike, type UpdatesOnError } from "./modules";
+
+export interface ReloadGuard {
+  /** Hold reloads off until the returned function is called. */
+  block(): () => void;
+  /** True when nothing blocks and your `canReload` agrees. */
+  canReload(): boolean;
+  /** Fires when a block starts or ends. */
+  subscribe(listener: () => void): () => void;
+}
+
+export function createReloadGuard(canReload?: () => boolean): ReloadGuard {
+  let blockers = 0;
+  const listeners = new Set<() => void>();
+  const notify = () => {
+    for (const listener of [...listeners]) listener();
+  };
+  return {
+    block() {
+      blockers++;
+      notify();
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        blockers--;
+        notify();
+      };
+    },
+    canReload() {
+      if (blockers > 0) return false;
+      try {
+        return canReload ? canReload() === true : true;
+      } catch {
+        return false; // When in doubt, don't throw away someone's work.
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+export type UpdateCheckStatus = "disabled" | "idle" | "checking" | "downloading" | "ready" | "reloading" | "error";
+
+export interface UpdateCheckState {
+  status: UpdateCheckStatus;
+  /** The downloaded update's id, when the manifest has one. */
+  updateId: string | null;
+  /** The person closed the banner; the update still applies on the next cold start. */
+  dismissed: boolean;
+  /** The last tap was refused by the reload guard; cleared when the guard opens. */
+  blocked: boolean;
+  error: Error | null;
+}
+
+export interface UpdateCheckerOptions {
+  updates?: UpdatesModuleLike;
+  guard: ReloadGuard;
+  /** Passed to `reloadAsync` (a branded reload screen). */
+  reloadScreenOptions?: object;
+  now?: () => number;
+  onError?: UpdatesOnError;
+}
+
+export interface UpdateChecker extends Pick<Store<UpdateCheckState>, "getState" | "subscribe"> {
+  /** Check and download. Never rejects; does nothing while one is in flight or an update is ready. */
+  check(): Promise<void>;
+  /** `check()` unless the last one started less than `minIntervalMs` ago. */
+  checkIfDue(minIntervalMs: number): Promise<void>;
+  /** Reload into the downloaded update. Resolves false when there is none or the guard refuses. */
+  reload(): Promise<boolean>;
+  dismiss(): void;
+  /** Stop following the guard. */
+  dispose(): void;
+}
+
+export function createUpdateChecker(options: UpdateCheckerOptions): UpdateChecker {
+  const { updates, guard, reloadScreenOptions, now = Date.now, onError } = options;
+  const enabled = Boolean(updates?.isEnabled);
+  const store = createStore<UpdateCheckState>({
+    status: enabled ? "idle" : "disabled",
+    updateId: null,
+    dismissed: false,
+    blocked: false,
+    error: null,
+  });
+  let inflight: Promise<void> | null = null;
+  let lastCheck: number | null = null;
+  const report = (error: Error, from: "check" | "reload") => {
+    try {
+      onError?.(error, from);
+    } catch {
+      // ignore a failing reporter
+    }
+  };
+  const stopGuard = guard.subscribe(() => {
+    if (store.getState().blocked && guard.canReload()) store.setState({ blocked: false });
+  });
+
+  const check = (): Promise<void> => {
+    if (!updates || !enabled) return Promise.resolve();
+    const { status } = store.getState();
+    if (inflight || status === "ready" || status === "reloading") return inflight ?? Promise.resolve();
+    lastCheck = now();
+    // eslint-disable-next-line prefer-const -- read in `finally`, after the assignment below
+    let run!: Promise<void>;
+    run = (async () => {
+      // Never settle synchronously (a module that throws before its first await).
+      await null;
+      try {
+        store.setState({ status: "checking", error: null });
+        const result = await updates.checkForUpdateAsync();
+        if (!result.isAvailable && !result.isRollBackToEmbedded) {
+          store.setState({ status: "idle" });
+          return;
+        }
+        const runtime = manifestField(result.manifest, "runtimeVersion");
+        if (runtime && updates.runtimeVersion && runtime !== updates.runtimeVersion) {
+          store.setState({ status: "idle" });
+          return;
+        }
+        store.setState({ status: "downloading" });
+        const fetched = await updates.fetchUpdateAsync();
+        const updateId = manifestField(fetched.manifest, "id") ?? manifestField(result.manifest, "id");
+        if ((fetched.isNew || fetched.isRollBackToEmbedded) && !(updateId && updateId === updates.updateId)) {
+          store.setState({ status: "ready", updateId, dismissed: false });
+        } else {
+          store.setState({ status: "idle" });
+        }
+      } catch (raw) {
+        const error = toError(raw);
+        report(error, "check");
+        store.setState({ status: "error", error });
+      } finally {
+        if (inflight === run) inflight = null;
+      }
+    })();
+    inflight = run;
+    return run;
+  };
+
+  return {
+    getState: store.getState,
+    subscribe: store.subscribe,
+    check,
+    checkIfDue(minIntervalMs) {
+      const at = now();
+      if (lastCheck !== null && at >= lastCheck && at - lastCheck < minIntervalMs) return Promise.resolve();
+      return check();
+    },
+    async reload() {
+      if (!updates || store.getState().status !== "ready") return false;
+      if (!guard.canReload()) {
+        store.setState({ blocked: true });
+        return false;
+      }
+      store.setState({ status: "reloading", blocked: false });
+      try {
+        await updates.reloadAsync(reloadScreenOptions ? { reloadScreenOptions } : undefined);
+        return true;
+      } catch (raw) {
+        const error = toError(raw);
+        report(error, "reload");
+        store.setState({ status: "ready", error });
+        return false;
+      }
+    },
+    dismiss() {
+      store.setState({ dismissed: true, blocked: false });
+    },
+    dispose: stopGuard,
+  };
+}

package/src/updates/index.ts

@@ -0,0 +1,87 @@
+/**
+ * `@marktiderman/genesis-native/updates`: force upgrade, maintenance, the
+ * update banner, what's new, and the version signature for internal builds.
+ *
+ * Rung 1: `<GenesisNativeApp updates={createUpdates(…)}>`. Rung 2: its
+ * `forceUpgrade`, `maintenance`, `updateBanner` and `whatsNew` slots. Rung 3:
+ * the screens (`ForceUpgradeScreen`, …) and stores (`createPolicyStore`, …).
+ * Rung 4: the hooks (`useForceUpgrade`, …) under `UpdatesProvider`.
+ *
+ * Optional peers: `expo-updates` (banner, channels) and `expo-application`
+ * (the installed version), passed in rather than imported.
+ *
+ * @stability Beta
+ */
+export {
+  createUpdates,
+  UPDATES_BLOCK_ID,
+  UpdatesProvider,
+  UpdatesRoot,
+  useUpdates,
+  useBlockReload,
+  useUpdatePolicy,
+  useUpdateVerdict,
+  useForceUpgrade,
+  useMaintenance,
+  useUpdateCheck,
+  useCanReload,
+  useUpdateBanner,
+  useWhatsNew,
+  useVersionSignature,
+  type UpdatesBlock,
+  type UpdatesOptions,
+  type UpdatesRootProps,
+  type UpdatesSlots,
+} from "./block";
+export {
+  ForceUpgradeScreen,
+  MaintenanceScreen,
+  UpdateBanner,
+  WhatsNewSheet,
+  type ForceUpgradeProps,
+  type MaintenanceProps,
+  type UpdateBannerProps,
+  type WhatsNewProps,
+} from "./screens";
+export {
+  createPolicyStore,
+  evaluatePolicy,
+  sanitizePolicy,
+  staticPolicySource,
+  supabasePolicySource,
+  CLOCK_SKEW_MS,
+  WEEK_MS,
+  type EvaluatePolicyOptions,
+  type PolicyClientLike,
+  type PolicyOrigin,
+  type PolicyState,
+  type PolicyStore,
+  type PolicyStoreOptions,
+  type ReleaseNote,
+  type SupabasePolicySourceOptions,
+  type UpdatePlatform,
+  type UpdatePolicy,
+  type UpdatePolicySource,
+  type UpdateVerdict,
+} from "./policy";
+export {
+  createUpdateChecker,
+  createReloadGuard,
+  type ReloadGuard,
+  type UpdateChecker,
+  type UpdateCheckerOptions,
+  type UpdateCheckState,
+  type UpdateCheckStatus,
+} from "./checker";
+export { createWhatsNewStore, notesSince, type WhatsNewOptions, type WhatsNewState, type WhatsNewStore } from "./whats-new";
+export { versionSignature, type VersionSignature, type VersionSignatureInput } from "./signature";
+export { createChannelSwitcher, type ChannelSwitcher, type ChannelSwitcherOptions, type ChannelSwitchResult } from "./channels";
+export { compareVersions, isBelowMinimum, parseVersion } from "./version";
+export type {
+  ApplicationLike,
+  UpdatesAppStateLike,
+  UpdatesErrorSource,
+  UpdatesModuleLike,
+  UpdatesOnError,
+  UpdatesStorageLike,
+} from "./modules";

package/src/updates/modules.ts

@@ -0,0 +1,64 @@
+/**
+ * The native modules the updates block reads, as the shapes it needs. Pass
+ * the real ones (`import * as Updates from "expo-updates"`,
+ * `import * as Application from "expo-application"`); tests pass fakes.
+ * Both are optional peers: without `expo-updates` there is no update banner
+ * and no channel switching, and without `expo-application` no force upgrade.
+ */
+
+/** `expo-updates` (SDK 58): the constants and calls this block uses. */
+export interface UpdatesModuleLike {
+  /** False in development, Expo Go, or a build without updates configured. */
+  readonly isEnabled: boolean;
+  /** The running update's id; `null` when updates are off. */
+  readonly updateId: string | null;
+  /** The build's channel; `null` in development builds and Expo Go. */
+  readonly channel: string | null;
+  readonly runtimeVersion: string | null;
+  /** True when the code that shipped in the binary is running, not a downloaded update. */
+  readonly isEmbeddedLaunch: boolean;
+  /** True when expo-updates fell back to the embedded update after a failed launch. */
+  readonly isEmergencyLaunch?: boolean;
+  readonly emergencyLaunchReason?: string | null;
+  checkForUpdateAsync(): Promise<{ isAvailable: boolean; isRollBackToEmbedded?: boolean; manifest?: unknown }>;
+  fetchUpdateAsync(): Promise<{ isNew: boolean; isRollBackToEmbedded?: boolean; manifest?: unknown }>;
+  reloadAsync(options?: { reloadScreenOptions?: object }): Promise<void>;
+  /** Overrides the `expo-channel-name` header (persists on the device); `null` removes the override. */
+  setUpdateRequestHeadersOverride?(requestHeaders: Record<string, string> | null): void;
+}
+
+/** `expo-application`: the installed store version and build number. */
+export interface ApplicationLike {
+  /** `CFBundleShortVersionString` / `versionName`, e.g. `"1.4.0"`. */
+  readonly nativeApplicationVersion: string | null;
+  /** `CFBundleVersion` / `versionCode`, e.g. `"37"`. */
+  readonly nativeBuildVersion: string | null;
+}
+
+/** AsyncStorage, MMKV's async adapter, or a stand-in. */
+export interface UpdatesStorageLike {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem?(key: string): Promise<void>;
+}
+
+/** React Native's `AppState`. */
+export interface UpdatesAppStateLike {
+  addEventListener(type: "change", listener: (state: string) => void): { remove(): void };
+}
+
+/** Where a reported error came from. */
+export type UpdatesErrorSource = "policy" | "check" | "reload" | "storage" | "channel";
+
+export type UpdatesOnError = (error: Error, source: UpdatesErrorSource) => void;
+
+export function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(typeof value === "string" ? value : "Unknown error");
+}
+
+/** The `id` (and `runtimeVersion`) of an update manifest, when it has them. */
+export function manifestField(manifest: unknown, field: "id" | "runtimeVersion"): string | null {
+  if (!manifest || typeof manifest !== "object") return null;
+  const value = (manifest as Record<string, unknown>)[field];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}

package/src/updates/policy.ts

@@ -0,0 +1,314 @@
+/**
+ * The release policy: the oldest store version each platform may run, a
+ * maintenance switch, and release notes. It comes from an
+ * `UpdatePolicySource` (a static object, Supabase, or your own), is cached on
+ * the phone, and **fails open**: no answer, a timeout, a malformed value or
+ * an untrusted cache never blocks anyone.
+ *
+ * What may block, and from where:
+ * - Force upgrade: a policy fetched this session, or a cached one no older
+ *   than `cacheMaxAgeMs` (7 days) by the phone's clock. A cache whose time is
+ *   in the future (the clock moved back) is not trusted. A minimum without a
+ *   store link for the platform forces nothing (there would be no way out).
+ * - Maintenance: only a policy fetched from the network this session. A
+ *   cached maintenance flag never blocks a cold start.
+ */
+import { createStore, delay, type Store } from "./store";
+import { isBelowMinimum } from "./version";
+import { toError, type UpdatesOnError, type UpdatesStorageLike } from "./modules";
+
+export type UpdatePlatform = "ios" | "android";
+
+export interface ReleaseNote {
+  /** The store version these notes describe, e.g. `"1.4.0"`. */
+  version: string;
+  title?: string;
+  body: string;
+}
+
+export interface UpdatePolicy {
+  /** The oldest store version still supported, per platform. Missing or malformed: no minimum. */
+  minimumVersion?: Partial<Record<UpdatePlatform, string>>;
+  /** Where "Update" goes (`https://apps.apple.com/…`, `itms-apps://…`, `market://…`, `https://play.google.com/…`). */
+  storeUrl?: Partial<Record<UpdatePlatform, string>>;
+  maintenance?: { active: boolean; message: string | null };
+  notes?: readonly ReleaseNote[];
+}
+
+/** Where the policy comes from. `load` throws (or rejects) when it can't answer; resolving `null` means "no policy". */
+export interface UpdatePolicySource {
+  load(): Promise<UpdatePolicy | null | undefined>;
+}
+
+/** A policy written in the app (or a test). */
+export function staticPolicySource(policy: UpdatePolicy): UpdatePolicySource {
+  return { load: async () => policy };
+}
+
+/** A Supabase client: anything with `from(table)` (a real `SupabaseClient` fits without a cast). */
+export interface PolicyClientLike {
+  from(table: string): unknown;
+}
+
+interface PolicyQuery {
+  select(columns: string): { eq(column: string, value: string): { maybeSingle(): PromiseLike<{ data: unknown; error: unknown }> } };
+}
+
+export interface SupabasePolicySourceOptions {
+  /** The `app_id` row to read. Default `"default"`. */
+  appId?: string;
+  /** Default `"app_release_policy"` (migration `0002_genesis_app_release_policy.sql` in `@marktiderman/genesis-supabase`). */
+  table?: string;
+}
+
+const COLUMNS = "min_version_ios,min_version_android,store_url_ios,store_url_android,maintenance,maintenance_message,notes";
+
+/**
+ * Reads one row of `public.app_release_policy` (readable by anon and
+ * authenticated, written only with the service role). No row is no policy.
+ */
+export function supabasePolicySource(client: PolicyClientLike, options: SupabasePolicySourceOptions = {}): UpdatePolicySource {
+  const { appId = "default", table = "app_release_policy" } = options;
+  return {
+    async load() {
+      const query = client.from(table) as PolicyQuery;
+      const { data, error } = await query.select(COLUMNS).eq("app_id", appId).maybeSingle();
+      if (error) throw toError(error instanceof Error ? error : (error as { message?: unknown }).message ?? error);
+      if (!data || typeof data !== "object") return {};
+      const row = data as Record<string, unknown>;
+      return {
+        minimumVersion: pick({ ios: row.min_version_ios, android: row.min_version_android }),
+        storeUrl: pick({ ios: row.store_url_ios, android: row.store_url_android }),
+        maintenance: { active: row.maintenance === true, message: typeof row.maintenance_message === "string" ? row.maintenance_message : null },
+        notes: Array.isArray(row.notes) ? (row.notes as ReleaseNote[]) : [],
+      };
+    },
+  };
+}
+
+function pick(values: Record<UpdatePlatform, unknown>): Partial<Record<UpdatePlatform, string>> {
+  const out: Partial<Record<UpdatePlatform, string>> = {};
+  for (const platform of ["ios", "android"] as const) {
+    const value = values[platform];
+    if (typeof value === "string" && value.trim() !== "") out[platform] = value.trim();
+  }
+  return out;
+}
+
+const STORE_URL = /^(https:\/\/|itms-apps:\/\/|market:\/\/)/i;
+
+/** Keeps only well-formed fields; throws when `raw` isn't an object at all (so the cache answers instead). */
+export function sanitizePolicy(raw: unknown): UpdatePolicy {
+  if (raw === null || raw === undefined) return {};
+  if (typeof raw !== "object" || Array.isArray(raw)) throw new Error("The release policy is not an object");
+  const value = raw as Record<string, unknown>;
+  const policy: UpdatePolicy = {};
+  const minimum = value.minimumVersion && typeof value.minimumVersion === "object" ? (value.minimumVersion as Record<UpdatePlatform, unknown>) : null;
+  if (minimum) policy.minimumVersion = pick(minimum);
+  const store = value.storeUrl && typeof value.storeUrl === "object" ? pick(value.storeUrl as Record<UpdatePlatform, unknown>) : null;
+  if (store) {
+    for (const platform of ["ios", "android"] as const) if (store[platform] && !STORE_URL.test(store[platform])) delete store[platform];
+    policy.storeUrl = store;
+  }
+  const maintenance = value.maintenance as { active?: unknown; message?: unknown } | null | undefined;
+  if (maintenance && typeof maintenance === "object") {
+    policy.maintenance = {
+      active: maintenance.active === true,
+      message: typeof maintenance.message === "string" && maintenance.message.trim() !== "" ? maintenance.message : null,
+    };
+  }
+  if (Array.isArray(value.notes)) {
+    policy.notes = value.notes.flatMap((note): ReleaseNote[] => {
+      if (!note || typeof note !== "object") return [];
+      const { version, title, body } = note as Record<string, unknown>;
+      if (typeof version !== "string" || typeof body !== "string") return [];
+      return [{ version: version.trim(), body, ...(typeof title === "string" ? { title } : {}) }];
+    });
+  }
+  return policy;
+}
+
+export type PolicyOrigin = "network" | "cache" | "none";
+
+export interface PolicyState {
+  /** `loading` until the first answer (or the timeout); then `ready`, with or without a policy. */
+  status: "loading" | "ready";
+  policy: UpdatePolicy | null;
+  /** `network`: fetched this session. `cache`: read from the phone. `none`: no answer yet (fail open). */
+  origin: PolicyOrigin;
+  /** When it was fetched, by the phone's clock (ms). */
+  fetchedAt: number | null;
+  /** The last failed fetch, if the most recent one failed. */
+  error: Error | null;
+  /** A fetch is in flight. */
+  refreshing: boolean;
+}
+
+export interface PolicyStoreOptions {
+  source: UpdatePolicySource;
+  storage?: UpdatesStorageLike;
+  /** Default `"genesis:updates:policy"`. */
+  cacheKey?: string;
+  /** The longest `load()` waits before carrying on without an answer. Default 3000 ms. */
+  timeoutMs?: number;
+  now?: () => number;
+  onError?: UpdatesOnError;
+}
+
+export interface PolicyStore extends Pick<Store<PolicyState>, "getState" | "subscribe"> {
+  /** The first load: the cache and the network together, for at most `timeoutMs`. Never rejects; runs once. */
+  load(): Promise<void>;
+  /** Fetch again (maintenance "Try again", the app coming to the front). Never rejects; resolves true on an answer. */
+  refresh(): Promise<boolean>;
+  /** `refresh()` unless one ran less than `minIntervalMs` ago. */
+  refreshIfDue(minIntervalMs: number): Promise<boolean>;
+}
+
+interface CacheEntry {
+  v: 1;
+  savedAt: number;
+  policy: UpdatePolicy;
+}
+
+export function createPolicyStore(options: PolicyStoreOptions): PolicyStore {
+  const { source, storage, cacheKey = "genesis:updates:policy", now = Date.now, onError } = options;
+  const timeoutMs = validTimeout(options.timeoutMs, 3000);
+  const store = createStore<PolicyState>({ status: "loading", policy: null, origin: "none", fetchedAt: null, error: null, refreshing: false });
+  let inflight: Promise<boolean> | null = null;
+  let firstLoad: Promise<void> | null = null;
+  let lastAttempt: number | null = null;
+  const report = (error: unknown, from: "policy" | "storage") => {
+    try {
+      onError?.(toError(error), from);
+    } catch {
+      // A failing reporter must not change the answer.
+    }
+  };
+
+  const fetchNetwork = (): Promise<boolean> => {
+    if (inflight) return inflight;
+    lastAttempt = now();
+    store.setState({ refreshing: true });
+    // eslint-disable-next-line prefer-const -- read in `finally`, after the assignment below
+    let run!: Promise<boolean>;
+    run = (async () => {
+      // Never settle synchronously: a source that throws before its first await must not leave a settled `inflight` behind.
+      await null;
+      try {
+        const policy = sanitizePolicy(await source.load());
+        const fetchedAt = now();
+        store.setState({ status: "ready", policy, origin: "network", fetchedAt, error: null });
+        if (storage) {
+          const entry: CacheEntry = { v: 1, savedAt: fetchedAt, policy };
+          Promise.resolve()
+            .then(() => storage.setItem(cacheKey, JSON.stringify(entry)))
+            .catch((error) => report(error, "storage"));
+        }
+        return true;
+      } catch (error) {
+        report(error, "policy");
+        // A network answer from earlier this session stays; the cache (if any) was already applied.
+        store.setState({ error: toError(error) });
+        return false;
+      } finally {
+        if (inflight === run) inflight = null;
+        store.setState({ refreshing: false });
+      }
+    })();
+    inflight = run;
+    return run;
+  };
+
+  const readCache = async () => {
+    if (!storage) return;
+    try {
+      const entry = parseCache(await storage.getItem(cacheKey));
+      if (entry && store.getState().origin !== "network") {
+        store.setState({ policy: entry.policy, origin: "cache", fetchedAt: entry.savedAt });
+      }
+    } catch (error) {
+      report(error, "storage");
+    }
+  };
+
+  return {
+    getState: store.getState,
+    subscribe: store.subscribe,
+    load() {
+      firstLoad ??= (async () => {
+        const cache = readCache();
+        const network = fetchNetwork();
+        const answered = network.then(async (ok) => {
+          if (!ok) await cache;
+        });
+        await Promise.race([answered, delay(timeoutMs)]);
+        store.setState({ status: "ready" });
+      })();
+      return firstLoad;
+    },
+    refresh: fetchNetwork,
+    refreshIfDue(minIntervalMs) {
+      const at = now();
+      // A clock that moved back makes the last attempt look in the future: refresh.
+      if (lastAttempt !== null && at >= lastAttempt && at - lastAttempt < minIntervalMs) return Promise.resolve(false);
+      return fetchNetwork();
+    },
+  };
+}
+
+/** A finite, non-negative timeout, or `fallback` (a NaN or Infinity would wait forever). */
+export function validTimeout(value: number | undefined, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+function parseCache(raw: string | null): CacheEntry | null {
+  if (!raw) return null;
+  try {
+    const entry = JSON.parse(raw) as Partial<CacheEntry>;
+    if (entry?.v !== 1 || typeof entry.savedAt !== "number" || !Number.isFinite(entry.savedAt)) return null;
+    return { v: 1, savedAt: entry.savedAt, policy: sanitizePolicy(entry.policy) };
+  } catch {
+    return null;
+  }
+}
+
+/** What the policy says this install must do. */
+export type UpdateVerdict =
+  | { kind: "ok" }
+  | { kind: "forceUpgrade"; minimumVersion: string; installedVersion: string; storeUrl: string }
+  | { kind: "maintenance"; message: string | null };
+
+export interface EvaluatePolicyOptions {
+  /** `Platform.OS`. Only `ios` and `android` can be forced to upgrade. */
+  platform: string;
+  /** The installed store version (`Application.nativeApplicationVersion`). `null`: never forced. */
+  installedVersion: string | null;
+  now: number;
+  /** How old a cached policy may be and still force an upgrade. Default 7 days. */
+  cacheMaxAgeMs?: number;
+}
+
+/** How far in the future a cache's time may be (clocks drift) before it isn't trusted. */
+export const CLOCK_SKEW_MS = 5 * 60_000;
+export const WEEK_MS = 7 * 24 * 60 * 60_000;
+
+/** Force upgrade first (the store is the way out), then maintenance, else ok. Fails open. */
+export function evaluatePolicy(state: PolicyState, options: EvaluatePolicyOptions): UpdateVerdict {
+  const { policy, origin, fetchedAt } = state;
+  if (!policy) return { kind: "ok" };
+  const { platform, installedVersion, now, cacheMaxAgeMs = WEEK_MS } = options;
+  const age = fetchedAt === null ? null : now - fetchedAt;
+  const trusted = origin === "network" || (origin === "cache" && age !== null && age >= -CLOCK_SKEW_MS && age <= cacheMaxAgeMs);
+  if (trusted && (platform === "ios" || platform === "android")) {
+    const minimum = policy.minimumVersion?.[platform];
+    const storeUrl = policy.storeUrl?.[platform];
+    // Without a store link there is no way out of the screen, so no store link means no force upgrade.
+    if (minimum && storeUrl && installedVersion && isBelowMinimum(installedVersion, minimum)) {
+      return { kind: "forceUpgrade", minimumVersion: minimum.trim(), installedVersion, storeUrl };
+    }
+  }
+  if (origin === "network" && policy.maintenance?.active === true) {
+    return { kind: "maintenance", message: policy.maintenance.message };
+  }
+  return { kind: "ok" };
+}