> ## Documentation Index
> Fetch the complete documentation index at: https://botmesh.afaya.com.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Packages and versions

> botmesh is a set of packages in one monorepo: the engine, @botmesh/core, plus one package per channel, store, plugin and tool. This page is the reference for which of them are published, under which npm tag, and what every package requires. Other pages link here instead of repeating it.

## Release status

botmesh is in **beta**. The public packages are published from the
[Changesets](https://github.com/changesets/changesets) prerelease mode `beta`:

| Package | Beta versions | Stable line |
| - | - | - |
| `@botmesh/core` | `2.0.0-beta.N` | `2.0.0` |
| Every other public package | `1.0.0-beta.N` | `1.0.0` |

The guides document the beta and the API it freezes for the stable line.
Coming from a 2.0 alpha, read the [upgrade guide](https://botmesh.afaya.com.co/guide/stable-migration.md).

## npm dist-tags

* **`beta`** always points at the newest beta of each package. A publish moves
  it automatically.
* **`latest`** is what a plain install (`pnpm add @botmesh/core`) resolves to.
  The release tooling never moves it during the beta: the maintainer moves it
  **by hand** to the same versions after each publish, so a plain install gets
  the beta too.

Right after a publish, `latest` can still point at the previous beta for a
while. Check the tags with:

```bash theme={null}
pnpm view @botmesh/core dist-tags
```

## Installing

Install the core plus the packages you need, with a plain install:

```bash theme={null}
pnpm add @botmesh/core @botmesh/baileys
```

or with the `beta` tag, which always gets the newest beta (use it when
`latest` lags behind):

```bash theme={null}
pnpm add @botmesh/core@beta @botmesh/baileys@beta
```

Install every `@botmesh/*` package from the **same tag**. The published
packages depend on each other with caret ranges (`^x.y.z`), so the package
manager keeps a single copy of `@botmesh/core`; mixing builds from different
tags can fail on missing exports or peer ranges (see
[Troubleshooting](https://botmesh.afaya.com.co/guide/troubleshooting.md#pnpm-add-@botmesh/core-installs-an-older-build)).
To start a new project, `npm create botmesh` stamps matching versions for you
(see [Quick start](https://botmesh.afaya.com.co/guide/getting-started.md)).

## Requirements

* **Node.js 22 or newer.** Every package declares `"engines": { "node": ">=22" }`.
  The [quick start](https://botmesh.afaya.com.co/guide/getting-started.md#requirements) recommends 22.12 or newer.
* **ESM only.** No package ships CommonJS: use `import` (never `require()`),
  set `"type": "module"` in your `package.json` (or use `.mjs` files) and, with
  TypeScript, `"module": "nodenext"`.
* Optional SDKs are **peer dependencies loaded lazily**: the LLM SDKs of
  `@botmesh/ai`, `better-sqlite3`, `pg`, `mysql2`, `mongodb` and `redis` for the
  stores, `imapflow` and `nodemailer` for email, `pdf-parse` for RAG,
  `@opentelemetry/api` for `@botmesh/otel`. Install the one you use.

## Entry points and semver

A package's main entry (`@botmesh/core`, `@botmesh/telegram`…) is its public
API, covered by semver. Some packages add subpath entries:

| Entry | What it holds |
| - | - |
| `@botmesh/core/spi` | Building blocks for store, durability, scheduler and transport authors. Covered by semver. |
| `@botmesh/core/testing` | `createTestBot`, `MockProvider` and the contract helpers ([Testing](https://botmesh.afaya.com.co/guide/testing.md)). Covered by semver. |
| `@botmesh/core/dev` | The terminal simulator as a library ([Terminal simulator](https://botmesh.afaya.com.co/guide/dev-simulator.md)). |
| `@botmesh/server/express`, `/fastify`, `/hono` | Framework adapters of the [webhook server](https://botmesh.afaya.com.co/guide/server.md). |
| `@botmesh/events/durability` | The event-journal durability backend ([Durable processing](https://botmesh.afaya.com.co/guide/durability.md)). |
| `@botmesh/ai/testing` | `MockAIProvider` and `validateArgs` ([AI plugin](https://botmesh.afaya.com.co/guide/ai.md)). Covered by semver. |
| `<package>/internal` | Engine internals and building blocks, with **no semver guarantee**: they can change in any release. A published package never imports another package's `/internal`. |

## Public packages (36)

All of them are on npm under `beta` and `latest`. The directory is the folder
under [`packages/`](https://github.com/andresayac/botmesh/tree/main/packages).

**Engine**

| Package | Directory | Guide |
| - | - | - |
| `@botmesh/core` | `core` | [Core concepts](https://botmesh.afaya.com.co/guide/concepts.md) |

**Channels (12)**

| Package | Directory | Guide |
| - | - | - |
| `@botmesh/baileys` | `baileys-provider` | [Baileys (WhatsApp Web)](https://botmesh.afaya.com.co/guide/baileys.md) |
| `@botmesh/meta` | `meta-provider` | [WhatsApp Cloud API](https://botmesh.afaya.com.co/guide/whatsapp-cloud-api.md) |
| `@botmesh/evolution` | `evolution-provider` | [Evolution API](https://botmesh.afaya.com.co/guide/evolution.md) |
| `@botmesh/wppconnect` | `wppconnect-provider` | [WPPConnect](https://botmesh.afaya.com.co/guide/wppconnect.md) |
| `@botmesh/twilio` | `twilio-provider` | [Twilio](https://botmesh.afaya.com.co/guide/twilio.md) |
| `@botmesh/gupshup` | `gupshup-provider` | [Gupshup](https://botmesh.afaya.com.co/guide/gupshup.md) |
| `@botmesh/gohighlevel` | `gohighlevel-provider` | [HighLevel](https://botmesh.afaya.com.co/guide/gohighlevel.md) |
| `@botmesh/messenger` | `messenger-provider` | [Messenger](https://botmesh.afaya.com.co/guide/messenger.md) |
| `@botmesh/instagram` | `instagram-provider` | [Instagram](https://botmesh.afaya.com.co/guide/instagram.md) |
| `@botmesh/telegram` | `telegram-provider` | [Telegram](https://botmesh.afaya.com.co/guide/telegram.md) |
| `@botmesh/discord` | `discord-provider` | [Discord](https://botmesh.afaya.com.co/guide/discord.md) |
| `@botmesh/email` | `email-provider` | [Email](https://botmesh.afaya.com.co/guide/email.md) |

**Shared infrastructure**

| Package | Directory | Guide |
| - | - | - |
| `@botmesh/http` | `http` | [Security](https://botmesh.afaya.com.co/guide/security.md) (SSRF-safe HTTP client) |
| `@botmesh/graph-core` | `graph-core` | Shared Meta Graph helpers of `meta`, `messenger` and `instagram` |
| `@botmesh/wa-gateway-kit` | `wa-gateway-kit` | Shared identity, REST and media of `evolution` and `wppconnect` |
| `@botmesh/server` | `server` | [Webhook server](https://botmesh.afaya.com.co/guide/server.md) |

**Stores (5)**

| Package | Directory | Guide |
| - | - | - |
| `@botmesh/sqlite-store` | `sqlite-store` | [Persistent store](https://botmesh.afaya.com.co/guide/store.md) |
| `@botmesh/redis-store` | `redis-store` | [Persistent store](https://botmesh.afaya.com.co/guide/store.md), [Redis Cluster](https://botmesh.afaya.com.co/guide/redis-cluster.md) |
| `@botmesh/postgres-store` | `postgres-store` | [Persistent store](https://botmesh.afaya.com.co/guide/store.md) |
| `@botmesh/mysql-store` | `mysql-store` | [Persistent store](https://botmesh.afaya.com.co/guide/store.md) |
| `@botmesh/mongo-store` | `mongo-store` | [Persistent store](https://botmesh.afaya.com.co/guide/store.md) |

**Operations and observability**

| Package | Directory | Guide |
| - | - | - |
| `@botmesh/events` | `events` | [Operations](https://botmesh.afaya.com.co/guide/operations.md) |
| `@botmesh/otel` | `otel` | [Tracing (OpenTelemetry)](https://botmesh.afaya.com.co/guide/tracing.md) |

**Plugins (8)**

| Package | Directory | Guide |
| - | - | - |
| `@botmesh/ai` | `ai` | [AI plugin](https://botmesh.afaya.com.co/guide/ai.md) |
| `@botmesh/rag` | `rag` | [AI memory & RAG](https://botmesh.afaya.com.co/guide/ai-memory-rag.md) |
| `@botmesh/voice` | `voice` | [Voice (STT/TTS)](https://botmesh.afaya.com.co/guide/voice.md) |
| `@botmesh/nlu` | `nlu` | [Integrations](https://botmesh.afaya.com.co/guide/integrations.md) |
| `@botmesh/dialogflow` | `dialogflow` | [Integrations](https://botmesh.afaya.com.co/guide/integrations.md) |
| `@botmesh/chatwoot` | `chatwoot` | [Integrations](https://botmesh.afaya.com.co/guide/integrations.md) |
| `@botmesh/tickets` | `tickets` | [Integrations](https://botmesh.afaya.com.co/guide/integrations.md) |
| `@botmesh/moderation` | `moderation` | [Integrations](https://botmesh.afaya.com.co/guide/integrations.md) |

**Tooling**

| Package | Directory | Guide |
| - | - | - |
| `@botmesh/flow-schema` | `flow-schema` | [JSON flow schema](https://botmesh.afaya.com.co/guide/flow-schema.md) |
| `create-botmesh` | `create-botmesh` | [Quick start](https://botmesh.afaya.com.co/guide/getting-started.md) |
| `eslint-plugin-botmesh` | `eslint-plugin` | [ESLint plugin](https://botmesh.afaya.com.co/guide/eslint.md) |
| `@botmesh/mcp` | `mcp` | [MCP server](https://botmesh.afaya.com.co/guide/mcp.md) |

Ten of them were first published during the alpha (`core`, `baileys`, `meta`,
`telegram`, `sqlite-store`, `redis-store`, `ai`, `http`, `graph-core` and
`create-botmesh`); the other 26 were published for the first time with the beta.

## Private packages (9)

These packages are implemented and tested, but they have `"private": true` in
their `package.json`: they are **not on npm**, they do not follow semver and
their API may change. Pages that document them carry an "Experimental" notice
and sit at the end of their section. Use them from a clone of the monorepo,
with `"workspace:*"` dependencies. A published package never depends on them.

| Package | Directory | What it is | Guide |
| - | - | - | - |
| `@botmesh/tiktok` | `tiktok-provider` | TikTok channel (comments and DMs) | [TikTok](https://botmesh.afaya.com.co/guide/tiktok.md) |
| `@botmesh/manager` | `manager` | Many bots per process, REST control plane | [Control plane](https://botmesh.afaya.com.co/guide/control-plane.md) |
| `@botmesh/sandbox` | `sandbox` | Local platform simulators and web chat | [Platform sandbox](https://botmesh.afaya.com.co/guide/sandbox.md) |
| `@botmesh/inbox` | `inbox` | Shared inbox: assignment, notes, unread | [Operations](https://botmesh.afaya.com.co/guide/operations.md#operational-packages) |
| `@botmesh/crm` | `crm` | Contacts, tags, consent and segments | [Operations](https://botmesh.afaya.com.co/guide/operations.md#operational-packages) |
| `@botmesh/hub` | `hub` | Plugin manifests and permissions | [Operations](https://botmesh.afaya.com.co/guide/operations.md#operational-packages) |
| `@botmesh/campaigns` | `campaigns` | Campaign sends with consent and dedupe | [Operations](https://botmesh.afaya.com.co/guide/operations.md#operational-packages) |
| `@botmesh/deployments` | `deployments` | Publish gate and audit log for flows | [Golden transcripts](https://botmesh.afaya.com.co/guide/golden-transcripts.md#publish-gate-@botmesh/deployments) |
| `@botmesh/tenant-kv` | `tenant-kv` | Per-tenant JSON documents over any `DurableKv` | [Operations](https://botmesh.afaya.com.co/guide/operations.md#operational-packages) |

The repository also holds a runnable example, `examples/bakery-ai`
(`@botmesh/example-bakery-ai`, private).

## Next steps

* [Quick start](https://botmesh.afaya.com.co/guide/getting-started.md): scaffold a project or install by hand.
* [Channels](https://botmesh.afaya.com.co/guide/channels.md): choose a channel and compare what each one supports.
* [Upgrade guide](https://botmesh.afaya.com.co/guide/stable-migration.md): moving from a 2.0 alpha.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.