@hot-updater/plugin-insights 1.0.0-rc.20

package/dist/server/eventInput.mjs

@@ -0,0 +1,282 @@
+import { InsightsBadRequestError, InsightsPayloadTooLargeError } from "./errors.mjs";
+import { createUUIDv7, isUUIDv7 } from "@hot-updater/plugin-core";
+//#region src/server/eventInput.ts
+const MAX_EVENT_STRING_LENGTH = 1024;
+const MAX_IDENTITY_LENGTH = 255;
+const EVENT_BODY_MAX_BYTES = 16384;
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireStringField(payload, key) {
+	const value = payload[key];
+	if (typeof value !== "string" || value.length === 0 || value.length > MAX_EVENT_STRING_LENGTH || new TextDecoder("utf-8", { ignoreBOM: true }).decode(new TextEncoder().encode(value)) !== value) throw new InsightsBadRequestError(`Invalid event field: ${key}`);
+	return value;
+}
+function requireNullableStringField(payload, key) {
+	if (payload[key] === null) return null;
+	return requireStringField(payload, key);
+}
+function requireIdentityField(payload, key) {
+	const value = requireStringField(payload, key);
+	if (value.length > MAX_IDENTITY_LENGTH) throw new InsightsBadRequestError(`Invalid event field: ${key}`);
+	return value;
+}
+/**
+* The report's idempotency key, when the client sends one: it creates the
+* UUIDv7 once and repeats it on every retry of that report.
+*/
+function readEventId(payload) {
+	const value = payload.eventId;
+	if (value === void 0) return void 0;
+	if (!isUUIDv7(value)) throw new InsightsBadRequestError("Invalid event field: eventId");
+	return value;
+}
+/** One value of an open set: any other value reads as `unknown`. */
+const oneOf = (values, value) => values.includes(value) ? value : "unknown";
+const STAGES = [
+	"check",
+	"download",
+	"install"
+];
+const REASONS = [
+	"network",
+	"http",
+	"invalid_response",
+	"hash_mismatch",
+	"signature",
+	"patch",
+	"extract",
+	"storage"
+];
+const RESOURCES = [
+	"catalog",
+	"artifact",
+	"manifest",
+	"file",
+	"patch",
+	"archive"
+];
+const TRANSPORTS = [
+	"timeout",
+	"dns",
+	"tls",
+	"connection",
+	"offline",
+	"cancelled"
+];
+const DELIVERIES = [
+	"patch",
+	"manifest",
+	"archive"
+];
+/** A storage error code or an Android exit reason: letters, digits, and `._-`. */
+const CODE = /^[A-Za-z0-9._-]{1,64}$/;
+const readCode = (value) => typeof value === "string" && CODE.test(value) ? value : void 0;
+const readMetadata = (payload) => isRecord(payload.metadata) ? payload.metadata : {};
+/**
+* What an UPDATE_FAILED report says failed. It never refuses the report: an
+* unknown value of a set reads as `unknown`, a missing or malformed failure
+* as an unknown stage and reason, and a malformed optional field is left out,
+* as is a null one.
+*/
+function readFailure(value) {
+	const failure = isRecord(value) ? value : {};
+	const httpStatus = failure.httpStatus;
+	const originCode = readCode(failure.originCode);
+	const previousProcessExit = readCode(failure.previousProcessExit);
+	return {
+		stage: oneOf(STAGES, failure.stage),
+		reason: oneOf(REASONS, failure.reason),
+		...failure.resource == null ? {} : { resource: oneOf(RESOURCES, failure.resource) },
+		...Number.isSafeInteger(httpStatus) && httpStatus >= 100 && httpStatus <= 599 ? { httpStatus } : {},
+		...failure.transport == null ? {} : { transport: oneOf(TRANSPORTS, failure.transport) },
+		...originCode === void 0 ? {} : { originCode },
+		...previousProcessExit === void 0 ? {} : { previousProcessExit }
+	};
+}
+async function readBoundedText(request) {
+	const contentLength = request.headers.get("content-length");
+	const declaredByteLength = Number(contentLength);
+	if (contentLength !== null && Number.isSafeInteger(declaredByteLength) && declaredByteLength > 16384) throw new InsightsPayloadTooLargeError(EVENT_BODY_MAX_BYTES);
+	if (request.body === null) return "";
+	const reader = request.body.getReader();
+	const decoder = new TextDecoder();
+	let byteLength = 0;
+	let text = "";
+	while (true) {
+		const result = await reader.read();
+		if (result.done) break;
+		byteLength += result.value.byteLength;
+		if (byteLength > 16384) {
+			await reader.cancel();
+			throw new InsightsPayloadTooLargeError(EVENT_BODY_MAX_BYTES);
+		}
+		text += decoder.decode(result.value, { stream: true });
+	}
+	return text + decoder.decode();
+}
+async function parseJson(request) {
+	const text = await readBoundedText(request);
+	try {
+		return JSON.parse(text);
+	} catch (error) {
+		if (error instanceof SyntaxError) throw new InsightsBadRequestError("Invalid event payload");
+		throw error;
+	}
+}
+function requireEvent(payload) {
+	if (!isRecord(payload)) throw new InsightsBadRequestError("Invalid event payload");
+	const platform = requireStringField(payload, "platform");
+	if (platform !== "ios" && platform !== "android") throw new InsightsBadRequestError("Invalid event field: platform");
+	const eventId = readEventId(payload);
+	const base = {
+		...eventId === void 0 ? {} : { eventId },
+		installId: requireIdentityField(payload, "installId"),
+		toBundleId: requireStringField(payload, "toBundleId"),
+		...payload.userId === void 0 ? {} : { userId: requireIdentityField(payload, "userId") },
+		platform,
+		appVersion: requireStringField(payload, "appVersion"),
+		channel: requireStringField(payload, "channel"),
+		cohort: requireStringField(payload, "cohort"),
+		fingerprintHash: requireNullableStringField(payload, "fingerprintHash"),
+		sdkVersion: payload.sdkVersion === void 0 ? null : requireNullableStringField(payload, "sdkVersion"),
+		fromReleaseId: requireNullableStringField(payload, "fromReleaseId"),
+		toReleaseId: requireNullableStringField(payload, "toReleaseId")
+	};
+	const type = requireStringField(payload, "type");
+	const movement = () => {
+		const updateStrategy = requireStringField(payload, "updateStrategy");
+		if (updateStrategy !== "fingerprint" && updateStrategy !== "appVersion") throw new InsightsBadRequestError("Invalid event field: updateStrategy");
+		return {
+			...base,
+			fromBundleId: requireStringField(payload, "fromBundleId"),
+			updateStrategy
+		};
+	};
+	const metadata = readMetadata(payload);
+	switch (type) {
+		case "UPDATE_DOWNLOADED": {
+			const delivery = metadata.delivery;
+			const read = {
+				...delivery == null ? {} : { delivery: oneOf(DELIVERIES, delivery) },
+				...metadata.patchFallback === true ? { patchFallback: true } : {}
+			};
+			return {
+				...movement(),
+				type,
+				...Object.keys(read).length === 0 ? {} : { metadata: read }
+			};
+		}
+		case "UPDATE_APPLIED": return {
+			...movement(),
+			type
+		};
+		case "RECOVERED": {
+			const previousProcessExit = readCode(metadata.previousProcessExit);
+			return {
+				...movement(),
+				type,
+				...previousProcessExit === void 0 ? {} : { metadata: { previousProcessExit } }
+			};
+		}
+		case "UPDATE_FAILED": return {
+			...movement(),
+			type,
+			metadata: { failure: readFailure(metadata.failure) }
+		};
+		case "UNCHANGED":
+			if (payload.fromBundleId !== null || payload.updateStrategy !== null) throw new InsightsBadRequestError("Invalid unchanged event shape");
+			return {
+				...base,
+				type,
+				fromBundleId: null,
+				updateStrategy: null
+			};
+		default: throw new InsightsBadRequestError("Invalid event field: type");
+	}
+}
+async function parseBundleEventRequest(request) {
+	return requireEvent(await parseJson(request));
+}
+function createBundleEventRow(input) {
+	input = requireEvent(input);
+	const base = {
+		app_version: input.appVersion,
+		channel: input.channel,
+		from_release_id: input.fromReleaseId,
+		id: input.eventId ?? 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
+	};
+	const metadata = {
+		cohort: input.cohort,
+		fingerprint_hash: input.fingerprintHash,
+		sdk_version: input.sdkVersion ?? null,
+		update_strategy: input.updateStrategy
+	};
+	switch (input.type) {
+		case "UPDATE_DOWNLOADED": {
+			const { delivery, patchFallback } = input.metadata ?? {};
+			return {
+				...base,
+				from_bundle_id: input.fromBundleId,
+				type: input.type,
+				metadata: {
+					...metadata,
+					...delivery === void 0 ? {} : { delivery },
+					...patchFallback ? { patch_fallback: true } : {}
+				}
+			};
+		}
+		case "UPDATE_APPLIED": return {
+			...base,
+			from_bundle_id: input.fromBundleId,
+			type: input.type,
+			metadata
+		};
+		case "RECOVERED": {
+			const exit = input.metadata?.previousProcessExit;
+			return {
+				...base,
+				from_bundle_id: input.fromBundleId,
+				type: input.type,
+				metadata: {
+					...metadata,
+					...exit === void 0 ? {} : { previous_process_exit: exit }
+				}
+			};
+		}
+		case "UPDATE_FAILED": {
+			const { failure } = input.metadata;
+			return {
+				...base,
+				from_bundle_id: input.fromBundleId,
+				type: input.type,
+				metadata: {
+					...metadata,
+					failure: {
+						stage: failure.stage,
+						reason: failure.reason,
+						...failure.resource === void 0 ? {} : { resource: failure.resource },
+						...failure.httpStatus === void 0 ? {} : { http_status: failure.httpStatus },
+						...failure.transport === void 0 ? {} : { transport: failure.transport },
+						...failure.originCode === void 0 ? {} : { origin_code: failure.originCode },
+						...failure.previousProcessExit === void 0 ? {} : { previous_process_exit: failure.previousProcessExit }
+					}
+				}
+			};
+		}
+		case "UNCHANGED": return {
+			...base,
+			from_bundle_id: null,
+			type: input.type,
+			metadata
+		};
+	}
+}
+//#endregion
+export { EVENT_BODY_MAX_BYTES, createBundleEventRow, parseBundleEventRequest };

