@garuhq/node 0.3.0 → 0.5.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

@@ -337,7 +337,7 @@ var Customers = class {
   }
   http;
   /**
-   * Create a customer and link it to the current seller.
+   * Register a customer for the current seller.
    *
    * @example
    * const customer = await garu.customers.create({
@@ -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(
@@ -402,6 +403,30 @@ var Customers = class {
       }).then((r) => r)
     );
   }
+  /**
+   * Set or clear the per-seller billing email override.
+   *
+   * The override is sticky: it takes precedence over the per-seller last-used
+   * email and the global `customer.email` for outbound seller→customer emails,
+   * and is **never** auto-overwritten by subsequent payments or registrations.
+   *
+   * @example
+   * // Set
+   * await garu.customers.setBillingEmailOverride(42, {
+   *   billingEmailOverride: 'cobrancas@empresa.com.br'
+   * });
+   *
+   * // Clear and fall back to the last-used email
+   * await garu.customers.setBillingEmailOverride(42, { billingEmailOverride: null });
+   */
+  async setBillingEmailOverride(id, params) {
+    return this.http.call(
+      (signal) => this.http.client.PATCH(`/api/customers/${id}/billing-email-override`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
   /**
    * Remove a customer from the current seller.
    *
@@ -479,6 +504,156 @@ 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). Allowed from `due_today` / `overdue`.
+   *
+   * @example
+   * await garu.scheduledCharges.markPaid('sch_abc123', {
+   *   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)
+    );
+  }
+};
 var webhooks = {
   verify(params) {
     const { signature, secret, payload } = params;
@@ -544,6 +719,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.
@@ -563,6 +739,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

@@ -219,8 +219,22 @@ interface CustomerRecord {
     state?: string | null;
     createdAt: string;
     updatedAt: string;
+    /**
+     * Resolved billing email used for outbound seller→customer emails:
+     * `billingEmailOverride ?? per-seller email ?? customer.email`.
+     */
+    billingEmail?: string;
+    /** True when a sticky `billingEmailOverride` is set for this seller. */
+    hasBillingEmailOverride?: boolean;
     [key: string]: unknown;
 }
+interface SetBillingEmailOverrideParams {
+    /**
+     * Customer-controlled billing email. Pass `null` to clear and fall back to
+     * the per-seller last-used email or the global `customer.email`.
+     */
+    billingEmailOverride: string | null;
+}
 type CustomerList = PaginatedList<CustomerRecord>;
 interface CreateCustomerParams {
     name: string;
@@ -258,6 +272,127 @@ 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';
+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;
+    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';
+    /** 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). */
+    methods: ScheduledPaymentMethod[];
+    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;
 }
 interface Product {
     id: number;
@@ -406,7 +541,7 @@ declare class Customers {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Create a customer and link it to the current seller.
+     * Register a customer for the current seller.
      *
      * @example
      * const customer = await garu.customers.create({
@@ -439,6 +574,23 @@ declare class Customers {
      * const updated = await garu.customers.update(42, { name: 'Maria Santos' });
      */
     update(id: number, params: UpdateCustomerParams): Promise<CustomerRecord>;
+    /**
+     * Set or clear the per-seller billing email override.
+     *
+     * The override is sticky: it takes precedence over the per-seller last-used
+     * email and the global `customer.email` for outbound seller→customer emails,
+     * and is **never** auto-overwritten by subsequent payments or registrations.
+     *
+     * @example
+     * // Set
+     * await garu.customers.setBillingEmailOverride(42, {
+     *   billingEmailOverride: 'cobrancas@empresa.com.br'
+     * });
+     *
+     * // Clear and fall back to the last-used email
+     * await garu.customers.setBillingEmailOverride(42, { billingEmailOverride: null });
+     */
+    setBillingEmailOverride(id: number, params: SetBillingEmailOverrideParams): Promise<CustomerRecord>;
     /**
      * Remove a customer from the current seller.
      *
@@ -495,6 +647,102 @@ 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 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.
+ *
+ * Recurring schedules are reserved for a future API version; the current
+ * `type` field accepts only `one_time`.
+ */
+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). Allowed from `due_today` / `overdue`.
+     *
+     * @example
+     * await garu.scheduledCharges.markPaid('sch_abc123', {
+     *   paymentDate: '2026-06-20',
+     *   externalReference: 'TED 4472881'
+     * });
+     */
+    markPaid(id: string, params: MarkPaidScheduledChargeParams): Promise<ScheduledChargeRecord>;
+}
+
 interface GaruOptions {
     /**
      * Your Garu API key. `sk_live_…` for production, `sk_test_…` for test mode.
@@ -534,6 +782,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.
@@ -592,4 +841,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 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 };

package/dist/index.d.ts

@@ -219,8 +219,22 @@ interface CustomerRecord {
     state?: string | null;
     createdAt: string;
     updatedAt: string;
+    /**
+     * Resolved billing email used for outbound seller→customer emails:
+     * `billingEmailOverride ?? per-seller email ?? customer.email`.
+     */
+    billingEmail?: string;
+    /** True when a sticky `billingEmailOverride` is set for this seller. */
+    hasBillingEmailOverride?: boolean;
     [key: string]: unknown;
 }
+interface SetBillingEmailOverrideParams {
+    /**
+     * Customer-controlled billing email. Pass `null` to clear and fall back to
+     * the per-seller last-used email or the global `customer.email`.
+     */
+    billingEmailOverride: string | null;
+}
 type CustomerList = PaginatedList<CustomerRecord>;
 interface CreateCustomerParams {
     name: string;
@@ -258,6 +272,127 @@ 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';
+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;
+    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';
+    /** 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). */
+    methods: ScheduledPaymentMethod[];
+    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;
 }
 interface Product {
     id: number;
@@ -406,7 +541,7 @@ declare class Customers {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Create a customer and link it to the current seller.
+     * Register a customer for the current seller.
      *
      * @example
      * const customer = await garu.customers.create({
@@ -439,6 +574,23 @@ declare class Customers {
      * const updated = await garu.customers.update(42, { name: 'Maria Santos' });
      */
     update(id: number, params: UpdateCustomerParams): Promise<CustomerRecord>;
+    /**
+     * Set or clear the per-seller billing email override.
+     *
+     * The override is sticky: it takes precedence over the per-seller last-used
+     * email and the global `customer.email` for outbound seller→customer emails,
+     * and is **never** auto-overwritten by subsequent payments or registrations.
+     *
+     * @example
+     * // Set
+     * await garu.customers.setBillingEmailOverride(42, {
+     *   billingEmailOverride: 'cobrancas@empresa.com.br'
+     * });
+     *
+     * // Clear and fall back to the last-used email
+     * await garu.customers.setBillingEmailOverride(42, { billingEmailOverride: null });
+     */
+    setBillingEmailOverride(id: number, params: SetBillingEmailOverrideParams): Promise<CustomerRecord>;
     /**
      * Remove a customer from the current seller.
      *
@@ -495,6 +647,102 @@ 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 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.
+ *
+ * Recurring schedules are reserved for a future API version; the current
+ * `type` field accepts only `one_time`.
+ */
+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). Allowed from `due_today` / `overdue`.
+     *
+     * @example
+     * await garu.scheduledCharges.markPaid('sch_abc123', {
+     *   paymentDate: '2026-06-20',
+     *   externalReference: 'TED 4472881'
+     * });
+     */
+    markPaid(id: string, params: MarkPaidScheduledChargeParams): Promise<ScheduledChargeRecord>;
+}
+
 interface GaruOptions {
     /**
      * Your Garu API key. `sk_live_…` for production, `sk_test_…` for test mode.
@@ -534,6 +782,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.
@@ -592,4 +841,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 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 };

package/dist/index.js

@@ -331,7 +331,7 @@ var Customers = class {
   }
   http;
   /**
-   * Create a customer and link it to the current seller.
+   * Register a customer for the current seller.
    *
    * @example
    * const customer = await garu.customers.create({
@@ -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(
@@ -396,6 +397,30 @@ var Customers = class {
       }).then((r) => r)
     );
   }
+  /**
+   * Set or clear the per-seller billing email override.
+   *
+   * The override is sticky: it takes precedence over the per-seller last-used
+   * email and the global `customer.email` for outbound seller→customer emails,
+   * and is **never** auto-overwritten by subsequent payments or registrations.
+   *
+   * @example
+   * // Set
+   * await garu.customers.setBillingEmailOverride(42, {
+   *   billingEmailOverride: 'cobrancas@empresa.com.br'
+   * });
+   *
+   * // Clear and fall back to the last-used email
+   * await garu.customers.setBillingEmailOverride(42, { billingEmailOverride: null });
+   */
+  async setBillingEmailOverride(id, params) {
+    return this.http.call(
+      (signal) => this.http.client.PATCH(`/api/customers/${id}/billing-email-override`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
   /**
    * Remove a customer from the current seller.
    *
@@ -473,6 +498,156 @@ 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). Allowed from `due_today` / `overdue`.
+   *
+   * @example
+   * await garu.scheduledCharges.markPaid('sch_abc123', {
+   *   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)
+    );
+  }
+};
 var webhooks = {
   verify(params) {
     const { signature, secret, payload } = params;
@@ -538,6 +713,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.
@@ -557,6 +733,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.3.0",
+  "version": "0.5.0",
   "description": "Official Node.js / TypeScript SDK for the Garu payment gateway.",
   "license": "MIT",
   "homepage": "https://garu.com.br",