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

package/src/adapters/prisma.ts

@@ -1,6 +1,8 @@
 import {
   createDatabasePlugin,
   DatabasePluginInputError,
+  type InsightsRecordInput,
+  type InsightsModel,
 } from "@hot-updater/plugin-core";
 import {
   createDatabasePluginAdapter,
@@ -30,6 +32,7 @@ import { createPrismaOrderBy, createPrismaWhere } from "./prismaQuery";
 import {
   getPrismaDelegate,
   parsePrismaBundleEventRow,
+  parsePrismaInsightsInstallationRow,
   parsePrismaBundleRow,
   parsePrismaChannelRow,
   parsePrismaApiKeyRow,
@@ -69,6 +72,7 @@ const runPrismaTransaction = <TResult>(
   client: PrismaTransactionClient,
   isolationLevel: "default" | "serializable",
   callback: (client: object) => Promise<TResult>,
+  retryUniqueConflict = false,
 ): Promise<TResult> => {
   const execute = () =>
     isolationLevel === "serializable"
@@ -86,7 +90,8 @@ const runPrismaTransaction = <TResult>(
           typeof error !== "object" ||
           error === null ||
           !("code" in error) ||
-          error.code !== "P2034"
+          (error.code !== "P2034" &&
+            !(retryUniqueConflict && error.code === "P2002"))
         ) {
           throw error;
         }
@@ -135,6 +140,8 @@ const findMany = async (
       return parsePrismaRows(rows, parsePrismaPatchRow);
     case "bundle_events":
       return parsePrismaRows(rows, parsePrismaBundleEventRow);
+    case "bundle_installations":
+      return parsePrismaRows(rows, parsePrismaInsightsInstallationRow);
     case "channels":
       return parsePrismaRows(rows, parsePrismaChannelRow);
     case "api_keys":
@@ -218,7 +225,9 @@ const createCrudImplementation = (
       const where =
         input.model === "channels"
           ? { name: input.data.name }
-          : { hash: input.data.hash };
+          : input.model === "api_keys"
+            ? { hash: input.data.hash }
+            : { install_id: input.data.install_id };
       row = await delegate.upsert({
         where,
         create: input.data,
@@ -234,6 +243,8 @@ const createCrudImplementation = (
         return parsePrismaPatchRow(row);
       case "bundle_events":
         return parsePrismaBundleEventRow(row);
+      case "bundle_installations":
+        return parsePrismaInsightsInstallationRow(row);
       case "channels":
         return parsePrismaChannelRow(row);
       case "api_keys":
@@ -245,6 +256,36 @@ const createCrudImplementation = (
     }
   },
   update: async (input) => {
+    if (input.model === "bundle_installations") {
+      const installId = input.where.find(
+        (item) =>
+          item.field === "install_id" &&
+          (item.operator === undefined || item.operator === "eq") &&
+          typeof item.value === "string",
+      )?.value;
+      if (typeof installId !== "string") {
+        throw new PrismaAdapterError(
+          "bundle_installations update requires install_id",
+        );
+      }
+      const delegate = getPrismaDelegate(client, "bundle_installations");
+      if (delegate.updateMany === undefined) {
+        throw new PrismaAdapterError(
+          'model delegate "bundle_installations" requires updateMany',
+        );
+      }
+      const result = await delegate.updateMany({
+        where: createPrismaWhere(input.where, provider),
+        data: input.update,
+      });
+      if (result.count === 0) return null;
+      const stored = await delegate.findFirst({
+        where: { install_id: installId },
+      });
+      return stored === null
+        ? null
+        : parsePrismaInsightsInstallationRow(stored);
+    }
     const id = input.where[0]?.value;
     if (typeof id !== "string") {
       throw new PrismaAdapterError(
@@ -343,6 +384,8 @@ const createCrudImplementation = (
         return parsePrismaReleaseRow(row);
       case "release_catalogs":
         return parsePrismaReleaseCatalogRow(row);
+      case "bundle_installations":
+        return parsePrismaInsightsInstallationRow(row);
     }
   },
   findMany: (input) => findMany(client, input, provider),
@@ -356,6 +399,48 @@ const createPrismaImplementation = (
   const crud = createCrudImplementation(client, provider, relationMode);
   const implementation: DatabasePluginImplementation = {
     ...crud,
+    recordInsights: (input: InsightsRecordInput) => {
+      if (!hasCallbackTransaction(client)) {
+        throw new PrismaAdapterError(
+          "Insights recording requires callback transactions",
+        );
+      }
+      return runPrismaTransaction(
+        client,
+        "serializable",
+        async (transactionClient) => {
+          const events = getPrismaDelegate(transactionClient, "bundle_events");
+          if (
+            (await events.findFirst({ where: { id: input.event.id } })) !== null
+          )
+            return;
+          await events.create({ data: input.event });
+          const installations = getPrismaDelegate(
+            transactionClient,
+            "bundle_installations",
+          );
+          const existing = await installations.findFirst({
+            where: { install_id: input.installation.install_id },
+          });
+          if (existing === null) {
+            await installations.create({ data: input.installation });
+            return;
+          }
+          const current = parsePrismaInsightsInstallationRow(existing);
+          if (
+            current.received_at_ms > input.installation.received_at_ms ||
+            (current.received_at_ms === input.installation.received_at_ms &&
+              current.id >= input.installation.id)
+          )
+            return;
+          await installations.update({
+            where: { install_id: input.installation.install_id },
+            data: input.installation,
+          });
+        },
+        true,
+      );
+    },
     deleteChannel: (input) => {
       if (!hasCallbackTransaction(client)) {
         throw new PrismaAdapterError(
@@ -442,10 +527,25 @@ export const prismaAdapter = (
       config.provider,
     ),
   );
+  const unsupportedMssqlInsights = async (): Promise<never> => {
+    throw new PrismaAdapterError(
+      "SQL Server Insights is unsupported: string keys pad trailing spaces and do not provide the required exact UTF-8 identity ordering",
+    );
+  };
+  const insights: InsightsModel =
+    config.provider === "mssql"
+      ? {
+          record: unsupportedMssqlInsights,
+          listEvents: unsupportedMssqlInsights,
+          findInstallations: unsupportedMssqlInsights,
+          countInstallations: unsupportedMssqlInsights,
+          countEvents: unsupportedMssqlInsights,
+        }
+      : adapter.models.insights;
   return Object.assign(
     createDatabasePlugin({
       name: "prisma",
-      models: adapter.models,
+      models: { ...adapter.models, insights },
       commit: adapter.commit,
     }),
     {

package/src/adapters/prismaRows.ts

@@ -4,6 +4,7 @@ import type {
   BundleRow,
   ChannelRow,
   ApiKeyRow,
+  InsightsInstallationRow,
   ReleaseCatalogRow,
   ReleaseRow,
 } from "@hot-updater/plugin-core";
@@ -19,7 +20,9 @@ export type PrismaDelegate = {
   readonly findFirst: (args?: PrismaQuery) => Promise<unknown>;
   readonly findMany: (args?: PrismaQuery) => Promise<readonly unknown[]>;
   readonly update: (args: PrismaQuery) => Promise<unknown>;
-  readonly updateMany?: (args: PrismaQuery) => Promise<unknown>;
+  readonly updateMany?: (
+    args: PrismaQuery,
+  ) => Promise<{ readonly count: number }>;
   readonly upsert: (args: PrismaQuery) => Promise<unknown>;
 };
 
@@ -48,6 +51,7 @@ const modelDelegates = {
   bundles: "bundles",
   bundle_patches: "bundle_patches",
   bundle_events: "bundle_events",
+  bundle_installations: "bundle_installations",
   channels: "channels",
   api_keys: "api_keys",
   releases: "releases",
@@ -196,6 +200,38 @@ export const parsePrismaBundleEventRow = (value: unknown): BundleEventRow => {
   } as BundleEventRow;
 };
 
+export const parsePrismaInsightsInstallationRow = (
+  value: unknown,
+): InsightsInstallationRow => {
+  if (!isRecord(value)) {
+    throw new PrismaAdapterError("invalid installation row");
+  }
+  const platform = readString(value, "platform");
+  const type = readString(value, "type");
+  if (
+    (platform !== "ios" && platform !== "android") ||
+    (type !== "UPDATE_APPLIED" &&
+      type !== "RECOVERED" &&
+      type !== "RELEASE_ADOPTED" &&
+      type !== "UNCHANGED")
+  ) {
+    throw new PrismaAdapterError("invalid installation fields");
+  }
+  return {
+    install_id: readString(value, "install_id"),
+    id: readString(value, "id"),
+    user_id: readNullableString(value, "user_id"),
+    username: readNullableString(value, "username"),
+    to_bundle_id: readString(value, "to_bundle_id"),
+    type,
+    platform,
+    app_version: readString(value, "app_version"),
+    channel: readString(value, "channel"),
+    cohort: readString(value, "cohort"),
+    received_at_ms: readNumber(value, "received_at_ms"),
+  };
+};
+
 export const parsePrismaApiKeyRow = (value: unknown): ApiKeyRow => {
   if (!isRecord(value)) {
     throw new PrismaAdapterError("invalid API key row");

package/src/adapters/prismaTestClient.ts

@@ -4,9 +4,11 @@ import type {
   BundleRow,
   ChannelRow,
   ApiKeyRow,
+  InsightsInstallationRow,
   ReleaseCatalogRow,
   ReleaseRow,
 } from "@hot-updater/plugin-core";
+import { compareInsightsText } from "@hot-updater/plugin-core";
 
 type Row =
   | BundleEventRow
@@ -14,6 +16,7 @@ type Row =
   | BundleRow
   | ChannelRow
   | ApiKeyRow
+  | InsightsInstallationRow
   | ReleaseRow
   | ReleaseCatalogRow;
 type Table = Row[];
@@ -21,6 +24,7 @@ type Tables = {
   bundle_patches: Table;
   bundles: Table;
   bundle_events: Table;
+  bundle_installations: Table;
   channels: Table;
   api_keys: Table;
   releases: Table;
@@ -60,7 +64,7 @@ const compare = (left: unknown, right: unknown): number => {
     return left - right;
   }
   if (typeof left === "string" && typeof right === "string") {
-    return left.localeCompare(right);
+    return compareInsightsText(left, right);
   }
   return 0;
 };
@@ -71,7 +75,12 @@ const normalize = (value: unknown, insensitive: boolean): unknown =>
 const readField = (row: Row, field: string): unknown =>
   Object.entries(row).find(([key]) => key === field)?.[1];
 
-const rowKey = (row: Row): string => ("id" in row ? row.id : row.scope_key);
+const rowKey = (model: keyof Tables, row: Row): string =>
+  model === "bundle_installations" && "install_id" in row
+    ? row.install_id
+    : "id" in row
+      ? row.id
+      : row.scope_key;
 
 const matchesCondition = (current: unknown, condition: unknown): boolean => {
   if (!isRecord(condition)) return Object.is(current, condition);
@@ -190,7 +199,9 @@ const createDelegate = (tables: Tables, model: keyof Tables, hooks: Hooks) => ({
   count: async (args?: QueryArgs): Promise<number> =>
     tables[model].filter((row) => matchesWhere(row, args?.where)).length,
   create: async ({ data }: CreateArgs): Promise<Row> => {
-    if (tables[model].some((row) => rowKey(row) === rowKey(data))) {
+    if (
+      tables[model].some((row) => rowKey(model, row) === rowKey(model, data))
+    ) {
       throw new PrismaTestConstraintError("duplicate id");
     }
     if (
@@ -220,7 +231,7 @@ const createDelegate = (tables: Tables, model: keyof Tables, hooks: Hooks) => ({
       matchesWhere(row, args?.where),
     );
     if (model === "bundles") {
-      const ids = new Set(selected.map(rowKey));
+      const ids = new Set(selected.map((row) => rowKey(model, row)));
       if (
         tables.releases.some(
           (row) =>
@@ -293,7 +304,9 @@ const createDelegate = (tables: Tables, model: keyof Tables, hooks: Hooks) => ({
       tables[model][index] = updated;
       return structuredClone(updated);
     }
-    if (tables[model].some((row) => rowKey(row) === rowKey(create))) {
+    if (
+      tables[model].some((row) => rowKey(model, row) === rowKey(model, create))
+    ) {
       throw new PrismaTestConstraintError("duplicate id");
     }
     assertReferences(tables, model, create);
@@ -304,6 +317,7 @@ const createDelegate = (tables: Tables, model: keyof Tables, hooks: Hooks) => ({
 
 const createClient = (tables: Tables, hooks: Hooks) => ({
   bundle_events: createDelegate(tables, "bundle_events", hooks),
+  bundle_installations: createDelegate(tables, "bundle_installations", hooks),
   bundle_patches: createDelegate(tables, "bundle_patches", hooks),
   bundles: createDelegate(tables, "bundles", hooks),
   channels: createDelegate(tables, "channels", hooks),
@@ -317,6 +331,7 @@ export const createPrismaTestHarness = () => {
     bundle_patches: [],
     bundles: [],
     bundle_events: [],
+    bundle_installations: [],
     channels: [],
     api_keys: [],
     releases: [],
@@ -347,6 +362,7 @@ export const createPrismaTestHarness = () => {
         tables.bundle_patches = transactionTables.bundle_patches;
         tables.bundles = transactionTables.bundles;
         tables.bundle_events = transactionTables.bundle_events;
+        tables.bundle_installations = transactionTables.bundle_installations;
         tables.channels = transactionTables.channels;
         tables.api_keys = transactionTables.api_keys;
         tables.releases = transactionTables.releases;
@@ -387,6 +403,7 @@ export const createPrismaTestHarness = () => {
       tables.bundle_patches = [];
       tables.bundles = [];
       tables.bundle_events = [];
+      tables.bundle_installations = [];
       tables.channels = [];
       tables.api_keys = [];
       tables.releases = [];

package/src/apiKeys.integration.spec.ts

@@ -31,7 +31,7 @@ describe("createHotUpdater API keys", () => {
     ).toThrow("clientAccess.headerName must be a valid header name.");
   });
 
-  it("protects only client OTA and Analytics write routes", async () => {
+  it("protects only client OTA and Insights write routes", async () => {
     const database = createInMemoryDatabasePlugin();
     await registerApiKey({
       apiKeys: database.models.apiKeys,
@@ -59,7 +59,7 @@ describe("createHotUpdater API keys", () => {
     expect(
       (
         await hotUpdater.handlers.admin(
-          withApiKey("https://example.com/installations/overview"),
+          withApiKey("https://example.com/events"),
         )
       ).status,
     ).toBe(200);
@@ -86,7 +86,7 @@ describe("createHotUpdater API keys", () => {
     expect(revoked).not.toHaveProperty("hash");
   });
 
-  it("authenticates before parsing Analytics event bodies", async () => {
+  it("authenticates before parsing Insights event bodies", async () => {
     const database = createInMemoryDatabasePlugin();
     await registerApiKey({
       apiKeys: database.models.apiKeys,

package/src/createHotUpdaterCore.ts

@@ -1,10 +1,9 @@
 import {
   assertStorageOperations,
+  type InsightsModel,
   type StoragePlugin,
 } from "@hot-updater/plugin-core";
 
-import { createAnalyticsProvider } from "./analytics/bounded/provider";
-import type { AnalyticsProvider } from "./analytics/types";
 import {
   authenticateApiKey,
   createApiKeyManagement,
@@ -20,17 +19,19 @@ import {
   isDatabasePlugin,
 } from "./db/types";
 import { createHotUpdaterHandlers, type HotUpdaterHandlers } from "./handler";
+import { createInsightsProvider } from "./insights/provider";
+import type { InsightsProvider } from "./insights/types";
 import { createStorageAccess } from "./storageAccess";
 
 export type RuntimeHotUpdaterAPI = DatabaseAPI & {
   readonly handlers: HotUpdaterHandlers;
   readonly adapterName: string;
   /**
-   * Built-in Analytics provider. Client ingestion and admin query routes are
-   * always mounted; React Native clients independently opt into lifecycle
-   * reporting with `HotUpdater.init({ analytics: true })`.
+   * Built-in Insights provider. Client ingestion and admin query routes are
+   * always mounted; React Native clients report lifecycle events by default
+   * and can opt out with `HotUpdater.init({ insights: false })`.
    */
-  readonly analytics: AnalyticsProvider;
+  readonly insights: InsightsProvider;
   /**
    * In-process API key lifecycle operations for trusted server tooling.
    * Creation returns the plaintext once; list and revoke expose only metadata.
@@ -44,7 +45,7 @@ export type HotUpdaterAPI = RuntimeHotUpdaterAPI;
 export type ClientAccessPolicy =
   | {
       /**
-       * Leaves Release Catalog, artifact, and Analytics ingestion routes
+       * Leaves Release Catalog, artifact, and Insights ingestion routes
        * publicly accessible without a client credential.
        */
       readonly type: "public";
@@ -52,7 +53,7 @@ export type ClientAccessPolicy =
   | {
       /**
        * Requires a key registered in `database.models.apiKeys` for
-       * Release Catalog, artifact, and Analytics ingestion requests.
+       * Release Catalog, artifact, and Insights ingestion requests.
        */
       readonly type: "api-key";
       /**
@@ -168,16 +169,29 @@ export function createHotUpdaterCore(
     readStorageText,
   });
   const clientAccess = normalizeClientAccess(options.clientAccess);
-  const analytics = createAnalyticsProvider({
-    async append(row) {
+  const insightsModel: InsightsModel = {
+    async record(input) {
       await assertSchemaReady();
-      return plugin.models.analytics.append(row);
+      return plugin.models.insights.record(input);
     },
-    async scan(input) {
+    async listEvents(input) {
       await assertSchemaReady();
-      return plugin.models.analytics.scan(input);
+      return plugin.models.insights.listEvents(input);
     },
-  });
+    async findInstallations(input) {
+      await assertSchemaReady();
+      return plugin.models.insights.findInstallations(input);
+    },
+    async countInstallations(input) {
+      await assertSchemaReady();
+      return plugin.models.insights.countInstallations(input);
+    },
+    async countEvents(input) {
+      await assertSchemaReady();
+      return plugin.models.insights.countEvents(input);
+    },
+  };
+  const insights = createInsightsProvider(insightsModel);
   const apiKeys = createApiKeyManagement({
     apiKeys: plugin.models.apiKeys,
     beforeOperation: assertSchemaReady,
@@ -185,7 +199,7 @@ export function createHotUpdaterCore(
 
   const handlers = createHotUpdaterHandlers(
     core.api,
-    analytics,
+    insights,
     clientAccess.type === "api-key"
       ? {
           authenticate: (request) =>
@@ -204,7 +218,7 @@ export function createHotUpdaterCore(
   const api: RuntimeHotUpdaterAPI = Object.assign(
     {
       adapterName: adapterCapabilities.adapterName ?? core.adapterName,
-      analytics,
+      insights,
       apiKeys,
       handlers,
     },

package/src/db/databasePluginUpdateCheck.bench.ts

@@ -54,6 +54,9 @@ class BenchmarkMutationError extends Error {
 
 const name = "release-catalog-benchmark";
 const adapter = createDatabasePluginAdapter(name, {
+  async recordInsights() {
+    throw new BenchmarkMutationError();
+  },
   async count() {
     return 0;
   },

package/src/db/fixedMigrator.spec.ts

@@ -1,11 +1,14 @@
 import { DatabaseSync, type SqliteValue } from "node:sqlite";
 
 import { PGlite } from "@electric-sql/pglite";
+import { toInsightsInstallationRow } from "@hot-updater/plugin-core";
 import { Kysely, SqliteDialect } from "kysely";
 import { PGliteDialect } from "kysely-pglite-dialect";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
+import { createBundleEventRowFixture } from "../../../test-utils/src/databaseTestFixtures";
 import { createInMemoryDatabasePlugin } from "../../../test-utils/test/inMemoryDatabasePlugin";
+import { kyselyAdapter } from "../adapters/kysely";
 import { createDatabasePluginCore } from "./databasePluginCore";
 import { createKyselyMigrator } from "./fixedMigrator";
 import { createSchemaReadinessChecker } from "./schemaReadiness";
@@ -54,6 +57,68 @@ describe("Kysely migrator", () => {
     await Promise.all(databases.splice(0).map((db) => db.close()));
   });
 
+  it("creates the final Insights access paths in the initial schema", async () => {
+    const database = new PGlite();
+    databases.push(database);
+    const kysely = new Kysely<SettingsDatabase>({
+      dialect: new PGliteDialect(database),
+    });
+    kyselyInstances.push(kysely);
+    const migrator = createKyselyMigrator({
+      db: kysely,
+      provider: "postgresql",
+    });
+    await expect(migrator.next()).resolves.toEqual({ version: "1.0.0" });
+    await expect(migrator.previous()).resolves.toBeUndefined();
+    const migration = await migrator.migrateToLatest();
+    await migration.execute();
+    await expect(migrator.getVersion()).resolves.toBe("1.0.0");
+    const plugin = kyselyAdapter({ db: kysely, provider: "postgresql" });
+    const event = createBundleEventRowFixture("706", 100);
+    const input = { event, installation: toInsightsInstallationRow(event) };
+    await plugin.models.insights.record(input);
+
+    const repeated = await migrator.migrateToLatest();
+    expect(repeated.operations).toEqual([]);
+    expect(repeated.getSQL?.()).toBe("");
+    await repeated.execute();
+    await expect(migrator.next()).resolves.toBeUndefined();
+    await expect(
+      plugin.models.insights.findInstallations({ installId: event.install_id }),
+    ).resolves.toEqual([input.installation]);
+    await expect(
+      plugin.models.insights.countEvents({
+        filter: {
+          platform: "ios",
+          channel: "production",
+          type: "UPDATE_APPLIED",
+          toBundleId: event.to_bundle_id,
+        },
+        sinceMs: 0,
+        beforeReceivedAtMs: 101,
+      }),
+    ).resolves.toBe(1);
+    const indexes = await database.query<{ indexname: string }>(
+      "select indexname from pg_indexes where tablename in ('bundle_events', 'bundle_installations')",
+    );
+    expect(indexes.rows.map(({ indexname }) => indexname)).toEqual(
+      expect.arrayContaining([
+        "bundle_events_from_bundle_idx",
+        "bundle_events_to_bundle_idx",
+        "bundle_installations_scope_idx",
+        "bundle_installations_bundle_idx",
+      ]),
+    );
+    await database.exec("set enable_seqscan = off");
+    const plan = await database.query<{ "QUERY PLAN": string }>(
+      "explain select * from bundle_events where type = 'UPDATE_APPLIED' and platform = 'ios' and channel = 'production' and to_bundle_id = $1 and received_at_ms < 101 order by received_at_ms desc, id desc limit 10",
+      [event.to_bundle_id],
+    );
+    expect(plan.rows.map((row) => row["QUERY PLAN"]).join("\n")).toContain(
+      "bundle_events_to_bundle_idx",
+    );
+  });
+
   it("creates schema 1.0.0 from an empty database", async () => {
     const database = new PGlite();
     databases.push(database);