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

package/dist/client/index.d.mts

@@ -0,0 +1,42 @@
+import { HotUpdaterClientPlugin } from "@hot-updater/core";
+//#region src/client/index.d.ts
+interface InsightsOptions {
+  /**
+   * Also report from debug builds (`__DEV__`). Defaults to `false`, so
+   * development sessions stay out of production Insights.
+   */
+  readonly debug?: boolean;
+}
+/** The app's own id for the signed-in user, attached to later reports. */
+interface InsightsUser {
+  readonly userId: string | number;
+}
+interface InsightsPlugin extends HotUpdaterClientPlugin {
+  readonly id: "insights";
+  /**
+   * Attaches the signed-in user's id to later reports, or clears it with
+   * `null`. It persists on the device, sends nothing by itself, and can be
+   * called before `HotUpdater.init`.
+   */
+  setUser(user: InsightsUser | null): void;
+}
+/**
+ * Reports update adoption to a server that runs the `insights()` server
+ * plugin: launches (at most once a UTC day while nothing changes), downloads,
+ * applies, recoveries, and update failures. After the server answers that
+ * Insights is off, the plugin sends nothing for 24 hours, and for the rest
+ * of that runtime.
+ *
+ * @example
+ * ```ts
+ * import { HotUpdater } from "@hot-updater/react-native";
+ * import { insights } from "@hot-updater/react-native/plugins/insights";
+ *
+ * const analytics = insights();
+ * HotUpdater.init({ baseURL, plugins: [analytics] });
+ * analytics.setUser({ userId: "user-123" });
+ * ```
+ */
+declare const insights: (options?: InsightsOptions) => InsightsPlugin;
+//#endregion
+export { InsightsOptions, InsightsPlugin, InsightsUser, insights };

package/dist/client/index.mjs

