@garuhq/cli 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 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.13.0] — 2026-08-22
+
+### Added
+
+- `--idempotency-key <key>` on `garu customers create`, `garu charges refund`,
+  and `garu installment-plans request-refund` (auto-generated if omitted).
+  The gateway now dedupes all three against the header (bumped
+  `@garuhq/node` to 4.1.0), so a retried command can no longer register a
+  duplicate customer or open a second refund request.
+
+## [0.12.0] — 2026-08-22
+
+### Changed
+
+- **`garu scheduled-charges` now targets `/api/v1/scheduled-charges`.**
+  `list`/`attempts` pretty-print output reports `count`/`totalCount`/
+  `totalPages` instead of a `page`/`total` counter. No command flags or
+  arguments changed — scheduled-charge ids were already opaque strings
+  (`sch_...`), so this is a wire-level move, not an identifier change.
+- **`@garuhq/node` bumped to `4.0.0`.** Breaking for
+  `garu.scheduledCharges.list()`/`.listAttempts()` (see that package's
+  changelog); `garu-cli`'s own commands are unaffected beyond the
+  pretty-print header above.
+
 ## [0.11.0] — 2026-08-22
 
 ### Changed

package/dist/index.cjs

@@ -15,7 +15,7 @@ var pc__default = /*#__PURE__*/_interopDefault(pc);
 // src/index.ts
 
 // src/version.ts
