@hot-updater/console 1.0.0-rc.2 → 1.0.0-rc.20

package/src/lib/console-access.ts

@@ -0,0 +1,20 @@
+import { createMiddleware } from "@tanstack/react-start";
+
+/**
+ * Refuses a caller the console does not authorize before a server function
+ * reads its input. TanStack Start runs a function's middleware before the
+ * function's own validator, so an anonymous or unlisted caller gets the access
+ * check's 401 or 403, never an input error, whatever it sends. Every server
+ * function except the sign-in reads in `auth-rpc.ts` uses it, and
+ * `console-access.spec.ts` checks that.
+ */
+export const consoleAccess = createMiddleware({ type: "function" }).server(
+  async ({ next }) => {
+    const [{ getRequest }, { requireConsoleAccess }] = await Promise.all([
+      import("@tanstack/react-start/server"),
+      import("./server/auth.server"),
+    ]);
+    await requireConsoleAccess(getRequest());
+    return next();
+  },
+);

package/src/lib/console-features-api.ts

@@ -0,0 +1,68 @@
+import {
+  type QueryClient,
+  queryOptions,
+  useQuery,
+} from "@tanstack/react-query";
+import { notFound } from "@tanstack/react-router";
+
+import { type ConsoleFeature, consoleFeatures } from "./console-features";
+import { getConsoleFeaturesRpc } from "./console-features-rpc";
+
+export const consoleFeaturesQueryKey = ["console", "features"] as const;
+
+export const consoleFeaturesQueryOptions = () =>
+  queryOptions({
+    queryKey: consoleFeaturesQueryKey,
+    queryFn: () => getConsoleFeaturesRpc(),
+    // A server's plugins change only when it restarts: one read serves a visit.
+    staleTime: Infinity,
+  });
+
+/** The features the console serves; the authorized layout loads them first. */
+export const useConsoleFeatures = () => useQuery(consoleFeaturesQueryOptions());
+
+/** Whether `feature` is on; false until the features load. */
+export const useConsoleFeature = (feature: ConsoleFeature): boolean =>
+  useConsoleFeatures().data?.features[feature] === true;
+
+/** A feature route's not-found data: the feature its guard found off. */
+type ConsoleFeatureNotFoundData = { readonly feature: ConsoleFeature };
+
+/** The feature in a route's not-found data, when a feature guard threw it. */
+export const notFoundFeature = (data: unknown): ConsoleFeature | undefined => {
+  const feature =
+    typeof data === "object" && data !== null
+      ? Reflect.get(data, "feature")
+      : undefined;
+  return typeof feature === "string" && Object.hasOwn(consoleFeatures, feature)
+    ? (feature as ConsoleFeature)
+    : undefined;
+};
+
+/**
+ * A feature route's `beforeLoad`: not found, naming the feature, when the
+ * console does not serve it. A failed features read lets the route load: the
+ * root layout answers a visitor it does not authorize, and the route's own
+ * reads report any other failure. The failure leaves the cache, which a
+ * server render sends to the browser: a refused visitor's failure is the 401
+ * or 403 Response, which the render cannot serialize.
+ */
+export const requireConsoleFeature = async (
+  queryClient: QueryClient,
+  feature: ConsoleFeature,
+): Promise<void> => {
+  const featureSet = await queryClient
+    .ensureQueryData(consoleFeaturesQueryOptions())
+    .catch(() => {
+      queryClient.removeQueries({
+        queryKey: consoleFeaturesQueryKey,
+        exact: true,
+      });
+      return undefined;
+    });
+  if (featureSet !== undefined && !featureSet.features[feature]) {
+    throw notFound({
+      data: { feature } satisfies ConsoleFeatureNotFoundData,
+    });
+  }
+};

package/src/lib/console-features-rpc.ts

@@ -0,0 +1,13 @@
+import { createServerFn } from "@tanstack/react-start";
+
+import { consoleAccess } from "./console-access";
+import type { ConsoleFeatureSet } from "./console-features";
+
+/** The features this console serves, for navigation and route guards. */
+export const getConsoleFeaturesRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .handler(async (): Promise<ConsoleFeatureSet> => {
+    const { prepareConfig } = await import("./server/config.server");
+    const { runtime } = await prepareConfig();
+    return { features: await runtime.features(), remote: runtime.remote };
+  });

package/src/lib/console-features.ts

