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

package/dist/handlerTypes.d.mts

@@ -1,63 +1,9 @@
-import { ReleaseCatalogRequest } from "./db/releaseCatalog.mjs";
-import { PaginatedResult } from "./types/index.mjs";
-import { ChannelDeleteInput, ChannelDeleteResult, ChannelInsertInput, ChannelInsertResult, ChannelRow, DatabaseBundleQueryOptions, DatabaseCommit, DatabaseCommitResult, ReleaseCatalogMutationPreflight, ReleaseCatalogMutationResult, ReleaseCatalogRebuildResult, ReleaseCatalogRow, ReleasePolicyPatch, ReleaseRow } from "@hot-updater/plugin-core";
-import { ArtifactInfo, Bundle as Bundle$1, ReleaseCatalog } from "@hot-updater/core";
-
+import "./core/api.mjs";
 //#region src/handlerTypes.d.ts
-interface HandlerAPI {
-  getReleaseCatalog?: (input: ReleaseCatalogRequest) => Promise<ReleaseCatalog | null>;
-  getArtifactInfo?: (targetBundleId: string, currentBundleId: string) => Promise<ArtifactInfo | null>;
-  getReleaseById?: (id: string) => Promise<ReleaseRow | null>;
-  getReleasesByScope?: (input: {
-    readonly scopeKey: string;
-    readonly afterReleaseId?: string;
-    readonly limit: number;
-  }) => Promise<readonly ReleaseRow[]>;
-  getReleases?: (input: {
-    readonly afterReleaseId?: string;
-    readonly beforeReleaseId?: string;
-    readonly bundleId?: string;
-    readonly channelId?: string;
-    readonly enabled?: boolean;
-    readonly platform?: "ios" | "android";
-    readonly targetAppVersion?: string;
-    readonly limit: number;
-  }) => Promise<readonly ReleaseRow[]>;
-  getReleaseCatalogByScopeKey?: (scopeKey: string) => Promise<ReleaseCatalogRow | null>;
-  getReleaseCatalogs?: (input: {
-    readonly afterScopeKey?: string;
-    readonly limit: number;
-  }) => Promise<readonly ReleaseCatalogRow[]>;
-  updateReleasePolicy?: (input: {
-    readonly expectedRevision?: number;
-    readonly patch: ReleasePolicyPatch;
-    readonly releaseId: string;
-  }) => Promise<ReleaseCatalogMutationResult>;
-  preflightReleasePolicy?: (input: {
-    readonly expectedRevision?: number;
-    readonly patch: ReleasePolicyPatch;
-    readonly releaseId: string;
-  }) => Promise<ReleaseCatalogMutationPreflight>;
-  deleteRelease?: (input: {
-    readonly expectedRevision?: number;
-    readonly releaseId: string;
-  }) => Promise<ReleaseCatalogMutationResult>;
-  rebuildReleaseCatalog?: (scopeKey: string) => Promise<ReleaseCatalogRebuildResult>;
-  commitDatabase?: (input: DatabaseCommit) => Promise<DatabaseCommitResult>;
-  getBundleById: (id: string) => Promise<Bundle$1 | null>;
-  getBundles: (options: DatabaseBundleQueryOptions) => Promise<PaginatedResult>;
-  insertBundle: (bundle: Bundle$1) => Promise<void>;
-  insertBundles?: (bundles: readonly Bundle$1[]) => Promise<void>;
-  updateBundleById: (bundleId: string, bundle: Partial<Bundle$1>) => Promise<void>;
-  deleteBundleById: (bundleId: string) => Promise<void>;
-  getChannels: () => Promise<readonly ChannelRow[]>;
-  insertChannel: (input: ChannelInsertInput) => Promise<ChannelInsertResult>;
-  deleteChannel: (input: ChannelDeleteInput) => Promise<ChannelDeleteResult>;
-}
 type HotUpdaterHandler = (request: Request) => Promise<Response>;
 interface HotUpdaterHandlers {
   readonly client: HotUpdaterHandler;
   readonly admin: HotUpdaterHandler;
 }
 //#endregion
-export { HandlerAPI, HotUpdaterHandler, HotUpdaterHandlers };
+export { HotUpdaterHandler, HotUpdaterHandlers };

package/dist/handlerVersionRoutes.cjs

