@garuhq/node 0.15.0 → 1.0.0

package/CHANGELOG.md

@@ -3,6 +3,107 @@
 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.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
+
+- **Products now use the versioned public API `/api/v1/products`.** Every product
+  method (`list`, `get`, `create`, `update`, `portalConfig.*`) moved from the
+  un-versioned `/api/products/*` (dashboard) paths to `/api/v1/products`. Method
+  signatures are unchanged — `get`/`update`/portal-config still accept the product
+  UUID (recommended) or the legacy numeric id.
+- **`Product.value` is decimal reais (BRL), not centavos.** The type comments and
+  create/update examples wrongly said centavos — following them created a product
+  priced 100× (`4990` → R$ 4.990,00 instead of R$ 49,90). No behavior change: the
+  SDK already sent `value` as-is. Charges/refunds `amount` remain centavos.
+- **`ProductList` is the real flat shape** `{ data, count, totalCount, totalPages }`
+  (previously mistyped `{ data, meta }`, which was never populated at runtime).
+- **`Product.installments` is `Installment[]`** (`{ quantity, value }`) — was
+  `number[]`, which didn't match the API.
+
+### Deprecated
+
+- **`Product.id`** — the v1 API no longer returns a numeric id; use `uuid`. It is
+  now optional and `undefined` on v1 responses, though still accepted as an input
+  identifier on `get`/`update`/portal-config.
+- **`ListProductsParams.tab`** — not supported by v1 (ignored). `list()` returns
+  the authenticated seller's own products.
+
+### Migration
+
+Read a product's `uuid`, not `.id`. Persisted numeric ids still work as **input**
+identifiers, but responses now carry only `uuid`.
+
 ## [0.15.0] — 2026-05-31
 
 ### Added

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 */

package/dist/index.cjs

@@ -192,11 +192,6 @@ function generateIdempotencyKey() {
   return crypto.randomUUID();
 }
 
-// src/types.ts
-function toWirePaymentMethod(pm) {
-  return pm === "credit_card" ? "creditcard" : pm;
-}
-
 // src/resources/charges.ts
 var Charges = class {
   constructor(http) {
@@ -204,16 +199,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',
@@ -222,111 +217,109 @@ 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.http.call(
-      (signal) => this.http.client.GET(url, { signal }).then(
-        (r) => r
-      )
-    );
+    return this.get(`/api/v1/charges${qs ? `?${qs}` : ""}`);
   }
   /**
-   * 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
-   * const charge = await garu.charges.get(4472);
-   * if (charge.status === 'paid') { ... }
+   * await garu.charges.refund('6f1c9b2e-...');                       // full
+   * await garu.charges.refund('6f1c9b2e-...', { amount: 10.0 });     // R$10,00
    */
-  async get(id) {
-    return this.http.call(
-      (signal) => this.http.client.GET("/api/transactions/{id}", {
-        params: { path: { id } },
-        signal
-      })
-    );
+  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);
   }
   /**
-   * Refund a charge — fully, or partially by passing `amount` in centavos.
+   * Cancel an unpaid charge.
    *
    * @example
-   * // Full refund
-   * await garu.charges.refund(4472);
-   *
-   * @example
-   * // Partial refund of R$ 10,00
-   * await garu.charges.refund(4472, { amount: 1000, reason: 'customer_request' });
+   * const { canceled } = await garu.charges.cancel('6f1c9b2e-...');
    */
-  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 cancel(uuid) {
     return this.http.call(
-      (signal) => this.http.client.POST("/api/transactions/{id}/refund", {
-        params: { path: { id } },
-        body,
-        headers: { "X-Idempotency-Key": idempotencyKey },
-        signal
-      })
+      (signal) => this.http.client.DELETE(
+        `/api/v1/charges/${encodeURIComponent(uuid)}`,
+        { signal }
+      )
     );
   }
-  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;
-    }
-    if (params.cardInfo) body.CardInfo = params.cardInfo;
-    return body;
+  // 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 })
+    );
   }
 };
 
