# @bi-nova/services 中文文档

规范地址：https://npmcn.com/package/%40bi-nova/services/

版本：2\.0\.3
npm 元数据更新时间：2026-11-12T06:56:08.901Z
中文译文更新时间：2026-11-12T06:56:49.214Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bi-nova/services
原文对照：https://npmcn.com/package/%40bi-nova/services/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：529 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-05-16T04:25:36.430Z
- 最新版本发布：2026-11-12T06:56:08.635Z
- 近 30 天下载量：3593（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：91（近 12 个月 91 个）

## 中文简介

BI Nova 跨平台广告服务 SDK（京东/淘宝/拼多多等）

## 安装

```sh
npm install @bi-nova/services
```

也可以使用：`pnpm add @bi-nova/services`、`yarn add @bi-nova/services`、`bun add @bi-nova/services`

## README

# @bi-nova/services

跨平台广告服务 SDK，以 NovaSDK 插件形式提供京东保险口令、京东金融现金贷、平台大会员等业务服务。

支持环境：微信小程序、支付宝小程序、Taro、H5（浏览器）。

## 安装

::: code-group

```bash
pnpm add @bi-nova/core @bi-nova/services
```

```bash
npm install @bi-nova/core @bi-nova/services
```

:::

## 快速开始

```ts
import { createNova } from '@bi-nova/core'
import { createServices } from '@bi-nova/services'

const nova = createNova({ appId: 'your-app-id', autoEnv: true })

nova.use(createServices({
  env: 'prod',
  debug: false,
  getAuthToken: () => getToken(),
}))

// 调用服务
const result = await nova.jd.handleJdInsurance({ equipmentValue: '...' })
```

