@garuhq/node 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to `@garuhq/node` are documented in this file. Format:
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
 
+## [0.5.0] — 2026-05-01
+
+### Added
+
+- `scheduledCharges` resource on the `Garu` client. Schedule a charge to
+  bill a customer on a future date; Garu drives the customer reminder
+  on the due date and dunning to the seller team after.
+  - `scheduledCharges.create({ customerId, amount, type, dueDate, methods, ... })`
+    — `POST /api/scheduled-charges`. PIX and Boleto are supported now;
+    `type` accepts only `one_time` in this version.
+  - `scheduledCharges.list({ status?, customerId?, type?, dueFrom?, dueTo?, search?, ... })`
+    — `GET /api/scheduled-charges`. `status` accepts a single value or
+    an array; arrays are sent as repeated query params.
+  - `scheduledCharges.get(id)` — `GET /api/scheduled-charges/{id}`.
+    Returns a bundle: `{ charge, events, transactions }`.
+  - `scheduledCharges.postpone(id, { newDueDate, reason? })` — allowed
+    from `scheduled` / `due_today` / `overdue` / `paused`. Clears any
+    pending dunning so the new dueDate triggers a fresh reminder.
+  - `scheduledCharges.pause(id, { reason? })` — allowed from
+    `scheduled` / `due_today` / `overdue`.
+  - `scheduledCharges.resume(id)` — only valid from `paused`.
+  - `scheduledCharges.markPaid(id, { paymentDate, externalReference? })`
+    — record an off-Garu payment (transfer, cash). Allowed from
+    `due_today` / `overdue`.
+- `customers.list({ status: 'overdue' })` — new filter that returns
+  customers with at least one overdue scheduled charge.
+- Types exported from the package root: `CreateScheduledChargeParams`,
+  `ListScheduledChargesParams`, `MarkPaidScheduledChargeParams`,
+  `PauseScheduledChargeParams`, `PostponeScheduledChargeParams`,
+  `ScheduledChargeActor`, `ScheduledChargeDetail`,
+  `ScheduledChargeEvent`, `ScheduledChargeEventType`,
+  `ScheduledChargeLinkedTransaction`, `ScheduledChargeList`,
+  `ScheduledChargeRecord`, `ScheduledChargeStatus`,
+  `ScheduledChargeType`, `ScheduledPaymentMethod`.
+
 ## [0.3.0] — 2026-04-28
 
 ### Added

package/dist/index.cjs

@@ -367,6 +367,7 @@ var Customers = class {
     if (params.page !== void 0) query.page = String(params.page);
     if (params.limit !== void 0) query.limit = String(params.limit);
     if (params.search) query.search = params.search;
+    if (params.status) query.status = params.status;
     const qs = new URLSearchParams(query).toString();
     const url = `/api/customers${qs ? `?${qs}` : ""}`;
     return this.http.call(
@@ -503,6 +504,236 @@ var Products = class {
     );
   }
 };
