@hot-updater/react-native 1.0.0-rc.2 → 1.0.0-rc.21

package/src/httpClient.ts

@@ -1,14 +1,16 @@
 import {
+  ARTIFACT_PROTOCOL_VERSION,
+  canonicalizeAppVersion,
   encodeChannelKey,
+  resolveBaseURL,
   type ArtifactInfo,
+  type HotUpdaterBaseURL,
   type ReleaseCatalog,
-} from "@hot-updater/core";
-import { canonicalizeAppVersion } from "@hot-updater/plugin-core";
+} from "@hot-updater/protocol";
 
-import { fetchJSON } from "./fetchJSON";
+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";
@@ -27,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_APPLIED" | "RECOVERED" | "RELEASE_ADOPTED";
-  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.",
     );
   }
@@ -101,109 +65,56 @@ const resolveArtifactUrls = (
   info: ArtifactInfo,
 ): ArtifactInfo => ({
   ...info,
-  fileUrl:
-    info.fileUrl === null ? null : resolveArtifactUrl(baseURL, info.fileUrl),
-  ...(info.manifestUrl === undefined
-    ? {}
-    : {
-        manifestUrl:
-          info.manifestUrl === null
-            ? null
-            : resolveArtifactUrl(baseURL, info.manifestUrl),
-      }),
-  ...(info.changedAssets === undefined
-    ? {}
-    : {
-        changedAssets:
-          info.changedAssets === null
-            ? null
-            : Object.fromEntries(
-                Object.entries(info.changedAssets).map(([path, asset]) => [
-                  path,
-                  {
-                    ...asset,
-                    ...(asset.file
-                      ? {
-                          file: {
-                            ...asset.file,
-                            url: resolveArtifactUrl(baseURL, asset.file.url),
-                          },
-                        }
-                      : {}),
-                    ...(asset.patch
-                      ? {
-                          patch: {
-                            ...asset.patch,
-                            patchUrl: resolveArtifactUrl(
-                              baseURL,
-                              asset.patch.patchUrl,
-                            ),
-                          },
-                        }
-                      : {}),
-                  },
-                ]),
-              ),
-      }),
-});
-
-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,
+  manifestUrl: resolveArtifactUrl(baseURL, info.manifestUrl),
+  ...(info.archiveUrl
+    ? { archiveUrl: resolveArtifactUrl(baseURL, info.archiveUrl) }
+    : {}),
+  assets: Object.fromEntries(
+    Object.entries(info.assets).map(([path, asset]) => [
+      path,
+      {
+        ...asset,
+        file: {
+          ...asset.file,
+          url: resolveArtifactUrl(baseURL, asset.file.url),
+        },
+        ...(asset.patch
+          ? {
+              patch: {
+                ...asset.patch,
+                patchUrl: resolveArtifactUrl(baseURL, asset.patch.patchUrl),
+              },
+            }
+          : {}),
       },
-      method: "POST",
-      signal: controller.signal,
-    });
+    ]),
+  ),
+});
 
