@garuhq/cli 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 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.7.0] — 2026-05-31
+
+### Added
+
+- **Pix Automático** (BACEN auto-debit recurring Pix) across the CLI.
+- `garu scheduled-charges create --methods pix_automatic` — schedule a
+  Pix Automático recurring series. The CLI validates locally that
+  `pix_automatic` is paired with `--type=recurring` **and** a
+  `--product-id`, returning an `invalid_input` error before any network
+  round-trip if either is missing.
+- `garu products` — a new command group wrapping the SDK's product
+  write surface:
+  - `garu products create --name <name> [...]` — create a product.
+  - `garu products update <id> [...]` — partial update by numeric id or
+    UUID; only the flags you pass are changed.
+  - Both accept `--pix-automatic` / `--no-pix-automatic` to toggle Pix
+    Automático on the product's subscription checkout, alongside
+    `--pix`, `--boleto`, `--credit-card`, `--value` (centavos),
+    `--installments`, `--subscription`, and related fields.
+- `garu --help` now includes an end-to-end **Pix Automático recurring
+  subscription** recipe (create the product, then schedule the
+  recurring charge).
+
+### Changed
+
+- `@garuhq/node` SDK bumped to 0.15.0 for `pix_automatic` on scheduled
+  charges, the `pixAutomatic` product field, and the new
+  `products.create()` / `products.update()` methods.
+
 ## [0.6.0] — 2026-05-25
 
 ### Added

package/dist/index.cjs

@@ -15,7 +15,7 @@ var pc__default = /*#__PURE__*/_interopDefault(pc);
 // src/index.ts
 
 // src/version.ts
