@garuhq/node 4.1.0 → 5.1.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

@@ -76,6 +76,15 @@ var GaruRateLimitError = class extends GaruAPIError {
     this.retryAfterSec = retryAfterSec;
   }
 };
+var GaruDuplicateChargeError = class extends GaruAPIError {
+  /** How long to wait before sending the same request again. */
+  retryAfterSec;
+  constructor(code, message, status, requestId, body, retryAfterSec) {
+    super(code, message, status, requestId, body);
+    this.name = "GaruDuplicateChargeError";
+    this.retryAfterSec = retryAfterSec;
+  }
+};
 var GaruServerError = class extends GaruAPIError {
   constructor(message, status, requestId, body) {
     super("server_error", message, status, requestId, body);
@@ -93,6 +102,13 @@ function mapApiError(status, body, requestId, retryAfterSec) {
   if (status === 429) {
     return new GaruRateLimitError(message, status, requestId, body, retryAfterSec);
   }
+  if (status === 409) {
+    const code = readDuplicateChargeCode(body);
+    if (code) {
+      const wait = retryAfterSec ?? readRetryAfterFromBody(body) ?? DEFAULT_DUPLICATE_RETRY_SEC;
+      return new GaruDuplicateChargeError(code, message, status, requestId, body, wait);
+    }
+  }
   if (status >= 500) return new GaruServerError(message, status, requestId, body);
   return new GaruAPIError("api_error", message, status, requestId, body);
 }
@@ -105,6 +121,15 @@ function extractMessage(body) {
   }
   return null;
 }
+var DEFAULT_DUPLICATE_RETRY_SEC = 5;
+function readDuplicateChargeCode(body) {
+  const code = body?.error;
+  return code === "charge_in_progress" || code === "charge_already_processed" ? code : null;
+}
+function readRetryAfterFromBody(body) {
+  const value = body?.retryAfter;
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
+}
 
 // src/http.ts
 var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
@@ -188,8 +213,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 +226,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
@@ -234,9 +261,22 @@ var Charges = class {
    *   }
    * });
    * // charge.amount is the base price; charge.chargedTotal is what was charged.
+   *
+   * @example
+   * // Handling a duplicate. A 409 means an identical charge is already being
+   * // processed, or already went through — NOT that this one failed. Send the
+   * // same request again after the wait and you get the ORIGINAL charge back.
+   * // The SDK will not retry it for you.
+   * try {
+   *   await garu.charges.create({ productId, paymentMethod: 'creditCard', customer, card });
+   * } catch (err) {
+   *   if (err instanceof GaruDuplicateChargeError) {
+   *     await new Promise((r) => setTimeout(r, err.retryAfterSec * 1000));
+   *     // retry the same call
+   *   }
+   * }
    */
   async create(params) {
-    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
     const body = {
       productId: params.productId,
       paymentMethod: params.paymentMethod,
@@ -245,7 +285,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 +326,24 @@ 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 +384,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 +419,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 +566,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 +578,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 +690,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 +707,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 +956,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 +976,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 +1015,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 +1050,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 +1443,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 +1458,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)
     );
@@ -1521,6 +1568,7 @@ exports.Garu = Garu;
 exports.GaruAPIError = GaruAPIError;
 exports.GaruAuthenticationError = GaruAuthenticationError;
 exports.GaruConnectionError = GaruConnectionError;
+exports.GaruDuplicateChargeError = GaruDuplicateChargeError;
 exports.GaruError = GaruError;
 exports.GaruNotFoundError = GaruNotFoundError;
 exports.GaruPermissionError = GaruPermissionError;

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
@@ -1133,6 +1135,20 @@ declare class Charges {
      *   }
      * });
      * // charge.amount is the base price; charge.chargedTotal is what was charged.
