@hot-updater/server 1.0.0-rc.16 → 1.0.0-rc.18

package/src/plugins/insights/modelTypes.ts

@@ -0,0 +1,197 @@
+import type { BundleEventRow } from "./eventRow";
+
+export interface InsightsEventCursor {
+  readonly receivedAtMs: number;
+  readonly id: string;
+}
+
+export interface InsightsScope {
+  readonly platform: "ios" | "android";
+  readonly channel: string;
+}
+
+/**
+ * Raw event predicates; recovery is attributed to the source bundle. An
+ * UNCHANGED report is kept as no event, so no filter names it.
+ */
+export type InsightsBundleEventFilter = InsightsScope &
+  (
+    | { readonly type: "RECOVERED"; readonly fromBundleId: string }
+    | {
+        readonly type: "UPDATE_DOWNLOADED" | "UPDATE_APPLIED" | "UPDATE_FAILED";
+        readonly toBundleId: string;
+      }
+  );
+
+export type InsightsEventFilter =
+  | { readonly kind: "all" }
+  | {
+      readonly kind: "installationMovement";
+      readonly installId: string;
+    }
+  | ({ readonly kind: "bundle" } & InsightsBundleEventFilter);
+
+export interface InsightsRecordEventInput {
+  readonly event: BundleEventRow;
+}
+
+export interface InsightsListEventsInput {
+  readonly filter: InsightsEventFilter;
+  readonly sinceMs?: number;
+  readonly beforeReceivedAtMs: number;
+  readonly after?: InsightsEventCursor;
+  readonly limit: number;
+}
+
+export type InsightsFindLatestEventsInput =
+  | { readonly installId: string }
+  | {
+      readonly userId: string;
+      readonly afterInstallId?: string;
+      readonly limit: number;
+    };
+
+export interface InsightsCountLatestEventsInput extends InsightsScope {
+  /** A UTC day's start: latest events are counted by the day they fall in. */
+  readonly sinceMs: number;
+  /** Optional OR of one or two fixed predicates; count a matching event once. */
+  readonly bundle?: readonly {
+    readonly field: "from_bundle_id" | "to_bundle_id";
+    readonly value: string;
+    readonly types: readonly BundleEventRow["type"][];
+  }[];
+}
+
+export interface InsightsCountEventsInput {
+  readonly filter: InsightsBundleEventFilter;
+  readonly sinceMs: number;
+  readonly beforeReceivedAtMs: number;
+}
+
+export interface ReleaseReference {
+  readonly releaseId: string;
+  readonly platform: "ios" | "android";
+  readonly channel: string;
+}
+
+export interface InsightsTimeRange {
+  /** Inclusive UTC Unix timestamp in milliseconds. */
+  readonly start: number;
+  /** Exclusive UTC Unix timestamp in milliseconds. */
+  readonly end: number;
+}
+
+export type InsightsCoverage =
+  | { readonly kind: "complete"; readonly sinceMs: number }
+  | { readonly kind: "partial"; readonly sinceMs: number | null };
+
+export interface ReleaseActivityMetrics {
+  readonly downloads: number;
+  readonly launches: number;
+  readonly failedLaunches: number;
+  /** Omitted for lifetime-only bundle-row reads. */
+  readonly uniqueUsers?: number;
+  /** Daily points, present only for period reads. */
+  readonly series?: readonly {
+    readonly startMs: number;
+    readonly launches: number;
+    readonly failedLaunches: number;
+  }[];
+}
+
+export type InsightsGetReleaseActivityInput =
+  | {
+      readonly releases: readonly ReleaseReference[];
+      readonly timeRange?: InsightsTimeRange;
+      readonly scope?: never;
+    }
+  | {
+      readonly scope: InsightsScope;
+      readonly timeRange: InsightsTimeRange;
+      readonly releases?: never;
+    };
+
+export interface InsightsGetReleaseActivityResult {
+  readonly coverage: InsightsCoverage;
+  readonly data: readonly {
+    readonly release?: ReleaseReference;
+    readonly scope?: InsightsScope;
+    readonly metrics: ReleaseActivityMetrics;
+  }[];
+  readonly measuredAtMs: number;
+}
+
+export interface InsightsGetAppUsageInput {
+  readonly channel: string;
+  readonly platform: "all" | "ios" | "android";
+  readonly appVersion?: string;
+  readonly timeRange: InsightsTimeRange;
+  readonly intervalMs: number;
+}
+
+export interface InsightsGetAppUsageResult {
+  readonly coverage: InsightsCoverage;
+  readonly activeInstallations: number;
+  readonly points: readonly {
+    readonly startMs: number;
+    readonly installations: number;
+  }[];
+  readonly appVersions: readonly string[];
+  readonly versions: readonly {
+    readonly name: string;
+    readonly installations: number;
+  }[];
+  readonly platforms: readonly {
+    readonly name: string;
+    readonly installations: number;
+  }[];
+  readonly bundleDistribution: readonly {
+    readonly appVersion: string;
+    readonly platform: "ios" | "android";
+    readonly releaseId: string | null;
+    readonly installations: number;
+  }[];
+  readonly measuredAtMs: number;
+}
+
+export interface InsightsModel {
+  /**
+   * Persist the immutable event once. A private latest-event index, if used,
+   * advances atomically for a greater (received_at_ms, id). Duplicate event
+   * IDs are complete no-ops, whichever installation sends them.
+   * Retry the identical prepared input after an ambiguous commit outcome.
+   */
+  recordEvent(input: InsightsRecordEventInput): Promise<void>;
+  /**
+   * Descending (received_at_ms, id), in [sinceMs ?? 0, beforeReceivedAtMs).
+   * Apply filters and the exclusive cursor before limit (1..101). Return the
+   * complete matching prefix; native continuation pages must not truncate it.
+   * A global or bundle list may reject a range longer than 90 × 24 hours;
+   * the server asks for older events with an earlier range instead.
+   */
+  listEvents(
+    input: InsightsListEventsInput,
+  ): Promise<readonly BundleEventRow[]>;
+  /**
+   * Choose each installation's greatest (received_at_ms, id) before filtering.
+   * Exact installation lookup returns zero or one canonical event. User lookup
+   * returns current membership ordered by UTF-8 installation ID, exclusive
+   * afterInstallId and limit 1..101. Check lagging index candidates against
+   * canonical state; newly indexed associations may temporarily be absent.
+   */
+  findLatestEvents(
+    input: InsightsFindLatestEventsInput,
+  ): Promise<readonly BundleEventRow[]>;
+  /** Count latest events once per installation, then apply the supplied predicates. */
+  countLatestEvents(input: InsightsCountLatestEventsInput): Promise<number>;
+  /** Count accepted reports in [sinceMs, beforeReceivedAtMs), across all pages. */
+  countEvents(input: InsightsCountEventsInput): Promise<number>;
+  /** Read maintained release/scope summaries without scanning raw events. */
+  getReleaseActivity(
+    input: InsightsGetReleaseActivityInput,
+  ): Promise<InsightsGetReleaseActivityResult>;
+  /** Read maintained App usage summaries and latest-report distribution. */
+  getAppUsage(
+    input: InsightsGetAppUsageInput,
+  ): Promise<InsightsGetAppUsageResult>;
+}