@@ -481,7 +474,7 @@ var ProductPortalConfigResource = class {
   async get(productId) {
     return this.http.call(
       (signal) => this.http.client.GET(
-        `/api/products/${encodeURIComponent(String(productId))}/portal-config`,
+        `/api/v1/products/${encodeURIComponent(String(productId))}/portal-config`,
         {
           signal
         }
@@ -504,7 +497,7 @@ var ProductPortalConfigResource = class {
   async set(productId, params) {
     return this.http.call(
       (signal) => this.http.client.POST(
-        `/api/products/${encodeURIComponent(String(productId))}/portal-config`,
+        `/api/v1/products/${encodeURIComponent(String(productId))}/portal-config`,
         {
           body: params,
           signal
@@ -516,7 +509,7 @@ var ProductPortalConfigResource = class {
   async patch(productId, params) {
     return this.http.call(
       (signal) => this.http.client.PATCH(
-        `/api/products/${encodeURIComponent(String(productId))}/portal-config`,
+        `/api/v1/products/${encodeURIComponent(String(productId))}/portal-config`,
         {
           body: params,
           signal
@@ -535,7 +528,7 @@ var ProductPortalConfigResource = class {
   async clear(productId) {
     return this.http.call(
       (signal) => this.http.client.DELETE(
-        `/api/products/${encodeURIComponent(String(productId))}/portal-config`,
+        `/api/v1/products/${encodeURIComponent(String(productId))}/portal-config`,
         {
           body: {},
           signal
@@ -556,16 +549,15 @@ var Products = class {
    * List products for the authenticated seller, with pagination and search.
    *
    * @example
-   * const { data, meta } = await garu.products.list({ search: 'curso', limit: 10 });
+   * const { data, totalCount } = await garu.products.list({ search: 'curso', limit: 10 });
    */
   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.search) query.search = params.search;
-    if (params.tab) query.tab = params.tab;
     const qs = new URLSearchParams(query).toString();
-    const url = `/api/products/seller${qs ? `?${qs}` : ""}`;
+    const url = `/api/v1/products${qs ? `?${qs}` : ""}`;
     return this.http.call(
       (signal) => this.http.client.GET(url, { signal }).then(
         (r) => r
@@ -581,7 +573,7 @@ var Products = class {
    */
   async get(uuid) {
     return this.http.call(
-      (signal) => this.http.client.GET(`/api/products/uuid/${uuid}`, { signal }).then(
+      (signal) => this.http.client.GET(`/api/v1/products/${uuid}`, { signal }).then(
         (r) => r
       )
     );
@@ -599,7 +591,7 @@ var Products = class {
    * @example
    * const product = await garu.products.create({
    *   name: 'Plano Mensal',
-   *   value: 4990, // R$ 49,90 in centavos
+   *   value: 49.90, // R$ 49,90 in reais (decimal BRL), NOT centavos
    *   description: 'Acesso completo à plataforma',
    *   pix: true,
    *   creditCard: true,
@@ -612,7 +604,7 @@ var Products = class {
     const { idempotencyKey, ...body } = params;
     const key = idempotencyKey ?? generateIdempotencyKey();
     return this.http.call(
-      (signal) => this.http.client.POST("/api/products", {
+      (signal) => this.http.client.POST("/api/v1/products", {
         body,
         headers: { "X-Idempotency-Key": key },
         signal
@@ -623,19 +615,19 @@ var Products = class {
    * Update a product (partial PATCH — only the fields you pass are changed).
    * Returns the updated product.
    *
-   * `id` accepts the numeric id or the product UUID — the same identifiers
-   * accepted elsewhere on the `/api/products/:id` path (see
+   * `id` accepts the product UUID (recommended) or the legacy numeric id —
+   * both resolve on the `/api/v1/products/:id` path (see
    * {@link ProductPortalConfigResource}).
    *
    * @example
    * const updated = await garu.products.update('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f', {
-   *   value: 5990,
+   *   value: 59.90, // reais (decimal BRL), NOT centavos
    *   pixAutomatic: true // turn on Pix Automático for this product
    * });
    */
   async update(id, params) {
     return this.http.call(
-      (signal) => this.http.client.PATCH(`/api/products/${encodeURIComponent(String(id))}`, {
+      (signal) => this.http.client.PATCH(`/api/v1/products/${encodeURIComponent(String(id))}`, {
         body: params,
         signal
       }).then((r) => r)