@@ -0,0 +1,91 @@
+/**
+ * The console's features and the server plugin each one needs. The server is
+ * the source of truth: the console serves a feature only when the server runs
+ * its plugin, and against a self-hosted server (`standaloneRepository`) only
+ * the features its admin API serves (`remote`); the rest read the database.
+ * Navigation, route guards, and server functions all read this registry. Its
+ * other halves, keyed by the same features, hold what serves each feature on
+ * the server (`server/console-feature-apis.ts`) and what each adds to pages
+ * (`components/features/console-feature-ui.tsx`).
+ */
+export const consoleFeatures = {
+  /** Event history and installation lookups, which the admin API serves too. */
+  insights: { plugin: "insights", label: "Insights", remote: true },
+  /** App usage, distribution, and release activity, read from the database. */
+  insightsAnalytics: { plugin: "insights", label: "Insights", remote: false },
+  /** API key management: `apiKeys()` mounts no admin routes to manage them. */
+  apiKeys: { plugin: "apiKeys", label: "API keys", remote: false },
+} as const satisfies Readonly<
+  Record<
+    string,
+    {
+      readonly plugin: string;
+      /** How navigation and the not-installed page name the feature. */
+      readonly label: string;
+      readonly remote: boolean;
+    }
+  >
+>;
+
+export type ConsoleFeature = keyof typeof consoleFeatures;
+
+/** Whether each feature is on. */
+export type ConsoleFeatures = Readonly<Record<ConsoleFeature, boolean>>;
+
+/** What the console serves, as its client reads it. */
+export type ConsoleFeatureSet = {
+  readonly features: ConsoleFeatures;
+  /** Whether the console reaches a self-hosted server through its admin API. */
+  readonly remote: boolean;
+};
+
+const featureIds = Object.keys(consoleFeatures) as ConsoleFeature[];
+
+/** The features on for the plugins a server runs, from where the console reads them. */
+export const resolveConsoleFeatures = (
+  plugins: readonly string[],
+  { remote }: { readonly remote: boolean },
+): ConsoleFeatures => {
+  const installed = new Set(plugins);
+  return Object.fromEntries(
+    featureIds.map((feature) => {
+      const { plugin, remote: servedRemotely } = consoleFeatures[feature];
+      return [feature, installed.has(plugin) && (servedRemotely || !remote)];
+    }),
+  ) as Record<ConsoleFeature, boolean>;
+};
+
+/** Why a feature is off: its plugin is missing, or it reads a database the console does not open. */
+export const unavailableReason = (
+  feature: ConsoleFeature,
+  { remote }: { readonly remote: boolean },
+): "plugin" | "remote" =>
+  remote && !consoleFeatures[feature].remote ? "remote" : "plugin";
+
+/**
+ * A server function refused a feature the console does not serve: the
+ * features' 404. The client recognizes it by `name`, which survives
+ * serialization where the class does not.
+ */
+export class ConsoleFeatureUnavailableError extends Error {
+  override readonly name = "ConsoleFeatureUnavailableError";
+  readonly status = 404;
+
+  constructor(
+    readonly feature: ConsoleFeature,
+    { remote }: { readonly remote: boolean },
+  ) {
+    super(
+      unavailableReason(feature, { remote }) === "remote"
+        ? "The console reads this from the database, and it reaches a self-hosted server through its admin API instead."
+        : `The server runs without the ${consoleFeatures[feature].plugin}() plugin.`,
+    );
+  }
+}
+
+export const isConsoleFeatureUnavailableError = (
+  error: unknown,
+): error is Error & { readonly feature: ConsoleFeature } =>
+  error instanceof Error &&
+  error.name === "ConsoleFeatureUnavailableError" &&
+  featureIds.includes(Reflect.get(error, "feature") as ConsoleFeature);

package/src/lib/insights-api.ts

@@ -1,9 +1,19 @@
-import type { InsightsEventPageInput } from "@hot-updater/server";
+import type { InsightsEventPageInput } from "@hot-updater/server/plugins/insights";
 import { useQuery } from "@tanstack/react-query";
 
