feat: sap dms sdk addition

.env_integration_tests.example

@@ -13,3 +13,6 @@ CLOUD_SDK_CFG_DESTINATION_DEFAULT_CLIENTSECRET=your-destination-client-secret-he
 CLOUD_SDK_CFG_DESTINATION_DEFAULT_URL=https://your-destination-auth-url-here
 CLOUD_SDK_CFG_DESTINATION_DEFAULT_URI=https://your-destination-configuration-uri-here
 CLOUD_SDK_CFG_DESTINATION_DEFAULT_IDENTITYZONE=your-identity-zone-here
+
+CLOUD_SDK_CFG_SDM_DEFAULT_URI=https://your-sdm-api-uri-here
+CLOUD_SDK_CFG_SDM_DEFAULT_UAA='{"url":"https://your-auth-url","clientid":"your-client-id","clientsecret":"your-client-secret","identityzone":"your-identity-zone"}'

README.md

@@ -13,6 +13,7 @@ The Python SDK offers a clean, type-safe API following Python best practices whi
 - **AI Core Integration**
 - **Audit Log Service**
 - **Destination Service**
+- **Document Management Service**
 - **ObjectStore Service**
 - **Secret Resolver**
 - **Telemetry & Observability**
@@ -49,6 +50,7 @@ Each module has comprehensive usage guides:
 
 - [AuditLog](src/sap_cloud_sdk/core/auditlog/user-guide.md)
 - [Destination](src/sap_cloud_sdk/destination/user-guide.md)
+- [DMS](src/sap_cloud_sdk/dms/user-guide.md)
 - [ObjectStore](src/sap_cloud_sdk/objectstore/user-guide.md)
 - [Secret Resolver](src/sap_cloud_sdk/core/secret_resolver/user-guide.md)
 - [Telemetry](src/sap_cloud_sdk/core/telemetry/user-guide.md)

src/sap_cloud_sdk/core/telemetry/module.py

@@ -10,6 +10,7 @@ class Module(str, Enum):
     AUDITLOG = "auditlog"
     DESTINATION = "destination"
     OBJECTSTORE = "objectstore"
+    DMS = "dms"
 
     def __str__(self) -> str:
         return self.value

src/sap_cloud_sdk/core/telemetry/operation.py

@@ -52,5 +52,34 @@ class Operation(str, Enum):
     AICORE_SET_CONFIG = "set_aicore_config"
     AICORE_AUTO_INSTRUMENT = "auto_instrument"
 
+    # DMS Operations
+    DMS_ONBOARD_REPOSITORY = "onboard_repository"
+    DMS_GET_REPOSITORY = "get_repository"
+    DMS_GET_ALL_REPOSITORIES = "get_all_repositories"
+    DMS_UPDATE_REPOSITORY = "update_repository"
+    DMS_DELETE_REPOSITORY = "delete_repository"
+    DMS_CREATE_CONFIG = "create_config"
+    DMS_GET_CONFIGS = "get_configs"
+    DMS_UPDATE_CONFIG = "update_config"
+    DMS_DELETE_CONFIG = "delete_config"
+
+    # DMS CMIS Operations
+    DMS_CREATE_FOLDER = "create_folder"
+    DMS_CREATE_DOCUMENT = "create_document"
+    DMS_CHECK_OUT = "check_out"
+    DMS_CHECK_IN = "check_in"
+    DMS_CANCEL_CHECK_OUT = "cancel_check_out"
+    DMS_APPLY_ACL = "apply_acl"
+    DMS_GET_OBJECT = "get_object"
+    DMS_GET_CONTENT = "get_content"
+    DMS_UPDATE_PROPERTIES = "update_properties"
+    DMS_GET_CHILDREN = "get_children"
+    # Value is "delete_cmis_object" (not "delete_object") to avoid collision
+    # with OBJECTSTORE_DELETE_OBJECT which already uses "delete_object".
+    DMS_DELETE_OBJECT = "delete_cmis_object"
+    DMS_RESTORE_OBJECT = "restore_object"
+    DMS_APPEND_CONTENT_STREAM = "append_content_stream"
+    DMS_CMIS_QUERY = "cmis_query"
+
     def __str__(self) -> str:
         return self.value

src/sap_cloud_sdk/dms/__init__.py

