konecty-sdk-python 2.1.6__tar.gz → 2.2.0__tar.gz

{konecty_sdk_python-2.1.6 → konecty_sdk_python-2.2.0}/KonectySdkPython/lib/client.py

@@ -86,11 +86,20 @@ async def _read_json_body(response: "aiohttp.ClientResponse") -> Optional[Dict[s
     Lê o corpo como JSON sem explodir quando não é JSON (proxy, gateway, HTML).
 
     Devolve ``None`` nesse caso, e o chamador cai no tratamento por status.
+
+    Também devolve ``None`` quando o corpo é JSON válido mas **não é objeto** —
+    uma string ou lista, que é o que alguns proxies devolvem. O ``cast`` não
+    verifica nada em runtime, então sem esta checagem o chamador fazia
+    ``result.get(...)`` num ``str`` e recebia ``AttributeError`` no lugar do erro
+    de API.
     """
     try:
-        return cast(Dict[str, Any], await response.json(content_type=None))
+        body = await response.json(content_type=None)
     except Exception:  # noqa: BLE001 - corpo não-JSON é caso esperado aqui
         return None
+    if not isinstance(body, dict):
+        return None
+    return cast(Dict[str, Any], body)
 
 
 class KonectyClient:
@@ -454,10 +463,30 @@ class KonectyClient:
             fingerprint=fingerprint,
         )
 
+    async def impersonate(
+        self, user_id: Optional[str] = None, code: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """
+        Issue a support session (1 h) for another user (POST /api/auth/impersonate).
+
+        Exactly one of ``user_id`` or ``code``. Requires an admin first-party session.
+        Returns ``{"authId", "expiresAt", "user"}``; the returned authId is not adopted by
+        this client. Raises KonectyImpersonateError with a machine-readable ``code``.
+        """
+        return await self._auth.impersonate(user_id=user_id, code=code)
+
     async def get_login_options(self) -> Dict[str, Any]:
         """Get login method flags for the namespace (GET /api/auth/login-options)."""
         return await self._auth.get_login_options()
 
+    async def info(self) -> Dict[str, Any]:
+        """
+        Get the session user (GET /rest/auth/info), including ``user["redirectURL"]``.
+
+        Returns ``{"logged": False}`` without a token or when the server refuses the session.
+        """
+        return await self._auth.info()
+
     @property
     def _pat(self) -> PatService:
         if not hasattr(self, "_pat_service"):
@@ -719,7 +748,6 @@ class KonectyClient:
         if search:
             params["search"] = search
 
-        print(f"params: {params}")
         async with (
             aiohttp.ClientSession() as session,
             session.get(
@@ -728,12 +756,16 @@ class KonectyClient:
                 headers={"Authorization": self.headers["Authorization"]},
             ) as response,
         ):
-            response.raise_for_status()
-            result = await response.json()
+            # Mesma ordem do `find`: corpo primeiro, status depois. Ver `find`.
+            result = await _read_json_body(response)
+            if result is None:
+                response.raise_for_status()
+                raise KonectyAPIError(f"{response.status} {response.reason}")
             if not result.get("success", False):
                 errors = result.get("errors", [])
                 logger.error(errors)
-                raise KonectyAPIError(errors)
+                raise_for_konecty_errors(errors)
+            response.raise_for_status()
             data = result.get("data", [])
             return cast(List[KonectyDict], data)
 
@@ -784,12 +816,16 @@ class KonectyClient:
                 headers={"Authorization": self.headers["Authorization"]},
             ) as response,
         ):
-            response.raise_for_status()
-            result = await response.json()
+            # Mesma ordem do `find`: corpo primeiro, status depois. Ver `find`.
+            result = await _read_json_body(response)
+            if result is None:
+                response.raise_for_status()
+                raise KonectyAPIError(f"{response.status} {response.reason}")
             if not result.get("success", False):
                 errors = result.get("errors", [])
                 logger.error(errors)
-                raise KonectyAPIError(errors)
+                raise_for_konecty_errors(errors)
+            response.raise_for_status()
             data = result.get("data", [None])
             return get_first_dict(data)
 
@@ -1022,12 +1058,16 @@ class KonectyClient:
                 headers={"Authorization": self.headers["Authorization"]},
             ) as response,
         ):
-            response.raise_for_status()
-            result = await response.json()
+            # Mesma ordem do `find`: corpo primeiro, status depois. Ver `find`.
+            result = await _read_json_body(response)
+            if result is None:
+                response.raise_for_status()
+                raise KonectyAPIError(f"{response.status} {response.reason}")
             if not result.get("success", False):
                 errors = result.get("errors", [])
                 logger.error(errors)
-                raise KonectyAPIError(errors)
+                raise_for_konecty_errors(errors)
+            response.raise_for_status()
             count = result.get("total", 0)
             return count
 

konecty_sdk_python-2.2.0/KonectySdkPython/lib/exceptions.py

@@ -0,0 +1,279 @@
+"""Exceptions for the Konecty SDK."""
+
+from typing import Optional
+
+
+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 KonectyGoogleSessionError(KonectyAPIError):
+    """
+    Raised by exchange_google_code. Carries the machine-readable ``code`` from
+    ``errors[0].code`` so callers can branch or translate without parsing the
+    message; ``failed`` covers unreadable or unrecognised bodies.
+
+    Subclasses KonectyAPIError so existing ``except KonectyAPIError`` keeps working.
+
+    Mirrors KonectyGoogleSessionError in the TypeScript SDK — keep both in sync.
+    """
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class KonectyImpersonateError(KonectyAPIError):
+    """
+    Raised by impersonate. Carries the machine-readable ``code`` from ``errors[0].code``
+    (``IMPERSONATE_FORBIDDEN``, ``IMPERSONATE_INVALID_TARGET``,
+    ``IMPERSONATE_TARGET_NOT_FOUND``, ``IMPERSONATE_TARGET_NOT_ALLOWED``,
+    ``IMPERSONATED_SESSION_FORBIDDEN``, ``admin-credential-routes-require-session``);
+    ``failed`` covers transport errors, unreadable bodies and answers without a recognised
+    code, e.g. a plain 401. ``IMPERSONATE_INVALID_TARGET`` is also raised locally, with no
+    request, when the target does not have exactly one of ``user_id`` or ``code``.
+
+    Subclasses KonectyAPIError so existing ``except KonectyAPIError`` keeps working.
+
+    Mirrors KonectyImpersonateError in the TypeScript SDK — keep both in sync.
+    """
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+#: Código devolvido pelo Konecty quando a requisição pede ordenação arbitrária
+#: acima do teto de página. Espelha ``SORT_ABOVE_MAX_PAGE_SIZE`` no SDK
+#: TypeScript — manter os dois em sincronia.
+SORT_ABOVE_MAX_PAGE_SIZE = "SORT_ABOVE_MAX_PAGE_SIZE"
+
+#: Teto do servidor. Informativo: quem decide é a API, este valor só evita adivinhação.
+MAX_SORTED_PAGE_SIZE = 1000
+
+
+class KonectySortLimitError(KonectyAPIError):
+    """
+    Raised when the request asks for arbitrary ordering above the page cap.
+
+    Acima de ``MAX_SORTED_PAGE_SIZE`` registros — e no caso sem limite
+    (``limit=-1``) — o ``$sort`` teria de terminar antes de o primeiro documento
+    sair do cursor, então a API recusa com HTTP 400 em vez de trocar a ordenação
+    em silêncio, como fazia antes.
+
+    Carrega o ``code`` legível por máquina para o chamador ramificar sem
+    inspecionar a mensagem, como ``KonectyGoogleSessionError``. Subclasse de
+    ``KonectyAPIError``, então ``except KonectyAPIError`` existente continua
+    pegando.
+
+    A saída é ordenar por ``_id`` (ascendente ou descendente) e paginar por faixa
+    de ``_id``, ou pedir no máximo ``MAX_SORTED_PAGE_SIZE`` registros.
+
+    Espelha ``KonectySortLimitError`` no SDK TypeScript — manter os dois em sincronia.
+    """
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.code = SORT_ABOVE_MAX_PAGE_SIZE
+
+
+#: Códigos do operador de filtro ``within_radius``. Espelham as constantes de
+#: mesmo nome no SDK TypeScript (``src/sdk/filters/withinRadius.ts``) e no
+#: servidor (``src/imports/data/filters/withinRadius.ts`` no repo Konecty).
+#:
+#: Recusa de forma ou de faixa do valor: ``lat``/``lng`` (ou ``record``) ou
+#: ``radius`` ausente, as duas formas juntas, chave desconhecida, coordenada fora
+#: da faixa, string numérica no lugar de número, raio não positivo ou acima do
+#: teto do servidor.
+#: Nome do operador, usado nas mensagens default. Espelha `WITHIN_RADIUS` no SDK TS.
+WITHIN_RADIUS_OPERATOR = "within_radius"
+
+WITHIN_RADIUS_INVALID_VALUE = "WITHIN_RADIUS_INVALID_VALUE"
+
+#: O centro por referência a registro não pôde ser resolvido. Um código só para
+#: os três casos (registro inexistente, ilegível, ou sem geolocalização) é
+#: decisão do servidor: distinguí-los na resposta transformaria o filtro num
+#: oráculo de localização para quem não pode ler o registro.
+WITHIN_RADIUS_CENTER_UNRESOLVED = "WITHIN_RADIUS_CENTER_UNRESOLVED"
+
+#: A cadeia de centros por referência passou do teto de profundidade do servidor.
+#: Acontece quando um centro aponta para um registro cujo filtro de leitura tem, ele
+#: próprio, um `within_radius` com centro por referência — a resolução é recursiva e o
+#: servidor corta. Não é erro do valor enviado: é configuração de metadado do documento
+#: alvo. Espelha `WITHIN_RADIUS_CENTER_DEPTH_EXCEEDED` no SDK TS.
+WITHIN_RADIUS_CENTER_DEPTH_EXCEEDED = "WITHIN_RADIUS_CENTER_DEPTH_EXCEEDED"
+
+#: A requisição pediu mais centros por referência do que o servidor resolve de uma vez.
+#: O SDK **não** duplica o teto: quem decide é o servidor, e um número copiado aqui
+#: passaria a mentir assim que o backend mudasse. Espelha `WITHIN_RADIUS_TOO_MANY_CENTERS`
+#: no SDK TS.
+WITHIN_RADIUS_TOO_MANY_CENTERS = "WITHIN_RADIUS_TOO_MANY_CENTERS"
+
+#: Recusa de ordenação por ``_distance``: o filtro não tem exatamente um
+#: ``within_radius`` no caminho AND, ou o usuário não pode ler (ou só lê sob
+#: condição) o campo ``address`` do centro. O servidor responde HTTP 400; a mensagem
+#: diz qual dos dois casos é. Espelha ``DISTANCE_SORT_UNAVAILABLE`` no SDK TS.
+DISTANCE_SORT_UNAVAILABLE = "DISTANCE_SORT_UNAVAILABLE"
+
+
+class KonectyWithinRadiusValueError(KonectyAPIError):
+    """
+    Raised when the server refuses the shape or range of a ``within_radius`` value.
+
+    Carrega o ``code`` legível por máquina e preserva a mensagem do servidor, que
+    nomeia o termo e a chave exata que falhou. Subclasse de ``KonectyAPIError``,
+    então ``except KonectyAPIError`` existente continua pegando.
+
+    O SDK **não** duplica a validação de faixa nem o teto de raio: quem decide é
+    o servidor, e um teto copiado no cliente passa a mentir assim que o backend
+    muda. Mesma postura do ``SORT_ABOVE_MAX_PAGE_SIZE``.
+
+    Espelha ``KonectyWithinRadiusValueError`` no SDK TypeScript — manter os dois
+    em sincronia.
+    """
+
+    #: Default idêntico ao do SDK TS (`message ?? \`Invalid value for operator ${WITHIN_RADIUS}\``
+    #: em `src/sdk/filters/withinRadius.ts`), para que um erro sem `message` produza a MESMA
+    #: frase nos dois — antes o Python levantava com a string literal "None".
+    def __init__(self, message: Optional[str] = None) -> None:
+        super().__init__(
+            message or f"Invalid value for operator {WITHIN_RADIUS_OPERATOR}"
+        )
+        self.code = WITHIN_RADIUS_INVALID_VALUE
+
+
+class KonectyWithinRadiusCenterError(KonectyAPIError):
+    """
+    Raised when a ``within_radius`` center given as a record reference could not
+    be resolved — the record does not exist, is not readable, or has no geolocation.
+
+    Espelha ``KonectyWithinRadiusCenterError`` no SDK TypeScript — manter os dois
+    em sincronia.
+    """
+
+    #: Mesmo default do SDK TS — ver `KonectyWithinRadiusValueError` acima.
+    def __init__(self, message: Optional[str] = None) -> None:
+        super().__init__(
+            message
+            or f"Could not resolve the center record for operator {WITHIN_RADIUS_OPERATOR}"
+        )
+        self.code = WITHIN_RADIUS_CENTER_UNRESOLVED
+
+
+class KonectyWithinRadiusCenterDepthError(KonectyWithinRadiusCenterError):
+    """
+    Raised when the chain of center-by-reference resolutions exceeds the server depth cap.
+
+    **Herda de ``KonectyWithinRadiusCenterError`` de propósito**, como no SDK TS: é uma
+    falha de resolução de centro, e a própria mensagem do servidor começa com "Could not
+    resolve the center record". Quem escreveu ``except KonectyWithinRadiusCenterError``
+    antes deste código existir continua pegando.
+
+    Espelha ``KonectyWithinRadiusCenterDepthError`` no SDK TypeScript.
+    """
+
+    def __init__(self, message: Optional[str] = None) -> None:
+        super().__init__(
+            message
+            or f"Center hydration exceeded the maximum depth for operator {WITHIN_RADIUS_OPERATOR}"
+        )
+        self.code = WITHIN_RADIUS_CENTER_DEPTH_EXCEEDED
+
+
+class KonectyWithinRadiusTooManyCentersError(KonectyAPIError):
+    """
+    Raised when the request asks for more center records than the server resolves at once.
+
+    **NÃO** herda de ``KonectyWithinRadiusCenterError``: nenhum centro específico falhou —
+    a requisição inteira foi recusada antes de qualquer leitura. Tratar cota como falha de
+    centro levaria o chamador a procurar um registro culpado que não existe.
+
+    Espelha ``KonectyWithinRadiusTooManyCentersError`` no SDK TypeScript.
+    """
+
+    def __init__(self, message: Optional[str] = None) -> None:
+        super().__init__(
+            message
+            or f"Too many center records requested for operator {WITHIN_RADIUS_OPERATOR}"
+        )
+        self.code = WITHIN_RADIUS_TOO_MANY_CENTERS
+
+
+class KonectyDistanceSortUnavailableError(KonectyAPIError):
+    """
+    Raised when the server refuses a sort by ``_distance``.
+
+    **NÃO** herda de ``KonectySortLimitError``: não é teto de página, e a saída não é
+    ordenar por ``_id`` — é acertar o filtro (um ``within_radius`` só, no caminho AND)
+    ou a permissão de leitura do campo ``address``.
+
+    Espelha ``KonectyDistanceSortUnavailableError`` no SDK TypeScript.
+    """
+
+    #: Mesmo default do SDK TS (`src/sdk/filters/withinRadius.ts`).
+    def __init__(self, message: Optional[str] = None) -> None:
+        super().__init__(
+            message or "Sorting by _distance is not available for this query"
+        )
+        self.code = DISTANCE_SORT_UNAVAILABLE
+
+
+#: Códigos que o SDK promove a exceção própria. A tabela existe para que um
+#: código novo seja UMA linha em vez de mais um ``if`` no meio do fluxo — e para
+#: que a lista de códigos suportados seja legível de uma vez, ao lado da lista
+#: equivalente no SDK TypeScript (``ERROR_BY_CODE`` em ``src/sdk/errors.ts``).
+#:
+#: Todo código ausente daqui continua virando ``KonectyAPIError`` genérico.
+_ERROR_BY_CODE = {
+    SORT_ABOVE_MAX_PAGE_SIZE: KonectySortLimitError,
+    WITHIN_RADIUS_INVALID_VALUE: KonectyWithinRadiusValueError,
+    WITHIN_RADIUS_CENTER_UNRESOLVED: KonectyWithinRadiusCenterError,
+    WITHIN_RADIUS_CENTER_DEPTH_EXCEEDED: KonectyWithinRadiusCenterDepthError,
+    WITHIN_RADIUS_TOO_MANY_CENTERS: KonectyWithinRadiusTooManyCentersError,
+    DISTANCE_SORT_UNAVAILABLE: KonectyDistanceSortUnavailableError,
+}
+
+
+def raise_for_konecty_errors(errors: object) -> None:
+    """
+    Lança a exceção mais específica que a lista de ``errors`` da API permitir.
+
+    Existe porque os caminhos de find liam o corpo só para logar e lançavam
+    ``KonectyAPIError`` genérico — e, no caso de HTTP 400, o
+    ``response.raise_for_status()`` disparava ANTES de o corpo ser lido, então
+    nem a mensagem nem o código chegavam a quem chamou.
+    """
+    items = errors if isinstance(errors, list) else []
+    for error in items:
+        if not isinstance(error, dict):
+            continue
+        exception_class = _ERROR_BY_CODE.get(error.get("code"))
+        if exception_class is not None:
+            # `message` ausente OU `None`: cai no default da própria exceção, como o SDK
+            # TS faz (`new Klass(message ?? undefined)` usa o default do construtor).
+            # `str(None)` produziria a string literal "None" na mensagem do chamador.
+            message = error.get("message")
+            raise exception_class(message) if message else exception_class()
+
+    raise KonectyAPIError(errors)
+
+
+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")

konecty_sdk_python-2.2.0/KonectySdkPython/lib/filters.py

@@ -0,0 +1,291 @@
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Mapping, Optional, TypedDict, 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"
+    #: Busca por raio geográfico em campo de tipo ``address``. Espelha
+    #: ``WITHIN_RADIUS`` no SDK TypeScript — manter os dois em sincronia.
+    WITHIN_RADIUS = "within_radius"
+
+
+#: Campo calculado que o servidor acrescenta a cada registro devolvido por ``find``
+#: quando o filtro tem **um** centro de distância: a única condição ``within_radius``
+#: habilitada no caminho AND do filtro da requisição. Valor em **metros**, inteiro.
+#: Com zero ou duas+ condições nessa posição, ou quando o usuário não pode ler o campo
+#: ``address`` do centro, o campo simplesmente não vem — não é erro.
+#:
+#: É também o ``property`` de ordenação por distância:
+#: ``SortOrder(property=DISTANCE_FIELD, direction=SortDirection.ASC)``.
+#:
+#: Nunca é gravado: devolver o registro inteiro num ``update`` com ``_distance``
+#: dentro é recusado pelo servidor como campo inexistente.
+#:
+#: Espelha ``DISTANCE_FIELD`` no SDK TypeScript (``src/sdk/filters/withinRadius.ts``).
+DISTANCE_FIELD = "_distance"
+
+#: Referência ao registro de onde tirar o centro, em vez de coordenadas literais:
+#: "perto do empreendimento X". O servidor lê o registro sob controle de acesso
+#: completo e substitui pelas coordenadas antes de compilar a query.
+#:
+#: ``field`` é obrigatório porque um documento pode ter mais de um campo
+#: ``address`` e adivinhar seria escolher em silêncio.
+WithinRadiusCenterRef = TypedDict(
+    "WithinRadiusCenterRef",
+    {"document": str, "_id": str, "field": str},
+)
+
+
+def within_radius_condition(
+    term: str,
+    *,
+    lat: Optional[float] = None,
+    lng: Optional[float] = None,
+    record: Optional[WithinRadiusCenterRef] = None,
+    radius: float,
+) -> "FilterCondition":
+    """
+    Monta a condição de filtro do operador ``within_radius``.
+
+    O ``term`` é o campo ``address`` puro: o sufixo ``.geolocation`` é
+    acrescentado pelo SERVIDOR, não pelo cliente. O ``radius`` é em **metros**.
+    O centro é ``lat``/``lng`` **ou** ``record`` — exatamente uma das duas formas.
+
+    .. code-block:: python
+
+        within_radius_condition("address", lat=-30.0346, lng=-51.2177, radius=5000)
+        # value={"lat": -30.0346, "lng": -51.2177, "radius": 5000}
+
+        within_radius_condition(
+            "address",
+            record={"document": "Development", "_id": "<id>", "field": "address"},
+            radius=2000,
+        )
+
+    Todos os parâmetros depois de ``term`` são nomeados: a forma antiga
+    ``within_radius_condition(term, (lng, lat), radius)`` deixou de existir e
+    levanta ``TypeError``.
+
+    O SDK **não** valida faixa, teto de raio nem a exclusão mútua das formas:
+    quem decide é o servidor, e um teto copiado aqui passaria a mentir assim que
+    o backend mudasse. O que o chamador passou vai para a requisição — as duas
+    formas juntas inclusive, para o servidor recusar nomeando o problema — e
+    nada é convertido para número. Valor recusado volta como
+    ``WITHIN_RADIUS_INVALID_VALUE``.
+
+    Espelha ``withinRadiusCondition`` no SDK TypeScript — a mesma entrada produz
+    a mesma saída (travado por teste: ``tests/test_within_radius.py`` e
+    ``src/__test__/api/withinRadius.test.ts``).
+
+    A ARIDADE difere de propósito: lá é ``withinRadiusCondition(term, {lat, lng,
+    radius})``, porque o SDK TypeScript passa objeto de opções em todo lugar;
+    aqui são parâmetros nomeados, que é a convenção deste SDK. A paridade que
+    importa é mesma entrada → mesma saída, não a forma de chamar.
+    """
+    value: Dict[str, Any] = {}
+    if lat is not None:
+        value["lat"] = lat
+    if lng is not None:
+        value["lng"] = lng
+    if record is not None:
+        value["record"] = dict(record) if isinstance(record, Mapping) else record
+    value["radius"] = radius
+    return FilterCondition(
+        term=term,
+        operator=FilterOperator.WITHIN_RADIUS,
+        value=value,
+    )
+
+
+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_within_radius(
+        self,
+        term: str,
+        *,
+        lat: Optional[float] = None,
+        lng: Optional[float] = None,
+        record: Optional[WithinRadiusCenterRef] = None,
+        radius: float,
+    ) -> "KonectyFilter":
+        """Adiciona uma condição ``within_radius`` ao filtro.
+
+        Args:
+            term: Campo de tipo ``address`` (sem o sufixo ``.geolocation``)
+            lat: Latitude do centro, em ``[-90, 90]``
+            lng: Longitude do centro, em ``[-180, 180]``
+            record: Ou, no lugar de ``lat``/``lng``, a referência
+                ``{"document", "_id", "field"}`` a outro registro
+            radius: Raio em **metros**
+
+        Returns:
+            Self para encadeamento
+
+        Nota: o SDK TypeScript **não** tem equivalente disto, e é escolha: lá o
+        filtro é objeto literal, não há classe de builder nenhuma, e criar uma só
+        para este operador seria superfície pública nova sem caso de uso.
+        """
+        self.conditions.append(
+            within_radius_condition(
+                term, lat=lat, lng=lng, record=record, radius=radius
+            )
+        )
+        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

{konecty_sdk_python-2.1.6 → konecty_sdk_python-2.2.0}/KonectySdkPython/lib/services/auth.py

@@ -1,9 +1,15 @@
-"""Auth API: Google hosted authorization code flow and login options."""
+"""Auth API: Google hosted authorization code flow, login options and session info."""
 
 from typing import Any, Dict, Optional, Union
 from urllib.parse import quote, urlencode
 
-from ..exceptions import KonectyAPIError, KonectyGoogleSessionError
+import aiohttp
+
+from ..exceptions import (
+    KonectyAPIError,
+    KonectyGoogleSessionError,
+    KonectyImpersonateError,
+)
 from .base import BaseService
 
 GOOGLE_START_PATH = "/api/auth/google/start"
@@ -13,6 +19,8 @@ GOOGLE_START_PATH = "/api/auth/google/start"
 _ENCODE_URI_COMPONENT_SAFE = "!*'()"
 GOOGLE_SESSION_PATH = "/api/auth/google/session"
 LOGIN_OPTIONS_PATH = "/api/auth/login-options"
+USER_INFO_PATH = "/rest/auth/info"
+IMPERSONATE_PATH = "/api/auth/impersonate"
 
 
 _GOOGLE_SESSION_ERROR_CODES = (
@@ -23,7 +31,19 @@ _GOOGLE_SESSION_ERROR_CODES = (
 )
 
 
-def _first_error_code(error: KonectyAPIError) -> str:
+_IMPERSONATE_ERROR_CODES = (
+    "IMPERSONATE_FORBIDDEN",
+    "IMPERSONATE_INVALID_TARGET",
+    "IMPERSONATE_TARGET_NOT_FOUND",
+    "IMPERSONATE_TARGET_NOT_ALLOWED",
+    "IMPERSONATED_SESSION_FORBIDDEN",
+    "admin-credential-routes-require-session",
+)
+
+
+def _first_error_code(
+    error: KonectyAPIError, recognised: tuple = _GOOGLE_SESSION_ERROR_CODES
+) -> str:
     """
     Extract the first recognised ``errors[].code``; ``failed`` when there is none.
 
@@ -33,7 +53,7 @@ def _first_error_code(error: KonectyAPIError) -> str:
     errors = error.args[0] if error.args else None
     if isinstance(errors, list):
         for item in errors:
-            if isinstance(item, dict) and item.get("code") in _GOOGLE_SESSION_ERROR_CODES:
+            if isinstance(item, dict) and item.get("code") in recognised:
                 return str(item["code"])
     return "failed"
 
@@ -128,7 +148,79 @@ class AuthService(BaseService):
         self._client.set_auth_id(auth_id)
         return response
 
+    async def impersonate(
+        self, user_id: Optional[str] = None, code: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """
+        POST /api/auth/impersonate. Issues a support session (1 h) for another user.
+
+        Pass exactly one of ``user_id`` (the user's ``_id``, sent as ``userId``) or ``code``
+        (the user's numeric code). The caller must be an admin authenticated with a
+        first-party session. Returns ``{"authId", "expiresAt", "user"}`` (``expiresAt`` is
+        ISO 8601). The returned ``authId`` is NOT adopted by this client — the admin session
+        stays intact.
+
+        Raises KonectyImpersonateError — errors[0].message as the message plus the
+        machine-readable ``code`` — on any failure. Zero or two targets raise
+        ``IMPERSONATE_INVALID_TARGET`` without sending a request. The error subclasses
+        KonectyAPIError, so callers catching that keep working.
+        """
+        if (user_id is not None) == (code is not None):
+            raise KonectyImpersonateError(
+                "IMPERSONATE_INVALID_TARGET", "Pass exactly one of userId or code"
+            )
+        payload: Dict[str, Any] = (
+            {"userId": user_id} if user_id is not None else {"code": code}
+        )
+
+        try:
+            response = await self._post(IMPERSONATE_PATH, json=payload)
+        except KonectyAPIError as error:
+            raise KonectyImpersonateError(
+                _first_error_code(error, _IMPERSONATE_ERROR_CODES),
+                _first_error_message(error),
+            ) from error
+
+        data = response.get("data") if isinstance(response, dict) else None
+        auth_id = data.get("authId") if isinstance(data, dict) else None
+        if not isinstance(auth_id, str) or not auth_id:
+            raise KonectyImpersonateError(
+                "failed", "Impersonate response has no authId"
+            )
+
+        return {
+            "authId": auth_id,
+            "expiresAt": data.get("expiresAt"),
+            "user": data.get("user"),
+        }
+
     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)
+
+    async def info(self) -> Dict[str, Any]:
+        """
+        GET /rest/auth/info. The session user and namespace: ``{"logged": True, "user": {...}}``.
+
+        ``user`` carries ``_id``, ``name``, ``email``, ``login``, ``group``, ``role``, ``access``,
+        ``locale``, ``namespace`` and ``redirectURL`` — the page to open the interface on, or
+        None when the user record sets none. In a support session (see ``impersonate``) it also
+        carries ``impersonatedBy`` (``{"_id", "name"}`` of the admin) and ``impersonationExpiresAt``
+        (ISO 8601). Keys are the wire names, as in the TypeScript SDK.
+
+        Same contract as ``KonectyClient.info()`` in the TypeScript SDK: without a token there is
+        no session to ask about, so no request goes out; a 4xx/5xx answer means not logged. Both
+        return ``{"logged": False}``.
+        """
+        if not self._client.auth_id:
+            return {"logged": False}
+        try:
+            return await self._get(USER_INFO_PATH)
+        except KonectyAPIError:
+            return {"logged": False}
+        except aiohttp.ContentTypeError as error:
+            # 401 sem corpo JSON: o http layer tenta ler JSON antes de olhar o status.
+            if error.status >= 400:
+                return {"logged": False}
+            raise

{konecty_sdk_python-2.1.6 → konecty_sdk_python-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: konecty_sdk_python
-Version: 2.1.6
+Version: 2.2.0
 Summary: Konecty SDK Python
 Author-email: Leonardo Leal <leonardo.leal@konecty.com>, Derotino Silveira <derotino.silveira@konecty.com>
 License: MIT

{konecty_sdk_python-2.1.6 → konecty_sdk_python-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "konecty_sdk_python"
-version = "2.1.6"
+version = "2.2.0"
 description = "Konecty SDK Python"
 readme = "README.md"
 requires-python = ">=3.11"

konecty_sdk_python-2.1.6/KonectySdkPython/lib/exceptions.py

@@ -1,93 +0,0 @@
-"""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 KonectyGoogleSessionError(KonectyAPIError):
-    """
-    Raised by exchange_google_code. Carries the machine-readable ``code`` from
-    ``errors[0].code`` so callers can branch or translate without parsing the
-    message; ``failed`` covers unreadable or unrecognised bodies.
-
-    Subclasses KonectyAPIError so existing ``except KonectyAPIError`` keeps working.
-
-    Mirrors KonectyGoogleSessionError in the TypeScript SDK — keep both in sync.
-    """
-
-    def __init__(self, code: str, message: str) -> None:
-        super().__init__(message)
-        self.code = code
-
-
-#: Código devolvido pelo Konecty quando a requisição pede ordenação arbitrária
-#: acima do teto de página. Espelha ``SORT_ABOVE_MAX_PAGE_SIZE`` no SDK
-#: TypeScript — manter os dois em sincronia.
-SORT_ABOVE_MAX_PAGE_SIZE = "SORT_ABOVE_MAX_PAGE_SIZE"
-
-#: Teto do servidor. Informativo: quem decide é a API, este valor só evita adivinhação.
-MAX_SORTED_PAGE_SIZE = 1000
-
-
-class KonectySortLimitError(KonectyAPIError):
-    """
-    Raised when the request asks for arbitrary ordering above the page cap.
-
-    Acima de ``MAX_SORTED_PAGE_SIZE`` registros — e no caso sem limite
-    (``limit=-1``) — o ``$sort`` teria de terminar antes de o primeiro documento
-    sair do cursor, então a API recusa com HTTP 400 em vez de trocar a ordenação
-    em silêncio, como fazia antes.
-
-    Carrega o ``code`` legível por máquina para o chamador ramificar sem
-    inspecionar a mensagem, como ``KonectyGoogleSessionError``. Subclasse de
-    ``KonectyAPIError``, então ``except KonectyAPIError`` existente continua
-    pegando.
-
-    A saída é ordenar por ``_id`` (ascendente ou descendente) e paginar por faixa
-    de ``_id``, ou pedir no máximo ``MAX_SORTED_PAGE_SIZE`` registros.
-
-    Espelha ``KonectySortLimitError`` no SDK TypeScript — manter os dois em sincronia.
-    """
-
-    def __init__(self, message: str) -> None:
-        super().__init__(message)
-        self.code = SORT_ABOVE_MAX_PAGE_SIZE
-
-
-def raise_for_konecty_errors(errors: object) -> None:
-    """
-    Lança a exceção mais específica que a lista de ``errors`` da API permitir.
-
-    Existe porque os caminhos de find liam o corpo só para logar e lançavam
-    ``KonectyAPIError`` genérico — e, no caso de HTTP 400, o
-    ``response.raise_for_status()`` disparava ANTES de o corpo ser lido, então
-    nem a mensagem nem o código chegavam a quem chamou.
-    """
-    items = errors if isinstance(errors, list) else []
-    for error in items:
-        if isinstance(error, dict) and error.get("code") == SORT_ABOVE_MAX_PAGE_SIZE:
-            raise KonectySortLimitError(str(error.get("message", SORT_ABOVE_MAX_PAGE_SIZE)))
-
-    raise KonectyAPIError(errors)
-
-
-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")

konecty_sdk_python-2.1.6/KonectySdkPython/lib/filters.py

@@ -1,155 +0,0 @@
-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