Esquemas de Datos¶

Esquemas estandarizados para almacenamiento en @arcaelas/whatsapp.

Principios: - Minimalista: Solo campos esenciales - Plano: Sin anidación innecesaria - Tipado: Tipos explícitos - Temporal: Marcas de tiempo en milisegundos UTC - Anulable: null para ausencia, nunca undefined

Esquemas Crudos¶

Las clases funcionan con objetos "crudos" que contienen propiedades del protocolo. Los getters/setters exponen una API simplificada.

Contacto Crudo¶

Propiedades del objeto de contacto crudo (IContactRaw).

Ejemplo Crudo¶

{
    "id": "584144709840@s.whatsapp.net",
    "lid": "140913951141911@lid",
    "name": "Juan Perez",
    "notify": "Juanito",
    "verifiedName": null,
    "imgUrl": "https://pps.whatsapp.net/v/t61.24694-24/...",
    "status": "Available 24/7"
}

Chat Crudo¶

Propiedades del objeto de conversación crudo (IChatRaw).

IGroupParticipant¶

Ejemplo Crudo¶

{
    "id": "120363123456789@g.us",
    "name": "Development Team",
    "displayName": null,
    "description": "Project coordination group",
    "unreadCount": 5,
    "readOnly": false,
    "archived": false,
    "pinned": 1767371367857,
    "muteEndTime": null,
    "markedAsUnread": false,
    "createdAt": 1700000000,
    "createdBy": "584144709840@s.whatsapp.net",
    "participant": [
        { "id": "584144709840@s.whatsapp.net", "admin": "superadmin" },
        { "id": "584121234567@s.whatsapp.net", "admin": null }
    ],
    "ephemeralExpiration": 604800
}

Mensaje Crudo¶

Propiedades del objeto de mensaje crudo. La librería almacena dos partes: IMessageIndex (metadatos) y WAMessage (crudo Baileys completo).

MessageKey (key)¶

Propiedades Principales¶

Estados de Mensaje (status)¶

Propiedades de Medios¶

Propiedades Temporales¶

Propiedades de Reacción y Encuesta¶

Propiedades de Recibos¶

Propiedades de Stub (Mensajes de Sistema)¶

Propiedades Comerciales¶

Propiedades de Estado/Historial¶

Propiedades de Fijación¶

Propiedades de Bot/IA¶

Propiedades Internas¶

Ejemplo Crudo¶

{
    "key": {
        "remoteJid": "584144709840@s.whatsapp.net",
        "fromMe": false,
        "id": "AC07DE0D18FA8254897A26C90B2FFD98",
        "participant": null
    },
    "message": {
        "extendedTextMessage": {
            "text": "Hello world",
            "contextInfo": {
                "stanzaId": "AC9BE0D81D965A3C240B6ACAA891C6FD",
                "participant": "584121234567@s.whatsapp.net",
                "isForwarded": false,
                "forwardingScore": 0,
                "expiration": 604800
            }
        }
    },
    "messageTimestamp": 1767366759,
    "status": 4,
    "pushName": "Juan Perez",
    "broadcast": false,
    "starred": false,
    "duration": null,
    "labels": [],
    "ephemeralStartTimestamp": 1767366759,
    "ephemeralDuration": 604800,
    "reactions": [
        { "text": "❤️", "groupingKey": "❤️", "senderTimestampMs": 1767366800000 }
    ],
    "userReceipt": [
        { "userJid": "584144709840@s.whatsapp.net", "readTimestamp": 1767366800 }
    ]
}

Contenido del Mensaje¶

Tipos de contenido dentro de message.

Texto¶

Medios¶

Propiedades de Medios (común)¶

Ubicación¶

Encuesta¶

Reacción¶

Protocolo¶

Tipos de ProtocolMessage¶

ContextInfo¶

Esquemas de API¶

Esquemas simplificados expuestos por las clases.

Contacto¶

Clave de Almacenamiento¶

contact/{id}/index

Formato almacenado: JSON IContactRaw (id, lid, name, notify, verifiedName, imgUrl, status).

Chat¶

Clave de Almacenamiento¶

chat/{id}/index

Formato almacenado: JSON IChatRaw (id, name, displayName, description, unreadCount, readOnly, archived, pinned, muteEndTime, markedAsUnread, participant, createdBy, createdAt, ephemeralExpiration).

Mensaje¶

IMessageIndex (almacenado en chat/{cid}/message/{id}/index)¶

Métodos de Instancia¶

Almacenamiento¶

Resumen de Campos¶

Directrices de Almacenamiento¶

Estrategias de almacenamiento para diferentes backends.