-    if (response.status !== 204) {
-      throw new Error(
-        `Expected HTTP 204 from /events, received ${response.status}`,
+const requireArtifactProtocolV1 = (info: ArtifactInfo): ArtifactInfo => {
+  if (
+    info.artifactProtocolVersion !== ARTIFACT_PROTOCOL_VERSION ||
+    !info.assets ||
+    !info.manifestUrl ||
+    !info.manifestFileHash ||
+    (info.archiveUrl !== undefined && typeof info.archiveUrl !== "string")
+  ) {
+    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 InvalidUpdateResponseError(
+        "Artifact protocol 1 requires an original file for every asset.",
       );
     }
-  } catch (error: unknown) {
-    if (error instanceof Error && error.name === "AbortError") {
-      throw new Error("Request timed out");
-    }
-    throw error;
-  } finally {
-    clearTimeout(timeoutId);
   }
+  return info;
 };
 
 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") {
@@ -241,16 +152,26 @@ const createSession = (baseURL: string): HotUpdaterHttpSession => ({
     });
   },
   resolveArtifact: async (params): Promise<ArtifactInfo> => {
-    const info = await fetchJSON<ArtifactInfo>({
-      requestHeaders: params.requestHeaders,
-      requestTimeout: params.requestTimeout,
-      url: `${baseURL}/artifacts/${encodeURIComponent(
-        params.targetBundleId,
-      )}/from/${encodeURIComponent(params.currentBundleId)}`,
-    });
-    return resolveArtifactUrls(baseURL, info);
+    let info: ArtifactInfo;
+    try {
+      info = await fetchJSON<ArtifactInfo>({
+        requestHeaders: params.requestHeaders,
+        requestTimeout: params.requestTimeout,
+        url: `${baseURL}/artifacts/v1/${encodeURIComponent(
+          params.targetBundleId,
+        )}/from/${encodeURIComponent(params.currentBundleId)}`,
+      });
+    } catch (error) {
+      if (error instanceof FetchJSONResponseError && error.status === 404) {
+        throw new InvalidUpdateResponseError(
+          `Server does not support artifact protocol ${ARTIFACT_PROTOCOL_VERSION}.`,
+          { cause: error },
+        );
+      }
+      throw error;
+    }
+    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.ts

@@ -1,16 +1,20 @@
+import { emitAfterAppReady } from "./appReady";
 import {
   type CheckForUpdateOptions,
   checkForUpdate,
   type InternalCheckForUpdateOptions,
+  reportUpdateError,
 } from "./checkForUpdate";
 import { createHttpClient, type HotUpdaterHttpClient } from "./httpClient";
 import {
   addListener,
   getPublicActiveUpdateState,
+  getActiveUpdateState,
+  getBundleId,
   clearCrashHistory,
   getAppVersion,
   getBaseURL,
-  getBundleId,
+  getUpdateId,
   getChannel,
   getCohort,
   getCrashHistory,
@@ -19,17 +23,16 @@ import {
   getInstallId,
   getManifest,
   getMinBundleId,
-  getReleaseId,
   isChannelSwitched,
   notifyAppReady,
   reload,
   resetChannel,
   setCohort,
   setReloadBehavior,
-  setUser,
+  stageBundle,
   type UpdateParams,
-  updateBundle,
 } from "./native";
+import { configurePlugins } from "./pluginHost";
 import { hotUpdaterStore } from "./store";
 import {
   type AutoUpdateOptions,
@@ -41,6 +44,28 @@ 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";
+// The built-in Insights client plugin, for HotUpdater.init({ plugins }).
+export {
+  insights,
+  type InsightsOptions,
+  type InsightsPlugin,
+  type InsightsUser,
+} from "@hot-updater/plugin-insights/client";
 export type {
   CustomReloadHandler,
   HotUpdaterEvent,
@@ -52,7 +77,6 @@ export type {
   ActiveUpdateState,
   ReloadBehavior,
   ReloadBehaviorSetting,
-  SetUserParams,
 } from "./native";
 export * from "./store";
 export {
@@ -101,13 +125,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,
   };
 
@@ -156,10 +178,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),
       };
     }
@@ -176,10 +197,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),
       };
     }
@@ -191,7 +211,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;
@@ -336,16 +362,14 @@ function createHotUpdaterClient() {
     getActiveUpdateState: async () => getPublicActiveUpdateState(),
 
     /**
-     * Fetches the current bundle ID of the app.
+     * Returns the selected update ID, matching the ID shown in the console.
+     * A staged update can change this ID before the app reloads.
      */
-    getBundleId,
+    getBundleId: getUpdateId,
 
     /** Returns the minimum bundle ID based on the native app build time. */
     getMinBundleId,
 
-    /** Returns the active Release identity, or null for BUILTIN/legacy state. */
-    getReleaseId,
-
     /**
      * Fetches the current manifest for the active bundle.
      */
@@ -451,7 +475,6 @@ function createHotUpdaterClient() {
 
       const mergedConfig: InternalCheckForUpdateOptions = {
         ...config,
-        insights: globalConfig.insights,
         client,
         requestHeaders: {
           ...globalConfig.requestHeaders,
@@ -469,8 +492,6 @@ function createHotUpdaterClient() {
      *
      * @param {UpdateBundleParams} params - Parameters object required for bundle update
      * @param {string} params.bundleId - The bundle ID of the app
-     * @param {string|null} params.fileUrl - The URL of the zip file
-     *
      * @returns {Promise<boolean>} Whether the update was successful
      *
      * @example
@@ -494,9 +515,53 @@ function createHotUpdaterClient() {
      * }
      * ```
      */
-    updateBundle: (params: UpdateParams) => {
+    updateBundle: async (params: UpdateParams) => {
       ensureGlobalClient("updateBundle");
-      return updateBundle(params);
+      const fromBundleId = getBundleId();
+      const state = getActiveUpdateState();
+      const active = state.activeSelection;
+      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,
+            toBundleId: params.bundleId,
+            toReleaseId: selection?.releaseId ?? null,
+            updateStrategy: strategyOf(selection?.scopeKey),
+            ...delivery,
+          };
+        });
+      }
+      return true;
     },
 
     /**
@@ -510,10 +575,8 @@ function createHotUpdaterClient() {
         hotUpdaterStore.setState({
           artifactType: null,
           details: null,
-          downloadedBytes: undefined,
           isUpdateDownloaded: false,
           progress: 0,
-          totalBytes: undefined,
         });
       }
       return ok;
@@ -537,11 +600,6 @@ function createHotUpdaterClient() {
      */
     getInstallId,
 
-    /**
-     * Persists nullable user identity fields associated with this installation.
-     */
-    setUser,
-
     /**
      * Reads the native launch report for the current process.
      */