@garuhq/node 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -3,6 +3,80 @@
 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/).
 
+## [2.0.0] — 2026-08-22
+
+**Breaking:** `customers` now targets the versioned public API `/api/v1/customers`,
+keyed on `uuid`. If you use `garu.customers.*`, read the migration below.
+
+### Breaking
+
+- **`customers` moved to `/api/v1/customers`** and a customer is keyed by
+  **`uuid`**, not a numeric `id`.
+  - `customers.get(id: number)` → **`customers.get(uuid: string)`** (name
+    unchanged, param type changed).
+  - `customers.update(id, params)` — same signature shape, but the id
+    argument is now the `uuid`, and the request now goes out as `PATCH`
+    (was `PUT`).
+  - `customers.setBillingEmailOverride(id, params)` / `customers.delete(id)`
+    — same, `id` → `uuid`.
+  - `CustomerRecord.id` is **removed**; there is no numeric id in the public
+    shape. Use `CustomerRecord.uuid` everywhere.
+  - **`customers.delete()` now resolves `{ removed: boolean }`** (was `void`).
+  - **`customers.list()` returns `{ data, count, totalCount, totalPages }`**
+    (was `{ data, meta }`).
+- `installmentPlans.create` and `scheduledCharges.create` are **not**
+  migrated yet — they still take a numeric `customerId`. Fetch that id from
+  the dashboard or the internal `/api/customers` endpoint until those two
+  resources move to `/api/v1` too (tracked in `SPEC-public-api-v1.md` §9
+  Phase 4 on the `gateway` repo).
+
+### Migration
+
+```ts
+// before (1.x)
+const c = await garu.customers.create({ name, email, document, phone, personType });
+c.id;                    // number
+const one = await garu.customers.get(c.id);
+await garu.customers.update(c.id, { name: 'Maria Santos' });
+await garu.customers.delete(c.id);
+
+// after (2.0.0)
+const c = await garu.customers.create({ name, email, document, phone, personType });
+c.uuid;                   // string
+const one = await garu.customers.get(c.uuid);
+await garu.customers.update(c.uuid, { name: 'Maria Santos' });
+const { removed } = await garu.customers.delete(c.uuid);
+```
+
+## [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

package/README.md

