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

package/dist/server/testing/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/testing/setupInsightsHttpTestSuite.d.mts

@@ -0,0 +1,11 @@
+import { HttpTestClient } from "./types.mjs";
+//#region src/server/testing/setupInsightsHttpTestSuite.d.ts
+/**
+ * The Insights plugin's routes on a database: a client reports an event, and
+ * the admin routes read it back. The server must run `insights()`.
+ */
+declare const setupInsightsHttpTestSuite: (options: {
+  readonly getClient: () => HttpTestClient;
+}) => void;
+//#endregion
+export { setupInsightsHttpTestSuite };

package/dist/server/testing/setupInsightsHttpTestSuite.mjs

@@ -0,0 +1,107 @@
+import { expectInsightsIndex } from "./expectInsightsIndex.mjs";
+import { describe, expect, it } from "vitest";
+//#region src/server/testing/setupInsightsHttpTestSuite.ts
+const jsonRequest = (method, body) => ({
+	method,
+	headers: { "content-type": "application/json" },
+	body: JSON.stringify(body)
+});
+/**
+* The Insights plugin's routes on a database: a client reports an event, and
+* the admin routes read it back. The server must run `insights()`.
+*/
+const setupInsightsHttpTestSuite = (options) => {
+	describe("Insights HTTP routes", () => {
+		it("records a reported event and reads it back", async () => {
+			const client = options.getClient();
+			const installId = `install-${crypto.randomUUID()}`;
+			const userId = `user-${crypto.randomUUID()}`;
+			const channel = `insights-${crypto.randomUUID()}`;
+			const event = {
+				appVersion: "1.0.0",
+				channel,
+				cohort: "default",
+				fingerprintHash: null,
+				fromBundleId: null,
+				fromReleaseId: null,
+				installId,
+				platform: "ios",
+				toBundleId: "00000000-0000-7000-8000-000000000001",
+				toReleaseId: null,
+				type: "UNCHANGED",
+				updateStrategy: null,
+				userId,
+				sdkVersion: "2.0.0"
+			};
+			const reported = await client.client("/events", jsonRequest("POST", event));
+			expect(reported.status).toBe(204);
+			await reported.text();
+			const installation = await client.admin(`/installations/${encodeURIComponent(installId)}`);
+			expect(installation.status).toBe(200);
+			expect(await installation.json()).toMatchObject({
+				installId,
+				latestStatus: "UNCHANGED",
+				lastKnownBundleId: event.toBundleId,
+				channel
+			});
+			await expectInsightsIndex(async () => {
+				return (await (await client.admin(`/installations?userId=${encodeURIComponent(userId)}`)).json()).data.map(({ installId: id }) => id);
+			}, [installId]);
+			await expectInsightsIndex(async () => {
+				return (await (await client.admin(`/overview?platform=ios&channel=${encodeURIComponent(channel)}&window=24h`)).json()).reportingInstallations.count;
+			}, 1);
+		});
+		it("records an update failure in installation history and the failures read", async () => {
+			const client = options.getClient();
+			const installId = `install-${crypto.randomUUID()}`;
+			const channel = `insights-${crypto.randomUUID()}`;
+			const releaseId = "00000000-0000-7000-8000-0000000000b2";
+			const reported = await client.client("/events", jsonRequest("POST", {
+				appVersion: "1.0.0",
+				channel,
+				cohort: "default",
+				fingerprintHash: null,
+				fromBundleId: "00000000-0000-7000-8000-000000000001",
+				fromReleaseId: null,
+				installId,
+				platform: "ios",
+				toBundleId: "00000000-0000-7000-8000-000000000002",
+				toReleaseId: releaseId,
+				type: "UPDATE_FAILED",
+				updateStrategy: "appVersion",
+				metadata: { failure: {
+					stage: "download",
+					reason: "http",
+					httpStatus: 403
+				} }
+			}));
+			expect(reported.status).toBe(204);
+			await reported.text();
+			await expectInsightsIndex(async () => {
+				return (await (await client.admin(`/installations/${encodeURIComponent(installId)}/events?limit=10`)).json()).data.map(({ type, failure }) => ({
+					type,
+					failure
+				}));
+			}, [{
+				type: "UPDATE_FAILED",
+				failure: {
+					stage: "download",
+					reason: "http",
+					httpStatus: 403
+				}
+			}]);
+			const now = Date.now();
+			await expectInsightsIndex(async () => {
+				const body = await (await client.admin(`/failures?platform=ios&channel=${encodeURIComponent(channel)}&releaseId=${releaseId}&start=${now - 864e5}&end=${now + 36e5}`)).json();
+				return [body.failedUpdates, body.failedInstallations];
+			}, [1, 1]);
+		});
+		it("refuses a malformed event", async () => {
+			const response = await options.getClient().client("/events", jsonRequest("POST", { type: "UNCHANGED" }));
+			expect(response.status).toBe(400);
+			await response.text();
+		});
+	});
+};
+//#endregion
+export { setupInsightsHttpTestSuite };

