@cn-quickotp/k3cloud-webapi-sdk 0.0.0-stage → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,168 @@
1
+ # CHANGELOG
2
+
3
+ ## [v2] - 2026-11-06
4
+ ### 变更类型:变更
5
+ ### 影响范围:包名、仓库元信息与许可署名
6
+ ### 变更内容:
7
+ - npm 包名改为 `@cn-quickotp/k3cloud-webapi-sdk`
8
+ - `package.json` 补充 `repository`、`homepage`、`bugs`、`keywords`
9
+ - `LICENSE` 版权人改为 `jundu2016 / cn-quickotp`
10
+ - `README.md`、`examples/`、`docs/` 同步新包名与项目名
11
+ - 新增 `docs/发布规划.md`:包元信息、发布门禁、CI、版本策略与发布步骤
12
+ ### 原因:
13
+ - 项目已推送至 `github.com/cn-quickotp/k3cloud-webapi-sdk`,包名与仓库、组织保持一致
14
+
15
+ ## [v2] - 2026-11-05
16
+ ### 变更类型:新增
17
+ ### 影响范围:T9 公共 API、文档与发布链路
18
+ ### 变更内容:
19
+ - 交付 `src/kernel/client.js`:装配层(传输层适配、Cookie 注入与响应头回传、凭证缺省合并、能力模块装配)
20
+ - `src/index.js` 收敛为 `SDK_VERSION`、`K3CloudError`、`createClient`、`createClientFromEnv` 四项公共导出
21
+ - `src/kernel/config.js` 新增 `fromEnvVars`,`src/modules/storage/env-loader.js` 改为再导出,避免 `fs` 进入浏览器 bundle
22
+ - 交付 `types/index.d.ts` 公开类型声明(`ClientConfig`、`Logger`、`FetchLike`、`BillService`、`MetadataService`、`Session`、`K3CloudClient`、`K3CloudError`)
23
+ - 交付 `README.md`(安装、快速开始、配置项表、错误码表)、`examples/node-cjs/`、`scripts/smoke.js`
24
+ - 交付 `tests/client.test.js`、`tests/publish.test.js`;AC-1—AC-7 全部由自动化用例或工程脚本覆盖
25
+ - 验收结果:AC-1—AC-7 全部通过(206 用例全绿、语句覆盖率 98.13%;`build`、`typecheck`、`lint`、`format:check`、`smoke` 退出码均 0;`npm pack --dry-run` 清单与 AC-G3 一致)
26
+ ### 原因:
27
+ - T9 任务完成,公共出口、类型声明、文档与发布门禁就绪
28
+
29
+ ## [v2] - 2026-11-04
30
+ ### 变更类型:新增
31
+ ### 影响范围:T8 日志与脱敏
32
+ ### 变更内容:
33
+ - 交付 `src/modules/logger.js`:`LOG_LEVELS`、`nullLogger`、`createLogger`、`redactRecord`、`logRecord`、`createRequestLog`
34
+ - `src/constants.js` 新增 `SENSITIVE_FIELDS`、`REDACTED`,`src/utils/redact.js` 改为引用该常量
35
+ - `src/kernel/request.js` 与 `src/modules/auth/session.js` 改用共享日志写出路径,移除各自的本地实现
36
+ - 交付 `tests/logger.test.js`,AC-1—AC-4 全部由单元用例覆盖
37
+ - 验收结果:AC-1—AC-4 全部通过(194 用例全绿、语句覆盖率 99.38%,`logger.js` 四项覆盖率均 100%)
38
+ ### 原因:
39
+ - T8 任务完成,请求生命周期日志与输出脱敏就绪,公共 API 装配(T9)可注入日志器
40
+
41
+ ## [v2] - 2026-11-04
42
+ ### 变更类型:新增
43
+ ### 影响范围:T7 元数据查询
44
+ ### 变更内容:
45
+ - 交付 `src/modules/services/metadata.js`:`createMetadataService`(`queryBusinessInfo`)、`defaultParseMetadata`、`METADATA_ENDPOINTS`
46
+ - 交付 `tests/metadata.test.js`,AC-1—AC-5 全部由单元用例覆盖
47
+ - 验收结果:AC-1—AC-5 全部通过(170 用例全绿、语句覆盖率 99.33%,`metadata.js` 四项覆盖率均 100%)
48
+ ### 原因:
49
+ - T7 任务完成,单据元数据查询与实例内缓存就绪,公共 API 装配(T9)可接入该模块
50
+
51
+ ## [v2] - 2026-11-04
52
+ ### 变更类型:新增
53
+ ### 影响范围:T6 单据操作
54
+ ### 变更内容:
55
+ - 交付 `src/modules/services/bill.js`:`createBillService`(`save` / `view` / `submit` / `audit` / `unAudit` / `delete` / `executeBillQuery`)、`defaultIsBusinessSuccess`、`defaultParseResponse`、`BILL_ENDPOINTS`
56
+ - `src/constants.js` 新增 `METHODS.VIEW`
57
+ - 交付 `tests/bill.test.js`,AC-1—AC-5 全部由单元用例覆盖
58
+ - 验收结果:AC-1—AC-5 全部通过(151 用例全绿、语句覆盖率 99.28%,`bill.js` 四项覆盖率均 100%)
59
+ ### 原因:
60
+ - T6 任务完成,单据保存、查看、提交、审核、反审核、删除与单据查询就绪,元数据模块(T7)可复用同一解析扩展点
61
+
62
+ ## [v2] - 2026-11-04
63
+ ### 变更类型:新增
64
+ ### 影响范围:T5 认证与会话
65
+ ### 变更内容:
66
+ - 交付 `src/modules/auth/login.js`:`login`(按凭证形态分派)、`loginByPassword`、`loginByAppSecret`、`isLoginSuccess`、`extractCookie`、`resolveCredentials`、`LOGIN_ENDPOINTS`
67
+ - 交付 `src/modules/auth/session.js`:`createSession`(`isAuthenticated`/`getState`/`getCookie`/`login`/`logout`/`execute`)、`defaultIsSessionExpired`、`LOGOUT_ENDPOINT`
68
+ - `src/constants.js` 新增 `METHODS.LOGIN_BY_APP_SECRET`、`METHODS.LOGOUT`
69
+ - 交付 `tests/auth-login.test.js`、`tests/auth-session.test.js`,AC-1—AC-6 全部由单元用例覆盖
70
+ - 验收结果:AC-1—AC-6 全部通过(126 用例全绿、语句覆盖率 99.18%,auth 两模块语句覆盖率 100%)
71
+ ### 原因:
72
+ - T5 任务完成,登录态与续期就绪,业务模块(T6、T7)可只依赖会话与传输层
73
+
74
+ ## [v2] - 2026-11-04
75
+ ### 变更类型:新增
76
+ ### 影响范围:T4 HTTP 传输层
77
+ ### 变更内容:
78
+ - 交付 `src/kernel/request.js`:`request`(URL 拼接、完整封装构造、超时控制、退避重试、错误归一化、日志埋点)、`buildRequestBody`、`truncate`
79
+ - 交付 `src/utils/retry.js`:`backoffDelay`(`retryBaseDelay * 2^n`)、`delay`、`isRetryable`(仅网络错误与 5xx)
80
+ - 交付 `tests/request.test.js`、`tests/retry.test.js`;AC-5 由「真实 `fetch` 打本地临时端口桩服务」覆盖
81
+ - 验收结果:AC-1—AC-6 全部通过(80 用例全绿、语句覆盖率 98.63%,`request.js` 语句覆盖率 100%)
82
+ ### 原因:
83
+ - T4 任务完成,统一请求出口与错误归一化就绪,可进入 T5
84
+
85
+ ## [v2] - 2026-11-04
86
+ ### 变更类型:新增
87
+ ### 影响范围:T3 配置内核
88
+ ### 变更内容:
89
+ - 交付 `src/kernel/config.js`(四级来源合并、必填校验、`serverUrl` 归一化)
90
+ - 交付 `src/modules/storage/env-loader.js`(`.env` 解析与载入)、`src/modules/storage/browser-config.js`(浏览器 localStorage 配置)
91
+ - 交付 `src/utils/redact.js`(敏感字段脱敏)
92
+ - `src/constants.js` 扩充 `ENV_KEYS`、`STORAGE_KEYS`;ESLint 增加 browser 环境覆盖
93
+ - 验收结果:AC-1—AC-6 全部通过
94
+ ### 原因:
95
+ - T3 任务完成,配置来源与脱敏就绪,可进入 T4
96
+
97
+ ## [v2] - 2026-11-04
98
+ ### 变更类型:新增
99
+ ### 影响范围:T2 常量与错误体系
100
+ ### 变更内容:
101
+ - 交付 `src/constants.js`:endpoint 前缀/后缀、`SERVICES`、`METHODS`、`DEFAULTS`、`ENVELOPE_FIELDS`、`ENVELOPE_VALUES`、`buildEndpoint`、`buildEnvelope`
102
+ - 交付 `src/errors.js`:`K3CloudError`(`code`/`message`/`cause`/`details`)与 `ERROR_CODES` 八类
103
+ - 交付 `tests/constants.test.js`、`tests/errors.test.js`
104
+ - 验收结果:AC-1—AC-5 全部通过
105
+ ### 原因:
106
+ - T2 任务完成,协议常量与错误表达就绪,可进入 T3
107
+
108
+ ## [v2] - 2026-11-04
109
+ ### 变更类型:新增
110
+ ### 影响范围:T1 工程骨架与工具链
111
+ ### 变更内容:
112
+ - 交付 `package.json`(CommonJS 入口/`exports`/`files`/`license`/脚本)、`rollup.config.js` + `@rollup/plugin-commonjs`、`jest.config.js`、`tsconfig.json`、ESLint/Prettier 配置、`.gitignore`、`LICENSE`(MulanPSL-2.0)
113
+ - 交付 `src/version.js`、`src/index.js`、`types/index.d.ts`、`README.md`(占位)与 `tests/version.test.js`、`tests/package.test.js`
114
+ - 验收结果:AC-1—AC-6 全部通过
115
+ ### 原因:
116
+ - T1 任务完成,工具链就绪,可进入 T2
117
+
118
+ ## [v2] - 2026-11-04
119
+ ### 变更类型:修改
120
+ ### 影响范围:全局 SPEC、CHARTER、9 份子 SPEC、SDK 开发规划
121
+ ### 变更内容:
122
+ - 评审通过,全部文档状态由 Review 流转为 Active
123
+ - 全局任务 T1(工程骨架与工具链)开工
124
+ ### 原因:
125
+ - 评审方确认 SPEC,允许进入实施阶段
126
+
127
+ ## [v2] - 2026-11-04
128
+ ### 变更类型:修改
129
+ ### 影响范围:全局 SPEC、CHARTER、9 份子 SPEC、SDK 开发规划
130
+ ### 变更内容:
131
+ - 全局任务列表补齐负责人字段;9 份子 SPEC 元信息补齐负责人字段
132
+ - 全部文档状态由 Draft 提交为 Review,进入评审
133
+ ### 原因:
134
+ - 满足 spec-doc R-2.1、R-3.4、R-6.1 的提交评审合规要求
135
+
136
+ ## [v2] - 2026-11-04
137
+ ### 变更类型:修改
138
+ ### 影响范围:全局 SPEC、CHARTER、9 份子 SPEC、package.json
139
+ ### 变更内容:
140
+ - 产物形态由 ESM-only 改为 CommonJS-only:`main`/`exports` 指向 `dist/index.js`,`types` 指向 `types/index.d.ts`
141
+ - 构建工具引入 Rollup;测试框架由 vitest 改为 Jest
142
+ - `package.json` 移除 `type: module`、`axios`、`dotenv`、`vitest` 相关依赖,`dependencies`/`optionalDependencies` 置空
143
+ - 全局 SPEC 新增 D-7(测试与类型约定);验收总纲改为 CommonJS 入口校验
144
+ - T1、T9 子 SPEC 按 CommonJS 工具链重写;其余子 SPEC 同步版本与父 SPEC 引用
145
+ - 新增 `docs/SDK开发规划.md` 作为架构与模块设计依据
146
+ ### 原因:
147
+ - 目标产物明确为 CommonJS,供其他项目 `require()` 使用
148
+ - `@prosdevlab/sdk-kit` 为纯 ESM 且依赖 TypeScript,不符合 CommonJS 交付要求,故自研最小框架
149
+
150
+ ## [v1] - 2026-10-28
151
+ ### 变更类型:新增
152
+ ### 影响范围:全局
153
+ ### 变更内容:
154
+ - 项目立项:立项单(`docs/CHARTER.md`)、全局 SPEC(`docs/SPEC.md`)与 9 份子 SPEC(`docs/specs/`)创建,状态置 Draft,待评审
155
+ ### 原因:
156
+ - 项目正式立项,建立执行依据与验收基线
157
+
158
+ ## [v1] - 2026-10-28
159
+ ### 变更类型:修改
160
+ ### 影响范围:全局 SPEC、9 份子 SPEC、立项单
161
+ ### 变更内容:
162
+ - 移除全部负责人与排期字段(立项单发起人/负责人、全局 SPEC 任务表负责人列、风险 R-4、同步机制责任人、子 SPEC 元信息负责人)
163
+ - 立项单"初步资源"改为"前置依赖",仅保留接口清单与运行环境
164
+ - 新增 `docs/接口报文采集清单.md` 与 `scripts/capture.mjs`,为风险 R-1、R-2 提供报文采集路径
165
+ - T6 增加 `view` 能力,与立项单"单据 CRUD 含 Query"对齐
166
+ ### 原因:
167
+ - 项目不做负责人与排期管控
168
+ - 协议常量与序列化语义需以真实报文校正
package/LICENSE ADDED
@@ -0,0 +1,102 @@
1
+ Copyright (c) 2026 jundu2016 / cn-quickotp
2
+ @cn-quickotp/k3cloud-webapi-sdk is licensed under Mulan PSL v2.
3
+ You can use this software according to the terms and conditions of the Mulan PSL v2.
4
+ You may obtain a copy of Mulan PSL v2 at:
5
+ http://license.coscl.org.cn/MulanPSL2
6
+
7
+ THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
8
+ See the Mulan PSL v2 for more details.
9
+
10
+ ---
11
+
12
+ 木兰宽松许可证,第2版
13
+
14
+ 2020年1月
15
+ http://license.coscl.org.cn/MulanPSL2
16
+
17
+ 您对"软件"的复制、使用、修改及分发受木兰宽松许可证,第2版("本许可证")的如下条款的约束:
18
+
19
+ 0. 定义
20
+
21
+ "软件" 是指由"贡献"构成的许可在"本许可证"下的程序和相关文档的集合。
22
+
23
+ "贡献" 是指由任一"贡献者"许可在"本许可证"下的受版权法保护的作品。
24
+
25
+ "贡献者" 是指将受版权法保护的作品许可在"本许可证"下的自然人或"法人实体"。
26
+
27
+ "法人实体" 是指提交贡献的机构及其"关联实体"。
28
+
29
+ "关联实体" 是指,对"本许可证"下的行为方而言,控制、受控制或与其共同受控制的机构,此处的控制是指有受控方或共同受控方至少50%直接或间接的投票权、资金或其他有价证券。
30
+
31
+ 1. 授予版权许可
32
+
33
+ 每个"贡献者"根据"本许可证"授予您永久性的、全球性的、免费的、非独占的、不可撤销的版权许可,您可以复制、使用、修改、分发其"贡献",不论修改与否。
34
+
35
+ 2. 授予专利许可
36
+
37
+ 每个"贡献者"根据"本许可证"授予您永久性的、全球性的、免费的、非独占的、不可撤销的(根据本条规定撤销除外)专利许可,供您制造、委托制造、使用、许诺销售、销售、进口其"贡献"或以其他方式转移其"贡献"。前述专利许可仅限于"贡献者"现在或将来拥有或控制的其"贡献"本身或其"贡献"与许可"贡献"时的"软件"结合而将必然会侵犯的专利权利要求,不包括对"贡献"的修改或包含"贡献"的其他结合。如果您或您的"关联实体"直接或间接地,就"软件"或其中的"贡献"对任何人发起专利侵权诉讼(包括反诉或交叉诉讼)或其他专利维权行动,指控其侵犯专利权,则"本许可证"授予您对"软件"的专利许可自您提起诉讼或发起维权行动之日终止。
38
+
39
+ 3. 无商标许可
40
+
41
+ "本许可证"不提供对"贡献者"的商品名称、商标、服务标志或产品名称的商标许可,但您为满足第4条规定的声明义务而必须使用除外。
42
+
43
+ 4. 分发限制
44
+
45
+ 您可以在任何媒介中将"软件"以源程序形式或可执行形式重新分发,不论修改与否,但您必须向接收者提供"本许可证"的副本,并保留"软件"中的版权、商标、专利及免责声明。
46
+
47
+ 5. 免责声明与责任限制
48
+
49
+ "软件"及其中的"贡献"在提供时不带任何明示或默示的担保。在任何情况下,"贡献者"或版权所有者不对任何人因使用"软件"或其中的"贡献"而引发的任何直接或间接损失承担责任,不论因何种原因导致或者基于何种法律理论,即使其曾被建议有此种损失的可能性。
50
+
51
+ 6. 语言
52
+
53
+ "本许可证"以中英文双语表述,中英文版本具有同等法律效力。如果中英文版本存在任何冲突不一致,以中文版为准。
54
+
55
+ 条款结束
56
+
57
+ ---
58
+
59
+ Mulan Permissive Software License,Version 2
60
+
61
+ January 2020
62
+ http://license.coscl.org.cn/MulanPSL2
63
+
64
+ Your reproduction, use, modification and distribution of the Software shall be subject to Mulan PSL v2 (this License) with the following terms and conditions:
65
+
66
+ 0. Definition
67
+
68
+ Software means the program and related documents which are licensed under this License and comprise all Contribution(s).
69
+
70
+ Contribution means the copyrightable work licensed by a particular Contributor under this License.
71
+
72
+ Contributor means the Individual or Legal Entity who licenses its copyrightable work under this License.
73
+
74
+ Legal Entity means the entity making a Contribution and all its Affiliates.
75
+
76
+ Affiliates means entities that control, are controlled by, or are under common control with the acting entity under this License, 'control' means direct or indirect ownership of at least fifty percent (50%) of the voting power, capital or other securities of controlled or commonly controlled entity.
77
+
78
+ 1. Grant of Copyright License
79
+
80
+ Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable copyright license to reproduce, use, modify, or distribute its Contribution, with modification or not.
81
+
82
+ 2. Grant of Patent License
83
+
84
+ Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable (except for revocation under this Section) patent license to make, have made, use, offer for sale, sell, import or otherwise transfer its Contribution, where such patent license is only limited to the patent claims owned or controlled by such Contributor now or in future which will be necessarily infringed by its Contribution alone, or by combination of the Contribution with the Software to which the Contribution was contributed. The patent license shall not apply to any modification of the Contribution, and any other combination which includes the Contribution. If you or your Affiliates directly or indirectly institute patent litigation (including a cross claim or counterclaim in a litigation) or other patent enforcement activities against any individual or entity by alleging that the Software or any Contribution in it infringes patents, then any patent license granted to you under this License for the Software shall terminate as of the date such litigation or activity is filed or taken.
85
+
86
+ 3. No Trademark License
87
+
88
+ No trademark license is granted to use the trade names, trademarks, service marks, or product names of Contributor, except as required to fulfill notice requirements in section 4.
89
+
90
+ 4. Distribution Restriction
91
+
92
+ You may distribute the Software in any medium with or without modification, whether in source or executable forms, provided that you provide recipients with a copy of this License and retain copyright, patent, trademark and disclaimer statements in the Software.
93
+
94
+ 5. Disclaimer of Warranty and Limitation of Liability
95
+
96
+ THE SOFTWARE AND CONTRIBUTION IN IT ARE PROVIDED WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL ANY CONTRIBUTOR OR COPYRIGHT HOLDER BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO ANY DIRECT, OR INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM YOUR USE OR INABILITY TO USE THE SOFTWARE OR THE CONTRIBUTION IN IT, NO MATTER HOW IT'S CAUSED OR BASED ON WHICH LEGAL THEORY, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
97
+
98
+ 6. Language
99
+
100
+ THIS LICENSE IS WRITTEN IN BOTH CHINESE AND ENGLISH, AND THE CHINESE VERSION AND ENGLISH VERSION SHALL HAVE THE SAME LEGAL EFFECT. IN THE CASE OF DIVERGENCE BETWEEN THE CHINESE AND ENGLISH VERSIONS, THE CHINESE VERSION SHALL PREVAIL.
101
+
102
+ END OF THE TERMS AND CONDITIONS
package/README.md CHANGED
@@ -1,3 +1,105 @@
1
- # Temporary Holding Version
1
+ # @cn-quickotp/k3cloud-webapi-sdk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 金蝶云星空 WebAPI 的 JavaScript SDK(CommonJS,运行时零依赖)。
4
+
5
+ ## 安装
6
+
7
+ ```bash
8
+ npm install @cn-quickotp/k3cloud-webapi-sdk
9
+ ```
10
+
11
+ 要求 Node.js >= 18;浏览器环境直接使用全局 `fetch`,无需额外依赖。
12
+
13
+ ## 快速开始
14
+
15
+ ```js
16
+ const { createClient, K3CloudError } = require('@cn-quickotp/k3cloud-webapi-sdk');
17
+
18
+ const client = createClient({
19
+ serverUrl: 'https://example.k3cloud.com/K3Cloud/',
20
+ acctId: '000000',
21
+ username: 'demo',
22
+ password: '******',
23
+ appKey: 'your-app-key',
24
+ appSec: 'your-app-sec',
25
+ });
26
+
27
+ try {
28
+ await client.login();
29
+
30
+ const saved = await client.bill.save('SAL_SaleOrder', {
31
+ FormId: 'SAL_SaleOrder',
32
+ Data: { FBillerId: 'A001' },
33
+ });
34
+
35
+ const rows = await client.bill.executeBillQuery({
36
+ FormId: 'SAL_SaleOrder',
37
+ FieldKeys: 'FBillNo',
38
+ TopRowCount: 20,
39
+ });
40
+
41
+ const meta = await client.metadata.queryBusinessInfo('SAL_SaleOrder');
42
+ } catch (err) {
43
+ if (err instanceof K3CloudError) {
44
+ console.error(err.code, err.message);
45
+ }
46
+ } finally {
47
+ await client.logout();
48
+ }
49
+ ```
50
+
51
+ ### 由环境变量创建
52
+
53
+ ```js
54
+ const { createClientFromEnv } = require('@cn-quickotp/k3cloud-webapi-sdk');
55
+
56
+ const client = createClientFromEnv();
57
+ ```
58
+
59
+ 对应环境变量:`K3CLOUD_SERVER_URL`、`K3CLOUD_ACCT_ID`、`K3CLOUD_USERNAME`、`K3CLOUD_PASSWORD`、`K3CLOUD_APP_KEY`、`K3CLOUD_APP_SEC`、`K3CLOUD_LANG`。
60
+
61
+ ### 浏览器
62
+
63
+ 浏览器环境从 `localStorage` 的 `k3cloud.*` 键读取配置,并使用全局 `fetch`。
64
+
65
+ ## 配置项
66
+
67
+ | 配置项 | 类型 | 必填 | 默认值 | 说明 |
68
+ | -------------- | -------- | ---- | --------------------------- | ------------------------------------------------ |
69
+ | serverUrl | string | 是 | `http://localhost/K3Cloud/` | 服务根地址,结尾 `/` 可省略 |
70
+ | acctId | string | 是 | — | 账套 ID |
71
+ | username | string | 是 | — | 登录用户名 |
72
+ | password | string | 是 | — | 登录密码 |
73
+ | appKey | string | 是 | — | 应用 Key |
74
+ | appSec | string | 是 | — | 应用密钥 |
75
+ | lang | number | 否 | 2052 | 语言标识 |
76
+ | timeout | number | 否 | 30000 | 单次请求超时(毫秒) |
77
+ | retries | number | 否 | 3 | 网络错误与 5xx 的重试次数 |
78
+ | retryBaseDelay | number | 否 | 500 | 重试退避基数(毫秒) |
79
+ | logger | object | 否 | — | 日志器,需含 `debug` / `info` / `warn` / `error` |
80
+ | fetchImpl | function | 否 | 全局 `fetch` | 自定义 fetch 实现,用于测试或特殊运行时 |
81
+
82
+ 优先级:默认值 < 环境变量 < 显式传入。必填项缺失时抛出 `VALIDATION` 错误并列出全部缺失字段。
83
+
84
+ ## 错误码
85
+
86
+ | code | 说明 |
87
+ | ---------- | ---------------------------- |
88
+ | VALIDATION | 配置或参数校验失败 |
89
+ | AUTH | 登录凭证缺失或登录失败 |
90
+ | SESSION | 会话失效且重新登录后仍未通过 |
91
+ | NETWORK | 网络请求失败 |
92
+ | TIMEOUT | 请求超时 |
93
+ | HTTP | HTTP 非 2xx 响应 |
94
+ | PARSE | 响应体解析失败 |
95
+ | BUSINESS | 业务处理失败 |
96
+
97
+ 所有错误均为 `K3CloudError` 实例,含 `code`、`message` 与 `details`;日志输出对 `password`、`appSec` 自动脱敏。
98
+
99
+ ## 示例
100
+
101
+ 可运行示例见 `examples/node-cjs/`。
102
+
103
+ ## 许可
104
+
105
+ MulanPSL-2.0