@hot-updater/react-native 1.0.0-rc.1 → 1.0.0-rc.15

package/src/{notifyAppReadyAnalytics.spec.ts → notifyAppReadyInsights.spec.ts}

@@ -1,13 +1,14 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 import type {
-  NotifyAppReadyAnalyticsEvent,
+  ActiveUpdateState,
+  NotifyAppReadyInsightsEvent,
   NotifyAppReadyResult,
 } from "./native";
 import {
   createNotifyReadResult,
   stubNotifyFrame,
-} from "./notifyAppReadyAnalytics.test-utils";
+} from "./notifyAppReadyInsights.test-utils";
 
 vi.mock("react-native", () => ({
   Platform: { OS: "ios" },
@@ -19,13 +20,14 @@ const mocks = vi.hoisted(() => ({
   getAppVersion: vi.fn(() => "1.0.0"),
   getBundleId: vi.fn(() => "bundle-id"),
   getChannel: vi.fn(() => "production"),
+  getActiveUpdateState: vi.fn<() => ActiveUpdateState>(),
   getCohort: vi.fn(() => "123"),
   getFingerprintHash: vi.fn(() => "fingerprint-hash"),
   getInstallId: vi.fn(() => "install-id"),
   getPersistedUserIdentity: vi.fn(() => ({})),
   readNotifyAppReady: vi.fn<
     () => {
-      analyticsEvent: NotifyAppReadyAnalyticsEvent | null;
+      insightsEvent: NotifyAppReadyInsightsEvent | null;
       pending: boolean;
       result: NotifyAppReadyResult;
     }
@@ -42,6 +44,7 @@ vi.mock("./native", () => ({
   getAppVersion: mocks.getAppVersion,
   getBundleId: mocks.getBundleId,
   getChannel: mocks.getChannel,
+  getActiveUpdateState: mocks.getActiveUpdateState,
   getCohort: mocks.getCohort,
   getFingerprintHash: mocks.getFingerprintHash,
   getInstallId: mocks.getInstallId,
@@ -51,20 +54,20 @@ vi.mock("./native", () => ({
 }));
 
 const createClient = () => {
-  const sendAnalyticsEvent = vi.fn().mockResolvedValue(undefined);
+  const sendInsightsEvent = vi.fn().mockResolvedValue(undefined);
   return {
     client: {
       createSession: vi.fn(async () => ({
         fetchReleaseCatalog: vi.fn(),
         resolveArtifact: vi.fn(),
-        sendAnalyticsEvent,
+        sendInsightsEvent,
       })),
     },
-    sendAnalyticsEvent,
+    sendInsightsEvent,
   };
 };
 
-describe("automatic notifyAppReady analytics", () => {
+describe("automatic notifyAppReady insights", () => {
   beforeEach(() => {
     vi.resetModules();
     vi.unstubAllGlobals();
@@ -78,6 +81,11 @@ describe("automatic notifyAppReady analytics", () => {
     mocks.addListener.mockReturnValue(() => {});
     mocks.getBundleId.mockReturnValue("bundle-id");
     mocks.getChannel.mockReturnValue("production");
+    mocks.getActiveUpdateState.mockReturnValue({
+      activeSelection: null,
+      stableSelection: null,
+      verificationPending: false,
+    });
     mocks.getCohort.mockReturnValue("123");
     mocks.getFingerprintHash.mockReturnValue("fingerprint-hash");
     mocks.getInstallId.mockReturnValue("install-id");
@@ -85,6 +93,117 @@ describe("automatic notifyAppReady analytics", () => {
     mocks.readNotifyAppReady.mockReturnValue(createNotifyReadResult());
   });
 
+  it.each([
+    {
+      label: "running selection",
+      pending: false,
+      channel: "production",
+      expected: "release-running",
+    },
+    {
+      label: "staged selection",
+      pending: true,
+      channel: "production",
+      expected: "release-running",
+    },
+    {
+      label: "another channel",
+      pending: false,
+      channel: "preview",
+      expected: null,
+    },
+  ])(
+    "attributes an unchanged launch with $label",
+    async ({ pending, channel, expected }) => {
+      const running = {
+        kind: "BUNDLE" as const,
+        releaseId: "release-running",
+        bundleId: "bundle-id",
+        channel,
+      };
+      mocks.getActiveUpdateState.mockReturnValue({
+        activeSelection: pending
+          ? {
+              ...running,
+              releaseId: "release-pending",
+              bundleId: "bundle-pending",
+            }
+          : running,
+        stableSelection: pending ? running : null,
+        verificationPending: pending,
+      });
+      const { reportNoChange } = await import("./notifyAppReadyInsights");
+      const { client, sendInsightsEvent } = createClient();
+      await reportNoChange({ client, insights: true });
+      expect(sendInsightsEvent).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: "UNCHANGED",
+          toBundleId: "bundle-id",
+          toReleaseId: expected,
+        }),
+      );
+    },
+  );
+
+  it("orders download after in-flight startup reporting and suppresses a later no-change report", async () => {
+    const { handleNotifyAppReady, reportBundleDownloaded, reportNoChange } =
+      await import("./notifyAppReadyInsights");
+    const { client, sendInsightsEvent } = createClient();
+    let finishStartup!: () => void;
+    sendInsightsEvent.mockImplementationOnce(
+      () =>
+        new Promise<void>((resolve) => {
+          finishStartup = resolve;
+        }),
+    );
+    const options = { client, insights: true };
+    const startup = handleNotifyAppReady(options);
+    await vi.waitFor(() => expect(sendInsightsEvent).toHaveBeenCalledOnce());
+    const download = reportBundleDownloaded(options, {
+      fromBundleId: "bundle-id",
+      fromReleaseId: null,
+      toBundleId: "next-bundle",
+      toReleaseId: "next-release",
+      channel: "production",
+      updateStrategy: "appVersion",
+    });
+    await Promise.resolve();
+    expect(sendInsightsEvent).toHaveBeenCalledOnce();
+    finishStartup();
+    await Promise.all([startup, download]);
+    await reportNoChange(options);
+    expect(sendInsightsEvent.mock.calls.map(([params]) => params.type)).toEqual(
+      ["UNCHANGED", "UPDATE_DOWNLOADED"],
+    );
+  });
+
+  it("reports selecting a previous download again after a different pending bundle", async () => {
+    const { reportBundleDownloaded } = await import("./notifyAppReadyInsights");
+    const { client, sendInsightsEvent } = createClient();
+    const transition = {
+      fromBundleId: "bundle-id",
+      fromReleaseId: null,
+      toBundleId: "next-bundle",
+      toReleaseId: "next-release",
+      channel: "production",
+      updateStrategy: "appVersion" as const,
+    };
+    await reportBundleDownloaded({ client, insights: true }, transition);
+    await reportBundleDownloaded({ client, insights: true }, transition);
+    await reportBundleDownloaded(
+      { client, insights: true },
+      {
+        ...transition,
+        toBundleId: "other-bundle",
+        toReleaseId: "other-release",
+      },
+    );
+    await reportBundleDownloaded({ client, insights: true }, transition);
+    expect(
+      sendInsightsEvent.mock.calls.map(([params]) => params.toBundleId),
+    ).toEqual(["next-bundle", "other-bundle", "next-bundle"]);
+  });
+
   it("sends UPDATE_APPLIED with transition metadata and invokes readiness", async () => {
     stubNotifyFrame();
     mocks.getPersistedUserIdentity.mockReturnValue({
@@ -107,12 +226,12 @@ describe("automatic notifyAppReady analytics", () => {
       ),
     );
 
-    const { client, sendAnalyticsEvent } = createClient();
+    const { client, sendInsightsEvent } = createClient();
     const onNotifyAppReady = vi.fn();
     const { init } = await import("./wrap");
 
     init({
-      analytics: true,
+      insights: true,
       onNotifyAppReady,
       requestHeaders: { Authorization: "Bearer token" },
       requestTimeout: 1000,
@@ -120,7 +239,7 @@ describe("automatic notifyAppReady analytics", () => {
     });
     await vi.runOnlyPendingTimersAsync();
 
-    expect(sendAnalyticsEvent).toHaveBeenCalledWith({
+    expect(sendInsightsEvent).toHaveBeenCalledWith({
       appVersion: "1.0.0",
       channel: "production",
       cohort: "123",
@@ -162,14 +281,14 @@ describe("automatic notifyAppReady analytics", () => {
         },
       ),
     );
-    const { client, sendAnalyticsEvent } = createClient();
+    const { client, sendInsightsEvent } = createClient();
     const onNotifyAppReady = vi.fn();
     const { init } = await import("./wrap");
 
-    init({ analytics: true, client, onNotifyAppReady });
+    init({ insights: true, client, onNotifyAppReady });
     await vi.runOnlyPendingTimersAsync();
 
-    expect(sendAnalyticsEvent).toHaveBeenCalledWith({
+    expect(sendInsightsEvent).toHaveBeenCalledWith({
       appVersion: "1.0.0",
       channel: "production",
       cohort: "123",
@@ -194,16 +313,16 @@ describe("automatic notifyAppReady analytics", () => {
 
   it("sends one UNCHANGED event for repeated init calls", async () => {
     stubNotifyFrame();
-    const { client, sendAnalyticsEvent } = createClient();
+    const { client, sendInsightsEvent } = createClient();
     const onNotifyAppReady = vi.fn();
     const { init } = await import("./wrap");
 
-    init({ analytics: true, client, onNotifyAppReady });
-    init({ analytics: true, client, onNotifyAppReady });
+    init({ insights: true, client, onNotifyAppReady });
+    init({ insights: true, client, onNotifyAppReady });
     await vi.runOnlyPendingTimersAsync();
 
-    expect(sendAnalyticsEvent).toHaveBeenCalledTimes(1);
-    expect(sendAnalyticsEvent).toHaveBeenCalledWith({
+    expect(sendInsightsEvent).toHaveBeenCalledTimes(1);
+    expect(sendInsightsEvent).toHaveBeenCalledWith({
       appVersion: "1.0.0",
       channel: "production",
       cohort: "123",
@@ -228,16 +347,16 @@ describe("automatic notifyAppReady analytics", () => {
     });
   });
 
-  it("skips automatic analytics when disabled while preserving readiness", async () => {
+  it("skips automatic insights when disabled while preserving readiness", async () => {
     stubNotifyFrame();
-    const { client, sendAnalyticsEvent } = createClient();
+    const { client, sendInsightsEvent } = createClient();
     const onNotifyAppReady = vi.fn();
     const { init } = await import("./wrap");
 
-    init({ analytics: false, client, onNotifyAppReady });
+    init({ insights: false, client, onNotifyAppReady });
     await vi.runOnlyPendingTimersAsync();
 
-    expect(sendAnalyticsEvent).not.toHaveBeenCalled();
+    expect(sendInsightsEvent).not.toHaveBeenCalled();
     expect(onNotifyAppReady).toHaveBeenCalledWith({ status: "UNCHANGED" });
   });
 });

package/src/{notifyAppReadyAnalytics.test-utils.ts → notifyAppReadyInsights.test-utils.ts}

@@ -1,20 +1,20 @@
 import { vi } from "vitest";
 
 import type {
-  NotifyAppReadyAnalyticsEvent,
+  NotifyAppReadyInsightsEvent,
   NotifyAppReadyResult,
 } from "./native";
 
 export const createNotifyReadResult = (
   result: NotifyAppReadyResult = { status: "UNCHANGED" },
-  analyticsEvent: NotifyAppReadyAnalyticsEvent | null = null,
+  insightsEvent: NotifyAppReadyInsightsEvent | null = null,
   pending = false,
 ): {
-  analyticsEvent: NotifyAppReadyAnalyticsEvent | null;
+  insightsEvent: NotifyAppReadyInsightsEvent | null;
   pending: boolean;
   result: NotifyAppReadyResult;
 } => ({
-  analyticsEvent,
+  insightsEvent,
   pending,
   result,
 });

package/src/{notifyAppReadyAnalytics.transport.spec.ts → notifyAppReadyInsights.transport.spec.ts}

@@ -1,13 +1,14 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 import type {
-  NotifyAppReadyAnalyticsEvent,
+  ActiveUpdateState,
+  NotifyAppReadyInsightsEvent,
   NotifyAppReadyResult,
 } from "./native";
 import {
   createNotifyReadResult,
   stubNotifyFrame,
-} from "./notifyAppReadyAnalytics.test-utils";
+} from "./notifyAppReadyInsights.test-utils";
 
 vi.mock("react-native", () => ({
   Platform: { OS: "ios" },
@@ -30,13 +31,14 @@ const mocks = vi.hoisted(() => ({
   getAppVersion: vi.fn(() => "1.0.0"),
   getBundleId: vi.fn(() => "bundle-id"),
   getChannel: vi.fn(() => "production"),
+  getActiveUpdateState: vi.fn<() => ActiveUpdateState>(),
   getCohort: vi.fn(() => "123"),
   getFingerprintHash: vi.fn(() => "fingerprint-hash"),
   getInstallId: vi.fn(() => "install-id"),
   getPersistedUserIdentity: vi.fn(() => ({})),
   readNotifyAppReady: vi.fn<
     () => {
-      analyticsEvent: NotifyAppReadyAnalyticsEvent | null;
+      insightsEvent: NotifyAppReadyInsightsEvent | null;
       pending: boolean;
       result: NotifyAppReadyResult;
     }
@@ -53,6 +55,7 @@ vi.mock("./native", () => ({
   getAppVersion: mocks.getAppVersion,
   getBundleId: mocks.getBundleId,
   getChannel: mocks.getChannel,
+  getActiveUpdateState: mocks.getActiveUpdateState,
   getCohort: mocks.getCohort,
   getFingerprintHash: mocks.getFingerprintHash,
   getInstallId: mocks.getInstallId,
@@ -75,6 +78,11 @@ describe("automatic notifyAppReady transport failures", () => {
     mocks.getAppVersion.mockReturnValue("1.0.0");
     mocks.getBundleId.mockReturnValue("bundle-id");
     mocks.getChannel.mockReturnValue("production");
+    mocks.getActiveUpdateState.mockReturnValue({
+      activeSelection: null,
+      stableSelection: null,
+      verificationPending: false,
+    });
     mocks.getCohort.mockReturnValue("123");
     mocks.getFingerprintHash.mockReturnValue("fingerprint-hash");
     mocks.getInstallId.mockReturnValue("install-id");
@@ -110,7 +118,7 @@ describe("automatic notifyAppReady transport failures", () => {
           "https://updates.example.test/hot-updater",
         );
 
-        init({ analytics: true, client, onError, onNotifyAppReady });
+        init({ insights: true, client, onError, onNotifyAppReady });
         await vi.runOnlyPendingTimersAsync();
 
         expect(fetchMock).toHaveBeenCalledTimes(1);
@@ -119,7 +127,7 @@ describe("automatic notifyAppReady transport failures", () => {
           status: "UNCHANGED",
         });
         expect(warn).toHaveBeenCalledWith(
-          "[HotUpdater] Automatic notifyAppReady analytics failed:",
+          "[HotUpdater] Automatic notifyAppReady insights failed:",
           expect.any(Error),
         );
       } finally {

package/src/notifyAppReadyInsights.ts

@@ -0,0 +1,293 @@
+import { Platform } from "react-native";
+
+import type { HotUpdaterError } from "./error";
+import type { InsightsEventParams, HotUpdaterHttpClient } from "./httpClient";
+import {
+  getActiveUpdateState,
+  getAppVersion,
+  getBundleId,
+  getChannel,
+  getCohort,
+  getFingerprintHash,
+  getInstallId,
+  getPersistedUserIdentity,
+  type NotifyAppReadyInsightsEvent,
+  type NotifyAppReadyResult,
+  readNotifyAppReady,
+} from "./native";
+
+export type NotifyAppReadyOptions = {
+  insights?: boolean;
+  client: HotUpdaterHttpClient;
+  requestHeaders?: Record<string, string>;
+  requestTimeout?: number;
+  reportUnchanged?: boolean;
+  onNotifyAppReady?: (result: NotifyAppReadyResult) => void;
+  onError?: (error: HotUpdaterError | Error | unknown) => void;
+};
+
+type RequestAnimationFrame = (callback: (timestamp: number) => void) => number;
+
+let didAttemptAutomaticInsights = false;
+let didDownload = false;
+let readinessPromise: Promise<NotifyAppReadyResult | undefined> | undefined;
+
+const waitForNextFrame = () =>
+  new Promise<void>((resolve) => {
+    const requestAnimationFrame = (
+      globalThis as typeof globalThis & {
+        requestAnimationFrame?: RequestAnimationFrame;
+      }
+    )?.requestAnimationFrame;
+
+    if (requestAnimationFrame) {
+      requestAnimationFrame(() => resolve());
+      return;
+    }
+
+    void Promise.resolve().then(resolve);
+  });
+
+const assertNever = (value: never): never => {
+  throw new Error(`[HotUpdater] Unexpected notifyAppReady status: ${value}`);
+};
+
+const buildNotifyAppReadyInsightsParams = (
+  nativeResult: NotifyAppReadyResult,
+  insightsEvent: NotifyAppReadyInsightsEvent | null,
+  options: Pick<NotifyAppReadyOptions, "requestHeaders" | "requestTimeout">,
+): InsightsEventParams => {
+  const appVersion = getAppVersion();
+
+  if (!appVersion) {
+    throw new Error(
+      "[HotUpdater] Automatic insights requires a non-null native app version.",
+    );
+  }
+
+  const { userId, username } = getPersistedUserIdentity();
+  const installId = getInstallId();
+
+  if (!installId) {
+    throw new Error(
+      "[HotUpdater] Automatic insights requires a non-null native install id.",
+    );
+  }
+
+  const platform: "ios" | "android" =
+    Platform.OS === "android" ? "android" : "ios";
+
+  const commonParams = {
+    appVersion,
+    channel: getChannel(),
+    cohort: getCohort(),
+    fingerprintHash: getFingerprintHash(),
+    fromReleaseId: insightsEvent?.fromReleaseId ?? null,
+    installId,
+    platform,
+    requestHeaders: options.requestHeaders,
+    requestTimeout: options.requestTimeout,
+    toReleaseId: insightsEvent?.toReleaseId ?? null,
+    ...(userId != null ? { userId } : {}),
+    ...(username != null ? { username } : {}),
+  };
+
+  switch (nativeResult.status) {
+    case "UNCHANGED": {
+      const bundleId = getBundleId();
+
+      if (!bundleId) {
+        throw new Error(
+          "[HotUpdater] Automatic insights requires a non-null current bundle id.",
+        );
+      }
+
+      const state = getActiveUpdateState();
+      const runningSelection = [
+        state.activeSelection,
+        state.stableSelection,
+      ].find(
+        (selection) =>
+          selection?.bundleId === bundleId &&
+          selection.channel === commonParams.channel,
+      );
+
+      return {
+        ...commonParams,
+        fromBundleId: null,
+        toBundleId: bundleId,
+        toReleaseId: runningSelection?.releaseId ?? null,
+        type: "UNCHANGED",
+        updateStrategy: null,
+      };
+    }
+    case "UPDATE_APPLIED":
+    case "RECOVERED":
+      if (!insightsEvent) {
+        throw new Error(
+          "[HotUpdater] Native launch report is missing persisted metadata required for automatic insights.",
+        );
+      }
+
+      switch (insightsEvent.type) {
+        case "UPDATE_APPLIED":
+          return {
+            ...commonParams,
+            fromBundleId: insightsEvent.fromBundleId,
+            toBundleId: insightsEvent.toBundleId,
+            type: "UPDATE_APPLIED",
+            updateStrategy: insightsEvent.updateStrategy,
+          };
+        case "RECOVERED":
+          return {
+            ...commonParams,
+            fromBundleId: insightsEvent.fromBundleId,
+            toBundleId: insightsEvent.toBundleId,
+            type: "RECOVERED",
+            updateStrategy: insightsEvent.updateStrategy,
+          };
+        default:
+          return assertNever(insightsEvent.type);
+      }
+    default:
+      return assertNever(nativeResult);
+  }
+};
+
+let lastInsightsReport = Promise.resolve();
+const sendInsights = (
+  options: Pick<NotifyAppReadyOptions, "client">,
+  params: InsightsEventParams,
+): Promise<void> => {
+  lastInsightsReport = lastInsightsReport
+    .catch(() => {})
+    .then(async () => {
+      const session = await options.client.createSession();
+      await session.sendInsightsEvent(params);
+    });
+  return lastInsightsReport;
+};
+
+const maybeSendAutomaticInsights = async (
+  options: NotifyAppReadyOptions,
+  nativeResult: NotifyAppReadyResult,
+  insightsEvent: NotifyAppReadyInsightsEvent | null,
+): Promise<void> => {
+  if (
+    !options.insights ||
+    didAttemptAutomaticInsights ||
+    (nativeResult.status === "UNCHANGED" &&
+      (options.reportUnchanged === false || didDownload))
+  ) {
+    return;
+  }
+
+  didAttemptAutomaticInsights = true;
+
+  if (nativeResult.status !== "UNCHANGED" && !insightsEvent) {
+    throw new Error(
+      "[HotUpdater] Native launch report is missing persisted metadata required for automatic insights.",
+    );
+  }
+
+  await sendInsights(
+    options,
+    buildNotifyAppReadyInsightsParams(nativeResult, insightsEvent, options),
+  );
+};
+
+const notifyAppReady = async (
+  options: NotifyAppReadyOptions,
+): Promise<NotifyAppReadyResult | undefined> => {
+  try {
+    let nativeReadResult: ReturnType<typeof readNotifyAppReady>;
+    do {
+      await waitForNextFrame();
+      nativeReadResult = readNotifyAppReady();
+    } while (nativeReadResult.pending);
+
+    const { insightsEvent, result: nativeResult } = nativeReadResult;
+
+    try {
+      await maybeSendAutomaticInsights(options, nativeResult, insightsEvent);
+    } catch (error) {
+      const warning = error instanceof Error ? error : new Error(String(error));
+      console.warn(
+        "[HotUpdater] Automatic notifyAppReady insights failed:",
+        warning,
+      );
+    }
+
+    options.onNotifyAppReady?.(nativeResult);
+    return nativeResult;
+  } catch (error) {
+    const normalizedError =
+      error instanceof Error ? error : new Error(String(error));
+    options.onError?.(error);
+    console.warn("[HotUpdater] Failed to notify app ready:", normalizedError);
+    return undefined;
+  }
+};
+
+export const handleNotifyAppReady = (
+  options: NotifyAppReadyOptions,
+): Promise<NotifyAppReadyResult | undefined> => {
+  readinessPromise = notifyAppReady(options);
+  return readinessPromise;
+};
+
+/** Called after an automatic update check finds no download or transition. */
+export const reportNoChange = async (
+  options: NotifyAppReadyOptions,
+): Promise<void> => {
+  try {
+    await maybeSendAutomaticInsights(options, { status: "UNCHANGED" }, null);
+  } catch (error) {
+    console.warn("[HotUpdater] Automatic no-change insights failed:", error);
+  }
+};
+
+let lastDownloadedSelection: string | undefined;
+
+/** Report only after the manifest update has been verified and staged successfully. */
+export const reportBundleDownloaded = async (
+  options: Pick<
+    NotifyAppReadyOptions,
+    "insights" | "client" | "requestHeaders" | "requestTimeout"
+  >,
+  transition: {
+    readonly fromBundleId: string;
+    readonly fromReleaseId: string | null;
+    readonly toBundleId: string;
+    readonly toReleaseId: string | null;
+    readonly channel: string;
+    readonly updateStrategy: "fingerprint" | "appVersion";
+  },
+): Promise<void> => {
+  if (!options.insights || transition.fromBundleId === transition.toBundleId)
+    return;
+  const key = JSON.stringify([
+    transition.channel,
+    transition.toReleaseId,
+    transition.toBundleId,
+  ]);
+  if (lastDownloadedSelection === key) return;
+  lastDownloadedSelection = key;
+  // A later init/mount in this JS runtime must not overwrite pending apply with UNCHANGED.
+  didDownload = true;
+  try {
+    await readinessPromise;
+    const common = buildNotifyAppReadyInsightsParams(
+      { status: "UNCHANGED" },
+      null,
+      options,
+    );
+    await sendInsights(options, {
+      ...common,
+      ...transition,
+      type: "UPDATE_DOWNLOADED",
+    });
+  } catch (error) {
+    console.warn("[HotUpdater] Download insights failed:", error);
+  }
+};

package/src/sdkVersion.ts

@@ -1 +1 @@
-export const HOT_UPDATER_SDK_VERSION = "1.0.0-rc.1";
+export const HOT_UPDATER_SDK_VERSION = "1.0.0-rc.15";