feat: update http destination using core

Author: NicoleMGomes

src/sap_cloud_sdk/core/http_client/user-guide.md

@@ -0,0 +1,147 @@
+# HTTP Client User Guide
+
+This module provides a general-purpose HTTP client for calling target systems described by BTP Destinations. It handles auth-header injection, typed exceptions, and telemetry automatically.
+
+```python
+from sap_cloud_sdk.core.http_client import (
+    HttpClient,
+    http_client_for_destination,
+    HttpClientError,
+    HttpConnectionError,
+    HttpNotFoundError,
+    HttpResponseError,
+    HttpUnauthorizedError,
+)
+```
+
+## Destination integration
+
+`http_client_for_destination` builds an `HttpClient` from a resolved BTP `Destination`. The destination's auth tokens, ERP headers, and `URL.headers.*` properties are pre-baked into the underlying `requests.Session`, so no manual header management is needed.
+
+```python
+from sap_cloud_sdk.destination import create_client
+from sap_cloud_sdk.core.http_client import http_client_for_destination
+
+dest_client = create_client()
+dest = dest_client.get_destination("MY_API")
+
+http = http_client_for_destination(dest)
+response = http.get("/api/v1/resources")
+data = response.json()
+```
+
+> **Note:** Use a destination fetched via `get_destination()` (v2 API), which populates `auth_tokens`. Destinations from the deprecated v1 methods do not carry pre-fetched tokens.
+
+When the destination URL points to a host root rather than the service root, pass `sub_path`:
+
+```python
+http = http_client_for_destination(dest, sub_path="api/v1")
+response = http.get("/resources")  # calls https://host/api/v1/resources
+```
+
+## Direct construction
+
+Inject any `requests.Session` directly when not using BTP Destinations:
+
+```python
+import requests
+from sap_cloud_sdk.core.http_client import HttpClient
+
+session = requests.Session()
+session.headers["Authorization"] = "Bearer <token>"
+
+http = HttpClient(base_url="https://api.example.com", session=session)
+```
+
+## HTTP methods
+
+All convenience methods raise typed exceptions on non-2xx responses and record telemetry automatically.
+
+```python
+# GET — with optional query parameters
+response = http.get("/items", params={"$top": "10", "status": "active"})
+
+# POST — JSON body
+response = http.post("/items", json={"name": "new item", "type": "A"})
+
+# PUT — full replacement
+response = http.put("/items/1", json={"name": "updated item"})
+
+# PATCH — partial update
+response = http.patch("/items/1", json={"status": "inactive"})
+
+# DELETE
+response = http.delete("/items/1")
+
+# Low-level request — does NOT raise on non-2xx; caller inspects the response
+response = http.request("GET", "/items")
+if not response.ok:
+    ...
+```
+
+### Extra headers per request
+
+Pass `headers=` to add or override headers for a single call:
+
+```python
+response = http.get("/items", headers={"X-Correlation-ID": "abc123"})
+```
+
+Per-request headers are merged on top of the session defaults.
+
+### Raw body
+
+Use `data=` for non-JSON payloads:
+
+```python
+response = http.post("/upload", data=b"raw bytes", headers={"Content-Type": "application/octet-stream"})
+```
+
+## What headers are pre-baked
+
+When `http_client_for_destination` builds the client it calls `dest.get_headers()`, which injects the following into the session:
+
+1. **ERP headers** — `sap-client` and `sap-language` from destination properties (if present)
+2. **`URL.headers.*` properties** — any destination property prefixed with `URL.headers.` becomes a header (e.g. `URL.headers.apiKey = secret` → `apiKey: secret`)
+3. **Auth tokens** — pre-fetched by BTP and returned in `dest.auth_tokens`; each token's `http_header` dict is injected directly (e.g. `Authorization: Bearer eyJ...`)
+
+Auth tokens take precedence over `URL.headers.*` when both set the same key.
+
+## Error handling
+
+```python
+from sap_cloud_sdk.core.http_client import (
+    http_client_for_destination,
+    HttpNotFoundError,
+    HttpUnauthorizedError,
+    HttpResponseError,
+    HttpConnectionError,
+)
+
+http = http_client_for_destination(dest)
+
+try:
+    response = http.get("/items/123")
+except HttpNotFoundError:
+    print("item not found")
+except HttpUnauthorizedError as e:
+    print(f"auth failure (HTTP {e.status_code}): check destination configuration")
+except HttpResponseError as e:
+    print(f"service error (HTTP {e.status_code})")
+except HttpConnectionError:
+    print("network unreachable — no response received")
+```
+
+Exception hierarchy:
+
+```
+HttpClientError
+├── HttpResponseError       # non-2xx HTTP response (carries .status_code and .response)
+│   ├── HttpNotFoundError   # 404
+│   └── HttpUnauthorizedError  # 401 / 403
+└── HttpConnectionError     # network failure — no HTTP response received
+```
+
+`HttpResponseError` exposes:
+- `.status_code: int` — the HTTP status code
+- `.response` — the raw `requests.Response` object

