feat(adms): add SAP ADMS module with sync/async clients and BDD tests

.env_integration_tests.example

@@ -26,6 +26,14 @@ CLOUD_SDK_CFG_SDM_DEFAULT_UAA='{"url":"https://your-auth-url","clientid":"your-c
 CLOUD_SDK_CFG_HANA_AGENT_MEMORY_DEFAULT_APPLICATION_URL=https://your-agent-memory-api-url-here
 CLOUD_SDK_CFG_HANA_AGENT_MEMORY_DEFAULT_UAA='{"url":"https://your-auth-url","clientid":"your-client-id","clientsecret":"your-client-secret"}'
 
+# ADMS (Advanced Document Management Service) — integration tests against
+# a deployed ADM instance. Tests are skipped when any of these are missing.
+CLOUD_SDK_CFG_ADMS_DEFAULT_CLIENTID=your-adms-client-id-here
+CLOUD_SDK_CFG_ADMS_DEFAULT_CLIENTSECRET=your-adms-client-secret-here
+CLOUD_SDK_CFG_ADMS_DEFAULT_URL=https://your-tenant.accounts.ondemand.com
+CLOUD_SDK_CFG_ADMS_DEFAULT_URI=https://your-adm-host.cfapps.eu20.hana.ondemand.com
+CLOUD_SDK_CFG_ADMS_DEFAULT_RESOURCE=urn:sap:identity:application:provider:name:your-adm-app-name
+
 APPFND_CONHOS_LANDSCAPE=your-landscape-here
 TENANT_SUBDOMAIN=your-tenant-subdomain-here
 AGW_USER_TOKEN=your-user-jwt-here

.gitignore

@@ -38,4 +38,13 @@ mocks/
 
 # Generated files
 PULL_REQUEST.md
-RELEASE.md
+
+# macOS metadata
+.DS_Store
+
+# UCL provisioning artefacts (separate repo concern)
+.ucl-provision/
+src/sap_cloud_sdk/adms/ucl/
+RELEASE.md
+.env.adms
+scripts/adms_cli.py

docs/INTEGRATION_TESTS.md

@@ -96,6 +96,21 @@ CLOUD_SDK_CFG_DATA_ANONYMIZATION_DEFAULT_DESTINATION_NAME=your-client-certificat
 
 The destination must be configured with `ClientCertificateAuthentication` and reference a certificate bundle containing the client certificate and private key.
 
+### ADMS Integration Tests
+
+For ADMS (Advanced Document Management Service) integration tests, configure the following variables in `.env_integration_tests`:
+
+```bash
+# ADMS Configuration
+CLOUD_SDK_CFG_ADMS_DEFAULT_URL=https://your-tenant.accounts.ondemand.com
+CLOUD_SDK_CFG_ADMS_DEFAULT_URI=https://your-adm-instance.cfapps.eu20.hana.ondemand.com
+CLOUD_SDK_CFG_ADMS_DEFAULT_CLIENTID=your-ias-client-id
+CLOUD_SDK_CFG_ADMS_DEFAULT_CLIENTSECRET=your-ias-client-secret
+CLOUD_SDK_CFG_ADMS_DEFAULT_RESOURCE=urn:sap:identity:application:provider:name:your-app
+```
+
+`CLOUD_SDK_CFG_ADMS_DEFAULT_URI` points the tests at the target ADM service. The other `CLOUD_SDK_CFG_ADMS_DEFAULT_*` variables hold the IAS service-binding credentials used by the SDK to fetch Bearer tokens. Tests are skipped automatically when any of these are missing.
+
 ### Agent Gateway Integration Tests
 
 Agent Gateway integration tests use the LoB agent flow via the Destination Service. Configure the following variables in `.env_integration_tests`:
@@ -131,6 +146,7 @@ uv run pytest tests/core/integration/data_anonymization -v
 uv run pytest tests/objectstore/integration/ -v
 uv run pytest tests/destination/integration/ -v
 uv run pytest tests/agent_memory/integration/ -v
