@garuhq/node 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -3,6 +3,62 @@
 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.14.0] — 2026-05-31
+
+### Added
+
+- **Pix Automático support** — Brazil's BACEN auto-debit recurring Pix, where
+  the customer authorizes once via a consent QR/link in their bank app and
+  cycles 2+ debit silently. All changes are additive; existing
+  Card / Pix / Boleto callers are unaffected.
+  - `'pix_automatic'` added to the `ScheduledPaymentMethod` union, so
+    `scheduledCharges.create({ methods: ['pix_automatic'], ... })` is now
+    typed. Recurring-only and requires `productId` (whose product must have
+    Pix Automático enabled).
+  - `Product.pixAutomatic: boolean` — when `true`, the public subscription
+    checkout exposes Pix Automático. Enabled by default; sellers can disable
+    it per product.
+  - `'pix_automatic'` added to the `ScheduledChargeAttempt.paymentMethod`
+    union and to `WirePaymentMethodId`, so transactions/charges read back
+    from Pix Automático cycles type-check.
+- README: new **Pix Automático** section — what it is, when to use it, how to
+  enable it on a product, creating a `pix_automatic` scheduled charge, and
+  branching webhook handlers on `paymentMethod === 'pix_automatic'`.
+
+### Notes
+
+- No new webhook event names: Pix Automático fires the same
+  `subscription.*` / `transaction.*` events as card recurrence. Branch on the
+  payload's `paymentMethod` field. Refused debits are **not** retried at the
+  network level — Garu fires `subscription.payment_failed` and moves the
+  series to `past_due`.
+
+## [0.13.0] — 2026-05-25
+
+### Added
+
+- `scheduledCharges.chargeNow(id)` — `POST /api/scheduled-charges/{id}/charge-now`.
+  Force-bills the current cycle right now instead of waiting for its due
+  date, running the same dispatch the daily billing cron would (customer
+  email/notification + outbound webhook + timeline event). Allowed only
+  from a billable status (`scheduled` / `due_today`); a recurring series
+  must have an open cycle. **Idempotent** — a cycle whose d-day was
+  already dispatched reports `already_sent` and does not re-charge.
+  Returns `{ outcome, cycleNumber, reason?, message }`:
+  - `outcome` is `'dispatched' | 'already_sent' | 'not_sent' | 'failed'`.
+  - `reason` (on `not_sent` / `failed`) is one of the documented literals
+    (`no_email`, `lock_lost`, `no_saved_payment_method`, `card_expired`,
+    `payment_method_missing`, `customer_missing`) or a raw gateway decline
+    code.
+  - `message` is a ready-to-show pt-BR string.
+- `ChargeNowOutcome`, `ChargeNowReason`, and `ChargeNowResult` types
+  exported from the package root.
+- `maxRecoveryDays?: number` (integer 1–365) on
+  `CreateScheduledChargeParams` — caps how many days past `dueDate` the
+  daily recovery sweep will still auto-bill a missed charge. Omit for the
+  system default (14). Also surfaced on the scheduled charge object as
+  `ScheduledChargeRecord.maxRecoveryDays: number | null`.
+
 ## [0.12.1] — 2026-05-19
 
 ### Fixed
@@ -30,7 +86,7 @@ All notable changes to `@garuhq/node` are documented in this file. Format:
 
 - `webhookEvents.resend(id)` — `POST /api/webhook-events/{id}/resend`,
   the audit-trail-preserving counterpart to `retry()`. The backend
-  inserts a *clone* event (new numeric id) that points back at the
+  inserts a _clone_ event (new numeric id) that points back at the
   source via `manualResendOf`, then dispatches that clone. The
   original row is untouched, so the historical record of the prior
   failure (status, response status/body, attempts) survives. Works on

package/README.md

@@ -54,8 +54,8 @@ const charge = await garu.charges.create({
     name: 'Maria Silva',
     email: 'maria@exemplo.com.br',
     document: '12345678909', // CPF, digits only
-    phone: '11987654321',
-  },
+    phone: '11987654321'
+  }
 });
 
 console.log(charge.id, charge.status);
@@ -78,7 +78,7 @@ const garu = new Garu({ apiKey: process.env.GARU_API_KEY });
 const garu = new Garu({
   apiKey: process.env.GARU_API_KEY,
   timeoutMs: 30_000, // default
-  maxRetries: 2,     // default (3 total attempts)
+  maxRetries: 2 // default (3 total attempts)
 });
 ```
 
@@ -101,8 +101,8 @@ const charge = await garu.charges.create({
     name: 'Maria Silva',
     email: 'maria@exemplo.com.br',
     document: '12345678909',
-    phone: '11987654321',
-  },
+    phone: '11987654321'
+  }
 });
 ```
 
