xero-cli-bin 1.7.4 → 1.7.5

package/bin/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/bin/README.md

@@ -0,0 +1,666 @@
+# Xero CLI
+
+[![Go Version](https://img.shields.io/go.mod/1.21)](https://golang.org/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![Release](https://img.shields.io/github/v/release/MMHK/xero-cli)](https://github.com/MMHK/xero-cli/releases)
+
+Xero Accounting API 的命令行工具，使用 OAuth2 PKCE 流程進行認證。
+
+## 功能特性
+
+- ✅ OAuth2 PKCE 認證流程（適合 CLI/桌面應用）
+- ✅ **Config 配置管理系統**（獨立的 config 命令）
+- ✅ 支援 Refresh Token 離線訪問（60 天）
+- ✅ AES-256-GCM 加密儲存 Token 和 Config（機器綁定）
+- ✅ 扁平化專案結構，易於理解和維護
+- ✅ 多種查詢功能：發票、聯絡人、帳戶、付款、貸項通知單
+- ✅ 可作為 AI Agent Skill 整合到自動化流程
+
+## 快速開始
+
+### 安裝方式
+
+#### 方法一：下載預編譯 Binary（推薦）
+
+從 [GitHub Releases](https://github.com/MMHK/xero-cli/releases) 下載適合您系統的版本：
+
+| 平台 | 架構 | 下載 |
+|------|------|------|
+| Windows | x86_64 (amd64) | `xero-cli_Windows_x86_64.zip` |
+| Windows | arm64 | `xero-cli_Windows_arm64.zip` |
+| macOS | x86_64 (Intel) | `xero-cli_Darwin_x86_64.tar.gz` |
+| macOS | arm64 (M1/M2/M3) | `xero-cli_Darwin_arm64.tar.gz` |
+| Linux | x86_64 (amd64) | `xero-cli_Linux_x86_64.tar.gz` |
+| Linux | arm64 | `xero-cli_Linux_arm64.tar.gz` |
+
+**安裝步驟：**
+
+```bash
+# macOS/Linux
+tar -xzf xero-cli_<OS>_<ARCH>.tar.gz
+chmod +x xero-cli
+sudo mv xero-cli /usr/local/bin/
+
+# Windows (PowerShell)
+Expand-Archive xero-cli_Windows_x86_64.zip -DestinationPath C:\Program Files\xero-cli
+# 將 C:\Program Files\xero-cli 加入 PATH
+```
+
+**驗證安裝：**
+
+```bash
+# 檢查校驗和
+sha256sum -c checksums.txt
+
+# 檢查版本
+./xero-cli --version
+./xero-cli -V
+```
+
+#### 方法二：從原始碼編譯
+
+```bash
+git clone https://github.com/MMHK/xero-cli.git
+cd xero-cli
+go build -o xero-cli.exe
+```
+
+### 2. 設定
+
+#### 方法一：使用 Config 命令（推薦）
+
+```bash
+# 初始化配置（交互式）
+xero-cli config --init
+
+# 查看配置
+xero-cli config
+
+# 更新配置
+xero-cli config --update
+
+# 重置配置
+xero-cli config --reset
+```
+
+**配置儲存位置**：
+- Windows: `C:\Users\<user>\AppData\Roaming\xero-cli\config.json`
+- macOS: `/Users/<user>/Library/Application Support/xero-cli/config.json`
+- Linux: `/home/<user>/.config/xero-cli/config.json`
+
+**安全特性**：
+- AES-256-GCM 加密儲存
+- 機器綁定（防止跨機器使用）
+- 文件權限 0600（僅所有者可讀寫）
+
+#### 方法二：使用 .env 文件
+
+建立 `.env` 檔案：
+
+```env
+XERO_CLIENT_ID=your_client_id_here
+XERO_CLIENT_SECRET=your_client_secret_here  # PKCE 可選，一般 OAuth 必需
+XERO_REDIRECT_URI=http://localhost:3456/callback
+XERO_SCOPES=openid profile email accounting.transactions accounting.settings offline_access
+```
+
+**預設 Scopes**：
+```
+openid profile email accounting.transactions accounting.settings accounting.contacts offline_access
+```
+
+**配置來源優先級**：
+1. CLI flags (`--client-id`, `--secret`, ...) - 最高優先級
+2. 環境變數 (`.env`) - 中優先級
+3. 加密 config.json - 低優先級
+4. 預設值 - 最低優先級
+
+### 3. 使用
+
+```bash
+# 認證（使用保存的配置）
+./xero-cli auth
+
+# 強制重新認證
+./xero-cli auth --force
+
+# 切換 Tenant/Organization
+./xero-cli auth --switch
+
+# 檢查狀態
+./xero-cli status
+
+# 查詢發票
+./xero-cli invoices list --type ACCREC --status AUTHORISED
+
+# 查詢聯絡人
+./xero-cli contacts list --type customer
+
+# 搜尋發票（使用 SearchTerm）
+./xero-cli invoices list --search-term "INV-2024"
+
+# 搜尋聯絡人（使用 SearchTerm）
+./xero-cli contacts list --search-term "Smith"
+
+# 查詢貸項通知單
+./xero-cli creditnotes list --type ACCREC --status AUTHORISED
+
+# 查詢剩餘可沖銷金額 > 0 的貸項通知單
+./xero-cli creditnotes list --where "RemainingCredit>0"
+
+# JSON 輸出
+./xero-cli invoices list --json
+
+# 詳細模式
+./xero-cli status -v
+```
+
+## 命令參考
+
+| 命令 | 用途 | 範例 |
+|------|------|------|
+| `auth` | 啟動認證 | `xero-cli auth` |
+| `auth --force` | 強制重新認證 | `xero-cli auth --force` |
+| `auth --switch` | 切換 Tenant | `xero-cli auth --switch` |
+| `config` | 配置管理 | `xero-cli config` |
+| `config --init` | 初始化配置 | `xero-cli config --init` |
+| `config --update` | 更新配置 | `xero-cli config --update` |
+| `config --reset` | 重置配置 | `xero-cli config --reset` |
+| `status` | 檢查狀態 | `xero-cli status` |
+| `refresh` | 刷新 Token | `xero-cli refresh` |
+| `revoke` | 撤銷授權 | `xero-cli revoke` |
+| `connections` | 列出組織 | `xero-cli connections` |
+| `invoices list` | 發票列表 | `xero-cli invoices list --type ACCREC` |
+| `invoices get` | 單一發票 | `xero-cli invoices get <uuid>` |
+| `contacts list` | 聯絡人列表 | `xero-cli contacts list --type customer` |
+| `contacts get` | 單一聯絡人 | `xero-cli contacts get <uuid>` |
+| `accounts list` | 科目列表 | `xero-cli accounts list --type BANK` |
+| `accounts get` | 單一科目 | `xero-cli accounts get <code>` |
+| `payments list` | 付款列表 | `xero-cli payments list --type AR` |
+| `payments get` | 單一付款 | `xero-cli payments get <uuid>` |
+| `creditnotes list` | 貸項通知單列表 | `xero-cli creditnotes list --type ACCREC` |
+| `creditnotes get` | 單一貸項通知單 | `xero-cli creditnotes get <uuid>` |
+
+### 通用篩選參數
+
+| 參數 | 說明 | 預設 | 範圍 |
+|------|------|------|------|
+| `--page` | 頁碼 | 1 | 1-N |
+| `--page-size` | 每頁數量 | 50 | 1-100 |
+| `--order-by` | 排序欄位 | varies | 任意欄位名稱 |
+| `--sort-direction` | 排序方向 | varies | ASC/DESC |
+| `--where` | WHERE 條件 | - | Xero 語法 |
+| `--search-term` | 搜尋關鍵字 | - | 文字搜尋 |
+| `--json` | JSON 輸出 | false | - |
+
+### SearchTerm 搜尋功能
+
+`--search-term` 參數提供快速文字搜尋功能，適用於以下場景：
+
+**Invoices（發票搜尋）**：
+```bash
+# 搜尋發票號碼或參考號
+xero-cli invoices list --search-term "INV-2024"
+
+# 搜尋參考號包含 "REF123" 的應收發票
+xero-cli invoices list --search-term "REF123" --type ACCREC
+
+# 結合其他篩選條件
+xero-cli invoices list --search-term "INV" --status AUTHORISED --page-size 20
+```
+
+搜尋範圍：`InvoiceNumber`, `Reference`（不區分大小寫）
+
+**Contacts（聯絡人搜尋）**：
+```bash
+# 搜尋聯絡人名稱、郵件等
+xero-cli contacts list --search-term "Smith"
+
+# 搜尋客戶且名稱包含 "john"
+xero-cli contacts list --search-term "john" --type customer
+
+# 結合排序
+xero-cli contacts list --search-term "ABC" --order-by Name --sort-direction ASC
+```
+
+搜尋範圍：`Name`, `FirstName`, `LastName`, `ContactNumber`, `CompanyNumber`, `EmailAddress`（不區分大小寫）
+
+**與 WHERE 的差異**：
+- `--search-term`：快速全文搜尋，Xero API 內部優化，效能佳
+- `--where`：靈活的條件組合，支持複雜邏輯運算
+
+建議優先使用 `--search-term` 進行簡單文字搜尋，複雜條件再使用 `--where`。
+
+### Order By 範例
+
+```bash
+# 依日期倒序（預設）
+xero-cli invoices list --order-by Date --sort-direction DESC
+
+# 依金額倒序（大額在前）
+xero-cli invoices list --order-by Total --sort-direction DESC
+
+# 依名稱正序（A-Z）
+xero-cli contacts list --order-by Name --sort-direction ASC
+
+# 依聯絡人名稱排序
+xero-cli invoices list --order-by Contact.Name --sort-direction ASC
+
+# 依剩餘可沖銷金額排序（貸項通知單）
+xero-cli creditnotes list --order-by RemainingCredit --sort-direction DESC
+
+# 結合 SearchTerm 搜尋
+xero-cli invoices list --search-term "INV" --order-by Date --sort-direction DESC
+xero-cli contacts list --search-term "ABC" --order-by Name --sort-direction ASC
+```
+
+**Xero API 優化排序欄位**：
+- **Invoices**: `InvoiceId`, `UpdatedDateUTC`, `Date`（預設：UpdatedDateUTC ASC, InvoiceId ASC）
+- **Contacts**: `UpdatedDateUTC`, `ContactId`（預設：UpdatedDateUTC ASC, ContactId ASC）
+- **Accounts**: `Code`（預設：Code ASC）
+- **Payments**: `UpdatedDateUTC`, `Date`, `PaymentId`（預設：UpdatedDateUTC ASC, PaymentId ASC）
+- **CreditNotes**: `UpdatedDateUTC`, `CreditNoteId`（預設：UpdatedDateUTC ASC, CreditNoteId ASC）
+
+### WHERE 查詢範例
+
+```bash
+# 未結清應收發票
+--where "Type=='ACCREC'&&AmountDue>0"
+
+# 逾期發票
+--where "DueDate<DateTime.Today&&AmountDue>0"
+
+# 日期範圍
+--where "Date>=DateTime(2024, 01, 01) AND Date<DateTime(2024, 02, 01)"
+
+# 指定客戶
+--where "Contact.ContactID=Guid('uuid-here')"
+
+# 金額範圍
+--where "AmountDue>=5000 AND AmountDue<6000"
+
+# 貸項通知單查詢
+# 剩餘可沖銷金額 > 0
+--where "RemainingCredit>0"
+
+# 已授權的應收貸項通知單
+--where "Type=='ACCREC' && Status=='AUTHORISED'"
+
+# 依金額排序
+--order-by Total --sort-direction DESC
+
+# 文字字段部分匹配（Contacts）
+# 名稱包含 "MOTOR"
+--where "Name.Contains('MOTOR')"
+
+# 名稱以 "ABC" 開頭
+--where "Name.StartsWith('ABC')"
+
+# 名稱以 "LIMITED" 結尾
+--where "Name.EndsWith('LIMITED')"
+
+# 郵箱包含 "gmail"
+--where "EmailAddress.Contains('gmail')"
+
+# 統一編號包含 "123"
+--where "TaxNumber.Contains('123')"
+
+# 地址包含 "Road"
+--where "AddressLine1.Contains('Road')"
+
+# 城市包含 "Taipei"
+--where "City.Contains('Taipei')"
+
+# 聯絡人編號包含 "CUST"
+--where "AccountNumber.Contains('CUST')"
+
+# 組合查詢：客戶且名稱包含 "LIMITED"
+--where "IsCustomer==true && Name.Contains('LIMITED')"
+
+# 文字字段部分匹配（Invoices）
+# 參考號包含 "INV"
+--where "Reference.Contains('INV')"
+
+# 發票號以 "2024" 開頭
+--where "InvoiceNumber.StartsWith('2024')"
+
+# 文字字段部分匹配（Accounts）
+# 科目名稱包含 "Bank"
+--where "Name.Contains('Bank')"
+
+# 科目代碼以 "1" 開頭
+--where "Code.StartsWith('1')"
+
+# 文字字段部分匹配（Payments）
+# 付款參考號包含 "PAY"
+--where "Reference.Contains('PAY')"
+
+# 文字字段部分匹配（CreditNotes）
+# 參考號包含 "CN"
+--where "Reference.Contains('CN')"
+
+# 貸項單號以 "2024" 開頭
+--where "CreditNoteNumber.StartsWith('2024')"
+
+# SearchTerm vs WHERE 使用建議
+# 簡單文字搜尋（推薦使用 searchTerm，效能更佳）
+xero-cli invoices list --search-term "INV-2024"
+xero-cli contacts list --search-term "Smith"
+
+# 複雜條件組合（使用 where）
+xero-cli invoices list --search-term "INV" --where "AmountDue>0"
+```
+
+### 測試
+
+詳細測試文檔請參閱 [測試指南](./docs/guides/testing.md)。
+
+```bash
+# 運行所有測試
+go test ./...
+
+# 詳細輸出
+go test ./... -v
+
+# 覆蓋率報告
+go test ./... -cover
+
+# 單一測試
+go test -run ^TestGetPayment_Mock$ ./...
+go test -run ^TestBuildOrderClause$ ./...
+go test -run ^TestBuildCreditNoteWhereClause$ ./...
+```
+
+**測試涵蓋範圍**：70+ 測試用例（API 測試、WHERE Clause 測試、排序測試、認證測試）
+
+[查看完整測試指南 →](./docs/guides/testing.md)
+
+#### 代碼質量檢查
+
+```bash
+go fmt ./...     # 格式化
+go vet ./...     # 靜態分析
+go build -o xero-cli.exe  # 編譯
+```
+
+**測試檔案**：`api_payments_test.go`, `api_creditnotes_test.go`, `cmd_helpers_test.go`, `api_test.go`, `auth_test.go`, `config_test.go`
+
+[查看完整測試指南 →](./docs/guides/testing.md)
+
+## 專案結構
+
+```
+.
+├── main.go              # 程式入口
+├── types.go             # 資料結構定義
+├── auth.go              # OAuth2 PKCE 認證邏輯
+├── api.go               # Xero API 呼叫封裝
+├── api_*.go             # 各類 API 查詢實作
+├── config.go            # 設定與環境變數 + Config 管理
+├── config_action.go     # Config action 實現
+├── cmd.go               # CLI 命令定義
+├── cmd_helpers.go       # 命令輔助函數
+├── crypto.go            # 加密工具
+├── utils.go             # 工具函數
+├── go.mod
+├── README.md            # 主說明文件
+├── AGENTS.md            # AI 開發指導原則
+├── .env.example         # 環境變數範本
+└── docs/                # 文檔目錄
+    ├── README.md        # 開發指南索引
+    ├── api/             # API 端點文檔
+    │   ├── invoices.md
+    │   ├── contacts.md
+    │   ├── payments.md
+    │   ├── accounts.md
+    │   └── credit-notes.md
+    └── guides/          # 實現指南
+        ├── oauth2-pkce.md
+        ├── error-handling.md
+        ├── config-system.md
+        ├── testing.md
+        ├── ai-agent-integration.md
+        └── business-scenarios.md
+```
+
+## 開發命令
+
+```bash
+# 編譯
+go build -o xero-cli.exe
+
+# 執行
+go run main.go
+
+# 格式化
+go fmt ./...
+
+# Lint
+golint ./...
+
+# 靜態分析
+go vet ./...
+
+# 測試
+go test ./...
+go test -run ^TestName$ ./...
+go test -cover ./...
+```
+
+## OAuth2 PKCE 流程
+
+```
+1. 生成 code_verifier (43-128 字元)
+2. 計算 code_challenge = SHA256(verifier)
+3. 開啟瀏覽器到授權網址
+4. localhost:3456 監聽回調接收 auth_code
+5. 用 auth_code + code_verifier 交換 token
+6. 取得 access_token (30 分鐘) + refresh_token (60 天)
+7. 使用 access_token 呼叫 API
+```
+
+**授權網址**:
+```
+https://login.xero.com/identity/connect/authorize?
+  response_type=code&
+  client_id=YOUR_CLIENT_ID&
+  redirect_uri=http://localhost:3456/callback&
+  scope=openid%20profile%20email%20accounting.transactions%20offline_access&
+  state=random_state&
+  code_challenge=CHALLENGE&
+  code_challenge_method=S256
+```
+
+**Token 端點**:
+```
+POST https://identity.xero.com/connect/token
+```
+
+## Token 管理
+
+| Token 類型 | 過期時間 |
+|------------|----------|
+| Access Token | 30 分鐘 |
+| Refresh Token | 60 天 |
+
+**儲存路徑**:
+- Windows: `C:\Users\<user>\AppData\Roaming\xero-cli\tokens.json`
+- macOS: `/Users/<user>/Library/Application Support/xero-cli/tokens.json`
+- Linux: `/home/<user>/.config/xero-cli/tokens.json`
+
+**Config 儲存路徑**:
+- Windows: `C:\Users\<user>\AppData\Roaming\xero-cli\config.json`
+- macOS: `/Users/<user>/Library/Application Support/xero-cli/config.json`
+- Linux: `/home/<user>/.config/xero-cli/config.json`
+
+**加密方式**: AES-256-GCM 加密，使用機器特徵生成密鑰（綁定當前機器）
+
+**安全特性**:
+- AES-256-GCM Authenticated Encryption
+- scrypt KDF 密鑰派生 (N=32768, r=8, p=1)
+- 機器綁定（machineid.ID()）
+- 平台驗證（防止跨機器使用）
+- 文件權限 0600（僅所有者可讀寫）
+
+## 常用 Scopes
+
+| Scope | 說明 |
+|-------|------|
+| `openid profile email` | OpenID Connect 用戶資訊 |
+| `accounting.transactions` | 讀取發票、帳單、付款、**貸項通知單**等交易資料 |
+| `accounting.settings` | 讀取組織設定、科目表等基本設定資訊 |
+| `accounting.contacts` | 讀取客戶、供應商聯絡人資訊 |
+| `offline_access` | **必需** 取得 Refresh Token 以支持離線訪問 |
+
+## 安全注意事項
+
+1. **勿提交機密資訊**: `.env`、`config.json` 和 `token` 檔案必須加入 `.gitignore`
+2. **加密儲存**: Token 和 Config 使用 AES-256-GCM 加密，綁定當前機器
+3. **檔案權限**: Token 和 Config 檔案使用 0600 權限（僅所有者可讀寫）
+4. **定期撤銷**: 不再使用時執行 `./xero-cli revoke`
+5. **最小權限**: 只申請必要的 scopes
+6. **機器綁定**: Config 和 Token 無法在不同機器間遷移（安全特性）
+7. **密碼模式輸入**: Client Secret 使用隱藏輸入（不回顯）
+
+## API 基礎
+
+**Base URL**:
+```
+https://api.xero.com/api.xro/2.0/
+```
+
+**Headers**:
+```
+Authorization: Bearer <access_token>
+Xero-tenant-id: <tenant_id>
+Accept: application/json
+```
+
+**Rate Limits**:
+- 每分鐘：60 次
+- 每小時：3600 次
+- 每日：50000 次
+
+## 錯誤處理
+
+| 錯誤 | 原因 | 解決方法 |
+|------|------|----------|
+| `Not authenticated` | 未執行 auth 命令 | 執行 `xero-cli auth` |
+| `Token expired` | Access token 已過期 | 執行 `xero-cli refresh` |
+| `No connections found` | 無連接的組織 | 檢查 Xero 組織設定 |
+| `Rate limit exceeded` | 超過 API 限制 | 等待後重試 |
+
+## AI Agent Skill 整合
+
+Xero CLI 可作為 AI Agent（opencode、Cline、Cursor 等）的 CLI Skill。
+
+**快速範例**：
+
+```bash
+# AI 查詢發票
+xero-cli invoices list --type ACCREC --status AUTHORISED --json
+
+# AI 查詢客戶
+xero-cli contacts list --type customer --json
+```
+
+[查看完整 AI Agent 整合指南 →](./docs/guides/ai-agent-integration.md)
+
+## 業務場景範例
+
+完整的業務場景範例（財務報表、往來對象查詢、進階查詢、jq 整合、貸項通知單應用）請參閱：
+
+[查看業務場景範例 →](./docs/guides/business-scenarios.md)
+
+### 快速範例
+
+```bash
+# 逾期發票查詢
+xero-cli invoices list --where "Type==\"ACCREC\" && AmountDue>0 && DueDate<DateTime.Today"
+
+# 本月收款總額
+xero-cli payments list --type AR --date-from 2024-02-01 --date-to 2024-02-29 --json | jq '[.[].Amount] | add'
+
+# 貸項通知單（剩餘可沖銷金額>0）
+xero-cli creditnotes list --where "RemainingCredit>0" --order-by RemainingCredit --sort-direction DESC
+```
+
+## 自動打包與 Release
+
+本專案使用 GoReleaser 和 GitHub Actions 實現自動化多平台打包。
+
+### 支援的平台
+
+| 平台 | 架構 | 檔案格式 |
+|------|------|----------|
+| Windows | x86_64, arm64 | `.zip` |
+| macOS | x86_64 (Intel), arm64 (M1/M2/M3) | `.tar.gz` |
+| Linux | x86_64, arm64 | `.tar.gz` |
+
+### 建立 Release
+
+```bash
+# 1. 建立語義化版本標籤
+git tag v1.0.0
+
+# 2. Push 標籤到 GitHub（自動觸發打包）
+git push origin v1.0.0
+
+# 3. 前往 GitHub Actions 查看進度
+# https://github.com/MMHK/xero-cli/actions
+```
+
+### 本地測試編譯
+
+```bash
+# 安裝 GoReleaser
+go install github.com/goreleaser/goreleaser/v2@latest
+
+# 測試編譯（不建立 release）
+goreleaser build --snapshot --clean
+
+# 或使用提供的腳本
+./scripts/build-release.sh        # macOS/Linux
+.\scripts\build-release.bat       # Windows
+```
+
+### 配置檔案
+
+- `.goreleaser.yaml` - GoReleaser 配置
+- `.github/workflows/release.yml` - GitHub Actions 配置
+
+### 編譯產出
+
+每次 release 會自動生成：
+
+- 6 個平台的 binary（Windows/macOS/Linux × amd64/arm64）
+- `checksums.txt` - SHA256 校驗和
+- 自動生成的 CHANGELOG
+
+### Release 前檢查清單
+
+- [ ] 所有測試通過：`go test ./...`
+- [ ] 代碼格式化：`go fmt ./...`
+- [ ] 靜態分析：`go vet ./...`
+- [ ] 本地測試編譯：`goreleaser build --snapshot`
+
+## 開發階段
+
+- [x] 第一階段：核心認證功能
+- [x] 第二階段：API 查詢功能
+- [x] 第三階段：CLI 命令整合
+- [x] 第四階段：測試與文件
+
+## 相關資源
+
+- [Xero Developer Portal](https://developer.xero.com/app/manage)
+- [OAuth2 PKCE 文檔](https://developer.xero.com/documentation/guides/oauth2/pkce-flow)
+- [Accounting API](https://developer.xero.com/documentation/api/accounting)
+- [Go OAuth2 套件](https://pkg.go.dev/golang.org/x/oauth2)
+- [GoReleaser 官方文檔](https://goreleaser.com/)
+- [GoReleaser v2 遷移指南](https://goreleaser.com/blog/goreleaser-v2/)
+- [GitHub Actions 文檔](https://docs.github.com/en/actions)
+
+## 授權
+
+MIT License

package/bin/xero-cli

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const { join } = require('path');
+const { platform } = process;
+
+const ext = platform === 'win32' ? '.exe' : '';
+const binaryPath = join(__dirname, `xero-cli${ext}`);
+
+spawn(binaryPath, process.argv.slice(2), { stdio: 'inherit' })
+  .on('error', (err) => {
+    console.error('Failed to start xero-cli:', err.message);
+    process.exit(1);
+  })
+  .on('close', (code) => {
+    process.exit(code);
+  });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xero-cli-bin",
-  "version": "1.7.4",
+  "version": "1.7.5",
   "description": "Xero Accounting API CLI - Xero 會計 API 命令行工具",
   "bin": {
     "xero-cli": "./bin/xero-cli"