@hot-updater/react-native 1.0.0-rc.16 → 1.0.0-rc.17

package/src/index.spec.ts

@@ -31,7 +31,9 @@ const mocks = vi.hoisted(() => {
     getInstallId: vi.fn(() => "install-id"),
     getManifest: vi.fn(() => null),
     getMinBundleId: vi.fn(() => "min-bundle-id"),
-    getPersistedUserIdentity: vi.fn(() => ({})),
+    configurePlugins: vi.fn(),
+    emitAfterAppReady: vi.fn(),
+    reportUpdateError: vi.fn(),
     init: vi.fn(),
     isChannelSwitched: vi.fn(() => false),
     notifyAppReady: vi.fn(() => ({ status: "UNCHANGED" as const })),
@@ -39,8 +41,7 @@ const mocks = vi.hoisted(() => {
     resetChannel: vi.fn(),
     setCohort: vi.fn(),
     setReloadBehavior: vi.fn(),
-    setUser: vi.fn(),
-    updateBundle: vi.fn(),
+    stageBundle: vi.fn(),
     wrap: vi.fn((Component: unknown) => Component),
   };
 });
@@ -53,6 +54,15 @@ vi.mock("./httpClient", () => ({
 
 vi.mock("./checkForUpdate", () => ({
   checkForUpdate: mocks.checkForUpdate,
+  reportUpdateError: mocks.reportUpdateError,
+}));
+
+vi.mock("./pluginHost", () => ({
+  configurePlugins: mocks.configurePlugins,
+}));
+
+vi.mock("./appReady", () => ({
+  emitAfterAppReady: mocks.emitAfterAppReady,
 }));
 
 vi.mock("./native", () => ({
@@ -72,15 +82,13 @@ vi.mock("./native", () => ({
   getInstallId: mocks.getInstallId,
   getManifest: mocks.getManifest,
   getMinBundleId: mocks.getMinBundleId,
-  getPersistedUserIdentity: mocks.getPersistedUserIdentity,
   isChannelSwitched: mocks.isChannelSwitched,
   notifyAppReady: mocks.notifyAppReady,
   reload: mocks.reload,
   resetChannel: mocks.resetChannel,
   setCohort: mocks.setCohort,
   setReloadBehavior: mocks.setReloadBehavior,
-  setUser: mocks.setUser,
-  updateBundle: mocks.updateBundle,
+  stageBundle: mocks.stageBundle,
 }));
 
 vi.mock("./wrap", () => ({
@@ -120,7 +128,6 @@ describe("HotUpdater client initialization", () => {
     const HotUpdater = await importHotUpdater();
 
     HotUpdater.init({
-      insights: true,
       baseURL: "https://updates.example.com",
       requestHeaders: { Authorization: "Bearer token" },
       requestTimeout: 1000,
@@ -130,7 +137,6 @@ describe("HotUpdater client initialization", () => {
       "https://updates.example.com",
     );
     expect(mocks.init).toHaveBeenCalledWith({
-      insights: true,
       client,
       requestHeaders: { Authorization: "Bearer token" },
       requestTimeout: 1000,
@@ -147,105 +153,131 @@ describe("HotUpdater client initialization", () => {
     expect(resolveBaseURL).not.toHaveBeenCalled();
   });
 
-  it("enables insights by default for init and wrap", async () => {
-    const HotUpdater = await importHotUpdater();
-
-    HotUpdater.init({ baseURL: "https://updates.example.com" });
-    HotUpdater.wrap({
-      baseURL: "https://updates.example.com",
-      updateStrategy: "appVersion",
+  it("sets up plugins with the settings they fetch with, before init reads the launch", async () => {
+    const plugin = { id: "example", setup: vi.fn() };
+    const onError = vi.fn();
+    mocks.init.mockImplementationOnce(() => {
+      expect(mocks.configurePlugins).toHaveBeenCalledOnce();
     });
-
-    expect(mocks.init).toHaveBeenCalledWith(
-      expect.objectContaining({ insights: true }),
-    );
-    expect(mocks.wrap).toHaveBeenCalledWith(
-      expect.objectContaining({ insights: true }),
-    );
-  });
-
-  it("preserves an explicit insights opt-out", async () => {
     const HotUpdater = await importHotUpdater();
 
     HotUpdater.init({
       baseURL: "https://updates.example.com",
-      insights: false,
+      onError,
+      plugins: [plugin],
+      requestHeaders: { "x-api-key": "client-key" },
+      requestTimeout: 1000,
     });
     HotUpdater.wrap({
-      baseURL: "https://updates.example.com",
-      insights: false,
+      baseURL: "https://other.example.com",
+      plugins: [plugin],
       updateStrategy: "appVersion",
     });
 
+    expect(mocks.configurePlugins).toHaveBeenNthCalledWith(1, [plugin], {
+      baseURL: "https://updates.example.com",
+      onError,
+      requestHeaders: { "x-api-key": "client-key" },
+      requestTimeout: 1000,
+    });
+    expect(mocks.configurePlugins).toHaveBeenNthCalledWith(2, [plugin], {
+      baseURL: "https://other.example.com",
+      onError: undefined,
+      requestHeaders: undefined,
+      requestTimeout: undefined,
+    });
     expect(mocks.init).toHaveBeenCalledWith(
-      expect.objectContaining({ insights: false }),
+      expect.not.objectContaining({ plugins: expect.anything() }),
     );
     expect(mocks.wrap).toHaveBeenCalledWith(
-      expect.objectContaining({ insights: false }),
+      expect.not.objectContaining({ plugins: expect.anything() }),
     );
   });
 
-  it.each([
-    { dev: true, insights: undefined, expected: false },
-    { dev: true, insights: true, expected: false },
-    { dev: true, insights: false, expected: false },
-    { dev: true, insights: { debug: true }, expected: true },
-    { dev: false, insights: { debug: true }, expected: true },
-    { dev: false, insights: { debug: false }, expected: true },
-    { dev: false, insights: false, expected: false },
-  ] as const)(
-    "resolves insights $insights to $expected when __DEV__ is $dev",
-    async ({ dev, insights, expected }) => {
-      vi.stubGlobal("__DEV__", dev);
-      vi.spyOn(console, "error").mockImplementation(() => undefined);
-      const HotUpdater = await importHotUpdater();
+  it("reports a staged manual download to plugins after the launch", async () => {
+    mocks.stageBundle.mockResolvedValueOnce({
+      delivery: "archive",
+      patchFallback: true,
+    });
+    mocks.getActiveUpdateState.mockReturnValue({
+      activeSelection: {
+        bundleId: "next-bundle-id",
+        channel: "production",
+        kind: "BUNDLE",
+        releaseId: "next-release-id",
+        scopeKey: "v1:fingerprint:project:ios:cHJvZHVjdGlvbg:hash",
+      },
+      highestSeenCatalogs: {},
+      stableSelection: null,
+      verificationPending: true,
+    } as never);
+    const HotUpdater = await importHotUpdater();
+    HotUpdater.init({ baseURL: "https://updates.example.com" });
 
-      HotUpdater.init({ baseURL: "https://updates.example.com", insights });
-      HotUpdater.wrap({
-        baseURL: "https://updates.example.com",
-        insights,
-        updateStrategy: "appVersion",
-      });
+    await HotUpdater.updateBundle({
+      assets: {},
+      bundleId: "next-bundle-id",
+      manifestFileHash: "manifest-hash",
+      manifestUrl: "https://updates.example.com/manifest.json",
+      status: "UPDATE",
+    });
 
-      expect(mocks.init).toHaveBeenCalledWith(
-        expect.objectContaining({ insights: expected }),
-      );
-      expect(mocks.wrap).toHaveBeenCalledWith(
-        expect.objectContaining({ insights: expected }),
-      );
-    },
-  );
+    expect(mocks.emitAfterAppReady).toHaveBeenCalledOnce();
+    const [name, createPayload] = mocks.emitAfterAppReady.mock.calls[0] as [
+      string,
+      () => unknown,
+    ];
+    expect(name).toBe("onBundleDownloaded");
+    expect(createPayload()).toEqual({
+      channel: "production",
+      fromBundleId: "bundle-id",
+      fromReleaseId: null,
+      toBundleId: "next-bundle-id",
+      toReleaseId: "next-release-id",
+      updateStrategy: "fingerprint",
+      delivery: "archive",
+      patchFallback: true,
+    });
+  });
 
-  it.each([
-    { dev: true, reports: false },
-    { dev: false, reports: true },
-  ])(
-    "gates manual checks and downloads on the build type (__DEV__: $dev)",
-    async ({ dev, reports }) => {
-      vi.stubGlobal("__DEV__", dev);
-      const sendInsightsEvent = vi.fn(async () => undefined);
-      mocks.createHttpClient.mockReturnValue({
-        createSession: vi.fn(async () => ({ sendInsightsEvent })),
-      } as never);
-      mocks.updateBundle.mockResolvedValueOnce(true);
-      const HotUpdater = await importHotUpdater();
-      HotUpdater.init({ baseURL: "https://updates.example.com" });
+  it("reports a failed manual download to plugins and rethrows it", async () => {
+    const error = Object.assign(new Error("hash mismatch"), {
+      code: "SIGNATURE_VERIFICATION_FAILED",
+      userInfo: { reason: "hash_mismatch", stage: "download" },
+    });
+    mocks.stageBundle.mockRejectedValueOnce(error);
+    const HotUpdater = await importHotUpdater();
+    HotUpdater.init({ baseURL: "https://updates.example.com" });
 
-      await HotUpdater.checkForUpdate({ updateStrategy: "appVersion" });
-      await HotUpdater.updateBundle({
+    await expect(
+      HotUpdater.updateBundle({
         assets: {},
         bundleId: "next-bundle-id",
+        channel: "beta",
         manifestFileHash: "manifest-hash",
         manifestUrl: "https://updates.example.com/manifest.json",
+        selection: {
+          releaseId: "next-release-id",
+          scopeKey: "v1:app-version:project:ios:YmV0YQ",
+        },
         status: "UPDATE",
-      });
-
-      expect(mocks.checkForUpdate).toHaveBeenCalledWith(
-        expect.objectContaining({ insights: reports }),
-      );
-      expect(sendInsightsEvent).toHaveBeenCalledTimes(reports ? 1 : 0);
-    },
-  );
+      }),
+    ).rejects.toBe(error);
+
+    expect(mocks.reportUpdateError).toHaveBeenCalledWith(
+      error,
+      "download",
+      undefined,
+      {
+        bundleId: "bundle-id",
+        channel: "beta",
+        targetBundleId: "next-bundle-id",
+        targetReleaseId: "next-release-id",
+        updateStrategy: "appVersion",
+      },
+    );
+    expect(mocks.emitAfterAppReady).not.toHaveBeenCalled();
+  });
 
   it("requires baseURL and rejects the removed resolver shape", async () => {
     const HotUpdater = await importHotUpdater();
@@ -288,13 +320,12 @@ describe("HotUpdater client initialization", () => {
     expect(wrapOptions.updateStrategy).toBe("appVersion");
   });
 
-  it("merges settings and carries the insights gate to checks", async () => {
+  it("merges settings into checks", async () => {
     const client = { createSession: vi.fn() };
     mocks.createHttpClient.mockReturnValue(client as never);
     const checkOnError = vi.fn();
     const HotUpdater = await importHotUpdater();
     HotUpdater.init({
-      insights: true,
       baseURL: "https://updates.example.com",
       requestHeaders: { Authorization: "Bearer token" },
       requestTimeout: 1000,
@@ -307,7 +338,6 @@ describe("HotUpdater client initialization", () => {
     });
 
     expect(mocks.checkForUpdate).toHaveBeenCalledWith({
-      insights: true,
       client,
       onError: checkOnError,
       requestHeaders: {
@@ -325,13 +355,11 @@ describe("HotUpdater client initialization", () => {
     const HotUpdater = await importHotUpdater();
 
     HotUpdater.wrap({
-      insights: true,
       baseURL: "https://updates.example.com",
       updateStrategy: "appVersion",
     });
 
     expect(mocks.wrap).toHaveBeenCalledWith({
-      insights: true,
       client,
       updateStrategy: "appVersion",
     });
@@ -396,15 +424,11 @@ describe("HotUpdater client initialization", () => {
     ).toThrow("requires HotUpdater.wrap() or HotUpdater.init() to be used");
   });
 
-  it("preserves native identity and user APIs", async () => {
+  it("keeps the install id and leaves user identity to the insights plugin", async () => {
     const HotUpdater = await importHotUpdater();
 
     expect(HotUpdater.getInstallId()).toBe("install-id");
     expect(HotUpdater.getMinBundleId()).toBe("min-bundle-id");
-    HotUpdater.setUser({ userId: "user-123", username: "alice" });
-    expect(mocks.setUser).toHaveBeenCalledWith({
-      userId: "user-123",
-      username: "alice",
-    });
+    expect(HotUpdater).not.toHaveProperty("setUser");
   });
 });

package/src/index.ts

@@ -1,7 +1,9 @@
+import { emitAfterAppReady } from "./appReady";
 import {
   type CheckForUpdateOptions,
   checkForUpdate,
   type InternalCheckForUpdateOptions,
+  reportUpdateError,
 } from "./checkForUpdate";
 import { createHttpClient, type HotUpdaterHttpClient } from "./httpClient";
 import {
@@ -27,11 +29,10 @@ import {
   resetChannel,
   setCohort,
   setReloadBehavior,
-  setUser,
+  stageBundle,
   type UpdateParams,
-  updateBundle,
 } from "./native";
-import { reportBundleDownloaded } from "./notifyAppReadyInsights";
+import { configurePlugins } from "./pluginHost";
 import { hotUpdaterStore } from "./store";
 import {
   type AutoUpdateOptions,
@@ -43,6 +44,21 @@ import {
   wrap,
 } from "./wrap";
 
+export {
+  defineClientPlugin,
+  type AppReadyResult,
+  type BundleDownloadedInfo,
+  type HotUpdaterClientContext,
+  type HotUpdaterClientHooks,
+  type HotUpdaterClientPlugin,
+  type HotUpdaterClientStorage,
+  type ReleaseTransitionKind,
+  type UpdateCheckResult,
+  type UpdateError,
+  type UpdateErrorReason,
+  type UpdateErrorStage,
+  type UpdateStrategy,
+} from "./clientPlugin";
 export type {
   CustomReloadHandler,
   HotUpdaterEvent,
@@ -54,7 +70,6 @@ export type {
   ActiveUpdateState,
   ReloadBehavior,
   ReloadBehaviorSetting,
-  SetUserParams,
 } from "./native";
 export * from "./store";
 export {
@@ -93,21 +108,6 @@ type HotUpdaterWrap = {
   (options: HotUpdaterOptions): ReturnType<typeof wrap>;
 };
 
-/**
- * Debug builds report only with `insights: { debug: true }`, so development
- * sessions do not mix into production Insights. `__DEV__` is defined only in
- * a React Native bundle; anywhere else, such as unit tests, counts as release.
- */
-const resolveInsights = (
-  insights: HotUpdaterInitOptions["insights"],
-): boolean => {
-  if (insights === false) return false;
-  const isDebugBuild = typeof __DEV__ !== "undefined" && __DEV__;
-  return (
-    !isDebugBuild || (typeof insights === "object" && insights?.debug === true)
-  );
-};
-
 /**
  * Creates a HotUpdater client instance with all update management methods.
  * This function is called once on module initialization to create a singleton instance.
@@ -118,13 +118,11 @@ function createHotUpdaterClient() {
 
   // Global configuration stored from wrap
   const globalConfig: {
-    insights: boolean;
     client: HotUpdaterHttpClient | null;
     requestHeaders?: Record<string, string>;
     requestTimeout?: number;
     onError?: (error: unknown) => void;
   } = {
-    insights: true,
     client: null,
   };
 
@@ -173,10 +171,9 @@ function createHotUpdaterClient() {
     const autoOptions = incoming as AutoUpdateOptions;
 
     if (autoOptions.baseURL) {
-      const { baseURL, ...rest } = autoOptions;
+      const { baseURL, plugins: _plugins, ...rest } = autoOptions;
       return {
         ...rest,
-        insights: resolveInsights(rest.insights),
         client: createHttpClient(baseURL),
       };
     }
@@ -193,10 +190,9 @@ function createHotUpdaterClient() {
       };
 
     if (rest.baseURL) {
-      const { baseURL, ...baseURLRest } = rest;
+      const { baseURL, plugins: _plugins, ...baseURLRest } = rest;
       return {
         ...baseURLRest,
-        insights: resolveInsights(baseURLRest.insights),
         client: createHttpClient(baseURL),
       };
     }
@@ -208,7 +204,13 @@ function createHotUpdaterClient() {
     normalizedOptions: InternalInitOptions | InternalWrapOptions,
     options: HotUpdaterOptions | HotUpdaterInitOptions,
   ) => {
-    globalConfig.insights = normalizedOptions.insights ?? true;
+    // Plugins are set up before init or wrap reads the launch they observe.
+    configurePlugins(options.plugins, {
+      baseURL: options.baseURL,
+      requestHeaders: options.requestHeaders,
+      requestTimeout: options.requestTimeout,
+      onError: options.onError,
+    });
     globalConfig.client = normalizedOptions.client;
     globalConfig.requestHeaders = options.requestHeaders;
     globalConfig.requestTimeout = options.requestTimeout;
@@ -466,7 +468,6 @@ function createHotUpdaterClient() {
 
       const mergedConfig: InternalCheckForUpdateOptions = {
         ...config,
-        insights: globalConfig.insights,
         client,
         requestHeaders: {
           ...globalConfig.requestHeaders,
@@ -508,33 +509,52 @@ function createHotUpdaterClient() {
      * ```
      */
     updateBundle: async (params: UpdateParams) => {
-      const client = ensureGlobalClient("updateBundle");
+      ensureGlobalClient("updateBundle");
       const fromBundleId = getBundleId();
       const state = getActiveUpdateState();
       const active = state.activeSelection;
-      const downloaded = await updateBundle(params);
-      if (downloaded) {
-        const selection = getActiveUpdateState().activeSelection;
-        await reportBundleDownloaded(
-          { ...globalConfig, client },
-          {
+      const fromReleaseId =
+        active?.bundleId === fromBundleId
+          ? active.releaseId
+          : state.stableSelection?.bundleId === fromBundleId
+            ? state.stableSelection.releaseId
+            : null;
+      const channel = params.channel ?? getChannel();
+      const strategyOf = (scopeKey: string | null | undefined) =>
+        scopeKey?.startsWith("v1:fingerprint:") ? "fingerprint" : "appVersion";
+      let delivery: Awaited<ReturnType<typeof stageBundle>>;
+      try {
+        delivery = await stageBundle(params);
+      } catch (error) {
+        reportUpdateError(error, "download", undefined, {
+          bundleId: fromBundleId,
+          channel,
+          targetBundleId: params.bundleId,
+          targetReleaseId:
+            (params.selection as { releaseId?: string | null } | undefined)
+              ?.releaseId ?? null,
+          updateStrategy: strategyOf(
+            (params.selection as { scopeKey?: string | null } | undefined)
+              ?.scopeKey,
+          ),
+        });
+        throw error;
+      }
+      if (delivery !== null && params.bundleId !== fromBundleId) {
+        emitAfterAppReady("onBundleDownloaded", () => {
+          const selection = getActiveUpdateState().activeSelection;
+          return {
+            channel,
             fromBundleId,
-            fromReleaseId:
-              active?.bundleId === fromBundleId
-                ? active.releaseId
-                : state.stableSelection?.bundleId === fromBundleId
-                  ? state.stableSelection.releaseId
-                  : null,
+            fromReleaseId,
             toBundleId: params.bundleId,
             toReleaseId: selection?.releaseId ?? null,
-            channel: params.channel ?? getChannel(),
-            updateStrategy: selection?.scopeKey?.startsWith("v1:fingerprint:")
-              ? "fingerprint"
-              : "appVersion",
-          },
-        );
+            updateStrategy: strategyOf(selection?.scopeKey),
+            ...delivery,
+          };
+        });
       }
-      return downloaded;
+      return true;
     },
 
     /**
@@ -573,11 +593,6 @@ function createHotUpdaterClient() {
      */
     getInstallId,
 
-    /**
-     * Persists nullable user identity fields associated with this installation.
-     */
-    setUser,
-
     /**
      * Reads the native launch report for the current process.
      */