@hot-updater/react-native 1.0.0-rc.3 → 1.0.0-rc.31

package/src/appReady.ts

@@ -0,0 +1,149 @@
+import type { AppReadyResult } from "./clientPlugin";
+import type { HotUpdaterError } from "./error";
+import {
+  getActiveUpdateState,
+  getBundleId,
+  getChannel,
+  type LaunchTransition,
+  type NotifyAppReadyResult,
+  readNotifyAppReady,
+} from "./native";
+import {
+  buildPluginEvent,
+  dispatchPluginHook,
+  emitPluginHook,
+} from "./pluginHost";
+
+export type NotifyAppReadyOptions = {
+  onNotifyAppReady?: (result: NotifyAppReadyResult) => void;
+  onError?: (error: HotUpdaterError | Error | unknown) => void;
+};
+
+type RequestAnimationFrame = (callback: (timestamp: number) => void) => number;
+
+let didEmitAppReady = false;
+/** Settles once this runtime's launch was read, whether it was reported or failed. */
+let appReadyRead: Promise<unknown> | null = null;
+/** Why the previous main process exited, read with this runtime's launch. */
+let previousProcessExit: string | null = null;
+
+/** Android 11+: why the app's previous main process exited, once the launch was read. */
+export const getPreviousProcessExit = (): string | null => previousProcessExit;
+
+const waitForNextFrame = () =>
+  new Promise<void>((resolve) => {
+    const requestAnimationFrame = (
+      globalThis as typeof globalThis & {
+        requestAnimationFrame?: RequestAnimationFrame;
+      }
+    )?.requestAnimationFrame;
+
+    if (requestAnimationFrame) {
+      requestAnimationFrame(() => resolve());
+      return;
+    }
+
+    void Promise.resolve().then(resolve);
+  });
+
+/**
+ * The Release the running bundle was selected as: the active or stable
+ * selection that names it on the current channel.
+ */
+export const getRunningReleaseId = (
+  bundleId: string,
+  channel: string,
+): string | null => {
+  const state = getActiveUpdateState();
+  return (
+    [state.activeSelection, state.stableSelection].find(
+      (selection) =>
+        selection?.bundleId === bundleId && selection.channel === channel,
+    )?.releaseId ?? null
+  );
+};
+
+const toAppReadyResult = (
+  result: NotifyAppReadyResult,
+  transition: LaunchTransition | null,
+): AppReadyResult | null => {
+  const channel = getChannel();
+  if (result.status === "UNCHANGED") {
+    const bundleId = getBundleId();
+    return {
+      status: "UNCHANGED",
+      channel,
+      bundleId,
+      releaseId: getRunningReleaseId(bundleId, channel),
+      previousProcessExit,
+    };
+  }
+  // Native persists the transition with every applied or recovered launch;
+  // a report without it cannot say what moved.
+  if (transition === null) return null;
+  return {
+    status: transition.type,
+    channel,
+    fromBundleId: transition.fromBundleId,
+    fromReleaseId: transition.fromReleaseId,
+    toBundleId: transition.toBundleId,
+    toReleaseId: transition.toReleaseId,
+    updateStrategy: transition.updateStrategy,
+    previousProcessExit,
+  };
+};
+
+const notifyAppReady = async (
+  options: NotifyAppReadyOptions,
+): Promise<NotifyAppReadyResult | undefined> => {
+  try {
+    let nativeReadResult: ReturnType<typeof readNotifyAppReady>;
+    do {
+      await waitForNextFrame();
+      nativeReadResult = readNotifyAppReady();
+    } while (nativeReadResult.pending);
+
+    const { result, transition } = nativeReadResult;
+    previousProcessExit = nativeReadResult.previousProcessExit;
+    if (!didEmitAppReady) {
+      didEmitAppReady = true;
+      emitPluginHook("onAppReady", () => toAppReadyResult(result, transition));
+    }
+
+    options.onNotifyAppReady?.(result);
+    return result;
+  } catch (error) {
+    const normalizedError =
+      error instanceof Error ? error : new Error(String(error));
+    options.onError?.(error);
+    console.warn("[HotUpdater] Failed to notify app ready:", normalizedError);
+    return undefined;
+  }
+};
+
+/** Reads this runtime's launch once native finalizes it and reports it to plugins. */
+export const handleNotifyAppReady = (
+  options: NotifyAppReadyOptions,
+): Promise<NotifyAppReadyResult | undefined> => {
+  const readiness = notifyAppReady(options);
+  appReadyRead ??= readiness;
+  return readiness;
+};
+
+/**
+ * Calls a plugin hook after this runtime's `onAppReady`, so plugins see the
+ * launch before anything that followed it. The event is built now, from the
+ * state it describes, and only when a plugin listens.
+ */
+export const emitAfterAppReady: typeof emitPluginHook = (
+  name,
+  createPayload,
+) => {
+  const payload = buildPluginEvent(name, createPayload);
+  if (payload === null) return;
+  if (appReadyRead === null) {
+    dispatchPluginHook(name, payload);
+    return;
+  }
+  void appReadyRead.then(() => dispatchPluginHook(name, payload));
+};

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.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,18 @@
+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 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
    */

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,54 @@
+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();
+  const timeoutId = setTimeout(() => 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) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error("Request timed out");
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+};