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

package/src/httpClient.ts

@@ -6,10 +6,11 @@ import {
 } from "@hot-updater/core";
 import { canonicalizeAppVersion } from "@hot-updater/plugin-core";
 
+import { resolveBaseURL } from "./baseURL";
 import { fetchJSON, FetchJSONResponseError } from "./fetchJSON";
 import { fetchReleaseCatalogWithCache } from "./releaseCatalogCache";
-import { HOT_UPDATER_SDK_VERSION } from "./sdkVersion";
 import type { HotUpdaterBaseURL } from "./types";
+import { InvalidUpdateResponseError } from "./updateError";
 
 export interface ReleaseCatalogRequest {
   readonly platform: "ios" | "android";
@@ -28,69 +29,31 @@ export interface ArtifactRequest {
   readonly requestTimeout?: number;
 }
 
-interface InsightsEventCommonParams {
-  readonly installId: string;
-  readonly userId?: string;
-  readonly username?: string;
-  readonly platform: "ios" | "android";
-  readonly appVersion: string;
-  readonly channel: string;
-  readonly cohort: string;
-  readonly fingerprintHash: string | null;
-  readonly fromReleaseId?: string | null;
-  readonly toReleaseId?: string | null;
-  readonly requestHeaders?: Record<string, string>;
-  readonly requestTimeout?: number;
-}
-
-type InsightsTransitionEventParams = InsightsEventCommonParams & {
-  readonly type: "UPDATE_DOWNLOADED" | "UPDATE_APPLIED" | "RECOVERED";
-  readonly fromBundleId: string;
-  readonly toBundleId: string;
-  readonly updateStrategy: "fingerprint" | "appVersion";
-};
-
-type InsightsUnchangedEventParams = InsightsEventCommonParams & {
-  readonly type: "UNCHANGED";
-  readonly fromBundleId: null;
-  readonly toBundleId: string;
-  readonly updateStrategy: null;
-};
-
-export type InsightsEventParams =
-  | InsightsTransitionEventParams
-  | InsightsUnchangedEventParams;
-
 export interface HotUpdaterHttpSession {
+  /** Resolves to null when the server says the scope has no catalog, so no update. */
   fetchReleaseCatalog: (
     params: ReleaseCatalogRequest,
-  ) => Promise<ReleaseCatalog>;
+  ) => Promise<ReleaseCatalog | null>;
   resolveArtifact: (params: ArtifactRequest) => Promise<ArtifactInfo>;
-  sendInsightsEvent: (params: InsightsEventParams) => Promise<void>;
 }
 
 export interface HotUpdaterHttpClient {
   createSession: () => Promise<HotUpdaterHttpSession>;
 }
 
