love-protocol

💘 LOVE Protocol JS

Lucy Open Voice Exchange – Protocol Library (TypeScript)

This is the official TypeScript implementation of the LOVE Protocol, a modular and transport-agnostic messaging system for building conversational interfaces, voice assistants, and intelligent agents.

It provides message encoding/decoding, schema validation, handler routing, session management, and developer tooling.

---

📦 Installation

npm install love-protocol

---

🚀 Quickstart

🧠 Server Example

import { WebSocketServer } from "ws";
import { LoveHandler, MESSAGE_TYPES, encodeLoveMessage } from "love-protocol";

const wss = new WebSocketServer({ port: 12345 });
const handler = new LoveHandler();

handler.on(MESSAGE_TYPES.HELLO, (msg, { send }) => {
  send({
    protocol: "LOVE/1.0",
    type: MESSAGE_TYPES.HELLO_ACK,
    device_id: "server",
    timestamp: Date.now() / 1000,
  });
});

handler.onError((err, raw, { send }) => {
  send({
    protocol: "LOVE/1.0",
    type: MESSAGE_TYPES.ERROR,
    device_id: "server",
    timestamp: Date.now() / 1000,
    error: {
      message: err instanceof Error ? err.message : String(err),
    },
  });
});

wss.on("connection", (ws) => {
  ws.on("message", (data) => {
    handler.handle(data.toString(), {
      send: (msg) => ws.send(encodeLoveMessage(msg)),
    });
  });
});

---

🤖 Client Example

import WebSocket from "ws";
import { encodeLoveMessage, decodeLoveMessage, MESSAGE_TYPES } from "love-protocol";

const ws = new WebSocket("ws://localhost:12345");

ws.on("open", () => {
  ws.send(
    encodeLoveMessage({
      protocol: "LOVE/1.0",
      type: MESSAGE_TYPES.HELLO,
      device_id: "test-client",
      timestamp: Date.now() / 1000,
      capabilities: { mic: true, speaker: true },
    })
  );
});

ws.on("message", (data) => {
  const msg = decodeLoveMessage(data.toString());
  console.log("Received:", msg);
});

---

🧱 Features

• ✅ Fully typed message definitions with Zod
• ✅ Type-safe handler registration per message type
• ✅ Async middleware chain (use(fn))
• ✅ Session middleware with TTL support
• ✅ Transport-agnostic (WebSocket, TCP, MQTT, etc.)
• ✅ Works in Node.js, Browser & Edge runtimes

---

📚 API Documentation

Full developer reference available at:

👉 https://lucy-assistant.com/protocol/docs/love-protocol-js

Generated automatically via TypeDoc.

---

🛠 Dev Scripts

npm run test        # Run all unit tests
npm run generate    # Generate types from JSON Schemas
npm run docs        # Build static documentation with TypeDoc
npm run build       # Compile the library
npm run clean       # Optional: clean up dist and docs

---

📁 Project Structure

packages/love-protocol-js/
├── src/              # Core source code (handlers, types, middleware)
├── types/generated/  # Auto-generated Zod schemas
├── examples/         # WebSocket, TCP, MQTT examples
├── tests/            # Unit and integration tests
└── docs/             # TypeDoc-generated API documentation

---

📄 License

Apache-2.0
© 2025 Lucy Project – Made with ❤️ by Julian Amelung