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

package/dist/server/modelTypes.d.cts

@@ -0,0 +1,176 @@
+import { BundleEventRow } from "./eventRow.cjs";
+//#region src/server/modelTypes.d.ts
+interface InsightsEventCursor {
+  readonly receivedAtMs: number;
+  readonly id: string;
+}
+interface InsightsScope {
+  readonly platform: "ios" | "android";
+  readonly channel: string;
+}
+/**
+ * Raw event predicates; recovery is attributed to the source bundle. An
+ * UNCHANGED report is kept as no event, so no filter names it.
+ */
+type InsightsBundleEventFilter = InsightsScope & ({
+  readonly type: "RECOVERED";
+  readonly fromBundleId: string;
+} | {
+  readonly type: "UPDATE_DOWNLOADED" | "UPDATE_APPLIED" | "UPDATE_FAILED";
+  readonly toBundleId: string;
+});
+type InsightsEventFilter = {
+  readonly kind: "all";
+} | {
+  readonly kind: "installationMovement";
+  readonly installId: string;
+} | ({
+  readonly kind: "bundle";
+} & InsightsBundleEventFilter);
+interface InsightsRecordEventInput {
+  readonly event: BundleEventRow;
+}
+interface InsightsListEventsInput {
+  readonly filter: InsightsEventFilter;
+  readonly sinceMs?: number;
+  readonly beforeReceivedAtMs: number;
+  readonly after?: InsightsEventCursor;
+  readonly limit: number;
+}
+type InsightsFindLatestEventsInput = {
+  readonly installId: string;
+} | {
+  readonly userId: string;
+  readonly afterInstallId?: string;
+  readonly limit: number;
+};
+interface InsightsCountLatestEventsInput extends InsightsScope {
+  /** A UTC day's start: latest events are counted by the day they fall in. */
+  readonly sinceMs: number;
+  /** Optional OR of one or two fixed predicates; count a matching event once. */
+  readonly bundle?: readonly {
+    readonly field: "from_bundle_id" | "to_bundle_id";
+    readonly value: string;
+    readonly types: readonly BundleEventRow["type"][];
+  }[];
+}
+interface InsightsCountEventsInput {
+  readonly filter: InsightsBundleEventFilter;
+  readonly sinceMs: number;
+  readonly beforeReceivedAtMs: number;
+}
+interface ReleaseReference {
+  readonly releaseId: string;
+  readonly platform: "ios" | "android";
+  readonly channel: string;
+}
+interface InsightsTimeRange {
+  /** Inclusive UTC Unix timestamp in milliseconds. */
+  readonly start: number;
+  /** Exclusive UTC Unix timestamp in milliseconds. */
+  readonly end: number;
+}
+type InsightsCoverage = {
+  readonly kind: "complete";
+  readonly sinceMs: number;
+} | {
+  readonly kind: "partial";
+  readonly sinceMs: number | null;
+};
+interface ReleaseActivityMetrics {
+  readonly downloads: number;
+  readonly launches: number;
+  readonly failedLaunches: number;
+  /** Omitted for lifetime-only bundle-row reads. */
+  readonly uniqueUsers?: number;
+  /** Daily points, present only for period reads. */
+  readonly series?: readonly {
+    readonly startMs: number;
+    readonly launches: number;
+    readonly failedLaunches: number;
+  }[];
+}
+type InsightsGetReleaseActivityInput = {
+  readonly releases: readonly ReleaseReference[];
+  readonly timeRange?: InsightsTimeRange;
+  readonly scope?: never;
+} | {
+  readonly scope: InsightsScope;
+  readonly timeRange: InsightsTimeRange;
+  readonly releases?: never;
+};
+interface InsightsGetReleaseActivityResult {
+  readonly coverage: InsightsCoverage;
+  readonly data: readonly {
+    readonly release?: ReleaseReference;
+    readonly scope?: InsightsScope;
+    readonly metrics: ReleaseActivityMetrics;
+  }[];
+  readonly measuredAtMs: number;
+}
+interface InsightsGetAppUsageInput {
+  readonly channel: string;
+  readonly platform: "all" | "ios" | "android";
+  readonly appVersion?: string;
+  readonly timeRange: InsightsTimeRange;
+  readonly intervalMs: number;
+}
+interface InsightsGetAppUsageResult {
+  readonly coverage: InsightsCoverage;
+  readonly activeInstallations: number;
+  readonly points: readonly {
+    readonly startMs: number;
+    readonly installations: number;
+  }[];
+  readonly appVersions: readonly string[];
+  readonly versions: readonly {
+    readonly name: string;
+    readonly installations: number;
+  }[];
+  readonly platforms: readonly {
+    readonly name: string;
+    readonly installations: number;
+  }[];
+  readonly bundleDistribution: readonly {
+    readonly appVersion: string;
+    readonly platform: "ios" | "android";
+    readonly releaseId: string | null;
+    readonly installations: number;
+  }[];
+  readonly measuredAtMs: number;
+}
+interface InsightsModel {
+  /**
+   * Persist the immutable event once. A private latest-event index, if used,
+   * advances atomically for a greater (received_at_ms, id). Duplicate event
+   * IDs are complete no-ops, whichever installation sends them.
+   * Retry the identical prepared input after an ambiguous commit outcome.
+   */
+  recordEvent(input: InsightsRecordEventInput): Promise<void>;
+  /**
+   * Descending (received_at_ms, id), in [sinceMs ?? 0, beforeReceivedAtMs).
+   * Apply filters and the exclusive cursor before limit (1..101). Return the
+   * complete matching prefix; native continuation pages must not truncate it.
+   * A global or bundle list may reject a range longer than 90 × 24 hours;
+   * the server asks for older events with an earlier range instead.
+   */
+  listEvents(input: InsightsListEventsInput): Promise<readonly BundleEventRow[]>;
+  /**
+   * Choose each installation's greatest (received_at_ms, id) before filtering.
+   * Exact installation lookup returns zero or one canonical event. User lookup
+   * returns current membership ordered by UTF-8 installation ID, exclusive
+   * afterInstallId and limit 1..101. Check lagging index candidates against
+   * canonical state; newly indexed associations may temporarily be absent.
+   */
+  findLatestEvents(input: InsightsFindLatestEventsInput): Promise<readonly BundleEventRow[]>;
+  /** Count latest events once per installation, then apply the supplied predicates. */
+  countLatestEvents(input: InsightsCountLatestEventsInput): Promise<number>;
+  /** Count accepted reports in [sinceMs, beforeReceivedAtMs), across all pages. */
+  countEvents(input: InsightsCountEventsInput): Promise<number>;
+  /** Read maintained release/scope summaries without scanning raw events. */
+  getReleaseActivity(input: InsightsGetReleaseActivityInput): Promise<InsightsGetReleaseActivityResult>;
+  /** Read maintained App usage summaries and latest-report distribution. */
+  getAppUsage(input: InsightsGetAppUsageInput): Promise<InsightsGetAppUsageResult>;
+}
+//#endregion
+export { InsightsBundleEventFilter, InsightsCountEventsInput, InsightsCountLatestEventsInput, InsightsCoverage, InsightsEventCursor, InsightsEventFilter, InsightsFindLatestEventsInput, InsightsGetAppUsageInput, InsightsGetAppUsageResult, InsightsGetReleaseActivityInput, InsightsGetReleaseActivityResult, InsightsListEventsInput, InsightsModel, InsightsRecordEventInput, InsightsScope, InsightsTimeRange, ReleaseActivityMetrics, ReleaseReference };

