@garuhq/node 0.6.0 → 0.8.0

package/README.md

@@ -165,6 +165,90 @@ 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, v0.8.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(57, {
+  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 });
+```
+
+## 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

@@ -464,11 +464,80 @@ var Meta = class {
 };
 
 // src/resources/products.ts
+var ProductPortalConfigResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Get the portal customization for a product. Returns `null` when no
+   * per-product config exists (the product falls back to seller-level
+   * portal config).
+   *
+   * @example
+   * const cfg = await garu.products.portalConfig.get(57);
+   */
+  async get(productId) {
+    return this.http.call(
+      (signal) => this.http.client.GET(`/api/products/${productId}/portal-config`, {
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Create or merge the portal customization (idempotent upsert). Both
+   * `set` and `patch` have the same merge semantics — only fields present
+   * in the body are written, unspecified fields keep their persisted
+   * value. Use `clear` to reset everything.
+   *
+   * @example
+   * await garu.products.portalConfig.set(57, {
+   *   businessName: 'Coach Maria — Corrida & Trilha',
+   *   primaryColor: '#257264',
+   *   logoUrl: 'https://cdn.atletia.com.br/coaches/maria.png'
+   * });
+   */
+  async set(productId, params) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/products/${productId}/portal-config`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /** 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`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * 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);
+   */
+  async clear(productId) {
+    return this.http.call(
+      (signal) => this.http.client.DELETE(`/api/products/${productId}/portal-config`, {
+        signal
+      }).then((r) => r)
+    );
+  }
+};
 var Products = class {
   constructor(http) {
     this.http = http;
+    this.portalConfig = new ProductPortalConfigResource(http);
   }
   http;
+  /** Per-product portal customization (Garu v0.8.0). */
+  portalConfig;
   /**
    * List products for the authenticated seller, with pagination and search.
    *
@@ -733,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;
     /**
@@ -485,6 +512,98 @@ interface MetaResponse {
     dashboard_url: string;
     support_email: string;
 }
+/**
+ * Canonical Garu failure code on `transaction.payment.failed` and
+ * `scheduled_charge.cycle_failed` events. Stable across acquirer changes —
+ * branch on this rather than the raw Celcoin code.
+ */
+type GaruFailureCode = 'insufficient_funds' | 'card_declined' | 'card_expired' | 'card_canceled' | 'processing_error' | 'issuer_unavailable' | 'fraud_suspected' | 'invalid_cvv' | 'do_not_honor_repeated' | 'unknown';
+/**
+ * Shape of the failure trio added to `transaction.payment.failed` and
+ * `scheduled_charge.cycle_failed` payloads. Sellers should always receive
+ * a non-null `failureCode` — `unknown` is the sentinel when the gateway
+ * didn't surface enough detail to map.
+ */
+interface FailurePayload {
+    failureCode: GaruFailureCode;
+    failureReason: string | null;
+    /** Raw acquirer code (Celcoin's ABECS code today). For forensics only. */
+    gatewayFailureCode: string | null;
+}
+/**
+ * `payment_method.expiring_soon` — fires at 30/14/7 days before card
+ * expiry, idempotent per stage. Use to nudge the customer to update
+ * their card before silent-charge starts failing.
+ */
+interface PaymentMethodExpiringPayload {
+    paymentMethodId: number;
+    customerId: number;
+    cardLast4: string;
+    cardBrand: string;
+    expiresAt: string;
+    daysUntilExpiry: 30 | 14 | 7;
+}
+/**
+ * `payment_method.expired` — fires once on the day-of-expiry when the cron
+ * flips `status='expired'`. Future silent charges short-circuit
+ * with `failureCode='card_expired'` instead of hitting the acquirer.
+ */
+interface PaymentMethodExpiredPayload {
+    paymentMethodId: number;
+    customerId: number;
+    cardLast4: string;
+    cardBrand: string;
+    expiresAt: string;
+}
+/**
+ * Per-product portal customization (Atletia coach-as-product modeling and
+ * any other B2B2C platform). `null` fields inherit from the seller-level
+ * portal config.
+ */
+interface ProductPortalConfig {
+    id: number;
+    productId: number;
+    businessName: string | null;
+    logoUrl: string | null;
+    primaryColor: string | null;
+    allowCancelSubscription: boolean | null;
+    allowUpdatePaymentMethod: boolean | null;
+    allowUpdateBillingInfo: boolean | null;
+    allowViewInvoices: boolean | null;
+    allowApplyCoupons: boolean | null;
+    requireCancelReason: boolean | null;
+    cancelAtPeriodEndOnly: boolean | null;
+    sendCancellationEmail: boolean | null;
+    sendPaymentMethodUpdatedEmail: boolean | null;
+    customSuccessMessage: string | null;
+    customCancellationMessage: string | null;
+    customWelcomeText: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Body for `POST` / `PATCH /api/products/:id/portal-config`. Both verbs
+ * are upsert with merge semantics — only fields present are written;
+ * unspecified fields keep their persisted value. Use the `clear`
+ * method (DELETE) to reset everything.
+ */
+interface SetProductPortalConfigParams {
+    businessName?: string | null;
+    logoUrl?: string | null;
+    primaryColor?: string | null;
+    allowCancelSubscription?: boolean | null;
+    allowUpdatePaymentMethod?: boolean | null;
+    allowUpdateBillingInfo?: boolean | null;
+    allowViewInvoices?: boolean | null;
+    allowApplyCoupons?: boolean | null;
+    requireCancelReason?: boolean | null;
+    cancelAtPeriodEndOnly?: boolean | null;
+    sendCancellationEmail?: boolean | null;
+    sendPaymentMethodUpdatedEmail?: boolean | null;
+    customSuccessMessage?: string | null;
+    customCancellationMessage?: string | null;
+    customWelcomeText?: string | null;
+}
 
 /**
  * Charges — the core of the Garu API.
@@ -657,13 +776,61 @@ declare class Meta {
 }
 
 /**
- * Products — discover products available to charge.
+ * 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.
+ */
+declare class ProductPortalConfigResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get the portal customization for a product. Returns `null` when no
+     * per-product config exists (the product falls back to seller-level
+     * portal config).
+     *
+     * @example
+     * const cfg = await garu.products.portalConfig.get(57);
+     */
+    get(productId: number): Promise<ProductPortalConfig | null>;
+    /**
+     * Create or merge the portal customization (idempotent upsert). Both
+     * `set` and `patch` have the same merge semantics — only fields present
+     * in the body are written, unspecified fields keep their persisted
+     * value. Use `clear` to reset everything.
+     *
+     * @example
+     * await garu.products.portalConfig.set(57, {
+     *   businessName: 'Coach Maria — Corrida & Trilha',
+     *   primaryColor: '#257264',
+     *   logoUrl: 'https://cdn.atletia.com.br/coaches/maria.png'
+     * });
+     */
+    set(productId: number, params: SetProductPortalConfigParams): Promise<ProductPortalConfig>;
+    /** Same merge semantics as `set` — alias for HTTP-PATCH-prefering callers. */
+    patch(productId: 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);
+     */
+    clear(productId: number): Promise<{
+        removed: boolean;
+    }>;
+}
+/**
+ * Products — discover products available to charge, and customize the
+ * per-product portal experience (v0.8.0).
  *
  * Products are scoped to the seller identified by the API key. The UUID
  * returned here is the same identifier accepted by `charges.create({ productId })`.
  */
 declare class Products {
     private readonly http;
+    /** Per-product portal customization (Garu v0.8.0). */
+    readonly portalConfig: ProductPortalConfigResource;
     constructor(http: HttpClient);
     /**
      * List products for the authenticated seller, with pagination and search.
@@ -831,6 +998,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 {
@@ -931,4 +1112,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, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, 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 PostponeScheduledChargeParams, type Product, type ProductList, 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 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;
     /**
@@ -485,6 +512,98 @@ interface MetaResponse {
     dashboard_url: string;
     support_email: string;
 }
+/**
+ * Canonical Garu failure code on `transaction.payment.failed` and
+ * `scheduled_charge.cycle_failed` events. Stable across acquirer changes —
+ * branch on this rather than the raw Celcoin code.
+ */
+type GaruFailureCode = 'insufficient_funds' | 'card_declined' | 'card_expired' | 'card_canceled' | 'processing_error' | 'issuer_unavailable' | 'fraud_suspected' | 'invalid_cvv' | 'do_not_honor_repeated' | 'unknown';
+/**
+ * Shape of the failure trio added to `transaction.payment.failed` and
+ * `scheduled_charge.cycle_failed` payloads. Sellers should always receive
+ * a non-null `failureCode` — `unknown` is the sentinel when the gateway
+ * didn't surface enough detail to map.
+ */
+interface FailurePayload {
+    failureCode: GaruFailureCode;
+    failureReason: string | null;
+    /** Raw acquirer code (Celcoin's ABECS code today). For forensics only. */
+    gatewayFailureCode: string | null;
+}
+/**
+ * `payment_method.expiring_soon` — fires at 30/14/7 days before card
+ * expiry, idempotent per stage. Use to nudge the customer to update
+ * their card before silent-charge starts failing.
+ */
+interface PaymentMethodExpiringPayload {
+    paymentMethodId: number;
+    customerId: number;
+    cardLast4: string;
+    cardBrand: string;
+    expiresAt: string;
+    daysUntilExpiry: 30 | 14 | 7;
+}
+/**
+ * `payment_method.expired` — fires once on the day-of-expiry when the cron
+ * flips `status='expired'`. Future silent charges short-circuit
+ * with `failureCode='card_expired'` instead of hitting the acquirer.
+ */
+interface PaymentMethodExpiredPayload {
+    paymentMethodId: number;
+    customerId: number;
+    cardLast4: string;
+    cardBrand: string;
+    expiresAt: string;
+}
+/**
+ * Per-product portal customization (Atletia coach-as-product modeling and
+ * any other B2B2C platform). `null` fields inherit from the seller-level
+ * portal config.
+ */
+interface ProductPortalConfig {
+    id: number;
+    productId: number;
+    businessName: string | null;
+    logoUrl: string | null;
+    primaryColor: string | null;
+    allowCancelSubscription: boolean | null;
+    allowUpdatePaymentMethod: boolean | null;
+    allowUpdateBillingInfo: boolean | null;
+    allowViewInvoices: boolean | null;
+    allowApplyCoupons: boolean | null;
+    requireCancelReason: boolean | null;
+    cancelAtPeriodEndOnly: boolean | null;
+    sendCancellationEmail: boolean | null;
+    sendPaymentMethodUpdatedEmail: boolean | null;
+    customSuccessMessage: string | null;
+    customCancellationMessage: string | null;
+    customWelcomeText: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Body for `POST` / `PATCH /api/products/:id/portal-config`. Both verbs
+ * are upsert with merge semantics — only fields present are written;
+ * unspecified fields keep their persisted value. Use the `clear`
+ * method (DELETE) to reset everything.
+ */
+interface SetProductPortalConfigParams {
+    businessName?: string | null;
+    logoUrl?: string | null;
+    primaryColor?: string | null;
+    allowCancelSubscription?: boolean | null;
+    allowUpdatePaymentMethod?: boolean | null;
+    allowUpdateBillingInfo?: boolean | null;
+    allowViewInvoices?: boolean | null;
+    allowApplyCoupons?: boolean | null;
+    requireCancelReason?: boolean | null;
+    cancelAtPeriodEndOnly?: boolean | null;
+    sendCancellationEmail?: boolean | null;
+    sendPaymentMethodUpdatedEmail?: boolean | null;
+    customSuccessMessage?: string | null;
+    customCancellationMessage?: string | null;
+    customWelcomeText?: string | null;
+}
 
 /**
  * Charges — the core of the Garu API.
@@ -657,13 +776,61 @@ declare class Meta {
 }
 
 /**
- * Products — discover products available to charge.
+ * 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.
+ */
+declare class ProductPortalConfigResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get the portal customization for a product. Returns `null` when no
+     * per-product config exists (the product falls back to seller-level
+     * portal config).
+     *
+     * @example
+     * const cfg = await garu.products.portalConfig.get(57);
+     */
+    get(productId: number): Promise<ProductPortalConfig | null>;
+    /**
+     * Create or merge the portal customization (idempotent upsert). Both
+     * `set` and `patch` have the same merge semantics — only fields present
+     * in the body are written, unspecified fields keep their persisted
+     * value. Use `clear` to reset everything.
+     *
+     * @example
+     * await garu.products.portalConfig.set(57, {
+     *   businessName: 'Coach Maria — Corrida & Trilha',
+     *   primaryColor: '#257264',
+     *   logoUrl: 'https://cdn.atletia.com.br/coaches/maria.png'
+     * });
+     */
+    set(productId: number, params: SetProductPortalConfigParams): Promise<ProductPortalConfig>;
+    /** Same merge semantics as `set` — alias for HTTP-PATCH-prefering callers. */
+    patch(productId: 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);
+     */
+    clear(productId: number): Promise<{
+        removed: boolean;
+    }>;
+}
+/**
+ * Products — discover products available to charge, and customize the
+ * per-product portal experience (v0.8.0).
  *
  * Products are scoped to the seller identified by the API key. The UUID
  * returned here is the same identifier accepted by `charges.create({ productId })`.
  */
 declare class Products {
     private readonly http;
+    /** Per-product portal customization (Garu v0.8.0). */
+    readonly portalConfig: ProductPortalConfigResource;
     constructor(http: HttpClient);
     /**
      * List products for the authenticated seller, with pagination and search.
@@ -831,6 +998,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 {
@@ -931,4 +1112,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, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, 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 PostponeScheduledChargeParams, type Product, type ProductList, 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 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

@@ -458,11 +458,80 @@ var Meta = class {
 };
 
 // src/resources/products.ts
+var ProductPortalConfigResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Get the portal customization for a product. Returns `null` when no
+   * per-product config exists (the product falls back to seller-level
+   * portal config).
+   *
+   * @example
+   * const cfg = await garu.products.portalConfig.get(57);
+   */
+  async get(productId) {
+    return this.http.call(
+      (signal) => this.http.client.GET(`/api/products/${productId}/portal-config`, {
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Create or merge the portal customization (idempotent upsert). Both
+   * `set` and `patch` have the same merge semantics — only fields present
+   * in the body are written, unspecified fields keep their persisted
+   * value. Use `clear` to reset everything.
+   *
+   * @example
+   * await garu.products.portalConfig.set(57, {
+   *   businessName: 'Coach Maria — Corrida & Trilha',
+   *   primaryColor: '#257264',
+   *   logoUrl: 'https://cdn.atletia.com.br/coaches/maria.png'
+   * });
+   */
+  async set(productId, params) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/products/${productId}/portal-config`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /** 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`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * 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);
+   */
+  async clear(productId) {
+    return this.http.call(
+      (signal) => this.http.client.DELETE(`/api/products/${productId}/portal-config`, {
+        signal
+      }).then((r) => r)
+    );
+  }
+};
 var Products = class {
   constructor(http) {
     this.http = http;
+    this.portalConfig = new ProductPortalConfigResource(http);
   }
   http;
+  /** Per-product portal customization (Garu v0.8.0). */
+  portalConfig;
   /**
    * List products for the authenticated seller, with pagination and search.
    *
@@ -727,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.6.0",
+  "version": "0.8.0",
   "description": "Official Node.js / TypeScript SDK for the Garu payment gateway.",
   "license": "MIT",
   "homepage": "https://garu.com.br",