@garuhq/cli 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 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

package/dist/index.cjs

@@ -15,7 +15,7 @@ var pc__default = /*#__PURE__*/_interopDefault(pc);
 // src/index.ts
 
 // src/version.ts
-var CLI_VERSION = "0.12.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;
@@ -1435,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");
@@ -1656,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,
@@ -1671,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(
@@ -1824,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.12.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": "4.0.0",
+    "@garuhq/node": "4.1.0",
     "@inquirer/prompts": "8.4.1",
     "commander": "12.0.0",
     "picocolors": "1.0.0",