@hot-updater/plugin-insights 1.0.0-rc.35 → 1.0.0-rc.37

package/dist/client/index.cjs

@@ -60,7 +60,8 @@ const insights = (options = {}) => {
 			appVersion,
 			cohort: context.getCohort(),
 			fingerprintHash: context.getFingerprintHash(),
-			sdkVersion: context.sdkVersion
+			sdkVersion: context.sdkVersion,
+			minBundleId: context.minBundleId
 		};
 		const day = require_state.utcDay(now);
 		return {

package/dist/client/index.mjs

@@ -59,7 +59,8 @@ const insights = (options = {}) => {
 			appVersion,
 			cohort: context.getCohort(),
 			fingerprintHash: context.getFingerprintHash(),
-			sdkVersion: context.sdkVersion
+			sdkVersion: context.sdkVersion,
+			minBundleId: context.minBundleId
 		};
 		const day = utcDay(now);
 		return {

package/dist/server/contract.cjs

@@ -1,4 +1,5 @@
 const require_eventRow = require("./eventRow.cjs");
+const require_schema = require("./schema.cjs");
 let _hot_updater_plugin_core = require("@hot-updater/plugin-core");
 //#region src/server/contract.ts
 const encoder = new TextEncoder();
@@ -30,7 +31,7 @@ const isBundleFilter = (value, withKind = false) => {
 		"type",
 		...withKind ? ["kind"] : []
 	];
-	return value.type === "RECOVERED" ? isText(value.fromBundleId) && hasOnlyKeys(value, [...keys, "fromBundleId"]) : (value.type === "UPDATE_DOWNLOADED" || value.type === "UPDATE_APPLIED" || value.type === "UPDATE_FAILED") && isText(value.toBundleId) && hasOnlyKeys(value, [...keys, "toBundleId"]);
+	return value.type === "RECOVERED" ? isText(value.fromBundleId) && hasOnlyKeys(value, [...keys, "fromBundleId"]) : (value.type === "UPDATE_DOWNLOADED" || value.type === "UPDATE_APPLIED" || value.type === "UPDATE_FAILED" || value.type === "UNCHANGED") && isText(value.toBundleId) && hasOnlyKeys(value, [...keys, "toBundleId"]);
 };
 const isEventFilter = (value) => {
 	if (!require_eventRow.isRecord(value)) return false;
@@ -49,12 +50,15 @@ const validateRow = (model, row, result = false) => {
 };
 /** Throws `invalid-data` unless `row` is a complete, well-formed bundle event row. */
 const assertBundleEventRow = (row) => validateRow("bundle_events", row);
-/** Downloads, applies, recoveries, and failed updates belong in installation history. */
-const isInsightsMovementEvent = (event) => event.type === "UPDATE_DOWNLOADED" || event.type === "UPDATE_APPLIED" || event.type === "RECOVERED" || event.type === "UPDATE_FAILED";
+/**
+* Downloads, applies, recoveries, failed updates, and the UNCHANGED rows
+* kept for a change belong in installation history.
+*/
+const isInsightsMovementEvent = (event) => event.type === "UPDATE_DOWNLOADED" || event.type === "UPDATE_APPLIED" || event.type === "RECOVERED" || event.type === "UPDATE_FAILED" || event.type === "UNCHANGED";
 const matchesInsightsEventFilter = (event, filter) => {
 	if (filter.kind === "all") return true;
 	if (filter.kind === "installationMovement") return event.install_id === filter.installId && isInsightsMovementEvent(event);
-	return event.type === filter.type && event.platform === filter.platform && event.channel === filter.channel && (filter.type === "RECOVERED" ? event.from_bundle_id === filter.fromBundleId : event.to_bundle_id === filter.toBundleId && event.metadata.failure?.stage !== "check");
+	return event.type === filter.type && event.platform === filter.platform && event.channel === filter.channel && require_schema.bundleRefsOf(event).includes(require_schema.bundleRefOfFilter(filter));
 };
 const invalidQuery = () => {
 	throw new _hot_updater_plugin_core.DatabaseAdapterInputError("invalid-query");

package/dist/server/contract.mjs

@@ -1,4 +1,5 @@
 import { isRecord, validateBundleEventFields } from "./eventRow.mjs";
+import { bundleRefOfFilter, bundleRefsOf } from "./schema.mjs";
 import { DatabaseAdapterInputError, isUUIDv7 } from "@hot-updater/plugin-core";
 //#region src/server/contract.ts
 const encoder = new TextEncoder();
@@ -30,7 +31,7 @@ const isBundleFilter = (value, withKind = false) => {
 		"type",
 		...withKind ? ["kind"] : []
 	];
-	return value.type === "RECOVERED" ? isText(value.fromBundleId) && hasOnlyKeys(value, [...keys, "fromBundleId"]) : (value.type === "UPDATE_DOWNLOADED" || value.type === "UPDATE_APPLIED" || value.type === "UPDATE_FAILED") && isText(value.toBundleId) && hasOnlyKeys(value, [...keys, "toBundleId"]);
+	return value.type === "RECOVERED" ? isText(value.fromBundleId) && hasOnlyKeys(value, [...keys, "fromBundleId"]) : (value.type === "UPDATE_DOWNLOADED" || value.type === "UPDATE_APPLIED" || value.type === "UPDATE_FAILED" || value.type === "UNCHANGED") && isText(value.toBundleId) && hasOnlyKeys(value, [...keys, "toBundleId"]);
 };
 const isEventFilter = (value) => {
 	if (!isRecord(value)) return false;
@@ -49,12 +50,15 @@ const validateRow = (model, row, result = false) => {
 };
 /** Throws `invalid-data` unless `row` is a complete, well-formed bundle event row. */
 const assertBundleEventRow = (row) => validateRow("bundle_events", row);
-/** Downloads, applies, recoveries, and failed updates belong in installation history. */
-const isInsightsMovementEvent = (event) => event.type === "UPDATE_DOWNLOADED" || event.type === "UPDATE_APPLIED" || event.type === "RECOVERED" || event.type === "UPDATE_FAILED";
+/**
+* Downloads, applies, recoveries, failed updates, and the UNCHANGED rows
+* kept for a change belong in installation history.
+*/
+const isInsightsMovementEvent = (event) => event.type === "UPDATE_DOWNLOADED" || event.type === "UPDATE_APPLIED" || event.type === "RECOVERED" || event.type === "UPDATE_FAILED" || event.type === "UNCHANGED";
 const matchesInsightsEventFilter = (event, filter) => {
 	if (filter.kind === "all") return true;
 	if (filter.kind === "installationMovement") return event.install_id === filter.installId && isInsightsMovementEvent(event);
-	return event.type === filter.type && event.platform === filter.platform && event.channel === filter.channel && (filter.type === "RECOVERED" ? event.from_bundle_id === filter.fromBundleId : event.to_bundle_id === filter.toBundleId && event.metadata.failure?.stage !== "check");
+	return event.type === filter.type && event.platform === filter.platform && event.channel === filter.channel && bundleRefsOf(event).includes(bundleRefOfFilter(filter));
 };
 const invalidQuery = () => {
 	throw new DatabaseAdapterInputError("invalid-query");

package/dist/server/domain.d.cts

@@ -1,4 +1,4 @@
-import { BundleEventFailure, BundleEventFailureReason, BundleEventFailureStage, DatabaseBundleEventMetadata } from "./eventRow.cjs";
+import { BundleEventChangeKind, BundleEventFailure, BundleEventFailureReason, BundleEventFailureStage, DatabaseBundleEventMetadata } from "./eventRow.cjs";
 import { InsightsScope } from "./modelTypes.cjs";
 import { UpdateHttpResponse } from "@hot-updater/protocol";
 //#region src/server/domain.d.ts
@@ -44,6 +44,12 @@ type CreateBundleEventRequestBase = {
   readonly cohort: string;
   readonly fingerprintHash: string | null;
   readonly sdkVersion?: string | null;
+  /**
+   * The bundle ID the native build ships as its built-in bundle. A report
+   * whose running bundle is this one, with no Release, runs the built-in
+   * bundle. Older SDKs leave it out.
+   */
+  readonly minBundleId?: string | null;
   readonly fromReleaseId: string | null;
   readonly toReleaseId: string | null;
 };
@@ -76,9 +82,27 @@ type CreateBundleEventRequest = (Movement & {
   readonly updateStrategy: null;
 });
 type ActiveInstallationWindow = "24h" | "7d" | "30d";
+/**
+ * What a kept UNCHANGED report changed against its installation's previous
+ * report: the running bundle or release, the app version, or the channel,
+ * with the previous values; `first_seen` alone for an installation's first
+ * report to this server.
+ */
+type EventHistoryChange = {
+  readonly kinds: readonly BundleEventChangeKind[];
+  readonly previous?: {
+    readonly bundleId: string;
+    readonly releaseId: string | null;
+    readonly appVersion: string;
+    readonly channel: string;
+    readonly minBundleId?: string;
+  };
+};
 type EventHistoryRow = {
   readonly toReleaseId?: string;
   readonly sdkVersion?: string;
+  /** The native build's built-in bundle ID, when the SDK reported it. */
+  readonly minBundleId?: string;
   readonly id: string;
   readonly installId: string;
   readonly type: "UPDATE_DOWNLOADED" | "UPDATE_APPLIED" | "RECOVERED" | "UPDATE_FAILED" | "UNCHANGED";
@@ -97,16 +121,28 @@ type EventHistoryRow = {
   readonly delivery?: NonNullable<DatabaseBundleEventMetadata["delivery"]>;
   /** `UPDATE_DOWNLOADED`: a patch failed, and the files or the archive came instead. */
   readonly patchFallback?: true;
+  /** `UNCHANGED`: what the report changed, the reason it was kept. */
+  readonly change?: EventHistoryChange;
+  /** A download or apply that arrived after its target already ran: it counted nothing. */
+  readonly late?: true;
+  /** A launch or crash whose download report never arrived, counted with it. */
+  readonly impliedDownload?: true;
 };
-type InstallationHistoryRow = EventHistoryRow & {
+type InstallationHistoryRow = EventHistoryRow & ({
   readonly type: "UPDATE_DOWNLOADED" | "UPDATE_APPLIED" | "RECOVERED" | "UPDATE_FAILED";
   readonly fromBundleId: string;
-};
+} | {
+  readonly type: "UNCHANGED";
+  readonly fromBundleId: null;
+  readonly change: EventHistoryChange;
+});
 type InsightsHttpResponse = UpdateHttpResponse & {
   readonly receivedAtMs: number;
 };
 type InstallationRow = {
   readonly httpResponse?: InsightsHttpResponse;
+  /** The native build's built-in bundle ID, when the SDK reported it. */
+  readonly minBundleId?: string;
   readonly installId: string;
   readonly userId: string | null;
   readonly lastKnownBundleId: string;
@@ -150,4 +186,4 @@ type ReportingOverview = InsightsScope & {
   };
 };
 //#endregion
-export { ActiveInstallationWindow, BundleEventFailureInput, CreateBundleEventRequest, CreateBundleEventRequestBase, CursorPage, EventCursorPage, EventHistoryRow, InsightsBundleSelection, InsightsCountMeasurement, InsightsHttpResponse, InstallationHistoryRow, InstallationRow, ReportingOverview };
+export { ActiveInstallationWindow, BundleEventFailureInput, CreateBundleEventRequest, CreateBundleEventRequestBase, CursorPage, EventCursorPage, EventHistoryChange, EventHistoryRow, InsightsBundleSelection, InsightsCountMeasurement, InsightsHttpResponse, InstallationHistoryRow, InstallationRow, ReportingOverview };

package/dist/server/domain.d.mts

@@ -1,4 +1,4 @@
-import { BundleEventFailure, BundleEventFailureReason, BundleEventFailureStage, DatabaseBundleEventMetadata } from "./eventRow.mjs";
+import { BundleEventChangeKind, BundleEventFailure, BundleEventFailureReason, BundleEventFailureStage, DatabaseBundleEventMetadata } from "./eventRow.mjs";
 import { InsightsScope } from "./modelTypes.mjs";
 import { UpdateHttpResponse } from "@hot-updater/protocol";
 //#region src/server/domain.d.ts
@@ -44,6 +44,12 @@ type CreateBundleEventRequestBase = {
   readonly cohort: string;
   readonly fingerprintHash: string | null;
   readonly sdkVersion?: string | null;
+  /**
+   * The bundle ID the native build ships as its built-in bundle. A report
+   * whose running bundle is this one, with no Release, runs the built-in
+   * bundle. Older SDKs leave it out.
+   */
+  readonly minBundleId?: string | null;
   readonly fromReleaseId: string | null;
   readonly toReleaseId: string | null;
 };
@@ -76,9 +82,27 @@ type CreateBundleEventRequest = (Movement & {
   readonly updateStrategy: null;
 });
 type ActiveInstallationWindow = "24h" | "7d" | "30d";
+/**
+ * What a kept UNCHANGED report changed against its installation's previous
+ * report: the running bundle or release, the app version, or the channel,
+ * with the previous values; `first_seen` alone for an installation's first
+ * report to this server.
+ */
+type EventHistoryChange = {
+  readonly kinds: readonly BundleEventChangeKind[];
+  readonly previous?: {
+    readonly bundleId: string;
+    readonly releaseId: string | null;
+    readonly appVersion: string;
+    readonly channel: string;
+    readonly minBundleId?: string;
+  };
+};
 type EventHistoryRow = {
   readonly toReleaseId?: string;
   readonly sdkVersion?: string;
+  /** The native build's built-in bundle ID, when the SDK reported it. */
+  readonly minBundleId?: string;
   readonly id: string;
   readonly installId: string;
   readonly type: "UPDATE_DOWNLOADED" | "UPDATE_APPLIED" | "RECOVERED" | "UPDATE_FAILED" | "UNCHANGED";
@@ -97,16 +121,28 @@ type EventHistoryRow = {
   readonly delivery?: NonNullable<DatabaseBundleEventMetadata["delivery"]>;
   /** `UPDATE_DOWNLOADED`: a patch failed, and the files or the archive came instead. */
   readonly patchFallback?: true;
+  /** `UNCHANGED`: what the report changed, the reason it was kept. */
+  readonly change?: EventHistoryChange;
+  /** A download or apply that arrived after its target already ran: it counted nothing. */
+  readonly late?: true;
+  /** A launch or crash whose download report never arrived, counted with it. */
+  readonly impliedDownload?: true;
 };
-type InstallationHistoryRow = EventHistoryRow & {
+type InstallationHistoryRow = EventHistoryRow & ({
   readonly type: "UPDATE_DOWNLOADED" | "UPDATE_APPLIED" | "RECOVERED" | "UPDATE_FAILED";
   readonly fromBundleId: string;
-};
+} | {
+  readonly type: "UNCHANGED";
+  readonly fromBundleId: null;
+  readonly change: EventHistoryChange;
+});
 type InsightsHttpResponse = UpdateHttpResponse & {
   readonly receivedAtMs: number;
 };
 type InstallationRow = {
   readonly httpResponse?: InsightsHttpResponse;
+  /** The native build's built-in bundle ID, when the SDK reported it. */
+  readonly minBundleId?: string;
   readonly installId: string;
   readonly userId: string | null;
   readonly lastKnownBundleId: string;
@@ -150,4 +186,4 @@ type ReportingOverview = InsightsScope & {
   };
 };
 //#endregion
-export { ActiveInstallationWindow, BundleEventFailureInput, CreateBundleEventRequest, CreateBundleEventRequestBase, CursorPage, EventCursorPage, EventHistoryRow, InsightsBundleSelection, InsightsCountMeasurement, InsightsHttpResponse, InstallationHistoryRow, InstallationRow, ReportingOverview };
+export { ActiveInstallationWindow, BundleEventFailureInput, CreateBundleEventRequest, CreateBundleEventRequestBase, CursorPage, EventCursorPage, EventHistoryChange, EventHistoryRow, InsightsBundleSelection, InsightsCountMeasurement, InsightsHttpResponse, InstallationHistoryRow, InstallationRow, ReportingOverview };

package/dist/server/eventInput.cjs

@@ -31,6 +31,11 @@ function readEventId(payload) {
 	if (!(0, _hot_updater_plugin_core.isUUIDv7)(value)) throw new require_errors.InsightsBadRequestError("Invalid event field: eventId");
 	return value;
 }
+/**
+* The native build's built-in bundle ID: a bundle ID's length at most, and
+* left out when it is missing or malformed, so the report still records.
+*/
+const readMinBundleId = (value) => typeof value === "string" && value.length > 0 && value.length <= 36 ? value : null;
 /** One value of an open set: any other value reads as `unknown`. */
 const oneOf = (values, value) => values.includes(value) ? value : "unknown";
 const STAGES = [
@@ -156,6 +161,7 @@ function requireEvent(payload) {
 		cohort: requireStringField(payload, "cohort"),
 		fingerprintHash: requireNullableStringField(payload, "fingerprintHash"),
 		sdkVersion: payload.sdkVersion === void 0 ? null : requireNullableStringField(payload, "sdkVersion"),
+		minBundleId: readMinBundleId(payload.minBundleId),
 		fromReleaseId: requireNullableStringField(payload, "fromReleaseId"),
 		toReleaseId: requireNullableStringField(payload, "toReleaseId")
 	};
@@ -237,6 +243,7 @@ function createBundleEventRow(input) {
 		cohort: input.cohort,
 		fingerprint_hash: input.fingerprintHash,
 		sdk_version: input.sdkVersion ?? null,
+		...input.minBundleId ? { min_bundle_id: input.minBundleId } : {},
 		update_strategy: input.updateStrategy
 	};
 	switch (input.type) {

package/dist/server/eventInput.mjs

@@ -31,6 +31,11 @@ function readEventId(payload) {
 	if (!isUUIDv7(value)) throw new InsightsBadRequestError("Invalid event field: eventId");
 	return value;
 }
+/**
+* The native build's built-in bundle ID: a bundle ID's length at most, and
+* left out when it is missing or malformed, so the report still records.
+*/
+const readMinBundleId = (value) => typeof value === "string" && value.length > 0 && value.length <= 36 ? value : null;
 /** One value of an open set: any other value reads as `unknown`. */
 const oneOf = (values, value) => values.includes(value) ? value : "unknown";
 const STAGES = [
@@ -156,6 +161,7 @@ function requireEvent(payload) {
 		cohort: requireStringField(payload, "cohort"),
 		fingerprintHash: requireNullableStringField(payload, "fingerprintHash"),
 		sdkVersion: payload.sdkVersion === void 0 ? null : requireNullableStringField(payload, "sdkVersion"),
+		minBundleId: readMinBundleId(payload.minBundleId),
 		fromReleaseId: requireNullableStringField(payload, "fromReleaseId"),
 		toReleaseId: requireNullableStringField(payload, "toReleaseId")
 	};
@@ -237,6 +243,7 @@ function createBundleEventRow(input) {
 		cohort: input.cohort,
 		fingerprint_hash: input.fingerprintHash,
 		sdk_version: input.sdkVersion ?? null,
+		...input.minBundleId ? { min_bundle_id: input.minBundleId } : {},
 		update_strategy: input.updateStrategy
 	};
 	switch (input.type) {

package/dist/server/eventRow.cjs

@@ -1,12 +1,32 @@
 let _hot_updater_plugin_core = require("@hot-updater/plugin-core");
 //#region src/server/eventRow.ts
+const CHANGE_KINDS = /* @__PURE__ */ new Set([
+	"first_seen",
+	"bundle",
+	"release",
+	"app_version",
+	"channel",
+	"native_build"
+]);
+const isBundleEventChange = (value) => (0, _hot_updater_plugin_core.isDatabaseJsonObject)(value) && Array.isArray(value.kinds) && value.kinds.length > 0 && value.kinds.every((kind) => CHANGE_KINDS.has(kind)) && (value.previous === null || (0, _hot_updater_plugin_core.isDatabaseJsonObject)(value.previous) && typeof value.previous.bundle_id === "string" && (value.previous.release_id === null || typeof value.previous.release_id === "string") && typeof value.previous.app_version === "string" && typeof value.previous.channel === "string" && isOptional(value.previous, "min_bundle_id", isString));
 const isOptional = (value, key, valid) => !Object.hasOwn(value, key) || valid(value[key]);
 const isString = (value) => typeof value === "string";
 const isDatabaseHttpResponse = (value) => (0, _hot_updater_plugin_core.isDatabaseJsonObject)(value) && (value.resource === "catalog" || value.resource === "artifact") && isString(value.path) && Number.isSafeInteger(value.status) && (value.body === null || isString(value.body)) && typeof value.body_truncated === "boolean" && Number.isSafeInteger(value.received_at_ms);
 /** An `UPDATE_FAILED` report's stored failure: a stage and a reason, and what else the client knew. */
 const isDatabaseBundleEventFailure = (value) => (0, _hot_updater_plugin_core.isDatabaseJsonObject)(value) && isString(value.stage) && isString(value.reason) && isOptional(value, "resource", isString) && isOptional(value, "http_status", (status) => Number.isSafeInteger(status)) && isOptional(value, "transport", isString) && isOptional(value, "origin_code", isString) && isOptional(value, "error_message", isString) && isOptional(value, "error_stack", isString);
-const isDatabaseBundleEventMetadata = (value) => (0, _hot_updater_plugin_core.isDatabaseJsonObject)(value) && typeof value.cohort === "string" && (value.update_strategy === null || value.update_strategy === "fingerprint" || value.update_strategy === "appVersion") && (value.fingerprint_hash === null || typeof value.fingerprint_hash === "string") && (value.sdk_version === null || typeof value.sdk_version === "string") && isOptional(value, "failure", isDatabaseBundleEventFailure) && isOptional(value, "http_response", isDatabaseHttpResponse) && isOptional(value, "delivery", isString) && isOptional(value, "patch_fallback", (flag) => typeof flag === "boolean");
+const isDatabaseBundleEventMetadata = (value) => (0, _hot_updater_plugin_core.isDatabaseJsonObject)(value) && typeof value.cohort === "string" && (value.update_strategy === null || value.update_strategy === "fingerprint" || value.update_strategy === "appVersion") && (value.fingerprint_hash === null || typeof value.fingerprint_hash === "string") && (value.sdk_version === null || typeof value.sdk_version === "string") && isOptional(value, "min_bundle_id", isString) && isOptional(value, "failure", isDatabaseBundleEventFailure) && isOptional(value, "http_response", isDatabaseHttpResponse) && isOptional(value, "delivery", isString) && isOptional(value, "patch_fallback", (flag) => typeof flag === "boolean") && isOptional(value, "change", isBundleEventChange) && isOptional(value, "late", (flag) => flag === true) && isOptional(value, "implied_download", (flag) => flag === true);
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* The built-in bundle a report says its installation runs: the running
+* bundle, which a download leaves at its source, when it is the native
+* build's built-in bundle, whatever Release selected it. Null for any other
+* bundle, and for a report without the build's built-in bundle ID.
+*/
+const runningBuiltinBundleId = (row) => {
+	const running = row.type === "UPDATE_DOWNLOADED" ? row.from_bundle_id : row.to_bundle_id;
+	const builtin = isRecord(row.metadata) ? row.metadata.min_bundle_id : null;
+	return typeof builtin === "string" && running === builtin ? builtin : null;
+};
 const isIdentity = (value) => typeof value === "string" && value.length > 0 && value.length <= 255;
 const isTextOrNull = (value) => value === null || typeof value === "string";
 /** Each bundle event field and what it holds. */
@@ -25,13 +45,14 @@ const BUNDLE_EVENT_FIELDS = {
 	metadata: isDatabaseBundleEventMetadata,
 	received_at_ms: (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0
 };
+const hasMetadata = (row, key) => isRecord(row.metadata) && Object.hasOwn(row.metadata, key);
 const updateStrategyOf = (row) => isRecord(row.metadata) ? row.metadata.update_strategy : void 0;
 /**
 * A movement, or a failed update, names the bundle it left and how the
 * device updates, and a failed update says what failed; an unchanged report
 * names neither.
 */
-const hasEventInvariants = (row) => (row.type === "UPDATE_DOWNLOADED" || row.type === "UPDATE_APPLIED" || row.type === "RECOVERED" || row.type === "UPDATE_FAILED") && typeof row.from_bundle_id === "string" && (updateStrategyOf(row) === "fingerprint" || updateStrategyOf(row) === "appVersion") && (row.type !== "UPDATE_FAILED" || isRecord(row.metadata) && isRecord(row.metadata.failure)) || row.type === "UNCHANGED" && row.from_bundle_id === null && updateStrategyOf(row) === null;
+const hasEventInvariants = (row) => (row.type === "UPDATE_DOWNLOADED" || row.type === "UPDATE_APPLIED" || row.type === "RECOVERED" || row.type === "UPDATE_FAILED") && typeof row.from_bundle_id === "string" && (updateStrategyOf(row) === "fingerprint" || updateStrategyOf(row) === "appVersion") && (row.type !== "UPDATE_FAILED" || isRecord(row.metadata) && isRecord(row.metadata.failure)) && !hasMetadata(row, "change") && (!hasMetadata(row, "late") || row.type === "UPDATE_DOWNLOADED" || row.type === "UPDATE_APPLIED") && (!hasMetadata(row, "implied_download") || row.type === "UPDATE_APPLIED" || row.type === "RECOVERED") || row.type === "UNCHANGED" && !hasMetadata(row, "late") && row.from_bundle_id === null && updateStrategyOf(row) === null;
 /**
 * Throws unless `row` has exactly the bundle event fields, each of its type,
 * and the invariants of its event type: `invalid-field` for an unknown field,
@@ -46,4 +67,5 @@ const validateBundleEventFields = (row) => {
 //#endregion
 exports.isDatabaseBundleEventMetadata = isDatabaseBundleEventMetadata;
 exports.isRecord = isRecord;
+exports.runningBuiltinBundleId = runningBuiltinBundleId;
 exports.validateBundleEventFields = validateBundleEventFields;

package/dist/server/eventRow.d.cts

@@ -25,12 +25,33 @@ type DatabaseHttpResponse = DatabaseJsonObject & {
   readonly body_truncated: boolean;
   readonly received_at_ms: number;
 };
+/** What a kept UNCHANGED row changed against its installation's head. */
+type BundleEventChangeKind = "first_seen" | "bundle" | "release" | "app_version" | "channel" | "native_build";
+/**
+ * An UNCHANGED report the server keeps: what it changed against its
+ * installation's head, and the running values the head held before it. A
+ * report from an installation without a head is `first_seen` alone, with no
+ * previous values: the installation is new to this server, not necessarily
+ * to its device.
+ */
+type BundleEventChange = DatabaseJsonObject & {
+  readonly kinds: BundleEventChangeKind[];
+  readonly previous: (DatabaseJsonObject & {
+    readonly bundle_id: string;
+    readonly release_id: string | null;
+    readonly app_version: string;
+    readonly channel: string;
+    readonly min_bundle_id?: string;
+  }) | null;
+};
 /** Ancillary report data; queryable identity and lifecycle fields stay on the row. */
 type DatabaseBundleEventMetadata = DatabaseJsonObject & {
   readonly cohort: string;
   readonly update_strategy: "fingerprint" | "appVersion" | null;
   readonly fingerprint_hash: string | null;
   readonly sdk_version: string | null;
+  /** The native build's built-in bundle ID, when the SDK reports it. */
+  readonly min_bundle_id?: string;
   /** `UPDATE_FAILED`: what failed. */
   readonly failure?: BundleEventFailure;
   readonly http_response?: DatabaseHttpResponse;
@@ -38,6 +59,19 @@ type DatabaseBundleEventMetadata = DatabaseJsonObject & {
   readonly delivery?: "patch" | "manifest" | "archive" | "unknown";
   /** `UPDATE_DOWNLOADED`: a patch failed and the full files came instead. */
   readonly patch_fallback?: boolean;
+  /** A kept `UNCHANGED` row: what it changed, which the server sets. */
+  readonly change?: BundleEventChange;
+  /**
+   * A download or apply that arrived after its installation already ran its
+   * target, as when a reload cut the first runtime's report short: the
+   * server keeps it in history, but it moves and counts nothing.
+   */
+  readonly late?: true;
+  /**
+   * A launch or crash of a bundle whose download report never arrived: the
+   * server counted that download with it.
+   */
+  readonly implied_download?: true;
 };
 type BundleEventRowBase = {
   readonly id: string;
@@ -68,4 +102,4 @@ type BundleEventRow = BundleEventRowBase & ({
   readonly from_bundle_id: null;
 });
 //#endregion
-export { BundleEventFailure, BundleEventFailureReason, BundleEventFailureStage, BundleEventRow, BundleEventRowBase, DatabaseBundleEventMetadata, DatabaseHttpResponse };
+export { BundleEventChange, BundleEventChangeKind, BundleEventFailure, BundleEventFailureReason, BundleEventFailureStage, BundleEventRow, BundleEventRowBase, DatabaseBundleEventMetadata, DatabaseHttpResponse };

package/dist/server/eventRow.d.mts

@@ -25,12 +25,33 @@ type DatabaseHttpResponse = DatabaseJsonObject & {
   readonly body_truncated: boolean;
   readonly received_at_ms: number;
 };
+/** What a kept UNCHANGED row changed against its installation's head. */
+type BundleEventChangeKind = "first_seen" | "bundle" | "release" | "app_version" | "channel" | "native_build";
+/**
+ * An UNCHANGED report the server keeps: what it changed against its
+ * installation's head, and the running values the head held before it. A
+ * report from an installation without a head is `first_seen` alone, with no
+ * previous values: the installation is new to this server, not necessarily
+ * to its device.
+ */
+type BundleEventChange = DatabaseJsonObject & {
+  readonly kinds: BundleEventChangeKind[];
+  readonly previous: (DatabaseJsonObject & {
+    readonly bundle_id: string;
+    readonly release_id: string | null;
+    readonly app_version: string;
+    readonly channel: string;
+    readonly min_bundle_id?: string;
+  }) | null;
+};
 /** Ancillary report data; queryable identity and lifecycle fields stay on the row. */
 type DatabaseBundleEventMetadata = DatabaseJsonObject & {
   readonly cohort: string;
   readonly update_strategy: "fingerprint" | "appVersion" | null;
   readonly fingerprint_hash: string | null;
   readonly sdk_version: string | null;
+  /** The native build's built-in bundle ID, when the SDK reports it. */
+  readonly min_bundle_id?: string;
   /** `UPDATE_FAILED`: what failed. */
   readonly failure?: BundleEventFailure;
   readonly http_response?: DatabaseHttpResponse;
@@ -38,6 +59,19 @@ type DatabaseBundleEventMetadata = DatabaseJsonObject & {
   readonly delivery?: "patch" | "manifest" | "archive" | "unknown";
   /** `UPDATE_DOWNLOADED`: a patch failed and the full files came instead. */
   readonly patch_fallback?: boolean;
+  /** A kept `UNCHANGED` row: what it changed, which the server sets. */
+  readonly change?: BundleEventChange;
+  /**
+   * A download or apply that arrived after its installation already ran its
+   * target, as when a reload cut the first runtime's report short: the
+   * server keeps it in history, but it moves and counts nothing.
+   */
+  readonly late?: true;
+  /**
+   * A launch or crash of a bundle whose download report never arrived: the
+   * server counted that download with it.
+   */
+  readonly implied_download?: true;
 };
 type BundleEventRowBase = {
   readonly id: string;
@@ -68,4 +102,4 @@ type BundleEventRow = BundleEventRowBase & ({
   readonly from_bundle_id: null;
 });
 //#endregion
-export { BundleEventFailure, BundleEventFailureReason, BundleEventFailureStage, BundleEventRow, BundleEventRowBase, DatabaseBundleEventMetadata, DatabaseHttpResponse };
+export { BundleEventChange, BundleEventChangeKind, BundleEventFailure, BundleEventFailureReason, BundleEventFailureStage, BundleEventRow, BundleEventRowBase, DatabaseBundleEventMetadata, DatabaseHttpResponse };

package/dist/server/eventRow.mjs

@@ -1,12 +1,32 @@
 import { DatabaseAdapterInputError, isDatabaseJsonObject } from "@hot-updater/plugin-core";
 //#region src/server/eventRow.ts
+const CHANGE_KINDS = /* @__PURE__ */ new Set([
+	"first_seen",
+	"bundle",
+	"release",
+	"app_version",
+	"channel",
+	"native_build"
+]);
+const isBundleEventChange = (value) => isDatabaseJsonObject(value) && Array.isArray(value.kinds) && value.kinds.length > 0 && value.kinds.every((kind) => CHANGE_KINDS.has(kind)) && (value.previous === null || isDatabaseJsonObject(value.previous) && typeof value.previous.bundle_id === "string" && (value.previous.release_id === null || typeof value.previous.release_id === "string") && typeof value.previous.app_version === "string" && typeof value.previous.channel === "string" && isOptional(value.previous, "min_bundle_id", isString));
 const isOptional = (value, key, valid) => !Object.hasOwn(value, key) || valid(value[key]);
 const isString = (value) => typeof value === "string";
 const isDatabaseHttpResponse = (value) => isDatabaseJsonObject(value) && (value.resource === "catalog" || value.resource === "artifact") && isString(value.path) && Number.isSafeInteger(value.status) && (value.body === null || isString(value.body)) && typeof value.body_truncated === "boolean" && Number.isSafeInteger(value.received_at_ms);
 /** An `UPDATE_FAILED` report's stored failure: a stage and a reason, and what else the client knew. */
 const isDatabaseBundleEventFailure = (value) => isDatabaseJsonObject(value) && isString(value.stage) && isString(value.reason) && isOptional(value, "resource", isString) && isOptional(value, "http_status", (status) => Number.isSafeInteger(status)) && isOptional(value, "transport", isString) && isOptional(value, "origin_code", isString) && isOptional(value, "error_message", isString) && isOptional(value, "error_stack", isString);
-const isDatabaseBundleEventMetadata = (value) => isDatabaseJsonObject(value) && typeof value.cohort === "string" && (value.update_strategy === null || value.update_strategy === "fingerprint" || value.update_strategy === "appVersion") && (value.fingerprint_hash === null || typeof value.fingerprint_hash === "string") && (value.sdk_version === null || typeof value.sdk_version === "string") && isOptional(value, "failure", isDatabaseBundleEventFailure) && isOptional(value, "http_response", isDatabaseHttpResponse) && isOptional(value, "delivery", isString) && isOptional(value, "patch_fallback", (flag) => typeof flag === "boolean");
+const isDatabaseBundleEventMetadata = (value) => isDatabaseJsonObject(value) && typeof value.cohort === "string" && (value.update_strategy === null || value.update_strategy === "fingerprint" || value.update_strategy === "appVersion") && (value.fingerprint_hash === null || typeof value.fingerprint_hash === "string") && (value.sdk_version === null || typeof value.sdk_version === "string") && isOptional(value, "min_bundle_id", isString) && isOptional(value, "failure", isDatabaseBundleEventFailure) && isOptional(value, "http_response", isDatabaseHttpResponse) && isOptional(value, "delivery", isString) && isOptional(value, "patch_fallback", (flag) => typeof flag === "boolean") && isOptional(value, "change", isBundleEventChange) && isOptional(value, "late", (flag) => flag === true) && isOptional(value, "implied_download", (flag) => flag === true);
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* The built-in bundle a report says its installation runs: the running
+* bundle, which a download leaves at its source, when it is the native
+* build's built-in bundle, whatever Release selected it. Null for any other
+* bundle, and for a report without the build's built-in bundle ID.
+*/
+const runningBuiltinBundleId = (row) => {
+	const running = row.type === "UPDATE_DOWNLOADED" ? row.from_bundle_id : row.to_bundle_id;
+	const builtin = isRecord(row.metadata) ? row.metadata.min_bundle_id : null;
+	return typeof builtin === "string" && running === builtin ? builtin : null;
+};
 const isIdentity = (value) => typeof value === "string" && value.length > 0 && value.length <= 255;
 const isTextOrNull = (value) => value === null || typeof value === "string";
 /** Each bundle event field and what it holds. */
@@ -25,13 +45,14 @@ const BUNDLE_EVENT_FIELDS = {
 	metadata: isDatabaseBundleEventMetadata,
 	received_at_ms: (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0
 };
+const hasMetadata = (row, key) => isRecord(row.metadata) && Object.hasOwn(row.metadata, key);
 const updateStrategyOf = (row) => isRecord(row.metadata) ? row.metadata.update_strategy : void 0;
 /**
 * A movement, or a failed update, names the bundle it left and how the
 * device updates, and a failed update says what failed; an unchanged report
 * names neither.
 */
-const hasEventInvariants = (row) => (row.type === "UPDATE_DOWNLOADED" || row.type === "UPDATE_APPLIED" || row.type === "RECOVERED" || row.type === "UPDATE_FAILED") && typeof row.from_bundle_id === "string" && (updateStrategyOf(row) === "fingerprint" || updateStrategyOf(row) === "appVersion") && (row.type !== "UPDATE_FAILED" || isRecord(row.metadata) && isRecord(row.metadata.failure)) || row.type === "UNCHANGED" && row.from_bundle_id === null && updateStrategyOf(row) === null;
+const hasEventInvariants = (row) => (row.type === "UPDATE_DOWNLOADED" || row.type === "UPDATE_APPLIED" || row.type === "RECOVERED" || row.type === "UPDATE_FAILED") && typeof row.from_bundle_id === "string" && (updateStrategyOf(row) === "fingerprint" || updateStrategyOf(row) === "appVersion") && (row.type !== "UPDATE_FAILED" || isRecord(row.metadata) && isRecord(row.metadata.failure)) && !hasMetadata(row, "change") && (!hasMetadata(row, "late") || row.type === "UPDATE_DOWNLOADED" || row.type === "UPDATE_APPLIED") && (!hasMetadata(row, "implied_download") || row.type === "UPDATE_APPLIED" || row.type === "RECOVERED") || row.type === "UNCHANGED" && !hasMetadata(row, "late") && row.from_bundle_id === null && updateStrategyOf(row) === null;
 /**
 * Throws unless `row` has exactly the bundle event fields, each of its type,
 * and the invariants of its event type: `invalid-field` for an unknown field,
@@ -44,4 +65,4 @@ const validateBundleEventFields = (row) => {
 	if (!hasEventInvariants(row)) throw new DatabaseAdapterInputError("invalid-data");
 };
 //#endregion
-export { isDatabaseBundleEventMetadata, isRecord, validateBundleEventFields };
+export { isDatabaseBundleEventMetadata, isRecord, runningBuiltinBundleId, validateBundleEventFields };

package/dist/server/index.cjs

@@ -1,9 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_schema = require("./schema.cjs");
 const require_model = require("./model.cjs");
 const require_official = require("./official.cjs");
 const require_errors = require("./errors.cjs");
 const require_provider = require("./provider.cjs");
-const require_schema = require("./schema.cjs");
 const require_recordEvent = require("./recordEvent.cjs");
 const require_reads = require("./reads.cjs");
 const require_routes = require("./routes.cjs");

package/dist/server/index.d.cts

@@ -2,7 +2,7 @@ import { BundleEventFailure, BundleEventFailureReason, BundleEventFailureStage,
 import { InsightsBundleEventFilter, InsightsCountEventSeriesInput, InsightsCountEventsInput, InsightsCountLatestEventsInput, InsightsCoverage, InsightsEventCursor, InsightsEventFilter, InsightsEventSeriesPoint, InsightsFindLatestEventsInput, InsightsGetAppUsageInput, InsightsGetAppUsageResult, InsightsGetReleaseActivityInput, InsightsGetReleaseActivityResult, InsightsListEventsInput, InsightsModel, InsightsRecordEventInput, InsightsScope, InsightsTimeRange, ReleaseActivityMetrics, ReleaseReference } from "./modelTypes.cjs";
 import { DEFAULT_INSIGHTS_RETENTION, InsightsRetention, InsightsSchema, createInsightsSchema, insightsSchema } from "./schema.cjs";
 import { InsightsFailureBreakdown, InsightsUpdateFailures, InsightsUpdateFailuresInput } from "./reads.cjs";
-import { ActiveInstallationWindow, BundleEventFailureInput, CreateBundleEventRequest, CreateBundleEventRequestBase, CursorPage, EventCursorPage, EventHistoryRow, InsightsBundleSelection, InsightsCountMeasurement, InsightsHttpResponse, InstallationHistoryRow, InstallationRow, ReportingOverview } from "./domain.cjs";
+import { ActiveInstallationWindow, BundleEventFailureInput, CreateBundleEventRequest, CreateBundleEventRequestBase, CursorPage, EventCursorPage, EventHistoryChange, EventHistoryRow, InsightsBundleSelection, InsightsCountMeasurement, InsightsHttpResponse, InstallationHistoryRow, InstallationRow, ReportingOverview } from "./domain.cjs";
 import { InsightsBadRequestError } from "./errors.cjs";
 import { createInsightsModel } from "./model.cjs";
 import { InsightsEventPageInput, InsightsInstallationEventPageInput, InsightsProvider, InsightsUserInstallationPageInput } from "./types.cjs";
@@ -284,6 +284,38 @@ declare const insights: (options?: InsightsOptions) => import("@hot-updater/plug
       readonly sort: readonly ["bucket_start_ms"];
     };
   }, never, readonly ["channel", "platform", "app_version", "release_id", "bucket_start_ms"]>;
+  readonly insights_builtin_distribution: import("@hot-updater/plugin-core").AggregateDefinition<{
+    readonly channel: {
+      readonly type: "string";
+    };
+    readonly platform: {
+      readonly type: "string";
+      readonly maxLength: 16;
+    };
+    readonly app_version: {
+      readonly type: "string";
+    };
+    readonly release_id: {
+      readonly type: "string";
+      readonly maxLength: 36;
+    };
+    readonly builtin_bundle_id: {
+      readonly type: "string";
+      readonly maxLength: 36;
+    };
+    readonly bucket_start_ms: {
+      readonly type: "integer";
+    };
+  }, "latest_installations", {
+    readonly byScope: {
+      readonly eq: readonly ["channel", "platform"];
+      readonly sort: readonly ["bucket_start_ms"];
+    };
+    readonly byVersion: {
+      readonly eq: readonly ["channel", "platform", "app_version"];
+      readonly sort: readonly ["bucket_start_ms"];
+    };
+  }, never, readonly ["channel", "platform", "app_version", "release_id", "builtin_bundle_id", "bucket_start_ms"]>;
   readonly insights_latest_by_bundle: import("@hot-updater/plugin-core").AggregateDefinition<{
     readonly platform: {
       readonly type: "string";
@@ -390,4 +422,4 @@ declare const insights: (options?: InsightsOptions) => import("@hot-updater/plug
   endpoints: PluginEndpoint[];
 }, {}>;
 //#endregion
-export { type ActiveInstallationWindow, type BundleEventFailure, type BundleEventFailureInput, type BundleEventFailureReason, type BundleEventFailureStage, type BundleEventRow, type BundleEventRowBase, type CreateBundleEventRequest, type CreateBundleEventRequestBase, type CursorPage, DEFAULT_INSIGHTS_RETENTION, type DatabaseBundleEventMetadata, type EventCursorPage, type EventHistoryRow, InsightsApi, InsightsBadRequestError, type InsightsBundleEventFilter, type InsightsBundleSelection, type InsightsCountEventSeriesInput, type InsightsCountEventsInput, type InsightsCountLatestEventsInput, type InsightsCountMeasurement, type InsightsCoverage, type InsightsEventCursor, type InsightsEventFilter, type InsightsEventPageInput, type InsightsEventSeriesPoint, type InsightsFailureBreakdown, type InsightsFindLatestEventsInput, type InsightsGetAppUsageInput, type InsightsGetAppUsageResult, type InsightsGetReleaseActivityInput, type InsightsGetReleaseActivityResult, type InsightsHttpResponse, type InsightsIdentityParts, type InsightsInstallationEventPageInput, type InsightsListEventsInput, type InsightsModel, InsightsOptions, type InsightsProvider, type InsightsRecordEventInput, type InsightsRetention, type InsightsSchema, type InsightsScope, type InsightsTimeRange, type InsightsUpdateFailures, type InsightsUpdateFailuresInput, type InsightsUserInstallationPageInput, type InstallationHistoryRow, type InstallationRow, type ReleaseActivityMetrics, type ReleaseReference, type ReportingOverview, createInsightsModel, createInsightsProvider, createInsightsSchema, insights, insightsIdentity, insightsSchema };
+export { type ActiveInstallationWindow, type BundleEventFailure, type BundleEventFailureInput, type BundleEventFailureReason, type BundleEventFailureStage, type BundleEventRow, type BundleEventRowBase, type CreateBundleEventRequest, type CreateBundleEventRequestBase, type CursorPage, DEFAULT_INSIGHTS_RETENTION, type DatabaseBundleEventMetadata, type EventCursorPage, type EventHistoryChange, type EventHistoryRow, InsightsApi, InsightsBadRequestError, type InsightsBundleEventFilter, type InsightsBundleSelection, type InsightsCountEventSeriesInput, type InsightsCountEventsInput, type InsightsCountLatestEventsInput, type InsightsCountMeasurement, type InsightsCoverage, type InsightsEventCursor, type InsightsEventFilter, type InsightsEventPageInput, type InsightsEventSeriesPoint, type InsightsFailureBreakdown, type InsightsFindLatestEventsInput, type InsightsGetAppUsageInput, type InsightsGetAppUsageResult, type InsightsGetReleaseActivityInput, type InsightsGetReleaseActivityResult, type InsightsHttpResponse, type InsightsIdentityParts, type InsightsInstallationEventPageInput, type InsightsListEventsInput, type InsightsModel, InsightsOptions, type InsightsProvider, type InsightsRecordEventInput, type InsightsRetention, type InsightsSchema, type InsightsScope, type InsightsTimeRange, type InsightsUpdateFailures, type InsightsUpdateFailuresInput, type InsightsUserInstallationPageInput, type InstallationHistoryRow, type InstallationRow, type ReleaseActivityMetrics, type ReleaseReference, type ReportingOverview, createInsightsModel, createInsightsProvider, createInsightsSchema, insights, insightsIdentity, insightsSchema };