sh
c8f20bcc91
* core: add chat_migrate_init_queue FFI export * bots: fix BadgeServiceErrorCode API type * nodejs: pass required command fields * nodejs: fix migration error types * nodejs: install libsimplex from SIMPLEX_LIBS_DIR * nodejs: add queue size option * nodejs: regenerate docs * python: add queue size option * bots: pass incognito in APIConnect * nodejs: accept documented success responses * python: accept documented success responses * nodejs: dispatch each bot message once * nodejs: fix startChat events loop lifecycle * nodejs, python: parse multi-line bot commands * nodejs: fix file buffer handling in addon * nodejs: keep events loop when chat stop fails * python: fix send_and_wait race, load lib off loop * python: make queue size export optional * nodejs: receive events on a dedicated thread * nodejs: release haskell thread after receive * python: receive on a dedicated thread per chat * python: test receive shutdown order * nodejs: one receive thread per chat controller * nodejs: harden receiver shutdown and tests * nodejs: stop chat before closing store * python: stop chat before closing store * nodejs, python: harden close regression and retry * python: free results with ucrt on windows * nodejs: enable c++ exceptions on mac and windows
24 KiB
simplex-chat / api / ChatApi
Class: ChatApi
Defined in: src/api.ts:97
Main API class for interacting with the chat core library.
Properties
ctrl_
protectedctrl_:bigint|undefined
Defined in: src/api.ts:103
Accessors
ctrl
Get Signature
get ctrl():
bigint
Defined in: src/api.ts:344
Chat controller reference
Returns
bigint
initialized
Get Signature
get initialized():
boolean
Defined in: src/api.ts:330
Chat controller is initialized
Returns
boolean
started
Get Signature
get started():
boolean
Defined in: src/api.ts:337
Chat controller is started
Returns
boolean
Methods
apiAcceptContactRequest()
apiAcceptContactRequest(
contactReqId):Promise<Contact>
Defined in: src/api.ts:750
Accept contact request. Network usage: interactive.
Parameters
contactReqId
number
Returns
Promise<Contact>
apiAcceptMember()
apiAcceptMember(
groupId,groupMemberId,memberRole):Promise<GroupMember>
Defined in: src/api.ts:570
Accept group member. Requires Admin role. Network usage: background.
Parameters
groupId
number
groupMemberId
number
memberRole
GroupMemberRole
Returns
Promise<GroupMember>
apiAddMember()
apiAddMember(
groupId,contactId,memberRole):Promise<GroupMember>
Defined in: src/api.ts:550
Add contact to group. Requires bot to have Admin role. Network usage: interactive.
Parameters
groupId
number
contactId
number
memberRole
GroupMemberRole
Returns
Promise<GroupMember>
apiBlockMembersForAll()
apiBlockMembersForAll(
groupId,groupMemberIds,blocked):Promise<void>
Defined in: src/api.ts:590
Block members. Requires Moderator role. Network usage: background.
Parameters
groupId
number
groupMemberIds
number[]
blocked
boolean
Returns
Promise<void>
apiCancelFile()
apiCancelFile(
fileId):Promise<void>
Defined in: src/api.ts:540
Cancel file. Network usage: background.
Parameters
fileId
number
Returns
Promise<void>
apiChatItemReaction()
apiChatItemReaction(
chatType,chatId,chatItemId,add,reaction):Promise<ACIReaction>
Defined in: src/api.ts:513
Add/remove message reaction. Network usage: background.
Parameters
chatType
ChatType
chatId
number
chatItemId
number
add
boolean
reaction
MsgReaction
Returns
Promise<ACIReaction>
apiConnect()
apiConnect(
userId,incognito,preparedLink):Promise<ConnReqType>
Defined in: src/api.ts:719
Connect via prepared SimpleX link. The link can be 1-time invitation link, contact address or group link Network usage: interactive.
Parameters
userId
number
incognito
boolean
preparedLink
CreatedConnLink
Returns
Promise<ConnReqType>
apiConnectActiveUser()
apiConnectActiveUser(
connLink):Promise<ConnReqType>
Defined in: src/api.ts:728
Connect via SimpleX link as string in the active user profile. Network usage: interactive.
Parameters
connLink
string
Returns
Promise<ConnReqType>
apiConnectPlan()
apiConnectPlan(
userId,connectionLink):Promise<[ConnectionPlan,CreatedConnLink]>
Defined in: src/api.ts:709
Determine SimpleX link type and if the bot is already connected via this link. Network usage: interactive.
Parameters
userId
number
connectionLink
string
Returns
Promise<[ConnectionPlan, CreatedConnLink]>
apiCreateActiveUser()
apiCreateActiveUser(
profile?):Promise<User>
Defined in: src/api.ts:887
Create new user profile Network usage: no.
Parameters
profile?
Profile
Returns
Promise<User>
apiCreateGroupLink()
apiCreateGroupLink(
groupId,memberRole):Promise<string>
Defined in: src/api.ts:650
Create group link. Network usage: interactive.
Parameters
groupId
number
memberRole
GroupMemberRole
Returns
Promise<string>
apiCreateLink()
apiCreateLink(
userId):Promise<string>
Defined in: src/api.ts:696
Create 1-time invitation link. Network usage: interactive.
Parameters
userId
number
Returns
Promise<string>
apiCreateMemberContact()
apiCreateMemberContact(
groupId,groupMemberId):Promise<Contact>
Defined in: src/api.ts:953
Create a direct message contact with a group member. Returns the created contact. Network usage: interactive.
Parameters
groupId
number
groupMemberId
number
Returns
Promise<Contact>
apiCreateUserAddress()
apiCreateUserAddress(
userId):Promise<CreatedConnLink>
Defined in: src/api.ts:361
Create bot address. Network usage: interactive.
Parameters
userId
number
Returns
Promise<CreatedConnLink>
apiDeleteChat()
apiDeleteChat(
chatType,chatId,deleteMode?):Promise<void>
Defined in: src/api.ts:809
Delete chat. Network usage: background.
Parameters
chatType
ChatType
chatId
number
deleteMode?
ChatDeleteMode = ...
Returns
Promise<void>
apiDeleteChatItems()
apiDeleteChatItems(
chatType,chatId,chatItemIds,deleteMode):Promise<ChatItemDeletion[]>
Defined in: src/api.ts:488
Delete message. Network usage: background.
Parameters
chatType
ChatType
chatId
number
chatItemIds
number[]
deleteMode
CIDeleteMode
Returns
Promise<ChatItemDeletion[]>
apiDeleteGroupLink()
apiDeleteGroupLink(
groupId):Promise<void>
Defined in: src/api.ts:672
Delete group link. Network usage: background.
Parameters
groupId
number
Returns
Promise<void>
apiDeleteMemberChatItem()
apiDeleteMemberChatItem(
groupId,chatItemIds):Promise<ChatItemDeletion[]>
Defined in: src/api.ts:503
Moderate message. Requires Moderator role (and higher than message author's). Network usage: background.
Parameters
groupId
number
chatItemIds
number[]
Returns
Promise<ChatItemDeletion[]>
apiDeleteUser()
apiDeleteUser(
userId,delSMPQueues,viewPwd?):Promise<void>
Defined in: src/api.ts:917
Delete user profile. Network usage: background.
Parameters
userId
number
delSMPQueues
boolean
viewPwd?
string
Returns
Promise<void>
apiDeleteUserAddress()
apiDeleteUserAddress(
userId):Promise<void>
Defined in: src/api.ts:371
Deletes a user address. Network usage: background.
Parameters
userId
number
Returns
Promise<void>
apiGetActiveUser()
apiGetActiveUser():
Promise<User|undefined>
Defined in: src/api.ts:867
Get active user profile Network usage: no.
Returns
Promise<User | undefined>
apiGetChat()
apiGetChat(
chatType,chatId,count):Promise<any>
Defined in: src/api.ts:857
Get chat items. Network usage: no.
Parameters
chatType
ChatType
chatId
number
count
number
Returns
Promise<any>
apiGetChats()
apiGetChats(
userId,pagination,query?,pendingConnections?):Promise<AChat[]>
Defined in: src/api.ts:794
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.
Parameters
userId
number
pagination
Last
query?
ChatListQuery = ...
pendingConnections?
boolean = false
Returns
Promise<AChat[]>
apiGetGroupLink()
apiGetGroupLink(
groupId):Promise<GroupLink>
Defined in: src/api.ts:681
Get group link. Network usage: no.
Parameters
groupId
number
Returns
Promise<GroupLink>
apiGetGroupLinkStr()
apiGetGroupLinkStr(
groupId):Promise<string>
Defined in: src/api.ts:687
Parameters
groupId
number
Returns
Promise<string>
apiGetUserAddress()
apiGetUserAddress(
userId):Promise<UserContactLink|undefined>
Defined in: src/api.ts:381
Get bot address and settings. Network usage: no.
Parameters
userId
number
Returns
Promise<UserContactLink | undefined>
apiJoinGroup()
apiJoinGroup(
groupId):Promise<GroupInfo>
Defined in: src/api.ts:560
Join group. Network usage: interactive.
Parameters
groupId
number
Returns
Promise<GroupInfo>
apiLeaveGroup()
apiLeaveGroup(
groupId):Promise<GroupInfo>
Defined in: src/api.ts:610
Leave group. Network usage: background.
Parameters
groupId
number
Returns
Promise<GroupInfo>
apiListContacts()
apiListContacts(
userId):Promise<Contact[]>
Defined in: src/api.ts:770
Get contacts. Network usage: no.
Parameters
userId
number
Returns
Promise<Contact[]>
apiListGroups()
apiListGroups(
userId,contactId?,search?):Promise<GroupInfo[]>
Defined in: src/api.ts:780
Get groups. Network usage: no.
Parameters
userId
number
contactId?
number
search?
string
Returns
Promise<GroupInfo[]>
apiListMembers()
apiListMembers(
groupId):Promise<GroupMember[]>
Defined in: src/api.ts:620
Get group members. Network usage: no.
Parameters
groupId
number
Returns
Promise<GroupMember[]>
apiListUsers()
apiListUsers():
Promise<UserInfo[]>
Defined in: src/api.ts:897
Get all user profiles Network usage: no.
Returns
Promise<UserInfo[]>
apiNewGroup()
apiNewGroup(
userId,groupProfile):Promise<GroupInfo>
Defined in: src/api.ts:630
Create group. Network usage: no.
Parameters
userId
number
groupProfile
GroupProfile
Returns
Promise<GroupInfo>
apiReceiveFile()
apiReceiveFile(
fileId):Promise<AChatItem>
Defined in: src/api.ts:529
Receive file. Network usage: no.
Parameters
fileId
number
Returns
Promise<AChatItem>
apiRejectContactRequest()
apiRejectContactRequest(
contactReqId):Promise<void>
Defined in: src/api.ts:760
Reject contact request. The user who sent the request is not notified. Network usage: no.
Parameters
contactReqId
number
Returns
Promise<void>
apiRemoveMembers()
apiRemoveMembers(
groupId,memberIds,withMessages?):Promise<GroupMember[]>
Defined in: src/api.ts:600
Remove members. Requires Admin role. Network usage: background.
Parameters
groupId
number
memberIds
number[]
withMessages?
boolean = false
Returns
Promise<GroupMember[]>
apiSendMemberContactInvitation()
apiSendMemberContactInvitation(
contactId,message?):Promise<Contact>
Defined in: src/api.ts:964
Send a direct message invitation to a group member contact. The contact must have been created with apiCreateMemberContact. Network usage: interactive.
Parameters
contactId
number
message?
string | MsgContent
Returns
Promise<Contact>
apiSendMessages()
apiSendMessages(
chat,messages,liveMessage?):Promise<AChatItem[]>
Defined in: src/api.ts:432
Send messages. Network usage: background.
Parameters
chat
ChatInfo | ChatRef | [ChatType, number]
messages
ComposedMessage[]
liveMessage?
boolean = false
Returns
Promise<AChatItem[]>
apiSendTextMessage()
apiSendTextMessage(
chat,text,inReplyTo?):Promise<AChatItem[]>
Defined in: src/api.ts:455
Send text message. Network usage: background.
Parameters
chat
ChatInfo | ChatRef | [ChatType, number]
text
string
inReplyTo?
number
Returns
Promise<AChatItem[]>
apiSendTextReply()
apiSendTextReply(
chatItem,text):Promise<AChatItem[]>
Defined in: src/api.ts:463
Send text message in reply to received message. Network usage: background.
Parameters
chatItem
AChatItem
text
string
Returns
Promise<AChatItem[]>
apiSetActiveUser()
apiSetActiveUser(
userId,viewPwd?):Promise<User>
Defined in: src/api.ts:907
Set active user profile Network usage: no.
Parameters
userId
number
viewPwd?
string
Returns
Promise<User>
apiSetAddressSettings()
apiSetAddressSettings(
userId,__namedParameters):Promise<void>
Defined in: src/api.ts:415
Set bot address settings. Network usage: interactive.
Parameters
userId
number
__namedParameters
Returns
Promise<void>
apiSetAutoAcceptMemberContacts()
apiSetAutoAcceptMemberContacts(
userId,onOff):Promise<void>
Defined in: src/api.ts:846
Set auto-accept member contacts. Network usage: no.
Parameters
userId
number
onOff
boolean
Returns
Promise<void>
apiSetContactCustomData()
apiSetContactCustomData(
contactId,customData?):Promise<void>
Defined in: src/api.ts:836
Set contact custom data. Network usage: no.
Parameters
contactId
number
customData?
object
Returns
Promise<void>
apiSetContactPrefs()
apiSetContactPrefs(
contactId,preferences):Promise<void>
Defined in: src/api.ts:943
Configure chat preference overrides for the contact. Network usage: background.
Parameters
contactId
number
preferences
Preferences
Returns
Promise<void>
apiSetGroupCustomData()
apiSetGroupCustomData(
groupId,customData?):Promise<void>
Defined in: src/api.ts:826
Set group custom data. Network usage: no.
Parameters
groupId
number
customData?
object
Returns
Promise<void>
apiSetGroupLinkMemberRole()
apiSetGroupLinkMemberRole(
groupId,memberRole):Promise<void>
Defined in: src/api.ts:663
Set member role for group link. Network usage: no.
Parameters
groupId
number
memberRole
GroupMemberRole
Returns
Promise<void>
apiSetMembersRole()
apiSetMembersRole(
groupId,groupMemberIds,memberRole):Promise<void>
Defined in: src/api.ts:580
Set members role. Requires Admin role. Network usage: background.
Parameters
groupId
number
groupMemberIds
number[]
memberRole
GroupMemberRole
Returns
Promise<void>
apiSetProfileAddress()
apiSetProfileAddress(
userId,enable):Promise<UserProfileUpdateSummary>
Defined in: src/api.ts:399
Add address to bot profile. Network usage: interactive.
Parameters
userId
number
enable
boolean
Returns
Promise<UserProfileUpdateSummary>
apiUpdateChatItem()
apiUpdateChatItem(
chatType,chatId,chatItemId,msgContent,liveMessage):Promise<ChatItem>
Defined in: src/api.ts:471
Update message. Network usage: background.
Parameters
chatType
ChatType
chatId
number
chatItemId
number
msgContent
MsgContent
liveMessage
false
Returns
Promise<ChatItem>
apiUpdateGroupProfile()
apiUpdateGroupProfile(
groupId,groupProfile):Promise<GroupInfo>
Defined in: src/api.ts:640
Update group profile. Network usage: background.
Parameters
groupId
number
groupProfile
GroupProfile
Returns
Promise<GroupInfo>
apiUpdateProfile()
apiUpdateProfile(
userId,profile):Promise<UserProfileUpdateSummary|undefined>
Defined in: src/api.ts:927
Update user profile. Network usage: background.
Parameters
userId
number
profile
Profile
Returns
Promise<UserProfileUpdateSummary | undefined>
close()
close():
Promise<void>
Defined in: src/api.ts:158
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.
Returns
Promise<void>
off()
off<
K>(event,subscriber?):void
Defined in: src/api.ts:302
Unsubscribe all or a specific handler from a specific event.
Type Parameters
K
K extends Tag
Parameters
event
K
The event type to unsubscribe from.
subscriber?
EventSubscriberFunc<K> | undefined
An optional subscriber function for the event.
Returns
void
offAny()
offAny(
receiver?):void
Defined in: src/api.ts:318
Unsubscribe all or a specific handler from any events.
Parameters
receiver?
EventSubscriberFunc<Tag> | undefined
An optional subscriber function for the event.
Returns
void
on()
Call Signature
on<
K>(subscribers):void
Defined in: src/api.ts:212
Subscribe multiple event handlers at once.
Type Parameters
K
K extends Tag
Parameters
subscribers
An object mapping event types (CEvt.Tag) to their subscriber functions.
Returns
void
Throws
If the same function is subscribed to event.
Call Signature
on<
K>(event,subscriber):void
Defined in: src/api.ts:220
Subscribe a handler to a specific event.
Type Parameters
K
K extends Tag
Parameters
event
K
The event type to subscribe to.
subscriber
The subscriber function for the event.
Returns
void
Throws
If the same function is subscribed to event.
onAny()
onAny(
receiver):void
Defined in: src/api.ts:243
Subscribe a handler to any event.
Parameters
receiver
EventSubscriberFunc<Tag>
The receiver function for any event.
Returns
void
Throws
If the same function is subscribed to event.
once()
once<
K>(event,subscriber):void
Defined in: src/api.ts:254
Subscribe a handler to a specific event to be delivered one time.
Type Parameters
K
K extends Tag
Parameters
event
K
The event type to subscribe to.
subscriber
The subscriber function for the event.
Returns
void
Throws
If the same function is subscribed to event.
recvChatEvent()
recvChatEvent(
wait?):Promise<ChatEvent|undefined>
Defined in: src/api.ts:353
Parameters
wait?
number = 500_000
Returns
Promise<ChatEvent | undefined>
sendChatCmd()
sendChatCmd(
cmd):Promise<ChatResponse>
Defined in: src/api.ts:349
Parameters
cmd
string
Returns
Promise<ChatResponse>
startChat()
startChat():
Promise<void>
Defined in: src/api.ts:124
Start chat controller. Must be called with the existing user profile.
Returns
Promise<void>
stopChat()
stopChat():
Promise<void>
Defined in: src/api.ts:147
Stop chat controller.
close calls it before closing the database.
Usually doesn't need to be called in chat bots.
Returns
Promise<void>
wait()
Call Signature
wait<
K>(event):Promise<ChatEvent&object>
Defined in: src/api.ts:262
Waits for specific event, with an optional predicate.
Returns undefined on timeout if specified.
Type Parameters
K
K extends Tag
Parameters
event
K
Returns
Promise<ChatEvent & object>
Call Signature
wait<
K>(event,predicate):Promise<ChatEvent&object>
Defined in: src/api.ts:263
Waits for specific event, with an optional predicate.
Returns undefined on timeout if specified.
Type Parameters
K
K extends Tag
Parameters
event
K
predicate
((event) => boolean) | undefined
Returns
Promise<ChatEvent & object>
Call Signature
wait<
K>(event,timeout):Promise<ChatEvent & { type: K; } |undefined>
Defined in: src/api.ts:264
Waits for specific event, with an optional predicate.
Returns undefined on timeout if specified.
Type Parameters
K
K extends Tag
Parameters
event
K
timeout
number
Returns
Promise<ChatEvent & { type: K; } | undefined>
Call Signature
wait<
K>(event,predicate,timeout):Promise<ChatEvent & { type: K; } |undefined>
Defined in: src/api.ts:265
Waits for specific event, with an optional predicate.
Returns undefined on timeout if specified.
Type Parameters
K
K extends Tag
Parameters
event
K
predicate
((event) => boolean) | undefined
timeout
number
Returns
Promise<ChatEvent & { type: K; } | undefined>
init()
staticinit(db,confirm?,queueSize?):Promise<ChatApi>
Defined in: src/api.ts:111
Initializes the ChatApi.
Parameters
db
Database configuration (sqlite or postgres).
confirm?
MigrationConfirmation = core.MigrationConfirmation.YesUp
Migration confirmation mode.
queueSize?
number
Size of internal queues, the core default is used when omitted.
Returns
Promise<ChatApi>