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

package/dist/insights/errors.mjs

@@ -1,20 +1,47 @@
+import { DatabaseConflictError } from "../database/errors.mjs";
 //#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 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
-export { InsightsBadRequestError, InsightsPayloadTooLargeError, InsightsScanLimitExceededError };
+export { InsightsBadRequestError, InsightsPayloadTooLargeError, isDatabaseBusyError };

package/dist/insights/eventInput.cjs

@@ -1,36 +1,36 @@
 const require_errors = require("./errors.cjs");
+let _hot_updater_plugin_core = require("@hot-updater/plugin-core");
 //#region src/insights/eventInput.ts
 const MAX_EVENT_STRING_LENGTH = 1024;
-const EVENT_BODY_MAX_BYTES = 16 * 1024;
-const eventKeys = new Set([
-	"type",
-	"installId",
-	"toBundleId",
-	"userId",
-	"username",
-	"platform",
-	"appVersion",
-	"channel",
-	"cohort",
-	"fingerprintHash",
-	"fromBundleId",
-	"fromReleaseId",
-	"toReleaseId",
-	"updateStrategy",
-	"sdkVersion"
-]);
+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) throw new require_errors.InsightsBadRequestError(`Invalid event field: ${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 require_errors.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 require_errors.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 (!(0, _hot_updater_plugin_core.isUUIDv7)(value)) throw new require_errors.InsightsBadRequestError("Invalid event field: eventId");
+	return value;
+}
 async function readBoundedText(request) {
 	const contentLength = request.headers.get("content-length");
 	const declaredByteLength = Number(contentLength);
@@ -62,13 +62,15 @@ async function parseJson(request) {
 	}
 }
 function requireEvent(payload) {
-	if (!isRecord(payload) || Object.keys(payload).some((key) => !eventKeys.has(key))) throw new require_errors.InsightsBadRequestError("Invalid event payload");
+	if (!isRecord(payload)) throw new require_errors.InsightsBadRequestError("Invalid event payload");
 	const platform = requireStringField(payload, "platform");
 	if (platform !== "ios" && platform !== "android") throw new require_errors.InsightsBadRequestError("Invalid event field: platform");
+	const eventId = readEventId(payload);
 	const base = {
-		installId: requireStringField(payload, "installId"),
+		...eventId === void 0 ? {} : { eventId },
+		installId: requireIdentityField(payload, "installId"),
 		toBundleId: requireStringField(payload, "toBundleId"),
-		...payload.userId === void 0 ? {} : { userId: requireStringField(payload, "userId") },
+		...payload.userId === void 0 ? {} : { userId: requireIdentityField(payload, "userId") },
 		...payload.username === void 0 ? {} : { username: requireStringField(payload, "username") },
 		platform,
 		appVersion: requireStringField(payload, "appVersion"),
@@ -81,9 +83,9 @@ function requireEvent(payload) {
 	};
 	const type = requireStringField(payload, "type");
 	switch (type) {
+		case "UPDATE_DOWNLOADED":
 		case "UPDATE_APPLIED":
-		case "RECOVERED":
-		case "RELEASE_ADOPTED": {
+		case "RECOVERED": {
 			const updateStrategy = requireStringField(payload, "updateStrategy");
 			if (updateStrategy !== "fingerprint" && updateStrategy !== "appVersion") throw new require_errors.InsightsBadRequestError("Invalid event field: updateStrategy");
 			return {
@@ -107,5 +109,43 @@ function requireEvent(payload) {
 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 ?? (0, _hot_updater_plugin_core.createUUIDv7)(),
+		install_id: input.installId,
+		platform: input.platform,
+		received_at_ms: Date.now(),
+		to_bundle_id: input.toBundleId,
+		to_release_id: input.toReleaseId,
+		user_id: input.userId ?? null,
+		metadata: {
+			cohort: input.cohort,
+			fingerprint_hash: input.fingerprintHash,
+			sdk_version: input.sdkVersion ?? null,
+			username: input.username ?? null,
+			update_strategy: input.updateStrategy
+		}
+	};
+	switch (input.type) {
+		case "UPDATE_DOWNLOADED":
+		case "UPDATE_APPLIED":
+		case "RECOVERED": return {
+			...base,
+			from_bundle_id: input.fromBundleId,
+			type: input.type
+		};
+		case "UNCHANGED": return {
+			...base,
+			from_bundle_id: null,
+			type: input.type
+		};
+	}
+}
 //#endregion
+exports.EVENT_BODY_MAX_BYTES = EVENT_BODY_MAX_BYTES;
+exports.createBundleEventRow = createBundleEventRow;
 exports.parseBundleEventRequest = parseBundleEventRequest;

package/dist/insights/eventInput.mjs

@@ -1,36 +1,36 @@
 import { InsightsBadRequestError, InsightsPayloadTooLargeError } from "./errors.mjs";
+import { createUUIDv7, isUUIDv7 } from "@hot-updater/plugin-core";
 //#region src/insights/eventInput.ts
 const MAX_EVENT_STRING_LENGTH = 1024;
-const EVENT_BODY_MAX_BYTES = 16 * 1024;
-const eventKeys = new Set([
-	"type",
-	"installId",
-	"toBundleId",
-	"userId",
-	"username",
-	"platform",
-	"appVersion",
-	"channel",
-	"cohort",
-	"fingerprintHash",
-	"fromBundleId",
-	"fromReleaseId",
-	"toReleaseId",
-	"updateStrategy",
-	"sdkVersion"
-]);
+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) throw new InsightsBadRequestError(`Invalid event field: ${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;
+}
 async function readBoundedText(request) {
 	const contentLength = request.headers.get("content-length");
 	const declaredByteLength = Number(contentLength);
@@ -62,13 +62,15 @@ async function parseJson(request) {
 	}
 }
 function requireEvent(payload) {
-	if (!isRecord(payload) || Object.keys(payload).some((key) => !eventKeys.has(key))) throw new InsightsBadRequestError("Invalid event 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 = {
-		installId: requireStringField(payload, "installId"),
+		...eventId === void 0 ? {} : { eventId },
+		installId: requireIdentityField(payload, "installId"),
 		toBundleId: requireStringField(payload, "toBundleId"),
-		...payload.userId === void 0 ? {} : { userId: requireStringField(payload, "userId") },
+		...payload.userId === void 0 ? {} : { userId: requireIdentityField(payload, "userId") },
 		...payload.username === void 0 ? {} : { username: requireStringField(payload, "username") },
 		platform,
 		appVersion: requireStringField(payload, "appVersion"),
@@ -81,9 +83,9 @@ function requireEvent(payload) {
 	};
 	const type = requireStringField(payload, "type");
 	switch (type) {
+		case "UPDATE_DOWNLOADED":
 		case "UPDATE_APPLIED":
-		case "RECOVERED":
-		case "RELEASE_ADOPTED": {
+		case "RECOVERED": {
 			const updateStrategy = requireStringField(payload, "updateStrategy");
 			if (updateStrategy !== "fingerprint" && updateStrategy !== "appVersion") throw new InsightsBadRequestError("Invalid event field: updateStrategy");
 			return {
@@ -107,5 +109,41 @@ function requireEvent(payload) {
 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,
+		metadata: {
+			cohort: input.cohort,
+			fingerprint_hash: input.fingerprintHash,
+			sdk_version: input.sdkVersion ?? null,
+			username: input.username ?? null,
+			update_strategy: input.updateStrategy
+		}
+	};
+	switch (input.type) {
+		case "UPDATE_DOWNLOADED":
+		case "UPDATE_APPLIED":
+		case "RECOVERED": return {
+			...base,
+			from_bundle_id: input.fromBundleId,
+			type: input.type
+		};
+		case "UNCHANGED": return {
+			...base,
+			from_bundle_id: null,
+			type: input.type
+		};
+	}
+}
 //#endregion
-export { parseBundleEventRequest };
+export { EVENT_BODY_MAX_BYTES, createBundleEventRow, parseBundleEventRequest };

package/dist/insights/provider.cjs

@@ -0,0 +1,356 @@
+const require_errors = require("./errors.cjs");
+const require_eventInput = require("./eventInput.cjs");
+let _hot_updater_plugin_core = require("@hot-updater/plugin-core");
+//#region src/insights/provider.ts
+const DEFAULT_PAGE_LIMIT = 50;
+const MAX_PAGE_LIMIT = 100;
+const MAX_EVENT_ID_LENGTH = 1024;
+const MAX_IDENTITY_LENGTH = 255;
+const MAX_CURSOR_LENGTH = 8192;
+const HOUR_MS = 36e5;
+const WINDOW_MS = {
+	"24h": 864e5,
+	"7d": 6048e5,
+	"30d": 2592e6
+};
+/**
+* The longest receipt range, `[sinceMs, beforeReceivedAtMs)`, of a global or
+* bundle event list, and the range one covers without `sinceMs`: raw events
+* are listed inside a time range, as analytics products list them. It is a
+* duration, so a range that ends mid-day touches 91 UTC days. Installation
+* history is one index range and reads back to `sinceMs`.
+*/
+const EVENT_LIST_RANGE_MS = 2160 * HOUR_MS;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const requireString = (value, label, maximumLength) => {
+	if (typeof value !== "string" || value.length === 0 || value.length > maximumLength || new TextDecoder("utf-8", { ignoreBOM: true }).decode(new TextEncoder().encode(value)) !== value) throw new require_errors.InsightsBadRequestError(`Invalid ${label}.`);
+	return value;
+};
+const requireTimestamp = (value, label) => {
+	if (!Number.isSafeInteger(value) || Number(value) < 0) throw new require_errors.InsightsBadRequestError(`Invalid ${label}.`);
+	return Number(value);
+};
+const readLimit = (value) => {
+	const limit = value ?? DEFAULT_PAGE_LIMIT;
+	if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_PAGE_LIMIT) throw new require_errors.InsightsBadRequestError("Invalid page limit.");
+	return limit;
+};
+const encodeBase64Url = (value) => {
+	const bytes = new TextEncoder().encode(value);
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+};
+const decodeBase64Url = (value) => {
+	if (value.length === 0 || value.length > MAX_CURSOR_LENGTH) throw new require_errors.InsightsBadRequestError("Invalid Insights cursor.");
+	try {
+		const base64 = value.replaceAll("-", "+").replaceAll("_", "/");
+		const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+		const binary = atob(padded);
+		const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		throw new require_errors.InsightsBadRequestError("Invalid Insights cursor.");
+	}
+};
+const encodeCursor = (value) => encodeBase64Url(JSON.stringify(value));
+const decodeCursor = (value) => {
+	try {
+		return JSON.parse(decodeBase64Url(value));
+	} catch (error) {
+		if (error instanceof require_errors.InsightsBadRequestError) throw error;
+		throw new require_errors.InsightsBadRequestError("Invalid Insights cursor.");
+	}
+};
+const readScope = (input) => {
+	if (input.platform !== "ios" && input.platform !== "android") throw new require_errors.InsightsBadRequestError("Invalid Insights platform.");
+	return {
+		platform: input.platform,
+		channel: requireString(input.channel, "channel", MAX_EVENT_ID_LENGTH)
+	};
+};
+const bundleFilter = (input) => {
+	const scope = readScope(input);
+	const bundleId = requireString(input.bundleId, "bundle ID", MAX_EVENT_ID_LENGTH);
+	switch (input.outcome) {
+		case "downloaded": return {
+			...scope,
+			type: "UPDATE_DOWNLOADED",
+			toBundleId: bundleId
+		};
+		case "applied": return {
+			...scope,
+			type: "UPDATE_APPLIED",
+			toBundleId: bundleId
+		};
+		case "recovered": return {
+			...scope,
+			type: "RECOVERED",
+			fromBundleId: bundleId
+		};
+		case "unchanged": return {
+			...scope,
+			type: "UNCHANGED",
+			toBundleId: bundleId
+		};
+		default: throw new require_errors.InsightsBadRequestError("Invalid Insights outcome.");
+	}
+};
+const sameFilter = (left, right) => {
+	if (!isRecord(left) || left.kind !== right.kind) return false;
+	switch (right.kind) {
+		case "all": return true;
+		case "installationMovement": return left.installId === right.installId;
+		case "bundle": return left.platform === right.platform && left.channel === right.channel && left.type === right.type && (right.type === "RECOVERED" ? left.fromBundleId === right.fromBundleId : left.toBundleId === right.toBundleId);
+	}
+};
+const readEventCursor = (value, filter) => {
+	const cursor = decodeCursor(value);
+	if (!isRecord(cursor) || cursor.version !== 2 || cursor.kind !== "events" || !isRecord(cursor.filter) || !isRecord(cursor.after)) throw new require_errors.InsightsBadRequestError("Invalid Insights cursor.");
+	if (!sameFilter(cursor.filter, filter)) throw new require_errors.InsightsBadRequestError("Insights cursor does not match the requested events.");
+	if (typeof cursor.after.id !== "string" || !(0, _hot_updater_plugin_core.isUUIDv7)(cursor.after.id)) throw new require_errors.InsightsBadRequestError("Invalid Insights event cursor ID.");
+	return {
+		after: {
+			id: cursor.after.id,
+			receivedAtMs: requireTimestamp(cursor.after.receivedAtMs, "event cursor")
+		},
+		beforeReceivedAtMs: requireTimestamp(cursor.beforeReceivedAtMs, "event cutoff"),
+		kind: "events",
+		sinceMs: requireTimestamp(cursor.sinceMs, "event start"),
+		filter,
+		version: 2
+	};
+};
+const readUserInstallationCursor = (value, userId) => {
+	const cursor = decodeCursor(value);
+	if (!isRecord(cursor) || cursor.version !== 1 || cursor.kind !== "user-installations" || cursor.userId !== userId) throw new require_errors.InsightsBadRequestError("Insights cursor does not match the requested user ID.");
+	return {
+		afterInstallId: requireString(cursor.afterInstallId, "installation cursor", MAX_IDENTITY_LENGTH),
+		kind: "user-installations",
+		userId,
+		version: 1
+	};
+};
+const compareEventNewest = (left, right) => right.received_at_ms - left.received_at_ms || (0, _hot_updater_plugin_core.compareInsightsText)(right.id, left.id);
+const isAfterEventCursor = (row, after) => row.received_at_ms < after.receivedAtMs || row.received_at_ms === after.receivedAtMs && (0, _hot_updater_plugin_core.compareInsightsText)(row.id, after.id) < 0;
+const assertEventRows = (rows, input) => {
+	if (rows.length > input.limit) throw new Error("Insights database returned too many event rows.");
+	for (let index = 0; index < rows.length; index += 1) {
+		const row = rows[index];
+		const previous = rows[index - 1];
+		if (!row || typeof row.id !== "string" || !(0, _hot_updater_plugin_core.isUUIDv7)(row.id) || !Number.isSafeInteger(row.received_at_ms) || row.received_at_ms >= input.beforeReceivedAtMs || row.received_at_ms < input.sinceMs || previous !== void 0 && compareEventNewest(previous, row) >= 0 || input.after !== void 0 && !isAfterEventCursor(row, input.after) || input.filter.kind === "installationMovement" && (row.install_id !== input.filter.installId || !(0, _hot_updater_plugin_core.isInsightsMovementEvent)(row)) || input.filter.kind === "bundle" && (row.platform !== input.filter.platform || row.channel !== input.filter.channel || row.type !== input.filter.type || (input.filter.type === "RECOVERED" ? row.from_bundle_id !== input.filter.fromBundleId : row.to_bundle_id !== input.filter.toBundleId))) throw new Error("Insights database returned invalid event rows.");
+	}
+};
+const toEventHistoryRow = (row) => ({
+	appVersion: row.app_version,
+	channel: row.channel,
+	cohort: row.metadata.cohort,
+	fromBundleId: row.from_bundle_id,
+	id: row.id,
+	installId: row.install_id,
+	platform: row.platform,
+	receivedAtMs: row.received_at_ms,
+	toBundleId: row.to_bundle_id,
+	type: row.type,
+	userId: row.user_id,
+	username: row.metadata.username
+});
+const toInstallationRow = (row) => ({
+	appVersion: row.app_version,
+	channel: row.channel,
+	cohort: row.metadata.cohort,
+	installId: row.install_id,
+	lastKnownBundleId: row.type === "UPDATE_DOWNLOADED" ? row.from_bundle_id : row.to_bundle_id,
+	pendingBundleId: row.type === "UPDATE_DOWNLOADED" ? row.to_bundle_id : null,
+	pendingReleaseId: row.type === "UPDATE_DOWNLOADED" ? row.to_release_id : null,
+	latestStatus: row.type,
+	platform: row.platform,
+	receivedAtMs: row.received_at_ms,
+	userId: row.user_id,
+	username: row.metadata.username
+});
+/**
+* Where a list without `sinceMs` starts: 90 days before its cutoff for the
+* global and bundle lists, at the first event for installation history.
+*/
+const defaultEventStart = (filter, beforeReceivedAtMs) => filter.kind === "installationMovement" ? 0 : Math.max(0, beforeReceivedAtMs - EVENT_LIST_RANGE_MS);
+/** Whether a cursor's row lies inside the list's range. */
+const isInsideBounds = ({ after }, bounds) => after.receivedAtMs >= bounds.sinceMs && after.receivedAtMs < bounds.beforeReceivedAtMs;
+/** A page's range: its cursor's, which the request may repeat but not change. */
+const readEventBounds = (input, cursor, filter) => {
+	const beforeReceivedAtMs = cursor?.beforeReceivedAtMs ?? (input.beforeReceivedAtMs === void 0 ? Date.now() : requireTimestamp(input.beforeReceivedAtMs, "event cutoff"));
+	if (cursor !== void 0 && input.beforeReceivedAtMs !== void 0 && input.beforeReceivedAtMs !== beforeReceivedAtMs) throw new require_errors.InsightsBadRequestError("Insights cursor does not match the requested event cutoff.");
+	const sinceMs = cursor?.sinceMs ?? (input.sinceMs === void 0 ? defaultEventStart(filter, beforeReceivedAtMs) : requireTimestamp(input.sinceMs, "event start"));
+	const bounds = {
+		beforeReceivedAtMs,
+		sinceMs
+	};
+	if (sinceMs > beforeReceivedAtMs || input.sinceMs !== void 0 && input.sinceMs !== sinceMs || cursor !== void 0 && !isInsideBounds(cursor, bounds)) throw new require_errors.InsightsBadRequestError("Insights cursor or range does not match the requested event start.");
+	if (filter.kind !== "installationMovement" && beforeReceivedAtMs - sinceMs > 7776e6) throw new require_errors.InsightsBadRequestError("Insights event lists cover at most 90 days: send a sinceMs no more than 90 days before beforeReceivedAtMs.");
+	return bounds;
+};
+const pageEventRows = async (model, input, filter, map) => {
+	const limit = readLimit(input.limit);
+	const cursor = input.cursor === void 0 ? void 0 : readEventCursor(input.cursor, filter);
+	const bounds = readEventBounds(input, cursor, filter);
+	const query = {
+		filter,
+		...bounds,
+		...cursor === void 0 ? {} : { after: cursor.after },
+		limit
+	};
+	const rows = await model.listEvents(query);
+	assertEventRows(rows, query);
+	const last = rows.at(-1);
+	return {
+		beforeReceivedAtMs: bounds.beforeReceivedAtMs,
+		data: rows.map(map),
+		nextCursor: rows.length === limit && last ? encodeCursor({
+			after: {
+				id: last.id,
+				receivedAtMs: last.received_at_ms
+			},
+			...bounds,
+			kind: "events",
+			filter,
+			version: 2
+		}) : null
+	};
+};
+const assertInstallationRows = (rows, input) => {
+	if (rows.length > input.limit) throw new Error("Insights database returned too many installation rows.");
+	for (let index = 0; index < rows.length; index += 1) {
+		const row = rows[index];
+		const previous = rows[index - 1];
+		if (!row || row.user_id !== input.userId || input.afterInstallId !== void 0 && (0, _hot_updater_plugin_core.compareInsightsText)(row.install_id, input.afterInstallId) <= 0 || previous !== void 0 && (0, _hot_updater_plugin_core.compareInsightsText)(previous.install_id, row.install_id) >= 0) throw new Error("Insights database returned invalid installation rows.");
+	}
+};
+const createInsightsProvider = (model) => Object.freeze({
+	async appendBundleEvent(input) {
+		const event = require_eventInput.createBundleEventRow(input);
+		await model.recordEvent({ event });
+	},
+	listEvents(input) {
+		const filter = input.bundle === void 0 ? { kind: "all" } : {
+			kind: "bundle",
+			...bundleFilter(input.bundle)
+		};
+		return pageEventRows(model, input, filter, toEventHistoryRow);
+	},
+	async listInstallationEvents(input) {
+		if ("bundle" in input && input.bundle !== void 0) throw new require_errors.InsightsBadRequestError("Installation movement queries cannot include a bundle filter.");
+		const installId = requireString(input.installId, "install ID", MAX_IDENTITY_LENGTH);
+		return pageEventRows(model, input, {
+			kind: "installationMovement",
+			installId
+		}, (row) => toEventHistoryRow(row));
+	},
+	async getInstallation({ installId }) {
+		const normalizedInstallId = requireString(installId, "install ID", MAX_IDENTITY_LENGTH);
+		const rows = await model.findLatestEvents({ installId: normalizedInstallId });
+		const row = rows[0] ?? null;
+		if (rows.length > 1 || row !== null && row.install_id !== normalizedInstallId) throw new Error("Insights database returned an invalid installation.");
+		return row === null ? null : toInstallationRow(row);
+	},
+	async pageInstallationsByCurrentUserId(input) {
+		const userId = requireString(input.userId, "user ID", MAX_IDENTITY_LENGTH);
+		const limit = readLimit(input.limit);
+		const cursor = input.cursor === void 0 ? void 0 : readUserInstallationCursor(input.cursor, userId);
+		const databaseInput = {
+			userId,
+			...cursor === void 0 ? {} : { afterInstallId: cursor.afterInstallId },
+			limit
+		};
+		const rows = await model.findLatestEvents(databaseInput);
+		assertInstallationRows(rows, databaseInput);
+		const last = rows.at(-1);
+		return {
+			data: rows.map(toInstallationRow),
+			nextCursor: rows.length === limit && last ? encodeCursor({
+				afterInstallId: last.install_id,
+				kind: "user-installations",
+				userId,
+				version: 1
+			}) : null
+		};
+	},
+	async getReportingOverview(input) {
+		const scope = readScope(input);
+		const { window } = input;
+		if (!Object.hasOwn(WINDOW_MS, window)) throw new require_errors.InsightsBadRequestError("Invalid reporting installation window.");
+		const now = Date.now();
+		const beforeReceivedAtMs = now - now % HOUR_MS + (now % HOUR_MS === 0 ? 0 : HOUR_MS);
+		const sinceMs = Math.max(0, beforeReceivedAtMs - WINDOW_MS[window]);
+		const measure = async (count) => {
+			const value = await count;
+			if (!Number.isSafeInteger(value) || value < 0) throw new Error("Insights database returned an invalid count.");
+			return {
+				count: value,
+				measuredAtMs: Date.now()
+			};
+		};
+		const bundleId = input.bundleId === void 0 ? void 0 : requireString(input.bundleId, "bundle ID", MAX_EVENT_ID_LENGTH);
+		const reporting = measure(model.countLatestEvents({
+			...scope,
+			sinceMs
+		}));
+		if (bundleId === void 0) return {
+			...scope,
+			window,
+			sinceMs,
+			beforeReceivedAtMs,
+			reportingInstallations: await reporting
+		};
+		const countOutcome = (outcome) => measure(model.countEvents({
+			filter: bundleFilter({
+				...scope,
+				bundleId,
+				outcome
+			}),
+			sinceMs,
+			beforeReceivedAtMs
+		}));
+		const [reportingInstallations, bundleInstallations, downloadedReports, appliedReports, recoveredReports, unchangedReports] = await Promise.all([
+			reporting,
+			measure(model.countLatestEvents({
+				...scope,
+				sinceMs,
+				bundle: [{
+					field: "from_bundle_id",
+					value: bundleId,
+					types: ["UPDATE_DOWNLOADED"]
+				}, {
+					field: "to_bundle_id",
+					value: bundleId,
+					types: [
+						"UNCHANGED",
+						"UPDATE_APPLIED",
+						"RECOVERED"
+					]
+				}]
+			})),
+			countOutcome("downloaded"),
+			countOutcome("applied"),
+			countOutcome("recovered"),
+			countOutcome("unchanged")
+		]);
+		return {
+			...scope,
+			window,
+			sinceMs,
+			beforeReceivedAtMs,
+			reportingInstallations,
+			bundle: {
+				bundleId,
+				reportingInstallations: bundleInstallations,
+				downloadedReports,
+				appliedReports,
+				recoveredReports,
+				unchangedReports
+			}
+		};
+	}
+});
+//#endregion
+exports.EVENT_LIST_RANGE_MS = EVENT_LIST_RANGE_MS;
+exports.createInsightsProvider = createInsightsProvider;

package/dist/insights/provider.d.cts

@@ -0,0 +1,6 @@
+import { InsightsProvider } from "./types.cjs";
+import { InsightsModel } from "@hot-updater/plugin-core";
+//#region src/insights/provider.d.ts
+declare const createInsightsProvider: (model: InsightsModel) => InsightsProvider;
+//#endregion
+export { createInsightsProvider };

package/dist/insights/provider.d.mts

@@ -0,0 +1,6 @@
+import { InsightsProvider } from "./types.mjs";
+import { InsightsModel } from "@hot-updater/plugin-core";
+//#region src/insights/provider.d.ts
+declare const createInsightsProvider: (model: InsightsModel) => InsightsProvider;
+//#endregion
+export { createInsightsProvider };