@garuhq/node 0.7.0 → 0.10.0

package/README.md

@@ -165,6 +165,94 @@ const customer = await garu.customers.create({
 const { data, meta } = await garu.customers.list({ search: 'maria', limit: 10 });
 ```
 
+## Products
+
+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                                                       |
+| ----------------------------------- | ----------------------------------------------------------------- |
+| `list(params?)`                     | Paginated list of products for the seller.                        |
+| `get(uuid)`                         | Fetch a single product by UUID — same id used by charges.         |
+| `portalConfig.get(productId)`       | Read per-product portal customization. Returns `null` if unset.   |
+| `portalConfig.set(productId, p)`    | Upsert with merge — only fields present are written.              |
+| `portalConfig.patch(productId, p)`  | Same merge semantics as `set` — alias for HTTP-PATCH callers.     |
+| `portalConfig.clear(productId)`     | Remove the customization; product falls back to seller config.    |
+
+```ts
+// SaaS de coaching: per-coach branding under one Seller account
+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('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f', {
+  primaryColor: null,
+});
+```
+
+## Scheduled charges
+
+Bill an existing customer on a future date — one-time or recurring with card tokenization. The Garu drives email reminders, dunning, retries, and the lifecycle state machine.
+
+| Method                                        | Description                                                                |
+| --------------------------------------------- | -------------------------------------------------------------------------- |
+| `create(params)`                              | Create one-time or recurring schedule. Auto-attaches `X-Idempotency-Key`.  |
+| `list(params?)`                               | Paginated list with status / type / dueFrom / dueTo / customerId filters.  |
+| `get(id)`                                     | Detail bundle: charge + event timeline + linked transactions.              |
+| `markPaid(id, params)`                        | Mark cycle paid (off-Garu reconciliation).                                 |
+| `postpone(id, params)`                        | Move the next cycle's due date forward.                                    |
+| `pause(id, params?)` / `resume(id)`           | Suspend / re-enable a series.                                              |
+| `cancelRecurrence(id, params?)`               | Hard-stop future cycles (recurring only).                                  |
+| `cancelAtPeriodEnd(id, { enabled })`          | Stripe-style soft-cancel; reversible.                                      |
+| `changePaymentMethod(id, params)`             | Swap the saved card.                                                       |
+| `clearPaymentMethod(id)`                      | Remove the saved card; future cycles email-with-link.                      |
+| `listAttempts(id, params?)`                   | Per-attempt billing log — every silent-charge / retry / mark-paid (v0.8.2).|
+
+```ts
+// Recurring with 7-day trial
+const series = await garu.scheduledCharges.create({
+  customerId: 42,
+  productId: 17,
+  amount: 49.9,
+  type: 'recurring',
+  dueDate: '2026-06-01',
+  methods: ['card', 'pix'],
+  recurrence: { interval: 'monthly' },
+  trialDays: 7,
+});
+
+// Audit why cycle 3 failed (v0.8.2)
+const { data } = await garu.scheduledCharges.listAttempts(series.id, {
+  cycleNumber: 3,
+});
+const declines = data.filter((a) => a.status === 'declined');
+// → each declines[i].failureCode is one of GaruFailureCode (insufficient_funds,
+//   card_expired, card_declined, ...)
+```
+
+## Failure codes (v0.8.0)
+
+Every `transaction.payment.failed`, `scheduled_charge.cycle_failed`, and `listAttempts()` row carries:
+
+- `failureCode` — canonical `GaruFailureCode` enum (10 values, gateway-independent)
+- `failureReason` — human-readable PT-BR
+- `gatewayFailureCode` — raw code from Celcoin (ABECS for forensics)
+
+```ts
+import type { GaruFailureCode } from '@garuhq/node';
+
+const PERMANENT: GaruFailureCode[] = ['card_expired', 'card_canceled', 'fraud_suspected'];
+function shouldAskForNewCard(code: GaruFailureCode): boolean {
+  return PERMANENT.includes(code);
+}
+```
+
+Full table at [docs.garu.com.br/api-reference/webhooks/codigos-de-falha](https://docs.garu.com.br/api-reference/webhooks/codigos-de-falha).
+
 ## Meta
 
 Discover available payment methods and webhook events. No authentication required.

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)
     );
@@ -802,6 +802,32 @@ var ScheduledCharges = class {
       }).then((r) => r)
     );
   }
+  /**
+   * Per-attempt billing log for the series (SPEC §4.2). One row per
+   * logical billing event — cycle 1 interactive charge, every silent
+   * charge attempt, every retry, every manual mark-paid. Carries the
+   * canonical `failureCode` for declines so you can audit billing
+   * outcomes without cross-referencing Transactions.
+   *
+   * @example
+   * const { data } = await garu.scheduledCharges.listAttempts('sch_abc', {
+   *   cycleNumber: 3
+   * });
+   * const declines = data.filter((a) => a.status === 'declined');
+   */
+  async listAttempts(id, 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.cycleNumber !== void 0) qs.set("cycleNumber", String(params.cycleNumber));
+    const query = qs.toString();
+    const url = `/api/scheduled-charges/${id}/attempts${query ? `?${query}` : ""}`;
+    return this.http.call(
+      (signal) => this.http.client.GET(url, { signal }).then(
+        (r) => r
+      )
+    );
+  }
 };
 var webhooks = {
   verify(params) {

package/dist/index.d.cts

@@ -354,6 +354,33 @@ interface ScheduledChargeDetail {
     transactions: ScheduledChargeLinkedTransaction[];
 }
 type ScheduledChargeList = PaginatedList<ScheduledChargeRecord>;
+/** Source of a billing attempt — see SPEC §3.1. */
+type ScheduledChargeAttemptSource = 'cycle1_interactive' | 'silent_charge' | 'card_retry' | 'manual_mark_paid' | 'fallback_pix';
+type ScheduledChargeAttemptStatus = 'pending' | 'succeeded' | 'declined' | 'canceled' | 'errored';
+interface ScheduledChargeAttempt {
+    id: number;
+    cycleId: string;
+    cycleNumber: number;
+    attemptNumber: number;
+    attemptedAt: string;
+    source: ScheduledChargeAttemptSource;
+    paymentMethod: 'card' | 'pix' | 'boleto' | 'manual';
+    paymentMethodId: number | null;
+    cardLast4: string | null;
+    cardBrand: string | null;
+    status: ScheduledChargeAttemptStatus;
+    failureCode: GaruFailureCode | null;
+    failureReason: string | null;
+    gatewayFailureCode: string | null;
+    gatewayChargeId: number | null;
+    transactionId: number | null;
+}
+type ScheduledChargeAttemptList = PaginatedList<ScheduledChargeAttempt>;
+interface ListScheduledChargeAttemptsParams {
+    page?: number;
+    limit?: number;
+    cycleNumber?: number;
+}
 interface CreateScheduledChargeParams {
     customerId: number;
     /**
@@ -749,9 +776,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;
@@ -762,9 +793,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
@@ -772,24 +803,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;
     }>;
 }
@@ -971,6 +1002,20 @@ declare class ScheduledCharges {
      * await garu.scheduledCharges.clearPaymentMethod('sch_abc123');
      */
     clearPaymentMethod(id: string): Promise<ScheduledChargeRecord>;
+    /**
+     * Per-attempt billing log for the series (SPEC §4.2). One row per
+     * logical billing event — cycle 1 interactive charge, every silent
+     * charge attempt, every retry, every manual mark-paid. Carries the
+     * canonical `failureCode` for declines so you can audit billing
+     * outcomes without cross-referencing Transactions.
+     *
+     * @example
+     * const { data } = await garu.scheduledCharges.listAttempts('sch_abc', {
+     *   cycleNumber: 3
+     * });
+     * const declines = data.filter((a) => a.status === 'declined');
+     */
+    listAttempts(id: string, params?: ListScheduledChargeAttemptsParams): Promise<ScheduledChargeAttemptList>;
 }
 
 interface GaruOptions {
@@ -1071,4 +1116,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 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 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 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 };

package/dist/index.d.ts

@@ -354,6 +354,33 @@ interface ScheduledChargeDetail {
     transactions: ScheduledChargeLinkedTransaction[];
 }
 type ScheduledChargeList = PaginatedList<ScheduledChargeRecord>;
+/** Source of a billing attempt — see SPEC §3.1. */
+type ScheduledChargeAttemptSource = 'cycle1_interactive' | 'silent_charge' | 'card_retry' | 'manual_mark_paid' | 'fallback_pix';
+type ScheduledChargeAttemptStatus = 'pending' | 'succeeded' | 'declined' | 'canceled' | 'errored';
+interface ScheduledChargeAttempt {
+    id: number;
+    cycleId: string;
+    cycleNumber: number;
+    attemptNumber: number;
+    attemptedAt: string;
+    source: ScheduledChargeAttemptSource;
+    paymentMethod: 'card' | 'pix' | 'boleto' | 'manual';
+    paymentMethodId: number | null;
+    cardLast4: string | null;
+    cardBrand: string | null;
+    status: ScheduledChargeAttemptStatus;
+    failureCode: GaruFailureCode | null;
+    failureReason: string | null;
+    gatewayFailureCode: string | null;
+    gatewayChargeId: number | null;
+    transactionId: number | null;
+}
+type ScheduledChargeAttemptList = PaginatedList<ScheduledChargeAttempt>;
+interface ListScheduledChargeAttemptsParams {
+    page?: number;
+    limit?: number;
+    cycleNumber?: number;
+}
 interface CreateScheduledChargeParams {
     customerId: number;
     /**
@@ -749,9 +776,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;
@@ -762,9 +793,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
@@ -772,24 +803,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;
     }>;
 }
@@ -971,6 +1002,20 @@ declare class ScheduledCharges {
      * await garu.scheduledCharges.clearPaymentMethod('sch_abc123');
      */
     clearPaymentMethod(id: string): Promise<ScheduledChargeRecord>;
+    /**
+     * Per-attempt billing log for the series (SPEC §4.2). One row per
+     * logical billing event — cycle 1 interactive charge, every silent
+     * charge attempt, every retry, every manual mark-paid. Carries the
+     * canonical `failureCode` for declines so you can audit billing
+     * outcomes without cross-referencing Transactions.
+     *
+     * @example
+     * const { data } = await garu.scheduledCharges.listAttempts('sch_abc', {
+     *   cycleNumber: 3
+     * });
+     * const declines = data.filter((a) => a.status === 'declined');
+     */
+    listAttempts(id: string, params?: ListScheduledChargeAttemptsParams): Promise<ScheduledChargeAttemptList>;
 }
 
 interface GaruOptions {
@@ -1071,4 +1116,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 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 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 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 };

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)
     );
@@ -796,6 +796,32 @@ var ScheduledCharges = class {
       }).then((r) => r)
     );
   }
+  /**
+   * Per-attempt billing log for the series (SPEC §4.2). One row per
+   * logical billing event — cycle 1 interactive charge, every silent
+   * charge attempt, every retry, every manual mark-paid. Carries the
+   * canonical `failureCode` for declines so you can audit billing
+   * outcomes without cross-referencing Transactions.
+   *
+   * @example
+   * const { data } = await garu.scheduledCharges.listAttempts('sch_abc', {
+   *   cycleNumber: 3
+   * });
+   * const declines = data.filter((a) => a.status === 'declined');
+   */
+  async listAttempts(id, 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.cycleNumber !== void 0) qs.set("cycleNumber", String(params.cycleNumber));
+    const query = qs.toString();
+    const url = `/api/scheduled-charges/${id}/attempts${query ? `?${query}` : ""}`;
+    return this.http.call(
+      (signal) => this.http.client.GET(url, { signal }).then(
+        (r) => r
+      )
+    );
+  }
 };
 var webhooks = {
   verify(params) {

package/package.json

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