package/dist/server/modelTypes.d.mts

@@ -0,0 +1,176 @@
+import { BundleEventRow } from "./eventRow.mjs";
+//#region src/server/modelTypes.d.ts
+interface InsightsEventCursor {
+  readonly receivedAtMs: number;
+  readonly id: string;
+}
+interface InsightsScope {
+  readonly platform: "ios" | "android";
+  readonly channel: string;
+}
+/**
+ * Raw event predicates; recovery is attributed to the source bundle. An
+ * UNCHANGED report is kept as no event, so no filter names it.
+ */
+type InsightsBundleEventFilter = InsightsScope & ({
+  readonly type: "RECOVERED";
+  readonly fromBundleId: string;
+} | {
+  readonly type: "UPDATE_DOWNLOADED" | "UPDATE_APPLIED" | "UPDATE_FAILED";
+  readonly toBundleId: string;
+});
+type InsightsEventFilter = {
+  readonly kind: "all";
+} | {
+  readonly kind: "installationMovement";
+  readonly installId: string;
+} | ({
+  readonly kind: "bundle";
+} & InsightsBundleEventFilter);
+interface InsightsRecordEventInput {
+  readonly event: BundleEventRow;
+}
+interface InsightsListEventsInput {
+  readonly filter: InsightsEventFilter;
+  readonly sinceMs?: number;
+  readonly beforeReceivedAtMs: number;
+  readonly after?: InsightsEventCursor;
+  readonly limit: number;
+}
+type InsightsFindLatestEventsInput = {
+  readonly installId: string;
+} | {
+  readonly userId: string;
+  readonly afterInstallId?: string;
+  readonly limit: number;
+};
+interface InsightsCountLatestEventsInput extends InsightsScope {
+  /** A UTC day's start: latest events are counted by the day they fall in. */
+  readonly sinceMs: number;
+  /** Optional OR of one or two fixed predicates; count a matching event once. */
+  readonly bundle?: readonly {
+    readonly field: "from_bundle_id" | "to_bundle_id";
+    readonly value: string;
+    readonly types: readonly BundleEventRow["type"][];
+  }[];
+}
+interface InsightsCountEventsInput {
+  readonly filter: InsightsBundleEventFilter;
+  readonly sinceMs: number;
+  readonly beforeReceivedAtMs: number;
+}
+interface ReleaseReference {
+  readonly releaseId: string;
+  readonly platform: "ios" | "android";
+  readonly channel: string;
+}
+interface InsightsTimeRange {
+  /** Inclusive UTC Unix timestamp in milliseconds. */
+  readonly start: number;
+  /** Exclusive UTC Unix timestamp in milliseconds. */
+  readonly end: number;
+}
+type InsightsCoverage = {
+  readonly kind: "complete";
+  readonly sinceMs: number;
+} | {
+  readonly kind: "partial";
+  readonly sinceMs: number | null;
+};
+interface ReleaseActivityMetrics {
+  readonly downloads: number;
+  readonly launches: number;
+  readonly failedLaunches: number;
+  /** Omitted for lifetime-only bundle-row reads. */
+  readonly uniqueUsers?: number;
+  /** Daily points, present only for period reads. */
+  readonly series?: readonly {
+    readonly startMs: number;
+    readonly launches: number;
+    readonly failedLaunches: number;
+  }[];
+}
+type InsightsGetReleaseActivityInput = {
+  readonly releases: readonly ReleaseReference[];
+  readonly timeRange?: InsightsTimeRange;
+  readonly scope?: never;
+} | {
+  readonly scope: InsightsScope;
+  readonly timeRange: InsightsTimeRange;
+  readonly releases?: never;
+};
+interface InsightsGetReleaseActivityResult {
+  readonly coverage: InsightsCoverage;
+  readonly data: readonly {
+    readonly release?: ReleaseReference;
+    readonly scope?: InsightsScope;
+    readonly metrics: ReleaseActivityMetrics;
+  }[];
+  readonly measuredAtMs: number;
+}
+interface InsightsGetAppUsageInput {
+  readonly channel: string;
+  readonly platform: "all" | "ios" | "android";
+  readonly appVersion?: string;
+  readonly timeRange: InsightsTimeRange;
+  readonly intervalMs: number;
+}
+interface InsightsGetAppUsageResult {
+  readonly coverage: InsightsCoverage;
+  readonly activeInstallations: number;
+  readonly points: readonly {
+    readonly startMs: number;
+    readonly installations: number;
+  }[];
+  readonly appVersions: readonly string[];
+  readonly versions: readonly {
+    readonly name: string;
+    readonly installations: number;
+  }[];
+  readonly platforms: readonly {
+    readonly name: string;
+    readonly installations: number;
+  }[];
+  readonly bundleDistribution: readonly {
+    readonly appVersion: string;
+    readonly platform: "ios" | "android";
+    readonly releaseId: string | null;
+    readonly installations: number;
+  }[];
+  readonly measuredAtMs: number;
+}
+interface InsightsModel {
+  /**
+   * Persist the immutable event once. A private latest-event index, if used,
+   * advances atomically for a greater (received_at_ms, id). Duplicate event
+   * IDs are complete no-ops, whichever installation sends them.
+   * Retry the identical prepared input after an ambiguous commit outcome.
+   */
+  recordEvent(input: InsightsRecordEventInput): Promise<void>;
+  /**
+   * Descending (received_at_ms, id), in [sinceMs ?? 0, beforeReceivedAtMs).
+   * Apply filters and the exclusive cursor before limit (1..101). Return the
+   * complete matching prefix; native continuation pages must not truncate it.
+   * A global or bundle list may reject a range longer than 90 × 24 hours;
+   * the server asks for older events with an earlier range instead.
+   */
+  listEvents(input: InsightsListEventsInput): Promise<readonly BundleEventRow[]>;
+  /**
+   * Choose each installation's greatest (received_at_ms, id) before filtering.
+   * Exact installation lookup returns zero or one canonical event. User lookup
+   * returns current membership ordered by UTF-8 installation ID, exclusive
+   * afterInstallId and limit 1..101. Check lagging index candidates against
+   * canonical state; newly indexed associations may temporarily be absent.
+   */
+  findLatestEvents(input: InsightsFindLatestEventsInput): Promise<readonly BundleEventRow[]>;
+  /** Count latest events once per installation, then apply the supplied predicates. */
+  countLatestEvents(input: InsightsCountLatestEventsInput): Promise<number>;
+  /** Count accepted reports in [sinceMs, beforeReceivedAtMs), across all pages. */
+  countEvents(input: InsightsCountEventsInput): Promise<number>;
+  /** Read maintained release/scope summaries without scanning raw events. */
+  getReleaseActivity(input: InsightsGetReleaseActivityInput): Promise<InsightsGetReleaseActivityResult>;
+  /** Read maintained App usage summaries and latest-report distribution. */
+  getAppUsage(input: InsightsGetAppUsageInput): Promise<InsightsGetAppUsageResult>;
+}
+//#endregion
+export { InsightsBundleEventFilter, InsightsCountEventsInput, InsightsCountLatestEventsInput, InsightsCoverage, InsightsEventCursor, InsightsEventFilter, InsightsFindLatestEventsInput, InsightsGetAppUsageInput, InsightsGetAppUsageResult, InsightsGetReleaseActivityInput, InsightsGetReleaseActivityResult, InsightsListEventsInput, InsightsModel, InsightsRecordEventInput, InsightsScope, InsightsTimeRange, ReleaseActivityMetrics, ReleaseReference };

