Upgrade to stable: checklist and API changes

​

Upgrade checklist

1. Upgrade every @botmesh/* package together, to the same release line. Mixing an old core with newer channel packages is not supported.
2. Dependencies (details): install ffmpeg if your Baileys bot sends voice notes, move Gemini bots to @google/genai, check the redis peer range and the Graph API version, and update dashboards that read botwa_* metrics.
3. Run the type checker (tsc --noEmit) and fix what it reports (details below): imports that moved to @botmesh/core/spi, /testing or /internal, @botmesh/ai/testing, @botmesh/baileys/internal and the removed RedisStore APIs.
4. Replace the deprecated names (table): ctx.reply instead of ctx.say, flow instead of addKeyword, bot.send, bot.plug for plugins, bot.trigger, onType… They still work, but they are removed in v3.
5. Review the behaviour changes (details). The two most bots need: lang: 'es' if your bot speaks Spanish (built-in texts are now English), and maxAttempts: N where a wait set retries: N.
6. Read the notes for your channels and plugins (details).
7. Run your tests and start the bot once with a bot.on('error', …) listener. Watch for the one-time retries warning and for ConfigValidationError, which now names any invalid duration option.

​

Package entries

// Before: Bot, KvDurability, MemoryKv and MemoryCoordinator all came from '@botmesh/core'.
// After:
import { Bot } from '@botmesh/core'
import { KvDurability, MemoryKv } from '@botmesh/core/spi'
import { MemoryCoordinator } from '@botmesh/core/testing'

​

One name per concept

​

Plugins: one instance per name

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

​

Durations

​

Logger

​

Channel and store packages

​

@botmesh/baileys: entries and native types

• Breaking: toInbound and toOutbound are no longer exported by @botmesh/baileys: their signatures use Baileys’ own types. Import them from @botmesh/baileys/internal.
• Breaking (types only): Baileys’ native values are opaque. provider.socket is BaileysSocket | null, provider.auth is BaileysAuthState, and the raw / native of messages, refs and send results are BaileysNativeMessage; the three are unknown aliases. Nothing changes at runtime. Use socketOf(provider) and authStateOf(provider) from @botmesh/baileys/internal for typed handles, or cast with your own @whiskeysockets/baileys import:
  // before
  const sock = provider.socket
  // after
  import { socketOf } from '@botmesh/baileys/internal'
  const sock = socketOf(provider)
  
• The JID predicates (isGroup, isPn, isLid, isBroadcast, isNewsletter) return boolean instead of boolean | undefined (undefined is now false).
• pairingCode is renamed pairingPhoneNumber (the value was always the phone number); passing both with different numbers throws a TypeError.

​

@botmesh/redis-store

// Before
const token = await store.acquireLock(`job:${id}`, 30_000)
// After
const token = (await store.acquireLockFenced(`job:${id}`, 30_000))?.token

​

@botmesh/ai entries

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

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

new AnthropicProvider(client, { model, persona })   // before: compiled; now: TS2353
new AnthropicProvider(client, { model })            // drop the plugin fields
new AnthropicProvider(client, cfg)                  // or pass a variable typed AIConfig

​

HTTP, Graph and scaffolder packages

• Breaking (types only): redirect is gone. It was always overridden with 'manual', because the client follows redirects itself and validates each hop; use maxRedirects (0 refuses any redirect).
• The other RequestInit fields (cache, keepalive, integrity…) still type-check through a @deprecated overload (LegacySecureFetchOptions) and are still forwarded to fetch. They stop being accepted at stable.
• Streaming uploads need no extra field: with a ReadableStream (or async iterable) body, the client sets the duplex: 'half' that fetch requires. Drop an explicit duplex along with the other RequestInit fields.
• A variable typed SecureFetchOptions no longer accepts browser fields (mode, credentials, window…). Remove them.
• resolvePublicHost is now resolveHost: it resolves any host and leaves the verdict to assertSafeTarget. The old name stays as a @deprecated alias.

// Before
await fetchBuffer(url, { redirect: 'follow', cache: 'no-store', maxBytes })
// After
await fetchBuffer(url, { maxRedirects: 3, maxBytes })

// Before
const sig = checkGraphSignature(rawBody, headers, appSecret, logger)
// After
const sig = checkGraphSignature({ body: rawBody, headers, appSecret, logger })

// Before
import { TEMPLATES } from 'create-botmesh'
const files = TEMPLATES.telegram.files('my-bot')
// After
import { getTemplate } from 'create-botmesh'
const files = getTemplate('telegram').files('my-bot')

​

Sandbox API token

• Breaking: POST /api/<channel>/send|fault|status|reset now needs the per-run token in the x-sandbox-token header. Read it from sandbox.token (or the CLI output), or fix it with startSandbox({ token }) / --token.
• Requests whose Host is not loopback, or whose Origin is another site, get a 403. Pass allowedHosts / --allow-host when the hub is reached through another name on purpose.
• Bad input is now a 4xx: unknown fields, wrong types and a body that is not a JSON object are refused, and toUserInput() throws SandboxInputError.

​

Next steps

• Upgrade to stable: dependencies
• Upgrade to stable: behaviour changes
• Upgrade notes: channels & plugins