konecty_sdk_python 2.1.1__py3-none-any.whl

KonectySdkPython/lib/exceptions.py

@@ -0,0 +1,26 @@
+"""Exceptions for the Konecty SDK."""
+
+
+class KonectyError(Exception):
+    """Base exception for Konecty errors."""
+
+    pass
+
+
+class KonectyAPIError(KonectyError):
+    """Raised when the API returns success=false or a non-2xx status."""
+
+    pass
+
+
+class KonectyValidationError(KonectyError):
+    """Raised for validation errors."""
+
+    pass
+
+
+class KonectySerializationError(KonectyError):
+    """Raised when a value is not serializable."""
+
+    def __init__(self) -> None:
+        super().__init__("Tipo não serializável")

KonectySdkPython/lib/feature_types/__init__.py

@@ -0,0 +1,46 @@
+"""Feature-specific types (KPI, Graph, Pivot, CrossModuleQuery, QueryJson, etc.). Re-exported for convenience."""
+
+from .cross_module_query import (
+    DEFAULT_PRIMARY_LIMIT,
+    MAX_RELATION_LIMIT,
+    MAX_RELATIONS,
+    Aggregator,
+    CrossModuleQuery,
+    CrossModuleRelation,
+)
+from .kpi import KpiConfig, KpiOperation
+from .query_json import (
+    AggregatorName,
+    AggregatorSpec,
+    ConditionValue,
+    ExplicitJoinCondition,
+    FilterMatch,
+    QueryFilter,
+    QueryFilterCondition,
+    QueryJson,
+    QueryRelation,
+    QuerySortItem,
+    SortDirection,
+)
+
+__all__ = [
+    "Aggregator",
+    "AggregatorName",
+    "AggregatorSpec",
+    "ConditionValue",
+    "CrossModuleQuery",
+    "CrossModuleRelation",
+    "DEFAULT_PRIMARY_LIMIT",
+    "ExplicitJoinCondition",
+    "FilterMatch",
+    "KpiConfig",
+    "KpiOperation",
+    "MAX_RELATION_LIMIT",
+    "MAX_RELATIONS",
+    "QueryFilter",
+    "QueryFilterCondition",
+    "QueryJson",
+    "QueryRelation",
+    "QuerySortItem",
+    "SortDirection",
+]

KonectySdkPython/lib/feature_types/cross_module_query.py

@@ -0,0 +1,78 @@
+"""Types for cross-module query (query/json and query/sql). Mirrors Konecty crossModuleQuery schema."""
+
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, Field
+
+MAX_RELATIONS = 10
+MAX_NESTING_DEPTH = 2
+MAX_RELATION_LIMIT = 100_000
+DEFAULT_RELATION_LIMIT = 1000
+DEFAULT_PRIMARY_LIMIT = 1000
+
+AggregatorName = (
+    str  # count, countDistinct, sum, avg, min, max, first, last, push, addToSet
+)
+
+
+class Aggregator(BaseModel):
+    """Aggregator in a relation or root. Field required for some (e.g. countDistinct)."""
+
+    aggregator: str
+    field: Optional[str] = None
+
+
+class SortItem(BaseModel):
+    """Sort item: property and direction."""
+
+    property: str
+    direction: str = "ASC"  # ASC | DESC
+
+
+class ExplicitJoinCondition(BaseModel):
+    """Explicit join condition: left and right keys."""
+
+    left: str
+    right: str
+
+
+class CrossModuleRelation(BaseModel):
+    """Relation in a cross-module query. At least one aggregator required."""
+
+    document: str
+    lookup: str
+    on: Optional[ExplicitJoinCondition] = None
+    filter: Optional[Dict[str, Any]] = None
+    fields: Optional[str] = None
+    sort: Optional[Union[str, List[SortItem]]] = None
+    limit: int = Field(default=DEFAULT_RELATION_LIMIT, ge=1, le=MAX_RELATION_LIMIT)
+    start: int = Field(default=0, ge=0)
+    aggregators: Dict[str, Aggregator] = Field(..., min_length=1)
+    relations: Optional[List["CrossModuleRelation"]] = Field(
+        default=None, max_length=MAX_RELATIONS
+    )
+
+    model_config = {"extra": "allow"}
+
+
+CrossModuleRelation.model_rebuild()
+
+
+class CrossModuleQuery(BaseModel):
+    """Body for POST /rest/query/json. Primary document + optional relations, groupBy, aggregators."""
+
+    document: str
+    filter: Optional[Dict[str, Any]] = None
+    fields: Optional[str] = None
+    sort: Optional[Union[str, List[SortItem]]] = None
+    limit: int = Field(default=DEFAULT_PRIMARY_LIMIT, ge=1, le=MAX_RELATION_LIMIT)
+    start: int = Field(default=0, ge=0)
+    relations: List[CrossModuleRelation] = Field(
+        default_factory=list, max_length=MAX_RELATIONS
+    )
+    groupBy: List[str] = Field(default_factory=list, alias="groupBy")
+    aggregators: Dict[str, Aggregator] = Field(default_factory=dict)
+    includeTotal: bool = Field(default=True, alias="includeTotal")
+    includeMeta: bool = Field(default=False, alias="includeMeta")
+
+    model_config = {"extra": "allow", "populate_by_name": True}

