bots: add APIs (#7494)

* docs: fix bot API surface - Fix missing space in APIShareMyAddress syntax expression which resulted in parse errors - Document missing `Connect` responses: `CRConnectionPlan`, `CRSentInvitationToContact`, `CRStartedConnectionToContact`, and `CRStartedConnectionToGroup` (relay channel links). - Document missing `CRUserProfileNoChange` responsed returned when `APISetProfileAddress` doesn't change the profile. - Expose remote control APIs to bots * website: improve sign-up forms (#7484) * website: improve sign-up forms * name --------- Co-authored-by: Evgeny @ SimpleX Chat <259188159+evgeny-simplex@users.noreply.github.com> * rename field * generic --------- Co-authored-by: a1akris <alkrivitskiy@pm.me> Co-authored-by: Evgeny @ SimpleX Chat <259188159+evgeny-simplex@users.noreply.github.com>
2026-09-21 16:07:35 +00:00 · 2026-09-12 14:13:11 +01:00
parent 9631e0b1b9
commit 47d32b674a
17 changed files with 661 additions and 26 deletions
@@ -80,7 +80,7 @@ chatCommandsDocsData =
      [ ("APICreateMyAddress", ["server_"], "Create bot address.", ["CRUserContactLinkCreated", "CRChatCmdError"], [], Just UNInteractive, "/_address " <> Param "userId" <> OnOffParam "pq_ratchet" "pqRatchet" Nothing),
        ("APIDeleteMyAddress", [], "Delete bot address.", ["CRUserContactLinkDeleted", "CRChatCmdError"], [], Just UNBackground, "/_delete_address " <> Param "userId"),
        ("APIShowMyAddress", [], "Get bot address and settings.", ["CRUserContactLink", "CRChatCmdError"], [], Nothing, "/_show_address " <> Param "userId"),
-        ("APISetProfileAddress", [], "Add address to bot profile.", ["CRUserProfileUpdated", "CRChatCmdError"], [], Just UNInteractive, "/_profile_address " <> Param "userId" <> " " <> OnOff "enable"),
+        ("APISetProfileAddress", [], "Add address to bot profile.", ["CRUserProfileUpdated", "CRUserProfileNoChange", "CRChatCmdError"], [], Just UNInteractive, "/_profile_address " <> Param "userId" <> " " <> OnOff "enable"),
        ("APISetAddressSettings", [], "Set bot address settings.", ["CRUserContactLinkUpdated", "CRChatCmdError"], [], Just UNInteractive, "/_address_settings " <> Param "userId" <> OnOffParam "pq_ratchet" "pqRatchet" Nothing <> " " <> Json "settings")
      ]
    ),
@@ -98,7 +98,7 @@ 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"),
-        ("APIShareMyAddress", [], "Share user address card", ["CRChatMsgContent"], [], Nothing, "/_share address" <> Param "toSendRef"),
+        ("APIShareMyAddress", [], "Share user address card", ["CRChatMsgContent"], [], Nothing, "/_share address " <> Param "toSendRef"),
        ("APIShareChatMsgContent", [], "Share channel address", ["CRChatMsgContent"], [], Nothing, "/_share chat content " <> Param "shareChatRef" <> " " <> Param "toSendRef")
      ]
    ),
@@ -141,7 +141,7 @@ chatCommandsDocsData =
        -- `Maybe` in `connectTarget :: Maybe ConnectTarget` is used to signal parse failure to the runtime (the handler returns CEInvalidConnReq on Nothing); it is NOT API-level optionality. The parameter is required from callers.
        ("APIConnectPlan", [], "Determine SimpleX link type and if the bot is already connected via this link or name.", ["CRConnectionPlan", "CRChatCmdError"], [], Just UNInteractive, "/_connect plan " <> Param "userId" <> " " <> Param "connectTarget"),
        ("APIConnect", [], "Connect via prepared SimpleX link. The link can be 1-time invitation link, contact address or group link.", ["CRSentConfirmation", "CRContactAlreadyExists", "CRSentInvitation", "CRChatCmdError"], [], Just UNInteractive, "/_connect " <> Param "userId" <> Optional "" (" " <> Param "$0") "preparedLink_"),
-        ("Connect", [], "Connect via SimpleX link or name as string in the active user profile.", ["CRSentConfirmation", "CRContactAlreadyExists", "CRSentInvitation", "CRChatCmdError"], [], Just UNInteractive, "/connect" <> Optional "" (" " <> Param "$0") "connTarget_"),
+        ("Connect", [], "Connect via SimpleX link or name as string in the active user profile.", ["CRSentConfirmation", "CRContactAlreadyExists", "CRSentInvitation", "CRConnectionPlan", "CRSentInvitationToContact", "CRStartedConnectionToContact", "CRStartedConnectionToGroup", "CRChatCmdError"], [], Just UNInteractive, "/connect" <> Optional "" (" " <> Param "$0") "connTarget_"),
        ("APIAcceptContact", ["incognito"], "Accept contact request.", ["CRAcceptingContactRequest", "CRChatCmdError"], [], Just UNInteractive, "/_accept " <> Param "contactReqId"),
        ("APIRejectContact", [], "Reject contact request. The user who sent the request is **not notified**.", ["CRContactRequestRejected", "CRChatCmdError"], [], Nothing, "/_reject " <> Param "contactReqId")
      ]
