@hot-updater/console 1.0.0-rc.3 → 1.0.0-rc.31

package/src/components/features/insights/InsightsPageHeader.tsx

@@ -1,14 +1,21 @@
 import { Link } from "@tanstack/react-router";
-import { ChartNoAxesCombined } from "lucide-react";
+import { ChartNoAxesCombined, ListIcon } from "lucide-react";
 
 import { buttonVariants } from "@/components/ui/button";
 import { SidebarTrigger } from "@/components/ui/sidebar";
+import { useConsoleFeature } from "@/lib/console-features-api";
+import type { InsightsSearch } from "@/lib/insights-search";
+import { cn } from "@/lib/utils";
 
 export function InsightsPageHeader({
   view,
+  overviewSearch,
 }: {
-  readonly view: "overview" | "events";
+  readonly view: "overview" | "events" | "distribution";
+  readonly overviewSearch?: InsightsSearch;
 }) {
+  // A self-hosted server's admin API serves events, not the overview.
+  const overview = useConsoleFeature("insightsAnalytics");
   return (
     <header className="sticky top-0 z-10 flex shrink-0 flex-wrap items-center gap-3 border-b bg-background px-3 py-3 sm:bg-card/70 sm:px-4 sm:backdrop-blur-sm">
       <SidebarTrigger className="-ml-1 size-11 lg:size-7" />
@@ -19,28 +26,36 @@ export function InsightsPageHeader({
         />
         <h1 className="text-sm font-medium">Insights</h1>
       </div>
-      <nav aria-label="Insights views" className="ml-auto flex gap-1">
-        <Link
-          aria-current={view === "overview" ? "page" : undefined}
-          className={buttonVariants({
-            className: "h-11 px-3 lg:h-8 lg:px-2.5",
-            size: "lg",
-            variant: view === "overview" ? "secondary" : "ghost",
-          })}
-          to="/insights"
-        >
-          Overview
-        </Link>
+      <nav aria-label="Insights views" className="ml-auto flex gap-2">
+        {overview ? (
+          <Link
+            aria-current={view === "overview" ? "page" : undefined}
+            className={cn(
+              buttonVariants({
+                className: "h-11 px-3 lg:h-8 lg:px-2.5",
+                size: "lg",
+                variant: view === "overview" ? "secondary" : "ghost",
+              }),
+            )}
+            search={overviewSearch}
+            to="/insights"
+          >
+            Overview
+          </Link>
+        ) : null}
         <Link
           aria-current={view === "events" ? "page" : undefined}
-          className={buttonVariants({
-            className: "h-11 px-3 lg:h-8 lg:px-2.5",
-            size: "lg",
-            variant: view === "events" ? "secondary" : "ghost",
-          })}
+          className={cn(
+            buttonVariants({
+              className: "h-11 px-3 lg:h-8 lg:px-2.5",
+              size: "lg",
+              variant: view === "events" ? "secondary" : "ghost",
+            }),
+          )}
           to="/installations"
         >
-          Events
+          <ListIcon aria-hidden="true" data-icon="inline-start" />
+          All events
         </Link>
       </nav>
     </header>

package/src/components/features/insights/InsightsPeriodSelector.tsx

@@ -0,0 +1,89 @@
+import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import type { InsightsWindow } from "@/lib/insights-api";
+import { usageMetrics, type UsageWindow } from "@/lib/insights-usage";
+
+/** A segmented control over fixed periods, each shown by its short value. */
+export function PeriodSelector<TPeriod extends string>({
+  label,
+  onPeriodChange,
+  period,
+  periods,
+}: {
+  readonly label: string;
+  readonly onPeriodChange: (period: TPeriod) => void;
+  readonly period: TPeriod;
+  readonly periods: readonly {
+    readonly value: TPeriod;
+    readonly name: string;
+  }[];
+}) {
+  return (
+    <Tabs
+      value={period}
+      onValueChange={(value) => {
+        const next = periods.find((item) => item.value === value);
+        if (next) onPeriodChange(next.value);
+      }}
+    >
+      <TabsList aria-label={label} className="min-h-11 sm:min-h-9">
+        {periods.map(({ value, name }) => (
+          <TabsTrigger
+            key={value}
+            value={value}
+            aria-label={name}
+            className="min-w-12 px-3"
+          >
+            {value}
+          </TabsTrigger>
+        ))}
+      </TabsList>
+    </Tabs>
+  );
+}
+
+const reportingPeriods = (["24h", "7d", "30d"] as const).map((value) => ({
+  value,
+  name: usageMetrics[value].period,
+}));
+const usagePeriods = (Object.keys(usageMetrics) as UsageWindow[]).map(
+  (value) => ({ value, name: usageMetrics[value].period }),
+);
+
+export function InsightsPeriodSelector({
+  window,
+  onWindowChange,
+}: {
+  readonly window: InsightsWindow;
+  readonly onWindowChange: (window: InsightsWindow) => void;
+}) {
+  return (
+    <PeriodSelector
+      label="Reporting period"
+      onPeriodChange={onWindowChange}
+      period={window}
+      periods={reportingPeriods}
+    />
+  );
+}
+
+/** App usage's periods: the reporting periods, and 12 months where daily totals cover it. */
+export function UsagePeriodSelector({
+  window,
+  onWindowChange,
+  twelveMonths = true,
+}: {
+  readonly window: UsageWindow;
+  readonly onWindowChange: (window: UsageWindow) => void;
+  readonly twelveMonths?: boolean;
+}) {
+  return (
+    <PeriodSelector
+      label="Reporting period"
+      onPeriodChange={onWindowChange}
+      period={window}
+      periods={usagePeriods.filter(
+        ({ value }) => twelveMonths || value !== "12m",
+      )}
+    />
+  );
+}

package/src/components/features/insights/InstallationHistoryCard.tsx

@@ -2,7 +2,13 @@ import { RefreshCw } from "lucide-react";
 
 import { HashValueDisplay } from "@/components/HashValueDisplay";
 import { Button } from "@/components/ui/button";
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
 import { Separator } from "@/components/ui/separator";
 import { Skeleton } from "@/components/ui/skeleton";
 import {
@@ -13,6 +19,11 @@ import {
   TableHeader,
   TableRow,
 } from "@/components/ui/table";
+import {
+  DEFAULT_INSIGHTS_RETENTION,
+  formatDays,
+  type InsightsRetentionDays,
+} from "@/lib/insights-retention";
 import type {
   InsightsEventRow,
   InsightsInstallationViewRow,
@@ -22,24 +33,26 @@ import type {
 import {
   EventBundleTransition,
   EventTimestamp,
-  EventTypeBadge,
+  EventTypeDetails,
+  HttpResponseDetails,
   useInsightsTimeFormat,
 } from "./EventDetails";
 import { EventHistoryList } from "./EventHistoryList";
 import { InsightsErrorAlert } from "./InsightsErrorAlert";
 import { InsightsPagination } from "./InsightsPagination";
 
-const getUserLabel = (event: {
-  readonly username: string | null;
-  readonly userId: string | null;
-}) => event.userId ?? event.username ?? "—";
+const getUserLabel = (event: { readonly userId: string | null }) =>
+  event.userId ?? "—";
 
+/** A download or a failed update leaves the installation on the bundle it ran. */
 const getLastKnownBundleId = (
   event: InsightsEventRow | InsightsInstallationViewRow,
 ) =>
   "lastKnownBundleId" in event
     ? event.lastKnownBundleId
-    : (event.toBundleId ?? event.fromBundleId);
+    : event.type === "UPDATE_DOWNLOADED" || event.type === "UPDATE_FAILED"
+      ? event.fromBundleId
+      : event.toBundleId;
 
 export function InstallationHistoryCard({
   error,
@@ -49,6 +62,7 @@ export function InstallationHistoryCard({
   onPrevious,
   onRefresh,
   pageNumber,
+  retention = DEFAULT_INSIGHTS_RETENTION,
   selectedEvent,
   selectedInstallId,
 }: {
@@ -59,6 +73,8 @@ export function InstallationHistoryCard({
   readonly onNext: () => void;
   readonly onPrevious: () => void;
   readonly pageNumber: number;
+  /** How long the server keeps Insights rows. */
+  readonly retention?: InsightsRetentionDays;
   readonly selectedEvent:
     | InsightsEventRow
     | InsightsInstallationViewRow
@@ -70,6 +86,15 @@ export function InstallationHistoryCard({
     ? getLastKnownBundleId(selectedEvent)
     : undefined;
 
+  const pendingBundleId =
+    selectedEvent && "pendingBundleId" in selectedEvent
+      ? selectedEvent.pendingBundleId
+      : selectedEvent &&
+          "type" in selectedEvent &&
+          selectedEvent.type === "UPDATE_DOWNLOADED"
+        ? selectedEvent.toBundleId
+        : null;
+
   return (
     <Card className="@container min-h-0 min-w-0 shadow-sm">
       <CardHeader className="p-4 sm:p-6">
@@ -82,6 +107,14 @@ export function InstallationHistoryCard({
                   : "Select an installation"}
               </h2>
             </CardTitle>
+            {selectedInstallId !== undefined ? (
+              <CardDescription>
+                Bundle changes and update failures are kept for{" "}
+                {formatDays(retention.rawDays)}; the latest report, for{" "}
+                {formatDays(retention.dailyDays)} after the installation last
+                reports.
+              </CardDescription>
+            ) : null}
           </div>
           {onRefresh && selectedInstallId !== undefined ? (
             <Button
@@ -138,7 +171,22 @@ export function InstallationHistoryCard({
                     )}
                   </dd>
                 </div>
+                {pendingBundleId ? (
+                  <div className="col-span-2 min-w-0">
+                    <dt className="text-xs text-muted-foreground">
+                      Downloaded · Pending apply
+                    </dt>
+                    <dd className="mt-1 text-xs">
+                      <HashValueDisplay value={pendingBundleId} />
+                    </dd>
+                  </div>
+                ) : null}
               </dl>
+              {selectedEvent.httpResponse ? (
+                <div className="mt-4">
+                  <HttpResponseDetails event={selectedEvent} />
+                </div>
+              ) : null}
             </section>
             <Separator />
           </>
@@ -192,7 +240,7 @@ export function InstallationHistoryCard({
                           />
                         </TableCell>
                         <TableCell>
-                          <EventTypeBadge type={event.type} />
+                          <EventTypeDetails event={event} />
                         </TableCell>
                         <TableCell className="whitespace-normal text-xs">
                           <div className="flex flex-col gap-2">
@@ -226,8 +274,8 @@ export function InstallationHistoryCard({
           ) : (
             <>
               <div className="p-6 text-sm text-muted-foreground">
-                {pageNumber > 1 || history?.nextCursor
-                  ? "No bundle changes on this page."
+                {pageNumber > 1
+                  ? "No older bundle changes."
                   : "No bundle changes recorded yet."}
               </div>
               {history && (pageNumber > 1 || history.nextCursor) ? (

package/src/components/features/insights/InstallationMatchesCard.tsx

@@ -17,7 +17,7 @@ const getLastKnownBundleId = (event: InsightsInstallationViewRow) =>
   event.lastKnownBundleId;
 
 const getUserLabel = (event: InsightsInstallationViewRow) =>
-  event.userId ?? event.username ?? "—";
+  event.userId ?? "—";
 
 export function InstallationMatchesCard({
   error,

package/src/components/features/insights/ReleaseActivity.tsx

@@ -0,0 +1,290 @@
+import { Link } from "@tanstack/react-router";
+import { ChartLine } from "lucide-react";
+
+import { buttonVariants } from "@/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import { Separator } from "@/components/ui/separator";
+import { Skeleton } from "@/components/ui/skeleton";
+import type {
+  BundleActivityInput,
+  BundleActivityReport,
+} from "@/lib/bundle-activity";
+import { useBundleActivityQuery } from "@/lib/bundle-activity";
+import { useConsoleFeature } from "@/lib/console-features-api";
+import { useUpdateFailuresQuery } from "@/lib/insights-api";
+import { failureRate, formatRate } from "@/lib/insights-failures";
+import { adoptionWindow } from "@/lib/insights-search";
+import { cn } from "@/lib/utils";
+
+import type { ReleaseColumn } from "../FeatureSlots";
+import { InsightsInfo } from "./InsightsInfo";
+
+const activityStats = [
+  { label: "Downloads", field: "downloads", color: "text-primary/85" },
+  { label: "Active days", field: "activeDays", color: "text-success/85" },
+  { label: "Known crashes", field: "failedLaunches", color: "text-warning/85" },
+] as const;
+
+const crashRate = (report: BundleActivityReport): string => {
+  const attempts = report.activeDays + report.failedLaunches;
+  return attempts === 0
+    ? "—"
+    : `${((report.failedLaunches / attempts) * 100).toFixed(2)}%`;
+};
+
+function ReleaseMetricsInfo() {
+  return (
+    <InsightsInfo label="About release insight metrics">
+      Active days count each installation once for each UTC day it launched this
+      release. Known crashes are reported OTA launch failures that triggered
+      recovery. The rate is known crashes divided by active days plus known
+      crashes.
+    </InsightsInfo>
+  );
+}
+
+export function BundleMovementSummary({
+  report,
+  loading = false,
+  input,
+  variant = "inline",
+}: {
+  readonly report?: BundleActivityReport;
+  readonly loading?: boolean;
+  readonly input?: BundleActivityInput;
+  readonly variant?: "inline" | "card";
+}) {
+  if (!report) {
+    return loading ? (
+      <Skeleton
+        aria-label="Loading release insights"
+        className={variant === "card" ? "h-16 w-full" : "h-4 w-40"}
+      />
+    ) : (
+      <span
+        aria-label="Release insights unavailable"
+        className="text-sm text-muted-foreground"
+      >
+        —
+      </span>
+    );
+  }
+  const metrics = (
+    <dl
+      className={cn(
+        variant === "card"
+          ? "grid grid-cols-[1fr_1fr_auto] gap-4"
+          : "flex min-w-[220px] flex-wrap items-baseline gap-x-3 gap-y-1",
+      )}
+    >
+      {activityStats.map(({ label, field, color }) => (
+        <div
+          key={field}
+          className={cn(
+            "flex",
+            variant === "card"
+              ? "min-w-0 flex-col gap-1"
+              : "items-baseline gap-1.5 whitespace-nowrap",
+          )}
+        >
+          <dt className="text-xs text-muted-foreground">{label}</dt>
+          <dd
+            className={cn(
+              "flex flex-wrap items-baseline gap-x-1.5 tabular-nums",
+              variant === "card"
+                ? "text-xl font-semibold"
+                : "text-sm font-medium",
+              report[field] > 0 ? color : "text-muted-foreground",
+            )}
+          >
+            {report[field].toLocaleString()}
+            {field === "failedLaunches" ? (
+              <span className="text-xs font-normal text-muted-foreground">
+                ({crashRate(report)})
+              </span>
+            ) : null}
+          </dd>
+        </div>
+      ))}
+    </dl>
+  );
+  return (
+    <div
+      className={cn(
+        "flex",
+        variant === "card" ? "flex-col gap-2" : "items-center gap-1",
+      )}
+    >
+      {input ? (
+        <Link
+          className="min-w-0 rounded-sm hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          to="/insights"
+          search={{
+            healthPlatform: input.platform,
+            healthChannel: input.channel,
+            releaseId: input.releaseId,
+            bundleWindow: "7d",
+          }}
+        >
+          {metrics}
+        </Link>
+      ) : (
+        metrics
+      )}
+      {variant === "inline" ? <ReleaseMetricsInfo /> : null}
+    </div>
+  );
+}
+
+/** The release's failed downloads and installs since its first report, and their rate. */
+export function BundleDownloadFailures({
+  input,
+}: {
+  readonly input: BundleActivityInput;
+}) {
+  const query = useUpdateFailuresQuery({
+    platform: input.platform,
+    channel: input.channel,
+    releaseId: input.releaseId,
+  });
+  const report = query.data;
+  return (
+    <div className="flex items-center gap-1">
+      {report ? (
+        <dl>
+          <div className="flex flex-wrap items-baseline gap-x-1.5">
+            <dt className="text-xs text-muted-foreground">Download failures</dt>
+            <dd
+              className={cn(
+                "flex items-baseline gap-1.5 text-sm font-medium tabular-nums",
+                report.failedUpdates > 0
+                  ? "text-warning/85"
+                  : "text-muted-foreground",
+              )}
+            >
+              {report.failedUpdates.toLocaleString()}
+              <span className="text-xs font-normal text-muted-foreground">
+                ({formatRate(failureRate(report))})
+              </span>
+            </dd>
+          </div>
+        </dl>
+      ) : query.isPending ? (
+        <Skeleton aria-label="Loading download failures" className="h-4 w-40" />
+      ) : (
+        <span
+          aria-label="Download failures unavailable"
+          className="text-sm text-muted-foreground"
+        >
+          —
+        </span>
+      )}
+      <InsightsInfo label="About download failures">
+        Reported failures to download or install this release, since its first
+        report; each client reports one at most once a UTC day. The rate is the
+        failure rate of update attempts: failures divided by failures plus
+        download reports.
+      </InsightsInfo>
+    </div>
+  );
+}
+
+/** The bundle detail's Insights card, a section of the release editor: activity and download failures. */
+export function BundleInsightsSummary({
+  input,
+}: {
+  readonly input: BundleActivityInput;
+}) {
+  const query = useBundleActivityQuery([input]);
+  return (
+    <Card>
+      <CardHeader className="flex-row items-center justify-between px-4 pt-4 pb-3">
+        <CardTitle className="text-sm font-medium">Insights</CardTitle>
+        <ReleaseMetricsInfo />
+      </CardHeader>
+      <CardContent className="flex flex-col gap-3 px-4 pb-4">
+        <BundleMovementSummary
+          variant="card"
+          input={input}
+          loading={query.isFetching}
+          report={query.data?.[input.releaseId]}
+        />
+        <Separator />
+        <BundleDownloadFailures input={input} />
+      </CardContent>
+      <CardFooter className="px-4 pb-4">
+        <Link
+          className={buttonVariants({ variant: "outline", size: "sm" })}
+          to="/insights"
+          search={{
+            healthPlatform: input.platform,
+            healthChannel: input.channel,
+            releaseId: input.releaseId,
+            bundleWindow: adoptionWindow(input.releaseId),
+            healthChart: "adoption",
+          }}
+        >
+          <ChartLine aria-hidden="true" data-icon="inline-start" />
+          View adoption
+        </Link>
+      </CardFooter>
+    </Card>
+  );
+}
+
+/**
+ * The release editor's Insights card where the console reads no release
+ * activity, as through a self-hosted server's admin API: download failures
+ * alone. With release activity, its card shows them.
+ */
+export function ReleaseFailuresSection({
+  input,
+}: {
+  readonly input: BundleActivityInput;
+}) {
+  const activity = useConsoleFeature("insightsAnalytics");
+  if (activity) return null;
+  return (
+    <Card>
+      <CardHeader className="px-4 pt-4 pb-3">
+        <CardTitle className="text-sm font-medium">Insights</CardTitle>
+      </CardHeader>
+      <CardContent className="px-4 pb-4">
+        <BundleDownloadFailures input={input} />
+      </CardContent>
+    </Card>
+  );
+}
+
+/**
+ * One release's activity in the Bundles page's Insights column. Every cell
+ * asks for the page's releases under one query key, so the page makes one
+ * request.
+ */
+function ReleaseActivityCell({
+  releaseId,
+  releases,
+}: {
+  readonly releaseId: string;
+  readonly releases: readonly BundleActivityInput[];
+}) {
+  const query = useBundleActivityQuery(releases);
+  return (
+    <BundleMovementSummary
+      input={releases.find((release) => release.releaseId === releaseId)}
+      loading={query.isFetching}
+      report={query.data?.[releaseId]}
+    />
+  );
+}
+
+/** The Bundles page's Insights column: each release's downloads, active days, and crashes. */
+export const releaseActivityColumn: ReleaseColumn = {
+  Cell: ReleaseActivityCell,
+};

package/src/components/features/insights/ReportingDevicesSummary.tsx

@@ -0,0 +1,65 @@
+import { Skeleton } from "@/components/ui/skeleton";
+import {
+  DEFAULT_INSIGHTS_RETENTION,
+  formatDays,
+  type InsightsRetentionDays,
+} from "@/lib/insights-retention";
+import { usageMetrics, type UsageWindow } from "@/lib/insights-usage";
+
+import { EstimatedCount } from "./EstimatedCount";
+import { InsightsInfo } from "./InsightsInfo";
+
+export function ReportingDevicesSummary({
+  window,
+  count,
+  isPending,
+  partial,
+  retention = DEFAULT_INSIGHTS_RETENTION,
+}: {
+  readonly window: UsageWindow;
+  readonly count: number | undefined;
+  readonly isPending: boolean;
+  readonly partial: boolean;
+  readonly retention?: InsightsRetentionDays;
+}) {
+  const metric = usageMetrics[window];
+  return (
+    <div
+      aria-label={`${metric.label} over ${metric.period}`}
+      role="region"
+      className="flex items-center gap-3"
+    >
+      {isPending ? (
+        <Skeleton aria-label="Loading active users" className="h-9 w-12" />
+      ) : (
+        <p className="text-4xl font-semibold tracking-tight tabular-nums">
+          {count === undefined ? (
+            "—"
+          ) : partial ? (
+            `≥${count.toLocaleString()}`
+          ) : (
+            <EstimatedCount value={count} />
+          )}
+        </p>
+      )}
+      <div className="flex items-center gap-1 text-sm text-muted-foreground">
+        <span>{metric.label}</span>
+        <InsightsInfo label={`How ${metric.label} is counted`}>
+          Unique app installations that reported activity in the last{" "}
+          {metric.period}, including no-change reports. Filtered by platform,
+          channel, and app version. The chart counts unique reporting
+          installations per {metric.interval}. Unique counts are estimates,
+          typically within about 3%. On DynamoDB and Firestore the server
+          updates totals in batches: when the Console cannot write to the
+          database, totals can leave out up to a minute of the latest reports.
+          Hourly counts are kept for {formatDays(retention.rawDays)} and daily
+          counts for {formatDays(retention.dailyDays)}, so 12 months counts
+          whole UTC days.
+          {partial
+            ? " Only part of the history is available; the total is a lower bound."
+            : ""}
+        </InsightsInfo>
+      </div>
+    </div>
+  );
+}