@@ -0,0 +1,233 @@
+import { createKeyedUUIDv7, createUUIDv7 } from "./eventId.mjs";
+import { createInsightsEventSender } from "./sender.mjs";
+import { createInsightsState, utcDay, utcDayStart } from "./state.mjs";
+import { defineClientPlugin } from "@hot-updater/core";
+//#region src/client/index.ts
+const normalizeUserId = (user) => {
+	if (user === null) return null;
+	const userId = String(user.userId).trim();
+	return userId.length === 0 ? null : userId;
+};
+/**
+* Reports update adoption to a server that runs the `insights()` server
+* plugin: launches (at most once a UTC day while nothing changes), downloads,
+* applies, recoveries, and update failures. After the server answers that
+* Insights is off, the plugin sends nothing for 24 hours, and for the rest
+* of that runtime.
+*
+* @example
+* ```ts
+* import { HotUpdater } from "@hot-updater/react-native";
+* import { insights } from "@hot-updater/react-native/plugins/insights";
+*
+* const analytics = insights();
+* HotUpdater.init({ baseURL, plugins: [analytics] });
+* analytics.setUser({ userId: "user-123" });
+* ```
+*/
+const insights = (options = {}) => {
+	let context = null;
+	let state = null;
+	/** A user set before setup, applied once the plugin has storage. */
+	let pendingUser = null;
+	/** A download in this runtime: a later no-change report would hide it. */
+	let didDownload = false;
+	let lastDownloadedSelection = null;
+	const pending = /* @__PURE__ */ new Map();
+	let send = null;
+	const createEvent = (movement, eventId) => {
+		if (context === null || state === null) return null;
+		const appVersion = context.appVersion;
+		if (appVersion === null) {
+			console.warn(`[HotUpdater] Insights needs the native app version; the ${movement.type} event was not sent.`);
+			return null;
+		}
+		const now = context.now();
+		const installId = context.installId;
+		const userId = state.readUserId();
+		const body = {
+			...movement,
+			eventId: eventId?.(now, installId) ?? createUUIDv7(),
+			installId,
+			...userId === null ? {} : { userId },
+			platform: context.platform,
+			appVersion,
+			cohort: context.getCohort(),
+			fingerprintHash: context.getFingerprintHash(),
+			sdkVersion: context.sdkVersion
+		};
+		const day = utcDay(now);
+		return {
+			body,
+			day,
+			report: movement.type === "UNCHANGED" || movement.type === "UPDATE_APPLIED" || movement.type === "RECOVERED" ? {
+				day,
+				channel: movement.channel,
+				appVersion,
+				bundleId: movement.toBundleId,
+				releaseId: movement.toReleaseId,
+				userId
+			} : null,
+			failureKey: null
+		};
+	};
+	const enqueue = (event) => {
+		if (event === null || send === null) return;
+		const { type, toBundleId } = event.body;
+		if (type === "UPDATE_DOWNLOADED" || type === "UPDATE_APPLIED") {
+			for (const queued of pending.values()) if (queued.body.type === "UPDATE_FAILED" && queued.body.toBundleId === toBundleId) queued.superseded = true;
+		}
+		pending.set(event.body, event);
+		send(event.body).catch((error) => {
+			console.warn(`[HotUpdater] Insights ${event.body.type} event was not delivered:`, error);
+		});
+	};
+	const reportLaunch = (channel, bundleId, releaseId, fromReleaseId) => {
+		if (didDownload) return;
+		enqueue(createEvent({
+			type: "UNCHANGED",
+			channel,
+			fromBundleId: null,
+			fromReleaseId,
+			toBundleId: bundleId,
+			toReleaseId: releaseId,
+			updateStrategy: null
+		}));
+	};
+	const onAppReady = (result) => {
+		if (result.status === "UNCHANGED") {
+			reportLaunch(result.channel, result.bundleId, result.releaseId, null);
+			return;
+		}
+		enqueue(createEvent({
+			type: result.status,
+			channel: result.channel,
+			fromBundleId: result.fromBundleId,
+			fromReleaseId: result.fromReleaseId,
+			toBundleId: result.toBundleId,
+			toReleaseId: result.toReleaseId,
+			updateStrategy: result.updateStrategy,
+			...result.status === "RECOVERED" && result.previousProcessExit !== null ? { metadata: { previousProcessExit: result.previousProcessExit } } : {}
+		}));
+	};
+	const onUpdateCheck = (result) => {
+		if (result.status !== "UNCHANGED") return;
+		reportLaunch(result.channel, result.bundleId, result.releaseId, result.previousReleaseId === result.releaseId ? null : result.previousReleaseId);
+	};
+	const onBundleDownloaded = (info) => {
+		const selection = JSON.stringify([
+			info.channel,
+			info.toReleaseId,
+			info.toBundleId
+		]);
+		if (lastDownloadedSelection === selection) return;
+		lastDownloadedSelection = selection;
+		didDownload = true;
+		enqueue(createEvent({
+			type: "UPDATE_DOWNLOADED",
+			channel: info.channel,
+			fromBundleId: info.fromBundleId,
+			fromReleaseId: info.fromReleaseId,
+			toBundleId: info.toBundleId,
+			toReleaseId: info.toReleaseId,
+			updateStrategy: info.updateStrategy,
+			metadata: {
+				delivery: info.delivery,
+				...info.patchFallback ? { patchFallback: true } : {}
+			}
+		}));
+	};
+	const onUpdateError = (error) => {
+		if (error.stage === "check" && error.reason === "network") return;
+		const targetBundleId = error.targetBundleId ?? error.bundleId;
+		const failureKey = [
+			error.stage,
+			error.reason,
+			targetBundleId
+		].join(" ");
+		const event = createEvent({
+			type: "UPDATE_FAILED",
+			channel: error.channel,
+			fromBundleId: error.bundleId,
+			fromReleaseId: error.releaseId,
+			toBundleId: targetBundleId,
+			toReleaseId: error.targetReleaseId ?? null,
+			updateStrategy: error.updateStrategy,
+			metadata: { failure: {
+				stage: error.stage,
+				reason: error.reason,
+				...error.resource === void 0 ? {} : { resource: error.resource },
+				...error.httpStatus === void 0 ? {} : { httpStatus: error.httpStatus },
+				...error.transport === void 0 ? {} : { transport: error.transport },
+				...error.originCode === void 0 ? {} : { originCode: error.originCode },
+				...error.previousProcessExit === void 0 ? {} : { previousProcessExit: error.previousProcessExit }
+			} }
+		}, (now, installId) => createKeyedUUIDv7([
+			installId,
+			utcDay(now),
+			failureKey
+		].join("\n"), utcDayStart(now)));
+		enqueue(event === null ? null : {
+			...event,
+			failureKey
+		});
+	};
+	const admit = (body) => {
+		const event = pending.get(body);
+		if (event === void 0 || state === null || context === null) return false;
+		if (event.superseded === true || state.isPaused(context.now())) {
+			pending.delete(body);
+			return false;
+		}
+		const admitted = body.type === "UNCHANGED" ? event.report === null || !state.repeatsReport(event.report) : body.type === "UPDATE_FAILED" ? event.failureKey === null || !state.hasFailure(event.day, event.failureKey) : true;
+		if (!admitted) pending.delete(body);
+		return admitted;
+	};
+	const settle = (body, delivery) => {
+		const event = pending.get(body);
+		pending.delete(body);
+		if (event === void 0 || state === null || context === null) return;
+		if (delivery === "failed") return;
+		if (delivery === "disabled") {
+			state.pause(context.now());
+			return;
+		}
+		if (event.failureKey !== null) state.recordFailure(event.day, event.failureKey);
+		if (delivery === "refused") return;
+		state.resume();
+		if (event.report !== null) state.recordReport(event.report);
+		else state.forgetReport();
+	};
+	return defineClientPlugin({
+		id: "insights",
+		setup(pluginContext) {
+			context = pluginContext;
+			state = createInsightsState(pluginContext.storage);
+			if (pendingUser !== null) {
+				state.writeUserId(pendingUser.userId);
+				pendingUser = null;
+			}
+			if (pluginContext.isDebugBuild && options.debug !== true) return;
+			send = createInsightsEventSender(pluginContext.fetch, {
+				admit,
+				settle
+			});
+			return {
+				onAppReady,
+				onUpdateCheck,
+				onBundleDownloaded,
+				onUpdateError
+			};
+		},
+		setUser(user) {
+			const userId = normalizeUserId(user);
+			if (state === null) {
+				pendingUser = { userId };
+				return;
+			}
+			state.writeUserId(userId);
+		}
+	});
+};
+//#endregion
+export { insights };

