Node API updated.

Author: smelamud

src/moeralib/node/node.py

@@ -1939,7 +1939,7 @@ def get_remote_sheriff_order(self, node_name: str, id: str) -> types.SheriffOrde
         )
         return types.SheriffOrderInfo.from_json(data)
 
-    def search_nodes(self, query: str | None = None, limit: int | None = None) -> List[types.SearchNodeInfo]:
+    def search_nodes(self, filter: types.SearchNodeFilter) -> types.SearchNodePageInfo:
         """
         Search for Moera nodes matching the search ``query``. Every space-delimited word in the query must match
         case-insensitively a beginning of the node's name or a beginning of any non-letter-delimited word in the node's
@@ -1950,13 +1950,36 @@ def search_nodes(self, query: str | None = None, limit: int | None = None) -> Li
         The returned nodes are sorted by their relevance. The exact definition of this term is left to the search
         engine's implementation.
 
+        :param filter:
+        """
+        location = "/search/nodes"
+        data = self.call(
+            "search_nodes", location, method="POST", body=filter, schema=schemas.SEARCH_NODE_PAGE_INFO_SCHEMA
+        )
+        return types.SearchNodePageInfo.from_json(data)
+
+    def search_node_suggestions(
+        self, query: str | None = None, sheriff: str | None = None, limit: int | None = None
+    ) -> List[types.SearchNodeInfo]:
+        """
+        Search for Moera nodes matching the search ``query`` and return a short list of "smart suggestions" for the
+        user. Every space-delimited word in the query must match case-insensitively a beginning of the node's name or a
+        beginning of any non-letter-delimited word in the node's full name. The order of words is not significant.
+        
+        The search engine may decide to return fewer nodes than the given ``limit``.
+        
+        The returned nodes are sorted by their relevance. The exact definition of this term is left to the search
+        engine's implementation.
+
         :param query: the search query
+        :param sheriff: filter out entries prohibited by the given sheriff
         :param limit: maximum number of nodes returned
         """
-        location = "/search/nodes".format()
-        params = {"query": query, "limit": limit}
+        location = "/search/nodes/suggestions".format()
+        params = {"query": query, "sheriff": sheriff, "limit": limit}
         data = self.call(
-            "search_nodes", location, method="GET", params=params, schema=schemas.SEARCH_NODE_INFO_ARRAY_SCHEMA
+            "search_node_suggestions", location, method="GET", params=params,
+            schema=schemas.SEARCH_NODE_INFO_ARRAY_SCHEMA
         )
         return structure_list(data, types.SearchNodeInfo)
 

src/moeralib/node/schemas.py

@@ -1611,6 +1611,28 @@
 
 SEARCH_NODE_INFO_ARRAY_SCHEMA = array_schema(SEARCH_NODE_INFO_SCHEMA)
 
+SEARCH_NODE_PAGE_INFO_SCHEMA: Any = {
+    "type": "object",
+    "properties": {
+        "page": {
+            "type": "integer"
+        },
+        "total": {
+            "type": "integer"
+        },
+        "nodes": {
+            "type": "array",
+            "items": SEARCH_NODE_INFO_SCHEMA
+        },
+    },
+    "required": [
+        "page",
+        "total",
+        "nodes",
+    ],
+    "additionalProperties": False
+}
+
 SEARCH_REPLIED_TO_SCHEMA: Any = {
     "type": "object",
     "properties": {
@@ -2902,6 +2924,9 @@
         "bodyPreview": {
             "type": "string"
         },
+        "bodyFormat": {
+            "type": ["string", "null"]
+        },
         "heading": {
             "type": "string"
         },

src/moeralib/node/types.py

@@ -1759,6 +1759,17 @@ class SearchHashtagFilter(Structure):
     """maximum number of entries returned"""
 
 
+class SearchNodeFilter(Structure):
+    query: str
+    """the search query"""
+    sheriff_name: str | None = None
+    """filter out nodes prohibited by the given sheriff"""
+    page: int | None = None
+    """page number, 0 by default"""
+    limit: int | None = None
+    """page size (maximum number of entries returned), the default is set by the search engine"""
+
+
 class SearchNodeInfo(Structure):
     node_name: str
     full_name: str | None = None
@@ -1771,6 +1782,15 @@ class SearchNodeInfo(Structure):
     """social distance between the node and the client"""
 
 
+class SearchNodePageInfo(Structure):
+    page: int
+    """number of the page"""
+    total: int
+    """total number of nodes found (this number may be approximate)"""
+    nodes: List[SearchNodeInfo]
+    """the nodes"""
+
+
 class SearchPostingUpdate(Structure):
     feed_name: str
     """name of the feed where the posting is published"""
@@ -2965,6 +2985,8 @@ class SearchEntryInfo(Structure):
     """avatar of the entry's owner"""
     body_preview: Body
     """preview of the entry's body, a string representation of a JSON structure"""
+    body_format: BodyFormat | None = None
+    """format of the entry's body, may have any value meaningful for the client"""
     heading: str
     """heading of the entry"""
     image_count: int | None = None
@@ -2994,7 +3016,7 @@ class SearchTextPageInfo(Structure):
     page: int
     """number of the page"""
     total: int
-    """total number of pages"""
+    """total number of entries found"""
     entries: List[SearchEntryInfo]
     """the entries"""