@garuhq/node 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+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.1.0] — 2026-04-08
+
+### Added
+
+- Initial public beta. Reference Node.js / TypeScript SDK for the Garu payment gateway.
+- `Garu` client class with `apiKey`, `baseUrl`, `timeoutMs`, `maxRetries` options.
+- `charges.create` — PIX, credit card, and boleto charges. Auto-generates `X-Idempotency-Key`
+  (UUIDv4) unless the caller supplies one; safe to retry against the Chunk 2 backend cache.
+- `charges.get` / `charges.list` / `charges.refund`.
+- `meta.get` — capability introspection via `GET /api/meta`.
+- `webhooks.verify` — HMAC-SHA256 signature verification, constant-time comparison,
+  configurable tolerance window (default 300s). Matches backend `X-Garu-Signature` format
+  `t=<ts>,v1=<hex>`.
+- Typed error hierarchy: `GaruAuthenticationError`, `GaruPermissionError`, `GaruNotFoundError`,
+  `GaruValidationError`, `GaruRateLimitError`, `GaruServerError`, `GaruConnectionError`,
+  `GaruSignatureVerificationError`. Every error has a stable `code` string.
+- Automatic retries with exponential backoff + full jitter on 408/429/5xx and connection
+  errors. Honors `Retry-After`. Never retries 4xx validation errors.
+- One runtime dependency (`openapi-fetch`). Node.js ≥ 18 (native `fetch`, `crypto.randomUUID`).
+- Dual ESM + CJS build via `tsup` with full `.d.ts`.
+- Wire types generated from the live backend OpenAPI spec via `openapi-typescript` —
+  `npm run generate` refreshes `src/generated/{openapi.json, schema.d.ts}`.
+- Contract tests assert the generated snapshot still covers every endpoint the SDK uses.
+- GitHub Actions CI runs typecheck, tests, and build on Node 18 / 20 / 22.
+
+### Known limitations
+
+- Only `charges` and `meta` namespaces. Customers, products, subscriptions, checkout
+  sessions, and webhook-endpoint management land in a future release.
+- `charges.list` is intentionally omitted — the backend does not yet expose
+  `GET /api/transactions`. It will land when the backend grows a seller-scoped list endpoint.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Garu Pagamentos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# @garuhq/node
+
+Official Node.js / TypeScript SDK for the [Garu](https://garu.com.br) payment gateway.
+
+- **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`.
+- **ESM + CJS** dual build.
+
+## Install
+
+```bash
+npm install @garuhq/node
+# or
+pnpm add @garuhq/node
+# or
+yarn add @garuhq/node
+```
+
+## 60-second quickstart
+
+```ts
+import { Garu } from '@garuhq/node';
+
+const garu = new Garu({ apiKey: process.env.GARU_API_KEY });
+
+// Create a PIX charge
+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', // CPF, digits only
+    phone: '11987654321'
+  }
+});
+
+console.log(charge.id, charge.status);
+```
+
+## Authentication
+
+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.
+
+```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.
+
+## Surface
+
+### `garu.charges`
+
+| Method                | What it does                                 |
+| --------------------- | -------------------------------------------- |
+| `create(params)`      | Create a PIX, credit-card, or boleto charge. |
+| `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.
+
+### `garu.meta`
+
+```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`
+
+Verify an incoming webhook before trusting its body. Uses HMAC-SHA256 with constant-time
+comparison.
+
+```ts
+import express from 'express';
+import { Garu, GaruSignatureVerificationError } from '@garuhq/node';
+
+const app = express();
+
+app.post('/webhooks/garu', express.raw({ type: 'application/json' }), (req, res) => {
+  try {
+    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!
+    });
+
+    // handle event
+    console.log('Received', event);
+    res.sendStatus(200);
+  } catch (err) {
+    if (err instanceof GaruSignatureVerificationError) return res.sendStatus(400);
+    throw err;
+  }
+});
+```
+
+## Errors
+
+Every error extends `GaruError` and has a stable `code`:
+
+```ts
+import {
+  GaruAPIError,
+  GaruNotFoundError,
+  GaruRateLimitError,
+  GaruValidationError
+} from '@garuhq/node';
+
+try {
+  await garu.charges.refund(4472, { amount: 1000 });
+} catch (err) {
+  if (err instanceof GaruNotFoundError) {
+    /* 404 */
+  }
+  if (err instanceof GaruValidationError) {
+    /* 400/422 */
+  }
+  if (err instanceof GaruRateLimitError) {
+    console.log('Retry in', err.retryAfterSec, 'seconds');
+  }
+  if (err instanceof GaruAPIError) {
+    console.log(err.status, err.requestId, err.body);
+  }
+}
+```
+
+## 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)
+});
+```
+
+## TypeScript
+
+Ships with full `.d.ts` and strict types. All public types are exported from the root:
+
+```ts
+import type {
+  Charge,
+  ChargeStatus,
+  CreateChargeParams,
+  Customer,
+  CardInfo,
+  PaymentMethod,
+  MetaResponse
+} from '@garuhq/node';
+```
+
+## License
+
+MIT.