package/dist/client/sender.cjs

@@ -0,0 +1,103 @@
+//#region src/client/sender.ts
+/** Attempts per Insights event, the first one included. */
+const INSIGHTS_MAX_ATTEMPTS = 3;
+/** Wait before the second attempt; it doubles for each later attempt. */
+const INSIGHTS_RETRY_BASE_DELAY_MS = 1e3;
+/** Longest wait between attempts, a server's `Retry-After` included. */
+const INSIGHTS_RETRY_MAX_DELAY_MS = 3e4;
+/**
+* Reads `Retry-After` as delay-seconds, the form a server under load sends;
+* an HTTP-date falls back to the backoff.
+*/
+const parseRetryAfterMs = (value) => {
+	const seconds = value?.trim();
+	return seconds && /^\d+$/.test(seconds) ? Number(seconds) * 1e3 : null;
+};
+const getRetryDelayMs = (failedAttempt, retryAfterMs) => Math.min(retryAfterMs ?? INSIGHTS_RETRY_BASE_DELAY_MS * 2 ** (failedAttempt - 1) * (.5 + Math.random()), INSIGHTS_RETRY_MAX_DELAY_MS);
+const wait = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms);
+});
+/** Makes one POST, with the context's timeout, and settles with its outcome. */
+const postInsightsEvent = async (fetch, event) => {
+	try {
+		const response = await fetch("events", {
+			body: JSON.stringify(event),
+			headers: { "Content-Type": "application/json" },
+			method: "POST"
+		});
+		if (response.status === 204) return "delivered";
+		if (response.status === 404) return "disabled";
+		if (response.status === 400 && event.type === "UPDATE_FAILED") return "refused";
+		return {
+			error: /* @__PURE__ */ new Error(`Expected HTTP 204 from /events, received ${response.status}`),
+			retryable: response.status === 429 || response.status >= 500,
+			retryAfterMs: parseRetryAfterMs(response.headers.get("Retry-After"))
+		};
+	} catch (error) {
+		return {
+			error: error instanceof Error ? error : new Error(String(error)),
+			retryable: true,
+			retryAfterMs: null
+		};
+	}
+};
+/**
+* Sends Insights events one at a time and retries each in the background.
+*
+* The server keeps an installation's latest report by arrival, so a later
+* event waits behind an earlier one's retries; otherwise a retried
+* UPDATE_APPLIED could land after the UPDATE_DOWNLOADED that followed it.
+* Callers wait only for first attempts, so a report never waits out a
+* backoff: once an event backs off, every waiting caller is released, and a
+* failure after that only warns. The gate sees each event before each
+* attempt, after every earlier event settled, so it decides with what the
+* server already answered.
+*/
+const createInsightsEventSender = (fetch, gate) => {
+	let queue = Promise.resolve();
+	let retrying = false;
+	const waiting = /* @__PURE__ */ new Set();
+	return (event) => new Promise((resolve, reject) => {
+		let released = false;
+		const release = () => {
+			released = true;
+			waiting.delete(release);
+			resolve();
+		};
+		if (retrying) release();
+		else waiting.add(release);
+		queue = queue.then(async () => {
+			try {
+				for (let attempt = 1;; attempt += 1) {
+					if (!gate.admit(event)) {
+						release();
+						break;
+					}
+					const outcome = await postInsightsEvent(fetch, event);
+					if (typeof outcome === "string") {
+						gate.settle(event, outcome);
+						release();
+						break;
+					}
+					if (!outcome.retryable || attempt === INSIGHTS_MAX_ATTEMPTS) {
+						gate.settle(event, "failed");
+						waiting.delete(release);
+						if (released) console.warn(`[HotUpdater] Insights ${event.type} event was not delivered:`, outcome.error);
+						else reject(outcome.error);
+						break;
+					}
+					retrying = true;
+					for (const releaseWaiting of waiting) releaseWaiting();
+					await wait(getRetryDelayMs(attempt, outcome.retryAfterMs));
+				}
+			} catch (error) {
+				waiting.delete(release);
+				if (!released) reject(error);
+			} finally {
+				retrying = false;
+			}
+		});
+	});
+};
+//#endregion
+exports.createInsightsEventSender = createInsightsEventSender;

