konecty_sdk_python 2.1.1__py3-none-any.whl

KonectySdkPython/lib/filters.py

@@ -0,0 +1,155 @@
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, Field
+
+
+class FilterMatch(str, Enum):
+    """Tipo de correspondência do filtro."""
+
+    AND = "and"
+    OR = "or"
+
+
+class FilterOperator(str, Enum):
+    """Operadores disponíveis para filtros."""
+
+    EQUALS = "equals"
+    NOT_EQUALS = "not_equals"
+    STARTS_WITH = "starts_with"
+    END_WITH = "end_with"
+    CONTAINS = "contains"
+    NOT_CONTAINS = "not_contains"
+    LESS_THAN = "less_than"
+    GREATER_THAN = "greater_than"
+    LESS_OR_EQUALS = "less_or_equals"
+    GREATER_OR_EQUALS = "greater_or_equals"
+    BETWEEN = "between"
+    IN = "in"
+    NOT_IN = "not_in"
+    EXISTS = "exists"
+
+
+class DateValue(BaseModel):
+    """Valor de data para filtros."""
+
+    date: datetime
+
+
+class BetweenValue(BaseModel):
+    """Valor para filtros do tipo between."""
+
+    greater_or_equals: Union[int, float, DateValue, datetime, None]
+    less_or_equals: Union[int, float, DateValue, datetime, None]
+
+
+class FilterCondition(BaseModel):
+    """Condição de filtro."""
+
+    term: str = Field(..., description="Campo a ser filtrado")
+    operator: FilterOperator = Field(..., description="Operador de comparação")
+    value: Any = Field(..., description="Valor para comparação")
+    disabled: bool = Field(False, description="Se a condição está desativada")
+
+
+class KonectyFilter(BaseModel):
+    """Filtro Konecty."""
+
+    match: FilterMatch = Field(FilterMatch.AND, description="Tipo de correspondência")
+    conditions: List[FilterCondition] = Field(default_factory=list, description="Lista de condições")
+    filters: List["KonectyFilter"] = Field(default_factory=list, description="Lista de filtros aninhados")
+
+    def to_json(self) -> Dict[str, Any]:
+        """Converte o filtro para formato JSON."""
+        return self.model_dump(mode="json")
+    
+    def is_empty(self) -> bool:
+        """Verifica se o filtro está vazio."""
+        return len(self.conditions) == 0 and len(self.filters) == 0
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "KonectyFilter":
+        """Converte dicionário para filtro."""
+        return cls(**data)
+
+    @classmethod
+    def create(cls, match: Union[FilterMatch, str] = FilterMatch.AND) -> "KonectyFilter":
+        """Cria uma nova instância de filtro.
+
+        Args:
+            match: Tipo de correspondência ("and" ou "or")
+
+        Returns:
+            Nova instância de KonectyFilter
+        """
+        if isinstance(match, str):
+            match = FilterMatch(match.lower())
+        return cls(match=match)
+
+    def add_condition(
+        self, term: str, operator: Union[FilterOperator, str], value: Any, disabled: bool = False
+    ) -> "KonectyFilter":
+        """Adiciona uma condição ao filtro.
+
+        Args:
+            term: Campo a ser filtrado
+            operator: Operador de comparação
+            value: Valor para comparação
+            disabled: Se a condição está desativada
+
+        Returns:
+            Self para encadeamento
+        """
+        if isinstance(operator, str):
+            operator = FilterOperator(operator.lower())
+
+        self.conditions.append(
+            FilterCondition(
+                term=term,
+                operator=operator,
+                value=value,
+                disabled=disabled,
+            )
+        )
+        return self
+
+    def add_filter(self, match: Union[FilterMatch, str] = FilterMatch.AND) -> "KonectyFilter":
+        """Adiciona um filtro aninhado.
+
+        Args:
+            match: Tipo de correspondência do filtro aninhado
+
+        Returns:
+            Novo filtro aninhado
+        """
+        if isinstance(match, str):
+            match = FilterMatch(match.lower())
+
+        nested_filter = KonectyFilter(match=match)
+        self.filters.append(nested_filter)
+        return nested_filter
+
+
+class SortDirection(str, Enum):
+    """Direção da ordenação."""
+
+    ASC = "ASC"
+    DESC = "DESC"
+
+
+class SortOrder(BaseModel):
+    """Ordenação de resultados."""
+
+    property: str = Field(..., description="Campo para ordenação")
+    direction: SortDirection = Field(..., description="Direção da ordenação")
+
+
+class KonectyFindParams(BaseModel):
+    """Parâmetros para busca no Konecty."""
+
+    filter: KonectyFilter
+    start: Optional[int] = None
+    limit: Optional[int] = None
+    sort: Optional[List[SortOrder]] = None
+    fields: Optional[List[Union[str, int]]] = None

