@garuhq/node 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -3,6 +3,59 @@
 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
+
+- **Product writes** — the `Products` resource now wraps the create and update
+  endpoints, not just reads:
+  - `products.create(params)` — `POST /api/products`, returns the created
+    `Product`. Only `name` is required; all other fields fall back to
+    seller/server defaults. Auto-attaches an `X-Idempotency-Key` (override
+    via `params.idempotencyKey`), so the built-in retry can't create a
+    duplicate product.
+  - `products.update(id, params)` — `PATCH /api/products/{id}`, partial update
+    returning the updated `Product`. `id` accepts the numeric id or the
+    product UUID, matching the `/api/products/:id` portal-config methods.
+  - New exported param types `CreateProductParams` and `UpdateProductParams`,
+    covering `name`, `value` (centavos), `description`, `image`, `tags`,
+    `pix`, `boleto`, `creditCard`, `pixAutomatic`, `installments`,
+    `isSubscription`, `subscriptionType`, `unitLabel`, `returnUrl`,
+    `returnUrlButtonText`, and `statementDescriptor`.
+  - Both param types include `pixAutomatic` so you can toggle Pix Automático
+    on the subscription checkout at create/update time.
+
 ## [0.14.0] — 2026-05-31
 
 ### Added

package/dist/index.cjs

