react-native-update 10.54.0 → 10.55.0

package/README-CN.md

@@ -16,6 +16,34 @@
 
 请查看[文档](https://pushy.reactnative.cn/docs/getting-started.html)
 
+### JS 错误上报
+
+SDK 可以把未捕获错误和手动捕获的 JavaScript 错误关联到当前实际运行的热更版本。
+此能力默认开启、仅做尽力上报，在开发环境或启用 `disableTelemetry` 时不发送；
+全局处理器采用链式安装，不会取代 React Native、Sentry 或 Crashlytics 已有的处理器。
+
+```ts
+import { Pushy } from 'react-native-update';
+
+const client = new Pushy({ appKey: 'your-app-key' });
+
+try {
+  await submitOrder();
+} catch (error) {
+  client.captureException(error, {
+    extra: { screen: 'checkout', retry: 1 },
+  });
+}
+
+// 运行时显式退出（同时关闭手动 captureException 的传输）：
+client.setOptions({ disableErrorReporting: true });
+```
+
+也可以在初始化时通过 `new Pushy({ appKey, disableErrorReporting: true })` 直接退出。
+
+只有携带明确版本 hash 的热更版本错误会被上传。上下文字段只接受经过限长的标量值；
+不要放入密钥或个人信息。
+
 ### 优势
 
 1. 对中国用户使用阿里云高速 CDN 分发，对比其他服务器在国外的热更新服务，分发更稳定，更新成功率极高。海外用户智能分流至 cloudflare，同样提供稳定高速的分发体验。

package/README.md

@@ -14,6 +14,37 @@ See the docs:
 
 - English docs: <https://cresc.dev/docs/getting-started>
 
+## JS error reporting
+
+The SDK reports uncaught and manually captured JavaScript errors against the
+currently running OTA release. Reporting is enabled by default, best-effort,
+disabled in development and when `disableTelemetry` is enabled, and never
+replaces an existing React Native, Sentry or Crashlytics global handler.
+
+```ts
+import { Cresc } from 'react-native-update';
+
+const client = new Cresc({ appKey: 'your-app-key' });
+
+try {
+  await submitOrder();
+} catch (error) {
+  client.captureException(error, {
+    extra: { screen: 'checkout', retry: 1 },
+  });
+}
+
+// Explicit runtime opt-out (also disables manual captureException transport):
+client.setOptions({ disableErrorReporting: true });
+```
+
+You can also opt out at construction with
+`new Cresc({ appKey, disableErrorReporting: true })`.
+
+Only errors from an OTA version with a known version hash are uploaded. Context
+is deliberately restricted to bounded scalar values; do not include secrets or
+personal information.
+
 ## Advantages
 
 1. react-native-update provides a dedicated global service with fast and reliable worldwide delivery.
@@ -85,4 +116,3 @@ Since 10.52.1 every cold start runs one background update check that **does not
 | **Technical Support** | ✅ Paid dedicated support | ⚠️ Community support | ❌ **Discontinued** |
 | **Server Deployment** | ✅ Hosted service or paid private deployment | ✅ Hosted by Expo (EAS Update) | ❌ **Discontinued** |
 | **Bandwidth Usage** | ⭐⭐⭐⭐⭐ Very low (incremental) | ⭐⭐⭐ Higher (full bundle) | ❌ **Discontinued** |
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-update",
-  "version": "10.54.0",
+  "version": "10.55.0",
   "description": "react-native hot update",
   "main": "src/index",
   "types": "src/index.ts",

package/src/client.ts

@@ -25,6 +25,13 @@ import {
   UpdateError,
   type UpdateErrorCode,
 } from './error';
+import {
+  type ErrorReportContext,
+  type ErrorReportingOptions,
+  installGlobalErrorHandler,
+  type SerializedException,
+  serializeException,
+} from './errorReporting';
 import i18n from './i18n';
 import {
   resolveServerEventHash,
@@ -78,10 +85,6 @@ const SERVER_PRESETS = {
     main: [
       'https://update.react-native.cn/api',
       'https://update.reactnative.cn/api',
-      'https://1.rnupdate.online/api',
-      'https://2.rnupdate.online/api',
-      'https://3.rnupdate.online/api',
-      'https://4.rnupdate.online/api',
     ],
     queryUrls: [
       'https://gitee.com/sunnylqm/react-native-pushy/raw/master/endpoints.json',
@@ -125,6 +128,7 @@ const createDefaultClientOptions = (): ClientOptions => ({
   logger: noop,
   debug: false,
   throwError: false,
+  disableErrorReporting: false,
 });
 
 export const sharedState: {
@@ -182,6 +186,8 @@ export class Pushy {
   private pendingNativeConfigJson?: string;
   private nativeConfigSyncInFlight = false;
   private reportedInvalidUpdates = new Set<string>();
+  private reportedExceptions = new WeakSet<object>();
+  private globalErrorCleanup?: () => void;
 
   version = cInfo.rnu;
   loggerPromise = (() => {
@@ -280,9 +286,18 @@ export class Pushy {
         log('onOptionsChange listener error:', e?.message || e);
       }
     }
+    this.syncAutomaticErrorReporting();
     this.syncNativeConfig();
   };
 
+  private syncAutomaticErrorReporting = (): void => {
+    if (this.options.disableTelemetry || this.options.disableErrorReporting) {
+      this.globalErrorCleanup?.();
+      return;
+    }
+    this.enableErrorReporting();
+  };
+
   /** Build the subset of options used by the native cold-start check. */
   private getNativeConfig = (): Record<string, unknown> | undefined => {
     if (
@@ -518,6 +533,115 @@ export class Pushy {
     });
   };
 
+  /**
+   * Best-effort JS exception reporting for the currently running OTA release.
+   * It is intentionally synchronous to call and never throws; the transport
+   * runs in the background and preserves the app's existing error flow.
+   */
+  captureException = (
+    error: unknown,
+    context: ErrorReportContext = {}
+  ): void => {
+    try {
+      if (
+        __DEV__ ||
+        this.options.disableTelemetry ||
+        this.options.disableErrorReporting
+      ) {
+        return;
+      }
+      if (
+        error !== null &&
+        (typeof error === 'object' || typeof error === 'function')
+      ) {
+        const object = error as object;
+        if (this.reportedExceptions.has(object)) {
+          return;
+        }
+        this.reportedExceptions.add(object);
+      }
+      this.reportExceptionToServer(serializeException(error, context));
+    } catch (e: any) {
+      log('exception telemetry error:', e?.message || e);
+    }
+  };
+
+  /**
+   * Ensure uncaught JS exception capture is installed and return a runtime
+   * cleanup function. Capture is installed automatically by default; this
+   * method remains an idempotent compatibility hook. The wrapper always
+   * chains the handler that was installed before it and only restores that
+   * handler when no later integration has replaced ours.
+   */
+  enableErrorReporting = (
+    options: ErrorReportingOptions = {}
+  ): (() => void) => {
+    if (
+      options.captureGlobal === false ||
+      this.options.disableTelemetry ||
+      this.options.disableErrorReporting
+    ) {
+      return () => {};
+    }
+    if (this.globalErrorCleanup) {
+      return this.globalErrorCleanup;
+    }
+    const uninstall = installGlobalErrorHandler((error, isFatal) => {
+      this.captureException(error, { fatal: isFatal === true });
+    });
+    let active = true;
+    const cleanup = () => {
+      if (!active) {
+        return;
+      }
+      active = false;
+      uninstall();
+      if (this.globalErrorCleanup === cleanup) {
+        this.globalErrorCleanup = undefined;
+      }
+    };
+    this.globalErrorCleanup = cleanup;
+    return cleanup;
+  };
+
+  private reportExceptionToServer = (error: SerializedException): void => {
+    try {
+      if (
+        __DEV__ ||
+        this.options.disableTelemetry ||
+        this.options.disableErrorReporting ||
+        !currentVersion
+      ) {
+        return;
+      }
+      const { appKey } = this.options;
+      const endpoint =
+        this.lastWorkingEndpoint || this.options.server?.main?.[0];
+      if (!appKey || !endpoint) {
+        return;
+      }
+      fetchWithTimeout(
+        `${endpoint}/report/${appKey}`,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            type: 'js_exception',
+            hash: currentVersion,
+            packageVersion: this.getEffectivePackageVersion(),
+            cInfo,
+            error,
+          }),
+        },
+        DEFAULT_FETCH_TIMEOUT_MS
+      ).catch((e: any) => {
+        log('exception telemetry report failed:', e?.message || e);
+      });
+    } catch (e: any) {
+      log('exception telemetry error:', e?.message || e);
+    }
+  };
+
   report = async ({
     type,
     message = '',

package/src/errorReporting.ts

@@ -0,0 +1,136 @@
+export type ErrorContextValue = string | number | boolean | null;
+
+export interface ErrorReportContext {
+  fatal?: boolean;
+  componentStack?: string;
+  extra?: Record<string, ErrorContextValue>;
+}
+
+export interface ErrorReportingOptions {
+  /** Install a chained React Native ErrorUtils handler. Default: true. */
+  captureGlobal?: boolean;
+}
+
+export interface SerializedException {
+  name: string;
+  message: string;
+  stack: string;
+  fatal: boolean;
+  componentStack?: string;
+  extra?: Record<string, ErrorContextValue>;
+}
+
+const MAX_NAME = 128;
+const MAX_MESSAGE = 2 * 1024;
+const MAX_STACK = 32 * 1024;
+const MAX_COMPONENT_STACK = 16 * 1024;
+const MAX_EXTRA_FIELDS = 32;
+const MAX_EXTRA_KEY = 64;
+const MAX_EXTRA_STRING = 1024;
+const MAX_EXTRA_JSON = 8 * 1024;
+
+const boundedString = (value: unknown, maximum: number) =>
+  typeof value === 'string' ? value.slice(0, maximum) : '';
+
+const normalizeExtra = (
+  extra?: Record<string, ErrorContextValue>
+): Record<string, ErrorContextValue> | undefined => {
+  if (!extra || typeof extra !== 'object') {
+    return undefined;
+  }
+  const result: Record<string, ErrorContextValue> = {};
+  for (const [rawKey, value] of Object.entries(extra).slice(
+    0,
+    MAX_EXTRA_FIELDS
+  )) {
+    const key = rawKey.slice(0, MAX_EXTRA_KEY);
+    if (!key) {
+      continue;
+    }
+    if (typeof value === 'string') {
+      result[key] = value.slice(0, MAX_EXTRA_STRING);
+    } else if (
+      value === null ||
+      typeof value === 'boolean' ||
+      (typeof value === 'number' && Number.isFinite(value))
+    ) {
+      result[key] = value;
+    }
+    // Keep the client comfortably inside the server's byte cap. The server
+    // remains authoritative because JS string length is not UTF-8 byte length.
+    if (JSON.stringify(result).length > MAX_EXTRA_JSON) {
+      delete result[key];
+      break;
+    }
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+};
+
+export const serializeException = (
+  error: unknown,
+  context: ErrorReportContext = {}
+): SerializedException => {
+  const source =
+    error !== null && (typeof error === 'object' || typeof error === 'function')
+      ? (error as Record<string, unknown>)
+      : undefined;
+  const name = boundedString(source?.name, MAX_NAME).trim() || 'Error';
+  const message = (
+    boundedString(source?.message, MAX_MESSAGE) || String(error ?? '')
+  ).slice(0, MAX_MESSAGE);
+  const stack =
+    boundedString(source?.stack, MAX_STACK) || `${name}: ${message}`;
+  const componentStack = boundedString(
+    context.componentStack,
+    MAX_COMPONENT_STACK
+  );
+  const extra = normalizeExtra(context.extra);
+  return {
+    name,
+    message,
+    stack,
+    fatal: context.fatal === true,
+    ...(componentStack ? { componentStack } : {}),
+    ...(extra ? { extra } : {}),
+  };
+};
+
+type GlobalErrorHandler = (error: unknown, isFatal?: boolean) => void;
+
+interface GlobalErrorUtils {
+  getGlobalHandler?: () => GlobalErrorHandler;
+  setGlobalHandler?: (handler: GlobalErrorHandler) => void;
+}
+
+/**
+ * Install a React Native global error wrapper without taking ownership away
+ * from ExceptionsManager, Sentry, Crashlytics, or a handler installed later.
+ */
+export const installGlobalErrorHandler = (
+  capture: GlobalErrorHandler
+): (() => void) => {
+  const errorUtils = (globalThis as any).ErrorUtils as
+    | GlobalErrorUtils
+    | undefined;
+  if (
+    typeof errorUtils?.getGlobalHandler !== 'function' ||
+    typeof errorUtils.setGlobalHandler !== 'function'
+  ) {
+    return () => {};
+  }
+  const previous = errorUtils.getGlobalHandler();
+  const wrapper: GlobalErrorHandler = (error, isFatal) => {
+    try {
+      capture(error, isFatal);
+    } catch {
+      // Reporting must never alter React Native's original failure path.
+    }
+    previous?.(error, isFatal);
+  };
+  errorUtils.setGlobalHandler(wrapper);
+  return () => {
+    if (errorUtils.getGlobalHandler?.() === wrapper) {
+      errorUtils.setGlobalHandler?.(previous);
+    }
+  };
+};

package/src/index.ts

@@ -10,6 +10,12 @@ export {
 export { PushyModule, UpdateModule } from './core';
 export type { UpdateErrorCode } from './error';
 export { UpdateError } from './error';
+export type {
+  ErrorContextValue,
+  ErrorReportContext,
+  ErrorReportingOptions,
+  SerializedException,
+} from './errorReporting';
 export type { CrashReporterLike, UpdateMetadata } from './metadata';
 export {
   attachToCrashlytics,

package/src/type.ts

@@ -205,6 +205,13 @@ export interface ClientOptions {
    * the version health view in the console. Default: false (enabled).
    */
   disableTelemetry?: boolean;
+  /**
+   * Disable automatic and manual JavaScript exception reporting. Reporting is
+   * enabled by default and chains React Native's existing global ErrorUtils
+   * handler. Set this to true for an explicit opt-out; update lifecycle
+   * telemetry remains controlled separately by `disableTelemetry`.
+   */
+  disableErrorReporting?: boolean;
   /**
    * Disable the native cold-start update check: the background check that runs
    * a few seconds after every launch, independent of JS