名称： freshbooks-cli
描述： FreshBooks 命令行工具，用于管理发票、客户和账单。当用户提到 freshbooks、开票、账单、客户或会计时使用。
元数据： {"openclaw":{"emoji":"💰","requires":{"bins":["freshbooks"]},"install":[{"id":"npm","kind":"node","package":"@haseebuchiha/freshbooks-cli","bins":["freshbooks"],"label":"安装 freshbooks-cli (npm)"}]}}

freshbooks-cli

用于管理 FreshBooks 发票、客户和账单的命令行工具。基于官方 @freshbooks/api SDK 构建。

安装

npm install -g @haseebuchiha/freshbooks-cli

需要配置 .npmrc 文件，添加 @haseebuchiha:registry=https://npm.pkg.github.com 以使用 GitHub Package Registry。

初始设置（仅需一次）

通过 FreshBooks OAuth2 进行身份验证。必须使用 --manual 标志（FreshBooks 不支持 localhost 重定向）。

freshbooks auth login \
  --client-id "<FRESHBOOKS_CLIENT_ID>" \
  --client-secret "<FRESHBOOKS_CLIENT_SECRET>" \
  --manual

此命令将打开浏览器。授权后，从页面复制代码并粘贴到 CLI 中。令牌将存储在 ~/.config/freshbooks-cli/config.json（权限为 0600），并在过期前自动刷新。

验证：freshbooks auth status

身份验证命令

• freshbooks auth login --client-id <id> --client-secret <secret> --manual —— 通过 OAuth2 OOB 流程进行身份验证
• freshbooks auth logout —— 清除存储的令牌和凭据
• freshbooks auth status —— 显示账户 ID、令牌过期时间和认证状态
• freshbooks auth refresh —— 手动刷新访问令牌

客户管理命令

• freshbooks clients list [-p <页码>] [--per-page <数量>] [-s <搜索词>] —— 列出客户，可按组织名称搜索
• freshbooks clients get <id> —— 根据 ID 获取单个客户信息
• freshbooks clients create [--fname <名>] [--lname <姓>] [--email <邮箱>] [--organization <组织>] —— 创建客户
• freshbooks clients create --data '<json>' —— 使用完整 JSON 数据创建客户
• freshbooks clients update <id> --data '<json>' —— 更新客户信息

示例：freshbooks clients create --fname "Taha" --organization "abcg.io"

发票管理命令

• freshbooks invoices list [-p <页码>] [--per-page <数量>] —— 列出发票
• freshbooks invoices get <id> —— 根据 ID 获取单个发票
• freshbooks invoices create --client-id <客户ID> [--lines '<json>'] —— 创建包含明细项目的发票
• freshbooks invoices create --client-id <客户ID> --data '<json>' —— 使用完整 JSON 数据创建发票
• freshbooks invoices update <id> --data '<json>' —— 更新发票
• freshbooks invoices archive <id> —— 归档发票（FreshBooks 不支持永久删除）
• freshbooks invoices share-link <id> —— 获取发票的可分享链接

明细项目格式

明细项目为 JSON 数组。每项包含 name（名称）、qty（数量）和 unitCost（单价，为货币对象）：

[
  {"name": "Web Services", "qty": 1, "unitCost": {"amount": "15000.00", "code": "USD"}},
  {"name": "App Services", "qty": 1, "unitCost": {"amount": "15000.00", "code": "USD"}}
]

示例（完整发票创建命令）：

freshbooks invoices create --client-id 818183 \
  --lines '[{"name":"Web Services","qty":1,"unitCost":{"amount":"15000.00","code":"USD"}},{"name":"App Services","qty":1,"unitCost":{"amount":"15000.00","code":"USD"}}]'

常用工作流

为新客户创建并发送发票

1. freshbooks clients create --fname "姓名" --organization "公司" —— 记录返回的 id
2. freshbooks invoices create --client-id <客户ID> --lines '[...]' —— 创建发票
3. freshbooks invoices share-link <发票ID> —— 获取可分享链接

查询客户账单信息

1. freshbooks clients list -s "公司名称" —— 查找客户 ID
2. freshbooks invoices list —— 列出所有发票（可在输出中按客户筛选）
3. freshbooks invoices get <发票ID> —— 获取发票完整详情

注意事项

• 所有输出均为 JSON 格式至 stdout。可通过 jq 进行过滤：freshbooks clients list | jq '.clients[].organization'
• 货币值格式为 {"amount": "字符串", "code": "USD"}。金额始终为字符串（如 "30000.00"），切勿使用 parseFloat 处理。
• archive 操作会将 vis_state 设为 1。FreshBooks 不支持永久删除。
• 令牌会自动刷新。若刷新失败，请重新运行 freshbooks auth login --client-id <id> --client-secret <secret> --manual。
• 客户端凭据也可从环境变量 FRESHBOOKS_CLIENT_ID 和 FRESHBOOKS_CLIENT_SECRET 读取（优先级高于存储的配置）。
• 身份验证登录时务必使用 --manual 标志。FreshBooks 不支持 localhost 回调重定向 URI。
• 创建发票或修改账单数据前，请务必与用户确认。