xero-cli-bin 0.0.0

package/README.md

@@ -0,0 +1,219 @@
+# xero-cli-bin
+
+Xero Accounting API 命令行工具 - 透過 npx 直接使用
+
+## 快速開始
+
+### 無需安裝（推薦）
+
+```bash
+# 直接使用
+npx xero-cli-bin --version
+npx xero-cli-bin auth
+npx xero-cli-bin invoices list
+```
+
+### 全域安裝（可選）
+
+```bash
+npm install -g xero-cli-bin
+xero-cli --version
+```
+
+## 功能特點
+
+- 🔐 OAuth2 PKCE 認證
+- 📄 發票管理（查詢、取得）
+- 👥 聯絡人管理
+- 🏦 帳戶查詢
+- 💰 付款記錄查詢
+- 📊 貸項通知單查詢
+- 🔄 Token 自動更新
+- 🔒 加密儲存憑證
+
+## 系統需求
+
+- Node.js >= 14.0.0
+- 支援平台：
+  - Windows (x64, arm64)
+  - macOS (x64, arm64)
+  - Linux (x64, arm64)
+
+## 使用說明
+
+### 1. 認證
+
+```bash
+npx xero-cli-bin auth
+```
+
+首次使用需要進行 OAuth2 認證，會開啟瀏覽器引導您完成授權流程。
+
+### 2. 查看狀態
+
+```bash
+npx xero-cli-bin status
+```
+
+### 3. 查詢發票
+
+```bash
+# 列出所有發票
+npx xero-cli-bin invoices list
+
+# 查詢已授權的應收發票
+npx xero-cli-bin invoices list --type ACCREC --status AUTHORISED
+
+# 條件查詢
+npx xero-cli-bin invoices list --where "AmountDue>0"
+
+# JSON 輸出
+npx xero-cli-bin invoices list --json
+```
+
+### 4. 查詢聯絡人
+
+```bash
+# 列出客戶
+npx xero-cli-bin contacts list --type customer
+
+# 搜尋聯絡人
+npx xero-cli-bin contacts list --search-term "Smith"
+
+# 條件查詢
+npx xero-cli-bin contacts list --where "Name.Contains('ABC')"
+```
+
+### 5. 查詢帳戶
+
+```bash
+npx xero-cli-bin accounts list
+```
+
+### 6. 查詢付款
+
+```bash
+npx xero-cli-bin payments list --type AR
+```
+
+## 環境變數
+
+| 變數 | 說明 | 必填 |
+|------|------|------|
+| `XERO_CLIENT_ID` | Xero Client ID | ✅ |
+| `XERO_REDIRECT_URI` | Redirect URI | ❌ (預設：http://localhost:3456/callback) |
+| `XERO_SCOPES` | OAuth Scopes | ❌ |
+
+## 常見命令
+
+```bash
+# 認證
+npx xero-cli-bin auth
+npx xero-cli-bin auth --client-id=xxx --port=4000
+
+# 狀態
+npx xero-cli-bin status --json
+
+# 發票
+npx xero-cli-bin invoices list --type ACCREC --status AUTHORISED
+npx xero-cli-bin invoices get <invoice-uuid>
+
+# 聯絡人
+npx xero-cli-bin contacts list --type customer
+npx xero-cli-bin contacts get <contact-uuid>
+
+# 帳戶
+npx xero-cli-bin accounts list
+
+# 付款
+npx xero-cli-bin payments list --type AR
+
+# 貸項通知單
+npx xero-cli-bin creditnotes list
+
+# Token 管理
+npx xero-cli-bin refresh
+npx xero-cli-bin revoke
+
+# 說明
+npx xero-cli-bin --help
+npx xero-cli-bin --llms
+```
+
+## WHERE 子句語法
+
+`--where` 參數接受 Xero API 的 SQL-like 查詢表達式：
+
+```bash
+# 基本運算子
+npx xero-cli-bin invoices list --where "AmountDue>1000"
+npx xero-cli-bin invoices list --where "Status=\"AUTHORISED\""
+
+# 日期查詢
+npx xero-cli-bin invoices list --where "Date>=DateTime(2024, 01, 01)"
+
+# GUID 查詢
+npx xero-cli-bin contacts list --where "Contact.ContactID=Guid('123e4567-e89b-12d3-a456-426614174000')"
+
+# 部分匹配
+npx xero-cli-bin contacts list --where "Name.Contains('ABC')"
+npx xero-cli-bin contacts list --where "Name.StartsWith('Smith')"
+
+# 邏輯運算
+npx xero-cli-bin invoices list --where "Type=\"ACCREC\" AND AmountDue>0"
+npx xero-cli-bin invoices list --where "AmountDue>1000 OR Total>5000"
+```
+
+## 排序與分頁
+
+```bash
+# 排序
+npx xero-cli-bin invoices list --order-by Date --sort-direction DESC
+
+# 分頁
+npx xero-cli-bin invoices list --page 2 --page-size 50
+```
+
+## jq 整合
+
+```bash
+# 統計總額
+npx xero-cli-bin invoices list --json | jq '[.[].Total] | add'
+
+# 依客戶分組
+npx xero-cli-bin invoices list --json | \
+  jq 'group_by(.Contact.Name) | .[] | {name: .[0].Contact.Name, total: (map(.AmountDue) | add)}'
+
+# 匯出 CSV
+npx xero-cli-bin invoices list --json | \
+  jq -r '.[] | [.InvoiceNumber, .Contact.Name, .Total] | @csv'
+```
+
+## 安裝問題排除
+
+### 下載失敗
+
+如果安裝時下載失敗，請手動從 GitHub Releases 下載：
+
+```bash
+# 前往 https://github.com/mmhk/xero-cli/releases
+# 下載對應平台的壓縮檔
+# 解壓後將二進制文件放到 PATH 中
+```
+
+### 權限問題（macOS/Linux）
+
+```bash
+chmod +x $(npm root -g)/xero-cli-bin/bin/xero-cli
+```
+
+## 相關連結
+
+- [GitHub Repository](https://github.com/mmhk/xero-cli)
+- [Xero API 文件](https://developer.xero.com/documentation/)
+- [CHANGELOG](https://github.com/mmhk/xero-cli/blob/main/CHANGELOG.md)
+- [問題回報](https://github.com/mmhk/xero-cli/issues)
+
+## License
+
+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/bin/xero-cli.cmd

@@ -0,0 +1 @@
+@node "%~dp0\xero-cli" %*

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "xero-cli-bin",
+  "version": "0.0.0",
+  "description": "Xero Accounting API CLI - Xero 會計 API 命令行工具",
+  "bin": {
+    "xero-cli": "./bin/xero-cli"
+  },
+  "scripts": {
+    "postinstall": "node ./scripts/install.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mmhk/xero-cli.git"
+  },
+  "keywords": [
+    "xero",
+    "accounting",
+    "cli",
+    "xero-api",
+    "會計",
+    "發票",
+    "聯絡人"
+  ],
+  "author": "MMHK",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/mmhk/xero-cli/issues"
+  },
+  "homepage": "https://github.com/mmhk/xero-cli#readme",
+  "os": [
+    "win32",
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+const { platform, arch } = process;
+const { join, dirname } = require('path');
+const { execSync } = require('child_process');
+const fs = require('fs');
+
+const PLATFORM_MAP = {
+  win32: 'Windows',
+  darwin: 'Darwin',
+  linux: 'Linux'
+};
+
+const ARCH_MAP = {
+  x64: 'x86_64',
+  arm64: 'arm64'
+};
+
+function getBinaryName() {
+  const os = PLATFORM_MAP[platform];
+  const arch = ARCH_MAP[arch];
+  return `xero-cli_${os}_${arch}`;
+}
+
+function downloadFromGitHubRelease() {
+  const pkg = require('../package.json');
+  const version = pkg.version.replace(/^v/, '');
+  const binaryName = getBinaryName();
+  const ext = platform === 'win32' ? 'zip' : 'tar.gz';
+  const url = `https://github.com/mmhk/xero-cli/releases/download/v${version}/${binaryName}.${ext}`;
+  
+  console.log(`[xero-cli-bin] Downloading from ${url}`);
+  
+  const binDir = join(__dirname, '..');
+  const tarballPath = join(binDir, `download.${ext}`);
+  
+  try {
+    execSync(`curl -L -o "${tarballPath}" "${url}"`, { stdio: 'inherit' });
+    
+    console.log(`[xero-cli-bin] Extracting...`);
+    if (platform === 'win32') {
+      execSync(`powershell -Command "Expand-Archive -Path '${tarballPath}' -DestinationPath '${binDir}' -Force"`, { stdio: 'inherit' });
+    } else {
+      execSync(`tar -xf "${tarballPath}" -C "${binDir}"`, { stdio: 'inherit' });
+    }
+    
+    fs.unlinkSync(tarballPath);
+    
+    if (platform !== 'win32') {
+      const binaryPath = join(binDir, 'xero-cli');
+      fs.chmodSync(binaryPath, 0o755);
+    }
+    
+    console.log('[xero-cli-bin] Installation complete!');
+  } catch (error) {
+    if (fs.existsSync(tarballPath)) {
+      fs.unlinkSync(tarballPath);
+    }
+    throw error;
+  }
+}
+
+console.log(`[xero-cli-bin] Platform: ${platform} ${arch}`);
+
+try {
+  downloadFromGitHubRelease();
+} catch (error) {
+  console.error('[xero-cli-bin] Installation failed:', error.message);
+  console.error('');
+  console.error('Please install manually from:');
+  console.error('https://github.com/mmhk/xero-cli/releases');
+  process.exit(1);
+}