Esquemas de datos¶

Referencia para cada documento que @arcaelas/whatsapp v3 escribe a través de un Engine.

La librería nunca almacena blobs binarios directamente: cada valor pasa primero por serialize() (que usa BufferJSON de baileys) por lo que el motor solo ve y persiste strings. Los drivers de motor (RedisEngine, FileSystemEngine) son tuberías opacas; no están al tanto de JSON, de WhatsApp, ni de buffers.

Vista general del layout de almacenamiento¶

El orquestador (WhatsApp) escribe en un conjunto pequeño y fijo de rutas. Todo lo que produce la librería vive bajo una de estas ramas:

Las rutas usan / como separador y nunca comienzan ni terminan con una barra una vez normalizadas — ambos motores colapsan // y recortan / iniciales/finales.

Índice de rutas¶

Cada ruta concreta que el orquestador puede escribir o leer.

Formas de los documentos¶

Todos los documentos son JSON serializados con BufferJSON. Los buffers se codifican como:

{ "type": "Buffer", "data": "<base64 string>" }

deserialize<T>(raw) reconstruye las instancias originales Buffer/Uint8Array al leer.

IContactRaw — /contact/<jid>¶

interface IContactRaw {
    id: string;                  // JID canónico (p. ej. 584144709840@s.whatsapp.net)
    lid: string | null;          // identificador LID alternativo cuando se conoce
    name: string | null;         // nombre de libreta de direcciones
    notify: string | null;       // push name definido por el contacto
    verified_name: string | null;// nombre verificado de negocio
    img_url: string | null;      // URL de la foto de perfil ("changed" si rotó)
    status: string | null;       // bio / about
}

Payload de ejemplo:

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

IChatRaw — /chat/<cid>¶

El documento de chat solo persiste los campos que el orquestador rastrea explícitamente (ver _handle_chats_upsert / _handle_chats_update):

interface IChatRaw {
    id: string;
    name?: string | null;
    archived?: boolean | null;
    pinned?: number | null;          // timestamp de pin; null/ausente = sin pin
    mute_end_time?: number | null;   // ms epoch; <= Date.now() significa sin silenciar
    unread_count?: number | null;
    read_only?: boolean | null;
}

Payload de ejemplo:

{
    "id": "120363123456789@g.us",
    "name": "Dev Team",
    "archived": false,
    "pinned": 1767371367857,
    "mute_end_time": null,
    "unread_count": 5,
    "read_only": false
}

IMessage — /chat/<cid>/message/<mid>¶

interface IMessage {
    id: string;                  // key.id
    cid: string;                 // remoteJidAlt || remoteJid
    mid: string | null;          // contextInfo.stanzaId (padre para respuestas)
    me: boolean;                 // key.fromMe
    type: 'text' | 'image' | 'video' | 'audio' | 'location' | 'poll';
    author: string;              // JID resuelto del remitente
    status: MessageStatus;       // 0..5 (ERROR..PLAYED)
    starred: boolean;
    forwarded: boolean;          // contextInfo.isForwarded
    created_at: number;          // ms epoch (messageTimestamp * 1000)
    deleted_at: number | null;   // ms epoch cuando expira un efímero
    mime: string;                // text/plain | application/json | mimetype de media
    caption: string;             // cuerpo de texto o caption/title/option-list para media
    edited: boolean;
    raw: WAMessage;              // raw completo de baileys, usado para forward / re-descarga
}

Enum MessageStatus:

Contenido del mensaje — /chat/<cid>/message/<mid>/content¶

Almacenado como un pequeño sobre JSON:

interface IMessageContent {
    data: string;                // payload codificado en base64
}

La forma del contenido depende de IMessage.type:

Credenciales de sesión — /session/creds¶

El valor es el objeto opaco AuthenticationCreds de baileys serializado con BufferJSON. La librería no introspecciona ni documenta sus campos internos; los consumidores deben tratarlo como una caja negra propiedad de baileys.

Para rotar la sesión manualmente, unset('/session/creds') y deja que connect() lo regenere en el próximo start() (el orquestador vuelve a leer las creds al inicio de cada reintento).

Índice LID — /lid/<lid> y /lid/<lid>_reverse¶

Usado por WhatsApp._resolve_jid() para normalizar cualquier identificador @lid a un JID @s.whatsapp.net canónico.

Mapeo de rutas del motor¶

RedisEngine¶

El driver de Redis usa dos keyspaces por ruta lógica:

<prefix>:doc:<path>          -> valor string (el documento serializado)
<prefix>:idx:<parent_path>   -> sorted set; score = mtime (Date.now()), member = ruta hija completa

Por lo que una escritura a /chat/120363@g.us/message/ABC realmente ejecuta:

SET   wa:default:doc:chat/120363@g.us/message/ABC  "<json>"
ZADD  wa:default:idx:chat/120363@g.us/message      <ts>  "chat/120363@g.us/message/ABC"

El prefijo por defecto es wa:default. Usa un prefijo diferente por cuenta cuando compartas una instancia de Redis entre sesiones:

import IORedis from 'ioredis';
import { RedisEngine } from '@arcaelas/whatsapp';

const redis = new IORedis(process.env.REDIS_URL);

const engine_a = new RedisEngine(redis, 'wa:584144709840');
const engine_b = new RedisEngine(redis, 'wa:584121234567');

FileSystemEngine¶

El driver del sistema de archivos mapea cada ruta lógica a un directorio y escribe el documento dentro como index.json:

<base>/<path>/index.json      -> documento

Una escritura a /chat/120363@g.us/message/ABC produce:

<base>/chat/120363@g.us/message/ABC/index.json

Las sub-rutas simplemente se anidan como directorios adicionales junto a index.json, por lo que un recurso y sus hijos pueden coexistir en disco:

<base>/chat/120363@g.us/
├── index.json                     # el documento del chat
└── message/
    ├── ABC/
    │   ├── index.json             # el documento del mensaje
    │   └── content/
    │       └── index.json         # el sobre { data: base64 }
    └── DEF/
        └── index.json

unset() en cascada¶

unset(path) elimina el documento y todo el subárbol debajo de él. Esto es intencional y se usa a lo largo del orquestador para limpieza masiva barata:

Helpers de serialización¶

Los motores nunca ven objetos tipados — solo strings. Los helpers serialize/deserialize manejan la frontera JSON ↔ objeto y preservan las instancias de Buffer a través de BufferJSON:

import { serialize, deserialize } from '@arcaelas/whatsapp';

await wa.engine.set('/chat/abc', serialize({ id: 'abc', name: 'demo' }));

const raw = await wa.engine.get('/chat/abc');
const doc = deserialize<IChatRaw>(raw);  // → { id, name, ... } o null

Usa los mismos helpers en cualquier llamador de Engine personalizado si quieres compatibilidad bit a bit con lo que escribe el orquestador.