+import {
+  readUpdateFailuresInput,
+  type UpdateFailuresInput,
+} from "./insights-failures";
+import { getUpdateFailuresRpc } from "./insights-failures-rpc";
+import {
+  DEFAULT_INSIGHTS_RETENTION,
+  type InsightsRetentionDays,
+} from "./insights-retention";
 import {
   findInsightsInstallationsRpc,
   getInsightsInstallationRpc,
+  getInsightsRetentionRpc,
   getReportingInstallationsRpc,
   listInsightsEventsRpc,
   listInsightsInstallationEventsRpc,
@@ -98,3 +108,29 @@ export const useInsightsInstallationEventsQuery = (
     refetchOnWindowFocus: true,
     staleTime: STALE_TIME_MS,
   });
+
+/** A release's or a channel's update failures; lifetime for a release without a window. */
+export const useUpdateFailuresQuery = (
+  input: UpdateFailuresInput,
+  enabled = true,
+) =>
+  useQuery({
+    queryKey: ["insights", "update-failures", input],
+    queryFn: () =>
+      getUpdateFailuresRpc({ data: readUpdateFailuresInput(input) }),
+    enabled,
+    refetchOnWindowFocus: true,
+    staleTime: STALE_TIME_MS,
+  });
+
+/**
+ * How long the server keeps Insights rows; the defaults until it answers, or
+ * when it does not report them.
+ */
+export const useInsightsRetention = (): InsightsRetentionDays =>
+  useQuery({
+    queryKey: ["insights", "retention"],
+    queryFn: () => getInsightsRetentionRpc(),
+    // A server's periods change only when it restarts.
+    staleTime: Infinity,
+  }).data ?? DEFAULT_INSIGHTS_RETENTION;

package/src/lib/insights-failures-rpc.ts

@@ -0,0 +1,21 @@
+import { createServerFn } from "@tanstack/react-start";
+
+import { consoleAccess } from "./console-access";
+import { readUpdateFailuresInput } from "./insights-failures";
+
+export const getUpdateFailuresRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .validator(readUpdateFailuresInput)
+  .handler(async ({ data }) => {
+    const [{ prepareConfig }, { getUpdateFailuresReport }, { requireFeature }] =
+      await Promise.all([
+        import("./server/config.server"),
+        import("./server/updateFailures"),
+        import("./server/runtime.server"),
+      ]);
+    const { runtime } = await prepareConfig();
+    return getUpdateFailuresReport(
+      await requireFeature(runtime, "insights"),
+      data,
+    );
+  });

package/src/lib/insights-failures.ts

