SDK de JavaScript / Navegador

@lartech/infraio-checkout-js es el único SDK que publicamos hoy. Corre en el navegador y abre nuestro checkout alojado. Los SDKs de backend (Node, Go, Python) están en el roadmap; hasta entonces, habla directamente con el gateway: consulta el Inicio rápido para un helper de firma HMAC.

• Versión actual: 0.1.1-beta.17 (pre-1.0; espera rupturas menores)
• Formatos: ESM (index.js), CJS (index.cjs), IIFE (index.global.js)
• Tipos incluidos (index.d.ts)
• Cero peers en runtime: sin React, jQuery u otras dependencias

Instalación

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?)

Devuelve un Promise<InfraIoInstance>.

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere", {
  // Opcional. Sobreescribe solo cuando apuntes a un entorno no-prod.
  checkoutUrl: "https://checkout-dev.infraio.xyz",
});

sdk.checkout({ … })

Abre el checkout alojado. Devuelve void (usa callbacks para el estado).

sdk.close()

Descarta programáticamente un popup o embed abierto. No-op para el modo redirect.

sdk.checkout({ sessionId, mode: "popup", /* … */ });
// más tarde, p. ej. cuando el usuario navega fuera
sdk.close();

sdk.openRefundRequest({ … })

Abre el formulario de solicitud de reembolso alojado para un token de un solo uso que tu backend emitió vía POST /b2b/v1/merchants/{merchant_id}/refund-requests. El comprador rellena su dirección de destino del reembolso + razón + metadatos (opcional) en nuestra página; tu página solo maneja el ciclo de vida de apertura/cierre. Devuelve una función close(): llámala para descartar programáticamente el popup o separar el iframe embed. En modo redirect la función devuelta es un no-op.

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere");
 
// Emite el token en el lado servidor, luego entrégaselo al SDK en el 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 }) => {
    // El comprador envió el formulario.
    // linkToken → página de estado /r/:linkToken (compartir con el comprador).
    // refundId  → usar con la API B2B para aprobar / rechazar.
    window.location.href = `/r/${linkToken}`;
  },
  onCancel: () => { /* el comprador cerró sin enviar */ },
});
 
// Descartar programáticamente el popup más tarde si es necesario:
// close();

Estados del token expuestos vía onError

Si el comprador abre un token caducado, la propia página maneja la visualización (renderiza un prompt “Expirado: solicita un enlace nuevo”, etc.), y el SDK no dispara onError para esos casos: el comprador está dentro del flujo del formulario y tu código no necesita reaccionar. onError solo se dispara para cosas sobre las que tu código puede actuar (argumentos incorrectos, fallo de red al cargar el iframe).

Clase de error

import { InfraIoError } from "@lartech/infraio-checkout-js";
 
sdk.checkout({
  sessionId,
  onError: (err: InfraIoError) => {
    switch (err.code) {
      case "invalid_request_error":   /* sessionId / args malos */ break;
      case "iframe_load_error":       /* el iframe falló al cargar */ break;
      case "iframe_timeout_error":    /* excedió timeoutMs */ break;
      case "already_open_error":      /* otro checkout ya está abierto */ break;
      case "network_error":           /* problema de red transitorio hablando con el origin del checkout */ break;
      case "api_error":               /* el backend devolvió un no-2xx para una llamada emitida por el SDK */ break;
    }
  },
});

sdk.openRefundRequest() solo lanza invalid_request_error (token / args ausentes o inválidos), de forma síncrona. iframe_load_error (el iframe de solicitud de reembolso falló al cargar) se entrega de forma asíncrona vía onError, no se lanza. No emite iframe_timeout_error ni already_open_error: el popup de solicitud de reembolso no tiene timeout de carga y permite múltiples popups concurrentes.

Notas de modo

Popup

• Overlay centrado con un fondo oscuro semi-transparente
• z-index: 2147483647 (max int32): se sienta encima de todo lo demás
• El scroll del body se bloquea mientras está abierto; se restaura al cerrar
• El botón de cerrar recibe el foco inicial; Tab queda atrapado en el popup
• Se cierra por: botón de cerrar, Escape, clic fuera, sdk.close(). Todos ellos llaman a onCancel
• La página de checkout puede solicitar redimensión vía postMessage: el SDK acota dentro de los límites de width/height

Redirect

• Navegación dura vía window.location.href
• Añade automáticamente ?return_url=<página-actual> para que el comprador regrese de donde vino. Si tu success_url / cancel_url en la sesión ya cubren esto, el viaje de ida y vuelta ignora return_url

Embed

• iframe con allow="payment; clipboard-write" (directivas de Feature Policy HTML5, no el atributo sandbox). El iframe se sirve desde el origin del checkout, así que los popups de wallet y las escrituras al portapapeles desde el lado del comprador funcionan sin opt-in adicional.
• El ancho del contenedor es 100%; la altura se autodimensiona vía postMessage INFRAIO_RESIZE, acotado a [200, 2000]px
• Sin aislamiento CSS más allá del borde del iframe: los estilos de tu página padre no se filtran
• Cablea siempre onReady para que puedas ocultar tu propio estado de carga cuando el checkout se vuelva interactivo

TypeScript

Todos los tipos están incluidos. Las exportaciones más útiles:

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

VERSION es la cadena de versión del propio SDK: útil en reportes de bug.

Qué sigue

• Wrappers de framework React / Vue: planificados para la iteración post-lanzamiento una vez que la superficie vanilla JS se estabilice entre los comerciantes piloto. El SDK vanilla funciona bien dentro de React hoy; los wrappers solo eliminarán la plomería manual de useRef + ciclo de vida.
• Reanudación de sesión entre pestañas: abre el checkout en la pestaña A, termina en la pestaña B. Útil cuando un comprador sigue un magic-link a mitad de flujo. Rastreado para el próximo release menor.
• Theming vía variables CSS: exponer un set pequeño de design tokens (radio, color de acento) en el iframe para que los comerciantes puedan igualar su marca sin forkear la página.
• Helpers del lado servidor: un pequeño paquete @lartech/infraio-server exponiendo verifyWebhook() + signedRequest() para que el código de backend no necesite copiar el ritual de HMAC. Hasta que se envíe, la página de verificación de firma lista implementaciones drop-in en TypeScript, Go, Python y Ruby.