tencentcloud-sdk-nodejs 4.1.64 → 4.1.66

package/tencentcloud/common/abstract_client.js

@@ -10,21 +10,42 @@ const tencent_cloud_sdk_exception_1 = tslib_1.__importDefault(require("./excepti
 const sse_response_model_1 = require("./sse_response_model");
 const uuid_1 = require("uuid");
 /**
- * @inner
+ * Abstract base client for Tencent Cloud SDK
+ *
+ * This class provides common functionality for making API requests to Tencent Cloud services,
+ * including request signing, error handling, and response parsing.
  */
 class AbstractClient {
     /**
-     * 实例化client对象
-     * @param {string} endpoint 接入点域名
-     * @param {string} version 产品版本
-     * @param {Credential} credential 认证信息实例
-     * @param {string} region 产品地域
-     * @param {ClientProfile} profile 可选配置实例
+     * Constructs a new AbstractClient instance
+     *
+     * @param {string} endpoint - The service endpoint URL (e.g. "cvm.tencentcloudapi.com")
+     * @param {string} version - The API version of the service (e.g. "2017-03-12")
+     * @param {ClientConfig} config - Configuration object containing:
+     * @param {Credential|DynamicCredential} config.credential - Credentials for authentication
+     * @param {string} [config.region] - The region of the service (e.g. "ap-shanghai")
+     * @param {ClientProfile} [config.profile={}] - Optional client configuration profile
+     *
+     * @throws {TencentCloudSDKHttpException} If invalid language is specified in profile
+     *
+     * @example
+     * const client = new AbstractClient(
+     *   "cvm.tencentcloudapi.com",
+     *   "2017-03-12",
+     *   {
+     *     credential: {
+     *       secretId: process.env.secretId,
+     *       secretKey: process.env.secretKey,
+     *     },
+     *     region: "ap-shanghai",
+     *     profile: {}
+     *   }
+     * );
      */
     constructor(endpoint, version, { credential, region, profile = {} }) {
         this.path = "/";
         /**
-         * 认证信息实例
+         * Credential instance
          */
         if (credential && "getCredential" in credential) {
             this.credential = credential;
@@ -37,14 +58,14 @@ class AbstractClient {
             }, credential);
         }
         /**
-         * 产品地域
+         * The region of the service
          */
         this.region = region || null;
         this.sdkVersion = "SDK_NODEJS_" + sdk_version_1.sdkVersion;
         this.apiVersion = version;
         this.endpoint = (profile && profile.httpProfile && profile.httpProfile.endpoint) || endpoint;
         /**
-         * 可选配置实例
+         * Optional configuration instance
          * @type {ClientProfile}
          */
         this.profile = {
@@ -61,6 +82,10 @@ class AbstractClient {
             throw new tencent_cloud_sdk_exception_1.default(`Language invalid, choices: ${interface_1.SUPPORT_LANGUAGE_LIST.join("|")}`);
         }
     }
+    /**
+     * Get credential information
+     * @returns {Promise<Credential>} Promise that resolves with credential information
+     */
     async getCredential() {
         if ("getCredential" in this.credential) {
             return await this.credential.getCredential();
@@ -68,7 +93,30 @@ class AbstractClient {
         return this.credential;
     }
     /**
-     * @inner
+     * Make an API request to Tencent Cloud service
+     *
+     * @param {string} action - The API action name to call
+     * @param {any} req - The request payload/parameters
+     * @param {ResponseCallback|RequestOptions} [options] - Either request options or callback function
+     * @param {ResponseCallback} [cb] - Optional callback function for async operation
+     * @returns {Promise<ResponseData>} Promise that resolves with the API response data
+     *
+     * @example
+     * // Using promise
+     * client.request('DescribeInstances', {Limit: 10})
+     *   .then(data => console.log(data))
+     *   .catch(err => console.error(err));
+     *
+     * // Using callback
+     * client.request('DescribeInstances', {Limit: 10}, (err, data) => {
+     *   if (err) console.error(err);
+     *   else console.log(data);
+     * });
+     *
+     * // With options
+     * client.request('DescribeInstances', {Limit: 10}, {signal: abortController.signal})
+     *   .then(data => console.log(data))
+     *   .catch(err => console.error(err));
      */
     async request(action, req, options, cb) {
         if (typeof options === "function") {
@@ -86,7 +134,12 @@ class AbstractClient {
         }
     }
     /**
-     * @inner
+     * Make a request with octet-stream content type
+     * @param {string} action API action name
+     * @param {any} req Request data
+     * @param {ResponseCallback|RequestOptions} [options] Request options or callback
+     * @param {ResponseCallback} [cb] Callback function
+     * @returns {Promise<any>} Promise that resolves with response data
      */
     async requestOctetStream(action, req, options, cb) {
         if (typeof options === "function") {
@@ -191,6 +244,12 @@ class AbstractClient {
         }
         return this.parseResponse(res);
     }
+    /**
+     * Parse HTTP response
+     * @param {Response} res HTTP response object
+     * @returns {Promise<ResponseData>} Promise that resolves with parsed response data
+     * @throws {TencentCloudSDKHttpException} If response contains error
+     */
     async parseResponse(res) {
         const traceId = res.headers.get("x-tc-traceid");
         if (res.status !== 200) {
@@ -216,7 +275,10 @@ class AbstractClient {
         }
     }
     /**
-     * @inner
+     * Merge nested data into flat structure
+     * @param {any} data Input data
+     * @param {string} [prefix=""] Key prefix
+     * @returns {any} Flattened data object
      */
     mergeData(data, prefix = "") {
         const ret = {};
@@ -234,7 +296,10 @@ class AbstractClient {
         return ret;
     }
     /**
-     * @inner
+     * Format request data with required fields and signature
+     * @param {string} action API action name
+     * @param {RequestData} params Request parameters
+     * @returns {Promise<RequestData>} Promise that resolves with formatted request data
      */
     async formatRequestData(action, params) {
         params.Action = action;
@@ -263,7 +328,9 @@ class AbstractClient {
         return params;
     }
     /**
-     * @inner
+     * Format string for signature calculation
+     * @param {RequestData} params Request parameters
+     * @returns {string} String to be signed
      */
     formatSignString(params) {
         let strParam = "";

package/tencentcloud/common/common_client.d.ts

@@ -1,3 +1,10 @@
 import { AbstractClient } from "./abstract_client";
+/**
+ * Common client class for Tencent Cloud SDK
+ *
+ * You only need to install the tencentcloud-sdk-nodejs-common package to Make an API request to any product
+ *
+ * @see {@link https://github.com/TencentCloud/tencentcloud-sdk-nodejs/tree/master/examples/common} view exmaple
+ */
 export declare class CommonClient extends AbstractClient {
 }

package/tencentcloud/common/common_client.js

@@ -2,6 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommonClient = void 0;
 const abstract_client_1 = require("./abstract_client");
+/**
+ * Common client class for Tencent Cloud SDK
+ *
+ * You only need to install the tencentcloud-sdk-nodejs-common package to Make an API request to any product
+ *
+ * @see {@link https://github.com/TencentCloud/tencentcloud-sdk-nodejs/tree/master/examples/common} view exmaple
+ */
 class CommonClient extends abstract_client_1.AbstractClient {
 }
 exports.CommonClient = CommonClient;

package/tencentcloud/common/cvm_role_credential.d.ts

@@ -7,6 +7,12 @@ interface CvmRoleCredentialResult {
     Token: string;
     Code: string;
 }
+/**
+ * Tencent Cloud Credential via CVM role
+ *
+ * Automatically generates temporary credentials when binding a service role to instance.
+ * @see {@link https://cloud.tencent.com/document/product/598/85616} for more information.
+ */
 export default class CvmRoleCredential implements DynamicCredential {
     protected roleNameTask: Promise<string> | null;
     protected credentialTask: Promise<CvmRoleCredentialResult> | null;

package/tencentcloud/common/cvm_role_credential.js

@@ -5,7 +5,14 @@ const fetch_1 = tslib_1.__importDefault(require("./http/fetch"));
 const META_URL = "http://metadata.tencentyun.com/latest/meta-data/";
 const ROLE_URL = META_URL + "cam/security-credentials/";
 const EXPIRE_BUFFER = 30 * 1000;
+/**
+ * Tencent Cloud Credential via CVM role
+ *
+ * Automatically generates temporary credentials when binding a service role to instance.
+ * @see {@link https://cloud.tencent.com/document/product/598/85616} for more information.
+ */
 class CvmRoleCredential {
+    // Method to fetch the role name from the metadata server
     async getRoleName() {
         const response = await fetch_1.default(ROLE_URL, {});
         if (!response.ok) {
@@ -13,6 +20,7 @@ class CvmRoleCredential {
         }
         return await response.text();
     }
+    // Method to fetch credentials for a given role name
     async getRoleCredential(roleName) {
         const response = await fetch_1.default(ROLE_URL + roleName, {});
         if (!response.ok) {
@@ -24,6 +32,7 @@ class CvmRoleCredential {
         }
         return json;
     }
+    // Method to get the current credential, refreshing if expired
     async getCredential() {
         if (!this.roleNameTask) {
             this.roleNameTask = this.getRoleName();
@@ -33,7 +42,7 @@ class CvmRoleCredential {
             this.credentialTask = this.getRoleCredential(roleName);
         }
         const credential = await this.credentialTask;
-        // expired
+        // Check if the credential is expired
         if (credential.ExpiredTime * 1000 - EXPIRE_BUFFER <= Date.now()) {
             this.credentialTask = null;
             return this.getCredential();

package/tencentcloud/common/http/http_connection.js

@@ -34,8 +34,7 @@ class HttpConnection {
         return await fetch_1.default(url, config);
     }
     static async doRequestWithSign3({ method, url, data, service, action, region, version, secretId, secretKey, multipart = false, timeout = 60000, token, requestClient, language, headers = {}, agent, proxy, signal, }) {
-        // data 中可能带有 readStream，由于需要计算整个 body 的 hash，
-        // 所以这里把 readStream 转为 Buffer
+        // Convert readStream to Buffer to calculate the hash of the entire body
         // eslint-disable-next-line @typescript-eslint/no-use-before-define
         await convertReadStreamToBuffer(data);
         // eslint-disable-next-line @typescript-eslint/no-use-before-define

package/tencentcloud/common/interface.d.ts

@@ -1,116 +1,115 @@
 /// <reference types="node" />
 import { Agent } from "http";
 /**
- * 初始化client对象参数类型
+ * Configuration type for initializing client object
  */
 export interface ClientConfig {
     /**
-     * @param {Credential} credential 认证信息
-     * 必选
+     * @param {Credential} credential Authentication information
      */
     credential: Credential | DynamicCredential;
     /**
-     * @param {string} region 产品地域
-     * 对于要求区分地域的产品，此参数必选（如 cvm）；对于不区分地域的产品（如 sms），无需传入。
+     * @param {string} region Product region
+     * Required for region-specific products (e.g. CVM), optional for non-region products (e.g. SMS)
      */
     region?: string;
     /**
-     * @param {ClientProfile} profile 可选配置实例
-     * 可选，没有特殊需求可以跳过。
+     * @param {ClientProfile} profile Optional configuration instance
+     * Optional, can be skipped if no special requirements
      */
     profile?: ClientProfile;
 }
 /**
- * 可选配置实例
+ * Optional configuration instance
  */
 export interface ClientProfile {
     /**
-     * 签名方法 (TC3-HMAC-SHA256 HmacSHA1 HmacSHA256)
+     * Signature method (TC3-HMAC-SHA256 HmacSHA1 HmacSHA256)
      * @type {string}
-     * 非必选
+     * Optional
      */
     signMethod?: "TC3-HMAC-SHA256" | "HmacSHA256" | "HmacSHA1";
     /**
-     * http相关选项实例
+     * HTTP related options instance
      * @type {HttpProfile}
-     * 非必选
+     * Optional
      */
     httpProfile?: HttpProfile;
     /**
-     * api请求时附带的 language 字段
+     * Language field attached to API requests
      * @type {"zh-CN" | "en-US"}
-     * 非必选
+     * Optional
      */
     language?: "zh-CN" | "en-US";
 }
 export interface HttpProfile {
     /**
-     * 请求方法
+     * Request method
      * @type {"POST" | "GET"}
-     * 非必选
+     * Optional
      */
     reqMethod?: "POST" | "GET";
     /**
-     * 接入点域名，形如（cvm.ap-shanghai.tencentcloud.com）
+     * The service endpoint URL (e.g. "cvm.tencentcloudapi.com")
      * @type {string}
-     * 非必选
+     * Optional
      */
     endpoint?: string;
     /**
-     * 协议，目前支持（https://）
+     * Protocol, currently supports "https://"
      * @type {string}
-     * 非必选
+     * Optional
      */
     protocol?: string;
     /**
-     *  请求超时时间，默认60s
+     * Request timeout in seconds, default 60s
      * @type {number}
-     * 非必选
+     * Optional
      */
     reqTimeout?: number;
     /**
-     * 自定义请求头，例如 { "X-TC-TraceId": "ffe0c072-8a5d-4e17-8887-a8a60252abca" }
+     * Custom headers, e.g. { "X-TC-TraceId": "ffe0c072-8a5d-4e17-8887-a8a60252abca" }
      * @type {Record<string, string>}
-     * 非必选
+     * Optional
      */
     headers?: Record<string, string>;
     /**
-     * 高级请求代理，例如 new HttpsProxyAgent("http://127.0.0.1:8899")
+     * Advanced request agent, e.g. new HttpsProxyAgent("http://127.0.0.1:8899")
      *
-     * 优先级高于 proxy 配置
+     * Higher priority than proxy configuration
      */
     agent?: Agent;
     /**
-     * http请求代理，例如 "http://127.0.0.1:8899"
+     * HTTP request proxy, e.g. "http://127.0.0.1:8899"
      */
     proxy?: string;
 }
 /**
- * ClientProfile.language 属性支持的取值列表
+ * Supported values for ClientProfile.language property
  */
 export declare const SUPPORT_LANGUAGE_LIST: string[];
 /**
- * 认证信息类
+ * Credential information class
  */
 export interface Credential {
     /**
-     * 腾讯云账户secretId，secretKey
-     * 非必选，和 token 二选一
+     * Tencent Cloud account secretId and secretKey
+     * Optional, mutually exclusive with token
      */
     secretId?: string;
     /**
-     * 腾讯云账户secretKey
-     * 非必选，和 token 二选一
+     * Tencent Cloud account secretKey
+     * Optional, mutually exclusive with token
      */
     secretKey?: string;
     /**
-     * 腾讯云账户token
-     * 非必选，和 secretId 二选一
+     * Tencent Cloud account token
+     * Optional, mutually exclusive with secretId
      */
     token?: string;
 }
 /**
- * 动态认证信息
+ * Dynamic credential information
  */
 export interface DynamicCredential {
     getCredential(): Promise<Credential>;

package/tencentcloud/common/interface.js

@@ -2,6 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SUPPORT_LANGUAGE_LIST = void 0;
 /**
- * ClientProfile.language 属性支持的取值列表
+ * Supported values for ClientProfile.language property
  */
 exports.SUPPORT_LANGUAGE_LIST = ["zh-CN", "en-US"];

package/tencentcloud/common/sdk_version.d.ts

@@ -1 +1 @@
-export declare const sdkVersion = "4.1.64";
+export declare const sdkVersion = "4.1.66";

package/tencentcloud/common/sdk_version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sdkVersion = void 0;
-exports.sdkVersion = "4.1.64";
+exports.sdkVersion = "4.1.66";

package/tencentcloud/common/sign.js

@@ -24,7 +24,7 @@ class Sign {
     static sign3({ method = "POST", url = "", payload, timestamp, service, secretId, secretKey, multipart, boundary, headers: configHeaders = {}, }) {
         const urlObj = new url_1.URL(url);
         const contentType = configHeaders["Content-Type"];
-        // 通用头部
+        // general headers
         let headers = "";
         let signedHeaders = "";
         if (method === "GET") {

package/tencentcloud/common/sse_response_model.d.ts

@@ -9,25 +9,49 @@ interface EventSourceMessage {
     /** The reconnection interval (in milliseconds) to wait before retrying the connection */
     retry?: number;
 }
+/**
+ * Class to handle Server-Sent Events (SSE) responses.
+ * Parses SSE data from a readable stream and emits events for messages, errors, and stream closure.
+ */
 export declare class SSEResponseModel {
     private stream;
     private readline;
     private eventSource;
+    /**
+     * Constructs an SSEResponseModel instance.
+     * @param stream - The readable stream containing SSE data.
+     */
     constructor(stream: NodeJS.ReadableStream);
     /**
-     * @inner
+     * Initializes the SSE parser by setting up event listeners for the stream and readline.
      */
     private init;
     /**
-     * @inner
+     * Parses raw SSE lines into an EventSourceMessage object.
+     * @param lines - An array of raw SSE lines.
+     * @returns The parsed EventSourceMessage.
      */
     private parseSSEMessage;
+    /**
+     * Registers an event listener for SSE messages.
+     * @param event - The event type ("message", "close", or "error").
+     * @param listener - The callback function.
+     */
     on(event: "message", listener: (message: EventSourceMessage) => void): this;
     on(event: "close", listener: () => void): this;
     on(event: "error", listener: (err: Error) => void): this;
+    /**
+     * Removes an event listener for SSE messages.
+     * @param event - The event type ("message", "close", or "error").
+     * @param listener - The callback function.
+     */
     removeListener(event: "message", listener: (message: EventSourceMessage) => void): this;
     removeListener(event: "close", listener: () => void): this;
     removeListener(event: "error", listener: (err: Error) => void): this;
+    /**
+     * Provides an async iterator for consuming SSE messages.
+     * @returns An async iterator yielding parsed EventSourceMessage objects.
+     */
     [Symbol.asyncIterator](): AsyncIterableIterator<EventSourceMessage>;
 }
 export {};

package/tencentcloud/common/sse_response_model.js

@@ -3,9 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SSEResponseModel = void 0;
 const events_1 = require("events");
 const readline_1 = require("readline");
+// Custom EventEmitter for handling SSE events
 class SSEEventEmitter extends events_1.EventEmitter {
 }
+/**
+ * Class to handle Server-Sent Events (SSE) responses.
+ * Parses SSE data from a readable stream and emits events for messages, errors, and stream closure.
+ */
 class SSEResponseModel {
+    /**
+     * Constructs an SSEResponseModel instance.
+     * @param stream - The readable stream containing SSE data.
+     */
     constructor(stream) {
         this.stream = stream;
         this.readline = readline_1.createInterface({
@@ -16,7 +25,7 @@ class SSEResponseModel {
         this.init();
     }
     /**
-     * @inner
+     * Initializes the SSE parser by setting up event listeners for the stream and readline.
      */
     init() {
         const { stream, readline, eventSource } = this;
@@ -41,7 +50,9 @@ class SSEResponseModel {
         });
     }
     /**
-     * @inner
+     * Parses raw SSE lines into an EventSourceMessage object.
+     * @param lines - An array of raw SSE lines.
+     * @returns The parsed EventSourceMessage.
      */
     parseSSEMessage(lines) {
         const message = {
@@ -87,6 +98,10 @@ class SSEResponseModel {
         this.eventSource.removeListener(event, listener);
         return this;
     }
+    /**
+     * Provides an async iterator for consuming SSE messages.
+     * @returns An async iterator yielding parsed EventSourceMessage objects.
+     */
     async *[Symbol.asyncIterator]() {
         let lines = [];
         for await (const line of this.readline) {