+     *
+     * @example
+     * // Handling a duplicate. A 409 means an identical charge is already being
+     * // processed, or already went through — NOT that this one failed. Send the
+     * // same request again after the wait and you get the ORIGINAL charge back.
+     * // The SDK will not retry it for you.
+     * try {
+     *   await garu.charges.create({ productId, paymentMethod: 'creditCard', customer, card });
+     * } catch (err) {
+     *   if (err instanceof GaruDuplicateChargeError) {
+     *     await new Promise((r) => setTimeout(r, err.retryAfterSec * 1000));
+     *     // retry the same call
+     *   }
+     * }
      */
     create(params: CreateChargeParams): Promise<Charge>;
     /**
@@ -1159,10 +1175,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 +1212,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 +1332,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 +1425,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 +1599,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 +1653,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 +1928,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.
@@ -1982,7 +2010,7 @@ declare class Garu {
  * without parsing messages. Non-2xx API responses are mapped to the most specific
  * subclass of `GaruAPIError` by {@link mapApiError}.
  */
-type GaruErrorCode = 'authentication_error' | 'permission_error' | 'not_found' | 'validation_error' | 'rate_limited' | 'server_error' | 'api_error' | 'connection_error' | 'signature_verification_failed';
+type GaruErrorCode = 'authentication_error' | 'permission_error' | 'not_found' | 'validation_error' | 'rate_limited' | 'charge_in_progress' | 'charge_already_processed' | 'server_error' | 'api_error' | 'connection_error' | 'signature_verification_failed';
 declare class GaruError extends Error {
     readonly code: GaruErrorCode;
     constructor(code: GaruErrorCode, message: string);
@@ -2016,8 +2044,40 @@ declare class GaruRateLimitError extends GaruAPIError {
     readonly retryAfterSec: number | null;
     constructor(message: string, status: number, requestId: string | null, body: unknown, retryAfterSec: number | null);
 }
+/**
+ * A charge identical to this one — same buyer, product, rail, amount and
+ * instalment count — is already being processed, or already went through inside
+ * the gateway's duplicate window.
+ *
+ * **This is not a failure.** The buyer's money is either on its way or already
+ * taken. Wait `retryAfterSec` and send the same request again: the retry is
+ * answered with the ORIGINAL charge rather than creating a second one.
+ *
+ * The SDK does not retry this for you. Re-POSTing to a money endpoint on your
+ * behalf is exactly the kind of hidden behaviour 5.0.0 removed, and if your own
+ * client also retries, the two stack.
+ *
+ * The real fix is upstream: pass `idempotencyKey` derived from something stable
+ * in your domain, so a retry reproduces it. This error is the backstop for when
+ * that has not happened.
+ *
+ * @example
+ * try {
+ *   await garu.charges.create({ productId, paymentMethod: 'creditCard', customer });
+ * } catch (err) {
+ *   if (err instanceof GaruDuplicateChargeError) {
+ *     await new Promise((r) => setTimeout(r, err.retryAfterSec * 1000));
+ *     // Sending it again returns the original charge.
+ *   }
+ * }
+ */
+declare class GaruDuplicateChargeError extends GaruAPIError {
+    /** How long to wait before sending the same request again. */
+    readonly retryAfterSec: number;
+    constructor(code: 'charge_in_progress' | 'charge_already_processed', message: string, status: number, requestId: string | null, body: unknown, retryAfterSec: number);
+}
 declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CancelAtPeriodEndScheduledChargeParams, type CancelChargeResult, type CancelInstallmentPlanParams, type CancelRecurrenceScheduledChargeParams, type CardInput, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeNowOutcome, type ChargeNowReason, type ChargeNowResult, type ChargePaymentMethod, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateInstallmentPlanParams, type CreateProductParams, type CreateScheduledChargeParams, type Customer, type CustomerList, type CustomerRecord, type FailurePayload, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, type GaruFailureCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type Installment, type InstallmentPlan, type InstallmentPlanList, type InstallmentPlanStatus, type InstallmentStatus, type ListChargesParams, type ListCustomersParams, type ListInstallmentPlansParams, type ListProductsParams, type ListRefundRequestsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeInstallmentParams, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type RefundRequest, type RefundRequestList, type RefundRequestStatus, type ReissueInstallmentResult, type RequestPlanRefundParams, type ResendWebhookEventParams, type ResolveRefundRequestParams, type ScheduledChargeActor, type ScheduledChargeAttempt, type ScheduledChargeAttemptList, type ScheduledChargeAttemptSource, type ScheduledChargeAttemptStatus, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type SetBillingEmailOverrideParams, type SetProductPortalConfigParams, type UpdateCustomerParams, type UpdateProductParams, type VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, webhooks };
