@garuhq/cli 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -3,6 +3,62 @@
 All notable changes to `@garuhq/cli` are documented in this file. Format:
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
 
+## [0.10.0] — 2026-08-22
+
+### Added
+
+- **`garu customers` — manage your customer base.** `create`, `list`, `get`,
+  `update`, `set-billing-email`, `clear-billing-email`, `delete`. Backed by
+  the new `/api/v1/customers`, keyed on `uuid`.
+
+### Changed
+
+- **`@garuhq/node` bumped to `2.0.0`.** Breaking for `garu.customers.*` (see
+  that package's changelog); does not affect any other `garu-cli` command —
+  `customers` is a new command group in this release, so nothing here
+  changes behavior.
+
+## [0.9.0] — 2026-08-21
+
+### Added
+
+- **`garu installment-plans` — boleto parcelado (carnê).** Sell a product as
+  2–12 monthly bank slips: `create`, `list`, `get`, `reissue`, `postpone`,
+  `mark-paid`, `cancel`, `request-refund`.
+- **`garu refund-requests` — refunds Garu cannot make for you.** A boleto
+  cannot be reversed and Celcoin exposes no Pix devolução, so this records the
+  request and waits for you to confirm the transfer: `list`, `get`, `confirm`,
+  `reject`.
+
+### Changed
+
+- **`@garuhq/node` bumped to `1.1.0`.**
+
+### Breaking
+
+- **`charges` commands now use the versioned `/api/v1/charges` API**, via
+  `@garuhq/node@1.0.0`+.
+  - `garu charges get <id>` and `garu charges refund <id>` now take the
+    charge's **uuid**, not the old numeric id.
+  - `garu charges refund --amount` is now **decimal BRL / reais** (e.g.
+    `10.00`), not centavos. The `--idempotency-key` flag on `refund` is
+    removed — the v1 refund route doesn't take one.
+  - `garu charges create --type credit_card` keeps its flag spelling; the
+    underlying SDK call now sends `creditCard` and a `card` object (was
+    `cardInfo`) — no CLI-facing change beyond the `--card-*` flags already in
+    use.
+  - `garu charges list --payment-method` now takes `credit_card` (was
+    `creditcard`, undocumented and unvalidated); `--status` is validated
+    against the new friendly status set (`pending`, `authorized`, `paid`,
+    `failed`, `expired`, `canceled`, `refund_pending`, `refunded`,
+    `chargeback`).
+  - `garu charges get`/`list` output: `charge.uuid` (was `.id`),
+    `charge.paymentMethod` (was `.paymentMethodId`), `charge.createdAt` /
+    `.expiresAt` (was `.date` / `.deadline`), and a new `charge.chargedTotal`
+    field (what was actually charged, vs. `.amount`, the product's base
+    price). `charges list`'s response shape is now `{ data, count, totalCount,
+totalPages }` (was `{ data, meta }`).
+
 ## [0.8.0] — 2026-07-18
 
 ### Changed

package/README.md

@@ -156,13 +156,13 @@ garu charges list --status paid --limit 50
 garu charges list --search "Maria" --payment-method pix
 ```
 
-| Flag                        | Description                                 |
-| --------------------------- | ------------------------------------------- |
-| `--page <n>`                | Page number (1-based)                       |
-| `--limit <n>`               | Items per page (1-100)                      |
-| `--status <status>`         | Filter by status (e.g. `paid`, `pending`)   |
-| `--search <query>`          | Search by customer name, email, or document |
-| `--payment-method <method>` | Filter: `pix`, `creditcard`, `boleto`       |
+| Flag                        | Description                                                                                                                    |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `--page <n>`                | Page number (1-based)                                                                                                          |
+| `--limit <n>`               | Items per page (1-100)                                                                                                         |
+| `--status <status>`         | Filter by status: `pending`, `authorized`, `paid`, `failed`, `expired`, `canceled`, `refund_pending`, `refunded`, `chargeback` |
+| `--search <query>`          | Search by customer name, email, or document                                                                                    |
+| `--payment-method <method>` | Filter: `pix`, `credit_card`, `boleto`                                                                                         |
 
 ---
 
@@ -211,32 +211,31 @@ garu charges create --type credit_card --product-id prod-uuid \
 
 ### `garu charges get`
 
-Fetch a single charge by ID.
+Fetch a single charge by its uuid.
 
 ```bash
-garu charges get 4472
-garu charges get 4472 --json | jq '.status'
+garu charges get 6f1c9b2e-4a7d-4f0b-9a3e-1d2c3b4a5e6f
+garu charges get 6f1c9b2e-4a7d-4f0b-9a3e-1d2c3b4a5e6f --json | jq '.status'
 ```
 
 ---
 
 ### `garu charges refund`
 
-Refund a charge (full or partial).
+Refund a charge by its uuid (full or partial).
 
 ```bash
 # Full refund
-garu charges refund 4472
+garu charges refund 6f1c9b2e-4a7d-4f0b-9a3e-1d2c3b4a5e6f
 
-# Partial refund (1000 centavos = R$10.00)
-garu charges refund 4472 --amount 1000 --reason "customer_request"
+# Partial refund, in decimal BRL / reais
+garu charges refund 6f1c9b2e-4a7d-4f0b-9a3e-1d2c3b4a5e6f --amount 10.00 --reason "customer_request"
 ```
 
-| Flag                      | Description                                       |
-| ------------------------- | ------------------------------------------------- |
-| `--amount <centavos>`     | Partial refund amount in centavos (omit for full) |
-| `--reason <text>`         | Optional refund reason                            |
-| `--idempotency-key <key>` | Idempotency key (auto-generated if omitted)       |
+| Flag               | Description                                                        |
+| ------------------ | ------------------------------------------------------------------ |
+| `--amount <reais>` | Partial refund amount in decimal BRL, e.g. `10.00` (omit for full) |
+| `--reason <text>`  | Optional refund reason                                             |
 
 ---
 
