simplex-chat 0.2.1 → 6.5.0-beta.4

package/README.md

@@ -1,42 +1,89 @@
-# SimpleX Chat JavaScript client
+# SimpleX Chat Node.js library
 
-This is a TypeScript library that defines WebSocket API client for [SimpleX Chat terminal CLI](https://github.com/simplex-chat/simplex-chat/blob/stable/docs/CLI.md) that should be run as a WebSockets server on any port:
-
-```bash
-simplex-chat -p 5225
-```
-
-Client API 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.
-- create, join and manage group.
-- send and receive files.
+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 SimleX Chat users with each other.
+- 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
+## Quick start: a simple bot
+
+```
+npm i simplex-chat@6.5.0-beta.4
+```
+
+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")
+  const [chat, _user, _address] = await bot.run({
+    profile: {displayName: "Squaring bot example", fullName: ""},
+    dbOpts: {dbFilePrefix: "./squaring_bot", dbKey: ""},
+    options: {
+      addressSettings: {welcomeMessage: "If you send me a number, I will calculate its square."},
+    },
+    onMessage: async (ci, content) => {
+      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 cloned this repository, you can:
 
 ```
-npm i simplex-chat
+cd ./packages/simplex-chat-nodejs
+npm install
 npm run build
+node ./examples/squaring-bot-readme.js
 ```
 
-See the example of a simple chat bot in [squaring-bot.js](./examples/squaring-bot.js):
+There is an example with more options in [./examples/squaring-bot.ts](./examples/squaring-bot.ts).
 
-- start `simplex-chat` as a server on port 5225: `simplex-chat -p 5225 -d test_db`
-- run chatbot: `node examples/squaring-bot`
-- connect to chatbot via SimpleX Chat client using the address of the chat bot
+You can run it with: `npx ts-node ./examples/squaring-bot.ts`
 
 ## Documentation
 
-Please refer to the available client API in [client.ts](./src/client.ts).
+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
 

package/dist/api.d.ts

@@ -0,0 +1,371 @@
+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;
+}) => void | Promise<void>;
+export type EventSubscribers = {
+    [K in CEvt.Tag]?: EventSubscriberFunc<K>;
+};
+/**
+ * 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.
+     * @param {string} dbFilePrefix - File prefix for the database files.
+     * @param {string} [dbKey=""] - Database encryption key.
+     * @param {core.MigrationConfirmation} [confirm=core.MigrationConfirmation.YesUp] - Migration confirmation mode.
+     */
+    static init(dbFilePrefix: string, dbKey?: string, confirm?: core.MigrationConfirmation): Promise<ChatApi>;
+    /**
+     * Start chat controller. Must be called with the existing user profile.
+     */
+    startChat(): Promise<void>;
+    /**
+     * Stop chat controller.
+     * Must be called before closing the database.
+     * Usually doesn't need to be called in chat bots.
+     */
+    stopChat(): Promise<void>;
+    /**
+     * Close chat database.
+     * Usually doesn't need to be called in chat bots.
+     */
+    close(): Promise<void>;
+    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>;
+    /**
+     * 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.ChatItemDeletion[]>;
+    /**
+     * 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>;
+    /**
+     * 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[]>;
+    /**
+     * Delete chat.
+     * Network usage: background.
+     */
+    apiDeleteChat(chatType: T.ChatType, chatId: number, deleteMode?: T.ChatDeleteMode): Promise<void>;
+    /**
+     * 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>;
+}