@hot-updater/console 1.0.0-rc.9 → 1.0.0

package/src/lib/insights-failures.ts

@@ -0,0 +1,130 @@
+import type {
+  InsightsFailureBreakdown,
+  InsightsUpdateFailures,
+} from "@hot-updater/server/plugins";
+
+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;
+  readonly previous?: {
+    readonly attemptRate: number | null;
+    readonly checkRate: number | null;
+    readonly complete: boolean;
+  };
+};
+
+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);
+
+/** 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",
+  unknown: "No reason reported",
+};
+
+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 => {
+  const message =
+    failure.errorMessage ||
+    (failure.reason === "unknown"
+      ? "The client did not report a detailed cause"
+      : failureReasonLabel(failure.reason));
+  return [
+    `${failureStageLabel(failure.stage)} failed: ${message}`,
+    ...failureDetailParts(failure),
+  ].join(" · ");
+};

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

@@ -1,6 +1,7 @@
 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(
@@ -16,23 +17,18 @@ export function readBundleActivityInput(
 }
 
 export const getBundleActivityRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
   .validator(readBundleActivityInput)
   .handler(async ({ data }) => {
-    const [{ prepareConfig }, { getBundleActivity }] = await Promise.all([
-      import("./server/config.server"),
-      import("./server/bundleActivity"),
-    ]);
-    const { config } = await prepareConfig();
-    return getBundleActivity(config.database.models.insights, data);
-  });
-
-export const getRecoveryReportRpc = createServerFn({ method: "GET" })
-  .validator(readRecoveryInput)
-  .handler(async ({ data }) => {
-    const [{ prepareConfig }, { getRecoveryReport }] = await Promise.all([
-      import("./server/config.server"),
-      import("./server/insightsRecovery"),
-    ]);
-    const { config } = await prepareConfig();
-    return getRecoveryReport(config.database.models.insights, 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,
+    );
   });

package/src/lib/insights-recovery.ts

@@ -1,60 +1,36 @@
 import type { InsightsWindow } from "./insights-rpc";
 
+/** Release health's scope: its channel, platform, period, and focused release. */
 export type RecoveryInput = {
-  readonly platform: "all" | "ios" | "android";
+  readonly platform: "ios" | "android";
   readonly channel: string;
-  readonly appVersion?: string;
   readonly window: InsightsWindow;
   readonly releaseId?: string;
 };
 
-export type RecoveryPoint = {
-  readonly startMs: number;
-  readonly active: number | null;
-  readonly recoveredInstallations: number;
-  readonly applied: number;
-  readonly recovered: number;
-  readonly rate: number | null;
-  readonly spike: boolean;
-};
-
-export type RecoverySeries = {
-  readonly releaseId: string;
-  readonly firstAppliedAtMs: number | null;
-  readonly activeInstallations: number;
-  readonly recoveredInstallations: number;
-  readonly points: readonly RecoveryPoint[];
-};
-
-export type RecoveryReport = {
-  readonly sinceMs: number;
-  readonly beforeReceivedAtMs: number;
-  readonly intervalMs: number;
-  readonly truncated: boolean;
-  readonly unattributedInstallations: number;
-  readonly series: readonly RecoverySeries[];
-};
-
 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 !== "all" &&
-      input.platform !== "ios" &&
-      input.platform !== "android") ||
+    (input.platform !== "ios" && input.platform !== "android") ||
     typeof input.channel !== "string" ||
     !input.channel.trim() ||
     input.channel.length > 1_024 ||
     !Object.hasOwn(recoveryWindows, input.window) ||