-var CLI_VERSION = "0.11.0";
+var CLI_VERSION = "0.13.0";
 var CliError = class extends Error {
   code;
   exitCode;
@@ -490,6 +490,7 @@ 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;
@@ -559,6 +560,7 @@ async function customersCreateCommand(opts) {
   if (opts.neighborhood !== void 0) params.neighborhood = opts.neighborhood;
   if (opts.city !== void 0) params.city = opts.city;
   if (opts.state !== void 0) params.state = opts.state;
+  if (opts.idempotencyKey !== void 0) params.idempotencyKey = opts.idempotencyKey;
   const customer = await garu.customers.create(params);
   printResult(customer, { ...opts, prettyPrint: prettyCustomer });
   return customer;
@@ -809,6 +811,7 @@ async function installmentPlansRequestRefundCommand(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 request = await garu.installmentPlans.requestRefund(opts.uuid, params);
   printResult(request, { ...opts, prettyPrint: prettyRefundRequest });
   return request;
@@ -1226,10 +1229,8 @@ function prettyScheduledCharge(c) {
   return lines.join("\n");
 }
 function prettyScheduledChargeList(list) {
-  if (list.data.length === 0) {
-    return `No scheduled charges found (page ${list.meta.page}/${list.meta.totalPages || 1})`;
-  }
-  const header = `Scheduled charges (page ${list.meta.page}/${list.meta.totalPages || "?"}, ${list.meta.total} total)`;
+  if (list.data.length === 0) return "No scheduled charges found";
+  const header = `Scheduled charges (${list.count} of ${list.totalCount} total, ${list.totalPages} page(s))`;
   const rows = list.data.map(
     (c) => `  ${c.id.padEnd(20)}  ${String(c.status).padEnd(18)}  ${String(c.type).padEnd(9)}  ${String(c.amount).padStart(10)}  ${c.dueDate}`
   );
@@ -1252,10 +1253,8 @@ function prettyScheduledChargeDetail(detail) {
   return lines.join("\n");
 }
 function prettyAttemptList(list) {
-  if (list.data.length === 0) {
-    return `No billing attempts found (page ${list.meta.page}/${list.meta.totalPages || 1})`;
-  }
-  const header = `Billing attempts (page ${list.meta.page}/${list.meta.totalPages || "?"}, ${list.meta.total} total)`;
+  if (list.data.length === 0) return "No billing attempts found";
+  const header = `Billing attempts (${list.count} of ${list.totalCount} total, ${list.totalPages} page(s))`;
   const rows = list.data.map(
     (a) => `  cycle ${String(a.cycleNumber).padStart(3)}  #${a.attemptNumber}  ${a.status.padEnd(10)}  ${a.paymentMethod.padEnd(7)}  ${a.failureCode ?? ""}  ${a.attemptedAt}`
   );
@@ -1439,13 +1438,14 @@ Recipes:
     "--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) => {
+  ).option("--reason <text>", "optional refund reason").option("--idempotency-key <key>", "idempotency key (auto-generated if omitted)").action(async (id, cmdOpts) => {
     const base = toCommandOptions(program);
     await chargesRefundCommand({
       ...base,
       id,
       amount: cmdOpts.amount,
-      reason: cmdOpts.reason
+      reason: cmdOpts.reason,
+      idempotencyKey: cmdOpts.idempotencyKey
     }).catch((err) => printErrorAndExit(err, base));
   });
   const scheduled = program.command("scheduled-charges").description("Schedule, inspect, and act on future-dated charges");
@@ -1660,7 +1660,7 @@ Recipes:
     );
   });
   const customers = program.command("customers").description("Manage your customer base");
-  customers.command("create").description("Register a customer for the current seller (dedup by document)").requiredOption("--name <name>", "customer name").requiredOption("--email <email>", "customer email").requiredOption("--document <document>", "CPF (11 digits) or CNPJ (14 digits), digits only").requiredOption("--phone <phone>", "phone with area code, 10-11 digits").requiredOption("--person-type <type>", "'fisica' or 'juridica'").option("--zip-code <cep>", "ZIP code, 8 digits").option("--street <street>", "street address").option("--number <number>", "address number").option("--complement <text>", "address complement").option("--neighborhood <text>", "neighborhood").option("--city <city>", "city").option("--state <uf>", "2-letter state code, e.g. SP").action(async (cmdOpts) => {
+  customers.command("create").description("Register a customer for the current seller (dedup by document)").requiredOption("--name <name>", "customer name").requiredOption("--email <email>", "customer email").requiredOption("--document <document>", "CPF (11 digits) or CNPJ (14 digits), digits only").requiredOption("--phone <phone>", "phone with area code, 10-11 digits").requiredOption("--person-type <type>", "'fisica' or 'juridica'").option("--zip-code <cep>", "ZIP code, 8 digits").option("--street <street>", "street address").option("--number <number>", "address number").option("--complement <text>", "address complement").option("--neighborhood <text>", "neighborhood").option("--city <city>", "city").option("--state <uf>", "2-letter state code, e.g. SP").option("--idempotency-key <key>", "idempotency key (auto-generated if omitted)").action(async (cmdOpts) => {
     const base = toCommandOptions(program);
     await customersCreateCommand({
       ...base,
@@ -1675,7 +1675,8 @@ Recipes:
       complement: cmdOpts.complement,
       neighborhood: cmdOpts.neighborhood,
       city: cmdOpts.city,
-      state: cmdOpts.state
+      state: cmdOpts.state,
+      idempotencyKey: cmdOpts.idempotencyKey
     }).catch((err) => printErrorAndExit(err, base));
   });
   customers.command("list").description("List customers with pagination and search").option("--page <n>", "page number (1-based)", (v) => parseInt(v, 10)).option("--limit <n>", "items per page (1-100)", (v) => parseInt(v, 10)).option("--search <query>", "search by name, email, or document").option(
@@ -1828,15 +1829,18 @@ Recipes:
     "--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));
-  });
+  ).option("--reason <text>", "optional reason").option("--idempotency-key <key>", "idempotency key (auto-generated if omitted)").action(
+    async (uuid, cmdOpts) => {
+      const base = toCommandOptions(program);
+      await installmentPlansRequestRefundCommand({
+        ...base,
+        uuid,
+        amount: cmdOpts.amount,
+        reason: cmdOpts.reason,
+        idempotencyKey: cmdOpts.idempotencyKey
+      }).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>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garuhq/cli",
-  "version": "0.11.0",
+  "version": "0.13.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": "3.0.0",
+    "@garuhq/node": "4.1.0",
     "@inquirer/prompts": "8.4.1",
     "commander": "12.0.0",
     "picocolors": "1.0.0",