Campos Primarios (Columnas/Índices)¶

Campos escalares utilizados para filtros/búsquedas:

Estrategia NoSQL (Key-Value)¶

Para FileEngine, RedisEngine u otros almacenes de key-value.

Estructura de Claves¶

contact/{id}/index          -> IContactRaw JSON
lid/{lid}                   -> JID string
chat/{id}/index             -> IChatRaw JSON
chat/{cid}/messages         -> Archivo de índice de mensajes
chat/{cid}/message/{id}/index   -> IMessageIndex JSON
chat/{cid}/message/{id}/content -> Buffer base64
chat/{cid}/message/{id}/raw     -> WAMessage JSON

Formato de Almacenamiento¶

// contact/{id}/index -- almacena IContactRaw
{
    "id": "584144709840@s.whatsapp.net",
    "lid": "140913951141911@lid",
    "name": "Juan Perez",
    "notify": "Juanito",
    "verifiedName": null,
    "imgUrl": "https://...",
    "status": "Available"
}

// chat/{id}/index -- almacena IChatRaw
{
    "id": "120363123456789@g.us",
    "name": "Dev Team",
    "displayName": null,
    "description": "Group description",
    "unreadCount": 5,
    "readOnly": false,
    "archived": false,
    "pinned": 1767371367857,
    "muteEndTime": null,
    "markedAsUnread": false,
    "participant": [
        { "id": "584144709840@s.whatsapp.net", "admin": "superadmin" }
    ],
    "createdBy": "584144709840@s.whatsapp.net",
    "createdAt": 1700000000,
    "ephemeralExpiration": 604800
}

// chat/{cid}/message/{id}/index -- almacena IMessageIndex
{
    "id": "AC07DE0D18FA8254897A26C90B2FFD98",
    "cid": "584144709840@s.whatsapp.net",
    "mid": null,
    "me": false,
    "type": "text",
    "author": "584144709840@s.whatsapp.net",
    "status": 4,
    "starred": false,
    "forwarded": false,
    "created_at": 1767366759000,
    "deleted_at": null,
    "mime": "text/plain",
    "caption": "",
    "edited": false
}

Ventajas¶

• Simplicidad: Todo es JSON, sin migraciones
• Atomicidad: Un registro = una clave
• Flexibilidad: Agregar campos sin alterar estructura

Consideraciones¶

Listados y Filtros:

# Listar contactos
engine.list("contact/")

# Listar mensajes de un chat
Leer chat/{cid}/messages index, luego obtener cada mensaje

# Filtrar mensajes marcados con estrella
Requiere iterar y filtrar en memoria

Limpieza (cascade delete):

# Eliminar chat y todos sus mensajes
engine.set("chat/{cid}", null)
# El engine elimina cascadingly todas las subclaves: chat/{cid}/*

Datos Huérfanos: - Al eliminar chat: set("chat/{cid}", null) elimina todas las claves con prefijo chat/{cid}/ - Al eliminar contacto: set("contact/{id}/index", null) (sin dependencias)

Estrategia SQL (Relacional)¶

Para PostgreSQL, MySQL, SQLite.

Esquema de Tabla¶

-- Contactos (almacena campos IContactRaw)
CREATE TABLE contacts (
    id VARCHAR(50) PRIMARY KEY,
    lid VARCHAR(50),
    name VARCHAR(255),
    notify VARCHAR(255),
    verified_name VARCHAR(255),
    img_url TEXT,
    status TEXT
);

-- Chats (almacena campos IChatRaw)
CREATE TABLE chats (
    id VARCHAR(50) PRIMARY KEY,
    name VARCHAR(255),
    display_name VARCHAR(255),
    description TEXT,
    unread_count INTEGER,
    read_only BOOLEAN DEFAULT FALSE,
    archived BOOLEAN DEFAULT FALSE,
    pinned BIGINT,  -- timestamp o NULL
    mute_end_time BIGINT,  -- timestamp o NULL
    marked_as_unread BOOLEAN DEFAULT FALSE,
    created_by VARCHAR(50),
    created_at BIGINT,
    ephemeral_expiration INTEGER
);

-- Participantes del grupo
CREATE TABLE chat_participants (
    chat_id VARCHAR(50) REFERENCES chats(id) ON DELETE CASCADE,
    contact_id VARCHAR(50),
    admin VARCHAR(20),  -- NULL, 'admin', 'superadmin'
    PRIMARY KEY (chat_id, contact_id)
);

