@garuhq/node 4.0.0 → 5.0.0

package/CHANGELOG.md

@@ -3,6 +3,73 @@
 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/).
 
+## [5.0.0] — 2026-09-09
+
+**Breaking:** requests that omit `idempotencyKey` no longer carry an
+`X-Idempotency-Key` header. No API contract changed and no gateway endpoint
+requires the header, so most integrations need no code change — but if you were
+relying on a key always being present, you must now pass one, which is the only
+way it ever gave you real protection. See below.
+
+### Fixed
+
+- **The SDK no longer invents an idempotency key.** Every write that takes
+  `idempotencyKey` (`charges.create`, `charges.refund`, `customers.create`,
+  `products.create`, `scheduledCharges.create`, `installmentPlans.create`,
+  `installmentPlans.requestRefund`, `webhookEvents.resend`) used to generate a
+  fresh UUIDv4 when you omitted one. That protected nothing: an idempotency key
+  only works if the SAME key comes back on a retry, and a key invented per call
+  is different every time. The header is now sent only when you pass a key.
+
+  This was not theoretical. On 2026-09-08 an integrator's HTTP client timed out
+  at 30s on a card charge that was still being created, retried, drew a fresh
+  UUIDv4, and charged a real buyer twice.
+
+  Docstrings that promised "Safe to retry: the same key returns the original
+  charge for 24h" were describing a guarantee the code did not provide. They now
+  say what actually happens.
+
+### Changed
+
+- Behaviour change, no API change: requests where you omit `idempotencyKey` now
+  carry no `X-Idempotency-Key` header. Nothing rejects a missing key — the header
+  is optional on every gateway endpoint — and the gateway also gained a duplicate
+  guard that replays the original charge when the same buyer, product, rail and
+  instalment count arrive again within 60 seconds.
+
+  **To get real protection, pass a key derived from your own domain** so a retry
+  reproduces it:
+
+  ```ts
+  await garu.charges.create({
+    productId,
+    paymentMethod: 'creditCard',
+    customer,
+    idempotencyKey: `booking:${booking.id}:charge`
+  });
+  ```
+
+- `generateIdempotencyKey()` is still exported and unchanged. It is only useful
+  if you store the result and reuse it across retries of the same operation.
+
+## [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

