From 31faceef7381d7a31c30b4eb0f059e3a33097a5a Mon Sep 17 00:00:00 2001 From: Evgeny Date: Sun, 2 Aug 2026 14:12:57 +0100 Subject: [PATCH] docs: add bot library APIs (#7334) --- bots/api/COMMANDS.md | 104 ++++++++++++++++++ bots/api/TYPES.md | 1 + bots/src/API/Docs/Commands.hs | 10 +- bots/src/API/Docs/Responses.hs | 4 +- bots/src/API/Docs/Types.hs | 2 +- .../types/typescript/src/commands.ts | 43 ++++++++ .../types/typescript/src/responses.ts | 17 +++ .../types/typescript/src/types.ts | 1 + .../src/simplex_chat/types/_commands.py | 37 +++++++ .../src/simplex_chat/types/_responses.py | 15 ++- .../src/simplex_chat/types/_types.py | 2 +- 11 files changed, 226 insertions(+), 10 deletions(-) diff --git a/bots/api/COMMANDS.md b/bots/api/COMMANDS.md index 8d61622fff..476ee4f94d 100644 --- a/bots/api/COMMANDS.md +++ b/bots/api/COMMANDS.md @@ -15,6 +15,8 @@ This file is generated automatically. - [APIDeleteChatItem](#apideletechatitem) - [APIDeleteMemberChatItem](#apideletememberchatitem) - [APIChatItemReaction](#apichatitemreaction) +- [APIShareMyAddress](#apisharemyaddress) +- [APIShareChatMsgContent](#apisharechatmsgcontent) [File commands](#file-commands) - [ReceiveFile](#receivefile) @@ -35,6 +37,7 @@ This file is generated automatically. - [APIAddGroupRelays](#apiaddgrouprelays) - [APIAllowRelayGroup](#apiallowrelaygroup) - [APIUpdateGroupProfile](#apiupdategroupprofile) +- [APIVerifyGroupDomain](#apiverifygroupdomain) [Group link commands](#group-link-commands) - [APICreateGroupLink](#apicreategrouplink) @@ -489,6 +492,73 @@ ChatCmdError: Command error (only used in WebSockets API). --- +### APIShareMyAddress + +Share user address card + +*Network usage*: no. + +**Parameters**: +- toSendRef: [ChatRef](./TYPES.md#chatref) + +**Syntax**: + +``` +/_share address +``` + +```javascript +'/_share address' + ChatRef.cmdString(toSendRef) // JavaScript +``` + +```python +'/_share address' + ChatRef_cmd_string(toSendRef) # Python +``` + +**Response**: + +ChatMsgContent: Chat card content that can be sent. +- type: "chatMsgContent" +- user: [User](./TYPES.md#user) +- msgContent: [MsgContent](./TYPES.md#msgcontent) + +--- + + +### APIShareChatMsgContent + +Share channel address + +*Network usage*: no. + +**Parameters**: +- shareChatRef: [ChatRef](./TYPES.md#chatref) +- toSendRef: [ChatRef](./TYPES.md#chatref) + +**Syntax**: + +``` +/_share chat content +``` + +```javascript +'/_share chat content ' + ChatRef.cmdString(shareChatRef) + ' ' + ChatRef.cmdString(toSendRef) // JavaScript +``` + +```python +'/_share chat content ' + ChatRef_cmd_string(shareChatRef) + ' ' + ChatRef_cmd_string(toSendRef) # Python +``` + +**Response**: + +ChatMsgContent: Chat card content that can be sent. +- type: "chatMsgContent" +- user: [User](./TYPES.md#user) +- msgContent: [MsgContent](./TYPES.md#msgcontent) + +--- + + ## File commands Commands to receive and to cancel files. Files are sent as part of the message, there are no separate commands to send files. @@ -1165,6 +1235,40 @@ ChatCmdError: Command error (only used in WebSockets API). --- +### APIVerifyGroupDomain + +Verify group domain + +*Network usage*: interactive. + +**Parameters**: +- groupId: int64 + +**Syntax**: + +``` +/_verify domain # +``` + +```javascript +'/_verify domain #' + groupId // JavaScript +``` + +```python +'/_verify domain #' + str(groupId) # Python +``` + +**Response**: + +GroupDomainVerified: Group domain verified. +- type: "groupDomainVerified" +- user: [User](./TYPES.md#user) +- groupInfo: [GroupInfo](./TYPES.md#groupinfo) +- verificationFailure: string? + +--- + + ## Group link commands These commands can be used by bots that manage multiple public groups diff --git a/bots/api/TYPES.md b/bots/api/TYPES.md index 61c8c97132..4546a6aaa7 100644 --- a/bots/api/TYPES.md +++ b/bots/api/TYPES.md @@ -1448,6 +1448,7 @@ Search: **Enum type**: - "human" - "bot" +- "business" --- diff --git a/bots/src/API/Docs/Commands.hs b/bots/src/API/Docs/Commands.hs index da2a9e5d59..09ae1faa5b 100644 --- a/bots/src/API/Docs/Commands.hs +++ b/bots/src/API/Docs/Commands.hs @@ -97,7 +97,9 @@ chatCommandsDocsData = ), ("APIDeleteChatItem", [], "Delete message.", ["CRChatItemsDeleted", "CRChatCmdError"], [], Just UNBackground, "/_delete item " <> Param "chatRef" <> " " <> Join ',' "chatItemIds" <> " " <> Param "deleteMode"), ("APIDeleteMemberChatItem", [], "Moderate message. Requires Moderator role (and higher than message author's).", ["CRChatItemsDeleted", "CRChatCmdError"], [], Just UNBackground, "/_delete member item #" <> Param "groupId" <> " " <> Join ',' "chatItemIds"), - ("APIChatItemReaction", [], "Add/remove message reaction.", ["CRChatItemReaction", "CRChatCmdError"], [], Just UNBackground, "/_reaction " <> Param "chatRef" <> " " <> Param "chatItemId" <> " " <> OnOff "add" <> " " <> Json "reaction") + ("APIChatItemReaction", [], "Add/remove message reaction.", ["CRChatItemReaction", "CRChatCmdError"], [], Just UNBackground, "/_reaction " <> Param "chatRef" <> " " <> Param "chatItemId" <> " " <> OnOff "add" <> " " <> Json "reaction"), + ("APIShareMyAddress", [], "Share user address card", ["CRChatMsgContent"], [], Nothing, "/_share address" <> Param "toSendRef"), + ("APIShareChatMsgContent", [], "Share channel address", ["CRChatMsgContent"], [], Nothing, "/_share chat content " <> Param "shareChatRef" <> " " <> Param "toSendRef") ] ), ( "File commands", @@ -121,7 +123,8 @@ chatCommandsDocsData = ("APIGetGroupRelays", [], "Get group relays.", ["CRGroupRelays", "CRChatCmdError"], [], Nothing, "/_get relays #" <> Param "groupId"), ("APIAddGroupRelays", [], "Add relays to group.", ["CRGroupRelaysAdded", "CRGroupRelaysAddFailed", "CRChatCmdError"], [], Just UNInteractive, "/_add relays #" <> Param "groupId" <> " " <> Join ',' "relayIds"), ("APIAllowRelayGroup", [], "Clear relay rejection for a channel (relay operator).", ["CRRelayGroupAllowed", "CRChatCmdError"], [], Just UNBackground, "/_relay allow #" <> Param "groupId"), - ("APIUpdateGroupProfile", [], "Update group profile.", ["CRGroupUpdated", "CRChatCmdError"], [], Just UNBackground, "/_group_profile #" <> Param "groupId" <> " " <> Json "groupProfile") + ("APIUpdateGroupProfile", [], "Update group profile.", ["CRGroupUpdated", "CRChatCmdError"], [], Just UNBackground, "/_group_profile #" <> Param "groupId" <> " " <> Json "groupProfile"), + ("APIVerifyGroupDomain", [], "Verify group domain", ["CRGroupDomainVerified"], [], Just UNInteractive, "/_verify domain #" <> Param "groupId") ] ), ( "Group link commands", @@ -426,8 +429,6 @@ undocumentedCommands = "APISetUserDomain", "APISetUserServers", "APISetUserUIThemes", - "APIShareChatMsgContent", - "APIShareMyAddress", "APIStandaloneFileInfo", "APIStorageEncryption", "APISuspendChat", @@ -446,7 +447,6 @@ undocumentedCommands = "APIVerifyContact", "APIVerifyContactDomain", "APIVerifyGroupMember", - "APIVerifyGroupDomain", "APIVerifyToken", "CheckChatRunning", "ConfirmRemoteCtrl", diff --git a/bots/src/API/Docs/Responses.hs b/bots/src/API/Docs/Responses.hs index 7f158f7540..76f1ddb76b 100644 --- a/bots/src/API/Docs/Responses.hs +++ b/bots/src/API/Docs/Responses.hs @@ -51,6 +51,7 @@ chatResponsesDocsData = ("CRChatItemReaction", "Message reaction"), ("CRChatItemUpdated", "Message updated"), ("CRChatItemsDeleted", "Messages deleted"), + ("CRChatMsgContent", "Chat card content that can be sent"), ("CRChatRunning", ""), ("CRChatStarted", ""), ("CRChatStopped", ""), @@ -77,6 +78,7 @@ chatResponsesDocsData = ("CRGroupMembers", ""), ("CRGroupUpdated", ""), ("CRGroupsList", "Groups"), + ("CRGroupDomainVerified", ""), ("CRInvitation", "One-time invitation"), ("CRLeftMemberUser", "User left group"), ("CRMemberAccepted", "Member accepted to group"), @@ -136,7 +138,6 @@ undocumentedResponses = "CRChatItemInfo", "CRChatItems", "CRChatItemTTL", - "CRChatMsgContent", "CRChatRelayTestResult", "CRChats", "CRConnectionsDiff", @@ -169,7 +170,6 @@ undocumentedResponses = "CRGroupMemberRatchetSyncStarted", "CRGroupMemberSwitchAborted", "CRGroupMemberSwitchStarted", - "CRGroupDomainVerified", "CRGroupProfile", "CRGroupUserChanged", "CRItemsReadForChat", diff --git a/bots/src/API/Docs/Types.hs b/bots/src/API/Docs/Types.hs index f6b25934b1..e0af1f3ff5 100644 --- a/bots/src/API/Docs/Types.hs +++ b/bots/src/API/Docs/Types.hs @@ -226,7 +226,7 @@ chatTypesDocsData = (sti @BadgeType, STEnum, "BT", ["BTUnknown"], "", ""), (sti @ChatFeature, STEnum, "CF", [], "", ""), (sti @ChatItemDeletion, STRecord, "", [], "", "Message deletion result."), - (sti @ChatPeerType, STEnum, "CPT", [], "", ""), + (sti @ChatPeerType, STEnum, "CPT", ["CPTUnknown"], "", ""), (sti @ChatRef, STRecord, "", [], Param "chatType" <> Param "chatId" <> Optional "" (Param "$0") "chatScope", "Used in API commands. Chat scope can only be passed with groups."), (sti @ChatSettings, STRecord, "", [], "", ""), (sti @ChatStats, STRecord, "", [], "", ""), diff --git a/packages/simplex-chat-client/types/typescript/src/commands.ts b/packages/simplex-chat-client/types/typescript/src/commands.ts index 4c7c13403e..14b03f560f 100644 --- a/packages/simplex-chat-client/types/typescript/src/commands.ts +++ b/packages/simplex-chat-client/types/typescript/src/commands.ts @@ -168,6 +168,35 @@ export namespace APIChatItemReaction { } } +// Share user address card +// Network usage: no. +export interface APIShareMyAddress { + toSendRef: T.ChatRef +} + +export namespace APIShareMyAddress { + export type Response = CR.ChatMsgContent + + export function cmdString(self: APIShareMyAddress): string { + return '/_share address' + T.ChatRef.cmdString(self.toSendRef) + } +} + +// Share channel address +// Network usage: no. +export interface APIShareChatMsgContent { + shareChatRef: T.ChatRef + toSendRef: T.ChatRef +} + +export namespace APIShareChatMsgContent { + export type Response = CR.ChatMsgContent + + export function cmdString(self: APIShareChatMsgContent): string { + return '/_share chat content ' + T.ChatRef.cmdString(self.shareChatRef) + ' ' + T.ChatRef.cmdString(self.toSendRef) + } +} + // File commands // Commands to receive and to cancel files. Files are sent as part of the message, there are no separate commands to send files. @@ -419,6 +448,20 @@ export namespace APIUpdateGroupProfile { } } +// Verify group domain +// Network usage: interactive. +export interface APIVerifyGroupDomain { + groupId: number // int64 +} + +export namespace APIVerifyGroupDomain { + export type Response = CR.GroupDomainVerified + + export function cmdString(self: APIVerifyGroupDomain): string { + return '/_verify domain #' + self.groupId + } +} + // Group link commands // These commands can be used by bots that manage multiple public groups diff --git a/packages/simplex-chat-client/types/typescript/src/responses.ts b/packages/simplex-chat-client/types/typescript/src/responses.ts index fa5c83d03c..b2d29490c8 100644 --- a/packages/simplex-chat-client/types/typescript/src/responses.ts +++ b/packages/simplex-chat-client/types/typescript/src/responses.ts @@ -10,6 +10,7 @@ export type ChatResponse = | CR.ChatItemReaction | CR.ChatItemUpdated | CR.ChatItemsDeleted + | CR.ChatMsgContent | CR.ChatRunning | CR.ChatStarted | CR.ChatStopped @@ -36,6 +37,7 @@ export type ChatResponse = | CR.GroupMembers | CR.GroupUpdated | CR.GroupsList + | CR.GroupDomainVerified | CR.Invitation | CR.LeftMemberUser | CR.MemberAccepted @@ -69,6 +71,7 @@ export namespace CR { | "chatItemReaction" | "chatItemUpdated" | "chatItemsDeleted" + | "chatMsgContent" | "chatRunning" | "chatStarted" | "chatStopped" @@ -95,6 +98,7 @@ export namespace CR { | "groupMembers" | "groupUpdated" | "groupsList" + | "groupDomainVerified" | "invitation" | "leftMemberUser" | "memberAccepted" @@ -162,6 +166,12 @@ export namespace CR { timed: boolean } + export interface ChatMsgContent extends Interface { + type: "chatMsgContent" + user: T.User + msgContent: T.MsgContent + } + export interface ChatRunning extends Interface { type: "chatRunning" } @@ -326,6 +336,13 @@ export namespace CR { groups: T.GroupInfo[] } + export interface GroupDomainVerified extends Interface { + type: "groupDomainVerified" + user: T.User + groupInfo: T.GroupInfo + verificationFailure?: string + } + export interface Invitation extends Interface { type: "invitation" user: T.User diff --git a/packages/simplex-chat-client/types/typescript/src/types.ts b/packages/simplex-chat-client/types/typescript/src/types.ts index abc4187747..5faf084dce 100644 --- a/packages/simplex-chat-client/types/typescript/src/types.ts +++ b/packages/simplex-chat-client/types/typescript/src/types.ts @@ -1680,6 +1680,7 @@ export namespace ChatListQuery { export enum ChatPeerType { Human = "human", Bot = "bot", + Business = "business", } // Used in API commands. Chat scope can only be passed with groups. diff --git a/packages/simplex-chat-python/src/simplex_chat/types/_commands.py b/packages/simplex-chat-python/src/simplex_chat/types/_commands.py index 1886df7868..f73a4fa4f7 100644 --- a/packages/simplex-chat-python/src/simplex_chat/types/_commands.py +++ b/packages/simplex-chat-python/src/simplex_chat/types/_commands.py @@ -149,6 +149,31 @@ def APIChatItemReaction_cmd_string(self: APIChatItemReaction) -> str: APIChatItemReaction_Response = CR.ChatItemReaction | CR.ChatCmdError +# Share user address card +# Network usage: no. +class APIShareMyAddress(TypedDict): + toSendRef: "T.ChatRef" + + +def APIShareMyAddress_cmd_string(self: APIShareMyAddress) -> str: + return '/_share address' + T.ChatRef_cmd_string(self['toSendRef']) + +APIShareMyAddress_Response = CR.ChatMsgContent + + +# Share channel address +# Network usage: no. +class APIShareChatMsgContent(TypedDict): + shareChatRef: "T.ChatRef" + toSendRef: "T.ChatRef" + + +def APIShareChatMsgContent_cmd_string(self: APIShareChatMsgContent) -> str: + return '/_share chat content ' + T.ChatRef_cmd_string(self['shareChatRef']) + ' ' + T.ChatRef_cmd_string(self['toSendRef']) + +APIShareChatMsgContent_Response = CR.ChatMsgContent + + # File commands # Commands to receive and to cancel files. Files are sent as part of the message, there are no separate commands to send files. @@ -368,6 +393,18 @@ def APIUpdateGroupProfile_cmd_string(self: APIUpdateGroupProfile) -> str: APIUpdateGroupProfile_Response = CR.GroupUpdated | CR.ChatCmdError +# Verify group domain +# Network usage: interactive. +class APIVerifyGroupDomain(TypedDict): + groupId: int # int64 + + +def APIVerifyGroupDomain_cmd_string(self: APIVerifyGroupDomain) -> str: + return '/_verify domain #' + str(self['groupId']) + +APIVerifyGroupDomain_Response = CR.GroupDomainVerified + + # Group link commands # These commands can be used by bots that manage multiple public groups diff --git a/packages/simplex-chat-python/src/simplex_chat/types/_responses.py b/packages/simplex-chat-python/src/simplex_chat/types/_responses.py index 955291d0f0..393c20f311 100644 --- a/packages/simplex-chat-python/src/simplex_chat/types/_responses.py +++ b/packages/simplex-chat-python/src/simplex_chat/types/_responses.py @@ -36,6 +36,11 @@ class ChatItemsDeleted(TypedDict): byUser: bool timed: bool +class ChatMsgContent(TypedDict): + type: Literal["chatMsgContent"] + user: "T.User" + msgContent: "T.MsgContent" + class ChatRunning(TypedDict): type: Literal["chatRunning"] @@ -174,6 +179,12 @@ class GroupsList(TypedDict): user: "T.User" groups: list["T.GroupInfo"] +class GroupDomainVerified(TypedDict): + type: Literal["groupDomainVerified"] + user: "T.User" + groupInfo: "T.GroupInfo" + verificationFailure: NotRequired[str] + class Invitation(TypedDict): type: Literal["invitation"] user: "T.User" @@ -319,6 +330,7 @@ ChatResponse = ( | ChatItemReaction | ChatItemUpdated | ChatItemsDeleted + | ChatMsgContent | ChatRunning | ChatStarted | ChatStopped @@ -345,6 +357,7 @@ ChatResponse = ( | GroupMembers | GroupUpdated | GroupsList + | GroupDomainVerified | Invitation | LeftMemberUser | MemberAccepted @@ -371,4 +384,4 @@ ChatResponse = ( | ApiChats ) -ChatResponse_Tag = Literal["acceptingContactRequest", "activeUser", "chatItemNotChanged", "chatItemReaction", "chatItemUpdated", "chatItemsDeleted", "chatRunning", "chatStarted", "chatStopped", "cmdOk", "chatCmdError", "connectionPlan", "contactAlreadyExists", "contactConnectionDeleted", "contactDeleted", "contactPrefsUpdated", "contactRequestRejected", "contactsList", "groupDeletedUser", "groupLink", "groupLinkCreated", "groupLinkDeleted", "groupCreated", "publicGroupCreated", "publicGroupCreationFailed", "groupRelays", "groupRelaysAdded", "groupRelaysAddFailed", "relayGroupAllowed", "groupMembers", "groupUpdated", "groupsList", "invitation", "leftMemberUser", "memberAccepted", "membersBlockedForAllUser", "membersRoleUser", "newChatItems", "rcvFileAccepted", "rcvFileAcceptedSndCancelled", "rcvFileCancelled", "sentConfirmation", "sentGroupInvitation", "sentInvitation", "serviceReplyAccepted", "sndFileCancelled", "userAcceptedGroupSent", "userContactLink", "userContactLinkCreated", "userContactLinkDeleted", "userContactLinkUpdated", "userDeletedMembers", "userProfileUpdated", "userProfileNoChange", "usersList", "apiChats"] +ChatResponse_Tag = Literal["acceptingContactRequest", "activeUser", "chatItemNotChanged", "chatItemReaction", "chatItemUpdated", "chatItemsDeleted", "chatMsgContent", "chatRunning", "chatStarted", "chatStopped", "cmdOk", "chatCmdError", "connectionPlan", "contactAlreadyExists", "contactConnectionDeleted", "contactDeleted", "contactPrefsUpdated", "contactRequestRejected", "contactsList", "groupDeletedUser", "groupLink", "groupLinkCreated", "groupLinkDeleted", "groupCreated", "publicGroupCreated", "publicGroupCreationFailed", "groupRelays", "groupRelaysAdded", "groupRelaysAddFailed", "relayGroupAllowed", "groupMembers", "groupUpdated", "groupsList", "groupDomainVerified", "invitation", "leftMemberUser", "memberAccepted", "membersBlockedForAllUser", "membersRoleUser", "newChatItems", "rcvFileAccepted", "rcvFileAcceptedSndCancelled", "rcvFileCancelled", "sentConfirmation", "sentGroupInvitation", "sentInvitation", "serviceReplyAccepted", "sndFileCancelled", "userAcceptedGroupSent", "userContactLink", "userContactLinkCreated", "userContactLinkDeleted", "userContactLinkUpdated", "userDeletedMembers", "userProfileUpdated", "userProfileNoChange", "usersList", "apiChats"] diff --git a/packages/simplex-chat-python/src/simplex_chat/types/_types.py b/packages/simplex-chat-python/src/simplex_chat/types/_types.py index b57915d2db..b00a559f92 100644 --- a/packages/simplex-chat-python/src/simplex_chat/types/_types.py +++ b/packages/simplex-chat-python/src/simplex_chat/types/_types.py @@ -1175,7 +1175,7 @@ ChatListQuery = ChatListQuery_filters | ChatListQuery_search ChatListQuery_Tag = Literal["filters", "search"] -ChatPeerType = Literal["human", "bot"] +ChatPeerType = Literal["human", "bot", "business"] # Used in API commands. Chat scope can only be passed with groups.