@garuhq/node 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -3,6 +3,32 @@
 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.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

package/README.md

@@ -203,6 +203,7 @@ Bill an existing customer on a future date — one-time or recurring with card t
 | `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.                                              |
@@ -213,7 +214,8 @@ Bill an existing customer on a future date — one-time or recurring with card t
 | `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,8 +225,17 @@ 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,

package/dist/index.cjs

@@ -653,9 +653,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 +671,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 +690,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 +707,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 +741,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 +802,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 +822,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 +841,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 +860,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 +888,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

@@ -312,6 +312,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;
@@ -407,6 +412,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 +466,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;
@@ -1035,6 +1069,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 +1352,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

@@ -312,6 +312,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;
@@ -407,6 +412,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 +466,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;
@@ -1035,6 +1069,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 +1352,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

@@ -647,9 +647,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 +665,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 +684,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 +701,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 +735,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 +796,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 +816,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 +835,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 +854,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 +882,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.13.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"