package/dist/client/sender.mjs

@@ -0,0 +1,103 @@
+//#region src/client/sender.ts
+/** Attempts per Insights event, the first one included. */
+const INSIGHTS_MAX_ATTEMPTS = 3;
+/** Wait before the second attempt; it doubles for each later attempt. */
+const INSIGHTS_RETRY_BASE_DELAY_MS = 1e3;
+/** Longest wait between attempts, a server's `Retry-After` included. */
+const INSIGHTS_RETRY_MAX_DELAY_MS = 3e4;
+/**
+* Reads `Retry-After` as delay-seconds, the form a server under load sends;
+* an HTTP-date falls back to the backoff.
+*/
+const parseRetryAfterMs = (value) => {
+	const seconds = value?.trim();
+	return seconds && /^\d+$/.test(seconds) ? Number(seconds) * 1e3 : null;
+};
+const getRetryDelayMs = (failedAttempt, retryAfterMs) => Math.min(retryAfterMs ?? INSIGHTS_RETRY_BASE_DELAY_MS * 2 ** (failedAttempt - 1) * (.5 + Math.random()), INSIGHTS_RETRY_MAX_DELAY_MS);
+const wait = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms);
+});
+/** Makes one POST, with the context's timeout, and settles with its outcome. */
+const postInsightsEvent = async (fetch, event) => {
+	try {
+		const response = await fetch("events", {
+			body: JSON.stringify(event),
+			headers: { "Content-Type": "application/json" },
+			method: "POST"
+		});
+		if (response.status === 204) return "delivered";
+		if (response.status === 404) return "disabled";
+		if (response.status === 400 && event.type === "UPDATE_FAILED") return "refused";
+		return {
+			error: /* @__PURE__ */ new Error(`Expected HTTP 204 from /events, received ${response.status}`),
+			retryable: response.status === 429 || response.status >= 500,
+			retryAfterMs: parseRetryAfterMs(response.headers.get("Retry-After"))
+		};
+	} catch (error) {
+		return {
+			error: error instanceof Error ? error : new Error(String(error)),
+			retryable: true,
+			retryAfterMs: null
+		};
+	}
+};
+/**
+* Sends Insights events one at a time and retries each in the background.
+*
+* The server keeps an installation's latest report by arrival, so a later
+* event waits behind an earlier one's retries; otherwise a retried
+* UPDATE_APPLIED could land after the UPDATE_DOWNLOADED that followed it.
+* Callers wait only for first attempts, so a report never waits out a
+* backoff: once an event backs off, every waiting caller is released, and a
+* failure after that only warns. The gate sees each event before each
+* attempt, after every earlier event settled, so it decides with what the
+* server already answered.
+*/
+const createInsightsEventSender = (fetch, gate) => {
+	let queue = Promise.resolve();
+	let retrying = false;
+	const waiting = /* @__PURE__ */ new Set();
+	return (event) => new Promise((resolve, reject) => {
+		let released = false;
+		const release = () => {
+			released = true;
+			waiting.delete(release);
+			resolve();
+		};
+		if (retrying) release();
+		else waiting.add(release);
+		queue = queue.then(async () => {
+			try {
+				for (let attempt = 1;; attempt += 1) {
+					if (!gate.admit(event)) {
+						release();
+						break;
+					}
+					const outcome = await postInsightsEvent(fetch, event);
+					if (typeof outcome === "string") {
+						gate.settle(event, outcome);
+						release();
+						break;
+					}
+					if (!outcome.retryable || attempt === INSIGHTS_MAX_ATTEMPTS) {
+						gate.settle(event, "failed");
+						waiting.delete(release);
+						if (released) console.warn(`[HotUpdater] Insights ${event.type} event was not delivered:`, outcome.error);
+						else reject(outcome.error);
+						break;
+					}
+					retrying = true;
+					for (const releaseWaiting of waiting) releaseWaiting();
+					await wait(getRetryDelayMs(attempt, outcome.retryAfterMs));
+				}
+			} catch (error) {
+				waiting.delete(release);
+				if (!released) reject(error);
+			} finally {
+				retrying = false;
+			}
+		});
+	});
+};
+//#endregion
+export { createInsightsEventSender };