KonectySdkPython/lib/feature_types/kpi.py

@@ -0,0 +1,21 @@
+"""KPI config for aggregation API."""
+
+from typing import Literal, Optional
+
+from pydantic import BaseModel, model_validator
+
+
+KpiOperation = Literal["count", "sum", "avg", "min", "max", "countDistinct"]
+
+
+class KpiConfig(BaseModel):
+    """Config for KPI aggregation. Field is required for all operations except count."""
+
+    operation: KpiOperation
+    field: Optional[str] = None
+
+    @model_validator(mode="after")
+    def count_distinct_requires_field(self) -> "KpiConfig":
+        if self.operation == "countDistinct" and not self.field:
+            raise ValueError("countDistinct requires field")
+        return self

KonectySdkPython/lib/feature_types/query_json.py

@@ -0,0 +1,242 @@
+"""
+Strongly-typed query creator for POST /rest/query/json (Konecty cross-module query).
+Use classes/dataclasses with properties for full intellisense; no builder pattern.
+Serializes to the exact payload Konecty expects via to_dict().
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Optional, Union
+
+# ---------------------------------------------------------------------------
+# Literal types (Konecty schema)
+# ---------------------------------------------------------------------------
+
+AggregatorName = Literal[
+    "count",
+    "countDistinct",
+    "sum",
+    "avg",
+    "min",
+    "max",
+    "first",
+    "last",
+    "push",
+    "addToSet",
+]
+"""Allowed aggregator names for relations (Konecty schema)."""
+
+FilterMatch = Literal["and", "or"]
+SortDirection = Literal["ASC", "DESC"]
+
+# Value in a filter condition: scalar or list (e.g. for "in" operator)
+ConditionValue = Union[str, int, float, bool, None, List[Union[str, int, float, bool]]]
+
+
+# ---------------------------------------------------------------------------
+# Filter (KonFilter)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=False)
+class QueryFilterCondition:
+    """Single condition: term, operator, optional value. Mirrors Konecty Condition."""
+
+    term: str
+    operator: str
+    value: Optional[ConditionValue] = None
+    editable: Optional[bool] = None
+    disabled: Optional[bool] = None
+    sort: Optional[int] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"term": self.term, "operator": self.operator}
+        if self.value is not None:
+            out["value"] = self.value
+        if self.editable is not None:
+            out["editable"] = self.editable
+        if self.disabled is not None:
+            out["disabled"] = self.disabled
+        if self.sort is not None:
+            out["sort"] = self.sort
+        return out
+
+
+@dataclass(frozen=False)
+class QueryFilter:
+    """Filter for query or relation. match + conditions; optional textSearch and nested filters."""
+
+    match: FilterMatch = "and"
+    conditions: List[QueryFilterCondition] = field(default_factory=list)
+    text_search: Optional[str] = None
+    filters: Optional[List["QueryFilter"]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"match": self.match}
+        if self.conditions:
+            out["conditions"] = [c.to_dict() for c in self.conditions]
+        if self.text_search is not None:
+            out["textSearch"] = self.text_search
+        if self.filters:
+            out["filters"] = [f.to_dict() for f in self.filters]
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Sort
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class QuerySortItem:
+    """Sort item: property and direction. Konecty sort element."""
+
+    property: str
+    direction: SortDirection = "ASC"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"property": self.property, "direction": self.direction}
+
+
+# ---------------------------------------------------------------------------
+# Join (explicit on)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ExplicitJoinCondition:
+    """Explicit join: left and right keys. Optional in relation."""
+
+    left: str
+    right: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"left": self.left, "right": self.right}
+
+
+# ---------------------------------------------------------------------------
+# Aggregator
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class AggregatorSpec:
+    """Aggregator in a relation. aggregator (name); field required for countDistinct and similar."""
+
+    aggregator: AggregatorName
+    field: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"aggregator": self.aggregator}
+        if self.field is not None:
+            out["field"] = self.field
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Relation (nested)
+# ---------------------------------------------------------------------------
+
+# Sort in relation: list of QuerySortItem or single string (e.g. "_createdAt DESC")
+RelationSort = Union[List[QuerySortItem], str]
+
+
+@dataclass(frozen=False)
+class QueryRelation:
+    """
+    Relation in a cross-module query. document + lookup; at least one aggregator required.
+    Optional: on, filter, fields, sort, limit, start; optional nested relations.
+    """
+
+    document: str
+    lookup: str
+    aggregators: Dict[str, AggregatorSpec]
+    on: Optional[ExplicitJoinCondition] = None
+    filter: Optional[QueryFilter] = None
+    fields: Optional[str] = None
+    sort: Optional[RelationSort] = None
+    limit: int = 1000
+    start: int = 0
+    relations: Optional[List["QueryRelation"]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        if not self.aggregators:
+            raise ValueError("At least one aggregator is required per relation")
+        out: Dict[str, Any] = {
+            "document": self.document,
+            "lookup": self.lookup,
+            "aggregators": {k: v.to_dict() for k, v in self.aggregators.items()},
+            "limit": self.limit,
+            "start": self.start,
+        }
+        if self.on is not None:
+            out["on"] = self.on.to_dict()
+        if self.filter is not None:
+            out["filter"] = self.filter.to_dict()
+        if self.fields is not None:
+            out["fields"] = self.fields
+        if self.sort is not None:
+            if isinstance(self.sort, str):
+                out["sort"] = self.sort
+            else:
+                out["sort"] = [s.to_dict() for s in self.sort]
+        if self.relations:
+            out["relations"] = [r.to_dict() for r in self.relations]
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Root query (CrossModuleQuery)
+# ---------------------------------------------------------------------------
+
+# Sort at root: list of QuerySortItem or string
+QuerySort = Union[List[QuerySortItem], str]
+
+# Limits (Konecty constants)
+MAX_RELATION_LIMIT_QUERY = 100_000
+DEFAULT_PRIMARY_LIMIT_QUERY = 1000
+
+
+@dataclass(frozen=False)
+class QueryJson:
+    """
+    Fully-typed body for POST /rest/query/json. Primary document + optional filter,
+    fields, sort, limit, start, relations, groupBy, aggregators, includeTotal, includeMeta.
+    Use to_dict() to get the API payload (camelCase where required).
+    """
+
+    document: str
+    filter: Optional[QueryFilter] = None
+    fields: Optional[str] = None
+    sort: Optional[QuerySort] = None
+    limit: int = DEFAULT_PRIMARY_LIMIT_QUERY
+    start: int = 0
+    relations: List[QueryRelation] = field(default_factory=list)
+    group_by: List[str] = field(default_factory=list)
+    aggregators: Dict[str, AggregatorSpec] = field(default_factory=dict)
+    include_total: bool = True
+    include_meta: bool = False
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Payload for POST /rest/query/json (camelCase for includeTotal, includeMeta, groupBy)."""
+        out: Dict[str, Any] = {
+            "document": self.document,
+            "limit": max(1, min(self.limit, MAX_RELATION_LIMIT_QUERY)),
+            "start": max(0, self.start),
+            "relations": [r.to_dict() for r in self.relations],
+            "groupBy": self.group_by,
+            "aggregators": {k: v.to_dict() for k, v in self.aggregators.items()},
+            "includeTotal": self.include_total,
+            "includeMeta": self.include_meta,
+        }
+        if self.filter is not None:
+            out["filter"] = self.filter.to_dict()
+        if self.fields is not None:
+            out["fields"] = self.fields
+        if self.sort is not None:
+            if isinstance(self.sort, str):
+                out["sort"] = self.sort
+            else:
+                out["sort"] = [s.to_dict() for s in self.sort]
+        return out

