@garuhq/node 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to `@garuhq/node` are documented in this file. Format:
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
 
+## [4.1.0] — 2026-08-22
+
+### Added
+
+- `customers.create()`, `charges.refund()`, and
+  `installmentPlans.requestRefund()` now attach an `X-Idempotency-Key`
+  header automatically (UUIDv4 unless you pass `idempotencyKey`). The
+  gateway now caches and replays the first response for 24h, so a network
+  retry can no longer register a duplicate customer, open a second refund
+  request, or (via `scheduledCharges.create()` — see Fixed below)
+  double-book recurring billing.
+
+### Fixed
+
+- `scheduledCharges.create()`'s docstring dropped the "the gateway does not
+  currently deduplicate" caveat — the backend now enforces it, so a retried
+  create is safe by default.
+
 ## [4.0.0] — 2026-08-22
 
 **Breaking:** `scheduledCharges` now targets the versioned public API

package/dist/index.cjs

@@ -217,7 +217,7 @@ var Charges = class {
    *     phone: '11987654321'
    *   }
    * });
-   * console.log(charge.uuid, charge.pix?.code);
+   * // charge.uuid, charge.pix?.code
    *
    * @example
    * // Credit card, 2 installments. Server-to-server only (PCI scope).
@@ -262,7 +262,7 @@ var Charges = class {
    *
    * @example
    * const { data, totalCount } = await garu.charges.list({ status: 'paid', limit: 50 });
-   * console.log(`${data.length} of ${totalCount} paid charges`);
+   * // data.length of totalCount paid charges
    */
   async list(params = {}) {
     const query = {};
@@ -285,15 +285,24 @@ var Charges = class {
    * charge in `refund_pending`, reaching `refunded` only once the transfer
    * settles.
    *
+   * For Pix/boleto (which open a refund request instead of an automated
+   * reversal), attaches an `X-Idempotency-Key` header automatically — if you
+   * don't pass `idempotencyKey`, the SDK generates a UUIDv4. Ignored for
+   * card, which reverses automatically and has no manual request to
+   * duplicate.
+   *
    * @example
    * await garu.charges.refund('6f1c9b2e-...');                       // full
    * await garu.charges.refund('6f1c9b2e-...', { amount: 10.0 });     // R$10,00
    */
   async refund(uuid, params = {}) {
+    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
     const body = {};
     if (params.amount !== void 0) body.amount = params.amount;
     if (params.reason !== void 0) body.reason = params.reason;
-    return this.post(`/api/v1/charges/${encodeURIComponent(uuid)}/refund`, body);
+    return this.post(`/api/v1/charges/${encodeURIComponent(uuid)}/refund`, body, {
+      "X-Idempotency-Key": idempotencyKey
+    });
   }
   /**
    * Cancel an unpaid charge.
@@ -318,7 +327,11 @@ var Charges = class {
   }
   post(url, body, headers) {
     return this.http.call(
-      (signal) => this.http.client.POST(url, { body, headers, signal })
+      (signal) => this.http.client.POST(url, {
+        body,
+        headers,
+        signal
+      })
     );
   }
 };
@@ -507,6 +520,11 @@ var InstallmentPlans = class {
    * team. Transfer the money to the buyer yourself, then close it with
    * `garu.refundRequests.confirm`.
    *
+   * Attaches an `X-Idempotency-Key` header automatically — if you don't pass
+   * `idempotencyKey`, the SDK generates a UUIDv4. The backend already dedupes
+   * a second pending request for the same carnê, so this is mainly
+   * defense-in-depth for the request-in-flight window.
+   *
    * @example
    * const request = await garu.installmentPlans.requestRefund(uuid, {
    *   reason: 'Produto não entregue'
@@ -515,9 +533,12 @@ var InstallmentPlans = class {
    * request.amount;  // defaults to everything the carnê collected
    */
   async requestRefund(uuid, params = {}) {
+    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
+    const { idempotencyKey: _omit, ...body } = params;
     return this.http.call(
       (signal) => this.http.client.POST(`/api/v1/installment-plans/${uuid}/refund-requests`, {
-        body: params,
+        body,
+        headers: { "X-Idempotency-Key": idempotencyKey },
         signal
       }).then((r) => r)
     );
@@ -625,6 +646,10 @@ var Customers = class {
   /**
    * Register a customer for the current seller.
    *
+   * Attaches an `X-Idempotency-Key` header automatically — if you don't pass
+   * `idempotencyKey`, the SDK generates a UUIDv4. Safe to retry: the same key
+   * returns the originally-created/matched customer for 24h.
+   *
    * @example
    * const customer = await garu.customers.create({
    *   name: 'Maria Silva',
@@ -636,9 +661,12 @@ var Customers = class {
    * customer.uuid;
    */
   async create(params) {
+    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
+    const { idempotencyKey: _omit, ...body } = params;
     return this.http.call(
       (signal) => this.http.client.POST("/api/v1/customers", {
-        body: params,
+        body,
+        headers: { "X-Idempotency-Key": idempotencyKey },
         signal
       }).then((r) => r)
     );
@@ -942,13 +970,10 @@ var ScheduledCharges = class {
   }
   http;
   /**
-   * Create a new scheduled charge. The SDK attaches an `X-Idempotency-Key`
-   * header (UUIDv4 unless you pass `idempotencyKey`), but the gateway does
-   * not currently deduplicate `/scheduled-charges` creates against it — a
-   * retry after a network failure can create more than one series. Pair
-   * this with your own retry-suppression (e.g. check `list` for an existing
-   * series with the same `externalReference`) if that matters for your
-   * integration.
+   * Create a new scheduled charge. Attaches an `X-Idempotency-Key` header
+   * automatically — if you don't pass `idempotencyKey`, the SDK generates a
+   * UUIDv4. Safe to retry: the same key returns the originally-created
+   * series for 24h instead of double-booking recurring billing.
    *
    * @example
    * const charge = await garu.scheduledCharges.create({

package/dist/index.d.cts

@@ -219,6 +219,13 @@ interface RefundChargeParams {
     amount?: number;
     /** Free-form reason stored on the refund. */
     reason?: string;
+    /**
+     * Optional idempotency key for safe retries. The SDK auto-generates a
+     * UUIDv4 when omitted and forwards it as `X-Idempotency-Key`. Only used
+     * for Pix/boleto, which open a refund request instead of an automated
+     * reversal — ignored for card, which has no manual request to duplicate.
+     */
+    idempotencyKey?: string;
 }
 interface ListChargesParams {
     /** Page number (1-based). Default: 1. */
@@ -324,6 +331,13 @@ interface CreateCustomerParams {
     city?: string;
     /** 2-letter uppercase state code, e.g. `SP`. */
     state?: string;
+    /**
+     * Optional idempotency key for safe retries. The SDK auto-generates a
+     * UUIDv4 when omitted and forwards it as `X-Idempotency-Key`. Document
+     * uniqueness already merges a retried create into the same customer, so
+     * this mainly protects registrations with no document set.
+     */
+    idempotencyKey?: string;
 }
 interface UpdateCustomerParams {
     name?: string;
@@ -1051,6 +1065,13 @@ interface RequestPlanRefundParams {
     /** Defaults to everything the carnê has collected. */
     amount?: number;
     reason?: string;
+    /**
+     * Optional idempotency key for safe retries. The SDK auto-generates a
+     * UUIDv4 when omitted and forwards it as `X-Idempotency-Key`. The backend
+     * already dedupes a second pending request for the same carnê, so this is
+     * mainly defense-in-depth for the request-in-flight window.
+     */
+    idempotencyKey?: string;
 }
 interface ListRefundRequestsParams {
     page?: number;
@@ -1095,7 +1116,7 @@ declare class Charges {
      *     phone: '11987654321'
      *   }
      * });
-     * console.log(charge.uuid, charge.pix?.code);
+     * // charge.uuid, charge.pix?.code
      *
      * @example
      * // Credit card, 2 installments. Server-to-server only (PCI scope).
@@ -1127,7 +1148,7 @@ declare class Charges {
      *
      * @example
      * const { data, totalCount } = await garu.charges.list({ status: 'paid', limit: 50 });
-     * console.log(`${data.length} of ${totalCount} paid charges`);
+     * // data.length of totalCount paid charges
      */
     list(params?: ListChargesParams): Promise<ChargeList>;
     /**
@@ -1137,6 +1158,12 @@ declare class Charges {
      * charge in `refund_pending`, reaching `refunded` only once the transfer
      * settles.
      *
+     * For Pix/boleto (which open a refund request instead of an automated
+     * reversal), attaches an `X-Idempotency-Key` header automatically — if you
+     * don't pass `idempotencyKey`, the SDK generates a UUIDv4. Ignored for
+     * card, which reverses automatically and has no manual request to
+     * duplicate.
+     *
      * @example
      * await garu.charges.refund('6f1c9b2e-...');                       // full
      * await garu.charges.refund('6f1c9b2e-...', { amount: 10.0 });     // R$10,00
@@ -1283,6 +1310,11 @@ declare class InstallmentPlans {
      * team. Transfer the money to the buyer yourself, then close it with
      * `garu.refundRequests.confirm`.
      *
+     * Attaches an `X-Idempotency-Key` header automatically — if you don't pass
+     * `idempotencyKey`, the SDK generates a UUIDv4. The backend already dedupes
+     * a second pending request for the same carnê, so this is mainly
+     * defense-in-depth for the request-in-flight window.
+     *
      * @example
      * const request = await garu.installmentPlans.requestRefund(uuid, {
      *   reason: 'Produto não entregue'
@@ -1372,6 +1404,10 @@ declare class Customers {
     /**
      * Register a customer for the current seller.
      *
+     * Attaches an `X-Idempotency-Key` header automatically — if you don't pass
+     * `idempotencyKey`, the SDK generates a UUIDv4. Safe to retry: the same key
+     * returns the originally-created/matched customer for 24h.
+     *
      * @example
      * const customer = await garu.customers.create({
      *   name: 'Maria Silva',
@@ -1593,13 +1629,10 @@ declare class ScheduledCharges {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Create a new scheduled charge. The SDK attaches an `X-Idempotency-Key`
-     * header (UUIDv4 unless you pass `idempotencyKey`), but the gateway does
-     * not currently deduplicate `/scheduled-charges` creates against it — a
-     * retry after a network failure can create more than one series. Pair
-     * this with your own retry-suppression (e.g. check `list` for an existing
-     * series with the same `externalReference`) if that matters for your
-     * integration.
+     * Create a new scheduled charge. Attaches an `X-Idempotency-Key` header
+     * automatically — if you don't pass `idempotencyKey`, the SDK generates a
+     * UUIDv4. Safe to retry: the same key returns the originally-created
+     * series for 24h instead of double-booking recurring billing.
      *
      * @example
      * const charge = await garu.scheduledCharges.create({

package/dist/index.d.ts

@@ -219,6 +219,13 @@ interface RefundChargeParams {
     amount?: number;
     /** Free-form reason stored on the refund. */
     reason?: string;
+    /**
+     * Optional idempotency key for safe retries. The SDK auto-generates a
+     * UUIDv4 when omitted and forwards it as `X-Idempotency-Key`. Only used
+     * for Pix/boleto, which open a refund request instead of an automated
+     * reversal — ignored for card, which has no manual request to duplicate.
+     */
+    idempotencyKey?: string;
 }
 interface ListChargesParams {
     /** Page number (1-based). Default: 1. */
@@ -324,6 +331,13 @@ interface CreateCustomerParams {
     city?: string;
     /** 2-letter uppercase state code, e.g. `SP`. */
     state?: string;
+    /**
+     * Optional idempotency key for safe retries. The SDK auto-generates a
+     * UUIDv4 when omitted and forwards it as `X-Idempotency-Key`. Document
+     * uniqueness already merges a retried create into the same customer, so
+     * this mainly protects registrations with no document set.
+     */
+    idempotencyKey?: string;
 }
 interface UpdateCustomerParams {
     name?: string;
@@ -1051,6 +1065,13 @@ interface RequestPlanRefundParams {
     /** Defaults to everything the carnê has collected. */
     amount?: number;
     reason?: string;
+    /**
+     * Optional idempotency key for safe retries. The SDK auto-generates a
+     * UUIDv4 when omitted and forwards it as `X-Idempotency-Key`. The backend
+     * already dedupes a second pending request for the same carnê, so this is
+     * mainly defense-in-depth for the request-in-flight window.
+     */
+    idempotencyKey?: string;
 }
 interface ListRefundRequestsParams {
     page?: number;
@@ -1095,7 +1116,7 @@ declare class Charges {
      *     phone: '11987654321'
      *   }
      * });
-     * console.log(charge.uuid, charge.pix?.code);
+     * // charge.uuid, charge.pix?.code
      *
      * @example
      * // Credit card, 2 installments. Server-to-server only (PCI scope).
@@ -1127,7 +1148,7 @@ declare class Charges {
      *
      * @example
      * const { data, totalCount } = await garu.charges.list({ status: 'paid', limit: 50 });
-     * console.log(`${data.length} of ${totalCount} paid charges`);
+     * // data.length of totalCount paid charges
      */
     list(params?: ListChargesParams): Promise<ChargeList>;
     /**
@@ -1137,6 +1158,12 @@ declare class Charges {
      * charge in `refund_pending`, reaching `refunded` only once the transfer
      * settles.
      *
+     * For Pix/boleto (which open a refund request instead of an automated
+     * reversal), attaches an `X-Idempotency-Key` header automatically — if you
+     * don't pass `idempotencyKey`, the SDK generates a UUIDv4. Ignored for
+     * card, which reverses automatically and has no manual request to
+     * duplicate.
+     *
      * @example
      * await garu.charges.refund('6f1c9b2e-...');                       // full
      * await garu.charges.refund('6f1c9b2e-...', { amount: 10.0 });     // R$10,00
@@ -1283,6 +1310,11 @@ declare class InstallmentPlans {
      * team. Transfer the money to the buyer yourself, then close it with
      * `garu.refundRequests.confirm`.
      *
+     * Attaches an `X-Idempotency-Key` header automatically — if you don't pass
+     * `idempotencyKey`, the SDK generates a UUIDv4. The backend already dedupes
+     * a second pending request for the same carnê, so this is mainly
+     * defense-in-depth for the request-in-flight window.
+     *
      * @example
      * const request = await garu.installmentPlans.requestRefund(uuid, {
      *   reason: 'Produto não entregue'
@@ -1372,6 +1404,10 @@ declare class Customers {
     /**
      * Register a customer for the current seller.
      *
+     * Attaches an `X-Idempotency-Key` header automatically — if you don't pass
+     * `idempotencyKey`, the SDK generates a UUIDv4. Safe to retry: the same key
+     * returns the originally-created/matched customer for 24h.
+     *
      * @example
      * const customer = await garu.customers.create({
      *   name: 'Maria Silva',
@@ -1593,13 +1629,10 @@ declare class ScheduledCharges {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Create a new scheduled charge. The SDK attaches an `X-Idempotency-Key`
-     * header (UUIDv4 unless you pass `idempotencyKey`), but the gateway does
-     * not currently deduplicate `/scheduled-charges` creates against it — a
-     * retry after a network failure can create more than one series. Pair
-     * this with your own retry-suppression (e.g. check `list` for an existing
-     * series with the same `externalReference`) if that matters for your
-     * integration.
+     * Create a new scheduled charge. Attaches an `X-Idempotency-Key` header
+     * automatically — if you don't pass `idempotencyKey`, the SDK generates a
+     * UUIDv4. Safe to retry: the same key returns the originally-created
+     * series for 24h instead of double-booking recurring billing.
      *
      * @example
      * const charge = await garu.scheduledCharges.create({

package/dist/index.js

@@ -211,7 +211,7 @@ var Charges = class {
    *     phone: '11987654321'
    *   }
    * });
-   * console.log(charge.uuid, charge.pix?.code);
+   * // charge.uuid, charge.pix?.code
    *
    * @example
    * // Credit card, 2 installments. Server-to-server only (PCI scope).
@@ -256,7 +256,7 @@ var Charges = class {
    *
    * @example
    * const { data, totalCount } = await garu.charges.list({ status: 'paid', limit: 50 });
-   * console.log(`${data.length} of ${totalCount} paid charges`);
+   * // data.length of totalCount paid charges
    */
   async list(params = {}) {
     const query = {};
@@ -279,15 +279,24 @@ var Charges = class {
    * charge in `refund_pending`, reaching `refunded` only once the transfer
    * settles.
    *
+   * For Pix/boleto (which open a refund request instead of an automated
+   * reversal), attaches an `X-Idempotency-Key` header automatically — if you
+   * don't pass `idempotencyKey`, the SDK generates a UUIDv4. Ignored for
+   * card, which reverses automatically and has no manual request to
+   * duplicate.
+   *
    * @example
    * await garu.charges.refund('6f1c9b2e-...');                       // full
    * await garu.charges.refund('6f1c9b2e-...', { amount: 10.0 });     // R$10,00
    */
   async refund(uuid, params = {}) {
+    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
     const body = {};
     if (params.amount !== void 0) body.amount = params.amount;
     if (params.reason !== void 0) body.reason = params.reason;
-    return this.post(`/api/v1/charges/${encodeURIComponent(uuid)}/refund`, body);
+    return this.post(`/api/v1/charges/${encodeURIComponent(uuid)}/refund`, body, {
+      "X-Idempotency-Key": idempotencyKey
+    });
   }
   /**
    * Cancel an unpaid charge.
@@ -312,7 +321,11 @@ var Charges = class {
   }
   post(url, body, headers) {
     return this.http.call(
-      (signal) => this.http.client.POST(url, { body, headers, signal })
+      (signal) => this.http.client.POST(url, {
+        body,
+        headers,
+        signal
+      })
     );
   }
 };
@@ -501,6 +514,11 @@ var InstallmentPlans = class {
    * team. Transfer the money to the buyer yourself, then close it with
    * `garu.refundRequests.confirm`.
    *
+   * Attaches an `X-Idempotency-Key` header automatically — if you don't pass
+   * `idempotencyKey`, the SDK generates a UUIDv4. The backend already dedupes
+   * a second pending request for the same carnê, so this is mainly
+   * defense-in-depth for the request-in-flight window.
+   *
    * @example
    * const request = await garu.installmentPlans.requestRefund(uuid, {
    *   reason: 'Produto não entregue'
@@ -509,9 +527,12 @@ var InstallmentPlans = class {
    * request.amount;  // defaults to everything the carnê collected
    */
   async requestRefund(uuid, params = {}) {
+    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
+    const { idempotencyKey: _omit, ...body } = params;
     return this.http.call(
       (signal) => this.http.client.POST(`/api/v1/installment-plans/${uuid}/refund-requests`, {
-        body: params,
+        body,
+        headers: { "X-Idempotency-Key": idempotencyKey },
         signal
       }).then((r) => r)
     );
@@ -619,6 +640,10 @@ var Customers = class {
   /**
    * Register a customer for the current seller.
    *
+   * Attaches an `X-Idempotency-Key` header automatically — if you don't pass
+   * `idempotencyKey`, the SDK generates a UUIDv4. Safe to retry: the same key
+   * returns the originally-created/matched customer for 24h.
+   *
    * @example
    * const customer = await garu.customers.create({
    *   name: 'Maria Silva',
@@ -630,9 +655,12 @@ var Customers = class {
    * customer.uuid;
    */
   async create(params) {
+    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
+    const { idempotencyKey: _omit, ...body } = params;
     return this.http.call(
       (signal) => this.http.client.POST("/api/v1/customers", {
-        body: params,
+        body,
+        headers: { "X-Idempotency-Key": idempotencyKey },
         signal
       }).then((r) => r)
     );
@@ -936,13 +964,10 @@ var ScheduledCharges = class {
   }
   http;
   /**
-   * Create a new scheduled charge. The SDK attaches an `X-Idempotency-Key`
-   * header (UUIDv4 unless you pass `idempotencyKey`), but the gateway does
-   * not currently deduplicate `/scheduled-charges` creates against it — a
-   * retry after a network failure can create more than one series. Pair
-   * this with your own retry-suppression (e.g. check `list` for an existing
-   * series with the same `externalReference`) if that matters for your
-   * integration.
+   * Create a new scheduled charge. Attaches an `X-Idempotency-Key` header
+   * automatically — if you don't pass `idempotencyKey`, the SDK generates a
+   * UUIDv4. Safe to retry: the same key returns the originally-created
+   * series for 24h instead of double-booking recurring billing.
    *
    * @example
    * const charge = await garu.scheduledCharges.create({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garuhq/node",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Official Node.js / TypeScript SDK for the Garu payment gateway.",
   "license": "MIT",
   "homepage": "https://garu.com.br",