-const resolveBaseURL = async (baseURL: HotUpdaterBaseURL): Promise<string> => {
-  const resolvedBaseURL =
-    typeof baseURL === "function" ? await baseURL() : baseURL;
-
-  if (!resolvedBaseURL) {
-    throw new Error("baseURL function must return a non-empty string");
-  }
-
-  return resolvedBaseURL.replace(/\/+$/, "");
-};
-
 const resolveArtifactUrl = (baseURL: string, value: string): string => {
   if (/^https?:\/\//i.test(value)) {
-    new URL(value);
+    try {
+      new URL(value);
+    } catch (error) {
+      throw new InvalidUpdateResponseError(`Invalid artifact URL: ${value}`, {
+        cause: error,
+      });
+    }
     return value;
   }
   if (!value.startsWith("/storage/")) {
-    throw new Error(
+    throw new InvalidUpdateResponseError(
       "Artifact URLs must be absolute HTTP(S) URLs or client-relative storage paths.",
     );
   }
@@ -136,13 +99,13 @@ const requireArtifactProtocolV1 = (info: ArtifactInfo): ArtifactInfo => {
     !info.manifestFileHash ||
     (info.archiveUrl !== undefined && typeof info.archiveUrl !== "string")
   ) {
-    throw new Error(
+    throw new InvalidUpdateResponseError(
       `Server does not support artifact protocol ${ARTIFACT_PROTOCOL_VERSION}.`,
     );
   }
   for (const asset of Object.values(info.assets)) {
     if (!asset.file?.url || !asset.fileHash) {
-      throw new Error(
+      throw new InvalidUpdateResponseError(
         "Artifact protocol 1 requires an original file for every asset.",
       );
     }
@@ -150,63 +113,8 @@ const requireArtifactProtocolV1 = (info: ArtifactInfo): ArtifactInfo => {
   return info;
 };
 
-const sendInsightsEvent = async (
-  baseURL: string,
-  params: InsightsEventParams,
-): Promise<void> => {
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => {
-    controller.abort();
-  }, params.requestTimeout ?? 5000);
-
-  try {
-    const response = await fetch(`${baseURL}/events`, {
-      body: JSON.stringify({
-        appVersion: params.appVersion,
-        channel: params.channel,
-        cohort: params.cohort,
-        fingerprintHash: params.fingerprintHash,
-        fromBundleId: params.fromBundleId,
-        ...(params.fromReleaseId === undefined
-          ? {}
-          : { fromReleaseId: params.fromReleaseId }),
-        installId: params.installId,
-        platform: params.platform,
-        sdkVersion: HOT_UPDATER_SDK_VERSION,
-        toBundleId: params.toBundleId,
-        ...(params.toReleaseId === undefined
-          ? {}
-          : { toReleaseId: params.toReleaseId }),
-        type: params.type,
-        updateStrategy: params.updateStrategy,
-        ...(params.userId != null ? { userId: params.userId } : {}),
-        ...(params.username != null ? { username: params.username } : {}),
-      }),
-      headers: {
-        "Content-Type": "application/json",
-        ...params.requestHeaders,
-      },
-      method: "POST",
-      signal: controller.signal,
-    });
-
-    if (response.status !== 204) {
-      throw new Error(
-        `Expected HTTP 204 from /events, received ${response.status}`,
-      );
-    }
-  } catch (error: unknown) {
-    if (error instanceof Error && error.name === "AbortError") {
-      throw new Error("Request timed out");
-    }
-    throw error;
-  } finally {
-    clearTimeout(timeoutId);
-  }
-};
-
 const createSession = (baseURL: string): HotUpdaterHttpSession => ({
-  fetchReleaseCatalog: async (params): Promise<ReleaseCatalog> => {
+  fetchReleaseCatalog: async (params): Promise<ReleaseCatalog | null> => {
     const channelKey = encodeChannelKey(params.channel);
     let strategyValue: string;
     if (params.updateStrategy === "fingerprint") {
@@ -255,7 +163,7 @@ const createSession = (baseURL: string): HotUpdaterHttpSession => ({
       });
     } catch (error) {
       if (error instanceof FetchJSONResponseError && error.status === 404) {
-        throw new Error(
+        throw new InvalidUpdateResponseError(
           `Server does not support artifact protocol ${ARTIFACT_PROTOCOL_VERSION}.`,
           { cause: error },
         );
@@ -264,7 +172,6 @@ const createSession = (baseURL: string): HotUpdaterHttpSession => ({
     }
     return resolveArtifactUrls(baseURL, requireArtifactProtocolV1(info));
   },
-  sendInsightsEvent: (params) => sendInsightsEvent(baseURL, params),
 });
 
 /** Creates the private HTTP client used by HotUpdater.init and HotUpdater.wrap. */

package/src/index.spec.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { HotUpdaterInitOptions, HotUpdaterOptions } from "./wrap";
 
@@ -31,6 +31,9 @@ const mocks = vi.hoisted(() => {
     getInstallId: vi.fn(() => "install-id"),
     getManifest: vi.fn(() => null),
     getMinBundleId: vi.fn(() => "min-bundle-id"),
+    configurePlugins: vi.fn(),
+    emitAfterAppReady: vi.fn(),
+    reportUpdateError: vi.fn(),
     init: vi.fn(),
     isChannelSwitched: vi.fn(() => false),
     notifyAppReady: vi.fn(() => ({ status: "UNCHANGED" as const })),
@@ -38,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),
   };
 });
@@ -52,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", () => ({
@@ -77,8 +88,7 @@ vi.mock("./native", () => ({
   resetChannel: mocks.resetChannel,
   setCohort: mocks.setCohort,
   setReloadBehavior: mocks.setReloadBehavior,
-  setUser: mocks.setUser,
-  updateBundle: mocks.updateBundle,
+  stageBundle: mocks.stageBundle,
 }));
 
 vi.mock("./wrap", () => ({
@@ -99,6 +109,11 @@ describe("HotUpdater client initialization", () => {
     mocks.wrap.mockImplementation((Component: unknown) => Component);
   });
 
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
   it("exposes the console ID through the existing getter only", async () => {
     const HotUpdater = await importHotUpdater();
 
@@ -113,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,
@@ -123,7 +137,6 @@ describe("HotUpdater client initialization", () => {
       "https://updates.example.com",
     );
     expect(mocks.init).toHaveBeenCalledWith({
-      insights: true,
       client,
       requestHeaders: { Authorization: "Bearer token" },
       requestTimeout: 1000,
@@ -140,42 +153,130 @@ describe("HotUpdater client initialization", () => {
     expect(resolveBaseURL).not.toHaveBeenCalled();
   });
 
-  it("enables insights by default for init and wrap", async () => {
+  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();
+    });
     const HotUpdater = await importHotUpdater();
 
-    HotUpdater.init({ baseURL: "https://updates.example.com" });
-    HotUpdater.wrap({
+    HotUpdater.init({
       baseURL: "https://updates.example.com",
+      onError,
+      plugins: [plugin],
+      requestHeaders: { "x-api-key": "client-key" },
+      requestTimeout: 1000,
+    });
+    HotUpdater.wrap({
+      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: true }),
+      expect.not.objectContaining({ plugins: expect.anything() }),
     );
     expect(mocks.wrap).toHaveBeenCalledWith(
-      expect.objectContaining({ insights: true }),
+      expect.not.objectContaining({ plugins: expect.anything() }),
     );
   });
 
-  it("preserves an explicit insights opt-out", async () => {
+  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: false,
+    await HotUpdater.updateBundle({
+      assets: {},
+      bundleId: "next-bundle-id",
+      manifestFileHash: "manifest-hash",
+      manifestUrl: "https://updates.example.com/manifest.json",
+      status: "UPDATE",
     });
-    HotUpdater.wrap({
-      baseURL: "https://updates.example.com",
-      insights: false,
-      updateStrategy: "appVersion",
+
+    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,
     });
+  });
 
-    expect(mocks.init).toHaveBeenCalledWith(
-      expect.objectContaining({ insights: false }),
-    );
-    expect(mocks.wrap).toHaveBeenCalledWith(
-      expect.objectContaining({ insights: false }),
+  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 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",
+      }),
+    ).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 () => {
@@ -219,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,
@@ -238,7 +338,6 @@ describe("HotUpdater client initialization", () => {
     });
 
     expect(mocks.checkForUpdate).toHaveBeenCalledWith({
-      insights: true,
       client,
       onError: checkOnError,
       requestHeaders: {
@@ -256,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",
     });
@@ -327,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 {
@@ -103,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,
   };
 
@@ -158,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: rest.insights ?? true,
         client: createHttpClient(baseURL),
       };
     }
@@ -178,10 +190,9 @@ function createHotUpdaterClient() {
       };
 
     if (rest.baseURL) {
-      const { baseURL, ...baseURLRest } = rest;
+      const { baseURL, plugins: _plugins, ...baseURLRest } = rest;
       return {
         ...baseURLRest,
-        insights: baseURLRest.insights ?? true,
         client: createHttpClient(baseURL),
       };
     }
@@ -193,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;
@@ -451,7 +468,6 @@ function createHotUpdaterClient() {
 
       const mergedConfig: InternalCheckForUpdateOptions = {
         ...config,
-        insights: globalConfig.insights,
         client,
         requestHeaders: {
           ...globalConfig.requestHeaders,
@@ -493,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;
     },
 
     /**
@@ -558,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.
      */