@recur-tw/cli 0.1.0 → 0.1.1

package/README.md

@@ -21,7 +21,7 @@ npx @recur-tw/cli products list
 前往 [Recur Dashboard](https://app.recur.tw) 取得 Secret Key（`sk_test_*` 或 `sk_live_*`），然後執行：
 
 ```bash
-recur --key sk_test_xxx login
+recur login
 ```
 
 API Key 會安全存儲在 `~/.recur/credentials.json`（檔案權限 `0600`）。
@@ -58,7 +58,7 @@ recur <資源> <動作> [選項]
 | `--key <sk_*>` | 指定 API Secret Key |
 | `--profile <name>` | 使用指定的 profile |
 | `--base-url <url>` | API 位址覆寫 |
-| `--output <format>` | 輸出格式：`json`、`table`（預設）、`csv` |
+| `--output <format>` | 輸出格式：`json`、`table`（預設）、`csv`、`ndjson` |
 | `--fields <fields>` | 逗號分隔的欄位篩選 |
 | `--dry-run` | 僅本地驗證，不發送 API 請求 |
 | `--json <payload>` | 直接傳入 JSON 作為 API request body |
@@ -66,9 +66,8 @@ recur <資源> <動作> [選項]
 ### 驗證管理
 
 ```bash
-recur login                       # 互動式設定 API Key
-recur --key sk_test_xxx login     # 直接設定
-recur whoami                      # 顯示目前 profile
+recur login                       # 互動式設定 API Key（輸入時遮蔽顯示）
+recur whoami                      # 顯示目前 profile 與 masked key
 recur profiles                    # 列出所有 profile
 recur use <profile>               # 切換 profile
 recur logout [profile]            # 移除 profile
@@ -95,7 +94,7 @@ recur --profile sandbox products list
 
 ```bash
 recur products list                                    # 列出所有產品
-recur products list --status active                    # 篩選狀態
+recur products list --status archived                  # 列出已封存產品
 recur products get <id>                                # 以 ID 查詢
 recur products get <slug>                              # 以 slug 查詢
 recur products create --name "方案" --price 299 --interval monthly --type SUBSCRIPTION
@@ -109,7 +108,8 @@ recur products archive <id>
 ```bash
 recur customers list                                   # 列出所有客戶
 recur customers list --email user@example.com          # 以 email 篩選
-recur customers list --limit 50 --offset 100           # 分頁
+recur customers list --starting-after <id> --limit 50  # 游標分頁
+recur customers list --page-all                        # 自動分頁（輸出 NDJSON）
 recur customers get <id>                               # 查詢客戶詳情
 recur customers update <id> --name "新名稱"
 ```
@@ -119,8 +119,8 @@ recur customers update <id> --name "新名稱"
 ```bash
 recur subscriptions list                               # 列出所有訂閱
 recur subscriptions list --status active               # 篩選狀態
-recur subscriptions list --customer-id cus_xxx         # 以客戶篩選
-recur subscriptions list --email user@example.com      # 以 email 篩選
+recur subscriptions list --customer-id <id>            # 以客戶篩選
+recur subscriptions list --page-all                    # 自動分頁
 recur subscriptions get <id>                           # 查詢訂閱詳情
 recur subscriptions cancel <id>                        # 期末取消
 recur subscriptions cancel <id> --immediately          # 立即取消
@@ -131,7 +131,7 @@ recur subscriptions cancel <id> --immediately          # 立即取消
 ```bash
 recur orders list                                      # 列出所有訂單
 recur orders list --status paid                        # 篩選狀態
-recur orders list --customer-id cus_xxx                # 以客戶篩選
+recur orders list --customer-id <id>                   # 以客戶篩選
 recur orders get <id>                                  # 查詢訂單詳情
 ```
 
@@ -139,8 +139,8 @@ recur orders get <id>                                  # 查詢訂單詳情
 
 ```bash
 recur invoices list                                    # 列出所有帳單
-recur invoices list --subscription-id sub_xxx          # 以訂閱篩選
-recur invoices list --customer-id cus_xxx              # 以客戶篩選
+recur invoices list --subscription-id <id>             # 以訂閱篩選
+recur invoices list --customer-id <id>                 # 以客戶篩選
 recur invoices list --status paid                      # 篩選狀態
 recur invoices get <id>                                # 查詢帳單詳情
 ```
@@ -159,7 +159,7 @@ recur webhooks listen http://localhost:3000/api/webhooks  # 即時轉發到本
 
 ### 本地 Webhook 開發（`webhooks listen`）
 
-類似 `stripe listen`，`recur webhooks listen` 讓你在本地開發時即時接收 webhook 事件，不需要公開 URL。
+`recur webhooks listen` 讓你在本地開發時即時接收 webhook 事件，不需要公開 URL。
 
 ```bash
 # 基本用法：轉發所有事件到本地伺服器
@@ -211,8 +211,8 @@ recur webhooks listen http://localhost:3000/api/webhooks --events checkout.compl
 ### Checkout Sessions
 
 ```bash
-recur checkouts create --product-id prod_xxx --customer-email user@example.com
-recur checkouts create --json '{"productId":"prod_xxx","successUrl":"https://..."}'
+recur checkouts create --product-id <id> --customer-email user@example.com
+recur checkouts create --json '{"productId":"<id>","successUrl":"https://..."}'
 recur checkouts get <id>                               # 查詢 session 狀態
 ```
 
@@ -237,7 +237,7 @@ name             price  type
 $ recur products list --output json
 
 [
-  { "id": "prod_xxx", "name": "大師方案", "price": 799 },
+  { "id": "k672i1kd6zgrw5b6w39xwpx3", "name": "大師方案", "price": 799 },
   ...
 ]
 ```
@@ -249,6 +249,13 @@ recur products list --output json | jq '.[].name'
 recur subscriptions list --output json | jq '[.[] | select(.status == "ACTIVE")]'
 ```
 
+### NDJSON（適合串流處理）
+
+```bash
+# --page-all 自動輸出 NDJSON（一行一筆）
+recur customers list --page-all --fields id,email
+```
+
 ### CSV（適合匯出與試算表）
 
 ```bash
@@ -264,7 +271,58 @@ recur products list --fields id,name,price
 recur customers list --fields email,name --output json
 ```
 
-## AI Agent 整合
+## MCP Server（AI Agent 整合）
+
+`recur mcp` 啟動一個本地 MCP（Model Context Protocol）server，讓 AI 助理直接操作 Recur API。
+
+### Claude Desktop
+
+在 `claude_desktop_config.json` 中加入：
+
+```json
+{
+  "mcpServers": {
+    "recur": {
+      "command": "npx",
+      "args": ["@recur-tw/cli", "mcp"],
+      "env": { "RECUR_SECRET_KEY": "sk_test_xxx" }
+    }
+  }
+}
+```
+
+### Claude Code
+
+在專案根目錄的 `.mcp.json` 中加入：
+
+```json
+{
+  "mcpServers": {
+    "recur": {
+      "command": "npx",
+      "args": ["@recur-tw/cli", "mcp"],
+      "env": { "RECUR_SECRET_KEY": "sk_test_xxx" }
+    }
+  }
+}
+```
+
+### 提供的 Tools（22 個）
+
+| 類別 | Tools | 類型 |
+|------|-------|------|
+| Schema | `get_schema` | 唯讀 |
+| Products | `list_products`, `get_product`, `create_product`, `update_product`, `archive_product` | 讀寫 |
+| Customers | `list_customers`, `get_customer`, `update_customer` | 讀寫 |
+| Subscriptions | `list_subscriptions`, `get_subscription`, `cancel_subscription` | 讀寫 |
+| Orders | `list_orders`, `get_order` | 唯讀 |
+| Invoices | `list_invoices`, `get_invoice` | 唯讀 |
+| Webhooks | `list_webhooks`, `create_webhook`, `test_webhook`, `delete_webhook` | 讀寫 |
+| Checkouts | `create_checkout`, `get_checkout` | 寫入 |
+
+所有 tools 帶有 MCP Tool Annotations（`readOnlyHint`、`destructiveHint`），讓 agent 能判斷操作風險。
+
+## Agent-Optimized 設計
 
 此 CLI 遵循 [Agent-Optimized CLI](https://justin.poehnelt.com/posts/rewrite-your-cli-for-ai-agents/) 設計原則：
 
@@ -305,12 +363,12 @@ recur products create --dry-run --json '{"name":"Test","price":299}'
 
 ### Input 驗證（防止 AI 幻覺）
 
-CLI 內建多層輸入驗證，防止 Agent 送出錯誤的 ID 或惡意輸入：
+CLI 內建多層輸入驗證，防止 Agent 送出錯誤或惡意輸入：
 
-- Resource ID 前綴驗證（`prod_*`、`cus_*`、`sub_*` 等）
 - 路徑穿越偵測（`../`、`/`、`\`）
-- 特殊字元阻擋（`?`、`#`、`%`）
-- 控制字元過濾
+- Query injection 阻擋（`?`、`#`、`%`）
+- 控制字元與不可見 Unicode 過濾
+- API 回應 sanitization（ANSI escape、零寬字元）
 
 ## 驗證方式
 
@@ -331,10 +389,12 @@ CLI 僅接受 Secret Key。Publishable Key（`pk_*`）僅供前端 SDK 使用。
 
 ### 安全性
 
+- Login 輸入 key 時以 `*` 遮蔽顯示
 - API Key 以 `0600` 權限存儲在 `~/.recur/credentials.json`
 - CLI 不直接連接資料庫，所有操作經由 API server 驗證
 - 每個 API Key 綁定一個 Organization，資料完全隔離
 - Key 以 SHA-256 hash 存儲在 server 端
+- API 回應自動 sanitize 以防止 prompt injection
 
 ## 程式化使用
 
@@ -353,7 +413,7 @@ const products = await client.get('/v1/products')
 
 ## 系統需求
 
-- Node.js >= 18
+- Node.js >= 22
 - 作業系統：macOS、Linux、Windows
 
 ## 授權

package/dist/cli.mjs

@@ -920,7 +920,7 @@ var RecurClient = class {
 		}
 		const headers = {
 			Authorization: `Bearer ${this.secretKey}`,
-			"User-Agent": `@recur-tw/cli/0.1.0`
+			"User-Agent": `@recur-tw/cli/0.1.1`
 		};
 		const hasBody = opts?.body !== void 0;
 		if (hasBody) headers["Content-Type"] = "application/json";
@@ -1676,7 +1676,7 @@ async function parseSSEStream(body, handlers, signal) {
 	}
 }
 function registerListenSubcommand(webhooksCmd) {
-	const listenCmd = webhooksCmd.command("listen").description("Forward webhook events from Recur to your local server in real-time (similar to stripe listen)").argument("<url>", "Local URL to forward events to (e.g. http://localhost:3000/api/webhooks)").option("--events <types>", "Comma-separated event types to filter (e.g. checkout.completed,order.paid)").option("--relay-url <url>", "Override relay server URL (for development)");
+	const listenCmd = webhooksCmd.command("listen").description("Forward webhook events from Recur to your local server in real-time").argument("<url>", "Local URL to forward events to (e.g. http://localhost:3000/api/webhooks)").option("--events <types>", "Comma-separated event types to filter (e.g. checkout.completed,order.paid)").option("--relay-url <url>", "Override relay server URL (for development)");
 	listenCmd.addHelpText("after", `
 Connects to Recur's SSE relay and forwards webhook events to your local server.
 Each session gets a unique signing secret (whsec_*) for verifying event signatures.
@@ -2489,7 +2489,7 @@ Requires a Secret Key (sk_test_* or sk_live_*) via --key, RECUR_SECRET_KEY, or r
 			});
 			const server = new McpServer({
 				name: "recur",
-				version: "0.1.0"
+				version: "0.1.1"
 			}, { capabilities: { tools: {} } });
 			registerTools(server, client);
 			const transport = new StdioServerTransport();
@@ -2505,7 +2505,7 @@ Requires a Secret Key (sk_test_* or sk_live_*) via --key, RECUR_SECRET_KEY, or r
 //#endregion
 //#region src/cli.ts
 const program = new Command();
-program.name("recur").description("Recur CLI — Taiwan subscription payment platform.\nManage products, customers, subscriptions, webhooks, and more.\nAll commands require a Secret Key (sk_test_* or sk_live_*).").version("0.1.0").option("--key <secret-key>", "API secret key (sk_test_* or sk_live_*)").option("--profile <name>", "Use a named profile from ~/.recur/credentials.json").option("--base-url <url>", "API base URL (default: https://api.recur.tw)").option("--output <format>", "Output format: json, table, csv, ndjson (default: json when piped, table otherwise)").hook("preAction", (thisCommand) => {
+program.name("recur").description("Recur CLI — Taiwan subscription payment platform.\nManage products, customers, subscriptions, webhooks, and more.\nAll commands require a Secret Key (sk_test_* or sk_live_*).").version("0.1.1").option("--key <secret-key>", "API secret key (sk_test_* or sk_live_*)").option("--profile <name>", "Use a named profile from ~/.recur/credentials.json").option("--base-url <url>", "API base URL (default: https://api.recur.tw)").option("--output <format>", "Output format: json, table, csv, ndjson (default: json when piped, table otherwise)").hook("preAction", (thisCommand) => {
 	const opts = thisCommand.opts();
 	if (!opts.output) opts.output = process.stdout.isTTY ? "table" : "json";
 	if (![

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recur-tw/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "CLI for Recur - Taiwan's subscription payment platform",
   "keywords": [
     "recur",