# @ding-live/ding 中文文档

规范地址：https://npmcn.com/package/%40ding-live/ding/

版本：0\.22\.40
npm 元数据更新时间：2025-04-28T00:05:46.630Z
中文译文更新时间：2026-11-12T10:09:30.797Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40ding-live/ding
原文对照：https://npmcn.com/package/%40ding-live/ding/?lang=original
项目主页：https://github.com/ding-live/ding-typescript#readme
源码仓库：https://github.com/ding-live/ding-typescript

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

- 包体积（解压后）：4.5 MB，405 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@modelcontextprotocol/sdk \>=1\.5\.0 \<1\.10\.0，zod \>= 3
- 首次发布：2023-11-08T18:35:59.234Z
- 最新版本发布：2025-04-28T00:05:46.415Z
- 近 30 天下载量：8833（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：224（近 12 个月 0 个）

## 中文简介

Ding Typescript文库从JS或TS所写的应用程序中为Ding API提供方便访问.

## 安装

```sh
npm install @ding-live/ding
```

也可以使用：`pnpm add @ding-live/ding`、`yarn add @ding-live/ding`、`bun add @ding-live/ding`

## README

# 叮当打字机/ Javascript SDK

Ding Typescript文库从JS或TS所写的应用程序中为Ding API提供方便访问.

## 内容提要

叮当: OTP API允许您使用用户的电话号码向用户发送认证码.

## 目录