package/dist/server/overview.cjs

@@ -0,0 +1,109 @@
+//#region src/server/overview.ts
+const encodeIdentity = (identity) => [
+	identity.scopeKind,
+	identity.releaseKind,
+	identity.releaseId,
+	identity.channel,
+	identity.platform,
+	identity.appVersionKind,
+	identity.appVersion,
+	identity.periodKind,
+	String(identity.bucketStartMs)
+].map((value) => `${new TextEncoder().encode(value).length}:${value}`).join("");
+const fnv = (value, seed) => {
+	let result = seed;
+	for (const byte of new TextEncoder().encode(value)) {
+		result ^= BigInt(byte);
+		result = BigInt.asUintN(64, result * 1099511628211n);
+	}
+	return result.toString(16).padStart(16, "0");
+};
+/** A 128-bit hex key for a string: two FNV-1a 64 hashes with different seeds. */
+const insightsKey = (value) => `${fnv(value, 14695981039346656037n)}${fnv(value, 9521211207457086692n)}`;
+const insightsOverviewId = (identity) => insightsKey(encodeIdentity(identity));
+const hour = (value) => Math.floor(value / 36e5) * 36e5;
+const insightsOverviewDeltas = (event) => {
+	const bucketStartMs = hour(event.received_at_ms);
+	const counters = /* @__PURE__ */ new Map();
+	const append = (identity, values) => {
+		const key = encodeIdentity(identity);
+		const previous = counters.get(key);
+		counters.set(key, {
+			identity,
+			downloads: (previous?.downloads ?? 0) + values.downloads,
+			launches: (previous?.launches ?? 0) + values.launches,
+			failedLaunches: (previous?.failedLaunches ?? 0) + values.failedLaunches,
+			launchIdentity: previous?.launchIdentity ?? values.launchIdentity,
+			activityIdentity: previous?.activityIdentity ?? values.activityIdentity
+		});
+	};
+	const metric = (releaseId, values) => {
+		const launchIdentity = values.launches > 0 ? event.install_id : void 0;
+		if (releaseId !== null) for (const [periodKind, start] of [["lifetime", 0], ["hour", bucketStartMs]]) append({
+			scopeKind: "release",
+			releaseKind: "specific",
+			releaseId,
+			channel: event.channel,
+			platform: event.platform,
+			appVersionKind: "all",
+			appVersion: "",
+			periodKind,
+			bucketStartMs: start
+		}, {
+			...values,
+			...periodKind === "hour" ? { launchIdentity } : {}
+		});
+		append({
+			scopeKind: "channel",
+			releaseKind: "all",
+			releaseId: "",
+			channel: event.channel,
+			platform: event.platform,
+			appVersionKind: "all",
+			appVersion: "",
+			periodKind: "hour",
+			bucketStartMs
+		}, {
+			...values,
+			launchIdentity
+		});
+	};
+	if (event.type === "UPDATE_DOWNLOADED") metric(event.to_release_id, {
+		downloads: 1,
+		launches: 0,
+		failedLaunches: 0
+	});
+	else if (event.type !== "UPDATE_FAILED") {
+		metric(event.to_release_id, {
+			downloads: 0,
+			launches: 1,
+			failedLaunches: 0
+		});
+		if (event.type === "RECOVERED") metric(event.from_release_id, {
+			downloads: 0,
+			launches: 0,
+			failedLaunches: 1
+		});
+	}
+	for (const platform of [event.platform, "all"]) for (const appVersionKind of ["specific", "all"]) append({
+		scopeKind: "usage",
+		releaseKind: "all",
+		releaseId: "",
+		channel: event.channel,
+		platform,
+		appVersionKind,
+		appVersion: appVersionKind === "specific" ? event.app_version : "",
+		periodKind: "hour",
+		bucketStartMs
+	}, {
+		downloads: 0,
+		launches: 0,
+		failedLaunches: 0,
+		activityIdentity: event.install_id
+	});
+	return [...counters.values()];
+};
+//#endregion
+exports.insightsKey = insightsKey;
+exports.insightsOverviewDeltas = insightsOverviewDeltas;
+exports.insightsOverviewId = insightsOverviewId;