@@ -1,10 +1,26 @@
 const require_version = require("./version.cjs");
 //#region src/handlerVersionRoutes.ts
 const HOT_UPDATER_INFRASTRUCTURE_GENERATION = 1;
-const createVersionRouteHandlers = () => ({ version: async () => Response.json({
-	infrastructureGeneration: 1,
-	version: require_version.HOT_UPDATER_SERVER_VERSION
-}) });
+/**
+* `/version` on both mounts. The admin mount also lists the ids of the
+* plugins the server runs, sorted, so a console shows only the features they
+* serve; apps never learn which plugins a server runs.
+*/
+const createVersionRouteHandlers = (plugins = []) => {
+	const version = {
+		adminProtocol: 2,
+		infrastructureGeneration: 1,
+		version: require_version.HOT_UPDATER_SERVER_VERSION
+	};
+	const adminVersion = {
+		...version,
+		plugins: [...plugins].sort()
+	};
+	return {
+		version: async () => Response.json(version),
+		adminVersion: async () => Response.json(adminVersion)
+	};
+};
 //#endregion
 exports.HOT_UPDATER_INFRASTRUCTURE_GENERATION = HOT_UPDATER_INFRASTRUCTURE_GENERATION;
 exports.createVersionRouteHandlers = createVersionRouteHandlers;

package/dist/handlerVersionRoutes.d.cts

@@ -1,3 +1,4 @@
+import "./handlerTypes.cjs";
 //#region src/handlerVersionRoutes.d.ts
 declare const HOT_UPDATER_INFRASTRUCTURE_GENERATION = 1;
 //#endregion

package/dist/handlerVersionRoutes.d.mts

@@ -1,3 +1,4 @@
+import "./handlerTypes.mjs";
 //#region src/handlerVersionRoutes.d.ts
 declare const HOT_UPDATER_INFRASTRUCTURE_GENERATION = 1;
 //#endregion

package/dist/handlerVersionRoutes.mjs

@@ -1,9 +1,25 @@
 import { HOT_UPDATER_SERVER_VERSION } from "./version.mjs";
 //#region src/handlerVersionRoutes.ts
 const HOT_UPDATER_INFRASTRUCTURE_GENERATION = 1;
-const createVersionRouteHandlers = () => ({ version: async () => Response.json({
-	infrastructureGeneration: 1,
-	version: HOT_UPDATER_SERVER_VERSION
-}) });
+/**
+* `/version` on both mounts. The admin mount also lists the ids of the
+* plugins the server runs, sorted, so a console shows only the features they
+* serve; apps never learn which plugins a server runs.
+*/
+const createVersionRouteHandlers = (plugins = []) => {
+	const version = {
+		adminProtocol: 2,
+		infrastructureGeneration: 1,
+		version: HOT_UPDATER_SERVER_VERSION
+	};
+	const adminVersion = {
+		...version,
+		plugins: [...plugins].sort()
+	};
+	return {
+		version: async () => Response.json(version),
+		adminVersion: async () => Response.json(adminVersion)
+	};
+};
 //#endregion
 export { HOT_UPDATER_INFRASTRUCTURE_GENERATION, createVersionRouteHandlers };

package/dist/index.cjs

@@ -1,16 +1,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_provider = require("./insights/provider.cjs");
+const require_apiKeys = require("./apiKeys.cjs");
+const require_assemblePlugins = require("./assembly/assemblePlugins.cjs");
 const require_version = require("./version.cjs");
 const require_handlerVersionRoutes = require("./handlerVersionRoutes.cjs");
-const require_handler = require("./handler.cjs");
-const require_provider = require("./insights/bounded/provider.cjs");
-const require_apiKeys = require("./apiKeys.cjs");
 const require_createHotUpdaterCore = require("./createHotUpdaterCore.cjs");
 exports.API_KEY_HEADER_NAME = require_apiKeys.API_KEY_HEADER_NAME;
 exports.HOT_UPDATER_INFRASTRUCTURE_GENERATION = require_handlerVersionRoutes.HOT_UPDATER_INFRASTRUCTURE_GENERATION;
 exports.HOT_UPDATER_SERVER_VERSION = require_version.HOT_UPDATER_SERVER_VERSION;
-exports.createApiKey = require_apiKeys.createApiKey;
-exports.createHandlers = require_handler.createHandlers;
+exports.HotUpdaterConfigError = require_assemblePlugins.HotUpdaterConfigError;
 exports.createHotUpdater = require_createHotUpdaterCore.createHotUpdater;
 exports.createInsightsProvider = require_provider.createInsightsProvider;