-var CLI_VERSION = "0.6.0";
+var CLI_VERSION = "0.7.0";
 var CliError = class extends Error {
   code;
   exitCode;
@@ -476,7 +476,7 @@ async function logoutCommand(opts = {}) {
   return { cleared: opts.profile };
 }
 
-// src/commands/scheduled-charges.ts
+// src/commands/products.ts
 async function getClient2(opts) {
   if (opts.garu) return opts.garu;
   const auth = await resolveAuth({
@@ -488,6 +488,73 @@ async function getClient2(opts) {
     ...opts.baseUrl !== void 0 ? { baseUrl: opts.baseUrl } : {}
   });
 }
+function buildProductBody(opts) {
+  const body = {};
+  if (opts.name !== void 0) body.name = opts.name;
+  if (opts.value !== void 0) body.value = opts.value;
+  if (opts.description !== void 0) body.description = opts.description;
+  if (opts.image !== void 0) body.image = opts.image;
+  if (opts.tags !== void 0) body.tags = opts.tags;
+  if (opts.pix !== void 0) body.pix = opts.pix;
+  if (opts.boleto !== void 0) body.boleto = opts.boleto;
+  if (opts.creditCard !== void 0) body.creditCard = opts.creditCard;
+  if (opts.pixAutomatic !== void 0) body.pixAutomatic = opts.pixAutomatic;
+  if (opts.installments !== void 0) body.installments = opts.installments;
+  if (opts.isSubscription !== void 0) body.isSubscription = opts.isSubscription;
+  if (opts.subscriptionType !== void 0) body.subscriptionType = opts.subscriptionType;
+  if (opts.unitLabel !== void 0) body.unitLabel = opts.unitLabel;
+  if (opts.returnUrl !== void 0) body.returnUrl = opts.returnUrl;
+  if (opts.returnUrlButtonText !== void 0) body.returnUrlButtonText = opts.returnUrlButtonText;
+  return body;
+}
+async function productsCreateCommand(opts) {
+  const garu = await getClient2(opts);
+  const params = { ...buildProductBody(opts), name: opts.name };
+  const product = await garu.products.create(params);
+  printSuccess(`Created product ${product.uuid ?? product.id}`, opts);
+  printResult(product, { ...opts, prettyPrint: prettyProduct });
+  return product;
+}
+async function productsUpdateCommand(opts) {
+  const body = buildProductBody(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 product = await garu.products.update(opts.id, body);
+  printSuccess(`Updated product ${product.uuid ?? product.id}`, opts);
+  printResult(product, { ...opts, prettyPrint: prettyProduct });
+  return product;
+}
+function prettyProduct(p) {
+  const methods = [
+    p.pix ? "pix" : null,
+    p.boleto ? "boleto" : null,
+    p.creditCard ? "card" : null,
+    p.pixAutomatic ? "pix_automatic" : null
+  ].filter(Boolean).join(", ");
+  const lines = [
+    `Product ${p.uuid ?? p.id}`,
+    `  name:    ${p.name}`,
+    `  value:   ${p.value} (centavos)`,
+    `  methods: ${methods || "(none)"}`
+  ];
+  if (p.description) lines.push(`  description: ${p.description}`);
+  return lines.join("\n");
+}
+
+// src/commands/scheduled-charges.ts
+async function getClient3(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 } : {}
+  });
+}
 function buildRecurrence(opts) {
   if (opts.recurrenceInterval === void 0) return void 0;
   const recurrence = { interval: opts.recurrenceInterval };
@@ -497,8 +564,24 @@ function buildRecurrence(opts) {
   if (opts.recurrenceEndsOn !== void 0) recurrence.endsOn = opts.recurrenceEndsOn;
   return recurrence;
 }
+function assertPixAutomaticRequirements(opts) {
+  if (!opts.methods.includes("pix_automatic")) return;
+  if (opts.type !== "recurring") {
+    throw new CliError(
+      "invalid_input",
+      `--methods pix_automatic requires --type=recurring (Pix Autom\xE1tico is auto-debit recurring; got '${opts.type}')`
+    );
+  }
+  if (opts.productId === void 0) {
+    throw new CliError(
+      "invalid_input",
+      "--methods pix_automatic requires --product-id (Pix Autom\xE1tico must be enabled on a product)"
+    );
+  }
+}
 async function scheduledChargesCreateCommand(opts) {
-  const garu = await getClient2(opts);
+  assertPixAutomaticRequirements(opts);
+  const garu = await getClient3(opts);
   const params = {
     customerId: opts.customerId,
     amount: opts.amount,
@@ -520,7 +603,7 @@ async function scheduledChargesCreateCommand(opts) {
   return charge;
 }
 async function scheduledChargesListCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const params = {};
   if (opts.page !== void 0) params.page = opts.page;
   if (opts.limit !== void 0) params.limit = opts.limit;
@@ -537,13 +620,13 @@ async function scheduledChargesListCommand(opts) {
   return result;
 }
 async function scheduledChargesGetCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const detail = await garu.scheduledCharges.get(opts.id);
   printResult(detail, { ...opts, prettyPrint: prettyScheduledChargeDetail });
   return detail;
 }
 async function scheduledChargesPostponeCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const params = { newDueDate: opts.newDueDate };
   if (opts.reason !== void 0) params.reason = opts.reason;
   const charge = await garu.scheduledCharges.postpone(opts.id, params);
@@ -551,7 +634,7 @@ async function scheduledChargesPostponeCommand(opts) {
   return charge;
 }
 async function scheduledChargesPauseCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const params = {};
   if (opts.reason !== void 0) params.reason = opts.reason;
   const charge = await garu.scheduledCharges.pause(opts.id, params);
@@ -559,13 +642,13 @@ async function scheduledChargesPauseCommand(opts) {
   return charge;
 }
 async function scheduledChargesResumeCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const charge = await garu.scheduledCharges.resume(opts.id);
   printResult(charge, { ...opts, prettyPrint: prettyScheduledCharge });
   return charge;
 }
 async function scheduledChargesMarkPaidCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const params = { paymentDate: opts.paymentDate };
   if (opts.externalReference !== void 0) params.externalReference = opts.externalReference;
   if (opts.cycleNumber !== void 0) params.cycleNumber = opts.cycleNumber;
@@ -574,7 +657,7 @@ async function scheduledChargesMarkPaidCommand(opts) {
   return charge;
 }
 async function scheduledChargesCancelRecurrenceCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const params = {};
   if (opts.reason !== void 0) params.reason = opts.reason;
   const charge = await garu.scheduledCharges.cancelRecurrence(opts.id, params);
@@ -582,14 +665,14 @@ async function scheduledChargesCancelRecurrenceCommand(opts) {
   return charge;
 }
 async function scheduledChargesCancelAtPeriodEndCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(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 getClient2(opts);
+  const garu = await getClient3(opts);
   const params = {
     paymentMethodId: opts.paymentMethodId
   };
@@ -598,13 +681,13 @@ async function scheduledChargesChangePaymentMethodCommand(opts) {
   return charge;
 }
 async function scheduledChargesClearPaymentMethodCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const charge = await garu.scheduledCharges.clearPaymentMethod(opts.id);
   printResult(charge, { ...opts, prettyPrint: prettyScheduledCharge });
   return charge;
 }
 async function scheduledChargesAttemptsCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const params = {};
   if (opts.page !== void 0) params.page = opts.page;
   if (opts.limit !== void 0) params.limit = opts.limit;
@@ -614,7 +697,7 @@ async function scheduledChargesAttemptsCommand(opts) {
   return result;
 }
 async function scheduledChargesChargeNowCommand(opts) {
-  const garu = await getClient2(opts);
+  const garu = await getClient3(opts);
   const result = await garu.scheduledCharges.chargeNow(opts.id);
   printResult(result, { ...opts, prettyPrint: prettyChargeNow });
   if (result.outcome === "failed" || result.outcome === "not_sent") {
@@ -678,7 +761,7 @@ function prettyChargeNow(result) {
   if (result.reason) lines.push(`  reason:  ${result.reason}`);
   return lines.join("\n");
 }
-async function getClient3(opts) {
+async function getClient4(opts) {
   if (opts.garu) return opts.garu;
   const auth = await resolveAuth({
     ...opts.apiKey !== void 0 ? { apiKey: opts.apiKey } : {},
@@ -690,7 +773,7 @@ async function getClient3(opts) {
   });
 }
 async function webhooksEventsListCommand(opts) {
-  const garu = await getClient3(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;
@@ -702,19 +785,19 @@ async function webhooksEventsListCommand(opts) {
   return result;
 }
 async function webhooksEventsGetCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient4(opts);
   const event = await garu.webhookEvents.get(opts.id);
   printResult(event, { ...opts, prettyPrint: prettyWebhookEvent });
   return event;
 }
 async function webhooksEventsRetryCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient4(opts);
   const event = await garu.webhookEvents.retry(opts.id);
   printResult(event, { ...opts, prettyPrint: prettyWebhookEvent });
   return event;
 }
 async function webhooksEventsResendCommand(opts) {
-  const garu = await getClient3(opts);
+  const garu = await getClient4(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 });
@@ -782,9 +865,17 @@ 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"];
+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 = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  const parts = parseCsvList(raw);
   if (parts.length === 0) {
     throw new CliError(
       "invalid_input",
@@ -846,6 +937,14 @@ function parseIntInRange(raw, label, min, max) {
   }
   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) {
@@ -872,7 +971,28 @@ function parseMetadata(raw) {
 // src/index.ts
 function buildCli() {
   const program = new commander.Command();
-  program.name("garu").description("Command-line interface for the Garu payment gateway.").version(CLI_VERSION, "-v, --version").addOption(new commander.Option("--api-key <key>", "Garu API key (overrides env and credentials file)")).addOption(new commander.Option("-p, --profile <name>", "credentials profile name")).addOption(new commander.Option("--json", "emit strict JSON on stdout (forced in pipes)")).addOption(new commander.Option("-q, --quiet", "suppress status output; only print results and errors")).showHelpAfterError();
+  program.name("garu").description("Command-line interface for the Garu payment gateway.").version(CLI_VERSION, "-v, --version").addOption(new commander.Option("--api-key <key>", "Garu API key (overrides env and credentials file)")).addOption(new commander.Option("-p, --profile <name>", "credentials profile name")).addOption(new commander.Option("--json", "emit strict JSON on stdout (forced in pipes)")).addOption(new commander.Option("-q, --quiet", "suppress status output; only print results and errors")).showHelpAfterError().addHelpText(
+    "after",
+    `
+Recipes:
+  Pix Autom\xE1tico recurring subscription (end-to-end):
+
+    # 1. Create a product with Pix Autom\xE1tico enabled
+    garu products create \\
+      --name "Plano Mensal" --value 4990 \\
+      --pix --credit-card --pix-automatic \\
+      --subscription --subscription-type monthly
+
+    # 2. Schedule the recurring auto-debit charge for that product.
+    #    pix_automatic requires --type=recurring and --product-id.
+    garu scheduled-charges create \\
+      --customer-id 42 --product-id 456 \\
+      --amount 49.90 --type recurring \\
+      --due-date 2026-06-15 \\
+      --methods pix_automatic \\
+      --recurrence-interval monthly
+`
+  );
   program.command("login").description("Save a Garu API key to the credentials file").option("--api-key <key>", "pre-supply the key instead of prompting").option("-p, --profile <name>", "profile name to store under", "default").action(async (cmdOpts) => {
     const base = toCommandOptions(program);
     await loginCommand({
@@ -954,9 +1074,9 @@ function buildCli() {
     "--customer-id <n>",
     "customer id",
     (v) => parsePositiveIntId(v, "--customer-id")
-  ).requiredOption("--amount <brl>", "decimal BRL amount, e.g. 297.50").requiredOption("--type <type>", "one_time | recurring").requiredOption("--due-date <yyyy-mm-dd>", "first due date in S\xE3o Paulo time").requiredOption("--methods <list>", "comma-separated: pix,boleto,card").option(
+  ).requiredOption("--amount <brl>", "decimal BRL amount, e.g. 297.50").requiredOption("--type <type>", "one_time | recurring").requiredOption("--due-date <yyyy-mm-dd>", "first due date in S\xE3o Paulo time").requiredOption("--methods <list>", "comma-separated: pix,boleto,card,pix_automatic").option(
     "--product-id <n>",
-    "product id (required when methods includes card)",
+    "product id (required when methods includes card or pix_automatic)",
     (v) => parsePositiveIntId(v, "--product-id")
   ).option("--description <text>", "charge description").option("--recurrence-interval <interval>", "recurring cadence: weekly|monthly|yearly|\u2026").option(
     "--recurrence-interval-count <n>",
@@ -1163,6 +1283,68 @@ function buildCli() {
       id: parsePositiveIntId(id, "Webhook event ID")
     }).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")
+  ).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",
+    (v) => parsePositiveIntId(v, "--installments")
+  ).option("--subscription", "mark the product as a subscription").option("--no-subscription", "mark the product as one-time").option("--subscription-type <type>", "subscription cadence, e.g. monthly").option("--unit-label <label>", "unit label shown on the checkout").option("--return-url <url>", "post-purchase redirect URL").option("--return-url-button-text <text>", "label for the return-URL button").action(async (cmdOpts) => {
+    const base = toCommandOptions(program);
+    await productsCreateCommand({
+      ...base,
+      name: cmdOpts.name,
+      value: cmdOpts.value,
+      description: cmdOpts.description,
+      image: cmdOpts.image,
+      tags: cmdOpts.tags,
+      pix: cmdOpts.pix,
+      boleto: cmdOpts.boleto,
+      creditCard: cmdOpts.creditCard,
+      pixAutomatic: cmdOpts.pixAutomatic,
+      installments: cmdOpts.installments,
+      isSubscription: cmdOpts.subscription,
+      subscriptionType: cmdOpts.subscriptionType,
+      unitLabel: cmdOpts.unitLabel,
+      returnUrl: cmdOpts.returnUrl,
+      returnUrlButtonText: cmdOpts.returnUrlButtonText
+    }).catch((err) => printErrorAndExit(err, base));
+  });
+  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")
+  ).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",
+    (v) => parsePositiveIntId(v, "--installments")
+  ).option("--subscription", "mark the product as a subscription").option("--no-subscription", "mark the product as one-time").option("--subscription-type <type>", "subscription cadence, e.g. monthly").option("--unit-label <label>", "unit label shown on the checkout").option("--return-url <url>", "post-purchase redirect URL").option("--return-url-button-text <text>", "label for the return-URL button").action(async (id, cmdOpts) => {
+    const base = toCommandOptions(program);
+    await productsUpdateCommand({
+      ...base,
+      id,
+      name: cmdOpts.name,
+      value: cmdOpts.value,
+      description: cmdOpts.description,
+      image: cmdOpts.image,
+      tags: cmdOpts.tags,
+      pix: cmdOpts.pix,
+      boleto: cmdOpts.boleto,
+      creditCard: cmdOpts.creditCard,
+      pixAutomatic: cmdOpts.pixAutomatic,
+      installments: cmdOpts.installments,
+      isSubscription: cmdOpts.subscription,
+      subscriptionType: cmdOpts.subscriptionType,
+      unitLabel: cmdOpts.unitLabel,
+      returnUrl: cmdOpts.returnUrl,
+      returnUrlButtonText: cmdOpts.returnUrlButtonText
+    }).catch((err) => printErrorAndExit(err, base));
+  });
   program.command("doctor").description("Environment diagnostic").action(async () => {
     const base = toCommandOptions(program);
     await doctorCommand(base).catch((err) => printErrorAndExit(err, base));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garuhq/cli",
-  "version": "0.6.0",
+  "version": "0.7.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.13.0",
+    "@garuhq/node": "0.15.0",
     "@inquirer/prompts": "8.4.1",
     "commander": "12.0.0",
     "picocolors": "1.0.0",