@@ -202,6 +202,12 @@ chatCommandsDocsData =
      [ ("StartChat", [], "Start chat controller.", ["CRChatStarted", "CRChatRunning"], [], Nothing, "/_start" <> OnOffParam "main" "mainApp" Nothing <> OnOffParam "snd_files" "enableSndFiles" (Just True) <> OnOffParam "service_requests" "serviceRequests" (Just False)),
        ("APIStopChat", [], "Stop chat controller.", ["CRChatStopped"], [], Nothing, "/_stop")
      ]
+    ),
+    ( "Remote control commands",
+      "Allows a bot to accept an incoming remote control session from a SimpleX Desktop client, giving the desktop live access to the bot's SimpleX instance.",
+      [ ("ConnectRemoteCtrl", [], "Connect to a remote controller using an OOB invitation link.", ["CRRemoteCtrlConnecting", "CRChatCmdError"], [], Just UNInteractive, "/crc " <> Param "remoteInvitation"),
+        ("VerifyRemoteCtrlSession", [], "Verify the remote controller session code to complete the connection.", ["CRRemoteCtrlConnected", "CRChatCmdError"], [], Nothing, "/verify remote ctrl " <> Param "sessionCode")
+      ]
    )
  ]

@@ -452,7 +458,6 @@ undocumentedCommands =
    "APIVerifyToken",
    "CheckChatRunning",
    "ConfirmRemoteCtrl",
-    "ConnectRemoteCtrl",
    "CustomChatCommand",
    "DebugEvent",
    "DebugLocks",
@@ -499,6 +504,5 @@ undocumentedCommands =
    "SwitchRemoteHost",
    "TestChatRelay",
    "TestProtoServer",
-    "TestStorageEncryption",
-    "VerifyRemoteCtrlSession"
+    "TestStorageEncryption"
  ]
@@ -152,6 +152,13 @@ chatEventsDocsData =
      ],
      []
    ),