-exports.provisionApiKey = require_apiKeys.provisionApiKey;
-exports.registerApiKey = require_apiKeys.registerApiKey;

package/dist/index.d.cts

@@ -1,11 +1,12 @@
-import { API_KEY_HEADER_NAME, ApiKeyManagementAPI, ApiKeyMetadata, CreatedApiKey, createApiKey, provisionApiKey, registerApiKey } from "./apiKeys.cjs";
-import { HandlerAPI, HotUpdaterHandler, HotUpdaterHandlers } from "./handlerTypes.cjs";
-import { ActiveInstallationInput, ActiveInstallationOverview, ActiveInstallationWindow, BundleEventInsightsResult, BundleEventInsightsWindow, BundleEventOverview, BundleEventSummary, BundleEventSummaryByBundle, CreateBundleEventRequest, CreateBundleEventRequestBase, InsightsCohortPoint, InsightsSeriesPoint, InstallationHistoryRow, InstallationSearchRow, OffsetPaginationResult } from "./insights/domain.cjs";
-import { InsightsProvider } from "./insights/types.cjs";
-import { createHandlers } from "./handler.cjs";
-import { ClientAccessPolicy, CreateHotUpdaterOptions, HotUpdaterAPI, RuntimeHotUpdaterAPI, createHotUpdater } from "./createHotUpdaterCore.cjs";
-import { Bundle, ChannelsResponse, DataResponse, Paginated, PaginatedResult, PaginationInfo, PaginationOptions } from "./types/index.cjs";
 import { HOT_UPDATER_SERVER_VERSION } from "./version.cjs";
-import { createInsightsProvider } from "./insights/bounded/provider.cjs";
+import { HotUpdaterConfigError } from "./assembly/assemblePlugins.cjs";
+import { HotUpdaterHandler, HotUpdaterHandlers } from "./handlerTypes.cjs";
+import "./handler.cjs";
+import { ActiveInstallationWindow, CreateBundleEventRequest, CreateBundleEventRequestBase, CursorPage, EventCursorPage, EventHistoryRow, InsightsBundleSelection, InsightsCountMeasurement, InsightsScope, InstallationHistoryRow, InstallationRow, ReportingOverview } from "./insights/domain.cjs";
+import { InsightsEventPageInput, InsightsInstallationEventPageInput, InsightsProvider, InsightsUserInstallationPageInput } from "./insights/types.cjs";
+import { createInsightsProvider } from "./insights/provider.cjs";
+import { API_KEY_HEADER_NAME, ApiKeyManagementAPI, ApiKeyMetadata, CreatedApiKey } from "./apiKeys.cjs";
+import { ClientAccessPolicy, ClientAccessRule, CreateHotUpdaterOptions, HotUpdaterAPI, RemovedClientAccess, RuntimeHotUpdaterAPI, createHotUpdater } from "./createHotUpdaterCore.cjs";
+import { Bundle } from "./types/index.cjs";
 import { HOT_UPDATER_INFRASTRUCTURE_GENERATION } from "./handlerVersionRoutes.cjs";
-export { API_KEY_HEADER_NAME, ActiveInstallationInput, ActiveInstallationOverview, ActiveInstallationWindow, type ApiKeyManagementAPI, type ApiKeyMetadata, Bundle, BundleEventInsightsResult, BundleEventInsightsWindow, BundleEventOverview, BundleEventSummary, BundleEventSummaryByBundle, ChannelsResponse, type ClientAccessPolicy, CreateBundleEventRequest, CreateBundleEventRequestBase, type CreateHotUpdaterOptions, type CreatedApiKey, DataResponse, HOT_UPDATER_INFRASTRUCTURE_GENERATION, HOT_UPDATER_SERVER_VERSION, type HandlerAPI, type HotUpdaterAPI, type HotUpdaterHandler, type HotUpdaterHandlers, InsightsCohortPoint, type InsightsProvider, InsightsSeriesPoint, InstallationHistoryRow, InstallationSearchRow, OffsetPaginationResult, Paginated, PaginatedResult, PaginationInfo, PaginationOptions, type RuntimeHotUpdaterAPI, createApiKey, createHandlers, createHotUpdater, createInsightsProvider, provisionApiKey, registerApiKey };
+export { API_KEY_HEADER_NAME, type ActiveInstallationWindow, type ApiKeyManagementAPI, type ApiKeyMetadata, type Bundle, type ClientAccessPolicy, type ClientAccessRule, type CreateBundleEventRequest, type CreateBundleEventRequestBase, type CreateHotUpdaterOptions, type CreatedApiKey, type CursorPage, type EventCursorPage, type EventHistoryRow, HOT_UPDATER_INFRASTRUCTURE_GENERATION, HOT_UPDATER_SERVER_VERSION, type HotUpdaterAPI, HotUpdaterConfigError, type HotUpdaterHandler, type HotUpdaterHandlers, type InsightsBundleSelection, type InsightsCountMeasurement, type InsightsEventPageInput, type InsightsInstallationEventPageInput, type InsightsProvider, type InsightsScope, type InsightsUserInstallationPageInput, type InstallationHistoryRow, type InstallationRow, type RemovedClientAccess, type ReportingOverview, type RuntimeHotUpdaterAPI, createHotUpdater, createInsightsProvider };

