neris-api-client 1.1.0__tar.gz → 1.2.0.post0__tar.gz

neris_api_client-1.2.0.post0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.1
+Name: neris_api_client
+Version: 1.2.0.post0
+Summary: NERIS API Client
+Author-email: Ben Coleman <ben.coleman@ul.org>, Tommy Messbauer <thomas.messbauer@ul.org>
+Project-URL: Homepage, https://github.com/ulfsri/neris-api-client
+Project-URL: Issues, https://neris.atlassian.net/servicedesk/customer/portal/3/group/3/create/10027
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: pydantic[email]>=2
+Requires-Dist: python-dotenv
+
+# NERIS API Client
+
+A Python class to interact with the NERIS API programmatically.
+
+## Installation
+
+To install:
+```bash
+pip install neris-api-client
+```
+Package published on PyPi: [`NERIS API Client`](https://pypi.org/project/neris-api-client/)
+
+## Usage
+
+**Auth with password `auth` flow**
+
+All config parameters can be specified as environment variables prefixed with `NERIS_` e.g. `NERIS_GRANT_TYPE=password`.
+```python
+from neris_api_client import NerisApiClient, Config
+
+client = NerisApiClient(
+    Config(
+        base_url="https://api-test.neris.fsri.org/v1",
+        grant_type="password",
+        username="neris.user@email.co",
+        password="*******",
+    )
+)
+
+# Get an entity
+entity = client.get_entity("FD24027240")
+
+# If MFA enabled, prompt for auth challenge answer
+Provide MFA code for email_otp: ******
+```
+
+**Auth with `client_credentials` auth flow**
+
+All config parameters can be specified as environment variables prefixed with `NERIS_` e.g. `NERIS_GRANT_TYPE=client_credentials`.
+```python
+from neris_api_client import NerisApiClient, Config
+
+client = NerisApiClient(
+    Config(
+        base_url="https://api-test.neris.fsri.org/v1",
+        grant_type="client_credentials",
+        client_id="********************",
+        client_secret="***************",
+    )
+)
+
+# Get an entity
+entity = client.get_entity("FD24027240")
+```
+
+**Using environment varables to instantiate the library**
+
+[Configuration should be stored in the environment](https://12factor.net/config). The following uses `dotenv` to load the configuration, but you can use whatever you like. In the cloud, you might load all of these values into the environment from an encrypted parameter store. 
+
+All variables prefixed are prefixed with `NERIS_`
+
+* See [env.example](./examples/.env.example) for the parameter options. 
+* Store the `/env` file in the current working directory. 
+
+```python
+from dotenv import load_dotenv
+from neris_api_client import NerisApiClient, Config
+
+ # Credentials must be defined in .env
+load_dotenv()
+client = NerisApiClient()
+
+# Get an entity
+entity = client.get_entity("FD24027240")
+```
+
+## Disclaimer
+The models in this package are generated using [`datamodel-code-generator`](https://github.com/koxudaxi/datamodel-code-generator) and are not guaranteed
+to contain all of the information present in the full specification. The generated models are used to validate request payloads prior to
+API submission.
+
+## Additional Information
+To ask a question, make a suggestion, or otherwise get help with the NERIS API Client, please visit [the NERIS helpdesk](https://neris.atlassian.net/servicedesk/customer/portals).
+
+**Beta sandbox users**:
+- Be sure to use the base URL `https://api-test.neris.fsri.org/v1` with the NERIS API Client. You will not be able to authenticate requests in the other environments.
+- For the beta testing period, your user is only authorized to perform actions on behalf of the FSRI Fire Department `FD24027214`.

neris_api_client-1.2.0.post0/README.md

@@ -0,0 +1,87 @@
+# NERIS API Client
+
+A Python class to interact with the NERIS API programmatically.
+
+## Installation
+
+To install:
+```bash
+pip install neris-api-client
+```
+Package published on PyPi: [`NERIS API Client`](https://pypi.org/project/neris-api-client/)
+
+## Usage
+
+**Auth with password `auth` flow**
+
+All config parameters can be specified as environment variables prefixed with `NERIS_` e.g. `NERIS_GRANT_TYPE=password`.
+```python
+from neris_api_client import NerisApiClient, Config
+
+client = NerisApiClient(
+    Config(
+        base_url="https://api-test.neris.fsri.org/v1",
+        grant_type="password",
+        username="neris.user@email.co",
+        password="*******",
+    )
+)
+
+# Get an entity
+entity = client.get_entity("FD24027240")
+
+# If MFA enabled, prompt for auth challenge answer
+Provide MFA code for email_otp: ******
+```
+
+**Auth with `client_credentials` auth flow**
+
+All config parameters can be specified as environment variables prefixed with `NERIS_` e.g. `NERIS_GRANT_TYPE=client_credentials`.
+```python
+from neris_api_client import NerisApiClient, Config
+
+client = NerisApiClient(
+    Config(
+        base_url="https://api-test.neris.fsri.org/v1",
+        grant_type="client_credentials",
+        client_id="********************",
+        client_secret="***************",
+    )
+)
+
+# Get an entity
+entity = client.get_entity("FD24027240")
+```
+
+**Using environment varables to instantiate the library**
+
+[Configuration should be stored in the environment](https://12factor.net/config). The following uses `dotenv` to load the configuration, but you can use whatever you like. In the cloud, you might load all of these values into the environment from an encrypted parameter store. 
+
+All variables prefixed are prefixed with `NERIS_`
+
+* See [env.example](./examples/.env.example) for the parameter options. 
+* Store the `/env` file in the current working directory. 
+
+```python
+from dotenv import load_dotenv
+from neris_api_client import NerisApiClient, Config
+
+ # Credentials must be defined in .env
+load_dotenv()
+client = NerisApiClient()
+
+# Get an entity
+entity = client.get_entity("FD24027240")
+```
+
+## Disclaimer
+The models in this package are generated using [`datamodel-code-generator`](https://github.com/koxudaxi/datamodel-code-generator) and are not guaranteed
+to contain all of the information present in the full specification. The generated models are used to validate request payloads prior to
+API submission.
+
+## Additional Information
+To ask a question, make a suggestion, or otherwise get help with the NERIS API Client, please visit [the NERIS helpdesk](https://neris.atlassian.net/servicedesk/customer/portals).
+
+**Beta sandbox users**:
+- Be sure to use the base URL `https://api-test.neris.fsri.org/v1` with the NERIS API Client. You will not be able to authenticate requests in the other environments.
+- For the beta testing period, your user is only authorized to perform actions on behalf of the FSRI Fire Department `FD24027214`.

{neris_api_client-1.1.0 → neris_api_client-1.2.0.post0}/pyproject.toml

@@ -4,9 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "neris_api_client"
-version = "1.1.0"
+version = "1.2.0.post0"
 authors = [
   { name="Ben Coleman", email="ben.coleman@ul.org" },
+  { name="Tommy Messbauer", email="thomas.messbauer@ul.org" },
 ]
 description = "NERIS API Client"
 readme = "README.md"
@@ -17,11 +18,9 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
-    "boto3",
-    "PyJWT",
     "requests",
     "pydantic[email]>=2",
-    "typing_extensions",
+    "python-dotenv",
 ]
 
 [project.urls]

{neris_api_client-1.1.0 → neris_api_client-1.2.0.post0}/src/neris_api_client/__init__.py

@@ -1 +1,2 @@
 from .client import *
+from .config import *

neris_api_client-1.2.0.post0/src/neris_api_client/client.py

@@ -0,0 +1,326 @@
+import base64
+from http import HTTPStatus
+import json
+from uuid import UUID
+from typing import List, Optional, Dict, Any
+from datetime import datetime, timedelta
+
+import requests
+from pydantic import BaseModel
+
+from .config import Config, GrantType, TokenSet
+
+from .models import (
+    IncidentPayload,
+    PatchUnitPayload,
+    CreateUserPayload,
+    DepartmentPayload,
+    UpdateUserPayload,
+    PatchStationPayload,
+    PatchDepartmentPayload,
+    CreateDepartmentPayload,
+    PatchIncidentAction,
+    TypeIncidentStatusValue,
+)
+
+__all__ = ("NerisApiClient",)
+
+
+class Encoder(json.JSONEncoder):
+    def default(self, obj):
+        if isinstance(obj, requests.structures.CaseInsensitiveDict):
+            return {k: v for k, v in obj.items()}
+
+        return super().default(obj)
+
+
+class _NerisApiClient:
+    config: Config
+    tokens: TokenSet | None = TokenSet(access_token="", refresh_token="", expires_at=datetime.min)
+    _session: requests.Session = requests.Session()
+
+    def __init__(self, config: Config | None = None):
+        if config is None:
+            config = Config()  # by default it loads from env
+
+        match config.grant_type:
+            case GrantType.CLIENT_CREDENTIALS:
+                assert config.client_id is not None
+                assert config.client_secret is not None
+            case GrantType.PASSWORD:
+                assert config.username is not None
+                assert config.password is not None
+            case _:
+                raise Exception("Bad grant type. Must be \"password\" or \"client_credentials\"")
+
+        self.config = config
+
+    def _update_auth(self) -> None:
+        res: requests.Response | None = None
+        token_url: str = f"{self.config.base_url}/token"
+
+        if self.tokens.expires_at <= datetime.now() and not self.tokens.refresh_token:
+            match self.config.grant_type:
+                case GrantType.PASSWORD:
+                    res = self._session.post(
+                        token_url,
+                        headers={},
+                        json={
+                            "grant_type": GrantType.PASSWORD,
+                            "username": self.config.username,
+                            "password": self.config.password,
+                        },
+                    )
+
+                case GrantType.CLIENT_CREDENTIALS:
+                    client_creds = base64.b64encode(f"{self.config.client_id}:{self.config.client_secret}".encode("utf-8")).decode("utf-8")
+
+                    res = self._session.post(
+                        token_url,
+                        headers={"Authorization": f"Basic {client_creds}"},
+                        json={"grant_type": GrantType.CLIENT_CREDENTIALS},
+                    )
+
+        elif self.tokens.expires_at <= datetime.now():
+            match self.config.grant_type:
+                case GrantType.PASSWORD:
+                    res = self._session.post(
+                        token_url,
+                        # No basic auth needed for Cognito refresh tokens
+                        headers={},
+                        json={
+                            "grant_type": "refresh_token",
+                            "refresh_token": self.tokens.refresh_token,
+                        },
+                    )
+
+                case GrantType.CLIENT_CREDENTIALS:
+                    res = self._session.post(
+                        token_url,
+                        headers={"Authorization": f"Basic {client_creds}"},
+                        json={
+                            "grant_type": "refresh_token",
+                            "refresh_token": self.tokens.refresh_token,
+                        },
+                    )
+
+        if not res:
+            return
+
+        while True:
+            if self.config.debug:
+                print(
+                    json.dumps(
+                        {
+                            "token_response": {
+                                "status_code": res.status_code,
+                                "headers": res.headers,
+                                "content": res.text,
+                            }
+                        },
+                        indent=4,
+                        cls=Encoder,
+                    ),
+                )
+
+            got: dict = res.json()
+
+            # Successfully generated tokens
+            if res.status_code == HTTPStatus.OK:
+                self.tokens = TokenSet(
+                    access_token=got["access_token"],
+                    refresh_token=got["refresh_token"],
+                    expires_at=datetime.now() + timedelta(seconds=got["expires_in"]),
+                )
+
+                break
+
+            # Respond to MFA challenge
+            elif res.status_code == HTTPStatus.ACCEPTED:
+                code: str = input(f"Provide MFA code for {got['challenge_name']}: ")
+
+                res = self._session.post(
+                    token_url,
+                    headers={},
+                    json={
+                        "grant_type": got["challenge_name"],
+                        "username": self.config.username,
+                        "session": got["session"],
+                        got["challenge_name"]: code,
+                    }
+                )
+
+    def _call(
+        self,
+        method: str,
+        path: str,
+        data: Optional[str | Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        model: Optional[BaseModel] = None,
+    ):
+        self._update_auth()
+        self._session.headers.update({"Authorization": f"Bearer {self.tokens.access_token}"})
+
+        if model:
+            if isinstance(data, str):
+                data = model.model_validate_json(data).model_dump(mode="json", by_alias=True)
+            if isinstance(data, dict):
+                data = model.model_validate(data).model_dump(mode="json", by_alias=True)
+
+
+        res = getattr(self._session, method)(f"{self.config.base_url}{path}", json=data, params=params)
+
+        if self.config.debug:
+            print(
+                json.dumps(
+                    {
+                        "request": {
+                            "url": f"{self.config.base_url}{path}",
+                            "body": data,
+                            "headers": self._session.headers,
+                            "params": params,
+                        },
+
+                        "response": {
+                            "status_code": res.status_code,
+                            "headers": res.headers,
+                            "content": res.text,
+                        }
+                    },
+                    indent=4,
+                    cls=Encoder,
+                ),
+            )
+
+        try:
+            res.raise_for_status()
+        except requests.exceptions.HTTPError as e:
+            try:
+                e.args = e.args + (e.response.json(),)
+            except requests.exceptions.JSONDecodeError as f:
+                e.args = e.args + (e.response.text,)
+            finally:
+                print(str(e))
+                return res
+
+        try:
+            response = res.json()
+        except requests.exceptions.JSONDecodeError:
+            response = res.text
+
+        return response
+
+
+class NerisApiClient(_NerisApiClient):
+    def health(self):
+        return self._call("get", "/health")
+
+    def get_entity(self, neris_id: str) -> Dict[str, Any]:
+        return self._call("get", f"/entity/{neris_id}")
+
+    def create_entity(self, body: str | Dict[str, Any]) -> Dict[str, Any]:
+        return self._call("post", "/entity/", body, model=CreateDepartmentPayload)
+
+    def update_entity(self, neris_id: str, body: str | Dict[str, Any]) -> Dict[str, Any]:
+        return self._call("put", f"/entity/{neris_id}", body, model=DepartmentPayload)
+
+    def get_user(self, sub: str | UUID) -> Dict[str, Any]:
+        return self._call("get", f"/user/{sub}")
+
+    def create_user(self, body: str | Dict[str, Any]) -> Dict[str, Any]:
+        return self._call("post", "/user", body, model=CreateUserPayload)
+
+    def update_user(self, sub: str | UUID, body: str | Dict[str, Any]) -> Dict[str, Any]:
+        return self._call("put", f"/user/{sub}", body, model=UpdateUserPayload)
+
+    def delete_user(self, sub: str | UUID) -> None:
+        self._call("delete", f"/user/{sub}")
+
+    def create_user_role_entity_set_attachment(self, sub_user: str | UUID, nuid_role: str | UUID, nuid_entity_set: str | UUID) -> Dict[str, Any]:
+        return self._call(
+            "post",
+            "/auth/user_role_entity_set_attachment",
+            params={"sub_user": str(sub_user), "nuid_role": str(nuid_role), "nuid_entity_set": str(nuid_entity_set)},
+        )
+
+    def create_user_entity_membership(self, sub: str | UUID, neris_id: str) -> None:
+        self._call("post", f"/user/{sub}/user_entity_membership/{neris_id}")
+
+    def delete_user_entity_membership(self, sub: str | UUID, neris_id: str) -> None:
+        self._call("delete", f"/user/{sub}/user_entity_membership/{neris_id}")
+
+    def update_user_entity_activation(self, sub: str | UUID, neris_id: str, active: bool) -> None:
+        self._call(
+            "put",
+            f"/user/{sub}/user_entity_activation/{neris_id}",
+            data={"active": active},
+        )
+
+    def list_user_entity_memberships(self, sub: str | UUID) -> List[Dict[str, Any]]:
+        return self._call("get", f"/user/{sub}/user_entity_membership")
+
+    def create_incident(self, neris_id: str, body: str | Dict[str, Any]) -> Dict[str, Any]:
+        return self._call("post", f"/incident/{neris_id}", data=body, model=IncidentPayload)
+
+    def validate_incident(self, neris_id: str, body: str | Dict[str, Any]) -> Dict[str, Any]:
+        return self._call(
+            "post", f"/incident/{neris_id}/validate", data=body, model=IncidentPayload
+        )
+
+    def patch_entity(self, neris_id: str, body: str | Dict[str, Any]) -> Dict[str, Any]:
+        return self._call("patch", f"/entity/{neris_id}", data=body, model=PatchDepartmentPayload)
+
+    def patch_station(
+        self, neris_id_entity: str, neris_id_station: str, body: str | Dict[str, Any]
+    ) -> Dict[str, Any]:
+        return self._call(
+            "patch",
+            f"/entity/{neris_id_entity}/station/{neris_id_station}",
+            data=body,
+            model=PatchStationPayload,
+        )
+
+    def patch_unit(
+        self,
+        neris_id_entity: str,
+        neris_id_station: str,
+        neris_id_unit: str,
+        body: str | Dict[str, Any],
+    ) -> Dict[str, Any]:
+        return self._call(
+            "patch",
+            f"/entity/{neris_id}/station/{neris_id_station}/unit/{neris_id_unit}",
+            data=body,
+            model=PatchUnitPayload,
+        )
+
+    def patch_incident(
+        self, neris_id_entity: str, neris_id_incident: str, body: str | Dict[str, Any]
+    ) -> Dict[str, Any]:
+        return self._call(
+            "patch",
+            f"/incident/{neris_id_entity}/{neris_id_incident}",
+            data=body,
+            model=PatchIncidentAction,
+        )
+
+    def update_incident_status(
+        self, neris_id_entity: str, neris_id_incident: str, status: TypeIncidentStatusValue
+    ) -> Dict[str, Any]:
+        return self._call(
+            "put",
+            f"/incident/{neris_id_entity}/{neris_id_incident}/status",
+            data={"status": str(status)},
+        )
+
+    def create_api_integration(self, neris_id: str, title: str) -> Dict[str, Any]:
+        return self._call("post", f"/account/integration/{neris_id}", data={ "title": title })
+
+    def generate_api_secret(self, client_id: str) -> Dict[str, Any]:
+        return self._call("post", f"/account/credential/{client_id}")
+
+    def list_integrations(self, neris_id: str) -> Dict[str, Any]:
+        return self._call("get", f"/account/integration/{neris_id}/list")
+
+    def enroll_integration(self, neris_id: str, client_id: UUID | str) -> Dict[str, Any]:
+        return self._call("post", f"/account/enrollment/{neris_id}/{client_id}")

neris_api_client-1.2.0.post0/src/neris_api_client/config.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+import os
+
+class GrantType(str, Enum):
+    CLIENT_CREDENTIALS = "client_credentials"
+    PASSWORD = "password"
+
+@dataclass
+class Config:
+    base_url: str | None = None
+    debug: bool | None = None
+    username: str | None = None
+    password: str | None = None
+    client_id: str | None = None
+    client_secret: str | None = None
+    grant_type: GrantType | None = None
+
+    def __post_init__(self):
+        # env var handling
+        self.base_url = self.base_url or os.getenv("NERIS_BASE_URL")
+        self.debug = self.debug if self.debug is not None else os.getenv("NERIS_DEBUG") == "true"
+
+        match os.getenv("NERIS_GRANT_TYPE"):
+            case GrantType.PASSWORD:
+                self.grant_type = self.grant_type or GrantType.PASSWORD
+                self.username = self.username or os.getenv("NERIS_USERNAME")
+                self.password = self.password or os.getenv("NERIS_PASSWORD")
+            case GrantType.CLIENT_CREDENTIALS:
+                self.grant_type = self.grant_type or GrantType.CLIENT_CREDENTIALS
+                self.client_id = self.client_id or os.getenv("NERIS_CLIENT_ID")
+                self.client_secret = self.client_secret or os.getenv("NERIS_CLIENT_SECRET")
+
+
+@dataclass
+class TokenSet:
+    access_token: str
+    refresh_token: str
+    expires_at: datetime