@garuhq/node 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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.3.0] — 2026-04-28
+
+### Added
+
+- `products` resource on the `Garu` client.
+  - `products.list({ page, limit, search, tab })` — paginated listing of the
+    authenticated seller's products (`GET /api/products/seller`).
+  - `products.get(uuid)` — fetch a single product by UUID
+    (`GET /api/products/uuid/{uuid}`). The UUID is the same identifier
+    accepted by `charges.create({ productId })`, so `products.list` is
+    the discovery path before creating a charge.
+- `Product`, `ProductList`, `ListProductsParams` types exported from the
+  package root.
+
 ## [0.1.1] — 2026-04-08
 
 ### Security

package/README.md

@@ -1,15 +1,32 @@
+<div align="center">
+
 # @garuhq/node
 
-Official Node.js / TypeScript SDK for the [Garu](https://garu.com.br) payment gateway.
+The official Node.js / TypeScript SDK for the [Garu](https://garu.com.br) payment gateway.
+
+[![npm version](https://img.shields.io/npm/v/@garuhq/node.svg)](https://www.npmjs.com/package/@garuhq/node)
+[![CI](https://img.shields.io/github/actions/workflow/status/Garu-Pagamentos/garu-node/release.yml?label=CI)](https://github.com/Garu-Pagamentos/garu-node/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+
+<p>
+  <a href="#quickstart">Quickstart</a> · 
+  <a href="#charges">Charges</a> · 
+  <a href="#customers">Customers</a> · 
+  <a href="#webhooks">Webhooks</a> · 
+  <a href="#error-handling">Errors</a>
+</p>
+
+</div>
 
-- **Typed end-to-end** — wire types are generated from the backend's OpenAPI spec, so the
-  SDK can never drift from the API. Run `npm run generate` to refresh.
-- **LLM-optimized** — every public method has a JSDoc `@example` so agents can autocomplete a
-  working call from partial input.
-- **Tiny footprint** — one runtime dependency ([`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/),
-  ~4 KB). Node.js ≥ 18, native `fetch`, native `crypto`.
-- **Safe to retry** — automatic idempotency keys on every mutation, exponential backoff with
-  full jitter, honors `Retry-After`.
+---
+
+Brazilian payments (PIX, credit card, boleto) in a few lines of code.
+
+- **Typed end-to-end** — wire types generated from the backend's OpenAPI spec; the SDK can never drift from the API.
+- **Tiny footprint** — one runtime dependency ([`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/), ~4 KB). Native `fetch`, native `crypto`.
+- **Safe to retry** — automatic idempotency keys on every mutation, exponential backoff with full jitter, honors `Retry-After`.
+- **LLM-friendly** — every public method has JSDoc `@example` blocks for agent autocomplete.
 - **ESM + CJS** dual build.
 
 ## Install
@@ -22,7 +39,7 @@ pnpm add @garuhq/node
 yarn add @garuhq/node
 ```
 
-## 60-second quickstart
+## Quickstart
 
 ```ts
 import { Garu } from '@garuhq/node';
@@ -37,53 +54,129 @@ const charge = await garu.charges.create({
     name: 'Maria Silva',
     email: 'maria@exemplo.com.br',
     document: '12345678909', // CPF, digits only
-    phone: '11987654321'
-  }
+    phone: '11987654321',
+  },
 });
 
 console.log(charge.id, charge.status);
 ```
 
-## Authentication
+## Setup
 
-Get your API key from the [Garu dashboard](https://garu.com.br/inicio) → **API Keys**. Use
-`sk_test_…` for test mode and `sk_live_…` for production.
+Get your API key from the [Garu dashboard](https://garu.com.br/inicio) → **API Keys**.
 
 ```ts
 const garu = new Garu({ apiKey: process.env.GARU_API_KEY });
 ```
 
-Public endpoints (`meta.get`, public checkout-style `charges.create`) also work without an
-API key.
+> [!NOTE]
+> Use `sk_test_…` for test mode and `sk_live_…` for production. Public endpoints like `meta.get` work without a key.
+
+## Configuration
 
-## Surface
+```ts
+const garu = new Garu({
+  apiKey: process.env.GARU_API_KEY,
+  timeoutMs: 30_000, // default
+  maxRetries: 2,     // default (3 total attempts)
+});
+```
 
-### `garu.charges`
+## Charges
 
-| Method                | What it does                                 |
+| Method                | Description                                  |
 | --------------------- | -------------------------------------------- |
 | `create(params)`      | Create a PIX, credit-card, or boleto charge. |
+| `list(params?)`       | List charges with pagination and filters.    |
 | `get(id)`             | Fetch a single charge by ID.                 |
 | `refund(id, params?)` | Refund a charge fully or partially.          |
 
-Every mutation automatically attaches an `X-Idempotency-Key` header (UUIDv4) unless you pass
-one via `params.idempotencyKey`. Safe to retry — the backend caches the first response for
-24h.
+### Create a PIX charge
+
+```ts
+const charge = await garu.charges.create({
+  productId: 'b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f',
+  paymentMethod: 'pix',
+  customer: {
+    name: 'Maria Silva',
+    email: 'maria@exemplo.com.br',
+    document: '12345678909',
+    phone: '11987654321',
+  },
+});
+```
 
-### `garu.meta`
+### Create a credit card charge
+
+```ts
+const charge = await garu.charges.create({
+  productId: 'b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f',
+  paymentMethod: 'credit_card',
+  card: {
+    number: '4111111111111111',
+    holderName: 'MARIA SILVA',
+    expirationMonth: '12',
+    expirationYear: '2028',
+    cvv: '123',
+  },
+  customer: {
+    name: 'Maria Silva',
+    email: 'maria@exemplo.com.br',
+    document: '12345678909',
+    phone: '11987654321',
+  },
+});
+```
+
+### List charges
+
+```ts
+const { data, meta } = await garu.charges.list({ limit: 10 });
+```
+
+### Refund a charge
+
+```ts
+await garu.charges.refund(4472, { amount: 1000 }); // partial refund (R$10.00)
+```
+
+> [!TIP]
+> Every mutation automatically attaches an `X-Idempotency-Key` header (UUIDv4) unless you provide one via `params.idempotencyKey`. Safe to retry — the backend caches the first response for 24h.
+
+## 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.                            |
+
+```ts
+const customer = await garu.customers.create({
+  name: 'Maria Silva',
+  email: 'maria@exemplo.com.br',
+  document: '12345678909',
+  phone: '11987654321',
+  personType: 'fisica',
+});
+
+const { data, meta } = await garu.customers.list({ search: 'maria', limit: 10 });
+```
+
+## Meta
+
+Discover available payment methods and webhook events. No authentication required.
 
 ```ts
 const meta = await garu.meta.get();
 console.log(meta.version, meta.payment_methods, meta.webhook_events);
 ```
 
-Unauthenticated. Use this to discover which payment methods and webhook events are
-currently supported.
-
-### `Garu.webhooks.verify`
+## Webhooks
 
-Verify an incoming webhook before trusting its body. Uses HMAC-SHA256 with constant-time
-comparison.
+Verify incoming webhooks with HMAC-SHA256 and constant-time comparison.
 
 ```ts
 import express from 'express';
@@ -96,10 +189,9 @@ app.post('/webhooks/garu', express.raw({ type: 'application/json' }), (req, res)
     const { event } = Garu.webhooks.verify({
       payload: req.body, // raw Buffer — do NOT re-serialize parsed JSON
       signature: req.header('x-garu-signature') ?? '',
-      secret: process.env.GARU_WEBHOOK_SECRET!
+      secret: process.env.GARU_WEBHOOK_SECRET!,
     });
 
-    // handle event
     console.log('Received', event);
     res.sendStatus(200);
   } catch (err) {
@@ -109,16 +201,19 @@ app.post('/webhooks/garu', express.raw({ type: 'application/json' }), (req, res)
 });
 ```
 
-## Errors
+> [!IMPORTANT]
+> Always pass the raw request body to `verify()`. Parsing and re-serializing JSON will break the signature check.
 
-Every error extends `GaruError` and has a stable `code`:
+## Error handling
+
+Every error extends `GaruError`. API errors include `status`, `requestId`, and `body`.
 
 ```ts
 import {
   GaruAPIError,
   GaruNotFoundError,
   GaruRateLimitError,
-  GaruValidationError
+  GaruValidationError,
 } from '@garuhq/node';
 
 try {
@@ -128,7 +223,7 @@ try {
     /* 404 */
   }
   if (err instanceof GaruValidationError) {
-    /* 400/422 */
+    /* 400 / 422 */
   }
   if (err instanceof GaruRateLimitError) {
     console.log('Retry in', err.retryAfterSec, 'seconds');
@@ -139,23 +234,24 @@ try {
 }
 ```
 
+| Error class                         | HTTP status        |
+| ----------------------------------- | ------------------ |
+| `GaruAuthenticationError`           | `401`              |
+| `GaruPermissionError`               | `403`              |
+| `GaruNotFoundError`                 | `404`              |
+| `GaruValidationError`               | `400` / `422`      |
+| `GaruRateLimitError`                | `429`              |
+| `GaruServerError`                   | `5xx`              |
+| `GaruConnectionError`               | Network failure    |
+| `GaruSignatureVerificationError`    | Webhook mismatch   |
+
 ## Retries
 
-The SDK retries idempotent requests automatically on connection errors, `408`, `429`, and
-`5xx` responses. Exponential backoff with full jitter. Honors `Retry-After`. Never retries
-`4xx` validation errors.
-
-```ts
-const garu = new Garu({
-  apiKey: process.env.GARU_API_KEY,
-  timeoutMs: 30_000, // default
-  maxRetries: 2 // default (so 3 total attempts)
-});
-```
+The SDK retries automatically on connection errors, `408`, `429`, and `5xx` responses. Exponential backoff with full jitter. Honors `Retry-After`. Never retries `4xx` validation errors.
 
 ## TypeScript
 
-Ships with full `.d.ts` and strict types. All public types are exported from the root:
+Ships with full `.d.ts` and strict types. All public types are re-exported from the root:
 
 ```ts
 import type {
@@ -165,10 +261,14 @@ import type {
   Customer,
   CardInfo,
   PaymentMethod,
-  MetaResponse
+  MetaResponse,
 } from '@garuhq/node';
 ```
 
+## Security
+
+To report a vulnerability, **do not open a public issue**. See [SECURITY.md](SECURITY.md) for responsible disclosure instructions.
+
 ## License
 
-MIT.
+MIT — see [LICENSE](LICENSE) for details.

package/dist/index.cjs

@@ -222,7 +222,7 @@ var Charges = class {
    *     phone: '11987654321'
    *   }
    * });
-   * console.log(charge.id, charge.status);
+   * // charge.id, charge.status
    *
    * @example
    * // Credit card charge, 3 installments
@@ -250,6 +250,28 @@ var Charges = class {
       })
     );
   }
+  /**
+   * List charges for the authenticated seller, with pagination and filters.
+   *
+   * @example
+   * const { data, meta } = await garu.charges.list({ status: 'paid', limit: 10 });
+   * // meta.total paid charges
+   */
+  async list(params = {}) {
+    const query = {};
+    if (params.page !== void 0) query.page = String(params.page);
+    if (params.limit !== void 0) query.limit = String(params.limit);
+    if (params.status) query.status = params.status;
+    if (params.search) query.search = params.search;
+    if (params.paymentMethod) query.paymentMethod = params.paymentMethod;
+    const qs = new URLSearchParams(query).toString();
+    const url = `/api/transactions${qs ? `?${qs}` : ""}`;
+    return this.http.call(
+      (signal) => this.http.client.GET(url, { signal }).then(
+        (r) => r
+      )
+    );
+  }
   /**
    * Fetch a single charge by numeric ID.
    *
@@ -308,6 +330,93 @@ var Charges = class {
   }
 };
 
+// src/resources/customers.ts
+var Customers = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Create a customer and link it to the current seller.
+   *
+   * @example
+   * const customer = await garu.customers.create({
+   *   name: 'Maria Silva',
+   *   email: 'maria@exemplo.com.br',
+   *   document: '12345678909',
+   *   phone: '11987654321',
+   *   personType: 'fisica'
+   * });
+   */
+  async create(params) {
+    return this.http.call(
+      (signal) => this.http.client.POST("/api/customers", {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * List customers for the authenticated seller, with pagination and search.
+   *
+   * @example
+   * const { data, meta } = await garu.customers.list({ search: 'maria', 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;
+    const qs = new URLSearchParams(query).toString();
+    const url = `/api/customers${qs ? `?${qs}` : ""}`;
+    return this.http.call(
+      (signal) => this.http.client.GET(url, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+  /**
+   * Fetch a single customer by numeric ID.
+   *
+   * @example
+   * const customer = await garu.customers.get(42);
+   */
+  async get(id) {
+    return this.http.call(
+      (signal) => this.http.client.GET(`/api/customers/${id}`, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+  /**
+   * Update a customer's profile for the current seller.
+   *
+   * @example
+   * const updated = await garu.customers.update(42, { name: 'Maria Santos' });
+   */
+  async update(id, params) {
+    return this.http.call(
+      (signal) => this.http.client.PUT(`/api/customers/${id}`, {
+        body: params,
+        signal
+      }).then((r) => r)
+    );
+  }
+  /**
+   * Remove a customer from the current seller.
+   *
+   * @example
+   * await garu.customers.delete(42);
+   */
+  async delete(id) {
+    await this.http.call(
+      (signal) => this.http.client.DELETE(`/api/customers/${id}`, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+};
+
 // src/resources/meta.ts
 var Meta = class {
   constructor(http) {
@@ -328,6 +437,48 @@ var Meta = class {
     );
   }
 };
+
+// src/resources/products.ts
+var Products = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * List products for the authenticated seller, with pagination and search.
+   *
+   * @example
+   * const { data, meta } = 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}` : ""}`;
+    return this.http.call(
+      (signal) => this.http.client.GET(url, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+  /**
+   * Fetch a single product by UUID — the same identifier used by
+   * `charges.create({ productId })`.
+   *
+   * @example
+   * const product = await garu.products.get('b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f');
+   */
+  async get(uuid) {
+    return this.http.call(
+      (signal) => this.http.client.GET(`/api/products/uuid/${uuid}`, { signal }).then(
+        (r) => r
+      )
+    );
+  }
+};
 var webhooks = {
   verify(params) {
     const { signature, secret, payload } = params;
@@ -387,10 +538,12 @@ function parseSignatureHeader(header) {
 var DEFAULT_BASE_URL = "https://garu.com.br";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.3.0";
 var Garu = class {
   charges;
+  customers;
   meta;
+  products;
   /**
    * Webhook helpers. Available both as an instance member and as a static —
    * `Garu.webhooks.verify(...)` works without constructing a client.
@@ -407,7 +560,9 @@ var Garu = class {
       fetch: options.fetch
     });
     this.charges = new Charges(http);
+    this.customers = new Customers(http);
     this.meta = new Meta(http);
+    this.products = new Products(http);
   }
 };
 
@@ -423,5 +578,3 @@ exports.GaruServerError = GaruServerError;
 exports.GaruSignatureVerificationError = GaruSignatureVerificationError;
 exports.GaruValidationError = GaruValidationError;
 exports.webhooks = webhooks;
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map