package/dist/index.d.mts

@@ -1,11 +1,12 @@
-import { API_KEY_HEADER_NAME, ApiKeyManagementAPI, ApiKeyMetadata, CreatedApiKey, createApiKey, provisionApiKey, registerApiKey } from "./apiKeys.mjs";
-import { HandlerAPI, HotUpdaterHandler, HotUpdaterHandlers } from "./handlerTypes.mjs";
-import { ActiveInstallationInput, ActiveInstallationOverview, ActiveInstallationWindow, BundleEventInsightsResult, BundleEventInsightsWindow, BundleEventOverview, BundleEventSummary, BundleEventSummaryByBundle, CreateBundleEventRequest, CreateBundleEventRequestBase, InsightsCohortPoint, InsightsSeriesPoint, InstallationHistoryRow, InstallationSearchRow, OffsetPaginationResult } from "./insights/domain.mjs";
-import { InsightsProvider } from "./insights/types.mjs";
-import { createHandlers } from "./handler.mjs";
-import { ClientAccessPolicy, CreateHotUpdaterOptions, HotUpdaterAPI, RuntimeHotUpdaterAPI, createHotUpdater } from "./createHotUpdaterCore.mjs";
-import { Bundle, ChannelsResponse, DataResponse, Paginated, PaginatedResult, PaginationInfo, PaginationOptions } from "./types/index.mjs";
 import { HOT_UPDATER_SERVER_VERSION } from "./version.mjs";
-import { createInsightsProvider } from "./insights/bounded/provider.mjs";
+import { HotUpdaterConfigError } from "./assembly/assemblePlugins.mjs";
+import { HotUpdaterHandler, HotUpdaterHandlers } from "./handlerTypes.mjs";
+import "./handler.mjs";
+import { ActiveInstallationWindow, CreateBundleEventRequest, CreateBundleEventRequestBase, CursorPage, EventCursorPage, EventHistoryRow, InsightsBundleSelection, InsightsCountMeasurement, InsightsScope, InstallationHistoryRow, InstallationRow, ReportingOverview } from "./insights/domain.mjs";
+import { InsightsEventPageInput, InsightsInstallationEventPageInput, InsightsProvider, InsightsUserInstallationPageInput } from "./insights/types.mjs";
+import { createInsightsProvider } from "./insights/provider.mjs";
+import { API_KEY_HEADER_NAME, ApiKeyManagementAPI, ApiKeyMetadata, CreatedApiKey } from "./apiKeys.mjs";
+import { ClientAccessPolicy, ClientAccessRule, CreateHotUpdaterOptions, HotUpdaterAPI, RemovedClientAccess, RuntimeHotUpdaterAPI, createHotUpdater } from "./createHotUpdaterCore.mjs";
+import { Bundle } from "./types/index.mjs";
 import { HOT_UPDATER_INFRASTRUCTURE_GENERATION } from "./handlerVersionRoutes.mjs";