@@ -0,0 +1,129 @@
+import type {
+  InsightsFailureBreakdown,
+  InsightsUpdateFailures,
+} from "@hot-updater/server/plugins/insights";
+
+import { recoveryWindows } from "./insights-recovery";
+import type { InsightsWindow } from "./insights-rpc";
+import type { InsightsEventRow } from "./insights-view";
+
+export type { InsightsFailureBreakdown };
+
+export type UpdateFailuresInput = {
+  readonly platform: "ios" | "android";
+  readonly channel: string;
+  /** A release's failures; the channel's without it. */
+  readonly releaseId?: string;
+  /** The period that ends with the current hour; a release's since its first report without it. */
+  readonly window?: InsightsWindow;
+};
+
+export type UpdateFailuresReport = InsightsUpdateFailures & {
+  /** Where the period starts, or null since the release's first report. */
+  readonly startMs: number | null;
+  readonly endMs: number;
+};
+
+export function readUpdateFailuresInput(
+  input: UpdateFailuresInput,
+): UpdateFailuresInput {
+  if (
+    !input ||
+    (input.platform !== "ios" && input.platform !== "android") ||
+    typeof input.channel !== "string" ||
+    !input.channel.trim() ||
+    input.channel.length > 1_024 ||
+    (input.releaseId !== undefined &&
+      (typeof input.releaseId !== "string" ||
+        !input.releaseId.trim() ||
+        input.releaseId.length > 36)) ||
+    (input.window === undefined
+      ? input.releaseId === undefined
+      : !Object.hasOwn(recoveryWindows, input.window))
+  ) {
+    throw new Error("Choose a platform, channel, and time window.");
+  }
+  return input;
+}
+
+/**
+ * The failure rate of update attempts: failed download and install reports,
+ * over those plus download reports. Null without either.
+ */
+export const failureRate = ({
+  failedUpdates,
+  downloads,
+}: Pick<InsightsUpdateFailures, "failedUpdates" | "downloads">):
+  | number
+  | null =>
+  failedUpdates + downloads === 0
+    ? null
+    : failedUpdates / (failedUpdates + downloads);
+
+/** Of the downloads that tried a patch, the share that fell back to files or the archive. */
+export const patchFallbackRate = ({
+  patchDownloads,
+  patchFallbacks,
+}: Pick<InsightsUpdateFailures, "patchDownloads" | "patchFallbacks">):
+  | number
+  | null =>
+  patchDownloads + patchFallbacks === 0
+    ? null
+    : patchFallbacks / (patchDownloads + patchFallbacks);
+
+/** Installations whose update check failed, over the active ones; estimates, so at most 100%. */
+export const checkFailureRate = ({
+  failedInstallations,
+  activeInstallations,
+}: NonNullable<InsightsUpdateFailures["checks"]>): number | null =>
+  activeInstallations === 0
+    ? null
+    : Math.min(1, failedInstallations / activeInstallations);
+
+export const formatRate = (rate: number | null): string =>
+  rate === null ? "—" : `${(rate * 100).toFixed(2)}%`;
+
+const STAGES: Readonly<Record<string, string>> = {
+  check: "Update check",
+  download: "Download",
+  install: "Install",
+};
+
+const REASONS: Readonly<Record<string, string>> = {
+  network: "Network",
+  http: "HTTP error",
+  invalid_response: "Invalid response",
+  hash_mismatch: "Hash mismatch",
+  signature: "Signature",
+  patch: "Patch",
+  extract: "Extract",
+  storage: "Storage",
+};
+
+export const failureStageLabel = (stage: string): string =>
+  STAGES[stage] ?? "Unknown stage";
+
+export const failureReasonLabel = (reason: string): string =>
+  REASONS[reason] ?? "Unknown reason";
+
+/** What else the client knew: its resource, HTTP status, origin code, and transport. */
+export const failureDetailParts = (detail: {
+  readonly resource?: string | null;
+  readonly httpStatus?: number | null;
+  readonly originCode?: string | null;
+  readonly transport?: string | null;
+}): string[] => [
+  ...(detail.httpStatus == null ? [] : [`HTTP ${detail.httpStatus}`]),
+  ...(detail.originCode == null ? [] : [detail.originCode]),
+  ...(detail.transport == null ? [] : [detail.transport]),
+  ...(detail.resource == null ? [] : [detail.resource]),
+];
+
+/** An update failure as one line: where, why, and what else the client knew. */
+export const describeFailure = (
+  failure: NonNullable<InsightsEventRow["failure"]>,
+): string =>
+  [
+    `${failureStageLabel(failure.stage)} failed: ${failureReasonLabel(failure.reason)}`,
+    ...failureDetailParts(failure),
+  ].join(" · ");

package/src/lib/insights-recovery-rpc.ts

@@ -0,0 +1,51 @@
+import { createServerFn } from "@tanstack/react-start";
+
+import type { BundleActivityInput } from "./bundle-activity";
+import { consoleAccess } from "./console-access";
+import { readRecoveryInput } from "./insights-recovery";
+
+export function readBundleActivityInput(
+  inputs: readonly BundleActivityInput[],
+) {
+  if (!Array.isArray(inputs) || inputs.length > 20)
+    throw new Error("Choose up to 20 bundles.");
+  return inputs.map((input) => {
+    readRecoveryInput({ ...input, window: "30d" });
+    if (!input.releaseId) throw new Error("Choose a bundle ID.");
+    return input;
+  });
+}
+
+export const getBundleActivityRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .validator(readBundleActivityInput)
+  .handler(async ({ data }) => {
+    const [{ prepareConfig }, { getBundleActivity }, { requireFeature }] =
+      await Promise.all([
+        import("./server/config.server"),
+        import("./server/bundleActivity"),
+        import("./server/runtime.server"),
+      ]);
+    const { runtime } = await prepareConfig();
+    return getBundleActivity(
+      await requireFeature(runtime, "insightsAnalytics"),
+      data,
+    );
+  });
+
+export const getRecoveryReportRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .validator(readRecoveryInput)
+  .handler(async ({ data }) => {
+    const [{ prepareConfig }, { getRecoveryReport }, { requireFeature }] =
+      await Promise.all([
+        import("./server/config.server"),
+        import("./server/insightsRecovery"),
+        import("./server/runtime.server"),
+      ]);
+    const { runtime } = await prepareConfig();
+    return getRecoveryReport(
+      await requireFeature(runtime, "insightsAnalytics"),
+      data,
+    );
+  });

