taiwan-payment-skill 1.5.13 → 1.5.14

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 (73) hide show
  1. package/README.md +139 -139
  2. package/assets/taiwan-payment/CLAUDE.md +339 -339
  3. package/assets/taiwan-payment/EXAMPLES.md +1392 -1392
  4. package/assets/taiwan-payment/README.md +139 -139
  5. package/assets/taiwan-payment/SKILL.md +151 -881
  6. package/assets/taiwan-payment/data/error-codes-payuni-1.csv +786 -786
  7. package/assets/taiwan-payment/data/error-codes-payuni-2.csv +719 -719
  8. package/assets/taiwan-payment/data/error-codes-tappay.csv +474 -474
  9. package/assets/taiwan-payment/data/error-codes.csv +1004 -1004
  10. package/assets/taiwan-payment/data/field-mappings.csv +20 -20
  11. package/assets/taiwan-payment/data/operations.csv +26 -26
  12. package/assets/taiwan-payment/data/payment-methods.csv +42 -42
  13. package/assets/taiwan-payment/data/pending.csv +8 -0
  14. package/assets/taiwan-payment/data/providers.csv +15 -15
  15. package/assets/taiwan-payment/data/reasoning.csv +46 -46
  16. package/assets/taiwan-payment/data/troubleshooting.csv +47 -47
  17. package/assets/taiwan-payment/evals/RESULTS.md +33 -0
  18. package/assets/taiwan-payment/evals/cases.json +193 -0
  19. package/assets/taiwan-payment/evals/grade.py +121 -0
  20. package/assets/taiwan-payment/examples/ecpay-payment-example.py +415 -415
  21. package/assets/taiwan-payment/examples/ezpay-payment-example.py +366 -366
  22. package/assets/taiwan-payment/examples/jkopay-payment-example.py +316 -316
  23. package/assets/taiwan-payment/examples/linepay-payment-example.py +310 -310
  24. package/assets/taiwan-payment/examples/newebpay-payment-example.py +607 -607
  25. package/assets/taiwan-payment/examples/paynow-payment-example.py +767 -767
  26. package/assets/taiwan-payment/examples/payuni-payment-example.py +301 -301
  27. package/assets/taiwan-payment/examples/pchomepay-payment-example.py +555 -555
  28. package/assets/taiwan-payment/examples/shopline-payment-example.py +290 -290
  29. package/assets/taiwan-payment/examples/smilepay-payment-example.py +673 -673
  30. package/assets/taiwan-payment/examples/sunpay-payment-example.py +343 -343
  31. package/assets/taiwan-payment/examples/tappay-payment-example.py +336 -336
  32. package/assets/taiwan-payment/references/ecpay-payment-api.md +502 -502
  33. package/assets/taiwan-payment/references/ezpay-payment-api.md +460 -460
  34. package/assets/taiwan-payment/references/gomypay-payment-api.md +50 -50
  35. package/assets/taiwan-payment/references/implementation-guide.md +768 -0
  36. package/assets/taiwan-payment/references/jkopay-payment-api.md +840 -840
  37. package/assets/taiwan-payment/references/linepay-payment-api.md +930 -930
  38. package/assets/taiwan-payment/references/newebpay-payment-api.md +829 -829
  39. package/assets/taiwan-payment/references/opay-payment-api.md +565 -565
  40. package/assets/taiwan-payment/references/paynow-payment-api.md +1651 -1651
  41. package/assets/taiwan-payment/references/payuni-payment-api.md +847 -847
  42. package/assets/taiwan-payment/references/pchomepay-payment-api.md +1428 -1428
  43. package/assets/taiwan-payment/references/shopline-payment-api.md +1524 -1524
  44. package/assets/taiwan-payment/references/smilepay-payment-api.md +907 -907
  45. package/assets/taiwan-payment/references/sunpay-payment-api.md +467 -467
  46. package/assets/taiwan-payment/references/tappay-payment-api.md +1243 -1243
  47. package/assets/taiwan-payment/references/twqr-ewallet-landscape.md +159 -159
  48. package/assets/taiwan-payment/requirements.txt +4 -0
  49. package/assets/taiwan-payment/scripts/check_numbers.py +147 -0
  50. package/assets/taiwan-payment/scripts/core.py +368 -351
  51. package/assets/taiwan-payment/scripts/recommend.py +288 -288
  52. package/assets/taiwan-payment/scripts/search.py +200 -187
  53. package/assets/taiwan-payment/scripts/test_payment.py +395 -373
  54. package/assets/taiwan-payment/scripts/test_recommend.py +114 -114
  55. package/assets/taiwan-payment/scripts/test_skill.py +202 -0
  56. package/assets/templates/base/quick-reference.md +70 -70
  57. package/assets/templates/base/skill-content.md +147 -875
  58. package/assets/templates/platforms/agent.json +26 -26
  59. package/assets/templates/platforms/claude.json +26 -26
  60. package/assets/templates/platforms/cline.json +26 -26
  61. package/assets/templates/platforms/codebuddy.json +25 -25
  62. package/assets/templates/platforms/codex.json +26 -26
  63. package/assets/templates/platforms/continue.json +25 -25
  64. package/assets/templates/platforms/copilot.json +25 -25
  65. package/assets/templates/platforms/cursor.json +26 -26
  66. package/assets/templates/platforms/gemini.json +25 -25
  67. package/assets/templates/platforms/kiro.json +25 -25
  68. package/assets/templates/platforms/opencode.json +25 -25
  69. package/assets/templates/platforms/qoder.json +25 -25
  70. package/assets/templates/platforms/trae.json +25 -25
  71. package/assets/templates/platforms/windsurf.json +25 -25
  72. package/dist/index.js +10 -1
  73. package/package.json +67 -67
