MercadoPago scraper 🤖💸

Una librería ligera y tipada en TypeScript para Node.js que permite extraer las cookies de sesión oficiales manipulando un navegador transparente (mediante Puppeteer). Especialmente diseñada para auditorías, lectura de saldo y conciliación automática interactuando directamente de manera no oficial con las APIs internas web de Mercado Pago.

🚀 Características

• Inicio de sesión humano-asistido: Permite saltar barreras como SMS o 2FA manejando Puppeteer de manera interactiva.
• Cacheo Inteligente: Guarda la información temporal en disco para evitar iniciar un navegador de Chrome cada vez que llamas a tu script.
• Tipado estricto (TypeScript): Resultados ya consolidados en Data Transfer Objects (DTO) predictivos para trabajar.
• Extracción de Tokens CSRF: Intercepta requests backend transparentemente para entregarte el cabezal x-csrf-token infalible para tus futuros Fetch/Axios.

📦 Instalación

Puedes instalarlo mediante NPM:

npm install mp-scraper puppeteer

Nota importante para entornos Linux / Docker: Puppeteer necesita instalar Chromium. Asegúrate de tener los permisos y bibliotecas C++ correspondientes si estas montándolo desde un servidor limpio.

🔧 Uso Básico y Prueba

Aquí tienes un ejemplo rápido de cómo instanciar e inicializar la librería, y listar las transacciones más recientes.

import { MercadoPagoScraper } from "mp-scraper";

const mps = new MercadoPagoScraper({
  timeout: 300000,
  cacheDir: "./.mp_cache", // Recomendado: evitar abrir el login múltiples veces
});

// Evento que se dispara al detectar ingreso exitoso.
mps.on("logged", async (data) => {
  console.log("¡Login detectado con éxito!");

  try {
    // Ya puedes pedir actividades directamente
    const listado = await mps.getActivities(1);

    console.log(`Página actual trajo ${listado.results.length} resultados.`);
    console.log(
      `El usuario tiene un histórico de ${listado.totalResults} transacciones.`,
    );

    // listado.results es un array completamente tipado:
    listado.results.forEach((tr) => {
      console.log(
        `[${tr.date.toLocaleDateString()}] ${tr.category}: $${tr.amount} | ID: ${tr.id}`,
      );
    });
  } catch (error) {
    console.error("Falló la obtención:", error);
  }
});

// Eventos de manejo de fallos
mps.on("login_error", (err) => console.error("Error en login:", err));
mps.on("browser_closed", () => console.log("Navegador finalizado"));

// Comando disparador
mps.init();

El Objeto TransactionDTO (Para getActivities)

Cada transacción devuelta en .results contiene un tipado sumamente limpio e inferido:

export interface TransactionDTO {
  id: string; // ID alfanumérico largo
  title: string; // Ej: "Ingreso de dinero" o "Mercado Libre"
  counterparty: string; // Destinario o remitente de la operación
  description: string; // Ej: "Compra", "Pago Automático"
  category: string; // "in_money", "purchases", "pays", "transfers"
  date: Date; // Objeto fecha parseado original
  amount: number; // Float numérico. Positivo para ingreso, negativo para salidas.
  currency: string; // Ej: "ARS"
  status: string; // Ej: "Aprobado", "Rechazado"
  paymentMethod: string; // Medio de pago original (Visa, Dinero en cuenta, etc)
}

📝 Scripts Útiles

Si quieres probar, o modificar la librería, puedes usar los siguientes comandos de forma nativa clonando este repositorio:

# Instalar dependencias
npm install

# Compilar Typescript
npm run build

# Abrir el Playground de Pruebas
npm run playground

🔐 Licencia y exención de responsabilidad

Uso bajo tu propia discreción. Esta no es una librería oficial de MercadoLibre/MercadoPago. Está desarrollada únicamente para propósitos educativos y de automatización interna de herramientas en los que al usuario le es legalmente permitido participar usando sus propios medios. No intentes eludir mecanismos de seguridad que prohíban o expongan datos a terceros sin autorización de las guías correspondientes.

Distribuido bajo licencia ISC.