package/dist/server/eventRow.cjs

@@ -0,0 +1,49 @@
+let _hot_updater_plugin_core = require("@hot-updater/plugin-core");
+let _hot_updater_plugin_core_internal = require("@hot-updater/plugin-core/internal");
+//#region src/server/eventRow.ts
+const isOptional = (value, key, valid) => !Object.hasOwn(value, key) || valid(value[key]);
+const isString = (value) => typeof value === "string";
+/** 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_internal.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, "previous_process_exit", isString);
+const isDatabaseBundleEventMetadata = (value) => (0, _hot_updater_plugin_core_internal.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, "delivery", isString) && isOptional(value, "patch_fallback", (flag) => typeof flag === "boolean") && isOptional(value, "previous_process_exit", isString);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+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. */
+const BUNDLE_EVENT_FIELDS = {
+	id: (value) => typeof value === "string",
+	type: (value) => value === "UPDATE_DOWNLOADED" || value === "UPDATE_APPLIED" || value === "RECOVERED" || value === "UPDATE_FAILED" || value === "UNCHANGED",
+	install_id: isIdentity,
+	user_id: (value) => value === null || isIdentity(value),
+	from_bundle_id: isTextOrNull,
+	from_release_id: isTextOrNull,
+	to_release_id: isTextOrNull,
+	to_bundle_id: (value) => typeof value === "string",
+	platform: (value) => value === "ios" || value === "android",
+	app_version: (value) => typeof value === "string",
+	channel: (value) => typeof value === "string",
+	metadata: isDatabaseBundleEventMetadata,
+	received_at_ms: (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0
+};
+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;
+/**
+* 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,
+* `invalid-data` for anything else.
+*/
+const validateBundleEventFields = (row) => {
+	if (!isRecord(row)) throw new _hot_updater_plugin_core.DatabaseAdapterInputError("invalid-data");
+	for (const field of Object.keys(row)) if (!Object.hasOwn(BUNDLE_EVENT_FIELDS, field)) throw new _hot_updater_plugin_core.DatabaseAdapterInputError("invalid-field");
+	for (const [field, valid] of Object.entries(BUNDLE_EVENT_FIELDS)) if (!Object.hasOwn(row, field) || !valid(row[field])) throw new _hot_updater_plugin_core.DatabaseAdapterInputError("invalid-data");
+	if (!hasEventInvariants(row)) throw new _hot_updater_plugin_core.DatabaseAdapterInputError("invalid-data");
+};
+//#endregion
+exports.isDatabaseBundleEventMetadata = isDatabaseBundleEventMetadata;
+exports.isRecord = isRecord;
+exports.validateBundleEventFields = validateBundleEventFields;

package/dist/server/eventRow.d.cts

@@ -0,0 +1,64 @@
+import { DatabaseJsonObject, Platform } from "@hot-updater/plugin-core";
+//#region src/server/eventRow.d.ts
+/** Where an update failed, and what failed; open sets, `unknown` for any other value. */
+type BundleEventFailureStage = "check" | "download" | "install" | "unknown";
+type BundleEventFailureReason = "network" | "http" | "invalid_response" | "hash_mismatch" | "signature" | "patch" | "extract" | "storage" | "unknown";
+/** An `UPDATE_FAILED` report's failure, as stored. */
+type BundleEventFailure = DatabaseJsonObject & {
+  readonly stage: BundleEventFailureStage;
+  readonly reason: BundleEventFailureReason;
+  /** What the client was fetching or writing. */
+  readonly resource?: "catalog" | "artifact" | "manifest" | "file" | "patch" | "archive" | "unknown";
+  readonly http_status?: number;
+  /** How the connection failed, when it did. */
+  readonly transport?: "timeout" | "dns" | "tls" | "connection" | "offline" | "cancelled" | "unknown";
+  /** The storage origin's error code, such as `ExpiredToken`. */
+  readonly origin_code?: string;
+  /** Android's `ApplicationExitInfo` reason for the process before this one. */
+  readonly previous_process_exit?: string;
+};
+/** 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;
+  /** `UPDATE_FAILED`: what failed. */
+  readonly failure?: BundleEventFailure;
+  /** `UPDATE_DOWNLOADED`: how the bundle arrived. */
+  readonly delivery?: "patch" | "manifest" | "archive" | "unknown";
+  /** `UPDATE_DOWNLOADED`: a patch failed and the full files came instead. */
+  readonly patch_fallback?: boolean;
+  /** `RECOVERED`: Android's `ApplicationExitInfo` reason for the crashed process. */
+  readonly previous_process_exit?: string;
+};
+type BundleEventRowBase = {
+  readonly id: string;
+  readonly install_id: string;
+  readonly user_id: string | null;
+  readonly from_release_id: string | null;
+  readonly to_release_id: string | null;
+  readonly to_bundle_id: string;
+  readonly platform: Platform;
+  readonly app_version: string;
+  readonly channel: string;
+  readonly metadata: DatabaseBundleEventMetadata;
+  readonly received_at_ms: number;
+};
+type BundleEventRow = BundleEventRowBase & ({
+  readonly type: "UPDATE_DOWNLOADED";
+  readonly from_bundle_id: string;
+} | {
+  readonly type: "UPDATE_APPLIED" | "RECOVERED";
+  readonly from_bundle_id: string;
+} |
+/** An update that failed: `from` is the running bundle, `to` the target (for a check, the running bundle). */
+{
+  readonly type: "UPDATE_FAILED";
+  readonly from_bundle_id: string;
+} | {
+  readonly type: "UNCHANGED";
+  readonly from_bundle_id: null;
+});
+//#endregion
+export { BundleEventFailure, BundleEventFailureReason, BundleEventFailureStage, BundleEventRow, BundleEventRowBase, DatabaseBundleEventMetadata };