@@ -0,0 +1,100 @@
+"""SAP Cloud SDK for Python - Document Management Service (DMS) module
+
+The create_client() function loads credentials from mounts/env vars and points
+to an instance in the cloud.
+
+Usage:
+    from sap_cloud_sdk.dms import create_client
+
+    # Recommended: use the factory which configures OAuth/HTTP from environment
+    client = create_client()
+
+    # Or specify a named instance
+    client = create_client(instance="my-sdm-instance")
+
+    # List all onboarded repositories
+    repos = client.get_all_repositories()
+
+    # Create a folder
+    folder = client.create_folder(repo.id, root_folder_id, "MyFolder")
+
+    # Upload a document
+    with open("file.pdf", "rb") as f:
+        doc = client.create_document(
+            repo.id, folder.object_id, "file.pdf", f, mime_type="application/pdf"
+        )
+"""
+
+from typing import Optional
+
+from sap_cloud_sdk.core.telemetry import Module
+from sap_cloud_sdk.dms.model import (
+    Ace,
+    Acl,
+    ChildrenOptions,
+    ChildrenPage,
+    CmisObject,
+    DMSCredentials,
+    Document,
+    Folder,
+    QueryOptions,
+    QueryResultPage,
+    UserClaim,
+)
+from sap_cloud_sdk.dms.client import DMSClient
+from sap_cloud_sdk.dms.config import load_sdm_config_from_env_or_mount
+from sap_cloud_sdk.dms.exceptions import DMSError
+
+
+def create_client(
+    *,
+    instance: Optional[str] = None,
+    dms_cred: Optional[DMSCredentials] = None,
+    connect_timeout: Optional[int] = None,
+    read_timeout: Optional[int] = None,
+    _telemetry_source: Optional[Module] = None,
+):
+    """Create a DMS client with automatic credential resolution.
+
+    Args:
+        instance: Logical instance name for secret resolution. Defaults to ``"default"``.
+        dms_cred: Explicit credentials. If provided, skips secret resolution.
+        connect_timeout: TCP connection timeout in seconds. Defaults to 10.
+        read_timeout: Response read timeout in seconds. Defaults to 30.
+        _telemetry_source: Internal telemetry source identifier. Not intended for external use.
+
+    Returns:
+        DMSClient: Configured client ready to use.
+
+    Raises:
+        DMSError: If client creation fails due to configuration or initialization issues.
+    """
+    try:
+        credentials = dms_cred or load_sdm_config_from_env_or_mount(instance)
+        client = DMSClient(
+            credentials,
+            connect_timeout=connect_timeout,
+            read_timeout=read_timeout,
+        )
+        client._telemetry_source = _telemetry_source
+        return client
+    except Exception as e:
+        raise DMSError(f"Failed to create DMS client: {e}") from e
+
+
+__all__ = [
+    "create_client",
+    "Ace",
+    "Acl",
+    "ChildrenOptions",
+    "ChildrenPage",
+    "CmisObject",
+    "DMSClient",
+    "DMSCredentials",
+    "DMSError",
+    "Document",
+    "Folder",
+    "QueryOptions",
+    "QueryResultPage",
+    "UserClaim",
+]

src/sap_cloud_sdk/dms/_auth.py

@@ -0,0 +1,109 @@
+import logging
+import time
+import requests
+from collections import OrderedDict
+from requests.exceptions import RequestException
+from typing import Optional, TypedDict
+from sap_cloud_sdk.dms.exceptions import (
+    DMSError,
+    DMSConnectionError,
+    DMSPermissionDeniedException,
+)
+from sap_cloud_sdk.dms.model import DMSCredentials
+
+logger = logging.getLogger(__name__)
+
+
+class _TokenResponse(TypedDict):
+    access_token: str
+    expires_in: int
+
+
+class _CachedToken:
+    def __init__(self, token: str, expires_at: float) -> None:
+        self.token = token
+        self.expires_at = expires_at
+
+    def is_valid(self) -> bool:
+        return time.monotonic() < self.expires_at - 30
+
+
+_MAX_CACHE_SIZE = 10
+
+
+class Auth:
+    """Fetches and caches OAuth2 access tokens for DMS service requests."""
+
+    def __init__(self, credentials: DMSCredentials) -> None:
+        self._credentials = credentials
+        self._cache: OrderedDict[str, _CachedToken] = OrderedDict()
+
+    def get_token(self, tenant_subdomain: Optional[str] = None) -> str:
+        cache_key = tenant_subdomain or "technical"
+
+        cached = self._cache.get(cache_key)
+        if cached and cached.is_valid():
+            self._cache.move_to_end(cache_key)  # Mark as recently used by moving to end
+            logger.debug("Using cached token for key '%s'", cache_key)
+            return cached.token
+
+        logger.debug("Fetching new token for key '%s'", cache_key)
+        token_url = self._resolve_token_url(tenant_subdomain)
+        token = self._fetch_token(token_url)
+
+        if len(self._cache) >= _MAX_CACHE_SIZE:
+            evicted, _ = self._cache.popitem(last=False)
+            logger.debug("Cache full — evicted token for key '%s'", evicted)
+
+        self._cache[cache_key] = _CachedToken(
+            token=token["access_token"],
+            expires_at=time.monotonic() + token.get("expires_in", 3600),
+        )
+        logger.debug("Token cached for key '%s'", cache_key)
+        return self._cache[cache_key].token
+
+    def _resolve_token_url(self, tenant_subdomain: Optional[str]) -> str:
+        if not tenant_subdomain:
+            return self._credentials.token_url
+        logger.debug("Resolving token URL for tenant '%s'", tenant_subdomain)
+        return self._credentials.token_url.replace(
+            self._credentials.identityzone,
+            tenant_subdomain,
+        )
+
+    def _fetch_token(self, token_url: str) -> _TokenResponse:
+        try:
+            response = requests.post(
+                f"{token_url}/oauth/token",
+                data={
+                    "grant_type": "client_credentials",
+                    "client_id": self._credentials.client_id,
+                    "client_secret": self._credentials.client_secret,
+                },
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                timeout=10,
+            )
+            response.raise_for_status()
+        except requests.exceptions.ConnectionError as e:
+            logger.error("Failed to connect to token endpoint")
+            raise DMSConnectionError(
+                "Failed to connect to the authentication server"
+            ) from e
+        except requests.exceptions.HTTPError as e:
+            status = e.response.status_code if e.response is not None else None
+            logger.error("Token request failed with status %s", status)
+            if status in (401, 403):
+                raise DMSPermissionDeniedException(
+                    "Authentication failed — invalid client credentials", status
+                ) from e
+            raise DMSError("Failed to obtain access token", status) from e
+        except RequestException as e:
+            logger.error("Unexpected error during token fetch")
+            raise DMSConnectionError("Unexpected error during authentication") from e
+
+        payload: _TokenResponse = response.json()
+        if not payload.get("access_token"):
+            raise DMSError("Token response missing access_token")
+
+        logger.debug("Token fetched successfully")
+        return payload