@garuhq/node 0.16.0 → 1.0.0

package/CHANGELOG.md

@@ -3,6 +3,76 @@
 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

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 })
+    );
   }
 };
 

package/dist/index.d.cts

@@ -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;
@@ -814,27 +867,27 @@ interface SetProductPortalConfigParams {
 }
 
 /**
- * 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 +896,62 @@ 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);
      */
-    list(params?: ListChargesParams): Promise<ChargeList>;
+    retrieve(uuid: string): Promise<Charge>;
     /**
-     * Fetch a single charge by numeric ID.
+     * List charges for the authenticated account, newest first by default.
      *
      * @example
-     * const charge = await garu.charges.get(4472);
-     * if (charge.status === 'paid') { ... }
+     * const { data, totalCount } = await garu.charges.list({ status: 'paid', limit: 50 });
+     * console.log(`${data.length} of ${totalCount} paid charges`);
      */
-    get(id: number): Promise<Charge>;
+    list(params?: ListChargesParams): Promise<ChargeList>;
     /**
-     * Refund a charge — fully, or partially by passing `amount` in centavos.
+     * 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
-     * // Full refund
-     * await garu.charges.refund(4472);
+     * 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
-     * // Partial refund of R$ 10,00
-     * await garu.charges.refund(4472, { amount: 1000, reason: 'customer_request' });
+     * const { canceled } = await garu.charges.cancel('6f1c9b2e-...');
      */
-    refund(id: number, params?: RefundChargeParams): Promise<Charge>;
-    private buildCreateBody;
+    cancel(uuid: string): Promise<CancelChargeResult>;
+    private get;
+    private post;
 }
 
 /**
@@ -1505,4 +1567,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 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 };

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;
@@ -814,27 +867,27 @@ interface SetProductPortalConfigParams {
 }
 
 /**
- * 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 +896,62 @@ 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);
      */
-    list(params?: ListChargesParams): Promise<ChargeList>;
+    retrieve(uuid: string): Promise<Charge>;
     /**
-     * Fetch a single charge by numeric ID.
+     * List charges for the authenticated account, newest first by default.
      *
      * @example
-     * const charge = await garu.charges.get(4472);
-     * if (charge.status === 'paid') { ... }
+     * const { data, totalCount } = await garu.charges.list({ status: 'paid', limit: 50 });
+     * console.log(`${data.length} of ${totalCount} paid charges`);
      */
-    get(id: number): Promise<Charge>;
+    list(params?: ListChargesParams): Promise<ChargeList>;
     /**
-     * Refund a charge — fully, or partially by passing `amount` in centavos.
+     * 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
-     * // Full refund
-     * await garu.charges.refund(4472);
+     * 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
-     * // Partial refund of R$ 10,00
-     * await garu.charges.refund(4472, { amount: 1000, reason: 'customer_request' });
+     * const { canceled } = await garu.charges.cancel('6f1c9b2e-...');
      */
-    refund(id: number, params?: RefundChargeParams): Promise<Charge>;
-    private buildCreateBody;
+    cancel(uuid: string): Promise<CancelChargeResult>;
+    private get;
+    private post;
 }
 
 /**
@@ -1505,4 +1567,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 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 };

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,111 +211,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 })
+    );
   }
 };
 

package/package.json

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