package/dist/client/state.cjs

@@ -0,0 +1,121 @@
+//#region src/client/state.ts
+const DAY_MS = 864e5;
+/** The UTC day of a time, as `YYYY-MM-DD`. */
+const utcDay = (time) => new Date(time).toISOString().slice(0, 10);
+/** The start of a time's UTC day, in milliseconds. */
+const utcDayStart = (time) => Math.floor(time / DAY_MS) * DAY_MS;
+const sameReport = (left, right) => left.day === right.day && left.channel === right.channel && left.appVersion === right.appVersion && left.bundleId === right.bundleId && left.releaseId === right.releaseId && left.userId === right.userId;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isNullableString = (value) => value === null || typeof value === "string";
+const parseReport = (value) => {
+	if (value === null) return null;
+	try {
+		const report = JSON.parse(value);
+		if (isRecord(report) && typeof report.day === "string" && typeof report.channel === "string" && typeof report.appVersion === "string" && typeof report.bundleId === "string" && isNullableString(report.releaseId) && isNullableString(report.userId)) return {
+			day: report.day,
+			channel: report.channel,
+			appVersion: report.appVersion,
+			bundleId: report.bundleId,
+			releaseId: report.releaseId,
+			userId: report.userId
+		};
+	} catch {}
+	return null;
+};
+const parseFailures = (value) => {
+	if (value === null) return null;
+	try {
+		const failures = JSON.parse(value);
+		if (isRecord(failures) && typeof failures.day === "string" && Array.isArray(failures.keys) && failures.keys.every((key) => typeof key === "string")) return {
+			day: failures.day,
+			keys: failures.keys
+		};
+	} catch {}
+	return null;
+};
+/**
+* The Insights plugin's memory across launches, in its plugin storage. Every
+* read tolerates a missing or unreadable value, and a storage failure only
+* costs a report that would otherwise have been skipped.
+*/
+const createInsightsState = (storage) => {
+	/** The server said Insights is off during this runtime. */
+	let pausedThisRuntime = false;
+	const read = (key) => {
+		try {
+			return storage.get(key);
+		} catch {
+			return null;
+		}
+	};
+	const write = (key, value) => {
+		try {
+			storage.set(key, value);
+		} catch {}
+	};
+	return {
+		/**
+		* Whether reporting pauses: the server answered that Insights is off
+		* during this runtime or in the 24 hours before `now`. A pause that
+		* starts after `now`, from a clock that went back, has ended.
+		*/
+		isPaused(now) {
+			if (pausedThisRuntime) return true;
+			const pausedAt = Number(read("pausedAt"));
+			return Number.isFinite(pausedAt) && pausedAt > 0 && pausedAt <= now && now < pausedAt + DAY_MS;
+		},
+		pause(now) {
+			pausedThisRuntime = true;
+			write("pausedAt", String(now));
+		},
+		/** The server stored a report, so Insights is on. */
+		resume() {
+			if (read("pausedAt") !== null) write("pausedAt", null);
+		},
+		/** Whether a launch report repeats what the installation reported that day. */
+		repeatsReport(report) {
+			const last = parseReport(read("report"));
+			return last !== null && sameReport(last, report);
+		},
+		/** Records a delivered report that says what runs. */
+		recordReport(report) {
+			write("report", JSON.stringify(report));
+		},
+		/**
+		* Forgets the last report after a delivered download or failure, so the
+		* next launch reports again, as the server records it after one.
+		*/
+		forgetReport() {
+			if (read("report") !== null) write("report", null);
+		},
+		/** Whether a failure was already reported, or refused, that day. */
+		hasFailure(day, key) {
+			const failures = parseFailures(read("failures"));
+			return failures?.day === day && failures.keys.includes(key);
+		},
+		recordFailure(day, key) {
+			const failures = parseFailures(read("failures"));
+			const keys = failures?.day === day ? failures.keys : [];
+			if (keys.includes(key)) return;
+			write("failures", JSON.stringify({
+				day,
+				keys: [...keys, key].slice(-32)
+			}));
+		},
+		readUserId() {
+			try {
+				const user = JSON.parse(read("user") ?? "null");
+				return isRecord(user) && typeof user.userId === "string" ? user.userId : null;
+			} catch {
+				return null;
+			}
+		},
+		writeUserId(userId) {
+			write("user", userId === null ? null : JSON.stringify({ userId }));
+		}
+	};
+};
+//#endregion
+exports.createInsightsState = createInsightsState;
+exports.utcDay = utcDay;
+exports.utcDayStart = utcDayStart;