@@ -328,6 +327,118 @@ The process **exits non-zero** when:
 
 ---
 
+### `garu installment-plans create`
+
+Sell a product as **boleto parcelado (carnê)** — a purchase split into 2–12
+monthly bank slips. This is seller-financed consumer credit: nobody guarantees
+a boleto, so Garu never advances funds and carries none of the default risk.
+Only the first slip is registered at creation; the rest are emitted month by
+month once parcela 1 compensates.
+
+```bash
+garu installment-plans create \
+  --product-id 40381e8e-6ee7-4b8e-9393-766a6e2109d2 \
+  --customer-id 4821 --installments 12
+
+# Attribute the sale to an affiliate (fixed for the whole carnê) and pick
+# the first due date
+garu installment-plans create \
+  --product-id 40381e8e-6ee7-4b8e-9393-766a6e2109d2 \
+  --customer-id 4821 --installments 6 \
+  --first-due-date 2026-10-05 --affiliate-id 5
+```
+
+| Flag                      | Description                                                     |
+| ------------------------- | --------------------------------------------------------------- |
+| `--product-id <uuid>`     | Product uuid (must have boleto parcelado enabled) — required    |
+| `--customer-id <n>`       | Customer id — required                                          |
+| `--installments <n>`      | 2–12 installments — required                                    |
+| `--first-due-date <date>` | First installment due date (default: today)                     |
+| `--affiliate-id <n>`      | Attribute the sale to this affiliate (fixed for the whole plan) |
+| `--idempotency-key <key>` | Idempotency key (auto-generated if omitted)                     |
+
+---
+
+### `garu installment-plans` — other subcommands
+
+| Command                                                         | Description                                                              |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `list [--page --limit --customer-id --product-id --status ...]` | List carnês (`--status` repeatable; `--due-from/--due-to`)               |
+| `get <uuid>`                                                    | Fetch a carnê with every installment: due date, status, barcode and PDF  |
+| `reissue <uuid> <number>`                                       | Issue a segunda via for one installment once its slip has expired        |
+| `postpone <uuid> <number> --new-due-date <date>`                | Move one installment to a later date (its siblings keep theirs)          |
+| `mark-paid <uuid> <number>`                                     | Record an installment as paid when the webhook never arrived             |
+| `cancel <uuid> [--note]`                                        | Cancel the carnê — stops emission/reminders, cancels open provider slips |
+| `request-refund <uuid> [--amount --reason]`                     | Ask for the carnê to be refunded (see `garu refund-requests` below)      |
+
+---
+
+### `garu refund-requests`
+
+Garu cannot reverse a boleto, and Celcoin exposes no Pix devolução, so a
+refund on either rail is a request-and-notify flow: you transfer the money
+back yourself, then tell Garu it happened. Card charges keep their automated
+reversal via `garu charges refund`.
+
+```bash
+# See everything you still owe a buyer
+garu refund-requests list --status pending
+
+# After you've transferred the money back
+garu refund-requests confirm a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
+  --note "Pix devolvido em 14/08, e2e E12345678"
+
+# Decline instead — the carnê or charge is left untouched
+garu refund-requests reject a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
+  --note "Produto entregue e retirado na loja"
+```
+
+| Command                                                | Description                                                  |
+| ------------------------------------------------------ | ------------------------------------------------------------ |
+| `list [--page --limit --status --plan-id --charge-id]` | List refund requests (`--status` repeatable)                 |
+| `get <uuid>`                                           | Fetch a single refund request                                |
+| `confirm <uuid> [--note]`                              | Record that you returned the money — call AFTER the transfer |
+| `reject <uuid> [--note]`                               | Decline the request — the carnê or charge is untouched       |
+
+---
+
+### `garu customers create`
+
+Register a customer for the current seller. Registering the same `document`
+twice attaches your profile to the existing global customer instead of
+erroring — safe to call once per seller per person.
+
+```bash
+garu customers create \
+  --name "Maria Silva" --email maria@exemplo.com.br \
+  --document 12345678909 --phone 11987654321 \
+  --person-type fisica
+```
+
+| Flag                    | Description                                    |
+| ----------------------- | ---------------------------------------------- |
+| `--name <name>`         | Customer name (required)                       |
+| `--email <email>`       | Customer email (required)                      |
+| `--document <document>` | CPF (11 digits) or CNPJ (14 digits) (required) |
+| `--phone <phone>`       | Phone with area code, 10-11 digits (required)  |
+| `--person-type <type>`  | `fisica` or `juridica` (required)              |
+| `--zip-code <cep>` etc. | Address fields (all optional)                  |
+
+---
+
+### `garu customers` — other subcommands
+
+| Command                                    | Description                                                      |
+| ------------------------------------------ | ---------------------------------------------------------------- |
+| `list [--page --limit --search --status]`  | List customers (`--status overdue` filters to at-risk customers) |
+| `get <uuid>`                               | Fetch a single customer                                          |
+| `update <uuid> [...]`                      | Partial update — same flags as `create`, all optional            |
+| `set-billing-email <uuid> --email <email>` | Set the sticky per-seller billing-email override                 |
+| `clear-billing-email <uuid>`               | Clear the override, falling back to the last-used email          |
+| `delete <uuid>`                            | Unlink the customer from the current seller                      |
+
+---
+
 ### `garu doctor`
 
 Run environment diagnostics. Verifies your CLI version, API connectivity, credentials, and detects AI agent integrations.