@garuhq/node 0.8.0 → 0.11.0

package/CHANGELOG.md

@@ -3,6 +3,40 @@
 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/).
 
+## [0.11.0] — 2026-05-19
+
+### Added
+
+- `webhookEvents` resource on the `Garu` client — the seller-facing
+  delivery log for outbound webhooks. Use it to audit deliveries from
+  the seller's API key, the canonical "did my customer's endpoint
+  actually receive event X?" workflow.
+  - `webhookEvents.list({ status?, eventType?, endpointId?, page?, limit? })`
+    — `GET /api/webhook-events`. Filter by delivery state
+    (`pending` / `success` / `failed`), Garu event type, or destination
+    endpoint id. Newest first.
+  - `webhookEvents.get(id)` — `GET /api/webhook-events/{id}`. Returns
+    the full payload, the embedded endpoint snapshot, and the most
+    recent response status/body.
+  - `webhookEvents.retry(id)` — `POST /api/webhook-events/{id}/retry`.
+    Resets the event to `pending`, clears the retry schedule, and
+    triggers an immediate delivery attempt. Works on any status
+    (`success` / `failed` / `pending`) — use this when a customer
+    reports a missed or unprocessed event.
+- Types exported from the package root: `WebhookEvent`,
+  `WebhookEventEndpoint`, `WebhookEventList`, `WebhookEventStatus`,
+  `ListWebhookEventsParams`.
+
+### Fixed
+
+- `webhookEvents.list` now normalizes the legacy backend response
+  (`{ events, total, page, limit, pages }`) into the standard
+  `{ data, meta: { page, limit, total, totalPages } }` paginated shape
+  used by every other SDK resource. Previously the cast-only
+  implementation returned `result.data === undefined` against the real
+  backend; tests had been mocking the post-normalization shape and
+  hid the bug.
+
 ## [0.5.0] — 2026-05-01
 
 ### Added

package/README.md

@@ -167,7 +167,9 @@ const { data, meta } = await garu.customers.list({ search: 'maria', limit: 10 })
 
 ## Products
 
-Discover products and customize the per-product portal experience (B2B2C, v0.8.0).
+Discover products and customize the per-product portal experience (B2B2C).
+
+`portalConfig.*` methods accept `productId` as either the product UUID (preferred — same identifier returned by `list()` and webhook payloads) or the legacy numeric id (Garu v0.10.0+).
 
 | Method                              | Description                                                       |
 | ----------------------------------- | ----------------------------------------------------------------- |