@@ -188,8 +188,8 @@ function backoffDelay(attempt, retryAfterSec) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function generateIdempotencyKey() {
-  return crypto.randomUUID();
+function idempotencyHeaders(key) {
+  return key ? { "X-Idempotency-Key": key } : {};
 }
 
 // src/resources/charges.ts
@@ -201,9 +201,11 @@ var Charges = class {
   /**
    * Create a charge (PIX, boleto, or credit card).
    *
-   * 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 original charge for 24h.
+   * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+   * original charge for 24h. Derive it from something stable in your own
+   * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+   * no key is sent — the SDK does NOT invent one, because a key generated per
+   * call is different every time and protects nothing.
    *
    * @example
    * // PIX — render charge.pix.code as a QR in your own checkout
@@ -217,7 +219,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).
@@ -236,7 +238,6 @@ var Charges = class {
    * // charge.amount is the base price; charge.chargedTotal is what was charged.
    */
   async create(params) {
-    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
     const body = {
       productId: params.productId,
       paymentMethod: params.paymentMethod,
@@ -245,7 +246,7 @@ var Charges = class {
     if (params.card) body.card = params.card;
     if (params.checkoutSessionToken) body.checkoutSessionToken = params.checkoutSessionToken;
     if (params.additionalInfo !== void 0) body.additionalInfo = params.additionalInfo;
-    return this.post("/api/v1/charges", body, { "X-Idempotency-Key": idempotencyKey });
+    return this.post("/api/v1/charges", body, idempotencyHeaders(params.idempotencyKey));
   }
   /**
    * Retrieve a charge by uuid.
@@ -262,7 +263,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,6 +286,12 @@ 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), pass `idempotencyKey` to make a retry return the original
+   * request rather than opening a second one; omit it and no key is sent.
+   * 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
@@ -293,7 +300,7 @@ var Charges = class {
     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, idempotencyHeaders(params.idempotencyKey));
   }
   /**
    * Cancel an unpaid charge.
@@ -318,7 +325,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
+      })
     );
   }
 };
@@ -330,10 +341,16 @@ var InstallmentPlans = class {
   }
   http;
   /**
-   * Sell a product as a carnê. Auto-attaches `X-Idempotency-Key` (UUIDv4 if
-   * you don't pass `idempotencyKey`), which matters more here than anywhere
-   * else in the API: this call registers a REAL boleto at the bank, so a
-   * blind retry can put two payable barcodes in one buyer's hands.
+   * Sell a product as a carnê.
+   *
+   * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+   * original plan for 24h. Derive it from something stable in your own
+   * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+   * no key is sent — the SDK does NOT invent one, because a key generated per
+   * call is different every time and protects nothing.
+   * This matters more here than anywhere else in the API: the call registers a
+   * REAL boleto at the bank, so a retry without a key can put two payable
+   * barcodes in one buyer's hands.
    *
    * @example
    * const carne = await garu.installmentPlans.create({
@@ -359,12 +376,11 @@ var InstallmentPlans = class {
    * });
    */
   async create(params) {
-    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
     const { idempotencyKey: _omit, ...body } = params;
     return this.http.call(
       (signal) => this.http.client.POST("/api/v1/installment-plans", {
         body,
-        headers: { "X-Idempotency-Key": idempotencyKey },
+        headers: idempotencyHeaders(params.idempotencyKey),
         signal
       }).then((r) => r)
     );
@@ -507,6 +523,10 @@ var InstallmentPlans = class {
    * team. Transfer the money to the buyer yourself, then close it with
    * `garu.refundRequests.confirm`.
    *
+   * Pass `idempotencyKey` to cover the request-in-flight window; omit it and no
+   * key is sent. The backend already dedupes a second pending request for the
+   * same carnê, so this is defense-in-depth rather than the main guard.
+   *
    * @example
    * const request = await garu.installmentPlans.requestRefund(uuid, {
    *   reason: 'Produto não entregue'
@@ -515,9 +535,11 @@ var InstallmentPlans = class {
    * request.amount;  // defaults to everything the carnê collected
    */
   async requestRefund(uuid, params = {}) {
+    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: idempotencyHeaders(params.idempotencyKey),
         signal
       }).then((r) => r)
     );
@@ -625,6 +647,12 @@ var Customers = class {
   /**
    * Register a customer for the current seller.
    *
+   * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+   * original customer for 24h. Derive it from something stable in your own
+   * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+   * no key is sent — the SDK does NOT invent one, because a key generated per
+   * call is different every time and protects nothing.
+   *
    * @example
    * const customer = await garu.customers.create({
    *   name: 'Maria Silva',
@@ -636,9 +664,11 @@ var Customers = class {
    * customer.uuid;
    */
   async create(params) {
+    const { idempotencyKey: _omit, ...body } = params;
     return this.http.call(
       (signal) => this.http.client.POST("/api/v1/customers", {
-        body: params,
+        body,
+        headers: idempotencyHeaders(params.idempotencyKey),
         signal
       }).then((r) => r)
     );
@@ -883,10 +913,11 @@ var Products = class {
    * product (HTTP 201). Only `name` is required; everything else falls back
    * to seller/server defaults.
    *
-   * Automatically attaches an `X-Idempotency-Key` header — if you don't pass
-   * `idempotencyKey`, the SDK generates a UUIDv4. This makes the built-in
-   * retry on transient failures safe: a retried POST returns the original
-   * product instead of creating a duplicate.
+   * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+   * original product for 24h. Derive it from something stable in your own
+   * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+   * no key is sent — the SDK does NOT invent one, because a key generated per
+   * call is different every time and protects nothing.
    *
    * @example
    * const product = await garu.products.create({
@@ -902,11 +933,10 @@ var Products = class {
    */
   async create(params) {
     const { idempotencyKey, ...body } = params;
-    const key = idempotencyKey ?? generateIdempotencyKey();
     return this.http.call(
       (signal) => this.http.client.POST("/api/v1/products", {
         body,
-        headers: { "X-Idempotency-Key": key },
+        headers: idempotencyHeaders(idempotencyKey),
         signal
       }).then((r) => r)
     );
@@ -942,13 +972,15 @@ 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.
+   *
+   * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+   * original series for 24h. Derive it from something stable in your own
+   * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+   * no key is sent — the SDK does NOT invent one, because a key generated per
+   * call is different every time and protects nothing.
+   * Worth the effort here: without a key, a retry double-books recurring
+   * billing for the same customer.
    *
    * @example
    * const charge = await garu.scheduledCharges.create({
@@ -975,12 +1007,11 @@ var ScheduledCharges = class {
    * });
    */
   async create(params) {
-    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
     const { idempotencyKey: _omit, ...body } = params;
     return this.http.call(
       (signal) => this.http.client.POST("/api/v1/scheduled-charges", {
         body,
-        headers: { "X-Idempotency-Key": idempotencyKey },
+        headers: idempotencyHeaders(params.idempotencyKey),
         signal
       }).then((r) => r)
     );
@@ -1369,11 +1400,10 @@ var WebhookEvents = class {
    * original — distinguishable both by the `resend_` prefix and by reading
    * the response payload's `manualResendOf` field.
    *
-   * The SDK also attaches an `X-Idempotency-Key` header (UUIDv4 unless you
-   * pass `idempotencyKey`); the gateway does not currently deduplicate
-   * `/resend` calls against it, so retrying this call from your own code
-   * after a network failure can create more than one clone — pair it with
-   * your own retry-suppression if that matters for your integration.
+   * `idempotencyKey` is forwarded when you pass one and omitted when you don't.
+   * Either way the gateway does not currently deduplicate `/resend` calls
+   * against it, so retrying after a network failure can create more than one
+   * clone — pair it with your own retry-suppression if that matters.
    *
    * Returns the *clone* event (new uuid), not the original. The original is
    * unchanged on the server.
@@ -1385,11 +1415,10 @@ var WebhookEvents = class {
    * clone.manualResendOf === event.uuid; // true — points back at the source
    */
   async resend(uuid, params = {}) {
-    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
     return this.http.call(
       (signal) => this.http.client.POST(`/api/v1/webhook-events/${uuid}/resend`, {
         body: {},
-        headers: { "X-Idempotency-Key": idempotencyKey },
+        headers: idempotencyHeaders(params.idempotencyKey),
         signal
       }).then((r) => r)
     );

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;
@@ -1079,9 +1100,11 @@ declare class Charges {
     /**
      * Create a charge (PIX, boleto, or credit card).
      *
-     * 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 original charge for 24h.
+     * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+     * original charge for 24h. Derive it from something stable in your own
+     * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+     * no key is sent — the SDK does NOT invent one, because a key generated per
+     * call is different every time and protects nothing.
      *
      * @example
      * // PIX — render charge.pix.code as a QR in your own checkout
@@ -1095,7 +1118,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 +1150,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 +1160,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), pass `idempotencyKey` to make a retry return the original
+     * request rather than opening a second one; omit it and no key is sent.
+     * 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
@@ -1169,10 +1198,16 @@ declare class InstallmentPlans {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Sell a product as a carnê. Auto-attaches `X-Idempotency-Key` (UUIDv4 if
-     * you don't pass `idempotencyKey`), which matters more here than anywhere
-     * else in the API: this call registers a REAL boleto at the bank, so a
-     * blind retry can put two payable barcodes in one buyer's hands.
+     * Sell a product as a carnê.
+     *
+     * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+     * original plan for 24h. Derive it from something stable in your own
+     * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+     * no key is sent — the SDK does NOT invent one, because a key generated per
+     * call is different every time and protects nothing.
+     * This matters more here than anywhere else in the API: the call registers a
+     * REAL boleto at the bank, so a retry without a key can put two payable
+     * barcodes in one buyer's hands.
      *
      * @example
      * const carne = await garu.installmentPlans.create({
@@ -1283,6 +1318,10 @@ declare class InstallmentPlans {
      * team. Transfer the money to the buyer yourself, then close it with
      * `garu.refundRequests.confirm`.
      *
+     * Pass `idempotencyKey` to cover the request-in-flight window; omit it and no
+     * key is sent. The backend already dedupes a second pending request for the
+     * same carnê, so this is defense-in-depth rather than the main guard.
+     *
      * @example
      * const request = await garu.installmentPlans.requestRefund(uuid, {
      *   reason: 'Produto não entregue'
@@ -1372,6 +1411,12 @@ declare class Customers {
     /**
      * Register a customer for the current seller.
      *
+     * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+     * original customer for 24h. Derive it from something stable in your own
+     * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+     * no key is sent — the SDK does NOT invent one, because a key generated per
+     * call is different every time and protects nothing.
+     *
      * @example
      * const customer = await garu.customers.create({
      *   name: 'Maria Silva',
@@ -1540,10 +1585,11 @@ declare class Products {
      * product (HTTP 201). Only `name` is required; everything else falls back
      * to seller/server defaults.
      *
-     * Automatically attaches an `X-Idempotency-Key` header — if you don't pass
-     * `idempotencyKey`, the SDK generates a UUIDv4. This makes the built-in
-     * retry on transient failures safe: a retried POST returns the original
-     * product instead of creating a duplicate.
+     * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+     * original product for 24h. Derive it from something stable in your own
+     * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+     * no key is sent — the SDK does NOT invent one, because a key generated per
+     * call is different every time and protects nothing.
      *
      * @example
      * const product = await garu.products.create({
@@ -1593,13 +1639,15 @@ 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.
+     *
+     * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+     * original series for 24h. Derive it from something stable in your own
+     * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+     * no key is sent — the SDK does NOT invent one, because a key generated per
+     * call is different every time and protects nothing.
+     * Worth the effort here: without a key, a retry double-books recurring
+     * billing for the same customer.
      *
      * @example
      * const charge = await garu.scheduledCharges.create({
@@ -1866,11 +1914,10 @@ declare class WebhookEvents {
      * original — distinguishable both by the `resend_` prefix and by reading
      * the response payload's `manualResendOf` field.
      *
-     * The SDK also attaches an `X-Idempotency-Key` header (UUIDv4 unless you
-     * pass `idempotencyKey`); the gateway does not currently deduplicate
-     * `/resend` calls against it, so retrying this call from your own code
-     * after a network failure can create more than one clone — pair it with
-     * your own retry-suppression if that matters for your integration.
+     * `idempotencyKey` is forwarded when you pass one and omitted when you don't.
+     * Either way the gateway does not currently deduplicate `/resend` calls
+     * against it, so retrying after a network failure can create more than one
+     * clone — pair it with your own retry-suppression if that matters.
      *
      * Returns the *clone* event (new uuid), not the original. The original is
      * unchanged on the server.

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;
@@ -1079,9 +1100,11 @@ declare class Charges {
     /**
      * Create a charge (PIX, boleto, or credit card).
      *
-     * 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 original charge for 24h.
+     * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+     * original charge for 24h. Derive it from something stable in your own
+     * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+     * no key is sent — the SDK does NOT invent one, because a key generated per
+     * call is different every time and protects nothing.
      *
      * @example
      * // PIX — render charge.pix.code as a QR in your own checkout
@@ -1095,7 +1118,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 +1150,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 +1160,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), pass `idempotencyKey` to make a retry return the original
+     * request rather than opening a second one; omit it and no key is sent.
+     * 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
@@ -1169,10 +1198,16 @@ declare class InstallmentPlans {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Sell a product as a carnê. Auto-attaches `X-Idempotency-Key` (UUIDv4 if
-     * you don't pass `idempotencyKey`), which matters more here than anywhere
-     * else in the API: this call registers a REAL boleto at the bank, so a
-     * blind retry can put two payable barcodes in one buyer's hands.
+     * Sell a product as a carnê.
+     *
+     * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+     * original plan for 24h. Derive it from something stable in your own
+     * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+     * no key is sent — the SDK does NOT invent one, because a key generated per
+     * call is different every time and protects nothing.
+     * This matters more here than anywhere else in the API: the call registers a
+     * REAL boleto at the bank, so a retry without a key can put two payable
+     * barcodes in one buyer's hands.
      *
      * @example
      * const carne = await garu.installmentPlans.create({
@@ -1283,6 +1318,10 @@ declare class InstallmentPlans {
      * team. Transfer the money to the buyer yourself, then close it with
      * `garu.refundRequests.confirm`.
      *
+     * Pass `idempotencyKey` to cover the request-in-flight window; omit it and no
+     * key is sent. The backend already dedupes a second pending request for the
+     * same carnê, so this is defense-in-depth rather than the main guard.
+     *
      * @example
      * const request = await garu.installmentPlans.requestRefund(uuid, {
      *   reason: 'Produto não entregue'
@@ -1372,6 +1411,12 @@ declare class Customers {
     /**
      * Register a customer for the current seller.
      *
+     * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+     * original customer for 24h. Derive it from something stable in your own
+     * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+     * no key is sent — the SDK does NOT invent one, because a key generated per
+     * call is different every time and protects nothing.
+     *
      * @example
      * const customer = await garu.customers.create({
      *   name: 'Maria Silva',
@@ -1540,10 +1585,11 @@ declare class Products {
      * product (HTTP 201). Only `name` is required; everything else falls back
      * to seller/server defaults.
      *
-     * Automatically attaches an `X-Idempotency-Key` header — if you don't pass
-     * `idempotencyKey`, the SDK generates a UUIDv4. This makes the built-in
-     * retry on transient failures safe: a retried POST returns the original
-     * product instead of creating a duplicate.
+     * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+     * original product for 24h. Derive it from something stable in your own
+     * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+     * no key is sent — the SDK does NOT invent one, because a key generated per
+     * call is different every time and protects nothing.
      *
      * @example
      * const product = await garu.products.create({
@@ -1593,13 +1639,15 @@ 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.
+     *
+     * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+     * original series for 24h. Derive it from something stable in your own
+     * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+     * no key is sent — the SDK does NOT invent one, because a key generated per
+     * call is different every time and protects nothing.
+     * Worth the effort here: without a key, a retry double-books recurring
+     * billing for the same customer.
      *
      * @example
      * const charge = await garu.scheduledCharges.create({
@@ -1866,11 +1914,10 @@ declare class WebhookEvents {
      * original — distinguishable both by the `resend_` prefix and by reading
      * the response payload's `manualResendOf` field.
      *
-     * The SDK also attaches an `X-Idempotency-Key` header (UUIDv4 unless you
-     * pass `idempotencyKey`); the gateway does not currently deduplicate
-     * `/resend` calls against it, so retrying this call from your own code
-     * after a network failure can create more than one clone — pair it with
-     * your own retry-suppression if that matters for your integration.
+     * `idempotencyKey` is forwarded when you pass one and omitted when you don't.
+     * Either way the gateway does not currently deduplicate `/resend` calls
+     * against it, so retrying after a network failure can create more than one
+     * clone — pair it with your own retry-suppression if that matters.
      *
      * Returns the *clone* event (new uuid), not the original. The original is
      * unchanged on the server.

package/dist/index.js

@@ -1,5 +1,5 @@
 import createClient from 'openapi-fetch';
-import { createHmac, timingSafeEqual, randomUUID } from 'crypto';
+import { createHmac, timingSafeEqual } from 'crypto';
 
 // src/http.ts
 
@@ -182,8 +182,8 @@ function backoffDelay(attempt, retryAfterSec) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function generateIdempotencyKey() {
-  return randomUUID();
+function idempotencyHeaders(key) {
+  return key ? { "X-Idempotency-Key": key } : {};
 }
 
 // src/resources/charges.ts
@@ -195,9 +195,11 @@ var Charges = class {
   /**
    * Create a charge (PIX, boleto, or credit card).
    *
-   * 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 original charge for 24h.
+   * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+   * original charge for 24h. Derive it from something stable in your own
+   * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+   * no key is sent — the SDK does NOT invent one, because a key generated per
+   * call is different every time and protects nothing.
    *
    * @example
    * // PIX — render charge.pix.code as a QR in your own checkout
@@ -211,7 +213,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).
@@ -230,7 +232,6 @@ var Charges = class {
    * // charge.amount is the base price; charge.chargedTotal is what was charged.
    */
   async create(params) {
-    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
     const body = {
       productId: params.productId,
       paymentMethod: params.paymentMethod,
@@ -239,7 +240,7 @@ var Charges = class {
     if (params.card) body.card = params.card;
     if (params.checkoutSessionToken) body.checkoutSessionToken = params.checkoutSessionToken;
     if (params.additionalInfo !== void 0) body.additionalInfo = params.additionalInfo;
-    return this.post("/api/v1/charges", body, { "X-Idempotency-Key": idempotencyKey });
+    return this.post("/api/v1/charges", body, idempotencyHeaders(params.idempotencyKey));
   }
   /**
    * Retrieve a charge by uuid.
@@ -256,7 +257,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,6 +280,12 @@ 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), pass `idempotencyKey` to make a retry return the original
+   * request rather than opening a second one; omit it and no key is sent.
+   * 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
@@ -287,7 +294,7 @@ var Charges = class {
     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, idempotencyHeaders(params.idempotencyKey));
   }
   /**
    * Cancel an unpaid charge.
@@ -312,7 +319,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
+      })
     );
   }
 };
@@ -324,10 +335,16 @@ var InstallmentPlans = class {
   }
   http;
   /**
-   * Sell a product as a carnê. Auto-attaches `X-Idempotency-Key` (UUIDv4 if
-   * you don't pass `idempotencyKey`), which matters more here than anywhere
-   * else in the API: this call registers a REAL boleto at the bank, so a
-   * blind retry can put two payable barcodes in one buyer's hands.
+   * Sell a product as a carnê.
+   *
+   * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+   * original plan for 24h. Derive it from something stable in your own
+   * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+   * no key is sent — the SDK does NOT invent one, because a key generated per
+   * call is different every time and protects nothing.
+   * This matters more here than anywhere else in the API: the call registers a
+   * REAL boleto at the bank, so a retry without a key can put two payable
+   * barcodes in one buyer's hands.
    *
    * @example
    * const carne = await garu.installmentPlans.create({
@@ -353,12 +370,11 @@ var InstallmentPlans = class {
    * });
    */
   async create(params) {
-    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
     const { idempotencyKey: _omit, ...body } = params;
     return this.http.call(
       (signal) => this.http.client.POST("/api/v1/installment-plans", {
         body,
-        headers: { "X-Idempotency-Key": idempotencyKey },
+        headers: idempotencyHeaders(params.idempotencyKey),
         signal
       }).then((r) => r)
     );
@@ -501,6 +517,10 @@ var InstallmentPlans = class {
    * team. Transfer the money to the buyer yourself, then close it with
    * `garu.refundRequests.confirm`.
    *
+   * Pass `idempotencyKey` to cover the request-in-flight window; omit it and no
+   * key is sent. The backend already dedupes a second pending request for the
+   * same carnê, so this is defense-in-depth rather than the main guard.
+   *
    * @example
    * const request = await garu.installmentPlans.requestRefund(uuid, {
    *   reason: 'Produto não entregue'
@@ -509,9 +529,11 @@ var InstallmentPlans = class {
    * request.amount;  // defaults to everything the carnê collected
    */
   async requestRefund(uuid, params = {}) {
+    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: idempotencyHeaders(params.idempotencyKey),
         signal
       }).then((r) => r)
     );
@@ -619,6 +641,12 @@ var Customers = class {
   /**
    * Register a customer for the current seller.
    *
+   * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+   * original customer for 24h. Derive it from something stable in your own
+   * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+   * no key is sent — the SDK does NOT invent one, because a key generated per
+   * call is different every time and protects nothing.
+   *
    * @example
    * const customer = await garu.customers.create({
    *   name: 'Maria Silva',
@@ -630,9 +658,11 @@ var Customers = class {
    * customer.uuid;
    */
   async create(params) {
+    const { idempotencyKey: _omit, ...body } = params;
     return this.http.call(
       (signal) => this.http.client.POST("/api/v1/customers", {
-        body: params,
+        body,
+        headers: idempotencyHeaders(params.idempotencyKey),
         signal
       }).then((r) => r)
     );
@@ -877,10 +907,11 @@ var Products = class {
    * product (HTTP 201). Only `name` is required; everything else falls back
    * to seller/server defaults.
    *
-   * Automatically attaches an `X-Idempotency-Key` header — if you don't pass
-   * `idempotencyKey`, the SDK generates a UUIDv4. This makes the built-in
-   * retry on transient failures safe: a retried POST returns the original
-   * product instead of creating a duplicate.
+   * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+   * original product for 24h. Derive it from something stable in your own
+   * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+   * no key is sent — the SDK does NOT invent one, because a key generated per
+   * call is different every time and protects nothing.
    *
    * @example
    * const product = await garu.products.create({
@@ -896,11 +927,10 @@ var Products = class {
    */
   async create(params) {
     const { idempotencyKey, ...body } = params;
-    const key = idempotencyKey ?? generateIdempotencyKey();
     return this.http.call(
       (signal) => this.http.client.POST("/api/v1/products", {
         body,
-        headers: { "X-Idempotency-Key": key },
+        headers: idempotencyHeaders(idempotencyKey),
         signal
       }).then((r) => r)
     );
@@ -936,13 +966,15 @@ 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.
+   *
+   * Pass `idempotencyKey` to make this safe to retry: the same key returns the
+   * original series for 24h. Derive it from something stable in your own
+   * domain (an order id, a booking id) so a retry reproduces it. Omit it and
+   * no key is sent — the SDK does NOT invent one, because a key generated per
+   * call is different every time and protects nothing.
+   * Worth the effort here: without a key, a retry double-books recurring
+   * billing for the same customer.
    *
    * @example
    * const charge = await garu.scheduledCharges.create({
@@ -969,12 +1001,11 @@ var ScheduledCharges = class {
    * });
    */
   async create(params) {
-    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
     const { idempotencyKey: _omit, ...body } = params;
     return this.http.call(
       (signal) => this.http.client.POST("/api/v1/scheduled-charges", {
         body,
-        headers: { "X-Idempotency-Key": idempotencyKey },
+        headers: idempotencyHeaders(params.idempotencyKey),
         signal
       }).then((r) => r)
     );
@@ -1363,11 +1394,10 @@ var WebhookEvents = class {
    * original — distinguishable both by the `resend_` prefix and by reading
    * the response payload's `manualResendOf` field.
    *
-   * The SDK also attaches an `X-Idempotency-Key` header (UUIDv4 unless you
-   * pass `idempotencyKey`); the gateway does not currently deduplicate
-   * `/resend` calls against it, so retrying this call from your own code
-   * after a network failure can create more than one clone — pair it with
-   * your own retry-suppression if that matters for your integration.
+   * `idempotencyKey` is forwarded when you pass one and omitted when you don't.
+   * Either way the gateway does not currently deduplicate `/resend` calls
+   * against it, so retrying after a network failure can create more than one
+   * clone — pair it with your own retry-suppression if that matters.
    *
    * Returns the *clone* event (new uuid), not the original. The original is
    * unchanged on the server.
@@ -1379,11 +1409,10 @@ var WebhookEvents = class {
    * clone.manualResendOf === event.uuid; // true — points back at the source
    */
   async resend(uuid, params = {}) {
-    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
     return this.http.call(
       (signal) => this.http.client.POST(`/api/v1/webhook-events/${uuid}/resend`, {
         body: {},
-        headers: { "X-Idempotency-Key": idempotencyKey },
+        headers: idempotencyHeaders(params.idempotencyKey),
         signal
       }).then((r) => r)
     );

package/package.json

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