konecty_sdk_python 2.1.1__py3-none-any.whl

KonectySdkPython/lib/services/change_user.py

@@ -0,0 +1,64 @@
+"""Change User API: add, remove, define, replace, countInactive, removeInactive, setQueue."""
+
+from typing import Any, Dict, List
+
+from .base import BaseService
+
+
+class ChangeUserService(BaseService):
+    """Service for changing user/queue on records."""
+
+    async def add_users(
+        self, module: str, ids: List[Any], users: Any
+    ) -> Dict[str, Any]:
+        """POST /rest/changeUser/{module}/add. Body: ids, data (users)."""
+        path = f"/rest/changeUser/{module}/add"
+        return await self._post(path, json={"ids": ids, "data": users})
+
+    async def remove_users(
+        self, module: str, ids: List[Any], users: Any
+    ) -> Dict[str, Any]:
+        """POST /rest/changeUser/{module}/remove."""
+        path = f"/rest/changeUser/{module}/remove"
+        return await self._post(path, json={"ids": ids, "data": users})
+
+    async def define_users(
+        self, module: str, ids: List[Any], users: Any
+    ) -> Dict[str, Any]:
+        """POST /rest/changeUser/{module}/define."""
+        path = f"/rest/changeUser/{module}/define"
+        return await self._post(path, json={"ids": ids, "data": users})
+
+    async def replace_users(
+        self,
+        module: str,
+        ids: List[Any],
+        *,
+        from_user: Any = None,
+        to_user: Any = None,
+    ) -> Dict[str, Any]:
+        """POST /rest/changeUser/{module}/replace. Body: ids, data: { from?, to? }."""
+        path = f"/rest/changeUser/{module}/replace"
+        data: Dict[str, Any] = {}
+        if from_user is not None:
+            data["from"] = from_user
+        if to_user is not None:
+            data["to"] = to_user
+        return await self._post(path, json={"ids": ids, "data": data})
+
+    async def count_inactive(self, module: str, ids: List[Any]) -> Dict[str, Any]:
+        """POST /rest/changeUser/{module}/countInactive. Body: ids."""
+        path = f"/rest/changeUser/{module}/countInactive"
+        return await self._post(path, json={"ids": ids})
+
+    async def remove_inactive(self, module: str, ids: List[Any]) -> Dict[str, Any]:
+        """POST /rest/changeUser/{module}/removeInactive. Body: ids."""
+        path = f"/rest/changeUser/{module}/removeInactive"
+        return await self._post(path, json={"ids": ids})
+
+    async def set_queue(
+        self, module: str, ids: List[Any], queue: Any
+    ) -> Dict[str, Any]:
+        """POST /rest/changeUser/{module}/setQueue. Body: ids, data (queue config)."""
+        path = f"/rest/changeUser/{module}/setQueue"
+        return await self._post(path, json={"ids": ids, "data": queue})

KonectySdkPython/lib/services/comments.py