@@ -480,9 +480,12 @@ var ProductPortalConfigResource = class {
    */
   async get(productId) {
     return this.http.call(
-      (signal) => this.http.client.GET(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.GET(
+        `/api/v1/products/${encodeURIComponent(String(productId))}/portal-config`,
+        {
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -500,19 +503,25 @@ var ProductPortalConfigResource = class {
    */
   async set(productId, params) {
     return this.http.call(
-      (signal) => this.http.client.POST(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
-        body: params,
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.POST(
+        `/api/v1/products/${encodeURIComponent(String(productId))}/portal-config`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /** Same merge semantics as `set` — alias for HTTP-PATCH-prefering callers. */
   async patch(productId, params) {
     return this.http.call(
-      (signal) => this.http.client.PATCH(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
-        body: params,
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.PATCH(
+        `/api/v1/products/${encodeURIComponent(String(productId))}/portal-config`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -525,10 +534,13 @@ var ProductPortalConfigResource = class {
    */
   async clear(productId) {
     return this.http.call(
-      (signal) => this.http.client.DELETE(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
-        body: {},
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.DELETE(
+        `/api/v1/products/${encodeURIComponent(String(productId))}/portal-config`,
+        {
+          body: {},
+          signal
+        }
+      ).then((r) => r)
     );
   }
 };
@@ -544,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
@@ -569,11 +580,66 @@ 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
       )
     );
   }
+  /**
+   * Create a product for the authenticated seller. Returns the created
+   * product (HTTP 201). Only `name` is required; everything else falls back
+   * to seller/server defaults.
+   *
+   * Automatically attaches an `X-Idempotency-Key` header — if you don't pass
+   * `idempotencyKey`, the SDK generates a UUIDv4. This makes the built-in
+   * retry on transient failures safe: a retried POST returns the original
+   * product instead of creating a duplicate.
+   *
+   * @example
+   * const product = await garu.products.create({
+   *   name: 'Plano Mensal',
+   *   value: 49.90, // R$ 49,90 in reais (decimal BRL), NOT centavos
+   *   description: 'Acesso completo à plataforma',
+   *   pix: true,
+   *   creditCard: true,
+   *   isSubscription: true,
+   *   subscriptionType: 'monthly',
+   *   pixAutomatic: true // expose Pix Automático on the subscription checkout
+   * });
+   */
+  async create(params) {
+    const { idempotencyKey, ...body } = params;
+    const key = idempotencyKey ?? generateIdempotencyKey();
+    return this.http.call(
+      (signal) => this.http.client.POST("/api/v1/products", {
+        body,
+        headers: { "X-Idempotency-Key": key },
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Update a product (partial PATCH — only the fields you pass are changed).
+   * Returns the updated product.
+   *
+   * `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: 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/v1/products/${encodeURIComponent(String(id))}`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
 };
 
 // src/resources/scheduled-charges.ts

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,15 +547,85 @@ 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 decimal BRL / reais (e.g. `297.50`) — NOT centavos. */
+    value?: number;
+    description?: string;
+    /** HTTPS URL of the product cover image. */
+    image?: string;
+    tags?: string[];
+    pix?: boolean;
+    boleto?: boolean;
+    creditCard?: boolean;
+    /**
+     * Enable Pix Automático (BACEN auto-debit recurring Pix) on the
+     * subscription checkout. Defaults to enabled server-side. Only the
+     * subscription checkout mode reads this flag. See {@link Product.pixAutomatic}.
+     */
+    pixAutomatic?: boolean;
+    /** Max number of installments offered on credit card. */
+    installments?: number;
+    isSubscription?: boolean;
+    subscriptionType?: string;
+    unitLabel?: string;
+    returnUrl?: string;
+    returnUrlButtonText?: string;
+    /** Text shown on the buyer's card/bank statement. */
+    statementDescriptor?: string;
+    /**
+     * Idempotency key for the create request. Defaults to a generated UUIDv4.
+     * Pass your own to make a retry across process restarts safe — the backend
+     * returns the original product instead of creating a duplicate.
+     */
+    idempotencyKey?: string;
+}
+interface UpdateProductParams {
+    name?: string;
+    /** Price in decimal BRL / reais (e.g. `297.50`) — NOT centavos. */
+    value?: number;
+    description?: string;
+    image?: string;
+    tags?: string[];
+    pix?: boolean;
+    boleto?: boolean;
+    creditCard?: boolean;
+    pixAutomatic?: boolean;
+    installments?: number;
+    isSubscription?: boolean;
+    subscriptionType?: string;
+    unitLabel?: string;
+    returnUrl?: string;
+    returnUrlButtonText?: string;
+    statementDescriptor?: string;
+}
 interface MetaFeatures {
     subscriptions: boolean;
     checkout_sessions: boolean;
@@ -972,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>;
     /**
@@ -983,6 +1059,44 @@ declare class Products {
      * const product = await garu.products.get('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f');
      */
     get(uuid: string): Promise<Product>;
+    /**
+     * Create a product for the authenticated seller. Returns the created
+     * product (HTTP 201). Only `name` is required; everything else falls back
+     * to seller/server defaults.
+     *
+     * Automatically attaches an `X-Idempotency-Key` header — if you don't pass
+     * `idempotencyKey`, the SDK generates a UUIDv4. This makes the built-in
+     * retry on transient failures safe: a retried POST returns the original
+     * product instead of creating a duplicate.
+     *
+     * @example
+     * const product = await garu.products.create({
+     *   name: 'Plano Mensal',
+     *   value: 49.90, // R$ 49,90 in reais (decimal BRL), NOT centavos
+     *   description: 'Acesso completo à plataforma',
+     *   pix: true,
+     *   creditCard: true,
+     *   isSubscription: true,
+     *   subscriptionType: 'monthly',
+     *   pixAutomatic: true // expose Pix Automático on the subscription checkout
+     * });
+     */
+    create(params: CreateProductParams): Promise<Product>;
+    /**
+     * Update a product (partial PATCH — only the fields you pass are changed).
+     * Returns the updated product.
+     *
+     * `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: 59.90, // reais (decimal BRL), NOT centavos
+     *   pixAutomatic: true // turn on Pix Automático for this product
+     * });
+     */
+    update(id: string | number, params: UpdateProductParams): Promise<Product>;
 }
 
 /**
@@ -1391,4 +1505,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 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 VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, type WirePaymentMethodId, webhooks };
+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 };

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,15 +547,85 @@ 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 decimal BRL / reais (e.g. `297.50`) — NOT centavos. */
+    value?: number;
+    description?: string;
+    /** HTTPS URL of the product cover image. */
+    image?: string;
+    tags?: string[];
+    pix?: boolean;
+    boleto?: boolean;
+    creditCard?: boolean;
+    /**
+     * Enable Pix Automático (BACEN auto-debit recurring Pix) on the
+     * subscription checkout. Defaults to enabled server-side. Only the
+     * subscription checkout mode reads this flag. See {@link Product.pixAutomatic}.
+     */
+    pixAutomatic?: boolean;
+    /** Max number of installments offered on credit card. */
+    installments?: number;
+    isSubscription?: boolean;
+    subscriptionType?: string;
+    unitLabel?: string;
+    returnUrl?: string;
+    returnUrlButtonText?: string;
+    /** Text shown on the buyer's card/bank statement. */
+    statementDescriptor?: string;
+    /**
+     * Idempotency key for the create request. Defaults to a generated UUIDv4.
+     * Pass your own to make a retry across process restarts safe — the backend
+     * returns the original product instead of creating a duplicate.
+     */
+    idempotencyKey?: string;
+}
+interface UpdateProductParams {
+    name?: string;
+    /** Price in decimal BRL / reais (e.g. `297.50`) — NOT centavos. */
+    value?: number;
+    description?: string;
+    image?: string;
+    tags?: string[];
+    pix?: boolean;
+    boleto?: boolean;
+    creditCard?: boolean;
+    pixAutomatic?: boolean;
+    installments?: number;
+    isSubscription?: boolean;
+    subscriptionType?: string;
+    unitLabel?: string;
+    returnUrl?: string;
+    returnUrlButtonText?: string;
+    statementDescriptor?: string;
+}
 interface MetaFeatures {
     subscriptions: boolean;
     checkout_sessions: boolean;
@@ -972,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>;
     /**
@@ -983,6 +1059,44 @@ declare class Products {
      * const product = await garu.products.get('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f');
      */
     get(uuid: string): Promise<Product>;
+    /**
+     * Create a product for the authenticated seller. Returns the created
+     * product (HTTP 201). Only `name` is required; everything else falls back
+     * to seller/server defaults.
+     *
+     * Automatically attaches an `X-Idempotency-Key` header — if you don't pass
+     * `idempotencyKey`, the SDK generates a UUIDv4. This makes the built-in
+     * retry on transient failures safe: a retried POST returns the original
+     * product instead of creating a duplicate.
+     *
+     * @example
+     * const product = await garu.products.create({
+     *   name: 'Plano Mensal',
+     *   value: 49.90, // R$ 49,90 in reais (decimal BRL), NOT centavos
+     *   description: 'Acesso completo à plataforma',
+     *   pix: true,
+     *   creditCard: true,
+     *   isSubscription: true,
+     *   subscriptionType: 'monthly',
+     *   pixAutomatic: true // expose Pix Automático on the subscription checkout
+     * });
+     */
+    create(params: CreateProductParams): Promise<Product>;
+    /**
+     * Update a product (partial PATCH — only the fields you pass are changed).
+     * Returns the updated product.
+     *
+     * `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: 59.90, // reais (decimal BRL), NOT centavos
+     *   pixAutomatic: true // turn on Pix Automático for this product
+     * });
+     */
+    update(id: string | number, params: UpdateProductParams): Promise<Product>;
 }
 
 /**
@@ -1391,4 +1505,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 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 VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, type WirePaymentMethodId, webhooks };
+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 };

package/dist/index.js

@@ -474,9 +474,12 @@ var ProductPortalConfigResource = class {
    */
   async get(productId) {
     return this.http.call(
-      (signal) => this.http.client.GET(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.GET(
+        `/api/v1/products/${encodeURIComponent(String(productId))}/portal-config`,
+        {
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -494,19 +497,25 @@ var ProductPortalConfigResource = class {
    */
   async set(productId, params) {
     return this.http.call(
-      (signal) => this.http.client.POST(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
-        body: params,
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.POST(
+        `/api/v1/products/${encodeURIComponent(String(productId))}/portal-config`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /** Same merge semantics as `set` — alias for HTTP-PATCH-prefering callers. */
   async patch(productId, params) {
     return this.http.call(
-      (signal) => this.http.client.PATCH(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
-        body: params,
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.PATCH(
+        `/api/v1/products/${encodeURIComponent(String(productId))}/portal-config`,
+        {
+          body: params,
+          signal
+        }
+      ).then((r) => r)
     );
   }
   /**
@@ -519,10 +528,13 @@ var ProductPortalConfigResource = class {
    */
   async clear(productId) {
     return this.http.call(
-      (signal) => this.http.client.DELETE(`/api/products/${encodeURIComponent(String(productId))}/portal-config`, {
-        body: {},
-        signal
-      }).then((r) => r)
+      (signal) => this.http.client.DELETE(
+        `/api/v1/products/${encodeURIComponent(String(productId))}/portal-config`,
+        {
+          body: {},
+          signal
+        }
+      ).then((r) => r)
     );
   }
 };
@@ -538,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
@@ -563,11 +574,66 @@ 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
       )
     );
   }
+  /**
+   * Create a product for the authenticated seller. Returns the created
+   * product (HTTP 201). Only `name` is required; everything else falls back
+   * to seller/server defaults.
+   *
+   * Automatically attaches an `X-Idempotency-Key` header — if you don't pass
+   * `idempotencyKey`, the SDK generates a UUIDv4. This makes the built-in
+   * retry on transient failures safe: a retried POST returns the original
+   * product instead of creating a duplicate.
+   *
+   * @example
+   * const product = await garu.products.create({
+   *   name: 'Plano Mensal',
+   *   value: 49.90, // R$ 49,90 in reais (decimal BRL), NOT centavos
+   *   description: 'Acesso completo à plataforma',
+   *   pix: true,
+   *   creditCard: true,
+   *   isSubscription: true,
+   *   subscriptionType: 'monthly',
+   *   pixAutomatic: true // expose Pix Automático on the subscription checkout
+   * });
+   */
+  async create(params) {
+    const { idempotencyKey, ...body } = params;
+    const key = idempotencyKey ?? generateIdempotencyKey();
+    return this.http.call(
+      (signal) => this.http.client.POST("/api/v1/products", {
+        body,
+        headers: { "X-Idempotency-Key": key },
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Update a product (partial PATCH — only the fields you pass are changed).
+   * Returns the updated product.
+   *
+   * `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: 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/v1/products/${encodeURIComponent(String(id))}`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
 };
 
 // src/resources/scheduled-charges.ts

package/package.json

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