SDK JavaScript / Navegador

@lartech/infraio-checkout-js é o único SDK que a gente publica hoje. Roda no navegador e abre o nosso checkout hospedado. SDKs de backend (Node, Go, Python) estão no roadmap; até lá, fale direto com o gateway — veja o Início rápido para um helper de assinatura HMAC.

• Versão atual: 0.1.1-beta.17 (pré-1.0; espere pequenas quebras)
• Formatos: ESM (index.js), CJS (index.cjs), IIFE (index.global.js)
• Tipos embutidos (index.d.ts)
• Zero dependências de runtime — sem React, jQuery ou outras deps

Instalação

npm install @lartech/infraio-checkout-js

pnpm add @lartech/infraio-checkout-js

yarn add @lartech/infraio-checkout-js

bun add @lartech/infraio-checkout-js

<script src="https://unpkg.com/@lartech/infraio-checkout-js/dist/index.global.js"></script>
<script>
  const sdk = await InfraIo.loadInfraIo("pk_live_yourkeyhere");
  sdk.checkout({ sessionId, checkoutUrl });
</script>

loadInfraIo(publicKey, options?)

Retorna uma Promise<InfraIoInstance>.

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere", {
  // Opcional. Sobrescreva só quando apontar para um ambiente não-prod.
  checkoutUrl: "https://checkout-dev.infraio.xyz",
});

sdk.checkout({ … })

Abre o checkout hospedado. Retorna void (use callbacks para estado).

sdk.close()

Descarta programaticamente um popup ou embed aberto. No-op para o modo redirect.

sdk.checkout({ sessionId, mode: "popup", /* … */ });
// depois, por exemplo, quando o usuário navega para longe
sdk.close();

sdk.openRefundRequest({ … })

Abre o formulário hospedado de pedido de reembolso para um token de uso único que o seu backend criou via POST /b2b/v1/merchants/{merchant_id}/refund-requests. O comprador preenche o endereço de destino do reembolso + motivo + (opcional) metadata na nossa página; a sua página só cuida do ciclo de abertura/fechamento. Retorna uma função close() — chame para descartar programaticamente o popup ou destacar o iframe de embed. No modo redirect a função retornada é no-op.

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere");
 
// Cria o token no servidor e entrega para o SDK no navegador.
const { token } = await fetch("/api/mint-refund-token", { method: "POST" }).then(r => r.json());
 
const close = sdk.openRefundRequest({
  token,
  mode: "popup",
  onSuccess: ({ linkToken, refundId }) => {
    // Comprador submeteu o formulário.
    // linkToken → página de status /r/:linkToken (compartilhe com o comprador).
    // refundId  → use com a API B2B para aprovar / rejeitar.
    window.location.href = `/r/${linkToken}`;
  },
  onCancel: () => { /* comprador fechou sem enviar */ },
});
 
// Descarte programaticamente o popup depois, se precisar:
// close();

Estados de token expostos via onError

Se o comprador abre um token velho, a própria página cuida do display (renderiza um prompt “Expirado — peça link novo”, etc.), e o SDK não dispara onError para esses casos — o comprador está dentro do fluxo do formulário e o seu código não precisa reagir. onError só dispara para coisas em que o seu código pode agir (argumentos ruins, falha de rede ao carregar o iframe).

Classe de erro

import { InfraIoError } from "@lartech/infraio-checkout-js";
 
sdk.checkout({
  sessionId,
  onError: (err: InfraIoError) => {
    switch (err.code) {
      case "invalid_request_error":   /* sessionId / args ruins */ break;
      case "iframe_load_error":       /* iframe falhou em carregar */ break;
      case "iframe_timeout_error":    /* excedeu timeoutMs */ break;
      case "already_open_error":      /* outro checkout já está aberto */ break;
      case "network_error":           /* problema de rede transiente falando com a origem do checkout */ break;
      case "api_error":               /* backend retornou não-2xx para uma chamada emitida pelo SDK */ break;
    }
  },
});

sdk.openRefundRequest() lança somente invalid_request_error (token / args ausentes ou inválidos), de forma síncrona. iframe_load_error (o iframe de pedido de reembolso falhou em carregar) é entregue de forma assíncrona via onError, não lançado. Ele não emite iframe_timeout_error nem already_open_error — o popup de pedido de reembolso não tem load-timeout e permite múltiplos popups concorrentes.

Notas sobre os modos

Popup

• Overlay centralizado com um backdrop escuro semi-transparente
• z-index: 2147483647 (max int32) — fica acima de tudo
• Scroll do body é travado enquanto aberto; restaurado no fechamento
• Botão de fechar pega o foco inicial; Tab é trapeado no popup
• Fechado por: botão de fechar, Escape, clique fora, sdk.close(). Todos eles chamam onCancel
• A página de checkout pode pedir resize via postMessage — o SDK limita dentro dos limites de width/height

Redirect

• Navegação completa via window.location.href
• Anexa automaticamente ?return_url=<página-atual> para que o comprador volte ao lugar de onde veio. Se a sua success_url / cancel_url na sessão já cobrem isso, a viagem de ida e volta ignora return_url

Embed

• iframe com allow="payment; clipboard-write" (diretivas HTML5 Feature Policy — não o atributo sandbox). O iframe é servido da origem do checkout, então popups de carteira e escritas no clipboard do lado do comprador funcionam sem opt-in adicional.
• Largura do container é 100%; altura faz auto-resize via postMessage INFRAIO_RESIZE, limitada a [200, 2000]px
• Sem isolamento CSS além da fronteira do iframe — os estilos da página pai não vazam para dentro
• Sempre conecte onReady para você poder esconder o seu próprio estado de carregamento quando o checkout fica interativo

TypeScript

Todos os tipos vêm embutidos. Exports mais úteis:

import type {
  CheckoutOptions,
  RefundRequestOptions,
  LoadOptions,
  InfraIoInstance,
  InfraIoErrorCode,
} from "@lartech/infraio-checkout-js";
import { loadInfraIo, InfraIoError, VERSION } from "@lartech/infraio-checkout-js";

VERSION é a string de versão do próprio SDK — útil em bug reports.

Próximos passos

• Wrappers para React / Vue — planejados para a iteração pós-lançamento, uma vez que a superfície JS vanilla estabilize entre os lojistas-piloto. O SDK vanilla funciona bem dentro do React hoje; os wrappers só vão remover o useRef manual + o plumbing de ciclo de vida.
• Resumo de sessão entre abas — abre o checkout na aba A, termina na aba B. Útil quando um comprador segue um magic-link no meio do fluxo. Rastreado para o próximo minor release.
• Theming via CSS variables — expor um pequeno conjunto de design tokens (raio, cor de acento) no iframe para que lojistas consigam combinar a marca sem forkar a página.
• Helpers do lado do servidor — um pacote minúsculo @lartech/infraio-server expondo verifyWebhook() + signedRequest() para que código de backend não precise copiar o ritual HMAC. Até ele chegar, a página de verificação de assinatura lista implementações drop-in em TypeScript, Go, Python e Ruby.