Introducción a Gmail.js para extensiones

Gmail.js es una biblioteca JavaScript diseñada específicamente para crear extensiones del navegador que interactúan con Gmail. Ofrece una API simplificada para acceder a datos de correo, escuchar eventos y manipular la interfaz de usuario sin requerir autenticación OAuth compleja. Esta guía muestra cómo desarrollar una extensión básica en minutos.

Configuración del entorno de desarrollo

Antes de comenzar, asegúrate de tener Node.js instalado. La biblioteca se instala mediante npm:

npm install gmail-js

Para explorar ejemplos y documentación, puedes revisar el repositorio oficial.

Arquitectura central de Gmail.js

La API se organiza en módulos principales:

• Obtención de datos: Métodos como gmail.get.email() para recuperar información de usuario y correos.
• Manejo de eventos: Funciones para observar acciones como envío, recepción o eliminación de correos.
• Manipulación del DOM: Herraimentas para interactuar con elementos de la interfaz de Gmail.
• Utilidades de UI: Funciones para agregar botones, ventanas modales y otros componentes.

Desarrollo práctico: extensión de notificaciones

Paso 1: Estructura inicial del proyecto

Crea un archivo manifest.json con la configuración básica de la extensión (compatible con Manifest V2/V3):

{
  "name": "Notificador de Gmail",
  "version": "1.0",
  "description": "Muestra alertas al recibir correos nuevos",
  "content_scripts": [
    {
      "matches": ["https://mail.google.com/*"],
      "js": ["lib-gmail.js", "app.js"],
      "run_at": "document_start"
    }
  ],
  "permissions": ["notifications"]
}

Paso 2: Lógica principal (app.js)

Implementa la detección de nuevos correos y la emisión de notificaciones del sistema:

const GmailLib = require('gmail-js');
const client = new GmailLib.Gmail();

client.observe.on('load', () => {
  const userEmail = client.get.user_email();
  console.log('Sesión activa para:', userEmail);

  client.observe.on('new_email', (msgId) => {
    const details = client.new.get.email_data(msgId);
    if (details) {
      chrome.notifications.create({
        type: 'basic',
        iconUrl: 'icon.png',
        title: 'Nuevo correo',
        message: `De: ${details.from.address}\nAsunto: ${details.subject}`
      });
    }
  });
});

Paso 3: Despliegue y pruebas

1. Abre chrome://extensions/ en Chrome.
2. Activa el "Modo desarrollador".
3. Selecciona "Cargar extensión sin empaquetar" y apunta a la carpeta del proyecto.
4. Accede a Gmail y verifica las notificaciones al recibir correos.

Consultas útiles de la API

Acceso a datos de correo

// Obtener dirección del usuario
const address = client.get.user_email();

// Leer contenido del correo activo
const activeEmail = client.new.get.email_data();
console.log('Asunto:', activeEmail.subject);
console.log('Remitente:', activeEmail.from.address);
console.log('Contenido HTML:', activeEmail.content_html);

Intercepción de acciones

// Modificar correos antes de enviar
client.observe.before('send_message', (url, payload, meta) => {
  console.log('Correo a enviar:', meta.subject);
  // Ejemplo: agregar destinatarios adicionales
});

// Detectar eliminación de correos
client.observe.on('delete', (id) => {
  console.log('Correo eliminado:', id);
});

Incorporación de elementos de interfaz

// Insertar botón en la barra de herramientas
client.tools.add_toolbar_button(
  '<span>⚡ Priorizar</span>',
  () => {
    const currentId = client.new.get.email_id();
    client.mark_as_important(currentId);
  },
  'btn-priority'
);

Estructura típica del proyecto

Un proyecto básico puede organizarse así:

mi-extension/
├── manifest.json
├── app.js                # Lógica principal
├── lib-gmail.js          # Biblioteca Gmail.js incluida
└── icon.png              # Ícono para notificaciones

Solución de problemas comunes

Problema: La extensión no responde.
Solución: Verifica que run_at sea document_start en el manifiesto y que los scripts se carguen en orden correcto.

Problema: No se obtienen datos de correo.
Solución: Usa el evento load para asegurar que Gmail.js se inicialice después de cargar la interfaz.

Problema: Compatibilidad del navegador.
Solución: Gmail.js funciona con navegadores que soportan WebExtensions, como Chrome y Firefox.