让开源，少一点语言距离。
npm包中文文档

@documenso/sdk-typescript

中文文档
0.9.1发布于 2026/09/01TypeScriptCommonJS近 30 天下载 32.1万
Documenso Logo
中文使用文档
中文原文
文档目录27 节
  1. Documenso 类型脚本 SDK
  2. ưμ㼯A
  3. 目录
  4. SDK 安装
  5. 国家预防机制
  6. 菲律宾
  7. 阿宝
  8. 雅伦
  9. 模式背景协议( MCP) 服务器
  10. 所需资源
  11. 认证
  12. 文档创建示例
  13. 现有资源和业务
  14. 文档
  15. 文档
  16. 嵌入
  17. 信封
  18. 信封接收器
  19. 信封
  20. 文件夹
  21. 模板
  22. 模板
  23. 文件上传
  24. 检索
  25. 处理错误
  26. 示例
  27. 错误分类
Documenso Logo

 

Documenso 类型脚本 SDK

一个用于与Documenso v2 API无缝融合的型式安全SDK,提供一等的TypeScript支持.

这个SDK提供了一个与Documenso的API交互的强型界面,使您能够:

  • 处理全类型安全的文件签名工作流程
  • 在您的 IDE 中调用自动完成
  • 编译时捕捉可能的错误

完整的 Documenso API 可以查看 这里,包括 TypeScript 示例.

ưμ㼯A

Documenso v2 API和SDK目前处于β. 可能要打破变化.

为了不断了解最新情况,请注意这里的讨论:

目录

SDK 安装

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

国家预防机制

npm add @documenso/sdk-typescript

菲律宾

pnpm add @documenso/sdk-typescript

阿宝

bun add @documenso/sdk-typescript

雅伦

yarn add @documenso/sdk-typescript

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

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

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

Claude 安装步骤

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

{
  "mcpServers": {
    "Documenso": {
      "command": "npx",
      "args": [
        "-y", "--package", "@documenso/sdk-typescript",
        "--",
        "mcp", "start",
        "--api-key", "..."
      ]
    }
  }
}
光标安装步骤

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

