lessel (from "vessel") is a general-purpose, open-source message pipeline framework. It connects to platforms like Discord, WhatsApp, and Slack, listens for messages that match your rules, stores them, and exposes them through a REST API for your own executors (plugins) to process.

---

Table of Contents

• Features
• Architecture
• Install
• Quick Start
• API Endpoints
• Plugins
• Ecosystem
• Project Structure
• Documentation
• Contributing
• License

---

Features

• Platform-agnostic — Discord, WhatsApp, Slack supported out of the box
• Schema-based filtering — Define what messages to capture using simple JSON rules
• SQLite storage — Zero-config persistence. No external database needed
• API Key authentication — Secure REST API with rate limiting and timing-safe key validation
• Plugin system — Install @lessel/plugin-* packages that run inside the pipeline
• Cross-platform sends — One plugin can send to any platform via context.send()
• Extensible — Build your own listeners, senders, and plugins via interfaces

---

Architecture

flowchart LR
subgraph Platform
D[Discord]
W[WhatsApp]
S[Slack]
end
subgraph lessel
direction TB
L[Listener]
P[Pipeline]
A[API Server]
ST[(SQLite Store)]
PL[Plugin Loader]
end
subgraph Plugins
PL1[plugin]
end
D --> L
W --> L
S --> L
L --> P
P --> ST
P --> PL
PL --> PL1
A --> ST

Loading

LES Framework

• Listener — Connects to a platform (Discord, WhatsApp, etc.) and ingests messages as MessageEvent objects
• Executer (Plugin) — Code that runs inside the pipeline when a message matches a schema. Could be an AI bot, a logging system, a notification service, etc
• Sender — Sends processed data back to platforms (e.g., post to WhatsApp)

---

Plugin Registry

lessel has a community plugin registry powered by GitHub. Browse, search, and install plugins:

# Search available plugins
npx @lessel/cli plugin search sentiment
# Install a plugin
npx @lessel/cli plugin install example-logger
# Prepare your plugin for publishing
npx @lessel/cli plugin publish ./path/to/plugin

Browse the registry:https://terminay.github.io/lessel-plugins

Submit plugins via PR:https://github.com/Terminay/lessel-plugins

---

Install via npm (no clone needed)

# Recommended: install the meta-package
npm install lessel-kit

This installs:

• @lessel/core — pipeline engine, store, API server
• @lessel/listener-discord — Discord listener
• @lessel/listener-slack — Slack listener
• @lessel/listener-whatsapp — WhatsApp listener
• @lessel/sender-discord — Discord sender
• @lessel/sender-slack — Slack sender
• @lessel/sender-whatsapp — WhatsApp sender
• @lessel/cli — command-line tool

Or use the CLI directly without installing:

npx @lessel/cli init # scaffolds lessel.config.json + .env
npx @lessel/cli start # starts the pipeline + API

---

Quick Start

Prerequisites

• Node.js >= 18
• npm

Installation

git clone https://github.com/Terminay/lessel.git
cd lessel
npm install

Configuration

1. Copy the example environment file:

   cp .env.example .env

2. Fill in your Discord bot token:

   DISCORD_BOT_TOKEN=your_discord_bot_token_here
   

3. Create lessel.config.json:

   {
   "port": 3100,
   "schemas": [
   {
   "name": "all-messages",
   "platforms": ["discord"],
   "filters": [],
   "extract": [
   { "key": "content", "path": "content" },
   { "key": "author", "path": "authorName" }
   ],
   "store": true
   }
   ],
   "plugins": ["@lessel/plugin-logger"]
   }

Run

npm run build
npm start

Lessel will start the Discord listener and the API server at http://localhost:3100.

---

API Endpoints

Endpoint	Auth	Description
GET /health	No	Health check
GET /stats	Yes	Dashboard statistics
GET /schemas	Yes	List all schemas
GET /messages	Yes	Retrieve stored messages
GET /messages?schema=...&platform=...	Yes	Filter messages
GET /messages/stream?since=ISO8601	Yes	Poll new messages
POST /admin/keys	Yes	Create a new API key
GET /admin/keys	Yes	List API keys

All protected endpoints require a Bearer token:

Authorisation: Bearer lsl_<your_api_key>

---

Plugins

lessel plugins (@lessel/cli plugin install <plugin-name>) are executers that run inside the pipeline, no external server or polling needed.

// my-plugin.jsmodule.exports={name: 'my-plugin',schema: 'all-messages',// which schema to hook intoasyncexecute(event,context){// event.payload — extracted fields// context.store — direct SQLite access// context.log — logging helper// context.send — send to any platform}};

Register in lessel.config.json:

{ "plugins": ["./my-plugin.js"] }

Or install published plugins: npx @lessel/cli plugin add @lessel/plugin-logger

---

Ecosystem

Package	npm	Description
lessel-kit	npm install lessel-kit	Meta-package with all platforms
@lessel/core	npm install @lessel/core	Pipeline engine, store, API server
@lessel/listener-discord	npm install @lessel/listener-discord	Discord listener
@lessel/listener-slack	npm install @lessel/listener-slack	Slack listener
@lessel/listener-whatsapp	npm install @lessel/listener-whatsapp	WhatsApp listener
@lessel/sender-discord	npm install @lessel/sender-discord	Discord sender
@lessel/sender-slack	npm install @lessel/sender-slack	Slack sender
@lessel/sender-whatsapp	npm install @lessel/sender-whatsapp	WhatsApp sender
@lessel/cli	npm install @lessel/cli	CLI tool
@lessel/plugin-logger	npm install @lessel/plugin-logger	Example plugin

---

Project Structure

packages/
core/ # @lessel/core
listener/ # IListener interface
api/ # REST API server
store/ # SQLite persistence
pipeline/ # Pipeline orchestrator
plugin/ # Plugin loader
listener-discord/ # @lessel/listener-discord
listener-slack/ # @lessel/listener-slack
listener-whatsapp/ # @lessel/listener-whatsapp
sender-discord/ # @lessel/sender-discord
sender-slack/ # @lessel/sender-slack
sender-whatsapp/ # @lessel/sender-whatsapp
cli/ # @lessel/cli (npx @lessel/cli init/start/plugin)
plugin-logger/ # @lessel/plugin-logger (example)
lessel-kit/ # lessel-kit meta-package

---

Documentation

• Getting Started
• Your First Plugin
• Sending Messages
• Understanding Schemas
• Configuration Reference
• CLI Reference
• API Reference

---

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Development setup
• Coding guidelines
• Pull request process
• Documentation generation

Also review the Code of Conduct and Security Policy.

---

License

MIT