@hot-updater/server 1.0.0-rc.1 → 1.0.0-rc.2

package/src/insights/domain.ts

@@ -15,17 +15,7 @@ export type CreateBundleEventRequestBase = {
 
 export type CreateBundleEventRequest =
   | (CreateBundleEventRequestBase & {
-      readonly type: "UPDATE_APPLIED";
-      readonly fromBundleId: string;
-      readonly updateStrategy: "fingerprint" | "appVersion";
-    })
-  | (CreateBundleEventRequestBase & {
-      readonly type: "RECOVERED";
-      readonly fromBundleId: string;
-      readonly updateStrategy: "fingerprint" | "appVersion";
-    })
-  | (CreateBundleEventRequestBase & {
-      readonly type: "RELEASE_ADOPTED";
+      readonly type: "UPDATE_APPLIED" | "RECOVERED" | "RELEASE_ADOPTED";
       readonly fromBundleId: string;
       readonly updateStrategy: "fingerprint" | "appVersion";
     })
@@ -35,28 +25,20 @@ export type CreateBundleEventRequest =
       readonly updateStrategy: null;
     });
 
-export type BundleEventSummary = {
-  readonly installed: number;
-  readonly recovered: number;
-};
-
-export type BundleEventSummaryByBundle = BundleEventSummary & {
-  readonly bundleId: string;
-};
-
-export type BundleEventInsightsWindow = "24h" | "7d" | "30d" | "all";
 export type ActiveInstallationWindow = "24h" | "7d" | "30d";
 
