@isnouu/zpay-sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+# SDK Z.PAY · JavaScript / TypeScript
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cliente para servidores Node.js 18+, com `import`, `require` e tipos TypeScript. Sem dependências de execução. Versão inicial: `0.1.0`.
+
+## Instalar
+
+Instale pelo npm:
+
+```sh
+npm install @isnouu/zpay-sdk
+```
+
+Para instalar a partir do arquivo distribuído com esta versão:
+
+```sh
+npm install ./zpay-sdk-0.1.0.tgz
+```
+
+Também é possível instalar a pasta local: `npm install ./sdk/javascript`. O nome importado é `@isnouu/zpay-sdk`.
+
+## Configurar e criar Pix
+
+Gere as credenciais no painel da Z.PAY e configure `ZPAY_CLIENT_ID` e `ZPAY_CLIENT_SECRET` no ambiente do seu servidor.
+
+```js
+import { ZPay, ZPayError } from '@isnouu/zpay-sdk';
+
+const zpay = new ZPay({
+  clientId: process.env.ZPAY_CLIENT_ID,
+  clientSecret: process.env.ZPAY_CLIENT_SECRET,
+});
+
+const payment = await zpay.payments.create({
+  amount: 19.90, // reais
+  payerName: 'Cliente',
+  description: 'Pedido 123',
+  idempotencyKey: 'pedido-123', // salve junto do pedido
+});
+
+console.log(payment.paymentId, payment.copyPaste);
+const current = await zpay.payments.get(payment.paymentId);
+console.log(current.status);
+```
+
+Em CommonJS: `const { ZPay, ZPayError } = require('@isnouu/zpay-sdk');`. Nunca importe o cliente com credenciais em páginas, componentes de navegador ou bots distribuídos aos clientes. A aplicação do lojista deve chamar seu próprio backend.
+
+## Recursos
+
+| Recurso | Métodos |
+| --- | --- |
+| Conta e tarifas | `account.stats()`, `account.fees()` |
+| Cobranças Pix | `payments.create()`, `payments.get(id)`, `payments.payer(id)` |
+| Doações | `donations.list(filtros)`, `donations.top(filtros)` |
+| Checkout hospedado | `checkouts.create(dados)`, `checkouts.get(id)` |
+| Saque para chave cadastrada | `withdrawals.create(dados)`, `withdrawals.get(id)`, `withdrawals.list(filtros)` |
+| Envio Pix para chave ou copia e cola | `cashouts.create(dados)`, `cashouts.get(id)` |
+| Reembolso Pix | `refunds.create({ transactionId })` |
+| Transferência interna | `transfers.recipient(destino)`, `transfers.create(dados)` |
+| Emissão de boleto | `boletos.create(dados)` |
+| Pagamento de boleto | `billPayments.preview(dados)`, `create(dados)`, `get(id)`, `list(filtros)` |
+| MEDs | `meds.list(filtros)`, `meds.get(id)` |
+| Cripto pela Purin | `crypto.createPayment(dados)`, `getPayment(id)`, `balance()`, `summary()`, `operation(id)`, `swap(dados)`, `withdraw(dados)` |
+| Subcontas | `subaccounts.create(dados)`, `list()`, `get(id)`, `update(id, dados)`, `block(id)`, `unblock(id)`, `delete(id)`, `transactions(id, filtros)`, `fund(id, dados)`, `transfer(id, dados)`, `payout(id, dados)`, `withdraw(id, dados)` |
+| Split | `splits.create(dados)`, `splits.pix(dados)`, `splits.get(id)` |
+
+Os nomes abreviados na tabela pertencem ao mesmo grupo da primeira chamada. Tipos dos parâmetros estão em `index.d.ts`. O SDK devolve a resposta da API sem transformar `pending` em confirmação de pagamento. Recursos dependem da disponibilidade e das permissões da conta na API.
+
+Valores monetários são em reais, salvo quantidade LTC e campos explicitamente em centavos, como `splits.create({ value, amount })` no modo `fixed`. A precisão LTC é de oito casas decimais.
+
+## Receber LTC e fazer swap
+
+```js
+const charge = await zpay.crypto.createPayment({
+  requestId: 'ltc-pedido-123',
+  amount: 50, // BRL; a Purin informa a quantidade exata LTC
+  currency: 'brl',
+  payCurrency: 'ltc',
+  payerName: 'Cliente',
+});
+console.log(charge.payAddress, charge.payAmount);
+const balance = await zpay.crypto.balance(); // LTC e saldo legado separados
+```
+
+O swap converte saldo em reais para USDT BEP20, enviando à carteira informada. Não converte saldo LTC. Execute apenas após a confirmação do usuário:
+
+```js
+const swap = await zpay.crypto.swap({
+  requestId: 'swap-pedido-456',
+  amount: 100, // reais a debitar
+  address: carteiraConfirmadaPeloUsuario,
+  confirmNotCoinbase: true,
+  acceptProviderRate: true, // cotação definida pela Purin no envio
+  // totpCode: codigo2faDaConta,
+});
+console.log(swap.id, swap.status, swap.receiveUSDT);
+const updated = await zpay.crypto.operation(swap.id);
+```
+
+A API com os novos endpoints Purin precisa estar publicada. Recebimento LTC exige confirmação das taxas pelo administrador; o SDK não configura tarifas nem ignora regras de KYC, telefone, 2FA ou limites do provedor. Novas cobranças USDT não estão disponíveis: recebimentos novos usam LTC, e USDT está disponível no swap BRL → USDT BEP20.
+
+## Paginação
+
+```js
+const page = await zpay.donations.list({
+  page: 1,
+  limit: 20,
+  status: 'paid',
+  date: '2026-10-27', // horário de Brasília
+  when: 'paid',
+});
+console.log(page.items, page.pagination);
+```
+
+O SDK não percorre páginas nem consulta status em loop automaticamente. Respeite os limites da API e use webhooks para acompanhar os pagamentos.
+
+## Falhas e referências
+
+```js
+try {
+  await zpay.withdrawals.create({ amount: 50, idempotencyKey: 'saque-pedido-789' });
+} catch (error) {
+  if (!(error instanceof ZPayError)) throw error;
+  console.error(error.status, error.code);
+  if (error.outcomeUnknown) {
+    // Consulte a referência original; não gere outra operação.
+    const original = await zpay.withdrawals.get('saque-pedido-789');
+    console.log(original.status);
+  }
+}
+```
+
+`ZPayError` inclui `status`, `code`, `details`, `retryAfter` e `outcomeUnknown`. Uma falha de conexão após despacho, timeout, 429 ou resposta 5xx pode deixar o resultado desconhecido. Nenhuma requisição é repetida automaticamente. Guarde `idempotencyKey` ou `requestId` antes de enviar e reutilize a referência somente para a mesma operação e os mesmos dados.
+
+O SDK exige chave explícita nos métodos cujos endpoints suportam esse campo. Checkouts e splits não oferecem essa garantia nesta versão da API; nunca repita a criação automaticamente. Reembolsos usam a transação original. Uma resposta HTTP 202 pode indicar processamento ou revisão, sem confirmar pagamento. Para cripto, salve o `id` da operação assim que recebido para consultar `crypto.operation(id)`.
+
+## Timeout e cancelamento
+
+```js
+const client = new ZPay({
+  clientId: process.env.ZPAY_CLIENT_ID,
+  clientSecret: process.env.ZPAY_CLIENT_SECRET,
+  timeoutMs: 30000,
+  // baseUrl: 'http://localhost:3000/api/v1', // desenvolvimento local
+});
+const controller = new AbortController();
+const pending = client.payments.get('payment-id', { signal: controller.signal });
+// controller.abort();
+const result = await pending;
+```
+
+Cancelar a requisição não cancela o pagamento ou saque na Z.PAY. `baseUrl` é a URL completa incluindo `/api/v1`; o padrão é `https://zpaysolution.com/api/v1`. Redirecionamentos são recusados para não encaminhar credenciais a outro destino. Você pode fornecer `fetch` compatível para testes ou instrumentação no servidor.
+
+## Desenvolvimento e pacote
+
+```sh
+npm ci
+npm test
+npm run test:types
+npm pack
+```
+
+Os testes usam respostas simuladas, sem chaves reais ou movimentação financeira. O empacotamento inclui somente cliente, tipos, README e exemplos. A publicação de novas versões requer acesso ao escopo `@isnouu` no npm.

