@vitrindigital/node 0.1.0

package/README.md

@@ -0,0 +1,185 @@
+# @vitrindigital/node
+
+SDK oficial Node.js para a [API da Vitrin Digital](https://api.vitrin.digital).
+
+```bash
+npm install @vitrindigital/node
+```
+
+> **Node 18+ requerido.** Usa `fetch` nativo, sem dependências externas em runtime.
+
+## Setup
+
+```ts
+import { Vitrin } from '@vitrindigital/node';
+
+const vitrin = new Vitrin({
+  apiKey: process.env.VITRIN_API_KEY!,
+  // Opcionais:
+  // baseUrl: 'https://api.vitrin.digital/api/v1',
+  // timeout: 30_000,
+  // maxRetries: 3,
+});
+```
+
+Use a chave `vd_test_*` em desenvolvimento e `vd_live_*` em produção.
+
+## Recursos
+
+### Clientes
+
+```ts
+const customer = await vitrin.customers.create({
+  name: 'Maria Silva',
+  email: 'maria@example.com',
+  cpf_cnpj: '12345678901',
+});
+
+const list = await vitrin.customers.list({ page: 1 });
+const updated = await vitrin.customers.update(customer.id, { phone: '11987654321' });
+await vitrin.customers.delete(customer.id);
+```
+
+### Cobranças
+
+```ts
+const charge = await vitrin.charges.create({
+  customer_id: customer.id,
+  amount: 99.90,
+  billing_type: 'PIX',
+  description: 'Mensalidade abril',
+  // Recomendado em fluxos com retry — evita duplo-débito
+  idempotencyKey: `mensalidade-${customer.id}-2026-04`,
+});
+
+console.log(charge.pix_qr_code);
+console.log(charge.pix_copy_paste);
+
+const refunded = await vitrin.charges.refund(charge.id, {
+  amount: 50.0, // omitir = total
+  pin: '123456',
+});
+```
+
+### Planos & Assinaturas
+
+```ts
+const plan = await vitrin.plans.create({
+  name: 'Pro Mensal',
+  price: 99.0,
+  billing_cycle: 'monthly',
+});
+
+const sub = await vitrin.subscriptions.create({
+  customer_id: customer.id,
+  plan_id: plan.id,
+  billing_type: 'CREDIT_CARD',
+  credit_card_token: 'tok_xxx',
+});
+
+await vitrin.subscriptions.cancel(sub.id, '123456');
+```
+
+### Saldo & Recebíveis
+
+```ts
+const balance = await vitrin.balance.retrieve();
+// → { available, total, pending, withdrawal_fees: { pix, ted } }
+
+const scheduled = await vitrin.balance.scheduled(90);
+// → cronograma 90 dias: PIX D+1, Boleto D+2, Cartão Nx D+30·n
+```
+
+## Webhooks
+
+Valide a assinatura HMAC do webhook antes de processar:
+
+```ts
+import { Webhooks, VitrinError } from '@vitrindigital/node';
+import express from 'express';
+
+const app = express();
+
+// IMPORTANTE: aceite o body cru, NÃO json parsed
+app.post('/webhooks/vitrin', express.raw({ type: 'application/json' }), (req, res) => {
+  try {
+    const event = Webhooks.constructEvent({
+      payload: req.body, // Buffer
+      signature: req.header('x-vitrin-signature'),
+      timestamp: req.header('x-vitrin-timestamp'),
+      eventType: req.header('x-vitrin-event'),
+      eventId: req.header('x-vitrin-event-id'),
+      secret: process.env.VITRIN_WEBHOOK_SECRET!,
+    });
+
+    console.log(event.type, event.id, event.data);
+    res.status(200).send();
+  } catch (err) {
+    if (err instanceof VitrinError) {
+      console.error('Webhook invalid:', err.message);
+      return res.status(400).send();
+    }
+    throw err;
+  }
+});
+```
+
+## Tratamento de erros
+
+Toda chamada lança subclasses de `VitrinError`:
+
+```ts
+import {
+  VitrinError, VitrinAuthError, VitrinValidationError,
+  VitrinRateLimitError, VitrinNotFoundError, VitrinServerError,
+} from '@vitrindigital/node';
+
+try {
+  await vitrin.charges.create({ /* ... */ });
+} catch (err) {
+  if (err instanceof VitrinValidationError) {
+    console.log('Campos inválidos:', err.fieldErrors);
+  } else if (err instanceof VitrinAuthError) {
+    console.log('Chave inválida ou sem permissão');
+  } else if (err instanceof VitrinRateLimitError) {
+    console.log('Aguarde antes de tentar de novo');
+  } else if (err instanceof VitrinError) {
+    console.log('Erro Vitrin:', err.statusCode, err.requestId, err.message);
+  } else {
+    throw err;
+  }
+}
+```
+
+O cliente faz **retry automático** em `429` e `5xx` com backoff exponencial
+(default: 3 tentativas). Erros 4xx (exceto 429) não são retentados.
+
+## Idempotência
+
+Inclua `idempotencyKey` em POSTs sensíveis. Se o request chegar duas vezes
+(retry de rede, deploy etc), a Vitrin reconhece pela chave e devolve a mesma
+resposta — sem cobrar duas vezes.
+
+```ts
+await vitrin.charges.create({
+  customer_id: 'cus_1',
+  amount: 100,
+  billing_type: 'PIX',
+  idempotencyKey: `pedido-${orderId}`,  // único por pedido
+});
+```
+
+## Acesso bruto
+
+Pra endpoints ainda não cobertos pelos resources:
+
+```ts
+const data = await vitrin.request<MyType>('/some/path/', {
+  method: 'POST',
+  body: { foo: 'bar' },
+});
+```
+
+## Licença
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,461 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Vitrin: () => Vitrin,
+  VitrinAuthError: () => VitrinAuthError,
+  VitrinError: () => VitrinError,
+  VitrinNetworkError: () => VitrinNetworkError,
+  VitrinNotFoundError: () => VitrinNotFoundError,
+  VitrinRateLimitError: () => VitrinRateLimitError,
+  VitrinServerError: () => VitrinServerError,
+  VitrinValidationError: () => VitrinValidationError,
+  Webhooks: () => Webhooks
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var VitrinError = class extends Error {
+  statusCode;
+  body;
+  requestId;
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.statusCode = opts.statusCode;
+    this.body = opts.body;
+    this.requestId = opts.requestId;
+  }
+};
+var VitrinAuthError = class extends VitrinError {
+};
+var VitrinValidationError = class extends VitrinError {
+  fieldErrors;
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.fieldErrors = opts.fieldErrors;
+  }
+};
+var VitrinRateLimitError = class extends VitrinError {
+};
+var VitrinNotFoundError = class extends VitrinError {
+};
+var VitrinServerError = class extends VitrinError {
+};
+var VitrinNetworkError = class extends VitrinError {
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.vitrin.digital/api/v1";
+var SDK_VERSION = "0.1.0";
+var VitrinClient = class {
+  baseUrl;
+  apiKey;
+  timeout;
+  maxRetries;
+  constructor(opts) {
+    if (!opts.apiKey) {
+      throw new Error("apiKey \xE9 obrigat\xF3rio");
+    }
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeout = opts.timeout ?? 3e4;
+    this.maxRetries = opts.maxRetries ?? 3;
+  }
+  /** Helper público pra resources. */
+  async request(path, options = {}) {
+    const { method = "GET", body, query, idempotencyKey } = options;
+    const url = this.buildUrl(path, query);
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: "application/json",
+      "User-Agent": `vitrindigital-node/${SDK_VERSION} node/${process.version}`
+    };
+    if (body !== void 0) headers["Content-Type"] = "application/json";
+    if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      let res;
+      try {
+        res = await fetch(url, {
+          method,
+          headers,
+          body: body !== void 0 ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+      } catch (err2) {
+        clearTimeout(timer);
+        const netErr = err2;
+        lastError = new VitrinNetworkError(
+          netErr.name === "AbortError" ? `Timeout ap\xF3s ${this.timeout}ms` : netErr.message || "Falha de rede"
+        );
+        if (attempt < this.maxRetries) {
+          await sleep(backoffMs(attempt));
+          continue;
+        }
+        throw lastError;
+      }
+      clearTimeout(timer);
+      const requestId = res.headers.get("x-request-id") || void 0;
+      if (res.status >= 200 && res.status < 300) {
+        if (res.status === 204) return void 0;
+        const text2 = await res.text();
+        return text2 ? JSON.parse(text2) : void 0;
+      }
+      const text = await res.text().catch(() => "");
+      let parsed = text;
+      try {
+        parsed = text ? JSON.parse(text) : null;
+      } catch {
+      }
+      const err = mapErrorResponse(res.status, parsed, requestId);
+      const retriable = res.status === 429 || res.status >= 500;
+      if (retriable && attempt < this.maxRetries) {
+        const retryAfter = parseRetryAfter(res.headers.get("retry-after"));
+        await sleep(retryAfter ?? backoffMs(attempt));
+        lastError = err;
+        continue;
+      }
+      throw err;
+    }
+    throw lastError ?? new VitrinError("Esgotou as tentativas sem erro identificado");
+  }
+  buildUrl(path, query) {
+    const url = new URL(this.baseUrl + (path.startsWith("/") ? path : `/${path}`));
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== void 0 && v !== null && v !== "") {
+          url.searchParams.set(k, String(v));
+        }
+      }
+    }
+    return url.toString();
+  }
+};
+function mapErrorResponse(status, body, requestId) {
+  const message = extractErrorMessage(body) || `HTTP ${status}`;
+  const opts = { statusCode: status, body, requestId };
+  if (status === 401 || status === 403) return new VitrinAuthError(message, opts);
+  if (status === 404) return new VitrinNotFoundError(message, opts);
+  if (status === 429) return new VitrinRateLimitError(message, opts);
+  if (status >= 500) return new VitrinServerError(message, opts);
+  if (status === 400 || status === 422) {
+    const fieldErrors = extractFieldErrors(body);
+    return new VitrinValidationError(message, { ...opts, fieldErrors });
+  }
+  return new VitrinError(message, opts);
+}
+function extractErrorMessage(body) {
+  if (!body || typeof body !== "object") return void 0;
+  const b = body;
+  if (typeof b.error === "string") return b.error;
+  if (typeof b.detail === "string") return b.detail;
+  for (const v of Object.values(b)) {
+    if (Array.isArray(v) && typeof v[0] === "string") return v[0];
+  }
+  return void 0;
+}
+function extractFieldErrors(body) {
+  if (!body || typeof body !== "object") return void 0;
+  const out = {};
+  for (const [k, v] of Object.entries(body)) {
+    if (Array.isArray(v) && v.every((item) => typeof item === "string")) {
+      out[k] = v;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function parseRetryAfter(header) {
+  if (!header) return null;
+  const seconds = Number(header);
+  if (!Number.isNaN(seconds)) return seconds * 1e3;
+  return null;
+}
+function backoffMs(attempt) {
+  const base = 250 * Math.pow(2, attempt);
+  return base + Math.floor(Math.random() * base * 0.5);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/resources/charges.ts
+var Charges = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Cria uma cobrança avulsa (PIX/Boleto/Cartão). */
+  create(params) {
+    const { idempotencyKey, ...body } = params;
+    return this.client.request("/charges/", {
+      method: "POST",
+      body,
+      idempotencyKey
+    });
+  }
+  retrieve(id) {
+    return this.client.request(`/transactions/${id}/`);
+  }
+  list(params = {}) {
+    return this.client.request("/reports/transactions/", {
+      query: params
+    });
+  }
+  refund(id, params) {
+    return this.client.request(`/payments/${id}/refund/`, {
+      method: "POST",
+      body: params
+    });
+  }
+  cancel(id, pin) {
+    return this.client.request(`/payments/${id}/cancel/`, {
+      method: "POST",
+      body: { pin }
+    });
+  }
+  /** Status atual da transação (consultado no provedor). */
+  status(id) {
+    return this.client.request(
+      `/payments/${id}/status/`
+    );
+  }
+};
+
+// src/resources/customers.ts
+var Customers = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  create(params) {
+    return this.client.request("/customers/", {
+      method: "POST",
+      body: params
+    });
+  }
+  retrieve(id) {
+    return this.client.request(`/customers/${id}/`);
+  }
+  list(params = {}) {
+    return this.client.request("/customers/", {
+      query: params
+    });
+  }
+  update(id, params) {
+    return this.client.request(`/customers/${id}/`, {
+      method: "PATCH",
+      body: params
+    });
+  }
+  delete(id) {
+    return this.client.request(`/customers/${id}/`, { method: "DELETE" });
+  }
+};
+
+// src/resources/plans.ts
+var Plans = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  create(params) {
+    return this.client.request("/plans/", { method: "POST", body: params });
+  }
+  retrieve(id) {
+    return this.client.request(`/plans/${id}/`);
+  }
+  list(params = {}) {
+    return this.client.request("/plans/", { query: params });
+  }
+  update(id, params) {
+    return this.client.request(`/plans/${id}/`, {
+      method: "PATCH",
+      body: params
+    });
+  }
+  delete(id) {
+    return this.client.request(`/plans/${id}/`, { method: "DELETE" });
+  }
+};
+
+// src/resources/subscriptions.ts
+var Subscriptions = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  create(params) {
+    return this.client.request("/subscriptions/", {
+      method: "POST",
+      body: params
+    });
+  }
+  retrieve(id) {
+    return this.client.request(`/subscriptions/${id}/`);
+  }
+  list(params = {}) {
+    return this.client.request("/subscriptions/", {
+      query: params
+    });
+  }
+  cancel(id, pin) {
+    return this.client.request(`/subscriptions/${id}/cancel/`, {
+      method: "POST",
+      body: { pin }
+    });
+  }
+};
+
+// src/resources/products.ts
+var Products = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  create(params) {
+    return this.client.request("/products/", {
+      method: "POST",
+      body: params
+    });
+  }
+  retrieve(id) {
+    return this.client.request(`/products/${id}/`);
+  }
+  list(params = {}) {
+    return this.client.request("/products/", { query: params });
+  }
+  update(id, params) {
+    return this.client.request(`/products/${id}/`, {
+      method: "PATCH",
+      body: params
+    });
+  }
+  delete(id) {
+    return this.client.request(`/products/${id}/`, { method: "DELETE" });
+  }
+};
+
+// src/resources/balance.ts
+var BalanceAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Saldo atual: disponível, pendente e total. */
+  retrieve() {
+    return this.client.request("/balance/");
+  }
+  /** Cronograma de recebíveis futuros (Pix D+1, Boleto D+2, Cartão D+30·N). */
+  scheduled(daysAhead = 90) {
+    return this.client.request("/balance/scheduled/", {
+      query: { days_ahead: daysAhead }
+    });
+  }
+};
+
+// src/webhooks.ts
+var import_node_crypto = require("crypto");
+var Webhooks = {
+  /** Valida a assinatura e retorna o evento parseado. Lança em qualquer falha. */
+  constructEvent(opts) {
+    const { payload, signature, timestamp, eventType, eventId, secret, toleranceMs = 3e5 } = opts;
+    if (!signature) {
+      throw new VitrinError("Header X-Vitrin-Signature ausente.");
+    }
+    if (!secret) {
+      throw new VitrinError("webhook secret \xE9 obrigat\xF3rio.");
+    }
+    const raw = Buffer.isBuffer(payload) ? payload : Buffer.from(payload, "utf8");
+    const expected = (0, import_node_crypto.createHmac)("sha256", secret).update(raw).digest("hex");
+    const got = signature.trim();
+    if (expected.length !== got.length || !(0, import_node_crypto.timingSafeEqual)(Buffer.from(expected, "hex"), bufferFromHex(got))) {
+      throw new VitrinError("Assinatura inv\xE1lida \u2014 payload pode ter sido adulterado.");
+    }
+    if (toleranceMs > 0 && timestamp) {
+      const tsSec = Number(timestamp);
+      if (!Number.isFinite(tsSec)) {
+        throw new VitrinError("X-Vitrin-Timestamp inv\xE1lido.");
+      }
+      const tsMs = tsSec * 1e3;
+      const drift = Math.abs(Date.now() - tsMs);
+      if (drift > toleranceMs) {
+        throw new VitrinError(
+          `Webhook fora da janela de toler\xE2ncia (drift ${drift}ms > ${toleranceMs}ms).`
+        );
+      }
+    }
+    let data;
+    try {
+      data = JSON.parse(raw.toString("utf8"));
+    } catch {
+      throw new VitrinError("Payload n\xE3o \xE9 JSON v\xE1lido.");
+    }
+    return {
+      type: eventType || "",
+      id: eventId || "",
+      timestampMs: timestamp ? Number(timestamp) * 1e3 : Date.now(),
+      data
+    };
+  }
+};
+function bufferFromHex(hex) {
+  if (hex.length % 2 !== 0) return Buffer.alloc(0);
+  return Buffer.from(hex, "hex");
+}
+
+// src/index.ts
+var Vitrin = class {
+  client;
+  charges;
+  customers;
+  plans;
+  subscriptions;
+  products;
+  balance;
+  constructor(opts) {
+    this.client = new VitrinClient(opts);
+    this.charges = new Charges(this.client);
+    this.customers = new Customers(this.client);
+    this.plans = new Plans(this.client);
+    this.subscriptions = new Subscriptions(this.client);
+    this.products = new Products(this.client);
+    this.balance = new BalanceAPI(this.client);
+  }
+  /** Acesso bruto pro caso de endpoint não coberto pelos resources. */
+  request(path, options) {
+    return this.client.request(path, options);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Vitrin,
+  VitrinAuthError,
+  VitrinError,
+  VitrinNetworkError,
+  VitrinNotFoundError,
+  VitrinRateLimitError,
+  VitrinServerError,
+  VitrinValidationError,
+  Webhooks
+});