package/src/plugins/insights/overview.spec.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+
+import type { BundleEventRow } from "./eventRow";
+import { insightsOverviewDeltas } from "./overview";
+
+const event = (type: BundleEventRow["type"]): BundleEventRow =>
+  ({
+    id: "01993e00-0000-7000-8000-000000000001",
+    type,
+    install_id: "install-a",
+    user_id: null,
+    from_release_id: type === "UNCHANGED" ? null : "source-release",
+    from_bundle_id: type === "UNCHANGED" ? null : "source-bundle",
+    to_release_id: "destination-release",
+    to_bundle_id: "destination-bundle",
+    platform: "ios",
+    app_version: "1.0.0",
+    channel: "production",
+    metadata: {
+      cohort: "default",
+      update_strategy: null,
+      fingerprint_hash: null,
+      sdk_version: null,
+    },
+    received_at_ms: 3_600_001,
+  }) as BundleEventRow;
+
+describe("Insights overview event contributions", () => {
+  it("attributes recovery failure to the source and readiness to the destination", () => {
+    const rows = insightsOverviewDeltas(event("RECOVERED"));
+    const lifetime = rows.filter(
+      ({ identity }) =>
+        identity.scopeKind === "release" && identity.periodKind === "lifetime",
+    );
+    expect(lifetime).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          identity: expect.objectContaining({ releaseId: "source-release" }),
+          failedLaunches: 1,
+          launches: 0,
+        }),
+        expect.objectContaining({
+          identity: expect.objectContaining({
+            releaseId: "destination-release",
+          }),
+          failedLaunches: 0,
+          launches: 1,
+        }),
+      ]),
+    );
+  });
+
+  it("counts downloads without treating them as launches", () => {
+    const lifetime = insightsOverviewDeltas(event("UPDATE_DOWNLOADED")).find(
+      ({ identity }) =>
+        identity.scopeKind === "release" && identity.periodKind === "lifetime",
+    );
+    expect(lifetime).toMatchObject({
+      downloads: 1,
+      launches: 0,
+      failedLaunches: 0,
+    });
+  });
+});