package/dist/index.cjs

@@ -0,0 +1,445 @@
+'use strict';
+
+var createClient = require('openapi-fetch');
+var crypto = require('crypto');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var createClient__default = /*#__PURE__*/_interopDefault(createClient);
+
+// src/http.ts
+
+// src/errors.ts
+var GaruError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "GaruError";
+    this.code = code;
+  }
+};
+var GaruConnectionError = class extends GaruError {
+  connectionCause;
+  constructor(message, connectionCause) {
+    super("connection_error", message);
+    this.name = "GaruConnectionError";
+    this.connectionCause = connectionCause;
+  }
+};
+var GaruSignatureVerificationError = class extends GaruError {
+  constructor(message) {
+    super("signature_verification_failed", message);
+    this.name = "GaruSignatureVerificationError";
+  }
+};
+var GaruAPIError = class extends GaruError {
+  status;
+  requestId;
+  body;
+  constructor(code, message, status, requestId, body) {
+    super(code, message);
+    this.name = "GaruAPIError";
+    this.status = status;
+    this.requestId = requestId;
+    this.body = body;
+  }
+};
+var GaruAuthenticationError = class extends GaruAPIError {
+  constructor(message, status, requestId, body) {
+    super("authentication_error", message, status, requestId, body);
+    this.name = "GaruAuthenticationError";
+  }
+};
+var GaruPermissionError = class extends GaruAPIError {
+  constructor(message, status, requestId, body) {
+    super("permission_error", message, status, requestId, body);
+    this.name = "GaruPermissionError";
+  }
+};
+var GaruNotFoundError = class extends GaruAPIError {
+  constructor(message, status, requestId, body) {
+    super("not_found", message, status, requestId, body);
+    this.name = "GaruNotFoundError";
+  }
+};
+var GaruValidationError = class extends GaruAPIError {
+  constructor(message, status, requestId, body) {
+    super("validation_error", message, status, requestId, body);
+    this.name = "GaruValidationError";
+  }
+};
+var GaruRateLimitError = class extends GaruAPIError {
+  retryAfterSec;
+  constructor(message, status, requestId, body, retryAfterSec) {
+    super("rate_limited", message, status, requestId, body);
+    this.name = "GaruRateLimitError";
+    this.retryAfterSec = retryAfterSec;
+  }
+};
+var GaruServerError = class extends GaruAPIError {
+  constructor(message, status, requestId, body) {
+    super("server_error", message, status, requestId, body);
+    this.name = "GaruServerError";
+  }
+};
+function mapApiError(status, body, requestId, retryAfterSec) {
+  const message = extractMessage(body) ?? `Garu API returned HTTP ${status}`;
+  if (status === 401)
+    return new GaruAuthenticationError(message, status, requestId, body);
+  if (status === 403)
+    return new GaruPermissionError(message, status, requestId, body);
+  if (status === 404)
+    return new GaruNotFoundError(message, status, requestId, body);
+  if (status === 400 || status === 422) {
+    return new GaruValidationError(message, status, requestId, body);
+  }
+  if (status === 429) {
+    return new GaruRateLimitError(message, status, requestId, body, retryAfterSec);
+  }
+  if (status >= 500)
+    return new GaruServerError(message, status, requestId, body);
+  return new GaruAPIError("api_error", message, status, requestId, body);
+}
+function extractMessage(body) {
+  if (typeof body === "string")
+    return body;
+  if (body && typeof body === "object") {
+    const m = body.message;
+    if (typeof m === "string")
+      return m;
+    if (Array.isArray(m) && m.every((x) => typeof x === "string"))
+      return m.join("; ");
+  }
+  return null;
+}
+
+// src/http.ts
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var HttpClient = class {
+  client;
+  cfg;
+  constructor(cfg) {
+    this.cfg = cfg;
+    const fetchImpl = cfg.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+      throw new GaruConnectionError(
+        "No fetch implementation available. Node.js >= 18 is required."
+      );
+    }
+    const headers = {
+      Accept: "application/json",
+      "User-Agent": cfg.userAgent
+    };
+    if (cfg.apiKey)
+      headers.Authorization = `Bearer ${cfg.apiKey}`;
+    this.client = createClient__default.default({
+      baseUrl: cfg.baseUrl.replace(/\/+$/, ""),
+      fetch: fetchImpl,
+      headers
+    });
+  }
+  /**
+   * Issue one HTTP call against the typed client, with retries + error mapping.
+   *
+   * `fn` is invoked up to `maxRetries + 1` times. The timeout in `cfg.timeoutMs`
+   * is enforced via `AbortController`.
+   */
+  async call(fn) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.cfg.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.cfg.timeoutMs);
+      try {
+        const { data, error, response } = await fn(controller.signal);
+        clearTimeout(timer);
+        if (response.ok) {
+          return data;
+        }
+        const requestId = response.headers.get("x-request-id");
+        const retryAfterSec = parseRetryAfter(response.headers.get("retry-after"));
+        const apiError = mapApiError(response.status, error ?? null, requestId, retryAfterSec);
+        lastError = apiError;
+        if (!RETRYABLE_STATUSES.has(response.status) || attempt === this.cfg.maxRetries) {
+          throw apiError;
+        }
+        await sleep(backoffDelay(attempt, retryAfterSec));
+        continue;
+      } catch (err) {
+        clearTimeout(timer);
+        if (isGaruApiError(err))
+          throw err;
+        const connErr = err instanceof Error && err.name === "AbortError" ? new GaruConnectionError(`Request timed out after ${this.cfg.timeoutMs}ms`, err) : new GaruConnectionError(err instanceof Error ? err.message : "Network error", err);
+        lastError = connErr;
+        if (attempt === this.cfg.maxRetries)
+          throw connErr;
+        await sleep(backoffDelay(attempt, null));
+        continue;
+      }
+    }
+    throw lastError ?? new GaruConnectionError("Request failed with no error captured");
+  }
+};
+function isGaruApiError(err) {
+  return err instanceof Error && err.name.startsWith("Garu") && err.name.endsWith("Error");
+}
+function parseRetryAfter(value) {
+  if (!value)
+    return null;
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+function backoffDelay(attempt, retryAfterSec) {
+  if (retryAfterSec !== null) {
+    return retryAfterSec * 1e3 + Math.random() * 250;
+  }
+  const base = 500 * 2 ** attempt;
+  const cap = 8e3;
+  return Math.min(cap, base) * Math.random();
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function generateIdempotencyKey() {
+  return crypto.randomUUID();
+}
+
+// src/types.ts
+function toWirePaymentMethod(pm) {
+  return pm === "credit_card" ? "creditcard" : pm;
+}
+
+// src/resources/charges.ts
+var Charges = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create a charge (PIX, credit card, or boleto).
+   *
+   * Automatically attaches an `X-Idempotency-Key` header — if you don't pass
+   * `idempotencyKey`, the SDK generates a UUIDv4. Safe to retry: the backend
+   * caches the first response for 24h.
+   *
+   * @example
+   * // PIX charge
+   * 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'
+   *   }
+   * });
+   * console.log(charge.id, charge.status);
+   *
+   * @example
+   * // Credit card charge, 3 installments
+   * const charge = await garu.charges.create({
+   *   productId: 'b3f2c1e8-6e4a-4b9f-9d1c-2a1f6c3d4e5f',
+   *   paymentMethod: 'credit_card',
+   *   customer: { name: 'Maria Silva', email: 'maria@exemplo.com.br', document: '12345678909', phone: '11987654321' },
+   *   cardInfo: {
+   *     cardNumber: '4111111111111111',
+   *     cvv: '123',
+   *     expirationDate: '2030-12',
+   *     holderName: 'MARIA SILVA',
+   *     installments: 3
+   *   }
+   * });
+   */
+  async create(params) {
+    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
+    const body = this.buildCreateBody(params);
+    return this.http.call(
+      (signal) => this.http.client.POST("/api/transactions", {
+        body,
+        headers: { "X-Idempotency-Key": idempotencyKey },
+        signal
+      })
+    );
+  }
+  /**
+   * Fetch a single charge by numeric ID.
+   *
+   * @example
+   * const charge = await garu.charges.get(4472);
+   * if (charge.status === 'paid') { ... }
+   */
+  async get(id) {
+    return this.http.call(
+      (signal) => this.http.client.GET("/api/transactions/{id}", {
+        params: { path: { id } },
+        signal
+      })
+    );
+  }
+  /**
+   * Refund a charge — fully, or partially by passing `amount` in centavos.
+   *
+   * @example
+   * // Full refund
+   * await garu.charges.refund(4472);
+   *
+   * @example
+   * // Partial refund of R$ 10,00
+   * await garu.charges.refund(4472, { amount: 1000, reason: 'customer_request' });
+   */
+  async refund(id, params = {}) {
+    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
+    const body = {};
+    if (params.amount !== void 0)
+      body.amount = params.amount;
+    if (params.reason !== void 0)
+      body.reason = params.reason;
+    return this.http.call(
+      (signal) => this.http.client.POST("/api/transactions/{id}/refund", {
+        params: { path: { id } },
+        body,
+        headers: { "X-Idempotency-Key": idempotencyKey },
+        signal
+      })
+    );
+  }
+  buildCreateBody(params) {
+    const body = {
+      customer: params.customer,
+      productId: params.productId,
+      paymentMethodId: toWirePaymentMethod(params.paymentMethod),
+      link: params.link ?? null,
+      affiliateId: params.affiliateId ?? null
+    };
+    if (params.additionalInfo !== void 0)
+      body.additionalInfo = params.additionalInfo;
+    if (params.priceId !== void 0)
+      body.priceId = params.priceId;
+    if (params.checkoutSessionToken !== void 0) {
+      body.checkoutSessionToken = params.checkoutSessionToken;
+    }
+    if (params.cardInfo)
+      body.CardInfo = params.cardInfo;
+    return body;
+  }
+};
+
+// src/resources/meta.ts
+var Meta = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Fetch the API's current capability payload.
+   *
+   * @example
+   * const meta = await garu.meta.get();
+   * console.log(meta.version, meta.payment_methods);
+   * if (meta.features.subscriptions) { ... }
+   */
+  async get() {
+    return this.http.call(
+      (signal) => this.http.client.GET("/api/meta", { signal })
+    );
+  }
+};
+var webhooks = {
+  verify(params) {
+    const { signature, secret, payload } = params;
+    const toleranceSec = params.toleranceSec ?? 300;
+    const now = params.now ?? Date.now;
+    if (!signature || typeof signature !== "string") {
+      throw new GaruSignatureVerificationError("Missing or malformed X-Garu-Signature header");
+    }
+    const parts = parseSignatureHeader(signature);
+    if (parts === null) {
+      throw new GaruSignatureVerificationError(
+        "X-Garu-Signature header does not match expected format t=<ts>,v1=<hex>"
+      );
+    }
+    const payloadStr = typeof payload === "string" ? payload : payload.toString("utf8");
+    const signedPayload = `${parts.timestamp}.${payloadStr}`;
+    const expected = crypto.createHmac("sha256", secret).update(signedPayload).digest("hex");
+    const expectedBuf = Buffer.from(expected, "hex");
+    const providedBuf = Buffer.from(parts.v1, "hex");
+    if (expectedBuf.length !== providedBuf.length || !crypto.timingSafeEqual(expectedBuf, providedBuf)) {
+      throw new GaruSignatureVerificationError("Signature does not match computed HMAC");
+    }
+    const nowSec = Math.floor(now() / 1e3);
+    if (Math.abs(nowSec - parts.timestamp) > toleranceSec) {
+      throw new GaruSignatureVerificationError(
+        `Signature timestamp outside tolerance window (${toleranceSec}s)`
+      );
+    }
+    let event;
+    try {
+      event = JSON.parse(payloadStr);
+    } catch {
+      throw new GaruSignatureVerificationError("Webhook payload is not valid JSON");
+    }
+    return { timestamp: parts.timestamp, event };
+  }
+};
+function parseSignatureHeader(header) {
+  const fields = {};
+  for (const part of header.split(",")) {
+    const idx = part.indexOf("=");
+    if (idx === -1)
+      return null;
+    const key = part.slice(0, idx).trim();
+    const value = part.slice(idx + 1).trim();
+    if (!key || !value)
+      return null;
+    fields[key] = value;
+  }
+  const t = fields.t;
+  const v1 = fields.v1;
+  if (!t || !v1)
+    return null;
+  const timestamp = Number(t);
+  if (!Number.isFinite(timestamp) || !/^[a-f0-9]+$/i.test(v1))
+    return null;
+  return { timestamp, v1 };
+}
+
+// src/client.ts
+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 Garu = class {
+  charges;
+  meta;
+  /**
+   * Webhook helpers. Available both as an instance member and as a static —
+   * `Garu.webhooks.verify(...)` works without constructing a client.
+   */
+  static webhooks = webhooks;
+  webhooks = webhooks;
+  constructor(options = {}) {
+    const http = new HttpClient({
+      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+      apiKey: options.apiKey,
+      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+      userAgent: `garu-node/${SDK_VERSION}`,
+      fetch: options.fetch
+    });
+    this.charges = new Charges(http);
+    this.meta = new Meta(http);
+  }
+};
+
+exports.Garu = Garu;
+exports.GaruAPIError = GaruAPIError;
+exports.GaruAuthenticationError = GaruAuthenticationError;
+exports.GaruConnectionError = GaruConnectionError;
+exports.GaruError = GaruError;
+exports.GaruNotFoundError = GaruNotFoundError;
+exports.GaruPermissionError = GaruPermissionError;
+exports.GaruRateLimitError = GaruRateLimitError;
+exports.GaruServerError = GaruServerError;
+exports.GaruSignatureVerificationError = GaruSignatureVerificationError;
+exports.GaruValidationError = GaruValidationError;
+exports.webhooks = webhooks;
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.cjs.map