@@ -0,0 +1,89 @@
+"""Comments API: list, create, update, delete, search users, search comments."""
+
+from typing import Any, Dict, Optional
+
+from .base import BaseService
+
+
+class CommentsService(BaseService):
+    """Service for record comments."""
+
+    async def get_comments(self, module: str, data_id: str) -> Dict[str, Any]:
+        """GET /rest/comment/{module}/{data_id}. Returns API result (success, data)."""
+        path = f"/rest/comment/{module}/{data_id}"
+        return await self._get(path)
+
+    async def create_comment(
+        self,
+        module: str,
+        data_id: str,
+        text: str,
+        parent_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """POST /rest/comment/{module}/{data_id}. Body: text, parentId optional."""
+        path = f"/rest/comment/{module}/{data_id}"
+        body: Dict[str, Any] = {"text": text}
+        if parent_id is not None:
+            body["parentId"] = parent_id
+        return await self._post(path, json=body)
+
+    async def update_comment(
+        self,
+        module: str,
+        data_id: str,
+        comment_id: str,
+        text: str,
+    ) -> Dict[str, Any]:
+        """PUT /rest/comment/{module}/{data_id}/{comment_id}. Body: text."""
+        path = f"/rest/comment/{module}/{data_id}/{comment_id}"
+        return await self._put(path, json={"text": text})
+
+    async def delete_comment(
+        self,
+        module: str,
+        data_id: str,
+        comment_id: str,
+    ) -> Dict[str, Any]:
+        """DELETE /rest/comment/{module}/{data_id}/{comment_id}."""
+        path = f"/rest/comment/{module}/{data_id}/{comment_id}"
+        return await self._delete(path)
+
+    async def search_comment_users(
+        self,
+        module: str,
+        data_id: str,
+        query: str = "",
+    ) -> Dict[str, Any]:
+        """GET /rest/comment/{module}/{data_id}/users/search?q=."""
+        path = f"/rest/comment/{module}/{data_id}/users/search"
+        params = {"q": query} if query else {}
+        return await self._get(path, params=params or None)
+
+    async def search_comments(
+        self,
+        module: str,
+        data_id: str,
+        *,
+        query: Optional[str] = None,
+        author_id: Optional[str] = None,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        page: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """GET /rest/comment/{module}/{data_id}/search with query params."""
+        path = f"/rest/comment/{module}/{data_id}/search"
+        params: Dict[str, str] = {}
+        if query is not None:
+            params["q"] = query
+        if author_id is not None:
+            params["authorId"] = author_id
+        if start_date is not None:
+            params["startDate"] = start_date
+        if end_date is not None:
+            params["endDate"] = end_date
+        if page is not None:
+            params["page"] = str(page)
+        if limit is not None:
+            params["limit"] = str(limit)
+        return await self._get(path, params=params or None)

KonectySdkPython/lib/services/export.py

@@ -0,0 +1,54 @@
+"""Export list as CSV, XLSX, or JSON (bytes)."""
+
+import json
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from ..serialization import json_serial
+from ..filters import KonectyFilter
+from .base import BaseService
+
+ExportFormat = Literal["csv", "xlsx", "json", "xls"]
+
+
+class ExportService(BaseService):
+    """Service for exporting lists (GET returns file bytes)."""
+
+    async def export_list(
+        self,
+        module: str,
+        list_name: str,
+        format: ExportFormat,
+        *,
+        filter_params: Optional[KonectyFilter] = None,
+        sort: Optional[Any] = None,
+        fields: Optional[List[Union[str, int]]] = None,
+        start: Optional[int] = None,
+        limit: Optional[int] = None,
+        display_name: Optional[str] = None,
+        display_type: Optional[str] = None,
+    ) -> bytes:
+        """
+        Export list as file. GET /rest/data/{module}/list/{list_name}/{type}.
+        type is csv, xlsx, or json (xls is normalized to xlsx).
+        Returns file content as bytes.
+        """
+        export_type = "xlsx" if format == "xls" else format
+        if export_type not in ("csv", "xlsx", "json"):
+            raise ValueError("format must be csv, xlsx, json, or xls")
+        params: Dict[str, str] = {}
+        if filter_params is not None:
+            params["filter"] = json.dumps(filter_params.to_json(), default=json_serial)
+        if sort is not None:
+            params["sort"] = json.dumps(sort, default=json_serial) if not isinstance(sort, str) else sort
+        if fields is not None:
+            params["fields"] = ",".join(str(f) for f in fields)
+        if start is not None:
+            params["start"] = str(start)
+        if limit is not None:
+            params["limit"] = str(limit)
+        if display_name is not None:
+            params["displayName"] = display_name
+        if display_type is not None:
+            params["displayType"] = display_type
+        path = f"/rest/data/{module}/list/{list_name}/{export_type}"
+        return await self._get(path, params=params, return_bytes=True)

KonectySdkPython/lib/services/files.py

@@ -0,0 +1,59 @@
+"""File download and image download (binary responses)."""
+
+from typing import Literal, Optional
+
+from .base import BaseService
+
+
+class FilesService(BaseService):
+    """Service for downloading files and images (GET returning bytes)."""
+
+    async def download_file(
+        self,
+        module: str,
+        record_code: str,
+        field_name: str,
+        file_name: str,
+    ) -> bytes:
+        """
+        Download a file from a record field. GET /rest/file/{module}/{record_code}/{field_name}/{file_name}.
+
+        Args:
+            module: Document/module name.
+            record_code: Record code (id).
+            field_name: Field name holding the file.
+            file_name: File name.
+
+        Returns:
+            File content as bytes.
+        """
+        path = f"/rest/file/{module}/{record_code}/{field_name}/{file_name}"
+        return await self._get(path, return_bytes=True)
+
+    async def download_image(
+        self,
+        module: str,
+        record_id: str,
+        field_name: str,
+        file_name: str,
+        *,
+        style: Optional[Literal["full", "thumb", "wm"]] = None,
+    ) -> bytes:
+        """
+        Download an image from a record field. GET /rest/image/... with optional style (full, thumb, watermark).
+
+        Args:
+            module: Document/module name.
+            record_id: Record id.
+            field_name: Field name holding the image.
+            file_name: File name.
+            style: None = full file; "thumb" = thumbnail; "wm" = watermark.
+
+        Returns:
+            Image content as bytes.
+        """
+        if style is not None:
+            path = f"/rest/image/{style}/{module}/{record_id}/{field_name}/{file_name}"
+        else:
+            path = f"/rest/image/{module}/{record_id}/{field_name}/{file_name}"
+        return await self._get(path, return_bytes=True)

KonectySdkPython/lib/services/notifications.py

@@ -0,0 +1,41 @@
+"""Notifications API: list, unread count, mark read, mark all read."""
+
+from typing import Any, Dict, Optional
+
+from .base import BaseService
+
+
+class NotificationsService(BaseService):
+    """Service for user notifications."""
+
+    async def list_notifications(
+        self,
+        *,
+        read: Optional[bool] = None,
+        page: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """GET /rest/notifications. Query: read, page, limit."""
+        params: Dict[str, str] = {}
+        if read is not None:
+            params["read"] = "true" if read else "false"
+        if page is not None:
+            params["page"] = str(page)
+        if limit is not None:
+            params["limit"] = str(limit)
+        return await self._get(
+            "/rest/notifications", params=params if params else None
+        )
+
+    async def get_unread_count(self) -> Dict[str, Any]:
+        """GET /rest/notifications/unread-count."""
+        return await self._get("/rest/notifications/unread-count")
+
+    async def mark_notification_read(self, notification_id: str) -> Dict[str, Any]:
+        """PUT /rest/notifications/{id}/read."""
+        path = f"/rest/notifications/{notification_id}/read"
+        return await self._put(path)
+
+    async def mark_all_notifications_read(self) -> Dict[str, Any]:
+        """PUT /rest/notifications/read-all."""
+        return await self._put("/rest/notifications/read-all")

KonectySdkPython/lib/services/query.py

@@ -0,0 +1,192 @@
+"""Custom query (query/json, query/sql) and Saved Queries CRUD."""
+
+import json
+from typing import Any, AsyncGenerator, Dict, List, Optional, Union
+
+from ..types import KonectyDict
+from ..exceptions import KonectyAPIError
+from ..http import StreamResponse
+from .base import BaseService
+
+
+class QueryResult:
+    """Result of execute_query_json or execute_query_sql. Stream of records + optional total and meta."""
+
+    __slots__ = ("stream", "total", "meta")
+
+    def __init__(
+        self,
+        stream: AsyncGenerator[KonectyDict, None],
+        total: Optional[int] = None,
+        meta: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self.stream = stream
+        self.total = total
+        self.meta = meta
+
+
+async def _build_query_result(
+    raw: StreamResponse,
+    include_meta: bool,
+    include_total: bool,
+) -> QueryResult:
+    """Read first line (maybe _meta), then return QueryResult. Generator consumes the rest."""
+    total: Optional[int] = None
+    meta: Optional[Dict[str, Any]] = None
+    if include_total:
+        tc = raw.headers.get("x-total-count")
+        if tc is not None:
+            try:
+                total = int(tc)
+            except ValueError:
+                pass
+
+    first_record: Optional[KonectyDict] = None
+    while True:
+        line = await raw.readline()
+        if not line:
+            break
+        line = line.strip()
+        if not line:
+            continue
+        obj = json.loads(line.decode("utf-8"))
+        if isinstance(obj, dict) and "_meta" in obj:
+            m = obj["_meta"]
+            if m.get("success") is False:
+                errors = m.get("errors", [])
+                raise KonectyAPIError(errors)
+            if include_meta:
+                meta = m
+                if total is None and "total" in m:
+                    total = m["total"]
+            continue
+        first_record = obj
+        break
+
+    async def gen() -> AsyncGenerator[KonectyDict, None]:
+        if first_record is not None:
+            yield first_record
+        async with raw:
+            while True:
+                line = await raw.readline()
+                if not line:
+                    break
+                line = line.strip()
+                if not line:
+                    continue
+                yield json.loads(line.decode("utf-8"))
+
+    return QueryResult(stream=gen(), total=total, meta=meta)
+
+
+class QueryService(BaseService):
+    """Service for custom query (JSON/SQL) and saved queries."""
+
+    async def execute_query_json(
+        self,
+        body: Union[Dict[str, Any], Any],
+        *,
+        include_total: bool = True,
+        include_meta: bool = False,
+    ) -> QueryResult:
+        """
+        Execute a cross-module query. POST /rest/query/json. Body is CrossModuleQuery (dict or model).
+        Returns QueryResult with .stream (async generator), .total, .meta.
+        """
+        if hasattr(body, "to_dict"):
+            payload = body.to_dict()
+        elif hasattr(body, "model_dump"):
+            payload = body.model_dump(by_alias=True, exclude_none=True)
+        else:
+            payload = dict(body)
+        path = "/rest/query/json"
+        raw = await self._post(path, json=payload, stream=True)
+        if not isinstance(raw, StreamResponse):
+            raise KonectyAPIError(["Unexpected non-stream response"])
+        return await _build_query_result(
+            raw, include_meta=include_meta, include_total=include_total
+        )
+
+    async def execute_query_sql(
+        self,
+        sql: str,
+        *,
+        include_total: bool = True,
+        include_meta: bool = False,
+    ) -> QueryResult:
+        """
+        Execute SQL (converted to cross-module query server-side). POST /rest/query/sql.
+        Returns QueryResult. On SQL parse error the server returns 400 with _meta.errors.
+        """
+        payload: Dict[str, Any] = {"sql": sql}
+        if include_total is not None:
+            payload["includeTotal"] = include_total
+        if include_meta is not None:
+            payload["includeMeta"] = include_meta
+        path = "/rest/query/sql"
+        raw = await self._post(path, json=payload, stream=True)
+        if not isinstance(raw, StreamResponse):
+            raise KonectyAPIError(["Unexpected non-stream response"])
+        return await _build_query_result(
+            raw, include_meta=include_meta, include_total=include_total
+        )
+
+    # --- Saved queries ---
+
+    async def list_saved_queries(self) -> Dict[str, Any]:
+        """GET /rest/query/saved."""
+        return await self._get("/rest/query/saved")
+
+    async def get_saved_query(self, query_id: str) -> Dict[str, Any]:
+        """GET /rest/query/saved/{id}."""
+        path = f"/rest/query/saved/{query_id}"
+        return await self._get(path)
+
+    async def create_saved_query(
+        self,
+        name: str,
+        query: Dict[str, Any],
+        description: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """POST /rest/query/saved. Body: name, query (CrossModuleQuery), description?."""
+        body: Dict[str, Any] = {"name": name, "query": query}
+        if description is not None:
+            body["description"] = description
+        return await self._post("/rest/query/saved", json=body)
+
+    async def update_saved_query(
+        self,
+        query_id: str,
+        *,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        query: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """PUT /rest/query/saved/{id}. Body: name?, description?, query?."""
+        body: Dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+        if description is not None:
+            body["description"] = description
+        if query is not None:
+            body["query"] = query
+        path = f"/rest/query/saved/{query_id}"
+        return await self._put(path, json=body)
+
+    async def delete_saved_query(self, query_id: str) -> Dict[str, Any]:
+        """DELETE /rest/query/saved/{id}."""
+        path = f"/rest/query/saved/{query_id}"
+        return await self._delete(path)
+
+    async def share_saved_query(
+        self,
+        query_id: str,
+        shared_with: List[Dict[str, Any]],
+        is_public: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """PATCH /rest/query/saved/{id}/share. Body: sharedWith (array of { type, _id, name }), isPublic?."""
+        body: Dict[str, Any] = {"sharedWith": shared_with}
+        if is_public is not None:
+            body["isPublic"] = is_public
+        path = f"/rest/query/saved/{query_id}/share"
+        return await self._patch(path, json=body)

KonectySdkPython/lib/services/stream.py

@@ -0,0 +1,133 @@
+"""Stream API: find_stream (NDJSON) and count_stream."""
+
+import json
+from typing import Any, AsyncGenerator, Dict, Optional
+
+from ..serialization import json_serial
+from ..types import KonectyDict
+from ..filters import KonectyFilter, KonectyFindParams
+from ..http import StreamResponse
+from .base import BaseService
+
+
+def _find_params_to_query(options: KonectyFindParams) -> Dict[str, str]:
+    """Build query params dict from KonectyFindParams (same as client.find)."""
+    params: Dict[str, str] = {}
+    for key, value in options.model_dump(exclude_none=True).items():
+        params[key] = (
+            json.dumps(value, default=json_serial)
+            if key != "fields"
+            else ",".join(str(f) for f in value)
+        )
+    return params
+
+
+class FindStreamResult:
+    """Result of find_stream. Has .stream (async generator of records) and .total (int | None)."""
+
+    __slots__ = ("stream", "total")
+
+    def __init__(
+        self,
+        stream: AsyncGenerator[KonectyDict, None],
+        total: Optional[int],
+    ) -> None:
+        self.stream = stream
+        self.total = total
+
+
+class StreamService(BaseService):
+    """Service for stream endpoints: findStream and count."""
+
+    async def find_stream(
+        self,
+        module: str,
+        options: KonectyFindParams,
+        *,
+        include_total: bool = False,
+    ) -> FindStreamResult:
+        """
+        Stream records as NDJSON (one JSON object per line). Uses GET /rest/stream/{module}/findStream.
+
+        Args:
+            module: Document/module name.
+            options: Find params (filter, sort, limit, start, fields).
+            include_total: If True, request total count; it will be in result.total and X-Total-Count header.
+
+        Returns:
+            FindStreamResult with .stream (async generator of dicts) and .total (int | None when include_total).
+        """
+        params = _find_params_to_query(options)
+        if include_total:
+            params["includeTotal"] = "1"
+        path = f"/rest/stream/{module}/findStream"
+        raw = await self._get(path, params=params, stream=True)
+        assert isinstance(raw, StreamResponse)
+        total: Optional[int] = None
+        if include_total:
+            tc = raw.headers.get("x-total-count")
+            if tc is not None:
+                try:
+                    total = int(tc)
+                except ValueError:
+                    pass
+
+        async def gen() -> AsyncGenerator[KonectyDict, None]:
+            async with raw:
+                while True:
+                    line = await raw.readline()
+                    if not line:
+                        break
+                    line = line.strip()
+                    if not line:
+                        continue
+                    yield json.loads(line.decode("utf-8"))
+
+        return FindStreamResult(stream=gen(), total=total)
+
+    async def count_stream(
+        self,
+        module: str,
+        filter_params: Optional[KonectyFilter] = None,
+        *,
+        display_name: Optional[str] = None,
+        display_type: Optional[str] = None,
+        sort: Optional[Any] = None,
+        with_detail_fields: Optional[bool] = None,
+    ) -> int:
+        """
+        Return total count for the module matching the filter. GET /rest/stream/{module}/count.
+
+        Args:
+            module: Document/module name.
+            filter_params: Optional filter. If None, uses empty filter (count all, subject to permissions).
+            display_name: Optional.
+            display_type: Optional.
+            sort: Optional sort (string or list).
+            with_detail_fields: Optional.
+
+        Returns:
+            Total count.
+        """
+        filter_obj = filter_params or KonectyFilter.create()
+        options = KonectyFindParams(filter=filter_obj)
+        params: Dict[str, str] = {}
+        for key, value in options.model_dump(exclude_none=True).items():
+            params[key] = (
+                json.dumps(value, default=json_serial)
+                if key != "fields"
+                else ",".join(str(f) for f in value)
+            )
+        if display_name is not None:
+            params["displayName"] = str(display_name)
+        if display_type is not None:
+            params["displayType"] = str(display_type)
+        if sort is not None:
+            params["sort"] = json.dumps(sort, default=json_serial) if not isinstance(sort, str) else sort
+        if with_detail_fields is not None:
+            params["withDetailFields"] = "1" if with_detail_fields else "0"
+        path = f"/rest/stream/{module}/count"
+        result = await self._get(path, params=params)
+        if isinstance(result, dict) and "total" in result:
+            return int(result["total"])
+        return 0

KonectySdkPython/lib/services/subscriptions.py

@@ -0,0 +1,26 @@
+"""Subscriptions API: get status, subscribe, unsubscribe."""
+
+from typing import Any, Dict
+
+from .base import BaseService
+
+
+class SubscriptionsService(BaseService):
+    """Service for record subscription (watch) status."""
+
+    async def get_subscription_status(
+        self, module: str, data_id: str
+    ) -> Dict[str, Any]:
+        """GET /rest/subscriptions/{module}/{data_id}. Returns success and subscription data."""
+        path = f"/rest/subscriptions/{module}/{data_id}"
+        return await self._get(path)
+
+    async def subscribe(self, module: str, data_id: str) -> Dict[str, Any]:
+        """POST /rest/subscriptions/{module}/{data_id}. Subscribe to record notifications."""
+        path = f"/rest/subscriptions/{module}/{data_id}"
+        return await self._post(path)
+
+    async def unsubscribe(self, module: str, data_id: str) -> Dict[str, Any]:
+        """DELETE /rest/subscriptions/{module}/{data_id}."""
+        path = f"/rest/subscriptions/{module}/{data_id}"
+        return await self._delete(path)