konecty-sdk-python 2.1.6__py3-none-any.whl → 2.2.0__py3-none-any.whl

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
 

KonectySdkPython/lib/exceptions.py

@@ -1,5 +1,7 @@
 """Exceptions for the Konecty SDK."""
 
+from typing import Optional
+
 
 class KonectyError(Exception):
     """Base exception for Konecty errors."""
@@ -29,6 +31,26 @@ class KonectyGoogleSessionError(KonectyAPIError):
         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.
@@ -63,6 +85,163 @@ class KonectySortLimitError(KonectyAPIError):
         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.
@@ -74,8 +253,15 @@ def raise_for_konecty_errors(errors: object) -> None:
     """
     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)))
+        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)
 

KonectySdkPython/lib/filters.py

@@ -1,6 +1,6 @@
 from datetime import datetime
 from enum import Enum
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Mapping, Optional, TypedDict, Union
 
 from pydantic import BaseModel, Field
 
@@ -29,6 +29,97 @@ class FilterOperator(str, Enum):
     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):
@@ -57,13 +148,17 @@ 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")
+    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
@@ -74,7 +169,9 @@ class KonectyFilter(BaseModel):
         return cls(**data)
 
     @classmethod
-    def create(cls, match: Union[FilterMatch, str] = FilterMatch.AND) -> "KonectyFilter":
+    def create(
+        cls, match: Union[FilterMatch, str] = FilterMatch.AND
+    ) -> "KonectyFilter":
         """Cria uma nova instância de filtro.
 
         Args:
