simplex-chat 0.3.0 → 6.5.0-beta.10

package/dist/api.d.ts

@@ -0,0 +1,423 @@
+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>;
+};
+/**
+ * Database configuration. The native library is built against exactly one
+ * backend (see `simplex_backend` / `SIMPLEX_BACKEND` at install time); this
+ * type makes the caller state which one they are targeting so field names
+ * can't lie about their meaning.
+ */
+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.
+     * @param {DbConfig} db - Database configuration (sqlite or postgres).
+     * @param {core.MigrationConfirmation} [confirm=core.MigrationConfirmation.YesUp] - Migration confirmation mode.
+     */
+    static init(db: DbConfig, 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>;
+    /**
+     * 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>;
+}