+export { type CancelAtPeriodEndScheduledChargeParams, type CancelChargeResult, type CancelInstallmentPlanParams, type CancelRecurrenceScheduledChargeParams, type CardInput, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeNowOutcome, type ChargeNowReason, type ChargeNowResult, type ChargePaymentMethod, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateInstallmentPlanParams, type CreateProductParams, type CreateScheduledChargeParams, type Customer, type CustomerList, type CustomerRecord, type FailurePayload, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruDuplicateChargeError, GaruError, type GaruErrorCode, type GaruFailureCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type Installment, type InstallmentPlan, type InstallmentPlanList, type InstallmentPlanStatus, type InstallmentStatus, type ListChargesParams, type ListCustomersParams, type ListInstallmentPlansParams, type ListProductsParams, type ListRefundRequestsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeInstallmentParams, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type RefundRequest, type RefundRequestList, type RefundRequestStatus, type ReissueInstallmentResult, type RequestPlanRefundParams, type ResendWebhookEventParams, type ResolveRefundRequestParams, type ScheduledChargeActor, type ScheduledChargeAttempt, type ScheduledChargeAttemptList, type ScheduledChargeAttemptSource, type ScheduledChargeAttemptStatus, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type SetBillingEmailOverrideParams, type SetProductPortalConfigParams, type UpdateCustomerParams, type UpdateProductParams, type VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, webhooks };

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
@@ -1133,6 +1135,20 @@ declare class Charges {
      *   }
      * });
      * // charge.amount is the base price; charge.chargedTotal is what was charged.
+     *
+     * @example
+     * // Handling a duplicate. A 409 means an identical charge is already being
+     * // processed, or already went through — NOT that this one failed. Send the
+     * // same request again after the wait and you get the ORIGINAL charge back.
+     * // The SDK will not retry it for you.
+     * try {
+     *   await garu.charges.create({ productId, paymentMethod: 'creditCard', customer, card });
+     * } catch (err) {
+     *   if (err instanceof GaruDuplicateChargeError) {
+     *     await new Promise((r) => setTimeout(r, err.retryAfterSec * 1000));
+     *     // retry the same call
+     *   }
+     * }
      */
     create(params: CreateChargeParams): Promise<Charge>;
     /**
@@ -1159,10 +1175,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 +1212,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 +1332,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 +1425,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 +1599,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 +1653,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 +1928,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.
@@ -1982,7 +2010,7 @@ declare class Garu {
  * without parsing messages. Non-2xx API responses are mapped to the most specific
  * subclass of `GaruAPIError` by {@link mapApiError}.
  */