{
  "mcpServers": {
    "Documenso": {
      "command": "npx",
      "args": [
        "-y", "--package", "@documenso/sdk-typescript",
        "--",
        "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 @documenso/sdk-typescript -- mcp start --help

所需资源

对于支持的 JavaScript 运行时间, 请参考 运行时间.md。 。 。 .

认证

要使用 SDK, 您需要能够创建的 Documenso API 密钥 这里。 。 。 .

const documenso = new Documenso({
  apiKey: process.env["DOCUMENSO_API_KEY"] ?? "",
});

文档创建示例

目前编写文件涉及两个步骤:

  1. 创建文档
  2. 上传 PDF

这是一项临时措施,在全面发布之前的近期,我们将将这两项任务合并为一个请求.

以下是您可以复制和运行的文档创建过程的全部实例 .

注意该功能暂时叫 createV0,将替换为 create 一旦我们解决了两步之遥.

import { Documenso } from "@documenso/sdk-typescript";
import fs from "fs";

const documenso = new Documenso({
  apiKey: process.env["DOCUMENSO_API_KEY"] ?? "",
});

async function uploadFileToPresignedUrl(filePath: string, uploadUrl: string) {
  const fileBuffer = await fs.promises.readFile(filePath);

  // Make PUT request to pre-signed URL
  const response = await fetch(uploadUrl, {
    method: "PUT",
    body: fileBuffer,
    headers: {
      "Content-Type": "application/octet-stream",
    },
  });

  if (!response.ok) {
    throw new Error(`Upload failed with status: ${response.status}`);
  }
}

const main = async () => {
  const createDocumentResponse = await documenso.documents.createV0({
    title: "Document title",
    recipients: [
      {
        email: "[email protected]",
        name: "Example Doe",
        role: "SIGNER",
        fields: [
          {
            type: "SIGNATURE",
            pageNumber: 1,
            pageX: 10,
            pageY: 10,
            width: 10,
            height: 10,
          },
          {
            type: "INITIALS",
            pageNumber: 1,
            pageX: 20,
            pageY: 20,
            width: 10,
            height: 10,
          },
        ],
      },
      {
        email: "[email protected]",
        name: "Admin Doe",
        role: "APPROVER",
        fields: [
          {
            type: "SIGNATURE",
            pageNumber: 1,
            pageX: 10,
            pageY: 50,
            width: 10,
            height: 10,
          },
        ],
      },
    ],
    meta: {
      timezone: "Australia/Melbourne",
      dateFormat: "MM/dd/yyyy hh:mm a",
      language: "de",
      subject: "Email subject",
      message: "Email message",
      emailSettings: {
        recipientRemoved: false,
      },
    },
  });

  const { document, uploadUrl } = createDocumentResponse;

  // Upload the PDF you want attached to the document.
  // Replace demo.pdf with your file to upload relative to this file.
  await uploadFileToPresignedUrl("./demo.pdf", uploadUrl);

  return document;
};

main()

现有资源和业务

可用方法

文档

文档

  • 起来 - 获取文档:警告: 折旧
  • 寻找 - 查找文档:警告: 折旧
  • 创建 - 创建文档:警告: 折旧
  • 更新 - 更新文档:警告: 折旧
  • 删除 - 删除文档:警告: 折旧
  • 复制 - 复制文件:警告: 折旧
  • 分发 - 分发文档:警告: 折旧
  • 重新分配 - 重分配文档:警告: 折旧
  • 下载 - 下载文档:警告: 折旧
  • 创建V0 - 创建文档:警告: 折旧

文档。 附录

  • 创建 - 创建附件:警告: 折旧
  • 更新 - 更新附件:警告: 折旧
  • 删除 - 删除附件:警告: 折旧
  • 寻找 - 查找附件:警告: 折旧

文档。 字段

  • 起来 - 获取文档字段:警告: 折旧
  • 创建 - 创建文档字段:警告: 折旧
  • 创建许多 - 创建文档字段:警告: 折旧
  • 更新 - 更新文档字段:警告: 折旧
  • 更新 Many - 更新文档字段:警告: 折旧
  • 删除 - 删除文档字段:警告: 折旧

文档。 收件人

  • 起来 - 获取文档收件人:警告: 折旧
  • 创建 - 创建文档收件人:警告: 折旧
  • 创建许多 - 创建文档收件人:警告: 折旧
  • 更新 - 更新文档收件人:警告: 折旧
  • 更新 Many - 更新文档收件人:警告: 折旧
  • 删除 - 删除文档收件人:警告: 折旧

嵌入

信封

信封接收器

信封

入于内. 附录

入于内. 字段

入于内. 项目

入于内. 收件人

文件夹

模板

模板

  • 寻找 - 查找模板:警告: 折旧
  • 起来 - 获取模板:警告: 折旧
  • 创建 - 创建模板:警告: 折旧
  • 更新 - 更新模板:警告: 折旧
  • 复制 - 复制模板:警告: 折旧
  • 删除 - 删除模板:警告: 折旧
  • 使用情况 - 使用模板:警告: 折旧
  • 创建 - 创建直接链接:警告: 折旧
  • 删除 - 删除直接链接:警告: 折旧
  • 切换 - 切换直接链接:警告: 折旧

标本. 字段

  • 创建 - 创建模板字段:警告: 折旧
  • 起来 - 获取模板字段:警告: 折旧
  • 创建许多 - 创建模板字段:警告: 折旧
  • 更新 - 更新模板字段:警告: 折旧
  • 更新 Many - 更新模板字段:警告: 折旧
  • 删除 - 删除模板字段:警告: 折旧

标本. 收件人

  • 起来 - 获取模板收件人:警告: 折旧
  • 创建 - 创建模板收件人:警告: 折旧
  • 创建许多 - 创建模板收件人:警告: 折旧
  • 更新 - 更新模板收件人:警告: 折旧
  • 更新 Many - 更新模板收件人:警告: 折旧
  • 删除 - 删除模板收件人:警告: 折旧

文件上传

某些SDK方法接受文件作为多段请求的一部分. 可以而且通常建议将文件作为流上传,而不是将全部内容读入内存. 这避免了过度的内存消耗,并且在与非常大的文件合作时,可能会与外出错误相撞. 以下示例说明如何在请求中附加文件流 .

[TIP]

根据您的 JavaScript 运行时间, 有一些方便的功能可以将一个控件返回到一个文件, 而不将全部内容读入内存 :

  • 节点.js v20+: V20年以后,Node.js有一个本地人 openAsBlob 函数在 node:fs。 。 。 .
  • 宾: 当地人 Bun.file 函数生成一个可用于流文件上传的文件手柄.
  • 浏览器 : 所有支持的浏览器返回实例到一个 File 当从一个值读取时 <input type="file"> 键.
  • 节点.js v18: 文件流可以使用 fileFrom 助手从 fetch-blob/from.js。 。 。 .
import { Documenso } from "@documenso/sdk-typescript";

const documenso = new Documenso({
  apiKey: process.env["DOCUMENSO_API_KEY"] ?? "",
});

async function run() {
  const result = await documenso.envelopes.create({
    payload: {
      title: "<value>",
      type: "TEMPLATE",
    },
  });

  console.log(result);
}

run();

检索

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

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

import { Documenso } from "@documenso/sdk-typescript";

const documenso = new Documenso({
  apiKey: process.env["DOCUMENSO_API_KEY"] ?? "",
});

async function run() {
  const result = await documenso.envelopes.get({
    envelopeId: "<id>",
  }, {
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  });

  console.log(result);
}

run();

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

import { Documenso } from "@documenso/sdk-typescript";

const documenso = new Documenso({
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
  apiKey: process.env["DOCUMENSO_API_KEY"] ?? "",
});

async function run() {
  const result = await documenso.envelopes.get({
    envelopeId: "<id>",
  });

  console.log(result);
}

run();

处理错误

DocumensoError 是所有 HTTP 错误响应的基础类。 其属性如下:

财产类型说明
error.messagestring错误消息
error.statusCodenumberHTTP 响应状态代码 eg 404
error.headersHeadersHTTP 响应头
error.bodystringHTTP 躯体. 如果没有尸体返回, 则可以是空字符串 .
error.rawResponseResponse原始 HTTP 响应
error.data$可选的 一些错误可能包含结构化数据. 参见错误类。 。 。 .

示例

import { Documenso } from "@documenso/sdk-typescript";
import * as errors from "@documenso/sdk-typescript/models/errors";

const documenso = new Documenso({
  apiKey: process.env["DOCUMENSO_API_KEY"] ?? "",
});

async function run() {
  try {
    const result = await documenso.envelopes.get({
      envelopeId: "<id>",
    });

    console.log(result);
  } catch (error) {
    // The base class for HTTP error responses
    if (error instanceof errors.DocumensoError) {
      console.log(error.message);
      console.log(error.statusCode);
      console.log(error.body);
      console.log(error.headers);

      // Depending on the method different errors may be thrown
      if (error instanceof errors.EnvelopeGetBadRequestError) {
        console.log(error.data$.message); // string
        console.log(error.data$.code); // string
        console.log(error.data$.issues); // EnvelopeGetBadRequestIssue[]
      }
    }
  }
}

run();

错误分类

主错误 :

少常见错误(383)

网络错误 :

继承从 DocumensoError数字 :

版本与发布记录

@documenso/sdk-typescript 共发布 15 个版本，首次发布于 2025/01/19；过去 12 个月发布了 7 个版本。

版本发布日期距今
0.9.1latest2026/09/012 个月前
0.9.02026/07/144 个月前
0.8.12026/05/205 个月前
0.8.02026/02/218 个月前
0.7.02026/02/039 个月前
0.6.22026/01/149 个月前

关于 @documenso/sdk-typescript 的常见问题

如何安装 @documenso/sdk-typescript？

在项目目录运行 npm install @documenso/sdk-typescript，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp，可以用 npx mcp 直接运行。

@documenso/sdk-typescript 支持 TypeScript 吗？

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

@documenso/sdk-typescript 支持 ESM 还是 CommonJS？

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

@documenso/sdk-typescript 可以商用吗？

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

@documenso/sdk-typescript 的下载量有多少？

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

@documenso/sdk-typescript 还在维护吗？

最新版本 0.9.1 发布于 2026/09/01（2 个月前）；至今共发布 15 个版本，其中过去 12 个月发布了 7 个；首次发布于 2025/01/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。