XuqmGroup-RNSDK/packages/common/README.md

# @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/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()` 会把 common 的初始化入口注册为 Metro pre-main module，确保初始化早于业务入口且不受 `inlineRequires` 影响。Metro 插件还会把同一份配置同步到 Android assets；宿主不需要在多个位置维护副本。

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

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

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

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

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

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

```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 订阅这一次会话变更，不得各自初始化或登录。

## 通用能力

- `apiRequest`：common-only 模式可直接使用；存在 SDK 配置时使用当前会话的 userId、access token 和请求签名。需要配置的扩展包会先调用共享 `awaitInitialization()`，common 不会擅自要求初始化。
- `downloadBytes`、`downloadText`、`downloadFileToPath`：统一小文件流式读取与大文件落盘、进度和取消能力。
- `compareVersions`、`satisfiesVersion`、`compatibleMajorRange`：统一 SemVer 与插件兼容范围判断。
- `expirationStatus`、`toTimestamp`、`millisecondsUntil`、`formatDateTime`：统一时间解析与过期判断。
- `fileExists`、`ensureDirectory`、`readFileAsBase64`、`writeBase64File`、`openLocalFile`、`registerAndroidDownloadedFile`：统一文件与 Android 下载登记操作。
- `decryptXuqmFile`、`hmacSha256Base64Url`：基于 `@noble/*` 的跨平台加密实现。
- `getDeviceInfo`、`getDeviceId`、`useApi`、`usePageApi`、`showToast` 等项目通用能力。

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