f40-sdk 0.1.0__py3-none-any.whl

f40_sdk/__init__.py

@@ -0,0 +1,48 @@
+"""
+f40_sdk — SDK clients for the MAT Auth Manager, Data Manager and related services.
+
+Built on the dependency-light HTTP building block in :mod:`f40_toolkit.common.http`
+(a dependency of this package). Those primitives are re-exported here under their
+historical ``Mat*`` names for convenience:
+
+    MatHttpClient -> f40_toolkit.common.http.HttpClient
+    MatHttpToken  -> f40_toolkit.common.http.BearerToken
+    MatHttpError  -> f40_toolkit.common.http.HttpError
+    MatAuthError  -> f40_toolkit.common.http.HttpAuthError
+
+Requires: ``pip install f40-sdk``
+
+Quick imports
+-------------
+    from f40_sdk import MatDataManagerClient, MatAuthManagerClient
+    from f40_sdk import MatHttpClient, MatBasicClient   # building blocks
+    from f40_sdk import MatHttpError                    # exception
+"""
+
+from f40_toolkit.common.http import BearerToken as MatHttpToken
+from f40_toolkit.common.http import HttpAuthError as MatAuthError
+from f40_toolkit.common.http import HttpClient as MatHttpClient
+from f40_toolkit.common.http import HttpError as MatHttpError
+from .clients import (
+    MatAiAgentsMngClient,
+    MatAuthManagerClient,
+    MatBasicClient,
+    MatCmmsMngClient,
+    MatCompData,
+    MatDataManagerClient,
+    WilsonMngClient,
+)
+
+__all__ = [
+    "MatHttpClient",
+    "MatBasicClient",
+    "MatHttpToken",
+    "MatAuthManagerClient",
+    "MatDataManagerClient",
+    "MatCompData",
+    "MatAiAgentsMngClient",
+    "MatCmmsMngClient",
+    "WilsonMngClient",
+    "MatHttpError",
+    "MatAuthError",
+]

f40_sdk/clients/__init__.py

@@ -0,0 +1,19 @@
+"""Service SDK clients for the MAT platform."""
+
+from .ai_agents import MatAiAgentsMngClient
+from .auth_manager import MatAuthManagerClient
+from .base import MatBasicClient
+from .cmms import MatCmmsMngClient
+from .data_manager import MatDataManagerClient
+from .models import MatCompData
+from .wilson import WilsonMngClient
+
+__all__ = [
+    "MatBasicClient",
+    "MatAuthManagerClient",
+    "MatDataManagerClient",
+    "MatCompData",
+    "MatAiAgentsMngClient",
+    "MatCmmsMngClient",
+    "WilsonMngClient",
+]

f40_sdk/clients/ai_agents.py

