tencentcloud-sdk-nodejs: a generated SDK for the Tencent Cloud API 3.0 platform

Per-product packages are the recommended install, and the diff is small

The Tencent Cloud Node.js SDK is the companion tool for the cloud API 3.0 platform, and the recommended install is a per-product package rather than the whole thing.

npm install tencentcloud-sdk-nodejs-cvm --save

npm install tencentcloud-sdk-nodejs-vpc --save

The abbreviation table for product package names lives in products.md in the repository.

Switching to a product package changes the import, and the README shows the edit as a diff.

- const tencentcloud = require("tencentcloud-sdk-nodejs")
+ const { cvm } = require("tencentcloud-sdk-nodejs-cvm")

- const CvmClient = tencentcloud.cvm.v20170312.Client
+ const CvmClient = cvm.v20170312.Client

The version segment in the client path is the API version of that product, so cvm.v20170312 is the 2017-03-12 revision of the CVM API. Every product client is addressed the same way, which means the pattern transfers between products even though the payload types do not.

The reason for the per-product default is stated plainly: the all-product SDK contains the calling code and TypeScript type files for every cloud product and is therefore large, so for size sensitive scenarios the README recommends installing the specific product SDK.

There is a middle option for a project that needs many products and is still sensitive to size. The Slim version SDK removes the type files and minifies the code.

npm install tencentcloud-sdk-slim-nodejs --save

So the packaging decision is a three-way choice: one package per product for the smallest footprint with the best typing, the slim all-product package for breadth without the type weight, or the full all-product package when you want the types for everything.

The runtime floor is Node.js 10.0.0 or newer, and the engines field in the package manifest states node >=10.

Client construction takes credentials, region and an optional profile

The calling convention is uniform across products. You instantiate a client with a credential object, a region and an optional profile, then call an action method and handle the promise.

const tencentcloud = require("tencentcloud-sdk-nodejs")

// 导入对应产品模块的client models。
const CvmClient = tencentcloud.cvm.v20170312.Client

// 实例化要请求产品(以cvm为例)的client对象
const client = new CvmClient({
  // 为了保护密钥安全，建议将密钥设置在环境变量中或者配置文件中，请参考本文凭证管理章节。
  // 硬编码密钥到代码中有可能随代码泄露而暴露，有安全隐患，并不推荐。
  credential: {
    secretId: process.env.TENCENTCLOUD_SECRET_ID,
    secretKey: process.env.TENCENTCLOUD_SECRET_KEY,
  },
  // 产品地域
  region: "ap-shanghai",
  // 可选配置实例
  profile: {
    signMethod: "TC3-HMAC-SHA256", // 签名方法
    httpProfile: {
      reqMethod: "POST", // 请求方法
      reqTimeout: 30, // 请求超时时间，默认60s
      headers: {
        // 自定义 header
      },
      // proxy: "http://127.0.0.1:8899" // http请求代理
    },
  },
})

Two details in that block matter more than the rest. The signMethod is TC3-HMAC-SHA256, which is the request signing scheme the platform expects, and it is set explicitly rather than left implicit. And the reqTimeout is 30 with a documented default of 60 seconds, so the SDK default is more forgiving than the example.

The credential values are read from environment variables in the example, and the comment explains why: hardcoding keys in code risks them leaking with the code, which is a security risk and not recommended.

The proxy setting is commented out in the same block, and the proxy section of the README explains the alternative. If you are in an environment with a proxy, you need to pass profile.httpProfile.proxy when creating the client or set the system environment variable http_proxy, or the call may fail with a connection timeout exception. That failure mode is worth knowing in advance, because a timeout in a proxied deployment looks like a network problem rather than a missing configuration.

In a TypeScript project the import is a namespace import.

import * as tencentcloud from "tencentcloud-sdk-nodejs"

const CvmClient = tencentcloud.cvm.v20170312.Client

The Client constructor arguments support clientConfig, and the data structure and description are documented in the ClientConfig interface in src/common/interface.ts.

Every action is a promise method on the client

The call shape is described in the README as passing a request object, or Params, and a response callback, and the example given is a zone listing call on cloud servers.

client.DescribeZones().then(
  (data) => {
    console.log(data)
  },
  (err) => {
    console.error("error", err)
  }
)

So each API action becomes a method on the client named after the action, returning a promise, with a two argument then for the success and failure paths. The comment in the README notes that this also works in the form client.Action(Params).then(res => console.log(res), err => console.error(err)).

The action methods are named after the API actions themselves, which means the mapping from the platform documentation to the code is direct: find the action in the docs, call the method with the same name. The generated parameter types are what carry the shape of each request, and those types are what the per-product package gives you and the slim package does not.

There is one naming detail that is easy to miss and matters when you write generic code. Each client is versioned in its path, v20170312 in the CVM case, so a product can expose several API versions side by side. When you write code that is meant to work across products rather than against one, that segment is the thing that varies.

More examples live in the examples directory, and the listing at the repository root shows the shape of the coverage: per-product directories for cbs, cls, cvm, ecc, hcm, hunyuan and soe, plus a common directory for the Common Client and the credential examples.

The API returns objects rather than text, and the SDK is written in TypeScript with type definitions published alongside, which is why the per-product package is described as including its type files.

The Common Client calls any action by name, at the cost of type safety

From version 4.0.714, the SDK supports a general purpose API calling style through the Common Client. Installing the tencentcloud-sdk-nodejs-common package is enough to call any product.

The README attaches a warning to it in bold. You must know exactly what parameters the interface you are calling requires, otherwise the call may fail.