@@ -180,14 +182,16 @@ Discover products and customize the per-product portal experience (B2B2C, v0.8.0
 
 ```ts
 // SaaS de coaching: per-coach branding under one Seller account
-await garu.products.portalConfig.set(57, {
+await garu.products.portalConfig.set('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f', {
   businessName: 'Coach Maria — Corrida & Trilha',
   primaryColor: '#257264',
   logoUrl: 'https://cdn.exemplo.com/coaches/maria.png',
 });
 
 // Pass `null` on a field to inherit from the seller-level config
-await garu.products.portalConfig.patch(57, { primaryColor: null });
+await garu.products.portalConfig.patch('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f', {
+  primaryColor: null,
+});
 ```
 
 ## Scheduled charges

package/dist/index.cjs

@@ -475,11 +475,11 @@ var ProductPortalConfigResource = class {
    * portal config).
    *
    * @example
-   * const cfg = await garu.products.portalConfig.get(57);
+   * const cfg = await garu.products.portalConfig.get('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f');
    */
   async get(productId) {
     return this.http.call(
-      (signal) => this.http.client.GET(`/api/products/${productId}/portal-config`, {
+      (signal) => this.http.client.GET(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
         signal
       }).then((r) => r)
     );
@@ -491,7 +491,7 @@ var ProductPortalConfigResource = class {
    * value. Use `clear` to reset everything.
    *
    * @example
-   * await garu.products.portalConfig.set(57, {
+   * await garu.products.portalConfig.set('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f', {
    *   businessName: 'Coach Maria — Corrida & Trilha',
    *   primaryColor: '#257264',
    *   logoUrl: 'https://cdn.atletia.com.br/coaches/maria.png'
@@ -499,7 +499,7 @@ var ProductPortalConfigResource = class {
    */
   async set(productId, params) {
     return this.http.call(
-      (signal) => this.http.client.POST(`/api/products/${productId}/portal-config`, {
+      (signal) => this.http.client.POST(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
         body: params,
         signal
       }).then((r) => r)
@@ -508,7 +508,7 @@ var ProductPortalConfigResource = class {
   /** Same merge semantics as `set` — alias for HTTP-PATCH-prefering callers. */
   async patch(productId, params) {
     return this.http.call(
-      (signal) => this.http.client.PATCH(`/api/products/${productId}/portal-config`, {
+      (signal) => this.http.client.PATCH(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
         body: params,
         signal
       }).then((r) => r)
@@ -520,11 +520,11 @@ var ProductPortalConfigResource = class {
    * deleted, `{ removed: false }` when there was nothing to remove.
    *
    * @example
-   * await garu.products.portalConfig.clear(57);
+   * await garu.products.portalConfig.clear('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f');
    */
   async clear(productId) {
     return this.http.call(
-      (signal) => this.http.client.DELETE(`/api/products/${productId}/portal-config`, {
+      (signal) => this.http.client.DELETE(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
         signal
       }).then((r) => r)
     );
@@ -829,6 +829,90 @@ var ScheduledCharges = class {
     );
   }
 };
+
+// src/resources/webhook-events.ts
+var WebhookEvents = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * List webhook events for the authenticated seller, newest first.
+   * Filter by delivery `status`, by Garu `eventType`, and/or by the
+   * destination `endpointId`.
+   *
+   * @example
+   * // Surface anything that didn't make it through
+   * const failed = await garu.webhookEvents.list({ status: 'failed', limit: 50 });
+   *
+   * @example
+   * // Inspect every paid-charge delivery for a specific endpoint
+   * const paidDeliveries = await garu.webhookEvents.list({
+   *   endpointId: 17,
+   *   eventType: 'transaction.payment.paid'
+   * });
+   */
+  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(
+      (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
+   * 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);
+   * }
+   */
+  async get(id) {
+    return this.http.call(
+      (signal) => this.http.client.GET(`/api/webhook-events/${id}`, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+  /**
+   * Re-deliver a webhook event by ID. Resets it to `pending`, clears the
+   * retry schedule, and triggers an immediate delivery attempt. Works on
+   * any status (`success`, `failed`, `pending`) — use this when a
+   * customer reports a missed or unprocessed event.
+   *
+   * @example
+   * const failed = await garu.webhookEvents.list({ status: 'failed', limit: 5 });
+   * for (const event of failed.data) {
+   *   await garu.webhookEvents.retry(event.id);
+   * }
+   */
+  async retry(id) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/webhook-events/${id}/retry`, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+};
 var webhooks = {
   verify(params) {
     const { signature, secret, payload } = params;
@@ -888,13 +972,14 @@ function parseSignatureHeader(header) {
 var DEFAULT_BASE_URL = "https://garu.com.br";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.11.0";
 var Garu = class {
   charges;
   customers;
   meta;
   products;
   scheduledCharges;
+  webhookEvents;
   /**
    * Webhook helpers. Available both as an instance member and as a static —
    * `Garu.webhooks.verify(...)` works without constructing a client.
@@ -915,6 +1000,7 @@ var Garu = class {
     this.meta = new Meta(http);
     this.products = new Products(http);
     this.scheduledCharges = new ScheduledCharges(http);
+    this.webhookEvents = new WebhookEvents(http);
   }
 };
 

package/dist/index.d.cts

@@ -555,6 +555,61 @@ interface PaymentMethodExpiredPayload {
     cardBrand: string;
     expiresAt: string;
 }
+/**
+ * Delivery state of an outbound webhook event.
+ *
+ * - `pending` — queued or scheduled for a future retry (e.g. exponential backoff).
+ * - `success` — endpoint returned 2xx.
+ * - `failed`  — endpoint exhausted retries or returned a non-2xx the gateway
+ *   refuses to retry. Trigger a manual retry with `webhookEvents.retry(id)`.
+ */
+type WebhookEventStatus = 'pending' | 'success' | 'failed';
+/**
+ * Minimal endpoint info embedded on every event row, so dashboards can
+ * render destination URL + description without a second lookup.
+ */
+interface WebhookEventEndpoint {
+    id: number;
+    url: string;
+    description: string | null;
+    enabled: boolean;
+    events: string[];
+    [key: string]: unknown;
+}
+interface WebhookEvent {
+    id: number;
+    endpointId: number;
+    /** Eager-loaded endpoint snapshot. */
+    webhookEndpoint: WebhookEventEndpoint;
+    /** Garu event type, e.g. `transaction.payment.paid`. */
+    eventType: string;
+    /** Full JSON payload the gateway POSTed (or will POST) to `webhookEndpoint.url`. */
+    payload: Record<string, unknown>;
+    status: WebhookEventStatus;
+    /** Number of delivery attempts so far. */
+    attempts: number;
+    /** ISO-8601. Null if no attempt has fired yet. */
+    lastAttemptAt: string | null;
+    /** ISO-8601. Null when terminal (`success`/`failed`) or not scheduled yet. */
+    nextRetryAt: string | null;
+    /** HTTP status returned by the endpoint on the most recent attempt. */
+    responseStatus: number | null;
+    /** Response body from the most recent attempt, truncated by the gateway. */
+    responseBody: string | null;
+    createdAt: string;
+    [key: string]: unknown;
+}
+type WebhookEventList = PaginatedList<WebhookEvent>;
+interface ListWebhookEventsParams {
+    page?: number;
+    limit?: number;
+    /** Filter by delivery state. */
+    status?: WebhookEventStatus;
+    /** Filter by Garu event type, e.g. `transaction.payment.paid`. */
+    eventType?: string;
+    /** Filter by the destination endpoint that should receive (or received) the event. */
+    endpointId?: number;
+}
 /**
  * Per-product portal customization (Atletia coach-as-product modeling and
  * any other B2B2C platform). `null` fields inherit from the seller-level
@@ -776,9 +831,13 @@ declare class Meta {
 }
 
 /**
- * Per-product portal customization (Garu v0.8.0). Used by B2B2C platforms
- * that model their professionals/coaches as Products under a single seller
- * and want per-product branding on the customer payment + portal pages.
+ * Per-product portal customization. Used by B2B2C platforms that model
+ * their professionals/coaches as Products under a single seller and want
+ * per-product branding on the customer payment + portal pages.
+ *
+ * `productId` accepts either the product UUID (preferred — same identifier
+ * returned by `garu.products.list()` and webhook payloads) or the legacy
+ * numeric id. UUID support added in Garu v0.10.0.
  */
 declare class ProductPortalConfigResource {
     private readonly http;
@@ -789,9 +848,9 @@ declare class ProductPortalConfigResource {
      * portal config).
      *
      * @example
-     * const cfg = await garu.products.portalConfig.get(57);
+     * const cfg = await garu.products.portalConfig.get('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f');
      */
-    get(productId: number): Promise<ProductPortalConfig | null>;
+    get(productId: string | number): Promise<ProductPortalConfig | null>;
     /**
      * Create or merge the portal customization (idempotent upsert). Both
      * `set` and `patch` have the same merge semantics — only fields present
@@ -799,24 +858,24 @@ declare class ProductPortalConfigResource {
      * value. Use `clear` to reset everything.
      *
      * @example
-     * await garu.products.portalConfig.set(57, {
+     * await garu.products.portalConfig.set('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f', {
      *   businessName: 'Coach Maria — Corrida & Trilha',
      *   primaryColor: '#257264',
      *   logoUrl: 'https://cdn.atletia.com.br/coaches/maria.png'
      * });
      */
-    set(productId: number, params: SetProductPortalConfigParams): Promise<ProductPortalConfig>;
+    set(productId: string | number, params: SetProductPortalConfigParams): Promise<ProductPortalConfig>;
     /** Same merge semantics as `set` — alias for HTTP-PATCH-prefering callers. */
-    patch(productId: number, params: SetProductPortalConfigParams): Promise<ProductPortalConfig>;
+    patch(productId: string | number, params: SetProductPortalConfigParams): Promise<ProductPortalConfig>;
     /**
      * Remove the per-product config. The product falls back to the
      * seller-level portal config. Returns `{ removed: true }` when a row was
      * deleted, `{ removed: false }` when there was nothing to remove.
      *
      * @example
-     * await garu.products.portalConfig.clear(57);
+     * await garu.products.portalConfig.clear('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f');
      */
-    clear(productId: number): Promise<{
+    clear(productId: string | number): Promise<{
         removed: boolean;
     }>;
 }
@@ -1014,6 +1073,64 @@ declare class ScheduledCharges {
     listAttempts(id: string, params?: ListScheduledChargeAttemptsParams): Promise<ScheduledChargeAttemptList>;
 }
 
+/**
+ * Webhook events — the seller-facing delivery log for outbound webhooks.
+ *
+ * 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
+ * canonical "did my customer's endpoint actually receive event X?" workflow.
+ *
+ * Webhook endpoint *configuration* (URL, subscribed events, secret) is still
+ * dashboard-only — this resource only covers the event log + manual retries.
+ */
+declare class WebhookEvents {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List webhook events for the authenticated seller, newest first.
+     * Filter by delivery `status`, by Garu `eventType`, and/or by the
+     * destination `endpointId`.
+     *
+     * @example
+     * // Surface anything that didn't make it through
+     * const failed = await garu.webhookEvents.list({ status: 'failed', limit: 50 });
+     *
+     * @example
+     * // Inspect every paid-charge delivery for a specific endpoint
+     * const paidDeliveries = await garu.webhookEvents.list({
+     *   endpointId: 17,
+     *   eventType: 'transaction.payment.paid'
+     * });
+     */
+    list(params?: ListWebhookEventsParams): Promise<WebhookEventList>;
+    /**
+     * Fetch one webhook event by numeric ID — 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);
+     * }
+     */
+    get(id: number): Promise<WebhookEvent>;
+    /**
+     * Re-deliver a webhook event by ID. Resets it to `pending`, clears the
+     * retry schedule, and triggers an immediate delivery attempt. Works on
+     * any status (`success`, `failed`, `pending`) — use this when a
+     * customer reports a missed or unprocessed event.
+     *
+     * @example
+     * const failed = await garu.webhookEvents.list({ status: 'failed', limit: 5 });
+     * for (const event of failed.data) {
+     *   await garu.webhookEvents.retry(event.id);
+     * }
+     */
+    retry(id: number): Promise<WebhookEvent>;
+}
+
 interface GaruOptions {
     /**
      * Your Garu API key. `sk_live_…` for production, `sk_test_…` for test mode.
@@ -1054,6 +1171,7 @@ declare class Garu {
     readonly meta: Meta;
     readonly products: Products;
     readonly scheduledCharges: ScheduledCharges;
+    readonly webhookEvents: WebhookEvents;
     /**
      * Webhook helpers. Available both as an instance member and as a static —
      * `Garu.webhooks.verify(...)` works without constructing a client.
@@ -1112,4 +1230,4 @@ declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CancelAtPeriodEndScheduledChargeParams, type CancelRecurrenceScheduledChargeParams, type CardInfo, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, 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 ListChargesParams, type ListCustomersParams, type ListProductsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, 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 VerifiedWebhook, type VerifyWebhookParams, type WirePaymentMethodId, webhooks };
+export { type CancelAtPeriodEndScheduledChargeParams, type CancelRecurrenceScheduledChargeParams, type CardInfo, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, 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 ListChargesParams, type ListCustomersParams, type ListProductsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, 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 VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, type WirePaymentMethodId, webhooks };

package/dist/index.d.ts

@@ -555,6 +555,61 @@ interface PaymentMethodExpiredPayload {
     cardBrand: string;
     expiresAt: string;
 }
+/**
+ * Delivery state of an outbound webhook event.
+ *
+ * - `pending` — queued or scheduled for a future retry (e.g. exponential backoff).
+ * - `success` — endpoint returned 2xx.
+ * - `failed`  — endpoint exhausted retries or returned a non-2xx the gateway
+ *   refuses to retry. Trigger a manual retry with `webhookEvents.retry(id)`.
+ */
+type WebhookEventStatus = 'pending' | 'success' | 'failed';
+/**
+ * Minimal endpoint info embedded on every event row, so dashboards can
+ * render destination URL + description without a second lookup.
+ */
+interface WebhookEventEndpoint {
+    id: number;
+    url: string;
+    description: string | null;
+    enabled: boolean;
+    events: string[];
+    [key: string]: unknown;
+}
+interface WebhookEvent {
+    id: number;
+    endpointId: number;
+    /** Eager-loaded endpoint snapshot. */
+    webhookEndpoint: WebhookEventEndpoint;
+    /** Garu event type, e.g. `transaction.payment.paid`. */
+    eventType: string;
+    /** Full JSON payload the gateway POSTed (or will POST) to `webhookEndpoint.url`. */
+    payload: Record<string, unknown>;
+    status: WebhookEventStatus;
+    /** Number of delivery attempts so far. */
+    attempts: number;
+    /** ISO-8601. Null if no attempt has fired yet. */
+    lastAttemptAt: string | null;
+    /** ISO-8601. Null when terminal (`success`/`failed`) or not scheduled yet. */
+    nextRetryAt: string | null;
+    /** HTTP status returned by the endpoint on the most recent attempt. */
+    responseStatus: number | null;
+    /** Response body from the most recent attempt, truncated by the gateway. */
+    responseBody: string | null;
+    createdAt: string;
+    [key: string]: unknown;
+}
+type WebhookEventList = PaginatedList<WebhookEvent>;
+interface ListWebhookEventsParams {
+    page?: number;
+    limit?: number;
+    /** Filter by delivery state. */
+    status?: WebhookEventStatus;
+    /** Filter by Garu event type, e.g. `transaction.payment.paid`. */
+    eventType?: string;
+    /** Filter by the destination endpoint that should receive (or received) the event. */
+    endpointId?: number;
+}
 /**
  * Per-product portal customization (Atletia coach-as-product modeling and
  * any other B2B2C platform). `null` fields inherit from the seller-level
@@ -776,9 +831,13 @@ declare class Meta {
 }
 
 /**
- * Per-product portal customization (Garu v0.8.0). Used by B2B2C platforms
- * that model their professionals/coaches as Products under a single seller
- * and want per-product branding on the customer payment + portal pages.
+ * Per-product portal customization. Used by B2B2C platforms that model
+ * their professionals/coaches as Products under a single seller and want
+ * per-product branding on the customer payment + portal pages.
+ *
+ * `productId` accepts either the product UUID (preferred — same identifier
+ * returned by `garu.products.list()` and webhook payloads) or the legacy
+ * numeric id. UUID support added in Garu v0.10.0.
  */
 declare class ProductPortalConfigResource {
     private readonly http;
@@ -789,9 +848,9 @@ declare class ProductPortalConfigResource {
      * portal config).
      *
      * @example
-     * const cfg = await garu.products.portalConfig.get(57);
+     * const cfg = await garu.products.portalConfig.get('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f');
      */
-    get(productId: number): Promise<ProductPortalConfig | null>;
+    get(productId: string | number): Promise<ProductPortalConfig | null>;
     /**
      * Create or merge the portal customization (idempotent upsert). Both
      * `set` and `patch` have the same merge semantics — only fields present
@@ -799,24 +858,24 @@ declare class ProductPortalConfigResource {
      * value. Use `clear` to reset everything.
      *
      * @example
-     * await garu.products.portalConfig.set(57, {
+     * await garu.products.portalConfig.set('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f', {
      *   businessName: 'Coach Maria — Corrida & Trilha',
      *   primaryColor: '#257264',
      *   logoUrl: 'https://cdn.atletia.com.br/coaches/maria.png'
      * });
      */
-    set(productId: number, params: SetProductPortalConfigParams): Promise<ProductPortalConfig>;
+    set(productId: string | number, params: SetProductPortalConfigParams): Promise<ProductPortalConfig>;
     /** Same merge semantics as `set` — alias for HTTP-PATCH-prefering callers. */
-    patch(productId: number, params: SetProductPortalConfigParams): Promise<ProductPortalConfig>;
+    patch(productId: string | number, params: SetProductPortalConfigParams): Promise<ProductPortalConfig>;
     /**
      * Remove the per-product config. The product falls back to the
      * seller-level portal config. Returns `{ removed: true }` when a row was
      * deleted, `{ removed: false }` when there was nothing to remove.
      *
      * @example
-     * await garu.products.portalConfig.clear(57);
+     * await garu.products.portalConfig.clear('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f');
      */
-    clear(productId: number): Promise<{
+    clear(productId: string | number): Promise<{
         removed: boolean;
     }>;
 }
@@ -1014,6 +1073,64 @@ declare class ScheduledCharges {
     listAttempts(id: string, params?: ListScheduledChargeAttemptsParams): Promise<ScheduledChargeAttemptList>;
 }
 
+/**
+ * Webhook events — the seller-facing delivery log for outbound webhooks.
+ *
+ * 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
+ * canonical "did my customer's endpoint actually receive event X?" workflow.
+ *
+ * Webhook endpoint *configuration* (URL, subscribed events, secret) is still
+ * dashboard-only — this resource only covers the event log + manual retries.
+ */
+declare class WebhookEvents {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List webhook events for the authenticated seller, newest first.
+     * Filter by delivery `status`, by Garu `eventType`, and/or by the
+     * destination `endpointId`.
+     *
+     * @example
+     * // Surface anything that didn't make it through
+     * const failed = await garu.webhookEvents.list({ status: 'failed', limit: 50 });
+     *
+     * @example
+     * // Inspect every paid-charge delivery for a specific endpoint
+     * const paidDeliveries = await garu.webhookEvents.list({
+     *   endpointId: 17,
+     *   eventType: 'transaction.payment.paid'
+     * });
+     */
+    list(params?: ListWebhookEventsParams): Promise<WebhookEventList>;
+    /**
+     * Fetch one webhook event by numeric ID — 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);
+     * }
+     */
+    get(id: number): Promise<WebhookEvent>;
+    /**
+     * Re-deliver a webhook event by ID. Resets it to `pending`, clears the
+     * retry schedule, and triggers an immediate delivery attempt. Works on
+     * any status (`success`, `failed`, `pending`) — use this when a
+     * customer reports a missed or unprocessed event.
+     *
+     * @example
+     * const failed = await garu.webhookEvents.list({ status: 'failed', limit: 5 });
+     * for (const event of failed.data) {
+     *   await garu.webhookEvents.retry(event.id);
+     * }
+     */
+    retry(id: number): Promise<WebhookEvent>;
+}
+
 interface GaruOptions {
     /**
      * Your Garu API key. `sk_live_…` for production, `sk_test_…` for test mode.
@@ -1054,6 +1171,7 @@ declare class Garu {
     readonly meta: Meta;
     readonly products: Products;
     readonly scheduledCharges: ScheduledCharges;
+    readonly webhookEvents: WebhookEvents;
     /**
      * Webhook helpers. Available both as an instance member and as a static —
      * `Garu.webhooks.verify(...)` works without constructing a client.
@@ -1112,4 +1230,4 @@ declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CancelAtPeriodEndScheduledChargeParams, type CancelRecurrenceScheduledChargeParams, type CardInfo, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, 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 ListChargesParams, type ListCustomersParams, type ListProductsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, 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 VerifiedWebhook, type VerifyWebhookParams, type WirePaymentMethodId, webhooks };
+export { type CancelAtPeriodEndScheduledChargeParams, type CancelRecurrenceScheduledChargeParams, type CardInfo, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, 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 ListChargesParams, type ListCustomersParams, type ListProductsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, 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 VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, type WirePaymentMethodId, webhooks };

package/dist/index.js

@@ -469,11 +469,11 @@ var ProductPortalConfigResource = class {
    * portal config).
    *
    * @example
-   * const cfg = await garu.products.portalConfig.get(57);
+   * const cfg = await garu.products.portalConfig.get('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f');
    */
   async get(productId) {
     return this.http.call(
-      (signal) => this.http.client.GET(`/api/products/${productId}/portal-config`, {
+      (signal) => this.http.client.GET(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
         signal
       }).then((r) => r)
     );
@@ -485,7 +485,7 @@ var ProductPortalConfigResource = class {
    * value. Use `clear` to reset everything.
    *
    * @example
-   * await garu.products.portalConfig.set(57, {
+   * await garu.products.portalConfig.set('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f', {
    *   businessName: 'Coach Maria — Corrida & Trilha',
    *   primaryColor: '#257264',
    *   logoUrl: 'https://cdn.atletia.com.br/coaches/maria.png'
@@ -493,7 +493,7 @@ var ProductPortalConfigResource = class {
    */
   async set(productId, params) {
     return this.http.call(
-      (signal) => this.http.client.POST(`/api/products/${productId}/portal-config`, {
+      (signal) => this.http.client.POST(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
         body: params,
         signal
       }).then((r) => r)
@@ -502,7 +502,7 @@ var ProductPortalConfigResource = class {
   /** Same merge semantics as `set` — alias for HTTP-PATCH-prefering callers. */
   async patch(productId, params) {
     return this.http.call(
-      (signal) => this.http.client.PATCH(`/api/products/${productId}/portal-config`, {
+      (signal) => this.http.client.PATCH(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
         body: params,
         signal
       }).then((r) => r)
@@ -514,11 +514,11 @@ var ProductPortalConfigResource = class {
    * deleted, `{ removed: false }` when there was nothing to remove.
    *
    * @example
-   * await garu.products.portalConfig.clear(57);
+   * await garu.products.portalConfig.clear('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f');
    */
   async clear(productId) {
     return this.http.call(
-      (signal) => this.http.client.DELETE(`/api/products/${productId}/portal-config`, {
+      (signal) => this.http.client.DELETE(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
         signal
       }).then((r) => r)
     );
@@ -823,6 +823,90 @@ var ScheduledCharges = class {
     );
   }
 };
+
+// src/resources/webhook-events.ts
+var WebhookEvents = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * List webhook events for the authenticated seller, newest first.
+   * Filter by delivery `status`, by Garu `eventType`, and/or by the
+   * destination `endpointId`.
+   *
+   * @example
+   * // Surface anything that didn't make it through
+   * const failed = await garu.webhookEvents.list({ status: 'failed', limit: 50 });
+   *
+   * @example
+   * // Inspect every paid-charge delivery for a specific endpoint
+   * const paidDeliveries = await garu.webhookEvents.list({
+   *   endpointId: 17,
+   *   eventType: 'transaction.payment.paid'
+   * });
+   */
+  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(
+      (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
+   * 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);
+   * }
+   */
+  async get(id) {
+    return this.http.call(
+      (signal) => this.http.client.GET(`/api/webhook-events/${id}`, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+  /**
+   * Re-deliver a webhook event by ID. Resets it to `pending`, clears the
+   * retry schedule, and triggers an immediate delivery attempt. Works on
+   * any status (`success`, `failed`, `pending`) — use this when a
+   * customer reports a missed or unprocessed event.
+   *
+   * @example
+   * const failed = await garu.webhookEvents.list({ status: 'failed', limit: 5 });
+   * for (const event of failed.data) {
+   *   await garu.webhookEvents.retry(event.id);
+   * }
+   */
+  async retry(id) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/webhook-events/${id}/retry`, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+};
 var webhooks = {
   verify(params) {
     const { signature, secret, payload } = params;
@@ -882,13 +966,14 @@ function parseSignatureHeader(header) {
 var DEFAULT_BASE_URL = "https://garu.com.br";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.11.0";
 var Garu = class {
   charges;
   customers;
   meta;
   products;
   scheduledCharges;
+  webhookEvents;
   /**
    * Webhook helpers. Available both as an instance member and as a static —
    * `Garu.webhooks.verify(...)` works without constructing a client.
@@ -909,6 +994,7 @@ var Garu = class {
     this.meta = new Meta(http);
     this.products = new Products(http);
     this.scheduledCharges = new ScheduledCharges(http);
+    this.webhookEvents = new WebhookEvents(http);
   }
 };
 

package/package.json

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