@hot-updater/react-native 1.0.0-rc.4 → 1.0.0-rc.41

package/src/checkForUpdate.ts

@@ -1,17 +1,24 @@
 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 { getRunningReleaseId, type LaunchReporter } 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,26 +29,22 @@ 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 {
   /**
    * Update strategy
    * - "fingerprint": Use fingerprint hash to check for updates
    * - "appVersion": Use app version to check for updates
-   * - Can override the strategy set in HotUpdater.wrap()
    */
   updateStrategy: "appVersion" | "fingerprint";
 
@@ -60,7 +63,7 @@ export interface CheckForUpdateOptions {
   requestTimeout?: number;
 }
 
-export type CheckForUpdateResult = ArtifactInfo & {
+export type CheckForUpdateResult = {
   readonly id: string;
   readonly message: string | null;
   readonly rolloutCohortCount: number;
@@ -71,20 +74,15 @@ export type CheckForUpdateResult = ArtifactInfo & {
   readonly transitionKind?: ReleaseTransitionKind;
   /**
    * Updates the bundle.
-   * This method is equivalent to `HotUpdater.updateBundle()` but with all required arguments pre-filled.
+   * This method is equivalent to `hotUpdater.updateBundle()` but with all required arguments pre-filled.
    */
   updateBundle: () => Promise<boolean>;
 };
 
-export type ReleaseTransitionKind =
-  | "INSTALL"
-  | "ADOPT_RELEASE"
-  | "USE_EMBEDDED"
-  | "USE_BUILTIN";
-
 export interface InternalCheckForUpdateOptions extends CheckForUpdateOptions {
-  insights?: boolean;
   client: HotUpdaterHttpClient;
+  /** Calls the checking instance's plugin hooks. */
+  emit: LaunchReporter["emit"];
 }
 
 const sameReceipt = (
@@ -113,7 +111,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,47 +119,49 @@ const resetProgress = () => {
   hotUpdaterStore.setState({
     artifactType: null,
     details: null,
-    downloadedBytes: undefined,
     isUpdateDownloaded: false,
     progress: 0,
-    totalBytes: undefined,
   });
 };
 
-const notifyUnchangedSelection = 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;
-}): 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: null,
-      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: "UNCHANGED",
-      updateStrategy: null,
-      ...(userId === undefined ? {} : { userId }),
-      ...(username === undefined ? {} : { username }),
-    });
-  } catch (error) {
-    console.warn("[HotUpdater] Unchanged selection 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 = (
+  emit: LaunchReporter["emit"],
+  error: unknown,
+  stage: UpdateErrorStage,
+  resource: UpdateErrorResource | undefined,
+  scope: UpdateErrorScope,
+): void => {
+  emit("onUpdateError", () => {
+    const classification = classifyUpdateError(error, stage, resource);
+    if (classification === null) return null;
+    return {
+      ...classification,
+      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: {
@@ -212,12 +212,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;
@@ -264,7 +267,7 @@ async function checkForReleaseCatalogUpdate(input: {
       scopeKey,
     })
   ) {
-    throw new HotUpdaterError(
+    throw new InvalidUpdateResponseError(
       "Rejected a stale or inconsistent Release catalog",
     );
   }
@@ -328,7 +331,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();
@@ -339,18 +355,14 @@ async function checkForReleaseCatalogUpdate(input: {
         guard,
         selection: receipt,
       });
-      if (committed && transitionKind === "ADOPT_RELEASE" && options.insights) {
-        await notifyUnchangedSelection({
-          active,
-          appVersion: input.currentAppVersion,
-          cohort: input.cohort,
-          desired: receipt,
-          fingerprintHash: input.fingerprintHash,
-          platform: input.platform,
-          requestHeaders: options.requestHeaders,
-          requestTimeout: options.requestTimeout,
-          session,
-        });
+      if (committed && transitionKind === "ADOPT_RELEASE") {
+        options.emit("onUpdateCheck", () => ({
+          status: "UNCHANGED",
+          channel: receipt.channel,
+          bundleId: receipt.bundleId,
+          releaseId: receipt.releaseId,
+          previousReleaseId: active?.releaseId ?? null,
+        }));
       }
       return committed;
     }
@@ -364,33 +376,70 @@ 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) {
+      options.emit("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(
+        options.emit,
+        error,
+        "download",
+        "artifact",
+        errorScope,
+      );
+      throw error;
+    }
   };
 
+  const shouldForceUpdate =
+    transitionKind === "ADOPT_RELEASE"
+      ? false
+      : desired.status === "ROLLBACK"
+        ? true
+        : (release?.shouldForceUpdate ?? false);
+  options.emit("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.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,
@@ -430,7 +479,7 @@ export async function checkForUpdate(
 
   if (isSwitched && explicitChannel && explicitChannel !== currentChannel) {
     const error = new HotUpdaterError(
-      `Runtime channel is already switched to "${currentChannel}". Call HotUpdater.resetChannel() before checking "${explicitChannel}".`,
+      `Runtime channel is already switched to "${currentChannel}". Call hotUpdater.resetChannel() before checking "${explicitChannel}".`,
     );
     options.onError?.(error);
     throw error;
@@ -439,7 +488,7 @@ export async function checkForUpdate(
   const fingerprintHash = getFingerprintHash();
 
   try {
-    return await checkForReleaseCatalogUpdate({
+    const result = await checkForReleaseCatalogUpdate({
       cohort,
       currentAppVersion,
       currentBundleId,
@@ -453,7 +502,25 @@ export async function checkForUpdate(
       platform,
       targetChannel,
     });
+    if (result === null) {
+      options.emit("onUpdateCheck", () => {
+        const releaseId = getRunningReleaseId(currentBundleId, currentChannel);
+        return {
+          status: "UNCHANGED",
+          channel: currentChannel,
+          bundleId: currentBundleId,
+          releaseId,
+          previousReleaseId: releaseId,
+        };
+      });
+    }
+    return result;
   } catch (error) {
+    reportUpdateError(options.emit, error, "check", "catalog", {
+      bundleId: currentBundleId,
+      channel: targetChannel,
+      updateStrategy: options.updateStrategy,
+    });
     options.onError?.(error as Error);
     return null;
   }

package/src/clientPlugin.ts

@@ -0,0 +1,21 @@
+export {
+  defineClientPlugin,
+  type AppReadyResult,
+  type BundleDownloadedInfo,
+  type ClientPluginApi,
+  type ClientPluginApis,
+  type HotUpdaterClientContext,
+  type HotUpdaterClientHooks,
+  type HotUpdaterClientPlugin,
+  type HotUpdaterClientSetup,
+  type HotUpdaterClientStorage,
+  type ReleaseTransitionKind,
+  type UpdateCheckResult,
+  type UpdateError,
+  type UpdateErrorReason,
+  type UpdateErrorResource,
+  type UpdateErrorStage,
+  type UpdateErrorTransport,
+  type UpdateHttpResponse,
+  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
    */
@@ -102,7 +92,7 @@ export enum HotUpdaterErrorCode {
   /**
    * Bundle is in crashed history and cannot be applied.
    * Thrown when attempting to install a bundle that previously caused a crash.
-   * Use HotUpdater.clearCrashHistory() to allow retrying this bundle.
+   * Use hotUpdater.clearCrashHistory() to allow retrying this bundle.
    * @retryable false - Bundle was marked as crashed for safety
    */
   BUNDLE_IN_CRASHED_HISTORY = "BUNDLE_IN_CRASHED_HISTORY",

package/src/fetchJSON.ts

@@ -1,33 +1,17 @@
-export const fetchJSON = async <T>({
-  url,
-  requestHeaders,
-  requestTimeout = 5000,
-}: {
-  url: string;
-  requestHeaders?: Record<string, string>;
-  requestTimeout?: number;
-}): Promise<T> => {
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), requestTimeout);
+import { fetchUpdateResponse, type UpdateRequest } from "./fetchUpdateResponse";
+import { UpdateHttpError } from "./updateError";
 
-  try {
-    const response = await fetch(url, {
-      headers: {
-        Accept: "application/json",
-        ...requestHeaders,
-      },
-      signal: controller.signal,
-    });
-    if (response.status !== 200) {
-      throw new Error(response.statusText);
-    }
-    return (await response.json()) as T;
-  } catch (error: unknown) {
-    if (error instanceof Error && error.name === "AbortError") {
-      throw new Error("Request timed out");
-    }
-    throw error;
-  } finally {
-    clearTimeout(timeoutId);
+export class FetchJSONResponseError extends UpdateHttpError {}
+
+export const fetchJSON = async <T>(
+  input: Omit<UpdateRequest, "resource">,
+): Promise<T> => {
+  const { response, body } = await fetchUpdateResponse({
+    ...input,
+    resource: "artifact",
+  });
+  if (response.status !== 200) {
+    throw new FetchJSONResponseError(response.status, response.statusText);
   }
+  return JSON.parse(body!) as T;
 };

package/src/fetchUpdateResponse.ts

@@ -0,0 +1,60 @@
+import type { UpdateHttpResponse } from "@hot-updater/protocol";
+
+export interface UpdateRequest {
+  readonly url: string;
+  readonly resource: UpdateHttpResponse["resource"];
+  readonly requestHeaders?: Record<string, string>;
+  readonly requestTimeout?: number;
+  readonly onResponse?: (response: UpdateHttpResponse) => void;
+}
+
+/** Read once for parsing and diagnostics, under the same request timeout. */
+export const fetchUpdateResponse = async ({
+  url,
+  resource,
+  requestHeaders,
+  requestTimeout = 5000,
+  onResponse,
+}: UpdateRequest): Promise<{ response: Response; body: string | null }> => {
+  const controller = new AbortController();
+  let timedOut = false;
+  const timeoutId = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, requestTimeout);
+  try {
+    const headers = new Headers(requestHeaders);
+    if (!headers.has("Accept")) headers.set("Accept", "application/json");
+    const response = await fetch(url, {
+      headers,
+      signal: controller.signal,
+    });
+    let body: string | null = null;
+    try {
+      body = await response.text();
+    } catch (error) {
+      // A broken error body must not hide an HTTP error already received.
+      if (response.status === 200) throw error;
+    } finally {
+      onResponse?.({
+        resource,
+        // React Native URL implementations do not all expose pathname.
+        path:
+          url.replace(/^https?:\/\/[^/?#]*/i, "").split(/[?#]/, 1)[0] || "/",
+        status: response.status,
+        body,
+        bodyTruncated: false,
+      });
+    }
+    return { response, body };
+  } catch (error: unknown) {
+    // Whatever the fetch rejects with once its timeout aborts it: an
+    // AbortError, or Expo's "fetch failed: FetchRequestCanceledException".
+    if (timedOut || (error instanceof Error && error.name === "AbortError")) {
+      throw new Error("Request timed out");
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+};