@garuhq/node 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -3,6 +3,37 @@
 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/).
 
+## [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/dist/index.cjs

@@ -481,7 +481,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 +504,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 +516,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 +535,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 +556,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 +580,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 +598,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 +611,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 +622,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)

package/dist/index.d.cts

@@ -509,12 +509,17 @@ interface ChargeNowResult {
     message: string;
 }
 interface Product {
-    id: number;
+    /**
+     * @deprecated The v1 API no longer returns a numeric id — use `uuid` to
+     * address a product. Present only on legacy `/api/products/*` responses;
+     * `undefined` on v1.
+     */
+    id?: number;
     uuid: string;
     name: string;
     description: string;
     image: string;
-    /** Price in centavos (BRL × 100). */
+    /** Price in decimal BRL / reais (e.g. `297.50`) — NOT centavos. */
     value: number;
     sellerId: number;
     sellerName?: string;
@@ -528,7 +533,8 @@ interface Product {
      * checkout mode reads this flag. See {@link ScheduledPaymentMethod}.
      */
     pixAutomatic: boolean;
-    installments: number[];
+    /** Per-parcela credit-card breakdown (the amount charged per installment). */
+    installments: Installment[];
     tags?: string[];
     isSubscription?: boolean;
     subscriptionType?: string;
@@ -541,18 +547,36 @@ interface Product {
     updatedAt: string;
     [key: string]: unknown;
 }
-type ProductList = PaginatedList<Product>;
+/** One entry in a product's credit-card installment breakdown. */
+interface Installment {
+    /** Number of parcelas. */
+    quantity: number;
+    /** Amount charged per installment, in reais (BRL), with the fator markup applied. */
+    value: number;
+}
+/**
+ * List envelope returned by `products.list()`. Flat (not `{ data, meta }`) —
+ * matches the `/api/v1/products` response.
+ */
+interface ProductList {
+    data: Product[];
+    /** Items returned on this page. */
+    count: number;
+    /** Total products matching the filter across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
 interface ListProductsParams {
     page?: number;
     limit?: number;
     /** Search by product name. */
     search?: string;
-    /** Backend tab filter (e.g. `active`, `archived`). Backend default is used when omitted. */
+    /** @deprecated Not supported by the v1 API (ignored). `list()` returns the seller's own products. */
     tab?: string;
 }
 interface CreateProductParams {
     name: string;
-    /** Price in centavos (BRL × 100). */
+    /** Price in decimal BRL / reais (e.g. `297.50`) — NOT centavos. */
     value?: number;
     description?: string;
     /** HTTPS URL of the product cover image. */
@@ -585,6 +609,7 @@ interface CreateProductParams {
 }
 interface UpdateProductParams {
     name?: string;
+    /** Price in decimal BRL / reais (e.g. `297.50`) — NOT centavos. */
     value?: number;
     description?: string;
     image?: string;
@@ -1023,7 +1048,7 @@ declare class Products {
      * 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 });
      */
     list(params?: ListProductsParams): Promise<ProductList>;
     /**
@@ -1047,7 +1072,7 @@ declare class Products {
      * @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,
@@ -1061,13 +1086,13 @@ declare class Products {
      * 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
      * });
      */

package/dist/index.d.ts

@@ -509,12 +509,17 @@ interface ChargeNowResult {
     message: string;
 }
 interface Product {
-    id: number;
+    /**
+     * @deprecated The v1 API no longer returns a numeric id — use `uuid` to
+     * address a product. Present only on legacy `/api/products/*` responses;
+     * `undefined` on v1.
+     */
+    id?: number;
     uuid: string;
     name: string;
     description: string;
     image: string;
-    /** Price in centavos (BRL × 100). */
+    /** Price in decimal BRL / reais (e.g. `297.50`) — NOT centavos. */
     value: number;
     sellerId: number;
     sellerName?: string;
@@ -528,7 +533,8 @@ interface Product {
      * checkout mode reads this flag. See {@link ScheduledPaymentMethod}.
      */
     pixAutomatic: boolean;
-    installments: number[];
+    /** Per-parcela credit-card breakdown (the amount charged per installment). */
+    installments: Installment[];
     tags?: string[];
     isSubscription?: boolean;
     subscriptionType?: string;
@@ -541,18 +547,36 @@ interface Product {
     updatedAt: string;
     [key: string]: unknown;
 }
-type ProductList = PaginatedList<Product>;
+/** One entry in a product's credit-card installment breakdown. */
+interface Installment {
+    /** Number of parcelas. */
+    quantity: number;
+    /** Amount charged per installment, in reais (BRL), with the fator markup applied. */
+    value: number;
+}
+/**
+ * List envelope returned by `products.list()`. Flat (not `{ data, meta }`) —
+ * matches the `/api/v1/products` response.
+ */
+interface ProductList {
+    data: Product[];
+    /** Items returned on this page. */
+    count: number;
+    /** Total products matching the filter across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
 interface ListProductsParams {
     page?: number;
     limit?: number;
     /** Search by product name. */
     search?: string;
-    /** Backend tab filter (e.g. `active`, `archived`). Backend default is used when omitted. */
+    /** @deprecated Not supported by the v1 API (ignored). `list()` returns the seller's own products. */
     tab?: string;
 }
 interface CreateProductParams {
     name: string;
-    /** Price in centavos (BRL × 100). */
+    /** Price in decimal BRL / reais (e.g. `297.50`) — NOT centavos. */
     value?: number;
     description?: string;
     /** HTTPS URL of the product cover image. */
@@ -585,6 +609,7 @@ interface CreateProductParams {
 }
 interface UpdateProductParams {
     name?: string;
+    /** Price in decimal BRL / reais (e.g. `297.50`) — NOT centavos. */
     value?: number;
     description?: string;
     image?: string;
@@ -1023,7 +1048,7 @@ declare class Products {
      * 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 });
      */
     list(params?: ListProductsParams): Promise<ProductList>;
     /**
@@ -1047,7 +1072,7 @@ declare class Products {
      * @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,
@@ -1061,13 +1086,13 @@ declare class Products {
      * 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
      * });
      */

package/dist/index.js

@@ -475,7 +475,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
         }
@@ -498,7 +498,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
@@ -510,7 +510,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
@@ -529,7 +529,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
@@ -550,16 +550,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
@@ -575,7 +574,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
       )
     );
@@ -593,7 +592,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,
@@ -606,7 +605,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
@@ -617,19 +616,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)

package/package.json

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