@garuhq/node 4.1.0 → 5.0.0

package/CHANGELOG.md

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

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
@@ -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.
@@ -286,23 +287,20 @@ var Charges = class {
    * 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.
+   * 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
    */
   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, {
-      "X-Idempotency-Key": idempotencyKey
-    });
+    return this.post(`/api/v1/charges/${encodeURIComponent(uuid)}/refund`, body, idempotencyHeaders(params.idempotencyKey));
   }
   /**
    * Cancel an unpaid charge.
@@ -343,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({
@@ -372,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)
     );
@@ -520,10 +523,9 @@ 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.
+   * 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, {
@@ -533,12 +535,11 @@ 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,
-        headers: { "X-Idempotency-Key": idempotencyKey },
+        headers: idempotencyHeaders(params.idempotencyKey),
         signal
       }).then((r) => r)
     );
@@ -646,9 +647,11 @@ 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.
+   * 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({
@@ -661,12 +664,11 @@ 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,
-        headers: { "X-Idempotency-Key": idempotencyKey },
+        headers: idempotencyHeaders(params.idempotencyKey),
         signal
       }).then((r) => r)
     );
@@ -911,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({
@@ -930,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)
     );
@@ -970,10 +972,15 @@ var ScheduledCharges = class {
   }
   http;
   /**
-   * 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.
+   * 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({
@@ -1000,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)
     );
@@ -1394,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.
@@ -1410,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

@@ -1100,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
@@ -1159,10 +1161,10 @@ declare class Charges {
      * 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.
+     * 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
@@ -1196,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({
@@ -1310,10 +1318,9 @@ 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.
+     * 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, {
@@ -1404,9 +1411,11 @@ 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.
+     * 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({
@@ -1576,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({
@@ -1629,10 +1639,15 @@ declare class ScheduledCharges {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * 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.
+     * 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({
@@ -1899,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

@@ -1100,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
@@ -1159,10 +1161,10 @@ declare class Charges {
      * 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.
+     * 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
@@ -1196,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({
@@ -1310,10 +1318,9 @@ 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.
+     * 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, {
@@ -1404,9 +1411,11 @@ 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.
+     * 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({
@@ -1576,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({
@@ -1629,10 +1639,15 @@ declare class ScheduledCharges {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * 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.
+     * 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({
@@ -1899,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
@@ -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.
@@ -280,23 +281,20 @@ var Charges = class {
    * 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.
+   * 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
    */
   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, {
-      "X-Idempotency-Key": idempotencyKey
-    });
+    return this.post(`/api/v1/charges/${encodeURIComponent(uuid)}/refund`, body, idempotencyHeaders(params.idempotencyKey));
   }
   /**
    * Cancel an unpaid charge.
@@ -337,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({
@@ -366,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)
     );
@@ -514,10 +517,9 @@ 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.
+   * 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, {
@@ -527,12 +529,11 @@ 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,
-        headers: { "X-Idempotency-Key": idempotencyKey },
+        headers: idempotencyHeaders(params.idempotencyKey),
         signal
       }).then((r) => r)
     );
@@ -640,9 +641,11 @@ 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.
+   * 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({
@@ -655,12 +658,11 @@ 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,
-        headers: { "X-Idempotency-Key": idempotencyKey },
+        headers: idempotencyHeaders(params.idempotencyKey),
         signal
       }).then((r) => r)
     );
@@ -905,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({
@@ -924,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)
     );
@@ -964,10 +966,15 @@ var ScheduledCharges = class {
   }
   http;
   /**
-   * 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.
+   * 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({
@@ -994,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)
     );
@@ -1388,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.
@@ -1404,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.1.0",
+  "version": "5.0.0",
   "description": "Official Node.js / TypeScript SDK for the Garu payment gateway.",
   "license": "MIT",
   "homepage": "https://garu.com.br",