@@ -117,14 +117,14 @@ const charge = await garu.charges.create({
     holderName: 'MARIA SILVA',
     expirationMonth: '12',
     expirationYear: '2028',
-    cvv: '123',
+    cvv: '123'
   },
   customer: {
     name: 'Maria Silva',
     email: 'maria@exemplo.com.br',
     document: '12345678909',
-    phone: '11987654321',
-  },
+    phone: '11987654321'
+  }
 });
 ```
 
@@ -145,13 +145,13 @@ await garu.charges.refund(4472, { amount: 1000 }); // partial refund (R$10.00)
 
 ## Customers
 
-| Method                    | Description                                   |
-| ------------------------- | --------------------------------------------- |
-| `create(params)`          | Create a new customer.                        |
-| `list(params?)`           | List customers with pagination and search.    |
-| `get(id)`                 | Fetch a single customer by ID.                |
-| `update(id, params)`      | Update a customer's profile.                  |
-| `delete(id)`              | Delete a customer.                            |
+| Method               | Description                                |
+| -------------------- | ------------------------------------------ |
+| `create(params)`     | Create a new customer.                     |
+| `list(params?)`      | List customers with pagination and search. |
+| `get(id)`            | Fetch a single customer by ID.             |
+| `update(id, params)` | Update a customer's profile.               |
+| `delete(id)`         | Delete a customer.                         |
 
 ```ts
 const customer = await garu.customers.create({
@@ -159,7 +159,7 @@ const customer = await garu.customers.create({
   email: 'maria@exemplo.com.br',
   document: '12345678909',
   phone: '11987654321',
-  personType: 'fisica',
+  personType: 'fisica'
 });
 
 const { data, meta } = await garu.customers.list({ search: 'maria', limit: 10 });
@@ -171,26 +171,26 @@ Discover products and customize the per-product portal experience (B2B2C).
 
 `portalConfig.*` methods accept `productId` as either the product UUID (preferred — same identifier returned by `list()` and webhook payloads) or the legacy numeric id (Garu v0.10.0+).
 
-| Method                              | Description                                                       |
-| ----------------------------------- | ----------------------------------------------------------------- |
-| `list(params?)`                     | Paginated list of products for the seller.                        |
-| `get(uuid)`                         | Fetch a single product by UUID — same id used by charges.         |
-| `portalConfig.get(productId)`       | Read per-product portal customization. Returns `null` if unset.   |
-| `portalConfig.set(productId, p)`    | Upsert with merge — only fields present are written.              |
-| `portalConfig.patch(productId, p)`  | Same merge semantics as `set` — alias for HTTP-PATCH callers.     |
-| `portalConfig.clear(productId)`     | Remove the customization; product falls back to seller config.    |
+| Method                             | Description                                                     |
+| ---------------------------------- | --------------------------------------------------------------- |
+| `list(params?)`                    | Paginated list of products for the seller.                      |
+| `get(uuid)`                        | Fetch a single product by UUID — same id used by charges.       |
+| `portalConfig.get(productId)`      | Read per-product portal customization. Returns `null` if unset. |
+| `portalConfig.set(productId, p)`   | Upsert with merge — only fields present are written.            |
+| `portalConfig.patch(productId, p)` | Same merge semantics as `set` — alias for HTTP-PATCH callers.   |
+| `portalConfig.clear(productId)`    | Remove the customization; product falls back to seller config.  |
 
 ```ts
 // SaaS de coaching: per-coach branding under one Seller account
 await garu.products.portalConfig.set('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f', {
   businessName: 'Coach Maria — Corrida & Trilha',
   primaryColor: '#257264',
-  logoUrl: 'https://cdn.exemplo.com/coaches/maria.png',
+  logoUrl: 'https://cdn.exemplo.com/coaches/maria.png'
 });
 
 // Pass `null` on a field to inherit from the seller-level config
 await garu.products.portalConfig.patch('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f', {
-  primaryColor: null,
+  primaryColor: null
 });
 ```
 
@@ -198,22 +198,24 @@ await garu.products.portalConfig.patch('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f', {
 
 Bill an existing customer on a future date — one-time or recurring with card tokenization. The Garu drives email reminders, dunning, retries, and the lifecycle state machine.
 
-| Method                                        | Description                                                                |
-| --------------------------------------------- | -------------------------------------------------------------------------- |
-| `create(params)`                              | Create one-time or recurring schedule. Auto-attaches `X-Idempotency-Key`.  |
-| `list(params?)`                               | Paginated list with status / type / dueFrom / dueTo / customerId filters.  |
-| `get(id)`                                     | Detail bundle: charge + event timeline + linked transactions.              |
-| `markPaid(id, params)`                        | Mark cycle paid (off-Garu reconciliation).                                 |
-| `postpone(id, params)`                        | Move the next cycle's due date forward.                                    |
-| `pause(id, params?)` / `resume(id)`           | Suspend / re-enable a series.                                              |
-| `cancelRecurrence(id, params?)`               | Hard-stop future cycles (recurring only).                                  |
-| `cancelAtPeriodEnd(id, { enabled })`          | Stripe-style soft-cancel; reversible.                                      |
-| `changePaymentMethod(id, params)`             | Swap the saved card.                                                       |
-| `clearPaymentMethod(id)`                      | Remove the saved card; future cycles email-with-link.                      |
-| `listAttempts(id, params?)`                   | Per-attempt billing log — every silent-charge / retry / mark-paid (v0.8.2).|
+| Method                               | Description                                                                 |
+| ------------------------------------ | --------------------------------------------------------------------------- |
+| `create(params)`                     | Create one-time or recurring schedule. Auto-attaches `X-Idempotency-Key`.   |
+| `list(params?)`                      | Paginated list with status / type / dueFrom / dueTo / customerId filters.   |
+| `get(id)`                            | Detail bundle: charge + event timeline + linked transactions.               |
+| `chargeNow(id)`                      | Force-bill the current cycle now instead of waiting for the due date.       |
+| `markPaid(id, params)`               | Mark cycle paid (off-Garu reconciliation).                                  |
+| `postpone(id, params)`               | Move the next cycle's due date forward.                                     |
+| `pause(id, params?)` / `resume(id)`  | Suspend / re-enable a series.                                               |
+| `cancelRecurrence(id, params?)`      | Hard-stop future cycles (recurring only).                                   |
+| `cancelAtPeriodEnd(id, { enabled })` | Stripe-style soft-cancel; reversible.                                       |
+| `changePaymentMethod(id, params)`    | Swap the saved card.                                                        |
+| `clearPaymentMethod(id)`             | Remove the saved card; future cycles email-with-link.                       |
+| `listAttempts(id, params?)`          | Per-attempt billing log — every silent-charge / retry / mark-paid (v0.8.2). |
 
 ```ts
-// Recurring with 7-day trial
+// Recurring with 7-day trial. `maxRecoveryDays` caps how long past the due
+// date the daily recovery sweep keeps auto-billing a missed charge (default 14).
 const series = await garu.scheduledCharges.create({
   customerId: 42,
   productId: 17,
@@ -223,11 +225,20 @@ const series = await garu.scheduledCharges.create({
   methods: ['card', 'pix'],
   recurrence: { interval: 'monthly' },
   trialDays: 7,
+  maxRecoveryDays: 30
 });
 
+// Force-bill the current cycle now instead of waiting for the due date.
+// Idempotent: a cycle already dispatched today reports `already_sent`.
+const result = await garu.scheduledCharges.chargeNow(series.id);
+if (result.outcome === 'failed') {
+  // result.reason is e.g. 'card_expired' or a gateway decline code
+  console.error(`${result.message} (${result.reason})`);
+}
+
 // Audit why cycle 3 failed (v0.8.2)
 const { data } = await garu.scheduledCharges.listAttempts(series.id, {
-  cycleNumber: 3,
+  cycleNumber: 3
 });
 const declines = data.filter((a) => a.status === 'declined');
 // → each declines[i].failureCode is one of GaruFailureCode (insufficient_funds,
@@ -253,6 +264,83 @@ function shouldAskForNewCard(code: GaruFailureCode): boolean {
 
 Full table at [docs.garu.com.br/api-reference/webhooks/codigos-de-falha](https://docs.garu.com.br/api-reference/webhooks/codigos-de-falha).
 
+## Pix Automático
+
+Pix Automático is Brazil's BACEN auto-debit recurring Pix. The customer authorizes **once** — they open their bank app, find the "Pix Automático" / "Recorrência Pix" section, and approve a consent QR/link. Every cycle from the second onward debits silently, with no further customer action.
+
+**When to use it:** recurring billing where you want bank-level auto-debit instead of a saved card — subscriptions, mensalidades, memberships. Use card recurrence when you need installments or international cards; use Pix Automático for low-friction domestic recurring Pix.
+
+It rides the **same SDK surface** as card-backed recurrence — no new methods, no new webhook events. The only differences are the `pix_automatic` method literal and a per-product enable flag.
+
+### 1. Enable it on a product
+
+Pix Automático only shows up on a product's checkout when the product has it enabled (`Product.pixAutomatic`). This is a property of the product (managed in the dashboard / product API); the SDK surfaces it as a boolean:
+
+```ts
+const product = await garu.products.get('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f');
+if (!product.pixAutomatic) {
+  // Pix Automático is off for this product — enable it before scheduling a
+  // `pix_automatic` charge, or the create call will 400.
+}
+```
+
+### 2. Create a Pix Automático scheduled charge
+
+`pix_automatic` is **recurring-only** and **requires `productId`** (the product must have `pixAutomatic` enabled). The charge starts in a waiting state until the customer approves the consent; cycles 2+ then debit silently.
+
+```ts
+const series = await garu.scheduledCharges.create({
+  customerId: 42,
+  productId: 17,
+  amount: 49.9,
+  type: 'recurring',
+  dueDate: '2026-06-15',
+  methods: ['pix_automatic'],
+  recurrence: { interval: 'monthly' }
+});
+```
+
+Cancel and the rest of the lifecycle use the **same methods** as card-backed series — `cancelRecurrence(id)`, `cancelAtPeriodEnd(id, { enabled })`, `pause(id)` / `resume(id)`. The customer can also revoke the authorization directly in their bank app; Garu surfaces that as a `subscription.cancelled` event.
+
+### 3. Handle the webhooks
+
+Pix Automático fires the **same events** as card recurrence — there are no Pix-Automático-specific event names. Branch on the payload's `paymentMethod` field (`'pix_automatic'`) when you need method-specific handling:
+
+```ts
+app.post('/webhooks/garu', express.raw({ type: 'application/json' }), (req, res) => {
+  const { event } = Garu.webhooks.verify({
+    payload: req.body,
+    signature: req.header('x-garu-signature') ?? '',
+    secret: process.env.GARU_WEBHOOK_SECRET!
+  });
+
+  // `event` is the verified payload. It carries the Garu `eventType` and a
+  // `paymentMethod` field; branch on `paymentMethod` to special-case Pix
+  // Automático. (Field paths follow your webhook payload reference.)
+  const { eventType, paymentMethod } = event as {
+    eventType?: string;
+    paymentMethod?: string;
+  };
+
+  if (paymentMethod === 'pix_automatic') {
+    switch (eventType) {
+      case 'transaction.payment.succeeded':
+        // a Pix Automático cycle debited
+        break;
+      case 'subscription.payment_failed':
+        // Pix Automático does NOT retry a refused debit at the network level —
+        // Garu flips the series to `past_due` and the usual dunning applies.
+        break;
+    }
+  }
+
+  res.sendStatus(200);
+});
+```
+
+> [!NOTE]
+> Failure model: Pix Automático does not retry a refused debit at the payment-network level. On a refused cycle Garu fires `subscription.payment_failed` and moves the series to `past_due`; your existing dunning handles recovery.
+
 ## Meta
 
 Discover available payment methods and webhook events. No authentication required.
@@ -277,7 +365,7 @@ app.post('/webhooks/garu', express.raw({ type: 'application/json' }), (req, res)
     const { event } = Garu.webhooks.verify({
       payload: req.body, // raw Buffer — do NOT re-serialize parsed JSON
       signature: req.header('x-garu-signature') ?? '',
-      secret: process.env.GARU_WEBHOOK_SECRET!,
+      secret: process.env.GARU_WEBHOOK_SECRET!
     });
 
     console.log('Received', event);
@@ -294,7 +382,7 @@ app.post('/webhooks/garu', express.raw({ type: 'application/json' }), (req, res)
 
 ## Webhook events
 
-The seller-facing delivery log for outbound webhooks. Use it to audit deliveries, surface failures, and replay events when a customer's endpoint missed one. Webhook endpoint *configuration* (URL, subscribed events, secret) is still dashboard-only — this resource only covers the event log + manual retries.
+The seller-facing delivery log for outbound webhooks. Use it to audit deliveries, surface failures, and replay events when a customer's endpoint missed one. Webhook endpoint _configuration_ (URL, subscribed events, secret) is still dashboard-only — this resource only covers the event log + manual retries.
 
 ```ts
 // Surface anything that didn't make it through
@@ -306,7 +394,7 @@ console.log(event.responseStatus, event.responseBody);
 
 // Audit-trail-preserving replay (recommended)
 const clone = await garu.webhookEvents.resend(42);
-clone.id !== event.id;             // true — fresh row with its own id
+clone.id !== event.id; // true — fresh row with its own id
 clone.manualResendOf === event.id; // true — points back at the source
 ```
 
@@ -317,12 +405,12 @@ Outbound deliveries of a resent event carry `Idempotency-Key: resend_<originalId
 > [!NOTE]
 > The SDK auto-attaches `X-Idempotency-Key` (UUIDv4) on `resend()` so transient transport retries can't create duplicate clones. Pass `{ idempotencyKey }` to dedupe across your own retry layer.
 
-| Method                          | Purpose                                                                            |
-| ------------------------------- | ---------------------------------------------------------------------------------- |
-| `list(params?)`                 | Paginated event log. Filter by `status`, `eventType`, `endpointId`. Newest first. |
-| `get(id)`                       | One event — full payload, endpoint snapshot, most recent response.                |
-| `resend(id, params?)`           | Clone-on-resend. Returns the new event; original is untouched. **Preferred.**     |
-| `retry(id)`                     | Legacy in-place reset (mutates the original row). Soft-deprecated.                |
+| Method                | Purpose                                                                           |
+| --------------------- | --------------------------------------------------------------------------------- |
+| `list(params?)`       | Paginated event log. Filter by `status`, `eventType`, `endpointId`. Newest first. |
+| `get(id)`             | One event — full payload, endpoint snapshot, most recent response.                |
+| `resend(id, params?)` | Clone-on-resend. Returns the new event; original is untouched. **Preferred.**     |
+| `retry(id)`           | Legacy in-place reset (mutates the original row). Soft-deprecated.                |
 
 ## Error handling
 
@@ -333,7 +421,7 @@ import {
   GaruAPIError,
   GaruNotFoundError,
   GaruRateLimitError,
-  GaruValidationError,
+  GaruValidationError
 } from '@garuhq/node';
 
 try {
@@ -354,16 +442,16 @@ try {
 }
 ```
 
-| Error class                         | HTTP status        |
-| ----------------------------------- | ------------------ |
-| `GaruAuthenticationError`           | `401`              |
-| `GaruPermissionError`               | `403`              |
-| `GaruNotFoundError`                 | `404`              |
-| `GaruValidationError`               | `400` / `422`      |
-| `GaruRateLimitError`                | `429`              |
-| `GaruServerError`                   | `5xx`              |
-| `GaruConnectionError`               | Network failure    |
-| `GaruSignatureVerificationError`    | Webhook mismatch   |
+| Error class                      | HTTP status      |
+| -------------------------------- | ---------------- |
+| `GaruAuthenticationError`        | `401`            |
+| `GaruPermissionError`            | `403`            |
+| `GaruNotFoundError`              | `404`            |
+| `GaruValidationError`            | `400` / `422`    |
+| `GaruRateLimitError`             | `429`            |
+| `GaruServerError`                | `5xx`            |
+| `GaruConnectionError`            | Network failure  |
+| `GaruSignatureVerificationError` | Webhook mismatch |
 
 ## Retries
 
@@ -381,7 +469,7 @@ import type {
   Customer,
   CardInfo,
   PaymentMethod,
-  MetaResponse,
+  MetaResponse
 } from '@garuhq/node';
 ```
 

package/dist/index.cjs

@@ -596,6 +596,20 @@ var ScheduledCharges = class {
    *   methods: ['pix', 'boleto'],
    *   description: 'Mensalidade Junho'
    * });
+   *
+   * @example
+   * // Pix Automático (BACEN auto-debit). Requires `type: 'recurring'` and a
+   * // `productId` whose product has Pix Automático enabled. The customer
+   * // authorizes once via their bank app; cycles 2+ debit silently.
+   * const series = await garu.scheduledCharges.create({
+   *   customerId: 42,
+   *   productId: 17,
+   *   amount: 49.9,
+   *   type: 'recurring',
+   *   dueDate: '2026-06-15',
+   *   methods: ['pix_automatic'],
+   *   recurrence: { interval: 'monthly' }
+   * });
    */
   async create(params) {
     const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
@@ -653,9 +667,9 @@ var ScheduledCharges = class {
    */
   async get(id) {
     return this.http.call(
-      (signal) => this.http.client.GET(`/api/scheduled-charges/${id}`, { signal }).then(
-        (r) => r
-      )
+      (signal) => this.http.client.GET(`/api/scheduled-charges/${encodeURIComponent(id)}`, {
+        signal
+      }).then((r) => r)
     );
   }
   /**
@@ -671,10 +685,13 @@ var ScheduledCharges = class {
    */
   async postpone(id, params) {
     return this.http.call(
-      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/postpone`, {
-        body: params,
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/postpone`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -687,10 +704,13 @@ var ScheduledCharges = class {
    */
   async pause(id, params = {}) {
     return this.http.call(
-      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/pause`, {
-        body: params,
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/pause`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -701,10 +721,13 @@ var ScheduledCharges = class {
    */
   async resume(id) {
     return this.http.call(
-      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/resume`, {
-        body: {},
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/resume`,
+        {
+          body: {},
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -732,10 +755,52 @@ var ScheduledCharges = class {
    */
   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)
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/mark-paid`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
+    );
+  }
+  /**
+   * Force-bill the current cycle right now instead of waiting for its due
+   * date. Runs the same dispatch the daily billing cron would (customer
+   * email/notification + outbound webhook + timeline event). Allowed only
+   * from a billable status (`scheduled` / `due_today`); a recurring series
+   * must have an open cycle (else the backend returns 400).
+   *
+   * Idempotent: if this cycle's d-day was already dispatched it reports
+   * `already_sent` and does not re-charge. Inspect `outcome` to branch.
+   *
+   * @example
+   * const result = await garu.scheduledCharges.chargeNow('sch_abc123');
+   * switch (result.outcome) {
+   *   case 'dispatched':
+   *     console.log(`Cobrança enviada (ciclo ${result.cycleNumber}).`);
+   *     break;
+   *   case 'already_sent':
+   *     console.log('Já havia sido enviada — nada a fazer.');
+   *     break;
+   *   case 'failed':
+   *     // result.reason is e.g. 'card_expired' or a gateway decline code
+   *     console.error(`Falha na cobrança: ${result.reason}. ${result.message}`);
+   *     break;
+   *   case 'not_sent':
+   *     console.warn(`Não enviada (${result.reason}): ${result.message}`);
+   *     break;
+   * }
+   */
+  async chargeNow(id) {
+    return this.http.call(
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/charge-now`,
+        {
+          body: {},
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -751,10 +816,13 @@ var ScheduledCharges = class {
    */
   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)
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/cancel-recurrence`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -768,10 +836,13 @@ var ScheduledCharges = class {
    */
   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)
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/cancel-at-period-end`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -784,10 +855,13 @@ var ScheduledCharges = class {
    */
   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)
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/payment-method`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -800,10 +874,13 @@ var ScheduledCharges = class {
    */
   async clearPaymentMethod(id) {
     return this.http.call(
-      (signal) => this.http.client.DELETE(`/api/scheduled-charges/${id}/payment-method`, {
-        body: {},
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.DELETE(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/payment-method`,
+        {
+          body: {},
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -825,7 +902,7 @@ var ScheduledCharges = class {
     if (params.limit !== void 0) qs.set("limit", String(params.limit));
     if (params.cycleNumber !== void 0) qs.set("cycleNumber", String(params.cycleNumber));
     const query = qs.toString();
-    const url = `/api/scheduled-charges/${id}/attempts${query ? `?${query}` : ""}`;
+    const url = `/api/scheduled-charges/${encodeURIComponent(id)}/attempts${query ? `?${query}` : ""}`;
     return this.http.call(
       (signal) => this.http.client.GET(url, { signal }).then(
         (r) => r

package/dist/index.d.cts

@@ -99,8 +99,13 @@ declare class HttpClient {
  */
 
 type PaymentMethod = 'pix' | 'credit_card' | 'boleto';
-/** Payment-method identifier as sent to the backend over the wire. */
-type WirePaymentMethodId = 'pix' | 'creditcard' | 'boleto';
+/**
+ * Payment-method identifier as it appears on the wire. `pix_automatic`
+ * (Pix Automático auto-debit) surfaces here on transactions/charges read
+ * back from Pix Automático recurring cycles. It is never produced by
+ * `toWirePaymentMethod`, since one-off charges can't use it.
+ */
+type WirePaymentMethodId = 'pix' | 'creditcard' | 'boleto' | 'pix_automatic';
 type ChargeStatus = 'pending' | 'authorized' | 'paid' | 'failed' | 'refunded' | 'cancelled' | 'expired';
 interface Customer {
     /** Full legal name. 3–255 chars. */
@@ -277,7 +282,16 @@ interface ListCustomersParams {
 }
 type ScheduledChargeStatus = 'scheduled' | 'due_today' | 'overdue' | 'paid' | 'paused' | 'canceled' | 'trial' | 'pending_tokenization' | 'recurrence_canceled';
 type ScheduledChargeType = 'one_time' | 'recurring';
-type ScheduledPaymentMethod = 'pix' | 'boleto' | 'card';
+/**
+ * Payment method for a scheduled charge.
+ *
+ * `pix_automatic` is Pix Automático — Brazil's BACEN auto-debit recurring
+ * Pix. The customer authorizes **once** via a consent link/QR in their bank
+ * app; every cycle from the second onward debits silently with no further
+ * action. It is only valid when `type='recurring'` **and** `productId` is
+ * set; the product must also have Pix Automático enabled (`pixAutomatic`).
+ */
+type ScheduledPaymentMethod = 'pix' | 'boleto' | 'card' | 'pix_automatic';
 type RecurrenceInterval = 'weekly' | 'biweekly' | 'monthly' | 'bimonthly' | 'quarterly' | 'biannual' | 'yearly';
 interface RecurrenceConfig {
     interval: RecurrenceInterval;
@@ -312,6 +326,11 @@ interface ScheduledChargeRecord {
     methods: ScheduledPaymentMethod[];
     status: ScheduledChargeStatus;
     externalReference: string | null;
+    /**
+     * Max days past `dueDate` the daily recovery sweep will still auto-bill a
+     * missed charge. `null` means the system default (14) applies.
+     */
+    maxRecoveryDays: number | null;
     metadata: Record<string, unknown> | null;
     createdAt: string;
     updatedAt: string;
@@ -364,7 +383,7 @@ interface ScheduledChargeAttempt {
     attemptNumber: number;
     attemptedAt: string;
     source: ScheduledChargeAttemptSource;
-    paymentMethod: 'card' | 'pix' | 'boleto' | 'manual';
+    paymentMethod: 'card' | 'pix' | 'boleto' | 'pix_automatic' | 'manual';
     paymentMethodId: number | null;
     cardLast4: string | null;
     cardBrand: string | null;
@@ -395,7 +414,11 @@ interface CreateScheduledChargeParams {
     type: ScheduledChargeType;
     /** YYYY-MM-DD in São Paulo time. Must be today or future. */
     dueDate: string;
-    /** `card` is recurring-only and requires `productId`. */
+    /**
+     * `card` is recurring-only and requires `productId`. `pix_automatic`
+     * (Pix Automático auto-debit) likewise requires `type='recurring'` **and**
+     * `productId`, and the product must have Pix Automático enabled.
+     */
     methods: ScheduledPaymentMethod[];
     /** Cadence for `type='recurring'`. Must be omitted when `type='one_time'`. */
     recurrence?: RecurrenceConfig;
@@ -407,6 +430,11 @@ interface CreateScheduledChargeParams {
     trialDays?: number;
     externalReference?: string;
     metadata?: Record<string, unknown>;
+    /**
+     * Max days past `dueDate` the daily recovery sweep will still auto-bill a
+     * missed charge (integer 1..365). Omit for the system default (14).
+     */
+    maxRecoveryDays?: number;
     /**
      * Optional idempotency key for safe retries. The SDK auto-generates a
      * UUIDv4 when omitted and forwards it as `X-Idempotency-Key`.
@@ -456,6 +484,30 @@ interface ChangePaymentMethodScheduledChargeParams {
     /** PaymentMethod id to bind. Must belong to the same customerId. */
     paymentMethodId: number;
 }
+/**
+ * Result of `scheduledCharges.chargeNow(id)` — what the immediate dispatch did:
+ *
+ * - `dispatched`   — sent now (customer email/notification + outbound webhook + timeline event).
+ * - `already_sent` — this cycle's d-day was already dispatched; no-op (the action is idempotent).
+ * - `not_sent`     — couldn't send; see `reason` (e.g. `no_email`, `lock_lost`, `no_saved_payment_method`).
+ * - `failed`       — card charge failed; see `reason` (e.g. `card_expired`, or a gateway decline code).
+ */
+type ChargeNowOutcome = 'dispatched' | 'already_sent' | 'not_sent' | 'failed';
+/**
+ * Why a `not_sent` / `failed` charge-now didn't go through. The documented
+ * literals are stable; `failed` may also surface a raw gateway decline code,
+ * so the type stays open (`string & {}`) without losing autocomplete.
+ */
+type ChargeNowReason = 'no_email' | 'lock_lost' | 'no_saved_payment_method' | 'card_expired' | 'payment_method_missing' | 'customer_missing' | (string & {});
+interface ChargeNowResult {
+    outcome: ChargeNowOutcome;
+    /** Cycle that was dispatched/attempted, or `null` for one-time charges. */
+    cycleNumber: number | null;
+    /** Present on `not_sent` / `failed`. See {@link ChargeNowReason}. */
+    reason?: ChargeNowReason;
+    /** Ready-to-show pt-BR message describing the outcome. */
+    message: string;
+}
 interface Product {
     id: number;
     uuid: string;
@@ -469,6 +521,13 @@ interface Product {
     pix: boolean;
     boleto: boolean;
     creditCard: boolean;
+    /**
+     * When `true`, the public subscription checkout exposes Pix Automático
+     * (BACEN auto-debit recurring Pix) as a payment option. Enabled by
+     * default; sellers can disable it per product. Only the subscription
+     * checkout mode reads this flag. See {@link ScheduledPaymentMethod}.
+     */
+    pixAutomatic: boolean;
     installments: number[];
     tags?: string[];
     isSubscription?: boolean;
@@ -957,6 +1016,20 @@ declare class ScheduledCharges {
      *   methods: ['pix', 'boleto'],
      *   description: 'Mensalidade Junho'
      * });
+     *
+     * @example
+     * // Pix Automático (BACEN auto-debit). Requires `type: 'recurring'` and a
+     * // `productId` whose product has Pix Automático enabled. The customer
+     * // authorizes once via their bank app; cycles 2+ debit silently.
+     * const series = await garu.scheduledCharges.create({
+     *   customerId: 42,
+     *   productId: 17,
+     *   amount: 49.9,
+     *   type: 'recurring',
+     *   dueDate: '2026-06-15',
+     *   methods: ['pix_automatic'],
+     *   recurrence: { interval: 'monthly' }
+     * });
      */
     create(params: CreateScheduledChargeParams): Promise<ScheduledChargeRecord>;
     /**
@@ -1035,6 +1108,35 @@ declare class ScheduledCharges {
      * });
      */
     markPaid(id: string, params: MarkPaidScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * Force-bill the current cycle right now instead of waiting for its due
+     * date. Runs the same dispatch the daily billing cron would (customer
+     * email/notification + outbound webhook + timeline event). Allowed only
+     * from a billable status (`scheduled` / `due_today`); a recurring series
+     * must have an open cycle (else the backend returns 400).
+     *
+     * Idempotent: if this cycle's d-day was already dispatched it reports
+     * `already_sent` and does not re-charge. Inspect `outcome` to branch.
+     *
+     * @example
+     * const result = await garu.scheduledCharges.chargeNow('sch_abc123');
+     * switch (result.outcome) {
+     *   case 'dispatched':
+     *     console.log(`Cobrança enviada (ciclo ${result.cycleNumber}).`);
+     *     break;
+     *   case 'already_sent':
+     *     console.log('Já havia sido enviada — nada a fazer.');
+     *     break;
+     *   case 'failed':
+     *     // result.reason is e.g. 'card_expired' or a gateway decline code
+     *     console.error(`Falha na cobrança: ${result.reason}. ${result.message}`);
+     *     break;
+     *   case 'not_sent':
+     *     console.warn(`Não enviada (${result.reason}): ${result.message}`);
+     *     break;
+     * }
+     */
+    chargeNow(id: string): Promise<ChargeNowResult>;
     /**
      * Stop future cycles for a recurring series. The currently in-flight
      * cycle (if any) remains active until paid, postponed, or marked-paid;
@@ -1289,4 +1391,4 @@ declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CancelAtPeriodEndScheduledChargeParams, type CancelRecurrenceScheduledChargeParams, type CardInfo, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateScheduledChargeParams, type Customer, type CustomerList, type CustomerRecord, type FailurePayload, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, type GaruFailureCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type ListChargesParams, type ListCustomersParams, type ListProductsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type ResendWebhookEventParams, type ScheduledChargeActor, type ScheduledChargeAttempt, type ScheduledChargeAttemptList, type ScheduledChargeAttemptSource, type ScheduledChargeAttemptStatus, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type SetProductPortalConfigParams, type UpdateCustomerParams, type VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, type WirePaymentMethodId, webhooks };
+export { type CancelAtPeriodEndScheduledChargeParams, type CancelRecurrenceScheduledChargeParams, type CardInfo, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeNowOutcome, type ChargeNowReason, type ChargeNowResult, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateScheduledChargeParams, type Customer, type CustomerList, type CustomerRecord, type FailurePayload, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, type GaruFailureCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type ListChargesParams, type ListCustomersParams, type ListProductsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type ResendWebhookEventParams, type ScheduledChargeActor, type ScheduledChargeAttempt, type ScheduledChargeAttemptList, type ScheduledChargeAttemptSource, type ScheduledChargeAttemptStatus, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type SetProductPortalConfigParams, type UpdateCustomerParams, type VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, type WirePaymentMethodId, webhooks };

package/dist/index.d.ts

@@ -99,8 +99,13 @@ declare class HttpClient {
  */
 
 type PaymentMethod = 'pix' | 'credit_card' | 'boleto';
-/** Payment-method identifier as sent to the backend over the wire. */
-type WirePaymentMethodId = 'pix' | 'creditcard' | 'boleto';
+/**
+ * Payment-method identifier as it appears on the wire. `pix_automatic`
+ * (Pix Automático auto-debit) surfaces here on transactions/charges read
+ * back from Pix Automático recurring cycles. It is never produced by
+ * `toWirePaymentMethod`, since one-off charges can't use it.
+ */
+type WirePaymentMethodId = 'pix' | 'creditcard' | 'boleto' | 'pix_automatic';
 type ChargeStatus = 'pending' | 'authorized' | 'paid' | 'failed' | 'refunded' | 'cancelled' | 'expired';
 interface Customer {
     /** Full legal name. 3–255 chars. */
@@ -277,7 +282,16 @@ interface ListCustomersParams {
 }
 type ScheduledChargeStatus = 'scheduled' | 'due_today' | 'overdue' | 'paid' | 'paused' | 'canceled' | 'trial' | 'pending_tokenization' | 'recurrence_canceled';
 type ScheduledChargeType = 'one_time' | 'recurring';
-type ScheduledPaymentMethod = 'pix' | 'boleto' | 'card';
+/**
+ * Payment method for a scheduled charge.
+ *
+ * `pix_automatic` is Pix Automático — Brazil's BACEN auto-debit recurring
+ * Pix. The customer authorizes **once** via a consent link/QR in their bank
+ * app; every cycle from the second onward debits silently with no further
+ * action. It is only valid when `type='recurring'` **and** `productId` is
+ * set; the product must also have Pix Automático enabled (`pixAutomatic`).
+ */
+type ScheduledPaymentMethod = 'pix' | 'boleto' | 'card' | 'pix_automatic';
 type RecurrenceInterval = 'weekly' | 'biweekly' | 'monthly' | 'bimonthly' | 'quarterly' | 'biannual' | 'yearly';
 interface RecurrenceConfig {
     interval: RecurrenceInterval;
@@ -312,6 +326,11 @@ interface ScheduledChargeRecord {
     methods: ScheduledPaymentMethod[];
     status: ScheduledChargeStatus;
     externalReference: string | null;
+    /**
+     * Max days past `dueDate` the daily recovery sweep will still auto-bill a
+     * missed charge. `null` means the system default (14) applies.
+     */
+    maxRecoveryDays: number | null;
     metadata: Record<string, unknown> | null;
     createdAt: string;
     updatedAt: string;
@@ -364,7 +383,7 @@ interface ScheduledChargeAttempt {
     attemptNumber: number;
     attemptedAt: string;
     source: ScheduledChargeAttemptSource;
-    paymentMethod: 'card' | 'pix' | 'boleto' | 'manual';
+    paymentMethod: 'card' | 'pix' | 'boleto' | 'pix_automatic' | 'manual';
     paymentMethodId: number | null;
     cardLast4: string | null;
     cardBrand: string | null;
@@ -395,7 +414,11 @@ interface CreateScheduledChargeParams {
     type: ScheduledChargeType;
     /** YYYY-MM-DD in São Paulo time. Must be today or future. */
     dueDate: string;
-    /** `card` is recurring-only and requires `productId`. */
+    /**
+     * `card` is recurring-only and requires `productId`. `pix_automatic`
+     * (Pix Automático auto-debit) likewise requires `type='recurring'` **and**
+     * `productId`, and the product must have Pix Automático enabled.
+     */
     methods: ScheduledPaymentMethod[];
     /** Cadence for `type='recurring'`. Must be omitted when `type='one_time'`. */
     recurrence?: RecurrenceConfig;
@@ -407,6 +430,11 @@ interface CreateScheduledChargeParams {
     trialDays?: number;
     externalReference?: string;
     metadata?: Record<string, unknown>;
+    /**
+     * Max days past `dueDate` the daily recovery sweep will still auto-bill a
+     * missed charge (integer 1..365). Omit for the system default (14).
+     */
+    maxRecoveryDays?: number;
     /**
      * Optional idempotency key for safe retries. The SDK auto-generates a
      * UUIDv4 when omitted and forwards it as `X-Idempotency-Key`.
@@ -456,6 +484,30 @@ interface ChangePaymentMethodScheduledChargeParams {
     /** PaymentMethod id to bind. Must belong to the same customerId. */
     paymentMethodId: number;
 }
+/**
+ * Result of `scheduledCharges.chargeNow(id)` — what the immediate dispatch did:
+ *
+ * - `dispatched`   — sent now (customer email/notification + outbound webhook + timeline event).
+ * - `already_sent` — this cycle's d-day was already dispatched; no-op (the action is idempotent).
+ * - `not_sent`     — couldn't send; see `reason` (e.g. `no_email`, `lock_lost`, `no_saved_payment_method`).
+ * - `failed`       — card charge failed; see `reason` (e.g. `card_expired`, or a gateway decline code).
+ */
+type ChargeNowOutcome = 'dispatched' | 'already_sent' | 'not_sent' | 'failed';
+/**
+ * Why a `not_sent` / `failed` charge-now didn't go through. The documented
+ * literals are stable; `failed` may also surface a raw gateway decline code,
+ * so the type stays open (`string & {}`) without losing autocomplete.
+ */
+type ChargeNowReason = 'no_email' | 'lock_lost' | 'no_saved_payment_method' | 'card_expired' | 'payment_method_missing' | 'customer_missing' | (string & {});
+interface ChargeNowResult {
+    outcome: ChargeNowOutcome;
+    /** Cycle that was dispatched/attempted, or `null` for one-time charges. */
+    cycleNumber: number | null;
+    /** Present on `not_sent` / `failed`. See {@link ChargeNowReason}. */
+    reason?: ChargeNowReason;
+    /** Ready-to-show pt-BR message describing the outcome. */
+    message: string;
+}
 interface Product {
     id: number;
     uuid: string;
@@ -469,6 +521,13 @@ interface Product {
     pix: boolean;
     boleto: boolean;
     creditCard: boolean;
+    /**
+     * When `true`, the public subscription checkout exposes Pix Automático
+     * (BACEN auto-debit recurring Pix) as a payment option. Enabled by
+     * default; sellers can disable it per product. Only the subscription
+     * checkout mode reads this flag. See {@link ScheduledPaymentMethod}.
+     */
+    pixAutomatic: boolean;
     installments: number[];
     tags?: string[];
     isSubscription?: boolean;
@@ -957,6 +1016,20 @@ declare class ScheduledCharges {
      *   methods: ['pix', 'boleto'],
      *   description: 'Mensalidade Junho'
      * });
+     *
+     * @example
+     * // Pix Automático (BACEN auto-debit). Requires `type: 'recurring'` and a
+     * // `productId` whose product has Pix Automático enabled. The customer
+     * // authorizes once via their bank app; cycles 2+ debit silently.
+     * const series = await garu.scheduledCharges.create({
+     *   customerId: 42,
+     *   productId: 17,
+     *   amount: 49.9,
+     *   type: 'recurring',
+     *   dueDate: '2026-06-15',
+     *   methods: ['pix_automatic'],
+     *   recurrence: { interval: 'monthly' }
+     * });
      */
     create(params: CreateScheduledChargeParams): Promise<ScheduledChargeRecord>;
     /**
@@ -1035,6 +1108,35 @@ declare class ScheduledCharges {
      * });
      */
     markPaid(id: string, params: MarkPaidScheduledChargeParams): Promise<ScheduledChargeRecord>;
+    /**
+     * Force-bill the current cycle right now instead of waiting for its due
+     * date. Runs the same dispatch the daily billing cron would (customer
+     * email/notification + outbound webhook + timeline event). Allowed only
+     * from a billable status (`scheduled` / `due_today`); a recurring series
+     * must have an open cycle (else the backend returns 400).
+     *
+     * Idempotent: if this cycle's d-day was already dispatched it reports
+     * `already_sent` and does not re-charge. Inspect `outcome` to branch.
+     *
+     * @example
+     * const result = await garu.scheduledCharges.chargeNow('sch_abc123');
+     * switch (result.outcome) {
+     *   case 'dispatched':
+     *     console.log(`Cobrança enviada (ciclo ${result.cycleNumber}).`);
+     *     break;
+     *   case 'already_sent':
+     *     console.log('Já havia sido enviada — nada a fazer.');
+     *     break;
+     *   case 'failed':
+     *     // result.reason is e.g. 'card_expired' or a gateway decline code
+     *     console.error(`Falha na cobrança: ${result.reason}. ${result.message}`);
+     *     break;
+     *   case 'not_sent':
+     *     console.warn(`Não enviada (${result.reason}): ${result.message}`);
+     *     break;
+     * }
+     */
+    chargeNow(id: string): Promise<ChargeNowResult>;
     /**
      * Stop future cycles for a recurring series. The currently in-flight
      * cycle (if any) remains active until paid, postponed, or marked-paid;
@@ -1289,4 +1391,4 @@ declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CancelAtPeriodEndScheduledChargeParams, type CancelRecurrenceScheduledChargeParams, type CardInfo, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateScheduledChargeParams, type Customer, type CustomerList, type CustomerRecord, type FailurePayload, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, type GaruFailureCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type ListChargesParams, type ListCustomersParams, type ListProductsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type ResendWebhookEventParams, type ScheduledChargeActor, type ScheduledChargeAttempt, type ScheduledChargeAttemptList, type ScheduledChargeAttemptSource, type ScheduledChargeAttemptStatus, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type SetProductPortalConfigParams, type UpdateCustomerParams, type VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, type WirePaymentMethodId, webhooks };
+export { type CancelAtPeriodEndScheduledChargeParams, type CancelRecurrenceScheduledChargeParams, type CardInfo, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeNowOutcome, type ChargeNowReason, type ChargeNowResult, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateScheduledChargeParams, type Customer, type CustomerList, type CustomerRecord, type FailurePayload, Garu, GaruAPIError, GaruAuthenticationError, GaruConnectionError, GaruError, type GaruErrorCode, type GaruFailureCode, GaruNotFoundError, type GaruOptions, GaruPermissionError, GaruRateLimitError, GaruServerError, GaruSignatureVerificationError, GaruValidationError, type ListChargesParams, type ListCustomersParams, type ListProductsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type ResendWebhookEventParams, type ScheduledChargeActor, type ScheduledChargeAttempt, type ScheduledChargeAttemptList, type ScheduledChargeAttemptSource, type ScheduledChargeAttemptStatus, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type SetProductPortalConfigParams, type UpdateCustomerParams, type VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, type WirePaymentMethodId, webhooks };

package/dist/index.js

@@ -590,6 +590,20 @@ var ScheduledCharges = class {
    *   methods: ['pix', 'boleto'],
    *   description: 'Mensalidade Junho'
    * });
+   *
+   * @example
+   * // Pix Automático (BACEN auto-debit). Requires `type: 'recurring'` and a
+   * // `productId` whose product has Pix Automático enabled. The customer
+   * // authorizes once via their bank app; cycles 2+ debit silently.
+   * const series = await garu.scheduledCharges.create({
+   *   customerId: 42,
+   *   productId: 17,
+   *   amount: 49.9,
+   *   type: 'recurring',
+   *   dueDate: '2026-06-15',
+   *   methods: ['pix_automatic'],
+   *   recurrence: { interval: 'monthly' }
+   * });
    */
   async create(params) {
     const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
@@ -647,9 +661,9 @@ var ScheduledCharges = class {
    */
   async get(id) {
     return this.http.call(
-      (signal) => this.http.client.GET(`/api/scheduled-charges/${id}`, { signal }).then(
-        (r) => r
-      )
+      (signal) => this.http.client.GET(`/api/scheduled-charges/${encodeURIComponent(id)}`, {
+        signal
+      }).then((r) => r)
     );
   }
   /**
@@ -665,10 +679,13 @@ var ScheduledCharges = class {
    */
   async postpone(id, params) {
     return this.http.call(
-      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/postpone`, {
-        body: params,
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/postpone`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -681,10 +698,13 @@ var ScheduledCharges = class {
    */
   async pause(id, params = {}) {
     return this.http.call(
-      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/pause`, {
-        body: params,
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/pause`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -695,10 +715,13 @@ var ScheduledCharges = class {
    */
   async resume(id) {
     return this.http.call(
-      (signal) => this.http.client.POST(`/api/scheduled-charges/${id}/resume`, {
-        body: {},
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/resume`,
+        {
+          body: {},
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -726,10 +749,52 @@ var ScheduledCharges = class {
    */
   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)
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/mark-paid`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
+    );
+  }
+  /**
+   * Force-bill the current cycle right now instead of waiting for its due
+   * date. Runs the same dispatch the daily billing cron would (customer
+   * email/notification + outbound webhook + timeline event). Allowed only
+   * from a billable status (`scheduled` / `due_today`); a recurring series
+   * must have an open cycle (else the backend returns 400).
+   *
+   * Idempotent: if this cycle's d-day was already dispatched it reports
+   * `already_sent` and does not re-charge. Inspect `outcome` to branch.
+   *
+   * @example
+   * const result = await garu.scheduledCharges.chargeNow('sch_abc123');
+   * switch (result.outcome) {
+   *   case 'dispatched':
+   *     console.log(`Cobrança enviada (ciclo ${result.cycleNumber}).`);
+   *     break;
+   *   case 'already_sent':
+   *     console.log('Já havia sido enviada — nada a fazer.');
+   *     break;
+   *   case 'failed':
+   *     // result.reason is e.g. 'card_expired' or a gateway decline code
+   *     console.error(`Falha na cobrança: ${result.reason}. ${result.message}`);
+   *     break;
+   *   case 'not_sent':
+   *     console.warn(`Não enviada (${result.reason}): ${result.message}`);
+   *     break;
+   * }
+   */
+  async chargeNow(id) {
+    return this.http.call(
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/charge-now`,
+        {
+          body: {},
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -745,10 +810,13 @@ var ScheduledCharges = class {
    */
   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)
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/cancel-recurrence`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -762,10 +830,13 @@ var ScheduledCharges = class {
    */
   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)
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/cancel-at-period-end`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -778,10 +849,13 @@ var ScheduledCharges = class {
    */
   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)
+      (signal) => this.http.client.POST(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/payment-method`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -794,10 +868,13 @@ var ScheduledCharges = class {
    */
   async clearPaymentMethod(id) {
     return this.http.call(
-      (signal) => this.http.client.DELETE(`/api/scheduled-charges/${id}/payment-method`, {
-        body: {},
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.DELETE(
+        `/api/scheduled-charges/${encodeURIComponent(id)}/payment-method`,
+        {
+          body: {},
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -819,7 +896,7 @@ var ScheduledCharges = class {
     if (params.limit !== void 0) qs.set("limit", String(params.limit));
     if (params.cycleNumber !== void 0) qs.set("cycleNumber", String(params.cycleNumber));
     const query = qs.toString();
-    const url = `/api/scheduled-charges/${id}/attempts${query ? `?${query}` : ""}`;
+    const url = `/api/scheduled-charges/${encodeURIComponent(id)}/attempts${query ? `?${query}` : ""}`;
     return this.http.call(
       (signal) => this.http.client.GET(url, { signal }).then(
         (r) => r

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garuhq/node",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "Official Node.js / TypeScript SDK for the Garu payment gateway.",
   "license": "MIT",
   "homepage": "https://garu.com.br",
@@ -46,7 +46,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "generate:fetch": "curl -sf ${GARU_SPEC_URL:-https://garu.com.br/api/swagger-json} -o src/generated/openapi.json",
+    "generate:fetch": "curl -sf ${GARU_SPEC_URL:-https://garu.com.br/api/openapi.json} -o src/generated/openapi.json",
     "generate:filter": "node scripts/filter-spec.mjs",
     "generate": "npm run generate:fetch && npm run generate:filter && openapi-typescript src/generated/openapi-sdk.json -o src/generated/schema.d.ts",
     "prepublishOnly": "npm run typecheck && npm test && npm run build"