package/src/plugins/insights/overview.ts

@@ -0,0 +1,214 @@
+import type { BundleEventRow } from "./eventRow";
+
+export type InsightsOverviewIdentity = {
+  readonly scopeKind: "release" | "channel" | "usage" | "distribution";
+  readonly releaseKind: "all" | "specific" | "embedded";
+  readonly releaseId: string;
+  readonly channel: string;
+  readonly platform: "all" | "ios" | "android";
+  readonly appVersionKind: "all" | "specific";
+  readonly appVersion: string;
+  readonly periodKind: "lifetime" | "hour" | "latest";
+  readonly bucketStartMs: number;
+};
+
+export type InsightsOverviewDelta = {
+  readonly identity: InsightsOverviewIdentity;
+  readonly downloads: number;
+  readonly launches: number;
+  readonly failedLaunches: number;
+  readonly launchIdentity?: string;
+  readonly activityIdentity?: string;
+};
+
+const encodeIdentity = (identity: InsightsOverviewIdentity): string =>
+  [
+    identity.scopeKind,
+    identity.releaseKind,
+    identity.releaseId,
+    identity.channel,
+    identity.platform,
+    identity.appVersionKind,
+    identity.appVersion,
+    identity.periodKind,
+    String(identity.bucketStartMs),
+  ]
+    .map((value) => `${new TextEncoder().encode(value).length}:${value}`)
+    .join("");
+
+const fnv = (value: string, seed: bigint): string => {
+  let result = seed;
+  for (const byte of new TextEncoder().encode(value)) {
+    result ^= BigInt(byte);
+    result = BigInt.asUintN(64, result * 0x100000001b3n);
+  }
+  return result.toString(16).padStart(16, "0");
+};
+
+/** A 128-bit hex key for a string: two FNV-1a 64 hashes with different seeds. */
+export const insightsKey = (value: string): string =>
+  `${fnv(value, 0xcbf29ce484222325n)}${fnv(value, 0x84222325cbf29ce4n)}`;
+
+export const insightsOverviewId = (
+  identity: InsightsOverviewIdentity,
+): string => insightsKey(encodeIdentity(identity));
+
+export const insightsOverviewValues = (identity: InsightsOverviewIdentity) => ({
+  id: insightsOverviewId(identity),
+  scope_kind: identity.scopeKind,
+  release_kind: identity.releaseKind,
+  release_id: identity.releaseId,
+  channel: identity.channel,
+  platform: identity.platform,
+  app_version_kind: identity.appVersionKind,
+  app_version: identity.appVersion,
+  period_kind: identity.periodKind,
+  bucket_start_ms: identity.bucketStartMs,
+});
+
+const hour = (value: number): number =>
+  Math.floor(value / 3_600_000) * 3_600_000;
+
+export const currentInsightsReleaseId = (
+  event: BundleEventRow,
+): string | null =>
+  event.type === "UPDATE_DOWNLOADED"
+    ? event.from_release_id
+    : event.to_release_id;
+
+export const insightsDistributionIdentity = (
+  event: BundleEventRow,
+): InsightsOverviewIdentity => {
+  const releaseId = currentInsightsReleaseId(event);
+  return {
+    scopeKind: "distribution",
+    releaseKind: releaseId === null ? "embedded" : "specific",
+    releaseId: releaseId ?? "",
+    channel: event.channel,
+    platform: event.platform,
+    appVersionKind: "specific",
+    appVersion: event.app_version,
+    periodKind: "latest",
+    bucketStartMs: hour(event.received_at_ms),
+  };
+};
+
+export const insightsOverviewDeltas = (
+  event: BundleEventRow,
+): readonly InsightsOverviewDelta[] => {
+  const bucketStartMs = hour(event.received_at_ms);
+  const counters = new Map<string, InsightsOverviewDelta>();
+  const append = (
+    identity: InsightsOverviewIdentity,
+    values: Pick<
+      InsightsOverviewDelta,
+      "downloads" | "launches" | "failedLaunches"
+    > & {
+      readonly launchIdentity?: string;
+      readonly activityIdentity?: string;
+    },
+  ) => {
+    const key = encodeIdentity(identity);
+    const previous = counters.get(key);
+    counters.set(key, {
+      identity,
+      downloads: (previous?.downloads ?? 0) + values.downloads,
+      launches: (previous?.launches ?? 0) + values.launches,
+      failedLaunches: (previous?.failedLaunches ?? 0) + values.failedLaunches,
+      launchIdentity: previous?.launchIdentity ?? values.launchIdentity,
+      activityIdentity: previous?.activityIdentity ?? values.activityIdentity,
+    });
+  };
+  const metric = (
+    releaseId: string | null,
+    values: Pick<
+      InsightsOverviewDelta,
+      "downloads" | "launches" | "failedLaunches"
+    >,
+  ) => {
+    const launchIdentity = values.launches > 0 ? event.install_id : undefined;
+    if (releaseId !== null) {
+      for (const [periodKind, start] of [
+        ["lifetime", 0],
+        ["hour", bucketStartMs],
+      ] as const) {
+        append(
+          {
+            scopeKind: "release",
+            releaseKind: "specific",
+            releaseId,
+            channel: event.channel,
+            platform: event.platform,
+            appVersionKind: "all",
+            appVersion: "",
+            periodKind,
+            bucketStartMs: start,
+          },
+          { ...values, ...(periodKind === "hour" ? { launchIdentity } : {}) },
+        );
+      }
+    }
+    append(
+      {
+        scopeKind: "channel",
+        releaseKind: "all",
+        releaseId: "",
+        channel: event.channel,
+        platform: event.platform,
+        appVersionKind: "all",
+        appVersion: "",
+        periodKind: "hour",
+        bucketStartMs,
+      },
+      { ...values, launchIdentity },
+    );
+  };
+
+  if (event.type === "UPDATE_DOWNLOADED") {
+    metric(event.to_release_id, {
+      downloads: 1,
+      launches: 0,
+      failedLaunches: 0,
+    });
+  } else if (event.type !== "UPDATE_FAILED") {
+    // A failed update is no launch. recordEvent counts a failure itself and
+    // asks for no deltas of it.
+    metric(event.to_release_id, {
+      downloads: 0,
+      launches: 1,
+      failedLaunches: 0,
+    });
+    if (event.type === "RECOVERED") {
+      metric(event.from_release_id, {
+        downloads: 0,
+        launches: 0,
+        failedLaunches: 1,
+      });
+    }
+  }
+
+  for (const platform of [event.platform, "all"] as const) {
+    for (const appVersionKind of ["specific", "all"] as const) {
+      append(
+        {
+          scopeKind: "usage",
+          releaseKind: "all",
+          releaseId: "",
+          channel: event.channel,
+          platform,
+          appVersionKind,
+          appVersion: appVersionKind === "specific" ? event.app_version : "",
+          periodKind: "hour",
+          bucketStartMs,
+        },
+        {
+          downloads: 0,
+          launches: 0,
+          failedLaunches: 0,
+          activityIdentity: event.install_id,
+        },
+      );
+    }
+  }
+  return [...counters.values()];
+};

