ADR 0009 ya había decidido PayU LatAm como proveedor (única opción que
no exige cuenta Bancolombia/Nequi) y confirmado que no existe ningún
plugin real de Medusa para su API -- los paquetes que aparecen
buscando "PayU" son para PayU Polonia/CEE, API completamente distinta
(clientId/posId/secondKey vs. apiLogin/apiKey/merchantId/accountId).
Este commit implementa esa decisión: módulo de pago custom
(AbstractPaymentProvider) para PSE (transferencia bancaria), primer
alcance del método de pago -- Nequi/Daviplata quedan fuera por ahora.
Backend (commerce-backend):
- src/modules/payu-pse/: initiatePayment arma y postea SUBMIT_TRANSACTION
contra la API real de PayU LatAm; authorizePayment devuelve
"pending_authorization" (PSE es async, la confirmación real llega por
webhook, no en el momento de completar el carrito); getWebhookActionAndData
valida la firma MD5 del webhook antes de confiar en cualquier
confirmación de pago -- falla cerrado si no matchea. refundPayment/
retrievePayment tiran error explícito en vez de simular éxito: esos
endpoints de PayU no quedaron verificados en vivo y hay dinero real de
por medio.
- No hace falta un subscriber propio para completar la orden -- el
subscriber nativo de Medusa (payment-webhook + process-payment-workflow)
ya hace ese trabajo con los métodos de arriba bien implementados
(confirmado leyendo el código fuente instalado de @medusajs/medusa
2.18.0, no la documentación).
- Correlación webhook↔sesión: Medusa inyecta su propio session_id en
`data` antes de initiatePayment; se usa ese mismo valor como
referenceCode de PayU, así el reference_sale que vuelve en el webhook
ya es directamente el session_id de Medusa.
- src/lib/payu.ts: cliente HTTP + firmas (orden y webhook, fórmulas
distintas, confirmadas contra el SDK PHP oficial de PayU).
- src/api/store/payments/pse-banks/route.ts: lista de bancos PSE,
cacheada en memoria.
- medusa-config.ts, Dockerfile, configmap/secrets.template: 7 env vars
nuevas (PAYU_API_LOGIN/API_KEY/MERCHANT_ID/ACCOUNT_ID/ENV/RESPONSE_URL/
NOTIFY_URL), dummies de build agregados, secrets con placeholder
"CAMBIAR".
Frontend (ecommerce):
- Nuevo step "payment" en components/checkout/checkout-client.tsx
(reemplaza al step "review" que solo ofrecía WhatsApp): selector de
banco, tipo de persona (N/J), tipo/número de documento, botón "Pagar
con PSE" que crea la sesión de pago, completa el carrito y redirige
al banco (navegación completa, no iframe -- así lo exige PayU).
WhatsApp queda como respaldo manual si falla la iniciación del pago.
- lib/headless/providers/medusa-payment.ts + 3 rutas proxy nuevas bajo
app/api/cart/, mismo patrón que el resto del carrito
(medusaCartFetch, ahora exportado desde medusa-cart.ts).
- app/checkout/pse/return/: página de vuelta del banco -- nunca afirma
éxito, la confirmación real es el webhook async.
Arranca contra las credenciales de sandbox genéricas y públicas de
PayU (developers.payulatam.com) mientras el usuario termina su propio
registro de comercio -- swap de las 4 credenciales via secret cuando
estén listas, sin cambios de código.
Verificado: build real de Medusa con las env vars dummy (no solo tsc),
tipos de AbstractPaymentProvider/WebhookActionResult/PaymentActions
confirmados contra @medusajs/utils y @medusajs/types instalados
(node_modules limpiado después), typecheck + lint + build completo del
frontend, páginas nuevas renderizando sin error. Pendiente: prueba
end-to-end contra el sandbox real de PayU (necesita el backend
desplegado) y habilitar el provider en la región Colombia desde el
Admin.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01THZFwPzrwv6VAbuwmaf5vR
Agrega el modulo @medusajs/medusa/auth con providers emailpass (explicito,
para no perder el default al customizar el modulo) y google, leyendo
GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET/GOOGLE_CALLBACK_URL desde
commerce-secrets con required().
Encontrado en vivo (gate de verificacion de Fase 2): el job de sync
inicial del plugin fallaba en TODOS los productos con "Method
calculatePrices requires currency_code in the pricing context" --
variants.calculated_price necesita region_id/currency_code en el
contexto de query.graph, que el workflow interno del plugin
(sync-products.js) no provee. Las categorias si indexaron bien (21),
solo productos fallaba, por eso numberOfDocuments quedaba en 0 pese a
que el indice y sus settings se crearon correctamente.
variants.prices (lista cruda, sin resolver promociones/reglas de
precio) no requiere ese contexto y alcanza para el filtro/orden por
precio de la busqueda -- no necesitamos el precio final promocional
ahi, esa resolucion ya la hace la ruta /store/search via query.graph
con el contexto real al re-hidratar los productos.
Instala @rokmohar/medusa-plugin-meilisearch@^1.4.1 (linea v1, la unica
compatible con nuestro Medusa 2.18.0 exacto -- confirmado contra
peerDependencies reales de npm: @medusajs/* ^2.15.2, satisfecho por
2.18.0). Conectado via un array `plugins:` nuevo en medusa-config.ts
(primer uso en este repo, no `modules:`), env vars leidos con `?? ""`
en vez de required() -- si Meilisearch esta caido o mal configurado,
el plugin se degrada solo en vez de tumbar el arranque de Medusa
entero.
No se escribe un subscriber propio: se verifico contra el codigo
fuente real del paquete (descargado el tarball exacto de npm,
inspeccionado en /app/node_modules dentro de una imagen Docker de
verdad) que trae sus propios subscribers de product/category/
collection/variant/etc, descubiertos por Medusa en runtime desde
dentro del propio paquete -- confirmado que sobreviven a
`npm prune --omit=dev` y llegan intactos a la imagen final. Tambien
trae un job de indexado inicial de una sola corrida al boot
(numberOfExecutions: 1, no un cron recurrente -- no viola la
restriccion del ADR de "nunca cron").
Nueva ruta Store API propia (src/api/store/search/route.ts): las
rutas /store/meilisearch/* que trae el plugin no devuelven
facetDistribution (verificado leyendo su codigo fuente), asi que esta
ruta pide facets explicitamente via additionalOptions.facets, y
despues re-hidrata los productos via query.graph (mismos campos que
ya usa el storefront) en vez de confiar en precios/inventario
indexados -- mismo patron "safe path" que ya usa la ruta oficial del
plugin para /store/meilisearch/products.
Transformer custom en medusa-config.ts que espeja mapProduct() del
storefront (category/collection/brand/ageRange desde metadata,
disponibilidad desde la primera variante) para que el documento
indexado sea exactamente lo que el storefront ya muestra.
Validado en vivo: build completo de Docker (target builder) corre
limpio -- npm ci, medusa build (typecheck + compile backend/frontend),
npm prune -- cero errores. package-lock.json regenerado con un
contenedor node:22.18.0-bookworm-slim real (mismo base image que el
Dockerfile), no a mano.
Dockerfile: dummy MEILISEARCH_HOST/MEILISEARCH_API_KEY en el stage de
build (insurance barata, no son required() asi que no eran
estrictamente necesarios para que el build pasara, y de hecho paso
sin ellos en la prueba -- se dejan de todas formas por consistencia
con el resto de dummies de esa capa).
Todos los Ingress del lab terminan en Traefik por HTTP plano (entrypoint
web, sin TLS); Cloudflare es quien atiende HTTPS de cara al navegador.
Con secure:true (default en produccion), express-session nunca emite
Set-Cookie porque no detecta la conexion como HTTPS, dejando el
dashboard admin con 401 en /admin/users/me pese a loguear bien.
devopsandClaude Sonnet 5