KonectySdkPython/lib/http.py

@@ -0,0 +1,95 @@
+"""HTTP helpers for Konecty API requests. Used by KonectyClient and services."""
+
+import logging
+from typing import Any, Dict, Optional, Union
+
+import aiohttp
+
+from .exceptions import KonectyAPIError
+
+logger = logging.getLogger(__name__)
+
+
+class StreamResponse:
+    """
+    Wrapper for streaming HTTP response. Caller can read headers and iterate body by line.
+    Must be used as async context manager so the session and response are closed on exit.
+    """
+
+    __slots__ = ("_session", "_response")
+
+    def __init__(self, session: aiohttp.ClientSession, response: aiohttp.ClientResponse) -> None:
+        self._session = session
+        self._response = response
+
+    @property
+    def headers(self) -> Dict[str, str]:
+        return dict(self._response.headers)
+
+    async def readline(self) -> bytes:
+        """Read one line (including newline). Returns empty bytes when done."""
+        return await self._response.content.readline()
+
+    async def __aenter__(self) -> "StreamResponse":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self._response.release()
+        await self._session.close()
+
+
+async def request(
+    client: Any,
+    method: str,
+    path: str,
+    *,
+    params: Optional[Dict[str, Any]] = None,
+    json: Optional[Dict[str, Any]] = None,
+    stream: bool = False,
+    return_bytes: bool = False,
+) -> Union[Dict[str, Any], StreamResponse, bytes]:
+    """
+    Perform an HTTP request using the client's base_url and headers.
+
+    Args:
+        client: KonectyClient (must have base_url and headers).
+        method: HTTP method (GET, POST, PUT, DELETE, etc.).
+        path: Path (e.g. /rest/data/Contact/find). Must not include base_url.
+        params: Optional query parameters.
+        json: Optional JSON body.
+        stream: If True, return StreamResponse for reading body by line; do not parse JSON.
+        return_bytes: If True (and not stream), return response body as bytes; do not parse JSON.
+
+    Returns:
+        If stream=True: StreamResponse (use as async with). Has .headers and .readline().
+        If return_bytes=True: bytes.
+        Else: parsed JSON dict. Raises KonectyAPIError if success is false.
+    """
+    url = f"{client.base_url.rstrip('/')}{path}"
+    kwargs: Dict[str, Any] = {"headers": client.headers}
+    if params is not None:
+        kwargs["params"] = params
+    if json is not None:
+        kwargs["json"] = json
+
+    if stream:
+        session = aiohttp.ClientSession()
+        response = await session.request(method, url, **kwargs)
+        response.raise_for_status()
+        return StreamResponse(session, response)
+
+    async with aiohttp.ClientSession() as session:
+        async with session.request(method, url, **kwargs) as response:
+            if return_bytes:
+                response.raise_for_status()
+                return await response.read()
+            body = await response.json()
+            if response.status >= 400:
+                errors = body.get("errors", []) if isinstance(body, dict) else []
+                logger.error("API error %s: %s", response.status, errors)
+                raise KonectyAPIError(errors)
+            if isinstance(body, dict) and body.get("success") is False:
+                errors = body.get("errors", [])
+                logger.error(errors)
+                raise KonectyAPIError(errors)
+            return body

KonectySdkPython/lib/model.py