平台大会员接入请参阅 [平台大会员服务接入指南](https://npmcn.com/services/global-vip)。

平台大会员**单次购买**（大会员入口 / 商家套餐入口，内部完成命中判断、统一下单与调起支付）请参阅 [单次购买组件接入文档](https://npmcn.com/services/global-vip-single-purchase)。

跨渠道签约接入请参阅 [自动代扣服务接入文档](https://npmcn.com/services/automatic-debit)。

## 登录态 token 管理

`createServices` 安装后会在 `nova` 实例上挂载登录态管理方法：

```ts
nova.setToken(token)
nova.clearToken()
```

推荐在宿主登录成功后写入 token：

```ts
const nova = createNova({ appId: 'your-app-id', autoEnv: true })

nova.use(createServices({
  env: 'prod',
  debug: false,
}))

// 用户登录成功后写入 token，后续需要登录态的内部服务会自动携带。
nova.setToken(loginResult.token)

// 用户退出登录或 token 失效时清理。
nova.clearToken()
```

如果宿主已经有统一登录态管理，也可以继续使用初始化配置中的 `getAuthToken`：

```ts
nova.use(createServices({
  env: 'prod',
  getAuthToken: () => appStore.token,
}))
```

内部请求的 token 获取优先级为：

```txt
nova.setToken(token) 写入的运行时 token
> createServices({ getAuthToken }) 返回值
> SDK storage 中的 auth_token
```

默认情况下，内部 API 请求需要 token；明确无需 token 的接口会在 SDK 内部单独标记，例如展示广告配置接口。

## UMD 使用

```html
<script src="bi-nova.umd.js"></script>
<script>
  const { createNova, createServices } = window.BiNova

  const nova = createNova({ appId: 'xxx', autoEnv: true })
  nova.use(createServices({
    env: 'sit',
    debug: true,
    getAuthToken: () => getToken(),
  }))

  // 调用方式完全一致
  const result = await nova.jd.handleJdInsurance({ equipmentValue: '...' })
</script>
```

* * *

## 初始化配置

### 配置选项（ServicesOptions）

| 字段 | 类型 | 必填 | 默认值 | 说明 | 适用 |
| --- | --- | :-: | --- | --- | --- |
| `debug` | `boolean` | 否 | `false` | 开启调试日志 | 所有 |
| `env` | `string` | 否 | `'prod'` | 内部 API 环境：`'dev'` / `'sit'` / `'uat'` / `'prod'` | 内部服务 |
| `apiDomain` | `string` | 否 | `''` | 自定义 API 域名（覆盖 env 映射） | 内部服务 |
| `getAuthToken` | `() => Promise<string> | string` | 否 | \- | 获取鉴权 token | 内部服务 |
| `externalEnv` | `string` | 否 | `'prod'` | 外部对接环境：`'sit'` / `'release'` / `'prod'` | 外部服务 |
| `externalAppId` | `string` | 外部必填 | \- | 乐遥摇平台分配的应用标识（⚠️ 非微信/支付宝小程序 appId） | 外部服务 |
| `externalAppSecret` | `string` | 外部必填 | \- | 乐遥摇平台分配的应用密钥 | 外部服务 |

> ⚠️ **注意**：`externalAppId` 和 `externalAppSecret` 是由乐遥摇平台分配的应用凭证，与微信/支付宝小程序的 `appId`/`appSecret` 无关。

### 配置示例

**仅内部服务：**

```ts
nova.use(createServices({
  env: 'sit',
  debug: true,
  getAuthToken: () => getToken(),
}))
```

**仅外部对接服务：**

```ts
nova.use(createServices({
  externalEnv: 'sit',
  externalAppId: 'leyaoyao-assigned-app-id',
  externalAppSecret: 'leyaoyao-assigned-secret',
}))
```

**同时使用内部和外部服务：**

```ts
nova.use(createServices({
  // 内部服务配置
  env: 'sit',
  getAuthToken: () => getToken(),
  // 外部服务配置
  externalEnv: 'sit',
  externalAppId: 'leyaoyao-assigned-app-id',
  externalAppSecret: 'leyaoyao-assigned-secret',
  debug: true,
}))
```

### 环境域名映射

**内部 API（`env`）** — 适用于京东保险服务、京东金融现金贷服务

| env | 域名 |
| --- | --- |
| `dev` | `https://dm.leyaoyao.com` |
| `sit` | `https://sm.leyaoyao.com` |
| `uat` | `https://um.leyaoyao.com` |
| `prod` | `https://m.leyaoyao.com` |

**外部对接 API（`externalEnv`）** — 适用于外部对接京东保险服务

| externalEnv | 域名 |
| --- | --- |
| `sit` | `https://sopenapi.leyaoyao.com` |
| `release` | `https://uopenapi.leyaoyao.com` |
| `prod` | `https://openapi.leyaoyao.com` |

* * *

## API 详解

所有方法返回统一格式：

```ts
interface BuildResultReturn<T = any> {
  code: number     // 0 = 成功，非 0 = 失败
  message: string  // 提示信息
  data: T | null   // 业务数据
}
```

* * *

## TypeScript 类型

### 类型导入

**方式一：导入特定类型（推荐）**

```ts
// 配置类型
import type { ServicesOptions } from '@bi-nova/services'

// 京东保险服务类型
import type {
  JdInsuranceOptions,
  JdInsuranceExternalOptions,
  JdInsuranceResult,
} from '@bi-nova/services'

// 京东金融现金贷服务类型
import type {
  JdjrCashLoanOptions,
  JdjrCashLoanExternalOptions,
} from '@bi-nova/services'

// 通用类型
import type {
  PluginConfig,
  BuildResultReturn,
  JumpConfig,
} from '@bi-nova/services'

// 环境枚举
import { ENV_TYPE, EXTERNAL_ENV_TYPE } from '@bi-nova/services'

// 错误码
import { JdErrorCode } from '@bi-nova/services'
```

**方式二：导入所有类型**

```ts
import type * as ServiceTypes from '@bi-nova/services'

// 使用时：ServiceTypes.JdInsuranceOptions
```

### 类型使用示例

**使用 ENV\_TYPE 枚举配置**

```ts
import { createNova } from '@bi-nova/core'
import { createServices, ENV_TYPE } from '@bi-nova/services'
import type { ServicesOptions } from '@bi-nova/services'

const config: ServicesOptions = {
  env: ENV_TYPE.SIT,        // IDE 会提示可用的环境选项
  debug: true,
  getAuthToken: async () => {
    return await getToken()
  },
}

const nova = createNova({ appId: 'your-app-id', autoEnv: true })
nova.use(createServices(config))
```

**泛型错误处理函数**

```ts
import type { BuildResultReturn } from '@bi-nova/services'

async function handleServiceResult<T>(
  promise: Promise<BuildResultReturn<T>>
): Promise<T | null> {
  const result = await promise

  if (result.code === 0 && result.data !== null) {
    return result.data
  }

  showToast(result.message || '操作失败，请重试')
  return null
}

// 使用
const data = await handleServiceResult(
  nova.jd.handleJdInsurance({ equipmentValue: 'xxx' })
)
```

**外部对接服务类型**

```ts
import type { JdInsuranceExternalOptions } from '@bi-nova/services'

const params: JdInsuranceExternalOptions = {
  thirdPlatform: 'yipule',
  thirdPlatformUserId: '23413494',
  thirdPlatformEquipmentValue: '999999',
  phone: '13800138000',
  extendData: {
    customField1: 'value1',
    customField2: 123,
  },
}

const result = await nova.jd.handleJdInsuranceExt(params)
```

**外部对接现金贷服务类型**

```ts
import type { JdjrCashLoanExternalOptions } from '@bi-nova/services'

const params: JdjrCashLoanExternalOptions = {
  phone: '13800138000',
  rtaId: 'rta_strategy_001',
  thirdPlatform: 'yipule',
  thirdPlatformUserId: '23413494',
  thirdPlatformEquipmentValue: '999999',
  os: 'ios',
  client: 'miniapp',
  extendData: {
    customField1: 'value1',
    customField2: 123,
  },
}

const result = await nova.jd.handleJdjrCashLoanExt(params)
```

* * *

## 注意事项

### 通用

1.  **SDK 引入**：确保已正确引入京东 SDK 文件（`LyyGetCommandSDK.min.js`）
2.  **网络请求**：插件会发起网络请求，确保小程序已配置合法域名
3.  **小程序跳转权限**：使用小程序跳转功能时，需要在小程序配置中添加跳转白名单
4.  **剪贴板权限**：复制口令功能需要用户授权剪贴板权限
5.  **异步处理**：所有方法返回 Promise，使用 `async/await` 或 `.then()` 处理

## 常见问题

### @bi-nova/services 是什么？

BI Nova 跨平台广告服务 SDK（京东/淘宝/拼多多等）

### 如何安装 @bi-nova/services？

在项目目录运行 npm install @bi-nova/services，或使用 pnpm add / yarn add / bun add。

### @bi-nova/services 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bi-nova/services 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bi-nova/services 可以商用吗？

@bi-nova/services 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bi-nova/services 的下载量有多少？

根据 npm 官方下载统计，@bi-nova/services 在 2026/10/08 – 2026/11/06 这 30 天内被下载 3,593 次，日均约 120 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bi-nova/services 还在维护吗？

最新版本 2\.0\.3 发布于 2026/11/12（今天）；至今共发布 91 个版本，其中过去 12 个月发布了 91 个；首次发布于 2026/05/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。