@qzsy/group-sdk 0.1.2 → 0.1.3

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 CHANGED
@@ -1,13 +1,28 @@
1
1
  # 变更记录
2
2
 
3
+ ## 0.1.3
4
+
5
+ ### 变更
6
+
7
+ - 常量改为从 `@qzsy/unipay-sdk` 复用(`GROUP_LIMITS` / `GROUP_STATEMENT_SCOPES`),不再在本包维护副本;契约校验脚本改为比对 SDK 与网关
8
+ - 操作人示例改为 ASCII;SDK 会在发请求前拒绝中文操作人名
9
+ - `withOperator()` 显式重建客户端(复制凭据与 fetch),换身份后的首个请求会重新取令牌
10
+ - 声明 Node ≥ 20.19(CJS 产物通过 `require(esm)` 依赖 ESM-only 的 `@qzsy/unipay-sdk`)
11
+ - 类型检查纳入测试文件(`tsconfig.test.json`);构建不再产出指向未发布源码的 `.d.ts.map`
12
+
13
+ ### 升级说明
14
+
15
+ - 依赖 `@qzsy/unipay-sdk@^0.3.2`
16
+ - 公开 API 不变
17
+
3
18
  ## 0.1.2
4
19
 
5
20
  ### 重构(不改变对外行为)
6
21
 
7
22
  - 按职责拆分为 `client.ts`(客户端)/ `constants.ts`(上限与 scope)/ `errors.ts`(错误文案),`index.ts` 只做导出
8
23
  - 默认操作人合并下沉到 `@qzsy/unipay-sdk` 的 `GroupClient.defaultOperator`:本包不再逐个覆写 5 个写方法,新增写接口不会漏带操作人
9
- - 操作人只随写请求(带幂等键)发送,读请求不再携带
10
- - `describeGroupError` 去掉多余类型断言,直接用 `GatewayError.problem`
24
+ - 操作人只随写请求(带幂等键)发送;读请求继续保持不携带(新增传输层门禁,防止将来给读方法传 options 时泄漏)
25
+ - `describeGroupError` 去掉多余类型断言,网关错误直接用 `message`
11
26
  - 新增 `scripts/check-group-contract.ts` 校验本包常量与网关 `group-queries.ts` 一致
12
27
 
13
28
  ### 升级说明
package/README.md CHANGED
@@ -4,8 +4,8 @@
4
4
 
