Merge pull request #6 from itk-dev-rpa/release/1.1.0

Release/1.1.0

Author: ghbm-itk

.github/workflows/Linting.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11"]
+        python-version: ["3.12"]
       fail-fast: false
     steps:
     - uses: actions/checkout@v4

README.md

@@ -1,6 +1,6 @@
 # python_serviceplatformen
 
-This project is made to hopefully make it easier to use Kombit's Serviceplatformen API.
+This project is made to make it easier to use Kombit's Serviceplatformen API.
 
 ## Certificates and authentication
 
@@ -27,9 +27,97 @@ class and it will handle the rest for you.
 
 ```python
 from python_serviceplatformen.authentication import KombitAccess
-ka = KombitAccess(cvr=cvr, cert_path=cert_path)
+kombit_access = KombitAccess(cvr="12345678", cert_path="C:\something\Certificate.pem", test=False)
 ```
 
+If you want to use the test system instead pass `test=True` to KombitAccess.
+
+## Digital Post
+
+This library supports the full functionality of Digital Post including NemSMS.
+
+### Check registration
+
+You can easily check if someone is registered for Digital Post or NemSMS:
+
+```python
+digital_post.is_registered(cpr="1234567890", service="digitalpost", kombit_access=kombit_access)
+digital_post.is_registered(cpr="1234567890", service="nemsms", kombit_access=kombit_access)
+```
+
+### MeMo model
+
+A detailed data class model has been defined to help define MeMo objects which are used
+in the api.
+
+The entire model is located in the message module:
+
+```python
+from python_serviceplatformen.models.message import Message
+```
+
+A detailed description of the model and all attributes can be found in the official documentation:
+[MeMo - Digitaliser.dk](https://digitaliser.dk/digital-post/vejledninger/memo)
+
+**Note:** The model doesn't follow the normal python naming conventions to follow the source names as close as possible.
+
+### Send Digital Post
+
+To send a message construct a message object and then send it off to the send_message function:
+
+```python
+import uuid
+from datetime import datetime
+import base64
+
+from python_serviceplatformen.authentication import KombitAccess
+from python_serviceplatformen import digital_post
+from python_serviceplatformen.models.message import (
+    Message, MessageHeader, Sender, Recipient, MessageBody, MainDocument, File
+)
+
+kombit_access = KombitAccess(cvr="55133018", cert_path=r"C:\Users\az68933\Desktop\SF1601\Certificate.pem")
+
+m = Message(
+    messageHeader=MessageHeader(
+        messageType="DIGITALPOST",
+        messageUUID=str(uuid.uuid4()),
+        label="Digital Post test message",
+        mandatory=False,
+        legalNotification=False,
+        sender=Sender(
+            senderID="12345678",
+            idType="CVR",
+            label="Python Serviceplatformen"
+        ),
+        recipient=Recipient(
+            recipientID="1234567890",
+            idType="CPR"
+        )
+    ),
+    messageBody=MessageBody(
+        createdDateTime=datetime.now(),
+        mainDocument=MainDocument(
+            files=[
+                File(
+                    encodingFormat="text/plain",
+                    filename="Besked.txt",
+                    language="da",
+                    content=base64.b64encode(b"Hello World").decode()
+                )
+            ]
+        )
+    )
+)
+
+digital_post.send_message("Digital Post", m, kombit_access)
+```
+
+### Recipes
+
+The message module also contains a few static helper functions to construct simple messages. These are not meant to
+be all encompassing but to help as a starting point.
+
 ## Tests
 
 This project contains automated tests in the "tests" folder.
@@ -46,4 +134,13 @@ Create a .env file in the project folder and fill out these variables:
 ```yaml
 KOMBIT_TEST_CVR = "XXXXXXXX"  # The cvr of the organization who owns the certificate
 KOMBIT_TEST_CERT_PATH = "C:\something\Certificate.pem"  # The path to the certificate file
+DIGITAL_POST_TEST_CPR = "xxxxxxxxxx"  # The receiver of the test messages
+```
+
+### Running the tests
+
+To run all tests open a command line in the project folder and run:
+
+```bash
+python -m unittest
 ```

changelog.md

@@ -7,12 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+nop
+
+## [1.1.0] - 2024-11-01
+
+### Added
+
+- Complete data class model of MeMo objects.
+- Tools to verify and convert MeMo objects to xml.
+- Function for sending a MeMo message.
+- Helper functions to create simple MeMo messages.
+
 ## [1.0.0] - 19-09-2024
 
 ### Added
 
 - Module for authenticating towards Kombit's Serviceplatform API.
 - Function for checking if someone is registered for Digital Post or NemSMS.
 
-[Unreleased]: https://github.com/itk-dev-rpa/python-serviceplatformen/compare/1.0.0...HEAD
+[Unreleased]: https://github.com/itk-dev-rpa/python-serviceplatformen/compare/1.1.0...HEAD
+[1.1.0]: https://github.com/itk-dev-rpa/python-serviceplatformen/releases/tag/1.1.0
 [1.0.0]: https://github.com/itk-dev-rpa/python-serviceplatformen/releases/tag/1.0.0

pyproject.toml

@@ -4,20 +4,21 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python_serviceplatformen"
-version = "1.0.0"
+version = "1.1.0"
 authors = [
   { name="ITK Development", email="[email protected]" },
 ]
 description = "Python modules for easier use of Kombit's serviceplatformen."
 readme = "README.md"
-requires-python = ">=3.7"
+requires-python = ">=3.10, <3.13"
 classifiers = [
     "Programming Language :: Python :: 3",
     "License :: OSI Approved :: MIT License",
 ]
 dependencies = [
   "requests == 2.*",
-  "cryptography"
+  "cryptography",
+  "xmlschema"
 ]
 
 [project.urls]
@@ -30,3 +31,6 @@ dev = [
   "flake8",
   "pylint"
 ]
+
+[tool.setuptools.package-data]
+"*" = ["*.xsd"]

python_serviceplatformen/authentication.py

@@ -61,7 +61,7 @@ def get_access_token(self, entity_id: str) -> str:
             self._access_tokens[entity_id] = access_token
             return access_token[0]
         except HTTPError as exc:
-            raise ValueError(f"Couldn't obtain access token for {entity_id}") from exc
+            raise ValueError(f"Couldn't obtain access token for {entity_id}: {exc.response.text}") from exc
 
 
 def _get_saml_token(cvr: str, cert_path: str, entity_id: str, test: bool) -> str:

python_serviceplatformen/date_helper.py

@@ -1,10 +1,17 @@
-"""This module contains function to help with datetimes in the Kombit API."""
+"""This module contains functions to help with dates and datetimes in the Kombit API."""
 
-from datetime import datetime
+from datetime import datetime, date
 
 
-def format_datetime(_datetime: datetime) -> str:
+def format_datetime(datetime_: datetime) -> str:
     """Convert a datetime object to a string with the format:
     %Y-%m-%dT%H:%M:%SZ
     """
-    return _datetime.strftime('%Y-%m-%dT%H:%M:%SZ')
+    return datetime_.strftime('%Y-%m-%dT%H:%M:%SZ')
+
+
+def format_date(date_: date) -> str:
+    """Convert a date object to a string with the format:
+    %Y-%m-%d
+    """
+    return date_.strftime('%Y-%m-%d')

python_serviceplatformen/digital_post.py

@@ -1,16 +1,19 @@
-"""This moduel contains helper functions to use the SF1601 Kombit API.
+"""This module contains helper functions to use the SF1601 Kombit API.
 https://digitaliseringskataloget.dk/integration/sf1601
 """
 
 import urllib.parse
 import uuid
 from datetime import datetime
 from typing import Literal
+from xml.etree import ElementTree
 
 import requests
 
 from python_serviceplatformen.authentication import KombitAccess
 from python_serviceplatformen.date_helper import format_datetime
+from python_serviceplatformen.models import xml_util
+from python_serviceplatformen.models.message import Message
 
 
 def is_registered(cpr: str, service: Literal['digitalpost', 'nemsms'], kombit_access: KombitAccess) -> bool:
@@ -41,3 +44,41 @@ def is_registered(cpr: str, service: Literal['digitalpost', 'nemsms'], kombit_ac
     response = requests.get(url, params=parameters, headers=headers, timeout=10)
     response.raise_for_status()
     return response.json()['result']
+
+
+def send_message(message_type: Literal['Digital Post', 'NemSMS'],
+                 message: Message, kombit_access: KombitAccess) -> str:
+    """Send a Message object as Digital Post or NemSMS.
+
+    Args:
+        message_type: The type of message to send.
+        message: The Message object to send.
+        kombit_access: The KombitAccess objet used to authenticate.
+
+    Returns:
+        The uuid of the transaction to trace the message later.
+    """
+    url = urllib.parse.urljoin(kombit_access.environment, "service/KombiPostAfsend_1/memos")
+
+    transaction_id = str(uuid.uuid4())
+
+    headers = {
+        "X-TransaktionsId": transaction_id,
+        "X-TransaktionsTid": format_datetime(datetime.now()),
+        "authorization": kombit_access.get_access_token("http://entityid.kombit.dk/service/kombipostafsend/1"),
+        "Content-Type": "application/xml"
+    }
+
+    message_xml = xml_util.dataclass_to_xml(message)
+    xml_util.validate_memo(message_xml)
+
+    element = ElementTree.Element("kombi_request")
+    ElementTree.SubElement(element, "KombiValgKode").text = message_type
+    element.append(message_xml)
+
+    xml_body = ElementTree.tostring(element, encoding="utf8").decode()
+
+    response = requests.post(url=url, headers=headers, data=xml_body, timeout=10)
+    response.raise_for_status()
+
+    return transaction_id