-export { API_KEY_HEADER_NAME, ActiveInstallationInput, ActiveInstallationOverview, ActiveInstallationWindow, type ApiKeyManagementAPI, type ApiKeyMetadata, Bundle, BundleEventInsightsResult, BundleEventInsightsWindow, BundleEventOverview, BundleEventSummary, BundleEventSummaryByBundle, ChannelsResponse, type ClientAccessPolicy, CreateBundleEventRequest, CreateBundleEventRequestBase, type CreateHotUpdaterOptions, type CreatedApiKey, DataResponse, HOT_UPDATER_INFRASTRUCTURE_GENERATION, HOT_UPDATER_SERVER_VERSION, type HandlerAPI, type HotUpdaterAPI, type HotUpdaterHandler, type HotUpdaterHandlers, InsightsCohortPoint, type InsightsProvider, InsightsSeriesPoint, InstallationHistoryRow, InstallationSearchRow, OffsetPaginationResult, Paginated, PaginatedResult, PaginationInfo, PaginationOptions, type RuntimeHotUpdaterAPI, createApiKey, createHandlers, createHotUpdater, createInsightsProvider, provisionApiKey, registerApiKey };
+export { API_KEY_HEADER_NAME, type ActiveInstallationWindow, type ApiKeyManagementAPI, type ApiKeyMetadata, type Bundle, type ClientAccessPolicy, type ClientAccessRule, type CreateBundleEventRequest, type CreateBundleEventRequestBase, type CreateHotUpdaterOptions, type CreatedApiKey, type CursorPage, type EventCursorPage, type EventHistoryRow, HOT_UPDATER_INFRASTRUCTURE_GENERATION, HOT_UPDATER_SERVER_VERSION, type HotUpdaterAPI, HotUpdaterConfigError, type HotUpdaterHandler, type HotUpdaterHandlers, type InsightsBundleSelection, type InsightsCountMeasurement, type InsightsEventPageInput, type InsightsInstallationEventPageInput, type InsightsProvider, type InsightsScope, type InsightsUserInstallationPageInput, type InstallationHistoryRow, type InstallationRow, type RemovedClientAccess, type ReportingOverview, type RuntimeHotUpdaterAPI, createHotUpdater, createInsightsProvider };

package/dist/index.mjs

@@ -1,7 +1,7 @@
+import { createInsightsProvider } from "./insights/provider.mjs";
+import { API_KEY_HEADER_NAME } from "./apiKeys.mjs";
+import { HotUpdaterConfigError } from "./assembly/assemblePlugins.mjs";
 import { HOT_UPDATER_SERVER_VERSION } from "./version.mjs";
 import { HOT_UPDATER_INFRASTRUCTURE_GENERATION } from "./handlerVersionRoutes.mjs";
-import { createHandlers } from "./handler.mjs";
-import { createInsightsProvider } from "./insights/bounded/provider.mjs";
-import { API_KEY_HEADER_NAME, createApiKey, provisionApiKey, registerApiKey } from "./apiKeys.mjs";
 import { createHotUpdater } from "./createHotUpdaterCore.mjs";
-export { API_KEY_HEADER_NAME, HOT_UPDATER_INFRASTRUCTURE_GENERATION, HOT_UPDATER_SERVER_VERSION, createApiKey, createHandlers, createHotUpdater, createInsightsProvider, provisionApiKey, registerApiKey };
+export { API_KEY_HEADER_NAME, HOT_UPDATER_INFRASTRUCTURE_GENERATION, HOT_UPDATER_SERVER_VERSION, HotUpdaterConfigError, createHotUpdater, createInsightsProvider };

package/dist/insights/domain.d.cts

@@ -1,5 +1,17 @@
 //#region src/insights/domain.d.ts