@@ -0,0 +1,88 @@
+from typing import Any, Dict, List, Optional, Type, TypeVar, cast
+
+from pydantic import BaseModel, Field, create_model
+from pydantic.fields import FieldInfo
+
+from .types import (
+    Address,
+    KonectyDateTime,
+    KonectyEmail,
+    KonectyLookup,
+    KonectyPersonName,
+    KonectyPhone,
+)
+
+T = TypeVar("T")
+ModelType = TypeVar("ModelType", bound=BaseModel)
+
+
+class KonectyModelGenerator:
+    def __init__(self, schema: Dict[str, Any]):
+        self.schema = schema
+        self.type_mapping: Dict[str, Type[Any]] = {
+            "json": dict,
+            "richText": str,
+            "lookup": KonectyLookup,
+            "picklist": str,
+            "url": str,
+            "boolean": bool,
+            "text": str,
+            "dateTime": KonectyDateTime,
+            "address": Address,
+            "email": KonectyEmail,
+            "phone": KonectyPhone,
+            "personName": KonectyPersonName,
+        }
+
+    def generate_model(self, language: str = "en") -> Type[BaseModel]:
+        fields: Dict[str, tuple[Type[Any], FieldInfo]] = {}
+        for field in self.schema["fields"]:
+            field_name = field["name"]
+            field_raw_type = field["type"]
+            description = (
+                field["help"].get(language, field["help"].get("en", ""))
+                if "help" in field
+                else field["label"].get(language, field["label"].get("en", ""))
+            )
+
+            base_type = self._get_field_type(field_raw_type)
+            current_type = base_type
+
+            if field.get("isList"):
+                current_type = List[base_type]  # type: ignore
+
+            if field.get("minSelected", 1) > 1 or field.get("maxSelected", 1) > 1:
+                current_type = List[base_type]  # type: ignore
+
+            is_required = (
+                field.get("isRequired", False) or field.get("minSelected", 0) > 0
+            )
+
+            if not is_required and "defaultValue" not in field:
+                current_type = Optional[base_type]  # type: ignore
+
+            field_params = {
+                "alias": field_name,
+                "description": description,
+            }
+
+            if "defaultValue" in field:
+                field_params["default"] = field["defaultValue"]
+
+            if not is_required and "defaultValue" not in field:
+                field_params["default"] = None
+
+            fields[self._clean_name_for_pydantic(field_name)] = (
+                current_type,
+                Field(**field_params),
+            )
+
+        model_name = self.schema["name"]
+        return create_model(model_name, **fields)
+
+    def _clean_name_for_pydantic(self, name: str) -> str:
+        return name.replace("_", "")
+
+    def _get_field_type(self, field_type: str) -> Type[Any]:
+        result = self.type_mapping.get(field_type, Any)
+        return cast(Type[Any], result)

KonectySdkPython/lib/serialization.py

@@ -0,0 +1,13 @@
+"""JSON serialization helpers for Konecty API (e.g. $date format)."""
+
+from datetime import datetime
+from typing import Any
+
+from .exceptions import KonectySerializationError
+
+
+def json_serial(obj: Any) -> Any:
+    """Serialize objects to JSON-friendly form (e.g. datetime -> $date)."""
+    if isinstance(obj, datetime):
+        return {"$date": obj.isoformat()}
+    raise KonectySerializationError()

KonectySdkPython/lib/services/__init__.py

@@ -0,0 +1,5 @@
+"""Services for Konecty API domains. Used by KonectyClient."""
+
+from .base import BaseService
+
+__all__ = ["BaseService"]

KonectySdkPython/lib/services/aggregation.py

