@garuhq/node 1.1.0 → 2.0.0

package/CHANGELOG.md

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

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

@@ -633,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)
@@ -646,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 = {};
@@ -655,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
@@ -663,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)
@@ -698,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)

package/dist/index.d.cts

@@ -261,8 +261,15 @@ interface ChargeList {
 interface CancelChargeResult {
     canceled: boolean;
 }
+/**
+ * Public API v1 customer representation. 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.
+ */
 interface CustomerRecord {
-    id: number;
+    uuid: string;
     name: string;
     email: string;
     document: string;
@@ -281,10 +288,9 @@ interface CustomerRecord {
      * Resolved billing email used for outbound seller→customer emails:
      * `billingEmailOverride ?? per-seller email ?? customer.email`.
      */
-    billingEmail?: string;
+    billingEmail: string;
     /** True when a sticky `billingEmailOverride` is set for this seller. */
-    hasBillingEmailOverride?: boolean;
-    [key: string]: unknown;
+    hasBillingEmailOverride: boolean;
 }
 interface SetBillingEmailOverrideParams {
     /**
@@ -293,7 +299,14 @@ interface SetBillingEmailOverrideParams {
      */
     billingEmailOverride: string | null;
 }
-type CustomerList = PaginatedList<CustomerRecord>;
+interface CustomerList {
+    data: CustomerRecord[];
+    /** Items on this page. */
+    count: number;
+    /** Total matches across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
 interface CreateCustomerParams {
     name: string;
     email: string;
@@ -1315,9 +1328,11 @@ declare class RefundRequests {
 /**
  * Customers — manage your customer base.
  *
- * Customers are scoped to the seller identified by the API key. The backend
- * uses a junction table (`customer_seller_profile`) so the same person can
- * exist across multiple sellers without duplication.
+ * Backed by `/api/v1/customers`, keyed on `uuid`. Customers are scoped to the
+ * seller identified by the API key. The backend uses a junction table
+ * (`customer_seller_profile`) so the same person can exist across multiple
+ * sellers without duplication — creating a customer whose `document` already
+ * exists globally attaches your own profile to it instead of erroring.
  */
 declare class Customers {
     private readonly http;
@@ -1333,29 +1348,35 @@ declare class Customers {
      *   phone: '11987654321',
      *   personType: 'fisica'
      * });
+     * customer.uuid;
      */
     create(params: CreateCustomerParams): Promise<CustomerRecord>;
     /**
      * 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' });
      */
     list(params?: ListCustomersParams): Promise<CustomerList>;
     /**
-     * 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');
      */
-    get(id: number): Promise<CustomerRecord>;
+    get(uuid: string): Promise<CustomerRecord>;
     /**
-     * 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' });
      */
-    update(id: number, params: UpdateCustomerParams): Promise<CustomerRecord>;
+    update(uuid: string, params: UpdateCustomerParams): Promise<CustomerRecord>;
     /**
      * Set or clear the per-seller billing email override.
      *
@@ -1365,21 +1386,24 @@ declare class Customers {
      *
      * @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 });
      */
-    setBillingEmailOverride(id: number, params: SetBillingEmailOverrideParams): Promise<CustomerRecord>;
+    setBillingEmailOverride(uuid: string, params: SetBillingEmailOverrideParams): Promise<CustomerRecord>;
     /**
-     * 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');
      */
-    delete(id: number): Promise<void>;
+    delete(uuid: string): Promise<{
+        removed: boolean;
+    }>;
 }
 
 /**
@@ -1929,4 +1953,4 @@ declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CancelAtPeriodEndScheduledChargeParams, type CancelChargeResult, type CancelInstallmentPlanParams, 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 CreateInstallmentPlanParams, 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 Installment, type InstallmentPlan, type InstallmentPlanList, type InstallmentPlanStatus, type InstallmentStatus, type ListChargesParams, type ListCustomersParams, type ListInstallmentPlansParams, type ListProductsParams, type ListRefundRequestsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeInstallmentParams, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type RefundRequest, type RefundRequestList, type RefundRequestStatus, type ReissueInstallmentResult, type RequestPlanRefundParams, type ResendWebhookEventParams, type ResolveRefundRequestParams, 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 };
+export { type CancelAtPeriodEndScheduledChargeParams, type CancelChargeResult, type CancelInstallmentPlanParams, 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 CreateInstallmentPlanParams, 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 Installment, type InstallmentPlan, type InstallmentPlanList, type InstallmentPlanStatus, type InstallmentStatus, type ListChargesParams, type ListCustomersParams, type ListInstallmentPlansParams, type ListProductsParams, type ListRefundRequestsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeInstallmentParams, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type RefundRequest, type RefundRequestList, type RefundRequestStatus, type ReissueInstallmentResult, type RequestPlanRefundParams, type ResendWebhookEventParams, type ResolveRefundRequestParams, 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 SetBillingEmailOverrideParams, type SetProductPortalConfigParams, type UpdateCustomerParams, type UpdateProductParams, type VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, webhooks };

package/dist/index.d.ts

@@ -261,8 +261,15 @@ interface ChargeList {
 interface CancelChargeResult {
     canceled: boolean;
 }
+/**
+ * Public API v1 customer representation. 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.
+ */
 interface CustomerRecord {
-    id: number;
+    uuid: string;
     name: string;
     email: string;
     document: string;
@@ -281,10 +288,9 @@ interface CustomerRecord {
      * Resolved billing email used for outbound seller→customer emails:
      * `billingEmailOverride ?? per-seller email ?? customer.email`.
      */
-    billingEmail?: string;
+    billingEmail: string;
     /** True when a sticky `billingEmailOverride` is set for this seller. */
-    hasBillingEmailOverride?: boolean;
-    [key: string]: unknown;
+    hasBillingEmailOverride: boolean;
 }
 interface SetBillingEmailOverrideParams {
     /**
@@ -293,7 +299,14 @@ interface SetBillingEmailOverrideParams {
      */
     billingEmailOverride: string | null;
 }
-type CustomerList = PaginatedList<CustomerRecord>;
+interface CustomerList {
+    data: CustomerRecord[];
+    /** Items on this page. */
+    count: number;
+    /** Total matches across all pages. */
+    totalCount: number;
+    totalPages: number;
+}
 interface CreateCustomerParams {
     name: string;
     email: string;
@@ -1315,9 +1328,11 @@ declare class RefundRequests {
 /**
  * Customers — manage your customer base.
  *
- * Customers are scoped to the seller identified by the API key. The backend
- * uses a junction table (`customer_seller_profile`) so the same person can
- * exist across multiple sellers without duplication.
+ * Backed by `/api/v1/customers`, keyed on `uuid`. Customers are scoped to the
+ * seller identified by the API key. The backend uses a junction table
+ * (`customer_seller_profile`) so the same person can exist across multiple
+ * sellers without duplication — creating a customer whose `document` already
+ * exists globally attaches your own profile to it instead of erroring.
  */
 declare class Customers {
     private readonly http;
@@ -1333,29 +1348,35 @@ declare class Customers {
      *   phone: '11987654321',
      *   personType: 'fisica'
      * });
+     * customer.uuid;
      */
     create(params: CreateCustomerParams): Promise<CustomerRecord>;
     /**
      * 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' });
      */
     list(params?: ListCustomersParams): Promise<CustomerList>;
     /**
-     * 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');
      */
-    get(id: number): Promise<CustomerRecord>;
+    get(uuid: string): Promise<CustomerRecord>;
     /**
-     * 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' });
      */
-    update(id: number, params: UpdateCustomerParams): Promise<CustomerRecord>;
+    update(uuid: string, params: UpdateCustomerParams): Promise<CustomerRecord>;
     /**
      * Set or clear the per-seller billing email override.
      *
@@ -1365,21 +1386,24 @@ declare class Customers {
      *
      * @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 });
      */
-    setBillingEmailOverride(id: number, params: SetBillingEmailOverrideParams): Promise<CustomerRecord>;
+    setBillingEmailOverride(uuid: string, params: SetBillingEmailOverrideParams): Promise<CustomerRecord>;
     /**
-     * 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');
      */
-    delete(id: number): Promise<void>;
+    delete(uuid: string): Promise<{
+        removed: boolean;
+    }>;
 }
 
 /**
@@ -1929,4 +1953,4 @@ declare class GaruServerError extends GaruAPIError {
     constructor(message: string, status: number, requestId: string | null, body: unknown);
 }
 
-export { type CancelAtPeriodEndScheduledChargeParams, type CancelChargeResult, type CancelInstallmentPlanParams, 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 CreateInstallmentPlanParams, 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 Installment, type InstallmentPlan, type InstallmentPlanList, type InstallmentPlanStatus, type InstallmentStatus, type ListChargesParams, type ListCustomersParams, type ListInstallmentPlansParams, type ListProductsParams, type ListRefundRequestsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeInstallmentParams, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type RefundRequest, type RefundRequestList, type RefundRequestStatus, type ReissueInstallmentResult, type RequestPlanRefundParams, type ResendWebhookEventParams, type ResolveRefundRequestParams, 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 };
+export { type CancelAtPeriodEndScheduledChargeParams, type CancelChargeResult, type CancelInstallmentPlanParams, 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 CreateInstallmentPlanParams, 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 Installment, type InstallmentPlan, type InstallmentPlanList, type InstallmentPlanStatus, type InstallmentStatus, type ListChargesParams, type ListCustomersParams, type ListInstallmentPlansParams, type ListProductsParams, type ListRefundRequestsParams, type ListScheduledChargeAttemptsParams, type ListScheduledChargesParams, type ListWebhookEventsParams, type MarkPaidScheduledChargeParams, type MetaFeatures, type MetaResponse, type PaginatedList, type PauseScheduledChargeParams, type PaymentMethodExpiredPayload, type PaymentMethodExpiringPayload, type PostponeInstallmentParams, type PostponeScheduledChargeParams, type Product, type ProductList, type ProductPortalConfig, type RecurrenceConfig, type RecurrenceInterval, type RefundChargeParams, type RefundRequest, type RefundRequestList, type RefundRequestStatus, type ReissueInstallmentResult, type RequestPlanRefundParams, type ResendWebhookEventParams, type ResolveRefundRequestParams, 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 SetBillingEmailOverrideParams, type SetProductPortalConfigParams, type UpdateCustomerParams, type UpdateProductParams, type VerifiedWebhook, type VerifyWebhookParams, type WebhookEvent, type WebhookEventEndpoint, type WebhookEventList, type WebhookEventStatus, webhooks };

package/dist/index.js

@@ -627,10 +627,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)
@@ -640,7 +641,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 = {};
@@ -649,7 +654,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
@@ -657,27 +662,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)
@@ -692,30 +698,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)

package/package.json

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