-    (input.appVersion !== undefined &&
-      (typeof input.appVersion !== "string" ||
-        !input.appVersion.trim() ||
-        input.appVersion.length > 1_024)) ||
     (input.releaseId !== undefined &&
       (typeof input.releaseId !== "string" ||
         !input.releaseId.trim() ||

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";
 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

@@ -1,5 +1,8 @@
+import { extractTimestampFromUUIDv7 } from "@hot-updater/plugin-core";
+import { isUUIDv7 } from "@hot-updater/protocol";
+
 import type { InsightsWindow } from "./insights-api";
-import type { RecoveryInput } from "./insights-recovery";
+import type { AppUsageScope, UsageWindow } from "./insights-usage";
 
 const readText = (value: unknown) =>
   typeof value === "string" && value.trim().length > 0 && value.length <= 1024
@@ -7,13 +10,28 @@ const readText = (value: unknown) =>
     : undefined;
 const readWindow = (value: unknown): InsightsWindow | undefined =>
   value === "24h" || value === "7d" || value === "30d" ? value : undefined;
+/** Release health's chart: whether bundles are launched, or crash. */
+export type HealthChart = "adoption" | "crashes";
+const readHealthChart = (value: unknown): HealthChart | undefined =>
+  value === "adoption" || value === "crashes" ? value : undefined;
+const readUsageWindow = (value: unknown): UsageWindow | undefined =>
+  value === "12m" ? value : readWindow(value);
 
 export type InsightsSearch = {
-  platform?: RecoveryInput["platform"];
+  platform?: AppUsageScope["platform"];
   channel?: string;
   appVersion?: string;
-  window?: InsightsWindow;
+  window?: UsageWindow;
   bundleWindow?: InsightsWindow;
+  healthPlatform?: "ios" | "android";
+  healthChannel?: string;
+  releaseId?: string;
+  healthChart?: HealthChart;
+  /**
+   * Release health's compared bundles, comma-separated release IDs; omitted,
+   * the focused release and the one before it, or the newest two.
+   */
+  bundles?: string;
 };
 
 export function validateInsightsSearch(
@@ -28,8 +46,16 @@ export function validateInsightsSearch(
         : undefined,
     channel: readText(search.channel),
     appVersion: readText(search.appVersion),
-    window: readWindow(search.window),
+    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),
+    healthChart: readHealthChart(search.healthChart),
+    bundles: readText(search.bundles),
   };
 }
 
@@ -45,3 +71,23 @@ export function validateDistributionSearch(search: Record<string, unknown>) {
         : undefined,
   };
 }
+
+/**
+ * The shortest Release health period that still covers a release's first
+ * hours: 24h within a day of its deployment, 7d within a week, else 30d.
+ */
+export function adoptionWindow(releaseId: string, now = Date.now()) {
+  if (!isUUIDv7(releaseId)) return "7d" as const;
+  const age = now - extractTimestampFromUUIDv7(releaseId);
+  return age <= 86_400_000
+    ? ("24h" as const)
+    : age <= 7 * 86_400_000
+      ? ("7d" as const)
+      : ("30d" as const);
+}
+
+/** Release health's compared bundles from the `bundles` search value. */
+export const comparedBundleIds = (value: string | undefined) =>
+  value === undefined
+    ? undefined
+    : [...new Set(value.split(",").filter((id) => id.length > 0))];

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

@@ -1,11 +1,12 @@
 import { createServerFn } from "@tanstack/react-start";
 
-import { readRecoveryInput } from "./insights-recovery";
-import type { AppUsageInput } from "./insights-usage";
+import { consoleAccess } from "./console-access";
+import { readAppUsageInput, type AppUsageInput } from "./insights-usage";
 
 export const getAppUsageReportRpc = createServerFn({ method: "GET" })
+  .middleware([consoleAccess])
   .validator((input: AppUsageInput) => {
-    readRecoveryInput(input);
+    readAppUsageInput(input);
     return {
       platform: input.platform,
       channel: input.channel,
@@ -14,10 +15,15 @@ export const getAppUsageReportRpc = createServerFn({ method: "GET" })
     };
   })
   .handler(async ({ data }) => {
-    const [{ prepareConfig }, { getAppUsageReport }] = await Promise.all([
-      import("./server/config.server"),
-      import("./server/insightsUsage"),
-    ]);
-    const { config } = await prepareConfig();
-    return getAppUsageReport(config.database.models.insights, data);
+    const [{ prepareConfig }, { getAppUsageReport }, { requireFeature }] =
+      await Promise.all([
+        import("./server/config.server"),
+        import("./server/insightsUsage"),
+        import("./server/runtime.server"),
+      ]);
+    const { runtime } = await prepareConfig();
+    return getAppUsageReport(
+      await requireFeature(runtime, "insightsAnalytics"),
+      data,
+    );
   });

package/src/lib/insights-usage.ts

