@h-ai/payment 0.1.0-alpha.56 → 0.1.0-alpha.57

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.
Files changed (4) hide show
  1. package/README.en.md +156 -0
  2. package/README.ja.md +156 -0
  3. package/README.md +4 -0
  4. package/package.json +3 -3
package/README.en.md ADDED
@@ -0,0 +1,156 @@
1
+ # @h-ai/payment
2
+
3
+ [简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
4
+
5
+ [Framework home](../../README.en.md) · Related modules: [@h-ai/audit](../audit/README.en.md) · [@h-ai/core](../core/README.en.md)
6
+
7
+ A unified payment module for WeChat Pay, Alipay, and Stripe, with provider-based server processing and payment initiation across clients.
8
+
9
+ ## Supported providers
10
+
11
+ | Provider | Payment scenarios |
12
+ | ---------- | ----------------------------------------- |
13
+ | WeChat Pay | JSAPI / H5 / App / Native (QR code) |
14
+ | Alipay | JSAPI / H5 / App / Native |
15
+ | Stripe | Checkout Session (international payments) |
16
+
17
+ ## Dependencies
18
+
19
+ - `@h-ai/audit`: optional audit logging; payment operations are recorded automatically when audit is initialized.
20
+
21
+ ## Quick start
22
+
23
+ ### Node.js server
24
+
25
+ ```typescript
26
+ import { payment } from '@h-ai/payment'
27
+
28
+ // 初始化（会自动注册可用的 Provider）
29
+ await payment.init({
30
+ wechat: { mchId: '...', apiV3Key: '...', serialNo: '...', privateKey: '...', appId: '...' },
31
+ alipay: { appId: '...', privateKey: '...', alipayPublicKey: '...' },
32
+ })
33
+
34
+ // 创建订单
35
+ const result = await payment.createOrder('wechat', {
36
+ orderNo: 'ORD001',
37
+ amount: 100,
38
+ description: '测试商品',
39
+ tradeType: 'jsapi',
40
+ userId: 'openid-xxx',
41
+ notifyUrl: 'https://api.example.com/payment/notify/wechat',
42
+ })
43
+
44
+ // 查询订单
45
+ const query = await payment.queryOrder('wechat', 'ORD001')
46
+
47
+ await payment.close()
48
+ ```
49
+
50
+ ### Browser client
51
+
52
+ ```typescript
53
+ import { invokePayment } from '@h-ai/payment/client'
54
+
55
+ // 使用服务端返回的订单数据调起支付
56
+ await invokePayment(orderData)
57
+ ```
58
+
59
+ ## HTTP API contracts
60
+
61
+ Payment HTTP APIs are defined by `apiContract.payment` in `@h-ai/api-contract`. After composing them into the application contract, call them through the typed client:
62
+
63
+ ```typescript
64
+ const order = await api.payment.orders.create({
65
+ provider: 'wechat',
66
+ amount: 100,
67
+ description: '商品',
68
+ tradeType: 'jsapi',
69
+ })
70
+ ```
71
+
72
+ ## Configuration
73
+
74
+ ```typescript
75
+ await payment.init({
76
+ wechat: {
77
+ mchId: '商户号',
78
+ apiV3Key: 'API v3 密钥',
79
+ serialNo: '证书序列号',
80
+ privateKey: '私钥内容',
81
+ appId: '应用 ID',
82
+ },
83
+ alipay: {
84
+ appId: '应用 ID',
85
+ privateKey: '私钥',
86
+ alipayPublicKey: '支付宝公钥',
87
+ signType: 'RSA2', // 可选，默认 RSA2
88
+ sandbox: false, // 可选，默认 false
89
+ },
90
+ stripe: {
91
+ secretKey: 'sk_xxx',
92
+ webhookSecret: 'whsec_xxx',
93
+ webhookToleranceSeconds: 300, // 可选，默认 300 秒
94
+ },
95
+ })
96
+ ```
97
+
98
+ Configure only the providers you need; unconfigured providers are not registered.
99
+
100
+ Amounts use minor currency units (cents) and must be positive integers. `amount` / `totalAmount` are validated before calling a provider, so invalid amounts never reach the payment platform.
101
+
102
+ All built-in provider HTTP requests have a default 15-second timeout to avoid long hangs on network failures.
103
+
104
+ ## Audit logging
105
+
106
+ Successful key payment operations automatically write audit logs through `@h-ai/audit`, without extra configuration. Audit failures produce warn logs and do not affect payment operations.
107
+
108
+ | Operation | `action` | Recorded data |
109
+ | ---------------- | ---------------- | --------------------------------------- |
110
+ | Create order | `create_order` | provider、amount、tradeType |
111
+ | Payment callback | `payment_notify` | provider、transactionId、status、amount |
112
+ | Refund | `refund` | provider、refundNo、amount |
113
+ | Close order | `close_order` | provider |
114
+
115
+ > Order queries (`queryOrder`) are read-only and do not write audit logs.
116
+
117
+ ## Error handling
118
+
119
+ ```typescript
120
+ const result = await payment.createOrder('wechat', orderInput)
121
+ if (!result.success) {
122
+ switch (result.error.code) {
123
+ case HaiPaymentError.INVALID_AMOUNT:
124
+ // 金额不是正整数，或 refund.totalAmount < amount
125
+ break
126
+ case HaiPaymentError.PROVIDER_NOT_FOUND:
127
+ // Provider 未注册
128
+ break
129
+ case HaiPaymentError.CREATE_ORDER_FAILED:
130
+ // 创建订单失败
131
+ break
132
+ }
133
+ }
134
+ ```
135
+
136
+ Common error codes:
137
+
138
+ | Error code | code | Description |
139
+ | -------------------------------------- | ----------------- | -------------------------------------- |
140
+ | `HaiPaymentError.CREATE_ORDER_FAILED` | `hai:payment:001` | Order creation failed |
141
+ | `HaiPaymentError.NOT_INITIALIZED` | `hai:payment:010` | Module not initialized |
142
+ | `HaiPaymentError.PROVIDER_NOT_FOUND` | `hai:payment:030` | Provider not registered |
143
+ | `HaiPaymentError.INVALID_AMOUNT` | `hai:payment:040` | Invalid amount |
144
+ | `HaiPaymentError.NOTIFY_VERIFY_FAILED` | `hai:payment:050` | Callback signature verification failed |
145
+ | `HaiPaymentError.NOTIFY_PARSE_FAILED` | `hai:payment:051` | Callback parsing failed |
146
+ | `HaiPaymentError.CONFIG_ERROR` | `hai:payment:070` | Invalid configuration |
147
+
148
+ ## Tests
149
+
150
+ ```bash
151
+ pnpm --filter @h-ai/payment test
152
+ ```
153
+
154
+ ## License
155
+
156
+ Apache-2.0
package/README.ja.md ADDED
@@ -0,0 +1,156 @@
1
+ # @h-ai/payment
2
+
3
+ [简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
4
+
5
+ [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/audit](../audit/README.ja.md) · [@h-ai/core](../core/README.ja.md)
6
+
7
+ WeChat Pay、Alipay、Stripe に対応する統一決済モジュールです。Provider によるサーバー側の決済処理と、複数プラットフォームからの決済開始を提供します。
8
+
9
+ ## 対応 Provider
10
+
11
+ | Provider | 決済方式 |
12
+ | ---------- | -------------------------------------- |
13
+ | WeChat Pay | JSAPI / H5 / App / Native（QR コード） |
14
+ | Alipay | JSAPI / H5 / App / Native |
15
+ | Stripe | Checkout Session（国際決済） |
16
+
17
+ ## 依存関係
18
+
19
+ - `@h-ai/audit`：任意の監査ログ。初期化済みの場合、決済操作を自動記録します。
20
+
21
+ ## クイックスタート
22
+
23
+ ### Node.js サーバー
24
+
25
+ ```typescript
26
+ import { payment } from '@h-ai/payment'
27
+
28
+ // 初始化（会自动注册可用的 Provider）
29
+ await payment.init({
30
+ wechat: { mchId: '...', apiV3Key: '...', serialNo: '...', privateKey: '...', appId: '...' },
31
+ alipay: { appId: '...', privateKey: '...', alipayPublicKey: '...' },
32
+ })
33
+
34
+ // 创建订单
35
+ const result = await payment.createOrder('wechat', {
36
+ orderNo: 'ORD001',
37
+ amount: 100,
38
+ description: '测试商品',
39
+ tradeType: 'jsapi',
40
+ userId: 'openid-xxx',
41
+ notifyUrl: 'https://api.example.com/payment/notify/wechat',
42
+ })
43
+
44
+ // 查询订单
45
+ const query = await payment.queryOrder('wechat', 'ORD001')
46
+
47
+ await payment.close()
48
+ ```
49
+
50
+ ### ブラウザークライアント
51
+
52
+ ```typescript
53
+ import { invokePayment } from '@h-ai/payment/client'
54
+
55
+ // 使用服务端返回的订单数据调起支付
56
+ await invokePayment(orderData)
57
+ ```
58
+
59
+ ## HTTP API 契約
60
+
61
+ 決済 HTTP API は `@h-ai/api-contract` の `apiContract.payment` で定義します。アプリケーション contract に組み込むと、型付きクライアントで呼び出せます：
62
+
63
+ ```typescript
64
+ const order = await api.payment.orders.create({
65
+ provider: 'wechat',
66
+ amount: 100,
67
+ description: '商品',
68
+ tradeType: 'jsapi',
69
+ })
70
+ ```
71
+
72
+ ## 設定
73
+
74
+ ```typescript
75
+ await payment.init({
76
+ wechat: {
77
+ mchId: '商户号',
78
+ apiV3Key: 'API v3 密钥',
79
+ serialNo: '证书序列号',
80
+ privateKey: '私钥内容',
81
+ appId: '应用 ID',
82
+ },
83
+ alipay: {
84
+ appId: '应用 ID',
85
+ privateKey: '私钥',
86
+ alipayPublicKey: '支付宝公钥',
87
+ signType: 'RSA2', // 可选，默认 RSA2
88
+ sandbox: false, // 可选，默认 false
89
+ },
90
+ stripe: {
91
+ secretKey: 'sk_xxx',
92
+ webhookSecret: 'whsec_xxx',
93
+ webhookToleranceSeconds: 300, // 可选，默认 300 秒
94
+ },
95
+ })
96
+ ```
97
+
98
+ 必要な Provider のみ設定してください。未設定の Provider は登録されません。
99
+
100
+ 金額は最小通貨単位（分・セント）で指定し、正の整数でなければなりません。Provider を呼ぶ前に `amount` / `totalAmount` を検証し、不正な金額を決済サービスに渡さないようにします。
101
+
102
+ すべての組み込み Provider の HTTP リクエストには既定で 15 秒のタイムアウトがあり、ネットワーク障害による長時間の待機を防ぎます。
103
+
104
+ ## 監査ログ
105
+
106
+ 主要な決済操作が成功すると、追加設定なしで `@h-ai/audit` に監査ログを自動記録します。監査記録の失敗は warn ログのみを出力し、決済操作に影響しません。
107
+
108
+ | 操作 | `action` | 記録内容 |
109
+ | ---------- | ---------------- | --------------------------------------- |
110
+ | 注文作成 | `create_order` | provider、amount、tradeType |
111
+ | 決済通知 | `payment_notify` | provider、transactionId、status、amount |
112
+ | 返金 | `refund` | provider、refundNo、amount |
113
+ | 注文の終了 | `close_order` | provider |
114
+
115
+ > 注文照会（`queryOrder`）は読み取り専用で、監査ログを記録しません。
116
+
117
+ ## エラー処理
118
+
119
+ ```typescript
120
+ const result = await payment.createOrder('wechat', orderInput)
121
+ if (!result.success) {
122
+ switch (result.error.code) {
123
+ case HaiPaymentError.INVALID_AMOUNT:
124
+ // 金额不是正整数，或 refund.totalAmount < amount
125
+ break
126
+ case HaiPaymentError.PROVIDER_NOT_FOUND:
127
+ // Provider 未注册
128
+ break
129
+ case HaiPaymentError.CREATE_ORDER_FAILED:
130
+ // 创建订单失败
131
+ break
132
+ }
133
+ }
134
+ ```
135
+
136
+ 主なエラーコード：
137
+
138
+ | エラーコード | code | 説明 |
139
+ | -------------------------------------- | ----------------- | -------------------- |
140
+ | `HaiPaymentError.CREATE_ORDER_FAILED` | `hai:payment:001` | 注文作成に失敗 |
141
+ | `HaiPaymentError.NOT_INITIALIZED` | `hai:payment:010` | モジュールが未初期化 |
142
+ | `HaiPaymentError.PROVIDER_NOT_FOUND` | `hai:payment:030` | Provider が未登録 |
143
+ | `HaiPaymentError.INVALID_AMOUNT` | `hai:payment:040` | 無効な金額 |
144
+ | `HaiPaymentError.NOTIFY_VERIFY_FAILED` | `hai:payment:050` | 通知の署名検証に失敗 |
145
+ | `HaiPaymentError.NOTIFY_PARSE_FAILED` | `hai:payment:051` | 通知の解析に失敗 |
146
+ | `HaiPaymentError.CONFIG_ERROR` | `hai:payment:070` | 無効な設定 |
147
+
148
+ ## テスト
149
+
150
+ ```bash
151
+ pnpm --filter @h-ai/payment test
152
+ ```
153
+
154
+ ## License
155
+
156
+ Apache-2.0
package/README.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # @h-ai/payment
2
2
 
3
+ [简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
4
+
5
+ [框架首页](../../README.md) · 相关模块：[@h-ai/audit](../audit/README.md) · [@h-ai/core](../core/README.md)
6
+
3
7
  统一支付模块，支持微信支付、支付宝和 Stripe，提供 Provider 模式的后端支付处理与多端客户端调起能力。
4
8
 
5
9
  ## 支持的 Provider
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@h-ai/payment",
3
3
  "type": "module",
4
- "version": "0.1.0-alpha.56",
4
+ "version": "0.1.0-alpha.57",
5
5
  "description": "Hai Framework payment module for WeChat Pay, Alipay, and Stripe.",
6
6
  "license": "Apache-2.0",
7
7
  "exports": {
@@ -27,8 +27,8 @@
27
27
  },
28
28
  "dependencies": {
29
29
  "zod": "^4.4.3",
30
- "@h-ai/audit": "0.1.0-alpha.56",
31
- "@h-ai/core": "0.1.0-alpha.56"
30
+ "@h-ai/audit": "0.1.0-alpha.57",
31
+ "@h-ai/core": "0.1.0-alpha.57"
32
32
  },
33
33
  "devDependencies": {
34
34
  "@types/node": "^25.9.1",