bots api: fix typescript code, add start/stop commands (#6565)

2026-03-31 09:46:03 +00:00 · 2026-01-11 16:57:15 +00:00
parent 4b986c4cf6
commit 8ebc8894de
13 changed files with 200 additions and 91 deletions
--- a/bots/src/API/Docs/Commands.hs
+++ b/bots/src/API/Docs/Commands.hs
@@ -72,7 +72,7 @@ instance IsString ErrorTypeDoc where fromString s = TD s ""


 -- category name, category description, commands
-- inner: constructor, description, responses, errors (ChatErrorType constructors), network usage, syntax
+-- inner: constructor, hidden params, description, responses, errors (ChatErrorType constructors), network usage, syntax
 chatCommandsDocsData :: [(String, String, [(ConsName, [String], Text, [ConsName], [ErrorTypeDoc], Maybe UsesNetwork, Expr)])]
 chatCommandsDocsData =
  [ ( "Address commands",
@@ -132,7 +132,7 @@ chatCommandsDocsData =
      "These commands may be used to create connections. Most bots do not need to use them - bot users will connect via bot address with auto-accept enabled.",
      [ ("APIAddContact", [], "Create 1-time invitation link.", ["CRInvitation", "CRChatCmdError"], [], Just UNInteractive, "/_connect " <> Param "userId" <> OnOffParam "incognito" "incognito" (Just False)),
        ("APIConnectPlan", [], "Determine SimpleX link type and if the bot is already connected via this link.", ["CRConnectionPlan", "CRChatCmdError"], [], Just UNInteractive, "/_connect plan " <> Param "userId" <> " " <> Param "connectionLink"),
-        ("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_"),
+        ("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 as string in the active user profile.", ["CRSentConfirmation", "CRContactAlreadyExists", "CRSentInvitation", "CRChatCmdError"], [], Just UNInteractive, "/connect" <> Optional "" (" " <> Param "$0") "connLink_"),
        ("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")
@@ -163,21 +163,27 @@ chatCommandsDocsData =
    ),
    ( "User profile commands",
      "Most bots don't need to use these commands, as bot profile can be configured manually via CLI or desktop client. These commands can be used by bots that need to manage multiple user profiles (e.g., the profiles of support agents).",
-      [ ("ShowActiveUser", [], "Get active user profile", ["CRActiveUser", "CRChatCmdError"], [], Nothing, "/user"),
+      [ ("ShowActiveUser", [], "Get active user profile.", ["CRActiveUser", "CRChatCmdError"], [], Nothing, "/user"),
        ( "CreateActiveUser",
          [],
-          "Create new user profile",
+          "Create new user profile.",
          ["CRActiveUser", "CRChatCmdError"],
          [TD "CEUserExists" "User or contact with this name already exists", TD "CEInvalidDisplayName" "Invalid user display name"],
          Nothing,
          "/_create user " <> Json "newUser"
        ),
-        ("ListUsers", [], "Get all user profiles", ["CRUsersList", "CRChatCmdError"], [], Nothing, "/users"),
-        ("APISetActiveUser", [], "Set active user profile", ["CRActiveUser", "CRChatCmdError"], ["CEChatNotStarted"], Nothing, "/_user " <> Param "userId" <> Optional "" (" " <> Json "$0") "viewPwd"),
+        ("ListUsers", [], "Get all user profiles.", ["CRUsersList", "CRChatCmdError"], [], Nothing, "/users"),
+        ("APISetActiveUser", [], "Set active user profile.", ["CRActiveUser", "CRChatCmdError"], ["CEChatNotStarted"], Nothing, "/_user " <> Param "userId" <> Optional "" (" " <> Json "$0") "viewPwd"),
        ("APIDeleteUser", [], "Delete user profile.", ["CRCmdOk", "CRChatCmdError"], [], Just UNBackground, "/_delete user " <> Param "userId" <> OnOffParam "del_smp" "delSMPQueues" Nothing <> Optional "" (" " <> Json "$0") "viewPwd"),
        ("APIUpdateProfile", [], "Update user profile.", ["CRUserProfileUpdated", "CRUserProfileNoChange", "CRChatCmdError"], [], Just UNBackground, "/_profile " <> Param "userId" <> " " <> Json "profile"),
        ("APISetContactPrefs", [], "Configure chat preference overrides for the contact.", ["CRContactPrefsUpdated", "CRChatCmdError"], [], Just UNBackground, "/_set prefs @" <> Param "contactId" <> " " <> Json "preferences")
      ]
+    ),
+    ( "Chat management",
+      "These commands should not be used with CLI-based bots",
+      [ ("StartChat", [], "Start chat controller.", ["CRChatStarted", "CRChatRunning"], [], Nothing, "/_start"),
+        ("APIStopChat", [], "Stop chat controller.", ["CRChatStopped"], [], Nothing, "/_stop")
+      ]
    )
  ]

@@ -396,7 +402,6 @@ undocumentedCommands =
    "APISetUserServers",
    "APISetUserUIThemes",
    "APIStandaloneFileInfo",
-    "APIStopChat",
    "APIStorageEncryption",
    "APISuspendChat",
    "APISwitchContact",
@@ -453,7 +458,6 @@ undocumentedCommands =
    "SetTempFolder",
    "SetUserProtoServers",
    "SlowSQLQueries",
-    "StartChat",
    "StartRemoteHost",
    "StopRemoteCtrl",
    "StopRemoteHost",
--- a/bots/src/API/Docs/Events.hs
+++ b/bots/src/API/Docs/Events.hs
@@ -143,7 +143,7 @@ chatEventsDocsData =
      \or because messages may be delivered to deleted chats for a short period of time \
      \(they will be ignored).",
      [ ("CEvtMessageError", ""),
-        ("CEvtChatError", ""), -- only used in WebSockets API, Haskell code uses Either, with error in Left
+        ("CEvtChatError", "Chat error (only used in WebSockets API)."), -- Haskell code uses Either, with error in Left
        ("CEvtChatErrors", "")
      ],
      []
--- a/bots/src/API/Docs/Generate.hs
+++ b/bots/src/API/Docs/Generate.hs
@@ -73,7 +73,7 @@ syntaxText :: TypeAndFields -> Expr -> Text
 syntaxText r syntax =
  "\n**Syntax**:\n"
    <> "\n```\n" <> docSyntaxText r syntax <> "\n```\n"
-    <> (if isConst syntax then "" else "\n```javascript\n" <> jsSyntaxText False r syntax <> " // JavaScript\n```\n")
+    <> (if isConst syntax then "" else "\n```javascript\n" <> jsSyntaxText False "" r syntax <> " // JavaScript\n```\n")
    <> (if isConst syntax then "" else "\n```python\n" <> pySyntaxText r syntax <> " # Python\n```\n")

 camelToSpace :: String -> String
--- a/bots/src/API/Docs/Generate/TypeScript.hs
+++ b/bots/src/API/Docs/Generate/TypeScript.hs
@@ -49,7 +49,7 @@ commandsCodeText =
            <> "}\n\n"
            <> ("export namespace " <> T.pack constrName <> " {\n")
            <> ("  export type Response = " <> constrsCode "  " "CR" (("CR." <> ) . T.pack . fstToUpper . memberTag) (map responseType responses))
-            <> (if syntax == "" then "" else funcCode APITypeDef {typeName' = constrName, typeDef = ATDRecord params} syntax)
+            <> (if syntax == "" then "" else funcCode APITypeDef {typeName' = constrName, typeDef = ATDRecord params} "T." syntax)
            <> "}\n"
          where
            constrName = fstToUpper tag
@@ -86,7 +86,7 @@ typesCodeText = ("// API Types\n// " <> autoGenerated <> "\n") <> foldMap typeCo
          "ConnectionMode" -> T.pack $ map toUpper tag
          "FileProtocol" -> T.pack $ map toUpper tag
          _ -> T.replace "-" "_" $ T.pack $ fstToUpper tag
-        namespaceFuncCode = "\nexport namespace " <> name' <> " {" <> funcCode td typeSyntax <> "}\n"
+        namespaceFuncCode = "\nexport namespace " <> name' <> " {" <> funcCode td "" typeSyntax <> "}\n"
        typeDefCode = case typeDef of
          ATDRecord fields ->
            ("\nexport interface " <> name' <> " {\n")
@@ -107,7 +107,7 @@ unionTypeCode unionNamespace typesNamespace td@APITypeDef {typeName' = name} cs
    <> ("  export type Tag = " <> constrsCode "  " name' constrTag (L.toList cs) <> "\n")
    <> ("  interface Interface {\n    type: Tag\n  }\n")
    <> foldMap constrType cs
-    <> (if cmdSyntax == "" then "" else funcCode td cmdSyntax)
+    <> (if cmdSyntax == "" then "" else funcCode td typesNamespace cmdSyntax)
    <> "}\n"
  where
    name' = T.pack name
@@ -128,9 +128,9 @@ constrsCode indent name' constr cs
    line = T.intercalate " | " cs'
    cs' = map constr cs

-funcCode :: APITypeDef -> Expr -> Text
-funcCode td@APITypeDef {typeName' = name, typeDef} cmdSyntax =
-  "\n  export function cmdString(" <> param <> ": " <> T.pack name <> "): string {\n    return " <> jsSyntaxText True (name, self : typeFields) cmdSyntax <> "\n  }\n"
+funcCode :: APITypeDef -> String -> Expr -> Text
+funcCode td@APITypeDef {typeName' = name, typeDef} typeNamespace cmdSyntax =
+  "\n  export function cmdString(" <> param <> ": " <> T.pack name <> "): string {\n    return " <> jsSyntaxText True typeNamespace (name, self : typeFields) cmdSyntax <> "\n  }\n"
  where
    param = if hasParams cmdSyntax then "self" else "_self"
    self = APIRecordField "self" (ATDef td)
--- a/bots/src/API/Docs/Responses.hs
+++ b/bots/src/API/Docs/Responses.hs
@@ -51,8 +51,11 @@ chatResponsesDocsData =
    ("CRChatItemReaction", "Message reaction"),
    ("CRChatItemUpdated", "Message updated"),
    ("CRChatItemsDeleted", "Messages deleted"),
+    ("CRChatRunning", ""),
+    ("CRChatStarted", ""),
+    ("CRChatStopped", ""),
    ("CRCmdOk", "Ok"),
-    ("CRChatCmdError", "Command error"), -- only used in WebSockets API, Haskell code uses Either, with error in Left
+    ("CRChatCmdError", "Command error (only used in WebSockets API)"), -- Haskell code uses Either, with error in Left
    ("CRConnectionPlan", "Connection link information"),
    ("CRContactAlreadyExists", ""),
    ("CRContactConnectionDeleted", "Connection deleted"),
@@ -127,10 +130,7 @@ undocumentedResponses =
    "CRChatItemInfo",
    "CRChatItems",
    "CRChatItemTTL",
-    "CRChatRunning",
    "CRChats",
-    "CRChatStarted",
-    "CRChatStopped",
    "CRConnectionsDiff",
    "CRChatTags",
    "CRConnectionAliasUpdated",
--- a/bots/src/API/Docs/Syntax.hs
+++ b/bots/src/API/Docs/Syntax.hs
@@ -99,8 +99,8 @@ withOptBoolParam r param p f =
    (ATOptional (ATPrim (PT TBool))) -> f True
    _ -> paramError r param p "is not [optional] boolean"

-jsSyntaxText :: Bool -> TypeAndFields -> Expr -> Text
-jsSyntaxText useSelf r = T.replace "' + '" "" . T.pack . go Nothing True
+jsSyntaxText :: Bool -> String -> TypeAndFields -> Expr -> Text
+jsSyntaxText useSelf typeNamespace r = T.replace "' + '" "" . T.pack . go Nothing True
  where
    go param top = \case
      Concat exs -> intercalate " + " $ map (go param False) $ L.toList exs
@@ -112,7 +112,7 @@ jsSyntaxText useSelf r = T.replace "' + '" "" . T.pack . go Nothing True
          _ -> paramName' useSelf param p
        where
          toStringSyntax (APITypeDef typeName _)
-            | typeHasSyntax typeName = paramName' useSelf param p <> ".toString()"
+            | typeHasSyntax typeName = typeNamespace <> typeName <> ".cmdString(" <> paramName' useSelf param p <> ")"
            | otherwise = paramName' useSelf param p
      Optional exN exJ p -> open <> n <> " ? " <> go (Just p) False exJ <> " : " <> nothing <> close
        where