That warning is the whole trade. The typed per-product clients give you a typed method per action with typed parameters, and the compiler catches a wrong field name. The Common Client gives you one generic entry point that reaches every action on every product, and the parameter contract is only enforced at runtime, by the platform rejecting the request.

For a codebase that calls a handful of products with stable shapes, the typed clients are clearly the better option. For a codebase that needs to reach actions that do not have a per-product package installed, or that dispatches calls by name from configuration, the Common Client is the way to do it without pulling in every product package.

There is a common example directory referenced in the README, with the link described as using the Common Client to make calls, and the common package has its own test script, test:common, which runs vitest while the main test script runs mocha with a ten second timeout.

That split in the tooling is a small clue about how the project is organised. The bulk of the SDK is generated code tested with mocha, while the newer hand-written surfaces are covered with vitest. The package manifest has vitest at 5.0.0 and mocha at 8.4.0 as dev dependencies, both present.

The build scripts follow the same split. The build runs the CommonJS and ES module TypeScript compiles concurrently, and a separate build:slim script runs node ./scripts/build_slim.js, which is where the slim variant is produced.

Instance role credentials avoid static keys, and the frontend prohibition is absolute

Two things in the credential and security sections are worth reading twice.

The first is instance role support. Besides passing credentials explicitly, the SDK has supported Tencent Cloud instance roles since v4.0.506. After you bind a role to your instance, the instance can reach a metadata interface to obtain temporary credentials.

// ...
const CvmRoleCredential = require("tencentcloud-sdk-nodejs/tencentcloud/common/cvm_role_credential").default

new XxxClient({
  // ...
  credential: new CvmRoleCredential(),
  // ...
})

So there are two credential modes. A static pair of SecretId and SecretKey, which you obtain from the access key page in the Tencent Cloud console and must keep strictly guarded, or a role credential where the SDK fetches temporary credentials from the instance metadata service at runtime.

The role path is the better fit for anything running on a Tencent Cloud instance, because there is no long-lived secret in your environment at all. The cost is that it only works where the metadata interface is reachable, and that the role has to be bound and configured first.

The second thing is the frontend prohibition, and it is the strongest warning in the README. You must not use this SDK directly in a web frontend, including mini programs, because exposing keys in those environments is very unsafe. The correct approach is to reference the SDK on your own server, keep the keys there, handle request authentication on the server, and have the frontend call your server for the business flow.

That is not a stylistic preference. A frontend bundle with a SecretKey in it is a published credential, and the SDK's own documentation says so. The dependency list backs the point up: node-fetch, https-proxy-agent and get-stream are all server-side assumptions, and there is no browser entry point in the files list.

The remaining FAQ entries cover the practical failures. The "original argument must be of type Function" error usually means the Node.js version is below v10 or the environment is not Node.js. For request problems, the README shows how to turn on HTTP request logging with the NODE_DEBUG environment variable on macOS, Windows cmd and Windows PowerShell, and how to set http_proxy with the proxy address and port.

Where the Tencent Cloud Node.js SDK is the wrong tool

The first wrong-tool case is a browser or mini program client, and the README closes that door itself. Keys shipped to the browser are exposed keys, and the correct architecture puts the SDK behind your own server. A team that wants direct client-to-cloud calls is not going to find a safe path here.

The second case is a project that needs every action in one place with full typing. The full package gives you every product's calling code and type files, and the README says outright that it is large and recommends the specific product packages for size sensitive projects. The slim package drops the type files, which is the right trade for a small bundle and the wrong one for a team that wants the compiler to check request payloads across many products.

The third case is a codebase that wants a uniform typed interface across products with no per-product typing work. The Common Client reaches everything but gives up compile-time parameter checking, and the README warns that you must know the required parameters or the call may fail. That is a decision about where you want your failures to happen, at build time or at run time.

The fourth case is a language other than JavaScript or TypeScript. This is the Node.js SDK, with the runtime floor at Node 10, and the repository carries separate per-language SDKs as separate projects.

Two implementation details are worth planning for. The runtime dependencies include json-bigint, and the FAQ names the reason: an integer value can exceed the maximum safe integer in JavaScript, and the SDK offers BigInt as the new data type for that case. If your application handles identifiers or counts from the platform, that is a type change rather than a detail, and it affects your serialisation.

On versions and maintenance, there is an oddity worth flagging. The manifest declares version 4.1.328, and the README describes the Node.js SDK as 4.0 throughout, including the 4.0.714 Common Client and the 4.0.506 instance role versions. The recent release list, however, shows only 3.0.3 from 2018-05-31, so the published release history in the repository metadata does not reflect the current line and the npm registry is the place to look for what is actually published.

The licence is Apache-2.0, declared both in the package manifest and in the LICENSE file at the root, which is the permissive grant you would expect from a vendor SDK and does not restrict commercial use of the client code. The credentials and the platform API itself remain governed by the Tencent Cloud service terms rather than by this repository.

Editorial conclusion

tencentcloud-sdk-nodejs suits a Node.js service that calls several Tencent Cloud products and does not want to ship the whole API surface, because each product is a separate npm package and the slim build drops type files and minifies the code. It does not suit a browser front end, and the README says so in the strongest terms: the SDK must not be used directly in a web frontend including mini programs, because exposing keys there is unsafe. Before adopting, pick the per-product packages over the full package if bundle size matters, and decide whether to use static SecretId and SecretKey credentials or the instance role credential, because the latter requires a role bound to the instance and a metadata endpoint the SDK calls at runtime.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. TencentCloud/tencentcloud-sdk-nodejs on GitHub