TMS Developer Bible 📘

Bienvenido a la documentación técnica de TMS Optin. Este recurso está diseñado para desarrolladores, integradores y arquitectos de soluciones que necesitan extender la funcionalidad del plugin o integrarlo con sistemas externos como CRMs, Zapier, Make o Pabbly Connect.

Esta "Biblia" técnica cubre todos los aspectos de ingeniería del plugin, desde cómo se almacenan los datos a bajo nivel hasta cómo interceptar eventos en el navegador para crear experiencias de usuario personalizadas.

1. Arquitectura del Sistema 🏗️

Comprender cómo TMS Optin maneja la información es crucial para integraciones exitosas. El sistema sigue un patrón de Validación Desacoplada, separando claramente la responsabilidad de presentación (Frontend) de la de lógica de negocio (Backend).

A diferencia de los formularios tradicionales de WordPress que recargan la página, TMS Optin utiliza un enfoque moderno basado en AJAX y REST-like endpoints para garantizar velocidad y una UX fluida.

2. Database Schema: `wp_tms_leads` 🗄️

Si necesitas realizar reportes avanzados, migraciones masivas o dashboards personalizados dentro del WP Admin, interactuarás directamente con la base de datos MySQL.

El plugin utiliza una tabla dedicada (`wp_prefix_tms_leads`) optimizada para lecturas rápidas y alto volumen, evitando la arquitectura lenta de `wp_posts` y `wp_postmeta`.

3. Webhook Payload Definition 📦

La integración con herramientas de terceros es el corazón de la automatización. Cuando un lead verifica su correo (hace clic en el enlace), el sistema "despierta" y envía un POST request al endpoint que hayas configurado.

Este payload es un objeto JSON plano diseñado para ser ingerido fácilmente por Zapier, Pabbly o tu propio servidor Node.js/Python.

TypeScript Interface Definition:

interface TMSWebhookPayload {
  // --- Datos del Usuario ---
  name: string;          // Nombre ingresado en el formulario
  email: string;         // Correo validado y verificado
  [key: string]: string; // Campos extra dinámicos (ej. "telefono", "ciudad", "empresa")

  // --- Datos de Campaña ---
  "id-slug": string;     // ID técnico de la campaña (ej. "ebook-2025")
  "Campaña": string;     // Nombre amigable para humanos (ej. "Lanzamiento Ebook")
  "producto": string;    // Nombre del producto entregable
  "descripcion"?: string;// Descripción opcional de la campaña

  // --- Sistema ---
  date: string;          // Timestamp ISO 8601 o formato MySQL (YYYY-MM-DD HH:MM:SS)
}

4. Frontend API Reference 🎨

Si el Diseñador Visual se te queda corto o necesitas una implementación "Headless" en una Single Page Application (SPA), puedes usar nuestra API de eventos del navegador.

El plugin está programado para emitir eventos estándar del DOM, lo que significa que puedes usar `addEventListener` puro, sin dependencias de jQuery ni frameworks pesados.

Clases Requeridas

Para que el motor "vea" tu formulario HTML manual, debes añadir las siguientes clases:

• .tms-engine-form: Obligatorio. Añádelo al tag <form>. Esto activa el JS listener.
• .tms-engine-loader: Opcional. Elemento visual que pasará a `display: block` automáticamente durante la petición AJAX.

Eventos del Ciclo de Vida

const form = document.querySelector('.tms-engine-form');

// 1. Evento de ÉXITO
form.addEventListener('tms:submit_success', (e) => {
    // El lead se guardó en DB y el correo salió. Status 200.
    // e.detail contiene la respuesta completa del servidor.
    const { message, behavior, redirect_url } = e.detail;
    
    console.log('✅ Lead Procesado:', message);
    
    // Ejemplo: Redirect manual
    if(redirect_url) window.location.href = redirect_url;
    
    // Ejemplo: Mostrar Toast message
    showToast(message);
    
    form.reset();
});

// 2. Evento de ERROR
form.addEventListener('tms:submit_error', (e) => {
    // Falló validación (email duplicado, nonce inválido) o error 500.
    const { message, code } = e.detail;
    
    console.error(`❌ Error ${code}:`, message);
    
    // UI Feedback
    document.getElementById('error-box').innerText = message;
});

5. Seguridad y Errores 🛡️

La seguridad no es una opción, es la base. TMS Optin implementa múltiples capas de defensa para asegurar que tu base de datos de leads esté limpia y tu servidor protegido contra abusos.

Estrategia de Rate Limiting (Token Bucket)

Para prevenir ataques de fuerza bruta en los enlaces de verificación o envíos masivos de formularios, el sistema rastrea la IP del visitante.

• Umbral: Máximo 5 intentos fallidos de verificación por hora.
• Castigo: Si se supera el umbral, la IP es bloqueada (`Ban`) durante 60 minutos.
• Persistencia: Utilizamos Transients de WordPress optimizados (`tms_block_{hash}`) para alto rendimiento.

Referencia de Códigos de Error

6. Métodos PHP (TMS_DB) 🐘

Si eres un desarrollador Backend que trabaja creando temas custom o plugins satélite, no necesitas hacer queries SQL manuales (`SELECT * FROM...`).

La clase `TMS_DB` expone métodos estáticos públicos, seguros y optimizados para interactuar con los datos del plugin desde cualquiera de tus archivos PHP (ej. `functions.php`).

/**
 * Caso de Uso 1: Obtener logs recientes para un Dashboard custom
 * @param int $limit Número de logs a recuperar (Default: 50)
 * @return array Array de objetos stdClass con datos del log + lead asociado
 */
$logs = TMS_DB::get_recent_logs( 10 );

foreach($logs as $log) {
    echo "Lead: " . $log->email . " - Status: " . $log->http_code;
}

/**
 * Caso de Uso 2: Mostrar un contador de descargas en el Frontend
 * @return int Total de leads
 */
$total_descargas = TMS_DB::count_leads( array(
    'campaign' => 'ebook-verano',  // Filtrar por campaña
    'status'   => 'verified'       // Solo contar los confirmados
));

echo "¡Ya somos " . $total_descargas . " lectores!";