叮当打字机/ Javascript SDK

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

内容提要

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

目录

• 叮当打字机/ Javascript SDK
  • SDK 安装
  • SDK 示例使用法
  • 现有资源和业务
  • 处理错误
  • 自定义 HTTP 客户端
  • 认证
  • 服务器选择
  • 所需资源
  • 检索
  • 调试
  • 独立职能
• 发展
  • 成熟度
  • 捐款

SDK 安装

SDK可以安装其中之一 无, (中文(简体) ), 小时, (中文(简体) ), 包头 或者说 线条 软件包管理器.

国家预防机制

npm add @ding-live/ding

菲律宾

pnpm add @ding-live/ding

阿宝

bun add @ding-live/ding

雅伦

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 或更多.

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

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

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

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}"。 。 。 .

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

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

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

SDK 示例使用法

发送代码

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

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();

检查代码

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

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();

进行重试

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

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();

发送反馈

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

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();

获取认证状态

获取认证状态 .

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();

查找电话号码

进行电话号码查询.

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();

现有资源和业务

处理错误

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

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

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 客户端

TypeScript SDK 使用一个 HTTPClient 将本地人包裹起来 获取 API这个 客户端是薄薄的包装 fetch 并且提供连接钩子的能力 围绕可用于修改请求或处理的请求生命周期 错误和反应.

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

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

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在全球支持以下安全计划:

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

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 客户端实例时的可选参数 。 例如:

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。 。 。 .

检索

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

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

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 :

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 令牌, 打印到控制台或文件中的日志信息 。 建议只在本地开发期间使用这一特征,而不能用于生产.

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

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

独立职能

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

要了解更多独立函数, 请检查 职能.md。 。 。 .

发展

成熟度

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

捐款

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