@garuhq/node 2.0.0 → 3.0.0

package/CHANGELOG.md

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

package/README.md

@@ -397,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

@@ -1293,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
       )
     );
@@ -1341,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.
@@ -1373,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

@@ -770,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`. */
@@ -791,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;
@@ -1754,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
@@ -1762,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;
@@ -1784,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()`
@@ -1802,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.
@@ -1827,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 {

package/dist/index.d.ts

@@ -770,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`. */
@@ -791,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;
@@ -1754,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
@@ -1762,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;
@@ -1784,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()`
@@ -1802,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.
@@ -1827,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 {

package/dist/index.js

@@ -1287,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
       )
     );
@@ -1335,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.
@@ -1367,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": "2.0.0",
+  "version": "3.0.0",
   "description": "Official Node.js / TypeScript SDK for the Garu payment gateway.",
   "license": "MIT",
   "homepage": "https://garu.com.br",