@@ -1,339 +1,339 @@
1
- # CLAUDE.md
2
-
3
- This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
-
5
- ## Project Overview
6
-
7
- Taiwan Payment Skill is an AI-powered toolkit for Taiwan Payment Gateway integration, providing API documentation, code examples, and scripts for Taiwan payment platforms (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow, Shopline Payments, LINE Pay, TapPay, O'Pay, JKOPAY, SunPay, GoMyPay). It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).
8
-
9
- ## Available Scripts
10
-
11
- ```bash
12
- # Search API documentation
13
- python3 taiwan-payment/scripts/search.py "<query>" [--domain <domain>]
14
-
15
- # Recommend payment provider
16
- python3 taiwan-payment/scripts/recommend.py "<requirements>"
17
-
18
- # Test API connectivity
19
- python3 taiwan-payment/scripts/test_payment.py [--platform <platform>]
20
- ```
21
-
22
- **Supported Platforms:** `ecpay`, `newebpay`, `payuni`, `smilepay`, `pchomepay`, `ezpay`, `paynow`, `shopline`, `linepay`, `tappay`, `opay`, `jkopay`, `sunpay`, `gomypay`
23
-
24
- **電子支付錢包生態(街口/全支付/全盈+PAY/悠遊付/一卡通/icash Pay/橘子支/TWQR/零售自有 pay):** 見 `references/twqr-ewallet-landscape.md`——多數不直接串,走聚合商或 TWQR。
25
-
26
- **Search Domains:** `provider`, `operation`, `error`, `field`, `payment_method`, `troubleshoot`, `reasoning`
27
-
28
- ## Architecture
29
-
30
- ```
31
- taiwan-payment/ # Source of Truth
32
- ├── SKILL.md # Main skill documentation
33
- ├── EXAMPLES.md # Code examples and patterns
34
- ├── references/ # API documentation
35
- │ ├── ecpay-payment-api.md
36
- │ ├── newebpay-payment-api.md
37
- │ ├── payuni-payment-api.md
38
- │ ├── smilepay-payment-api.md
39
- │ ├── pchomepay-payment-api.md
40
- │ ├── ezpay-payment-api.md
41
- │ ├── paynow-payment-api.md
42
- │ ├── shopline-payment-api.md
43
- │ ├── linepay-payment-api.md
44
- │ ├── tappay-payment-api.md
45
- │ ├── opay-payment-api.md
46
- │ ├── jkopay-payment-api.md
47
- │ ├── sunpay-payment-api.md
48
- │ ├── gomypay-payment-api.md
49
- │ └── twqr-ewallet-landscape.md
50
- ├── scripts/ # Utility scripts
51
- │ ├── core.py # BM25 search engine
52
- │ ├── recommend.py # Recommendation system
53
- │ ├── search.py # Search CLI
54
- │ └── test_payment.py # 已知答案測試 + 測試環境連線
55
- ├── examples/ # 可執行範例(CI 以官方測試向量驗證)
56
- └── data/ # search / recommend 使用的 CSV
57
- ├── providers.csv # 14 家(含 doc_access 文件公開程度分級)
58
- ├── operations.csv
59
- ├── error-codes*.csv # 依各家官方文件重建(依 256 KiB 上限分檔)
60
- ├── field-mappings.csv
61
- ├── payment-methods.csv
62
- ├── reasoning.csv
63
- └── troubleshooting.csv
64
-
65
- payment-cli/ # CLI installer (taiwan-payment-skill on npm)
66
- ├── src/
67
- │ ├── commands/init.ts # Install command with template generation
68
- │ ├── utils/template.ts # Template rendering engine
69
- │ ├── utils/detect.ts # AI type detection
70
- │ └── utils/logger.ts # Logging utilities
71
- └── assets/ # Bundled assets
72
- ├── taiwan-payment/ # Copy of taiwan-payment/
73
- └── templates/
74
- ├── base/ # Base templates (skill-content.md, quick-reference.md)
75
- └── platforms/ # Platform configs (14 platforms)
76
-
77
- .claude/skills/taiwan-payment/ # Claude Code skill (generated by CLI)
78
- ```
79
-
80
- ## Sync Rules
81
-
82
- **Source of Truth:** `taiwan-payment/`
83
-
84
- When modifying files:
85
-
86
- 1. **Skill Content** - Edit in `taiwan-payment/`:
87
- - `SKILL.md` - Main documentation
88
- - `EXAMPLES.md` - Code examples
89
- - `references/*.md` - API documentation
90
- - `scripts/*.py` - Utility scripts
91
- - `data/*.csv` - Data files
92
-
93
- 2. **Templates** - Edit in `payment-cli/assets/templates/`:
94
- - `base/skill-content.md` - Common skill content
95
- - `base/quick-reference.md` - Quick reference (Claude only)
96
- - `platforms/*.json` - Platform-specific configs (14 platforms)
97
-
98
- 3. **CLI Assets** - 自動同步,無需手動複製:
99
- - `<cli>/scripts/build.js` 會在打包前呼叫 `scripts/sync-assets.mjs`,
100
- 因此 `npm run build` 與 `npm publish`(透過 prepublishOnly)都會自動帶到最新內容
101
- - 發布流程另以 `node scripts/sync-assets.mjs --check` 驗證,落差會擋下發布
102
-
103
- ```bash
104
- node scripts/sync-assets.mjs # 手動同步全部
105
- node scripts/sync-assets.mjs --check # 只檢查,有落差 exit 1
106
- ```
107
-
108
- > assets 會隨 npm publish 一起發布(package.json 的 `files` 含 `assets`),
109
- > 過去忘記同步會靜默發出過期的 skill 內容,因此改為自動化。
110
-
111
- 4. **Reference Folders** - No manual sync needed. The CLI generates these from templates during `taiwan-payment init`.
112
-
113
- ## Supported AI Platforms
114
-
115
- | Platform | Folder | Install Type |
116
- |-------------|-------------|--------------|
117
- | Claude Code | `.claude` | full |
118
- | Cursor | `.cursor` | full |
119
- | Windsurf | `.windsurf` | full |
120
- | Antigravity | `.agents` | full |
121
- | Copilot | `.github` | full |
122
- | Kiro | `.kiro` | full |
123
- | Codex | `.agents` | full |
124
- | Qoder | `.qoder` | full |
125
- | Cline | `.cline` | full |
126
- | Gemini | `.gemini` | full |
127
- | Trae | `.trae` | full |
128
- | OpenCode | `.opencode` | full |
129
- | Continue | `.continue` | full |
130
- | CodeBuddy | `.codebuddy`| full |
131
-
132
- ## Prerequisites
133
-
134
- - Node.js 18+ (for CLI)
135
- - Python 3.x (for scripts, no external dependencies)
136
-
137
- ## Git Workflow
138
-
139
- Never push directly to `main`. Always:
140
-
141
- 1. Create a new branch: `git checkout -b feat/...` or `fix/...`
142
- 2. Commit changes
143
- 3. Push branch: `git push -u origin <branch>`
144
- 4. Create PR: `gh pr create`
145
-
146
- ## Development Guidelines
147
-
148
- ### When Working with Payment Integration
149
-
150
- 1. **Always verify CheckMacValue/CheckSum** - This is the most critical security measure
151
- 2. **Use test accounts** - Never use production credentials in examples
152
- 3. **Handle errors gracefully** - Payment failures are common, always provide fallback
153
- 4. **HTTPS only** - All callback URLs must use HTTPS
154
- 5. **Amount validation** - Always validate amounts are positive integers
155
- 6. **Idempotency** - Ensure order IDs are unique to prevent duplicate payments
156
-
157
- ### Common Pitfalls
158
-
159
- 1. **CheckMacValue calculation errors**:
160
- - Sort parameters alphabetically, case-insensitive
161
- - URL encode 後轉小寫,並把 `( ) ! * - _ .` 還原(.NET 規則;直接用 quote_plus 遇到括號就會錯)
162
- - Must exclude CheckMacValue itself from calculation
163
- - 物流 API 用 MD5,金流 AIO 用 SHA256
164
-
165
- 2. **AES encryption errors**:
166
- - NewebPay: Key=32 bytes, IV=16 bytes;解密須容許 1–32 bytes 的 padding,且 RespondType=JSON 時明文是 JSON
167
- - PAYUNi: EncryptInfo = hex(base64(密文) + ":::" + base64(tag));HashInfo 為 HashKey + EncryptInfo + HashIV
168
-
169
- 3. **Payment notification handling**:
170
- - Always verify CheckMacValue before processing
171
- - Return "1|OK" for ECPay, handle appropriately for others
172
- - Use database transactions to prevent duplicate processing
173
-
174
- ### Code Review Checklist
175
-
176
- - [ ] Sensitive data (HashKey/HashIV) not exposed in frontend
177
- - [ ] CheckMacValue/CheckSum properly calculated and verified
178
- - [ ] HTTPS used for all callback URLs
179
- - [ ] Proper error handling for payment failures
180
- - [ ] Unique order IDs generated
181
- - [ ] Test accounts used in examples
182
- - [ ] Comments explain complex encryption logic
183
- - [ ] CSV data validated and consistent
184
-
185
- ## Smart Tools Usage
186
-
187
- ### BM25 Search
188
-
189
- Use when user asks about:
190
- - "What's error code 10100058?"
191
- - "How to map MerchantID field?"
192
- - "Which payment methods does ECPay support?"
193
-
194
- ```bash
195
- python3 scripts/search.py "<query>" [--domain <domain>] [--format json]
196
- ```
197
-
198
- ### Recommendation System
199
-
200
- Use when user asks:
201
- - "Which payment provider should I use?"
202
- - "Best for high-volume e-commerce?"
203
- - "Need LINE Pay integration"
204
-
205
- ```bash
206
- python3 scripts/recommend.py "<requirements>" [--format ascii|json|simple]
207
- ```
208
-
209
- ### Connection Testing
210
-
211
- Use when user wants to:
212
- - Test API connectivity
213
- - Verify encryption implementation
214
- - Check test credentials
215
-
216
- ```bash
217
- python3 scripts/test_payment.py [--platform ecpay|newebpay|payuni]
218
- ```
219
-
220
- ## Data-Driven Architecture
221
-
222
- All core logic is in CSV files:
223
-
224
- - **providers.csv** - Provider details (encryption, API endpoints, test accounts)
225
- - **operations.csv** - API operations (create, query, refund, etc.)
226
- - **error-codes*.csv** - Error code lookup table (split to stay under 256 KiB per file)
227
- - **field-mappings.csv** - Field name mappings across providers
228
- - **payment-methods.csv** - Payment method details
229
- - **reasoning.csv** - Recommendation rules
230
- - **troubleshooting.csv** - Common issues and solutions
231
-
232
- To add new data, edit CSV files directly. No code changes needed.
233
-
234
- ## Encryption Methods
235
-
236
- > 以下三段皆與業者官方實作逐位元組比對過(`tests/vectors/`,CI 執行 `scripts/verify-examples.py`)。
237
- > 修改前請先跑該腳本;不要憑印象改演算法。
238
-
239
- ### ECPay - SHA256 CheckMacValue(物流用 MD5)
240
-
241
- <!-- verify: ecpay-cmv-sha256 -->
242
- ```python
243
- def ecpay_url_encode(text):
244
- # PHP urlencode → 小寫 → .NET 不編碼的 - _ . ! * ( ) 還原
245
- encoded = urllib.parse.quote_plus(text, safe='').replace('~', '%7E').lower()
246
- for src, dst in (('%2d', '-'), ('%5f', '_'), ('%2e', '.'), ('%21', '!'),
247
- ('%2a', '*'), ('%28', '('), ('%29', ')')):
248
- encoded = encoded.replace(src, dst)
249
- return encoded
250
-
251
- def generate_check_mac_value(params, hash_key, hash_iv):
252
- items = sorted(((k, v) for k, v in params.items() if k != 'CheckMacValue'),
253
- key=lambda kv: kv[0].lower()) # 不分大小寫排序(SDK 用 strcasecmp)
254
- raw = f"HashKey={hash_key}&{'&'.join(f'{k}={v}' for k, v in items)}&HashIV={hash_iv}"
255
- return hashlib.sha256(ecpay_url_encode(raw).encode('utf-8')).hexdigest().upper()
256
- ```
257
-
258
- ### NewebPay - AES-256-CBC + SHA256
259
-
260
- <!-- verify: newebpay -->
261
- ```python
262
- def generate_trade_info(params, hash_key, hash_iv):
263
- cipher = AES.new(hash_key.encode(), AES.MODE_CBC, hash_iv.encode())
264
- return cipher.encrypt(pad(urllib.parse.urlencode(params).encode(), 16)).hex()
265
-
266
- def decrypt_trade_info(trade_info, hash_key, hash_iv):
267
- data = AES.new(hash_key.encode(), AES.MODE_CBC, hash_iv.encode()).decrypt(bytes.fromhex(trade_info))
268
- # 官方外掛以 32 bytes 區塊補齊,padding 可能是 1–32;unpad(data, 16) 會失敗
269
- n = data[-1]
270
- if not 1 <= n <= 32 or data[-n:] != bytes([n]) * n:
271
- raise ValueError('padding 錯誤(金鑰或 IV 不正確)')
272
- text = data[:-n].decode()
273
- # RespondType=JSON 時明文是 JSON,不是 query string
274
- return json.loads(text) if text.startswith('{') else dict(urllib.parse.parse_qsl(text, keep_blank_values=True))
275
-
276
- def generate_trade_sha(trade_info, hash_key, hash_iv):
277
- raw = f'HashKey={hash_key}&{trade_info}&HashIV={hash_iv}'
278
- return hashlib.sha256(raw.encode()).hexdigest().upper()
279
- ```
280
-
281
- ### PAYUNi - AES-256-GCM + SHA256
282
-
283
- <!-- verify: payuni -->
284
- ```python
285
- def generate_encrypt_info(params, hash_key, hash_iv):
286
- cipher = AES.new(hash_key.encode(), AES.MODE_GCM, nonce=hash_iv.encode())
287
- encrypted, tag = cipher.encrypt_and_digest(urllib.parse.urlencode(params).encode())
288
- # hex( base64(密文) + ":::" + base64(tag) ) —— 最外層的 hex 不可省略
289
- return (base64.b64encode(encrypted) + b':::' + base64.b64encode(tag)).hex()
290
-
291
- def generate_hash_info(encrypt_info, hash_key, hash_iv):
292
- raw = hash_key + encrypt_info + hash_iv # HashKey 在前
293
- return hashlib.sha256(raw.encode()).hexdigest().upper()
294
- ```
295
-
296
- ## Test Accounts
297
-
298
- ### ECPay
299
- ```
300
- 商店代號: 3002607
301
- HashKey: pwFHCqoQZGmho4w6
302
- HashIV: EkRm7iFT261dpevs
303
- 測試網址: https://payment-stage.ecpay.com.tw/Cashier/AioCheckOut/V5
304
- 測試卡號: 4311-9522-2222-2222
305
- ```
306
-
307
- ### NewebPay
308
- ```
309
- 商店代號: 請至後台申請
310
- HashKey: 請至後台申請
311
- HashIV: 請至後台申請
312
- 測試網址: https://ccore.newebpay.com/MPG/mpg_gateway
313
- 測試卡號: 4000-2211-1111-1111
314
- ```
315
-
316
- ### PAYUNi
317
- ```
318
- 商店代號: 請至後台申請
319
- HashKey: 請至後台申請
320
- HashIV: 請至後台申請
321
- 測試網址: https://sandbox-api.payuni.com.tw/api/upp
322
- 測試卡號: 4000-2211-1111-1111
323
- ```
324
-
325
- ## Publishing Workflow
326
-
327
- Before publishing to npm:
328
-
329
- 1. Update version in `payment-cli/package.json`
330
- 2. Sync assets: 由 `npm run build` 自動處理(`scripts/sync-assets.mjs`)
331
- 3. Build CLI: `cd payment-cli && npm run build`
332
- 4. Test locally: `npm test`
333
- 5. Publish: `npm publish`
334
-
335
- ## Related Projects
336
-
337
- - **Taiwan Invoice Skill** - E-Invoice integration (ECPay, SmilePay, Amego, ezPay, PayNow, O'Pay, SunPay)
338
- - **Taiwan Logistics Skill** - Logistics integration (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, PayNow, ezShip, HCT, on-demand delivery)
339
-
1
+ # CLAUDE.md
2
+
3
+ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+ ## Project Overview
6
+
7
+ Taiwan Payment Skill is an AI-powered toolkit for Taiwan Payment Gateway integration, providing API documentation, code examples, and scripts for Taiwan payment platforms (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow, Shopline Payments, LINE Pay, TapPay, O'Pay, JKOPAY, SunPay, GoMyPay). It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).
8
+
9
+ ## Available Scripts
10
+
11
+ ```bash
12
+ # Search API documentation
13
+ python3 taiwan-payment/scripts/search.py "<query>" [--domain <domain>]
14
+
15
+ # Recommend payment provider
16
+ python3 taiwan-payment/scripts/recommend.py "<requirements>"
17
+
18
+ # Test API connectivity
19
+ python3 taiwan-payment/scripts/test_payment.py [--platform <platform>]
20
+ ```
21
+
22
+ **Supported Platforms:** `ecpay`, `newebpay`, `payuni`, `smilepay`, `pchomepay`, `ezpay`, `paynow`, `shopline`, `linepay`, `tappay`, `opay`, `jkopay`, `sunpay`, `gomypay`
23
+
24
+ **電子支付錢包生態(街口/全支付/全盈+PAY/悠遊付/一卡通/icash Pay/橘子支/TWQR/零售自有 pay):** 見 `references/twqr-ewallet-landscape.md`——多數不直接串,走聚合商或 TWQR。
25
+
26
+ **Search Domains:** `provider`, `operation`, `error`, `field`, `payment_method`, `troubleshoot`, `reasoning`
27
+
28
+ ## Architecture
29
+
30
+ ```
31
+ taiwan-payment/ # Source of Truth
32
+ ├── SKILL.md # Main skill documentation
33
+ ├── EXAMPLES.md # Code examples and patterns
34
+ ├── references/ # API documentation
35
+ │ ├── ecpay-payment-api.md
36
+ │ ├── newebpay-payment-api.md
37
+ │ ├── payuni-payment-api.md
38
+ │ ├── smilepay-payment-api.md
39
+ │ ├── pchomepay-payment-api.md
40
+ │ ├── ezpay-payment-api.md
41
+ │ ├── paynow-payment-api.md
42
+ │ ├── shopline-payment-api.md
43
+ │ ├── linepay-payment-api.md
44
+ │ ├── tappay-payment-api.md
45
+ │ ├── opay-payment-api.md
46
+ │ ├── jkopay-payment-api.md
47
+ │ ├── sunpay-payment-api.md
48
+ │ ├── gomypay-payment-api.md
49
+ │ └── twqr-ewallet-landscape.md
50
+ ├── scripts/ # Utility scripts
51
+ │ ├── core.py # BM25 search engine
52
+ │ ├── recommend.py # Recommendation system
53
+ │ ├── search.py # Search CLI
54
+ │ └── test_payment.py # 已知答案測試 + 測試環境連線
55
+ ├── examples/ # 可執行範例(CI 以官方測試向量驗證)
56
+ └── data/ # search / recommend 使用的 CSV
57
+ ├── providers.csv # 14 家(含 doc_access 文件公開程度分級)
58
+ ├── operations.csv
59
+ ├── error-codes*.csv # 依各家官方文件重建(依 256 KiB 上限分檔)
60
+ ├── field-mappings.csv
61
+ ├── payment-methods.csv
62
+ ├── reasoning.csv
63
+ └── troubleshooting.csv
64
+
65
+ payment-cli/ # CLI installer (taiwan-payment-skill on npm)
66
+ ├── src/
67
+ │ ├── commands/init.ts # Install command with template generation
68
+ │ ├── utils/template.ts # Template rendering engine
69
+ │ ├── utils/detect.ts # AI type detection
70
+ │ └── utils/logger.ts # Logging utilities
71
+ └── assets/ # Bundled assets
72
+ ├── taiwan-payment/ # Copy of taiwan-payment/
73
+ └── templates/
74
+ ├── base/ # Base templates (skill-content.md, quick-reference.md)
75
+ └── platforms/ # Platform configs (14 platforms)
76
+
77
+ .claude/skills/taiwan-payment/ # Claude Code skill (generated by CLI)
78
+ ```
79
+
80
+ ## Sync Rules
81
+
82
+ **Source of Truth:** `taiwan-payment/`
83
+
84
+ When modifying files:
85
+
86
+ 1. **Skill Content** - Edit in `taiwan-payment/`:
87
+ - `SKILL.md` - Main documentation
88
+ - `EXAMPLES.md` - Code examples
89
+ - `references/*.md` - API documentation
90
+ - `scripts/*.py` - Utility scripts
91
+ - `data/*.csv` - Data files
92
+
93
+ 2. **Templates** - Edit in `payment-cli/assets/templates/`:
94
+ - `base/skill-content.md` - Common skill content
95
+ - `base/quick-reference.md` - Quick reference (Claude only)
96
+ - `platforms/*.json` - Platform-specific configs (14 platforms)
97
+
98
+ 3. **CLI Assets** - 自動同步,無需手動複製:
99
+ - `<cli>/scripts/build.js` 會在打包前呼叫 `scripts/sync-assets.mjs`,
100
+ 因此 `npm run build` 與 `npm publish`(透過 prepublishOnly)都會自動帶到最新內容
101
+ - 發布流程另以 `node scripts/sync-assets.mjs --check` 驗證,落差會擋下發布
102
+
103
+ ```bash
104
+ node scripts/sync-assets.mjs # 手動同步全部
105
+ node scripts/sync-assets.mjs --check # 只檢查,有落差 exit 1
106
+ ```
107
+
108
+ > assets 會隨 npm publish 一起發布(package.json 的 `files` 含 `assets`),
109
+ > 過去忘記同步會靜默發出過期的 skill 內容,因此改為自動化。
110
+
111
+ 4. **Reference Folders** - No manual sync needed. The CLI generates these from templates during `taiwan-payment init`.
112
+
113
+ ## Supported AI Platforms
114
+
115
+ | Platform | Folder | Install Type |
116
+ |-------------|-------------|--------------|
117
+ | Claude Code | `.claude` | full |
118
+ | Cursor | `.cursor` | full |
119
+ | Windsurf | `.windsurf` | full |
120
+ | Antigravity | `.agents` | full |
121
+ | Copilot | `.github` | full |
122
+ | Kiro | `.kiro` | full |
123
+ | Codex | `.agents` | full |
124
+ | Qoder | `.qoder` | full |
125
+ | Cline | `.cline` | full |
126
+ | Gemini | `.gemini` | full |
127
+ | Trae | `.trae` | full |
128
+ | OpenCode | `.opencode` | full |
129
+ | Continue | `.continue` | full |
130
+ | CodeBuddy | `.codebuddy`| full |
131
+
132
+ ## Prerequisites
133
+
134
+ - Node.js 18+ (for CLI)
135
+ - Python 3.x (for scripts, no external dependencies)
136
+
137
+ ## Git Workflow
138
+
139
+ Never push directly to `main`. Always:
140
+
141
+ 1. Create a new branch: `git checkout -b feat/...` or `fix/...`
142
+ 2. Commit changes
143
+ 3. Push branch: `git push -u origin <branch>`
144
+ 4. Create PR: `gh pr create`
145
+
146
+ ## Development Guidelines
147
+
148
+ ### When Working with Payment Integration
149
+
150
+ 1. **Always verify CheckMacValue/CheckSum** - This is the most critical security measure
151
+ 2. **Use test accounts** - Never use production credentials in examples
152
+ 3. **Handle errors gracefully** - Payment failures are common, always provide fallback
153
+ 4. **HTTPS only** - All callback URLs must use HTTPS
154
+ 5. **Amount validation** - Always validate amounts are positive integers
155
+ 6. **Idempotency** - Ensure order IDs are unique to prevent duplicate payments
156
+
157
+ ### Common Pitfalls
158
+
159
+ 1. **CheckMacValue calculation errors**:
160
+ - Sort parameters alphabetically, case-insensitive
161
+ - URL encode 後轉小寫,並把 `( ) ! * - _ .` 還原(.NET 規則;直接用 quote_plus 遇到括號就會錯)
162
+ - Must exclude CheckMacValue itself from calculation
163
+ - 物流 API 用 MD5,金流 AIO 用 SHA256
164
+
165
+ 2. **AES encryption errors**:
166
+ - NewebPay: Key=32 bytes, IV=16 bytes;解密須容許 1–32 bytes 的 padding,且 RespondType=JSON 時明文是 JSON
167
+ - PAYUNi: EncryptInfo = hex(base64(密文) + ":::" + base64(tag));HashInfo 為 HashKey + EncryptInfo + HashIV
168
+
169
+ 3. **Payment notification handling**:
170
+ - Always verify CheckMacValue before processing
171
+ - Return "1|OK" for ECPay, handle appropriately for others
172
+ - Use database transactions to prevent duplicate processing
173
+
174
+ ### Code Review Checklist
175
+
176
+ - [ ] Sensitive data (HashKey/HashIV) not exposed in frontend
177
+ - [ ] CheckMacValue/CheckSum properly calculated and verified
178
+ - [ ] HTTPS used for all callback URLs
179
+ - [ ] Proper error handling for payment failures
180
+ - [ ] Unique order IDs generated
181
+ - [ ] Test accounts used in examples
182
+ - [ ] Comments explain complex encryption logic
183
+ - [ ] CSV data validated and consistent
184
+
185
+ ## Smart Tools Usage
186
+
187
+ ### BM25 Search
188
+
189
+ Use when user asks about:
190
+ - "What's error code 10100058?"
191
+ - "How to map MerchantID field?"
192
+ - "Which payment methods does ECPay support?"
193
+
194
+ ```bash
195
+ python3 scripts/search.py "<query>" [--domain <domain>] [--format json]
196
+ ```
197
+
198
+ ### Recommendation System
199
+
200
+ Use when user asks:
201
+ - "Which payment provider should I use?"
202
+ - "Best for high-volume e-commerce?"
203
+ - "Need LINE Pay integration"
204
+
205
+ ```bash
206
+ python3 scripts/recommend.py "<requirements>" [--format ascii|json|simple]
207
+ ```
208
+
209
+ ### Connection Testing
210
+
211
+ Use when user wants to:
212
+ - Test API connectivity
213
+ - Verify encryption implementation
214
+ - Check test credentials
215
+
216
+ ```bash
217
+ python3 scripts/test_payment.py [--platform ecpay|newebpay|payuni]
218
+ ```
219
+
220
+ ## Data-Driven Architecture
221
+
222
+ All core logic is in CSV files:
223
+
224
+ - **providers.csv** - Provider details (encryption, API endpoints, test accounts)
225
+ - **operations.csv** - API operations (create, query, refund, etc.)
226
+ - **error-codes*.csv** - Error code lookup table (split to stay under 256 KiB per file)
227
+ - **field-mappings.csv** - Field name mappings across providers
228
+ - **payment-methods.csv** - Payment method details
229
+ - **reasoning.csv** - Recommendation rules
230
+ - **troubleshooting.csv** - Common issues and solutions
231
+
232
+ To add new data, edit CSV files directly. No code changes needed.
233
+
234
+ ## Encryption Methods
235
+
236
+ > 以下三段皆與業者官方實作逐位元組比對過(`tests/vectors/`,CI 執行 `scripts/verify-examples.py`)。
237
+ > 修改前請先跑該腳本;不要憑印象改演算法。
238
+
239
+ ### ECPay - SHA256 CheckMacValue(物流用 MD5)
240
+
241
+ <!-- verify: ecpay-cmv-sha256 -->
242
+ ```python
243
+ def ecpay_url_encode(text):
244
+ # PHP urlencode → 小寫 → .NET 不編碼的 - _ . ! * ( ) 還原
245
+ encoded = urllib.parse.quote_plus(text, safe='').replace('~', '%7E').lower()
246
+ for src, dst in (('%2d', '-'), ('%5f', '_'), ('%2e', '.'), ('%21', '!'),
247
+ ('%2a', '*'), ('%28', '('), ('%29', ')')):
248
+ encoded = encoded.replace(src, dst)
249
+ return encoded
250
+
251
+ def generate_check_mac_value(params, hash_key, hash_iv):
252
+ items = sorted(((k, v) for k, v in params.items() if k != 'CheckMacValue'),
253
+ key=lambda kv: kv[0].lower()) # 不分大小寫排序(SDK 用 strcasecmp)
254
+ raw = f"HashKey={hash_key}&{'&'.join(f'{k}={v}' for k, v in items)}&HashIV={hash_iv}"
255
+ return hashlib.sha256(ecpay_url_encode(raw).encode('utf-8')).hexdigest().upper()
256
+ ```
257
+
258
+ ### NewebPay - AES-256-CBC + SHA256
259
+
260
+ <!-- verify: newebpay -->
261
+ ```python
262
+ def generate_trade_info(params, hash_key, hash_iv):
263
+ cipher = AES.new(hash_key.encode(), AES.MODE_CBC, hash_iv.encode())
264
+ return cipher.encrypt(pad(urllib.parse.urlencode(params).encode(), 16)).hex()
265
+
266
+ def decrypt_trade_info(trade_info, hash_key, hash_iv):
267
+ data = AES.new(hash_key.encode(), AES.MODE_CBC, hash_iv.encode()).decrypt(bytes.fromhex(trade_info))
268
+ # 官方外掛以 32 bytes 區塊補齊,padding 可能是 1–32;unpad(data, 16) 會失敗
269
+ n = data[-1]
270
+ if not 1 <= n <= 32 or data[-n:] != bytes([n]) * n:
271
+ raise ValueError('padding 錯誤(金鑰或 IV 不正確)')
272
+ text = data[:-n].decode()
273
+ # RespondType=JSON 時明文是 JSON,不是 query string
274
+ return json.loads(text) if text.startswith('{') else dict(urllib.parse.parse_qsl(text, keep_blank_values=True))
275
+
276
+ def generate_trade_sha(trade_info, hash_key, hash_iv):
277
+ raw = f'HashKey={hash_key}&{trade_info}&HashIV={hash_iv}'
278
+ return hashlib.sha256(raw.encode()).hexdigest().upper()
279
+ ```
280
+
281
+ ### PAYUNi - AES-256-GCM + SHA256
282
+
283
+ <!-- verify: payuni -->
284
+ ```python
285
+ def generate_encrypt_info(params, hash_key, hash_iv):
286
+ cipher = AES.new(hash_key.encode(), AES.MODE_GCM, nonce=hash_iv.encode())
287
+ encrypted, tag = cipher.encrypt_and_digest(urllib.parse.urlencode(params).encode())
288
+ # hex( base64(密文) + ":::" + base64(tag) ) —— 最外層的 hex 不可省略
289
+ return (base64.b64encode(encrypted) + b':::' + base64.b64encode(tag)).hex()
290
+
291
+ def generate_hash_info(encrypt_info, hash_key, hash_iv):
292
+ raw = hash_key + encrypt_info + hash_iv # HashKey 在前
293
+ return hashlib.sha256(raw.encode()).hexdigest().upper()
294
+ ```
295
+
296
+ ## Test Accounts
297
+
298
+ ### ECPay
299
+ ```
300
+ 商店代號: 3002607
301
+ HashKey: pwFHCqoQZGmho4w6
302
+ HashIV: EkRm7iFT261dpevs
303
+ 測試網址: https://payment-stage.ecpay.com.tw/Cashier/AioCheckOut/V5
304
+ 測試卡號: 4311-9522-2222-2222
305
+ ```
306
+
307
+ ### NewebPay
308
+ ```
309
+ 商店代號: 請至後台申請
310
+ HashKey: 請至後台申請
311
+ HashIV: 請至後台申請
312
+ 測試網址: https://ccore.newebpay.com/MPG/mpg_gateway
313
+ 測試卡號: 4000-2211-1111-1111
314
+ ```
315
+
316
+ ### PAYUNi
317
+ ```
318
+ 商店代號: 請至後台申請
319
+ HashKey: 請至後台申請
320
+ HashIV: 請至後台申請
321
+ 測試網址: https://sandbox-api.payuni.com.tw/api/upp
322
+ 測試卡號: 4000-2211-1111-1111
323
+ ```
324
+
325
+ ## Publishing Workflow
326
+
327
+ Before publishing to npm:
328
+
329
+ 1. Update version in `payment-cli/package.json`
330
+ 2. Sync assets: 由 `npm run build` 自動處理(`scripts/sync-assets.mjs`)
331
+ 3. Build CLI: `cd payment-cli && npm run build`
332
+ 4. Test locally: `npm test`
333
+ 5. Publish: `npm publish`
334
+
335
+ ## Related Projects
336
+
337
+ - **Taiwan Invoice Skill** - E-Invoice integration (ECPay, SmilePay, Amego, ezPay, PayNow, O'Pay, SunPay)
338
+ - **Taiwan Logistics Skill** - Logistics integration (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, PayNow, ezShip, HCT, on-demand delivery)
339
+