@garuhq/node 0.7.0 → 0.8.0

package/README.md

@@ -165,6 +165,90 @@ const customer = await garu.customers.create({
 const { data, meta } = await garu.customers.list({ search: 'maria', limit: 10 });
 ```
 
+## Products
+
+Discover products and customize the per-product portal experience (B2B2C, v0.8.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.    |
+
+```ts
+// SaaS de coaching: per-coach branding under one Seller account
+await garu.products.portalConfig.set(57, {
+  businessName: 'Coach Maria — Corrida & Trilha',
+  primaryColor: '#257264',
+  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(57, { primaryColor: null });
+```
+
+## Scheduled charges
+
+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).|
+
+```ts
+// Recurring with 7-day trial
+const series = await garu.scheduledCharges.create({
+  customerId: 42,
+  productId: 17,
+  amount: 49.9,
+  type: 'recurring',
+  dueDate: '2026-06-01',
+  methods: ['card', 'pix'],
+  recurrence: { interval: 'monthly' },
+  trialDays: 7,
+});
+
+// Audit why cycle 3 failed (v0.8.2)
+const { data } = await garu.scheduledCharges.listAttempts(series.id, {
+  cycleNumber: 3,
+});
+const declines = data.filter((a) => a.status === 'declined');
+// → each declines[i].failureCode is one of GaruFailureCode (insufficient_funds,
+//   card_expired, card_declined, ...)
+```
+
+## Failure codes (v0.8.0)
+
+Every `transaction.payment.failed`, `scheduled_charge.cycle_failed`, and `listAttempts()` row carries:
+
+- `failureCode` — canonical `GaruFailureCode` enum (10 values, gateway-independent)
+- `failureReason` — human-readable PT-BR
+- `gatewayFailureCode` — raw code from Celcoin (ABECS for forensics)
+
+```ts
+import type { GaruFailureCode } from '@garuhq/node';
+
+const PERMANENT: GaruFailureCode[] = ['card_expired', 'card_canceled', 'fraud_suspected'];
+function shouldAskForNewCard(code: GaruFailureCode): boolean {
+  return PERMANENT.includes(code);
+}
+```
+
+Full table at [docs.garu.com.br/api-reference/webhooks/codigos-de-falha](https://docs.garu.com.br/api-reference/webhooks/codigos-de-falha).
+
 ## Meta
 
 Discover available payment methods and webhook events. No authentication required.

package/dist/index.cjs

@@ -802,6 +802,32 @@ var ScheduledCharges = class {
       }).then((r) => r)
     );
   }
+  /**
+   * Per-attempt billing log for the series (SPEC §4.2). One row per
+   * logical billing event — cycle 1 interactive charge, every silent
+   * charge attempt, every retry, every manual mark-paid. Carries the
+   * canonical `failureCode` for declines so you can audit billing
+   * outcomes without cross-referencing Transactions.
+   *
+   * @example
+   * const { data } = await garu.scheduledCharges.listAttempts('sch_abc', {
+   *   cycleNumber: 3
+   * });
+   * const declines = data.filter((a) => a.status === 'declined');
+   */
+  async listAttempts(id, params = {}) {
+    const qs = new URLSearchParams();
+    if (params.page !== void 0) qs.set("page", String(params.page));
+    if (params.limit !== void 0) qs.set("limit", String(params.limit));
+    if (params.cycleNumber !== void 0) qs.set("cycleNumber", String(params.cycleNumber));
+    const query = qs.toString();
+    const url = `/api/scheduled-charges/${id}/attempts${query ? `?${query}` : ""}`;
+    return this.http.call(
+      (signal) => this.http.client.GET(url, { signal }).then(
+        (r) => r
+      )
+    );
+  }
 };
 var webhooks = {
   verify(params) {

package/dist/index.d.cts

@@ -354,6 +354,33 @@ interface ScheduledChargeDetail {
     transactions: ScheduledChargeLinkedTransaction[];
 }
 type ScheduledChargeList = PaginatedList<ScheduledChargeRecord>;
+/** Source of a billing attempt — see SPEC §3.1. */
+type ScheduledChargeAttemptSource = 'cycle1_interactive' | 'silent_charge' | 'card_retry' | 'manual_mark_paid' | 'fallback_pix';
+type ScheduledChargeAttemptStatus = 'pending' | 'succeeded' | 'declined' | 'canceled' | 'errored';
+interface ScheduledChargeAttempt {
+    id: number;
+    cycleId: string;
+    cycleNumber: number;
+    attemptNumber: number;
+    attemptedAt: string;
+    source: ScheduledChargeAttemptSource;
+    paymentMethod: 'card' | 'pix' | 'boleto' | 'manual';
+    paymentMethodId: number | null;
+    cardLast4: string | null;
+    cardBrand: string | null;
+    status: ScheduledChargeAttemptStatus;
+    failureCode: GaruFailureCode | null;
+    failureReason: string | null;
+    gatewayFailureCode: string | null;
+    gatewayChargeId: number | null;
+    transactionId: number | null;
+}
+type ScheduledChargeAttemptList = PaginatedList<ScheduledChargeAttempt>;
+interface ListScheduledChargeAttemptsParams {
+    page?: number;
+    limit?: number;
+    cycleNumber?: number;
+}
 interface CreateScheduledChargeParams {
     customerId: number;
     /**
@@ -971,6 +998,20 @@ declare class ScheduledCharges {
      * await garu.scheduledCharges.clearPaymentMethod('sch_abc123');
      */
     clearPaymentMethod(id: string): Promise<ScheduledChargeRecord>;
+    /**
+     * Per-attempt billing log for the series (SPEC §4.2). One row per
+     * logical billing event — cycle 1 interactive charge, every silent
+     * charge attempt, every retry, every manual mark-paid. Carries the
+     * canonical `failureCode` for declines so you can audit billing
+     * outcomes without cross-referencing Transactions.
+     *
+     * @example
+     * const { data } = await garu.scheduledCharges.listAttempts('sch_abc', {
+     *   cycleNumber: 3
+     * });
+     * const declines = data.filter((a) => a.status === 'declined');
+     */
+    listAttempts(id: string, params?: ListScheduledChargeAttemptsParams): Promise<ScheduledChargeAttemptList>;
 }
 
 interface GaruOptions {
@@ -1071,4 +1112,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 ListScheduledChargesParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type ScheduledChargeActor, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type SetProductPortalConfigParams, type UpdateCustomerParams, type VerifiedWebhook, type VerifyWebhookParams, type WirePaymentMethodId, webhooks };
+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 MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type ScheduledChargeActor, type 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 WirePaymentMethodId, webhooks };

package/dist/index.d.ts

@@ -354,6 +354,33 @@ interface ScheduledChargeDetail {
     transactions: ScheduledChargeLinkedTransaction[];
 }
 type ScheduledChargeList = PaginatedList<ScheduledChargeRecord>;
+/** Source of a billing attempt — see SPEC §3.1. */
+type ScheduledChargeAttemptSource = 'cycle1_interactive' | 'silent_charge' | 'card_retry' | 'manual_mark_paid' | 'fallback_pix';
+type ScheduledChargeAttemptStatus = 'pending' | 'succeeded' | 'declined' | 'canceled' | 'errored';
+interface ScheduledChargeAttempt {
+    id: number;
+    cycleId: string;
+    cycleNumber: number;
+    attemptNumber: number;
+    attemptedAt: string;
+    source: ScheduledChargeAttemptSource;
+    paymentMethod: 'card' | 'pix' | 'boleto' | 'manual';
+    paymentMethodId: number | null;
+    cardLast4: string | null;
+    cardBrand: string | null;
+    status: ScheduledChargeAttemptStatus;
+    failureCode: GaruFailureCode | null;
+    failureReason: string | null;
+    gatewayFailureCode: string | null;
+    gatewayChargeId: number | null;
+    transactionId: number | null;
+}
+type ScheduledChargeAttemptList = PaginatedList<ScheduledChargeAttempt>;
+interface ListScheduledChargeAttemptsParams {
+    page?: number;
+    limit?: number;
+    cycleNumber?: number;
+}
 interface CreateScheduledChargeParams {
     customerId: number;
     /**
@@ -971,6 +998,20 @@ declare class ScheduledCharges {
      * await garu.scheduledCharges.clearPaymentMethod('sch_abc123');
      */
     clearPaymentMethod(id: string): Promise<ScheduledChargeRecord>;
+    /**
+     * Per-attempt billing log for the series (SPEC §4.2). One row per
+     * logical billing event — cycle 1 interactive charge, every silent
+     * charge attempt, every retry, every manual mark-paid. Carries the
+     * canonical `failureCode` for declines so you can audit billing
+     * outcomes without cross-referencing Transactions.
+     *
+     * @example
+     * const { data } = await garu.scheduledCharges.listAttempts('sch_abc', {
+     *   cycleNumber: 3
+     * });
+     * const declines = data.filter((a) => a.status === 'declined');
+     */
+    listAttempts(id: string, params?: ListScheduledChargeAttemptsParams): Promise<ScheduledChargeAttemptList>;
 }
 
 interface GaruOptions {
@@ -1071,4 +1112,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 ListScheduledChargesParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type ScheduledChargeActor, type ScheduledChargeDetail, type ScheduledChargeEvent, type ScheduledChargeEventType, type ScheduledChargeLinkedTransaction, type ScheduledChargeList, type ScheduledChargeRecord, type ScheduledChargeStatus, type ScheduledChargeType, type ScheduledPaymentMethod, type SetProductPortalConfigParams, type UpdateCustomerParams, type VerifiedWebhook, type VerifyWebhookParams, type WirePaymentMethodId, webhooks };
+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 MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethod, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type ScheduledChargeActor, type 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 WirePaymentMethodId, webhooks };

package/dist/index.js

@@ -796,6 +796,32 @@ var ScheduledCharges = class {
       }).then((r) => r)
     );
   }
+  /**
+   * Per-attempt billing log for the series (SPEC §4.2). One row per
+   * logical billing event — cycle 1 interactive charge, every silent
+   * charge attempt, every retry, every manual mark-paid. Carries the
+   * canonical `failureCode` for declines so you can audit billing
+   * outcomes without cross-referencing Transactions.
+   *
+   * @example
+   * const { data } = await garu.scheduledCharges.listAttempts('sch_abc', {
+   *   cycleNumber: 3
+   * });
+   * const declines = data.filter((a) => a.status === 'declined');
+   */
+  async listAttempts(id, params = {}) {
+    const qs = new URLSearchParams();
+    if (params.page !== void 0) qs.set("page", String(params.page));
+    if (params.limit !== void 0) qs.set("limit", String(params.limit));
+    if (params.cycleNumber !== void 0) qs.set("cycleNumber", String(params.cycleNumber));
+    const query = qs.toString();
+    const url = `/api/scheduled-charges/${id}/attempts${query ? `?${query}` : ""}`;
+    return this.http.call(
+      (signal) => this.http.client.GET(url, { signal }).then(
+        (r) => r
+      )
+    );
+  }
 };
 var webhooks = {
   verify(params) {

package/package.json

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