# @xuqm/rn-common

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

## 安装

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

## 独立使用

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

```ts
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/`（目录内只能有一个
`.xuqmconfig`），并只包装一次 Metro 配置：

```js
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()` 会在 Node/Metro 构建进程中解密配置，生成只读的虚拟配置模块，并把 common 的初始化入口注册为 Metro pre-main module，确保初始化早于业务入口且不受 `inlineRequires` 影响。Metro 插件还会把同一份加密配置同步到 Android assets；宿主不需要在多个位置维护副本。PBKDF2 与 AES-GCM 解密不在 Hermes 启动线程执行，应用启动时只消费构建已经解析的配置并发起共享初始化。

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

Metro 预加载发起的自动初始化如果因临时网络或 DNS 问题失败，common 会终止该 Promise，避免形成未处理异常。随后第一个真正需要配置的扩展调用共享 `awaitInitialization()` 时，会使用同一份已解析配置重新尝试；配置、appKey 和平台地址不需要由页面或子 SDK 再次传入。持续失败由宿主入口统一记录一次，SDK 不重复打印同一错误。构建期配置损坏、密钥不匹配或 Schema 非法会直接阻断构建，禁止打出运行时才失败的安装包。

平台远程配置中的 `features.update` 是 Update 服务开关；兼容字段
`updateEnabled` 只在前者缺失时读取。两者都缺失时安全默认关闭，最后成功配置缓存会
原样保存开关值。关闭 Update 不影响 common、宿主业务或其它扩展 SDK。

## 扩展包的唯一登录入口

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

```ts
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 下载登记操作。
- `hmacSha256Base64Url`、`sha256Hex`：签名与文件摘要使用的统一实现。平台签发的
  `.xuqmconfig` 只允许由 Metro 构建插件验签和解析，不向运行时暴露通用解密 API。
- `getDeviceInfo`、`getDeviceId`、`useApi`、`usePageApi`、`showToast` 等项目通用能力。

业务代码不得导入 `@xuqm/rn-common/internal`。该子路径仅供官方 `@xuqm` 扩展包接入公共生命周期。
`internal-security` 同样只供官方扩展使用：配置 V2 和插件不可变 manifest 复用一份
canonical JSON（键排序、无空白、null/undefined 字段省略）与可信 Ed25519 keyId
集合，不是宿主可替换的通用验签入口。