@@ -0,0 +1,61 @@
+"""
+SDK client for the MAT AI-Agents (IoT-Agents) service.
+
+Auth is handled by the parent :class:`MatBasicClient` (auth_mng / basic /
+bearer_token / env_name). This client adds the agent listing and invocation API.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, List, Optional, Union
+
+from .base import MatBasicClient
+
+if TYPE_CHECKING:
+    from key_vault_interface.key_vault_interface import KeyVaultInterface  # type: ignore[import]
+
+logger = logging.getLogger(__name__)
+
+
+class MatAiAgentsMngClient(MatBasicClient):
+    """SDK client for the MAT AI-Agents service."""
+
+    def get_agents(self) -> List[dict]:
+        """Return the list of agents (empty list when none / unexpected shape)."""
+        res = self._send("GET", "iota/agents")
+        if isinstance(res, dict):
+            res = res.get("agents")
+        return res if isinstance(res, list) else []
+
+    def run_agent(self, agent_id: str, run_message: str) -> None:
+        """Invoke an agent with an alert message."""
+        self._send(
+            "POST", f"iota/agents/invoke/{agent_id}",
+            data=json.dumps({"alertMessage": run_message}), res_type="code",
+        )
+
+    @classmethod
+    def from_json(  # type: ignore[override]
+        cls,
+        _json: Union[dict, str],
+        kvi: Optional["KeyVaultInterface"] = None,
+    ) -> "MatAiAgentsMngClient":
+        """
+        Construct from a config dict or a path to a JSON file.
+
+        The JSON may have the config nested under an ``"ai_agents"`` key::
+
+            {"ai_agents": {"url": "...", "auth": {...}}}
+        """
+        if isinstance(_json, str):
+            with open(_json, "r") as fh:
+                _json = json.load(fh)
+            if isinstance(_json, dict) and "ai_agents" in _json:
+                _json = _json["ai_agents"]
+
+        if not isinstance(_json, dict):
+            raise TypeError(f"Expected a dict or JSON file path, got {type(_json).__name__}.")
+
+        return cls.from_dict(_json, kvi=kvi)

f40_sdk/clients/auth_manager.py

@@ -0,0 +1,440 @@
+"""
+SDK client for the MAT Auth Manager service.
+
+Handles OAuth application-token acquisition and credential validation. Typically
+used internally by :class:`MatBasicClient` to set up automatic bearer-token refresh
+for downstream services.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from base64 import b64encode
+from typing import Any, Optional
+
+from f40_toolkit.common.http import HttpClient
+from key_vault_interface.key_vault_interface import KeyVaultInterface as KVI
+
+logger = logging.getLogger(__name__)
+
+_TOKEN_ENDPOINT = "apif/oauth/application-token"
+
+
+class MatAuthManagerClient(HttpClient):
+    """
+    HTTP client for the MAT Auth Manager service.
+
+    Extends :class:`~f40_toolkit.common.http.HttpClient` directly (not
+    :class:`MatBasicClient`) because the auth manager is itself the token issuer —
+    it authenticates with HTTP Basic credentials to obtain tokens for downstream
+    services.
+
+    Example
+    -------
+        am = MatAuthManagerClient(
+            base_url="http://mat-auth-manager",
+            auth=("svc-user", "svc-password"),
+            credentials={"client_id": "my-app", "client_secret": "abc123"},
+        )
+        token = am.get_bearer_token()
+        # {"access_token": "eyJ...", "expires_in": 3600, "token_type": "Bearer"}
+
+    Parameters
+    ----------
+    base_url    : Auth Manager base URL.
+    auth        : (user, password) tuple for HTTP Basic auth to the auth manager itself.
+    credentials : OAuth credentials forwarded to the token endpoint. Must contain
+                  "client_id" and "client_secret" (or kvi resolves the secret).
+    app_name    : Injected as the "App-Name" header on token requests.
+    kvi         : KeyVaultInterface used to resolve a missing client_secret.
+    verify      : TLS verification flag.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        auth: tuple,
+        *,
+        credentials: Optional[dict] = None,
+        app_name: Optional[str] = None,
+        kvi: Optional["KVI"] = None,
+        verify: Optional[bool] = None,
+    ) -> None:
+        super().__init__(base_url=base_url, auth=auth, verify=verify)
+        self.app_name = app_name
+        self.credentials: Optional[dict] = credentials
+        # Cached "Bearer <token>" application token for user-management endpoints.
+        self._app_token: Optional[str] = None
+        self._app_token_exp: float = 0.0
+        if self.credentials is not None:
+            self.validate_credentials(self.credentials, kvi=kvi)
+
+    @staticmethod
+    def from_json(
+        config,
+        kvi=None,
+    ):
+
+        if isinstance(config, str):
+            with open(config) as rf:
+                config = json.load(rf)
+
+        if not isinstance(config, dict):
+            raise TypeError("Invalid config ...")
+
+        if "auth_mng" in config:
+            auth_mng = config.get("auth_mng")
+            if not isinstance(auth_mng, dict):
+                raise TypeError("Invalid config ...")
+        else:
+            auth_mng = config
+
+        base_url = auth_mng.get("url")
+        if not isinstance(base_url, str):
+            raise TypeError("Invalid config ...")
+
+        # kvi = KVI.from_json(
+        #     config=config.get("key_vault"),
+        #     secrets={
+        #         "webapp-registration-secret": "webapp-registration-secret-1",
+        #         "dm-to-am-secret": "dm-to-am-secret",
+        #     },
+        # )
+
+        auth_basic_creds = auth_mng.get("auth")
+
+        am_usr = None
+        am_pwd = None
+        if isinstance(auth_basic_creds, (list, tuple)):
+
+            if len(auth_basic_creds) == 1:
+                am_usr = auth_basic_creds[0]
+
+            elif len(auth_basic_creds) == 2:
+                am_usr, am_pwd = auth_basic_creds
+
+            else:
+                raise Exception("....")
+
+        elif isinstance(auth_basic_creds, dict):
+
+            am_usr = auth_basic_creds.get("user")
+            am_pwd = auth_basic_creds.get("pwd")
+
+        elif isinstance(auth_basic_creds, str):
+            am_usr = auth_basic_creds
+
+        if not isinstance(am_usr, str):
+            am_usr = "dm-to-am-secret"
+
+        if not isinstance(am_pwd, str):
+            if not isinstance(kvi, KVI):
+                raise Exception("....")
+
+            am_pwd = kvi.get("dm-to-am-secret")
+            if not isinstance(am_pwd, str):
+                raise Exception("....")
+
+        app_name = auth_mng.get("app_name")
+        if not isinstance(app_name, str):
+            raise TypeError("Invalid config ...")
+
+        return MatAuthManagerClient(
+            base_url=base_url,
+            auth=(am_usr, am_pwd),
+            app_name=app_name,
+            credentials=auth_mng.get("credentials"),
+            kvi=kvi,
+        )
+
+    # ------------------------------------------------------------------
+    # Token acquisition
+    # ------------------------------------------------------------------
+
+    def get_bearer_token(self, credentials: Optional[dict] = None) -> dict:
+        """
+        Request an application bearer token from the auth manager.
+
+        Returns the full token response dict
+        ``{"access_token": "…", "expires_in": 3600, …}``.
+
+        :class:`BearerToken` calls this automatically when the token is near expiry.
+
+        Parameters
+        ----------
+        credentials : Per-call override; uses instance credentials when None.
+        """
+        if credentials is not None:
+            self.validate_credentials(credentials)
+        else:
+            credentials = self.credentials
+
+        if credentials is None:
+            raise ValueError(
+                "No credentials available. Supply them at construction time "
+                "or pass them to get_bearer_token()."
+            )
+
+        headers: dict[str, str] = {}
+        if self.app_name is not None:
+            headers["App-Name"] = self.app_name
+
+        logger.debug("Requesting bearer token from %s.", _TOKEN_ENDPOINT)
+        return self.request(
+            "POST",
+            _TOKEN_ENDPOINT,
+            data=json.dumps({"credentials": credentials}),
+            headers=headers,
+        )
+
+    def refresh_token(self, refresh_token: str) -> Any:
+        """
+        Exchange a refresh token for a fresh user token (POST ``refresh-token``).
+
+        The app credentials (OAuth ``client_id``/``client_secret``) are sent as a
+        Basic ``credentials`` header and the refresh token in the JSON body. Returns
+        the parsed response dict (contains ``access_token`` on success).
+        """
+        headers: dict[str, str] = {}
+        creds = self.credentials or {}
+        client_id = creds.get("client_id")
+        client_secret = creds.get("client_secret")
+        if client_id and client_secret:
+            basic = b64encode(f"{client_id}:{client_secret}".encode()).decode()
+            headers["credentials"] = f"Basic {basic}"
+        if self.app_name is not None:
+            headers["App-Name"] = self.app_name
+
+        return self.request(
+            "POST",
+            "refresh-token",
+            data=json.dumps({"refresh_token": refresh_token}),
+            headers=headers,
+        )
+
+    # ------------------------------------------------------------------
+    # Credential validation
+    # ------------------------------------------------------------------
+
+    def validate_credentials(
+        self,
+        credentials: dict,
+        *,
+        kvi: Optional["KVI"] = None,
+    ) -> None:
+        """
+        Ensure credentials contain "client_id" and "client_secret".
+
+        Mutates the dict in place: a missing/invalid client_secret is fetched
+        from the key vault under the key "webapp-registration-secret".
+
+        Raises
+        ------
+        TypeError  : credentials is not a dict, or client_id has the wrong type.
+        KeyError   : a required key is missing and can't be sourced from the KV.
+        ValueError : the secret could not be retrieved from the key vault.
+        """
+        if not isinstance(credentials, dict):
+            raise TypeError(
+                f"credentials must be a dict, got {type(credentials).__name__}."
+            )
+
+        cs = credentials.get("client_secret")
+        if not isinstance(cs, str):
+            if kvi is None:
+                raise KeyError(
+                    "'client_secret' is missing from credentials and no "
+                    "KeyVaultInterface was provided to fetch it."
+                )
+            secret = kvi.get("webapp-registration-secret")
+            if not isinstance(secret, str):
+                raise ValueError(
+                    "Could not retrieve 'client_secret' from the key vault "
+                    "(key: 'webapp-registration-secret')."
+                )
+            credentials["client_secret"] = secret
+
+        if "client_id" not in credentials:
+            raise KeyError("'client_id' is missing from credentials.")
+
+        if not isinstance(credentials["client_id"], str):
+            raise TypeError(
+                f"'client_id' must be a string, got {type(credentials['client_id']).__name__}."
+            )
+
+    def check_user_permissions(
+        self,
+        token,
+        permissions=None,
+    ):
+        headers = {"appName": self.app_name, "App-Name": self.app_name}
+
+        if permissions is None:
+            permissions = {"permissions": {}}
+        body = {"user_token": token, "permissions": permissions}
+
+        return self.request(
+            method="POST",
+            endpoint="apif/check-user-permissions",
+            headers=headers,
+            json=body,
+        )
+
+    # ------------------------------------------------------------------
+    # User & group management
+    # ------------------------------------------------------------------
+
+    _USERS_ENDPOINT = "apif/users"
+    _USERS_SELECT = (
+        "id,displayName,mail,givenName,surname,"
+        "externalUserState,userType,userPrincipalName"
+    )
+
+    def _application_token(self) -> str:
+        """
+        Return a cached ``"Bearer <token>"`` application token for the user-management
+        endpoints, refreshing it from ``get_bearer_token`` shortly before expiry.
+
+        The token is cached in-memory on the client (a process-wide singleton), so
+        it is fetched at most once per ``expires_in`` window.
+        """
+        now = time.monotonic()
+        if self._app_token is not None and now < self._app_token_exp:
+            return self._app_token
+
+        resp = self.get_bearer_token()
+        access = resp.get("access_token") if isinstance(resp, dict) else None
+        if not access:
+            raise ValueError(
+                "Auth Manager did not return an application 'access_token'."
+            )
+        try:
+            ttl = int(resp.get("expires_in", 600))
+        except (TypeError, ValueError):
+            ttl = 600
+        self._app_token = f"Bearer {access}"
+        # refresh 180s early to avoid using a token that expires mid-flight
+        self._app_token_exp = now + max(0, ttl - 180)
+        return self._app_token
+
+    def _um_send(self, method: str, endpoint: str, **kwargs: Any) -> Any:
+        """
+        ``request`` variant for user-management endpoints: injects the cached
+        application token as the ``Application-Token`` header. Caller-supplied
+        headers take precedence on overlap.
+        """
+        headers = {
+            "Application-Token": self._application_token(),
+            **(kwargs.pop("headers", None) or {}),
+        }
+        return self.request(method, endpoint, headers=headers, **kwargs)
+
+    def get_users(self) -> list:
+        """List users from the Auth Manager user-management API.
+
+        Returns the parsed JSON list of users (a curated ``$select`` projection).
+        """
+        return self._um_send(
+            "GET", f"{self._USERS_ENDPOINT}?$select={self._USERS_SELECT}"
+        )
+
+    def create_users(self, users_data) -> Any:
+        """Create users via the Auth Manager user-management API."""
+        return self._um_send("POST", self._USERS_ENDPOINT, data=json.dumps(users_data))
+
+    def invite_users(self, users_data) -> Any:
+        """Invite users (POST ``apif/invitations``)."""
+        return self._um_send("POST", "apif/invitations", data=json.dumps(users_data))
+
+    def get_user_um(self, user_id: str) -> Any:
+        """Fetch a single user (GET ``apif/users/<id>``)."""
+        return self._um_send("GET", f"{self._USERS_ENDPOINT}/{user_id}")
+
+    def put_user(self, user_id: str, user_data) -> Any:
+        """Update a user (PUT ``apif/users/<id>``)."""
+        return self._um_send(
+            "PUT", f"{self._USERS_ENDPOINT}/{user_id}", data=json.dumps(user_data)
+        )
+
+    def delete_user(self, user_id: str) -> Any:
+        """Delete a user (DELETE ``apif/users/<id>``)."""
+        return self._um_send("DELETE", f"{self._USERS_ENDPOINT}/{user_id}")
+
+    def get_user_memberships(self, user_id: str) -> Any:
+        """List a user's group memberships (GET ``apif/users/<id>/memberships``)."""
+        return self._um_send("GET", f"{self._USERS_ENDPOINT}/{user_id}/memberships")
+
+    # --- groups ---
+
+    def get_groups(self, filters: Optional[str] = None) -> Any:
+        """List groups (GET ``apif/groups``), optionally filtered."""
+        endpoint = "apif/groups?$select=id,displayName"
+        if filters:
+            endpoint += f"&{filters}"
+        return self._um_send("GET", endpoint)
+
+    def create_groups(self, group_data) -> Any:
+        """Create groups (POST ``apif/groups``)."""
+        return self._um_send("POST", "apif/groups", data=json.dumps(group_data))
+
+    def get_group(self, group_id: str) -> Any:
+        """Fetch a single group (GET ``apif/groups/<id>``)."""
+        return self._um_send("GET", f"apif/groups/{group_id}")
+
+    def delete_group(self, group_id: str) -> Any:
+        """Delete a group (DELETE ``apif/groups/<id>``)."""
+        return self._um_send("DELETE", f"apif/groups/{group_id}")
+
+    def get_group_members(self, group_id: str) -> Any:
+        """List a group's members (GET ``apif/groups/<id>/members``)."""
+        return self._um_send("GET", f"apif/groups/{group_id}/members")
+
+    def add_members_to_group(
+        self, group_id: str, members, raise_on_error: bool = True
+    ) -> Any:
+        """Add members to a group (POST ``apif/groups/<id>/members``)."""
+        params = None if raise_on_error else {"raise": 0}
+        return self._um_send(
+            "POST",
+            f"apif/groups/{group_id}/members",
+            data=json.dumps(members),
+            params=params,
+        )
+
+    def remove_member_from_group(self, group_id: str, member_id: str) -> Any:
+        """Remove a member from a group (DELETE ``apif/groups/<id>/members?user_id=…``)."""
+        return self._um_send(
+            "DELETE", f"apif/groups/{group_id}/members", params={"user_id": member_id}
+        )
+
+    def remove_user_from_group(self, group_id: str, user_id: str) -> Any:
+        """Remove a user from a group (alias of :meth:`remove_member_from_group`)."""
+        return self.remove_member_from_group(group_id, user_id)
+
+    def put_group(self, group_id: str, group_data) -> Any:
+        """Update a group (PUT ``apif/groups/<id>``)."""
+        return self._um_send(
+            "PUT", f"apif/groups/{group_id}", data=json.dumps(group_data)
+        )
+
+    # --- profiles ---
+
+    def get_profiles(self, simple: bool = False) -> Any:
+        """List profiles (GET ``apif/profiles``)."""
+        endpoint = "apif/profiles?simple=1" if simple else "apif/profiles"
+        return self._um_send("GET", endpoint)
+
+    def create_profile(self, profile_data) -> Any:
+        """Create a profile (POST ``apif/profiles``)."""
+        return self._um_send("POST", "apif/profiles", data=json.dumps(profile_data))
+
+    def put_profile(self, profile_id: str, profile_data) -> Any:
+        """Update a profile (PUT ``apif/profiles/<id>``)."""
+        return self._um_send(
+            "PUT", f"apif/profiles/{profile_id}", data=json.dumps(profile_data)
+        )
+
+    def __repr__(self) -> str:
+        return f"MatAuthManagerClient(base_url={self.base_url!r}, app_name={self.app_name!r})"