@@ -84,13 +84,13 @@ const garu = new Garu({
 
 ## Charges
 
-| 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.                       |
+| 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
 
@@ -146,13 +146,20 @@ await garu.charges.refund('6f1c9b2e-…', { amount: 10.0 }); // partial refund (
 
 ## Customers
 
-| Method               | Description                                |
-| -------------------- | ------------------------------------------ |
-| `create(params)`     | Create a new customer.                     |
-| `list(params?)`      | List customers with pagination and search. |
-| `get(id)`            | Fetch a single customer by ID.             |
-| `update(id, params)` | Update a customer's profile.               |
-| `delete(id)`         | Delete a customer.                         |
+Backed by `/api/v1/customers`, keyed on `uuid` — there is no numeric id in
+this shape. `installmentPlans.create` and `scheduledCharges.create` still
+link customers by the internal numeric id (unmigrated resources); fetch that
+id from the dashboard or the internal `/api/customers` endpoint until they
+move to `/api/v1` too.
+
+| Method                                  | Description                                     |
+| --------------------------------------- | ----------------------------------------------- |
+| `create(params)`                        | Register a customer for the current seller.     |
+| `list(params?)`                         | List customers with pagination and search.      |
+| `get(uuid)`                             | Fetch a single customer by uuid.                |
+| `update(uuid, params)`                  | Partially update a customer's profile.          |
+| `setBillingEmailOverride(uuid, params)` | Set or clear the sticky billing-email override. |
+| `delete(uuid)`                          | Remove a customer from the current seller.      |
 
 ```ts
 const customer = await garu.customers.create({
@@ -163,7 +170,7 @@ const customer = await garu.customers.create({
   personType: 'fisica'
 });
 
-const { data, meta } = await garu.customers.list({ search: 'maria', limit: 10 });
+const { data, totalCount } = await garu.customers.list({ search: 'maria', limit: 10 });
 ```
 
 ## Products

package/dist/index.cjs

@@ -323,6 +323,299 @@ var Charges = class {
   }
 };
 
+// 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
+      )
+    );
+  }
+  /**
+   * Retrieve one carnê with every parcela: due date, status, barcode line and
+   * boleto PDF.
+   *
+   * @example
+   * const carne = await garu.installmentPlans.get(uuid);
+   * const unpaid = carne.installmentsDetail?.filter((i) => i.status !== 'paid');
+   * carne.totalCollected;  // what has actually cleared, not what was billed
+   */
+  async get(uuid) {
+    return this.http.call(
+      (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)
+    );
+  }
+  /**
+   * Move one parcela to a later date. Its siblings keep theirs — this
+   * postpones a payment, it does not restructure the carnê. A slip already
+   * emitted stays payable on its original date until it expires.
+   *
+   * @example
+   * await garu.installmentPlans.postponeInstallment(uuid, 4, {
+   *   newDueDate: '2026-12-20'
+   * });
+   */
+  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
+   * const parcela = await garu.installmentPlans.markInstallmentPaid(uuid, 3);
+   * parcela.status;  // 'paid'
+   */
+  async markInstallmentPaid(uuid, number) {
+    return this.http.call(
+      (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)
+    );
+  }
+  /**
+   * 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);
+    }
+    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)
+    );
+  }
+};
+
 // src/resources/customers.ts
 var Customers = class {
   constructor(http) {
@@ -340,10 +633,11 @@ var Customers = class {
    *   phone: '11987654321',
    *   personType: 'fisica'
    * });
+   * customer.uuid;
    */
   async create(params) {
     return this.http.call(
-      (signal) => this.http.client.POST("/api/customers", {
+      (signal) => this.http.client.POST("/api/v1/customers", {
         body: params,
         signal
       }).then((r) => r)
@@ -353,7 +647,11 @@ var Customers = class {
    * List customers for the authenticated seller, with pagination and search.
    *
    * @example
-   * const { data, meta } = await garu.customers.list({ search: 'maria', limit: 10 });
+   * const { data, totalCount } = await garu.customers.list({ search: 'maria', limit: 10 });
+   *
+   * @example
+   * // Customers with at least one overdue scheduled charge (carnê included).
+   * const atRisk = await garu.customers.list({ status: 'overdue' });
    */
   async list(params = {}) {
     const query = {};
@@ -362,7 +660,7 @@ var Customers = class {
     if (params.search) query.search = params.search;
     if (params.status) query.status = params.status;
     const qs = new URLSearchParams(query).toString();
-    const url = `/api/customers${qs ? `?${qs}` : ""}`;
+    const url = `/api/v1/customers${qs ? `?${qs}` : ""}`;
     return this.http.call(
       (signal) => this.http.client.GET(url, { signal }).then(
         (r) => r
@@ -370,27 +668,28 @@ var Customers = class {
     );
   }
   /**
-   * Fetch a single customer by numeric ID.
+   * Fetch a single customer by uuid.
    *
    * @example
-   * const customer = await garu.customers.get(42);
+   * const customer = await garu.customers.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
    */
-  async get(id) {
+  async get(uuid) {
     return this.http.call(
-      (signal) => this.http.client.GET(`/api/customers/${id}`, { signal }).then(
+      (signal) => this.http.client.GET(`/api/v1/customers/${uuid}`, { signal }).then(
         (r) => r
       )
     );
   }
   /**
-   * Update a customer's profile for the current seller.
+   * Update a customer's profile for the current seller. Partial — only the
+   * fields you pass change.
    *
    * @example
-   * const updated = await garu.customers.update(42, { name: 'Maria Santos' });
+   * const updated = await garu.customers.update('a1b2c3d4-...', { name: 'Maria Santos' });
    */
-  async update(id, params) {
+  async update(uuid, params) {
     return this.http.call(
-      (signal) => this.http.client.PUT(`/api/customers/${id}`, {
+      (signal) => this.http.client.PATCH(`/api/v1/customers/${uuid}`, {
         body: params,
         signal
       }).then((r) => r)
@@ -405,30 +704,31 @@ var Customers = class {
    *
    * @example
    * // Set
-   * await garu.customers.setBillingEmailOverride(42, {
+   * await garu.customers.setBillingEmailOverride('a1b2c3d4-...', {
    *   billingEmailOverride: 'cobrancas@empresa.com.br'
    * });
    *
    * // Clear and fall back to the last-used email
-   * await garu.customers.setBillingEmailOverride(42, { billingEmailOverride: null });
+   * await garu.customers.setBillingEmailOverride('a1b2c3d4-...', { billingEmailOverride: null });
    */
-  async setBillingEmailOverride(id, params) {
+  async setBillingEmailOverride(uuid, params) {
     return this.http.call(
-      (signal) => this.http.client.PATCH(`/api/customers/${id}/billing-email-override`, {
+      (signal) => this.http.client.PATCH(`/api/v1/customers/${uuid}/billing-email-override`, {
         body: params,
         signal
       }).then((r) => r)
     );
   }
   /**
-   * Remove a customer from the current seller.
+   * Remove a customer from the current seller (unlinks your profile — the
+   * global customer and other sellers' profiles are untouched).
    *
    * @example
-   * await garu.customers.delete(42);
+   * await garu.customers.delete('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
    */
-  async delete(id) {
-    await this.http.call(
-      (signal) => this.http.client.DELETE(`/api/customers/${id}`, {
+  async delete(uuid) {
+    return this.http.call(
+      (signal) => this.http.client.DELETE(`/api/v1/customers/${uuid}`, {
         body: {},
         signal
       }).then((r) => r)
@@ -1166,6 +1466,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;
@@ -1187,6 +1491,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);