-type GaruErrorCode = 'authentication_error' | 'permission_error' | 'not_found' | 'validation_error' | 'rate_limited' | 'server_error' | 'api_error' | 'connection_error' | 'signature_verification_failed';
+type GaruErrorCode = 'authentication_error' | 'permission_error' | 'not_found' | 'validation_error' | 'rate_limited' | 'charge_in_progress' | 'charge_already_processed' | 'server_error' | 'api_error' | 'connection_error' | 'signature_verification_failed';
 declare class GaruError extends Error {
     readonly code: GaruErrorCode;
     constructor(code: GaruErrorCode, message: string);
@@ -2016,8 +2044,40 @@ declare class GaruRateLimitError extends GaruAPIError {
     readonly retryAfterSec: number | null;
     constructor(message: string, status: number, requestId: string | null, body: unknown, retryAfterSec: number | null);
 }
+/**
+ * A charge identical to this one — same buyer, product, rail, amount and
+ * instalment count — is already being processed, or already went through inside
+ * the gateway's duplicate window.
+ *
+ * **This is not a failure.** The buyer's money is either on its way or already
+ * taken. Wait `retryAfterSec` and send the same request again: the retry is
+ * answered with the ORIGINAL charge rather than creating a second one.
+ *
+ * The SDK does not retry this for you. Re-POSTing to a money endpoint on your
+ * behalf is exactly the kind of hidden behaviour 5.0.0 removed, and if your own
+ * client also retries, the two stack.
+ *
+ * The real fix is upstream: pass `idempotencyKey` derived from something stable
+ * in your domain, so a retry reproduces it. This error is the backstop for when
+ * that has not happened.
+ *
+ * @example
+ * try {
+ *   await garu.charges.create({ productId, paymentMethod: 'creditCard', customer });
+ * } catch (err) {
+ *   if (err instanceof GaruDuplicateChargeError) {
+ *     await new Promise((r) => setTimeout(r, err.retryAfterSec * 1000));
+ *     // Sending it again returns the original charge.
+ *   }
+ * }
+ */
+declare class GaruDuplicateChargeError extends GaruAPIError {
+    /** How long to wait before sending the same request again. */
+    readonly retryAfterSec: number;
+    constructor(code: 'charge_in_progress' | 'charge_already_processed', message: string, status: number, requestId: string | null, body: unknown, retryAfterSec: number);
+}
 declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CancelAtPeriodEndScheduledChargeParams, type CancelChargeResult, type CancelInstallmentPlanParams, type CancelRecurrenceScheduledChargeParams, type CardInput, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeNowOutcome, type ChargeNowReason, type ChargeNowResult, type ChargePaymentMethod, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateInstallmentPlanParams, type CreateProductParams, type CreateScheduledChargeParams, type Customer, type CustomerList, type CustomerRecord, type FailurePayload, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, type GaruFailureCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type Installment, type InstallmentPlan, type InstallmentPlanList, type InstallmentPlanStatus, type InstallmentStatus, type ListChargesParams, type ListCustomersParams, type ListInstallmentPlansParams, type ListProductsParams, type ListRefundRequestsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeInstallmentParams, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type RefundRequest, type RefundRequestList, type RefundRequestStatus, type ReissueInstallmentResult, type RequestPlanRefundParams, type ResendWebhookEventParams, type ResolveRefundRequestParams, type ScheduledChargeActor, type ScheduledChargeAttempt, type ScheduledChargeAttemptList, type ScheduledChargeAttemptSource, type ScheduledChargeAttemptStatus, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type SetBillingEmailOverrideParams, type SetProductPortalConfigParams, type UpdateCustomerParams, type UpdateProductParams, type VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, webhooks };
+export { type CancelAtPeriodEndScheduledChargeParams, type CancelChargeResult, type CancelInstallmentPlanParams, type CancelRecurrenceScheduledChargeParams, type CardInput, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeNowOutcome, type ChargeNowReason, type ChargeNowResult, type ChargePaymentMethod, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateInstallmentPlanParams, type CreateProductParams, type CreateScheduledChargeParams, type Customer, type CustomerList, type CustomerRecord, type FailurePayload, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruDuplicateChargeError, GaruError, type GaruErrorCode, type GaruFailureCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type Installment, type InstallmentPlan, type InstallmentPlanList, type InstallmentPlanStatus, type InstallmentStatus, type ListChargesParams, type ListCustomersParams, type ListInstallmentPlansParams, type ListProductsParams, type ListRefundRequestsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeInstallmentParams, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type RefundRequest, type RefundRequestList, type RefundRequestStatus, type ReissueInstallmentResult, type RequestPlanRefundParams, type ResendWebhookEventParams, type ResolveRefundRequestParams, type ScheduledChargeActor, type ScheduledChargeAttempt, type ScheduledChargeAttemptList, type ScheduledChargeAttemptSource, type ScheduledChargeAttemptStatus, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type SetBillingEmailOverrideParams, type SetProductPortalConfigParams, type UpdateCustomerParams, type UpdateProductParams, type VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, webhooks };

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
 