@@ -1,6 +1,9 @@
-import type { RecoveryInput } from "./insights-recovery";
-
-export type AppUsageInput = Omit<RecoveryInput, "releaseId">;
+export type AppUsageInput = {
+  readonly platform: "all" | "ios" | "android";
+  readonly channel: string;
+  readonly appVersion?: string;
+  readonly window: UsageWindow;
+};
 export type AppUsageScope = Omit<AppUsageInput, "window">;
 
 export type UsageDistribution = {
@@ -12,6 +15,8 @@ export type BundleDistribution = {
   readonly appVersion: string;
   readonly platform: "ios" | "android";
   readonly releaseId: string | null;
+  /** The native build's built-in bundle, when the installations run it. */
+  readonly builtinBundleId: string | null;
   readonly installations: number;
 };
 
@@ -19,6 +24,12 @@ export type AppUsageReport = {
   readonly bundleDistribution: readonly BundleDistribution[];
   readonly activeInstallations: number;
   readonly sinceMs: number;
+  /**
+   * Where the distribution starts: the start of the UTC day that contains the
+   * period's start. Latest reports are counted by UTC day, so the
+   * distribution covers every UTC day the period touches.
+   */
+  readonly distributionSinceMs: number;
   readonly beforeReceivedAtMs: number;
   readonly intervalMs: number;
   readonly truncated: boolean;
@@ -35,4 +46,31 @@ export const usageMetrics = {
   "24h": { label: "DAU", period: "24 hours", interval: "hour" },
   "7d": { label: "WAU", period: "7 days", interval: "6 hours" },
   "30d": { label: "MAU", period: "30 days", interval: "day" },
+  "12m": { label: "YAU", period: "12 months", interval: "week" },
 } as const;
+
+/**
+ * An App usage period. Hourly counts are kept 90 days, so the 12-month
+ * period counts whole UTC days, from the daily counts kept 13 months.
+ */
+export type UsageWindow = keyof typeof usageMetrics;
+
+export function readAppUsageInput(input: AppUsageInput): AppUsageInput {
+  if (
+    !input ||
+    (input.platform !== "all" &&
+      input.platform !== "ios" &&
+      input.platform !== "android") ||
+    typeof input.channel !== "string" ||
+    !input.channel.trim() ||
+    input.channel.length > 1_024 ||
+    !Object.hasOwn(usageMetrics, input.window) ||
+    (input.appVersion !== undefined &&
+      (typeof input.appVersion !== "string" ||
+        !input.appVersion.trim() ||
+        input.appVersion.length > 1_024))
+  ) {
+    throw new Error("Choose App usage filters and a time window.");
+  }
+  return input;
+}

package/src/lib/insights-view.ts

@@ -1,4 +1,7 @@
-import type { EventHistoryRow, InstallationRow } from "@hot-updater/server";
+import type {
+  EventHistoryRow,
+  InstallationRow,
+} from "@hot-updater/server/plugins";
 
 export type InsightsEventRow = EventHistoryRow;
 export type InsightsInstallationViewRow = InstallationRow;
@@ -8,8 +11,34 @@ export type InsightsViewPage<TRow> = {
   readonly nextCursor: string | null;
 };
 
-export const outcomeLabels = {
-  applied: "Applied reports",
-  recovered: "Recovered-from reports",
-  unchanged: "No-change reports",
+const DAY_MS = 86_400_000;
+
+/** The time ranges an event list reads, shortest first. */
+export const eventRanges = {
+  "24h": { period: "24 hours", durationMs: DAY_MS },
+  "7d": { period: "7 days", durationMs: 7 * DAY_MS },
+  "30d": { period: "30 days", durationMs: 30 * DAY_MS },
+  "90d": { period: "90 days", durationMs: 90 * DAY_MS },
 } as const;
+
+export type EventRange = keyof typeof eventRanges;
+
+export const EVENT_RANGES = Object.keys(eventRanges) as readonly EventRange[];
+
+export const DEFAULT_EVENT_RANGE: EventRange = "7d";
+
+/** The next longer range, or undefined for the longest. */
+export const widerEventRange = (range: EventRange): EventRange | undefined =>
+  EVENT_RANGES[EVENT_RANGES.indexOf(range) + 1];
+
+/**
+ * The receipt interval [sinceMs, beforeReceivedAtMs) a range covers. The end
+ * stays fixed while the list pages, so every page reads the same interval.
+ */
+export const eventRangeBounds = (
+  range: EventRange,
+  beforeReceivedAtMs: number,
+) => ({
+  beforeReceivedAtMs,
+  sinceMs: Math.max(0, beforeReceivedAtMs - eventRanges[range].durationMs),
+});