feat(connector-superoffice): implement OAuth 2.0 flow and S2S architecture

Completed POC for SuperOffice integration with the following key achievements:
- Switched from RSA/SOAP to OAuth 2.0 (Refresh Token Flow) for better compatibility with SOD environment.
- Implemented robust token refreshing and caching mechanism in .
- Solved 'Wrong Subdomain' issue by enforcing  for tenant .
- Created  for REST API interaction (Search, Create, Update UDFs).
- Added helper scripts: , , .
- Documented usage and configuration in .
- Updated  configuration requirements.

[2ff88f42]

connector-superoffice/main.py

@@ -1,72 +1,59 @@
 import os
 import logging
 from dotenv import load_dotenv
+from auth_handler import AuthHandler
+from superoffice_client import SuperOfficeClient
 
-# Import the new classes
-from .auth_handler import AuthHandler
-from .superoffice_client import SuperOfficeClient
-
-# Configure logging
+# Setup logging
 logging.basicConfig(
     level=logging.INFO,
-    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-    handlers=[
-        logging.StreamHandler()
-    ]
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
 )
 logger = logging.getLogger(__name__)
 
 def main():
-    """
-    Main function to initialize and run the SuperOffice connector.
-    """
-    logger.info("Starting SuperOffice Connector Proof of Concept...")
-
-    # Load environment variables from the root .env file
-    dotenv_path = os.path.join(os.path.dirname(__file__), '..', '.env')
-    logger.info(f"Attempting to load .env file from: {dotenv_path}")
+    # Load .env from the root directory
+    load_dotenv(dotenv_path="../.env")
+    
+    logger.info("Starting SuperOffice Connector S2S POC...")
     
-    if os.path.exists(dotenv_path):
-        load_dotenv(dotenv_path=dotenv_path)
-        logger.info(".env file loaded successfully.")
-    else:
-        logger.error(f".env file not found at the expected location: {dotenv_path}")
-        logger.error("Please ensure the .env file exists in the project root directory.")
-        return
-
     try:
-        # 1. Initialize AuthHandler
-        auth_handler = AuthHandler()
-
-        # Define the tenant ID
-        TENANT_ID = "Cust26720" # As provided in the initial task description
-
-        # 2. Get a fresh access token (this will also update the refresh token if needed)
-        full_access_token = auth_handler.get_access_token()
-        logger.info(f"Full Access Token for curl: {full_access_token}")
-
-        # 3. Initialize SuperOfficeClient with the tenant ID
-        so_client = SuperOfficeClient(auth_handler, TENANT_ID)
-
-        # 3. Perform test connection
-        logger.info("--- Performing Connection Test ---")
-        connection_result = so_client.test_connection()
-        logger.info("--- Connection Test Finished ---")
-
-        if connection_result:
-            logger.info("POC Succeeded: Connection to SuperOffice API was successful.")
+        # Initialize Auth
+        auth = AuthHandler()
+        
+        # Initialize Client
+        client = SuperOfficeClient(auth)
+        
+        # 1. Test Connection
+        logger.info("Step 1: Testing connection...")
+        user_info = client.test_connection()
+        if user_info:
+            logger.info(f"Connected successfully as: {user_info.get('Name')}")
         else:
-            logger.error("POC Failed: Could not establish a connection to SuperOffice API.")
+            logger.error("Connection test failed.")
+            return
+
+        # 2. Search for a test contact
+        test_company = "Wackler Holding"
+        logger.info(f"Step 2: Searching for company '{test_company}'...")
+        contact = client.find_contact_by_criteria(name=test_company)
+        
+        if contact:
+            logger.info(f"Found contact: {contact.get('Name')} (ID: {contact.get('ContactId')})")
+            
+            # 3. Try to update UDFs (Warning: technical names might be wrong)
+            # logger.info("Step 3: Attempting UDF update (experimental)...")
+            # ai_test_data = {
+            #     "potential": "High",
+            #     "industry": "Facility Management",
+            #     "summary": "KI-Analyse erfolgreich durchgeführt."
+            # }
+            # client.update_udfs(contact.get('ContactId'), ai_test_data)
+        else:
+            logger.info(f"Contact '{test_company}' not found.")
 
-    except ValueError as ve:
-        logger.error(f"Configuration Error: {ve}")
-        logger.error("POC Failed due to missing configuration.")
     except Exception as e:
-        logger.error(f"An unexpected error occurred during the POC execution: {e}", exc_info=True)
-        logger.error("POC Failed due to an unexpected error.")
-
-
-    logger.info("SuperOffice Connector POC finished.")
+        logger.error(f"An error occurred: {e}", exc_info=True)
 
 if __name__ == "__main__":
-    main()
+    main()