@hot-updater/console 0.36.7 → 1.0.0-rc.0

package/src/lib/analytics-api.ts

@@ -0,0 +1,145 @@
+import { type QueryClient, useQuery } from "@tanstack/react-query";
+import { redirect } from "@tanstack/react-router";
+
+import {
+  type ActiveInstallationInput,
+  parseActiveInstallationInput,
+} from "./analytics-input";
+import {
+  getActiveInstallationOverviewRpc,
+  getAnalyticsCapabilitiesRpc,
+  getAnalyticsOverviewRpc,
+  type AnalyticsCapabilities,
+} from "./analytics-rpc";
+
+export type AnalyticsCapabilityState =
+  | { readonly status: "unresolved" }
+  | { readonly status: "unsupported" }
+  | {
+      readonly status: "supported";
+      readonly mode: "bounded";
+      readonly maxMatchingRows: number;
+    }
+  | { readonly status: "error"; readonly error: Error };
+
+type AnalyticsCapabilityQueryResult =
+  | { readonly status: "pending" }
+  | { readonly status: "success"; readonly data: AnalyticsCapabilities }
+  | { readonly status: "error"; readonly error: Error };
+
+export type ProtectedAnalyticsRouteDecision =
+  | "loading"
+  | "redirect"
+  | "allow"
+  | "error";
+
+export const analyticsQueryKeys = {
+  capabilities: ["analytics", "capabilities"] as const,
+  overview: ["analytics", "overview"] as const,
+  activeInstallations: (input: ActiveInstallationInput) =>
+    [
+      "analytics",
+      "active-installations",
+      input.window,
+      input.userId ?? null,
+    ] as const,
+};
+
+const ANALYTICS_STALE_TIME_MS = 30_000;
+
+export const getAnalyticsCapabilityState = (
+  query: AnalyticsCapabilityQueryResult,
+): AnalyticsCapabilityState => {
+  switch (query.status) {
+    case "pending":
+      return { status: "unresolved" };
+    case "error":
+      return { status: "error", error: query.error };
+    case "success":
+      if (!query.data.capabilities.analytics) {
+        return { status: "unsupported" };
+      }
+      return {
+        status: "supported",
+        mode: "bounded",
+        maxMatchingRows: query.data.capabilities.maxMatchingRows,
+      };
+  }
+};
+
+export const getProtectedAnalyticsRouteDecision = (
+  capability: AnalyticsCapabilityState,
+): ProtectedAnalyticsRouteDecision => {
+  switch (capability.status) {
+    case "unresolved":
+      return "loading";
+    case "unsupported":
+      return "redirect";
+    case "supported":
+      return "allow";
+    case "error":
+      return "error";
+  }
+};
+
+export const isAnalyticsQueryEnabled = (
+  capability: AnalyticsCapabilityState,
+): boolean => capability.status === "supported";
+
+export const getAnalyticsCapabilitiesQueryOptions = () => ({
+  queryKey: analyticsQueryKeys.capabilities,
+  queryFn: () => getAnalyticsCapabilitiesRpc(),
+  staleTime: Infinity,
+});
+
+export const useAnalyticsCapabilitiesQuery = () =>
+  useQuery(getAnalyticsCapabilitiesQueryOptions());
+
+export const ensureAnalyticsRouteAccess = async (
+  queryClient: QueryClient,
+): Promise<void> => {
+  const result = await queryClient.ensureQueryData(
+    getAnalyticsCapabilitiesQueryOptions(),
+  );
+
+  if (!result.capabilities.analytics) {
+    throw redirect({
+      to: "/",
+      search: {},
+      replace: true,
+    });
+  }
+};
+
+export const getAnalyticsOverviewQueryOptions = (
+  capability: AnalyticsCapabilityState,
+) => ({
+  queryKey: analyticsQueryKeys.overview,
+  queryFn: () => getAnalyticsOverviewRpc(),
+  staleTime: ANALYTICS_STALE_TIME_MS,
+  refetchOnWindowFocus: true,
+  enabled: isAnalyticsQueryEnabled(capability),
+});
+
+export const useAnalyticsOverviewQuery = (
+  capability: AnalyticsCapabilityState,
+) => useQuery(getAnalyticsOverviewQueryOptions(capability));
+
+export const getActiveInstallationQueryOptions = (
+  capability: AnalyticsCapabilityState,
+  input: ActiveInstallationInput,
+) => {
+  const normalized = parseActiveInstallationInput(input);
+  return {
+    queryKey: analyticsQueryKeys.activeInstallations(normalized),
+    queryFn: () => getActiveInstallationOverviewRpc({ data: normalized }),
+    staleTime: ANALYTICS_STALE_TIME_MS,
+    refetchOnWindowFocus: true,
+    enabled: isAnalyticsQueryEnabled(capability),
+  };
+};
+
+export const useActiveInstallationQuery = (
+  capability: AnalyticsCapabilityState,
+  input: ActiveInstallationInput,
+) => useQuery(getActiveInstallationQueryOptions(capability, input));

