konecty_sdk_python 2.1.2__py3-none-any.whl → 2.1.4__py3-none-any.whl

KonectySdkPython/cli/apply.py

@@ -191,12 +191,21 @@ async def apply_document(
 
     # Hooks
     for file_path in doc_files["hook"]:
-        data = file_path.read_text()
+        data: Any = file_path.read_text()
         if data:
+            hook_name = file_path.stem
+            # `validationData.json` é objeto no core, não texto: gravado como string, o
+            # `Object.keys` do `processValidationScript` itera os caracteres. Comparar o
+            # objeto também faz o apply reparar o que a versão antiga gravou como string.
+            if file_path.suffix == ".json":
+                try:
+                    data = json.loads(data)
+                except json.JSONDecodeError as error:
+                    errors.append(f"✗ {doc_name}/{hook_name}: JSON inválido ({error})")
+                    continue
             existing_data = collection.find_one(
                 {"name": doc_name, "type": {"$in": ["composite", "document"]}}
             )
-            hook_name = file_path.stem
             if existing_data:
                 if existing_data.get(hook_name, None) == data:
                     skipped.append(f"⚡ {doc_name}/{hook_name} [identical]")

KonectySdkPython/lib/client.py

@@ -7,13 +7,19 @@ from typing import Any, AsyncGenerator, Dict, List, Literal, Optional, Union, ca
 
 import aiohttp
 
-from .exceptions import KonectyAPIError, KonectyError, KonectyValidationError
+from .exceptions import (
+    KonectyAPIError,
+    KonectyError,
+    KonectyValidationError,
+    raise_for_konecty_errors,
+)
 from .feature_types.kpi import KpiConfig
 from .file_manager import FileManager
 from .filters import KonectyFilter, KonectyFindParams
 from .http import StreamResponse
 from .http import request as _http_request
 from .serialization import json_serial
+from .services.admin import AdminService
 from .services.aggregation import AggregationService
 from .services.auth import AuthService
 from .services.change_user import ChangeUserService
@@ -21,6 +27,7 @@ from .services.comments import CommentsService
 from .services.export import ExportService
 from .services.files import FilesService
 from .services.notifications import NotificationsService
+from .services.pat import PatService
 from .services.query import QueryResult, QueryService
 from .services.stream import FindStreamResult, StreamService
 from .services.subscriptions import SubscriptionsService
@@ -31,12 +38,15 @@ logging.getLogger("urllib3.connectionpool").setLevel(logging.ERROR)
 
 logger = logging.getLogger(__name__)
 
+# `_updatedBy` is NOT stripped: the backend accepts it on update as an explicit
+# authorship override for admin callers (automations crediting a write to the user
+# it acted on behalf of). Non-admin callers have it ignored server-side, so letting
+# it through costs nothing. See "Autoria da escrita" in docs/pt-BR/api.md (konecty/Konecty).
 KONECTY_UPDATE_IGNORE_FIELDS = [
     "_id",
     "code",
     "_updatedAt",
     "_createdAt",
-    "_updatedBy",
     "_createdBy",
 ]
 KONECTY_CREATE_IGNORE_FIELDS = ["_updatedAt", "_createdAt", "_updatedBy", "_createdBy"]
@@ -52,6 +62,18 @@ def get_first_dict(items: List[Any]) -> Optional[KonectyDict]:
     return None
 
 
+async def _read_json_body(response: "aiohttp.ClientResponse") -> Optional[Dict[str, Any]]:
+    """
+    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.
+    """
+    try:
+        return cast(Dict[str, Any], await response.json(content_type=None))
+    except Exception:  # noqa: BLE001 - corpo não-JSON é caso esperado aqui
+        return None
+
+
 class KonectyClient:
     def __init__(self, base_url: str, token: str = "") -> None:
         self.base_url = base_url
@@ -417,6 +439,145 @@ class KonectyClient:
         """Get login method flags for the namespace (GET /api/auth/login-options)."""
         return await self._auth.get_login_options()
 
+    @property
+    def _pat(self) -> PatService:
+        if not hasattr(self, "_pat_service"):
+            self._pat_service = PatService(self)
+        return self._pat_service
+
+    async def create_pat(
+        self, name: str, *, expires_at: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a Personal Access Token for the caller (POST /rest/auth/pat).
+
+        Requires a session/OAuth authentication (a PAT cannot mint another PAT). The
+        plaintext token is only ever returned here — save it now, it is not recoverable
+        afterwards. `expires_at` is an ISO date string; omit for a PAT that never expires.
+        """
+        return await self._pat.create_pat(name, expires_at=expires_at)
+
+    async def list_pats(self) -> Dict[str, Any]:
+        """List the caller's own Personal Access Tokens (GET /rest/auth/pat)."""
+        return await self._pat.list_pats()
+
+    async def revoke_pat(self, pat_id: str) -> Dict[str, Any]:
+        """Revoke one of the caller's own Personal Access Tokens (DELETE /rest/auth/pat/{pat_id})."""
+        return await self._pat.revoke_pat(pat_id)
+
+    @property
+    def _admin(self) -> AdminService:
+        if not hasattr(self, "_admin_service"):
+            self._admin_service = AdminService(self)
+        return self._admin_service
+
+    async def list_all_pats(self) -> Dict[str, Any]:
+        """Admin: list every PAT and legacy perpetual token in the namespace (GET /api/admin/pats)."""
+        return await self._admin.list_all_pats()
+
+    async def revoke_user_pat(self, user_id: str, pat_id: str) -> Dict[str, Any]:
+        """
+        Admin: revoke a PAT belonging to any user (DELETE /api/admin/pats/{user_id}/{pat_id}).
+
+        Named `revoke_user_pat` — not `revoke_pat` — because that flat name is already
+        taken by the self-service method above, and the two act on different resources
+        (`user_id` + `pat_id` here vs. a caller-scoped `pat_id`). Mirrors the TypeScript
+        SDK's equivalent method for the same reason.
+        """
+        return await self._admin.revoke_user_pat(user_id, pat_id)
+
+    async def revoke_legacy_token(self, user_id: str, fingerprint: str) -> Dict[str, Any]:
+        """Admin: revoke a legacy perpetual token by fingerprint (DELETE /api/admin/legacy-tokens/{user_id}/{fingerprint})."""
+        return await self._admin.revoke_legacy_token(user_id, fingerprint)
+
+    async def create_service_account(
+        self,
+        name: str,
+        username: str,
+        access_map: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Admin: create a Service Account with a sovereign access map (POST /api/admin/service-accounts).
+
+        `access_map` maps document name -> 'read' | 'readWrite'.
+        """
+        return await self._admin.create_service_account(name, username, access_map)
+
+    async def list_meta_documents(self) -> Dict[str, Any]:
+        """Admin: os documentos de metadado do namespace (GET /api/admin/meta)."""
+        return await self._admin.list_meta_documents()
+
+    async def read_meta(self, document: str) -> Dict[str, Any]:
+        """Admin: o metadado de um documento (GET /api/admin/meta/{document})."""
+        return await self._admin.read_meta(document)
+
+    async def upsert_meta(
+        self, document: str, type: str, body: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Admin: grava o metadado singleton de um tipo (PUT /api/admin/meta/{document}/{type}).
+
+        Campo de hook que o `body` omite é preservado do metadado já gravado e volta nomeado em
+        `data["preservedHooks"]`; para remover um hook, envie `None` naquele campo.
+        """
+        return await self._admin.upsert_meta(document, type, body)
+
+    async def delete_meta(self, document: str, type: str) -> Dict[str, Any]:
+        """Admin: remove e versiona a remoção (DELETE /api/admin/meta/{document}/{type})."""
+        return await self._admin.delete_meta(document, type)
+
+    async def list_meta_history(
+        self,
+        meta_id: str,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Admin: versões de um metadado, mais recentes primeiro (GET /api/admin/meta/{metaId}/history)."""
+        return await self._admin.list_meta_history(meta_id, limit, offset)
+
+    async def rollback_meta(self, meta_id: str, version: int) -> Dict[str, Any]:
+        """Admin: restaura o conteúdo de uma versão anterior (POST /api/admin/meta/{metaId}/rollback)."""
+        return await self._admin.rollback_meta(meta_id, version)
+
+    async def list_service_accounts(self) -> Dict[str, Any]:
+        """Admin: list every Service Account and its PATs (GET /api/admin/service-accounts)."""
+        return await self._admin.list_service_accounts()
+
+    async def update_service_account_access(
+        self, service_account_id: str, access_map: Dict[str, str]
+    ) -> Dict[str, Any]:
+        """Admin: replace a Service Account's access map (PUT /api/admin/service-accounts/{id}/access)."""
+        return await self._admin.update_service_account_access(
+            service_account_id, access_map
+        )
+
+    async def create_service_account_pat(
+        self,
+        service_account_id: str,
+        name: str,
+        *,
+        expires_at: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Admin: mint a PAT on behalf of a Service Account (POST /api/admin/service-accounts/{id}/pats)."""
+        return await self._admin.create_service_account_pat(
+            service_account_id, name, expires_at=expires_at
+        )
+
+    async def get_mcp_access(self) -> Dict[str, Any]:
+        """Admin: read the roles allowed to reach the MCP, split into read and write (GET /api/admin/mcp-access)."""
+        return await self._admin.get_mcp_access()
+
+    async def update_mcp_access(
+        self, read_role_ids: List[str], write_role_ids: List[str]
+    ) -> Dict[str, Any]:
+        """
+        Admin: replace both MCP role lists (PUT /api/admin/mcp-access).
+
+        A role in `write_role_ids` also gets read access. Mirrors the TypeScript SDK's
+        `updateMcpAccess`.
+        """
+        return await self._admin.update_mcp_access(read_role_ids, write_role_ids)
+
     @property
     def _query(self) -> QueryService:
         if not hasattr(self, "_query_service"):
@@ -511,12 +672,18 @@ class KonectyClient:
                 headers={"Authorization": self.headers["Authorization"]},
             ) as response,
         ):
-            response.raise_for_status()
-            result = await response.json()
+            # O corpo é lido ANTES do raise_for_status: a recusa de sort acima do
+            # teto chega como HTTP 400 com `errors[0].code`, e levantar pelo status
+            # primeiro descartava mensagem e código, deixando só "400 Bad Request".
+            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)
     
@@ -566,12 +733,19 @@ class KonectyClient:
             params=params,
             headers={"Authorization": self.headers["Authorization"]},
         )
-        response.raise_for_status()
-        result = response.json()
+        # Mesma ordem do `find` assíncrono: corpo primeiro, status depois.
+        try:
+            result = response.json()
+        except ValueError:
+            result = None
+        if result is None:
+            response.raise_for_status()
+            raise KonectyAPIError(f"{response.status_code} {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)
 

KonectySdkPython/lib/exceptions.py

@@ -29,6 +29,57 @@ class KonectyGoogleSessionError(KonectyAPIError):
         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."""
 

KonectySdkPython/lib/services/admin.py

@@ -0,0 +1,223 @@
+"""Admin API: cross-user PAT/legacy-token management and Service Accounts.
+
+Mirrors the backend's `src/server/routes/api/admin/credentials.ts` and
+`src/server/routes/api/admin/serviceAccounts.ts` (Konecty core repo). Every route here
+requires an admin session — a regular user gets 403.
+"""
+
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+from .base import BaseService
+
+ADMIN_PATS_PATH = "/api/admin/pats"
+ADMIN_LEGACY_TOKENS_PATH = "/api/admin/legacy-tokens"
+ADMIN_SERVICE_ACCOUNTS_PATH = "/api/admin/service-accounts"
+ADMIN_MCP_ACCESS_PATH = "/api/admin/mcp-access"
+ADMIN_META_PATH = "/api/admin/meta"
+
+#: `409` — o deployment carrega metadados de um diretório (`METADATA_DIR`); nada é gravável.
+META_ADMIN_CONFIG_READ_ONLY_CODE = "meta-admin-config-read-only"
+
+#: `403` — a rota exige sessão first-party; PAT e token OAuth são recusados.
+ADMIN_ROUTES_REQUIRE_SESSION_CODE = "admin-credential-routes-require-session"
+
+
+def _segment(value: str) -> str:
+    """Codifica UM segmento de path.
+
+    `safe=""` de propósito, e **não** `quote_plus`: o TS usa `encodeURIComponent`, que produz `%20`
+    para espaço enquanto `quote_plus` produziria `+` — as duas URLs deixariam de bater byte a byte,
+    que é exatamente a classe de divergência que já mordeu este time. Codifica por segmento porque
+    um `_id` de meta carrega `:` (`Product:list:Default`) e codificar o caminho inteiro escaparia as
+    barras que o separam.
+
+    Diferente dos ids de PAT/service account acima, aqui o valor é nome de documento ou `_id` de
+    meta — entrada livre, não identificador gerado pelo servidor.
+    """
+    return quote(value, safe="")
+
+
+class AdminService(BaseService):
+    """Service for namespace-wide credential and Service Account administration.
+
+    `user_id`/`pat_id`/`fingerprint`/`service_account_id` below are server-generated
+    identifiers (Mongo-style hex ids or slug-like alphanumeric/hyphen strings) —
+    interpolated raw into the path with an f-string, no percent-encoding, matching
+    the TS SDK's equivalent path-templating in adminCredentials.ts/
+    adminServiceAccounts.ts. They are never free-form user input.
+    """
+
+    async def list_all_pats(self) -> Dict[str, Any]:
+        """GET /api/admin/pats. Returns `data`: {pats: [...], legacyTokens: [...]} for the whole namespace."""
+        return await self._get(ADMIN_PATS_PATH)
+
+    async def revoke_user_pat(self, user_id: str, pat_id: str) -> Dict[str, Any]:
+        """DELETE /api/admin/pats/{user_id}/{pat_id}. Revokes a PAT belonging to any user."""
+        path = f"{ADMIN_PATS_PATH}/{user_id}/{pat_id}"
+        return await self._delete(path)
+
+    async def revoke_legacy_token(self, user_id: str, fingerprint: str) -> Dict[str, Any]:
+        """DELETE /api/admin/legacy-tokens/{user_id}/{fingerprint}. `fingerprint` comes from `list_all_pats`'s `legacyTokens` entries."""
+        path = f"{ADMIN_LEGACY_TOKENS_PATH}/{user_id}/{fingerprint}"
+        return await self._delete(path)
+
+    async def create_service_account(
+        self,
+        name: str,
+        username: str,
+        access_map: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        POST /api/admin/service-accounts. Wire body: {name, username, accessMap?}.
+
+        `access_map` maps document name -> 'read' | 'readWrite'; when omitted the
+        `accessMap` key itself is left out of the request body (matching the TS SDK,
+        which passes `accessMap: undefined` and drops it on `JSON.stringify`) — the
+        backend treats a missing map the same as an empty one: no access to anything.
+        Returns `data`: {_id, username, role, access, mcpRoleHint?} — 201 on success,
+        409 if the username is already in use.
+        """
+        payload: Dict[str, Any] = {"name": name, "username": username}
+        if access_map is not None:
+            payload["accessMap"] = access_map
+        return await self._post(ADMIN_SERVICE_ACCOUNTS_PATH, json=payload)
+
+    async def list_service_accounts(self) -> Dict[str, Any]:
+        """GET /api/admin/service-accounts. Returns `data`: list of {_id, name, username, active, access, pats}."""
+        return await self._get(ADMIN_SERVICE_ACCOUNTS_PATH)
+
+    async def update_service_account_access(
+        self, service_account_id: str, access_map: Dict[str, str]
+    ) -> Dict[str, Any]:
+        """
+        PUT /api/admin/service-accounts/{id}/access. Wire body: {accessMap}.
+
+        Replaces the whole access map (a document omitted from `access_map` loses
+        access). Returns `data`: {_id, access}.
+        """
+        path = f"{ADMIN_SERVICE_ACCOUNTS_PATH}/{service_account_id}/access"
+        return await self._put(path, json={"accessMap": access_map})
+
+    async def create_service_account_pat(
+        self,
+        service_account_id: str,
+        name: str,
+        *,
+        expires_at: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        POST /api/admin/service-accounts/{id}/pats. Wire body: {name, expiresAt?}.
+
+        Mints a PAT on behalf of a Service Account (never a human user — the backend
+        rejects that with 403, ADM-02). Returns `data`: {_id, token} — 201 on success.
+        """
+        payload: Dict[str, Any] = {"name": name}
+        if expires_at is not None:
+            payload["expiresAt"] = expires_at
+        path = f"{ADMIN_SERVICE_ACCOUNTS_PATH}/{service_account_id}/pats"
+        return await self._post(path, json=payload)
+
+    async def get_mcp_access(self) -> Dict[str, Any]:
+        """
+        GET /api/admin/mcp-access. Returns `data`: {roles, readRoleIds, writeRoleIds, readOnlyConfig}.
+
+        `readRoleIds` are the roles allowed to reach the MCP; `writeRoleIds` the subset
+        also allowed to use write/destructive tools (a role listed there reads too, whether
+        or not it also appears in `readRoleIds`). `readOnlyConfig` is true when the
+        deployment loads its namespace config from a metadata directory — `update_mcp_access`
+        then refuses with 409.
+        """
+        return await self._get(ADMIN_MCP_ACCESS_PATH)
+
+    async def update_mcp_access(
+        self, read_role_ids: List[str], write_role_ids: List[str]
+    ) -> Dict[str, Any]:
+        """
+        PUT /api/admin/mcp-access. Wire body: {readRoleIds, writeRoleIds}.
+
+        Replaces both lists wholesale (a role omitted loses access). An unknown role id
+        is rejected with 400 and nothing is written; a deployment configured by a metadata
+        directory answers 409 with code `mcp-access-config-read-only`.
+        """
+        return await self._put(
+            ADMIN_MCP_ACCESS_PATH,
+            json={"readRoleIds": read_role_ids, "writeRoleIds": write_role_ids},
+        )
+    # --- Meta Admin API (fatia mínima) ---------------------------------------------------------
+    #
+    # Seis métodos, não os 17 que `docs/features.json` declara. As demais rotas existem no core e
+    # ficam sem método de SDK até haver consumidor — YAGNI. Cada teste em `tests/test_admin.py`
+    # cita o equivalente em `src/__test__/api/adminMeta.test.ts` do `konecty-sdk`.
+    #
+    # Todas exigem **sessão first-party de admin**: PAT e token OAuth são recusados com `403` e o
+    # código `admin-credential-routes-require-session` — metadado decide quem lê e escreve o quê.
+
+    async def list_meta_documents(self) -> Dict[str, Any]:
+        """GET /api/admin/meta. Returns `data`: [{_id, name, type, label}] do namespace."""
+        return await self._get(ADMIN_META_PATH)
+
+    async def read_meta(self, document: str) -> Dict[str, Any]:
+        """GET /api/admin/meta/:document. `404` quando o metadado não existe."""
+        return await self._get(f"{ADMIN_META_PATH}/{_segment(document)}")
+
+    async def upsert_meta(self, document: str, type: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        PUT /api/admin/meta/:document/:type — grava o metadado singleton de um tipo
+        (`document`, `composite`, `namespace`).
+
+        Returns `data`: {matchedCount, modifiedCount, upsertedCount, versioned, version,
+        preservedHooks}. Escrita idêntica ao estado atual não cria versão (`versioned: False`).
+        Num deployment com `METADATA_DIR` responde `409` com `META_ADMIN_CONFIG_READ_ONLY_CODE`.
+
+        `preservedHooks` lista os campos de hook (`scriptBeforeValidation`, `validationScript`,
+        `scriptAfterSave`, `validationData`) que o `body` **omitiu** e vieram do metadado já
+        gravado. Hook é campo do metadado, mas nos repositórios de metadados ele vive em
+        `MetaObjects/<Doc>/hook/<nome>.js|json` e nunca aparece no `document.json`; por isso o core
+        preserva o hook cuja chave o payload não menciona, em vez de apagá-lo. Para remover um
+        hook, envie `None` explícito naquele campo. A chave está **ausente** quando o deployment é
+        anterior ao contrato — ausente significa "este servidor não informa", não "nada foi
+        preservado".
+        """
+        return await self._put(f"{ADMIN_META_PATH}/{_segment(document)}/{_segment(type)}", json=body)
+
+    async def delete_meta(self, document: str, type: str) -> Dict[str, Any]:
+        """
+        DELETE /api/admin/meta/:document/:type — remove e versiona a remoção.
+
+        Returns `data`: {deletedCount, version}. O documento `Namespace` não é deletável.
+        """
+        return await self._delete(f"{ADMIN_META_PATH}/{_segment(document)}/{_segment(type)}")
+
+    async def list_meta_history(
+        self,
+        meta_id: str,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """
+        GET /api/admin/meta/:metaId/history — versões, mais recentes primeiro.
+
+        `limit`/`offset` são omitidos da query quando não informados, igual ao TS. Um metadado nunca
+        escrito desde o deploy devolve **lista vazia**, não `404`: ausência de histórico não é
+        ausência de metadado.
+        """
+        params: Dict[str, Any] = {}
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+
+        return await self._get(
+            f"{ADMIN_META_PATH}/{_segment(meta_id)}/history",
+            params=params or None,
+        )
+
+    async def rollback_meta(self, meta_id: str, version: int) -> Dict[str, Any]:
+        """
+        POST /api/admin/meta/:metaId/rollback — restaura o conteúdo de uma versão anterior.
+
+        Returns `data`: {version, restoredFrom}. Forward-only: restaurar a v2 **cria** a v5 e nunca
+        reescreve nem apaga versão anterior.
+        """
+        return await self._post(f"{ADMIN_META_PATH}/{_segment(meta_id)}/rollback", json={"version": version})

KonectySdkPython/lib/services/pat.py

@@ -0,0 +1,46 @@
+"""Self-service Personal Access Token (PAT) API: create, list, revoke.
+
+Mirrors the backend's `src/server/routes/rest/auth/patApi.ts` (Konecty core repo). These
+routes require a session/OAuth authentication — a PAT itself cannot mint or revoke PATs
+(server-side rule D4/PAT-01), the SDK does not enforce that client-side.
+"""
+
+from typing import Any, Dict, Optional
+
+from .base import BaseService
+
+PAT_PATH = "/rest/auth/pat"
+
+
+class PatService(BaseService):
+    """Service for the caller's own Personal Access Tokens.
+
+    `pat_id` below is a server-generated identifier (Mongo-style hex id) —
+    interpolated raw into the path with an f-string, no percent-encoding, matching
+    the TS SDK's equivalent path-templating in pat.ts. It is never free-form user
+    input.
+    """
+
+    async def create_pat(
+        self, name: str, *, expires_at: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        POST /rest/auth/pat. Wire body: {name, expiresAt?}.
+
+        The plaintext token only ever appears in this response's `data.token` — it is
+        never recoverable afterwards. `expires_at` is an ISO date string; omit for a
+        PAT that never expires.
+        """
+        payload: Dict[str, Any] = {"name": name}
+        if expires_at is not None:
+            payload["expiresAt"] = expires_at
+        return await self._post(PAT_PATH, json=payload)
+
+    async def list_pats(self) -> Dict[str, Any]:
+        """GET /rest/auth/pat. Returns `data`: list of {_id, name, createdAt, expiresAt, lastUsedAt} — never the hashed token."""
+        return await self._get(PAT_PATH)
+
+    async def revoke_pat(self, pat_id: str) -> Dict[str, Any]:
+        """DELETE /rest/auth/pat/{pat_id}. Self-scoped: another user's PAT id 404s."""
+        path = f"{PAT_PATH}/{pat_id}"
+        return await self._delete(path)

{konecty_sdk_python-2.1.2.dist-info → konecty_sdk_python-2.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: konecty_sdk_python
-Version: 2.1.2
+Version: 2.1.4
 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.2.dist-info → konecty_sdk_python-2.1.4.dist-info}/RECORD

@@ -1,11 +1,11 @@
 KonectySdkPython/__init__.py,sha256=E8bSSpoh-XogtSp4oDAhhID0J0UtctOlGS9LhI5F5d0,1022
 KonectySdkPython/cli/__init__.py,sha256=Ap83UThRejLC44VaM-l31NhKcpkzx0Y4CgT042OJCBE,761
-KonectySdkPython/cli/apply.py,sha256=LyPoNcsU3oz9P_eTAi4BdtJHWkbp-sNK_SP9W8Xua04,17923
+KonectySdkPython/cli/apply.py,sha256=OSCsMZ6t8TCWvdlHksjUmTESjfZQV7FFvVvA0K6dL6w,18482
 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=i-7goKqsH-jvwxZfGeipTRFByOBAOhMHkuhjjdEN3kE,34034
-KonectySdkPython/lib/exceptions.py,sha256=RQ6H_zgbF8yeII1F75wCIEJ1LfO4lWfY5hnK30cwETY,1107
+KonectySdkPython/lib/client.py,sha256=55di-db_5zUwdPVuIseILcWFrv__9VqMUM5Ulg9U9Ig,41861
+KonectySdkPython/lib/exceptions.py,sha256=WkXRm0ZzKZdOdrHmgGxB_T_yvLH6agsHTsph3bTA0Vs,3251
 KonectySdkPython/lib/file_manager.py,sha256=CLpOJWdA1tb2iq0qOIeRyEEIuACRq9tIo7Rls1YT2ig,9986
 KonectySdkPython/lib/filters.py,sha256=PsFaUFCEyKgxgzD566LdTLvuMJevoF_i9U1WnpJZzPQ,4482
 KonectySdkPython/lib/http.py,sha256=atwyuKSFniulvAspi_VhinUhtPJGNyZYkIkaEgqfIqo,3377
@@ -18,6 +18,7 @@ KonectySdkPython/lib/feature_types/cross_module_query.py,sha256=kG21qBMgCWd2gE1M
 KonectySdkPython/lib/feature_types/kpi.py,sha256=67RpwwwnzU8piIPRyFb6Kn0hqSRpT9RFbYqiRnvYkFk,626
 KonectySdkPython/lib/feature_types/query_json.py,sha256=yZgMPmkMdiBLm-dIrmU1AeZe5G9zQLwLtKUPMb7IOhU,8139
 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/base.py,sha256=tdVyWb7Y77cBhVc8Mz2BQMN6kAyZIohoxBxdwDnRsYs,1820
@@ -26,10 +27,11 @@ KonectySdkPython/lib/services/comments.py,sha256=RNevCg4de2FWNk7mD60-pk3r8f2sJ1N
 KonectySdkPython/lib/services/export.py,sha256=WAtSOUYx4uK1ujGHmITP77B1_l69UykhxvUBXEOG_wE,2074
 KonectySdkPython/lib/services/files.py,sha256=YvaN2yyh48pcPfv0t4PtZLxaDxQlQrGnzIAwnEYN5Ag,1843
 KonectySdkPython/lib/services/notifications.py,sha256=7AtCBbBl-YAz_RBIW6bzoKvuwsYqAUVnLBnS4uAlMWQ,1446
+KonectySdkPython/lib/services/pat.py,sha256=yelMEubMX4G5aB5-4h-QAYjeQrqJp48AsapM6nK519s,1824
 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.2.dist-info/METADATA,sha256=TfygAtKFhJJZvdH8AgpgtIBQnoFexqBLQk9FaXwDZ8Q,5442
-konecty_sdk_python-2.1.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-konecty_sdk_python-2.1.2.dist-info/entry_points.txt,sha256=awf962DamFgy791G3PsJ354edBMLJg16Dqi-2Y1tb9s,58
-konecty_sdk_python-2.1.2.dist-info/RECORD,,
+konecty_sdk_python-2.1.4.dist-info/METADATA,sha256=b_dxxgMQsJVnVkGm9sXAkjc5qCvPJTAV3abh069hXDg,5442
+konecty_sdk_python-2.1.4.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+konecty_sdk_python-2.1.4.dist-info/entry_points.txt,sha256=awf962DamFgy791G3PsJ354edBMLJg16Dqi-2Y1tb9s,58
+konecty_sdk_python-2.1.4.dist-info/RECORD,,

{konecty_sdk_python-2.1.2.dist-info → konecty_sdk_python-2.1.4.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.31.0
+Generator: hatchling 1.32.4
 Root-Is-Purelib: true
 Tag: py3-none-any