@garuhq/node 1.1.0 → 3.0.0

package/CHANGELOG.md

@@ -3,6 +3,94 @@
 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/).
 
+## [3.0.0] — 2026-08-22
+
+**Breaking:** `webhookEvents` now targets the versioned public API
+`/api/v1/webhook-events`, keyed on `uuid`. If you use `garu.webhookEvents.*`,
+read the migration below.
+
+### Breaking
+
+- **`webhookEvents` moved to `/api/v1/webhook-events`** and an event is
+  keyed by **`uuid`**, not a numeric `id`.
+  - `webhookEvents.get(id: number)` → **`webhookEvents.get(uuid: string)`**.
+  - `webhookEvents.retry(id)` / `webhookEvents.resend(id, params?)` — same
+    signature shape, but the id argument is now the `uuid`.
+  - `WebhookEvent.id` is **removed**; there is no numeric id in the public
+    shape. Use `WebhookEvent.uuid` everywhere. `WebhookEvent.endpointId` is
+    also removed — read `webhookEndpoint.id` instead (endpoint configuration
+    stays numeric; it did not move to `/api/v1`).
+  - `WebhookEvent.manualResendOf` is now a **`uuid` string** (was a numeric
+    id), pointing at the source event's `uuid`.
+  - **`webhookEvents.list()` returns `{ data, count, totalCount, totalPages }`**
+    (was `{ data, meta }`).
+  - The gateway's outbound `Idempotency-Key` for `/resend` clones is now
+    `resend_<uuid>` (was `resend_<numeric id>`), to match the public
+    identifier the SDK/CLI/MCP now expose.
+
+### Migration
+
+```ts
+// before (0.x – 2.x)
+const failed = await garu.webhookEvents.list({ status: 'failed', limit: 5 });
+const event = failed.data[0];
+event.id;                                // number
+const clone = await garu.webhookEvents.resend(event.id);
+clone.manualResendOf === event.id;       // true
+
+// after (3.0.0)
+const failed = await garu.webhookEvents.list({ status: 'failed', limit: 5 });
+const event = failed.data[0];
+event.uuid;                              // string
+const clone = await garu.webhookEvents.resend(event.uuid);
+clone.manualResendOf === event.uuid;     // true
+```
+
+## [2.0.0] — 2026-08-22
+
+**Breaking:** `customers` now targets the versioned public API `/api/v1/customers`,
+keyed on `uuid`. If you use `garu.customers.*`, read the migration below.
+
+### Breaking
+
+- **`customers` moved to `/api/v1/customers`** and a customer is keyed by
+  **`uuid`**, not a numeric `id`.
+  - `customers.get(id: number)` → **`customers.get(uuid: string)`** (name
+    unchanged, param type changed).
+  - `customers.update(id, params)` — same signature shape, but the id
+    argument is now the `uuid`, and the request now goes out as `PATCH`
+    (was `PUT`).
+  - `customers.setBillingEmailOverride(id, params)` / `customers.delete(id)`
+    — same, `id` → `uuid`.
+  - `CustomerRecord.id` is **removed**; there is no numeric id in the public
+    shape. Use `CustomerRecord.uuid` everywhere.
+  - **`customers.delete()` now resolves `{ removed: boolean }`** (was `void`).
+  - **`customers.list()` returns `{ data, count, totalCount, totalPages }`**
+    (was `{ data, meta }`).
+- `installmentPlans.create` and `scheduledCharges.create` are **not**
+  migrated yet — they still take a numeric `customerId`. Fetch that id from
+  the dashboard or the internal `/api/customers` endpoint until those two
+  resources move to `/api/v1` too (tracked in `SPEC-public-api-v1.md` §9
+  Phase 4 on the `gateway` repo).
+
+### Migration
+
+```ts
+// before (1.x)
+const c = await garu.customers.create({ name, email, document, phone, personType });
+c.id;                    // number
+const one = await garu.customers.get(c.id);
+await garu.customers.update(c.id, { name: 'Maria Santos' });
+await garu.customers.delete(c.id);
+
+// after (2.0.0)
+const c = await garu.customers.create({ name, email, document, phone, personType });
+c.uuid;                   // string
+const one = await garu.customers.get(c.uuid);
+await garu.customers.update(c.uuid, { name: 'Maria Santos' });
+const { removed } = await garu.customers.delete(c.uuid);
+```
+
 ## [1.1.0] — 2026-08-15
 
 

package/README.md