package/dist/server/overview.d.cts

@@ -0,0 +1,15 @@
+import "./eventRow.cjs";
+//#region src/server/overview.d.ts
+type InsightsOverviewIdentity = {
+  readonly scopeKind: "release" | "channel" | "usage" | "distribution";
+  readonly releaseKind: "all" | "specific" | "embedded";
+  readonly releaseId: string;
+  readonly channel: string;
+  readonly platform: "all" | "ios" | "android";
+  readonly appVersionKind: "all" | "specific";
+  readonly appVersion: string;
+  readonly periodKind: "lifetime" | "hour" | "latest";
+  readonly bucketStartMs: number;
+};
+//#endregion
+export { InsightsOverviewIdentity };

package/dist/server/overview.d.mts

@@ -0,0 +1,15 @@
+import "./eventRow.mjs";
+//#region src/server/overview.d.ts
+type InsightsOverviewIdentity = {
+  readonly scopeKind: "release" | "channel" | "usage" | "distribution";
+  readonly releaseKind: "all" | "specific" | "embedded";
+  readonly releaseId: string;
+  readonly channel: string;
+  readonly platform: "all" | "ios" | "android";
+  readonly appVersionKind: "all" | "specific";
+  readonly appVersion: string;
+  readonly periodKind: "lifetime" | "hour" | "latest";
+  readonly bucketStartMs: number;
+};
+//#endregion
+export { InsightsOverviewIdentity };