package/src/{insights → plugins/insights}/provider.spec.ts

@@ -1,7 +1,8 @@
-import type { BundleEventRow, InsightsModel } from "@hot-updater/plugin-core";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { InsightsBadRequestError } from "./errors";
+import type { BundleEventRow } from "./eventRow";
+import type { InsightsModel } from "./modelTypes";
 import { createInsightsProvider } from "./provider";
 
 const eventId = (index: number) =>
@@ -34,7 +35,6 @@ const eventRow = (
     fingerprint_hash: null,
     sdk_version: "2.0.0",
     update_strategy: "appVersion",
-    username: "Jane",
   },
 
   from_bundle_id: "bundle-before",
@@ -408,7 +408,7 @@ describe("createInsightsProvider", () => {
     expect(fixture.countEvents).not.toHaveBeenCalled();
   });
 
-  it("counts whole hours that end with the current one", async () => {
+  it("counts from the UTC day the window reaches into to the end of the current hour", async () => {
     vi.useFakeTimers();
     vi.setSystemTime(new Date("2026-08-12T10:25:00.000Z"));
     const fixture = createModel();
@@ -421,15 +421,15 @@ describe("createInsightsProvider", () => {
       channel: "production",
     });
 
-    const end = Date.parse("2026-08-12T11:00:00.000Z");
+    const start = Date.parse("2026-08-11T00:00:00.000Z");
     expect(overview).toMatchObject({
-      beforeReceivedAtMs: end,
-      sinceMs: end - 24 * 60 * 60 * 1_000,
+      beforeReceivedAtMs: Date.parse("2026-08-12T11:00:00.000Z"),
+      sinceMs: start,
     });
     expect(fixture.countLatestEvents).toHaveBeenCalledWith({
       platform: "ios",
       channel: "production",
-      sinceMs: end - 24 * 60 * 60 * 1_000,
+      sinceMs: start,
     });
   });
 
@@ -442,7 +442,7 @@ describe("createInsightsProvider", () => {
       .mockResolvedValueOnce(7)
       .mockResolvedValueOnce(5)
       .mockResolvedValueOnce(3)
-      .mockResolvedValueOnce(1);
+      .mockResolvedValueOnce(2);
     const provider = createInsightsProvider(fixture.model);
     const scope = { platform: "ios", channel: "production" } as const;
     const result = await provider.getReportingOverview({
@@ -469,15 +469,26 @@ describe("createInsightsProvider", () => {
     expect(result.bundle?.downloadedReports.count).toBe(7);
     expect(result.bundle?.appliedReports.count).toBe(5);
     expect(result.bundle?.recoveredReports.count).toBe(3);
-    expect(result.bundle?.unchangedReports.count).toBe(1);
+    expect(result.bundle?.failedReports.count).toBe(2);
+    // UNCHANGED reports are kept as no events, so no count or list names them.
+    expect(result.bundle).not.toHaveProperty("unchangedReports");
     expect(
       fixture.countEvents.mock.calls.map(([input]) => input.filter),
     ).toEqual([
       { ...scope, type: "UPDATE_DOWNLOADED", toBundleId: "B" },
       { ...scope, type: "UPDATE_APPLIED", toBundleId: "B" },
       { ...scope, type: "RECOVERED", fromBundleId: "B" },
-      { ...scope, type: "UNCHANGED", toBundleId: "B" },
+      { ...scope, type: "UPDATE_FAILED", toBundleId: "B" },
     ]);
+    expect(() =>
+      provider.listEvents({
+        bundle: {
+          ...scope,
+          bundleId: "B",
+          outcome: "unchanged" as "applied",
+        },
+      }),
+    ).toThrow(InsightsBadRequestError);
     await provider.listEvents({
       bundle: { ...scope, bundleId: "B", outcome: "recovered" },
       sinceMs: result.sinceMs,