package/examples/create-pix.mjs

@@ -0,0 +1,18 @@
+import { ZPay, ZPayError } from '@isnouu/zpay-sdk';
+
+// Run with a stable order reference, e.g. node create-pix.mjs pedido-123.
+const reference = process.argv[2];
+if (!reference) throw new Error('Informe a referência persistida do pedido.');
+const zpay = new ZPay({ clientId: process.env.ZPAY_CLIENT_ID, clientSecret: process.env.ZPAY_CLIENT_SECRET });
+
+try {
+  const payment = await zpay.payments.create({
+    amount: 19.90, payerName: 'Cliente', description: `Pedido ${reference}`, idempotencyKey: reference,
+  });
+  console.log(JSON.stringify({ paymentId: payment.paymentId, status: payment.status, copyPaste: payment.copyPaste }, null, 2));
+} catch (error) {
+  if (!(error instanceof ZPayError)) throw error;
+  console.error(error.status, error.code, error.message);
+  if (error.outcomeUnknown) console.error('Resultado incerto. Consulte a referência original antes de qualquer nova tentativa.');
+  process.exitCode = 1;
+}

package/index.cjs

@@ -0,0 +1,159 @@
+'use strict';
+
+const DEFAULT_BASE_URL = 'https://zpaysolution.com/api/v1';
+const VERSION = '0.1.0';
+
+class ZPayError extends Error {
+  constructor(message, { status = 0, code = 'ZPAY_ERROR', details = null, retryAfter = null, outcomeUnknown = false } = {}) {
+    super(message);
+    this.name = 'ZPayError';
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.retryAfter = retryAfter;
+    this.outcomeUnknown = outcomeUnknown;
+  }
+}
+
+function identifier(value) {
+  if (typeof value !== 'string' || !value.trim() || value === '.' || value === '..') throw new TypeError('Informe um identificador válido.');
+  return encodeURIComponent(value);
+}
+
+function keyed(body, field = 'idempotencyKey') {
+  const key = body?.[field];
+  if (typeof key !== 'string' || !key.trim() || key.length > 120) throw new TypeError(`Informe ${field} estável, com até 120 caracteres. Reutilize-o para a mesma operação.`);
+  if (field === 'requestId' && !/^[a-zA-Z0-9_:.-]{8,120}$/.test(key)) throw new TypeError('requestId deve ter de 8 a 120 caracteres: letras, números, ponto, dois-pontos, hífen ou sublinhado.');
+  return body;
+}
+
+class ZPay {
+  #clientId;
+  #clientSecret;
+  #fetch;
+  #baseUrl;
+  #timeoutMs;
+
+  constructor({ clientId, clientSecret, baseUrl = DEFAULT_BASE_URL, timeoutMs = 30000, fetch: fetchImpl = globalThis.fetch } = {}) {
+    if (typeof window !== 'undefined') throw new TypeError('Use o SDK no servidor; as credenciais da Z.PAY são privadas.');
+    for (const [name, value] of Object.entries({ clientId, clientSecret })) {
+      if (typeof value !== 'string' || !value.trim() || /[\r\n]/.test(value)) throw new TypeError(`Informe ${name} válido.`);
+    }
+    const url = new URL(baseUrl);
+    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (url.username || url.password || url.search || url.hash || (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback))) {
+      throw new TypeError('baseUrl deve usar HTTPS, sem credenciais, query ou fragmento. HTTP é permitido apenas em localhost.');
+    }
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647) throw new TypeError('timeoutMs deve ser um inteiro positivo de até 2147483647.');
+    if (typeof fetchImpl !== 'function') throw new TypeError('Use Node.js 18+ ou informe uma implementação de fetch.');
+    this.#clientId = clientId;
+    this.#clientSecret = clientSecret;
+    this.#fetch = fetchImpl;
+    this.#baseUrl = url.href.replace(/\/+$/, '');
+    this.#timeoutMs = timeoutMs;
+
+    const get = (path, query, options) => this.#request('GET', path, { ...options, query });
+    const post = (path, body, options) => this.#request('POST', path, { ...options, body });
+    this.account = Object.freeze({ stats: (query, options) => get('/stats', query, options), fees: options => get('/fees', undefined, options) });
+    this.payments = Object.freeze({
+      create: (body, options) => post('/payments', keyed(body), options),
+      get: (id, options) => get(`/payments/${identifier(id)}`, undefined, options),
+      payer: (id, options) => get(`/payments/${identifier(id)}/payer`, undefined, options),
+    });
+    this.donations = Object.freeze({ list: (query, options) => get('/donations', query, options), top: (query, options) => get('/top-donates', query, options) });
+    this.checkouts = Object.freeze({ create: (body, options) => post('/checkouts', body, options), get: (id, options) => get(`/checkouts/${identifier(id)}`, undefined, options) });
+    this.withdrawals = Object.freeze({
+      create: (body, options) => post('/withdraw', keyed(body), options),
+      get: (id, options) => get(`/withdrawals/${identifier(id)}`, undefined, options),
+      list: (query, options) => get('/withdrawals', query, options),
+    });
+    this.cashouts = Object.freeze({ create: (body, options) => post('/cashout', keyed(body), options), get: (id, options) => get(`/cashout/${identifier(id)}`, undefined, options) });
+    this.refunds = Object.freeze({ create: (body, options) => post('/refund', body, options) });
+    this.transfers = Object.freeze({ recipient: (to, options) => get('/transfers/internal/recipient', { to }, options), create: (body, options) => post('/transfers/internal', keyed(body), options) });
+    this.boletos = Object.freeze({ create: (body, options) => post('/boletos', keyed(body), options) });
+    this.billPayments = Object.freeze({
+      preview: (body, options) => post('/bill-payments/preview', body, options),
+      create: (body, options) => post('/bill-payments', keyed(body), options),
+      get: (id, options) => get(`/bill-payments/${identifier(id)}`, undefined, options),
+      list: (query, options) => get('/bill-payments', query, options),
+    });
+    this.meds = Object.freeze({ list: (query, options) => get('/meds', query, options), get: (id, options) => get(`/meds/${identifier(id)}`, undefined, options) });
+    this.crypto = Object.freeze({
+      createPayment: (body, options) => post('/payments/crypto', keyed(body, 'requestId'), options),
+      getPayment: (id, options) => get(`/payments/crypto/${identifier(id)}`, undefined, options),
+      balance: options => get('/crypto/balance', undefined, options),
+      summary: options => get('/crypto/purin', undefined, options),
+      operation: (id, options) => get(`/crypto/purin/operations/${identifier(id)}`, undefined, options),
+      swap: (body, options) => post('/crypto/swap', keyed(body, 'requestId'), options),
+      withdraw: (body, options) => post('/crypto/purin/withdraw', keyed(body, 'requestId'), options),
+    });
+    this.subaccounts = Object.freeze({
+      create: (body, options) => post('/subaccounts', body, options),
+      list: options => get('/subaccounts', undefined, options),
+      get: (id, options) => get(`/subaccounts/${identifier(id)}`, undefined, options),
+      update: (id, body, options) => this.#request('PATCH', `/subaccounts/${identifier(id)}`, { ...options, body }),
+      block: (id, options) => post(`/subaccounts/${identifier(id)}/block`, {}, options),
+      unblock: (id, options) => post(`/subaccounts/${identifier(id)}/unblock`, {}, options),
+      delete: (id, options) => this.#request('DELETE', `/subaccounts/${identifier(id)}`, options),
+      transactions: (id, query, options) => get(`/subaccounts/${identifier(id)}/transactions`, query, options),
+      fund: (id, body, options) => post(`/subaccounts/${identifier(id)}/fund`, keyed(body), options),
+      transfer: (id, body, options) => post(`/subaccounts/${identifier(id)}/transfer`, keyed(body), options),
+      payout: (id, body, options) => post(`/subaccounts/${identifier(id)}/payout`, keyed(body), options),
+      withdraw: (id, body, options) => post(`/subaccounts/${identifier(id)}/withdraw`, keyed(body), options),
+    });
+    this.splits = Object.freeze({ create: (body, options) => post('/split/payment', body, options), pix: (body, options) => post('/split/pix', body, options), get: (id, options) => get(`/split/payments/${identifier(id)}`, undefined, options) });
+  }
+
+  async #request(method, path, { body, query, signal } = {}) {
+    const url = new URL(this.#baseUrl + path);
+    for (const [key, value] of Object.entries(query || {})) {
+      if (value == null) continue;
+      if (!['string', 'number', 'boolean'].includes(typeof value) || (typeof value === 'number' && !Number.isFinite(value))) throw new TypeError(`Filtro inválido: ${key}.`);
+      url.searchParams.set(key, String(value));
+    }
+    // Serialize before dispatch so a local serialization error isn't reported as
+    // an uncertain financial outcome.
+    const payload = body === undefined ? undefined : JSON.stringify(body);
+    if (signal?.aborted) throw new ZPayError('Requisição cancelada antes do envio.', { code: 'REQUEST_ABORTED' });
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    let timedOut = false;
+    signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(() => { timedOut = true; controller.abort(); }, this.#timeoutMs);
+    let response;
+    try {
+      response = await this.#fetch(url.href, {
+        method, redirect: 'error', signal: controller.signal,
+        headers: { accept: 'application/json', 'content-type': 'application/json',
+          'client-id': this.#clientId, 'client-secret': this.#clientSecret, 'user-agent': `zpay-sdk-node/${VERSION}` },
+        ...(payload === undefined ? {} : { body: payload }),
+      });
+      const text = await response.text();
+      let data = null;
+      if (text) {
+        try { data = JSON.parse(text); }
+        catch (_) { throw new ZPayError('A Z.PAY retornou uma resposta que não é JSON.', { status: response.status, code: 'INVALID_RESPONSE', outcomeUnknown: method !== 'GET' }); }
+      }
+      if (!response.ok) {
+        const message = typeof data?.error === 'string' ? data.error : `Erro HTTP ${response.status} na Z.PAY.`;
+        // Do not expose credentials even if an upstream error echoes them.
+        const redact = value => typeof value === 'string' ? value.split(this.#clientSecret).join('[redacted]').split(this.#clientId).join('[redacted]') : value;
+        const safe = data == null ? null : JSON.parse(JSON.stringify(data, (_key, value) => redact(value)));
+        throw new ZPayError(redact(message), { status: response.status, code: redact(typeof data?.code === 'string' ? data.code : 'API_ERROR'),
+          details: safe, retryAfter: response.headers.get('retry-after'), outcomeUnknown: method !== 'GET' && (response.status >= 500 || [408, 409, 429].includes(response.status)) });
+      }
+      if (data == null || typeof data !== 'object' || Array.isArray(data)) throw new ZPayError('Formato de resposta inválido da Z.PAY.', { status: response.status, code: 'INVALID_RESPONSE', outcomeUnknown: method !== 'GET' });
+      return data; // 202 is an acknowledgement; it does not mean funds arrived.
+    } catch (error) {
+      if (error instanceof ZPayError) throw error;
+      throw new ZPayError(timedOut ? 'Tempo de resposta da Z.PAY esgotado.' : signal?.aborted ? 'Requisição cancelada.' : 'Falha de conexão com a Z.PAY.', {
+        status: response?.status || 0, code: timedOut ? 'REQUEST_TIMEOUT' : signal?.aborted ? 'REQUEST_ABORTED' : 'NETWORK_ERROR', outcomeUnknown: method !== 'GET',
+      });
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
+    }
+  }
+}
+
+module.exports = { ZPay, ZPayError, DEFAULT_BASE_URL, VERSION };

