@garuhq/node 0.5.0 → 0.7.0

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.
    *
@@ -637,13 +706,26 @@ var ScheduledCharges = class {
   }
   /**
    * Manually mark a scheduled charge as paid, e.g. when the customer paid
-   * outside Garu (bank transfer, cash). Allowed from `due_today` / `overdue`.
+   * outside Garu (bank transfer, cash).
+   *
+   * - **One-time:** omit `cycleNumber`. Allowed from `due_today` / `overdue`.
+   * - **Recurring:** pass `cycleNumber`. Allowed from cycle status
+   *   `due_today` / `overdue` / `failed`. Future cycles continue.
    *
    * @example
+   * // One-time
    * await garu.scheduledCharges.markPaid('sch_abc123', {
    *   paymentDate: '2026-06-20',
    *   externalReference: 'TED 4472881'
    * });
+   *
+   * @example
+   * // Recurring — mark cycle 3 paid; future cycles keep billing
+   * await garu.scheduledCharges.markPaid('sch_abc123', {
+   *   cycleNumber: 3,
+   *   paymentDate: '2026-06-20',
+   *   externalReference: 'TED 4472881'
+   * });
    */
   async markPaid(id, params) {
     return this.http.call(
@@ -653,6 +735,73 @@ var ScheduledCharges = class {
       }).then((r) => r)
     );
   }