package/dist/server/testing/setupInsightsModelTestSuite.d.mts

@@ -0,0 +1,11 @@
+import { InsightsModel } from "./modelTypes.mjs";
+import { DatabaseTestLifecycle } from "./types.mjs";
+//#region src/server/testing/setupInsightsModelTestSuite.d.ts
+/**
+ * The Insights report contract on one database: pass the Insights plugin's
+ * model over it, `createInsightsModel(createDatabasePluginApis(database,
+ * [insights()]).insights)`, as `createDatabase`.
+ */
+declare const setupInsightsModelTestSuite: (lifecycle: DatabaseTestLifecycle<InsightsModel>) => void;
+//#endregion
+export { setupInsightsModelTestSuite };

package/dist/server/testing/setupInsightsModelTestSuite.mjs

@@ -0,0 +1,31 @@
+import { registerInsightsModelTests } from "./insightsModelTests.mjs";
+import { afterAll, beforeAll, beforeEach, describe } from "vitest";
+//#region src/server/testing/setupInsightsModelTestSuite.ts
+/**
+* The Insights report contract on one database: pass the Insights plugin's
+* model over it, `createInsightsModel(createDatabasePluginApis(database,
+* [insights()]).insights)`, as `createDatabase`.
+*/
+const setupInsightsModelTestSuite = (lifecycle) => {
+	describe(lifecycle.name, () => {
+		let model;
+		const getDatabase = () => {
+			if (model === void 0) throw new Error("The model is unavailable outside the test lifecycle");
+			return model;
+		};
+		beforeAll(async () => {
+			await lifecycle.migrate();
+			model = await lifecycle.createDatabase();
+		});
+		beforeEach(async () => {
+			await lifecycle.reset(getDatabase());
+		});
+		afterAll(async () => {
+			await lifecycle.dispose(getDatabase());
+			model = void 0;
+		});
+		registerInsightsModelTests({ getDatabase });
+	});
+};
+//#endregion
+export { setupInsightsModelTestSuite };

package/dist/server/testing/types.d.mts

@@ -0,0 +1,26 @@
+//#region src/server/testing/types.d.ts
+/**
+ * The shapes `@hot-updater/test-utils` passes a plugin's suite, restated
+ * here so the plugin's tests need no dependency on that package.
+ */
+type HttpTestRequest = (path: string, init?: NonNullable<ConstructorParameters<typeof Request>[1]>) => Promise<Response>;
+/** A running server's client and admin mounts. */
+interface HttpTestClient {
+  readonly client: HttpTestRequest;
+  readonly admin: HttpTestRequest;
+}
+type DatabaseTestState<TDatabase> = {
+  readonly getDatabase: () => TDatabase;
+};
+type Awaitable<T> = Promise<T> | T;
+/** How a suite gets a database, and gives it back. */
+type DatabaseTestLifecycle<TDatabase> = {
+  readonly name: string;
+  readonly migrate: () => Awaitable<void>;
+  readonly createDatabase: () => Awaitable<TDatabase>;
+  /** Empties every table between tests. */
+  readonly reset: (database: TDatabase) => Awaitable<void>;
+  readonly dispose: (database: TDatabase) => Awaitable<void>;
+};
+//#endregion
+export { DatabaseTestLifecycle, DatabaseTestState, HttpTestClient, HttpTestRequest };

package/dist/server/types.d.cts

