@garuhq/node 0.16.0 → 1.1.0

package/dist/index.js

@@ -186,11 +186,6 @@ function generateIdempotencyKey() {
   return randomUUID();
 }
 
-// src/types.ts
-function toWirePaymentMethod(pm) {
-  return pm === "credit_card" ? "creditcard" : pm;
-}
-
 // src/resources/charges.ts
 var Charges = class {
   constructor(http) {
@@ -198,16 +193,16 @@ var Charges = class {
   }
   http;
   /**
-   * 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',
@@ -216,50 +211,187 @@ var Charges = class {
    *     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.
    */
   async create(params) {
     const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
-    const body = this.buildCreateBody(params);
-    return this.http.call(
-      (signal) => this.http.client.POST("/api/transactions", {
-        body,
-        headers: { "X-Idempotency-Key": idempotencyKey },
-        signal
-      })
-    );
+    const body = {
+      productId: params.productId,
+      paymentMethod: params.paymentMethod,
+      customer: params.customer
+    };
+    if (params.card) body.card = params.card;
+    if (params.checkoutSessionToken) body.checkoutSessionToken = params.checkoutSessionToken;
+    if (params.additionalInfo !== void 0) body.additionalInfo = params.additionalInfo;
+    return this.post("/api/v1/charges", body, { "X-Idempotency-Key": idempotencyKey });
   }
   /**
-   * 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);
+   */
+  async retrieve(uuid) {
+    return this.get(`/api/v1/charges/${encodeURIComponent(uuid)}`);
+  }
+  /**
+   * 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`);
    */
   async list(params = {}) {
     const query = {};
     if (params.page !== void 0) query.page = String(params.page);
     if (params.limit !== void 0) query.limit = String(params.limit);
     if (params.status) query.status = params.status;
-    if (params.search) query.search = params.search;
     if (params.paymentMethod) query.paymentMethod = params.paymentMethod;
+    if (params.productId) query.productId = params.productId;
+    if (params.createdAfter) query.createdAfter = params.createdAfter;
+    if (params.createdBefore) query.createdBefore = params.createdBefore;
+    if (params.search) query.search = params.search;
+    if (params.sort) query.sort = params.sort;
     const qs = new URLSearchParams(query).toString();
-    const url = `/api/transactions${qs ? `?${qs}` : ""}`;
+    return this.get(`/api/v1/charges${qs ? `?${qs}` : ""}`);
+  }
+  /**
+   * 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
+   */
+  async refund(uuid, params = {}) {
+    const body = {};
+    if (params.amount !== void 0) body.amount = params.amount;
+    if (params.reason !== void 0) body.reason = params.reason;
+    return this.post(`/api/v1/charges/${encodeURIComponent(uuid)}/refund`, body);
+  }
+  /**
+   * Cancel an unpaid charge.
+   *
+   * @example
+   * const { canceled } = await garu.charges.cancel('6f1c9b2e-...');
+   */
+  async cancel(uuid) {
+    return this.http.call(
+      (signal) => this.http.client.DELETE(
+        `/api/v1/charges/${encodeURIComponent(uuid)}`,
+        { signal }
+      )
+    );
+  }
+  // v1 charge routes are not in the generated OpenAPI schema (it is regenerated
+  // from a live deploy), so these use the client's untyped path.
+  get(url) {
+    return this.http.call(
+      (signal) => this.http.client.GET(url, { signal })
+    );
+  }
+  post(url, body, headers) {
+    return this.http.call(
+      (signal) => this.http.client.POST(url, { body, headers, signal })
+    );
+  }
+};
+
+// src/resources/installment-plans.ts
+var InstallmentPlans = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * 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
+   * });
+   */
+  async create(params) {
+    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
+    const { idempotencyKey: _omit, ...body } = params;
+    return this.http.call(
+      (signal) => this.http.client.POST("/api/v1/installment-plans", {
+        body,
+        headers: { "X-Idempotency-Key": idempotencyKey },
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * 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
+   * });
+   */
+  async list(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.customerId !== void 0) qs.set("customerId", String(params.customerId));
+    if (params.productId) qs.set("productId", params.productId);
+    if (params.dueFrom) qs.set("dueFrom", params.dueFrom);
+    if (params.dueTo) qs.set("dueTo", params.dueTo);
+    if (params.status) {
+      const statuses = Array.isArray(params.status) ? params.status : [params.status];
+      for (const s of statuses) qs.append("status", s);
+    }
+    const query = qs.toString();
+    const url = `/api/v1/installment-plans${query ? `?${query}` : ""}`;
     return this.http.call(
       (signal) => this.http.client.GET(url, { signal }).then(
         (r) => r
@@ -267,60 +399,214 @@ var Charges = class {
     );
   }
   /**
-   * Fetch a single charge by numeric ID.
+   * Retrieve one carnê with every parcela: due date, status, barcode line and
+   * boleto PDF.
    *
    * @example
-   * const charge = await garu.charges.get(4472);
-   * if (charge.status === 'paid') { ... }
+   * 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
    */
-  async get(id) {
+  async get(uuid) {
     return this.http.call(
-      (signal) => this.http.client.GET("/api/transactions/{id}", {
-        params: { path: { id } },
-        signal
-      })
+      (signal) => this.http.client.GET(`/api/v1/installment-plans/${uuid}`, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+  /**
+   * 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);
+   * }
+   */
+  async reissueInstallment(uuid, number) {
+    return this.http.call(
+      (signal) => this.http.client.POST(
+        `/api/v1/installment-plans/${uuid}/installments/${number}/reissue`,
+        { signal }
+      ).then((r) => r)
     );
   }
   /**
-   * 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'
+   * });
+   */
+  async postponeInstallment(uuid, number, params) {
+    return this.http.call(
+      (signal) => this.http.client.POST(
+        `/api/v1/installment-plans/${uuid}/installments/${number}/postpone`,
+        { body: params, signal }
+      ).then((r) => r)
+    );
+  }
+  /**
+   * 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'
    */
-  async refund(id, params = {}) {
-    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
-    const body = {};
-    if (params.amount !== void 0) body.amount = params.amount;
-    if (params.reason !== void 0) body.reason = params.reason;
+  async markInstallmentPaid(uuid, number) {
     return this.http.call(
-      (signal) => this.http.client.POST("/api/transactions/{id}/refund", {
-        params: { path: { id } },
-        body,
-        headers: { "X-Idempotency-Key": idempotencyKey },
+      (signal) => this.http.client.POST(
+        `/api/v1/installment-plans/${uuid}/installments/${number}/mark-paid`,
+        { signal }
+      ).then((r) => r)
+    );
+  }
+  /**
+   * 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' });
+   */
+  async cancel(uuid, params = {}) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/v1/installment-plans/${uuid}/cancel`, {
+        body: params,
         signal
-      })
+      }).then((r) => r)
     );
   }
-  buildCreateBody(params) {
-    const body = {
-      customer: params.customer,
-      productId: params.productId,
-      paymentMethodId: toWirePaymentMethod(params.paymentMethod),
-      link: params.link ?? null,
-      affiliateId: params.affiliateId ?? null
-    };
-    if (params.additionalInfo !== void 0) body.additionalInfo = params.additionalInfo;
-    if (params.priceId !== void 0) body.priceId = params.priceId;
-    if (params.checkoutSessionToken !== void 0) {
-      body.checkoutSessionToken = params.checkoutSessionToken;
+  /**
+   * 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
+   */
+  async requestRefund(uuid, params = {}) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/v1/installment-plans/${uuid}/refund-requests`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+};
+
+// src/resources/refund-requests.ts
+var RefundRequests = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * 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 });
+   */
+  async list(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.planId) qs.set("planId", params.planId);
+    if (params.chargeId) qs.set("chargeId", params.chargeId);
+    if (params.status) {
+      const statuses = Array.isArray(params.status) ? params.status : [params.status];
+      for (const s of statuses) qs.append("status", s);
     }
-    if (params.cardInfo) body.CardInfo = params.cardInfo;
-    return body;
+    const query = qs.toString();
+    const url = `/api/v1/refund-requests${query ? `?${query}` : ""}`;
+    return this.http.call(
+      (signal) => this.http.client.GET(url, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+  /**
+   * Retrieve one refund request.
+   *
+   * @example
+   * const request = await garu.refundRequests.get(uuid);
+   * request.installmentPlanId ?? request.chargeId;  // exactly one is set
+   */
+  async get(uuid) {
+    return this.http.call(
+      (signal) => this.http.client.GET(`/api/v1/refund-requests/${uuid}`, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+  /**
+   * 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'
+   * });
+   */
+  async confirm(uuid, params = {}) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/v1/refund-requests/${uuid}/confirm`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * 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'
+   * });
+   */
+  async reject(uuid, params = {}) {
+    return this.http.call(
+      (signal) => this.http.client.POST(`/api/v1/refund-requests/${uuid}/reject`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
   }
 };
 
@@ -1167,6 +1453,10 @@ var DEFAULT_MAX_RETRIES = 2;
 var SDK_VERSION = "0.11.1";
 var Garu = class {
   charges;
+  /** Boleto parcelado (carnê): one product sold as N monthly bank slips. */
+  installmentPlans;
+  /** Refunds Garu has been asked to make and cannot make for you. */
+  refundRequests;
   customers;
   meta;
   products;
@@ -1188,6 +1478,8 @@ var Garu = class {
       fetch: options.fetch
     });
     this.charges = new Charges(http);
+    this.installmentPlans = new InstallmentPlans(http);
+    this.refundRequests = new RefundRequests(http);
     this.customers = new Customers(http);
     this.meta = new Meta(http);
     this.products = new Products(http);

package/package.json

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