+  /**
+   * Stop future cycles for a recurring series. The currently in-flight
+   * cycle (if any) remains active until paid, postponed, or marked-paid;
+   * only after that resolves does the series flip to `recurrence_canceled`.
+   * Recurring-only.
+   *
+   * @example
+   * await garu.scheduledCharges.cancelRecurrence('sch_abc123', {
+   *   reason: 'cliente cancelou plano'
+   * });
+   */
+  async cancelRecurrence(id, params = {}) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/cancel-recurrence`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Toggle Stripe-style soft cancel on a recurring series. With
+   * `enabled: true`, the cycle generator stops emitting new cycles after
+   * the next paid cycle; the in-flight cycle still bills + can be paid.
+   * Reversible by passing `enabled: false`. Recurring-only.
+   *
+   * @example
+   * await garu.scheduledCharges.setCancelAtPeriodEnd('sch_abc123', { enabled: true });
+   */
+  async setCancelAtPeriodEnd(id, params) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/cancel-at-period-end`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Swap the saved card on a recurring series. The new PaymentMethod must
+   * belong to the same customerId. Future cycles silent-charge the new
+   * card; the in-flight cycle is not retroactively rebound.
+   *
+   * @example
+   * await garu.scheduledCharges.changePaymentMethod('sch_abc123', { paymentMethodId: 42 });
+   */
+  async changePaymentMethod(id, params) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/payment-method`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Clear the saved card on a recurring series. Future cycles fall back
+   * to the email-with-link flow so the customer can re-enter card details
+   * or pay via PIX/Boleto.
+   *
+   * @example
+   * await garu.scheduledCharges.clearPaymentMethod('sch_abc123');
+   */
+  async clearPaymentMethod(id) {
+    return this.http.call(
+      (signal) => this.http.client.DELETE(`/api/scheduled-charges/${id}/payment-method`, {
+        signal
+      }).then((r) => r)
+    );
+  }
 };
 var webhooks = {
   verify(params) {

package/dist/index.d.cts

@@ -277,7 +277,17 @@ interface ListCustomersParams {
 }
 type ScheduledChargeStatus = 'scheduled' | 'due_today' | 'overdue' | 'paid' | 'paused' | 'canceled' | 'trial' | 'pending_tokenization' | 'recurrence_canceled';
 type ScheduledChargeType = 'one_time' | 'recurring';
-type ScheduledPaymentMethod = 'pix' | 'boleto';
+type ScheduledPaymentMethod = 'pix' | 'boleto' | 'card';
+type RecurrenceInterval = 'weekly' | 'biweekly' | 'monthly' | 'bimonthly' | 'quarterly' | 'biannual' | 'yearly';
+interface RecurrenceConfig {
+    interval: RecurrenceInterval;
+    /** Multiplier for the interval (default 1). */
+    intervalCount?: number;
+    /** Stop after N successful cycles. Mutually exclusive with `endsOn`. */
+    endsAfter?: number;
+    /** Stop after this calendar date (YYYY-MM-DD). Mutually exclusive with `endsAfter`. */
+    endsOn?: string;
+}
 type ScheduledChargeEventType = 'created' | 'postponed' | 'paused' | 'resumed' | 'recurrence_canceled' | 'manually_marked_paid' | 'paid' | 'overdue_reminder_sent' | 'd_day_reminder_sent';
 type ScheduledChargeActor = {
     type: 'user';
@@ -346,19 +356,28 @@ interface ScheduledChargeDetail {
 type ScheduledChargeList = PaginatedList<ScheduledChargeRecord>;
 interface CreateScheduledChargeParams {
     customerId: number;
+    /**
+     * Required when `methods` includes `card` — Celcoin transactions are
+     * scoped per product. Optional otherwise.
+     */
     productId?: number;
     /** Decimal BRL (e.g. `297.50`). */
     amount: number;
     description?: string;
-    /**
-     * Schedule type. Only `one_time` is accepted by the current API; the
-     * literal narrows to that until recurring schedules ship.
-     */
-    type: 'one_time';
+    /** Schedule type. `recurring` requires a `recurrence` block. */
+    type: ScheduledChargeType;
     /** YYYY-MM-DD in São Paulo time. Must be today or future. */
     dueDate: string;
-    /** PIX and Boleto are supported now; card requires tokenization (future). */
+    /** `card` is recurring-only and requires `productId`. */
     methods: ScheduledPaymentMethod[];
+    /** Cadence for `type='recurring'`. Must be omitted when `type='one_time'`. */
+    recurrence?: RecurrenceConfig;
+    /**
+     * Free-trial duration in days (1..365). Recurring-only. When set, cycle 1
+     * is rebased to `today + trialDays` and `customer.trial_started` fires
+     * immediately.
+     */
+    trialDays?: number;
     externalReference?: string;
     metadata?: Record<string, unknown>;
     /**
@@ -393,6 +412,22 @@ interface MarkPaidScheduledChargeParams {
     paymentDate: string;
     /** Bank reference, internal ID, or any stable string for reconciliation. */
     externalReference?: string;
+    /**
+     * Cycle number to mark paid. REQUIRED for recurring schedules. Omitted
+     * for one-time charges.
+     */
+    cycleNumber?: number;
+}
+interface CancelRecurrenceScheduledChargeParams {
+    reason?: string;
+}
+interface CancelAtPeriodEndScheduledChargeParams {
+    /** `true` enables Stripe-style soft cancel; `false` clears the flag. */
+    enabled: boolean;
+}
+interface ChangePaymentMethodScheduledChargeParams {
+    /** PaymentMethod id to bind. Must belong to the same customerId. */
+    paymentMethodId: number;
 }
 interface Product {
     id: number;
@@ -450,6 +485,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.
@@ -622,13 +749,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.
@@ -651,13 +826,15 @@ declare class Products {
  * Scheduled charges — bill a customer on a future date.
  *
  * The seller registers a customer (see `garu.customers.create`), then
- * schedules one or more charges (PIX or Boleto). Garu drives the rest:
- * pre-charge customer email on the due date, dunning to the seller team
- * after the due date, and a state machine for postpone/pause/resume/
- * mark-paid actions.
+ * schedules one or more charges (PIX, Boleto, or Card). Garu drives the
+ * rest: pre-charge customer email on the due date, dunning to the seller
+ * team after the due date, and a state machine for
+ * postpone/pause/resume/mark-paid actions.
  *
- * Recurring schedules are reserved for a future API version; the current
- * `type` field accepts only `one_time`.
+ * Recurring schedules (`type: 'recurring'`) silent-charge the saved card
+ * on every cycle past the first. Optional trial periods, cancel-recurrence,
+ * cancel-at-period-end, and payment-method swap actions cover the SaaS
+ * lifecycle.
  */
 declare class ScheduledCharges {
     private readonly http;
@@ -732,15 +909,68 @@ declare class ScheduledCharges {
     resume(id: string): Promise<ScheduledChargeRecord>;
     /**
      * Manually mark a scheduled charge as paid, e.g. when the customer paid
-     * outside Garu (bank transfer, cash). Allowed from `due_today` / `overdue`.
+     * outside Garu (bank transfer, cash).
+     *
+     * - **One-time:** omit `cycleNumber`. Allowed from `due_today` / `overdue`.
+     * - **Recurring:** pass `cycleNumber`. Allowed from cycle status
+     *   `due_today` / `overdue` / `failed`. Future cycles continue.
      *
      * @example
+     * // One-time
      * await garu.scheduledCharges.markPaid('sch_abc123', {
      *   paymentDate: '2026-06-20',
      *   externalReference: 'TED 4472881'
      * });
+     *
+     * @example
+     * // Recurring — mark cycle 3 paid; future cycles keep billing
+     * await garu.scheduledCharges.markPaid('sch_abc123', {
+     *   cycleNumber: 3,
+     *   paymentDate: '2026-06-20',
+     *   externalReference: 'TED 4472881'
+     * });
      */
     markPaid(id: string, params: MarkPaidScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * Stop future cycles for a recurring series. The currently in-flight
+     * cycle (if any) remains active until paid, postponed, or marked-paid;
+     * only after that resolves does the series flip to `recurrence_canceled`.
+     * Recurring-only.
+     *
+     * @example
+     * await garu.scheduledCharges.cancelRecurrence('sch_abc123', {
+     *   reason: 'cliente cancelou plano'
+     * });
+     */
+    cancelRecurrence(id: string, params?: CancelRecurrenceScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * Toggle Stripe-style soft cancel on a recurring series. With
+     * `enabled: true`, the cycle generator stops emitting new cycles after
+     * the next paid cycle; the in-flight cycle still bills + can be paid.
+     * Reversible by passing `enabled: false`. Recurring-only.
+     *
+     * @example
+     * await garu.scheduledCharges.setCancelAtPeriodEnd('sch_abc123', { enabled: true });
+     */
+    setCancelAtPeriodEnd(id: string, params: CancelAtPeriodEndScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * Swap the saved card on a recurring series. The new PaymentMethod must
+     * belong to the same customerId. Future cycles silent-charge the new
+     * card; the in-flight cycle is not retroactively rebound.
+     *
+     * @example
+     * await garu.scheduledCharges.changePaymentMethod('sch_abc123', { paymentMethodId: 42 });
+     */
+    changePaymentMethod(id: string, params: ChangePaymentMethodScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * Clear the saved card on a recurring series. Future cycles fall back
+     * to the email-with-link flow so the customer can re-enter card details
+     * or pay via PIX/Boleto.
+     *
+     * @example
+     * await garu.scheduledCharges.clearPaymentMethod('sch_abc123');
+     */
+    clearPaymentMethod(id: string): Promise<ScheduledChargeRecord>;
 }
 
 interface GaruOptions {
@@ -841,4 +1071,4 @@ declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CardInfo, 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 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 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 };

package/dist/index.d.ts

@@ -277,7 +277,17 @@ interface ListCustomersParams {
 }
 type ScheduledChargeStatus = 'scheduled' | 'due_today' | 'overdue' | 'paid' | 'paused' | 'canceled' | 'trial' | 'pending_tokenization' | 'recurrence_canceled';
 type ScheduledChargeType = 'one_time' | 'recurring';
-type ScheduledPaymentMethod = 'pix' | 'boleto';
+type ScheduledPaymentMethod = 'pix' | 'boleto' | 'card';
+type RecurrenceInterval = 'weekly' | 'biweekly' | 'monthly' | 'bimonthly' | 'quarterly' | 'biannual' | 'yearly';
+interface RecurrenceConfig {
+    interval: RecurrenceInterval;
+    /** Multiplier for the interval (default 1). */
+    intervalCount?: number;
+    /** Stop after N successful cycles. Mutually exclusive with `endsOn`. */
+    endsAfter?: number;
+    /** Stop after this calendar date (YYYY-MM-DD). Mutually exclusive with `endsAfter`. */
+    endsOn?: string;
+}
 type ScheduledChargeEventType = 'created' | 'postponed' | 'paused' | 'resumed' | 'recurrence_canceled' | 'manually_marked_paid' | 'paid' | 'overdue_reminder_sent' | 'd_day_reminder_sent';
 type ScheduledChargeActor = {
     type: 'user';
@@ -346,19 +356,28 @@ interface ScheduledChargeDetail {
 type ScheduledChargeList = PaginatedList<ScheduledChargeRecord>;
 interface CreateScheduledChargeParams {
     customerId: number;
+    /**
+     * Required when `methods` includes `card` — Celcoin transactions are
+     * scoped per product. Optional otherwise.
+     */
     productId?: number;
     /** Decimal BRL (e.g. `297.50`). */
     amount: number;
     description?: string;
-    /**
-     * Schedule type. Only `one_time` is accepted by the current API; the
-     * literal narrows to that until recurring schedules ship.
-     */
-    type: 'one_time';
+    /** Schedule type. `recurring` requires a `recurrence` block. */
+    type: ScheduledChargeType;
     /** YYYY-MM-DD in São Paulo time. Must be today or future. */
     dueDate: string;
-    /** PIX and Boleto are supported now; card requires tokenization (future). */
+    /** `card` is recurring-only and requires `productId`. */
     methods: ScheduledPaymentMethod[];
+    /** Cadence for `type='recurring'`. Must be omitted when `type='one_time'`. */
+    recurrence?: RecurrenceConfig;
+    /**
+     * Free-trial duration in days (1..365). Recurring-only. When set, cycle 1
+     * is rebased to `today + trialDays` and `customer.trial_started` fires
+     * immediately.
+     */
+    trialDays?: number;
     externalReference?: string;
     metadata?: Record<string, unknown>;
     /**
@@ -393,6 +412,22 @@ interface MarkPaidScheduledChargeParams {
     paymentDate: string;
     /** Bank reference, internal ID, or any stable string for reconciliation. */
     externalReference?: string;
+    /**
+     * Cycle number to mark paid. REQUIRED for recurring schedules. Omitted
+     * for one-time charges.
+     */
+    cycleNumber?: number;
+}
+interface CancelRecurrenceScheduledChargeParams {
+    reason?: string;
+}
+interface CancelAtPeriodEndScheduledChargeParams {
+    /** `true` enables Stripe-style soft cancel; `false` clears the flag. */
+    enabled: boolean;
+}
+interface ChangePaymentMethodScheduledChargeParams {
+    /** PaymentMethod id to bind. Must belong to the same customerId. */
+    paymentMethodId: number;
 }
 interface Product {
     id: number;
@@ -450,6 +485,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.
@@ -622,13 +749,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.
@@ -651,13 +826,15 @@ declare class Products {
  * Scheduled charges — bill a customer on a future date.
  *
  * The seller registers a customer (see `garu.customers.create`), then
- * schedules one or more charges (PIX or Boleto). Garu drives the rest:
- * pre-charge customer email on the due date, dunning to the seller team
- * after the due date, and a state machine for postpone/pause/resume/
- * mark-paid actions.
+ * schedules one or more charges (PIX, Boleto, or Card). Garu drives the
+ * rest: pre-charge customer email on the due date, dunning to the seller
+ * team after the due date, and a state machine for
+ * postpone/pause/resume/mark-paid actions.
  *
- * Recurring schedules are reserved for a future API version; the current
- * `type` field accepts only `one_time`.
+ * Recurring schedules (`type: 'recurring'`) silent-charge the saved card
+ * on every cycle past the first. Optional trial periods, cancel-recurrence,
+ * cancel-at-period-end, and payment-method swap actions cover the SaaS
+ * lifecycle.
  */
 declare class ScheduledCharges {
     private readonly http;
@@ -732,15 +909,68 @@ declare class ScheduledCharges {
     resume(id: string): Promise<ScheduledChargeRecord>;
     /**
      * Manually mark a scheduled charge as paid, e.g. when the customer paid
-     * outside Garu (bank transfer, cash). Allowed from `due_today` / `overdue`.
+     * outside Garu (bank transfer, cash).
+     *
+     * - **One-time:** omit `cycleNumber`. Allowed from `due_today` / `overdue`.
+     * - **Recurring:** pass `cycleNumber`. Allowed from cycle status
+     *   `due_today` / `overdue` / `failed`. Future cycles continue.
      *
      * @example
+     * // One-time
      * await garu.scheduledCharges.markPaid('sch_abc123', {
      *   paymentDate: '2026-06-20',
      *   externalReference: 'TED 4472881'
      * });
+     *
+     * @example
+     * // Recurring — mark cycle 3 paid; future cycles keep billing
+     * await garu.scheduledCharges.markPaid('sch_abc123', {
+     *   cycleNumber: 3,
+     *   paymentDate: '2026-06-20',
+     *   externalReference: 'TED 4472881'
+     * });
      */
     markPaid(id: string, params: MarkPaidScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * Stop future cycles for a recurring series. The currently in-flight
+     * cycle (if any) remains active until paid, postponed, or marked-paid;
+     * only after that resolves does the series flip to `recurrence_canceled`.
+     * Recurring-only.
+     *
+     * @example
+     * await garu.scheduledCharges.cancelRecurrence('sch_abc123', {
+     *   reason: 'cliente cancelou plano'
+     * });
+     */
+    cancelRecurrence(id: string, params?: CancelRecurrenceScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * Toggle Stripe-style soft cancel on a recurring series. With
+     * `enabled: true`, the cycle generator stops emitting new cycles after
+     * the next paid cycle; the in-flight cycle still bills + can be paid.
+     * Reversible by passing `enabled: false`. Recurring-only.
+     *
+     * @example
+     * await garu.scheduledCharges.setCancelAtPeriodEnd('sch_abc123', { enabled: true });
+     */
+    setCancelAtPeriodEnd(id: string, params: CancelAtPeriodEndScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * Swap the saved card on a recurring series. The new PaymentMethod must
+     * belong to the same customerId. Future cycles silent-charge the new
+     * card; the in-flight cycle is not retroactively rebound.
+     *
+     * @example
+     * await garu.scheduledCharges.changePaymentMethod('sch_abc123', { paymentMethodId: 42 });
+     */
+    changePaymentMethod(id: string, params: ChangePaymentMethodScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * Clear the saved card on a recurring series. Future cycles fall back
+     * to the email-with-link flow so the customer can re-enter card details
+     * or pay via PIX/Boleto.
+     *
+     * @example
+     * await garu.scheduledCharges.clearPaymentMethod('sch_abc123');
+     */
+    clearPaymentMethod(id: string): Promise<ScheduledChargeRecord>;
 }
 
 interface GaruOptions {
@@ -841,4 +1071,4 @@ declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CardInfo, 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 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 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 };

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.
    *
@@ -631,13 +700,26 @@ var ScheduledCharges = class {
   }
   /**
    * Manually mark a scheduled charge as paid, e.g. when the customer paid
-   * outside Garu (bank transfer, cash). Allowed from `due_today` / `overdue`.
+   * outside Garu (bank transfer, cash).
+   *
+   * - **One-time:** omit `cycleNumber`. Allowed from `due_today` / `overdue`.
+   * - **Recurring:** pass `cycleNumber`. Allowed from cycle status
+   *   `due_today` / `overdue` / `failed`. Future cycles continue.
    *
    * @example
+   * // One-time
    * await garu.scheduledCharges.markPaid('sch_abc123', {
    *   paymentDate: '2026-06-20',
    *   externalReference: 'TED 4472881'
    * });
+   *
+   * @example
+   * // Recurring — mark cycle 3 paid; future cycles keep billing
+   * await garu.scheduledCharges.markPaid('sch_abc123', {
+   *   cycleNumber: 3,
+   *   paymentDate: '2026-06-20',
+   *   externalReference: 'TED 4472881'
+   * });
    */
   async markPaid(id, params) {
     return this.http.call(
@@ -647,6 +729,73 @@ var ScheduledCharges = class {
       }).then((r) => r)
     );
   }
+  /**
+   * Stop future cycles for a recurring series. The currently in-flight
+   * cycle (if any) remains active until paid, postponed, or marked-paid;
+   * only after that resolves does the series flip to `recurrence_canceled`.
+   * Recurring-only.
+   *
+   * @example
+   * await garu.scheduledCharges.cancelRecurrence('sch_abc123', {
+   *   reason: 'cliente cancelou plano'
+   * });
+   */
+  async cancelRecurrence(id, params = {}) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/cancel-recurrence`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Toggle Stripe-style soft cancel on a recurring series. With
+   * `enabled: true`, the cycle generator stops emitting new cycles after
+   * the next paid cycle; the in-flight cycle still bills + can be paid.
+   * Reversible by passing `enabled: false`. Recurring-only.
+   *
+   * @example
+   * await garu.scheduledCharges.setCancelAtPeriodEnd('sch_abc123', { enabled: true });
+   */
+  async setCancelAtPeriodEnd(id, params) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/cancel-at-period-end`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Swap the saved card on a recurring series. The new PaymentMethod must
+   * belong to the same customerId. Future cycles silent-charge the new
+   * card; the in-flight cycle is not retroactively rebound.
+   *
+   * @example
+   * await garu.scheduledCharges.changePaymentMethod('sch_abc123', { paymentMethodId: 42 });
+   */
+  async changePaymentMethod(id, params) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/payment-method`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Clear the saved card on a recurring series. Future cycles fall back
+   * to the email-with-link flow so the customer can re-enter card details
+   * or pay via PIX/Boleto.
+   *
+   * @example
+   * await garu.scheduledCharges.clearPaymentMethod('sch_abc123');
+   */
+  async clearPaymentMethod(id) {
+    return this.http.call(
+      (signal) => this.http.client.DELETE(`/api/scheduled-charges/${id}/payment-method`, {
+        signal
+      }).then((r) => r)
+    );
+  }
 };
 var webhooks = {
   verify(params) {

package/package.json

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