+uv run pytest tests/adms/integration/ -v
 uv run pytest tests/agentgateway/integration/ -v
 ```
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sap-cloud-sdk"
-version = "0.22.0"
+version = "0.23.0"
 description = "SAP Cloud SDK for Python"
 readme = "README.md"
 license = "Apache-2.0"

src/sap_cloud_sdk/adms/__init__.py

@@ -0,0 +1,131 @@
+"""SAP Cloud SDK for Python — ADMS (Advanced Document Management Service) module.
+
+Provides a typed, high-level Python client for the SAP ADM OData V4 service.
+
+ADM is a **BTP Shared SaaS Application** (IAS-based multi-tenant service).
+It must be provisioned as a BTP service instance before use.
+
+Quick start::
+
+    from sap_cloud_sdk.adms import (
+        create_client,
+        BaseType,
+        CreateDocumentInput,
+        CreateDocumentRelationInput,
+    )
+
+    # Reads binding from /etc/secrets/appfnd/adms/default/ or env vars
+    client = create_client("default")
+
+    # Link a document to a business object
+    relation = client.relations.create(
+        CreateDocumentRelationInput(
+            business_object_node_type_unique_id="PurchaseOrder",
+            host_business_object_node_id="PO-4500012345",
+            document=CreateDocumentInput(
+                document_name="Invoice.pdf",
+                document_base_type=BaseType.DOCUMENT,
+                document_type_id="INVOICE",
+            ),
+            is_active_entity=False,
+        )
+    )
+    # Upload bytes to presigned URL (outside SDK)
+    import requests
+    requests.put(relation.document.document_content_upload_urls[0], data=open("f.pdf","rb"))
+"""
+
+from __future__ import annotations
+
+from sap_cloud_sdk.adms.client import (
+    AdmsClient,
+    AsyncAdmsClient,
+    create_client,
+    create_async_client,
+)
+from sap_cloud_sdk.adms.config import AdmsConfig
+from sap_cloud_sdk.adms.exceptions import (
+    AuthError,
+    ClientCreationError,
+    ConfigError,
+    AdmsError,
+    AdmsOperationError,
+    DocumentNotFoundError,
+    HttpError,
+    ScanNotCleanError,
+)
+from sap_cloud_sdk.adms._models import (
+    AllowedDomain,
+    BaseType,
+    BusinessObjectNodeType,
+    CreateAllowedDomainInput,
+    CreateBusinessObjectNodeTypeInput,
+    CreateDocumentTypeBoTypeMapInput,
+    CreateDocumentInput,
+    CreateDocumentRelationInput,
+    CreateDocumentTypeInput,
+    DeleteUserDataJobParameters,
+    Document,
+    DocumentContentVersion,
+    DocumentRelation,
+    DocumentType,
+    DocumentTypeBusinessObjectTypeMap,
+    DocumentTypeText,
+    DraftActivateInput,
+    DraftInput,
+    JobInput,
+    JobOutput,
+    JobStatus,
+    JobType,
+    ScanStatus,
+    UpdateDocumentInput,
+    ZipDownloadJobParameters,
+)
+
+
+__all__ = [
+    # factories
+    "create_client",
+    "create_async_client",
+    # clients
+    "AdmsClient",
+    "AsyncAdmsClient",
+    # config
+    "AdmsConfig",
+    # exceptions
+    "AdmsError",
+    "AdmsOperationError",
+    "AuthError",
+    "ClientCreationError",
+    "ConfigError",
+    "DocumentNotFoundError",
+    "HttpError",
+    "ScanNotCleanError",
+    # models — core
+    "BaseType",
+    "CreateDocumentInput",
+    "CreateDocumentRelationInput",
+    "DeleteUserDataJobParameters",
+    "Document",
+    "DocumentContentVersion",
+    "DocumentRelation",
+    "DraftActivateInput",
+    "DraftInput",
+    "JobInput",
+    "JobOutput",
+    "JobStatus",
+    "JobType",
+    "ScanStatus",
+    "UpdateDocumentInput",
+    "ZipDownloadJobParameters",
+    # models — config
+    "AllowedDomain",
+    "BusinessObjectNodeType",
+    "CreateAllowedDomainInput",
+    "CreateBusinessObjectNodeTypeInput",
+    "CreateDocumentTypeBoTypeMapInput",
+    "CreateDocumentTypeInput",
+    "DocumentType",
+    "DocumentTypeBusinessObjectTypeMap",
+    "DocumentTypeText",
+]

src/sap_cloud_sdk/adms/_auth.py

@@ -0,0 +1,75 @@
+"""IAS token management for the ADMS module — thin ADMS adapter over core auth.
+
+All token-fetching logic lives in :mod:`sap_cloud_sdk.core.auth._ias_fetcher`.
+This module provides ADMS-specific wrappers that:
+
+* Accept :class:`~sap_cloud_sdk.adms.config.AdmsConfig` instead of raw URL/credentials.
+* Re-raise :class:`~sap_cloud_sdk.core.auth.AuthError` as ADMS's own
+  :class:`~sap_cloud_sdk.adms.exceptions.AuthError` (a subclass of
+  ``AdmsError``) so that callers using ``except AdmsError`` still catch auth failures.
+
+The public symbols exported here match what the existing ADMS unit-tests import,
+so no test changes are required.
+"""
+
+from __future__ import annotations
+
+import requests
+
+# Core implementations — real logic lives here
+from sap_cloud_sdk.core.auth import (
+    IasTokenFetcher as _CoreIasTokenFetcher,
+    AuthError as _CoreAuthError,
+    TokenCache,
+)
+from sap_cloud_sdk.adms.config import AdmsConfig
+from sap_cloud_sdk.adms.exceptions import AuthError
+
+__all__ = [
+    "IasTokenFetcher",
+]
+
+
+class IasTokenFetcher(_CoreIasTokenFetcher):
+    """ADMS-flavoured IAS token fetcher that accepts :class:`AdmsConfig`.
+
+    Inherits all caching / fetching logic from the core layer.  Converts
+    :class:`~sap_cloud_sdk.core.auth.AuthError` to
+    :class:`~sap_cloud_sdk.adms.exceptions.AuthError` (a ``AdmsError`` subclass)
+    so existing ``except AdmsError / AuthError`` handlers are unaffected.
+
+    Args:
+        config: :class:`~sap_cloud_sdk.adms.config.AdmsConfig` with IAS credentials.
+        session: Optional ``requests.Session`` to reuse (useful for testing).
+        cache: Pluggable :class:`~sap_cloud_sdk.core.auth.TokenCache`.
+            Defaults to :class:`~sap_cloud_sdk.core.auth.InMemoryTokenCache`.
+            Pass a :class:`~sap_cloud_sdk.core.auth.RedisTokenCache` for
+            multi-instance deployments.
+    """
+
+    def __init__(
+        self,
+        config: AdmsConfig,
+        session: requests.Session | None = None,
+        cache: TokenCache | None = None,
+    ) -> None:
+        super().__init__(
+            ias_url=config.ias_url,
+            client_id=config.client_id,
+            client_secret=config.client_secret,
+            session=session,
+            cache=cache,
+            resource=config.resource,
+        )
+
+    def get_token(self) -> str:
+        try:
+            return super().get_token()
+        except _CoreAuthError as exc:
+            raise AuthError(str(exc)) from exc
+
+    def exchange_token(self, user_jwt: str) -> str:
+        try:
+            return super().exchange_token(user_jwt)
+        except _CoreAuthError as exc:
+            raise AuthError(str(exc)) from exc