@shhhum/simplex-chat 0.0.0-stage → 7.1.0-beta.6.2

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# 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/).
+
+## 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.
+- create, join and manage group.
+- send and receive files.
+- etc.
+
+## License
+
+[AGPL v3](./LICENSE)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/dist/api.d.ts

@@ -0,0 +1,439 @@
+import { CEvt, ChatEvent, ChatResponse, T } from "@simplex-chat/types";
+import * as core from "./core";
+export declare class ChatCommandError extends Error {
+    message: string;
+    response: ChatResponse;
+    constructor(message: string, response: ChatResponse);
+}
+/**
+ * Connection request types.
+ * @enum {string}
+ */
+export declare enum ConnReqType {
+    Invitation = "invitation",
+    Contact = "contact"
+}
+/**
+ * Bot address settings.
+ */
+export interface BotAddressSettings {
+    /**
+     * Automatically accept contact requests.
+     * @default true
+     */
+    autoAccept?: boolean;
+    /**
+     * Optional welcome message to show before connection to the users.
+     * @default undefined (no welcome message)
+     */
+    welcomeMessage?: T.MsgContent | string | undefined;
+    /**
+     * Business contact address.
+     * For all requests business chats will be created where other participants can be added.
+     * @default false
+     */
+    businessAddress?: boolean;
+}
+export declare const defaultBotAddressSettings: BotAddressSettings;
+export type EventSubscriberFunc<K extends CEvt.Tag> = (event: ChatEvent & {
+    type: K;
+}, chat: ChatApi) => void | Promise<void>;
+export type EventSubscribers = {
+    [K in CEvt.Tag]?: EventSubscriberFunc<K>;
+};
+/**
+ * Database configuration. `type` selects the libsimplex backend loaded by
+ * `ChatApi.init`; one backend per process.
+ */
+export type DbConfig = {
+    /** SQLite backend (default). */
+    type: "sqlite";
+    /** File prefix — two schema files are named `<prefix>_chat.db` and `<prefix>_agent.db`. */
+    filePrefix: string;
+    /** Optional SQLCipher encryption key. Empty/omitted = unencrypted. */
+    encryptionKey?: string;
+} | {
+    /** PostgreSQL backend (Linux x86_64 only, libpq5 required). */
+    type: "postgres";
+    /** Schema prefix used to namespace tables. Defaults to `"simplex_v1"` when omitted. */
+    schemaPrefix?: string;
+    /** PostgreSQL connection string (e.g. `postgres://user:pass@host/db`). */
+    connectionString: string;
+};
+/**
+ * Main API class for interacting with the chat core library.
+ */
+export declare class ChatApi {
+    protected ctrl_: bigint | undefined;
+    private receiveEvents;
+    private eventsLoop;
+    private subscribers;
+    private receivers;
+    private constructor();
+    /**
+     * Initializes the ChatApi, loading libsimplex for `db.type` (downloaded on first use).
+     * @param {DbConfig} db - Database configuration (sqlite or postgres).
+     * @param {core.MigrationConfirmation} [confirm=core.MigrationConfirmation.YesUp] - Migration confirmation mode.
+     * @param {number} [queueSize] - Size of internal queues, the core default is used when omitted.
+     */
+    static init(db: DbConfig, confirm?: core.MigrationConfirmation, queueSize?: number): Promise<ChatApi>;
+    /**
+     * Start chat controller. Must be called with the existing user profile.
+     */
+    startChat(): Promise<void>;
+    /**
+     * Stop chat controller.
+     * `close` calls it before closing the database.
+     * Usually doesn't need to be called in chat bots.
+     */
+    stopChat(): Promise<void>;
+    /**
+     * Stop chat controller and close chat database.
+     * The database is not closed if stopping fails.
+     * Usually doesn't need to be called in chat bots.
+     */
+    close(): Promise<void>;
+    private stopEventsLoop;
+    private runEventsLoop;
+    /**
+     * Subscribe multiple event handlers at once.
+     * @param subscribers - An object mapping event types (CEvt.Tag) to their subscriber functions.
+     * @throws {Error} If the same function is subscribed to event.
+     */
+    on<K extends CEvt.Tag>(subscribers: EventSubscribers): void;
+    /**
+     * Subscribe a handler to a specific event.
+     * @param {CEvt.Tag} event - The event type to subscribe to.
+     * @param subscriber - The subscriber function for the event.
+     * @throws {Error} If the same function is subscribed to event.
+     */
+    on<K extends CEvt.Tag>(event: K, subscriber: EventSubscriberFunc<K>): void;
+    private on_;
+    /**
+     * Subscribe a handler to any event.
+     * @param receiver - The receiver function for any event.
+     * @throws {Error} If the same function is subscribed to event.
+     */
+    onAny(receiver: EventSubscriberFunc<CEvt.Tag>): void;
+    /**
+     * Subscribe a handler to a specific event to be delivered one time.
+     * @param {CEvt.Tag} event - The event type to subscribe to.
+     * @param subscriber - The subscriber function for the event.
+     * @throws {Error} If the same function is subscribed to event.
+     */
+    once<K extends CEvt.Tag>(event: K, subscriber: EventSubscriberFunc<K>): void;
+    /**
+     * Waits for specific event, with an optional predicate.
+     * Returns `undefined` on timeout if specified.
+     */
+    wait<K extends CEvt.Tag>(event: K): Promise<ChatEvent & {
+        type: K;
+    }>;
+    wait<K extends CEvt.Tag>(event: K, predicate: ((event: ChatEvent & {
+        type: K;
+    }) => boolean) | undefined): Promise<ChatEvent & {
+        type: K;
+    }>;
+    wait<K extends CEvt.Tag>(event: K, timeout: number): Promise<ChatEvent & {
+        type: K;
+    } | undefined>;
+    wait<K extends CEvt.Tag>(event: K, predicate: ((event: ChatEvent & {
+        type: K;
+    }) => boolean) | undefined, timeout: number): Promise<ChatEvent & {
+        type: K;
+    } | undefined>;
+    /**
+     * Unsubscribe all or a specific handler from a specific event.
+     * @param {CEvt.Tag} event - The event type to unsubscribe from.
+     * @param subscriber - An optional subscriber function for the event.
+     */
+    off<K extends CEvt.Tag>(event: K, subscriber?: EventSubscriberFunc<K> | undefined): void;
+    /**
+     * Unsubscribe all or a specific handler from any events.
+     * @param receiver - An optional subscriber function for the event.
+     */
+    offAny(receiver?: EventSubscriberFunc<CEvt.Tag> | undefined): void;
+    /**
+     * Chat controller is initialized
+     */
+    get initialized(): boolean;
+    /**
+     * Chat controller is started
+     */
+    get started(): boolean;
+    /**
+     * Chat controller reference
+     */
+    get ctrl(): bigint;
+    sendChatCmd(cmd: string): Promise<ChatResponse>;
+    recvChatEvent(wait?: number): Promise<ChatEvent | undefined>;
+    /**
+     * Create bot address.
+     * Network usage: interactive.
+     */
+    apiCreateUserAddress(userId: number): Promise<T.CreatedConnLink>;
+    /**
+     * Deletes a user address.
+     * Network usage: background.
+     */
+    apiDeleteUserAddress(userId: number): Promise<void>;
+    /**
+     * Get bot address and settings.
+     * Network usage: no.
+     */
+    apiGetUserAddress(userId: number): Promise<T.UserContactLink | undefined>;
+    /**
+     * Add address to bot profile.
+     * Network usage: interactive.
+     */
+    apiSetProfileAddress(userId: number, enable: boolean): Promise<T.UserProfileUpdateSummary>;
+    /**
+     * Set bot address settings.
+     * Network usage: interactive.
+     */
+    apiSetAddressSettings(userId: number, { autoAccept, welcomeMessage, businessAddress }: BotAddressSettings): Promise<void>;
+    apiSetUserDomain(userId: number, simplexDomain?: string): Promise<T.User>;
+    /**
+     * Send messages.
+     * Network usage: background.
+     */
+    apiSendMessages(chat: [T.ChatType, number] | T.ChatRef | T.ChatInfo, messages: T.ComposedMessage[], liveMessage?: boolean): Promise<T.AChatItem[]>;
+    /**
+     * Send text message.
+     * Network usage: background.
+     */
+    apiSendTextMessage(chat: [T.ChatType, number] | T.ChatRef | T.ChatInfo, text: string, inReplyTo?: number): Promise<T.AChatItem[]>;
+    /**
+     * Send text message in reply to received message.
+     * Network usage: background.
+     */
+    apiSendTextReply(chatItem: T.AChatItem, text: string): Promise<T.AChatItem[]>;
+    /**
+     * Update message.
+     * Network usage: background.
+     */
+    apiUpdateChatItem(chatType: T.ChatType, chatId: number, chatItemId: number, msgContent: T.MsgContent, liveMessage: false): Promise<T.ChatItem>;
+    /**
+     * Delete message.
+     * Network usage: background.
+     */
+    apiDeleteChatItems(chatType: T.ChatType, chatId: number, chatItemIds: number[], deleteMode: T.CIDeleteMode): Promise<T.ChatItemDeletion[]>;
+    /**
+     * Moderate message. Requires Moderator role (and higher than message author's).
+     * Network usage: background.
+     */
+    apiDeleteMemberChatItem(groupId: number, chatItemIds: number[]): Promise<T.ChatItemDeletion[]>;
+    /**
+     * Add/remove message reaction.
+     * Network usage: background.
+     */
+    apiChatItemReaction(chatType: T.ChatType, chatId: number, chatItemId: number, add: boolean, reaction: T.MsgReaction): Promise<T.ACIReaction>;
+    /**
+     * Receive file.
+     * Network usage: no.
+     */
+    apiReceiveFile(fileId: number): Promise<T.AChatItem>;
+    /**
+     * Cancel file.
+     * Network usage: background.
+     */
+    apiCancelFile(fileId: number): Promise<void>;
+    /**
+     * Add contact to group. Requires bot to have Admin role.
+     * Network usage: interactive.
+     */
+    apiAddMember(groupId: number, contactId: number, memberRole: T.GroupMemberRole): Promise<T.GroupMember>;
+    /**
+     * Add member of another group to group. Requires bot to have Admin role in the group, and direct messages allowed for its role in another group.
+     * Network usage: interactive.
+     */
+    apiAddMemberViaGroup(groupId: number, viaGroupId: number, groupMemberId: number, memberRole: T.GroupMemberRole): Promise<T.GroupMember>;
+    /**
+     * Join group.
+     * Network usage: interactive.
+     */
+    apiJoinGroup(groupId: number): Promise<T.GroupInfo>;
+    /**
+     * Accept group member. Requires Admin role.
+     * Network usage: background.
+     */
+    apiAcceptMember(groupId: number, groupMemberId: number, memberRole: T.GroupMemberRole): Promise<T.GroupMember>;
+    /**
+     * Set members role. Requires Admin role.
+     * Network usage: background.
+     */
+    apiSetMembersRole(groupId: number, groupMemberIds: number[], memberRole: T.GroupMemberRole): Promise<void>;
+    /**
+     * Block members. Requires Moderator role.
+     * Network usage: background.
+     */
+    apiBlockMembersForAll(groupId: number, groupMemberIds: number[], blocked: boolean): Promise<void>;
+    /**
+     * Remove members. Requires Admin role.
+     * Network usage: background.
+     */
+    apiRemoveMembers(groupId: number, memberIds: number[], withMessages?: boolean): Promise<T.GroupMember[]>;
+    /**
+     * Leave group.
+     * Network usage: background.
+     */
+    apiLeaveGroup(groupId: number): Promise<T.GroupInfo>;
+    /**
+     * Get group members.
+     * Network usage: no.
+     */
+    apiListMembers(groupId: number): Promise<T.GroupMember[]>;
+    /**
+     * Create group.
+     * Network usage: no.
+     */
+    apiNewGroup(userId: number, groupProfile: T.GroupProfile): Promise<T.GroupInfo>;
+    /**
+     * Update group profile.
+     * Network usage: background.
+     */
+    apiUpdateGroupProfile(groupId: number, groupProfile: T.GroupProfile): Promise<T.GroupInfo>;
+    /**
+     * Create group link.
+     * Network usage: interactive.
+     */
+    apiCreateGroupLink(groupId: number, memberRole: T.GroupMemberRole): Promise<string>;
+    /**
+     * Set member role for group link.
+     * Network usage: no.
+     */
+    apiSetGroupLinkMemberRole(groupId: number, memberRole: T.GroupMemberRole): Promise<void>;
+    /**
+     * Delete group link.
+     * Network usage: background.
+     */
+    apiDeleteGroupLink(groupId: number): Promise<void>;
+    /**
+     * Get group link.
+     * Network usage: no.
+     */
+    apiGetGroupLink(groupId: number): Promise<T.GroupLink>;
+    apiGetGroupLinkStr(groupId: number): Promise<string>;
+    /**
+     * Create 1-time invitation link.
+     * Network usage: interactive.
+     */
+    apiCreateLink(userId: number): Promise<string>;
+    /**
+     * Determine SimpleX link type and if the bot is already connected via this link.
+     * Network usage: interactive.
+     */
+    apiConnectPlan(userId: number, connectionLink: string): Promise<[T.ConnectionPlan, T.CreatedConnLink]>;
+    /**
+     * Connect via prepared SimpleX link. The link can be 1-time invitation link, contact address or group link
+     * Network usage: interactive.
+     */
+    apiConnect(userId: number, incognito: boolean, preparedLink: T.CreatedConnLink): Promise<ConnReqType>;
+    /**
+     * Connect via SimpleX link as string in the active user profile.
+     * Network usage: interactive.
+     */
+    apiConnectActiveUser(connLink: string): Promise<ConnReqType>;
+    private handleConnectResult;
+    /**
+     * Accept contact request.
+     * Network usage: interactive.
+     */
+    apiAcceptContactRequest(contactReqId: number): Promise<T.Contact>;
+    /**
+     * Reject contact request. The user who sent the request is **not notified**.
+     * Network usage: no.
+     */
+    apiRejectContactRequest(contactReqId: number): Promise<void>;
+    /**
+     * Get contacts.
+     * Network usage: no.
+     */
+    apiListContacts(userId: number): Promise<T.Contact[]>;
+    /**
+     * Get groups.
+     * Network usage: no.
+     */
+    apiListGroups(userId: number, contactId?: number, search?: string): Promise<T.GroupInfo[]>;
+    /**
+     * Get chat previews (paginated).
+     * Network usage: no.
+     *
+     * Prefer this over apiListContacts / apiListGroups for any scan: those
+     * methods load every record into memory in a single response and will fail
+     * on large databases.
+     */
+    apiGetChats(userId: number, pagination: T.PaginationByTime, query?: T.ChatListQuery, pendingConnections?: boolean): Promise<T.AChat[]>;
+    /**
+     * Delete chat.
+     * Network usage: background.
+     */
+    apiDeleteChat(chatType: T.ChatType, chatId: number, deleteMode?: T.ChatDeleteMode): Promise<void>;
+    /**
+     * Set group custom data.
+     * Network usage: no.
+     */
+    apiSetGroupCustomData(groupId: number, customData?: object): Promise<void>;
+    /**
+     * Set contact custom data.
+     * Network usage: no.
+     */
+    apiSetContactCustomData(contactId: number, customData?: object): Promise<void>;
+    /**
+     * Set auto-accept member contacts.
+     * Network usage: no.
+     */
+    apiSetAutoAcceptMemberContacts(userId: number, onOff: boolean): Promise<void>;
+    /**
+     * Get chat items.
+     * Network usage: no.
+     */
+    apiGetChat(chatType: T.ChatType, chatId: number, count: number): Promise<any>;
+    /**
+     * Get active user profile
+     * Network usage: no.
+     */
+    apiGetActiveUser(): Promise<T.User | undefined>;
+    /**
+     * Create new user profile
+     * Network usage: no.
+     */
+    apiCreateActiveUser(profile?: T.Profile): Promise<T.User>;
+    /**
+     * Get all user profiles
+     * Network usage: no.
+     */
+    apiListUsers(): Promise<T.UserInfo[]>;
+    /**
+     * Set active user profile
+     * Network usage: no.
+     */
+    apiSetActiveUser(userId: number, viewPwd?: string): Promise<T.User>;
+    /**
+     * Delete user profile.
+     * Network usage: background.
+     */
+    apiDeleteUser(userId: number, delSMPQueues: boolean, viewPwd?: string): Promise<void>;
+    /**
+     * Update user profile.
+     * Network usage: background.
+     */
+    apiUpdateProfile(userId: number, profile: T.Profile): Promise<T.UserProfileUpdateSummary | undefined>;
+    /**
+     * Configure chat preference overrides for the contact.
+     * Network usage: background.
+     */
+    apiSetContactPrefs(contactId: number, preferences: T.Preferences): Promise<void>;
+    /**
+     * Create a direct message contact with a group member.
+     * Returns the created contact.
+     * Network usage: interactive.
+     */
+    apiCreateMemberContact(groupId: number, groupMemberId: number): Promise<T.Contact>;
+    /**
+     * Send a direct message invitation to a group member contact.
+     * The contact must have been created with {@link apiCreateMemberContact}.
+     * Network usage: interactive.
+     */
+    apiSendMemberContactInvitation(contactId: number, message?: T.MsgContent | string): Promise<T.Contact>;
+}