@@ -0,0 +1,142 @@
+"""Aggregation API: KPI, Graph, Pivot."""
+
+import json
+from typing import Any, Dict, Optional, Union
+
+from ..serialization import json_serial
+from ..filters import KonectyFilter
+from ..feature_types.kpi import KpiConfig
+from .base import BaseService
+
+
+class AggregationService(BaseService):
+    """Service for KPI, Graph, and Pivot aggregations."""
+
+    async def get_kpi(
+        self,
+        module: str,
+        kpi_config: KpiConfig,
+        *,
+        filter_params: Optional[KonectyFilter] = None,
+        display_name: Optional[str] = None,
+        display_type: Optional[str] = None,
+        sort: Optional[Any] = None,
+        limit: Optional[int] = None,
+        start: Optional[int] = None,
+        with_detail_fields: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """
+        Run KPI aggregation. GET /rest/data/{module}/kpi. Returns { value, count }.
+        """
+        params: Dict[str, str] = {
+            "kpiConfig": json.dumps(kpi_config.model_dump(exclude_none=True)),
+        }
+        if filter_params is not None:
+            params["filter"] = json.dumps(filter_params.to_json(), default=json_serial)
+        if display_name is not None:
+            params["displayName"] = display_name
+        if display_type is not None:
+            params["displayType"] = display_type
+        if sort is not None:
+            params["sort"] = json.dumps(sort, default=json_serial) if not isinstance(sort, str) else sort
+        if limit is not None:
+            params["limit"] = str(limit)
+        if start is not None:
+            params["start"] = str(start)
+        if with_detail_fields is not None:
+            params["withDetailFields"] = "1" if with_detail_fields else "0"
+        path = f"/rest/data/{module}/kpi"
+        result = await self._get(path, params=params)
+        if isinstance(result, dict) and result.get("success"):
+            return {"value": result.get("value", 0), "count": result.get("count", 0)}
+        return {"value": 0, "count": 0}
+
+    async def get_graph(
+        self,
+        module: str,
+        graph_config: Union[Dict[str, Any], Any],
+        *,
+        filter_params: Optional[KonectyFilter] = None,
+        display_name: Optional[str] = None,
+        display_type: Optional[str] = None,
+        sort: Optional[Any] = None,
+        limit: Optional[int] = None,
+        start: Optional[int] = None,
+        with_detail_fields: Optional[bool] = None,
+        lang: Optional[str] = None,
+    ) -> str:
+        """
+        Get graph as SVG. GET /rest/data/{module}/graph. graphConfig: type, xAxis, yAxis, series, etc.
+        """
+        payload = (
+            graph_config.model_dump(by_alias=True, exclude_none=True)
+            if hasattr(graph_config, "model_dump")
+            else graph_config
+        )
+        params: Dict[str, str] = {"graphConfig": json.dumps(payload)}
+        if filter_params is not None:
+            params["filter"] = json.dumps(filter_params.to_json(), default=json_serial)
+        if display_name is not None:
+            params["displayName"] = display_name
+        if display_type is not None:
+            params["displayType"] = display_type
+        if sort is not None:
+            params["sort"] = json.dumps(sort, default=json_serial) if not isinstance(sort, str) else sort
+        if limit is not None:
+            params["limit"] = str(limit)
+        if start is not None:
+            params["start"] = str(start)
+        if with_detail_fields is not None:
+            params["withDetailFields"] = "1" if with_detail_fields else "0"
+        if lang is not None:
+            params["lang"] = lang
+        path = f"/rest/data/{module}/graph"
+        raw = await self._get(path, params=params, return_bytes=True)
+        if isinstance(raw, bytes):
+            return raw.decode("utf-8")
+        return str(raw)
+
+    async def get_pivot(
+        self,
+        module: str,
+        pivot_config: Union[Dict[str, Any], Any],
+        *,
+        filter_params: Optional[KonectyFilter] = None,
+        display_name: Optional[str] = None,
+        display_type: Optional[str] = None,
+        sort: Optional[Any] = None,
+        limit: Optional[int] = None,
+        start: Optional[int] = None,
+        with_detail_fields: Optional[bool] = None,
+        lang: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Get pivot table result. GET /rest/data/{module}/pivot. pivotConfig: rows, columns, values.
+        """
+        payload = (
+            pivot_config.model_dump(by_alias=True, exclude_none=True)
+            if hasattr(pivot_config, "model_dump")
+            else pivot_config
+        )
+        params: Dict[str, str] = {"pivotConfig": json.dumps(payload)}
+        if filter_params is not None:
+            params["filter"] = json.dumps(filter_params.to_json(), default=json_serial)
+        if display_name is not None:
+            params["displayName"] = display_name
+        if display_type is not None:
+            params["displayType"] = display_type
+        if sort is not None:
+            params["sort"] = json.dumps(sort, default=json_serial) if not isinstance(sort, str) else sort
+        if limit is not None:
+            params["limit"] = str(limit)
+        if start is not None:
+            params["start"] = str(start)
+        if with_detail_fields is not None:
+            params["withDetailFields"] = "1" if with_detail_fields else "0"
+        if lang is not None:
+            params["lang"] = lang
+        path = f"/rest/data/{module}/pivot"
+        result = await self._get(path, params=params)
+        if isinstance(result, dict):
+            return result
+        return {}

KonectySdkPython/lib/services/auth.py

@@ -0,0 +1,105 @@
+"""Auth API: Google hosted authorization code flow and login options."""
+
+from typing import Any, Dict, Optional, Union
+from urllib.parse import quote, urlencode
+
+from ..exceptions import KonectyAPIError
+from .base import BaseService
+
+GOOGLE_START_PATH = "/api/auth/google/start"
+# Conjunto que `encodeURIComponent` deixa passar além de [A-Za-z0-9_.-~], que o
+# `quote` já preserva por padrão. Usado para que a URL montada aqui seja
+# byte a byte igual à do SDK TypeScript — ver `_encode_query` abaixo.
+_ENCODE_URI_COMPONENT_SAFE = "!*'()"
+GOOGLE_SESSION_PATH = "/api/auth/google/session"
+LOGIN_OPTIONS_PATH = "/api/auth/login-options"
+
+
+def _first_error_message(error: KonectyAPIError) -> str:
+    """Extract errors[0].message from a KonectyAPIError raised by the HTTP layer."""
+    errors = error.args[0] if error.args else None
+    if isinstance(errors, list) and errors:
+        first = errors[0]
+        if isinstance(first, dict):
+            message = first.get("message")
+            if isinstance(message, str) and message:
+                return message
+    return str(error)
+
+
+def _encode_query(params: list) -> str:
+    """
+    Codifica o query string como `encodeURIComponent` do SDK TypeScript.
+
+    O default do `urlencode` é `quote_plus`, que transforma espaço em `+`;
+    `encodeURIComponent` produz `%20`. Os dois decodificam para o mesmo valor no
+    servidor, mas a spec pede URLs idênticas entre os SDKs.
+    """
+    return urlencode(params, quote_via=quote, safe=_ENCODE_URI_COMPONENT_SAFE)
+
+
+class AuthService(BaseService):
+    """Service for the Google login flow (authorization code hosted by Konecty)."""
+
+    def google_login_url(
+        self,
+        client_id: str,
+        redirect_uri: Optional[str] = None,
+        state: Optional[str] = None,
+    ) -> str:
+        """
+        Build the absolute URL of GET /api/auth/google/start. Does not perform any request.
+
+        The browser follows this URL; Konecty redirects to accounts.google.com and,
+        after consent, back to redirect_uri with a single-use code (and the original state).
+        """
+        params = [("client_id", client_id)]
+        if redirect_uri is not None:
+            params.append(("redirect_uri", redirect_uri))
+        if state is not None:
+            params.append(("state", state))
+        base_url = self._client.base_url.rstrip("/")
+        return f"{base_url}{GOOGLE_START_PATH}?{_encode_query(params)}"
+
+    async def exchange_google_code(
+        self,
+        code: str,
+        *,
+        geolocation: Optional[Union[Dict[str, Any], str]] = None,
+        resolution: Optional[Union[Dict[str, Any], str]] = None,
+        source: Optional[str] = None,
+        fingerprint: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        POST /api/auth/google/session. Exchanges the single-use code (TTL 60s) for a session.
+
+        On success the returned authId is adopted by the client, so following requests
+        are authenticated. On error raises KonectyAPIError with errors[0].message and
+        leaves the client authentication state untouched.
+        """
+        payload: Dict[str, Any] = {"code": code}
+        if geolocation is not None:
+            payload["geolocation"] = geolocation
+        if resolution is not None:
+            payload["resolution"] = resolution
+        if source is not None:
+            payload["source"] = source
+        if fingerprint is not None:
+            payload["fingerprint"] = fingerprint
+
+        try:
+            response = await self._post(GOOGLE_SESSION_PATH, json=payload)
+        except KonectyAPIError as error:
+            raise KonectyAPIError(_first_error_message(error)) from error
+
+        auth_id = response.get("authId") if isinstance(response, dict) else None
+        if not isinstance(auth_id, str) or not auth_id:
+            raise KonectyAPIError("Google session response has no authId")
+
+        self._client.set_auth_id(auth_id)
+        return response
+
+    async def get_login_options(self) -> Dict[str, Any]:
+        """GET /api/auth/login-options. Flags: passwordEnabled, emailOtpEnabled,
+        whatsAppOtpEnabled, webauthnEnabled, webauthnRequired, googleEnabled."""
+        return await self._get(LOGIN_OPTIONS_PATH)

KonectySdkPython/lib/services/base.py

@@ -0,0 +1,63 @@
+"""Base service class. All domain services inherit from it and delegate HTTP to the client."""
+
+from typing import Any, Dict, Optional, TypeVar
+
+Client = TypeVar("Client", bound=Any)
+
+
+class BaseService:
+    """Base for all Konecty API services. Exposes _get, _post, _put, _delete via client._request."""
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    async def _get(
+        self,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        stream: bool = False,
+        return_bytes: bool = False,
+    ) -> Any:
+        return await self._client._request(
+            "GET", path, params=params, stream=stream, return_bytes=return_bytes
+        )
+
+    async def _post(
+        self,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        stream: bool = False,
+    ) -> Any:
+        return await self._client._request(
+            "POST", path, params=params, json=json, stream=stream
+        )
+
+    async def _put(
+        self,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        return await self._client._request("PUT", path, params=params, json=json)
+
+    async def _delete(
+        self,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        return await self._client._request("DELETE", path, params=params, json=json)
+
+    async def _patch(
+        self,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        return await self._client._request("PATCH", path, params=params, json=json)