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

package/src/db/schemaGenerators.ts

@@ -7,11 +7,13 @@ import {
   type HotUpdaterTableSchema,
   type HotUpdaterVersionedSchema,
 } from "../schema/types";
+import { getInsightsCollationSql } from "./schema/insightsCollation";
 import {
   getHotUpdaterSchemaVersion,
   hotUpdaterSchema,
   schemaIndexAppliesToProvider,
 } from "./schema/registry";
+import { getSqlType } from "./schema/sql";
 import type { ORMProvider, ORMSQLProvider, SchemaGenerator } from "./types";
 import { getSQLProvider } from "./types";
 
@@ -28,6 +30,7 @@ const toPascalCase = (value: string): string =>
     .join("");
 
 const prismaDb = (type: HotUpdaterColumnType, provider: ORMProvider) => {
+  if (provider === "cockroachdb" && type === "uuid") return " @db.Uuid";
   if (provider === "postgresql") {
     if (type === "uuid") return " @db.Uuid";
     if (type.startsWith("varchar")) {
@@ -154,19 +157,33 @@ const prismaIndexes = (
 export const generatePrismaSchema = (
   provider: ORMProvider,
   schema: HotUpdaterVersionedSchema = hotUpdaterSchema,
-) =>
-  schema.tables
-    .map((table) => {
-      const lines = [
-        ...table.columns.map((column) => prismaField(column, provider)),
-        ...prismaRelationFields(table, schema),
-        ...prismaIndexes(table, provider),
-      ];
-      return `model ${table.ormName} {\n${lines
-        .map((line) => `  ${line}`)
-        .join("\n")}\n}`;
-    })
-    .join("\n\n");
+) => {
+  const sqlProvider = getSQLProvider(provider);
+  const collationSql = sqlProvider ? getInsightsCollationSql(sqlProvider) : [];
+  const header =
+    collationSql.length === 0
+      ? ""
+      : [
+          "// Apply these statements in the initial Prisma SQL migration to preserve exact Insights identities and cursors:",
+          ...collationSql.map((statement) => `// ${statement};`),
+          "",
+        ].join("\n");
+  return (
+    header +
+    schema.tables
+      .map((table) => {
+        const lines = [
+          ...table.columns.map((column) => prismaField(column, provider)),
+          ...prismaRelationFields(table, schema),
+          ...prismaIndexes(table, provider),
+        ];
+        return `model ${table.ormName} {\n${lines
+          .map((line) => `  ${line}`)
+          .join("\n")}\n}`;
+      })
+      .join("\n\n")
+  );
+};
 
 const drizzleImportSource = (provider: ORMSQLProvider) =>
   provider === "sqlite"
@@ -186,6 +203,18 @@ const drizzleColumnFn = (
   column: HotUpdaterColumnSchema,
   provider: ORMSQLProvider,
 ): { code: string; imports: readonly string[] } => {
+  const collation = column.providerCollations?.[provider];
+  if (collation !== undefined) {
+    const charset =
+      provider === "mysql"
+        ? ` character set ${collation === "ascii_bin" ? "ascii" : "utf8mb4"}`
+        : "";
+    const dataType = `${getSqlType(column.type, provider)}${charset} collate ${collation}`;
+    return {
+      code: `customType<{ data: string }>({ dataType: () => ${literal(dataType)} })(${literal(column.ormName)})`,
+      imports: ["customType"],
+    };
+  }
   if (provider === "sqlite") {
     if (column.type === "bool") {
       return {

package/src/db/types.spec.ts

@@ -22,9 +22,16 @@ describe("isDatabasePlugin", () => {
         bundles: { ...plugin.models.bundles, findMany: null },
       },
     };
-    const missingAnalytics = {
+    const missingInsights = {
       ...plugin,
-      models: { ...plugin.models, analytics: undefined },
+      models: { ...plugin.models, insights: undefined },
+    };
+    const malformedInsights = {
+      ...plugin,
+      models: {
+        ...plugin.models,
+        insights: { ...plugin.models.insights, listEvents: null },
+      },
     };
     const malformedChannels = {
       ...plugin,
@@ -47,7 +54,8 @@ describe("isDatabasePlugin", () => {
 
     expect(isDatabasePlugin(factory)).toBe(false);
     expect(isDatabasePlugin(malformedBundles)).toBe(false);
-    expect(isDatabasePlugin(missingAnalytics)).toBe(false);
+    expect(isDatabasePlugin(missingInsights)).toBe(false);
+    expect(isDatabasePlugin(malformedInsights)).toBe(false);
     expect(isDatabasePlugin(malformedChannels)).toBe(false);
     expect(isDatabasePlugin(malformedApiKeys)).toBe(false);
     expect(isDatabasePlugin(malformedDispose)).toBe(false);

package/src/db/types.ts

@@ -123,13 +123,19 @@ export function isDatabasePlugin(plugin: unknown): plugin is DatabasePlugin {
     typeof plugin.models.channels.list === "function" &&
     "delete" in plugin.models.channels &&
     typeof plugin.models.channels.delete === "function" &&
-    "analytics" in plugin.models &&
-    typeof plugin.models.analytics === "object" &&
-    plugin.models.analytics !== null &&
-    "append" in plugin.models.analytics &&
-    typeof plugin.models.analytics.append === "function" &&
-    "scan" in plugin.models.analytics &&
-    typeof plugin.models.analytics.scan === "function" &&
+    "insights" in plugin.models &&
+    typeof plugin.models.insights === "object" &&
+    plugin.models.insights !== null &&
+    "recordEvent" in plugin.models.insights &&
+    typeof plugin.models.insights.recordEvent === "function" &&
+    "listEvents" in plugin.models.insights &&
+    typeof plugin.models.insights.listEvents === "function" &&
+    "findLatestEvents" in plugin.models.insights &&
+    typeof plugin.models.insights.findLatestEvents === "function" &&
+    "countEvents" in plugin.models.insights &&
+    typeof plugin.models.insights.countEvents === "function" &&
+    "countLatestEvents" in plugin.models.insights &&
+    typeof plugin.models.insights.countLatestEvents === "function" &&
     "apiKeys" in plugin.models &&
     typeof plugin.models.apiKeys === "object" &&
     plugin.models.apiKeys !== null &&

package/src/handler-standalone.integration.spec.ts

@@ -156,7 +156,7 @@ const commitTestRelease = async (
 };
 
 describe("Handler <-> Standalone Repository Integration", () => {
-  it("uses Standalone for bundle management and the server database for Analytics", async () => {
+  it("uses Standalone for bundle management and the server database for Insights", async () => {
     const bundleId = uuidv7();
     const installId = "standalone-install";
     await createStandaloneClient().insertBundle(
@@ -186,15 +186,13 @@ describe("Handler <-> Standalone Repository Integration", () => {
         }),
       }),
     );
-    const overview = await api.handlers.admin(
-      new Request(`${baseUrl}/installations/overview`),
-    );
+    const events = await api.handlers.admin(new Request(`${baseUrl}/events`));
 
     expect(ingestion.status).toBe(204);
-    expect(overview.status).toBe(200);
-    await expect(overview.json()).resolves.toEqual({
-      bundles: [{ bundleId, installations: 1 }],
-      trackedInstallations: 1,
+    expect(events.status).toBe(200);
+    await expect(events.json()).resolves.toMatchObject({
+      data: [{ installId, toBundleId: bundleId, type: "UPDATE_APPLIED" }],
+      nextCursor: null,
     });
   });
 

package/src/handler.ts

@@ -1,9 +1,3 @@
-import {
-  createAnalyticsRouteHandlers,
-  registerAnalyticsAdminRoutes,
-  registerAnalyticsClientRoutes,
-} from "./analytics/routes";
-import type { AnalyticsProvider } from "./analytics/types";
 import { createBundleRouteHandlers } from "./handlerBundleRoutes";
 import { HandlerBadRequestError } from "./handlerErrors";
 import { createReleaseCatalogRouteHandlers } from "./handlerReleaseCatalogRoutes";
@@ -15,6 +9,12 @@ import type {
   RouteHandler,
 } from "./handlerTypes";
 import { createVersionRouteHandlers } from "./handlerVersionRoutes";
+import {
+  createInsightsRouteHandlers,
+  registerInsightsAdminRoutes,
+  registerInsightsClientRoutes,
+} from "./insights/routes";
+import type { InsightsProvider } from "./insights/types";
 import { addRoute, createRouter, findRoute } from "./internalRouter";
 
 export type {
@@ -142,7 +142,7 @@ export function createHandlers(api: HandlerAPI): HotUpdaterHandlers {
 
 export function createHotUpdaterHandlers(
   api: HandlerAPI,
-  analytics?: AnalyticsProvider,
+  insights?: InsightsProvider,
   apiKeyAuth?: {
     readonly authenticate: (request: Request) => Promise<boolean>;
     readonly headerName: string;
@@ -157,7 +157,7 @@ export function createHotUpdaterHandlers(
     ...createReleaseCatalogRouteHandlers(apiKeyAuth?.headerName),
     ...createReleaseManagementRouteHandlers(),
     ...createBundleRouteHandlers(),
-    ...(analytics === undefined ? {} : createAnalyticsRouteHandlers(analytics)),
+    ...(insights === undefined ? {} : createInsightsRouteHandlers(insights)),
     ...(downloadStorageObject === undefined
       ? {}
       : {
@@ -196,8 +196,8 @@ export function createHotUpdaterHandlers(
     "/artifacts/:targetBundleId/from/:currentBundleId",
     "artifact",
   );
-  if (analytics !== undefined) {
-    registerAnalyticsClientRoutes(addClientRoute);
+  if (insights !== undefined) {
+    registerInsightsClientRoutes(addClientRoute);
   }
 
   const adminRouter = createRouter<string>();
@@ -224,8 +224,8 @@ export function createHotUpdaterHandlers(
   addAdminRoute("POST", "/bundles", "createBundles");
   addAdminRoute("PATCH", "/bundles/:id", "updateBundle");
   addAdminRoute("DELETE", "/bundles/:id", "deleteBundle");
-  if (analytics !== undefined) {
-    registerAnalyticsAdminRoutes(addAdminRoute);
+  if (insights !== undefined) {
+    registerInsightsAdminRoutes(addAdminRoute);
   }
 
   return Object.freeze({

package/src/index.ts

@@ -4,9 +4,9 @@ export type {
   HotUpdaterHandler,
   HotUpdaterHandlers,
 } from "./handler";
-export { createAnalyticsProvider } from "./analytics/bounded/provider";
-export type * from "./analytics/domain";
-export type { AnalyticsProvider } from "./analytics/types";
+export { createInsightsProvider } from "./insights/provider";
+export type * from "./insights/domain";
+export type * from "./insights/types";
 export {
   API_KEY_HEADER_NAME,
   createApiKey,

package/src/insights/domain.ts

@@ -0,0 +1,106 @@
+export type CreateBundleEventRequestBase = {
+  readonly installId: string;
+  readonly toBundleId: string;
+  readonly userId?: string;
+  readonly username?: string;
+  readonly platform: "ios" | "android";
+  readonly appVersion: string;
+  readonly channel: string;
+  readonly cohort: string;
+  readonly fingerprintHash: string | null;
+  readonly sdkVersion?: string | null;
+  readonly fromReleaseId: string | null;
+  readonly toReleaseId: string | null;
+};
+
+export type CreateBundleEventRequest =
+  | (CreateBundleEventRequestBase & {
+      readonly type: "UPDATE_DOWNLOADED" | "UPDATE_APPLIED" | "RECOVERED";
+      readonly fromBundleId: string;
+      readonly updateStrategy: "fingerprint" | "appVersion";
+    })
+  | (CreateBundleEventRequestBase & {
+      readonly type: "UNCHANGED";
+      readonly fromBundleId: null;
+      readonly updateStrategy: null;
+    });
+
+export type ActiveInstallationWindow = "24h" | "7d" | "30d";
+
+export type EventHistoryRow = {
+  readonly id: string;
+  readonly installId: string;
+  readonly type:
+    | "UPDATE_DOWNLOADED"
+    | "UPDATE_APPLIED"
+    | "RECOVERED"
+    | "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;
+  readonly cohort: string;
+  readonly receivedAtMs: number;
+};
+
+export type InstallationHistoryRow = EventHistoryRow & {
+  readonly type: "UPDATE_DOWNLOADED" | "UPDATE_APPLIED" | "RECOVERED";
+  readonly fromBundleId: string;
+};
+
+export type InstallationRow = {
+  readonly installId: string;
+  readonly username: string | null;
+  readonly userId: string | null;
+  readonly lastKnownBundleId: string;
+  readonly pendingBundleId: string | null;
+  readonly pendingReleaseId: string | null;
+  readonly latestStatus: EventHistoryRow["type"];
+  readonly platform: "ios" | "android";
+  readonly appVersion: string;
+  readonly channel: string;
+  readonly cohort: string;
+  readonly receivedAtMs: number;
+};
+
+export type CursorPage<T> = {
+  readonly data: readonly T[];
+  readonly nextCursor: string | null;
+};
+
+export type EventCursorPage<T extends EventHistoryRow> = CursorPage<T> & {
+  readonly beforeReceivedAtMs: number;
+};
+
+export type InsightsScope = {
+  readonly platform: "ios" | "android";
+  readonly channel: string;
+};
+
+export type InsightsBundleSelection = InsightsScope & {
+  readonly bundleId: string;
+  readonly outcome: "downloaded" | "applied" | "recovered" | "unchanged";
+};
+
+export type InsightsCountMeasurement = {
+  readonly count: number;
+  readonly measuredAtMs: number;
+};
+
+export type ReportingOverview = InsightsScope & {
+  readonly window: ActiveInstallationWindow;
+  readonly sinceMs: number;
+  readonly beforeReceivedAtMs: number;
+  readonly reportingInstallations: InsightsCountMeasurement;
+  readonly bundle?: {
+    readonly bundleId: string;
+    readonly reportingInstallations: InsightsCountMeasurement;
+    readonly downloadedReports: InsightsCountMeasurement;
+    readonly appliedReports: InsightsCountMeasurement;
+    readonly recoveredReports: InsightsCountMeasurement;
+    readonly unchangedReports: InsightsCountMeasurement;
+  };
+};

package/src/insights/errors.ts

@@ -0,0 +1,11 @@
+export class InsightsBadRequestError extends Error {
+  readonly name = "InsightsBadRequestError";
+}
+
+export class InsightsPayloadTooLargeError extends Error {
+  readonly name = "InsightsPayloadTooLargeError";
+
+  constructor(readonly maximumBytes: number) {
+    super(`Event payload exceeds ${maximumBytes} bytes`);
+  }
+}

package/src/{analytics → insights}/eventInput.ts

@@ -1,13 +1,16 @@
+import { createUUIDv7, type BundleEventRow } from "@hot-updater/plugin-core";
+
 import type {
   CreateBundleEventRequest,
   CreateBundleEventRequestBase,
 } from "./domain";
 import {
-  AnalyticsBadRequestError,
-  AnalyticsPayloadTooLargeError,
+  InsightsBadRequestError,
+  InsightsPayloadTooLargeError,
 } 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,9 +43,12 @@ 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 AnalyticsBadRequestError(`Invalid event field: ${key}`);
+    throw new InsightsBadRequestError(`Invalid event field: ${key}`);
   }
   return value;
 }
@@ -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);
@@ -63,7 +80,7 @@ async function readBoundedText(request: Request): Promise<string> {
     Number.isSafeInteger(declaredByteLength) &&
     declaredByteLength > EVENT_BODY_MAX_BYTES
   ) {
-    throw new AnalyticsPayloadTooLargeError(EVENT_BODY_MAX_BYTES);
+    throw new InsightsPayloadTooLargeError(EVENT_BODY_MAX_BYTES);
   }
   if (request.body === null) return "";
   const reader = request.body.getReader();
@@ -76,7 +93,7 @@ async function readBoundedText(request: Request): Promise<string> {
     byteLength += result.value.byteLength;
     if (byteLength > EVENT_BODY_MAX_BYTES) {
       await reader.cancel();
-      throw new AnalyticsPayloadTooLargeError(EVENT_BODY_MAX_BYTES);
+      throw new InsightsPayloadTooLargeError(EVENT_BODY_MAX_BYTES);
     }
     text += decoder.decode(result.value, { stream: true });
   }
@@ -89,7 +106,7 @@ async function parseJson(request: Request): Promise<unknown> {
     return JSON.parse(text);
   } catch (error) {
     if (error instanceof SyntaxError) {
-      throw new AnalyticsBadRequestError("Invalid event payload");
+      throw new InsightsBadRequestError("Invalid event payload");
     }
     throw error;
   }
@@ -100,18 +117,18 @@ function requireEvent(payload: unknown): CreateBundleEventRequest {
     !isRecord(payload) ||
     Object.keys(payload).some((key) => !eventKeys.has(key))
   ) {
-    throw new AnalyticsBadRequestError("Invalid event payload");
+    throw new InsightsBadRequestError("Invalid event payload");
   }
   const platform = requireStringField(payload, "platform");
   if (platform !== "ios" && platform !== "android") {
-    throw new AnalyticsBadRequestError("Invalid event field: platform");
+    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") }),
@@ -129,12 +146,12 @@ function requireEvent(payload: unknown): CreateBundleEventRequest {
   };
   const type = requireStringField(payload, "type");
   switch (type) {
+    case "UPDATE_DOWNLOADED":
     case "UPDATE_APPLIED":
-    case "RECOVERED":
-    case "RELEASE_ADOPTED": {
+    case "RECOVERED": {
       const updateStrategy = requireStringField(payload, "updateStrategy");
       if (updateStrategy !== "fingerprint" && updateStrategy !== "appVersion") {
-        throw new AnalyticsBadRequestError(
+        throw new InsightsBadRequestError(
           "Invalid event field: updateStrategy",
         );
       }
@@ -147,7 +164,7 @@ function requireEvent(payload: unknown): CreateBundleEventRequest {
     }
     case "UNCHANGED":
       if (payload.fromBundleId !== null || payload.updateStrategy !== null) {
-        throw new AnalyticsBadRequestError("Invalid unchanged event shape");
+        throw new InsightsBadRequestError("Invalid unchanged event shape");
       }
       return {
         ...base,
@@ -156,7 +173,7 @@ function requireEvent(payload: unknown): CreateBundleEventRequest {
         updateStrategy: null,
       };
     default:
-      throw new AnalyticsBadRequestError("Invalid event field: type");
+      throw new InsightsBadRequestError("Invalid event field: type");
   }
 }
 
@@ -166,3 +183,36 @@ 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,
+    from_release_id: input.fromReleaseId,
+    id: createUUIDv7(),
+    install_id: input.installId,
+    platform: input.platform,
+    received_at_ms: Date.now(),
+    to_bundle_id: input.toBundleId,
+    to_release_id: input.toReleaseId,
+    user_id: input.userId ?? null,
+    metadata: {
+      cohort: input.cohort,
+      fingerprint_hash: input.fingerprintHash,
+      sdk_version: input.sdkVersion ?? null,
+      username: input.username ?? null,
+      update_strategy: input.updateStrategy,
+    },
+  };
+  switch (input.type) {
+    case "UPDATE_DOWNLOADED":
+    case "UPDATE_APPLIED":
+    case "RECOVERED":
+      return { ...base, from_bundle_id: input.fromBundleId, type: input.type };
+    case "UNCHANGED":
+      return { ...base, from_bundle_id: null, type: input.type };
+  }
+}