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

@documenso/sdk-typescript

中文文档
0.9.1发布于 2026/09/01TypeScriptCommonJS近 30 天下载 32.1万
Documenso Logo
原始使用文档
中文原文
文档目录27 节
  1. Documenso TypeScript SDK
  2. ⚠️ Warning
  3. Table of Contents
  4. SDK Installation
  5. NPM
  6. PNPM
  7. Bun
  8. Yarn
  9. Model Context Protocol (MCP) Server
  10. Requirements
  11. Authentication
  12. Document creation example
  13. Available Resources and Operations
  14. Document
  15. Documents
  16. Embedding
  17. Envelope
  18. EnvelopeRecipients
  19. Envelopes
  20. Folders
  21. Template
  22. Templates
  23. File uploads
  24. Retries
  25. Error Handling
  26. Example
  27. Error Classes
Documenso Logo

 

Documenso TypeScript SDK

A type-safe SDK for seamless integration with Documenso v2 API, providing first-class TypeScript support.

This SDK offers a strongly-typed interface to interact with Documenso's API, enabling you to:

  • Handle document signing workflows with full type safety
  • Leverage autocomplete in your IDE
  • Catch potential errors at compile time

The full Documenso API can be viewed here, which includes TypeScript examples.

⚠️ Warning

Documenso v2 API and SDKs are currently in beta. There may be to breaking changes.

To keep updated, please follow the discussions here:

Table of Contents

SDK Installation

The SDK can be installed with either npm, pnpm, bun or yarn package managers.

NPM

npm add @documenso/sdk-typescript

PNPM

pnpm add @documenso/sdk-typescript

Bun

bun add @documenso/sdk-typescript

Yarn

yarn add @documenso/sdk-typescript

Model Context Protocol (MCP) Server

This SDK is also an installable MCP server where the various SDK methods are exposed as tools that can be invoked by AI applications.

Node.js v20 or greater is required to run the MCP server from npm.

Claude installation steps

Add the following server definition to your claude_desktop_config.json file:

{
  "mcpServers": {
    "Documenso": {
      "command": "npx",
      "args": [
        "-y", "--package", "@documenso/sdk-typescript",
        "--",
        "mcp", "start",
        "--api-key", "..."
      ]
    }
  }
}
Cursor installation steps

Create a .cursor/mcp.json file in your project root with the following content:

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

You can also run MCP servers as a standalone binary with no additional dependencies. You must pull these binaries from available Github releases:

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

If the repo is a private repo you must add your Github PAT to download a release -H "Authorization: Bearer {GITHUB_PAT}".

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

For a full list of server arguments, run:

npx -y --package @documenso/sdk-typescript -- mcp start --help

Requirements

For supported JavaScript runtimes, please consult RUNTIMES.md.

Authentication

To use the SDK, you will need a Documenso API key which can be created here.

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

Document creation example

Currently creating a document involves two steps:

  1. Create the document
  2. Upload the PDF

This is a temporary measure, in the near future prior to the full release we will merge these two tasks into one request.

Here is a full example of the document creation process which you can copy and run.

Note that the function is temporarily called createV0, which will be replaced by create once we resolve the 2 step workaround.

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

Available Resources and Operations

Available methods

Document

Documents

  • get - Get document :warning: Deprecated
  • find - Find documents :warning: Deprecated
  • create - Create document :warning: Deprecated
  • update - Update document :warning: Deprecated
  • delete - Delete document :warning: Deprecated
  • duplicate - Duplicate document :warning: Deprecated
  • distribute - Distribute document :warning: Deprecated
  • redistribute - Redistribute document :warning: Deprecated
  • download - Download document :warning: Deprecated
  • createV0 - Create document :warning: Deprecated

Documents.Attachments

  • create - Create attachment :warning: Deprecated
  • update - Update attachment :warning: Deprecated
  • delete - Delete attachment :warning: Deprecated
  • find - Find attachments :warning: Deprecated

Documents.Fields

  • get - Get document field :warning: Deprecated
  • create - Create document field :warning: Deprecated
  • createMany - Create document fields :warning: Deprecated
  • update - Update document field :warning: Deprecated
  • updateMany - Update document fields :warning: Deprecated
  • delete - Delete document field :warning: Deprecated

Documents.Recipients

  • get - Get document recipient :warning: Deprecated
  • create - Create document recipient :warning: Deprecated
  • createMany - Create document recipients :warning: Deprecated
  • update - Update document recipient :warning: Deprecated
  • updateMany - Update document recipients :warning: Deprecated
  • delete - Delete document recipient :warning: Deprecated

Embedding

Envelope

EnvelopeRecipients

Envelopes

Envelopes.Attachments

Envelopes.Fields

Envelopes.Items

Envelopes.Recipients

  • get - Get envelope recipient
  • createMany - Create envelope recipients
  • updateMany - Update envelope recipients
  • delete - Delete envelope recipient

Folders

Template

Templates

  • find - Find templates :warning: Deprecated
  • get - Get template :warning: Deprecated
  • create - Create template :warning: Deprecated
  • update - Update template :warning: Deprecated
  • duplicate - Duplicate template :warning: Deprecated
  • delete - Delete template :warning: Deprecated
  • use - Use template :warning: Deprecated
  • create - Create direct link :warning: Deprecated
  • delete - Delete direct link :warning: Deprecated
  • toggle - Toggle direct link :warning: Deprecated

Templates.Fields

  • create - Create template field :warning: Deprecated
  • get - Get template field :warning: Deprecated
  • createMany - Create template fields :warning: Deprecated
  • update - Update template field :warning: Deprecated
  • updateMany - Update template fields :warning: Deprecated
  • delete - Delete template field :warning: Deprecated

Templates.Recipients

  • get - Get template recipient :warning: Deprecated
  • create - Create template recipient :warning: Deprecated
  • createMany - Create template recipients :warning: Deprecated
  • update - Update template recipient :warning: Deprecated
  • updateMany - Update template recipients :warning: Deprecated
  • delete - Delete template recipient :warning: Deprecated

File uploads

Certain SDK methods accept files as part of a multi-part request. It is possible and typically recommended to upload files as a stream rather than reading the entire contents into memory. This avoids excessive memory consumption and potentially crashing with out-of-memory errors when working with very large files. The following example demonstrates how to attach a file stream to a request.

[!TIP]

Depending on your JavaScript runtime, there are convenient utilities that return a handle to a file without reading the entire contents into memory:

  • Node.js v20+: Since v20, Node.js comes with a native openAsBlob function in node:fs.
  • Bun: The native Bun.file function produces a file handle that can be used for streaming file uploads.
  • Browsers: All supported browsers return an instance to a File when reading the value from an <input type="file"> element.
  • Node.js v18: A file stream can be created using the fileFrom helper from 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();

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retryConfig object to the call:

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

If you'd like to override the default retry strategy for all operations that support retries, you can provide a retryConfig at SDK initialization:

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

Error Handling

DocumensoError is the base class for all HTTP error responses. It has the following properties:

PropertyTypeDescription
error.messagestringError message
error.statusCodenumberHTTP response status code eg 404
error.headersHeadersHTTP response headers
error.bodystringHTTP body. Can be empty string if no body is returned.
error.rawResponseResponseRaw HTTP response
error.data$Optional. Some errors may contain structured data. See Error Classes.

Example

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

Error Classes

Primary error:

Less common errors (383)

Network errors:

Inherit from 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 和提交记录判断。