freshbooks-cli

FreshBooks CLI 用于管理发票、客户和计费。当用户提到新书、发票、账单、客户或会计时使用。

# freshbooks-cli

CLI tool for managing FreshBooks invoices, clients, and billing. Uses the official `@freshbooks/api` SDK.

## Install

```bash
npm install -g @haseebuchiha/freshbooks-cli
```

Requires `.npmrc` with `@haseebuchiha:registry=https://npm.pkg.github.com` for GitHub Package Registry.

## Setup (once)

Authenticate with FreshBooks OAuth2. You must use the `--manual` flag (localhost redirect does not work with FreshBooks).

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

This opens the browser. Authorize, then copy the code from the page and paste it into the CLI. Tokens are stored at `~/.config/freshbooks-cli/config.json` (0600 permissions) and auto-refresh before expiry.

Verify: `freshbooks auth status`

## Auth commands

- `freshbooks auth login --client-id <id> --client-secret <secret> --manual` -- authenticate via OAuth2 OOB flow
- `freshbooks auth logout` -- clear stored tokens and credentials
- `freshbooks auth status` -- show account ID, token expiry, and auth state
- `freshbooks auth refresh` -- manually refresh the access token

## Clients commands

- `freshbooks clients list [-p <page>] [--per-page <n>] [-s <search>]` -- list clients, search by org name
- `freshbooks clients get <id>` -- get a single client by ID
- `freshbooks clients create [--fname <name>] [--lname <name>] [--email <email>] [--organization <org>]` -- create a client
- `freshbooks clients create --data '<json>'` -- create with full JSON payload
- `freshbooks clients update <id> --data '<json>'` -- update a client

Example: `freshbooks clients create --fname "Taha" --organization "abcg.io"`

## Invoices commands

- `freshbooks invoices list [-p <page>] [--per-page <n>]` -- list invoices
- `freshbooks invoices get <id>` -- get a single invoice by ID
- `freshbooks invoices create --client-id <id> [--lines '<json>']` -- create an invoice with line items
- `freshbooks invoices create --client-id <id> --data '<json>'` -- create with full JSON payload
- `freshbooks invoices update <id> --data '<json>'` -- update an invoice
- `freshbooks invoices archive <id>` -- archive an invoice (no permanent delete in FreshBooks)
- `freshbooks invoices share-link <id>` -- get a shareable link for an invoice

### Line items format

Lines are a JSON array. Each line has `name`, `qty`, and `unitCost` (money object):

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

Example (full invoice create):

```bash
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"}}]'
```

## Workflows

### Onboard a new client and invoice them

1. `freshbooks clients create --fname "Name" --organization "Company"` -- note the returned `id`
2. `freshbooks invoices create --client-id <id> --lines '[...]'` -- create the invoice
3. `freshbooks invoices share-link <invoice-id>` -- get shareable link

### Look up billing for a client

1. `freshbooks clients list -s "company name"` -- find the client ID
2. `freshbooks invoices list` -- list all invoices (filter by client in output)
3. `freshbooks invoices get <id>` -- get full invoice details

## Notes

- All output is JSON to stdout. Pipe to `jq` for filtering: `freshbooks clients list | jq '.clients[].organization'`
- Money values are `{"amount": "string", "code": "USD"}`. The amount is always a string like `"30000.00"`, never a number. Do not use parseFloat on money.
- `archive` sets vis_state=1. FreshBooks does not support permanent deletion.
- Tokens auto-refresh. If refresh fails, re-run `freshbooks auth login --client-id <id> --client-secret <secret> --manual`.
- Client credentials can also be read from env vars `FRESHBOOKS_CLIENT_ID` and `FRESHBOOKS_CLIENT_SECRET` (takes priority over stored config).
- Always use `--manual` for auth login. The localhost callback redirect URI does not work with FreshBooks.
- Confirm with the user before creating invoices or modifying billing data.

---

## 中文说明

# freshbooks-cli

用于管理 FreshBooks 发票、客户和计费的 CLI 工具。使用官方的 `@freshbooks/api` SDK。

## Install

```bash
npm install -g @haseebuchiha/freshbooks-cli
```

需要在 `.npmrc` 中配置 `@haseebuchiha:registry=https://npm.pkg.github.com` 以使用 GitHub Package Registry。

## Setup（一次性）

通过 FreshBooks OAuth2 进行身份验证。你必须使用 `--manual` 标志（localhost 重定向在 FreshBooks 上不可用）。

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

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

验证：`freshbooks auth status`

## Auth 命令

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

## Clients 命令

- `freshbooks clients list [-p <page>] [--per-page <n>] [-s <search>]` —— 列出客户，按组织名称搜索
- `freshbooks clients get <id>` —— 按 ID 获取单个客户
- `freshbooks clients create [--fname <name>] [--lname <name>] [--email <email>] [--organization <org>]` —— 创建客户
- `freshbooks clients create --data '<json>'` —— 使用完整 JSON 负载创建
- `freshbooks clients update <id> --data '<json>'` —— 更新客户

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

## Invoices 命令

- `freshbooks invoices list [-p <page>] [--per-page <n>]` —— 列出发票
- `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`（money 对象）：

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

示例（完整创建发票）：

```bash
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 "Name" --organization "Company"` —— 记下返回的 `id`
2. `freshbooks invoices create --client-id <id> --lines '[...]'` —— 创建发票
3. `freshbooks invoices share-link <invoice-id>` —— 获取可分享链接

### 查询某个客户的计费信息

1. `freshbooks clients list -s "company name"` —— 找到客户 ID
2. `freshbooks invoices list` —— 列出所有发票（在输出中按客户过滤）
3. `freshbooks invoices get <id>` —— 获取完整发票详情

## 注意事项

- 所有输出均为 JSON 到 stdout。可通过管道传给 `jq` 进行过滤：`freshbooks clients list | jq '.clients[].organization'`
- 金额值为 `{"amount": "string", "code": "USD"}`。amount 始终是字符串，例如 `"30000.00"`，绝不是数字。不要对金额使用 parseFloat。
- `archive` 会设置 vis_state=1。FreshBooks 不支持永久删除。
- 令牌会自动刷新。如果刷新失败，请重新运行 `freshbooks auth login --client-id <id> --client-secret <secret> --manual`。
- 客户端凭据也可从环境变量 `FRESHBOOKS_CLIENT_ID` 和 `FRESHBOOKS_CLIENT_SECRET` 读取（优先级高于存储的配置）。
- auth login 时始终使用 `--manual`。localhost 回调重定向 URI 在 FreshBooks 上不可用。
- 在创建发票或修改计费数据之前，请先与用户确认。