+/**
+ * The body of `POST /events`. Fields the server does not know are ignored, so
+ * a newer client's report still records on an older server.
+ */
 type CreateBundleEventRequestBase = {
+  /**
+   * The report's idempotency key: a canonical lowercase UUIDv7 that the
+   * client creates once per report and repeats on every retry. The server
+   * stores the report under it, so a retried report counts once, and a
+   * report under an ID already stored changes nothing. Without it, the
+   * server creates the ID, and a retry counts as another report.
+   */
+  readonly eventId?: string;
   readonly installId: string;
   readonly toBundleId: string;
   readonly userId?: string;
@@ -14,15 +26,7 @@ type CreateBundleEventRequestBase = {
   readonly toReleaseId: string | null;
 };
 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_DOWNLOADED" | "UPDATE_APPLIED" | "RECOVERED";
   readonly fromBundleId: string;
   readonly updateStrategy: "fingerprint" | "appVersion";
 }) | (CreateBundleEventRequestBase & {
@@ -30,92 +34,71 @@ type CreateBundleEventRequest = (CreateBundleEventRequestBase & {
   readonly fromBundleId: null;
   readonly updateStrategy: null;
 });
-type BundleEventSummary = {
-  readonly installed: number;
-  readonly recovered: number;
-};
-type BundleEventSummaryByBundle = BundleEventSummary & {
-  readonly bundleId: string;
-};
-type BundleEventInsightsWindow = "24h" | "7d" | "30d" | "all";
 type ActiveInstallationWindow = "24h" | "7d" | "30d";
-type InstallationSearchRow = {
+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 lastKnownBundleId: string;
-  readonly latestStatus: "UPDATE_APPLIED" | "RECOVERED" | "RELEASE_ADOPTED" | "UNCHANGED";
   readonly platform: "ios" | "android";
   readonly appVersion: string;
   readonly channel: string;
   readonly cohort: string;
   readonly receivedAtMs: number;
 };
-type InstallationHistoryRow = {
-  readonly id: string;
-  readonly type: "UPDATE_APPLIED" | "RECOVERED";
+type InstallationHistoryRow = EventHistoryRow & {
+  readonly type: "UPDATE_DOWNLOADED" | "UPDATE_APPLIED" | "RECOVERED";
   readonly fromBundleId: string;
-  readonly toBundleId: string;
+};
+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;
 };
-type OffsetPaginationResult<TData> = {
-  readonly data: readonly TData[];
-  readonly pagination: {
-    readonly total: number;
-    readonly limit: number;
-    readonly offset: number;
-  };
+type CursorPage<T> = {
+  readonly data: readonly T[];
+  readonly nextCursor: string | null;
 };
-type InsightsSeriesPoint = {
-  readonly bucketStartMs: number;
-  readonly value: number;
+type EventCursorPage<T extends EventHistoryRow> = CursorPage<T> & {
+  readonly beforeReceivedAtMs: number;
 };
-type InsightsCohortPoint = {
-  readonly cohort: string;
-  readonly value: number;
+type InsightsScope = {
+  readonly platform: "ios" | "android";
+  readonly channel: string;
 };
-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>;
+type InsightsBundleSelection = InsightsScope & {
+  readonly bundleId: string;
+  readonly outcome: "downloaded" | "applied" | "recovered" | "unchanged";
 };
-type BundleEventOverview = {
-  readonly trackedInstallations: number;
-  readonly bundles: readonly {
-    readonly bundleId: string;
-    readonly installations: number;
-  }[];
+type InsightsCountMeasurement = {
+  readonly count: number;
+  readonly measuredAtMs: number;
 };
-type ActiveInstallationOverview = {
-  readonly asOfMs: number;
+type ReportingOverview = InsightsScope & {
   readonly window: ActiveInstallationWindow;
-  readonly activeInstallations: number;
-  readonly series: readonly InsightsSeriesPoint[];
-  readonly bundleSeries: readonly {
+  readonly sinceMs: number;
+  readonly beforeReceivedAtMs: number;
+  readonly reportingInstallations: InsightsCountMeasurement;
+  readonly bundle?: {
     readonly bundleId: string;
-    readonly series: readonly InsightsSeriesPoint[];
-  }[];
-  readonly bundles: readonly {
-    readonly bundleId: string;
-    readonly installations: number;
-  }[];
-};
-type ActiveInstallationInput = {
-  readonly window: ActiveInstallationWindow;
-  readonly userId?: string;
+    readonly reportingInstallations: InsightsCountMeasurement;
+    readonly downloadedReports: InsightsCountMeasurement;
+    readonly appliedReports: InsightsCountMeasurement;
+    readonly recoveredReports: InsightsCountMeasurement;
+    readonly unchangedReports: InsightsCountMeasurement;
+  };
 };
 //#endregion
-export { ActiveInstallationInput, ActiveInstallationOverview, ActiveInstallationWindow, BundleEventInsightsResult, BundleEventInsightsWindow, BundleEventOverview, BundleEventSummary, BundleEventSummaryByBundle, CreateBundleEventRequest, CreateBundleEventRequestBase, InsightsCohortPoint, InsightsSeriesPoint, InstallationHistoryRow, InstallationSearchRow, OffsetPaginationResult };
+export { ActiveInstallationWindow, CreateBundleEventRequest, CreateBundleEventRequestBase, CursorPage, EventCursorPage, EventHistoryRow, InsightsBundleSelection, InsightsCountMeasurement, InsightsScope, InstallationHistoryRow, InstallationRow, ReportingOverview };

package/dist/insights/domain.d.mts

@@ -1,5 +1,17 @@
 //#region src/insights/domain.d.ts
+/**
+ * The body of `POST /events`. Fields the server does not know are ignored, so
+ * a newer client's report still records on an older server.
+ */
 type CreateBundleEventRequestBase = {
+  /**
+   * The report's idempotency key: a canonical lowercase UUIDv7 that the
+   * client creates once per report and repeats on every retry. The server
+   * stores the report under it, so a retried report counts once, and a
+   * report under an ID already stored changes nothing. Without it, the
+   * server creates the ID, and a retry counts as another report.
+   */
+  readonly eventId?: string;
   readonly installId: string;
   readonly toBundleId: string;
   readonly userId?: string;
@@ -14,15 +26,7 @@ type CreateBundleEventRequestBase = {
   readonly toReleaseId: string | null;
 };
 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_DOWNLOADED" | "UPDATE_APPLIED" | "RECOVERED";
   readonly fromBundleId: string;
   readonly updateStrategy: "fingerprint" | "appVersion";
 }) | (CreateBundleEventRequestBase & {
@@ -30,92 +34,71 @@ type CreateBundleEventRequest = (CreateBundleEventRequestBase & {
   readonly fromBundleId: null;
   readonly updateStrategy: null;
 });
-type BundleEventSummary = {
-  readonly installed: number;
-  readonly recovered: number;
-};
-type BundleEventSummaryByBundle = BundleEventSummary & {
-  readonly bundleId: string;
-};
-type BundleEventInsightsWindow = "24h" | "7d" | "30d" | "all";
 type ActiveInstallationWindow = "24h" | "7d" | "30d";
-type InstallationSearchRow = {
+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 lastKnownBundleId: string;
-  readonly latestStatus: "UPDATE_APPLIED" | "RECOVERED" | "RELEASE_ADOPTED" | "UNCHANGED";
   readonly platform: "ios" | "android";
   readonly appVersion: string;
   readonly channel: string;
   readonly cohort: string;
   readonly receivedAtMs: number;
 };
-type InstallationHistoryRow = {
-  readonly id: string;
-  readonly type: "UPDATE_APPLIED" | "RECOVERED";
+type InstallationHistoryRow = EventHistoryRow & {
+  readonly type: "UPDATE_DOWNLOADED" | "UPDATE_APPLIED" | "RECOVERED";
   readonly fromBundleId: string;
-  readonly toBundleId: string;
+};
+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;
 };
-type OffsetPaginationResult<TData> = {
-  readonly data: readonly TData[];
-  readonly pagination: {
-    readonly total: number;
-    readonly limit: number;
-    readonly offset: number;
-  };
+type CursorPage<T> = {
+  readonly data: readonly T[];
+  readonly nextCursor: string | null;
 };
-type InsightsSeriesPoint = {
-  readonly bucketStartMs: number;
-  readonly value: number;
+type EventCursorPage<T extends EventHistoryRow> = CursorPage<T> & {
+  readonly beforeReceivedAtMs: number;
 };
-type InsightsCohortPoint = {
-  readonly cohort: string;
-  readonly value: number;
+type InsightsScope = {
+  readonly platform: "ios" | "android";
+  readonly channel: string;
 };
-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>;
+type InsightsBundleSelection = InsightsScope & {
+  readonly bundleId: string;
+  readonly outcome: "downloaded" | "applied" | "recovered" | "unchanged";
 };
-type BundleEventOverview = {
-  readonly trackedInstallations: number;
-  readonly bundles: readonly {
-    readonly bundleId: string;
-    readonly installations: number;
-  }[];
+type InsightsCountMeasurement = {
+  readonly count: number;
+  readonly measuredAtMs: number;
 };
-type ActiveInstallationOverview = {
-  readonly asOfMs: number;
+type ReportingOverview = InsightsScope & {
   readonly window: ActiveInstallationWindow;
-  readonly activeInstallations: number;
-  readonly series: readonly InsightsSeriesPoint[];
-  readonly bundleSeries: readonly {
+  readonly sinceMs: number;
+  readonly beforeReceivedAtMs: number;
+  readonly reportingInstallations: InsightsCountMeasurement;
+  readonly bundle?: {
     readonly bundleId: string;
-    readonly series: readonly InsightsSeriesPoint[];
-  }[];
-  readonly bundles: readonly {
-    readonly bundleId: string;
-    readonly installations: number;
-  }[];
-};
-type ActiveInstallationInput = {
-  readonly window: ActiveInstallationWindow;
-  readonly userId?: string;
+    readonly reportingInstallations: InsightsCountMeasurement;
+    readonly downloadedReports: InsightsCountMeasurement;
+    readonly appliedReports: InsightsCountMeasurement;
+    readonly recoveredReports: InsightsCountMeasurement;
+    readonly unchangedReports: InsightsCountMeasurement;
+  };
 };
 //#endregion
-export { ActiveInstallationInput, ActiveInstallationOverview, ActiveInstallationWindow, BundleEventInsightsResult, BundleEventInsightsWindow, BundleEventOverview, BundleEventSummary, BundleEventSummaryByBundle, CreateBundleEventRequest, CreateBundleEventRequestBase, InsightsCohortPoint, InsightsSeriesPoint, InstallationHistoryRow, InstallationSearchRow, OffsetPaginationResult };
+export { ActiveInstallationWindow, CreateBundleEventRequest, CreateBundleEventRequestBase, CursorPage, EventCursorPage, EventHistoryRow, InsightsBundleSelection, InsightsCountMeasurement, InsightsScope, InstallationHistoryRow, InstallationRow, ReportingOverview };

package/dist/insights/errors.cjs

@@ -1,22 +1,49 @@
+const require_errors = require("../database/errors.cjs");
 //#region src/insights/errors.ts
-var InsightsScanLimitExceededError = class extends Error {
-	constructor(limit) {
-		super(`Insights event scan exceeded ${limit} rows.`);
-		this.limit = limit;
-		this.name = "InsightsScanLimitExceededError";
-	}
-};
 var InsightsBadRequestError = class extends Error {
 	name = "InsightsBadRequestError";
 };
 var InsightsPayloadTooLargeError = class extends Error {
+	maximumBytes;
 	name = "InsightsPayloadTooLargeError";
 	constructor(maximumBytes) {
 		super(`Event payload exceeds ${maximumBytes} bytes`);
 		this.maximumBytes = maximumBytes;
 	}
 };
+/** Error names the AWS SDKs give a throttled request, as their retry strategy classifies them. */
+const THROTTLING_NAMES = /* @__PURE__ */ new Set([
+	"ProvisionedThroughputExceededException",
+	"RequestLimitExceeded",
+	"RequestThrottled",
+	"RequestThrottledException",
+	"SlowDown",
+	"ThrottledException",
+	"Throttling",
+	"ThrottlingException",
+	"TooManyRequestsException"
+]);
+/** gRPC's RESOURCE_EXHAUSTED, the status Firestore throttles a request with. */
+const RESOURCE_EXHAUSTED = 8;
+/**
+* Whether the database is busy rather than broken, so the same request can
+* succeed later: a transaction ran out of retries, or the backend throttled
+* a request. Writes already retry transient failures, throttled ones
+* included, until the budget runs out. A throttled read throws the backend's
+* own error, so it is recognized by what the backends call it: a name the
+* AWS SDKs retry as throttling, HTTP 429, or gRPC's RESOURCE_EXHAUSTED.
+*/
+const isDatabaseBusyError = (error) => {
+	if (error instanceof require_errors.DatabaseConflictError) return true;
+	if (typeof error !== "object" || error === null) return false;
+	const { name, code, message, status, statusCode, $metadata } = error;
+	return typeof name === "string" && THROTTLING_NAMES.has(name) || [
+		status,
+		statusCode,
+		$metadata?.httpStatusCode
+	].includes(429) || code === RESOURCE_EXHAUSTED && typeof message === "string" && message.includes("RESOURCE_EXHAUSTED");
+};
 //#endregion
 exports.InsightsBadRequestError = InsightsBadRequestError;
 exports.InsightsPayloadTooLargeError = InsightsPayloadTooLargeError;
-exports.InsightsScanLimitExceededError = InsightsScanLimitExceededError;
+exports.isDatabaseBusyError = isDatabaseBusyError;