@@ -84,13 +84,13 @@ const garu = new Garu({
 
 ## Charges
 
-| Method                  | Description                                   |
-| ----------------------- | --------------------------------------------- |
-| `create(params)`        | Create a PIX, credit-card, or boleto charge.  |
-| `retrieve(uuid)`        | Fetch a single charge by uuid.                |
-| `list(params?)`         | List charges with pagination and filters.     |
-| `refund(uuid, params?)` | Refund a charge fully or partially (reais).   |
-| `cancel(uuid)`          | Cancel an unpaid charge.                       |
+| Method                  | Description                                  |
+| ----------------------- | -------------------------------------------- |
+| `create(params)`        | Create a PIX, credit-card, or boleto charge. |
+| `retrieve(uuid)`        | Fetch a single charge by uuid.               |
+| `list(params?)`         | List charges with pagination and filters.    |
+| `refund(uuid, params?)` | Refund a charge fully or partially (reais).  |
+| `cancel(uuid)`          | Cancel an unpaid charge.                     |
 
 ### Create a PIX charge
 
@@ -146,13 +146,20 @@ await garu.charges.refund('6f1c9b2e-…', { amount: 10.0 }); // partial refund (
 
 ## Customers
 
-| Method               | Description                                |
-| -------------------- | ------------------------------------------ |
-| `create(params)`     | Create a new customer.                     |
-| `list(params?)`      | List customers with pagination and search. |
-| `get(id)`            | Fetch a single customer by ID.             |
-| `update(id, params)` | Update a customer's profile.               |
-| `delete(id)`         | Delete a customer.                         |
+Backed by `/api/v1/customers`, keyed on `uuid` — there is no numeric id in
+this shape. `installmentPlans.create` and `scheduledCharges.create` still
+link customers by the internal numeric id (unmigrated resources); fetch that
+id from the dashboard or the internal `/api/customers` endpoint until they
+move to `/api/v1` too.
+
+| Method                                  | Description                                     |
+| --------------------------------------- | ----------------------------------------------- |
+| `create(params)`                        | Register a customer for the current seller.     |
+| `list(params?)`                         | List customers with pagination and search.      |
+| `get(uuid)`                             | Fetch a single customer by uuid.                |
+| `update(uuid, params)`                  | Partially update a customer's profile.          |
+| `setBillingEmailOverride(uuid, params)` | Set or clear the sticky billing-email override. |
+| `delete(uuid)`                          | Remove a customer from the current seller.      |
 
 ```ts
 const customer = await garu.customers.create({
@@ -163,7 +170,7 @@ const customer = await garu.customers.create({
   personType: 'fisica'
 });
 
-const { data, meta } = await garu.customers.list({ search: 'maria', limit: 10 });
+const { data, totalCount } = await garu.customers.list({ search: 'maria', limit: 10 });
 ```
 
 ## Products
@@ -390,18 +397,19 @@ The seller-facing delivery log for outbound webhooks. Use it to audit deliveries
 const failed = await garu.webhookEvents.list({ status: 'failed', limit: 50 });
 
 // Inspect one event end-to-end
-const event = await garu.webhookEvents.get(42);
-console.log(event.responseStatus, event.responseBody);
+const event = await garu.webhookEvents.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
+event.responseStatus;
+event.responseBody;
 
 // Audit-trail-preserving replay (recommended)
-const clone = await garu.webhookEvents.resend(42);
-clone.id !== event.id; // true — fresh row with its own id
-clone.manualResendOf === event.id; // true — points back at the source
+const clone = await garu.webhookEvents.resend(event.uuid);
+clone.uuid !== event.uuid; // true — fresh row with its own uuid
+clone.manualResendOf === event.uuid; // true — points back at the source
 ```
 
-`resend(id)` is the audit-preserving counterpart to `retry(id)` — the backend inserts a fresh event whose `manualResendOf` points back at the source, then dispatches that clone. The original row stays exactly as it was, so the historical record of the prior failure (status, response status/body, attempts) survives. Works on any source status (`success` / `failed` / `pending`).
+`resend(uuid)` is the audit-preserving counterpart to `retry(uuid)` — the backend inserts a fresh event whose `manualResendOf` points back at the source, then dispatches that clone. The original row stays exactly as it was, so the historical record of the prior failure (status, response status/body, attempts) survives. Works on any source status (`success` / `failed` / `pending`).
 
-Outbound deliveries of a resent event carry `Idempotency-Key: resend_<originalId>`, so recipient handlers can distinguish a resend from a fresh delivery both by the header prefix and by reading the response payload's `manualResendOf` field.
+Outbound deliveries of a resent event carry `Idempotency-Key: resend_<cloneUuid>`, so recipient handlers can distinguish a resend from a fresh delivery both by the header prefix and by reading the response payload's `manualResendOf` field.
 
 > [!NOTE]
 > The SDK auto-attaches `X-Idempotency-Key` (UUIDv4) on `resend()` so transient transport retries can't create duplicate clones. Pass `{ idempotencyKey }` to dedupe across your own retry layer.

package/dist/index.cjs

@@ -633,10 +633,11 @@ var Customers = class {
    *   phone: '11987654321',
    *   personType: 'fisica'
    * });
+   * customer.uuid;
    */
   async create(params) {
     return this.http.call(
-      (signal) => this.http.client.POST("/api/customers", {
+      (signal) => this.http.client.POST("/api/v1/customers", {
         body: params,
         signal
       }).then((r) => r)
@@ -646,7 +647,11 @@ var Customers = class {
    * List customers for the authenticated seller, with pagination and search.
    *
    * @example
-   * const { data, meta } = await garu.customers.list({ search: 'maria', limit: 10 });
+   * const { data, totalCount } = await garu.customers.list({ search: 'maria', limit: 10 });
+   *
+   * @example
+   * // Customers with at least one overdue scheduled charge (carnê included).
+   * const atRisk = await garu.customers.list({ status: 'overdue' });
    */
   async list(params = {}) {
     const query = {};
@@ -655,7 +660,7 @@ var Customers = class {
     if (params.search) query.search = params.search;
     if (params.status) query.status = params.status;
     const qs = new URLSearchParams(query).toString();
-    const url = `/api/customers${qs ? `?${qs}` : ""}`;
+    const url = `/api/v1/customers${qs ? `?${qs}` : ""}`;
     return this.http.call(
       (signal) => this.http.client.GET(url, { signal }).then(
         (r) => r
@@ -663,27 +668,28 @@ var Customers = class {
     );
   }
   /**
-   * Fetch a single customer by numeric ID.
+   * Fetch a single customer by uuid.
    *
    * @example
-   * const customer = await garu.customers.get(42);
+   * const customer = await garu.customers.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
    */
-  async get(id) {
+  async get(uuid) {
     return this.http.call(
-      (signal) => this.http.client.GET(`/api/customers/${id}`, { signal }).then(
+      (signal) => this.http.client.GET(`/api/v1/customers/${uuid}`, { signal }).then(
         (r) => r
       )
     );
   }
   /**
-   * Update a customer's profile for the current seller.
+   * Update a customer's profile for the current seller. Partial — only the
+   * fields you pass change.
    *
    * @example
-   * const updated = await garu.customers.update(42, { name: 'Maria Santos' });
+   * const updated = await garu.customers.update('a1b2c3d4-...', { name: 'Maria Santos' });
    */
-  async update(id, params) {
+  async update(uuid, params) {
     return this.http.call(
-      (signal) => this.http.client.PUT(`/api/customers/${id}`, {
+      (signal) => this.http.client.PATCH(`/api/v1/customers/${uuid}`, {
         body: params,
         signal
       }).then((r) => r)
@@ -698,30 +704,31 @@ var Customers = class {
    *
    * @example
    * // Set
-   * await garu.customers.setBillingEmailOverride(42, {
+   * await garu.customers.setBillingEmailOverride('a1b2c3d4-...', {
    *   billingEmailOverride: 'cobrancas@empresa.com.br'
    * });
    *
    * // Clear and fall back to the last-used email
-   * await garu.customers.setBillingEmailOverride(42, { billingEmailOverride: null });
+   * await garu.customers.setBillingEmailOverride('a1b2c3d4-...', { billingEmailOverride: null });
    */
-  async setBillingEmailOverride(id, params) {
+  async setBillingEmailOverride(uuid, params) {
     return this.http.call(
-      (signal) => this.http.client.PATCH(`/api/customers/${id}/billing-email-override`, {
+      (signal) => this.http.client.PATCH(`/api/v1/customers/${uuid}/billing-email-override`, {
         body: params,
         signal
       }).then((r) => r)
     );
   }
   /**
-   * Remove a customer from the current seller.
+   * Remove a customer from the current seller (unlinks your profile — the
+   * global customer and other sellers' profiles are untouched).
    *
    * @example
-   * await garu.customers.delete(42);
+   * await garu.customers.delete('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
    */
-  async delete(id) {
-    await this.http.call(
-      (signal) => this.http.client.DELETE(`/api/customers/${id}`, {
+  async delete(uuid) {
+    return this.http.call(
+      (signal) => this.http.client.DELETE(`/api/v1/customers/${uuid}`, {
         body: {},
         signal
       }).then((r) => r)
@@ -1286,42 +1293,31 @@ var WebhookEvents = class {
    * });
    */
   async list(params = {}) {
-    const qs = new URLSearchParams();
-    if (params.page !== void 0) qs.set("page", String(params.page));
-    if (params.limit !== void 0) qs.set("limit", String(params.limit));
-    if (params.status) qs.set("status", params.status);
-    if (params.eventType) qs.set("event_type", params.eventType);
-    if (params.endpointId !== void 0) qs.set("endpoint_id", String(params.endpointId));
-    const query = qs.toString();
-    const url = `/api/webhook-events${query ? `?${query}` : ""}`;
-    const raw = await this.http.call(
+    const query = {};
+    if (params.page !== void 0) query.page = String(params.page);
+    if (params.limit !== void 0) query.limit = String(params.limit);
+    if (params.status) query.status = params.status;
+    if (params.eventType) query.eventType = params.eventType;
+    if (params.endpointId !== void 0) query.endpointId = String(params.endpointId);
+    const qs = new URLSearchParams(query).toString();
+    const url = `/api/v1/webhook-events${qs ? `?${qs}` : ""}`;
+    return this.http.call(
       (signal) => this.http.client.GET(url, { signal }).then(
         (r) => r
       )
     );
-    return {
-      data: raw.events,
-      meta: {
-        page: raw.page,
-        limit: raw.limit,
-        total: raw.total,
-        totalPages: raw.pages
-      }
-    };
   }
   /**
-   * Fetch one webhook event by numeric ID — includes the full payload, the
+   * Fetch one webhook event by uuid — includes the full payload, the
    * embedded endpoint snapshot, and the most recent response status/body.
    *
    * @example
-   * const event = await garu.webhookEvents.get(42);
-   * if (event.status === 'failed') {
-   *   console.log(event.responseStatus, event.responseBody);
-   * }
+   * const event = await garu.webhookEvents.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
+   * event.status === 'failed' && event.responseStatus;
    */
-  async get(id) {
+  async get(uuid) {
     return this.http.call(
-      (signal) => this.http.client.GET(`/api/webhook-events/${id}`, { signal }).then(
+      (signal) => this.http.client.GET(`/api/v1/webhook-events/${uuid}`, { signal }).then(
         (r) => r
       )
     );
@@ -1334,28 +1330,28 @@ var WebhookEvents = class {
    * explicitly want the legacy in-place semantics (and for backwards
    * compatibility with older CLI / MCP releases).
    *
-   * Re-deliver a webhook event by ID. Resets it to `pending`, clears the
+   * Re-deliver a webhook event by uuid. Resets it to `pending`, clears the
    * retry schedule, and triggers an immediate delivery attempt. Works on
    * any status (`success`, `failed`, `pending`).
    *
    * @example
    * const failed = await garu.webhookEvents.list({ status: 'failed', limit: 5 });
    * for (const event of failed.data) {
-   *   await garu.webhookEvents.retry(event.id);
+   *   await garu.webhookEvents.retry(event.uuid);
    * }
    */
-  async retry(id) {
+  async retry(uuid) {
     return this.http.call(
-      (signal) => this.http.client.POST(`/api/webhook-events/${id}/retry`, {
+      (signal) => this.http.client.POST(`/api/v1/webhook-events/${uuid}/retry`, {
         body: {},
         signal
       }).then((r) => r)
     );
   }
   /**
-   * Re-deliver a webhook event by ID, audit-trail preserving. Unlike
+   * Re-deliver a webhook event by uuid, audit-trail preserving. Unlike
    * {@link retry}, this does *not* mutate the original row — it inserts a
-   * fresh event (new numeric id) that points back at the source via
+   * fresh event (new uuid) that points back at the source via
    * `manualResendOf`, then dispatches that clone. The original row is
    * untouched, so the historical record of the prior failure (and its
    * response status / body) is preserved.
@@ -1366,30 +1362,30 @@ var WebhookEvents = class {
    * delivery's outcome to remain on the record.
    *
    * **Outbound delivery semantics**: the gateway POSTs the clone with
-   * `Idempotency-Key: resend_<originalId>` (where `<originalId>` is the id
-   * of the source event, not the clone). Recipient handlers that key off
+   * `Idempotency-Key: resend_<cloneUuid>`. Recipient handlers that key off
    * `Idempotency-Key` will see this as a distinct delivery from the
    * original — distinguishable both by the `resend_` prefix and by reading
    * the response payload's `manualResendOf` field.
    *
-   * **SDK→gateway dedup**: the SDK auto-attaches `X-Idempotency-Key`
-   * (UUIDv4 unless you pass `idempotencyKey`) so transient transport
-   * retries (5xx → SDK backoff) cannot create duplicate clones — the
-   * backend returns the original clone on the second call within 24h.
+   * 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.
    *
-   * Returns the *clone* event (new id), not the original. The original is
+   * Returns the *clone* event (new uuid), not the original. The original is
    * unchanged on the server.
    *
    * @example
-   * const event = await garu.webhookEvents.get(42);
-   * const clone = await garu.webhookEvents.resend(42);
-   * clone.id !== event.id;            // true — clone has its own id
-   * clone.manualResendOf === event.id; // true — points back at the source
+   * const event = await garu.webhookEvents.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
+   * const clone = await garu.webhookEvents.resend(event.uuid);
+   * clone.uuid !== event.uuid;            // true — clone has its own uuid
+   * clone.manualResendOf === event.uuid; // true — points back at the source
    */
-  async resend(id, params = {}) {
+  async resend(uuid, params = {}) {
     const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
     return this.http.call(
-      (signal) => this.http.client.POST(`/api/webhook-events/${id}/resend`, {
+      (signal) => this.http.client.POST(`/api/v1/webhook-events/${uuid}/resend`, {
         body: {},
         headers: { "X-Idempotency-Key": idempotencyKey },
         signal

package/dist/index.d.cts

@@ -261,8 +261,15 @@ interface ChargeList {
 interface CancelChargeResult {
     canceled: boolean;
 }
+/**
+ * Public API v1 customer representation. Keyed on `uuid` — there is no
+ * numeric id in this shape. `installmentPlans.create` and
+ * `scheduledCharges.create` still link customers by the internal numeric id
+ * (unmigrated resources); fetch that id from the dashboard or the internal
+ * `/api/customers` endpoint until they move to `/api/v1` too.
+ */
 interface CustomerRecord {
-    id: number;
+    uuid: string;
     name: string;
     email: string;
     document: string;
@@ -281,10 +288,9 @@ interface CustomerRecord {
      * Resolved billing email used for outbound seller→customer emails:
      * `billingEmailOverride ?? per-seller email ?? customer.email`.
      */
-    billingEmail?: string;
+    billingEmail: string;
     /** True when a sticky `billingEmailOverride` is set for this seller. */
-    hasBillingEmailOverride?: boolean;
-    [key: string]: unknown;
+    hasBillingEmailOverride: boolean;
 }
 interface SetBillingEmailOverrideParams {
     /**
@@ -293,7 +299,14 @@ interface SetBillingEmailOverrideParams {
      */
     billingEmailOverride: string | null;
 }
-type CustomerList = PaginatedList<CustomerRecord>;
+interface CustomerList {
+    data: CustomerRecord[];
+    /** Items on this page. */
+    count: number;
+    /** Total matches across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
 interface CreateCustomerParams {
     name: string;
     email: string;
@@ -757,9 +770,14 @@ interface WebhookEventEndpoint {
     events: string[];
     [key: string]: unknown;
 }
+/**
+ * Public API v1 webhook-event representation. Keyed on `uuid` — there is no
+ * numeric id in this shape. `webhookEndpoint.id` stays numeric: endpoint
+ * *configuration* (create/update/delete) is still dashboard-only and did
+ * not move to `/api/v1`.
+ */
 interface WebhookEvent {
-    id: number;
-    endpointId: number;
+    uuid: string;
     /** Eager-loaded endpoint snapshot. */
     webhookEndpoint: WebhookEventEndpoint;
     /** Garu event type, e.g. `transaction.payment.paid`. */
@@ -778,17 +796,24 @@ interface WebhookEvent {
     /** Response body from the most recent attempt, truncated by the gateway. */
     responseBody: string | null;
     /**
-     * When this row is a clone produced by `webhookEvents.resend(id)`, this is
-     * the numeric id of the original event the clone was forked from. `null`
-     * on every originally-fired event (and on events resurrected via the
-     * legacy `webhookEvents.retry(id)` mutation, which mutates in place
-     * instead of cloning).
+     * When this row is a clone produced by `webhookEvents.resend(uuid)`, this
+     * is the uuid of the original event the clone was forked from. `null` on
+     * every originally-fired event (and on events resurrected via the legacy
+     * `webhookEvents.retry(uuid)` mutation, which mutates in place instead of
+     * cloning).
      */
-    manualResendOf: number | null;
+    manualResendOf: string | null;
     createdAt: string;
     [key: string]: unknown;
 }
-type WebhookEventList = PaginatedList<WebhookEvent>;
+interface WebhookEventList {
+    data: WebhookEvent[];
+    /** Items on this page. */
+    count: number;
+    /** Total matches across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
 interface ListWebhookEventsParams {
     page?: number;
     limit?: number;
@@ -1315,9 +1340,11 @@ declare class RefundRequests {
 /**
  * Customers — manage your customer base.
  *
- * Customers are scoped to the seller identified by the API key. The backend
- * uses a junction table (`customer_seller_profile`) so the same person can
- * exist across multiple sellers without duplication.
+ * Backed by `/api/v1/customers`, keyed on `uuid`. Customers are scoped to the
+ * seller identified by the API key. The backend uses a junction table
+ * (`customer_seller_profile`) so the same person can exist across multiple
+ * sellers without duplication — creating a customer whose `document` already
+ * exists globally attaches your own profile to it instead of erroring.
  */
 declare class Customers {
     private readonly http;
@@ -1333,29 +1360,35 @@ declare class Customers {
      *   phone: '11987654321',
      *   personType: 'fisica'
      * });
+     * customer.uuid;
      */
     create(params: CreateCustomerParams): Promise<CustomerRecord>;
     /**
      * List customers for the authenticated seller, with pagination and search.
      *
      * @example
-     * const { data, meta } = await garu.customers.list({ search: 'maria', limit: 10 });
+     * const { data, totalCount } = await garu.customers.list({ search: 'maria', limit: 10 });
+     *
+     * @example
+     * // Customers with at least one overdue scheduled charge (carnê included).
+     * const atRisk = await garu.customers.list({ status: 'overdue' });
      */
     list(params?: ListCustomersParams): Promise<CustomerList>;
     /**
-     * Fetch a single customer by numeric ID.
+     * Fetch a single customer by uuid.
      *
      * @example
-     * const customer = await garu.customers.get(42);
+     * const customer = await garu.customers.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
      */
-    get(id: number): Promise<CustomerRecord>;
+    get(uuid: string): Promise<CustomerRecord>;
     /**
-     * Update a customer's profile for the current seller.
+     * Update a customer's profile for the current seller. Partial — only the
+     * fields you pass change.
      *
      * @example
-     * const updated = await garu.customers.update(42, { name: 'Maria Santos' });
+     * const updated = await garu.customers.update('a1b2c3d4-...', { name: 'Maria Santos' });
      */
-    update(id: number, params: UpdateCustomerParams): Promise<CustomerRecord>;
+    update(uuid: string, params: UpdateCustomerParams): Promise<CustomerRecord>;
     /**
      * Set or clear the per-seller billing email override.
      *
@@ -1365,21 +1398,24 @@ declare class Customers {
      *
      * @example
      * // Set
-     * await garu.customers.setBillingEmailOverride(42, {
+     * await garu.customers.setBillingEmailOverride('a1b2c3d4-...', {
      *   billingEmailOverride: 'cobrancas@empresa.com.br'
      * });
      *
      * // Clear and fall back to the last-used email
-     * await garu.customers.setBillingEmailOverride(42, { billingEmailOverride: null });
+     * await garu.customers.setBillingEmailOverride('a1b2c3d4-...', { billingEmailOverride: null });
      */
-    setBillingEmailOverride(id: number, params: SetBillingEmailOverrideParams): Promise<CustomerRecord>;
+    setBillingEmailOverride(uuid: string, params: SetBillingEmailOverrideParams): Promise<CustomerRecord>;
     /**
-     * Remove a customer from the current seller.
+     * Remove a customer from the current seller (unlinks your profile — the
+     * global customer and other sellers' profiles are untouched).
      *
      * @example
-     * await garu.customers.delete(42);
+     * await garu.customers.delete('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
      */
-    delete(id: number): Promise<void>;
+    delete(uuid: string): Promise<{
+        removed: boolean;
+    }>;
 }
 
 /**
@@ -1730,7 +1766,8 @@ declare class ScheduledCharges {
 /**
  * Webhook events — the seller-facing delivery log for outbound webhooks.
  *
- * Every time the gateway fires a webhook (e.g. `transaction.payment.paid`,
+ * Backed by `/api/v1/webhook-events`, keyed on `uuid`. Every time the
+ * gateway fires a webhook (e.g. `transaction.payment.paid`,
  * `scheduled_charge.cycle_failed`), it persists one row per destination
  * endpoint with the full payload, the HTTP outcome, and the retry schedule.
  * Use this resource to audit deliveries from the seller's API key — the
@@ -1738,6 +1775,7 @@ declare class ScheduledCharges {
  *
  * Webhook endpoint *configuration* (URL, subscribed events, secret) is still
  * dashboard-only — this resource only covers the event log + manual retries.
+ * `webhookEndpoint.id` on every event stays a numeric id for that reason.
  */
 declare class WebhookEvents {
     private readonly http;
@@ -1760,16 +1798,14 @@ declare class WebhookEvents {
      */
     list(params?: ListWebhookEventsParams): Promise<WebhookEventList>;
     /**
-     * Fetch one webhook event by numeric ID — includes the full payload, the
+     * Fetch one webhook event by uuid — includes the full payload, the
      * embedded endpoint snapshot, and the most recent response status/body.
      *
      * @example
-     * const event = await garu.webhookEvents.get(42);
-     * if (event.status === 'failed') {
-     *   console.log(event.responseStatus, event.responseBody);
-     * }
+     * const event = await garu.webhookEvents.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
+     * event.status === 'failed' && event.responseStatus;
      */
-    get(id: number): Promise<WebhookEvent>;
+    get(uuid: string): Promise<WebhookEvent>;
     /**
      * @deprecated For most cases prefer {@link resend}, which preserves the
      * original event's audit trail by cloning rather than mutating. `retry()`
@@ -1778,21 +1814,21 @@ declare class WebhookEvents {
      * explicitly want the legacy in-place semantics (and for backwards
      * compatibility with older CLI / MCP releases).
      *
-     * Re-deliver a webhook event by ID. Resets it to `pending`, clears the
+     * Re-deliver a webhook event by uuid. Resets it to `pending`, clears the
      * retry schedule, and triggers an immediate delivery attempt. Works on
      * any status (`success`, `failed`, `pending`).
      *
      * @example
      * const failed = await garu.webhookEvents.list({ status: 'failed', limit: 5 });
      * for (const event of failed.data) {
-     *   await garu.webhookEvents.retry(event.id);
+     *   await garu.webhookEvents.retry(event.uuid);
      * }
      */
-    retry(id: number): Promise<WebhookEvent>;
+    retry(uuid: string): Promise<WebhookEvent>;
     /**
-     * Re-deliver a webhook event by ID, audit-trail preserving. Unlike
+     * Re-deliver a webhook event by uuid, audit-trail preserving. Unlike
      * {@link retry}, this does *not* mutate the original row — it inserts a
-     * fresh event (new numeric id) that points back at the source via
+     * fresh event (new uuid) that points back at the source via
      * `manualResendOf`, then dispatches that clone. The original row is
      * untouched, so the historical record of the prior failure (and its
      * response status / body) is preserved.
@@ -1803,27 +1839,27 @@ declare class WebhookEvents {
      * delivery's outcome to remain on the record.
      *
      * **Outbound delivery semantics**: the gateway POSTs the clone with
-     * `Idempotency-Key: resend_<originalId>` (where `<originalId>` is the id
-     * of the source event, not the clone). Recipient handlers that key off
+     * `Idempotency-Key: resend_<cloneUuid>`. Recipient handlers that key off
      * `Idempotency-Key` will see this as a distinct delivery from the
      * original — distinguishable both by the `resend_` prefix and by reading
      * the response payload's `manualResendOf` field.
      *
-     * **SDK→gateway dedup**: the SDK auto-attaches `X-Idempotency-Key`
-     * (UUIDv4 unless you pass `idempotencyKey`) so transient transport
-     * retries (5xx → SDK backoff) cannot create duplicate clones — the
-     * backend returns the original clone on the second call within 24h.
+     * 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.
      *
-     * Returns the *clone* event (new id), not the original. The original is
+     * Returns the *clone* event (new uuid), not the original. The original is
      * unchanged on the server.
      *
      * @example
-     * const event = await garu.webhookEvents.get(42);
-     * const clone = await garu.webhookEvents.resend(42);
-     * clone.id !== event.id;            // true — clone has its own id
-     * clone.manualResendOf === event.id; // true — points back at the source
+     * const event = await garu.webhookEvents.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
+     * const clone = await garu.webhookEvents.resend(event.uuid);
+     * clone.uuid !== event.uuid;            // true — clone has its own uuid
+     * clone.manualResendOf === event.uuid; // true — points back at the source
      */
-    resend(id: number, params?: ResendWebhookEventParams): Promise<WebhookEvent>;
+    resend(uuid: string, params?: ResendWebhookEventParams): Promise<WebhookEvent>;
 }
 
 interface GaruOptions {
@@ -1929,4 +1965,4 @@ 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 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, 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

@@ -261,8 +261,15 @@ interface ChargeList {
 interface CancelChargeResult {
     canceled: boolean;
 }
+/**
+ * Public API v1 customer representation. Keyed on `uuid` — there is no
+ * numeric id in this shape. `installmentPlans.create` and
+ * `scheduledCharges.create` still link customers by the internal numeric id
+ * (unmigrated resources); fetch that id from the dashboard or the internal
+ * `/api/customers` endpoint until they move to `/api/v1` too.
+ */
 interface CustomerRecord {
-    id: number;
+    uuid: string;
     name: string;
     email: string;
     document: string;
@@ -281,10 +288,9 @@ interface CustomerRecord {
      * Resolved billing email used for outbound seller→customer emails:
      * `billingEmailOverride ?? per-seller email ?? customer.email`.
      */
-    billingEmail?: string;
+    billingEmail: string;
     /** True when a sticky `billingEmailOverride` is set for this seller. */
-    hasBillingEmailOverride?: boolean;
-    [key: string]: unknown;
+    hasBillingEmailOverride: boolean;
 }
 interface SetBillingEmailOverrideParams {
     /**
@@ -293,7 +299,14 @@ interface SetBillingEmailOverrideParams {
      */
     billingEmailOverride: string | null;
 }
-type CustomerList = PaginatedList<CustomerRecord>;
+interface CustomerList {
+    data: CustomerRecord[];
+    /** Items on this page. */
+    count: number;
+    /** Total matches across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
 interface CreateCustomerParams {
     name: string;
     email: string;
@@ -757,9 +770,14 @@ interface WebhookEventEndpoint {
     events: string[];
     [key: string]: unknown;
 }
+/**
+ * Public API v1 webhook-event representation. Keyed on `uuid` — there is no
+ * numeric id in this shape. `webhookEndpoint.id` stays numeric: endpoint
+ * *configuration* (create/update/delete) is still dashboard-only and did
+ * not move to `/api/v1`.
+ */
 interface WebhookEvent {
-    id: number;
-    endpointId: number;
+    uuid: string;
     /** Eager-loaded endpoint snapshot. */
     webhookEndpoint: WebhookEventEndpoint;
     /** Garu event type, e.g. `transaction.payment.paid`. */
@@ -778,17 +796,24 @@ interface WebhookEvent {
     /** Response body from the most recent attempt, truncated by the gateway. */
     responseBody: string | null;
     /**
-     * When this row is a clone produced by `webhookEvents.resend(id)`, this is
-     * the numeric id of the original event the clone was forked from. `null`
-     * on every originally-fired event (and on events resurrected via the
-     * legacy `webhookEvents.retry(id)` mutation, which mutates in place
-     * instead of cloning).
+     * When this row is a clone produced by `webhookEvents.resend(uuid)`, this
+     * is the uuid of the original event the clone was forked from. `null` on
+     * every originally-fired event (and on events resurrected via the legacy
+     * `webhookEvents.retry(uuid)` mutation, which mutates in place instead of
+     * cloning).
      */
-    manualResendOf: number | null;
+    manualResendOf: string | null;
     createdAt: string;
     [key: string]: unknown;
 }
-type WebhookEventList = PaginatedList<WebhookEvent>;
+interface WebhookEventList {
+    data: WebhookEvent[];
+    /** Items on this page. */
+    count: number;
+    /** Total matches across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
 interface ListWebhookEventsParams {
     page?: number;
     limit?: number;
@@ -1315,9 +1340,11 @@ declare class RefundRequests {
 /**
  * Customers — manage your customer base.
  *
- * Customers are scoped to the seller identified by the API key. The backend
- * uses a junction table (`customer_seller_profile`) so the same person can
- * exist across multiple sellers without duplication.
+ * Backed by `/api/v1/customers`, keyed on `uuid`. Customers are scoped to the
+ * seller identified by the API key. The backend uses a junction table
+ * (`customer_seller_profile`) so the same person can exist across multiple
+ * sellers without duplication — creating a customer whose `document` already
+ * exists globally attaches your own profile to it instead of erroring.
  */
 declare class Customers {
     private readonly http;
@@ -1333,29 +1360,35 @@ declare class Customers {
      *   phone: '11987654321',
      *   personType: 'fisica'
      * });
+     * customer.uuid;
      */
     create(params: CreateCustomerParams): Promise<CustomerRecord>;
     /**
      * List customers for the authenticated seller, with pagination and search.
      *
      * @example
-     * const { data, meta } = await garu.customers.list({ search: 'maria', limit: 10 });
+     * const { data, totalCount } = await garu.customers.list({ search: 'maria', limit: 10 });
+     *
+     * @example
+     * // Customers with at least one overdue scheduled charge (carnê included).
+     * const atRisk = await garu.customers.list({ status: 'overdue' });
      */
     list(params?: ListCustomersParams): Promise<CustomerList>;
     /**
-     * Fetch a single customer by numeric ID.
+     * Fetch a single customer by uuid.
      *
      * @example
-     * const customer = await garu.customers.get(42);
+     * const customer = await garu.customers.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
      */
-    get(id: number): Promise<CustomerRecord>;
+    get(uuid: string): Promise<CustomerRecord>;
     /**
-     * Update a customer's profile for the current seller.
+     * Update a customer's profile for the current seller. Partial — only the
+     * fields you pass change.
      *
      * @example
-     * const updated = await garu.customers.update(42, { name: 'Maria Santos' });
+     * const updated = await garu.customers.update('a1b2c3d4-...', { name: 'Maria Santos' });
      */
-    update(id: number, params: UpdateCustomerParams): Promise<CustomerRecord>;
+    update(uuid: string, params: UpdateCustomerParams): Promise<CustomerRecord>;
     /**
      * Set or clear the per-seller billing email override.
      *
@@ -1365,21 +1398,24 @@ declare class Customers {
      *
      * @example
      * // Set
-     * await garu.customers.setBillingEmailOverride(42, {
+     * await garu.customers.setBillingEmailOverride('a1b2c3d4-...', {
      *   billingEmailOverride: 'cobrancas@empresa.com.br'
      * });
      *
      * // Clear and fall back to the last-used email
-     * await garu.customers.setBillingEmailOverride(42, { billingEmailOverride: null });
+     * await garu.customers.setBillingEmailOverride('a1b2c3d4-...', { billingEmailOverride: null });
      */
-    setBillingEmailOverride(id: number, params: SetBillingEmailOverrideParams): Promise<CustomerRecord>;
+    setBillingEmailOverride(uuid: string, params: SetBillingEmailOverrideParams): Promise<CustomerRecord>;
     /**
-     * Remove a customer from the current seller.
+     * Remove a customer from the current seller (unlinks your profile — the
+     * global customer and other sellers' profiles are untouched).
      *
      * @example
-     * await garu.customers.delete(42);
+     * await garu.customers.delete('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
      */
-    delete(id: number): Promise<void>;
+    delete(uuid: string): Promise<{
+        removed: boolean;
+    }>;
 }
 
 /**
@@ -1730,7 +1766,8 @@ declare class ScheduledCharges {
 /**
  * Webhook events — the seller-facing delivery log for outbound webhooks.
  *
- * Every time the gateway fires a webhook (e.g. `transaction.payment.paid`,
+ * Backed by `/api/v1/webhook-events`, keyed on `uuid`. Every time the
+ * gateway fires a webhook (e.g. `transaction.payment.paid`,
  * `scheduled_charge.cycle_failed`), it persists one row per destination
  * endpoint with the full payload, the HTTP outcome, and the retry schedule.
  * Use this resource to audit deliveries from the seller's API key — the
@@ -1738,6 +1775,7 @@ declare class ScheduledCharges {
  *
  * Webhook endpoint *configuration* (URL, subscribed events, secret) is still
  * dashboard-only — this resource only covers the event log + manual retries.
+ * `webhookEndpoint.id` on every event stays a numeric id for that reason.
  */
 declare class WebhookEvents {
     private readonly http;
@@ -1760,16 +1798,14 @@ declare class WebhookEvents {
      */
     list(params?: ListWebhookEventsParams): Promise<WebhookEventList>;
     /**
-     * Fetch one webhook event by numeric ID — includes the full payload, the
+     * Fetch one webhook event by uuid — includes the full payload, the
      * embedded endpoint snapshot, and the most recent response status/body.
      *
      * @example
-     * const event = await garu.webhookEvents.get(42);
-     * if (event.status === 'failed') {
-     *   console.log(event.responseStatus, event.responseBody);
-     * }
+     * const event = await garu.webhookEvents.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
+     * event.status === 'failed' && event.responseStatus;
      */
-    get(id: number): Promise<WebhookEvent>;
+    get(uuid: string): Promise<WebhookEvent>;
     /**
      * @deprecated For most cases prefer {@link resend}, which preserves the
      * original event's audit trail by cloning rather than mutating. `retry()`
@@ -1778,21 +1814,21 @@ declare class WebhookEvents {
      * explicitly want the legacy in-place semantics (and for backwards
      * compatibility with older CLI / MCP releases).
      *
-     * Re-deliver a webhook event by ID. Resets it to `pending`, clears the
+     * Re-deliver a webhook event by uuid. Resets it to `pending`, clears the
      * retry schedule, and triggers an immediate delivery attempt. Works on
      * any status (`success`, `failed`, `pending`).
      *
      * @example
      * const failed = await garu.webhookEvents.list({ status: 'failed', limit: 5 });
      * for (const event of failed.data) {
-     *   await garu.webhookEvents.retry(event.id);
+     *   await garu.webhookEvents.retry(event.uuid);
      * }
      */
-    retry(id: number): Promise<WebhookEvent>;
+    retry(uuid: string): Promise<WebhookEvent>;
     /**
-     * Re-deliver a webhook event by ID, audit-trail preserving. Unlike
+     * Re-deliver a webhook event by uuid, audit-trail preserving. Unlike
      * {@link retry}, this does *not* mutate the original row — it inserts a
-     * fresh event (new numeric id) that points back at the source via
+     * fresh event (new uuid) that points back at the source via
      * `manualResendOf`, then dispatches that clone. The original row is
      * untouched, so the historical record of the prior failure (and its
      * response status / body) is preserved.
@@ -1803,27 +1839,27 @@ declare class WebhookEvents {
      * delivery's outcome to remain on the record.
      *
      * **Outbound delivery semantics**: the gateway POSTs the clone with
-     * `Idempotency-Key: resend_<originalId>` (where `<originalId>` is the id
-     * of the source event, not the clone). Recipient handlers that key off
+     * `Idempotency-Key: resend_<cloneUuid>`. Recipient handlers that key off
      * `Idempotency-Key` will see this as a distinct delivery from the
      * original — distinguishable both by the `resend_` prefix and by reading
      * the response payload's `manualResendOf` field.
      *
-     * **SDK→gateway dedup**: the SDK auto-attaches `X-Idempotency-Key`
-     * (UUIDv4 unless you pass `idempotencyKey`) so transient transport
-     * retries (5xx → SDK backoff) cannot create duplicate clones — the
-     * backend returns the original clone on the second call within 24h.
+     * 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.
      *
-     * Returns the *clone* event (new id), not the original. The original is
+     * Returns the *clone* event (new uuid), not the original. The original is
      * unchanged on the server.
      *
      * @example
-     * const event = await garu.webhookEvents.get(42);
-     * const clone = await garu.webhookEvents.resend(42);
-     * clone.id !== event.id;            // true — clone has its own id
-     * clone.manualResendOf === event.id; // true — points back at the source
+     * const event = await garu.webhookEvents.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
+     * const clone = await garu.webhookEvents.resend(event.uuid);
+     * clone.uuid !== event.uuid;            // true — clone has its own uuid
+     * clone.manualResendOf === event.uuid; // true — points back at the source
      */
-    resend(id: number, params?: ResendWebhookEventParams): Promise<WebhookEvent>;
+    resend(uuid: string, params?: ResendWebhookEventParams): Promise<WebhookEvent>;
 }
 
 interface GaruOptions {
@@ -1929,4 +1965,4 @@ 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 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, 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

@@ -627,10 +627,11 @@ var Customers = class {
    *   phone: '11987654321',
    *   personType: 'fisica'
    * });
+   * customer.uuid;
    */
   async create(params) {
     return this.http.call(
-      (signal) => this.http.client.POST("/api/customers", {
+      (signal) => this.http.client.POST("/api/v1/customers", {
         body: params,
         signal
       }).then((r) => r)
@@ -640,7 +641,11 @@ var Customers = class {
    * List customers for the authenticated seller, with pagination and search.
    *
    * @example
-   * const { data, meta } = await garu.customers.list({ search: 'maria', limit: 10 });
+   * const { data, totalCount } = await garu.customers.list({ search: 'maria', limit: 10 });
+   *
+   * @example
+   * // Customers with at least one overdue scheduled charge (carnê included).
+   * const atRisk = await garu.customers.list({ status: 'overdue' });
    */
   async list(params = {}) {
     const query = {};
@@ -649,7 +654,7 @@ var Customers = class {
     if (params.search) query.search = params.search;
     if (params.status) query.status = params.status;
     const qs = new URLSearchParams(query).toString();
-    const url = `/api/customers${qs ? `?${qs}` : ""}`;
+    const url = `/api/v1/customers${qs ? `?${qs}` : ""}`;
     return this.http.call(
       (signal) => this.http.client.GET(url, { signal }).then(
         (r) => r
@@ -657,27 +662,28 @@ var Customers = class {
     );
   }
   /**
-   * Fetch a single customer by numeric ID.
+   * Fetch a single customer by uuid.
    *
    * @example
-   * const customer = await garu.customers.get(42);
+   * const customer = await garu.customers.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
    */
-  async get(id) {
+  async get(uuid) {
     return this.http.call(
-      (signal) => this.http.client.GET(`/api/customers/${id}`, { signal }).then(
+      (signal) => this.http.client.GET(`/api/v1/customers/${uuid}`, { signal }).then(
         (r) => r
       )
     );
   }
   /**
-   * Update a customer's profile for the current seller.
+   * Update a customer's profile for the current seller. Partial — only the
+   * fields you pass change.
    *
    * @example
-   * const updated = await garu.customers.update(42, { name: 'Maria Santos' });
+   * const updated = await garu.customers.update('a1b2c3d4-...', { name: 'Maria Santos' });
    */
-  async update(id, params) {
+  async update(uuid, params) {
     return this.http.call(
-      (signal) => this.http.client.PUT(`/api/customers/${id}`, {
+      (signal) => this.http.client.PATCH(`/api/v1/customers/${uuid}`, {
         body: params,
         signal
       }).then((r) => r)
@@ -692,30 +698,31 @@ var Customers = class {
    *
    * @example
    * // Set
-   * await garu.customers.setBillingEmailOverride(42, {
+   * await garu.customers.setBillingEmailOverride('a1b2c3d4-...', {
    *   billingEmailOverride: 'cobrancas@empresa.com.br'
    * });
    *
    * // Clear and fall back to the last-used email
-   * await garu.customers.setBillingEmailOverride(42, { billingEmailOverride: null });
+   * await garu.customers.setBillingEmailOverride('a1b2c3d4-...', { billingEmailOverride: null });
    */
-  async setBillingEmailOverride(id, params) {
+  async setBillingEmailOverride(uuid, params) {
     return this.http.call(
-      (signal) => this.http.client.PATCH(`/api/customers/${id}/billing-email-override`, {
+      (signal) => this.http.client.PATCH(`/api/v1/customers/${uuid}/billing-email-override`, {
         body: params,
         signal
       }).then((r) => r)
     );
   }
   /**
-   * Remove a customer from the current seller.
+   * Remove a customer from the current seller (unlinks your profile — the
+   * global customer and other sellers' profiles are untouched).
    *
    * @example
-   * await garu.customers.delete(42);
+   * await garu.customers.delete('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
    */
-  async delete(id) {
-    await this.http.call(
-      (signal) => this.http.client.DELETE(`/api/customers/${id}`, {
+  async delete(uuid) {
+    return this.http.call(
+      (signal) => this.http.client.DELETE(`/api/v1/customers/${uuid}`, {
         body: {},
         signal
       }).then((r) => r)
@@ -1280,42 +1287,31 @@ var WebhookEvents = class {
    * });
    */
   async list(params = {}) {
-    const qs = new URLSearchParams();
-    if (params.page !== void 0) qs.set("page", String(params.page));
-    if (params.limit !== void 0) qs.set("limit", String(params.limit));
-    if (params.status) qs.set("status", params.status);
-    if (params.eventType) qs.set("event_type", params.eventType);
-    if (params.endpointId !== void 0) qs.set("endpoint_id", String(params.endpointId));
-    const query = qs.toString();
-    const url = `/api/webhook-events${query ? `?${query}` : ""}`;
-    const raw = await this.http.call(
+    const query = {};
+    if (params.page !== void 0) query.page = String(params.page);
+    if (params.limit !== void 0) query.limit = String(params.limit);
+    if (params.status) query.status = params.status;
+    if (params.eventType) query.eventType = params.eventType;
+    if (params.endpointId !== void 0) query.endpointId = String(params.endpointId);
+    const qs = new URLSearchParams(query).toString();
+    const url = `/api/v1/webhook-events${qs ? `?${qs}` : ""}`;
+    return this.http.call(
       (signal) => this.http.client.GET(url, { signal }).then(
         (r) => r
       )
     );
-    return {
-      data: raw.events,
-      meta: {
-        page: raw.page,
-        limit: raw.limit,
-        total: raw.total,
-        totalPages: raw.pages
-      }
-    };
   }
   /**
-   * Fetch one webhook event by numeric ID — includes the full payload, the
+   * Fetch one webhook event by uuid — includes the full payload, the
    * embedded endpoint snapshot, and the most recent response status/body.
    *
    * @example
-   * const event = await garu.webhookEvents.get(42);
-   * if (event.status === 'failed') {
-   *   console.log(event.responseStatus, event.responseBody);
-   * }
+   * const event = await garu.webhookEvents.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
+   * event.status === 'failed' && event.responseStatus;
    */
-  async get(id) {
+  async get(uuid) {
     return this.http.call(
-      (signal) => this.http.client.GET(`/api/webhook-events/${id}`, { signal }).then(
+      (signal) => this.http.client.GET(`/api/v1/webhook-events/${uuid}`, { signal }).then(
         (r) => r
       )
     );
@@ -1328,28 +1324,28 @@ var WebhookEvents = class {
    * explicitly want the legacy in-place semantics (and for backwards
    * compatibility with older CLI / MCP releases).
    *
-   * Re-deliver a webhook event by ID. Resets it to `pending`, clears the
+   * Re-deliver a webhook event by uuid. Resets it to `pending`, clears the
    * retry schedule, and triggers an immediate delivery attempt. Works on
    * any status (`success`, `failed`, `pending`).
    *
    * @example
    * const failed = await garu.webhookEvents.list({ status: 'failed', limit: 5 });
    * for (const event of failed.data) {
-   *   await garu.webhookEvents.retry(event.id);
+   *   await garu.webhookEvents.retry(event.uuid);
    * }
    */
-  async retry(id) {
+  async retry(uuid) {
     return this.http.call(
-      (signal) => this.http.client.POST(`/api/webhook-events/${id}/retry`, {
+      (signal) => this.http.client.POST(`/api/v1/webhook-events/${uuid}/retry`, {
         body: {},
         signal
       }).then((r) => r)
     );
   }
   /**
-   * Re-deliver a webhook event by ID, audit-trail preserving. Unlike
+   * Re-deliver a webhook event by uuid, audit-trail preserving. Unlike
    * {@link retry}, this does *not* mutate the original row — it inserts a
-   * fresh event (new numeric id) that points back at the source via
+   * fresh event (new uuid) that points back at the source via
    * `manualResendOf`, then dispatches that clone. The original row is
    * untouched, so the historical record of the prior failure (and its
    * response status / body) is preserved.
@@ -1360,30 +1356,30 @@ var WebhookEvents = class {
    * delivery's outcome to remain on the record.
    *
    * **Outbound delivery semantics**: the gateway POSTs the clone with
-   * `Idempotency-Key: resend_<originalId>` (where `<originalId>` is the id
-   * of the source event, not the clone). Recipient handlers that key off
+   * `Idempotency-Key: resend_<cloneUuid>`. Recipient handlers that key off
    * `Idempotency-Key` will see this as a distinct delivery from the
    * original — distinguishable both by the `resend_` prefix and by reading
    * the response payload's `manualResendOf` field.
    *
-   * **SDK→gateway dedup**: the SDK auto-attaches `X-Idempotency-Key`
-   * (UUIDv4 unless you pass `idempotencyKey`) so transient transport
-   * retries (5xx → SDK backoff) cannot create duplicate clones — the
-   * backend returns the original clone on the second call within 24h.
+   * 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.
    *
-   * Returns the *clone* event (new id), not the original. The original is
+   * Returns the *clone* event (new uuid), not the original. The original is
    * unchanged on the server.
    *
    * @example
-   * const event = await garu.webhookEvents.get(42);
-   * const clone = await garu.webhookEvents.resend(42);
-   * clone.id !== event.id;            // true — clone has its own id
-   * clone.manualResendOf === event.id; // true — points back at the source
+   * const event = await garu.webhookEvents.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
+   * const clone = await garu.webhookEvents.resend(event.uuid);
+   * clone.uuid !== event.uuid;            // true — clone has its own uuid
+   * clone.manualResendOf === event.uuid; // true — points back at the source
    */
-  async resend(id, params = {}) {
+  async resend(uuid, params = {}) {
     const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
     return this.http.call(
-      (signal) => this.http.client.POST(`/api/webhook-events/${id}/resend`, {
+      (signal) => this.http.client.POST(`/api/v1/webhook-events/${uuid}/resend`, {
         body: {},
         headers: { "X-Idempotency-Key": idempotencyKey },
         signal

package/package.json

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