package/dist/server/eventRow.d.mts

@@ -0,0 +1,64 @@
+import { DatabaseJsonObject, Platform } from "@hot-updater/plugin-core";
+//#region src/server/eventRow.d.ts
+/** Where an update failed, and what failed; open sets, `unknown` for any other value. */
+type BundleEventFailureStage = "check" | "download" | "install" | "unknown";
+type BundleEventFailureReason = "network" | "http" | "invalid_response" | "hash_mismatch" | "signature" | "patch" | "extract" | "storage" | "unknown";
+/** An `UPDATE_FAILED` report's failure, as stored. */
+type BundleEventFailure = DatabaseJsonObject & {
+  readonly stage: BundleEventFailureStage;
+  readonly reason: BundleEventFailureReason;
+  /** What the client was fetching or writing. */
+  readonly resource?: "catalog" | "artifact" | "manifest" | "file" | "patch" | "archive" | "unknown";
+  readonly http_status?: number;
+  /** How the connection failed, when it did. */
+  readonly transport?: "timeout" | "dns" | "tls" | "connection" | "offline" | "cancelled" | "unknown";
+  /** The storage origin's error code, such as `ExpiredToken`. */
+  readonly origin_code?: string;
+  /** Android's `ApplicationExitInfo` reason for the process before this one. */
+  readonly previous_process_exit?: string;
+};
+/** 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;
+  /** `UPDATE_FAILED`: what failed. */
+  readonly failure?: BundleEventFailure;
+  /** `UPDATE_DOWNLOADED`: how the bundle arrived. */
+  readonly delivery?: "patch" | "manifest" | "archive" | "unknown";
+  /** `UPDATE_DOWNLOADED`: a patch failed and the full files came instead. */
+  readonly patch_fallback?: boolean;
+  /** `RECOVERED`: Android's `ApplicationExitInfo` reason for the crashed process. */
+  readonly previous_process_exit?: string;
+};
+type BundleEventRowBase = {
+  readonly id: string;
+  readonly install_id: string;
+  readonly user_id: string | null;
+  readonly from_release_id: string | null;
+  readonly to_release_id: string | null;
+  readonly to_bundle_id: string;
+  readonly platform: Platform;
+  readonly app_version: string;
+  readonly channel: string;
+  readonly metadata: DatabaseBundleEventMetadata;
+  readonly received_at_ms: number;
+};
+type BundleEventRow = BundleEventRowBase & ({
+  readonly type: "UPDATE_DOWNLOADED";
+  readonly from_bundle_id: string;
+} | {
+  readonly type: "UPDATE_APPLIED" | "RECOVERED";
+  readonly from_bundle_id: string;
+} |
+/** An update that failed: `from` is the running bundle, `to` the target (for a check, the running bundle). */
+{
+  readonly type: "UPDATE_FAILED";
+  readonly from_bundle_id: string;
+} | {
+  readonly type: "UNCHANGED";
+  readonly from_bundle_id: null;
+});
+//#endregion
+export { BundleEventFailure, BundleEventFailureReason, BundleEventFailureStage, BundleEventRow, BundleEventRowBase, DatabaseBundleEventMetadata };