package/src/lib/insights-recovery.ts

@@ -0,0 +1,68 @@
+import type { InsightsCoverage } from "@hot-updater/server/plugins/insights";
+
+import type { InsightsWindow } from "./insights-rpc";
+
+export type RecoveryInput = {
+  readonly platform: "ios" | "android";
+  readonly channel: string;
+  readonly window: InsightsWindow;
+  readonly releaseId?: string;
+};
+
+export type RecoveryReport = {
+  readonly downloads: number;
+  /**
+   * Distinct installations that reported in the scope and period, or that
+   * launched the release; estimated.
+   */
+  readonly activeInstallations: number;
+  /**
+   * Installation-days: each installation once for each UTC day it launched,
+   * and once more on a day an update applied or recovered.
+   */
+  readonly activeDays: number;
+  readonly failedLaunches: number;
+  readonly points: readonly {
+    readonly startMs: number;
+    /** That UTC day's daily active installations. */
+    readonly dailyActiveInstallations: number;
+    readonly failedLaunches: number;
+  }[];
+  readonly startMs: number;
+  readonly endMs: number;
+  readonly measuredAtMs: number;
+  readonly coverage: InsightsCoverage;
+};
+
+export const recoveryWindows = {
+  "24h": { durationMs: 86_400_000, intervalMs: 3_600_000 },
+  "7d": { durationMs: 7 * 86_400_000, intervalMs: 6 * 3_600_000 },
+  "30d": { durationMs: 30 * 86_400_000, intervalMs: 86_400_000 },
+} as const;
+
+/**
+ * Where a period ends: the end of the current UTC hour, as the server's
+ * reporting overview ends. The counters keep whole hours, so this is the
+ * latest end that still counts a report received just now; every Insights
+ * card ends here, so their numbers cover the same hours.
+ */
+export const insightsPeriodEnd = (now: number): number =>
+  Math.ceil(now / 3_600_000) * 3_600_000;
+
+export function readRecoveryInput(input: RecoveryInput): RecoveryInput {
+  if (
+    !input ||
+    (input.platform !== "ios" && input.platform !== "android") ||
+    typeof input.channel !== "string" ||
+    !input.channel.trim() ||
+    input.channel.length > 1_024 ||
+    !Object.hasOwn(recoveryWindows, input.window) ||
+    (input.releaseId !== undefined &&
+      (typeof input.releaseId !== "string" ||
+        !input.releaseId.trim() ||
+        input.releaseId.length > 1_024))
+  ) {
+    throw new Error("Choose a platform, channel, and time window.");
+  }
+  return input;
+}

package/src/lib/insights-retention.ts

@@ -0,0 +1,21 @@
+/** How long the server's `insights()` keeps rows, in days. */
+export interface InsightsRetentionDays {
+  /** Raw events and hourly totals. */
+  readonly rawDays: number;
+  /** Daily totals, distributions, and each installation's latest report. */
+  readonly dailyDays: number;
+}
+
+/** `insights()`'s defaults, for a server that does not report its periods. */
+export const DEFAULT_INSIGHTS_RETENTION: InsightsRetentionDays = {
+  rawDays: 90,
+  dailyDays: 400,
+};
+
+export const formatDays = (days: number): string =>
+  `${days.toLocaleString("en")} ${days === 1 ? "day" : "days"}`;
+
+/** Whether daily totals cover App usage's 12-month period: 52 weeks. */
+export const keepsTwelveMonths = ({
+  dailyDays,
+}: InsightsRetentionDays): boolean => dailyDays >= 364;

package/src/lib/insights-rpc.ts

@@ -1,13 +1,13 @@
 import type {
-  ReportingOverview,
   InsightsScope,
+  ReportingOverview,
   InsightsEventPageInput,
   InsightsInstallationEventPageInput,
   ActiveInstallationWindow,
-  InsightsProvider,
-} from "@hot-updater/server";
+} from "@hot-updater/server/plugins/insights";
 import { createServerFn } from "@tanstack/react-start";
 
