react-native-update 10.45.0 → 10.47.0

package/src/client.ts

@@ -39,7 +39,23 @@ import {
   testUrls,
 } from './utils';
 import i18n from './i18n';
+import { toUpdateError, UpdateError, UpdateErrorCode } from './error';
 import { dedupeEndpoints, executeEndpointFallback } from './endpoint';
+import {
+  resolveServerEventHash,
+  resolveServerEventType,
+  truncateDetail,
+} from './telemetry';
+
+/**
+ * Receives every error the client reports, alongside the report event type.
+ * The UpdateProvider subscribes to surface errors as lastError/Alert; user
+ * code can subscribe too. Listeners run before any throwError rethrow.
+ */
+export type UpdateErrorListener = (
+  error: UpdateError,
+  eventType: EventType,
+) => void;
 
 const SERVER_PRESETS = {
   // cn
@@ -119,6 +135,9 @@ export class Pushy {
   clientType: 'Pushy' | 'Cresc' = 'Pushy';
   lastChecking?: number;
   lastRespJson?: Promise<CheckResult>;
+  // Endpoint that most recently served a successful checkUpdate; telemetry
+  // reuses it instead of re-running the fallback race.
+  private lastWorkingEndpoint?: string;
 
   version = cInfo.rnu;
   loggerPromise = (() => {
@@ -142,7 +161,10 @@ export class Pushy {
 
     if (Platform.OS === 'ios' || Platform.OS === 'android') {
       if (!options.appKey) {
-        throw Error(i18n.t('error_appkey_required'));
+        throw new UpdateError(
+          i18n.t('error_appkey_required'),
+          'APPKEY_REQUIRED',
+        );
       }
     }
 
@@ -184,13 +206,17 @@ export class Pushy {
   report = async ({
     type,
     message = '',
+    code,
     data = {},
   }: {
     type: EventType;
     message?: string;
+    code?: UpdateErrorCode;
     data?: Record<string, string | number>;
   }) => {
-    log(`${type} ${message}`);
+    log(`${type} ${code ? `[${code}] ` : ''}${message}`);
+    // Fire-and-forget server telemetry; must not wait for the logger below.
+    this.reportToServer({ type, message, code, data });
     if (this.options.logger === noop) {
       // Wait briefly for a logger to arrive via setOptions (e.g. the rollback
       // report fires in the constructor before the user configures one), but
@@ -214,6 +240,7 @@ export class Pushy {
           overridePackageVersion,
           buildTime,
           message,
+          code,
           ...currentVersionInfo,
           ...data,
         },
@@ -225,11 +252,110 @@ export class Pushy {
       log('logger error:', e?.message || e);
     }
   };
+  /**
+   * Best-effort lifecycle event reporting to the update server (aggregate
+   * counts + sampled failure details power the version health view and the
+   * rollback safety net server-side). Single POST to the last known working
+   * endpoint, no retry, no fallback race; any failure is swallowed — telemetry
+   * must never affect the update flow. Opt out with disableTelemetry.
+   */
+  private reportToServer = ({
+    type,
+    message = '',
+    code,
+    data = {},
+  }: {
+    type: EventType;
+    message?: string;
+    code?: UpdateErrorCode;
+    data?: Record<string, string | number>;
+  }) => {
+    try {
+      if (__DEV__ || this.options.disableTelemetry) {
+        return;
+      }
+      const serverType = resolveServerEventType(type, code);
+      if (!serverType) {
+        return;
+      }
+      const { appKey } = this.options;
+      const endpoint =
+        this.lastWorkingEndpoint || this.options.server?.main?.[0];
+      if (!appKey || !endpoint) {
+        return;
+      }
+      const hash = resolveServerEventHash({ serverType, data, currentVersion });
+      if (!hash) {
+        return;
+      }
+      const send = (payloadType: typeof serverType, detail?: string) =>
+        fetchWithTimeout(
+          `${endpoint}/report/${appKey}`,
+          {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              type: payloadType,
+              hash,
+              packageVersion:
+                this.options.overridePackageVersion || packageVersion,
+              cInfo,
+              detail: truncateDetail(detail),
+            }),
+          },
+          DEFAULT_FETCH_TIMEOUT_MS,
+        ).catch((e: any) => {
+          log('telemetry report failed:', e?.message || e);
+        });
+      send(serverType, message || undefined);
+      // A download that only succeeded after an incremental patch failed is
+      // still a patch_fail signal server-side (diff quality), carried in
+      // data.error alongside the downloadSuccess event.
+      if (serverType === 'download_success' && data.error) {
+        send('patch_fail', String(data.error));
+      }
+    } catch (e: any) {
+      log('telemetry error:', e?.message || e);
+    }
+  };
   throwIfEnabled = (e: Error) => {
     if (this.options.throwError) {
       throw e;
     }
   };
+  private errorListeners = new Set<UpdateErrorListener>();
+  /**
+   * Subscribe to every error the client reports (regardless of throwError).
+   * Returns an unsubscribe function.
+   */
+  onError = (listener: UpdateErrorListener) => {
+    this.errorListeners.add(listener);
+    return () => {
+      this.errorListeners.delete(listener);
+    };
+  };
+  /**
+   * Single exit point for errors: reports to the logger (with the stable
+   * code) and notifies onError listeners. Whether to also throw stays with
+   * the caller (throwIfEnabled or an unconditional rethrow).
+   */
+  private emitError = (
+    error: UpdateError,
+    type: EventType,
+    {
+      message = error.message,
+      data,
+    }: { message?: string; data?: Record<string, string | number> } = {},
+  ) => {
+    this.report({ type, message, code: error.code, data });
+    for (const listener of this.errorListeners) {
+      try {
+        listener(error, type);
+      } catch (e: any) {
+        log('onError listener error:', e?.message || e);
+      }
+    }
+  };
   notifyAfterCheckUpdate = (state: UpdateCheckState) => {
     const { afterCheckUpdate } = this.options;
     if (!afterCheckUpdate) {
@@ -302,11 +428,13 @@ export class Pushy {
 
     if (!resp.ok) {
       const respText = await resp.text();
-      throw Error(
+      throw new UpdateError(
         this.t('error_http_status', {
           status: resp.status,
           statusText: respText,
         }),
+        'HTTP_STATUS',
+        { extra: { status: resp.status } },
       );
     }
 
@@ -335,6 +463,7 @@ export class Pushy {
     });
 
     log('check endpoint success', endpoint);
+    this.lastWorkingEndpoint = endpoint;
     return value;
   };
   assertDebug = (matter: string) => {
@@ -348,7 +477,13 @@ export class Pushy {
     if (sharedState.marked || __DEV__ || !isFirstTime) {
       return;
     }
-    await Promise.resolve(PushyModule.markSuccess());
+    try {
+      await Promise.resolve(PushyModule.markSuccess());
+    } catch (e) {
+      const err = toUpdateError(e, 'MARK_SUCCESS_FAILED');
+      this.emitError(err, 'errorMarkSuccess');
+      throw err;
+    }
     sharedState.marked = true;
     this.report({ type: 'markSuccess' });
   };
@@ -366,7 +501,11 @@ export class Pushy {
         }
       } catch (e) {
         sharedState.applyingUpdate = false;
-        throw e;
+        const err = toUpdateError(e, 'SWITCH_VERSION_FAILED');
+        this.emitError(err, 'errorSwitchVersion', {
+          data: { newVersion: hash },
+        });
+        throw err;
       }
       try {
         return await PushyModule.reloadUpdate({ hash });
@@ -374,7 +513,11 @@ export class Pushy {
         // reloadUpdate can reject (e.g. bundle missing); reset the flag so a
         // later retry is not permanently blocked by a stuck applyingUpdate.
         sharedState.applyingUpdate = false;
-        throw e;
+        const err = toUpdateError(e, 'SWITCH_VERSION_FAILED');
+        this.emitError(err, 'errorSwitchVersion', {
+          data: { newVersion: hash },
+        });
+        throw err;
       }
     }
   };
@@ -385,7 +528,15 @@ export class Pushy {
     }
     if (assertHash(hash)) {
       log(`switchVersionLater: ${hash}`);
-      return PushyModule.setNeedUpdate({ hash });
+      try {
+        return await PushyModule.setNeedUpdate({ hash });
+      } catch (e) {
+        const err = toUpdateError(e, 'SWITCH_VERSION_FAILED');
+        this.emitError(err, 'errorSwitchVersion', {
+          data: { newVersion: hash },
+        });
+        throw err;
+      }
     }
   };
   checkUpdate = async (extra?: Record<string, any>) => {
@@ -456,14 +607,12 @@ export class Pushy {
       return result;
     } catch (e: any) {
       this.lastRespJson = previousRespJson;
-      const errorMessage =
-        e?.message || this.t('error_cannot_connect_server');
-      this.report({
-        type: 'errorChecking',
-        message: errorMessage,
+      const err = toUpdateError(e, 'CHECK_FAILED');
+      this.emitError(err, 'errorChecking', {
+        message: err.message || this.t('error_cannot_connect_server'),
       });
-      this.notifyAfterCheckUpdate({ status: 'error', error: e });
-      this.throwIfEnabled(e);
+      this.notifyAfterCheckUpdate({ status: 'error', error: err });
+      this.throwIfEnabled(err);
       // Fall back to the previous successful response if we have one; otherwise
       // return undefined so callers can distinguish "check failed" from a real
       // empty result and avoid overwriting the last good updateInfo.
@@ -669,14 +818,22 @@ export class Pushy {
       delete sharedState.progressHandlers[hash];
     }
     if (!succeeded) {
+      const message = errorMessages.join(';');
+      if (lastError) {
+        const err = toUpdateError(lastError, 'DOWNLOAD_FAILED');
+        this.emitError(err, 'errorUpdate', {
+          message,
+          data: { newVersion: hash },
+        });
+        throw err;
+      }
+      // No download URL was even attempted (e.g. dev without a full URL):
+      // report for diagnostics but there is no error object to surface.
       this.report({
         type: 'errorUpdate',
         data: { newVersion: hash },
-        message: errorMessages.join(';'),
+        message,
       });
-      if (lastError) {
-        throw lastError;
-      }
       return;
     } else {
       const duration = Date.now() - patchStartTime;
@@ -717,8 +874,12 @@ export class Pushy {
       return;
     }
     if (sharedState.apkStatus === 'downloaded') {
-      this.report({ type: 'errorInstallApk' });
-      this.throwIfEnabled(Error('errorInstallApk'));
+      const err = new UpdateError(
+        this.t('error_apk_pending_install'),
+        'APK_INSTALL_PENDING',
+      );
+      this.emitError(err, 'errorInstallApk');
+      this.throwIfEnabled(err);
       return;
     }
     if (Platform.Version <= 23) {
@@ -727,13 +888,18 @@ export class Pushy {
           PermissionsAndroid.PERMISSIONS.WRITE_EXTERNAL_STORAGE,
         );
         if (granted !== PermissionsAndroid.RESULTS.GRANTED) {
-          this.report({ type: 'rejectStoragePermission' });
-          this.throwIfEnabled(Error('rejectStoragePermission'));
+          const err = new UpdateError(
+            this.t('error_storage_permission_rejected'),
+            'STORAGE_PERMISSION_REJECTED',
+          );
+          this.emitError(err, 'rejectStoragePermission');
+          this.throwIfEnabled(err);
           return;
         }
       } catch (e: any) {
-        this.report({ type: 'errorStoragePermission' });
-        this.throwIfEnabled(e);
+        const err = toUpdateError(e, 'STORAGE_PERMISSION_ERROR');
+        this.emitError(err, 'errorStoragePermission');
+        this.throwIfEnabled(err);
         return;
       }
     }
@@ -761,10 +927,14 @@ export class Pushy {
         hash: progressKey,
       });
       sharedState.apkStatus = 'downloaded';
-    } catch {
+    } catch (e) {
       sharedState.apkStatus = null;
-      this.report({ type: 'errorDownloadAndInstallApk' });
-      this.throwIfEnabled(Error('errorDownloadAndInstallApk'));
+      // Keep the native error (message/stack) instead of discarding it.
+      const err = toUpdateError(e, 'APK_DOWNLOAD_FAILED');
+      this.emitError(err, 'errorDownloadAndInstallApk', {
+        message: err.message || this.t('error_apk_download_failed'),
+      });
+      this.throwIfEnabled(err);
     } finally {
       if (sharedState.progressHandlers[progressKey]) {
         sharedState.progressHandlers[progressKey].remove();

package/src/core.ts

@@ -1,5 +1,6 @@
 import { NativeEventEmitter, NativeModules, Platform } from 'react-native';
 import i18n from './i18n';
+import { UpdateError } from './error';
 import { emptyModule, error, log } from './utils';
 
 /* eslint-disable @react-native/no-deep-imports */
@@ -21,8 +22,9 @@ export const PushyModule =
 export const UpdateModule = PushyModule;
 
 if (!PushyModule) {
-	throw Error(
+	throw new UpdateError(
 		'Failed to load react-native-update native module, please try to recompile',
+		'MODULE_NOT_LOADED',
 	);
 }
 

package/src/endpoint.ts

@@ -1,3 +1,5 @@
+import { UpdateError } from './error';
+
 export interface EndpointAttemptSuccess<T> {
   endpoint: string;
   value: T;
@@ -47,7 +49,7 @@ export const pickRandomEndpoint = (
   random: () => number = Math.random,
 ) => {
   if (!endpoints.length) {
-    throw new Error('No endpoints configured');
+    throw new UpdateError('No endpoints configured', 'NO_ENDPOINTS');
   }
   return endpoints[Math.floor(random() * endpoints.length)];
 };
@@ -120,7 +122,7 @@ export async function executeEndpointFallback<T>({
   let candidates = dedupeEndpoints(configuredEndpoints);
 
   if (!candidates.length) {
-    throw new Error('No endpoints configured');
+    throw new UpdateError('No endpoints configured', 'NO_ENDPOINTS');
   }
 
   const firstEndpoint = pickRandomEndpoint(candidates, random);

package/src/error.ts

@@ -0,0 +1,68 @@
+/**
+ * Stable, machine-readable error codes. Unlike messages (which are localized
+ * and vary across platforms), codes are safe to aggregate on in a logger.
+ *
+ * The native-originated codes (second group) are defined in
+ * cpp/patch_core/error_codes.h — the single source of truth shared by the
+ * Android/iOS/Harmony modules — and flow through promise rejections onto the
+ * `code` property, which toUpdateError() preserves.
+ */
+export type UpdateErrorCode =
+  // JS-layer codes
+  | 'MODULE_NOT_LOADED'
+  | 'APPKEY_REQUIRED'
+  | 'NO_ENDPOINTS'
+  | 'HTTP_STATUS'
+  | 'CHECK_FAILED'
+  | 'DOWNLOAD_FAILED'
+  | 'SWITCH_VERSION_FAILED'
+  | 'MARK_SUCCESS_FAILED'
+  | 'APK_INSTALL_PENDING'
+  | 'STORAGE_PERMISSION_REJECTED'
+  | 'STORAGE_PERMISSION_ERROR'
+  | 'APK_DOWNLOAD_FAILED'
+  // Native codes (see cpp/patch_core/error_codes.h)
+  | 'INVALID_OPTIONS'
+  | 'PATCH_FAILED'
+  | 'FILE_OPERATION_FAILED'
+  | 'RESTART_FAILED'
+  | 'INVALID_HASH_INFO'
+  | 'UNSUPPORTED_PLATFORM';
+
+export class UpdateError extends Error {
+  code: UpdateErrorCode;
+  cause?: unknown;
+  extra?: Record<string, string | number>;
+
+  constructor(
+    message: string,
+    code: UpdateErrorCode,
+    options?: { cause?: unknown; extra?: Record<string, string | number> },
+  ) {
+    super(message);
+    this.name = 'UpdateError';
+    this.code = code;
+    this.cause = options?.cause;
+    this.extra = options?.extra;
+  }
+}
+
+/**
+ * Attach a code to an unknown thrown value. An existing Error keeps its
+ * identity (message, stack, and any code already assigned upstream) so callers
+ * comparing the caught error to the original still match; non-Error values are
+ * wrapped.
+ */
+export const toUpdateError = (
+  e: unknown,
+  code: UpdateErrorCode,
+): UpdateError => {
+  if (e instanceof Error) {
+    const err = e as UpdateError;
+    if (!err.code) {
+      err.code = code;
+    }
+    return err;
+  }
+  return new UpdateError(String(e ?? code), code);
+};

package/src/index.ts

@@ -1,4 +1,7 @@
 export { Pushy, Cresc } from './client';
+export type { UpdateErrorListener } from './client';
+export { UpdateError } from './error';
+export type { UpdateErrorCode } from './error';
 export {
   ProgressContext,
   UpdateContext,

package/src/locales/en.ts

@@ -19,7 +19,6 @@ export default {
   time_remaining: 'Time remaining: {{time}}',
 
   // Error messages
-  error_code: 'Error code: {{code}}',
   error_message: 'Error message: {{message}}',
   retry_count: 'Retry attempt: {{count}}/{{max}}',
 
@@ -57,6 +56,11 @@ export default {
   error_ping_failed: 'Ping failed',
   error_ping_timeout: 'Ping timeout',
   error_http_status: '{{status}} {{statusText}}',
+  error_apk_pending_install:
+    'The APK has been downloaded, please complete the installation in the system installer',
+  error_storage_permission_rejected:
+    'Storage permission denied, unable to download the APK',
+  error_apk_download_failed: 'Failed to download or install the APK',
 
   // Development messages
   dev_debug_disabled:

package/src/locales/zh.ts

@@ -19,7 +19,6 @@ export default {
   time_remaining: '剩余时间: {{time}}',
 
   // Error messages
-  error_code: '错误代码: {{code}}',
   error_message: '错误信息: {{message}}',
   retry_count: '重试次数: {{count}}/{{max}}',
 
@@ -54,6 +53,9 @@ export default {
   error_ping_failed: 'Ping 失败',
   error_ping_timeout: 'Ping 超时',
   error_http_status: '{{status}} {{statusText}}',
+  error_apk_pending_install: '安装包已下载完成，请在系统安装界面完成安装',
+  error_storage_permission_rejected: '存储权限被拒绝，无法下载安装包',
+  error_apk_download_failed: '安装包下载或安装失败',
 
   // Development messages
   dev_debug_disabled:

package/src/provider.tsx

@@ -46,15 +46,6 @@ export const UpdateProvider = ({
   const [progress, setProgress] = useState<ProgressData>();
   const [lastError, setLastError] = useState<Error>();
 
-  const throwErrorIfEnabled = useCallback(
-    (e: Error) => {
-      if (options.throwError) {
-        throw e;
-      }
-    },
-    [options.throwError],
-  );
-
   const dismissError = useCallback(() => {
     setLastError(undefined);
   }, []);
@@ -80,6 +71,25 @@ export const UpdateProvider = ({
     [options.updateStrategy],
   );
 
+  // All client errors flow through this single subscription (regardless of
+  // throwError), so the catches below only handle flow control and never
+  // duplicate the lastError/Alert surfacing.
+  useEffect(
+    () =>
+      client.onError((e, eventType) => {
+        setLastError(e);
+        alertError(
+          client.t(
+            eventType === 'errorChecking'
+              ? 'error_update_check_failed'
+              : 'update_failed',
+          ),
+          e.message,
+        );
+      }),
+    [client, alertError],
+  );
+
   const switchVersion = useCallback(
     async (info: CheckResult | undefined = updateInfoRef.current) => {
       if (info && info.hash) {
@@ -117,10 +127,11 @@ export const UpdateProvider = ({
           return false;
         }
         if (options.updateStrategy === 'silentAndNow') {
-          client.switchVersion(hash);
+          // Failures are surfaced via the onError subscription above.
+          client.switchVersion(hash).catch(noop);
           return true;
         } else if (options.updateStrategy === 'silentAndLater') {
-          client.switchVersionLater(hash);
+          client.switchVersionLater(hash).catch(noop);
           return true;
         }
         alertUpdate(client.t('alert_title'), client.t('alert_update_ready'), [
@@ -128,26 +139,33 @@ export const UpdateProvider = ({
             text: client.t('alert_next_time'),
             style: 'cancel',
             onPress: () => {
-              client.switchVersionLater(hash);
+              client.switchVersionLater(hash).catch(noop);
             },
           },
           {
             text: client.t('alert_update_now'),
             style: 'default',
             onPress: () => {
-              client.switchVersion(hash);
+              client.switchVersion(hash).catch(noop);
             },
           },
         ]);
         return true;
       } catch (e: any) {
-        setLastError(e);
-        alertError(client.t('update_failed'), e.message);
-        throwErrorIfEnabled(e);
+        // Client pipeline errors carry a code and were already surfaced via
+        // the onError subscription; errors thrown by user hooks
+        // (afterDownloadUpdate) bypass the pipeline and are surfaced here.
+        if (!e?.code) {
+          setLastError(e);
+          alertError(client.t('update_failed'), e.message);
+        }
+        if (options.throwError) {
+          throw e;
+        }
         return false;
       }
     },
-    [client, options, alertUpdate, alertError, throwErrorIfEnabled],
+    [client, options, alertUpdate, alertError],
   );
 
   const downloadAndInstallApk = useCallback(
@@ -168,9 +186,16 @@ export const UpdateProvider = ({
       try {
         rootInfo = await client.checkUpdate(extra);
       } catch (e: any) {
-        setLastError(e);
-        alertError(client.t('error_update_check_failed'), e.message);
-        throwErrorIfEnabled(e);
+        // Client pipeline errors carry a code and were already surfaced via
+        // the onError subscription; errors thrown by user hooks
+        // (beforeCheckUpdate) bypass the pipeline and are surfaced here.
+        if (!e?.code) {
+          setLastError(e);
+          alertError(client.t('error_update_check_failed'), e.message);
+        }
+        if (options.throwError) {
+          throw e;
+        }
         return;
       }
       if (!rootInfo) {
@@ -252,10 +277,9 @@ export const UpdateProvider = ({
     },
     [
       client,
-      alertError,
-      throwErrorIfEnabled,
       options,
       alertUpdate,
+      alertError,
       downloadAndInstallApk,
       downloadUpdate,
     ],
@@ -274,7 +298,8 @@ export const UpdateProvider = ({
     let markSuccessTimer: ReturnType<typeof setTimeout> | undefined;
     if (autoMarkSuccess) {
       markSuccessTimer = setTimeout(() => {
-        markSuccess();
+        // Failures are reported and surfaced via the onError subscription.
+        Promise.resolve(markSuccess()).catch(noop);
       }, 1000);
     }
     if (checkStrategy === 'both' || checkStrategy === 'onAppResume') {
@@ -351,7 +376,8 @@ export const UpdateProvider = ({
       try {
         const payload = typeof code === 'string' ? JSON.parse(code) : code;
         return parseTestPayload(payload);
-      } catch {
+      } catch (e: any) {
+        log('parseTestQrCode: invalid payload', e?.message || e);
         return false;
       }
     },