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

package/src/specs/NativeHotUpdater.ts

@@ -2,48 +2,21 @@ import type { TurboModule } from "react-native";
 import { TurboModuleRegistry } from "react-native";
 import type { UnsafeObject } from "react-native/Libraries/Types/CodegenTypes";
 
-export interface ChangedAsset {
-  file?: {
-    compression?: "br" | null;
-    url: string;
-  } | null;
-  fileHash: string;
-  patch?: {
-    algorithm: "bsdiff";
-    baseBundleId: string;
-    baseFileHash: string;
-    patchFileHash: string;
-    patchUrl: string;
-  } | null;
-}
-
 export interface UpdateBundleParams {
   bundleId: string;
   channel?: string;
-  fileUrl: string | null;
   /**
-   * File hash for integrity/signature verification.
-   *
-   * Format depends on signing configuration:
-   * - Signed: `sig:<base64_signature>` - Native will verify signature (and implicitly hash)
-   * - Unsigned: `<hex_hash>` - Native will verify SHA256 hash only
-   *
-   * Native determines verification mode by checking for "sig:" prefix.
+   * Signed manifest URL for installation.
    */
-  fileHash: string | null;
-  /**
-   * Optional signed manifest URL for manifest-driven installation.
-   */
-  manifestUrl?: string | null;
+  manifestUrl: string;
   /**
    * File hash/signature for the manifest file itself.
    */
-  manifestFileHash?: string | null;
-  /**
-   * Per-file URLs for assets that must be downloaded instead of reused from
-   * the currently active bundle.
-   */
-  changedAssets?: UnsafeObject | null;
+  manifestFileHash: string;
+  /** Optional tar.br URL; integrity and sizes come from the verified manifest. */
+  archiveUrl?: string | null;
+  /** Full protocol v1 target file descriptor map. */
+  assets: UnsafeObject;
   /** Full Release Catalog selection receipt committed with the staged Bundle. */
   selection?: UnsafeObject | null;
 }
