Files
simplex-chat/packages/simplex-chat-nodejs
533bfd8ff5 core, store: merge master into names (#8298)
* core, ui: validate short link type, show contact info for long addresses and rejected contacts (#8184)

* tests: short link type, QR code capacity and contact statuses

* core: validate the type of short links

* android, desktop: show contact info for addresses above QR code capacity

* ui: show chats with rejected contact requests

* tests: short link types with group, channel and contact data

* core: validate short link type against link data

* tests: fix short link data test

* tests: group data in invitation link before its first use

* tests: connect via address in contact profile with group link

* core: connect via contact address only with address links

* core: parse short link data once, by link type

* core: types of short link data parser

* core: test short link types and contact rejection, record app fixtures

* android, desktop: test contact info, link alerts and rejected contacts

* ios: test invalid link alerts and rejected contacts in the chat list

* desktop: contact info tests find texts without app resources

* ui: core responses of invalid link plans and a rejected contact request

* desktop: contact info tests provide the app bar handler

* core: normalise file and message keys in app test fixtures

* core: normalise deletion times in app test fixtures

* desktop: test that a QR code above capacity is not shared on tap

* core: test relay link checks and known channel refresh from link data

* libs: nodejs 7.1.4 (#8263)

* nodejs: live test reads the updated item under the key of 7.1 and 7.2 cores

* libs: nodejs 7.1.4

* mcp: session states coloured by what they need, green for working (#8265)

* mcp: session states in the colours of what they need: green working, orange waiting in the chat, red idle

* mcp: the space after waiting for you in the tests

* mcp: a session with a background command shows working in the background

* mcp: a readable README, and the roadmap lines of 0.3.0 (#8264)

* mcp: readme by what the plugin does for its users, roadmap lines of 0.3.0

* mcp: almost every waiting state

* mcp: reply, edit and react in one line

* mcp: flat layout without the avatar note

* mcp: sessions use flat layout

* mcp: shorter lines on answers, the Main group and approvals

* mcp: approvals line without the taps

* mcp: live stream line

* mcp: status line

* mcp: shorter lines

* mcp: 0.3.1 with simplex-chat 7.1.4 (#8266)

* docs: testing approaches of the codebase (#8255)

* docs: app changes come with app tests on the core's recorded responses (#8252)

* ci: decide the library claim from the written releases (#8137)

* ci: test the library claim when reads return the previous releases

* ci: decide the library claim from the written releases

* tests: record name fixtures after the channel join settles (#8250)

* core, ci: update sqlcipher-simple to 0.4.19.0 and simplexmq (#8270)

* update sqlcipher-simple to 0.4.19.0

* sqlcipher-simple from simplex-chat/sqlcipher-simple

* update simplexmq

* ci: restore source repositories only for the same cabal.project

* ci: keep restored source checkouts only at their pinned commits

* android, desktop, ios: copy markdown files with line breaks, and the whole file with one button (#8269)

* android, desktop: test copying lines from the markdown text view

* android, desktop: keep line breaks in text copied from markdown files

* android, desktop: check the last copied text in the markdown view test

* android, desktop, ios: button to copy the whole markdown file

* android, desktop: test the markdown file copy button

* android, desktop, ios: ask before copying markdown files over 128 KB

* android, desktop, ios: title the markdown copy alerts File too large

* ios: test the markdown file copy button

* android, desktop, ios: preview the markdown file view and test the copy limit

* android, desktop, ios: snapshot references of the markdown file view

* docs: names conditions describe upgradeable registry contracts (#8277)

* docs: names conditions describe upgradeable registry contracts

* docs: names conditions without the immutability after stabilization

---------

Co-authored-by: brenzi-agent <346870783+brenzi-agent@users.noreply.github.com>

* ci: reproducible Linux builds of 7.1 releases (#8276)

* ci: plan reproducible Linux builds of 7.1 releases

* ci: reproduce Linux builds with the cabal store path of releases

* ci: reproduce releases with the current reproduce script

* ci: build in the image with the cabal directory of releases

* ci: reproduce releases on the Ubuntu 24.04 runner

* ci: correct the failure history and rollout in the plan

---------

Co-authored-by: sh-agents <350651734+sh-agents@users.noreply.github.com>

* website: remove the webinar promotion (#8281)

* website: remove the webinar invitation from the home page

* website: redirect the livestream page to Wefunder

* mcp server: recall the chat history in a new agent session (#8141)

* mcp server: recall the chat history in a new agent session

* docs: chat history in receive for a new agent session

* mcp server: type the history page for the compiler

* mcp server: recall the chat history after a compaction too

* docs: history plan changes with the message helpers of master

Claude-Session: https://claude.ai/code/session_01AV2VpomCCQNciqggT9gr75

* docs: drop anchor remapping from the docs table of the history plan

Claude-Session: https://claude.ai/code/session_01AV2VpomCCQNciqggT9gr75

---------

Co-authored-by: brenzi-agent <346870783+brenzi-agent@users.noreply.github.com>

* core: prevent stalled join of channel subscribers to a new relay (#8239)

* core: save relay connection before requesting relay link data

* core: share relay connection creation between join and retry

* tests: connect to a re-added relay when its connection is saved late

* tests: delay only the relay connection record, not the command

* ci, tests: run all tests in CI (#8238)

* bots, tests: run broadcast bot test in CI

* tests: test moderation that arrives before the message

* ci, tests: run all tests in CI

* tests: update re-enabled tests, restore query plans, PostgreSQL schema from CI

* tests: remove CI skip helpers no longer used

* tests: expect XFTP AUTH error of cancelled standalone file

* tests: update query plans from CI

* tests: update query plans from CI

* tests: expect group history and member contacts in async group test

* tests: accept subscription summary after first events on restart

* tests: make AUTH and client timeout direct tests deterministic

* tests: keep bob's badge clock before renewal until the move back

* tests: keep the quota of 2 messages only on the member's receive queue

* tests: keep query plans files with repeated entries of one query

* tests: update query plans from CI

* tests: stop the host before a member requests to join with a badge

* tests: remove repeated entries of one query from query plans files

* tests: accept the refusal of an unknown remote host after its session code

* ci: state when the query plans test fails

* tests: skip multicast discovery on macOS CI runners

* tests: accept a remote host started with one local address

* tests: restore the client timeout test except its zero timeout

* tests: fail when a remote host prints another line than its other addresses

* ci: name the tests that overwrite generated files

* tests: move the badge clock after the restoring device arms its wake

* tests: keep both members on the quota server in the member inactivity test

* tests: accept subscription summaries in any order in the async group test

* tests: update query plans from CI

* tests: quota of 2 only on bob's queues in member inactivity test

* tests: connect to a deleted link after its queue is deleted

* core: save relay connection before requesting relay link data

* core: share relay connection creation between join and retry

* tests: connect to a re-added relay when its connection is saved late

* tests: delay only the relay connection record, not the command

* tests: record API fixtures on SQLite only

* core: update query plans

* ci: run PostgreSQL tests with the steps of build-linux

* desktop: prevent crash on Linux with bitmap and WOFF2 fallback fonts (#8288)

* desktop: prevent crash on Linux with bitmap and WOFF2 fallback fonts

* desktop: record time offsets and snapshots rendered with Skia m138

* desktop: name the time offset test, skip only a missing fc-cache, update plan

---------

Co-authored-by: sh-agents <350651734+sh-agents@users.noreply.github.com>

* core, directory: stop cancelled actions instead of continuing them (#8279)

* ci: retry npm install once after a failure (#8280)

* core: query plans of the store group tests that master now verifies

---------

Co-authored-by: brenzi-agent <346870783+brenzi-agent@users.noreply.github.com>
Co-authored-by: sh-agents <justcheckingifitwillwork@gmail.com>
Co-authored-by: sh-agents <350651734+sh-agents@users.noreply.github.com>
Co-authored-by: brenzi-agent <brenzi-agent@brenzi.ch>
Co-authored-by: Evgeny Poberezkin <evgeny@poberezkin.com>
2026-11-21 23:35:25 +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