@garuhq/cli 0.7.0 → 0.9.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.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
+
+- **Products now use the versioned public API.** Via `@garuhq/node@0.16.0`,
+  `garu products create` / `update` hit `/api/v1/products` (uuid-keyed). The
+  numeric product id is no longer returned; product output shows the `uuid`.
+
+### Fixed
+
+- **`--value` is Reais, not centavos.** The flag was documented and parsed as
+  centavos; following the help (`--value 4990`) created a product priced 100×
+  (R$ 4.990,00 instead of R$ 49,90). `--value` now takes a decimal amount in
+  Reais (e.g. `49.90`). `charges` / refund `--amount` remain centavos.
+
 ## [0.7.0] — 2026-05-31
 
 ### Added

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,81 @@ 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 doctor`
 
 Run environment diagnostics. Verifies your CLI version, API connectivity, credentials, and detects AI agent integrations.

package/dist/index.cjs

@@ -15,7 +15,7 @@ var pc__default = /*#__PURE__*/_interopDefault(pc);
 // src/index.ts
 
 // src/version.ts
-var CLI_VERSION = "0.7.0";
+var CLI_VERSION = "0.9.0";
 var CliError = class extends Error {
   code;
   exitCode;
@@ -233,6 +233,185 @@ function createGaruClient(opts) {
   });
 }
 
+// src/lib/parse.ts
+function parsePositiveIntId(raw, label) {
+  const id = Number.parseInt(raw, 10);
+  if (!Number.isFinite(id) || id <= 0) {
+    throw new CliError("invalid_input", `${label} must be a positive integer (got '${raw}')`);
+  }
+  return id;
+}
+function parsePaymentMethod(raw) {
+  if (raw === "pix" || raw === "credit_card" || raw === "boleto") return raw;
+  throw new CliError(
+    "invalid_input",
+    `--type must be 'pix', 'credit_card', or 'boleto' (got '${raw}')`
+  );
+}
+function toChargePaymentMethod(type) {
+  return type === "credit_card" ? "creditCard" : type;
+}
+function parseChargePaymentMethodFilter(raw) {
+  return toChargePaymentMethod(parsePaymentMethod(raw));
+}
+var CHARGE_STATUSES = [
+  "pending",
+  "authorized",
+  "paid",
+  "failed",
+  "expired",
+  "canceled",
+  "refund_pending",
+  "refunded",
+  "chargeback"
+];
+function parseChargeStatus(raw) {
+  if (CHARGE_STATUSES.includes(raw)) return raw;
+  throw new CliError(
+    "invalid_input",
+    `--status must be one of ${CHARGE_STATUSES.join(", ")} (got '${raw}')`
+  );
+}
+var INSTALLMENT_PLAN_STATUSES = [
+  "pending_activation",
+  "active",
+  "completed",
+  "defaulted",
+  "canceled",
+  "refunded"
+];
+function parseInstallmentPlanStatus(raw) {
+  if (INSTALLMENT_PLAN_STATUSES.includes(raw)) return raw;
+  throw new CliError(
+    "invalid_input",
+    `--status must be one of ${INSTALLMENT_PLAN_STATUSES.join(", ")} (got '${raw}')`
+  );
+}
+var REFUND_REQUEST_STATUSES = ["pending", "confirmed", "rejected"];
+function parseRefundRequestStatus(raw) {
+  if (REFUND_REQUEST_STATUSES.includes(raw)) return raw;
+  throw new CliError(
+    "invalid_input",
+    `--status must be one of ${REFUND_REQUEST_STATUSES.join(", ")} (got '${raw}')`
+  );
+}
+function parseWebhookEventStatus(raw) {
+  if (raw === "pending" || raw === "success" || raw === "failed") return raw;
+  throw new CliError(
+    "invalid_input",
+    `--status must be 'pending', 'success', or 'failed' (got '${raw}')`
+  );
+}
+function parseScheduledChargeType(raw) {
+  if (raw === "one_time" || raw === "recurring") return raw;
+  throw new CliError("invalid_input", `--type must be 'one_time' or 'recurring' (got '${raw}')`);
+}
+var SCHEDULED_PAYMENT_METHODS = [
+  "pix",
+  "boleto",
+  "card",
+  "pix_automatic"
+];
+function parseCsvList(raw) {
+  return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+function parseScheduledPaymentMethods(raw) {
+  const parts = parseCsvList(raw);
+  if (parts.length === 0) {
+    throw new CliError(
+      "invalid_input",
+      `--methods must list at least one of: ${SCHEDULED_PAYMENT_METHODS.join(", ")}`
+    );
+  }
+  for (const p of parts) {
+    if (!SCHEDULED_PAYMENT_METHODS.includes(p)) {
+      throw new CliError(
+        "invalid_input",
+        `--methods entries must be one of ${SCHEDULED_PAYMENT_METHODS.join(", ")} (got '${p}')`
+      );
+    }
+  }
+  return parts;
+}
+var RECURRENCE_INTERVALS = [
+  "weekly",
+  "biweekly",
+  "monthly",
+  "bimonthly",
+  "quarterly",
+  "biannual",
+  "yearly"
+];
+function parseRecurrenceInterval(raw) {
+  if (RECURRENCE_INTERVALS.includes(raw)) return raw;
+  throw new CliError(
+    "invalid_input",
+    `--recurrence-interval must be one of ${RECURRENCE_INTERVALS.join(", ")} (got '${raw}')`
+  );
+}
+var SCHEDULED_CHARGE_STATUSES = [
+  "scheduled",
+  "due_today",
+  "overdue",
+  "paid",
+  "paused",
+  "canceled",
+  "trial",
+  "pending_tokenization",
+  "recurrence_canceled"
+];
+function parseScheduledChargeStatus(raw) {
+  if (SCHEDULED_CHARGE_STATUSES.includes(raw)) return raw;
+  throw new CliError(
+    "invalid_input",
+    `--status must be one of ${SCHEDULED_CHARGE_STATUSES.join(", ")} (got '${raw}')`
+  );
+}
+function parseIntInRange(raw, label, min, max) {
+  const trimmed = raw.trim();
+  const n = Number.parseInt(trimmed, 10);
+  if (!Number.isFinite(n) || String(n) !== trimmed || n < min || n > max) {
+    throw new CliError(
+      "invalid_input",
+      `${label} must be an integer between ${min} and ${max} (got '${raw}')`
+    );
+  }
+  return n;
+}
+function parseNonNegativeBrl(raw, label) {
+  const trimmed = raw.trim();
+  const n = Number(trimmed);
+  if (trimmed === "" || !Number.isFinite(n) || n < 0) {
+    throw new CliError(
+      "invalid_input",
+      `${label} must be a non-negative amount in BRL/reais, e.g. 49.90 (got '${raw}')`
+    );
+  }
+  return n;
+}
+function parseAmountBrl(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new CliError(
+      "invalid_input",
+      `--amount must be a positive decimal in BRL, e.g. 297.50 (got '${raw}')`
+    );
+  }
+  return n;
+}
+function parseMetadata(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CliError("invalid_input", `--metadata must be valid JSON (got '${raw}')`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new CliError("invalid_input", `--metadata must be a JSON object`);
+  }
+  return parsed;
+}
+
 // src/commands/charges.ts
 async function getClient(opts) {
   if (opts.garu) return opts.garu;
@@ -275,8 +454,9 @@ async function chargesCreateCommand(opts) {
     assertCardFieldsPresent(opts);
     charge = await garu.charges.create({
       ...base,
-      cardInfo: {
-        cardNumber: opts.cardNumber,
+      paymentMethod: toChargePaymentMethod(opts.type),
+      card: {
+        number: opts.cardNumber,
         cvv: opts.cardCvv,
         expirationDate: opts.cardExpiration,
         holderName: opts.cardHolder,
@@ -284,14 +464,17 @@ async function chargesCreateCommand(opts) {
       }
     });
   } else {
-    charge = await garu.charges.create(base);
+    charge = await garu.charges.create({
+      ...base,
+      paymentMethod: toChargePaymentMethod(opts.type)
+    });
   }
   printResult(charge, { ...opts, prettyPrint: prettyCharge });
   return charge;
 }
 async function chargesGetCommand(opts) {
   const garu = await getClient(opts);
-  const charge = await garu.charges.get(opts.id);
+  const charge = await garu.charges.retrieve(opts.id);
   printResult(charge, { ...opts, prettyPrint: prettyCharge });
   return charge;
 }
@@ -300,7 +483,6 @@ async function chargesRefundCommand(opts) {
   const params = {};
   if (opts.amount !== void 0) params.amount = opts.amount;
   if (opts.reason !== void 0) params.reason = opts.reason;
-  if (opts.idempotencyKey !== void 0) params.idempotencyKey = opts.idempotencyKey;
   const charge = await garu.charges.refund(opts.id, params);
   printResult(charge, { ...opts, prettyPrint: prettyCharge });
   return charge;
@@ -319,23 +501,26 @@ async function chargesListCommand(opts) {
 }
 function prettyChargeList(list) {
   if (list.data.length === 0) {
-    return `No charges found (page ${list.meta.page}/${list.meta.totalPages || 1})`;
+    return "No charges found";
   }
-  const header = `Charges (page ${list.meta.page}/${list.meta.totalPages || "?"}, ${list.meta.total} total)`;
+  const header = `Charges (${list.count} of ${list.totalCount} total, ${list.totalPages} page(s))`;
   const rows = list.data.map(
-    (c) => `  ${String(c.id).padStart(6)}  ${String(c.status).padEnd(14)}  ${c.paymentMethodId?.padEnd(10) ?? ""}  ${c.date}`
+    (c) => `  ${c.uuid}  ${String(c.status).padEnd(14)}  ${c.paymentMethod.padEnd(10)}  ${c.createdAt}`
   );
   return [header, ...rows].join("\n");
 }
 function prettyCharge(charge) {
   const lines = [
-    `Charge ${charge.id}`,
-    `  status:  ${charge.status}`,
-    `  amount:  ${charge.amount}`,
-    `  method:  ${charge.paymentMethodId}`,
-    `  date:    ${charge.date}`
+    `Charge ${charge.uuid}`,
+    `  status:       ${charge.status}`,
+    `  amount:       ${charge.amount}`,
+    `  chargedTotal: ${charge.chargedTotal}`,
+    `  method:       ${charge.paymentMethod}`,
+    `  createdAt:    ${charge.createdAt}`
   ];
-  if (charge.deadline) lines.push(`  deadline: ${charge.deadline}`);
+  if (charge.expiresAt) lines.push(`  expiresAt:    ${charge.expiresAt}`);
+  if (charge.refund)
+    lines.push(`  refund:       ${charge.refund.amount} (${charge.refund.reason ?? "no reason"})`);
   return lines.join("\n");
 }
 async function doctorCommand(opts = {}) {
@@ -430,6 +615,152 @@ function prettyDoctor(r) {
   ].filter((l) => l !== void 0);
   return lines.join("\n");
 }
+
+// src/commands/installment-plans.ts
+async function getClient2(opts) {
+  if (opts.garu) return opts.garu;
+  const auth = await resolveAuth({
+    ...opts.apiKey !== void 0 ? { apiKey: opts.apiKey } : {},
+    ...opts.profile !== void 0 ? { profile: opts.profile } : {}
+  });
+  return createGaruClient({
+    auth,
+    ...opts.baseUrl !== void 0 ? { baseUrl: opts.baseUrl } : {}
+  });
+}
+async function installmentPlansCreateCommand(opts) {
+  const garu = await getClient2(opts);
+  const params = {
+    productId: opts.productId,
+    customerId: opts.customerId,
+    installments: opts.installments
+  };
+  if (opts.firstDueDate !== void 0) params.firstDueDate = opts.firstDueDate;
+  if (opts.affiliateId !== void 0) params.affiliateId = opts.affiliateId;
+  if (opts.idempotencyKey !== void 0) params.idempotencyKey = opts.idempotencyKey;
+  const plan = await garu.installmentPlans.create(params);
+  printResult(plan, { ...opts, prettyPrint: prettyInstallmentPlan });
+  return plan;
+}
+async function installmentPlansListCommand(opts) {
+  const garu = await getClient2(opts);
+  const params = {};
+  if (opts.page !== void 0) params.page = opts.page;
+  if (opts.limit !== void 0) params.limit = opts.limit;
+  if (opts.customerId !== void 0) params.customerId = opts.customerId;
+  if (opts.productId !== void 0) params.productId = opts.productId;
+  if (opts.dueFrom !== void 0) params.dueFrom = opts.dueFrom;
+  if (opts.dueTo !== void 0) params.dueTo = opts.dueTo;
+  if (opts.status !== void 0 && opts.status.length > 0) {
+    params.status = opts.status.length === 1 ? opts.status[0] : opts.status;
+  }
+  const result = await garu.installmentPlans.list(params);
+  printResult(result, { ...opts, prettyPrint: prettyInstallmentPlanList });
+  return result;
+}
+async function installmentPlansGetCommand(opts) {
+  const garu = await getClient2(opts);
+  const plan = await garu.installmentPlans.get(opts.uuid);
+  printResult(plan, { ...opts, prettyPrint: prettyInstallmentPlanDetail });
+  return plan;
+}
+async function installmentPlansReissueCommand(opts) {
+  const garu = await getClient2(opts);
+  const result = await garu.installmentPlans.reissueInstallment(opts.uuid, opts.number);
+  printResult(result, { ...opts, prettyPrint: prettyReissueResult });
+  return result;
+}
+async function installmentPlansPostponeCommand(opts) {
+  const garu = await getClient2(opts);
+  const params = { newDueDate: opts.newDueDate };
+  const installment = await garu.installmentPlans.postponeInstallment(
+    opts.uuid,
+    opts.number,
+    params
+  );
+  printResult(installment, { ...opts, prettyPrint: prettyInstallment });
+  return installment;
+}
+async function installmentPlansMarkPaidCommand(opts) {
+  const garu = await getClient2(opts);
+  const installment = await garu.installmentPlans.markInstallmentPaid(opts.uuid, opts.number);
+  printResult(installment, { ...opts, prettyPrint: prettyInstallment });
+  return installment;
+}
+async function installmentPlansCancelCommand(opts) {
+  const garu = await getClient2(opts);
+  const params = {};
+  if (opts.note !== void 0) params.note = opts.note;
+  const plan = await garu.installmentPlans.cancel(opts.uuid, params);
+  printResult(plan, { ...opts, prettyPrint: prettyInstallmentPlan });
+  return plan;
+}
+async function installmentPlansRequestRefundCommand(opts) {
+  const garu = await getClient2(opts);
+  const params = {};
+  if (opts.amount !== void 0) params.amount = opts.amount;
+  if (opts.reason !== void 0) params.reason = opts.reason;
+  const request = await garu.installmentPlans.requestRefund(opts.uuid, params);
+  printResult(request, { ...opts, prettyPrint: prettyRefundRequest });
+  return request;
+}
+function prettyInstallmentPlan(p) {
+  const lines = [
+    `Installment plan ${p.uuid}`,
+    `  status:            ${p.status}`,
+    `  installments:      ${p.installmentsPaid}/${p.installments} paid`,
+    `  baseValue:         ${p.baseValue}`,
+    `  installmentAmount: ${p.installmentAmount}`,
+    `  totalScheduled:    ${p.totalScheduled}`,
+    `  totalCollected:    ${p.totalCollected}`,
+    `  firstDueDate:      ${p.firstDueDate}`
+  ];
+  if (p.product) lines.push(`  product:           ${p.product.name} (${p.product.uuid})`);
+  if (p.customer) lines.push(`  customer:          ${p.customer.name} <${p.customer.email}>`);
+  return lines.join("\n");
+}
+function prettyInstallmentPlanDetail(p) {
+  const lines = [prettyInstallmentPlan(p)];
+  if (p.installmentsDetail && p.installmentsDetail.length > 0) {
+    lines.push("  installments:");
+    for (const i of p.installmentsDetail) {
+      lines.push(
+        `    #${i.number}  ${i.status.padEnd(10)}  ${String(i.amount).padStart(10)}  due ${i.dueDate}${i.paidAt ? `  paid ${i.paidAt}` : ""}`
+      );
+    }
+  }
+  return lines.join("\n");
+}
+function prettyInstallmentPlanList(list) {
+  if (list.data.length === 0) return "No installment plans found";
+  const header = `Installment plans (${list.count} of ${list.totalCount} total, ${list.totalPages} page(s))`;
+  const rows = list.data.map(
+    (p) => `  ${p.uuid}  ${p.status.padEnd(18)}  ${p.installmentsPaid}/${p.installments} paid  ${p.firstDueDate}`
+  );
+  return [header, ...rows].join("\n");
+}
+function prettyInstallment(i) {
+  const lines = [
+    `Installment #${i.number}`,
+    `  status:  ${i.status}`,
+    `  amount:  ${i.amount}`,
+    `  dueDate: ${i.dueDate}`
+  ];
+  if (i.paidAt) lines.push(`  paidAt:  ${i.paidAt}`);
+  if (i.boleto) lines.push(`  boleto:  ${i.boleto.barcodeLine}`);
+  return lines.join("\n");
+}
+function prettyReissueResult(result) {
+  const lines = [`Reissue: ${result.status}`];
+  if (result.reason) lines.push(`  reason: ${result.reason}`);
+  if (result.installment) lines.push(prettyInstallment(result.installment));
+  return lines.join("\n");
+}
+function prettyRefundRequest(r) {
+  const lines = [`Refund request ${r.uuid}`, `  status: ${r.status}`, `  amount: ${r.amount}`];
+  if (r.reason) lines.push(`  reason: ${r.reason}`);
+  return lines.join("\n");
+}
 async function loginCommand(opts = {}) {
   const profile = opts.profile ?? "default";
   const apiKey = opts.apiKey ?? await import('@inquirer/prompts').then(
@@ -477,7 +808,7 @@ async function logoutCommand(opts = {}) {
 }
 
 // src/commands/products.ts
-async function getClient2(opts) {
+async function getClient3(opts) {
   if (opts.garu) return opts.garu;
   const auth = await resolveAuth({
     ...opts.apiKey !== void 0 ? { apiKey: opts.apiKey } : {},
@@ -508,7 +839,7 @@ function buildProductBody(opts) {
   return body;
 }
 async function productsCreateCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const params = { ...buildProductBody(opts), name: opts.name };
   const product = await garu.products.create(params);
   printSuccess(`Created product ${product.uuid ?? product.id}`, opts);
@@ -520,7 +851,7 @@ async function productsUpdateCommand(opts) {
   if (Object.keys(body).length === 0) {
     throw new CliError("invalid_input", "Nothing to update \u2014 pass at least one field to change.");
   }
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const product = await garu.products.update(opts.id, body);
   printSuccess(`Updated product ${product.uuid ?? product.id}`, opts);
   printResult(product, { ...opts, prettyPrint: prettyProduct });
@@ -536,15 +867,81 @@ function prettyProduct(p) {
   const lines = [
     `Product ${p.uuid ?? p.id}`,
     `  name:    ${p.name}`,
-    `  value:   ${p.value} (centavos)`,
+    `  value:   ${p.value} (reais)`,
     `  methods: ${methods || "(none)"}`
   ];
   if (p.description) lines.push(`  description: ${p.description}`);
   return lines.join("\n");
 }
 
+// src/commands/refund-requests.ts
+async function getClient4(opts) {
+  if (opts.garu) return opts.garu;
+  const auth = await resolveAuth({
+    ...opts.apiKey !== void 0 ? { apiKey: opts.apiKey } : {},
+    ...opts.profile !== void 0 ? { profile: opts.profile } : {}
+  });
+  return createGaruClient({
+    auth,
+    ...opts.baseUrl !== void 0 ? { baseUrl: opts.baseUrl } : {}
+  });
+}
+async function refundRequestsListCommand(opts) {
+  const garu = await getClient4(opts);
+  const params = {};
+  if (opts.page !== void 0) params.page = opts.page;
+  if (opts.limit !== void 0) params.limit = opts.limit;
+  if (opts.planId !== void 0) params.planId = opts.planId;
+  if (opts.chargeId !== void 0) params.chargeId = opts.chargeId;
+  if (opts.status !== void 0 && opts.status.length > 0) {
+    params.status = opts.status.length === 1 ? opts.status[0] : opts.status;
+  }
+  const result = await garu.refundRequests.list(params);
+  printResult(result, { ...opts, prettyPrint: prettyRefundRequestList });
+  return result;
+}
+async function refundRequestsGetCommand(opts) {
+  const garu = await getClient4(opts);
+  const request = await garu.refundRequests.get(opts.uuid);
+  printResult(request, { ...opts, prettyPrint: prettyRefundRequest2 });
+  return request;
+}
+async function refundRequestsConfirmCommand(opts) {
+  const garu = await getClient4(opts);
+  const params = {};
+  if (opts.note !== void 0) params.note = opts.note;
+  const request = await garu.refundRequests.confirm(opts.uuid, params);
+  printResult(request, { ...opts, prettyPrint: prettyRefundRequest2 });
+  return request;
+}
+async function refundRequestsRejectCommand(opts) {
+  const garu = await getClient4(opts);
+  const params = {};
+  if (opts.note !== void 0) params.note = opts.note;
+  const request = await garu.refundRequests.reject(opts.uuid, params);
+  printResult(request, { ...opts, prettyPrint: prettyRefundRequest2 });
+  return request;
+}
+function prettyRefundRequestList(list) {
+  if (list.data.length === 0) return "No refund requests found";
+  const header = `Refund requests (${list.count} of ${list.totalCount} total, ${list.totalPages} page(s))`;
+  const rows = list.data.map(
+    (r) => `  ${r.uuid}  ${r.status.padEnd(10)}  ${String(r.amount).padStart(10)}  ${r.installmentPlanId ?? r.chargeId ?? ""}`
+  );
+  return [header, ...rows].join("\n");
+}
+function prettyRefundRequest2(r) {
+  const lines = [`Refund request ${r.uuid}`, `  status: ${r.status}`, `  amount: ${r.amount}`];
+  if (r.reason) lines.push(`  reason: ${r.reason}`);
+  if (r.installmentPlanId) lines.push(`  installmentPlan: ${r.installmentPlanId}`);
+  if (r.chargeId) lines.push(`  charge: ${r.chargeId}`);
+  if (r.resolvedAt) lines.push(`  resolvedAt: ${r.resolvedAt}`);
+  if (r.sellerNote) lines.push(`  sellerNote: ${r.sellerNote}`);
+  return lines.join("\n");
+}
+
 // src/commands/scheduled-charges.ts
-async function getClient3(opts) {
+async function getClient5(opts) {
   if (opts.garu) return opts.garu;
   const auth = await resolveAuth({
     ...opts.apiKey !== void 0 ? { apiKey: opts.apiKey } : {},
@@ -581,7 +978,7 @@ function assertPixAutomaticRequirements(opts) {
 }
 async function scheduledChargesCreateCommand(opts) {
   assertPixAutomaticRequirements(opts);
-  const garu = await getClient3(opts);
+  const garu = await getClient5(opts);
   const params = {
     customerId: opts.customerId,
     amount: opts.amount,
@@ -603,7 +1000,7 @@ async function scheduledChargesCreateCommand(opts) {
   return charge;
 }
 async function scheduledChargesListCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient5(opts);
   const params = {};
   if (opts.page !== void 0) params.page = opts.page;
   if (opts.limit !== void 0) params.limit = opts.limit;
@@ -620,13 +1017,13 @@ async function scheduledChargesListCommand(opts) {
   return result;
 }
 async function scheduledChargesGetCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient5(opts);
   const detail = await garu.scheduledCharges.get(opts.id);
   printResult(detail, { ...opts, prettyPrint: prettyScheduledChargeDetail });
   return detail;
 }
 async function scheduledChargesPostponeCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient5(opts);
   const params = { newDueDate: opts.newDueDate };
   if (opts.reason !== void 0) params.reason = opts.reason;
   const charge = await garu.scheduledCharges.postpone(opts.id, params);
@@ -634,7 +1031,7 @@ async function scheduledChargesPostponeCommand(opts) {
   return charge;
 }
 async function scheduledChargesPauseCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient5(opts);
   const params = {};
   if (opts.reason !== void 0) params.reason = opts.reason;
   const charge = await garu.scheduledCharges.pause(opts.id, params);
@@ -642,13 +1039,13 @@ async function scheduledChargesPauseCommand(opts) {
   return charge;
 }
 async function scheduledChargesResumeCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient5(opts);
   const charge = await garu.scheduledCharges.resume(opts.id);
   printResult(charge, { ...opts, prettyPrint: prettyScheduledCharge });
   return charge;
 }
 async function scheduledChargesMarkPaidCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient5(opts);
   const params = { paymentDate: opts.paymentDate };
   if (opts.externalReference !== void 0) params.externalReference = opts.externalReference;
   if (opts.cycleNumber !== void 0) params.cycleNumber = opts.cycleNumber;
@@ -657,7 +1054,7 @@ async function scheduledChargesMarkPaidCommand(opts) {
   return charge;
 }
 async function scheduledChargesCancelRecurrenceCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient5(opts);
   const params = {};
   if (opts.reason !== void 0) params.reason = opts.reason;
   const charge = await garu.scheduledCharges.cancelRecurrence(opts.id, params);
@@ -665,14 +1062,14 @@ async function scheduledChargesCancelRecurrenceCommand(opts) {
   return charge;
 }
 async function scheduledChargesCancelAtPeriodEndCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient5(opts);
   const params = { enabled: opts.enabled };
   const charge = await garu.scheduledCharges.setCancelAtPeriodEnd(opts.id, params);
   printResult(charge, { ...opts, prettyPrint: prettyScheduledCharge });
   return charge;
 }
 async function scheduledChargesChangePaymentMethodCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient5(opts);
   const params = {
     paymentMethodId: opts.paymentMethodId
   };
@@ -681,13 +1078,13 @@ async function scheduledChargesChangePaymentMethodCommand(opts) {
   return charge;
 }
 async function scheduledChargesClearPaymentMethodCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient5(opts);
   const charge = await garu.scheduledCharges.clearPaymentMethod(opts.id);
   printResult(charge, { ...opts, prettyPrint: prettyScheduledCharge });
   return charge;
 }
 async function scheduledChargesAttemptsCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient5(opts);
   const params = {};
   if (opts.page !== void 0) params.page = opts.page;
   if (opts.limit !== void 0) params.limit = opts.limit;
@@ -697,7 +1094,7 @@ async function scheduledChargesAttemptsCommand(opts) {
   return result;
 }
 async function scheduledChargesChargeNowCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient5(opts);
   const result = await garu.scheduledCharges.chargeNow(opts.id);
   printResult(result, { ...opts, prettyPrint: prettyChargeNow });
   if (result.outcome === "failed" || result.outcome === "not_sent") {
@@ -761,7 +1158,7 @@ function prettyChargeNow(result) {
   if (result.reason) lines.push(`  reason:  ${result.reason}`);
   return lines.join("\n");
 }
-async function getClient4(opts) {
+async function getClient6(opts) {
   if (opts.garu) return opts.garu;
   const auth = await resolveAuth({
     ...opts.apiKey !== void 0 ? { apiKey: opts.apiKey } : {},
@@ -773,7 +1170,7 @@ async function getClient4(opts) {
   });
 }
 async function webhooksEventsListCommand(opts) {
-  const garu = await getClient4(opts);
+  const garu = await getClient6(opts);
   const params = {};
   if (opts.page !== void 0) params.page = opts.page;
   if (opts.limit !== void 0) params.limit = opts.limit;
@@ -785,19 +1182,19 @@ async function webhooksEventsListCommand(opts) {
   return result;
 }
 async function webhooksEventsGetCommand(opts) {
-  const garu = await getClient4(opts);
+  const garu = await getClient6(opts);
   const event = await garu.webhookEvents.get(opts.id);
   printResult(event, { ...opts, prettyPrint: prettyWebhookEvent });
   return event;
 }
 async function webhooksEventsRetryCommand(opts) {
-  const garu = await getClient4(opts);
+  const garu = await getClient6(opts);
   const event = await garu.webhookEvents.retry(opts.id);
   printResult(event, { ...opts, prettyPrint: prettyWebhookEvent });
   return event;
 }
 async function webhooksEventsResendCommand(opts) {
-  const garu = await getClient4(opts);
+  const garu = await getClient6(opts);
   const clone = await garu.webhookEvents.resend(opts.id);
   printSuccess(`Resent event ${opts.id} \u2192 new event ${clone.id}`, opts);
   printResult(clone, { ...opts, prettyPrint: prettyWebhookEvent });
@@ -839,135 +1236,6 @@ function prettyWebhookEvent(event) {
   return lines.join("\n");
 }
 
-// src/lib/parse.ts
-function parsePositiveIntId(raw, label) {
-  const id = Number.parseInt(raw, 10);
-  if (!Number.isFinite(id) || id <= 0) {
-    throw new CliError("invalid_input", `${label} must be a positive integer (got '${raw}')`);
-  }
-  return id;
-}
-function parsePaymentMethod(raw) {
-  if (raw === "pix" || raw === "credit_card" || raw === "boleto") return raw;
-  throw new CliError(
-    "invalid_input",
-    `--type must be 'pix', 'credit_card', or 'boleto' (got '${raw}')`
-  );
-}
-function parseWebhookEventStatus(raw) {
-  if (raw === "pending" || raw === "success" || raw === "failed") return raw;
-  throw new CliError(
-    "invalid_input",
-    `--status must be 'pending', 'success', or 'failed' (got '${raw}')`
-  );
-}
-function parseScheduledChargeType(raw) {
-  if (raw === "one_time" || raw === "recurring") return raw;
-  throw new CliError("invalid_input", `--type must be 'one_time' or 'recurring' (got '${raw}')`);
-}
-var SCHEDULED_PAYMENT_METHODS = [
-  "pix",
-  "boleto",
-  "card",
-  "pix_automatic"
-];
-function parseCsvList(raw) {
-  return raw.split(",").map((s) => s.trim()).filter(Boolean);
-}
-function parseScheduledPaymentMethods(raw) {
-  const parts = parseCsvList(raw);
-  if (parts.length === 0) {
-    throw new CliError(
-      "invalid_input",
-      `--methods must list at least one of: ${SCHEDULED_PAYMENT_METHODS.join(", ")}`
-    );
-  }
-  for (const p of parts) {
-    if (!SCHEDULED_PAYMENT_METHODS.includes(p)) {
-      throw new CliError(
-        "invalid_input",
-        `--methods entries must be one of ${SCHEDULED_PAYMENT_METHODS.join(", ")} (got '${p}')`
-      );
-    }
-  }
-  return parts;
-}
-var RECURRENCE_INTERVALS = [
-  "weekly",
-  "biweekly",
-  "monthly",
-  "bimonthly",
-  "quarterly",
-  "biannual",
-  "yearly"
-];
-function parseRecurrenceInterval(raw) {
-  if (RECURRENCE_INTERVALS.includes(raw)) return raw;
-  throw new CliError(
-    "invalid_input",
-    `--recurrence-interval must be one of ${RECURRENCE_INTERVALS.join(", ")} (got '${raw}')`
-  );
-}
-var SCHEDULED_CHARGE_STATUSES = [
-  "scheduled",
-  "due_today",
-  "overdue",
-  "paid",
-  "paused",
-  "canceled",
-  "trial",
-  "pending_tokenization",
-  "recurrence_canceled"
-];
-function parseScheduledChargeStatus(raw) {
-  if (SCHEDULED_CHARGE_STATUSES.includes(raw)) return raw;
-  throw new CliError(
-    "invalid_input",
-    `--status must be one of ${SCHEDULED_CHARGE_STATUSES.join(", ")} (got '${raw}')`
-  );
-}
-function parseIntInRange(raw, label, min, max) {
-  const trimmed = raw.trim();
-  const n = Number.parseInt(trimmed, 10);
-  if (!Number.isFinite(n) || String(n) !== trimmed || n < min || n > max) {
-    throw new CliError(
-      "invalid_input",
-      `${label} must be an integer between ${min} and ${max} (got '${raw}')`
-    );
-  }
-  return n;
-}
-function parseNonNegativeInt(raw, label) {
-  const trimmed = raw.trim();
-  const n = Number.parseInt(trimmed, 10);
-  if (!Number.isFinite(n) || String(n) !== trimmed || n < 0) {
-    throw new CliError("invalid_input", `${label} must be a non-negative integer (got '${raw}')`);
-  }
-  return n;
-}
-function parseAmountBrl(raw) {
-  const n = Number(raw);
-  if (!Number.isFinite(n) || n <= 0) {
-    throw new CliError(
-      "invalid_input",
-      `--amount must be a positive decimal in BRL, e.g. 297.50 (got '${raw}')`
-    );
-  }
-  return n;
-}
-function parseMetadata(raw) {
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    throw new CliError("invalid_input", `--metadata must be valid JSON (got '${raw}')`);
-  }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new CliError("invalid_input", `--metadata must be a JSON object`);
-  }
-  return parsed;
-}
-
 // src/index.ts
 function buildCli() {
   const program = new commander.Command();
@@ -979,7 +1247,7 @@ Recipes:
 
     # 1. Create a product with Pix Autom\xE1tico enabled
     garu products create \\
-      --name "Plano Mensal" --value 4990 \\
+      --name "Plano Mensal" --value 49.90 \\
       --pix --credit-card --pix-automatic \\
       --subscription --subscription-type monthly
 
@@ -1018,16 +1286,19 @@ Recipes:
     );
   });
   const charges = program.command("charges").description("Create, fetch, and refund charges");
-  charges.command("list").description("List charges with pagination and filters").option("--page <n>", "page number (1-based)", (v) => parseInt(v, 10)).option("--limit <n>", "items per page (1-100)", (v) => parseInt(v, 10)).option("--status <status>", "filter by status (e.g. paid, pending)").option("--search <query>", "search by customer name, email, or document").option("--payment-method <method>", "filter: pix, creditcard, boleto").action(
+  charges.command("list").description("List charges with pagination and filters").option("--page <n>", "page number (1-based)", (v) => parseInt(v, 10)).option("--limit <n>", "items per page (1-100)", (v) => parseInt(v, 10)).option(
+    "--status <status>",
+    "filter by status: pending, authorized, paid, failed, expired, canceled, refund_pending, refunded, chargeback"
+  ).option("--search <query>", "search by customer name, email, or document").option("--payment-method <method>", "filter: pix, credit_card, boleto").action(
     async (cmdOpts) => {
       const base = toCommandOptions(program);
       await chargesListCommand({
         ...base,
         page: cmdOpts.page,
         limit: cmdOpts.limit,
-        status: cmdOpts.status,
+        status: cmdOpts.status ? parseChargeStatus(cmdOpts.status) : void 0,
         search: cmdOpts.search,
-        paymentMethod: cmdOpts.paymentMethod
+        paymentMethod: cmdOpts.paymentMethod ? parseChargePaymentMethodFilter(cmdOpts.paymentMethod) : void 0
       }).catch((err) => printErrorAndExit(err, base));
     }
   );
@@ -1053,20 +1324,21 @@ Recipes:
       idempotencyKey: cmdOpts.idempotencyKey
     }).catch((err) => printErrorAndExit(err, base));
   });
-  charges.command("get <id>").description("Fetch a single charge by ID").action(async (id) => {
+  charges.command("get <id>").description("Fetch a single charge by its uuid").action(async (id) => {
     const base = toCommandOptions(program);
-    await chargesGetCommand({ ...base, id: parsePositiveIntId(id, "Charge ID") }).catch(
-      (err) => printErrorAndExit(err, base)
-    );
+    await chargesGetCommand({ ...base, id }).catch((err) => printErrorAndExit(err, base));
   });
-  charges.command("refund <id>").description("Refund a charge (full or partial)").option("--amount <centavos>", "partial refund amount in centavos", (v) => parseInt(v, 10)).option("--reason <text>", "optional refund reason").option("--idempotency-key <key>", "idempotency key (auto-generated if omitted)").action(async (id, cmdOpts) => {
+  charges.command("refund <id>").description("Refund a charge by its uuid (full or partial)").option(
+    "--amount <reais>",
+    "partial refund amount in decimal BRL, e.g. 10.00",
+    (v) => parseNonNegativeBrl(v, "--amount")
+  ).option("--reason <text>", "optional refund reason").action(async (id, cmdOpts) => {
     const base = toCommandOptions(program);
     await chargesRefundCommand({
       ...base,
-      id: parsePositiveIntId(id, "Charge ID"),
+      id,
       amount: cmdOpts.amount,
-      reason: cmdOpts.reason,
-      idempotencyKey: cmdOpts.idempotencyKey
+      reason: cmdOpts.reason
     }).catch((err) => printErrorAndExit(err, base));
   });
   const scheduled = program.command("scheduled-charges").description("Schedule, inspect, and act on future-dated charges");
@@ -1283,11 +1555,149 @@ Recipes:
       id: parsePositiveIntId(id, "Webhook event ID")
     }).catch((err) => printErrorAndExit(err, base));
   });
+  const installmentPlans = program.command("installment-plans").description("Sell a product as boleto parcelado (carn\xEA) and manage its installments");
+  installmentPlans.command("create").description("Sell a product as a carn\xEA (installments of boleto slips)").requiredOption("--product-id <uuid>", "product uuid (must have boleto parcelado enabled)").requiredOption(
+    "--customer-id <n>",
+    "customer id",
+    (v) => parsePositiveIntId(v, "--customer-id")
+  ).requiredOption(
+    "--installments <n>",
+    "2-12 installments",
+    (v) => parseIntInRange(v, "--installments", 2, 12)
+  ).option("--first-due-date <yyyy-mm-dd>", "first installment due date (default: today)").option(
+    "--affiliate-id <n>",
+    "attribute the sale to this affiliate (fixed for the whole plan)",
+    (v) => parsePositiveIntId(v, "--affiliate-id")
+  ).option("--idempotency-key <key>", "idempotency key (auto-generated if omitted)").action(async (cmdOpts) => {
+    const base = toCommandOptions(program);
+    await installmentPlansCreateCommand({
+      ...base,
+      productId: cmdOpts.productId,
+      customerId: cmdOpts.customerId,
+      installments: cmdOpts.installments,
+      firstDueDate: cmdOpts.firstDueDate,
+      affiliateId: cmdOpts.affiliateId,
+      idempotencyKey: cmdOpts.idempotencyKey
+    }).catch((err) => printErrorAndExit(err, base));
+  });
+  installmentPlans.command("list").description("List installment plans (carn\xEAs) with pagination and filters").option("--page <n>", "page number (1-based)", (v) => parseInt(v, 10)).option("--limit <n>", "items per page (1-100)", (v) => parseInt(v, 10)).option(
+    "--customer-id <n>",
+    "filter by customer id",
+    (v) => parsePositiveIntId(v, "--customer-id")
+  ).option("--product-id <uuid>", "filter by product uuid").option(
+    "--status <status>",
+    "filter by status (repeatable)",
+    (val, acc) => acc.concat(val),
+    []
+  ).option("--due-from <yyyy-mm-dd>", "lower bound for the first installment due date").option("--due-to <yyyy-mm-dd>", "upper bound for the first installment due date").action(
+    async (cmdOpts) => {
+      const base = toCommandOptions(program);
+      await installmentPlansListCommand({
+        ...base,
+        page: cmdOpts.page,
+        limit: cmdOpts.limit,
+        customerId: cmdOpts.customerId,
+        productId: cmdOpts.productId,
+        status: cmdOpts.status.length > 0 ? cmdOpts.status.map(parseInstallmentPlanStatus) : void 0,
+        dueFrom: cmdOpts.dueFrom,
+        dueTo: cmdOpts.dueTo
+      }).catch((err) => printErrorAndExit(err, base));
+    }
+  );
+  installmentPlans.command("get <uuid>").description("Fetch a carn\xEA with every installment: due date, status, barcode and PDF").action(async (uuid) => {
+    const base = toCommandOptions(program);
+    await installmentPlansGetCommand({ ...base, uuid }).catch(
+      (err) => printErrorAndExit(err, base)
+    );
+  });
+  installmentPlans.command("reissue <uuid> <number>").description("Issue a segunda via for one installment once its slip has expired").action(async (uuid, number) => {
+    const base = toCommandOptions(program);
+    await installmentPlansReissueCommand({
+      ...base,
+      uuid,
+      number: parsePositiveIntId(number, "installment number")
+    }).catch((err) => printErrorAndExit(err, base));
+  });
+  installmentPlans.command("postpone <uuid> <number>").description("Move one installment to a later due date (its siblings keep theirs)").requiredOption("--new-due-date <yyyy-mm-dd>", "new due date for this installment").action(async (uuid, number, cmdOpts) => {
+    const base = toCommandOptions(program);
+    await installmentPlansPostponeCommand({
+      ...base,
+      uuid,
+      number: parsePositiveIntId(number, "installment number"),
+      newDueDate: cmdOpts.newDueDate
+    }).catch((err) => printErrorAndExit(err, base));
+  });
+  installmentPlans.command("mark-paid <uuid> <number>").description("Record an installment as paid when the buyer paid but the webhook never arrived").action(async (uuid, number) => {
+    const base = toCommandOptions(program);
+    await installmentPlansMarkPaidCommand({
+      ...base,
+      uuid,
+      number: parsePositiveIntId(number, "installment number")
+    }).catch((err) => printErrorAndExit(err, base));
+  });
+  installmentPlans.command("cancel <uuid>").description("Cancel a carn\xEA \u2014 stops emission/reminders and cancels open provider slips").option("--note <text>", "optional note recorded on the plan").action(async (uuid, cmdOpts) => {
+    const base = toCommandOptions(program);
+    await installmentPlansCancelCommand({ ...base, uuid, note: cmdOpts.note }).catch(
+      (err) => printErrorAndExit(err, base)
+    );
+  });
+  installmentPlans.command("request-refund <uuid>").description(
+    "Ask for a carn\xEA to be refunded (Garu records the request; transfer the money yourself, then confirm with `garu refund-requests confirm`)"
+  ).option(
+    "--amount <reais>",
+    "defaults to everything the carn\xEA has collected",
+    (v) => parseNonNegativeBrl(v, "--amount")
+  ).option("--reason <text>", "optional reason").action(async (uuid, cmdOpts) => {
+    const base = toCommandOptions(program);
+    await installmentPlansRequestRefundCommand({
+      ...base,
+      uuid,
+      amount: cmdOpts.amount,
+      reason: cmdOpts.reason
+    }).catch((err) => printErrorAndExit(err, base));
+  });
+  const refundRequests = program.command("refund-requests").description("Inspect and resolve refund requests (carn\xEA and Pix/boleto)");
+  refundRequests.command("list").description("List refund requests with pagination and filters").option("--page <n>", "page number (1-based)", (v) => parseInt(v, 10)).option("--limit <n>", "items per page (1-100)", (v) => parseInt(v, 10)).option("--plan-id <uuid>", "filter by carn\xEA uuid").option("--charge-id <uuid>", "filter by charge uuid (Pix/boleto)").option(
+    "--status <status>",
+    "filter by status (repeatable): pending, confirmed, rejected",
+    (val, acc) => acc.concat(val),
+    []
+  ).action(
+    async (cmdOpts) => {
+      const base = toCommandOptions(program);
+      await refundRequestsListCommand({
+        ...base,
+        page: cmdOpts.page,
+        limit: cmdOpts.limit,
+        planId: cmdOpts.planId,
+        chargeId: cmdOpts.chargeId,
+        status: cmdOpts.status.length > 0 ? cmdOpts.status.map(parseRefundRequestStatus) : void 0
+      }).catch((err) => printErrorAndExit(err, base));
+    }
+  );
+  refundRequests.command("get <uuid>").description("Fetch a single refund request").action(async (uuid) => {
+    const base = toCommandOptions(program);
+    await refundRequestsGetCommand({ ...base, uuid }).catch(
+      (err) => printErrorAndExit(err, base)
+    );
+  });
+  refundRequests.command("confirm <uuid>").description("Record that you transferred the money back \u2014 call this AFTER the transfer").option("--note <text>", "optional note, e.g. a bank reference").action(async (uuid, cmdOpts) => {
+    const base = toCommandOptions(program);
+    await refundRequestsConfirmCommand({ ...base, uuid, note: cmdOpts.note }).catch(
+      (err) => printErrorAndExit(err, base)
+    );
+  });
+  refundRequests.command("reject <uuid>").description("Decline the request \u2014 the carn\xEA or charge is left untouched").option("--note <text>", "optional note explaining the rejection").action(async (uuid, cmdOpts) => {
+    const base = toCommandOptions(program);
+    await refundRequestsRejectCommand({ ...base, uuid, note: cmdOpts.note }).catch(
+      (err) => printErrorAndExit(err, base)
+    );
+  });
   const products = program.command("products").description("Create and update products");
   products.command("create").description("Create a product").requiredOption("--name <name>", "product name").option(
-    "--value <centavos>",
-    "price in centavos (BRL \xD7 100)",
-    (v) => parseNonNegativeInt(v, "--value")
+    "--value <reais>",
+    "price in reais / decimal BRL (e.g. 49.90)",
+    (v) => parseNonNegativeBrl(v, "--value")
   ).option("--description <text>", "product description").option("--image <url>", "HTTPS URL of the product cover image").option("--tags <list>", "comma-separated tags", parseCsvList).option("--pix", "accept PIX").option("--no-pix", "do not accept PIX").option("--boleto", "accept boleto").option("--no-boleto", "do not accept boleto").option("--credit-card", "accept credit card").option("--no-credit-card", "do not accept credit card").option("--pix-automatic", "expose Pix Autom\xE1tico on the subscription checkout").option("--no-pix-automatic", "do not expose Pix Autom\xE1tico").option(
     "--installments <n>",
     "max credit-card installments",
@@ -1316,9 +1726,9 @@ Recipes:
   products.command("update <id>").description(
     "Update a product (partial \u2014 only the flags you pass change). <id> is the numeric id or UUID"
   ).option("--name <name>", "product name").option(
-    "--value <centavos>",
-    "price in centavos (BRL \xD7 100)",
-    (v) => parseNonNegativeInt(v, "--value")
+    "--value <reais>",
+    "price in reais / decimal BRL (e.g. 49.90)",
+    (v) => parseNonNegativeBrl(v, "--value")
   ).option("--description <text>", "product description").option("--image <url>", "HTTPS URL of the product cover image").option("--tags <list>", "comma-separated tags", parseCsvList).option("--pix", "accept PIX").option("--no-pix", "do not accept PIX").option("--boleto", "accept boleto").option("--no-boleto", "do not accept boleto").option("--credit-card", "accept credit card").option("--no-credit-card", "do not accept credit card").option("--pix-automatic", "expose Pix Autom\xE1tico on the subscription checkout").option("--no-pix-automatic", "do not expose Pix Autom\xE1tico").option(
     "--installments <n>",
     "max credit-card installments",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garuhq/cli",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Official command-line interface for the Garu payment gateway.",
   "license": "MIT",
   "homepage": "https://garu.com.br",
@@ -46,7 +46,7 @@
     "prepublishOnly": "npm run check:version-sync && npm run typecheck && npm test && npm run build"
   },
   "dependencies": {
-    "@garuhq/node": "0.15.0",
+    "@garuhq/node": "1.1.0",
     "@inquirer/prompts": "8.4.1",
     "commander": "12.0.0",
     "picocolors": "1.0.0",