refactor: Typescript, ESM y Async Await

[ChrisGV04]

Esta PR tiene la intención de actualizar la SDK de Openpay para Node.js a sistemas más modernos, así como actualizar la API disponible y facilitar su uso.

¿Por qué?

Últimamente he intentado crear mis propios sistemas que se integran con Openpay, por lo tanto, requiero de esta SDK para facilitar la interacción con la API de Openpay.

Sin embargo, no dispone de tipos de datos y no soporta promesas async/await, lo que resulta inconveniente de utilizar en aplicaciones modernas sin caer en el famoso "callback hell" o sin errores accidentales por pasar información incorrecta sin saberlo.

Hoy en día, muchas aplicaciones de Node.js están siendo desarrolladas con Typescript y empaquetadas para utilizarse con ESM, lo cual mejora la experiencia de desarrollo y la compatibilidad con sistemas modernos.

¿Qué cambió?

El paquete fue reescrito por completo utilizando Typescript y arquitectura moderna de promesas, async/await y ofetch como librería para realizar las llamadas HTTP a la API de Openpay.

Typescript y ESM

Toda la librería fue reescrita utilizando Typescript, lo cual permite brindar autocompletado y tipos de datos a la hora de integrar la librería en tu proyecto. Actualmente existe el paquete @types/openpay, pero no cuenta con tipos de datos detallados ni la figura de los objetos que maneja la API.

Sin embargo, el proyecto es compilado a Javascript puro ES2018 en ambos cjs y esm para mantener retrocompatibilidad con muchos sistemas. La versión de compilado garantiza el funcionamiento en Node.js v14.0.0 en adelante, pero es posible que funcione en versiones anteriores debido a que no utiliza funciones más modernas.

Por lo tanto, ahora el import de la librería es el siguiente:

// Antes
const Openpay = require("openpay")

// Ahora. CommonJS
const { Openpay } = require("openpay")

// Ahora. ESM
import { Openpay } from "openpay"

Si deseas utilizar los tipos de datos de Openpay en tu aplicación, exponemos todos los tipos mediante el siguiente import:

import type { IOpenpay } from "openpay"

const camposParaCrearCliente: IOpenpay.Customer.CreateInput = {
  // Recibirás sugerencias de autocompletado para este tipo de dato
}

Note

A pesar de estar escrita en Typescript, la librería es compilada a Javascript puro y puede ser utilizada en ambos Javascript y Typescript por igual.

Configuración

Para facilitar la configuración de la instancia de Openpay, la configuración ha sido convertida en un objeto para que sea muy claro qué información se requiere y no confundir las claves utilizadas. A su vez, podrás recibir sugerencias de autocompletado, pues las opciones están cubiertas por los tipos de Typescript.

Aquí dejo un ejemplo del antes y después:

// Antes
const openpay = new Openpay("tu-merchant-id", "tu-private-key", "mx", true)

// Ahora
const openpay = new Openpay({
  merchantId: "tu-merchant-id",
  privateKey: "tu-private-key",
  isProductionReady: false,
  countryCode: 'mx',
});

Promesas

En la versión original de esta librería, todos los métodos para llamar la API requerían pasar un "callback" para procesar ya sea un error o la respuesta exitosa de la API.

Hoy en día, existen mejores alternativas para facilitar el desarrollo y el funcionamiento de nuestras aplicaciones. Las promesas con uso de async/await facilitan la legibilidad y el funcionamiento de las llamadas asíncronas. Por lo tanto, muchos desarrolladores se podrán beneficiar de utilizar estas características.

Aquí dejo un ejemplo del antes y después de la implementación con promesas:

// Antes
openpay.customers.create(infoCliente, function(error, body, response) {
  // Usa el error, body o la respuesta aquí
})

// Después
const cliente = await openpay.customers.create(infoCliente)

Cualquier error que ocurra durante la llamada a la API lanzará un error de tipo FetchError por parte de ofetch. Para manejar errores, podemos utilizar try/catch de la siguiente manera:

