simplex-chat/packages/simplex-chat-nodejs/README.md

# SimpleX Chat Node.js library

This library replaced now deprecated [SimpleX Chat WebRTC TypeScript client](https://www.npmjs.com/package/@simplex-chat/webrtc-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:

```javascript
(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:

```sh
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](https://github.com/nodejs/node-gyp) build tools.

There is an example with more options in [./examples/squaring-bot.ts](./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](../../apps/simplex-calculator-bot/).

## 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:

```javascript
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:

```bash
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

```ts
// 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](./docs/README.md).

Library provides these modules:
- [bot](./docs/Namespace.bot.md): 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](./docs/Namespace.api.md): 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](./docs/Namespace.core.md): 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](./docs/Namespace.util.md): useful functions for chat events and types.


This library uses [@simplex-chat/types](https://www.npmjs.com/package/@simplex-chat/types) package with auto-generated [bot API types](../../bots/api/README.md).

## 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

```sh
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](https://github.com/simplex-chat/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`:

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

## License

[AGPL v3](./LICENSE)