-   [叮当打字机/ Javascript SDK](https://npmcn.com/package/%40ding-live/ding/#readme-ding-typescriptjavascript-sdk)
    -   [SDK 安装](https://npmcn.com/package/%40ding-live/ding/#readme-sdk-installation)
    -   [SDK 示例使用法](https://npmcn.com/package/%40ding-live/ding/#readme-sdk-example-usage)
    -   [现有资源和业务](https://npmcn.com/package/%40ding-live/ding/#readme-available-resources-and-operations)
    -   [处理错误](https://npmcn.com/package/%40ding-live/ding/#readme-error-handling)
    -   [自定义 HTTP 客户端](https://npmcn.com/package/%40ding-live/ding/#readme-custom-http-client)
    -   [认证](https://npmcn.com/package/%40ding-live/ding/#readme-authentication)
    -   [服务器选择](https://npmcn.com/package/%40ding-live/ding/#readme-server-selection)
    -   [所需资源](https://npmcn.com/package/%40ding-live/ding/#readme-requirements)
    -   [检索](https://npmcn.com/package/%40ding-live/ding/#readme-retries)
    -   [调试](https://npmcn.com/package/%40ding-live/ding/#readme-debugging)
    -   [独立职能](https://npmcn.com/package/%40ding-live/ding/#readme-standalone-functions)
-   [发展](https://npmcn.com/package/%40ding-live/ding/#readme-development)
    -   [成熟度](https://npmcn.com/package/%40ding-live/ding/#readme-maturity)
    -   [捐款](https://npmcn.com/package/%40ding-live/ding/#readme-contributions)

## SDK 安装

SDK可以安装其中之一 [无](https://www.npmjs.com/), (中文(简体) ), [小时](https://pnpm.io/), (中文(简体) ), [包头](https://bun.sh/) 或者说 [线条](https://classic.yarnpkg.com/en/) 软件包管理器.

### 国家预防机制

```bash
npm add @ding-live/ding
```

### 菲律宾

```bash
pnpm add @ding-live/ding
```

### 阿宝

```bash
bun add @ding-live/ding
```

### 雅伦

```bash
yarn add @ding-live/ding zod

# Note that Yarn does not install peer dependencies automatically. You will need
# to install zod as shown above.
```

### 模式背景协议( MCP) 服务器

这个SDK也是可安装的MCP服务器,各种SDK方法都在这里 被曝光为AI应用程序可以引用的工具.

> 从 npm 运行 MCP 服务器需要node.js v20 或更多.

Claude 安装步骤

在您的服务器中添加以下定义 `claude_desktop_config.json` 文件 :

```json
{
  "mcpServers": {
    "Ding": {
      "command": "npx",
      "args": [
        "-y", "--package", "@ding-live/ding",
        "--",
        "mcp", "start",
        "--api-key", "..."
      ]
    }
  }
}
```
光标安装步骤

创建一个 `.cursor/mcp.json` 在工程根中包含以下内容的文件 :

```json
{
  "mcpServers": {
    "Ding": {
      "command": "npx",
      "args": [
        "-y", "--package", "@ding-live/ding",
        "--",
        "mcp", "start",
        "--api-key", "..."
      ]
    }
  }
}
```

也可以作为独立的二进制运行MCP服务器,没有额外的依赖性. 你必须从现有的 Github 释放中提取这些二进制:

```bash
curl -L -o mcp-server \
    https://github.com/{org}/{repo}/releases/download/{tag}/mcp-server-bun-darwin-arm64 && \
chmod +x mcp-server
```

如果回购是私人回购, 您必须加入您的 Github PAT 才能下载发行 `-H "Authorization: Bearer {GITHUB_PAT}"`。 。 。 .

```json
{
  "mcpServers": {
    "Todos": {
      "command": "./DOWNLOAD/PATH/mcp-server",
      "args": [
        "start"
      ]
    }
  }
}
```

服务器参数完整列表中, 运行 :

```sh
npx -y --package @ding-live/ding -- mcp start --help
```

## SDK 示例使用法

### 发送代码

向用户的电话号码发送一个OTP代码.

```typescript
import { Ding } from "@ding-live/ding";

const ding = new Ding({
  apiKey: "YOUR_API_KEY",
});

async function run() {
  const result = await ding.otp.createAuthentication({
    customerUuid: "cf2edc1c-7fc6-48fb-86da-b7508c6b7b71",
    locale: "fr-FR",
    phoneNumber: "+1234567890",
  });

  // Handle the result
  console.log(result);
}

run();

```

### 检查代码

检查用户输入的代码是否有效 .

```typescript
import { Ding } from "@ding-live/ding";

const ding = new Ding({
  apiKey: "YOUR_API_KEY",
});

async function run() {
  const result = await ding.otp.check({
    authenticationUuid: "eebe792b-2fcc-44a0-87f1-650e79259e02",
    checkCode: "123456",
    customerUuid: "64f66a7c-4b2c-4131-a8ff-d5b954cca05f",
  });

  // Handle the result
  console.log(result);
}

run();

```

### 进行重试

如果用户没有收到代码, 则进行重试 .

```typescript
import { Ding } from "@ding-live/ding";

const ding = new Ding({
  apiKey: "YOUR_API_KEY",
});

async function run() {
  const result = await ding.otp.retry();

  // Handle the result
  console.log(result);
}

run();

```

### 发送反馈

发送关于认证进程的反馈 .

```typescript
import { Ding } from "@ding-live/ding";

const ding = new Ding({
  apiKey: "YOUR_API_KEY",
});

async function run() {
  const result = await ding.otp.feedback({
    customerUuid: "cc0f6c04-40de-448f-8301-3cb0e6565dff",
    phoneNumber: "+1234567890",
    status: "onboarded",
  });

  // Handle the result
  console.log(result);
}

run();

```

### 获取认证状态

获取认证状态 .

```typescript
import { Ding } from "@ding-live/ding";

const ding = new Ding({
  apiKey: "YOUR_API_KEY",
});

async function run() {
  const result = await ding.otp.getAuthenticationStatus(
    "d8446450-f2fa-4dd9-806b-df5b8c661f23",
  );

  // Handle the result
  console.log(result);
}

run();

```

### 查找电话号码

进行电话号码查询.

```typescript
import { Ding } from "@ding-live/ding";

const ding = new Ding({
  apiKey: "YOUR_API_KEY",
});

async function run() {
  const result = await ding.lookup.lookup(
    "69a197d9-356c-45d1-a807-41874e16b555",
    "<value>",
  );

  // Handle the result
  console.log(result);
}

run();

```

## 现有资源和业务

可用方法

### [查询](https://npmcn.com/package/%40ding-live/ding/docs/sdks/lookup/README.md)

-   [查询](https://npmcn.com/package/%40ding-live/ding/docs/sdks/lookup/README.md#lookup) - 查查电话号码

### [水獭](https://npmcn.com/package/%40ding-live/ding/docs/sdks/otp/README.md)

-   [检查](https://npmcn.com/package/%40ding-live/ding/docs/sdks/otp/README.md#check) - 检查密码
-   [创建认证](https://npmcn.com/package/%40ding-live/ding/docs/sdks/otp/README.md#createauthentication) - 发送代码
-   [反馈](https://npmcn.com/package/%40ding-live/ding/docs/sdks/otp/README.md#feedback) - 发送反馈
-   [获取认证状态](https://npmcn.com/package/%40ding-live/ding/docs/sdks/otp/README.md#getauthenticationstatus) - 获取认证状态
-   [重试](https://npmcn.com/package/%40ding-live/ding/docs/sdks/otp/README.md#retry) - 重试一次

## 处理错误

一些方法指定了已知可以抛出的错误 。 所有已知出错均列于 `models/errors/errors.ts` 模块。 方法的已知出错记录在 _错误_ sDK文档中的表格。 例如 `check` 方法可能抛出以下错误:

| 错误类型 | 身份代码 | 内容类型 |
| --- | --- | --- |
| 错误。 答错 | 400个 | 应用程序/json |
| 错误。 SDKEROR | 页:1 | \* \*/\* 说明 |

如果该方法抛出出错误而未被已知错误所捕获,则默认投出错误 `SDKError`。 。 。 .

```typescript
import { Ding } from "@ding-live/ding";
import {
  ErrorResponse,
  SDKValidationError,
} from "@ding-live/ding/models/errors";

const ding = new Ding({
  apiKey: "YOUR_API_KEY",
});

async function run() {
  let result;
  try {
    result = await ding.otp.check({
      authenticationUuid: "eebe792b-2fcc-44a0-87f1-650e79259e02",
      checkCode: "123456",
      customerUuid: "64f66a7c-4b2c-4131-a8ff-d5b954cca05f",
    });

    // Handle the result
    console.log(result);
  } catch (err) {
    switch (true) {
      // The server response does not match the expected SDK schema
      case (err instanceof SDKValidationError): {
        // Pretty-print will provide a human-readable multi-line error message
        console.error(err.pretty());
        // Raw value may also be inspected
        console.error(err.rawValue);
        return;
      }
      case (err instanceof ErrorResponse): {
        // Handle err.data$: ErrorResponseData
        console.error(err);
        return;
      }
      default: {
        // Other errors such as network errors, see HTTPClientErrors for more details
        throw err;
      }
    }
  }
}

run();

```

当方法参数或从服务器返回的数据不符合预期格式时,验证错误也可能发生. 这个 `SDKValidationError` 因此被抛出, 将捕获在名为属性中失败验证的原始值 `rawValue`此外,a `pretty()` 方法可以在此错误上使用,用于登录一个格式良好的多行字符串,因为验证错误可以列出许多问题,而去除错误时,普通错误字符串可能很难被读取.

在一些罕见的情况下,由于网络条件等出乎意料的情况,SDK可能无法获得服务器的响应,甚至无法提出请求. 这些类型的错误在 `models/errors/httpclienterrors.ts` 模块 :

| HTTP 客户端错误 | 说明 |
| --- | --- |
| 请求中止错误 | HTTP 请求被客户端中止 |
| 请求超时错误 | HTTP 请求因中止信号而超时 |
| 连接错误 | HTTP 客户端无法向服务器提出请求 |
| 无效的请求错误 | 用于创建请求的任何输入无效 |
| 意外客户端错误 | 未识别或出乎意料的错误 |
|  |  |

## 自定义 HTTP 客户端

TypeScript SDK 使用一个 `HTTPClient` 将本地人包裹起来 [获取 API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)这个 客户端是薄薄的包装 `fetch` 并且提供连接钩子的能力 围绕可用于修改请求或处理的请求生命周期 错误和反应.

这个 `HTTPClient` 构造器使用可选 `fetcher` 参数可以是 用于整合第三方 HTTP 客户端或用于编写测试以嘲弄 hTTP 客户端并输入固定设备.

以下示例说明如何使用 `"beforeRequest"` 要添加的钩子 自定义标题和请求的超时及如何使用 `"requestError"` 钩子 记录错误 :

```typescript
import { Ding } from "@ding-live/ding";
import { HTTPClient } from "@ding-live/ding/lib/http";

const httpClient = new HTTPClient({
  // fetcher takes a function that has the same signature as native `fetch`.
  fetcher: (request) => {
    return fetch(request);
  }
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new Ding({ httpClient });
```

## 认证

### 常客安全计划

这个SDK在全球支持以下安全计划:

| 名称 | 类型 | 计划 |
| --- | --- | --- |
| `apiKey` | 键 | API 密钥 |

用 API 认证 `apiKey` 初始化 SDK 客户端实例时必须设置参数 。 例如:

```typescript
import { Ding } from "@ding-live/ding";

const ding = new Ding({
  apiKey: "YOUR_API_KEY",
});

async function run() {
  const result = await ding.otp.check({
    authenticationUuid: "eebe792b-2fcc-44a0-87f1-650e79259e02",
    checkCode: "123456",
    customerUuid: "64f66a7c-4b2c-4131-a8ff-d5b954cca05f",
  });

  // Handle the result
  console.log(result);
}

run();

```

## 服务器选择

### 覆盖服务器 URL / 客户端

通过将 URL 传递到 `serverURL: string` 初始化 SDK 客户端实例时的可选参数 。 例如:

```typescript
import { Ding } from "@ding-live/ding";

const ding = new Ding({
  serverURL: "https://api.ding.live/v1",
  apiKey: "YOUR_API_KEY",
});

async function run() {
  const result = await ding.otp.check({
    authenticationUuid: "eebe792b-2fcc-44a0-87f1-650e79259e02",
    checkCode: "123456",
    customerUuid: "64f66a7c-4b2c-4131-a8ff-d5b954cca05f",
  });

  // Handle the result
  console.log(result);
}

run();

```

## 所需资源

对于支持的 JavaScript 运行时间, 请参考 [运行时间.md](https://npmcn.com/package/%40ding-live/ding/RUNTIMES.md)。 。 。 .

## 检索

此 SDK 中的一些端点支持重试. 如果在没有任何配置的情况下使用SDK,则会回落到API提供的默认重试策略. 然而,默认的重试策略可以在一次操作的基础上被推翻,或者在整个SDK中被推翻.

更改单个 API 调用默认重试策略, 只需为调用提供重试 Config 对象 :

```typescript
import { Ding } from "@ding-live/ding";

const ding = new Ding({
  apiKey: "YOUR_API_KEY",
});

async function run() {
  const result = await ding.otp.check({
    authenticationUuid: "eebe792b-2fcc-44a0-87f1-650e79259e02",
    checkCode: "123456",
    customerUuid: "64f66a7c-4b2c-4131-a8ff-d5b954cca05f",
  }, {
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  });

  // Handle the result
  console.log(result);
}

run();

```

如果您想要覆盖所有支持重试的操作的默认重试策略, 您可以在 SDK 初始化时提供重试Config :

```typescript
import { Ding } from "@ding-live/ding";

const ding = new Ding({
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
  apiKey: "YOUR_API_KEY",
});

async function run() {
  const result = await ding.otp.check({
    authenticationUuid: "eebe792b-2fcc-44a0-87f1-650e79259e02",
    checkCode: "123456",
    customerUuid: "64f66a7c-4b2c-4131-a8ff-d5b954cca05f",
  });

  // Handle the result
  console.log(result);
}

run();

```

## 调试

您可以为 SDK 请求和响应设置 SDK 以发送调试日志 .

你可以通过一个匹配的日志 `console`'作为 SDK 选项的接口.

> \[尖叫声\] 注意调试日志会揭示一些秘密, 如标题中的 API 令牌, 打印到控制台或文件中的日志信息 。 建议只在本地开发期间使用这一特征,而不能用于生产.

```typescript
import { Ding } from "@ding-live/ding";

const sdk = new Ding({ debugLogger: console });
```

## 独立职能

上述所有方法都作为独立功能提供。 这些 函数是用于在浏览器中运行的应用程序的理想功能,没有服务器 运行时间或应用程序捆绑大小为主的其他环境 关心。 当使用捆绑器构建您的应用程序时, 全部未使用 功能将被从最后的捆绑中排除,或者被树切除.

要了解更多独立函数, 请检查 [职能.md](https://npmcn.com/package/%40ding-live/ding/FUNCTIONS.md)。 。 。 .

现有的独立职能

-   [`lookupLookup`](https://npmcn.com/package/%40ding-live/ding/docs/sdks/lookup/README.md#lookup) - 查查电话号码
-   [`otpCheck`](https://npmcn.com/package/%40ding-live/ding/docs/sdks/otp/README.md#check) - 检查密码
-   [`otpCreateAuthentication`](https://npmcn.com/package/%40ding-live/ding/docs/sdks/otp/README.md#createauthentication) - 发送代码
-   [`otpFeedback`](https://npmcn.com/package/%40ding-live/ding/docs/sdks/otp/README.md#feedback) - 发送反馈
-   [`otpGetAuthenticationStatus`](https://npmcn.com/package/%40ding-live/ding/docs/sdks/otp/README.md#getauthenticationstatus) - 获取认证状态
-   [`otpRetry`](https://npmcn.com/package/%40ding-live/ding/docs/sdks/otp/README.md#retry) - 重试一次

# 发展

## 成熟度

这个SDK是在β中,在版本之间可能会有断裂的更改,而没有主要的版本更新. 因此,我们建议使用 到特定软件包版本。 这样,您可以每次安装同一版本而不中断更改,除非您是故意的 正在寻找最新版本.

## 捐款

虽然我们重视对SDK的开源贡献,但这个库是程序生成的. 随便打开公关或Github问题作为概念的证明,我们会尽力将其纳入未来的发行中!

## 常见问题

### @ding-live/ding 是什么？

Ding Typescript文库从JS或TS所写的应用程序中为Ding API提供方便访问\.

### 如何安装 @ding-live/ding？

在项目目录运行 npm install @ding-live/ding，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（\>= 3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 mcp，可以用 npx mcp 直接运行。

### @ding-live/ding 支持 TypeScript 吗？

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

### @ding-live/ding 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @ding-live/ding 可以商用吗？

@ding-live/ding 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @ding-live/ding 的下载量有多少？

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

### @ding-live/ding 还在维护吗？

最新版本 0\.22\.40 发布于 2025/04/28（1\.5 年前）；至今共发布 224 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/11/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。