+import { consoleAccess } from "./console-access";
 import type {
   InsightsInstallationViewRow,
   InsightsViewPage,
@@ -30,10 +30,14 @@ type InstallationsPageInput = {
   readonly limit: number;
 };
 
-const runtime = async (): Promise<InsightsProvider> => {
-  const { prepareConfig } = await import("./server/config.server");
-  const { hotUpdater } = await prepareConfig();
-  return hotUpdater;
+/** The Insights reads, once the console's access check and the feature guard pass. */
+const insightsReads = async () => {
+  const [{ prepareConfig }, { requireFeature }] = await Promise.all([
+    import("./server/config.server"),
+    import("./server/runtime.server"),
+  ]);
+  const { runtime } = await prepareConfig();
+  return requireFeature(runtime, "insights");
 };
 
 const readOverview = (input: InsightsOverviewInput) => input;
@@ -44,27 +48,41 @@ const readInstallationPage = (input: InstallationsPageInput) => input;
 const readInstallId = (input: { readonly installId: string }) => input;
 
 export const getReportingInstallationsRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
   .validator(readOverview)
-  .handler(async ({ data }) => (await runtime()).getReportingOverview(data));
+  .handler(async ({ data }) =>
+    (await insightsReads()).getReportingOverview(data),
+  );
 
 export const listInsightsEventsRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
   .validator(readEventsPage)
-  .handler(async ({ data }) => (await runtime()).listEvents(data));
+  .handler(async ({ data }) => (await insightsReads()).listEvents(data));
 
 export const listInsightsInstallationEventsRpc = createServerFn({
   method: "GET",
 })
+  .middleware([consoleAccess])
   .validator(readInstallationEventsPage)
-  .handler(async ({ data }) => (await runtime()).listInstallationEvents(data));
+  .handler(async ({ data }) =>
+    (await insightsReads()).listInstallationEvents(data),
+  );
 
 export const getInsightsInstallationRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
   .validator(readInstallId)
-  .handler(async ({ data }) => (await runtime()).getInstallation(data));
+  .handler(async ({ data }) => (await insightsReads()).getInstallation(data));
+
+/** How long the server's `insights()` keeps rows. */
+export const getInsightsRetentionRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
+  .handler(async () => (await insightsReads()).getRetention());
 
 export const findInsightsInstallationsRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
   .validator(readInstallationPage)
   .handler(async ({ data }) => {
-    const insights = await runtime();
+    const insights = await insightsReads();
     const install = data.cursor
       ? null
       : await insights.getInstallation({ installId: data.identity });

package/src/lib/insights-search.ts

@@ -0,0 +1,58 @@
+import type { InsightsWindow } from "./insights-api";
+import type { AppUsageScope, UsageWindow } from "./insights-usage";
+
+const readText = (value: unknown) =>
+  typeof value === "string" && value.trim().length > 0 && value.length <= 1024
+    ? value
+    : undefined;
+const readWindow = (value: unknown): InsightsWindow | undefined =>
+  value === "24h" || value === "7d" || value === "30d" ? value : undefined;
+const readUsageWindow = (value: unknown): UsageWindow | undefined =>
+  value === "12m" ? value : readWindow(value);
+
+export type InsightsSearch = {
+  platform?: AppUsageScope["platform"];
+  channel?: string;
+  appVersion?: string;
+  window?: UsageWindow;
+  bundleWindow?: InsightsWindow;
+  healthPlatform?: "ios" | "android";
+  healthChannel?: string;
+  releaseId?: string;
+};
+
+export function validateInsightsSearch(
+  search: Record<string, unknown>,
+): InsightsSearch {
+  return {
+    platform:
+      search.platform === "all" ||
+      search.platform === "ios" ||
+      search.platform === "android"
+        ? search.platform
+        : undefined,
+    channel: readText(search.channel),
+    appVersion: readText(search.appVersion),
+    window: readUsageWindow(search.window),
+    bundleWindow: readWindow(search.bundleWindow),
+    healthPlatform:
+      search.healthPlatform === "ios" || search.healthPlatform === "android"
+        ? search.healthPlatform
+        : undefined,
+    healthChannel: readText(search.healthChannel),
+    releaseId: readText(search.releaseId),
+  };
+}
+
+export function validateDistributionSearch(search: Record<string, unknown>) {
+  return {
+    ...validateInsightsSearch(search),
+    version: readText(search.version),
+    page:
+      typeof search.page === "number" &&
+      Number.isSafeInteger(search.page) &&
+      search.page > 0
+        ? search.page
+        : undefined,
+  };
+}