-- Mensajes (almacena campos IMessageIndex)
CREATE TABLE messages (
    id VARCHAR(50),
    cid VARCHAR(50) REFERENCES chats(id) ON DELETE CASCADE,
    mid VARCHAR(50),  -- mensaje padre (respuesta)
    me BOOLEAN NOT NULL,
    type VARCHAR(20) NOT NULL,
    author VARCHAR(50) NOT NULL,
    status SMALLINT DEFAULT 1,
    starred BOOLEAN DEFAULT FALSE,
    forwarded BOOLEAN DEFAULT FALSE,
    created_at BIGINT NOT NULL,
    deleted_at BIGINT,
    mime VARCHAR(100),
    caption TEXT,
    edited BOOLEAN DEFAULT FALSE,
    PRIMARY KEY (cid, id)
);

-- Contenido del mensaje (separado para eficiencia)
CREATE TABLE message_contents (
    cid VARCHAR(50),
    message_id VARCHAR(50),
    content BYTEA,
    raw JSONB,
    PRIMARY KEY (cid, message_id),
    FOREIGN KEY (cid, message_id) REFERENCES messages(cid, id) ON DELETE CASCADE
);

-- Reacciones
CREATE TABLE message_reactions (
    cid VARCHAR(50),
    message_id VARCHAR(50),
    reactor_id VARCHAR(50),
    emoji VARCHAR(10),
    timestamp BIGINT,
    PRIMARY KEY (cid, message_id, reactor_id),
    FOREIGN KEY (cid, message_id) REFERENCES messages(cid, id) ON DELETE CASCADE
);

Índices Recomendados¶

-- Búsquedas frecuentes
CREATE INDEX idx_messages_chat ON messages(cid);
CREATE INDEX idx_messages_created ON messages(cid, created_at DESC);
CREATE INDEX idx_messages_author ON messages(author);
CREATE INDEX idx_messages_starred ON messages(cid, starred) WHERE starred = TRUE;

-- Filtros de chat
CREATE INDEX idx_chats_archived ON chats(archived) WHERE archived = TRUE;
CREATE INDEX idx_chats_pinned ON chats(pinned) WHERE pinned IS NOT NULL;

Ventajas¶

• Integridad: Las foreign keys garantizan consistencia
• cascade delete: ON DELETE CASCADE limpia automáticamente
• Filtros Eficientes: Índices en campos de búsqueda
• Joins: Relacionar datos sin múltiples consultas

Consultas Comunes¶

-- Mensajes del chat ordenados
SELECT * FROM messages WHERE cid = ? ORDER BY created_at DESC LIMIT 50;

-- Mensajes propios marcados con estrella
SELECT * FROM messages WHERE me = TRUE AND starred = TRUE;

-- Chats con mensajes no leídos
SELECT * FROM chats WHERE unread_count > 0 OR marked_as_unread = TRUE;

-- Eliminar chat (cascade elimina mensajes, reacciones, etc.)
DELETE FROM chats WHERE id = ?;

Comparación¶

Recomendaciones por Caso de Uso¶

Bot Simple / Prototipo¶

• Backend: FileEngine (archivos JSON)
• Razón: Cero configuración, fácil depuración

Bot de Producción (< 100k mensajes)¶

• Backend: SQLite + FileEngine (contenido)
• Razón: Balance entre rendimiento y simplicidad

Bot de Producción (> 100k mensajes)¶

• Backend: PostgreSQL + Redis (cache)
• Razón: Índices, cascade delete, consultas complejas

Multi-tenant / SaaS¶

• Backend: PostgreSQL con particionamiento por cid
• Razón: Aislamiento de datos, limpieza por-tenant

Prevención de Datos Huérfanos¶

Principio¶

Al eliminar una entidad padre, SIEMPRE elimina sus dependencias.

Cascada de Eliminación¶

Eliminar Contacto:
+-- contact/{id}/index

Eliminar Chat (vía set("chat/{cid}", null)):
|-- chat/{id}/index
|-- chat/{id}/messages
|-- chat/{id}/message/*/index
|-- chat/{id}/message/*/content
|-- chat/{id}/message/*/raw
+-- (SQL) chat_participants, messages, message_contents, message_reactions

Eliminar Mensaje (vía set("chat/{cid}/message/{mid}", null)):
|-- chat/{cid}/message/{id}/index
|-- chat/{cid}/message/{id}/content
+-- chat/{cid}/message/{id}/raw
    (SQL) message_contents, message_reactions

Implementación¶

El cascade delete es manejado por el contrato set(key, null) del Engine. La librería llama:

// Eliminar chat y todo su contenido
await wa.Chat.remove(cid);
// o
const chat = await wa.Chat.get(cid);
await chat.remove();

// Internamente llama:
// await wa.engine.set("chat/{cid}", null);
// que cascade-deleta todas las subclaves