@garuhq/node 0.16.0 → 1.1.0

package/CHANGELOG.md

@@ -3,6 +3,105 @@
 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/).
 
+## [1.1.0] — 2026-08-15
+
+
+### Added
+
+- **`garu.installmentPlans` — 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, so a buyer who stops at parcela 4
+  leaves the seller with four parcelas and no recourse through Garu. Only the
+  first slip is registered at creation; the rest are emitted month by month and
+  the sale activates when parcela 1 compensates.
+  - `create` (auto-attaches `X-Idempotency-Key`, which matters more here than
+    anywhere else in the API — the call registers a real boleto, so a blind
+    retry hands one buyer two payable barcodes), `list`, `get`,
+    `reissueInstallment`, `postponeInstallment`, `markInstallmentPaid`,
+    `cancel`, `requestRefund`.
+  - `create` takes an optional `affiliateId`. It is fixed at sale time and every
+    later parcela inherits it, so omitting it pays that affiliate nothing for
+    the whole carnê.
+  - Read `totalCollected` against `totalScheduled`: they differ once a bank adds
+    multa or mora, and `totalCollected` can legitimately exceed what was billed.
+
+- **`garu.refundRequests` — refunds Garu cannot make for you.** A boleto cannot
+  be reversed and Celcoin exposes no Pix devolução, so the funds already settled
+  to you and the return is a bank transfer only you can make. `list`, `get`,
+  `confirm`, `reject`. Confirming records that you _assert_ the money went back;
+  Garu never observes the transfer. Card and Woovi Pix are unaffected and keep
+  their real automated reversals via `garu.charges.refund`.
+
+## [1.0.0] — 2026-07-23
+
+First stable release. **Breaking:** `charges` now targets the versioned public
+API `/api/v1/charges`, keyed on `uuid`. If you use `garu.charges.*`, read the
+migration below. Nothing else (products, customers, scheduled-charges,
+webhook-events) changed.
+
+### Breaking
+
+- **`charges` moved to `/api/v1/charges`** and a charge is keyed by **`uuid`**,
+  not a numeric `id`.
+  - `charges.get(id: number)` → **`charges.retrieve(uuid: string)`**.
+  - `charge.id` → **`charge.uuid`**.
+- **`create` takes a v1 body.** `paymentMethod` uses `'creditCard'` (was
+  `'credit_card'`); card data goes under **`card`** (was `cardInfo`) as
+  `{ number, holderName, expirationDate, cvv, installments }` (was `cardNumber`).
+  Removed the unused `link`, `affiliateId`, `priceId` params.
+- **New response shape** (`Charge`), mirroring the API:
+  - `amount` is now the product **base price**; the amount actually charged is
+    the new **`chargedTotal`** (they differ on installment card sales). Reconcile
+    on `chargedTotal`.
+  - `date`/`deadline` → **`createdAt`/`expiresAt`** (`expiresAt` is null for PIX
+    and card, set only for boleto).
+  - `paymentMethodId` → **`paymentMethod`** (`'pix' | 'boleto' | 'creditCard'`).
+  - New method blocks: `pix.code`, `boleto.{barcodeLine,pdfUrl}`,
+    `card.{brand,last4,authorizationCode}`, `refund.{amount,reason,refundedAt}`.
+- **`status` is a friendly, stable set:** `pending`, `authorized`, `paid`,
+  `failed`, `expired`, `canceled`, `refund_pending`, `refunded`, `chargeback`.
+  The raw processor values (`payedPix`, `captured`, …) are gone. Note the
+  spelling `canceled` (one `l`).
+- **`list` returns `{ data, count, totalCount, totalPages }`** (was
+  `{ data, meta }`), and gains `productId`, `createdAfter`, `createdBefore`,
+  `sort` filters.
+- **`refund` amount is in reais**, not centavos, and no longer takes an
+  `idempotencyKey`. New **`charges.cancel(uuid)`** for unpaid charges.
+- Removed the now-unused exports `PaymentMethod`, `WirePaymentMethodId`,
+  `CardInfo`, `toWirePaymentMethod`. Use `ChargePaymentMethod` and `CardInput`.
+
+### Fixed
+
+- `charges.create()` now returns a usable charge. It previously read the raw
+  `/api/transactions` envelope, leaving `charge.id` undefined.
+- Refund amount is reais across code, types and the README (a `1000`-for-R$10,00
+  example is gone). Carried over from the 0.16.x fix.
+
+### Migration
+
+```ts
+// before (0.16.x)
+const c = await garu.charges.create({
+  productId, paymentMethod: 'credit_card', customer,
+  cardInfo: { cardNumber: '4111…', cvv, expirationDate, holderName, installments: 2 }
+});
+c.id;                 // number
+c.paymentMethodId;    // 'creditcard'
+const one = await garu.charges.get(c.id);
+await garu.charges.refund(c.id, { amount: 1000 }); // "R$10,00" (bug: reais)
+
+// after (1.0.0)
+const c = await garu.charges.create({
+  productId, paymentMethod: 'creditCard', customer,
+  card: { number: '4111…', cvv, expirationDate, holderName, installments: 2 }
+});
+c.uuid;               // string
+c.paymentMethod;      // 'creditCard'
+c.chargedTotal;       // what was actually charged
+const one = await garu.charges.retrieve(c.uuid);
+await garu.charges.refund(c.uuid, { amount: 10.0 }); // R$10,00
+```
+
 ## [0.16.0] — 2026-07-18
 
 ### Changed

