@recur-tw/cli 0.1.0

package/AGENT.md

@@ -0,0 +1,268 @@
+---
+name: recur-cli
+version: 0.1.0
+description: Manage subscriptions, products, customers, webhooks, and checkout sessions on Recur — Taiwan's subscription payment platform.
+requires:
+  bins: ["recur"]
+  env: ["RECUR_SECRET_KEY"]
+capabilities:
+  - products
+  - customers
+  - subscriptions
+  - orders
+  - invoices
+  - webhooks
+  - checkout-sessions
+  - schema-introspection
+  - dry-run-validation
+---
+
+# Recur CLI — Agent Instructions
+
+> For AI agents using `@recur-tw/cli`. Humans: see README.md.
+
+## Quick Start
+
+```bash
+# 1. Auth (once)
+export RECUR_SECRET_KEY=sk_test_xxx
+
+# 2. Discover API shape
+recur schema --output json
+
+# 3. Drill into a specific action
+recur schema products.create --output json
+
+# 4. Dry-run first (validates locally, no API call)
+recur products create --json '{"name":"Test","price":299}' --dry-run --output json
+
+# 5. Execute
+recur products create --json '{"name":"Test","price":299}' --output json
+```
+
+## Rules (Non-Negotiable)
+
+1. **`--output json` always.** Table format is for humans. When piped, JSON is auto-detected.
+2. **`--dry-run` before mutations.** create, update, archive, cancel, delete — always dry-run first.
+3. **`--fields id,name,price` on list calls.** Minimizes tokens. Only request fields you need.
+4. **`--json` for write payloads.** Maps 1:1 to API body. Prefer over individual flags.
+5. **Confirm with user before executing writes** without `--dry-run`.
+6. **Prices are TWD integers.** `299` = NT$299. Never divide by 100.
+7. **`--immediately` is a boolean flag.** Use `--immediately` or omit. Never `--immediately false`.
+8. **IDs are CUID.** e.g. `k672i1kd6zgrw5b6w39xwpx3`. No prefix like `cus_` or `prod_`.
+
+## Authentication
+
+Priority: `--key` flag > `RECUR_SECRET_KEY` env > `~/.recur/credentials.json`
+
+```bash
+# Best for agents: env var (no filesystem writes)
+export RECUR_SECRET_KEY=sk_test_xxx
+
+# Or per-command
+recur --key sk_test_xxx products list --output json
+```
+
+## Schema Introspection
+
+The CLI is self-describing. Use `recur schema` to discover everything at runtime.
+
+```bash
+# All resources (compact overview)
+recur schema --output json
+# Returns: [{resource, description, actions: [{name, method, path, description}]}]
+
+# Specific action (full detail)
+recur schema products.create --output json
+```
+
+### Schema Fields
+
+| Field | What it tells you |
+|-------|-------------------|
+| `bodySchema[field].required` | Must be provided |
+| `bodySchema[field].enum` | Valid values (array) |
+| `bodySchema[field].cliFlag` | CLI flag when different from API field (e.g. `--product-id` for `productId`) |
+| `responseFields[].name` | Field name for `--fields` |
+| `responseFields[].type` | `string`, `number`, `boolean`, `datetime`, `object`, `array` |
+| `responseFields[].description` | What this field contains |
+| `responseFields[].nullable` | `true` if field can be null |
+| `supportsDryRun` | Whether `--dry-run` is available |
+| `pagination.cursor` | Cursor param name (e.g. `starting_after`) |
+| `pagination.defaultLimit` | Default page size |
+| `pagination.maxLimit` | Max page size |
+
+### Example Schema Output
+
+```json
+{
+  "resource": "products",
+  "action": "create",
+  "method": "POST",
+  "path": "/v1/products",
+  "bodySchema": {
+    "name": { "type": "string", "description": "Product name", "required": true },
+    "price": { "type": "number", "description": "Price in TWD (integer)", "required": true },
+    "interval": { "type": "string", "description": "Billing interval", "enum": ["monthly", "yearly"] }
+  },
+  "responseFields": [
+    { "name": "id", "type": "string", "description": "Product ID (CUID)" },
+    { "name": "price", "type": "number", "description": "Price in TWD (integer)" },
+    { "name": "active", "type": "boolean" }
+  ],
+  "supportsDryRun": true
+}
+```
+
+## Output Parsing
+
+| Stream | Contains | Parse with |
+|--------|----------|------------|
+| **stdout** | Data only (JSON/CSV/NDJSON/table) | `jq`, JSON.parse |
+| **stderr** | Warnings, errors, `[dry-run]` labels | Ignore or log |
+| **Exit 0** | Success | Check code |
+| **Exit 1** | Error | Read stderr |
+
+```bash
+# Capture data, discard warnings
+result=$(recur products list --fields id,name --output json 2>/dev/null)
+
+# NDJSON for streaming (one JSON object per line)
+recur customers list --output ndjson --fields id,email 2>/dev/null
+```
+
+### Error Shape
+
+Errors print to stderr as `Error: [code] message`. The API error body follows:
+
+```json
+{
+  "error": {
+    "code": "not_found",
+    "message": "Product not found",
+    "doc_url": "https://docs.recur.tw/api#errors"
+  }
+}
+```
+
+### Dry-Run Behavior
+
+- Validates payload locally (required fields, enum values, numeric types)
+- Prints validated payload to stdout as JSON
+- Labels `[dry-run]` to stderr
+- **No API call is made**
+- Exit 1 if validation fails, exit 0 if valid
+
+```bash
+# Dry-run output:
+# stderr: [dry-run] Would create product:
+# stdout: {"name":"Test","price":299,"type":"SUBSCRIPTION"}
+recur products create --json '{"name":"Test","price":299,"type":"SUBSCRIPTION"}' --dry-run --output json
+```
+
+## Agent Workflow Patterns
+
+### Pattern 1: Lookup → Act → Verify
+
+```bash
+# 1. Find the customer
+email=$(recur customers list --fields id,email --output json 2>/dev/null | jq -r '.[] | select(.email=="user@example.com") | .id')
+
+# 2. Dry-run the cancel
+recur subscriptions cancel "$sub_id" --dry-run --output json
+
+# 3. Confirm with user, then execute
+recur subscriptions cancel "$sub_id" --output json
+```
+
+### Pattern 2: Minimal Reads
+
+```bash
+# Bad: fetches all fields (wastes tokens)
+recur products list --output json
+
+# Good: only what you need
+recur products list --fields id,name,price --output json
+```
+
+### Pattern 3: Schema-Driven Discovery
+
+When you don't know the API shape, introspect first:
+
+```bash
+# What resources exist?
+recur schema --output json 2>/dev/null | jq '.[].resource'
+
+# What can I do with subscriptions?
+recur schema subscriptions.cancel --output json 2>/dev/null | jq '{bodySchema, supportsDryRun}'
+```
+
+## Error Recovery
+
+All errors include machine-parseable hints:
+
+| Error | CLI behavior |
+|-------|-------------|
+| Unknown resource | Lists available resources |
+| Unknown action | Lists available actions for that resource |
+| Missing required field | Lists missing field names |
+| Invalid enum value | Lists valid values |
+| Invalid ID | Describes what's wrong (path traversal, control chars) |
+| HTTP 404 | Suggests checking ID or slug |
+
+## Available Resources
+
+| Resource | Actions | Writes | Paginated |
+|----------|---------|--------|-----------|
+| products | list, get, create, update, archive | --dry-run, --json | No |
+| customers | list, get, update | --dry-run, --json | Yes |
+| subscriptions | list, get, cancel | --dry-run, --json | Yes |
+| orders | list, get | Read-only | Yes |
+| invoices | list, get | Read-only | Yes |
+| webhooks | list, create, test, delete, listen | --dry-run, --json | No |
+| checkouts | create, get | --dry-run, --json | No |
+
+## Context Budget Tips
+
+1. **`--fields`** — Only request fields you need. `--fields id,status` instead of full object.
+2. **`--limit`** — Set explicit limits. Default is 10-20 but say `--limit 5` if you only need a few.
+3. **Pipe to `jq`** — Extract what you need: `recur products list --output json 2>/dev/null | jq '.[0].id'`
+4. **Schema caching** — Call `recur schema` once per session, not per command.
+5. **NDJSON** — For large lists, process line-by-line instead of loading entire array.
+
+## Local Webhook Development
+
+`recur webhooks listen` forwards live webhook events to a local URL via SSE relay. Use this during development to test webhook handlers without deploying to a public URL.
+
+```bash
+# Forward all events to local server
+recur webhooks listen http://localhost:3000/api/webhooks --output json
+
+# Filter specific event types (client-side filtering)
+recur webhooks listen http://localhost:3000/api/webhooks --events checkout.completed,order.paid
+```
+
+### How it works
+
+1. CLI connects to Recur's SSE relay with your Secret Key
+2. Relay assigns a per-session signing secret (`whsec_*`)
+3. When Recur dispatches a webhook event, the relay pushes it to the CLI via SSE
+4. CLI POSTs the event to your local URL with these headers:
+   - `X-Recur-Signature` — HMAC-SHA256 signature (verify with the signing secret)
+   - `X-Recur-Event-Type` — e.g. `checkout.completed`
+   - `X-Recur-Event-Id` — event ID
+   - `X-Recur-Timestamp` — ISO 8601 timestamp
+
+### Agent usage notes
+
+- **Not a daemon.** `listen` is a long-running foreground process — run it in a separate terminal or background process.
+- **Signing secret changes per session.** Don't cache it across sessions.
+- **Auto-reconnects** on disconnect (up to 10 consecutive failures).
+- **`--events` is client-side filtering.** All events are still sent from the relay; the CLI drops non-matching ones locally.
+- **Exit codes:** 0 = graceful shutdown (Ctrl+C / SIGTERM), 1 = max failures exceeded.
+
+## Security
+
+- All API responses are sanitized: control characters (ASCII < 0x20) are stripped from string values to prevent prompt injection.
+- Resource IDs are validated against path traversal (`..`, `/`), query injection (`?`, `#`), and control characters.
+- API keys are validated format before sending (`sk_test_*` or `sk_live_*`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Recur (recur.tw)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,368 @@
+# @recur-tw/cli
+
+Recur 訂閱金流平台的命令列工具。管理產品、客戶、訂閱、訂單等資源，同時支援人類使用與 AI Agent 整合。
+
+## 安裝
+
+```bash
+npm install -g @recur-tw/cli
+```
+
+或使用 npx 直接執行：
+
+```bash
+npx @recur-tw/cli products list
+```
+
+## 快速開始
+
+### 1. 設定 API Key
+
+前往 [Recur Dashboard](https://app.recur.tw) 取得 Secret Key（`sk_test_*` 或 `sk_live_*`），然後執行：
+
+```bash
+recur --key sk_test_xxx login
+```
+
+API Key 會安全存儲在 `~/.recur/credentials.json`（檔案權限 `0600`）。
+
+也可以透過環境變數設定：
+
+```bash
+export RECUR_SECRET_KEY=sk_test_xxx
+```
+
+### 2. 開始使用
+
+```bash
+# 列出所有產品
+recur products list
+
+# 查看訂閱狀態
+recur subscriptions list --status active
+
+# 查看客戶資料
+recur customers list --email user@example.com
+```
+
+## 指令一覽
+
+```
+recur <資源> <動作> [選項]
+```
+
+### 全域選項
+
+| 選項 | 說明 |
+|------|------|
+| `--key <sk_*>` | 指定 API Secret Key |
+| `--profile <name>` | 使用指定的 profile |
+| `--base-url <url>` | API 位址覆寫 |
+| `--output <format>` | 輸出格式：`json`、`table`（預設）、`csv` |
+| `--fields <fields>` | 逗號分隔的欄位篩選 |
+| `--dry-run` | 僅本地驗證，不發送 API 請求 |
+| `--json <payload>` | 直接傳入 JSON 作為 API request body |
+
+### 驗證管理
+
+```bash
+recur login                       # 互動式設定 API Key
+recur --key sk_test_xxx login     # 直接設定
+recur whoami                      # 顯示目前 profile
+recur profiles                    # 列出所有 profile
+recur use <profile>               # 切換 profile
+recur logout [profile]            # 移除 profile
+```
+
+#### 多環境管理
+
+```bash
+# 儲存 sandbox profile
+recur --key sk_test_xxx login --name sandbox
+
+# 儲存 production profile
+recur --key sk_live_xxx login --name production
+
+# 切換環境
+recur use production
+recur products list  # 使用 production key
+
+# 或單次指定
+recur --profile sandbox products list
+```
+
+### 產品 (Products)
+
+```bash
+recur products list                                    # 列出所有產品
+recur products list --status active                    # 篩選狀態
+recur products get <id>                                # 以 ID 查詢
+recur products get <slug>                              # 以 slug 查詢
+recur products create --name "方案" --price 299 --interval monthly --type SUBSCRIPTION
+recur products create --json '{"name":"方案","price":299,"interval":"monthly"}'
+recur products update <id> --name "新名稱"
+recur products archive <id>
+```
+
+### 客戶 (Customers)
+
+```bash
+recur customers list                                   # 列出所有客戶
+recur customers list --email user@example.com          # 以 email 篩選
+recur customers list --limit 50 --offset 100           # 分頁
+recur customers get <id>                               # 查詢客戶詳情
+recur customers update <id> --name "新名稱"
+```
+
+### 訂閱 (Subscriptions)
+
+```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 get <id>                           # 查詢訂閱詳情
+recur subscriptions cancel <id>                        # 期末取消
+recur subscriptions cancel <id> --immediately          # 立即取消
+```
+
+### 訂單 (Orders)
+
+```bash
+recur orders list                                      # 列出所有訂單
+recur orders list --status paid                        # 篩選狀態
+recur orders list --customer-id cus_xxx                # 以客戶篩選
+recur orders get <id>                                  # 查詢訂單詳情
+```
+
+### 帳單 (Invoices)
+
+```bash
+recur invoices list                                    # 列出所有帳單
+recur invoices list --subscription-id sub_xxx          # 以訂閱篩選
+recur invoices list --customer-id cus_xxx              # 以客戶篩選
+recur invoices list --status paid                      # 篩選狀態
+recur invoices get <id>                                # 查詢帳單詳情
+```
+
+### Webhook
+
+```bash
+recur webhooks list                                    # 列出所有 webhook
+recur webhooks create --url https://example.com/hook   # 建立 webhook
+recur webhooks create --json '{"url":"...","events":["checkout.completed"]}'
+recur webhooks test <id>                               # 發送測試事件
+recur webhooks test <id> --event subscription.canceled # 指定事件類型
+recur webhooks delete <id>                             # 刪除 webhook
+recur webhooks listen http://localhost:3000/api/webhooks  # 即時轉發到本地
+```
+
+### 本地 Webhook 開發（`webhooks listen`）
+
+類似 `stripe listen`，`recur webhooks listen` 讓你在本地開發時即時接收 webhook 事件，不需要公開 URL。
+
+```bash
+# 基本用法：轉發所有事件到本地伺服器
+recur webhooks listen http://localhost:3000/api/webhooks
+
+# 只轉發特定事件類型
+recur webhooks listen http://localhost:3000/api/webhooks --events checkout.completed,order.paid
+```
+
+#### 運作原理
+
+1. CLI 透過 SSE 連線到 Recur 的 relay 服務
+2. 收到一個專屬的 signing secret（`whsec_*`）
+3. 當 Recur 平台觸發 webhook 事件時，relay 即時推送到 CLI
+4. CLI 將事件 POST 到你指定的本地 URL，附帶以下 headers：
+   - `X-Recur-Signature` — HMAC-SHA256 簽名（用 signing secret 驗證）
+   - `X-Recur-Event-Type` — 事件類型
+   - `X-Recur-Event-Id` — 事件 ID
+   - `X-Recur-Timestamp` — 事件時間戳
+
+#### 輸出範例
+
+```
+  Ready! Listening for webhook events...
+
+  Signing secret: whsec_abc123def456...
+  Forwarding to:  http://localhost:3000/api/webhooks
+  Environment:    sandbox
+
+12:03:45  ->  checkout.completed [evt_abc123]  200 (23ms)
+12:03:46  ->  subscription.activated [evt_def456]  200 (18ms)
+12:05:12  ->  invoice.paid [evt_ghi789]  500 Internal Server Error (45ms)
+```
+
+#### 選項
+
+| 選項 | 說明 |
+|------|------|
+| `--events <types>` | 逗號分隔的事件類型篩選（CLI 端過濾） |
+| `--relay-url <url>` | 覆寫 relay 服務 URL（開發用） |
+
+#### 注意事項
+
+- 需要 Secret Key（`sk_test_*` 或 `sk_live_*`）
+- 斷線時自動重連（最多 10 次連續失敗後退出）
+- `Ctrl+C` 優雅關閉
+- Signing secret 每次連線都會重新產生
+
+### 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 get <id>                               # 查詢 session 狀態
+```
+
+## 輸出格式
+
+### Table（預設，適合人類閱讀）
+
+```bash
+$ recur products list --fields name,price,type
+
+name             price  type
+───────────────  ─────  ────────────
+大師方案 - 月繳  799    SUBSCRIPTION
+超級方案 - 月繳  499    SUBSCRIPTION
+
+2 results
+```
+
+### JSON（適合程式解析與 AI Agent）
+
+```bash
+$ recur products list --output json
+
+[
+  { "id": "prod_xxx", "name": "大師方案", "price": 799 },
+  ...
+]
+```
+
+搭配 `jq` 使用：
+
+```bash
+recur products list --output json | jq '.[].name'
+recur subscriptions list --output json | jq '[.[] | select(.status == "ACTIVE")]'
+```
+
+### CSV（適合匯出與試算表）
+
+```bash
+$ recur customers list --output csv --fields email,name > customers.csv
+```
+
+### 欄位篩選
+
+用 `--fields` 減少輸出量，適合腳本和 AI Agent 控制 context window：
+
+```bash
+recur products list --fields id,name,price
+recur customers list --fields email,name --output json
+```
+
+## AI Agent 整合
+
+此 CLI 遵循 [Agent-Optimized CLI](https://justin.poehnelt.com/posts/rewrite-your-cli-for-ai-agents/) 設計原則：
+
+### Schema 自省
+
+Agent 可以透過 `recur schema` 動態查詢 API 規格，不需要讀文件：
+
+```bash
+# 列出所有可用資源
+recur schema
+
+# 查看特定資源的所有動作
+recur schema products
+
+# 查看特定動作的完整參數定義
+recur schema products.create
+```
+
+輸出包含 `method`、`path`、`params`、`bodySchema`、`responseFields`、`supportsDryRun` 等結構化資訊。
+
+### Raw JSON Payload
+
+`--json` 讓 Agent 直接傳入 API body，不需要逐一對應 flag：
+
+```bash
+recur products create --json '{"name":"Pro Plan","price":599,"interval":"monthly","type":"SUBSCRIPTION"}'
+```
+
+### Dry Run
+
+所有寫入操作支援 `--dry-run`，讓 Agent 先驗證再執行：
+
+```bash
+recur products create --dry-run --json '{"name":"Test","price":299}'
+# [dry-run] Would create product:
+# { "name": "Test", "price": 299 }
+```
+
+### Input 驗證（防止 AI 幻覺）
+
+CLI 內建多層輸入驗證，防止 Agent 送出錯誤的 ID 或惡意輸入：
+
+- Resource ID 前綴驗證（`prod_*`、`cus_*`、`sub_*` 等）
+- 路徑穿越偵測（`../`、`/`、`\`）
+- 特殊字元阻擋（`?`、`#`、`%`）
+- 控制字元過濾
+
+## 驗證方式
+
+API Key 的解析優先順序：
+
+1. `--key` 參數（最高優先）
+2. `RECUR_SECRET_KEY` 環境變數
+3. `~/.recur/credentials.json` 中的 active profile
+
+### API Key 類型
+
+| 類型 | 格式 | 用途 |
+|------|------|------|
+| Secret Key (Sandbox) | `sk_test_*` | 測試環境，完整權限 |
+| Secret Key (Production) | `sk_live_*` | 正式環境，完整權限 |
+
+CLI 僅接受 Secret Key。Publishable Key（`pk_*`）僅供前端 SDK 使用。
+
+### 安全性
+
+- API Key 以 `0600` 權限存儲在 `~/.recur/credentials.json`
+- CLI 不直接連接資料庫，所有操作經由 API server 驗證
+- 每個 API Key 綁定一個 Organization，資料完全隔離
+- Key 以 SHA-256 hash 存儲在 server 端
+
+## 程式化使用
+
+`@recur-tw/cli` 也提供 library API，可在 Node.js 中直接使用：
+
+```typescript
+import { RecurClient, resolveSecretKey, resolveBaseUrl } from '@recur-tw/cli'
+
+const client = new RecurClient({
+  baseUrl: resolveBaseUrl({}),
+  secretKey: resolveSecretKey({}),
+})
+
+const products = await client.get('/v1/products')
+```
+
+## 系統需求
+
+- Node.js >= 18
+- 作業系統：macOS、Linux、Windows
+
+## 授權
+
+MIT
+
+## 相關連結
+
+- [Recur 官網](https://recur.tw)
+- [API 文件](https://recur.tw/docs/api)
+- [SDK (recur-tw)](https://www.npmjs.com/package/recur-tw)
+- [Dashboard](https://app.recur.tw)

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };