konecty-sdk-python 2.0.5__py3-none-any.whl → 2.1.0__py3-none-any.whl

KonectySdkPython/lib/client.py

@@ -15,6 +15,7 @@ from .http import StreamResponse
 from .http import request as _http_request
 from .serialization import json_serial
 from .services.aggregation import AggregationService
+from .services.auth import AuthService
 from .services.change_user import ChangeUserService
 from .services.comments import CommentsService
 from .services.export import ExportService
@@ -52,11 +53,21 @@ def get_first_dict(items: List[Any]) -> Optional[KonectyDict]:
 
 
 class KonectyClient:
-    def __init__(self, base_url: str, token: str) -> None:
+    def __init__(self, base_url: str, token: str = "") -> None:
         self.base_url = base_url
         self.headers = {"Authorization": f"{token}"}
         self.file_manager = FileManager(base_url=base_url, headers=self.headers)
 
+    @property
+    def auth_id(self) -> Optional[str]:
+        """Current session token (authId) sent in the Authorization header, or None."""
+        return self.headers.get("Authorization") or None
+
+    def set_auth_id(self, auth_id: str) -> None:
+        """Adopt a session token so following requests are authenticated."""
+        # headers is shared with file_manager: mutate in place so both see the token.
+        self.headers["Authorization"] = auth_id
+
     async def _request(
         self,
         method: str,
@@ -361,6 +372,51 @@ class KonectyClient:
         """Set queue on records."""
         return await self._change_user.set_queue(module, ids, queue)
 
+    @property
+    def _auth(self) -> AuthService:
+        if not hasattr(self, "_auth_service"):
+            self._auth_service = AuthService(self)
+        return self._auth_service
+
+    def google_login_url(
+        self,
+        client_id: str,
+        redirect_uri: Optional[str] = None,
+        state: Optional[str] = None,
+    ) -> str:
+        """Build the URL of GET /api/auth/google/start. Pure, performs no request."""
+        return self._auth.google_login_url(
+            client_id, redirect_uri=redirect_uri, state=state
+        )
+
+    async def exchange_google_code(
+        self,
+        code: str,
+        *,
+        geolocation: Optional[Union[Dict[str, Any], str]] = None,
+        resolution: Optional[Union[Dict[str, Any], str]] = None,
+        source: Optional[str] = None,
+        fingerprint: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Exchange the single-use code from the callback for a session
+        (POST /api/auth/google/session).
+
+        On success adopts the returned authId in this client. On error raises
+        KonectyAPIError with errors[0].message and keeps the client unauthenticated.
+        """
+        return await self._auth.exchange_google_code(
+            code,
+            geolocation=geolocation,
+            resolution=resolution,
+            source=source,
+            fingerprint=fingerprint,
+        )
+
+    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()
+
     @property
     def _query(self) -> QueryService:
         if not hasattr(self, "_query_service"):

KonectySdkPython/lib/services/auth.py

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

konecty_sdk_python-2.1.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: konecty_sdk_python
+Version: 2.1.0
+Summary: Konecty SDK Python
+Author-email: Leonardo Leal <leonardo.leal@konecty.com>, Derotino Silveira <derotino.silveira@konecty.com>
+License: MIT
+Keywords: api,konecty,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.11.11
+Requires-Dist: asyncio>=3.4.3
+Requires-Dist: black>=24.10.0
+Requires-Dist: email-validator>=2.2.0
+Requires-Dist: inquirer>=3.4.0
+Requires-Dist: pydantic>=2.11.4
+Requires-Dist: pymongo>=4.10.1
+Requires-Dist: requests>=2.32.3
+Requires-Dist: rich>=13.9.4
+Requires-Dist: typing-extensions>=4.12.2
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+## Konecty Python SDK
+
+> 🛠️ Work in progress
+
+This project exposes both:
+
+- a cli for interacting with the database
+- the Konecty client sdk for interacting with Konecty's api
+
+#### Usage
+
+##### Installing on a project
+
+```sh
+uv pip install konecty-sdk-python
+konecty-cli apply --mongo-url="..." --database my-db
+```
+
+##### Running on uvx
+
+```sh
+uvx --from konecty-sdk-python konecty-cli pull --all --mongo-url="..." --database my-db
+```
+
+#### Google login
+
+The Konecty core hosts the whole authorization code flow: your app never talks to Google
+and never sees `client_secret`. The `authId` never travels in a URL — the callback returns
+a single-use code (TTL 60s) and the `authId` only exists in the body of `POST /api/auth/google/session`.
+
+Three steps, three methods:
+
+1. `client.google_login_url(...)` — build the URL to send the browser to (no request is made).
+2. the browser comes back to your `redirect_uri` with `?code=...&state=...` (or `?error=...&state=...`).
+3. `await client.exchange_google_code(code)` — turn the code into a session; the returned
+   `authId` is adopted by the client, so the next calls are authenticated.
+
+```python
+import asyncio
+import os
+import secrets
+
+from KonectySdkPython import KonectyClient
+from KonectySdkPython.lib.exceptions import KonectyAPIError
+
+KONECTY_URL = os.environ["KONECTY_URL"]
+CLIENT_ID = os.environ["KONECTY_CLIENT_ID"]
+REDIRECT_URI = os.environ["KONECTY_REDIRECT_URI"]
+
+
+async def main() -> None:
+    client = KonectyClient(KONECTY_URL)
+
+    # Is Google login enabled for this namespace?
+    options = await client.get_login_options()
+    if not options["googleEnabled"]:
+        raise SystemExit("Google login is disabled for this namespace")
+
+    # Step 1 — send the browser here (state is opaque to Konecty; use it against CSRF).
+    state = secrets.token_urlsafe(16)
+    print(client.google_login_url(client_id=CLIENT_ID, redirect_uri=REDIRECT_URI, state=state))
+
+    # Step 2 — Konecty redirects the browser back to REDIRECT_URI with code + state.
+    #          On refusal it comes back as ?error=<access_denied|provider_error|
+    #          email_not_verified|user_not_found|user_inactive|ambiguous_user>&state=...
+    returned_code = input("code from the callback: ")
+
+    # Step 3 — exchange the single-use code for a session.
+    try:
+        session = await client.exchange_google_code(
+            returned_code,
+            source="my-app",  # optional telemetry: geolocation, resolution, source, fingerprint
+        )
+    except KonectyAPIError as error:
+        raise SystemExit(f"Google login failed: {error}")
+
+    print("logged as", session["user"]["login"], "authId:", client.auth_id)
+
+    # The client is now authenticated: no token needed on the constructor.
+    contacts = await client.find_by_id("User", session["user"]["_id"])
+    print(contacts)
+
+
+asyncio.run(main())
+```
+
+`exchange_google_code` raises `KonectyAPIError` with the message of `errors[0]`
+(`invalid_code`, `expired_code`, `user_not_found`, `user_inactive`) and leaves the client's
+authentication state untouched.
+
+#### Tests
+
+```sh
+uv pip install -e ".[dev]"
+.venv/bin/python -m pytest
+```
+
+#### Build & Publish
+
+It is needed to increase the version number on the [pyproject](./pyproject.toml) file.
+
+```sh
+uv build
+uvx twine upload --config-file .pypirc --skip-existing dist/*
+```

{konecty_sdk_python-2.0.5.dist-info → konecty_sdk_python-2.1.0.dist-info}/RECORD

@@ -4,7 +4,7 @@ KonectySdkPython/cli/apply.py,sha256=LyPoNcsU3oz9P_eTAi4BdtJHWkbp-sNK_SP9W8Xua04
 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=jX1_ayUYF_vMQuCj0Kuk1Fhw3SYie-RJ8Ekna9uUWSo,31954
+KonectySdkPython/lib/client.py,sha256=i-7goKqsH-jvwxZfGeipTRFByOBAOhMHkuhjjdEN3kE,34034
 KonectySdkPython/lib/exceptions.py,sha256=HR48cd-cptFPoObr37NcvDrdkb-RtxKRteQoG-tuPkk,529
 KonectySdkPython/lib/file_manager.py,sha256=CLpOJWdA1tb2iq0qOIeRyEEIuACRq9tIo7Rls1YT2ig,9986
 KonectySdkPython/lib/filters.py,sha256=PsFaUFCEyKgxgzD566LdTLvuMJevoF_i9U1WnpJZzPQ,4482
@@ -19,6 +19,7 @@ KonectySdkPython/lib/feature_types/kpi.py,sha256=67RpwwwnzU8piIPRyFb6Kn0hqSRpT9R
 KonectySdkPython/lib/feature_types/query_json.py,sha256=yZgMPmkMdiBLm-dIrmU1AeZe5G9zQLwLtKUPMb7IOhU,8139
 KonectySdkPython/lib/services/__init__.py,sha256=fluQuxs6LnIZwcjYTuKNeXCFTKuNF3At3X19fIB68p8,121
 KonectySdkPython/lib/services/aggregation.py,sha256=igK1mleMFU2_rDQCAU1yKyvDoOjhTO1SO0Nn4T_DokA,5610
+KonectySdkPython/lib/services/auth.py,sha256=JFiOvk0cqwRucvDQCN93jmKvSITxGtFYW1ME0gdEkMk,4226
 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
@@ -28,7 +29,7 @@ KonectySdkPython/lib/services/notifications.py,sha256=7AtCBbBl-YAz_RBIW6bzoKvuws
 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.0.5.dist-info/METADATA,sha256=GNN5r6m-JKJaOiwghqtS-IscpxYTmQB-Or5JMgI3PeA,1622
-konecty_sdk_python-2.0.5.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-konecty_sdk_python-2.0.5.dist-info/entry_points.txt,sha256=awf962DamFgy791G3PsJ354edBMLJg16Dqi-2Y1tb9s,58
-konecty_sdk_python-2.0.5.dist-info/RECORD,,
+konecty_sdk_python-2.1.0.dist-info/METADATA,sha256=bDqiKz0B699Mulju2AhOkSboeJIQetZBxCgtissnnNI,4454
+konecty_sdk_python-2.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+konecty_sdk_python-2.1.0.dist-info/entry_points.txt,sha256=awf962DamFgy791G3PsJ354edBMLJg16Dqi-2Y1tb9s,58
+konecty_sdk_python-2.1.0.dist-info/RECORD,,

{konecty_sdk_python-2.0.5.dist-info → konecty_sdk_python-2.1.0.dist-info}/WHEEL

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

konecty_sdk_python-2.0.5.dist-info/METADATA

@@ -1,59 +0,0 @@
-Metadata-Version: 2.4
-Name: konecty_sdk_python
-Version: 2.0.5
-Summary: Konecty SDK Python
-Author-email: Leonardo Leal <leonardo.leal@konecty.com>, Derotino Silveira <derotino.silveira@konecty.com>
-License: MIT
-Keywords: api,konecty,sdk
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.11
-Requires-Dist: aiohttp>=3.11.11
-Requires-Dist: asyncio>=3.4.3
-Requires-Dist: black>=24.10.0
-Requires-Dist: email-validator>=2.2.0
-Requires-Dist: inquirer>=3.4.0
-Requires-Dist: pydantic>=2.11.4
-Requires-Dist: pymongo>=4.10.1
-Requires-Dist: requests>=2.32.3
-Requires-Dist: rich>=13.9.4
-Requires-Dist: typing-extensions>=4.12.2
-Description-Content-Type: text/markdown
-
-## Konecty Python SDK
-
-> 🛠️ Work in progress
-
-This project exposes both:
-
-- a cli for interacting with the database
-- the Konecty client sdk for interacting with Konecty's api
-
-#### Usage
-
-##### Installing on a project
-
-```sh
-uv pip install konecty-sdk-python
-konecty-cli apply --mongo-url="..." --database my-db
-```
-
-##### Running on uvx
-
-```sh
-uvx --from konecty-sdk-python konecty-cli pull --all --mongo-url="..." --database my-db
-```
-
-#### Build & Publish
-
-It is needed to increase the version number on the [pyproject](./pyproject.toml) file.
-
-```sh
-uv build
-uvx twine upload --config-file .pypirc --skip-existing dist/*
-```