package/dist/server/eventRow.mjs

@@ -0,0 +1,47 @@
+import { DatabaseAdapterInputError } from "@hot-updater/plugin-core";
+import { isDatabaseJsonObject } from "@hot-updater/plugin-core/internal";
+//#region src/server/eventRow.ts
+const isOptional = (value, key, valid) => !Object.hasOwn(value, key) || valid(value[key]);
+const isString = (value) => typeof value === "string";
+/** 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, "previous_process_exit", 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, "delivery", isString) && isOptional(value, "patch_fallback", (flag) => typeof flag === "boolean") && isOptional(value, "previous_process_exit", isString);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+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. */
+const BUNDLE_EVENT_FIELDS = {
+	id: (value) => typeof value === "string",
+	type: (value) => value === "UPDATE_DOWNLOADED" || value === "UPDATE_APPLIED" || value === "RECOVERED" || value === "UPDATE_FAILED" || value === "UNCHANGED",
+	install_id: isIdentity,
+	user_id: (value) => value === null || isIdentity(value),
+	from_bundle_id: isTextOrNull,
+	from_release_id: isTextOrNull,
+	to_release_id: isTextOrNull,
+	to_bundle_id: (value) => typeof value === "string",
+	platform: (value) => value === "ios" || value === "android",
+	app_version: (value) => typeof value === "string",
+	channel: (value) => typeof value === "string",
+	metadata: isDatabaseBundleEventMetadata,
+	received_at_ms: (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0
+};
+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;
+/**
+* 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,
+* `invalid-data` for anything else.
+*/
+const validateBundleEventFields = (row) => {
+	if (!isRecord(row)) throw new DatabaseAdapterInputError("invalid-data");
+	for (const field of Object.keys(row)) if (!Object.hasOwn(BUNDLE_EVENT_FIELDS, field)) throw new DatabaseAdapterInputError("invalid-field");
+	for (const [field, valid] of Object.entries(BUNDLE_EVENT_FIELDS)) if (!Object.hasOwn(row, field) || !valid(row[field])) throw new DatabaseAdapterInputError("invalid-data");
+	if (!hasEventInvariants(row)) throw new DatabaseAdapterInputError("invalid-data");
+};
+//#endregion
+export { isDatabaseBundleEventMetadata, isRecord, validateBundleEventFields };

package/dist/server/index.cjs

@@ -0,0 +1,128 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_model = require("./model.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");
+let _hot_updater_plugin_core = require("@hot-updater/plugin-core");
+let _hot_updater_plugin_core_internal = require("@hot-updater/plugin-core/internal");
+let _hot_updater_plugin_core_server_plugin = require("@hot-updater/plugin-core/server-plugin");
+//#region src/server/index.ts
+const createInsightsApi = (db, now, retention) => ({
+	/** How long this plugin keeps its rows. */
+	retention,
+	/** Records one validated event row; a repeated id changes nothing. */
+	recordEvent: (event) => require_recordEvent.recordEvent(db, event),
+	listEvents: (input) => require_reads.listEvents(db, input),
+	findLatestEvents: (input) => require_reads.findLatestEvents(db, input),
+	countLatestEvents: (input) => require_reads.countLatestEvents(db, input),
+	countEvents: (input) => require_reads.countEvents(db, input),
+	getReleaseActivity: (input) => require_reads.getReleaseActivity(db, input, now, retention),
+	getAppUsage: (input) => require_reads.getAppUsage(db, input, now, retention),
+	/** A release's or a channel's update failures, and their breakdown over a time range. */
+	getUpdateFailures: (input) => require_reads.getUpdateFailures(db, input, now, retention)
+});
+/** `GET /failures`'s query: a scope, an optional release, and a time range or none. */
+const readFailuresQuery = (url) => {
+	const query = url.searchParams;
+	const time = (name) => {
+		const value = query.get(name);
+		return value === null ? void 0 : Number(value);
+	};
+	const [start, end] = [time("start"), time("end")];
+	const platform = query.get("platform");
+	const releaseId = query.get("releaseId");
+	if (platform !== "ios" && platform !== "android" || start === void 0 !== (end === void 0)) throw new _hot_updater_plugin_core.DatabaseAdapterInputError("invalid-query");
+	return {
+		platform,
+		channel: query.get("channel") ?? "",
+		...releaseId === null ? {} : { releaseId },
+		...start === void 0 ? {} : { timeRange: {
+			start,
+			end
+		} }
+	};
+};
+/**
+* The admin route of the update failures read: a release's (`releaseId`)
+* since its first report, or over `start`–`end`, or a channel's over a range,
+* which covers at most 30 days.
+*/
+const failuresEndpoint = (api) => ({
+	access: "admin",
+	method: "GET",
+	path: "/failures",
+	handler: async (request) => {
+		try {
+			return Response.json(await api.getUpdateFailures(readFailuresQuery(new URL(request.url))), { headers: { "cache-control": "private, no-store" } });
+		} catch (error) {
+			if (error instanceof _hot_updater_plugin_core.DatabaseAdapterInputError) return Response.json({ error: "Send platform and channel, and releaseId or start and end in epoch milliseconds, at most 30 days apart." }, { status: 400 });
+			if (!(0, _hot_updater_plugin_core_server_plugin.isDatabaseBusyError)(error)) throw error;
+			return Response.json({ error: "Service unavailable" }, {
+				status: 503,
+				headers: { "retry-after": "5" }
+			});
+		}
+	}
+});
+const retentionOf = ({ retention }) => {
+	const rawDays = retention?.rawDays ?? 90;
+	const dailyDays = retention?.dailyDays ?? 400;
+	const whole = (days) => Number.isSafeInteger(days) && days >= 1;
+	if (!whole(rawDays) || !whole(dailyDays) || dailyDays < rawDays) throw new _hot_updater_plugin_core_server_plugin.HotUpdaterConfigError(`insights({ retention }) takes whole days of at least 1, with dailyDays at least rawDays; got rawDays ${rawDays} and dailyDays ${dailyDays}.`);
+	return {
+		rawDays,
+		dailyDays
+	};
+};
+/**
+* Insights: bundle lifecycle events and update failures, each
+* installation's latest event, and the counters, gauges, and sketches its
+* reads come from, each kept for its retention. It serves `POST /events` to
+* clients, and the Insights reads, update failures, and retention to admins.
+*/
+const insights = (options = {}) => {
+	const retention = retentionOf(options);
+	const plugin = (0, _hot_updater_plugin_core_server_plugin.definePlugin)({
+		id: "insights",
+		namespace: false,
+		schemaVersion: "1.2.0",
+		schema: require_schema.createInsightsSchema(retention),
+		init: ({ db, now }) => {
+			const api = createInsightsApi(db, now, retention);
+			const routes = require_routes.createInsightsRouteHandlers(require_provider.createInsightsProvider(require_model.createInsightsModel(api)));
+			return {
+				api,
+				endpoints: [
+					...require_routes.INSIGHTS_ROUTES.map(({ access, method, path, handler }) => ({
+						access,
+						method,
+						path,
+						handler: (request, params) => routes[handler](params, request)
+					})),
+					failuresEndpoint(api),
+					{
+						access: "admin",
+						method: "GET",
+						path: "/retention",
+						handler: async () => Response.json(retention)
+					}
+				]
+			};
+		},
+		cli: { clientPlugin: {
+			module: "@hot-updater/react-native/plugins/insights",
+			name: "insights"
+		} }
+	});
+	return (0, _hot_updater_plugin_core_internal.markOfficial)(plugin);
+};
+//#endregion
+exports.DEFAULT_INSIGHTS_RETENTION = require_schema.DEFAULT_INSIGHTS_RETENTION;
+exports.createInsightsModel = require_model.createInsightsModel;
+exports.createInsightsProvider = require_provider.createInsightsProvider;
+exports.createInsightsSchema = require_schema.createInsightsSchema;
+exports.insights = insights;
+exports.insightsIdentity = require_recordEvent.insightsIdentity;
+exports.insightsSchema = require_schema.insightsSchema;