import { FetchError } from "ofetch"

try {
  const cliente = await openpay.customers.create(infoCliente)
} catch (error) {
  if (error instanceof FetchError) {
    error.data; // La información del error de Openpay estará contenida en `error.data`
  }
}

Para más información en cómo manejar errores de ofetch, consulta la documentación oficial.

ofetch

Decidí utilizar ofetch como librería para las llamadas HTTP por su simplicidad de uso, buen rendimiento y debido a que ya devuelve las respuestas del servidor procesadas y listas para utilizarse sin enredos.

Todas las peticiones a la API son realizadas mediante ofetch. Para conocer cómo funciona, visita su documentación oficial.

Emparejamiento con la Documentación Oficial

Al parecer, algunas características han sido removidas o actualizadas desde la última actualización de esta librería. Por ejemplo, ya no hay rastro alguno de los objetos Groups en la documentación de México, Colombia ni Perú; por lo tanto, ha sido removido de la librería.

Note

En caso de que se haya removido/olvidado alguna API que siga operando y esté documentada oficialmente, por favor háganmelo saber y la añado con gusto.

Pruebas del SDK

Todas las pruebas de la SDK fueron reescritas utilizando Vitest para soportar Typescript, hacerlas más fáciles de entender y separar las pruebas por país.

Para más información acerca de estas pruebas, por favor consulta el archivo README.md de esta PR.

¿Cómo probar esta versión?

Si desean probar esta librería antes de aprobarla oficialmente, la publiqué en NPM como:

npm i @cgvweb/openpay-node

Es una réplica exacta de los cambios propuestos en esta PR.

Conclusión

Espero que esta nueva arquitectura sea agradable para los desarrolladores que implementan Openpay y que facilite su integración en sistemas modernos.

Entiendo que puede conllevar una labor adicional el realizar la migración para aplicaciones muy grandes o complejas. Por lo tanto, sugiero que, si se aprueba esta PR, publicarla bajo una versión mayor v3.0.0 para que sea opcional y los desarrolladores estén conscientes de que hubieron cambios importantes que alteran el uso de la librería.

Por lo pronto, pueden probar esta integración mediante @cgvweb/openpay-node.

Cualquier duda, comentario, corrección o sugerencia estaré al pendiente.

Gracias.

[ChrisGV04]

Cabe recalcar que, en caso de aprobar esta PR, se deberán actualizar los ejemplos en las documentaciones oficiales de las APIs en México, Colombia y Perú.

[cristianPerez]

Hey @ChrisGV04 thanks for doing this, I'm actually trying to integrate your library in my project.
Let's keep in touch.

[ChrisGV04]

Sure thing. If you have any questions or observations on the refactor please let me know!

Sadly it seems that this project has been inactive for some time and I haven't been able to get in touch with the maintainers. Hopefully they come back soon to have official feedback.

[Joandres-Lara]

Any progress about merge this PR?

[cristianPerez]

Eres muy valiente de hacer esta integración, yo creo que lo mejor sería cambiar de pasarela.

Yo actualmente la
Utilizo en mi proyecto pero en Qa los webhooks no llegan a tiempo, es muy retrógrado.

Mi experiencia ha sido horrible y más con el servicio técnico ya he abierto 3 tickets y en la asesoría técnica se dan cuenta que no funciona y no responden más.

Simplemente lo más antiguo en pasarelas de pago.

[ChrisGV04]

Estoy completamente de acuerdo con @cristianPerez

Hace un año que hice esta PR fue para un proyecto mío que lo requería. Estuve usando mi versión unos meses pero quedé decepcionado con la calidad del servicio de OpenPay y al poco tiempo me cambié a Stripe.

También tengo en mente probar Conekta algún día, pero por lo pronto Stripe ha sido la mejor opción que he utilizado.

No recomiendo OpenPay a nadie, tristemente. Y menos con la mala atención que tienen a sus librerías como esta para Node.js.