@recur-tw/cli 0.1.0 → 0.1.2

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.2`
 		};
 		const hasBody = opts?.body !== void 0;
 		if (hasBody) headers["Content-Type"] = "application/json";
@@ -988,6 +988,16 @@ function sanitizeResponse(data) {
 }
 //#endregion
 //#region src/output.ts
+/** Fields to hide in table mode unless explicitly requested via --fields */
+const TABLE_HIDDEN_FIELDS = new Set([
+	"object",
+	"metadata",
+	"display_order",
+	"product_family",
+	"livemode",
+	"created_at",
+	"updated_at"
+]);
 /**
 * Render data in the specified format.
 * Agent-optimized: --output json produces clean, parseable JSON to stdout.
@@ -1037,32 +1047,88 @@ function renderCsv(data, opts) {
 		console.log(values.join(","));
 	}
 }
+/**
+* Calculate display width of a string in terminal columns.
+* CJK characters (Chinese/Japanese/Korean) take 2 columns.
+* ANSI escape sequences take 0 columns.
+*/
+function displayWidth(str) {
+	const stripped = str.replace(/\x1B\[[0-9;]*[A-Za-z]/g, "");
+	let width = 0;
+	for (const char of stripped) if (isFullWidth(char.codePointAt(0))) width += 2;
+	else width += 1;
+	return width;
+}
+/**
+* Check if a Unicode code point is full-width (2 terminal columns).
+* Covers CJK Unified Ideographs, CJK Compatibility, Hangul, Fullwidth Forms, etc.
+*/
+function isFullWidth(code) {
+	return code >= 4352 && code <= 4447 || code >= 11904 && code <= 12350 || code >= 12352 && code <= 13247 || code >= 13312 && code <= 19903 || code >= 19968 && code <= 42191 || code >= 43360 && code <= 43388 || code >= 44032 && code <= 55203 || code >= 63744 && code <= 64255 || code >= 65072 && code <= 65131 || code >= 65281 && code <= 65376 || code >= 65504 && code <= 65510 || code >= 131072 && code <= 196605 || code >= 196608 && code <= 262141;
+}
+/**
+* Pad a string to target display width (CJK-aware).
+*/
+function padEndDisplay(str, targetWidth) {
+	const currentWidth = displayWidth(str);
+	if (currentWidth >= targetWidth) return str;
+	return str + " ".repeat(targetWidth - currentWidth);
+}
+/**
+* Slice a string to fit within maxWidth display columns (CJK-aware).
+* Adds '…' if truncated.
+*/
+function sliceDisplay(str, maxWidth) {
+	if (maxWidth <= 1) return "…";
+	const stripped = str.replace(/\x1B\[[0-9;]*[A-Za-z]/g, "");
+	let width = 0;
+	let result = "";
+	for (const char of stripped) {
+		const charWidth = isFullWidth(char.codePointAt(0)) ? 2 : 1;
+		if (width + charWidth > maxWidth - 1) return result + "…";
+		result += char;
+		width += charWidth;
+	}
+	return str;
+}
 function renderTable(data, opts) {
 	const rows = Array.isArray(data) ? data : [data];
 	if (rows.length === 0) {
 		console.log(pc.dim("No results"));
 		return;
 	}
-	const fields = opts.fields ?? Object.keys(rows[0]);
+	const allFields = Object.keys(rows[0]);
+	const fields = opts.fields ?? allFields.filter((f) => !TABLE_HIDDEN_FIELDS.has(f));
+	const termWidth = process.stdout.columns || 120;
+	const maxColWidth = 40;
 	const widths = {};
-	for (const field of fields) widths[field] = field.length;
+	for (const field of fields) widths[field] = displayWidth(field);
 	for (const row of rows) {
 		const record = row;
 		for (const field of fields) {
-			const val = formatValue(record[field]);
-			widths[field] = Math.min(Math.max(widths[field] ?? 0, val.length), 50);
+			const w = displayWidth(formatValue(record[field]));
+			widths[field] = Math.min(Math.max(widths[field] ?? 0, w), maxColWidth);
 		}
 	}
-	const header = fields.map((f) => pc.bold(f.padEnd(widths[f] ?? 0))).join("  ");
+	const totalGap = 2 * (fields.length - 1);
+	let totalWidth = fields.reduce((sum, f) => sum + (widths[f] ?? 0), 0) + totalGap;
+	while (totalWidth > termWidth && fields.length > 1) {
+		let widest = fields[0];
+		for (const f of fields) if ((widths[f] ?? 0) > (widths[widest] ?? 0)) widest = f;
+		if ((widths[widest] ?? 0) <= 6) break;
+		widths[widest] = (widths[widest] ?? 0) - 1;
+		totalWidth--;
+	}
+	const header = fields.map((f) => pc.bold(padEndDisplay(f, widths[f] ?? 0))).join("  ");
 	console.log(header);
 	console.log(fields.map((f) => "─".repeat(widths[f] ?? 0)).join("  "));
 	for (const row of rows) {
 		const record = row;
 		const line = fields.map((f) => {
 			const val = formatValue(record[f]);
-			const maxWidth = widths[f] ?? 50;
-			const padded = val.padEnd(maxWidth);
-			return padded.length > maxWidth ? padded.slice(0, maxWidth - 1) + "…" : padded;
+			const maxW = widths[f] ?? maxColWidth;
+			if (displayWidth(val) > maxW) return sliceDisplay(val, maxW);
+			return padEndDisplay(val, maxW);
 		}).join("  ");
 		console.log(line);
 	}
@@ -1071,7 +1137,8 @@ function renderTable(data, opts) {
 function formatValue(val) {
 	if (val === null || val === void 0) return pc.dim("—");
 	if (typeof val === "boolean") return val ? pc.green("true") : pc.dim("false");
-	if (typeof val === "object") return sanitizeString(JSON.stringify(val));
+	if (Array.isArray(val)) return pc.dim(`[${val.length} items]`);
+	if (typeof val === "object") return pc.dim("{…}");
 	return sanitizeString(String(val));
 }
 /**
@@ -1676,7 +1743,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 +2556,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.2"
 			}, { capabilities: { tools: {} } });
 			registerTools(server, client);
 			const transport = new StdioServerTransport();
@@ -2505,7 +2572,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.2").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/dist/index.mjs

@@ -187,6 +187,16 @@ function resolveBaseUrl(opts) {
 }
 //#endregion
 //#region src/output.ts
+/** Fields to hide in table mode unless explicitly requested via --fields */
+const TABLE_HIDDEN_FIELDS = new Set([
+	"object",
+	"metadata",
+	"display_order",
+	"product_family",
+	"livemode",
+	"created_at",
+	"updated_at"
+]);
 /**
 * Render data in the specified format.
 * Agent-optimized: --output json produces clean, parseable JSON to stdout.
@@ -236,32 +246,88 @@ function renderCsv(data, opts) {
 		console.log(values.join(","));
 	}
 }
+/**
+* Calculate display width of a string in terminal columns.
+* CJK characters (Chinese/Japanese/Korean) take 2 columns.
+* ANSI escape sequences take 0 columns.
+*/
+function displayWidth(str) {
+	const stripped = str.replace(/\x1B\[[0-9;]*[A-Za-z]/g, "");
+	let width = 0;
+	for (const char of stripped) if (isFullWidth(char.codePointAt(0))) width += 2;
+	else width += 1;
+	return width;
+}
+/**
+* Check if a Unicode code point is full-width (2 terminal columns).
+* Covers CJK Unified Ideographs, CJK Compatibility, Hangul, Fullwidth Forms, etc.
+*/
+function isFullWidth(code) {
+	return code >= 4352 && code <= 4447 || code >= 11904 && code <= 12350 || code >= 12352 && code <= 13247 || code >= 13312 && code <= 19903 || code >= 19968 && code <= 42191 || code >= 43360 && code <= 43388 || code >= 44032 && code <= 55203 || code >= 63744 && code <= 64255 || code >= 65072 && code <= 65131 || code >= 65281 && code <= 65376 || code >= 65504 && code <= 65510 || code >= 131072 && code <= 196605 || code >= 196608 && code <= 262141;
+}
+/**
+* Pad a string to target display width (CJK-aware).
+*/
+function padEndDisplay(str, targetWidth) {
+	const currentWidth = displayWidth(str);
+	if (currentWidth >= targetWidth) return str;
+	return str + " ".repeat(targetWidth - currentWidth);
+}
+/**
+* Slice a string to fit within maxWidth display columns (CJK-aware).
+* Adds '…' if truncated.
+*/
+function sliceDisplay(str, maxWidth) {
+	if (maxWidth <= 1) return "…";
+	const stripped = str.replace(/\x1B\[[0-9;]*[A-Za-z]/g, "");
+	let width = 0;
+	let result = "";
+	for (const char of stripped) {
+		const charWidth = isFullWidth(char.codePointAt(0)) ? 2 : 1;
+		if (width + charWidth > maxWidth - 1) return result + "…";
+		result += char;
+		width += charWidth;
+	}
+	return str;
+}
 function renderTable(data, opts) {
 	const rows = Array.isArray(data) ? data : [data];
 	if (rows.length === 0) {
 		console.log(pc.dim("No results"));
 		return;
 	}
-	const fields = opts.fields ?? Object.keys(rows[0]);
+	const allFields = Object.keys(rows[0]);
+	const fields = opts.fields ?? allFields.filter((f) => !TABLE_HIDDEN_FIELDS.has(f));
+	const termWidth = process.stdout.columns || 120;
+	const maxColWidth = 40;
 	const widths = {};
-	for (const field of fields) widths[field] = field.length;
+	for (const field of fields) widths[field] = displayWidth(field);
 	for (const row of rows) {
 		const record = row;
 		for (const field of fields) {
-			const val = formatValue(record[field]);
-			widths[field] = Math.min(Math.max(widths[field] ?? 0, val.length), 50);
+			const w = displayWidth(formatValue(record[field]));
+			widths[field] = Math.min(Math.max(widths[field] ?? 0, w), maxColWidth);
 		}
 	}
-	const header = fields.map((f) => pc.bold(f.padEnd(widths[f] ?? 0))).join("  ");
+	const totalGap = 2 * (fields.length - 1);
+	let totalWidth = fields.reduce((sum, f) => sum + (widths[f] ?? 0), 0) + totalGap;
+	while (totalWidth > termWidth && fields.length > 1) {
+		let widest = fields[0];
+		for (const f of fields) if ((widths[f] ?? 0) > (widths[widest] ?? 0)) widest = f;
+		if ((widths[widest] ?? 0) <= 6) break;
+		widths[widest] = (widths[widest] ?? 0) - 1;
+		totalWidth--;
+	}
+	const header = fields.map((f) => pc.bold(padEndDisplay(f, widths[f] ?? 0))).join("  ");
 	console.log(header);
 	console.log(fields.map((f) => "─".repeat(widths[f] ?? 0)).join("  "));
 	for (const row of rows) {
 		const record = row;
 		const line = fields.map((f) => {
 			const val = formatValue(record[f]);
-			const maxWidth = widths[f] ?? 50;
-			const padded = val.padEnd(maxWidth);
-			return padded.length > maxWidth ? padded.slice(0, maxWidth - 1) + "…" : padded;
+			const maxW = widths[f] ?? maxColWidth;
+			if (displayWidth(val) > maxW) return sliceDisplay(val, maxW);
+			return padEndDisplay(val, maxW);
 		}).join("  ");
 		console.log(line);
 	}
@@ -270,7 +336,8 @@ function renderTable(data, opts) {
 function formatValue(val) {
 	if (val === null || val === void 0) return pc.dim("—");
 	if (typeof val === "boolean") return val ? pc.green("true") : pc.dim("false");
-	if (typeof val === "object") return sanitizeString(JSON.stringify(val));
+	if (Array.isArray(val)) return pc.dim(`[${val.length} items]`);
+	if (typeof val === "object") return pc.dim("{…}");
 	return sanitizeString(String(val));
 }
 /**

package/package.json

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