+    ( "Remote control events",
+      "Bots that act as remote control hosts receive these events during the remote control session lifecycle.",
+      [ ("CEvtRemoteCtrlSessionCode", "Remote controller session code ready for verification.\n\nUse [VerifyRemoteCtrlSession](./COMMANDS.md#verifyremotectrlsession) to complete the connection."),
+        ("CEvtRemoteCtrlStopped", "Remote controller session stopped.")
+      ],
+      []
+    ),
    ( "Error events",
      "Bots may log these events for debugging. \
      \There will be many error events - this does NOT indicate a malfunction - \
@@ -203,8 +210,6 @@ undocumentedEvents =
    "CEvtRcvFileProgressXFTP",
    "CEvtRcvStandaloneFileComplete",
    "CEvtRemoteCtrlFound",
-    "CEvtRemoteCtrlSessionCode",
-    "CEvtRemoteCtrlStopped",
    "CEvtRemoteHostConnected",
    "CEvtRemoteHostSessionCode",
    "CEvtRemoteHostStopped",
@@ -88,11 +88,16 @@ chatResponsesDocsData =
    ("CRRcvFileAccepted", "File accepted to be received"),
    ("CRRcvFileAcceptedSndCancelled", "File accepted, but no longer sent"),
    ("CRRcvFileCancelled", "Cancelled receiving file"),
+    ("CRRemoteCtrlConnected", "Remote controller session connected."),
+    ("CRRemoteCtrlConnecting", "Remote controller is connecting."),
    ("CRSentConfirmation", "Confirmation sent to one-time invitation"),
    ("CRSentGroupInvitation", "Group invitation sent"),
    ("CRSentInvitation", "Invitation sent to contact address"),
+    ("CRSentInvitationToContact", "Invitation sent to contact (when connecting via SimpleX name to a known contact address)."),
    ("CRServiceReplyAccepted", "Service reply accepted for delivery. `connectionId` correlates the reply delivery event."),
    ("CRSndFileCancelled", "Cancelled sending file"),
+    ("CRStartedConnectionToContact", "Connection to contact started (when connecting via prepared contact)."),
+    ("CRStartedConnectionToGroup", "Connection to channel started (when connecting via channel link)."),
    ("CRUserAcceptedGroupSent", "User accepted group invitation"),
    ("CRUserContactLink", "User contact address"),
    ("CRUserContactLinkCreated", "User contact address created"),
@@ -188,13 +193,10 @@ undocumentedResponses =
    "CRQueueInfo",
    "CRRcvStandaloneFileCreated",
    "CRReactionMembers",
-    "CRRemoteCtrlConnected",
-    "CRRemoteCtrlConnecting",
    "CRRemoteCtrlList",
    "CRRemoteFileStored",
    "CRRemoteHostList",
    "CRRemoteHostStarted",
-    "CRSentInvitationToContact",
    "CRServerOperatorConditions",
    "CRServerTestResult",
    "CRServiceResponse",
@@ -202,8 +204,6 @@ undocumentedResponses =
    "CRSndStandaloneFileCreated",
    "CRSQLResult",
    "CRStandaloneFileInfo",
-    "CRStartedConnectionToContact",
-    "CRStartedConnectionToGroup",
    "CRTagsUpdated",
    "CRUsageConditions",
    "CRUserPrivacy",
@@ -49,6 +49,8 @@ import Simplex.Messaging.Parsers (dropPrefix, fstToLower)
 import Simplex.Messaging.Protocol (BlockingInfo (..), BlockingReason (..), CommandError (..), ErrorType (..), NameErrorType (..), NetworkError (..), ProxyError (..))
 import Simplex.Messaging.Protocol.Types (ClientNotice (..))
 import Simplex.Messaging.Transport
+import Simplex.Chat.Remote.AppVersion (AppVersion, AppVersionRange)
+import Simplex.Chat.Remote.Types (CtrlAppInfo (..))
 import Simplex.RemoteControl.Types
 import System.Console.ANSI.Types (Color (..))

@@ -211,6 +213,7 @@ chatTypesDocsData =
    (sti @AgentCryptoError, STUnion, "", ["RATCHET_EARLIER", "RATCHET_SKIPPED"], "", ""), -- TODO add fields to types
    (sti @AgentErrorType, STUnion, "", [], "", ""),
    (sti @AgentServiceError, STUnion, "ASE", [], "", ""),
+    (STI "AppVersionRange" [RecordTypeInfo "AppVersionRange" [FieldInfo "minVersion" (TIType (ST TString [])), FieldInfo "maxVersion" (TIType (ST TString []))]], STRecord, "", [], "", "Remote controller app version range (min and max as version strings)."),
    (sti @AutoAccept, STRecord, "", [], "", ""),
    (sti @BadgeProof, STRecord, "", [], "", ""),
    (sti @BlockingInfo, STRecord, "", [], "", ""),
@@ -243,6 +246,7 @@ chatTypesDocsData =
    (sti @CIReactionCount, STRecord, "", [], "", ""),
    (sti @CITimed, STRecord, "", [], "", ""),
    (sti @ClientNotice, STRecord, "", [], "", ""),
+    (sti @CtrlAppInfo, STRecord, "", [], "", "Remote controller application info."),
    (sti @Color, STEnum, "", [], "", ""),
    (sti @CommandError, STUnion, "", [], "", ""),
    (sti @CommandErrorType, STUnion, "", [], "", ""),
@@ -354,8 +358,12 @@ chatTypesDocsData =
    (sti @RcvGroupEvent, STUnion, "RGE", [], "", ""),
    (sti @RcvMsgError, STUnion, "RME", [], "", ""),
    (sti @RelayCapabilities, STRecord, "", [], "", ""),
+    (sti @RelayConnectionResult, STRecord, "", [], "", ""),
    (sti @RelayProfile, STRecord, "", [], "", ""),
    (sti @RelayStatus, STEnum, "RS", [], "", ""),
+    (sti @RemoteCtrlInfo, STRecord, "", [], "", ""),
+    (sti @RemoteCtrlSessionState, STUnion, "RCS", [], "", ""),
+    (sti @RemoteCtrlStopReason, STUnion, "RCSR", [], "", ""),
    (sti @ReportReason, STEnum' (dropPfxSfx "RR" ""), "", ["RRUnknown"], "", ""),
    (sti @RoleGroupPreference, STRecord, "", [], "", ""),
    (sti @SecurityCode, STRecord, "", [], "", ""),
@@ -471,6 +479,7 @@ deriving instance Generic CIMentionMember
 deriving instance Generic CIReactionCount
 deriving instance Generic CITimed
 deriving instance Generic ClientNotice
+deriving instance Generic CtrlAppInfo
 deriving instance Generic Color
 deriving instance Generic CommandError
 deriving instance Generic CommandErrorType
@@ -589,8 +598,12 @@ deriving instance Generic RcvFileTransfer
 deriving instance Generic RcvGroupEvent
 deriving instance Generic RcvMsgError
 deriving instance Generic RelayCapabilities
+deriving instance Generic RelayConnectionResult
 deriving instance Generic RelayProfile
 deriving instance Generic RelayStatus
+deriving instance Generic RemoteCtrlInfo
+deriving instance Generic RemoteCtrlSessionState
+deriving instance Generic RemoteCtrlStopReason
 deriving instance Generic ReportReason
 deriving instance Generic SecurityCode
 deriving instance Generic SimplexDomain
@@ -200,6 +200,7 @@ toTypeInfo tr =
        "AgentInvId",
        "AgentRcvFileId",
        "AgentSndFileId",
+        "AppVersion",
        "BadgeMasterKey",
        "B64UrlByteString",
        "BBSProof",
@@ -219,6 +220,7 @@ toTypeInfo tr =
        "ProofPresHeader",
        "PublicKey",
        "ProtocolServer",
+        "RCSignedInvitation",
        "SbKey",
        "SharedMsgId",
        "Signature",