-export type InstallationSearchRow = {
+export type EventHistoryRow = {
+  readonly id: string;
   readonly installId: string;
-  readonly username: string | null;
-  readonly userId: string | null;
-  readonly lastKnownBundleId: string;
-  readonly latestStatus:
+  readonly type:
     | "UPDATE_APPLIED"
     | "RECOVERED"
     | "RELEASE_ADOPTED"
     | "UNCHANGED";
+  readonly fromBundleId: string | null;
+  readonly toBundleId: string;
+  readonly username: string | null;
+  readonly userId: string | null;
   readonly platform: "ios" | "android";
   readonly appVersion: string;
   readonly channel: string;
@@ -64,13 +46,17 @@ export type InstallationSearchRow = {
   readonly receivedAtMs: number;
 };
 
-export type InstallationHistoryRow = {
-  readonly id: string;
+export type InstallationHistoryRow = EventHistoryRow & {
   readonly type: "UPDATE_APPLIED" | "RECOVERED";
   readonly fromBundleId: string;
-  readonly toBundleId: string;
+};
+
+export type InstallationRow = {
+  readonly installId: string;
   readonly username: string | null;
   readonly userId: string | null;
+  readonly lastKnownBundleId: string;
+  readonly latestStatus: EventHistoryRow["type"];
   readonly platform: "ios" | "android";
   readonly appVersion: string;
   readonly channel: string;
@@ -78,62 +64,40 @@ export type InstallationHistoryRow = {
   readonly receivedAtMs: number;
 };
 
-export type OffsetPaginationResult<TData> = {
-  readonly data: readonly TData[];
-  readonly pagination: {
-    readonly total: number;
-    readonly limit: number;
-    readonly offset: number;
-  };
+export type CursorPage<T> = {
+  readonly data: readonly T[];
+  readonly nextCursor: string | null;
 };
 
-export type InsightsSeriesPoint = {
-  readonly bucketStartMs: number;
-  readonly value: number;
+export type EventCursorPage<T extends EventHistoryRow> = CursorPage<T> & {
+  readonly beforeReceivedAtMs: number;
 };
 
-export type InsightsCohortPoint = {
-  readonly cohort: string;
-  readonly value: number;
+export type InsightsScope = {
+  readonly platform: "ios" | "android";
+  readonly channel: string;
 };
 
-export type BundleEventInsightsResult = {
-  readonly summary: BundleEventSummary;
-  readonly series: {
-    readonly installed: readonly InsightsSeriesPoint[];
-    readonly recovered: readonly InsightsSeriesPoint[];
-  };
-  readonly cohorts: {
-    readonly installed: readonly InsightsCohortPoint[];
-    readonly recovered: readonly InsightsCohortPoint[];
-  };
-  readonly recentEvents: OffsetPaginationResult<InstallationHistoryRow>;
+export type InsightsBundleSelection = InsightsScope & {
+  readonly bundleId: string;
+  readonly outcome: "applied" | "recovered" | "adopted";
 };
 
-export type BundleEventOverview = {
-  readonly trackedInstallations: number;
-  readonly bundles: readonly {
-    readonly bundleId: string;
-    readonly installations: number;
-  }[];
+export type InsightsCountMeasurement = {
+  readonly count: number;
+  readonly measuredAtMs: number;
 };
 
-export type ActiveInstallationOverview = {
-  readonly asOfMs: number;
+export type ReportingOverview = InsightsScope & {
   readonly window: ActiveInstallationWindow;
-  readonly activeInstallations: number;
-  readonly series: readonly InsightsSeriesPoint[];
-  readonly bundleSeries: readonly {
-    readonly bundleId: string;
-    readonly series: readonly InsightsSeriesPoint[];
-  }[];
-  readonly bundles: readonly {
+  readonly sinceMs: number;
+  readonly beforeReceivedAtMs: number;
+  readonly reportingInstallations: InsightsCountMeasurement;
+  readonly bundle?: {
     readonly bundleId: string;
-    readonly installations: number;
-  }[];
-};
-
-export type ActiveInstallationInput = {
-  readonly window: ActiveInstallationWindow;
-  readonly userId?: string;
+    readonly reportingInstallations: InsightsCountMeasurement;
+    readonly appliedReports: InsightsCountMeasurement;
+    readonly recoveredReports: InsightsCountMeasurement;
+    readonly adoptedReports: InsightsCountMeasurement;
+  };
 };

package/src/insights/errors.ts

@@ -1,10 +1,3 @@
-export class InsightsScanLimitExceededError extends Error {
-  constructor(readonly limit: number) {
-    super(`Insights event scan exceeded ${limit} rows.`);
-    this.name = "InsightsScanLimitExceededError";
-  }
-}
-
 export class InsightsBadRequestError extends Error {
   readonly name = "InsightsBadRequestError";
 }

package/src/insights/eventInput.ts

@@ -1,3 +1,5 @@
+import { createUUIDv7, type BundleEventRow } from "@hot-updater/plugin-core";
+
 import type {
   CreateBundleEventRequest,
   CreateBundleEventRequestBase,
@@ -8,6 +10,7 @@ import {
 } from "./errors";
 
 const MAX_EVENT_STRING_LENGTH = 1_024;
+const MAX_IDENTITY_LENGTH = 255;
 export const EVENT_BODY_MAX_BYTES = 16 * 1_024;
 
 const eventKeys = new Set([
@@ -40,7 +43,10 @@ function requireStringField(
   if (
     typeof value !== "string" ||
     value.length === 0 ||
-    value.length > MAX_EVENT_STRING_LENGTH
+    value.length > MAX_EVENT_STRING_LENGTH ||
+    new TextDecoder("utf-8", { ignoreBOM: true }).decode(
+      new TextEncoder().encode(value),
+    ) !== value
   ) {
     throw new InsightsBadRequestError(`Invalid event field: ${key}`);
   }
@@ -55,6 +61,17 @@ function requireNullableStringField(
   return requireStringField(payload, key);
 }
 
+function requireIdentityField(
+  payload: Readonly<Record<string, unknown>>,
+  key: "installId" | "userId",
+): string {
+  const value = requireStringField(payload, key);
+  if (value.length > MAX_IDENTITY_LENGTH) {
+    throw new InsightsBadRequestError(`Invalid event field: ${key}`);
+  }
+  return value;
+}
+
 async function readBoundedText(request: Request): Promise<string> {
   const contentLength = request.headers.get("content-length");
   const declaredByteLength = Number(contentLength);
@@ -107,11 +124,11 @@ function requireEvent(payload: unknown): CreateBundleEventRequest {
     throw new InsightsBadRequestError("Invalid event field: platform");
   }
   const base: CreateBundleEventRequestBase = {
-    installId: requireStringField(payload, "installId"),
+    installId: requireIdentityField(payload, "installId"),
     toBundleId: requireStringField(payload, "toBundleId"),
     ...(payload.userId === undefined
       ? {}
-      : { userId: requireStringField(payload, "userId") }),
+      : { userId: requireIdentityField(payload, "userId") }),
     ...(payload.username === undefined
       ? {}
       : { username: requireStringField(payload, "username") }),
@@ -166,3 +183,43 @@ export async function parseBundleEventRequest(
   const payload = await parseJson(request);
   return requireEvent(payload);
 }
+
+export function createBundleEventRow(
+  input: CreateBundleEventRequest,
+): BundleEventRow {
+  input = requireEvent(input);
+  const base = {
+    app_version: input.appVersion,
+    channel: input.channel,
+    cohort: input.cohort,
+    fingerprint_hash: input.fingerprintHash,
+    from_release_id: input.fromReleaseId,
+    id: createUUIDv7(),
+    install_id: input.installId,
+    platform: input.platform,
+    received_at_ms: Date.now(),
+    sdk_version: input.sdkVersion ?? null,
+    to_bundle_id: input.toBundleId,
+    to_release_id: input.toReleaseId,
+    user_id: input.userId ?? null,
+    username: input.username ?? null,
+  };
+  switch (input.type) {
+    case "UPDATE_APPLIED":
+    case "RECOVERED":
+    case "RELEASE_ADOPTED":
+      return {
+        ...base,
+        from_bundle_id: input.fromBundleId,
+        type: input.type,
+        update_strategy: input.updateStrategy,
+      };
+    case "UNCHANGED":
+      return {
+        ...base,
+        from_bundle_id: null,
+        type: input.type,
+        update_strategy: null,
+      };
+  }
+}

package/src/insights/insights.integration.spec.ts

@@ -18,6 +18,8 @@ const event = {
   toReleaseId: null,
   type: "UNCHANGED",
   updateStrategy: null,
+  userId: "user-1",
+  username: "Jane",
   sdkVersion: "2.0.0",
 } as const;
 
@@ -33,11 +35,12 @@ afterEach(() => {
 });
 
 describe("createHotUpdater Insights", () => {
-  it("always persists events and serves queries without a server Insights flag", async () => {
+  it("persists an event and serves the lean Insights views", async () => {
     vi.useFakeTimers();
     vi.setSystemTime(new Date("2026-08-12T00:00:00.000Z"));
+    const receivedAtMs = Date.now();
     const database = createInMemoryDatabasePlugin();
-    const append = vi.spyOn(database.models.insights, "append");
+    const append = vi.spyOn(database.models.insights, "record");
     const hotUpdater = createHotUpdater({
       database,
       clientAccess: { type: "public" },
@@ -45,28 +48,173 @@ describe("createHotUpdater Insights", () => {
 
     const ingestion = await hotUpdater.handlers.client(eventRequest());
     vi.advanceTimersByTime(1);
-    const overview = await hotUpdater.handlers.admin(
-      new Request("https://example.com/installations/overview"),
+    const events = await hotUpdater.handlers.admin(
+      new Request("https://example.com/events"),
+    );
+    const installation = await hotUpdater.handlers.admin(
+      new Request("https://example.com/installations/install-1"),
+    );
+    const matches = await hotUpdater.handlers.admin(
+      new Request("https://example.com/installations?userId=user-1"),
+    );
+    const active = await hotUpdater.handlers.admin(
+      new Request(
+        "https://example.com/overview?platform=ios&channel=production&window=24h",
+      ),
     );
 
     expect(ingestion.status).toBe(204);
     expect(append).toHaveBeenCalledWith(
       expect.objectContaining({
-        install_id: "install-1",
-        sdk_version: "2.0.0",
-        to_bundle_id: "bundle-1",
-        type: "UNCHANGED",
+        event: expect.objectContaining({
+          install_id: "install-1",
+          sdk_version: "2.0.0",
+          to_bundle_id: "bundle-1",
+          type: "UNCHANGED",
+        }),
       }),
     );
-    expect(hotUpdater.insights).toMatchObject({
-      mode: "bounded",
-      maxMatchingRows: 50_000,
+    expect(events.status).toBe(200);
+    await expect(events.json()).resolves.toMatchObject({
+      data: [
+        {
+          id: expect.any(String),
+          installId: "install-1",
+          receivedAtMs,
+          type: "UNCHANGED",
+          userId: "user-1",
+          username: "Jane",
+        },
+      ],
+      nextCursor: null,
+    });
+    expect(installation.status).toBe(200);
+    await expect(installation.json()).resolves.toMatchObject({
+      installId: "install-1",
+      latestStatus: "UNCHANGED",
+      userId: "user-1",
+    });
+    expect(matches.status).toBe(200);
+    await expect(matches.json()).resolves.toMatchObject({
+      data: [{ installId: "install-1", userId: "user-1" }],
+      nextCursor: null,
+    });
+    expect(active.status).toBe(200);
+    await expect(active.json()).resolves.toEqual({
+      platform: "ios",
+      channel: "production",
+      sinceMs: Date.now() - 24 * 60 * 60 * 1_000,
+      beforeReceivedAtMs: Date.now(),
+      reportingInstallations: { count: 1, measuredAtMs: Date.now() },
+      window: "24h",
+    });
+  });
+
+  it("serves scoped bundle counts and the same half-open recovery drill-down", async () => {
+    vi.useFakeTimers();
+    const hotUpdater = createHotUpdater({
+      database: createInMemoryDatabasePlugin(),
+      clientAccess: { type: "public" },
+    });
+    const report = async (
+      receivedAtMs: number,
+      overrides: Record<string, unknown>,
+    ) => {
+      vi.setSystemTime(receivedAtMs);
+      const response = await hotUpdater.handlers.client(
+        eventRequest({ ...event, ...overrides }),
+      );
+      expect(response.status).toBe(204);
+    };
+    await report(100, {
+      type: "UPDATE_APPLIED",
+      fromBundleId: "A",
+      toBundleId: "B",
+      updateStrategy: "appVersion",
+    });
+    await report(200, {
+      type: "RECOVERED",
+      fromBundleId: "B",
+      toBundleId: "A",
+      updateStrategy: "appVersion",
+    });
+    await report(300, {
+      installId: "install-2",
+      type: "RELEASE_ADOPTED",
+      fromBundleId: "B",
+      toBundleId: "B",
+      updateStrategy: "appVersion",
+    });
+    await report(400, {
+      installId: "install-3",
+      platform: "android",
+      toBundleId: "B",
     });
+    vi.setSystemTime(500);
+    const overview = await hotUpdater.handlers.admin(
+      new Request(
+        "https://example.com/overview?platform=ios&channel=production&window=24h&bundleId=B",
+      ),
+    );
     expect(overview.status).toBe(200);
-    await expect(overview.json()).resolves.toEqual({
-      bundles: [{ bundleId: "bundle-1", installations: 1 }],
-      trackedInstallations: 1,
+    await expect(overview.json()).resolves.toMatchObject({
+      sinceMs: 0,
+      beforeReceivedAtMs: 500,
+      reportingInstallations: { count: 2 },
+      bundle: {
+        bundleId: "B",
+        reportingInstallations: { count: 1 },
+        appliedReports: { count: 1 },
+        recoveredReports: { count: 1 },
+        adoptedReports: { count: 1 },
+      },
+    });
+    const drilldown = await hotUpdater.handlers.admin(
+      new Request(
+        "https://example.com/events?platform=ios&channel=production&bundleId=B&outcome=recovered&sinceMs=200&beforeReceivedAtMs=300",
+      ),
+    );
+    await expect(drilldown.json()).resolves.toMatchObject({
+      data: [
+        {
+          type: "RECOVERED",
+          fromBundleId: "B",
+          toBundleId: "A",
+          receivedAtMs: 200,
+        },
+      ],
+      nextCursor: null,
+    });
+    const outside = await hotUpdater.handlers.admin(
+      new Request(
+        "https://example.com/events?platform=ios&channel=production&bundleId=B&outcome=recovered&sinceMs=0&beforeReceivedAtMs=200",
+      ),
+    );
+    await expect(outside.json()).resolves.toMatchObject({
+      data: [],
+      nextCursor: null,
+    });
+  });
+
+  it.each([
+    "/overview?window=24h",
+    "/overview?platform=ios&channel=production&platform=android",
+    "/events?bundleId=B",
+    "/events?platform=ios&channel=production&bundleId=B&outcome=UNCHANGED",
+    "/events?sinceMs=20&beforeReceivedAtMs=10",
+    "/installations/install-1/events?platform=ios&channel=production&bundleId=B&outcome=applied",
+  ])("rejects ambiguous or invalid Insights query %s", async (path) => {
+    const hotUpdater = createHotUpdater({
+      database: createInMemoryDatabasePlugin(),
+      clientAccess: { type: "public" },
     });
+    expect(
+      (
+        await hotUpdater.handlers.admin(
+          new Request(`https://example.com${path}`),
+        )
+      ).status,
+    ).toBe(400);
   });
 
   it("checks the official schema before Insights reads and writes", async () => {
@@ -81,7 +229,7 @@ describe("createHotUpdater Insights", () => {
     });
 
     expect((await hotUpdater.handlers.client(eventRequest())).status).toBe(204);
-    await hotUpdater.insights?.getBundleEventOverview();
+    await hotUpdater.insights.listEvents({});
 
     expect(createMigrator).toHaveBeenCalledOnce();
   });
@@ -94,11 +242,11 @@ describe("createHotUpdater Insights", () => {
 
     expect((await hotUpdater.handlers.client(eventRequest())).status).toBe(204);
     const clientQuery = await hotUpdater.handlers.client(
-      new Request("https://example.com/installations/overview"),
+      new Request("https://example.com/events"),
     );
     const adminIngestion = await hotUpdater.handlers.admin(eventRequest());
     const adminQuery = await hotUpdater.handlers.admin(
-      new Request("https://example.com/installations/overview"),
+      new Request("https://example.com/events"),
     );
 
     expect(clientQuery.status).toBe(404);
@@ -123,6 +271,95 @@ describe("createHotUpdater Insights", () => {
     });
   });
 
+  it.each(["installId", "userId"] as const)(
+    "rejects a 256-character event %s",
+    async (field) => {
+      const hotUpdater = createHotUpdater({
+        database: createInMemoryDatabasePlugin(),
+        clientAccess: { type: "public" },
+      });
+
+      const response = await hotUpdater.handlers.client(
+        eventRequest({ ...event, [field]: "x".repeat(256) }),
+      );
+
+      expect(response.status).toBe(400);
+      await expect(response.json()).resolves.toEqual({
+        error: `Invalid event field: ${field}`,
+      });
+    },
+  );
+
+  it("preserves a leading Unicode BOM in exact installation and current-user IDs", async () => {
+    const hotUpdater = createHotUpdater({
+      database: createInMemoryDatabasePlugin(),
+      clientAccess: { type: "public" },
+    });
+    const installId = "\uFEFFinstall";
+    const userId = "\uFEFFuser";
+    expect(
+      (
+        await hotUpdater.handlers.client(
+          eventRequest({ ...event, installId, userId }),
+        )
+      ).status,
+    ).toBe(204);
+    const installation = await hotUpdater.handlers.admin(
+      new Request(
+        `https://example.com/installations/${encodeURIComponent(installId)}`,
+      ),
+    );
+    expect(installation.status).toBe(200);
+    await expect(installation.json()).resolves.toMatchObject({
+      installId,
+      userId,
+    });
+    const matches = await hotUpdater.handlers.admin(
+      new Request(
+        `https://example.com/installations?userId=${encodeURIComponent(userId)}`,
+      ),
+    );
+    expect(matches.status).toBe(200);
+    await expect(matches.json()).resolves.toMatchObject({
+      data: [{ installId, userId }],
+    });
+  });
+
+  it.each(["\uD800", "\uDC00"])(
+    "rejects an unmatched surrogate identity %j",
+    async (installId) => {
+      const hotUpdater = createHotUpdater({
+        database: createInMemoryDatabasePlugin(),
+        clientAccess: { type: "public" },
+      });
+      expect(
+        (
+          await hotUpdater.handlers.client(
+            eventRequest({ ...event, installId }),
+          )
+        ).status,
+      ).toBe(400);
+    },
+  );
+
+  it("rejects 256-character installation query identities", async () => {
+    const hotUpdater = createHotUpdater({
+      database: createInMemoryDatabasePlugin(),
+      clientAccess: { type: "public" },
+    });
+    const tooLong = "x".repeat(256);
+
+    const user = await hotUpdater.handlers.admin(
+      new Request(`https://example.com/installations?userId=${tooLong}`),
+    );
+    const installation = await hotUpdater.handlers.admin(
+      new Request(`https://example.com/installations/${tooLong}`),
+    );
+
+    expect(user.status).toBe(400);
+    expect(installation.status).toBe(400);
+  });
+
   it.each(["fromReleaseId", "toReleaseId"] as const)(
     "rejects an omitted %s instead of treating it as null",
     async (field) => {