simplex-chat/packages/simplex-chat-nodejs

SimpleX Chat Node.js library

This library replaced now deprecated SimpleX Chat WebRTC TypeScript client.

Use cases

• chat bots: you can implement any logic of connecting with and communicating with SimpleX Chat users. Using chat groups a chat bot can connect SimpleX Chat users with each other.
• control of the equipment: e.g. servers or home automation. SimpleX Chat provides secure and authorised connections, so this is more secure than using rest APIs.
• any scenarios of scripted message sending.
• chat and chat-based interfaces.

Please share your use cases and implementations.

Quick start: a simple bot

npm i simplex-chat@6.5.1

Simple bot that replies with squares of numbers you send to it:

(async () => {
  const {bot} = await import("simplex-chat")
  // if you are running from this GitHub repo:
  // const {bot} = await import("../dist/index.js")
  await bot.run({
    profile: {displayName: "Squaring bot example", fullName: ""},
    dbOpts: {type: "sqlite", filePrefix: "./squaring_bot"},
    options: {
      addressSettings: {welcomeMessage: "Send a number, I will square it.",
    },
    onMessage: async (ci, content, chat) => {
      const n = +content.text
      const reply = typeof n === "number" && !isNaN(n)
                    ? `${n} * ${n} = ${n * n}`
                    : `this is not a number`
      await chat.apiSendTextReply(ci, reply)
    }
  })
})()

If you installed this package as dependency, you can run this example with:

node ./node_modules/simplex-chat/examples/squaring-bot-readme.js

If you run it on Mac, the first time it will take 20-30 seconds for MacOS to verify the library.

If you cloned this repository, you can:

cd ./packages/simplex-chat-nodejs
npm install
npm run build
SIMPLEX_ADDON_PATH=build/Release/simplex.node node ./examples/squaring-bot-readme.js

Building the Node.js add-on from source needs node-gyp build tools.

There is an example with more options in ./examples/squaring-bot.ts.

You can run it with: npx ts-node ./examples/squaring-bot.ts

A larger example, with a business address and commands as keys: SimpleX Calculator.

Live messages

Live messages are shown to recipients while they are written, e.g. a streamed reply of a language model.

onMessage handler for bot.run that streams a reply:

const {api, util} = require("simplex-chat")

async function onMessage(ci, content, chat) {
  const {chatType, chatId} = util.chatInfoRef(ci.chatInfo)
  const live = new api.LiveMessage(chat, chatType, chatId)
  let text = ""
  for await (const delta of streamReply(content.text)) {
    text += delta
    live.update(text)
  }
  await live.end()
}

streamReply stands for your function that returns text fragments as an async iterable.

update sends the first text at once, and then updates the message at most once per 3 seconds (interval parameter). end finalizes the message; a message without text is deleted.

The underlying commands: apiSendMessages with liveMessage = true sends a live message, apiUpdateChatItem with liveMessage = true updates it, and with liveMessage = false finalizes it.

Native library

libsimplex and the prebuilt Node.js add-on are downloaded on first use into the user cache ($XDG_CACHE_HOME/simplex-chat or ~/.cache/simplex-chat on Linux, ~/Library/Caches/simplex-chat on macOS, %LOCALAPPDATA%\simplex-chat on Windows), shared with the Python library. To download them ahead of time, for example in a Dockerfile, run as the user that runs the app:

npx simplex-chat install                     # sqlite (default)
npx simplex-chat install --backend postgres  # Linux x86_64 only

Set SIMPLEX_LIBS_DIR to a directory with a local build of libsimplex and its dependencies to use it instead; it must be built for the backend in use. Set SIMPLEX_ADDON_PATH to a locally built add-on (build/Release/simplex.node) to use it instead of the downloaded one.

ChatApi.init loads the library for DbConfig.type; the low-level core functions require core.loadLibrary(backend) first.

PostgreSQL backend

DbConfig.type selects the backend; one backend per process.

• libpq5 must be installed on the host system (apt install libpq5 on Debian/Ubuntu)
• PostgreSQL backend is only available for Linux x86_64
• A PostgreSQL server accessible via connection string

// SQLite (default)
dbOpts: {type: "sqlite", filePrefix: "./data/bot"}
// optional: encryptionKey: "<sqlcipher-key>"

// PostgreSQL
dbOpts: {
  type: "postgres",
  connectionString: "postgres://user:pass@host/db",
  // schemaPrefix: "bot",  // optional — defaults to "simplex_v1"
}

Documentation

The library docs are here.

Library provides these modules:

• bot: a simple declarative API to run a chat-bot with a single function call. It automates creating and updating of the bot profile, address and bot commands shown in the app UI.
• api: an API to send chat commands and receive chat events to/from chat core. You need to use it in bot event handlers, and for any other use cases.
• core: a low level API to the core library - the same that is used in desktop clients. You are unlikely to ever need to use this module directly.
• util: useful functions for chat events and types.

This library uses @simplex-chat/types package with auto-generated bot API types.

Supported chat functions

Library provides types and functions to:

• create and change user profile (although, in most cases you can do it manually, via SimpleX Chat terminal app).
• create and accept invitations or connect with the contacts.
• create and manage long-term user address, accepting connection requests automatically.
• send, receive, delete and update messages, and add message reactions.
• send live messages, e.g. streamed replies.
• create, join and manage group.
• send and receive files.
• etc.

Tests

npm install
npm run build
npm test

To run one test file: npm test -- tests/core.test.ts.

A local SMP server is started for the API and bot tests. On Linux x86-64 and arm64, smp-server is downloaded from simplexmq releases to node_modules/.cache/smp-server. To use another build, or on other systems, set SMP_SERVER to the path of smp-server:

SMP_SERVER=/path/to/smp-server npm test

License

AGPL v3