XuqmGroup-RNSDK/packages/common

@xuqm/rn-common

所有 @xuqm React Native SDK 的唯一基础包，也可以零初始化、零登录单独使用。文件、时间、加密、设备、UI、API hooks，以及使用绝对 URL 或 configureHttp 配置地址的网络请求，都不依赖 SDK 上下文。

安装

pnpm add @xuqm/rn-common axios \
  @react-native-async-storage/async-storage

独立使用

只使用 common 的通用能力时，不放配置文件、不调用 initialize，也不调用 login：

import { apiRequest, configureHttp, expirationStatus } from '@xuqm/rn-common'

configureHttp({ baseUrl: 'https://api.example.com' })
const result = await apiRequest('/health', { skipAuth: true })
const state = expirationStatus('2027-01-01T00:00:00Z')

没有 SDK 配置时，apiRequest 不添加 appKey、用户和签名请求头。

扩展包自动初始化

把平台生成的加密配置放到 src/assets/config/config.xuqmconfig，并只包装一次 Metro 配置：

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config')
const { withXuqmConfig } = require('@xuqm/rn-common/metro')

module.exports = withXuqmConfig(
  mergeConfig(getDefaultConfig(__dirname), {
    // 宿主自己的 Metro 配置
  }),
)

使用 update、bugcollect、xwebview 等扩展包时，withXuqmConfig() 会把 common 的初始化入口注册为 Metro pre-main module，确保初始化早于业务入口且不受 inlineRequires 影响。Metro 插件还会把同一份配置同步到 Android assets；宿主不需要在多个位置维护副本。

common-only 项目不要放置 .xuqmconfig，也不要使用 withXuqmConfig()，即可保持零初始化。是否初始化只由这一条规则决定，不提供额外 alias 或多套配置约定。

无法使用配置文件时，才调用一次手动初始化：

await XuqmSDK.initialize({ appKey: 'app-key' })

同一配置的并发初始化会复用同一个 Promise；重复使用不同配置会直接报错。

Metro 预加载发起的自动初始化如果因临时网络或 DNS 问题失败，common 会终止该 Promise，避免形成未处理异常。随后第一个真正需要配置的扩展调用共享 awaitInitialization() 时，会使用同一份加密配置重新尝试；配置、appKey 和平台地址不需要由页面或子 SDK 再次传入。持续失败由宿主入口统一记录一次，SDK 不重复打印同一错误。

扩展包的唯一登录入口

应用登录成功后只调用一次：

import { XuqmSDK } from '@xuqm/rn-common'

await XuqmSDK.login({
  userId: 'user-id',
  accessToken: 'http-access-token',
  userSig: 'optional-im-user-sig',
  name: '姓名',
  phone: '手机号',
})

await XuqmSDK.logout()

accessToken 仅用于公共 HTTP 鉴权，userSig 仅用于 IM。所有已安装的官方子 SDK 订阅这一次会话变更，不得各自初始化或登录。未使用 IM 的应用无需传 userSig。

通用能力

• apiRequest：common-only 模式可直接使用；存在 SDK 配置时使用当前会话的 userId、access token 和请求签名。需要配置的扩展包会先调用共享 awaitInitialization()，common 不会擅自要求初始化。
• downloadBytes、downloadText、downloadFileToPath：统一小文件流式读取与大文件落盘、进度和取消能力。
• compareVersions、satisfiesVersion、compatibleMajorRange：统一 SemVer 与插件兼容范围判断。
• expirationStatus、toTimestamp、millisecondsUntil、formatDateTime：统一时间解析与过期判断。
• formatNumericDateTime：为 API 参数和固定数字布局提供不受 locale 标点/顺序影响的本地时间格式，调用方通过选项控制日期、时间、秒和分隔符。
• fileExists、ensureDirectory、readFileAsBase64、writeBase64File、openLocalFile、registerAndroidDownloadedFile：统一文件与 Android 下载登记操作。
• decryptXuqmFile、hmacSha256Base64Url：基于 @noble/* 的跨平台加密实现。
• getDeviceInfo、getDeviceId、useApi、usePageApi、showToast 等项目通用能力。

业务代码不得导入 @xuqm/rn-common/internal。该子路径仅供官方 @xuqm 扩展包接入公共生命周期。