+
+// src/resources/scheduled-charges.ts
+var ScheduledCharges = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Create a new scheduled charge. Auto-attaches `X-Idempotency-Key`
+   * (UUIDv4 if you don't pass `idempotencyKey`) so retries on transient
+   * network failures don't silently double-create.
+   *
+   * @example
+   * const charge = await garu.scheduledCharges.create({
+   *   customerId: 42,
+   *   amount: 297.50,
+   *   type: 'one_time',
+   *   dueDate: '2026-06-15',
+   *   methods: ['pix', 'boleto'],
+   *   description: 'Mensalidade Junho'
+   * });
+   */
+  async create(params) {
+    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
+    const { idempotencyKey: _omit, ...body } = params;
+    return this.http.call(
+      (signal) => this.http.client.POST("/api/scheduled-charges", {
+        body,
+        headers: { "X-Idempotency-Key": idempotencyKey },
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * List scheduled charges for the authenticated seller, with pagination
+   * and filters. Repeat the `status` array to filter on multiple values.
+   *
+   * @example
+   * const overdue = await garu.scheduledCharges.list({ status: 'overdue', limit: 50 });
+   *
+   * @example
+   * const upcoming = await garu.scheduledCharges.list({
+   *   status: ['scheduled', 'due_today'],
+   *   dueFrom: '2026-06-01',
+   *   dueTo: '2026-06-30'
+   * });
+   */
+  async list(params = {}) {
+    const qs = new URLSearchParams();
+    if (params.page !== void 0) qs.set("page", String(params.page));
+    if (params.limit !== void 0) qs.set("limit", String(params.limit));
+    if (params.customerId !== void 0) qs.set("customerId", String(params.customerId));
+    if (params.type) qs.set("type", params.type);
+    if (params.dueFrom) qs.set("dueFrom", params.dueFrom);
+    if (params.dueTo) qs.set("dueTo", params.dueTo);
+    if (params.search) qs.set("search", params.search);
+    if (params.status) {
+      const statuses = Array.isArray(params.status) ? params.status : [params.status];
+      for (const s of statuses) qs.append("status", s);
+    }
+    const query = qs.toString();
+    const url = `/api/scheduled-charges${query ? `?${query}` : ""}`;
+    return this.http.call(
+      (signal) => this.http.client.GET(url, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+  /**
+   * Fetch a single scheduled charge by ID, bundled with its event timeline
+   * and any linked Garu transactions.
+   *
+   * @example
+   * const { charge, events, transactions } = await garu.scheduledCharges.get('sch_abc123');
+   * // charge.status, events[].eventType, transactions[].status
+   */
+  async get(id) {
+    return this.http.call(
+      (signal) => this.http.client.GET(`/api/scheduled-charges/${id}`, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+  /**
+   * Postpone a scheduled charge to a new due date. Allowed from
+   * `scheduled` / `due_today` / `overdue` / `paused`. Clears any pending
+   * dunning so the new dueDate triggers a fresh customer reminder.
+   *
+   * @example
+   * await garu.scheduledCharges.postpone('sch_abc123', {
+   *   newDueDate: '2026-07-01',
+   *   reason: 'cliente pediu mais prazo'
+   * });
+   */
+  async postpone(id, params) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/postpone`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Pause a scheduled charge. No reminders fire while paused. Resume
+   * returns it to `scheduled`. Allowed from
+   * `scheduled` / `due_today` / `overdue`.
+   *
+   * @example
+   * await garu.scheduledCharges.pause('sch_abc123', { reason: 'em negociação' });
+   */
+  async pause(id, params = {}) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/pause`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Resume a paused scheduled charge. Only valid from `paused`.
+   *
+   * @example
+   * await garu.scheduledCharges.resume('sch_abc123');
+   */
+  async resume(id) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/resume`, {
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Manually mark a scheduled charge as paid, e.g. when the customer paid
+   * 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(
+      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/mark-paid`, {
+        body: params,
+        signal
+      }).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) {
     const { signature, secret, payload } = params;
@@ -568,6 +799,7 @@ var Garu = class {
   customers;
   meta;
   products;
+  scheduledCharges;
   /**
    * Webhook helpers. Available both as an instance member and as a static —
    * `Garu.webhooks.verify(...)` works without constructing a client.
@@ -587,6 +819,7 @@ var Garu = class {
     this.customers = new Customers(http);
     this.meta = new Meta(http);
     this.products = new Products(http);
+    this.scheduledCharges = new ScheduledCharges(http);
   }
 };
 

package/dist/index.d.cts

@@ -272,6 +272,162 @@ interface ListCustomersParams {
     page?: number;
     limit?: number;
     search?: string;
+    /** Filter by aggregated status. `overdue` returns customers with at least one overdue scheduled charge. */
+    status?: 'overdue';
+}
+type ScheduledChargeStatus = 'scheduled' | 'due_today' | 'overdue' | 'paid' | 'paused' | 'canceled' | 'trial' | 'pending_tokenization' | 'recurrence_canceled';
+type ScheduledChargeType = 'one_time' | 'recurring';
+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';
+    id: number;
+} | {
+    type: 'api_key';
+    id: number;
+} | {
+    type: 'system';
+};
+interface ScheduledChargeRecord {
+    id: string;
+    sellerId: number;
+    customerId: number;
+    productId: number | null;
+    /** Decimal BRL (e.g. `297.50`), never centavos. */
+    amount: number;
+    description: string | null;
+    type: ScheduledChargeType;
+    /** YYYY-MM-DD in São Paulo time. */
+    dueDate: string;
+    methods: ScheduledPaymentMethod[];
+    status: ScheduledChargeStatus;
+    externalReference: string | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string;
+    /** Eager-loaded customer (id/name/email/document only). */
+    customer?: {
+        id: number;
+        name: string;
+        email: string;
+        document: string;
+    } | null;
+    /** Eager-loaded product (id/uuid/name only). */
+    product?: {
+        id: number;
+        uuid: string;
+        name: string;
+    } | null;
+    [key: string]: unknown;
+}
+interface ScheduledChargeEvent {
+    id: number;
+    scheduledChargeId: string;
+    eventType: ScheduledChargeEventType;
+    actor: ScheduledChargeActor;
+    payload: Record<string, unknown> | null;
+    createdAt: string;
+}
+interface ScheduledChargeLinkedTransaction {
+    id: number;
+    /** Centavos (BRL × 100), matching `garu.charges.*` value semantics. */
+    value: number;
+    paymentMethod: string;
+    status: string;
+    date: string;
+    refundedAt: string | null;
+    [key: string]: unknown;
+}
+interface ScheduledChargeDetail {
+    charge: ScheduledChargeRecord;
+    events: ScheduledChargeEvent[];
+    transactions: ScheduledChargeLinkedTransaction[];
+}
+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. `recurring` requires a `recurrence` block. */
+    type: ScheduledChargeType;
+    /** YYYY-MM-DD in São Paulo time. Must be today or future. */
+    dueDate: string;
+    /** `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>;
+    /**
+     * Optional idempotency key for safe retries. The SDK auto-generates a
+     * UUIDv4 when omitted and forwards it as `X-Idempotency-Key`.
+     */
+    idempotencyKey?: string;
+}
+interface ListScheduledChargesParams {
+    page?: number;
+    limit?: number;
+    customerId?: number;
+    status?: ScheduledChargeStatus | ScheduledChargeStatus[];
+    type?: ScheduledChargeType;
+    /** YYYY-MM-DD lower bound for `dueDate`. */
+    dueFrom?: string;
+    /** YYYY-MM-DD upper bound for `dueDate`. */
+    dueTo?: string;
+    /** Free-text match against customer name / email / document. */
+    search?: string;
+}
+interface PostponeScheduledChargeParams {
+    /** YYYY-MM-DD in São Paulo time. Must be today or future. */
+    newDueDate: string;
+    reason?: string;
+}
+interface PauseScheduledChargeParams {
+    reason?: string;
+}
+interface MarkPaidScheduledChargeParams {
+    /** YYYY-MM-DD in São Paulo time. Must be today or past. */
+    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;
@@ -526,6 +682,157 @@ declare class Products {
     get(uuid: string): Promise<Product>;
 }
 
+/**
+ * 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, 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 (`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;
+    constructor(http: HttpClient);
+    /**
+     * Create a new scheduled charge. Auto-attaches `X-Idempotency-Key`
+     * (UUIDv4 if you don't pass `idempotencyKey`) so retries on transient
+     * network failures don't silently double-create.
+     *
+     * @example
+     * const charge = await garu.scheduledCharges.create({
+     *   customerId: 42,
+     *   amount: 297.50,
+     *   type: 'one_time',
+     *   dueDate: '2026-06-15',
+     *   methods: ['pix', 'boleto'],
+     *   description: 'Mensalidade Junho'
+     * });
+     */
+    create(params: CreateScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * List scheduled charges for the authenticated seller, with pagination
+     * and filters. Repeat the `status` array to filter on multiple values.
+     *
+     * @example
+     * const overdue = await garu.scheduledCharges.list({ status: 'overdue', limit: 50 });
+     *
+     * @example
+     * const upcoming = await garu.scheduledCharges.list({
+     *   status: ['scheduled', 'due_today'],
+     *   dueFrom: '2026-06-01',
+     *   dueTo: '2026-06-30'
+     * });
+     */
+    list(params?: ListScheduledChargesParams): Promise<ScheduledChargeList>;
+    /**
+     * Fetch a single scheduled charge by ID, bundled with its event timeline
+     * and any linked Garu transactions.
+     *
+     * @example
+     * const { charge, events, transactions } = await garu.scheduledCharges.get('sch_abc123');
+     * // charge.status, events[].eventType, transactions[].status
+     */
+    get(id: string): Promise<ScheduledChargeDetail>;
+    /**
+     * Postpone a scheduled charge to a new due date. Allowed from
+     * `scheduled` / `due_today` / `overdue` / `paused`. Clears any pending
+     * dunning so the new dueDate triggers a fresh customer reminder.
+     *
+     * @example
+     * await garu.scheduledCharges.postpone('sch_abc123', {
+     *   newDueDate: '2026-07-01',
+     *   reason: 'cliente pediu mais prazo'
+     * });
+     */
+    postpone(id: string, params: PostponeScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * Pause a scheduled charge. No reminders fire while paused. Resume
+     * returns it to `scheduled`. Allowed from
+     * `scheduled` / `due_today` / `overdue`.
+     *
+     * @example
+     * await garu.scheduledCharges.pause('sch_abc123', { reason: 'em negociação' });
+     */
+    pause(id: string, params?: PauseScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * Resume a paused scheduled charge. Only valid from `paused`.
+     *
+     * @example
+     * await garu.scheduledCharges.resume('sch_abc123');
+     */
+    resume(id: string): Promise<ScheduledChargeRecord>;
+    /**
+     * Manually mark a scheduled charge as paid, e.g. when the customer paid
+     * 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 {
     /**
      * Your Garu API key. `sk_live_…` for production, `sk_test_…` for test mode.
@@ -565,6 +872,7 @@ declare class Garu {
     readonly customers: Customers;
     readonly meta: Meta;
     readonly products: Products;
+    readonly scheduledCharges: ScheduledCharges;
     /**
      * Webhook helpers. Available both as an instance member and as a static —
      * `Garu.webhooks.verify(...)` works without constructing a client.
@@ -623,4 +931,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 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 MetaFeatures, type MetaResponse, type PaginatedList, type PaymentMethod, type Product, type ProductList, type RefundChargeParams, 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, 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 };

package/dist/index.d.ts

@@ -272,6 +272,162 @@ interface ListCustomersParams {
     page?: number;
     limit?: number;
     search?: string;
+    /** Filter by aggregated status. `overdue` returns customers with at least one overdue scheduled charge. */
+    status?: 'overdue';
+}
+type ScheduledChargeStatus = 'scheduled' | 'due_today' | 'overdue' | 'paid' | 'paused' | 'canceled' | 'trial' | 'pending_tokenization' | 'recurrence_canceled';
+type ScheduledChargeType = 'one_time' | 'recurring';
+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';
+    id: number;
+} | {
+    type: 'api_key';
+    id: number;
+} | {
+    type: 'system';
+};
+interface ScheduledChargeRecord {
+    id: string;
+    sellerId: number;
+    customerId: number;
+    productId: number | null;
+    /** Decimal BRL (e.g. `297.50`), never centavos. */
+    amount: number;
+    description: string | null;
+    type: ScheduledChargeType;
+    /** YYYY-MM-DD in São Paulo time. */
+    dueDate: string;
+    methods: ScheduledPaymentMethod[];
+    status: ScheduledChargeStatus;
+    externalReference: string | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string;
+    /** Eager-loaded customer (id/name/email/document only). */
+    customer?: {
+        id: number;
+        name: string;
+        email: string;
+        document: string;
+    } | null;
+    /** Eager-loaded product (id/uuid/name only). */
+    product?: {
+        id: number;
+        uuid: string;
+        name: string;
+    } | null;
+    [key: string]: unknown;
+}
+interface ScheduledChargeEvent {
+    id: number;
+    scheduledChargeId: string;
+    eventType: ScheduledChargeEventType;
+    actor: ScheduledChargeActor;
+    payload: Record<string, unknown> | null;
+    createdAt: string;
+}
+interface ScheduledChargeLinkedTransaction {
+    id: number;
+    /** Centavos (BRL × 100), matching `garu.charges.*` value semantics. */
+    value: number;
+    paymentMethod: string;
+    status: string;
+    date: string;
+    refundedAt: string | null;
+    [key: string]: unknown;
+}
+interface ScheduledChargeDetail {
+    charge: ScheduledChargeRecord;
+    events: ScheduledChargeEvent[];
+    transactions: ScheduledChargeLinkedTransaction[];
+}
+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. `recurring` requires a `recurrence` block. */
+    type: ScheduledChargeType;
+    /** YYYY-MM-DD in São Paulo time. Must be today or future. */
+    dueDate: string;
+    /** `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>;
+    /**
+     * Optional idempotency key for safe retries. The SDK auto-generates a
+     * UUIDv4 when omitted and forwards it as `X-Idempotency-Key`.
+     */
+    idempotencyKey?: string;
+}
+interface ListScheduledChargesParams {
+    page?: number;
+    limit?: number;
+    customerId?: number;
+    status?: ScheduledChargeStatus | ScheduledChargeStatus[];
+    type?: ScheduledChargeType;
+    /** YYYY-MM-DD lower bound for `dueDate`. */
+    dueFrom?: string;
+    /** YYYY-MM-DD upper bound for `dueDate`. */
+    dueTo?: string;
+    /** Free-text match against customer name / email / document. */
+    search?: string;
+}
+interface PostponeScheduledChargeParams {
+    /** YYYY-MM-DD in São Paulo time. Must be today or future. */
+    newDueDate: string;
+    reason?: string;
+}
+interface PauseScheduledChargeParams {
+    reason?: string;
+}
+interface MarkPaidScheduledChargeParams {
+    /** YYYY-MM-DD in São Paulo time. Must be today or past. */
+    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;
@@ -526,6 +682,157 @@ declare class Products {
     get(uuid: string): Promise<Product>;
 }
 
+/**
+ * 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, 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 (`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;
+    constructor(http: HttpClient);
+    /**
+     * Create a new scheduled charge. Auto-attaches `X-Idempotency-Key`
+     * (UUIDv4 if you don't pass `idempotencyKey`) so retries on transient
+     * network failures don't silently double-create.
+     *
+     * @example
+     * const charge = await garu.scheduledCharges.create({
+     *   customerId: 42,
+     *   amount: 297.50,
+     *   type: 'one_time',
+     *   dueDate: '2026-06-15',
+     *   methods: ['pix', 'boleto'],
+     *   description: 'Mensalidade Junho'
+     * });
+     */
+    create(params: CreateScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * List scheduled charges for the authenticated seller, with pagination
+     * and filters. Repeat the `status` array to filter on multiple values.
+     *
+     * @example
+     * const overdue = await garu.scheduledCharges.list({ status: 'overdue', limit: 50 });
+     *
+     * @example
+     * const upcoming = await garu.scheduledCharges.list({
+     *   status: ['scheduled', 'due_today'],
+     *   dueFrom: '2026-06-01',
+     *   dueTo: '2026-06-30'
+     * });
+     */
+    list(params?: ListScheduledChargesParams): Promise<ScheduledChargeList>;
+    /**
+     * Fetch a single scheduled charge by ID, bundled with its event timeline
+     * and any linked Garu transactions.
+     *
+     * @example
+     * const { charge, events, transactions } = await garu.scheduledCharges.get('sch_abc123');
+     * // charge.status, events[].eventType, transactions[].status
+     */
+    get(id: string): Promise<ScheduledChargeDetail>;
+    /**
+     * Postpone a scheduled charge to a new due date. Allowed from
+     * `scheduled` / `due_today` / `overdue` / `paused`. Clears any pending
+     * dunning so the new dueDate triggers a fresh customer reminder.
+     *
+     * @example
+     * await garu.scheduledCharges.postpone('sch_abc123', {
+     *   newDueDate: '2026-07-01',
+     *   reason: 'cliente pediu mais prazo'
+     * });
+     */
+    postpone(id: string, params: PostponeScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * Pause a scheduled charge. No reminders fire while paused. Resume
+     * returns it to `scheduled`. Allowed from
+     * `scheduled` / `due_today` / `overdue`.
+     *
+     * @example
+     * await garu.scheduledCharges.pause('sch_abc123', { reason: 'em negociação' });
+     */
+    pause(id: string, params?: PauseScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * Resume a paused scheduled charge. Only valid from `paused`.
+     *
+     * @example
+     * await garu.scheduledCharges.resume('sch_abc123');
+     */
+    resume(id: string): Promise<ScheduledChargeRecord>;
+    /**
+     * Manually mark a scheduled charge as paid, e.g. when the customer paid
+     * 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 {
     /**
      * Your Garu API key. `sk_live_…` for production, `sk_test_…` for test mode.
@@ -565,6 +872,7 @@ declare class Garu {
     readonly customers: Customers;
     readonly meta: Meta;
     readonly products: Products;
+    readonly scheduledCharges: ScheduledCharges;
     /**
      * Webhook helpers. Available both as an instance member and as a static —
      * `Garu.webhooks.verify(...)` works without constructing a client.
@@ -623,4 +931,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 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 MetaFeatures, type MetaResponse, type PaginatedList, type PaymentMethod, type Product, type ProductList, type RefundChargeParams, 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, 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 };

package/dist/index.js

@@ -361,6 +361,7 @@ var Customers = class {
     if (params.page !== void 0) query.page = String(params.page);
     if (params.limit !== void 0) query.limit = String(params.limit);
     if (params.search) query.search = params.search;
+    if (params.status) query.status = params.status;
     const qs = new URLSearchParams(query).toString();
     const url = `/api/customers${qs ? `?${qs}` : ""}`;
     return this.http.call(
@@ -497,6 +498,236 @@ var Products = class {
     );
   }
 };
+
+// src/resources/scheduled-charges.ts
+var ScheduledCharges = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Create a new scheduled charge. Auto-attaches `X-Idempotency-Key`
+   * (UUIDv4 if you don't pass `idempotencyKey`) so retries on transient
+   * network failures don't silently double-create.
+   *
+   * @example
+   * const charge = await garu.scheduledCharges.create({
+   *   customerId: 42,
+   *   amount: 297.50,
+   *   type: 'one_time',
+   *   dueDate: '2026-06-15',
+   *   methods: ['pix', 'boleto'],
+   *   description: 'Mensalidade Junho'
+   * });
+   */
+  async create(params) {
+    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
+    const { idempotencyKey: _omit, ...body } = params;
+    return this.http.call(
+      (signal) => this.http.client.POST("/api/scheduled-charges", {
+        body,
+        headers: { "X-Idempotency-Key": idempotencyKey },
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * List scheduled charges for the authenticated seller, with pagination
+   * and filters. Repeat the `status` array to filter on multiple values.
+   *
+   * @example
+   * const overdue = await garu.scheduledCharges.list({ status: 'overdue', limit: 50 });
+   *
+   * @example
+   * const upcoming = await garu.scheduledCharges.list({
+   *   status: ['scheduled', 'due_today'],
+   *   dueFrom: '2026-06-01',
+   *   dueTo: '2026-06-30'
+   * });
+   */
+  async list(params = {}) {
+    const qs = new URLSearchParams();
+    if (params.page !== void 0) qs.set("page", String(params.page));
+    if (params.limit !== void 0) qs.set("limit", String(params.limit));
+    if (params.customerId !== void 0) qs.set("customerId", String(params.customerId));
+    if (params.type) qs.set("type", params.type);
+    if (params.dueFrom) qs.set("dueFrom", params.dueFrom);
+    if (params.dueTo) qs.set("dueTo", params.dueTo);
+    if (params.search) qs.set("search", params.search);
+    if (params.status) {
+      const statuses = Array.isArray(params.status) ? params.status : [params.status];
+      for (const s of statuses) qs.append("status", s);
+    }
+    const query = qs.toString();
+    const url = `/api/scheduled-charges${query ? `?${query}` : ""}`;
+    return this.http.call(
+      (signal) => this.http.client.GET(url, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+  /**
+   * Fetch a single scheduled charge by ID, bundled with its event timeline
+   * and any linked Garu transactions.
+   *
+   * @example
+   * const { charge, events, transactions } = await garu.scheduledCharges.get('sch_abc123');
+   * // charge.status, events[].eventType, transactions[].status
+   */
+  async get(id) {
+    return this.http.call(
+      (signal) => this.http.client.GET(`/api/scheduled-charges/${id}`, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+  /**
+   * Postpone a scheduled charge to a new due date. Allowed from
+   * `scheduled` / `due_today` / `overdue` / `paused`. Clears any pending
+   * dunning so the new dueDate triggers a fresh customer reminder.
+   *
+   * @example
+   * await garu.scheduledCharges.postpone('sch_abc123', {
+   *   newDueDate: '2026-07-01',
+   *   reason: 'cliente pediu mais prazo'
+   * });
+   */
+  async postpone(id, params) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/postpone`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Pause a scheduled charge. No reminders fire while paused. Resume
+   * returns it to `scheduled`. Allowed from
+   * `scheduled` / `due_today` / `overdue`.
+   *
+   * @example
+   * await garu.scheduledCharges.pause('sch_abc123', { reason: 'em negociação' });
+   */
+  async pause(id, params = {}) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/pause`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Resume a paused scheduled charge. Only valid from `paused`.
+   *
+   * @example
+   * await garu.scheduledCharges.resume('sch_abc123');
+   */
+  async resume(id) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/resume`, {
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Manually mark a scheduled charge as paid, e.g. when the customer paid
+   * 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(
+      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/mark-paid`, {
+        body: params,
+        signal
+      }).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) {
     const { signature, secret, payload } = params;
@@ -562,6 +793,7 @@ var Garu = class {
   customers;
   meta;
   products;
+  scheduledCharges;
   /**
    * Webhook helpers. Available both as an instance member and as a static —
    * `Garu.webhooks.verify(...)` works without constructing a client.
@@ -581,6 +813,7 @@ var Garu = class {
     this.customers = new Customers(http);
     this.meta = new Meta(http);
     this.products = new Products(http);
+    this.scheduledCharges = new ScheduledCharges(http);
   }
 };
 

package/package.json

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