package/src/lib/analytics-error.ts

@@ -0,0 +1,19 @@
+export type AnalyticsErrorCopy = {
+  readonly title: string;
+  readonly description: string;
+};
+
+export const getAnalyticsErrorCopy = (
+  error: Error,
+  fallbackTitle: string,
+): AnalyticsErrorCopy => {
+  const match = /^Bundle event scan exceeded (\d+) rows\.$/.exec(error.message);
+  if (!match) {
+    return { title: fallbackTitle, description: error.message };
+  }
+  const limit = Number(match[1]);
+  return {
+    title: "Analytics report limit reached",
+    description: `This query matched more than ${limit.toLocaleString()} reports. Narrow the query and try again.`,
+  };
+};

package/src/lib/analytics-input.ts

@@ -0,0 +1,187 @@
+import type { ActiveInstallationWindow } from "@hot-updater/server";
+import type { BundleEventAnalyticsWindow } from "@hot-updater/server";
+
+const MAX_ANALYTICS_STRING_LENGTH = 1024;
+const MAX_ANALYTICS_LIMIT = 100;
+
+export type BundleEventSummaryInput = {
+  readonly bundleId: string;
+};
+
+export type BundleEventAnalyticsInput = BundleEventSummaryInput & {
+  readonly window: BundleEventAnalyticsWindow;
+  readonly limit?: number;
+  readonly offset?: number;
+};
+
+export type SearchInstallationsInput = {
+  readonly query: string;
+  readonly limit?: number;
+  readonly offset?: number;
+};
+
+export type InstallationHistoryInput = {
+  readonly installId: string;
+  readonly limit?: number;
+  readonly offset?: number;
+};
+
+export type ActiveInstallationInput = {
+  readonly window: ActiveInstallationWindow;
+  readonly userId?: string;
+};
+
+type AnalyticsPagination = {
+  readonly limit?: number;
+  readonly offset?: number;
+};
+
+export class AnalyticsInputValidationError extends Error {
+  readonly name = "AnalyticsInputValidationError";
+
+  constructor(readonly field: string) {
+    super(`Invalid analytics input: ${field}`);
+  }
+}
+
+const isRecord = (input: unknown): input is Record<string, unknown> =>
+  typeof input === "object" && input !== null && !Array.isArray(input);
+
+const parseRecord = (input: unknown): Record<string, unknown> => {
+  if (!isRecord(input)) {
+    throw new AnalyticsInputValidationError("input");
+  }
+  return input;
+};
+
+const parseString = (input: Record<string, unknown>, field: string): string => {
+  const value = input[field];
+  if (typeof value !== "string") {
+    throw new AnalyticsInputValidationError(field);
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.length > MAX_ANALYTICS_STRING_LENGTH) {
+    throw new AnalyticsInputValidationError(field);
+  }
+  return trimmed;
+};
+
+const parseLimit = (input: Record<string, unknown>): number | undefined => {
+  const value = input.limit;
+  if (value === undefined) {
+    return undefined;
+  }
+  if (
+    typeof value !== "number" ||
+    !Number.isInteger(value) ||
+    value < 1 ||
+    value > MAX_ANALYTICS_LIMIT
+  ) {
+    throw new AnalyticsInputValidationError("limit");
+  }
+  return value;
+};
+
+const parseOffset = (input: Record<string, unknown>): number | undefined => {
+  const value = input.offset;
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new AnalyticsInputValidationError("offset");
+  }
+  return value;
+};
+
+const parsePagination = (
+  input: Record<string, unknown>,
+): AnalyticsPagination => {
+  const limit = parseLimit(input);
+  const offset = parseOffset(input);
+  return {
+    ...(limit === undefined ? {} : { limit }),
+    ...(offset === undefined ? {} : { offset }),
+  };
+};
+
+const parseWindow = (
+  input: Record<string, unknown>,
+): BundleEventAnalyticsWindow => {
+  const value = input.window;
+  if (value === "24h" || value === "7d" || value === "30d" || value === "all") {
+    return value;
+  }
+  throw new AnalyticsInputValidationError("window");
+};
+
+const parseActiveWindow = (
+  input: Record<string, unknown>,
+): ActiveInstallationWindow => {
+  const value = input.window;
+  if (value === "24h" || value === "7d" || value === "30d") {
+    return value;
+  }
+  throw new AnalyticsInputValidationError("window");
+};
+
+const parseOptionalUserId = (
+  input: Record<string, unknown>,
+): string | undefined => {
+  if (input.userId === undefined) return undefined;
+  if (typeof input.userId !== "string") {
+    throw new AnalyticsInputValidationError("userId");
+  }
+  const userId = input.userId.trim();
+  if (userId.length === 0) return undefined;
+  if (userId.length > MAX_ANALYTICS_STRING_LENGTH) {
+    throw new AnalyticsInputValidationError("userId");
+  }
+  return userId;
+};
+
+export const parseActiveInstallationInput = (
+  input: unknown,
+): ActiveInstallationInput => {
+  const record = parseRecord(input);
+  const window = parseActiveWindow(record);
+  const userId = parseOptionalUserId(record);
+  return userId === undefined ? { window } : { window, userId };
+};
+
+export const parseBundleEventSummaryInput = (
+  input: unknown,
+): BundleEventSummaryInput => {
+  const record = parseRecord(input);
+  return { bundleId: parseString(record, "bundleId") };
+};
+
+export const parseBundleEventAnalyticsInput = (
+  input: unknown,
+): BundleEventAnalyticsInput => {
+  const record = parseRecord(input);
+  return {
+    bundleId: parseString(record, "bundleId"),
+    window: parseWindow(record),
+    ...parsePagination(record),
+  };
+};
+
+export const parseSearchInstallationsInput = (
+  input: unknown,
+): SearchInstallationsInput => {
+  const record = parseRecord(input);
+  return {
+    query: parseString(record, "query"),
+    ...parsePagination(record),
+  };
+};
+
+export const parseInstallationHistoryInput = (
+  input: unknown,
+): InstallationHistoryInput => {
+  const record = parseRecord(input);
+  return {
+    installId: parseString(record, "installId"),
+    ...parsePagination(record),
+  };
+};