package/README.md

@@ -58,7 +58,7 @@ const charge = await garu.charges.create({
   }
 });
 
-console.log(charge.id, charge.status);
+console.log(charge.uuid, charge.pix?.code);
 ```
 
 ## Setup
@@ -84,12 +84,13 @@ const garu = new Garu({
 
 ## Charges
 
-| Method                | Description                                  |
-| --------------------- | -------------------------------------------- |
-| `create(params)`      | Create a PIX, credit-card, or boleto charge. |
-| `list(params?)`       | List charges with pagination and filters.    |
-| `get(id)`             | Fetch a single charge by ID.                 |
-| `refund(id, params?)` | Refund a charge fully or partially.          |
+| Method                  | Description                                   |
+| ----------------------- | --------------------------------------------- |
+| `create(params)`        | Create a PIX, credit-card, or boleto charge.  |
+| `retrieve(uuid)`        | Fetch a single charge by uuid.                |
+| `list(params?)`         | List charges with pagination and filters.     |
+| `refund(uuid, params?)` | Refund a charge fully or partially (reais).   |
+| `cancel(uuid)`          | Cancel an unpaid charge.                       |
 
 ### Create a PIX charge
 
@@ -111,13 +112,13 @@ const charge = await garu.charges.create({
 ```ts
 const charge = await garu.charges.create({
   productId: 'b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f',
-  paymentMethod: 'credit_card',
+  paymentMethod: 'creditCard',
   card: {
     number: '4111111111111111',
     holderName: 'MARIA SILVA',
-    expirationMonth: '12',
-    expirationYear: '2028',
-    cvv: '123'
+    expirationDate: '2030-12',
+    cvv: '123',
+    installments: 2
   },
   customer: {
     name: 'Maria Silva',
@@ -131,13 +132,13 @@ const charge = await garu.charges.create({
 ### List charges
 
 ```ts
-const { data, meta } = await garu.charges.list({ limit: 10 });
+const { data, totalCount } = await garu.charges.list({ status: 'paid', limit: 10 });
 ```
 
 ### Refund a charge
 
 ```ts
-await garu.charges.refund(4472, { amount: 1000 }); // partial refund (R$10.00)
+await garu.charges.refund('6f1c9b2e-…', { amount: 10.0 }); // partial refund (R$10,00, reais)
 ```
 
 > [!TIP]
@@ -425,7 +426,7 @@ import {
 } from '@garuhq/node';
 
 try {
-  await garu.charges.refund(4472, { amount: 1000 });
+  await garu.charges.refund('6f1c9b2e-…', { amount: 10.0 });
 } catch (err) {
   if (err instanceof GaruNotFoundError) {
     /* 404 */