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

package/src/checkForUpdate.ts

@@ -1,17 +1,28 @@
 import {
   authorizeReleaseTransition,
+  canonicalizeAppVersion,
   createReleaseSelectionContextHash,
   encodeChannelKey,
+  type ExpectedReleaseCatalogScope,
+  hasExpectedReleaseCatalogScope,
   selectDesiredRelease,
-  type ArtifactInfo,
   type PersistedSelectionReceipt,
   type ReleaseCatalog,
-} from "@hot-updater/core";
-import { canonicalizeAppVersion } from "@hot-updater/plugin-core";
+} from "@hot-updater/protocol";
 import { Platform } from "react-native";
 
+import {
+  emitAfterAppReady,
+  getPreviousProcessExit,
+  getRunningReleaseId,
+} from "./appReady";
+import type {
+  ReleaseTransitionKind,
+  UpdateErrorResource,
+  UpdateErrorStage,
+} from "./clientPlugin";
 import { HotUpdaterError, StaleReleaseCatalogError } from "./error";
-import type { HotUpdaterHttpClient, HotUpdaterHttpSession } from "./httpClient";
+import type { HotUpdaterHttpClient } from "./httpClient";
 import {
   acceptReleaseCatalog,
   commitReleaseSelection,
@@ -22,19 +33,16 @@ import {
   getCohort,
   getDefaultChannel,
   getFingerprintHash,
-  getInstallId,
   getMinBundleId,
   getCrashHistory,
-  getPersistedUserIdentity,
   isReleaseSelectionCurrent,
   isChannelSwitched,
-  updateBundle,
+  stageBundle,
 } from "./native";
-import {
-  hasExpectedReleaseCatalogScope,
-  type ExpectedReleaseCatalogScope,
-} from "./releaseCatalogCache";
 import { hotUpdaterStore } from "./store";
+import { classifyUpdateError, InvalidUpdateResponseError } from "./updateError";
+
+export type { ReleaseTransitionKind };
 
 export interface CheckForUpdateOptions {
   /**
@@ -60,7 +68,7 @@ export interface CheckForUpdateOptions {
   requestTimeout?: number;
 }
 
-export type CheckForUpdateResult = ArtifactInfo & {
+export type CheckForUpdateResult = {
   readonly id: string;
   readonly message: string | null;
   readonly rolloutCohortCount: number;
@@ -76,14 +84,7 @@ export type CheckForUpdateResult = ArtifactInfo & {
   updateBundle: () => Promise<boolean>;
 };
 
-export type ReleaseTransitionKind =
-  | "INSTALL"
-  | "ADOPT_RELEASE"
-  | "USE_EMBEDDED"
-  | "USE_BUILTIN";
-
 export interface InternalCheckForUpdateOptions extends CheckForUpdateOptions {
-  insights?: boolean;
   client: HotUpdaterHttpClient;
 }
 
@@ -113,7 +114,7 @@ const validateCatalog = (
     !/^sha256:[0-9a-f]{64}$/.test(catalog.catalogHash) ||
     !hasExpectedReleaseCatalogScope(catalog, expectedScope)
   ) {
-    throw new HotUpdaterError("Received an invalid Release catalog");
+    throw new InvalidUpdateResponseError("Received an invalid Release catalog");
   }
 };
 
@@ -121,48 +122,50 @@ const resetProgress = () => {
   hotUpdaterStore.setState({
     artifactType: null,
     details: null,
-    downloadedBytes: undefined,
     isUpdateDownloaded: false,
     progress: 0,
-    totalBytes: undefined,
   });
 };
 
-const notifyReleaseAdoption = async (input: {
-  readonly active: PersistedSelectionReceipt | null;
-  readonly desired: PersistedSelectionReceipt;
-  readonly appVersion: string;
-  readonly cohort: string;
-  readonly fingerprintHash: string | null;
-  readonly platform: "ios" | "android";
-  readonly session: HotUpdaterHttpSession;
-  readonly requestHeaders?: Record<string, string>;
-  readonly requestTimeout?: number;
-  readonly updateStrategy: "appVersion" | "fingerprint";
-}): Promise<void> => {
-  const { userId, username } = getPersistedUserIdentity();
-  try {
-    await input.session.sendInsightsEvent({
-      appVersion: input.appVersion,
-      channel: input.desired.channel,
-      cohort: input.cohort,
-      fingerprintHash: input.fingerprintHash,
-      fromBundleId: input.desired.bundleId,
-      fromReleaseId: input.active?.releaseId ?? null,
-      installId: getInstallId(),
-      platform: input.platform,
-      requestHeaders: input.requestHeaders,
-      requestTimeout: input.requestTimeout,
-      toBundleId: input.desired.bundleId,
-      toReleaseId: input.desired.releaseId,
-      type: "RELEASE_ADOPTED",
-      updateStrategy: input.updateStrategy,
-      ...(userId === undefined ? {} : { userId }),
-      ...(username === undefined ? {} : { username }),
-    });
-  } catch (error) {
-    console.warn("[HotUpdater] Release adoption insights failed:", error);
-  }
+/** The running bundle, the channel checked, and the update's target. */
+type UpdateErrorScope = {
+  readonly channel: string;
+  readonly bundleId: string;
+  readonly updateStrategy: "fingerprint" | "appVersion";
+  readonly targetBundleId?: string;
+  readonly targetReleaseId?: string | null;
+};
+
+/**
+ * Tells plugins why an update failed, when it failed as an update. An error
+ * the SDK's JavaScript raised happened in `stage`, fetching `resource`.
+ */
+export const reportUpdateError = (
+  error: unknown,
+  stage: UpdateErrorStage,
+  resource: UpdateErrorResource | undefined,
+  scope: UpdateErrorScope,
+): void => {
+  emitAfterAppReady("onUpdateError", () => {
+    const classification = classifyUpdateError(error, stage, resource);
+    if (classification === null) return null;
+    const previousProcessExit = getPreviousProcessExit();
+    return {
+      ...classification,
+      ...(previousProcessExit === null ? {} : { previousProcessExit }),
+      channel: scope.channel,
+      bundleId: scope.bundleId,
+      releaseId: getRunningReleaseId(scope.bundleId, getChannel()),
+      updateStrategy: scope.updateStrategy,
+      ...(scope.targetBundleId === undefined
+        ? {}
+        : { targetBundleId: scope.targetBundleId }),
+      ...(scope.targetReleaseId == null
+        ? {}
+        : { targetReleaseId: scope.targetReleaseId }),
+      cause: error,
+    };
+  });
 };
 
 async function checkForReleaseCatalogUpdate(input: {
@@ -213,12 +216,15 @@ async function checkForReleaseCatalogUpdate(input: {
     requestTimeout: options.requestTimeout,
     updateStrategy: options.updateStrategy,
   });
+  // The server says this scope has no catalog yet: no update, not a failure.
+  if (catalog === null) return null;
   validateCatalog(catalog, expectedScope);
   const catalogId = catalog.catalogId;
   const scopeKey = catalog.scopeKey;
 
   const crashedBundleIds = getCrashHistory();
-  const active = getActiveUpdateState().activeSelection;
+  const activeState = getActiveUpdateState();
+  const active = activeState.activeSelection;
   const explicitScopeSwitch =
     input.explicitChannel !== undefined &&
     input.explicitChannel !== input.currentChannel;
@@ -265,7 +271,7 @@ async function checkForReleaseCatalogUpdate(input: {
       scopeKey,
     })
   ) {
-    throw new HotUpdaterError(
+    throw new InvalidUpdateResponseError(
       "Rejected a stale or inconsistent Release catalog",
     );
   }
@@ -329,7 +335,20 @@ async function checkForReleaseCatalogUpdate(input: {
     scopeKey,
     selectionContextHash,
   };
-  const updateBundleForSelection = async (): Promise<boolean> => {
+  const fromReleaseId =
+    active?.bundleId === input.currentBundleId
+      ? active.releaseId
+      : activeState.stableSelection?.bundleId === input.currentBundleId
+        ? activeState.stableSelection.releaseId
+        : null;
+  const errorScope = {
+    bundleId: input.currentBundleId,
+    channel: input.targetChannel,
+    targetBundleId: desired.bundleId,
+    targetReleaseId: desired.releaseId,
+    updateStrategy: options.updateStrategy,
+  };
+  const installSelection = async (): Promise<boolean> => {
     resetProgress();
     if (!isReleaseSelectionCurrent(guard)) {
       throw new StaleReleaseCatalogError();
@@ -340,19 +359,14 @@ async function checkForReleaseCatalogUpdate(input: {
         guard,
         selection: receipt,
       });
-      if (committed && transitionKind === "ADOPT_RELEASE" && options.insights) {
-        await notifyReleaseAdoption({
-          active,
-          appVersion: input.currentAppVersion,
-          cohort: input.cohort,
-          desired: receipt,
-          fingerprintHash: input.fingerprintHash,
-          platform: input.platform,
-          requestHeaders: options.requestHeaders,
-          requestTimeout: options.requestTimeout,
-          session,
-          updateStrategy: options.updateStrategy,
-        });
+      if (committed && transitionKind === "ADOPT_RELEASE") {
+        emitAfterAppReady("onUpdateCheck", () => ({
+          status: "UNCHANGED",
+          channel: receipt.channel,
+          bundleId: receipt.bundleId,
+          releaseId: receipt.releaseId,
+          previousReleaseId: active?.releaseId ?? null,
+        }));
       }
       return committed;
     }
@@ -366,33 +380,64 @@ async function checkForReleaseCatalogUpdate(input: {
     if (!isReleaseSelectionCurrent(guard)) {
       throw new StaleReleaseCatalogError();
     }
-    return updateBundle({
+    const delivery = await stageBundle({
+      assets: artifact.assets,
       bundleId: desired.bundleId,
-      changedAssets: artifact.changedAssets ?? null,
       channel: input.targetChannel,
-      fileHash: artifact.fileHash,
-      fileUrl: artifact.fileUrl,
-      manifestFileHash: artifact.manifestFileHash ?? null,
-      manifestUrl: artifact.manifestUrl ?? null,
+      manifestFileHash: artifact.manifestFileHash,
+      manifestUrl: artifact.manifestUrl,
+      ...(artifact.archiveUrl ? { archiveUrl: artifact.archiveUrl } : {}),
       selection: receipt,
       shouldSkipCurrentBundleIdCheck: true,
       status: desired.status,
     });
+    if (delivery !== null && desired.bundleId !== input.currentBundleId) {
+      emitAfterAppReady("onBundleDownloaded", () => ({
+        channel: input.targetChannel,
+        fromBundleId: input.currentBundleId,
+        fromReleaseId,
+        toBundleId: desired.bundleId,
+        toReleaseId: desired.releaseId,
+        updateStrategy: options.updateStrategy,
+        ...delivery,
+      }));
+    }
+    return true;
+  };
+  const updateBundleForSelection = async (): Promise<boolean> => {
+    try {
+      return await installSelection();
+    } catch (error) {
+      reportUpdateError(error, "download", "artifact", errorScope);
+      throw error;
+    }
   };
 
+  const shouldForceUpdate =
+    transitionKind === "ADOPT_RELEASE"
+      ? false
+      : desired.status === "ROLLBACK"
+        ? true
+        : (release?.shouldForceUpdate ?? false);
+  emitAfterAppReady("onUpdateCheck", () => ({
+    status: "UPDATE_AVAILABLE",
+    channel: input.targetChannel,
+    fromBundleId: input.currentBundleId,
+    fromReleaseId,
+    toBundleId: desired.bundleId,
+    toReleaseId: desired.releaseId,
+    transitionKind,
+    updateStatus: desired.status,
+    shouldForceUpdate,
+    updateStrategy: options.updateStrategy,
+  }));
+
   return {
-    fileHash: null,
-    fileUrl: null,
-    id: desired.bundleId,
+    id: desired.releaseId ?? desired.bundleId,
     message: release?.message ?? null,
     releaseId: desired.releaseId,
     rolloutCohortCount: release?.rolloutCohortCount ?? 1000,
-    shouldForceUpdate:
-      transitionKind === "ADOPT_RELEASE"
-        ? false
-        : desired.status === "ROLLBACK"
-          ? true
-          : (release?.shouldForceUpdate ?? false),
+    shouldForceUpdate,
     status: desired.status,
     targetCohorts: release?.targetCohorts ? [...release.targetCohorts] : [],
     transitionKind,
@@ -441,7 +486,7 @@ export async function checkForUpdate(
   const fingerprintHash = getFingerprintHash();
 
   try {
-    return await checkForReleaseCatalogUpdate({
+    const result = await checkForReleaseCatalogUpdate({
       cohort,
       currentAppVersion,
       currentBundleId,
@@ -455,7 +500,25 @@ export async function checkForUpdate(
       platform,
       targetChannel,
     });
+    if (result === null) {
+      emitAfterAppReady("onUpdateCheck", () => {
+        const releaseId = getRunningReleaseId(currentBundleId, currentChannel);
+        return {
+          status: "UNCHANGED",
+          channel: currentChannel,
+          bundleId: currentBundleId,
+          releaseId,
+          previousReleaseId: releaseId,
+        };
+      });
+    }
+    return result;
   } catch (error) {
+    reportUpdateError(error, "check", "catalog", {
+      bundleId: currentBundleId,
+      channel: targetChannel,
+      updateStrategy: options.updateStrategy,
+    });
     options.onError?.(error as Error);
     return null;
   }

package/src/clientPlugin.ts

@@ -0,0 +1,17 @@
+export {
+  defineClientPlugin,
+  type AppReadyResult,
+  type BundleDownloadedInfo,
+  type HotUpdaterClientContext,
+  type HotUpdaterClientHooks,
+  type HotUpdaterClientPlugin,
+  type HotUpdaterClientStorage,
+  type ReleaseTransitionKind,
+  type UpdateCheckResult,
+  type UpdateError,
+  type UpdateErrorReason,
+  type UpdateErrorResource,
+  type UpdateErrorStage,
+  type UpdateErrorTransport,
+  type UpdateStrategy,
+} from "@hot-updater/protocol";

package/src/error.ts

@@ -7,7 +7,7 @@
  *
  * Error Classification:
  * - Parameter Validation: Invalid or missing function parameters
- * - Bundle Storage: Errors during download, extraction, and storage
+ * - Bundle Storage: Errors during download, verification, and storage
  * - Signature Verification: Cryptographic verification failures (collapsed to a single public code)
  * - Internal: Platform-specific or unexpected errors
  *
@@ -27,8 +27,7 @@ export enum HotUpdaterErrorCode {
   MISSING_BUNDLE_ID = "MISSING_BUNDLE_ID",
 
   /**
-   * File URL is invalid or malformed.
-   * Thrown when fileUrl parameter cannot be parsed as a valid URL.
+   * Manifest or asset URL is invalid or malformed.
    * @retryable false
    */
   INVALID_FILE_URL = "INVALID_FILE_URL",
@@ -58,25 +57,16 @@ export enum HotUpdaterErrorCode {
    */
   INCOMPLETE_DOWNLOAD = "INCOMPLETE_DOWNLOAD",
 
-  /**
-   * Bundle archive format is invalid or corrupted.
-   * Thrown when ZIP file has wrong magic bytes, invalid structure, or unsupported format.
-   * Also thrown for path traversal attempts during extraction.
-   * @retryable false - Indicates corrupted or malicious bundle
-   */
-  EXTRACTION_FORMAT_ERROR = "EXTRACTION_FORMAT_ERROR",
-
   /**
    * Bundle missing required platform files.
-   * Thrown when extracted bundle doesn't contain index.android.bundle (Android)
+   * Thrown when the staged bundle doesn't contain index.android.bundle (Android)
    * or main.jsbundle (iOS).
    * @retryable false - Indicates incorrectly built bundle
    */
   INVALID_BUNDLE = "INVALID_BUNDLE",
 
   /**
-   * Insufficient disk space for bundle download and extraction.
-   * Thrown when available disk space is less than required (file size * 2).
+   * Insufficient disk space for bundle staging.
    * Error message includes required and available bytes.
    * @retryable false - User must free up disk space
    */

package/src/fetchJSON.ts

@@ -1,3 +1,7 @@
+import { UpdateHttpError } from "./updateError";
+
+export class FetchJSONResponseError extends UpdateHttpError {}
+
 export const fetchJSON = async <T>({
   url,
   requestHeaders,
@@ -19,7 +23,7 @@ export const fetchJSON = async <T>({
       signal: controller.signal,
     });
     if (response.status !== 200) {
-      throw new Error(response.statusText);
+      throw new FetchJSONResponseError(response.status, response.statusText);
     }
     return (await response.json()) as T;
   } catch (error: unknown) {