Actualizar a estable: checklist y cambios de API

​

Checklist de actualización

1. Actualiza todos los paquetes @botmesh/* a la vez, a la misma línea de versiones. No se soporta mezclar un core antiguo con paquetes de canal nuevos.
2. Dependencias (detalles): instala ffmpeg si tu bot de Baileys envía notas de voz, pasa los bots de Gemini a @google/genai, revisa el rango del peer redis y la versión de la Graph API, y actualiza los dashboards que leen métricas botwa_*.
3. Pasa el verificador de tipos (tsc --noEmit) y corrige lo que reporte (detalles abajo): imports que se movieron a @botmesh/core/spi, /testing o /internal, @botmesh/ai/testing, @botmesh/baileys/internal y las APIs eliminadas de RedisStore.
4. Reemplaza los nombres obsoletos (tabla): ctx.reply en vez de ctx.say, flow en vez de addKeyword, bot.send, bot.plug para plugins, bot.trigger, onType… Siguen funcionando, pero se eliminan en la v3.
5. Revisa los cambios de comportamiento (detalles). Los dos que necesitan casi todos los bots: lang: 'es' si tu bot habla español (los textos internos ahora están en inglés) y maxAttempts: N donde una espera usaba retries: N.
6. Lee las notas de tus canales y plugins (detalles).
7. Pasa tus tests y arranca el bot una vez con un listener bot.on('error', …). Atento al aviso único de retries y a ConfigValidationError, que ahora nombra cualquier opción de duración inválida.

​

Entradas del paquete

// Antes: Bot, KvDurability, MemoryKv y MemoryCoordinator venían de '@botmesh/core'.
// Después:
import { Bot } from '@botmesh/core'
import { KvDurability, MemoryKv } from '@botmesh/core/spi'
import { MemoryCoordinator } from '@botmesh/core/testing'

​

Un nombre por concepto

​

Plugins: una instancia por nombre

definePlugin({ name: 'webhook', version: '1.0.0', multiple: true, install(ctx) { /* … */ } })

​

Duraciones

​

Logger

​

Paquetes de canales y stores

​

@botmesh/baileys: entradas y tipos nativos

• Ruptura: @botmesh/baileys ya no exporta toInbound ni toOutbound: sus firmas usan los tipos propios de Baileys. Impórtalos desde @botmesh/baileys/internal.
• Ruptura (solo tipos): los valores nativos de Baileys son opacos. provider.socket es BaileysSocket | null, provider.auth es BaileysAuthState, y el raw / native de mensajes, refs y resultados de envío es BaileysNativeMessage; los tres son alias de unknown. En ejecución no cambia nada. Usa socketOf(provider) y authStateOf(provider) de @botmesh/baileys/internal para tenerlos tipados, o haz el cast con tu propio import de @whiskeysockets/baileys:
  // antes
  const sock = provider.socket
  // después
  import { socketOf } from '@botmesh/baileys/internal'
  const sock = socketOf(provider)
  
• Los predicados de JID (isGroup, isPn, isLid, isBroadcast, isNewsletter) devuelven boolean en lugar de boolean | undefined (undefined ahora es false).
• pairingCode pasa a llamarse pairingPhoneNumber (el valor siempre fue el número de teléfono); pasar los dos con números distintos lanza un TypeError.

​

@botmesh/redis-store

// Antes
const token = await store.acquireLock(`job:${id}`, 30_000)
// Después
const token = (await store.acquireLockFenced(`job:${id}`, 30_000))?.token

​

Entradas de @botmesh/ai

import type { AnthropicLike } from '@botmesh/ai'
type Reply = Awaited<ReturnType<AnthropicLike['messages']['create']>>

aiPlugin({ toolConfirm: { yes: [...DEFAULT_YES, 'arre'] } })

new AnthropicProvider(client, { model, persona })   // antes compilaba; ahora: TS2353
new AnthropicProvider(client, { model })            // quita los campos del plugin
new AnthropicProvider(client, cfg)                  // o pasa una variable de tipo AIConfig

​

Paquetes HTTP, Graph y scaffolder

• Ruptura (solo tipos): desaparece redirect. Siempre se sobrescribía con 'manual', porque el cliente sigue las redirecciones por su cuenta y valida cada salto; usa maxRedirects (0 rechaza cualquier redirección).
• Los demás campos de RequestInit (cache, keepalive, integrity…) siguen compilando con una sobrecarga @deprecated (LegacySecureFetchOptions) y se siguen pasando a fetch. Dejan de aceptarse en la estable.
• Las subidas en streaming no necesitan ningún campo extra: con un body ReadableStream (o iterable asíncrono), el cliente pone el duplex: 'half' que exige fetch. Quita el duplex explícito junto con los demás campos de RequestInit.
• Una variable con tipo SecureFetchOptions ya no admite campos de navegador (mode, credentials, window…). Quítalos.
• resolvePublicHost pasa a llamarse resolveHost: resuelve cualquier host y deja el veredicto a assertSafeTarget. El nombre antiguo queda como alias @deprecated.

// Antes
await fetchBuffer(url, { redirect: 'follow', cache: 'no-store', maxBytes })
// Después
await fetchBuffer(url, { maxRedirects: 3, maxBytes })

// Antes
const sig = checkGraphSignature(rawBody, headers, appSecret, logger)
// Después
const sig = checkGraphSignature({ body: rawBody, headers, appSecret, logger })

// Antes
import { TEMPLATES } from 'create-botmesh'
const files = TEMPLATES.telegram.files('my-bot')
// Después
import { getTemplate } from 'create-botmesh'
const files = getTemplate('telegram').files('my-bot')

​

Token de la API del sandbox

• Ruptura: POST /api/<canal>/send|fault|status|reset necesita ahora el token de la ejecución en la cabecera x-sandbox-token. Léelo de sandbox.token (o de la salida de la CLI), o fíjalo con startSandbox({ token }) / --token.
• Las peticiones con un Host que no es de loopback, o con un Origin de otro sitio, reciben un 403. Pasa allowedHosts / --allow-host si llegas al hub con otro nombre a propósito.
• Una entrada incorrecta es ahora un 4xx: se rechazan los campos desconocidos, los tipos erróneos y un cuerpo que no sea un objeto JSON, y toUserInput() lanza SandboxInputError.

​

Siguientes pasos

• Actualizar a estable: dependencias
• Actualizar a estable: cambios de comportamiento
• Notas de actualización: canales y plugins