@quadcore-lib/coupons-server

Cupones de descuento para e-commerce. Validación pública en el checkout, gestión admin. Soporta porcentaje/monto fijo, compra mínima, máximo de usos y vigencia.

Endpoints

| Método | Ruta | Acceso | Descripción | |---|---|---|---| | POST | /coupons/validate | público | Valida un código contra un subtotal. Body: { code, subtotal } → { valid, discount, reason? }. | | GET | /coupons | admin | Listado paginado. | | GET | /coupons/:id | admin | Un cupón. | | POST | /coupons | admin | Crear. | | PATCH | /coupons/:id | admin | Actualizar. | | DELETE | /coupons/:id | admin | Soft-delete. |

CouponsService.redeem(code) incrementa el contador de usos de forma atómica (UPDATE ... WHERE usedCount < maxUses; 409 si no hay usos). CouponsService.restore(code) lo decrementa (UPDATE ... WHERE usedCount > 0, nunca negativo, best-effort) — usalo si la orden que redimió el cupón se cancela. @quadcore-lib/orders-server ya integra ambos en create()/cancel() vía CouponRedeemer (ver su README).

validate, redeem y restore aceptan un EntityManager opcional como último parámetro:

await coupons.redeem('OFF10', em); // dentro de una transacción ajena
await coupons.redeem('OFF10');     // manager propio, commitea solo

Sirve para que la redención participe de una transacción de otro módulo y se revierta con ella — es lo que usa orders-server para que cupón, stock y orden commiteen juntos. Sin el parámetro, el comportamiento es el de siempre.

Entidad CouponEntity (coupons)

id, code (único, uppercase), type (percentage|fixed), value, minPurchase?, maxUses?, usedCount, startsAt?, expiresAt?, isActive, timestamps + soft-delete.

Migraciones

Este paquete trae sus migraciones de TypeORM en dist/src/migrations/*.js (se compilan junto al resto). Ver la guía completa (setup del DataSource, cómo combinarlas con las de otros paquetes, synchronize en dev vs. prod) en el README de @quadcore-lib/core-server, sección "Migraciones de DB".