konecty-sdk-python 2.0.5__tar.gz → 2.1.0__tar.gz

{konecty_sdk_python-2.0.5 → konecty_sdk_python-2.1.0}/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"):

konecty_sdk_python-2.1.0/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/PKG-INFO

@@ -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.1.0/README.md

@@ -0,0 +1,105 @@
+## 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 → konecty_sdk_python-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "konecty_sdk_python"
-version = "2.0.5"
+version = "2.1.0"
 description = "Konecty SDK Python"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -32,6 +32,16 @@ dependencies = [
     "pydantic>=2.11.4",
 ]
 
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "strict"
+
 [project.scripts]
 konecty-cli = "KonectySdkPython.cli:main"
 

konecty_sdk_python-2.0.5/PKG-INFO

@@ -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/*
-```

konecty_sdk_python-2.0.5/README.md

@@ -1,32 +0,0 @@
-## 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/*
-```