SDK TypeScript

Instalação

O pacote @eclipta-pay/sdk faz parte do monorepo do Eclipta Pay e exige Node.js 20 ou superior. A publicação em registro público ainda não foi feita; até lá, use o pacote do repositório (dependência workspace:*), que expõe o código-fonte TypeScript. O README.md do pacote resume instalação, idempotência, operações e webhooks; as integrações de referência mostram o SDK em serviços completos.

import { EcliptaPay } from "@eclipta-pay/sdk";

export const eclipta = new EcliptaPay({
  apiKey: process.env.ECLIPTA_PAY_KEY!,      // ep_test_… ou ep_live_…
  baseUrl: process.env.ECLIPTA_PAY_API!,     // origem da API, sem /v1
  accountId: process.env.ECLIPTA_PAY_ACCOUNT, // X-Account-Id padrão
  timeoutMs: 30_000,
  maxNetworkRetries: 2,
});

Idempotência e retentativas

• Cada chamada de mutação recebe uma Idempotency-Key própria, gerada uma vez e repetida em todas as retentativas automáticas daquela chamada.
• Leituras são repetidas em falha de rede, 429 e 5xx. Mutações só quando é seguro: conexão recusada antes do envio, 429 e 409 REQUEST_IN_PROGRESS.
• Timeout, conexão caída depois do envio e 5xx numa mutação viram ConnectionError/ServerError com idempotencyKey. Repita você mesmo com a mesma chave: o servidor devolve o resultado gravado.

import { ConnectionError } from "@eclipta-pay/sdk";

const chave = `pedido-${pedido.id}-pix`; // uma chave por intenção, guardada com o pedido
try {
  await eclipta.createPayment({ orderId: pedido.id, method: "PIX", dueDate: "2026-11-20" }, { idempotencyKey: chave });
} catch (e) {
  if (e instanceof ConnectionError && e.mayHaveSucceeded) {
    // Mais tarde, a mesma chamada com a mesma chave devolve a operação original.
    await eclipta.createPayment({ orderId: pedido.id, method: "PIX", dueDate: "2026-11-20" }, { idempotencyKey: chave });
  } else throw e;
}

Operações 202

waitForOperation consulta GET /v1/operations/{id} com intervalo crescente até o fim ou até uma ação do pagador (3DS, trocar cartão). UNKNOWN continua sendo consultado; se o prazo acabar, o método lança OperationTimeoutError com o último estado. Ele nunca repete a escrita.

const final = await eclipta.waitForOperation(operacao, { timeoutMs: 60_000, intervalMs: 1_000 });

Webhooks

import { verifyWebhook } from "@eclipta-pay/sdk";

// Aceita Headers do fetch ou o objeto de headers do Node; um segredo ou uma lista (rotação).
const evento = verifyWebhook(corpoCru, headers, [segredoNovo, segredoAntigo], { toleranceSeconds: 300 });
switch (evento.type) {
  case "order.payment_completed":
    await liberarPedido(evento.aggregateId, evento.eventId);
    break;
}

Também disponível como eclipta.webhooks.verify e eclipta.webhooks.constructEvent. Para testar o seu receptor sem rede, signTestPayload(corpo, segredo) gera headers assinados.

Erros e paginação

Os erros são classes por situação (InvalidRequestError, AuthenticationError, PermissionError, NotFoundError, ConflictError, IdempotencyConflictError, BusinessRuleError, RateLimitError, ServerError, ConnectionError, TimeoutError), todas com code, requestId e fieldErrors. Veja Erros.

for await (const cobranca of eclipta.paginate("listPayments", { limit: 100 })) {
  console.log(cobranca.id, cobranca.status);
}

Métodos (66)

Um método por rota implementada, com o mesmo nome do operationId. Rotas ainda especificadas entram quando forem implementadas e o SDK for regenerado.