@@ -61,18 +34,21 @@ export interface Spec extends TurboModule {
    * Downloads and applies a bundle update.
    *
    * @param params - Update bundle parameters
-   * @returns Promise that resolves to true if successful
+   * @returns Promise that resolves, once the bundle is staged, to how it
+   *   arrived: `{ delivery, patchFallback }`. `delivery` is "patch" when a
+   *   bsdiff patch produced a file, "manifest" when only changed files were
+   *   downloaded, or "archive" for the full archive; `patchFallback` is true
+   *   when a patch was tried but the file or archive was downloaded instead.
    * @throws {HotUpdaterErrorCode} Rejects with one of the following error codes:
    *
    *   Parameter validation:
    *   - MISSING_BUNDLE_ID: Missing or empty bundleId
-   *   - INVALID_FILE_URL: Invalid fileUrl provided
+   *   - INVALID_FILE_URL: Invalid manifest or asset URL provided
    *
    *   Bundle storage:
    *   - DIRECTORY_CREATION_FAILED: Failed to create bundle directory
    *   - DOWNLOAD_FAILED: Failed to download bundle
    *   - INCOMPLETE_DOWNLOAD: Download incomplete (size mismatch)
-   *   - EXTRACTION_FORMAT_ERROR: Invalid or corrupted archive format
    *   - INVALID_BUNDLE: Bundle missing required platform files
    *   - INSUFFICIENT_DISK_SPACE: Insufficient disk space
    *   - MOVE_OPERATION_FAILED: Failed to move bundle files
@@ -87,8 +63,20 @@ export interface Spec extends TurboModule {
    *
    *   Note: iOS normalizes rare signature/storage errors to SIGNATURE_VERIFICATION_FAILED
    *   or UNKNOWN_ERROR to keep the JS error surface small.
+   *
+   *   A rejection from the download or install also carries `userInfo`
+   *   `{ stage, reason, resource?, httpStatus?, transport?, originCode? }`:
+   *   `stage` is "download" (transfer and verification) or "install" (patch,
+   *   extract, move into place); `reason` is one of "network", "http",
+   *   "invalid_response", "hash_mismatch", "signature", "patch", "extract",
+   *   "storage", or "unknown"; `resource` is what was being fetched or
+   *   applied: "manifest", "file", "patch", or "archive". `httpStatus` is
+   *   present when `reason` is "http", with `originCode`, the storage
+   *   origin's XML error `<Code>` when the body names one. `transport` is
+   *   present when no response arrived: "timeout", "dns", "tls",
+   *   "connection", "offline", or "cancelled".
    */
-  updateBundle(params: UpdateBundleParams): Promise<boolean>;
+  updateBundle(params: UpdateBundleParams): Promise<UnsafeObject>;
 
   /** Accepts and durably advances the catalog high-water for a scope. */
   acceptReleaseCatalog(params: UnsafeObject): boolean;
@@ -192,24 +180,22 @@ export interface Spec extends TurboModule {
   getCohort: () => string;
 
   /**
-   * Gets the persisted install id for this app installation.
+   * Gets the install id: a random id native creates once per app
+   * installation and keeps out of device backups.
    */
   getInstallId: () => string;
 
   /**
-   * Gets the persisted nullable user id associated with this installation.
-   */
-  getUserId: () => string | null;
-
-  /**
-   * Gets the persisted nullable username associated with this installation.
+   * Reads a value from the SDK's persistent key-value store, which native
+   * keeps out of device backups. Returns null when the key has no value.
    */
-  getUsername: () => string | null;
+  getStorageItem: (key: string) => string | null;
 
   /**
-   * Persists nullable user identity fields associated with this installation.
+   * Writes a value to the SDK's persistent key-value store; null removes the
+   * key.
    */
-  setUser: (userId: string | null, username: string | null) => void;
+  setStorageItem: (key: string, value: string | null) => void;
 
   // EventEmitter
   addListener(eventName: string): void;

package/src/store.ts

@@ -9,10 +9,8 @@ import { addListener } from "./native";
 
 export type HotUpdaterState = {
   progress: number;
-  downloadedBytes: number | undefined;
-  totalBytes: number | undefined;
   isUpdateDownloaded: boolean;
-  artifactType: "archive" | "diff" | null;
+  artifactType: "diff" | null;
   details: HotUpdaterDiffProgressDetails | null;
 };
 
@@ -56,8 +54,6 @@ const areDiffDetailsEqual = (
 const areStatesEqual = (left: HotUpdaterState, right: HotUpdaterState) => {
   return (
     left.progress === right.progress &&
-    left.downloadedBytes === right.downloadedBytes &&
-    left.totalBytes === right.totalBytes &&
     left.isUpdateDownloaded === right.isUpdateDownloaded &&
     left.artifactType === right.artifactType &&
     areDiffDetailsEqual(left.details, right.details)
@@ -78,8 +74,6 @@ const normalizeDownloadPath = (value: string | undefined) => {
 const createHotUpdaterStore = () => {
   let state: HotUpdaterState = {
     progress: 0,
-    downloadedBytes: undefined,
-    totalBytes: undefined,
     isUpdateDownloaded: false,
     artifactType: null,
     details: null,
@@ -165,10 +159,6 @@ const createHotUpdaterStore = () => {
       nextState.details = state.details;
     }
 
-    if (nextState.artifactType !== "diff") {
-      nextState.details = null;
-    }
-
     if (areStatesEqual(state, nextState)) {
       return;
     }
@@ -180,19 +170,8 @@ const createHotUpdaterStore = () => {
   const applyProgressEvent = (event: HotUpdaterProgressEvent) => {
     setState({
       artifactType: event.artifactType,
-      details:
-        event.artifactType === "diff"
-          ? normalizeDiffDetails(event.details)
-          : null,
-      downloadedBytes:
-        event.artifactType === "archive"
-          ? normalizeByteCount(event.downloadedBytes)
-          : undefined,
+      details: normalizeDiffDetails(event.details),
       progress: event.progress,
-      totalBytes:
-        event.artifactType === "archive"
-          ? normalizeByteCount(event.totalBytes)
-          : undefined,
     });
   };
 

package/src/types.ts

@@ -1,4 +1,4 @@
-export type HotUpdaterBaseURL = string | (() => string | Promise<string>);
+export type { HotUpdaterBaseURL } from "@hot-updater/protocol";
 
 /**
  * Information about a signature verification failure.

package/src/updateError.ts

@@ -0,0 +1,167 @@
+import type {
+  UpdateError,
+  UpdateErrorReason,
+  UpdateErrorResource,
+  UpdateErrorStage,
+  UpdateErrorTransport,
+} from "./clientPlugin";
+import { HotUpdaterError } from "./error";
+
+/**
+ * A response the SDK cannot use: a malformed or stale catalog, an artifact
+ * in another protocol, or an invalid URL.
+ */
+export class InvalidUpdateResponseError extends HotUpdaterError {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message);
+    this.name = "InvalidUpdateResponseError";
+    if (options?.cause !== undefined) this.cause = options.cause;
+  }
+}
+
+/** A request the server answered with a status the SDK does not accept. */
+export class UpdateHttpError extends HotUpdaterError {
+  constructor(
+    readonly status: number,
+    statusText: string,
+  ) {
+    super(
+      `Request failed with HTTP ${status}${statusText ? ` ${statusText}` : ""}`,
+    );
+    this.name = "UpdateHttpError";
+  }
+}
+
+const STAGES: readonly UpdateErrorStage[] = ["check", "download", "install"];
+const REASONS: readonly UpdateErrorReason[] = [
+  "network",
+  "http",
+  "invalid_response",
+  "hash_mismatch",
+  "signature",
+  "patch",
+  "extract",
+  "storage",
+  "unknown",
+];
+const RESOURCES: readonly UpdateErrorResource[] = [
+  "catalog",
+  "artifact",
+  "manifest",
+  "file",
+  "patch",
+  "archive",
+];
+const TRANSPORTS: readonly UpdateErrorTransport[] = [
+  "timeout",
+  "dns",
+  "tls",
+  "connection",
+  "offline",
+  "cancelled",
+];
+/** An S3, R2, or GCS error code: letters, digits, and punctuation only. */
+const ORIGIN_CODE = /^[A-Za-z0-9._-]{1,64}$/;
+/** Expo's iOS and Android names for a fetch canceled before its response. */
+const EXPO_FETCH_CANCELED =
+  /FetchRequestCanceledException|Fetch request has been canceled|The operation was aborted/;
+
+type Classification = Pick<
+  UpdateError,
+  "stage" | "reason" | "resource" | "httpStatus" | "originCode" | "transport"
+>;
+
+const oneOf = <T extends string>(
+  values: readonly T[],
+  value: unknown,
+): value is T => values.includes(value as T);
+
+const readNativeClassification = (
+  error: object,
+): Classification | null | undefined => {
+  if (!("code" in error) || typeof error.code !== "string") return undefined;
+  const userInfo =
+    "userInfo" in error && typeof error.userInfo === "object"
+      ? (error.userInfo as Record<string, unknown> | null)
+      : null;
+  const { stage, reason, resource, transport, originCode } = userInfo ?? {};
+  // Native classifies every failure of its download and install; a rejection
+  // without it, such as a stale selection, is not an update failure.
+  if (!oneOf(STAGES, stage) || !oneOf(REASONS, reason)) return null;
+  const httpStatus = Number(userInfo?.httpStatus);
+  return {
+    stage,
+    reason,
+    ...(oneOf(RESOURCES, resource) ? { resource } : {}),
+    ...(reason === "http" && Number.isSafeInteger(httpStatus)
+      ? { httpStatus }
+      : {}),
+    ...(reason === "http" &&
+    typeof originCode === "string" &&
+    ORIGIN_CODE.test(originCode)
+      ? { originCode }
+      : {}),
+    ...(reason === "network" && oneOf(TRANSPORTS, transport)
+      ? { transport }
+      : {}),
+  };
+};
+
+/**
+ * Where and why an update failed, or null when the error is not an update
+ * failure. Native rejections carry their own classification; an error the
+ * SDK's JavaScript raised happened in `stage`, fetching `resource` when one
+ * is given.
+ */
+export const classifyUpdateError = (
+  error: unknown,
+  stage: UpdateErrorStage,
+  resource?: UpdateErrorResource,
+): Classification | null => {
+  if (typeof error === "object" && error !== null) {
+    const native = readNativeClassification(error);
+    if (native !== undefined) return native;
+  }
+  const scope = {
+    stage,
+    ...(resource === undefined ? {} : { resource }),
+  };
+  // Names, not classes, so an error from another copy of a module still
+  // classifies, as it does across test module resets.
+  const name = error instanceof Error ? error.name : null;
+  // A selection that became stale is a race between checks, not a failure.
+  if (name === "StaleReleaseCatalogError") return null;
+  if (name === "UpdateHttpError") {
+    return {
+      ...scope,
+      reason: "http",
+      httpStatus: (error as UpdateHttpError).status,
+    };
+  }
+  if (name === "InvalidUpdateResponseError" || name === "SyntaxError") {
+    return { ...scope, reason: "invalid_response" };
+  }
+  if (error instanceof Error && error.message === "Request timed out") {
+    return { ...scope, reason: "network", transport: "timeout" };
+  }
+  if (name === "AbortError") {
+    return { ...scope, reason: "network", transport: "cancelled" };
+  }
+  // Expo's fetch rejects with "fetch failed: <native exception>" when no
+  // response arrives, and names a canceled request.
+  if (error instanceof Error && error.message.startsWith("fetch failed:")) {
+    return {
+      ...scope,
+      reason: "network",
+      ...(EXPO_FETCH_CANCELED.test(error.message)
+        ? { transport: "cancelled" }
+        : {}),
+    };
+  }
+  if (name === "TypeError") {
+    // fetch rejects with a TypeError when no response arrives, without
+    // saying why.
+    return { ...scope, reason: "network" };
+  }
+  return { ...scope, reason: "unknown" };
+};

package/src/wrap.tsx

@@ -1,11 +1,12 @@
 import React, { useEffect, useState } from "react";
 
+import { handleNotifyAppReady } from "./appReady";
 import { checkForUpdate } from "./checkForUpdate";
 import { useEventCallback } from "./hooks/useEventCallback";
 import { getUpdateId, reload } from "./native";
-import { handleNotifyAppReady } from "./notifyAppReadyInsights";
 import { useHotUpdaterStore } from "./store";
 import type {
+  HotUpdaterFallbackComponentProps,
   InternalInitOptions,
   InternalWrapOptions,
   UpdateStatus,
@@ -32,11 +33,46 @@ export function wrap(
 ) => React.ComponentType<P> {
   const { reloadOnForceUpdate = true, ...restOptions } = options;
 
+  // Progress is subscribed only where it is rendered or reported, so progress
+  // events don't re-render the wrapped app.
+  const ProgressReporter = ({
+    onProgress,
+  }: {
+    onProgress: (progress: number) => void;
+  }) => {
+    const progress = useHotUpdaterStore((state) => state.progress);
+
+    useEffect(() => {
+      onProgress(progress);
+    }, [progress]);
+
+    return null;
+  };
+
+  const FallbackWithProgress = ({
+    Fallback,
+    status,
+    message,
+  }: {
+    Fallback: React.FC<HotUpdaterFallbackComponentProps>;
+    status: HotUpdaterFallbackComponentProps["status"];
+    message: string | null;
+  }) => {
+    const progressState = useHotUpdaterStore((state) => state);
+
+    return (
+      <Fallback
+        artifactType={progressState.artifactType}
+        details={progressState.details}
+        progress={progressState.progress}
+        status={status}
+        message={message}
+      />
+    );
+  };
+
   return <P extends object>(WrappedComponent: React.ComponentType<P>) => {
     const HotUpdaterHOC: React.FC<P> = (props: P) => {
-      const progressState = useHotUpdaterStore((state) => state);
-      const progress = progressState.progress;
-
       const [message, setMessage] = useState<string | null>(null);
       const [updateStatus, setUpdateStatus] =
         useState<UpdateStatus>("CHECK_FOR_UPDATE");
@@ -45,8 +81,8 @@ export function wrap(
         try {
           setUpdateStatus("CHECK_FOR_UPDATE");
 
+          const readiness = handleNotifyAppReady(restOptions);
           const updateInfo = await checkForUpdate({
-            insights: restOptions.insights,
             client: restOptions.client,
             updateStrategy: restOptions.updateStrategy,
             requestHeaders: restOptions.requestHeaders,
@@ -54,6 +90,7 @@ export function wrap(
             onError: restOptions.onError,
           });
 
+          await readiness;
           setMessage(updateInfo?.message ?? null);
 
           if (!updateInfo) {
@@ -111,39 +148,33 @@ export function wrap(
         }
       });
 
-      useEffect(() => {
-        restOptions.onProgress?.(progress);
-      }, [progress]);
-
-      // Read the native launch report after the first render commit.
-      useEffect(() => {
-        void handleNotifyAppReady(restOptions);
-      }, []);
-
       // Start update check
       useEffect(() => {
         initHotUpdater();
       }, []);
 
-      if (
+      const content =
         restOptions.fallbackComponent &&
-        updateStatus !== "UPDATE_PROCESS_COMPLETED"
-      ) {
-        const Fallback = restOptions.fallbackComponent;
-        return (
-          <Fallback
-            artifactType={progressState.artifactType}
-            details={progressState.details}
-            downloadedBytes={progressState.downloadedBytes}
-            progress={progress}
+        updateStatus !== "UPDATE_PROCESS_COMPLETED" ? (
+          <FallbackWithProgress
+            Fallback={restOptions.fallbackComponent}
             status={updateStatus}
             message={message}
-            totalBytes={progressState.totalBytes}
           />
+        ) : (
+          <WrappedComponent {...props} />
         );
+
+      if (!restOptions.onProgress) {
+        return content;
       }
 
-      return <WrappedComponent {...props} />;
+      return (
+        <>
+          {content}
+          <ProgressReporter onProgress={restOptions.onProgress} />
+        </>
+      );
     };
 
     return HotUpdaterHOC as React.ComponentType<P>;

package/src/wrap.types.ts

@@ -1,5 +1,6 @@
 import type React from "react";
 
+import type { HotUpdaterClientPlugin } from "./clientPlugin";
 import type { HotUpdaterError } from "./error";
 import type { HotUpdaterHttpClient } from "./httpClient";
 import type { NotifyAppReadyResult } from "./native";
@@ -21,8 +22,6 @@ export type UpdateStatus =
 export type HotUpdaterFallbackComponentProps = {
   status: Exclude<UpdateStatus, "UPDATE_PROCESS_COMPLETED">;
   progress: number;
-  downloadedBytes: HotUpdaterState["downloadedBytes"];
-  totalBytes: HotUpdaterState["totalBytes"];
   message: string | null;
   artifactType: HotUpdaterState["artifactType"];
   details: HotUpdaterState["details"];
@@ -30,11 +29,12 @@ export type HotUpdaterFallbackComponentProps = {
 
 interface CommonHotUpdaterOptions {
   /**
-   * Sends app-ready transitions and same-Bundle Release adoptions to the
-   * configured server. Defaults to `true`; set to `false` to disable client
-   * reporting.
+   * Client plugins, such as `insights()` from `@hot-updater/react-native`.
+   * Each plugin's `setup` runs
+   * once, and its hooks observe launches, update checks, downloads, and
+   * update failures. Plugin ids must be unique.
    */
-  insights?: boolean;
+  plugins?: readonly HotUpdaterClientPlugin[];
   /** Base URL of a server exposing the Hot Updater v1 client HTTP protocol. */
   baseURL: HotUpdaterBaseURL;
   requestHeaders?: Record<string, string>;
@@ -56,7 +56,6 @@ export type HotUpdaterInitOptions = CommonHotUpdaterOptions;
 export type HotUpdaterOptions = AutoUpdateOptions;
 
 type InternalCommonOptions = {
-  insights?: boolean;
   client: HotUpdaterHttpClient;
   requestHeaders?: Record<string, string>;
   requestTimeout?: number;

package/android/src/main/java/com/hotupdater/DecompressService.kt

@@ -1,89 +0,0 @@
-package com.hotupdater
-
-import android.util.Log
-import java.io.File
-
-/**
- * Unified decompression service that uses Strategy pattern to handle multiple compression formats.
- * Automatically detects format by trying each strategy's validation and delegates to appropriate decompression strategy.
- */
-class DecompressService {
-    companion object {
-        private const val TAG = "DecompressService"
-    }
-
-    // Strategies with reliable file signatures that can be validated cheaply.
-    // TAR.BR is attempted only as the final fallback because Brotli has no reliable magic bytes.
-    private val signatureStrategies =
-        listOf(
-            ZipDecompressionStrategy(),
-            TarGzDecompressionStrategy(),
-        )
-    private val tarBrStrategy = TarBrDecompressionStrategy()
-
-    /**
-     * Extracts a compressed file to the destination directory.
-     * Automatically detects compression format by trying each strategy's validation.
-     * @param filePath Path to the compressed file
-     * @param destinationPath Path to the destination directory
-     * @param progressCallback Callback for progress updates (0.0 - 1.0)
-     * @return true if extraction was successful, false otherwise
-     */
-    fun extractZipFile(
-        filePath: String,
-        destinationPath: String,
-        progressCallback: (Double) -> Unit,
-    ): Boolean {
-        // Collect file information for better error messages
-        val file = File(filePath)
-        val fileName = file.name
-        val fileSize = if (file.exists()) file.length() else 0L
-
-        // Try each signature-based strategy first.
-        for (strategy in signatureStrategies) {
-            if (strategy.isValid(filePath)) {
-                Log.d(TAG, "Using strategy for $fileName")
-                return strategy.decompress(filePath, destinationPath, progressCallback)
-            }
-        }
-
-        Log.d(TAG, "No ZIP/TAR.GZ signature matched for $fileName, trying TAR.BR fallback")
-
-        if (tarBrStrategy.decompress(filePath, destinationPath, progressCallback)) {
-            Log.d(TAG, "Using TAR.BR fallback for $fileName")
-            return true
-        }
-
-        val errorMessage = createInvalidArchiveMessage(fileName, fileSize)
-        Log.e(TAG, errorMessage)
-        return false
-    }
-
-    /**
-     * Validates if a file matches one of the signature-based archive formats.
-     * @param filePath Path to the file to validate
-     * @return true if the file is a valid compressed archive
-     */
-    fun isValidZipFile(filePath: String): Boolean {
-        for (strategy in signatureStrategies) {
-            if (strategy.isValid(filePath)) {
-                return true
-            }
-        }
-        Log.d(TAG, "No ZIP/TAR.GZ signature matched for file: $filePath. TAR.BR is handled during extraction fallback.")
-        return false
-    }
-
-    private fun createInvalidArchiveMessage(
-        fileName: String,
-        fileSize: Long,
-    ): String =
-        """
-        The downloaded bundle file is not a valid compressed archive: $fileName ($fileSize bytes)
-
-        Supported formats:
-        - ZIP archives (.zip)
-        - GZIP compressed TAR archives (.tar.gz)
-        - Brotli compressed TAR archives (.tar.br)
-        """.trimIndent()
-}

package/android/src/main/java/com/hotupdater/DecompressionStrategy.kt

@@ -1,26 +0,0 @@
-package com.hotupdater
-
-/**
- * Interface for decompression strategies
- */
-interface DecompressionStrategy {
-    /**
-     * Validates if a file can be decompressed by this strategy
-     * @param filePath Path to the file to validate
-     * @return true if the file is valid for this strategy
-     */
-    fun isValid(filePath: String): Boolean
-
-    /**
-     * Decompresses a file to the destination directory
-     * @param filePath Path to the compressed file
-     * @param destinationPath Path to the destination directory
-     * @param progressCallback Callback for progress updates (0.0 - 1.0)
-     * @return true if decompression was successful, false otherwise
-     */
-    fun decompress(
-        filePath: String,
-        destinationPath: String,
-        progressCallback: (Double) -> Unit,
-    ): Boolean
-}