package/src/lib/analytics-overview.ts

@@ -0,0 +1,170 @@
+import { normalizeRolloutCohortCount } from "@hot-updater/core";
+import type { Bundle, ChannelRow, ReleaseRow } from "@hot-updater/plugin-core";
+
+export type AnalyticsBundleMetadata = {
+  readonly platform: "ios" | "android";
+  readonly channel: string | null;
+  readonly targetAppVersion: string | null;
+  readonly fingerprintHash: string | null;
+};
+
+export type LatestReportedBundle = {
+  readonly bundleId: string;
+  readonly trackedInstallations: number;
+  readonly observedShare: number;
+  readonly bundle: AnalyticsBundleMetadata | null;
+};
+
+export type ConfiguredRollout = {
+  readonly releaseId: string;
+  readonly bundleId: string;
+  readonly configuredPercentage: number;
+  readonly trackedInstallations: number;
+  readonly bundle: AnalyticsBundleMetadata;
+};
+
+export type AnalyticsOverview = {
+  readonly trackedInstallations: number;
+  readonly mostCommonLatestReportedBundle: LatestReportedBundle | null;
+  readonly latestReportedBundles: readonly LatestReportedBundle[];
+  readonly configuredRollouts: readonly ConfiguredRollout[];
+};
+
+export type LatestInstallationBundle = {
+  readonly lastKnownBundleId: string | null;
+};
+
+export type InstallationBundleCount = {
+  readonly bundleId: string;
+  readonly installations: number;
+};
+
+const toBundleMetadata = (
+  bundle: Bundle,
+  release: ReleaseRow | undefined,
+  channelById: ReadonlyMap<string, string>,
+): AnalyticsBundleMetadata => ({
+  platform: bundle.platform,
+  channel: release ? (channelById.get(release.channel_id) ?? null) : null,
+  targetAppVersion: release?.target_app_version ?? null,
+  fingerprintHash: release?.fingerprint_hash ?? null,
+});
+
+const compareCodePoints = (left: string, right: string): number =>
+  left < right ? -1 : left > right ? 1 : 0;
+
+const createOverview = (
+  bundles: readonly Bundle[],
+  releases: readonly ReleaseRow[],
+  channels: readonly ChannelRow[],
+  trackedInstallations: number,
+  latestReportedCounts: ReadonlyMap<string, number>,
+): AnalyticsOverview => {
+  const bundleById = new Map(bundles.map((bundle) => [bundle.id, bundle]));
+  const channelById = new Map(
+    channels.map((channel) => [channel.id, channel.name]),
+  );
+  const bundleReleases = releases
+    .filter(
+      (release): release is ReleaseRow & { readonly bundle_id: string } =>
+        release.kind === "BUNDLE" && release.bundle_id !== null,
+    )
+    .sort((left, right) => compareCodePoints(right.id, left.id));
+  const latestReleaseByBundleId = new Map<string, ReleaseRow>();
+  for (const release of bundleReleases) {
+    if (!latestReleaseByBundleId.has(release.bundle_id)) {
+      latestReleaseByBundleId.set(release.bundle_id, release);
+    }
+  }
+  const latestReportedBundles = [...latestReportedCounts]
+    .map(([bundleId, count]): LatestReportedBundle => {
+      const bundle = bundleById.get(bundleId);
+      return {
+        bundleId,
+        trackedInstallations: count,
+        observedShare:
+          trackedInstallations === 0 ? 0 : count / trackedInstallations,
+        bundle: bundle
+          ? toBundleMetadata(
+              bundle,
+              latestReleaseByBundleId.get(bundle.id),
+              channelById,
+            )
+          : null,
+      };
+    })
+    .sort(
+      (left, right) =>
+        right.trackedInstallations - left.trackedInstallations ||
+        compareCodePoints(left.bundleId, right.bundleId),
+    );
+  const configuredRollouts = bundleReleases
+    .filter((release) => bundleById.has(release.bundle_id))
+    .map(
+      (release): ConfiguredRollout => ({
+        releaseId: release.id,
+        bundleId: release.bundle_id,
+        configuredPercentage:
+          normalizeRolloutCohortCount(release.rollout_cohort_count) / 10,
+        trackedInstallations: latestReportedCounts.get(release.bundle_id) ?? 0,
+        bundle: toBundleMetadata(
+          bundleById.get(release.bundle_id)!,
+          release,
+          channelById,
+        ),
+      }),
+    )
+    .sort((left, right) => compareCodePoints(left.releaseId, right.releaseId));
+
+  return {
+    trackedInstallations,
+    mostCommonLatestReportedBundle: latestReportedBundles[0] ?? null,
+    latestReportedBundles,
+    configuredRollouts,
+  };
+};
+
+const countLatestInstallationBundles = (
+  rows: readonly LatestInstallationBundle[],
+): ReadonlyMap<string, number> => {
+  const counts = new Map<string, number>();
+  for (const row of rows) {
+    if (row.lastKnownBundleId === null) continue;
+    counts.set(
+      row.lastKnownBundleId,
+      (counts.get(row.lastKnownBundleId) ?? 0) + 1,
+    );
+  }
+  return counts;
+};
+
+export const createAnalyticsOverviewFromCounts = (
+  bundles: readonly Bundle[],
+  releases: readonly ReleaseRow[],
+  channels: readonly ChannelRow[],
+  trackedInstallations: number,
+  counts: readonly InstallationBundleCount[],
+): AnalyticsOverview =>
+  createOverview(
+    bundles,
+    releases,
+    channels,
+    trackedInstallations,
+    new Map(
+      counts.map(({ bundleId, installations }) => [bundleId, installations]),
+    ),
+  );
+
+export const createAnalyticsOverview = (
+  bundles: readonly Bundle[],
+  releases: readonly ReleaseRow[],
+  channels: readonly ChannelRow[],
+  latestInstallations: readonly LatestInstallationBundle[],
+): AnalyticsOverview =>
+  createOverview(
+    bundles,
+    releases,
+    channels,
+    latestInstallations.length,
+    countLatestInstallationBundles(latestInstallations),
+  );