@garuhq/node 0.16.0 → 1.1.0

package/dist/index.d.ts

@@ -98,15 +98,13 @@ declare class HttpClient {
  * The resource layer maps friendly → wire at the edge.
  */
 
-type PaymentMethod = 'pix' | 'credit_card' | '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.
+ * Stable, friendly charge status. Mirrors what /api/v1/charges returns — the
+ * raw processor statuses (payedPix, pendingBoleto, …) are normalized server-side
+ * and never surface here. Act on `paid`; `authorized` is card money held but not
+ * captured, `refund_pending` is a Pix devolução requested but not yet settled.
  */
-type WirePaymentMethodId = 'pix' | 'creditcard' | 'boleto' | 'pix_automatic';
-type ChargeStatus = 'pending' | 'authorized' | 'paid' | 'failed' | 'refunded' | 'cancelled' | 'expired';
+type ChargeStatus = 'pending' | 'authorized' | 'paid' | 'failed' | 'expired' | 'canceled' | 'refund_pending' | 'refunded' | 'chargeback';
 interface Customer {
     /** Full legal name. 3–255 chars. */
     name: string;
@@ -125,78 +123,122 @@ interface Customer {
     /** 2-letter uppercase state code, e.g. `SP`. */
     state?: string;
 }
-interface CardInfo {
-    /** 13–19 digits, no spaces or hyphens. */
-    cardNumber: string;
-    /** 3 or 4 digits. */
-    cvv: string;
-    /** `YYYY-MM`. */
-    expirationDate: string;
-    /** As printed on the card. */
+interface CardInput {
+    /** PAN, 13-19 digits, no spaces. Server-to-server only (PCI scope). */
+    number: string;
+    /** Holder name exactly as printed. */
     holderName: string;
-    /** 1–12. */
+    /** Expiry as `YYYY-MM`. */
+    expirationDate: string;
+    /** 3 or 4 digits. Never stored by Garu. */
+    cvv: string;
+    /** 1-12. */
     installments: number;
 }
 interface CreateChargeParams {
-    /** Customer buying the product. */
-    customer: Customer;
     /** UUID of the product being charged. */
     productId: string;
     /** Payment method. */
-    paymentMethod: PaymentMethod;
-    /** Required when `paymentMethod` is `credit_card`. */
-    cardInfo?: CardInfo;
-    /** Free-form metadata attached to the charge. */
-    additionalInfo?: string;
-    /** Original checkout link, if any. */
-    link?: string | null;
-    /** Associated affiliate ID, if any. */
-    affiliateId?: number | null;
-    /** Subscription price ID (`price_*`), for subscription charges only. */
-    priceId?: string | null;
-    /** Optional pre-created checkout session token. */
-    checkoutSessionToken?: string;
+    paymentMethod: ChargePaymentMethod;
+    /** Customer buying the product. */
+    customer: Customer;
     /**
-     * Idempotency key. If omitted, the SDK generates a UUIDv4.
-     * Keys are valid for 24h on the backend.
+     * Required when `paymentMethod` is `creditCard`. This is a raw PAN + CVV, so
+     * call the SDK only from your server, never a browser or app — it puts you in
+     * PCI DSS scope.
      */
+    card?: CardInput;
+    /** Optional pre-created checkout session token, for attribution. */
+    checkoutSessionToken?: string;
+    /** Free-form metadata attached to the charge. */
+    additionalInfo?: string;
+    /** Idempotency key. If omitted, the SDK generates a UUIDv4. Valid 24h. */
     idempotencyKey?: string;
 }
+type ChargePaymentMethod = 'pix' | 'boleto' | 'creditCard';
 interface Charge {
-    id: number;
+    /** Public identifier. Use this everywhere; there is no numeric id. */
+    uuid: string;
     status: ChargeStatus;
+    paymentMethod: ChargePaymentMethod;
+    /** Product base price, in decimal BRL / reais. */
     amount: number;
-    paymentMethodId: WirePaymentMethodId;
-    /** ISO-8601. */
-    date: string;
+    /**
+     * What the customer is actually charged, in reais. Equals `amount` for PIX,
+     * boleto and 1x card; higher for installment card sales (fator markup). Use
+     * this to reconcile, not `amount`.
+     */
+    chargedTotal: number;
+    installments: number;
+    product: {
+        uuid: string;
+        name: string;
+    } | null;
+    /** `document` is partially masked. */
+    customer: {
+        name: string;
+        email: string;
+        document: string;
+    } | null;
+    /** Present for PIX: the copy-paste EMV code to render as a QR. */
+    pix: {
+        code: string;
+    } | null;
+    /** Present for boleto: the barcode line and a Garu-hosted PDF URL. */
+    boleto: {
+        barcodeLine: string;
+        pdfUrl: string;
+    } | null;
+    /** Present for card: only brand, last4 and the authorization code. */
+    card: {
+        brand: string | null;
+        last4: string | null;
+        authorizationCode: string | null;
+    } | null;
+    /** Set once refunded. `refundedAt` is null while a Pix devolução is unsettled. */
+    refund: {
+        amount: number;
+        reason: string | null;
+        refundedAt: string | null;
+    } | null;
     /** ISO-8601. */
-    deadline?: string;
-    /** Product this charge belongs to. */
-    product?: {
-        id: number;
-        uuid?: string;
-        name?: string;
-    };
-    [key: string]: unknown;
+    createdAt: string;
+    /** ISO-8601. Only set for boleto (due date); null for PIX and card. */
+    expiresAt: string | null;
 }
 interface RefundChargeParams {
-    /** Partial refund in centavos. Omit for full refund. */
+    /**
+     * Partial refund in **decimal BRL / reais** (e.g. `10.00`) — NOT centavos.
+     * Omit for a full refund. Passing `1000` for "R$ 10,00" refunds a thousand
+     * reais.
+     *
+     * For a Pix Automático charge this starts an asynchronous devolução: the
+     * charge moves to `refund_pending` and only reaches `refunded` once the
+     * transfer settles.
+     */
     amount?: number;
     /** Free-form reason stored on the refund. */
     reason?: string;
-    idempotencyKey?: string;
 }
 interface ListChargesParams {
     /** Page number (1-based). Default: 1. */
     page?: number;
-    /** Items per page (1–100). Default: 20. */
+    /** Items per page (1-100). Default: 20. */
     limit?: number;
-    /** Filter by status (e.g. `paid`, `pending`). */
-    status?: string;
+    /** Filter by friendly status (e.g. `paid`, `pending`). */
+    status?: ChargeStatus;
+    /** Filter by payment method. */
+    paymentMethod?: ChargePaymentMethod;
+    /** Filter by product UUID. */
+    productId?: string;
+    /** Charges created at or after this ISO-8601 instant. */
+    createdAfter?: string;
+    /** Charges created at or before this ISO-8601 instant. */
+    createdBefore?: string;
     /** Search by customer name, email, or document. */
     search?: string;
-    /** Filter by payment method (`pix`, `creditcard`, `boleto`). */
-    paymentMethod?: string;
+    /** Sort order. Default `-createdAt` (newest first). */
+    sort?: 'createdAt' | '-createdAt' | 'amount' | '-amount';
 }
 interface PaginatedList<T> {
     data: T[];
@@ -207,7 +249,18 @@ interface PaginatedList<T> {
         totalPages: number;
     };
 }
-type ChargeList = PaginatedList<Charge>;
+interface ChargeList {
+    data: Charge[];
+    /** Items on this page. */
+    count: number;
+    /** Total matches across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
+/** Result of cancelling a charge. */
+interface CancelChargeResult {
+    canceled: boolean;
+}
 interface CustomerRecord {
     id: number;
     name: string;
@@ -547,13 +600,6 @@ interface Product {
     updatedAt: string;
     [key: string]: unknown;
 }
-/** One entry in a product's credit-card installment breakdown. */
-interface Installment {
-    /** Number of parcelas. */
-    quantity: number;
-    /** Amount charged per installment, in reais (BRL), with the fator markup applied. */
-    value: number;
-}
 /**
  * List envelope returned by `products.list()`. Flat (not `{ data, meta }`) —
  * matches the `/api/v1/products` response.
@@ -812,29 +858,190 @@ interface SetProductPortalConfigParams {
     customCancellationMessage?: string | null;
     customWelcomeText?: string | null;
 }
+type InstallmentPlanStatus = 'pending_activation' | 'active' | 'completed' | 'defaulted' | 'canceled' | 'refunded';
+type InstallmentStatus = 'scheduled' | 'due_today' | 'processing' | 'paid' | 'overdue' | 'failed' | 'canceled';
+/** One entry in a product's credit-card installment breakdown. */
+interface Installment {
+    /** Number of parcelas. */
+    quantity: number;
+    /** Amount charged per installment, in reais (BRL), with the fator markup applied. */
+    value: number;
+}
+/** One monthly slip of a carnê. */
+interface Installment {
+    /** 1-based position in the plan. */
+    number: number;
+    amount: number;
+    /** YYYY-MM-DD in São Paulo time. */
+    dueDate: string;
+    status: InstallmentStatus;
+    paidAt: string | null;
+    /**
+     * Null until the slip is registered. Parcelas 2..N are emitted month by
+     * month, so most of a fresh plan has no barcode yet.
+     */
+    boleto: {
+        barcodeLine: string;
+        pdfUrl: string;
+    } | null;
+    reissueCount: number;
+}
+interface InstallmentPlan {
+    uuid: string;
+    status: InstallmentPlanStatus;
+    installments: number;
+    installmentsPaid: number;
+    /** The cash price the buyer would have paid in one go. */
+    baseValue: number;
+    /** Interest multiplier snapshotted at sale time; never recomputed. */
+    fator: number;
+    installmentAmount: number;
+    /** `installmentAmount × installments` — what the carnê bills in total. */
+    totalScheduled: number;
+    /**
+     * What has actually cleared. May exceed `totalScheduled` once a bank adds
+     * multa or mora, which is why the two are separate fields.
+     */
+    totalCollected: number;
+    firstDueDate: string;
+    graceDays: number | null;
+    cancelReason: string | null;
+    product: {
+        uuid: string;
+        name: string;
+    } | null;
+    customer: {
+        name: string;
+        email: string;
+        document: string;
+    } | null;
+    activatedAt: string | null;
+    completedAt: string | null;
+    canceledAt: string | null;
+    createdAt: string;
+    /** Present on retrieve and create; omitted from list responses. */
+    installmentsDetail?: Installment[];
+}
+interface InstallmentPlanList {
+    data: InstallmentPlan[];
+    count: number;
+    totalCount: number;
+    totalPages: number;
+}
+interface CreateInstallmentPlanParams {
+    /** Public uuid of a product with carnê enabled. */
+    productId: string;
+    /** Numeric customer id, as returned by `garu.customers.create`. */
+    customerId: number;
+    /** 2..12. One parcela is not a carnê. */
+    installments: number;
+    /** YYYY-MM-DD. Defaults to today; must be within 90 days. */
+    firstDueDate?: string;
+    /**
+     * The affiliate who made this sale. Fixed at sale time: every later parcela
+     * inherits it, so omitting it pays that affiliate nothing for the whole
+     * carnê.
+     */
+    affiliateId?: number;
+    /** Auto-generated when omitted. */
+    idempotencyKey?: string;
+}
+interface ListInstallmentPlansParams {
+    page?: number;
+    limit?: number;
+    status?: InstallmentPlanStatus | InstallmentPlanStatus[];
+    customerId?: number;
+    productId?: string;
+    /** Filters on the FIRST parcela's due date, which identifies the plan. */
+    dueFrom?: string;
+    dueTo?: string;
+}
+interface PostponeInstallmentParams {
+    /** YYYY-MM-DD. Moves this parcela only; its siblings keep their dates. */
+    newDueDate: string;
+}
+interface ReissueInstallmentResult {
+    status: string;
+    reason: string | null;
+    installment: Installment | null;
+}
+interface CancelInstallmentPlanParams {
+    note?: string;
+}
+type RefundRequestStatus = 'pending' | 'confirmed' | 'rejected';
+/**
+ * A refund Garu has been ASKED to make and has not made. Garu never moves this
+ * money: a boleto cannot be reversed and Celcoin exposes no Pix devolução, so
+ * the funds already settled to the seller and the return is a bank transfer
+ * only they can make.
+ */
+interface RefundRequest {
+    uuid: string;
+    status: RefundRequestStatus;
+    /** Amount the seller is being asked to return, in reais. */
+    amount: number;
+    reason: string | null;
+    /** Exactly one of these is set. */
+    installmentPlanId: string | null;
+    chargeId: string | null;
+    requestedBy: {
+        type: string;
+        id?: number | string | null;
+    };
+    resolvedBy: {
+        type: string;
+        id?: number | string | null;
+    } | null;
+    sellerNote: string | null;
+    resolvedAt: string | null;
+    createdAt: string;
+}
+interface RefundRequestList {
+    data: RefundRequest[];
+    count: number;
+    totalCount: number;
+    totalPages: number;
+}
+interface RequestPlanRefundParams {
+    /** Defaults to everything the carnê has collected. */
+    amount?: number;
+    reason?: string;
+}
+interface ListRefundRequestsParams {
+    page?: number;
+    limit?: number;
+    status?: RefundRequestStatus | RefundRequestStatus[];
+    /** Filter by carnê uuid. */
+    planId?: string;
+    /** Filter by charge uuid (Pix and boleto requests). */
+    chargeId?: string;
+}
+interface ResolveRefundRequestParams {
+    note?: string;
+}
 
 /**
- * Charges — the core of the Garu API.
+ * Charges — create and manage payments against a product.
  *
- * A charge represents a single payment attempt against a product. The SDK
- * surfaces charges under `garu.charges` even though the backend route is
- * `/api/transactions` — this matches Stripe convention and is the name every
- * other Garu surface (MCP, CLI, docs) uses.
+ * Backed by `/api/v1/charges`, the versioned public contract. A charge is keyed
+ * by `uuid`; there is no numeric id. Create returns everything needed to render
+ * a transparent checkout: the PIX EMV (`pix.code`), the boleto line and a
+ * Garu-hosted PDF (`boleto`), or the card authorization (`card`).
  */
 declare class Charges {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Create a charge (PIX, credit card, or boleto).
+     * Create a charge (PIX, boleto, or credit card).
      *
-     * Automatically attaches an `X-Idempotency-Key` header — if you don't pass
-     * `idempotencyKey`, the SDK generates a UUIDv4. Safe to retry: the backend
-     * caches the first response for 24h.
+     * Attaches an `X-Idempotency-Key` header automatically — if you don't pass
+     * `idempotencyKey`, the SDK generates a UUIDv4. Safe to retry: the same key
+     * returns the original charge for 24h.
      *
      * @example
-     * // PIX charge
+     * // PIX — render charge.pix.code as a QR in your own checkout
      * const charge = await garu.charges.create({
-     *   productId: 'b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f',
+     *   productId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
      *   paymentMethod: 'pix',
      *   customer: {
      *     name: 'Maria Silva',
@@ -843,53 +1050,266 @@ declare class Charges {
      *     phone: '11987654321'
      *   }
      * });
-     * // charge.id, charge.status
+     * console.log(charge.uuid, charge.pix?.code);
      *
      * @example
-     * // Credit card charge, 3 installments
+     * // Credit card, 2 installments. Server-to-server only (PCI scope).
      * const charge = await garu.charges.create({
-     *   productId: 'b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f',
-     *   paymentMethod: 'credit_card',
+     *   productId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+     *   paymentMethod: 'creditCard',
      *   customer: { name: 'Maria Silva', email: 'maria@exemplo.com.br', document: '12345678909', phone: '11987654321' },
-     *   cardInfo: {
-     *     cardNumber: '4111111111111111',
-     *     cvv: '123',
-     *     expirationDate: '2030-12',
+     *   card: {
+     *     number: '4111111111111111',
      *     holderName: 'MARIA SILVA',
-     *     installments: 3
+     *     expirationDate: '2030-12',
+     *     cvv: '123',
+     *     installments: 2
      *   }
      * });
+     * // charge.amount is the base price; charge.chargedTotal is what was charged.
      */
     create(params: CreateChargeParams): Promise<Charge>;
     /**
-     * List charges for the authenticated seller, with pagination and filters.
+     * Retrieve a charge by uuid.
      *
      * @example
-     * const { data, meta } = await garu.charges.list({ status: 'paid', limit: 10 });
-     * // meta.total paid charges
+     * const charge = await garu.charges.retrieve('6f1c9b2e-4a7d-4f0b-9a3e-1d2c3b4a5e6f');
+     * if (charge.status === 'paid') fulfil(charge);
+     */
+    retrieve(uuid: string): Promise<Charge>;
+    /**
+     * List charges for the authenticated account, newest first by default.
+     *
+     * @example
+     * const { data, totalCount } = await garu.charges.list({ status: 'paid', limit: 50 });
+     * console.log(`${data.length} of ${totalCount} paid charges`);
      */
     list(params?: ListChargesParams): Promise<ChargeList>;
     /**
-     * Fetch a single charge by numeric ID.
+     * Refund a charge, fully or partially. `amount` is in reais.
+     *
+     * For a Pix Automático charge the refund is a devolução: it returns with the
+     * charge in `refund_pending`, reaching `refunded` only once the transfer
+     * settles.
+     *
+     * @example
+     * await garu.charges.refund('6f1c9b2e-...');                       // full
+     * await garu.charges.refund('6f1c9b2e-...', { amount: 10.0 });     // R$10,00
+     */
+    refund(uuid: string, params?: RefundChargeParams): Promise<Charge>;
+    /**
+     * Cancel an unpaid charge.
+     *
+     * @example
+     * const { canceled } = await garu.charges.cancel('6f1c9b2e-...');
+     */
+    cancel(uuid: string): Promise<CancelChargeResult>;
+    private get;
+    private post;
+}
+
+/**
+ * Boleto parcelado (carnê) — one product sold as N monthly bank slips.
+ *
+ * This is seller-financed consumer credit, not a card instalment. Nobody
+ * guarantees a boleto: if the buyer stops paying at parcela 4, the seller
+ * keeps four parcelas and loses the rest. Garu emits the slips, chases them
+ * and reports, but carries none of the default risk.
+ *
+ * Only the FIRST boleto exists at creation. The rest are emitted month by
+ * month, and the sale activates when parcela 1 compensates — a plan is not a
+ * sale until the buyer has paid something.
+ */
+declare class InstallmentPlans {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Sell a product as a carnê. Auto-attaches `X-Idempotency-Key` (UUIDv4 if
+     * you don't pass `idempotencyKey`), which matters more here than anywhere
+     * else in the API: this call registers a REAL boleto at the bank, so a
+     * blind retry can put two payable barcodes in one buyer's hands.
+     *
+     * @example
+     * const carne = await garu.installmentPlans.create({
+     *   productId: '40381e8e-6ee7-4b8e-9393-766a6e2109d2',
+     *   customerId: 4821,
+     *   installments: 12
+     * });
+     * // A R$1.200 product at fator 1,30 bills R$130,00 a month:
+     * carne.totalScheduled;            // 1560
+     * carne.installmentAmount;         // 130
+     * carne.installmentsDetail?.[0];   // parcela 1, with its barcode
+     *
+     * @example
+     * // Attribute the sale to an affiliate. Fixed at sale time: every later
+     * // parcela inherits it, so omitting it pays them nothing for the whole
+     * // carnê. The affiliate must already be active on this product.
+     * await garu.installmentPlans.create({
+     *   productId: '40381e8e-6ee7-4b8e-9393-766a6e2109d2',
+     *   customerId: 4821,
+     *   installments: 6,
+     *   firstDueDate: '2026-10-05',
+     *   affiliateId: 5
+     * });
+     */
+    create(params: CreateInstallmentPlanParams): Promise<InstallmentPlan>;
+    /**
+     * List carnês, newest first. `dueFrom`/`dueTo` filter on the FIRST
+     * parcela's due date, which is what identifies the plan; filtering on every
+     * parcela would return one carnê twelve times.
+     *
+     * @example
+     * const atRisk = await garu.installmentPlans.list({ status: 'defaulted' });
+     *
+     * @example
+     * const live = await garu.installmentPlans.list({
+     *   status: ['active', 'pending_activation'],
+     *   customerId: 4821,
+     *   limit: 50
+     * });
+     */
+    list(params?: ListInstallmentPlansParams): Promise<InstallmentPlanList>;
+    /**
+     * Retrieve one carnê with every parcela: due date, status, barcode line and
+     * boleto PDF.
+     *
+     * @example
+     * const carne = await garu.installmentPlans.get(uuid);
+     * const unpaid = carne.installmentsDetail?.filter((i) => i.status !== 'paid');
+     * carne.totalCollected;  // what has actually cleared, not what was billed
+     */
+    get(uuid: string): Promise<InstallmentPlan>;
+    /**
+     * Issue a segunda via for one parcela, once the current slip has expired.
+     *
+     * A boleto stays payable at any bank until its due date plus five days, so
+     * Garu refuses while the old barcode is still live — two live barcodes for
+     * one parcela is how a buyer pays it twice. Once per parcela per day.
      *
      * @example
-     * const charge = await garu.charges.get(4472);
-     * if (charge.status === 'paid') { ... }
+     * const result = await garu.installmentPlans.reissueInstallment(uuid, 4);
+     * if (result.status === 'emitted') {
+     *   send(result.installment!.boleto!.barcodeLine);
+     * }
      */
-    get(id: number): Promise<Charge>;
+    reissueInstallment(uuid: string, number: number): Promise<ReissueInstallmentResult>;
     /**
-     * Refund a charge — fully, or partially by passing `amount` in centavos.
+     * Move one parcela to a later date. Its siblings keep theirs — this
+     * postpones a payment, it does not restructure the carnê. A slip already
+     * emitted stays payable on its original date until it expires.
      *
      * @example
-     * // Full refund
-     * await garu.charges.refund(4472);
+     * await garu.installmentPlans.postponeInstallment(uuid, 4, {
+     *   newDueDate: '2026-12-20'
+     * });
+     */
+    postponeInstallment(uuid: string, number: number, params: PostponeInstallmentParams): Promise<Installment>;
+    /**
+     * Record a parcela as paid, for when the buyer paid the slip but the
+     * webhook never arrived.
+     *
+     * Garu asks the provider to confirm the charge really compensated before
+     * recording it, because this settles the transaction and pays affiliate and
+     * co-producer commissions. A provider outage refuses the action rather than
+     * trusting the assertion.
      *
      * @example
-     * // Partial refund of R$ 10,00
-     * await garu.charges.refund(4472, { amount: 1000, reason: 'customer_request' });
+     * const parcela = await garu.installmentPlans.markInstallmentPaid(uuid, 3);
+     * parcela.status;  // 'paid'
+     */
+    markInstallmentPaid(uuid: string, number: number): Promise<Installment>;
+    /**
+     * Cancel the carnê. Emission and reminders stop and open slips are
+     * cancelled at the provider.
+     *
+     * Money already collected is NOT returned — open a refund request for that.
+     * A cancelled carnê is never revived by a late payment; that money opens a
+     * refund request instead.
+     *
+     * @example
+     * await garu.installmentPlans.cancel(uuid, { note: 'Comprador desistiu' });
+     */
+    cancel(uuid: string, params?: CancelInstallmentPlanParams): Promise<InstallmentPlan>;
+    /**
+     * Ask for this carnê to be refunded.
+     *
+     * Garu does NOT move the money. A boleto cannot be reversed and the funds
+     * already settled to you, so this records the request and notifies your
+     * team. Transfer the money to the buyer yourself, then close it with
+     * `garu.refundRequests.confirm`.
+     *
+     * @example
+     * const request = await garu.installmentPlans.requestRefund(uuid, {
+     *   reason: 'Produto não entregue'
+     * });
+     * request.status;  // 'pending' — nothing has moved yet
+     * request.amount;  // defaults to everything the carnê collected
+     */
+    requestRefund(uuid: string, params?: RequestPlanRefundParams): Promise<RefundRequest>;
+}
+
+/**
+ * Refunds Garu has been asked to make and cannot make for you.
+ *
+ * A boleto cannot be reversed at all, and Celcoin exposes no Pix devolução.
+ * Either way the funds already settled to you, so the return is a bank
+ * transfer only you can make. This resource records the request, notifies
+ * your team, and waits for you to assert the money went back. Garu records
+ * the assertion; it never observes the transfer.
+ *
+ * Card and Woovi Pix never appear here — they have real automated reversals
+ * (`garu.charges.refund`).
+ */
+declare class RefundRequests {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List refund requests, newest first. Covers carnê and Pix/boleto alike.
+     *
+     * @example
+     * // Everything you still owe a buyer.
+     * const owed = await garu.refundRequests.list({ status: 'pending' });
+     * const total = owed.data.reduce((sum, r) => sum + r.amount, 0);
+     *
+     * @example
+     * const forThisCarne = await garu.refundRequests.list({ planId: carne.uuid });
+     */
+    list(params?: ListRefundRequestsParams): Promise<RefundRequestList>;
+    /**
+     * Retrieve one refund request.
+     *
+     * @example
+     * const request = await garu.refundRequests.get(uuid);
+     * request.installmentPlanId ?? request.chargeId;  // exactly one is set
+     */
+    get(uuid: string): Promise<RefundRequest>;
+    /**
+     * Record that you returned the money. Call this AFTER transferring it.
+     *
+     * Confirming closes a carnê as refunded, stops remaining parcelas, cancels
+     * open slips at the provider and claws back the affiliate and co-producer
+     * commissions on the parcelas that cleared. For a Pix or boleto charge it
+     * marks the charge reversed and fires `transaction.refunded`. Idempotent:
+     * confirming twice does not claw back twice.
+     *
+     * @example
+     * // 1. You send the money to the buyer, out of band.
+     * // 2. Then tell Garu it happened.
+     * await garu.refundRequests.confirm(uuid, {
+     *   note: 'Pix devolvido em 14/08, e2e E12345678'
+     * });
+     */
+    confirm(uuid: string, params?: ResolveRefundRequestParams): Promise<RefundRequest>;
+    /**
+     * Decline the request. The carnê is untouched and keeps running.
+     * Idempotent.
+     *
+     * @example
+     * await garu.refundRequests.reject(uuid, {
+     *   note: 'Produto entregue e retirado na loja em 02/08'
+     * });
      */
-    refund(id: number, params?: RefundChargeParams): Promise<Charge>;
-    private buildCreateBody;
+    reject(uuid: string, params?: ResolveRefundRequestParams): Promise<RefundRequest>;
 }
 
 /**
@@ -1442,6 +1862,10 @@ interface GaruOptions {
  */
 declare class Garu {
     readonly charges: Charges;
+    /** Boleto parcelado (carnê): one product sold as N monthly bank slips. */
+    readonly installmentPlans: InstallmentPlans;
+    /** Refunds Garu has been asked to make and cannot make for you. */
+    readonly refundRequests: RefundRequests;
     readonly customers: Customers;
     readonly meta: Meta;
     readonly products: Products;
@@ -1505,4 +1929,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 ChargeNowOutcome, type ChargeNowReason, type ChargeNowResult, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateProductParams, 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 UpdateProductParams, type VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, type WirePaymentMethodId, webhooks };
+export { type CancelAtPeriodEndScheduledChargeParams, type CancelChargeResult, type CancelInstallmentPlanParams, type CancelRecurrenceScheduledChargeParams, type CardInput, type ChangePaymentMethodScheduledChargeParams, type Charge, type ChargeList, type ChargeNowOutcome, type ChargeNowReason, type ChargeNowResult, type ChargePaymentMethod, type ChargeStatus, type CreateChargeParams, type CreateCustomerParams, type CreateInstallmentPlanParams, type CreateProductParams, 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 Installment, type InstallmentPlan, type InstallmentPlanList, type InstallmentPlanStatus, type InstallmentStatus, type ListChargesParams, type ListCustomersParams, type ListInstallmentPlansParams, type ListProductsParams, type ListRefundRequestsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeInstallmentParams, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type RefundRequest, type RefundRequestList, type RefundRequestStatus, type ReissueInstallmentResult, type RequestPlanRefundParams, type ResendWebhookEventParams, type ResolveRefundRequestParams, 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 UpdateProductParams, type VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, webhooks };