KonectySdkPython/lib/file_manager.py

@@ -0,0 +1,248 @@
+import logging
+from os import path, unlink
+from typing import AsyncGenerator, Optional, Union
+from urllib.parse import quote, urlparse
+
+import aiohttp
+
+
+class FileManager:
+    """
+    Handles file operations such as reading files as bytes and validating file existence.
+    Designed for use with KonectyClient and other components needing file manipulation.
+    """
+
+    DEFAULT_TIMEOUT = 60
+
+    def __init__(self, base_url: str, headers: dict) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.headers = headers
+        self.logger = logging.getLogger("konecty.file_manager")
+
+    async def upload_file(
+        self,
+        module: str,
+        record_code: str,
+        field_name: str,
+        file: Union[bytes, str, AsyncGenerator[bytes, None]],
+        file_name: Optional[str],
+        file_type: Optional[str],
+    ) -> dict:
+        """
+        Upload a file to Konecty. Only bytes or a URL (str) are accepted or a Stream (AsyncGenerator[bytes, None]).
+        If a URL is provided, the file will be streamed and uploaded.
+        Args:
+            module (str): Nome do módulo.
+            record_code (str): Código do registro.
+            field_name (str): Nome do campo.
+            file (bytes | str | AsyncGenerator[bytes, None]): Arquivo a ser enviado (bytes) ou URL (str) ou Stream (AsyncGenerator[bytes, None]).
+            file_name (Optional[str]): Nome do arquivo (obrigatório se file for bytes, opcional se for URL).
+        Returns:
+            dict: Resposta JSON da API.
+        Raises:
+            aiohttp.ClientError, ValueError, TypeError
+        """
+        import aiohttp
+        url = self._build_upload_url(module, record_code, field_name)
+        form = await self.build_multipart_form(file, file_name, file_type)
+
+        async with aiohttp.ClientSession() as session:
+            client_timeout = aiohttp.ClientTimeout(total=self.DEFAULT_TIMEOUT)
+            try:
+                async with session.post(url, data=form, headers=self.headers, timeout=client_timeout) as response:
+                    response.raise_for_status()
+                    return await response.json()
+            except aiohttp.ClientError as e:
+                raise
+
+    def _build_upload_url(
+        self,
+        module: str,
+        record_code: str,
+        field_name: str,
+    ) -> str:
+        if not all([module, record_code, field_name]):
+            raise ValueError("All parameters (module, record_code, field_name) must be provided.")
+        # URL encode each path segment
+        module_enc = quote(str(module), safe="")
+        record_code_enc = quote(str(record_code), safe="")
+        field_name_enc = quote(str(field_name), safe="")
+
+        return f"{self.base_url}/rest/file/upload/ns/access/{module_enc}/{record_code_enc}/{field_name_enc}"
+
+    async def build_multipart_form(
+        self,
+        file: Union[bytes, str, AsyncGenerator[bytes, None]],
+        file_name: Optional[str] = None,
+        file_type: Optional[str] = None,
+    ) -> "aiohttp.FormData":
+        file_bytes, name = await self.prepare_file_data(file, file_name)
+        import aiohttp
+        form = aiohttp.FormData()
+        form.add_field(
+            "file",
+            file_bytes,
+            filename=name,
+            content_type=file_type,
+        )
+        return form
+
+    async def prepare_file_data(
+        self,
+        file: Union[bytes, str, AsyncGenerator[bytes, None]],
+        file_name: Optional[str] = None,
+    ) -> tuple[bytes, str]:
+        """
+        Prepara os dados do arquivo para inclusão em um request multipart.
+        Args:
+            file (bytes | str): Conteúdo em bytes ou URL.
+            file_name (Optional[str]): Nome do arquivo (obrigatório se file for bytes, opcional se for URL).
+        Returns:
+            tuple[bytes, str, str]: (conteúdo em bytes, nome do arquivo, content-type)
+        Raises:
+            ValueError: Se file_name não for fornecido quando file for bytes.
+            TypeError: Se file não for bytes ou str.
+        """
+
+        if isinstance(file, bytes):
+            if not file_name:
+                raise ValueError("file_name must be provided when uploading bytes")
+            file_bytes = file
+            name = file_name
+        elif isinstance(file, AsyncGenerator):
+            # Save the file stream to a temporary file and read it
+            temp_file_name = f"/app/logs/{file_name}"
+            with open(temp_file_name, "wb") as temp_file:
+                async for chunk in file:
+                    self.logger.info(f"Chunk: {len(chunk)}")
+                    temp_file.write(chunk)
+
+            with open(temp_file_name, "rb") as temp_file:
+                file_bytes = temp_file.read()
+
+            unlink(temp_file_name)
+            name = file_name or temp_file.name
+        elif isinstance(file, str):
+            # Treat as URL
+            async with aiohttp.ClientSession() as session:
+                async with session.get(file) as resp:
+                    resp.raise_for_status()
+                    file_bytes = await resp.read()
+                    # Use file_name if provided, else extract from URL
+                    if file_name:
+                        name = file_name
+                    else:
+                        parsed = urlparse(file)
+                        name = path.basename(parsed.path) or "downloaded_file"
+        else:
+            raise TypeError("file must be bytes or a URL string")
+        # content_type, _ = mimetypes.guess_type(name)
+        # if not content_type:
+        #     content_type = "application/octet-stream"
+        return file_bytes, name
+
+    def get_auth_headers(self, headers: dict) -> dict:
+        if not headers or "Authorization" not in headers:
+            raise ValueError("Authorization header is required for file upload.")
+        return dict(headers)
+
+    async def upload_file_post(
+        self,
+        module: str,
+        record_code: str,
+        field_name: str,
+        file: Union[bytes, str],
+        file_name: Optional[str],
+        timeout: int = 60,
+    ) -> "aiohttp.ClientResponse":
+        import aiohttp
+        url = self._build_upload_url(module, record_code, field_name)
+        form = await self.build_multipart_form(file, file_name)
+        async with aiohttp.ClientSession() as session:
+            try:
+                client_timeout = aiohttp.ClientTimeout(total=timeout)
+                async with session.post(url, data=form, headers=self.headers, timeout=client_timeout) as response:
+                    response.raise_for_status()
+                    return response
+            except aiohttp.ClientError as e:
+                raise
+
+    async def parse_json_response(self, response: aiohttp.ClientResponse) -> dict:
+        try:
+            return await response.json()
+        except Exception as exc:
+            try:
+                text = await response.text()
+            except Exception:
+                text = "<erro ao obter texto da resposta>"
+            raise ValueError(f"Falha ao decodificar JSON da resposta: {exc}. Resposta original: {text}") from exc 
+
+    def handle_error_response(self, response_json: dict) -> None:
+        errors = response_json.get("errors", [])
+        if not errors:
+            raise FileManagerUnknownError("Erro desconhecido: resposta sem array 'errors'", details=response_json)
+        
+        error_message = ",\n ".join(error.get("message", "Erro desconhecido") for error in errors)
+        raise FileManagerUnknownError(error_message, details=errors[0])
+
+    async def process_api_response(self, response: aiohttp.ClientResponse) -> str:
+        """
+        Wrapper de alto nível para processar resposta de API, tratando todos os cenários de erro e sucesso.
+
+        Args:
+            response (aiohttp.ClientResponse): Resposta HTTP da API.
+
+        Returns:
+            str: Valor do campo 'key' em caso de sucesso.
+
+        Raises:
+            FileManagerAPIError: Para erros conhecidos de API.
+            ValueError: Para erros de parsing ou formato inesperado.
+        """
+        import logging
+        logger = logging.getLogger("konecty.file_manager")
+        try:
+            response_json = await self.parse_json_response(response)
+        except Exception as exc:
+            logger.error(f"Erro ao parsear resposta JSON: {exc}")
+            raise
+        try:
+            if response_json.get("success", False):
+                key = response_json.get("key")
+                if not key:
+                    raise FileManagerUnknownError("Campo 'key' ausente ou vazio na resposta de sucesso.", details=response_json)
+                return key
+            else:
+                self.handle_error_response(response_json)
+                # Se não lançar, garantir raise
+                raise FileManagerUnknownError(
+                    "Resposta de erro não mapeada corretamente.", details=response_json
+                )
+        except FileManagerAPIError as api_exc:
+            logger.error(f"Erro de API: {api_exc}")
+            raise
+        except Exception as exc:
+            logger.error(f"Erro inesperado ao processar resposta: {exc}")
+            raise FileManagerUnknownError(f"Erro inesperado ao processar resposta: {exc}", details=getattr(exc, 'details', None)) from exc
+
+class FileManagerAPIError(Exception):
+    """Exceção base para erros de API do FileManager."""
+    def __init__(self, message: str, details: dict | None = None) -> None:
+        super().__init__(message)
+        self.details = details or {}
+
+class FileManagerValidationError(FileManagerAPIError):
+    """Exceção para erros de validação de entrada."""
+    pass
+
+class FileManagerAuthError(FileManagerAPIError):
+    """Exceção para erros de autenticação."""
+    pass
+
+class FileManagerServerError(FileManagerAPIError):
+    """Exceção para erros de servidor/backend."""
+    pass
+
+class FileManagerUnknownError(FileManagerAPIError):
+    """Exceção para erros inesperados/desconhecidos."""
+    pass