package/dist/server/overview.mjs

@@ -0,0 +1,107 @@
+//#region src/server/overview.ts
+const encodeIdentity = (identity) => [
+	identity.scopeKind,
+	identity.releaseKind,
+	identity.releaseId,
+	identity.channel,
+	identity.platform,
+	identity.appVersionKind,
+	identity.appVersion,
+	identity.periodKind,
+	String(identity.bucketStartMs)
+].map((value) => `${new TextEncoder().encode(value).length}:${value}`).join("");
+const fnv = (value, seed) => {
+	let result = seed;
+	for (const byte of new TextEncoder().encode(value)) {
+		result ^= BigInt(byte);
+		result = BigInt.asUintN(64, result * 1099511628211n);
+	}
+	return result.toString(16).padStart(16, "0");
+};
+/** A 128-bit hex key for a string: two FNV-1a 64 hashes with different seeds. */
+const insightsKey = (value) => `${fnv(value, 14695981039346656037n)}${fnv(value, 9521211207457086692n)}`;
+const insightsOverviewId = (identity) => insightsKey(encodeIdentity(identity));
+const hour = (value) => Math.floor(value / 36e5) * 36e5;
+const insightsOverviewDeltas = (event) => {
+	const bucketStartMs = hour(event.received_at_ms);
+	const counters = /* @__PURE__ */ new Map();
+	const append = (identity, values) => {
+		const key = encodeIdentity(identity);
+		const previous = counters.get(key);
+		counters.set(key, {
+			identity,
+			downloads: (previous?.downloads ?? 0) + values.downloads,
+			launches: (previous?.launches ?? 0) + values.launches,
+			failedLaunches: (previous?.failedLaunches ?? 0) + values.failedLaunches,
+			launchIdentity: previous?.launchIdentity ?? values.launchIdentity,
+			activityIdentity: previous?.activityIdentity ?? values.activityIdentity
+		});
+	};
+	const metric = (releaseId, values) => {
+		const launchIdentity = values.launches > 0 ? event.install_id : void 0;
+		if (releaseId !== null) for (const [periodKind, start] of [["lifetime", 0], ["hour", bucketStartMs]]) append({
+			scopeKind: "release",
+			releaseKind: "specific",
+			releaseId,
+			channel: event.channel,
+			platform: event.platform,
+			appVersionKind: "all",
+			appVersion: "",
+			periodKind,
+			bucketStartMs: start
+		}, {
+			...values,
+			...periodKind === "hour" ? { launchIdentity } : {}
+		});
+		append({
+			scopeKind: "channel",
+			releaseKind: "all",
+			releaseId: "",
+			channel: event.channel,
+			platform: event.platform,
+			appVersionKind: "all",
+			appVersion: "",
+			periodKind: "hour",
+			bucketStartMs
+		}, {
+			...values,
+			launchIdentity
+		});
+	};
+	if (event.type === "UPDATE_DOWNLOADED") metric(event.to_release_id, {
+		downloads: 1,
+		launches: 0,
+		failedLaunches: 0
+	});
+	else if (event.type !== "UPDATE_FAILED") {
+		metric(event.to_release_id, {
+			downloads: 0,
+			launches: 1,
+			failedLaunches: 0
+		});
+		if (event.type === "RECOVERED") metric(event.from_release_id, {
+			downloads: 0,
+			launches: 0,
+			failedLaunches: 1
+		});
+	}
+	for (const platform of [event.platform, "all"]) for (const appVersionKind of ["specific", "all"]) append({
+		scopeKind: "usage",
+		releaseKind: "all",
+		releaseId: "",
+		channel: event.channel,
+		platform,
+		appVersionKind,
+		appVersion: appVersionKind === "specific" ? event.app_version : "",
+		periodKind: "hour",
+		bucketStartMs
+	}, {
+		downloads: 0,
+		launches: 0,
+		failedLaunches: 0,
+		activityIdentity: event.install_id
+	});
+	return [...counters.values()];
+};
+//#endregion
+export { insightsKey, insightsOverviewDeltas, insightsOverviewId };