5
5
  底层 HTTP、OAuth 令牌缓存、错误模型全部复用 [`@qzsy/unipay-sdk`](https://www.npmjs.com/package/@qzsy/unipay-sdk),所以集团侧只需要安装这一个包:应用维度(下单、收银台、退款、付款)的能力也一并可用。
6
6
 
7
- - Node.js ≥ 18(使用原生 `fetch`,无运行时依赖)
8
- - ESM / CJS / TypeScript 类型三者齐全
7
+ - Node.js ≥ 20.19(原生 `fetch` 与 `require(esm)`;无运行时依赖)
8
+ - ESM / CJS / TypeScript 类型三者齐全(CJS 依赖 Node ≥ 20.19 的 `require(esm)`;更早版本请用 ESM 入口)
9
9
  - 金额一律「分」为单位,时间一律 ISO 8601 字符串
10
10
 
11
11
  ## 安装
@@ -53,6 +53,7 @@ const { entity } = await group.createEntity({
53
53
  const { application, credential } = await group.createApplication({
54
54
  entity_id: entity.id,
55
55
  name: '西湖店小程序',
56
+ slug: 'xihu-mini', // 组织内唯一;留空会按名称生成,生成不出合法 slug 时必填
56
57
  wechat_app_id: 'wx1234567890abcdef',
57
58
  })
58
59
 
@@ -140,17 +141,18 @@ const { items: payouts, next_cursor } = await group.listGroupPayouts({
140
141
  const group = createGroupClient({ baseUrl, clientId, clientSecret, operator })
141
142
 
142
143
  // 方式二:换一个身份(复用同一套凭据)
143
- const asStoreManager = group.withOperator({ id: 'store_1_manager', name: '店长' })
144
+ const asStoreManager = group.withOperator({ id: 'store_1_manager', name: 'Store Manager' })
144
145
 
145
146
  // 单次覆盖
146
- await group.createEntity(input, { operator: { id: 'manager_2', name: '运营' } })
147
+ await group.createEntity(input, { operator: { id: 'manager_2', name: 'Ops' } })
147
148
  ```
148
149
 
149
- > 请求头只能放 ASCII,姓名请用拼音或英文。操作人只随写请求(带幂等键)发送,读请求不带。
150
+ > 三个字段都会进 HTTP 头,**只能使用 ASCII 可见字符**(中文名会被 SDK 在发请求前拒绝,报「只能使用 ASCII 可见字符」)。操作人只随写请求(同时带幂等键)发送,读请求不带。
151
+ > `withOperator()` 复用同一套凭据,但令牌缓存是实例级的 —— 换身份后的第一个请求会重新取一次令牌。
150
152
 
151
153
  ## 幂等
152
154
 
153
- 所有写接口自动携带 `Idempotency-Key`(首次调用生成,重试同一客户端实例会复用)。业务侧更应依赖自然幂等键:
155
+ 所有写接口自动携带 `Idempotency-Key`(每次调用生成;401 刷新令牌后的自动重试会复用同一把键)。**网络超时后请自行重试并显式传 `{ idempotencyKey }` 复用**,否则会生成新键。业务侧更应依赖自然幂等键:
154
156
 
155
157
  - W-1 建主体:`license_no` 相同 → 返回已有主体
156
158
  - W-2 建应用:`(entity_id, slug, LIVE)` 相同 → 返回已有应用,`credential` 为 `null`
package/dist/client.d.ts CHANGED
@@ -9,6 +9,8 @@ export interface GroupSdkOptions extends Omit<GroupClientOptions, 'defaultOperat
9
9
  /**
10
10
  * 默认操作人:集团总管理员代门店操作时上报,网关写入审计与审批单。
11
11
  * 单个调用也可以用 `{ operator }` 覆盖。
12
+ *
13
+ * 三个字段都会进 HTTP 头,**只能使用 ASCII 可见字符**(中文名会被 SDK 提前拒绝)。
12
14
  */
13
15
  operator?: GroupOperator;
14
16
  }
@@ -19,13 +21,15 @@ export interface GroupSdkOptions extends Omit<GroupClientOptions, 'defaultOperat
19
21
  * 操作人合并在基类的传输层完成,这里不再逐方法覆写。
20
22
  */
21
23
  export declare class GroupSdkClient extends GroupClient {
22
- private readonly sdkOptions;
23
24
  constructor(options: GroupSdkOptions);
24
25
  /** 构造时配置的默认操作人 */
25
26
  get defaultOperator(): GroupOperator | undefined;
26
- /** 换一个默认操作人:复用同一套凭据与 fetch 实现,返回新客户端 */
27
+ /**
28
+ * 换一个默认操作人:复用同一套凭据与 fetch 实现,返回新客户端。
29
+ *
30
+ * 注意令牌缓存是实例级的,换身份后的第一个请求会重新取一次令牌。
31
+ */
27
32
  withOperator(operator: GroupOperator): GroupSdkClient;
28
33
  }
29
34
  /** 创建集团客户端(推荐入口) */
30
35
  export declare function createGroupClient(options: GroupSdkOptions): GroupSdkClient;
31
- //# sourceMappingURL=client.d.ts.map
@@ -1,18 +1,8 @@
1
1
  /**
2
- * 与网关侧 `apps/web/src/biz-gateway/group-queries.ts` 的 `GROUP_LIMITS` 保持一致,
3
- * 改网关上限时同步改这里(`scripts/check-group-contract.ts` 会做一致性校验)。
2
+ * 集团接口的公共契约常量。
3
+ *
4
+ * 这两个常量来自 `@qzsy/unipay-sdk`(契约层只保留一份定义),这里重新导出,
5
+ * 方便集团侧只依赖 `@qzsy/group-sdk` 一个包。
4
6
  */
5
- export declare const GROUP_LIMITS: {
6
- /** 普通列表默认条数 */
7
- readonly list: 100;
8
- /** 单页上限(可显式传 limit,服务端会截断) */
9
- readonly page: 500;
10
- /** 全量快照每个维度的条数 */
11
- readonly snapshot: 200;
12
- /** 账单详情/CSV 的明细行上限 */
13
- readonly statementLines: 1000;
14
- };
15
- /** 账单查询可用的 scope(G-6) */
16
- export declare const GROUP_STATEMENT_SCOPES: readonly ['ORG', 'ENTITY', 'STORE'];
17
- export type GroupStatementScope = (typeof GROUP_STATEMENT_SCOPES)[number];
18
- //# sourceMappingURL=constants.d.ts.map
7
+ export { GROUP_LIMITS, GROUP_STATEMENT_SCOPES } from '@qzsy/unipay-sdk';
8
+ export type { GroupStatementScope } from '@qzsy/unipay-sdk';
package/dist/errors.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  /**
2
- * 把任意错误整理成可展示的文案:优先用网关返回的 `problem.detail`,
3
- * 其次 `problem.title`,再回退 `message`。
2
+ * 把任意错误整理成可展示的文案:网关错误直接用 `message`(`GatewayError` 已经把
3
+ * `problem.detail`/`problem.title` 合成为 message),其它错误取 `message`,兜底「未知错误」。
4
4
  *
5
5
  * ```ts
6
6
  * try {
@@ -11,4 +11,3 @@
11
11
  * ```
12
12
  */
13
13
  export declare function describeGroupError(error: unknown): string;
14
- //# sourceMappingURL=errors.d.ts.map
package/dist/index.cjs CHANGED
@@ -57,8 +57,8 @@ var __export = (target, all) => {
57
57
  // src/index.ts
58
58
  var exports_src = {};
59
59
  __export(exports_src, {
60
- GROUP_LIMITS: () => GROUP_LIMITS,
61
- GROUP_STATEMENT_SCOPES: () => GROUP_STATEMENT_SCOPES,
60
+ GROUP_LIMITS: () => import_unipay_sdk2.GROUP_LIMITS,
61
+ GROUP_STATEMENT_SCOPES: () => import_unipay_sdk2.GROUP_STATEMENT_SCOPES,
62
62
  GroupSdkClient: () => GroupSdkClient,
63
63
  createGroupClient: () => createGroupClient,
64
64
  describeGroupError: () => describeGroupError
@@ -75,8 +75,8 @@ __export(exports_client, {
75
75
  // src/constants.ts
76
76
  var exports_constants = {};
77
77
  __export(exports_constants, {
78
- GROUP_LIMITS: () => GROUP_LIMITS,
79
- GROUP_STATEMENT_SCOPES: () => GROUP_STATEMENT_SCOPES
78
+ GROUP_LIMITS: () => import_unipay_sdk2.GROUP_LIMITS,
79
+ GROUP_STATEMENT_SCOPES: () => import_unipay_sdk2.GROUP_STATEMENT_SCOPES
80
80
  });
81
81
 
82
82
  // src/errors.ts
@@ -89,37 +89,35 @@ __export(exports_errors, {
89
89
  var import_unipay_sdk = require("@qzsy/unipay-sdk");
90
90
 
91
91
  class GroupSdkClient extends import_unipay_sdk.GroupClient {
92
- sdkOptions;
93
92
  constructor(options) {
94
93
  const { operator, ...clientOptions } = options;
95
94
  super({ ...clientOptions, ...operator ? { defaultOperator: operator } : {} });
96
- this.sdkOptions = options;
97
95
  }
98
96
  get defaultOperator() {
99
- return this.sdkOptions.operator;
97
+ return this.groupOperator;
100
98
  }
101
99
  withOperator(operator) {
102
- return new GroupSdkClient({ ...this.sdkOptions, operator });
100
+ return new GroupSdkClient({
101
+ baseUrl: this.baseUrl,
102
+ clientId: this.clientId,
103
+ clientSecret: this.clientSecret,
104
+ scope: this.scope,
105
+ fetch: this.fetchImpl,
106
+ tokenRefreshSkewSeconds: this.tokenRefreshSkewSeconds,
107
+ operator
108
+ });
103
109
  }
104
110
  }
105
111
  function createGroupClient(options) {
106
112
  return new GroupSdkClient(options);
107
113
  }
108
114
  // src/constants.ts
109
- var GROUP_LIMITS = {
110
- list: 100,
111
- page: 500,
112
- snapshot: 200,
113
- statementLines: 1000
114
- };
115
- var GROUP_STATEMENT_SCOPES = ["ORG", "ENTITY", "STORE"];
116
- // src/errors.ts
117
115
  var import_unipay_sdk2 = require("@qzsy/unipay-sdk");
116
+ // src/errors.ts
117
+ var import_unipay_sdk3 = require("@qzsy/unipay-sdk");
118
118
  function describeGroupError(error) {
119
- if (import_unipay_sdk2.isGatewayError(error)) {
120
- const problem = error.problem;
121
- return problem.detail || problem.title || error.message || "网关返回了错误";
122
- }
119
+ if (import_unipay_sdk3.isGatewayError(error))
120
+ return error.message || "网关返回了错误";
123
121
  if (error instanceof Error)
124
122
  return error.message;
125
123
  return "未知错误";
package/dist/index.d.ts CHANGED
@@ -24,4 +24,3 @@ export { describeGroupError } from './errors';
24
24
  * 应用维度(下单/收银台/退款/付款)的能力与 `GroupClient` 在这里一并转出。
25
25
  */
26
26
  export * from '@qzsy/unipay-sdk';
27
- //# sourceMappingURL=index.d.ts.map
package/dist/index.js CHANGED
@@ -2,37 +2,35 @@
2
2
  import { GroupClient } from "@qzsy/unipay-sdk";
3
3
 
4
4
  class GroupSdkClient extends GroupClient {
5
- sdkOptions;
6
5
  constructor(options) {
7
6
  const { operator, ...clientOptions } = options;
8
7
  super({ ...clientOptions, ...operator ? { defaultOperator: operator } : {} });
9
- this.sdkOptions = options;
10
8
  }
11
9
  get defaultOperator() {
12
- return this.sdkOptions.operator;
10
+ return this.groupOperator;
13
11
  }
14
12
  withOperator(operator) {
15
- return new GroupSdkClient({ ...this.sdkOptions, operator });
13
+ return new GroupSdkClient({
14
+ baseUrl: this.baseUrl,
15
+ clientId: this.clientId,
16
+ clientSecret: this.clientSecret,
17
+ scope: this.scope,
18
+ fetch: this.fetchImpl,
19
+ tokenRefreshSkewSeconds: this.tokenRefreshSkewSeconds,
20
+ operator
21
+ });
16
22
  }
17
23
  }
18
24
  function createGroupClient(options) {
19
25
  return new GroupSdkClient(options);
20
26
  }
21
27
  // src/constants.ts
22
- var GROUP_LIMITS = {
23
- list: 100,
24
- page: 500,
25
- snapshot: 200,
26
- statementLines: 1000
27
- };
28
- var GROUP_STATEMENT_SCOPES = ["ORG", "ENTITY", "STORE"];
28
+ import { GROUP_LIMITS, GROUP_STATEMENT_SCOPES } from "@qzsy/unipay-sdk";
29
29
  // src/errors.ts
30
30
  import { isGatewayError } from "@qzsy/unipay-sdk";
31
31
  function describeGroupError(error) {
32
- if (isGatewayError(error)) {
33
- const problem = error.problem;
34
- return problem.detail || problem.title || error.message || "网关返回了错误";
35
- }
32
+ if (isGatewayError(error))
33
+ return error.message || "网关返回了错误";
36
34
  if (error instanceof Error)
37
35
  return error.message;
38
36
  return "未知错误";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qzsy/group-sdk",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "type": "module",
5
5
  "description": "群兴云集团 SaaS 对接统一支付网关的 TypeScript SDK:集团凭据、多主体/多应用管理、门店账单与佣金付款",
6
6
  "license": "MIT",
@@ -22,15 +22,16 @@
22
22
  ],
23
23
  "sideEffects": false,
24
24
  "scripts": {
25
- "build": "bun run build:js && bun run build:types",
25
+ "build": "bun run clean && bun run build:js && bun run build:types",
26
26
  "build:js": "bun build src/index.ts --outfile dist/index.js --target node --format esm --external @qzsy/unipay-sdk && bun build src/index.ts --outfile dist/index.cjs --target node --format cjs --external @qzsy/unipay-sdk",
27
27
  "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
28
28
  "prepublishOnly": "bun run build && bun test",
29
29
  "test": "bun test",
30
- "type-check": "tsc --noEmit"
30
+ "type-check": "tsc -p tsconfig.test.json --noEmit",
31
+ "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
31
32
  },
32
33
  "dependencies": {
33
- "@qzsy/unipay-sdk": "^0.3.1"
34
+ "@qzsy/unipay-sdk": "^0.3.2"
34
35
  },
35
36
  "publishConfig": {
36
37
  "access": "public",
@@ -50,7 +51,7 @@
50
51
  "directory": "packages/group-sdk"
51
52
  },
52
53
  "engines": {
53
- "node": ">=18"
54
+ "node": ">=20.19"
54
55
  },
55
56
  "devDependencies": {
56
57
  "@repo/typescript-config": "workspace:*",
@@ -1 +0,0 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAE3F;;;;;GAKG;AACH,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,kBAAkB,EAAE,iBAAiB,CAAC;IAClF;;;OAGG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAA;CACzB;AAED;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,WAAW;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAE5C,YAAY,OAAO,EAAE,eAAe,EAInC;IAED,kBAAkB;IAClB,IAAI,eAAe,IAAI,aAAa,GAAG,SAAS,CAE/C;IAED,wCAAwC;IACxC,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,cAAc,CAEpD;CACF;AAED,oBAAoB;AACpB,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,eAAe,GAAG,cAAc,CAE1E"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,YAAY;IACvB,eAAe;aACf,IAAI,EAAE,GAAG;IACT,8BAA8B;aAC9B,IAAI,EAAE,GAAG;IACT,kBAAkB;aAClB,QAAQ,EAAE,GAAG;IACb,sBAAsB;aACtB,cAAc,EAAE,IAAI;CACZ,CAAA;AAEV,yBAAyB;AACzB,eAAO,MAAM,sBAAsB,YAAI,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAA;AAEzE,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAA"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOzD"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,UAAU,CAAA;AAClF,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAC5F,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAE7C;;;GAGG;AACH,cAAc,kBAAkB,CAAA"}