src/sap_cloud_sdk/core/odata/_factory.py

@@ -21,7 +21,7 @@ def odata_transport_from_destination(
     """Build an :class:`ODataHttpTransport` from a resolved BTP Destination.
 
     The destination's auth tokens and ERP headers are pre-baked into the
-    underlying ``requests.Session`` exactly as ``DestinationHttpClient`` does,
+    underlying ``requests.Session`` exactly as ``http_client_for_destination`` does,
     so the transport inherits whatever authentication the destination carries
     (Bearer, Basic, mTLS, …).
 

src/sap_cloud_sdk/destination/__init__.py

@@ -48,7 +48,7 @@
 )
 from sap_cloud_sdk.destination.config import load_from_env_or_mount, DestinationConfig
 from sap_cloud_sdk.destination._http import TokenProvider, DestinationHttp
-from sap_cloud_sdk.destination._destination_http_client import DestinationHttpClient
+from sap_cloud_sdk.core.http_client import HttpClient, http_client_for_destination
 from sap_cloud_sdk.destination.client import DestinationClient
 from sap_cloud_sdk.destination.fragment_client import FragmentClient
 from sap_cloud_sdk.destination.certificate_client import CertificateClient
@@ -236,7 +236,8 @@ def create_certificate_client(
     "LocalDevDestinationClient",
     "LocalDevFragmentClient",
     "LocalDevCertificateClient",
-    "DestinationHttpClient",
+    "HttpClient",
+    "http_client_for_destination",
     # Exceptions
     "DestinationError",
     "ClientCreationError",

src/sap_cloud_sdk/destination/_destination_http_client.py

@@ -8,7 +8,6 @@
 from __future__ import annotations
 
 from typing import Any, Dict, Optional
-from enum import Enum
 
 import requests
 from requests import Response
@@ -24,16 +23,6 @@
 API_V2 = "v2"
 
 
-class HttpMethod(Enum):
-    """HTTP method enumeration for request verb selection."""
-
-    GET = "GET"
-    POST = "POST"
-    PUT = "PUT"
-    PATCH = "PATCH"
-    DELETE = "DELETE"
-
-
 class TokenProvider:
     """Provides OAuth2 access tokens with in-memory caching and proactive refresh."""
 
@@ -117,7 +106,7 @@ def _auth_headers(self, tenant_subdomain: Optional[str] = None) -> Dict[str, str
 
     def _request(
         self,
-        method: HttpMethod | str,
+        method: str,
         path: str,
         *,
         params: Optional[Dict[str, Any]] = None,
@@ -131,14 +120,9 @@ def _request(
         if extra_headers:
             headers.update(extra_headers)
 
-        # Normalize method to string
-        method_str = (
-            method.value if isinstance(method, HttpMethod) else str(method).upper()
-        )
-
         try:
             resp = self._session.request(
-                method=method_str,
+                method=method.upper(),
                 url=url,
                 headers=headers,
                 params=params,
@@ -157,7 +141,7 @@ def _request(
             text = "<failed to read response body>"
 
         raise HttpError(
-            f"HTTP {resp.status_code} for {method_str} {url}",
+            f"HTTP {resp.status_code} for {method.upper()} {url}",
             status_code=resp.status_code,
             response_text=text,
         )
@@ -187,7 +171,7 @@ def get(
             HttpError: If the request fails or returns a non-2xx status.
         """
         return self._request(
-            HttpMethod.GET,
+            "GET",
             path,
             params=params,
             extra_headers=headers,
@@ -217,7 +201,7 @@ def post(
             HttpError: If the request fails or returns a non-2xx status.
         """
         return self._request(
-            HttpMethod.POST,
+            "POST",
             path,
             json=body,
             extra_headers=headers,
@@ -247,7 +231,7 @@ def put(
             HttpError: If the request fails or returns a non-2xx status.
         """
         return self._request(
-            HttpMethod.PUT,
+            "PUT",
             path,
             json=body,
             extra_headers=headers,
@@ -277,7 +261,7 @@ def patch(
             HttpError: If the request fails or returns a non-2xx status.
         """
         return self._request(
-            HttpMethod.PATCH,
+            "PATCH",
             path,
             json=body,
             extra_headers=headers,
@@ -305,7 +289,7 @@ def delete(
             HttpError: If the request fails or returns a non-2xx status.
         """
         return self._request(
-            HttpMethod.DELETE,
+            "DELETE",
             path,
             extra_headers=headers,
             tenant_subdomain=tenant_subdomain,