@@ -88,7 +185,11 @@ class KonectyFilter(BaseModel):
         return cls(match=match)
 
     def add_condition(
-        self, term: str, operator: Union[FilterOperator, str], value: Any, disabled: bool = False
+        self,
+        term: str,
+        operator: Union[FilterOperator, str],
+        value: Any,
+        disabled: bool = False,
     ) -> "KonectyFilter":
         """Adiciona uma condição ao filtro.
 
@@ -114,7 +215,42 @@ class KonectyFilter(BaseModel):
         )
         return self
 
-    def add_filter(self, match: Union[FilterMatch, str] = FilterMatch.AND) -> "KonectyFilter":
+    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:

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.dist-info → konecty_sdk_python-2.2.0.dist-info}/METADATA

@@ -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.dist-info → konecty_sdk_python-2.2.0.dist-info}/RECORD

@@ -4,10 +4,10 @@ KonectySdkPython/cli/apply.py,sha256=OSCsMZ6t8TCWvdlHksjUmTESjfZQV7FFvVvA0K6dL6w
 KonectySdkPython/cli/backup.py,sha256=rcla3EWfPsy-vWgmDK844EaM5u3h7JF-u7-b2HUBMgA,4785
 KonectySdkPython/cli/pull.py,sha256=n4gIkKtuEpPKULb3zcYu5tZlBLbt_4oNQDeu2l6tHxU,9529
 KonectySdkPython/lib/__init__.py,sha256=Du8jLNfFG1bQuHX5u7pAhbyV9TjC7Ie9K1Xo1KSUqqc,995
-KonectySdkPython/lib/client.py,sha256=eazEV9hFz6Tm1Y8UDNCBKhC_J8qaUPMVYxymHsz0NNo,42575
-KonectySdkPython/lib/exceptions.py,sha256=WkXRm0ZzKZdOdrHmgGxB_T_yvLH6agsHTsph3bTA0Vs,3251
+KonectySdkPython/lib/client.py,sha256=cVofO8V6sn0ebpS33ru6As03a6lYWTXInzfXoSpjNaE,44543
+KonectySdkPython/lib/exceptions.py,sha256=rt6AeA2t-ipwx5yiere0lQFnSI5h5zuwgwMwBCKbsx4,11972
 KonectySdkPython/lib/file_manager.py,sha256=CLpOJWdA1tb2iq0qOIeRyEEIuACRq9tIo7Rls1YT2ig,9986
-KonectySdkPython/lib/filters.py,sha256=PsFaUFCEyKgxgzD566LdTLvuMJevoF_i9U1WnpJZzPQ,4482
+KonectySdkPython/lib/filters.py,sha256=1JPNqxFDJKOr9zgdcaYtUHTWf3M_I7xNDGXif2Pvsyo,9677
 KonectySdkPython/lib/http.py,sha256=lHb1GFN9OBGgZcC9TkP57S-KqnmeHbOzizq72OvChgk,3571
 KonectySdkPython/lib/model.py,sha256=8ok1VzPGpXQklz2fJwjP8HT0aKOzhtE93BzcgfVw4zY,2846
 KonectySdkPython/lib/serialization.py,sha256=HxA2t7uPv-4aqkGHMUF8WgP1RcTg6RXsFmr-nUhtx7E,401
@@ -20,7 +20,7 @@ KonectySdkPython/lib/feature_types/query_json.py,sha256=yZgMPmkMdiBLm-dIrmU1AeZe
 KonectySdkPython/lib/services/__init__.py,sha256=fluQuxs6LnIZwcjYTuKNeXCFTKuNF3At3X19fIB68p8,121
 KonectySdkPython/lib/services/admin.py,sha256=DyJWjDNVE9HSd3FaESLbMW6EviTwYbu6iocUhMMIlDc,10747
 KonectySdkPython/lib/services/aggregation.py,sha256=igK1mleMFU2_rDQCAU1yKyvDoOjhTO1SO0Nn4T_DokA,5610
-KonectySdkPython/lib/services/auth.py,sha256=seb2QgdeWT_ALcVLR8bDMgO1ycI9dz75OhuIjahzy7o,5173
+KonectySdkPython/lib/services/auth.py,sha256=pkJ-92snBxGN7hd7yt9GxPVAV4Z713qdFzeAW3zvHEU,8953
 KonectySdkPython/lib/services/base.py,sha256=tdVyWb7Y77cBhVc8Mz2BQMN6kAyZIohoxBxdwDnRsYs,1820
 KonectySdkPython/lib/services/change_user.py,sha256=ce6mcDYMP6eWxW0bEtzlVf7wbppGHCkGwdgo2jJFJOQ,2548
 KonectySdkPython/lib/services/comments.py,sha256=RNevCg4de2FWNk7mD60-pk3r8f2sJ1NLoolD2iNMidg,3033
@@ -31,7 +31,7 @@ KonectySdkPython/lib/services/pat.py,sha256=yelMEubMX4G5aB5-4h-QAYjeQrqJp48AsapM
 KonectySdkPython/lib/services/query.py,sha256=vCqbf0QdV8Blh8Hfsvq6Ne1-YFuC5siw1gVa7ZBGs_k,6605
 KonectySdkPython/lib/services/stream.py,sha256=1DMVxcg9Ymk2NgX0Qfvpjrr6vZJo5iFovPFT1NA3_CY,4737
 KonectySdkPython/lib/services/subscriptions.py,sha256=_Jq8jW7YkL_hwLNte1bWgrr4D2EMZUUSOXUgnRoGGK4,1022
-konecty_sdk_python-2.1.6.dist-info/METADATA,sha256=vGd9Fznf_FDSBFBqP8DTd4-wlgV9tQ2bltyZTynXkMg,5442
-konecty_sdk_python-2.1.6.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-konecty_sdk_python-2.1.6.dist-info/entry_points.txt,sha256=awf962DamFgy791G3PsJ354edBMLJg16Dqi-2Y1tb9s,58
-konecty_sdk_python-2.1.6.dist-info/RECORD,,
+konecty_sdk_python-2.2.0.dist-info/METADATA,sha256=BCAZTcKScpEhM6cWdMWx1G8tSqGW74rxo9Baz4oKRQQ,5442
+konecty_sdk_python-2.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+konecty_sdk_python-2.2.0.dist-info/entry_points.txt,sha256=awf962DamFgy791G3PsJ354edBMLJg16Dqi-2Y1tb9s,58
+konecty_sdk_python-2.2.0.dist-info/RECORD,,