@@ -0,0 +1,33 @@
+import { InsightsScope } from "./modelTypes.cjs";
+import { ActiveInstallationWindow, CreateBundleEventRequest, CursorPage, EventCursorPage, EventHistoryRow, InsightsBundleSelection, InstallationHistoryRow, InstallationRow, ReportingOverview } from "./domain.cjs";
+//#region src/server/types.d.ts
+type InsightsEventPageInput = {
+  readonly beforeReceivedAtMs?: number;
+  readonly sinceMs?: number;
+  readonly bundle?: InsightsBundleSelection;
+  readonly cursor?: string;
+  readonly limit?: number;
+};
+type InsightsInstallationEventPageInput = Omit<InsightsEventPageInput, "bundle"> & {
+  readonly installId: string;
+};
+type InsightsUserInstallationPageInput = {
+  readonly userId: string;
+  readonly cursor?: string;
+  readonly limit?: number;
+};
+type InsightsProvider = {
+  appendBundleEvent(input: CreateBundleEventRequest): Promise<void>;
+  listEvents(input: InsightsEventPageInput): Promise<EventCursorPage<EventHistoryRow>>;
+  listInstallationEvents(input: InsightsInstallationEventPageInput): Promise<EventCursorPage<InstallationHistoryRow>>;
+  getInstallation(input: {
+    readonly installId: string;
+  }): Promise<InstallationRow | null>;
+  pageInstallationsByCurrentUserId(input: InsightsUserInstallationPageInput): Promise<CursorPage<InstallationRow>>;
+  getReportingOverview(input: InsightsScope & {
+    readonly window: ActiveInstallationWindow;
+    readonly bundleId?: string;
+  }): Promise<ReportingOverview>;
+};
+//#endregion
+export { InsightsEventPageInput, InsightsInstallationEventPageInput, InsightsProvider, InsightsUserInstallationPageInput };

package/dist/server/types.d.mts

@@ -0,0 +1,33 @@
+import { InsightsScope } from "./modelTypes.mjs";
+import { ActiveInstallationWindow, CreateBundleEventRequest, CursorPage, EventCursorPage, EventHistoryRow, InsightsBundleSelection, InstallationHistoryRow, InstallationRow, ReportingOverview } from "./domain.mjs";
+//#region src/server/types.d.ts
+type InsightsEventPageInput = {
+  readonly beforeReceivedAtMs?: number;
+  readonly sinceMs?: number;
+  readonly bundle?: InsightsBundleSelection;
+  readonly cursor?: string;
+  readonly limit?: number;
+};
+type InsightsInstallationEventPageInput = Omit<InsightsEventPageInput, "bundle"> & {
+  readonly installId: string;
+};
+type InsightsUserInstallationPageInput = {
+  readonly userId: string;
+  readonly cursor?: string;
+  readonly limit?: number;
+};
+type InsightsProvider = {
+  appendBundleEvent(input: CreateBundleEventRequest): Promise<void>;
+  listEvents(input: InsightsEventPageInput): Promise<EventCursorPage<EventHistoryRow>>;
+  listInstallationEvents(input: InsightsInstallationEventPageInput): Promise<EventCursorPage<InstallationHistoryRow>>;
+  getInstallation(input: {
+    readonly installId: string;
+  }): Promise<InstallationRow | null>;
+  pageInstallationsByCurrentUserId(input: InsightsUserInstallationPageInput): Promise<CursorPage<InstallationRow>>;
+  getReportingOverview(input: InsightsScope & {
+    readonly window: ActiveInstallationWindow;
+    readonly bundleId?: string;
+  }): Promise<ReportingOverview>;
+};
+//#endregion
+export { InsightsEventPageInput, InsightsInstallationEventPageInput, InsightsProvider, InsightsUserInstallationPageInput };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@hot-updater/plugin-insights",
+  "type": "module",
+  "version": "1.0.0-rc.20",
+  "description": "Hot Updater's Insights plugin: launch, download, and update failure events, for the server and the React Native app",
+  "exports": {
+    "./client": {
+      "import": "./dist/client/index.mjs",
+      "require": "./dist/client/index.cjs"
+    },
+    "./internal": {
+      "import": "./dist/internal.mjs",
+      "require": "./dist/internal.cjs"
+    },
+    "./server": {
+      "import": "./dist/server/index.mjs",
+      "require": "./dist/server/index.cjs"
+    },
+    "./package.json": "./package.json",
+    "./testing": {
+      "import": "./dist/server/testing/index.mjs"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gronxb/hot-updater"
+  },
+  "author": "gronxb <gron1gh1@gmail.com> (https://github.com/gronxb)",
+  "bugs": {
+    "url": "https://github.com/gronxb/hot-updater/issues"
+  },
+  "homepage": "https://github.com/gronxb/hot-updater#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "client",
+    "package.json"
+  ],
+  "dependencies": {
+    "@hot-updater/core": "1.0.0-rc.20",
+    "@hot-updater/plugin-core": "1.0.0-rc.20"
+  },
+  "peerDependencies": {
+    "vitest": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "vitest": "4.1.4",
+    "@hot-updater/test-utils": "1.0.0-rc.20"
+  },
+  "nx": {
+    "implicitDependencies": [
+      "!@hot-updater/test-utils"
+    ]
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test:type": "tsc --noEmit"
+  }
+}