@@ -70,6 +70,15 @@ var GaruRateLimitError = class extends GaruAPIError {
     this.retryAfterSec = retryAfterSec;
   }
 };
+var GaruDuplicateChargeError = class extends GaruAPIError {
+  /** How long to wait before sending the same request again. */
+  retryAfterSec;
+  constructor(code, message, status, requestId, body, retryAfterSec) {
+    super(code, message, status, requestId, body);
+    this.name = "GaruDuplicateChargeError";
+    this.retryAfterSec = retryAfterSec;
+  }
+};
 var GaruServerError = class extends GaruAPIError {
   constructor(message, status, requestId, body) {
     super("server_error", message, status, requestId, body);
@@ -87,6 +96,13 @@ function mapApiError(status, body, requestId, retryAfterSec) {
   if (status === 429) {
     return new GaruRateLimitError(message, status, requestId, body, retryAfterSec);
   }
+  if (status === 409) {
+    const code = readDuplicateChargeCode(body);
+    if (code) {
+      const wait = retryAfterSec ?? readRetryAfterFromBody(body) ?? DEFAULT_DUPLICATE_RETRY_SEC;
+      return new GaruDuplicateChargeError(code, message, status, requestId, body, wait);
+    }
+  }
   if (status >= 500) return new GaruServerError(message, status, requestId, body);
   return new GaruAPIError("api_error", message, status, requestId, body);
 }
@@ -99,6 +115,15 @@ function extractMessage(body) {
   }
   return null;
 }
+var DEFAULT_DUPLICATE_RETRY_SEC = 5;
+function readDuplicateChargeCode(body) {
+  const code = body?.error;
+  return code === "charge_in_progress" || code === "charge_already_processed" ? code : null;
+}
+function readRetryAfterFromBody(body) {
+  const value = body?.retryAfter;
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
+}
 
 // src/http.ts
 var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
@@ -182,8 +207,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 +220,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
@@ -228,9 +255,22 @@ var Charges = class {
    *   }
    * });
    * // charge.amount is the base price; charge.chargedTotal is what was charged.
+   *
+   * @example
+   * // Handling a duplicate. A 409 means an identical charge is already being
+   * // processed, or already went through — NOT that this one failed. Send the
+   * // same request again after the wait and you get the ORIGINAL charge back.
+   * // The SDK will not retry it for you.
+   * try {
+   *   await garu.charges.create({ productId, paymentMethod: 'creditCard', customer, card });
+   * } catch (err) {
+   *   if (err instanceof GaruDuplicateChargeError) {
+   *     await new Promise((r) => setTimeout(r, err.retryAfterSec * 1000));
+   *     // retry the same call
+   *   }
+   * }
    */
   async create(params) {
-    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
     const body = {
       productId: params.productId,
       paymentMethod: params.paymentMethod,
@@ -239,7 +279,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 +320,24 @@ 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 +378,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 +413,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 +560,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 +572,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 +684,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 +701,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 +950,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 +970,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 +1009,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 +1044,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 +1437,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 +1452,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)
     );
@@ -1511,4 +1558,4 @@ var Garu = class {
   }
 };
 
-export { Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, GaruNotFoundError, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, webhooks };
+export { Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruDuplicateChargeError, GaruError, GaruNotFoundError, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, webhooks };

package/package.json

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