package/index.d.ts

@@ -0,0 +1,206 @@
+export const DEFAULT_BASE_URL: string;
+export const VERSION: string;
+export interface RequestOptions { signal?: AbortSignal }
+export interface ZPayOptions {
+  clientId: string;
+  clientSecret: string;
+  /** URL completa da API, incluindo /api/v1. */
+  baseUrl?: string;
+  /** Padrão: 30000 ms. Não provoca reenvio automático. */
+  timeoutMs?: number;
+  fetch?: typeof globalThis.fetch;
+}
+export class ZPayError extends Error {
+  status: number;
+  code: string;
+  details: unknown;
+  retryAfter: string | null;
+  /** A operação pode ter sido enviada; consulte antes de tentar novamente. */
+  outcomeUnknown: boolean;
+  constructor(message: string, options?: { status?: number; code?: string; details?: unknown; retryAfter?: string | null; outcomeUnknown?: boolean });
+}
+export interface ApiObject { [key: string]: unknown }
+export interface Page<T> extends ApiObject {
+  items: T[];
+  pagination: { page: number; limit: number; total: number; totalPages: number };
+}
+export interface TagFilter { tag?: string; tagSlug?: string }
+export interface ListQuery extends TagFilter {
+  page?: number; limit?: number; status?: string;
+  date?: string; hour?: number; from?: string; to?: string;
+  when?: 'created' | 'paid' | 'completed';
+}
+export interface Keyed { idempotencyKey: string }
+export interface Payer {
+  payerName: string; payerDocument?: string; payerEmail?: string; payerPhone?: string;
+}
+export interface CreatePayment extends Payer, Keyed {
+  /** Valor em reais, não centavos. */
+  amount: number;
+  description?: string; tag?: string; subaccountId?: string;
+}
+export interface Payment extends ApiObject {
+  paymentId: string; amount: number; status: string;
+  copyPaste: string | null; qrCodeBase64: string | null; qrcodeUrl?: string | null;
+  paymentMethod?: string; idempotencyKey?: string | null; subaccountId?: string | null;
+  paidAt?: string | null; replayed?: boolean;
+}
+export interface Donation extends ApiObject {
+  paymentId: string; amount: number; payerName: string; description: string;
+  status: string; paidAt: string | null; createdAt: string;
+}
+export interface CreateCheckout {
+  amount: number; name: string; description: string; payerName?: string;
+  payerDocument?: string; payerEmail?: string; payerPhone?: string;
+  methods?: Array<'pix' | 'card' | 'boleto'>; maxInstallments?: number; tag?: string;
+}
+export interface Checkout extends ApiObject {
+  checkoutId: string; paymentId: string; amount: number; status: string;
+  checkoutUrl?: string; expiresAt: string; methods: string[];
+}
+export interface Withdrawal extends ApiObject {
+  id: string; transactionId: string; status: string; amount: number; fee: number;
+  netAmount: number; clientTransactionId: string; kind: string;
+  createdAt: string; completedAt: string | null;
+}
+export interface CreateWithdrawal extends Keyed { amount: number; subaccountId?: string }
+export type PixKeyType = 'CPF' | 'CNPJ' | 'EMAIL' | 'TELEFONE' | 'CHAVE_ALEATORIA';
+export type CreateCashout = Keyed & { description?: string; subaccountId?: string } & (
+  { amount: number; pixKey: string; pixKeyType: PixKeyType; qrCode?: never } |
+  { qrCode: string; amount?: number; pixKey?: never; pixKeyType?: never }
+);
+export interface Transfer extends Keyed { to: string; amount: number; description?: string }
+export interface CryptoFees extends ApiObject {
+  receivePercent: number | null; receiveFixedLtc: number | null;
+  receiveFeeConfirmed: boolean; withdrawFixedLtc: number | null;
+  usdtNetwork: 'BEP20'; usdtRate: 'provider_at_submission';
+}
+export interface CryptoOperation extends ApiObject {
+  id: string; kind: 'deposit' | 'swap' | 'withdraw'; provider: 'purincash';
+  status: 'created' | 'dispatching' | 'pending' | 'paid' | 'failed' | 'review';
+  amountBrl: number; currency: 'LTC' | 'USDT'; payCurrency: 'ltc' | 'usdt';
+  payAmount: number | null; fee: number | null; address: string | null;
+  network: 'Litecoin' | 'BEP20'; receiveUSDT: number | null; rateBRLPerUSDT: number | null;
+  txHash: string | null; donateId: string | null; createdAt: string;
+  paidAt?: string | null; expiresAt?: string | null;
+}
+export interface CryptoPayment extends CryptoOperation {
+  paymentId: string; amount: number; payAddress: string | null;
+}
+export interface CreateCryptoPayment {
+  requestId: string; amount: number; currency?: 'brl'; payCurrency?: 'ltc';
+  payerName?: string; description?: string;
+}
+export interface CreateSwap {
+  requestId: string; amount: number; address: string;
+  confirmNotCoinbase: true; acceptProviderRate: true; totpCode?: string;
+}
+export interface CreateCryptoWithdrawal {
+  requestId: string;
+  /** Quantidade em LTC, até oito casas decimais. */
+  amount: number;
+  address: string; totpCode?: string;
+}
+export interface CryptoBalance extends ApiObject {
+  currency: 'ltc'; balance: number; provider: 'purincash'; fees: CryptoFees;
+  legacy: { currency: string; balance: number; pendingWithdrawal: number };
+}
+export interface SubaccountInput {
+  name: string; externalId: string; email?: string;
+  metadata?: Record<string, unknown>; feePercent?: number; feeFixed?: number;
+  payoutFeePercent?: number; payoutFeeFixed?: number;
+}
+export interface Subaccount extends ApiObject {
+  id: string; name: string; externalId: string; balance: number; status: string;
+}
+export interface SubaccountMove extends Keyed { amount: number; description?: string }
+export interface CreateBoleto extends CreatePayment { payerEmail: string; payerDocument: string; dueDays?: number }
+export interface BillPaymentPreview { line: string; amount?: number }
+export interface CreateBillPayment extends BillPaymentPreview, Keyed { description?: string }
+export interface Stats extends ApiObject {
+  balance?: number; totalEarnedToday: number; donationsToday: number;
+  totalEarnedThisMonth: number; donationsThisMonth: number; totalAllTime: number;
+  totalWithdrawn?: number;
+}
+export interface Fees extends ApiObject {
+  depositFee: number; depositRate: number; withdrawFee: number; cashoutFee: number;
+  minWithdraw: number; maxCashin: number; maxCashout: number;
+  highValueDepositThreshold: number; highValueDepositRate: number; accountType: string;
+}
+
+/** Cliente para Node.js 18+. Mantenha clientSecret exclusivamente no servidor. */
+export class ZPay {
+  constructor(options: ZPayOptions);
+  readonly account: {
+    stats(query?: TagFilter, options?: RequestOptions): Promise<Stats>;
+    fees(options?: RequestOptions): Promise<Fees>;
+  };
+  readonly payments: {
+    create(body: CreatePayment, options?: RequestOptions): Promise<Payment>;
+    get(id: string, options?: RequestOptions): Promise<Payment>;
+    payer(id: string, options?: RequestOptions): Promise<ApiObject>;
+  };
+  readonly donations: {
+    list(query?: ListQuery, options?: RequestOptions): Promise<Page<Donation>>;
+    top(query?: TagFilter & { limit?: number }, options?: RequestOptions): Promise<ApiObject>;
+  };
+  readonly checkouts: {
+    create(body: CreateCheckout, options?: RequestOptions): Promise<Checkout>;
+    get(id: string, options?: RequestOptions): Promise<Checkout>;
+  };
+  readonly withdrawals: {
+    create(body: CreateWithdrawal, options?: RequestOptions): Promise<Withdrawal>;
+    get(id: string, options?: RequestOptions): Promise<Withdrawal>;
+    list(query?: ListQuery & { kind?: 'withdraw' | 'cashout' | 'refund' }, options?: RequestOptions): Promise<Page<Withdrawal>>;
+  };
+  readonly cashouts: {
+    create(body: CreateCashout, options?: RequestOptions): Promise<Withdrawal>;
+    get(id: string, options?: RequestOptions): Promise<Withdrawal>;
+  };
+  readonly refunds: { create(body: { transactionId: string }, options?: RequestOptions): Promise<ApiObject> };
+  readonly transfers: {
+    recipient(to: string, options?: RequestOptions): Promise<ApiObject>;
+    create(body: Transfer, options?: RequestOptions): Promise<ApiObject>;
+  };
+  readonly boletos: { create(body: CreateBoleto, options?: RequestOptions): Promise<Payment> };
+  readonly billPayments: {
+    preview(body: BillPaymentPreview, options?: RequestOptions): Promise<ApiObject>;
+    create(body: CreateBillPayment, options?: RequestOptions): Promise<ApiObject>;
+    list(query?: Pick<ListQuery, 'page' | 'limit'>, options?: RequestOptions): Promise<ApiObject>;
+    get(id: string, options?: RequestOptions): Promise<ApiObject>;
+  };
+  readonly meds: {
+    list(query?: ListQuery, options?: RequestOptions): Promise<ApiObject>;
+    get(id: string, options?: RequestOptions): Promise<ApiObject>;
+  };
+  readonly crypto: {
+    createPayment(body: CreateCryptoPayment, options?: RequestOptions): Promise<CryptoPayment>;
+    /** Cobranças novas LTC; consultas antigas podem devolver o formato legado. */
+    getPayment(id: string, options?: RequestOptions): Promise<CryptoPayment | ApiObject>;
+    balance(options?: RequestOptions): Promise<CryptoBalance>;
+    summary(options?: RequestOptions): Promise<ApiObject & { balance: number; fees: CryptoFees; operations: CryptoOperation[] }>;
+    operation(id: string, options?: RequestOptions): Promise<CryptoOperation>;
+    swap(body: CreateSwap, options?: RequestOptions): Promise<CryptoOperation>;
+    withdraw(body: CreateCryptoWithdrawal, options?: RequestOptions): Promise<CryptoOperation>;
+  };
+  readonly subaccounts: {
+    create(body: SubaccountInput, options?: RequestOptions): Promise<{ ok: boolean; subaccount: Subaccount }>;
+    list(options?: RequestOptions): Promise<{ subaccounts: Subaccount[] }>;
+    get(id: string, options?: RequestOptions): Promise<{ subaccount: Subaccount }>;
+    update(id: string, body: Partial<Pick<SubaccountInput, 'name' | 'externalId' | 'email' | 'metadata'>>, options?: RequestOptions): Promise<{ ok: boolean; subaccount: Subaccount }>;
+    block(id: string, options?: RequestOptions): Promise<{ ok: boolean; subaccount: Subaccount }>;
+    unblock(id: string, options?: RequestOptions): Promise<{ ok: boolean; subaccount: Subaccount }>;
+    delete(id: string, options?: RequestOptions): Promise<ApiObject>;
+    transactions(id: string, query?: ListQuery, options?: RequestOptions): Promise<ApiObject>;
+    fund(id: string, body: SubaccountMove, options?: RequestOptions): Promise<ApiObject>;
+    transfer(id: string, body: SubaccountMove & { to: string }, options?: RequestOptions): Promise<ApiObject>;
+    payout(id: string, body: SubaccountMove, options?: RequestOptions): Promise<ApiObject>;
+    withdraw(id: string, body: SubaccountMove, options?: RequestOptions): Promise<ApiObject>;
+  };
+  readonly splits: {
+    /** value em centavos; amount é percentual inteiro ou valor em centavos. */
+    create(body: { value: number; type: 'percentage' | 'fixed'; amount: number; split_account: string; payerName?: string; description?: string }, options?: RequestOptions): Promise<ApiObject>;
+    pix(body: ApiObject & { value: number; splits: ApiObject[] }, options?: RequestOptions): Promise<ApiObject>;
+    get(id: string, options?: RequestOptions): Promise<ApiObject>;
+  };
+}

package/index.mjs

@@ -0,0 +1,2 @@
+import sdk from './index.cjs';
+export const { ZPay, ZPayError, DEFAULT_BASE_URL, VERSION } = sdk;

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@isnouu/zpay-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "SDK JavaScript e TypeScript da API Z.PAY para servidores Node.js",
+  "main": "./index.cjs",
+  "module": "./index.mjs",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.cjs"
+    }
+  },
+  "files": [
+    "index.cjs",
+    "index.mjs",
+    "index.d.ts",
+    "README.md",
+    "examples"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.cjs",
+    "test:types": "tsc -p tsconfig.json",
+    "prepack": "npm test && npm run test:types"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "zpay",
+    "pix",
+    "payments",
+    "sdk",
+    "typescript"
+  ],
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}