@garuhq/node 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -600,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.
@@ -865,6 +858,167 @@ 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 — create and manage payments against a product.
@@ -954,6 +1108,210 @@ declare class Charges {
     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 result = await garu.installmentPlans.reissueInstallment(uuid, 4);
+     * if (result.status === 'emitted') {
+     *   send(result.installment!.boleto!.barcodeLine);
+     * }
+     */
+    reissueInstallment(uuid: string, number: number): Promise<ReissueInstallmentResult>;
+    /**
+     * 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
+     * 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
+     * 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'
+     * });
+     */
+    reject(uuid: string, params?: ResolveRefundRequestParams): Promise<RefundRequest>;
+}
+
 /**
  * Customers — manage your customer base.
  *
@@ -1504,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;
@@ -1567,4 +1929,4 @@ declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CancelAtPeriodEndScheduledChargeParams, type CancelChargeResult, 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 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 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, 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 };