Files
simplex-chat/packages/simplex-chat-nodejs
Evgeny @ SimpleX Chat 4eeddce11d core, ui: chatItemUpdated event has the previous item (#8219)
* core, ui: chatItemUpdated event has the previous item

Apps change counters by the difference between the previous and the new item, and insert an updated item only when the update created it.

* core, ui: a recreated item is sent as newChatItems

An update of a locally deleted message creates it again and sends it as a new item, so chatItemUpdated always has the previous item and the apps never insert on an update.

* core, ui: previous item is optional and has no chat info

Events from older remote hosts decode without it; the apps then insert the item if it is not loaded and change no counters.

* core: catch-up subscriber gets an edited history post as a new item

* ui: updates in another profile do not notify, as on iOS

* core, ui: one type for the updated item and its previous version

AChatItemUpdate has the chat info, the new item and the previous item with the same chat type and direction. Its JSON is the JSON of AChatItem with an optional prevChatItem; the event keeps the key chatItem.

* core: tested event key, previous item reactions, cleared mentions

One function renames the event field to chatItem for JSON and docs, and the test checks the wire key and compatibility with AChatItem. The previous item of a direct edit has its reactions. An edit that removes all mentions sends the item without them.

* core: test that an edit removing mentions sends the item without them

* core: event JSON field mapping inline in the TH options, for the Windows build

* core: file chat item update checked in one store transaction

* core: test that a file reset by unknown relays sends its previous item

* core, ui: chatItemUpdated event key chatItemUpdate

* core, ui: chatItemUpdated always has the previous item

* ci: mcp scope tests the plugin with its published dependencies

* core: mention of the user follows edits of a group message

* core: previous item of a prohibited file is read before the prohibition

* android, desktop: missed call check inline, counter test with core pairs

* ios: spec link of the chatItemUpdated event

* core: mention edits in support chats update members requiring attention

* core: one rule for the mention of the user in received and edited items

* core: record item events of updates for app tests

* android, desktop: remove the missed call notification of updates, never shown

* android, desktop: test item updates on events recorded by the core

* ios: test item updates on events recorded by the core

* docs: plan of app tests of item updates, recording tests in the CI guide

* core: record the response to an update after its item status is final

* ios: notification manager replaceable in tests

* ios: test notifications of updates and the update response

* android, desktop: test the recorded update response

* docs: plan with iOS notifications and the update response

* core: recorded response to an update of a sent message
2026-11-17 20:47:18 +00:00
..
2026-11-12 09:07:07 +00:00
2026-11-12 09:07:07 +00:00

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, except for image resizing.
  • 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