feat: add consumption destination and fragment level

Author: NicoleMGomes

.claude/commands/release-prep.md

@@ -0,0 +1,65 @@
+Prepare a release for the changes on the current branch. Do the following steps in order:
+
+## Step 1 — Understand the changes
+
+Run `git diff main...HEAD` and `git log main...HEAD --oneline` to understand what was changed on this branch. Read all modified source files to understand the nature of the changes (new feature, bug fix, breaking change, docs, etc.).
+
+## Step 2 — Determine the new version
+
+Read `pyproject.toml` to get the current version. Apply SemVer rules based on the changes:
+- PATCH bump: bug fixes, docs, refactors, non-breaking improvements
+- MINOR bump: new non-breaking features or new public API surface
+- MAJOR bump: breaking changes (changes to existing public API signatures or behavior)
+
+Compute the new version string (no leading `v`).
+
+## Step 3 — Bump version in pyproject.toml
+
+Edit `pyproject.toml` and update `version = "..."` to the new version.
+
+## Step 4 — Create PULL_REQUEST.md
+
+Create `PULL_REQUEST.md` at the repo root following the structure of `.github/pull_request_template.md`. Fill it in based on what you learned from the diff:
+
+- **Description**: clear summary of what changed and why
+- **Related Issue**: leave as `Closes #` with a note to fill in the issue number
+- **Type of Change**: check the relevant boxes (use `[x]`)
+- **How to Test**: concrete steps to verify the change works
+- **Checklist**: check all boxes that apply given the changes made
+- **Breaking Changes**: fill in if applicable, otherwise remove the section
+- **Additional Notes**: any relevant context for reviewers
+
+> **Disclaimer:** Do not include SAP-internal or customer-specific information in this PR (e.g. internal system URLs, customer names, tenant IDs, or confidential configurations). This is a public repository.
+
+## Step 5 — Create RELEASE.md
+
+Create `RELEASE.md` at the repo root using this exact template structure:
+
+```
+## [vX.Y.Z] - YYYY-MM-DD
+
+### What's New
+- ...
+
+### Improvements
+- ...
+
+### Bug Fixes
+- ...
+
+### Breaking Changes
+> ⚠️ **Important**: This section is critical for users upgrading from previous versions
+- **[Breaking Change]**: ...
+
+### Contributors
+...
+```
+
+Fill in the version and today's date. Remove sections that don't apply. Infer the content from the diff — be specific about what changed (class names, method names, parameter names) so that users upgrading know exactly what to update.
+
+## Step 6 — Summarize
+
+Tell the user:
+- The old and new version
+- Which files were created/updated
+- Any sections in PULL_REQUEST.md or RELEASE.md that still need manual input (e.g. issue number, contributors)

.gitignore

@@ -35,3 +35,7 @@ test-results.*
 
 # Local Mode
 mocks/
+
+# Generated files
+PULL_REQUEST.md
+RELEASE.md

pyproject.toml

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

src/sap_cloud_sdk/destination/__init__.py

@@ -29,6 +29,7 @@
 from sap_cloud_sdk.destination._models import (
     Destination,
     AuthToken,
+    ConsumptionLevel,
     ConsumptionOptions,
     Fragment,
     Certificate,
@@ -208,6 +209,7 @@ def create_certificate_client(
     # Public types
     "Destination",
     "AuthToken",
+    "ConsumptionLevel",
     "ConsumptionOptions",
     "Fragment",
     "Certificate",

src/sap_cloud_sdk/destination/_models.py

@@ -84,6 +84,25 @@ class AccessStrategy(Enum):
     PROVIDER_FIRST = "PROVIDER_FIRST"
 
 
+class ConsumptionLevel(Enum):
+    """Level hint for the v2 consumption API (get_destination).
+
+    Appended as @level to the destination name or fragment name in the API request,
+    allowing the caller to hint which scope to search.
+
+    Attributes:
+        PROVIDER_SUBACCOUNT: Provider subaccount scope
+        PROVIDER_INSTANCE: Provider service instance scope
+        SUBACCOUNT: Subscriber subaccount scope
+        INSTANCE: Subscriber service instance scope
+    """
+
+    PROVIDER_SUBACCOUNT = "provider_subaccount"
+    PROVIDER_INSTANCE = "provider_instance"
+    SUBACCOUNT = "subaccount"
+    INSTANCE = "instance"
+
+
 class DestinationType(Enum):
     """Destination type (subset of v1)."""
 
@@ -412,6 +431,9 @@ class ConsumptionOptions:
         fragment_name: Name of the destination fragment used to override/extend destination
             properties (X-fragment-name). In case of overlapping properties, fragment values
             take priority.
+        fragment_level: Level hint for the fragment lookup. When set, appended to the fragment
+            name as @level (e.g., "my-fragment@provider_subaccount"). Only effective when
+            fragment_name is also provided.
         fragment_optional: When True, if the fragment specified by fragment_name does not
             exist the destination is returned without it. When False (default), a missing
             fragment causes an error (X-fragment-optional).
@@ -488,6 +510,7 @@ class ConsumptionOptions:
     """
 
     fragment_name: Optional[str] = None
+    fragment_level: Optional[ConsumptionLevel] = None
     fragment_optional: Optional[bool] = None
     tenant: Optional[str] = None
     user_token: Optional[str] = None

src/sap_cloud_sdk/destination/client.py

@@ -8,6 +8,7 @@
 from sap_cloud_sdk.destination._http import DestinationHttp, API_V1, API_V2
 from sap_cloud_sdk.destination._models import (
     AccessStrategy,
+    ConsumptionLevel,
     ConsumptionOptions,
     Destination,
     Label,
@@ -32,9 +33,6 @@
 _SUBACCOUNT_COLLECTION = "subaccountDestinations"
 _INSTANCE_COLLECTION = "instanceDestinations"
 
-_SUBACCOUNT_LEVEL = "subaccount"
-_INSTANCE_LEVEL = "instance"
-
 
 class DestinationClient:
     """Client for SAP Destination Service operations.
@@ -279,7 +277,7 @@ def get_subaccount_destination(
     def get_destination(
         self,
         name: str,
-        level: Optional[Level] = None,
+        level: Optional[ConsumptionLevel] = None,
         options: Optional[ConsumptionOptions] = None,
         proxy_enabled: Optional[bool] = None,
         tenant: Optional[str] = None,
@@ -296,8 +294,9 @@ def get_destination(
 
         Args:
             name: Destination name.
-            level: Optional level hint (subaccount or instance) to optimize lookup. If not
-                provided, the API will search on instance level.
+            level: Optional level hint to narrow the lookup scope. When provided, appended to
+                the destination name as @level (e.g., "my-dest@provider_subaccount"). Supported
+                values: PROVIDER_SUBACCOUNT, PROVIDER_INSTANCE, SUBACCOUNT, INSTANCE.
             options: Optional ConsumptionOptions controlling request headers sent to the
                 Destination Service. See ConsumptionOptions for the full list of supported
                 headers (fragment merging, token exchange, SAML, OAuth2 flows, chains, etc.).
@@ -324,7 +323,7 @@ def get_destination(
             dest = client.get_destination("my-api")
 
             # With level hint
-            dest = client.get_destination("my-api", level=Level.SERVICE_INSTANCE)
+            dest = client.get_destination("my-api", level=ConsumptionLevel.PROVIDER_SUBACCOUNT)
 
             # Fragment merging
             dest = client.get_destination("my-api", options=ConsumptionOptions(fragment_name="prod"))
@@ -359,7 +358,10 @@ def get_destination(
 
             if options:
                 if options.fragment_name:
-                    headers["X-fragment-name"] = options.fragment_name
+                    frag = options.fragment_name
+                    if options.fragment_level:
+                        frag = f"{frag}@{options.fragment_level.value}"
+                    headers["X-fragment-name"] = frag
                 if options.fragment_optional is not None:
                     headers["X-fragment-optional"] = str(
                         options.fragment_optional
@@ -393,11 +395,11 @@ def get_destination(
                         headers[f"X-chain-var-{var_name}"] = var_value
 
             # Build path with optional level hint
-            if level:
-                level_str = self._map_level_to_api(level)
-                path = f"{API_V2}/destinations/{name}@{level_str}"
-            else:
-                path = f"{API_V2}/destinations/{name}"
+            path = (
+                f"{API_V2}/destinations/{name}@{level.value}"
+                if level
+                else f"{API_V2}/destinations/{name}"
+            )
 
             resp = self._http.get(path, headers=headers, tenant_subdomain=tenant)
             data = resp.json()
@@ -821,8 +823,3 @@ def _sub_path_for_level(level: Optional[Level] = Level.SUB_ACCOUNT) -> str:
             if level == Level.SERVICE_INSTANCE
             else _SUBACCOUNT_COLLECTION
         )
-
-    @staticmethod
-    def _map_level_to_api(level: Level) -> str:
-        """Return the v2 API level string for the given level."""
-        return _INSTANCE_LEVEL if level == Level.SERVICE_INSTANCE else _SUBACCOUNT_LEVEL

src/sap_cloud_sdk/destination/user-guide.md

@@ -14,7 +14,9 @@ from sap_cloud_sdk.destination import (
     create_fragment_client,
     create_certificate_client,
     Level,
-    AccessStrategy
+    AccessStrategy,
+    ConsumptionLevel,
+    ConsumptionOptions,
 )
 
 # Auto-detection based on environment; in cloud mode it will load credentials
@@ -100,10 +102,16 @@ client.patch_destination_labels("my-dest", PatchLabels(action="DELETE", labels=l
 
 ## Concepts
 
-- Level:
+- Level (v1 admin API — write operations, label operations):
   - SERVICE_INSTANCE: Operates on instance destinations
   - SUB_ACCOUNT: Operates on subaccount destinations
 
+- ConsumptionLevel (v2 consumption API — `get_destination` only):
+  - PROVIDER_SUBACCOUNT: Provider subaccount scope
+  - PROVIDER_INSTANCE: Provider service instance scope
+  - SUBACCOUNT: Subscriber subaccount scope
+  - INSTANCE: Subscriber service instance scope
+
 - AccessStrategy (applies to subaccount reads):
   - SUBSCRIBER_ONLY: Only subscriber (tenant required)
   - PROVIDER_ONLY: Only provider (no tenant)
@@ -133,7 +141,7 @@ class DestinationClient:
     def patch_destination_labels(self, name: str, patch: PatchLabels, level: Optional[Level] = Level.SUB_ACCOUNT, tenant: Optional[str] = None) -> None: ...
 
     # V2 Runtime API - Destination consumption with automatic token retrieval
-    def get_destination(self, name: str, level: Optional[Level] = None, options: Optional[ConsumptionOptions] = None, proxy_enabled: Optional[bool] = None, tenant: Optional[str] = None) -> Optional[Destination | TransparentProxyDestination]: ...
+    def get_destination(self, name: str, level: Optional[ConsumptionLevel] = None, options: Optional[ConsumptionOptions] = None, proxy_enabled: Optional[bool] = None, tenant: Optional[str] = None) -> Optional[Destination | TransparentProxyDestination]: ...
 ```
 
 ### Fragment Client
@@ -178,6 +186,7 @@ class CertificateClient:
   - `auth_tokens` and `certificates` are populated by the v2 consumption API
 - `ConsumptionOptions` - Options for v2 destination consumption, controls HTTP headers sent to the Destination Service:
   - `fragment_name?: str` - Fragment to merge into the destination (`X-fragment-name`)
+  - `fragment_level?: ConsumptionLevel` - Level hint for the fragment lookup; appended to `fragment_name` as `@level` (e.g., `"my-frag@provider_subaccount"`). Only effective when `fragment_name` is also provided.
   - `fragment_optional?: bool` - If `True`, a missing fragment does not cause an error (`X-fragment-optional`)
   - `tenant?: str` - Tenant subdomain for token retrieval (`X-tenant`)
   - `user_token?: str` - User JWT for OAuth2UserTokenExchange / OAuth2JWTBearer / OAuth2SAMLBearerAssertion (`X-user-token`)
@@ -323,16 +332,25 @@ dest = client.get_destination("my-api", options=options, proxy_enabled=False)
 
 # Example 8: V2 API with level parameter for optimized lookup
 client = create_client(instance="default")
-# Search only at instance level
-dest = client.get_destination("my-api", level=Level.SERVICE_INSTANCE)
-# Search only at subaccount level
-dest = client.get_destination("my-api", level=Level.SUB_ACCOUNT)
-# No level specified - searches at instance level as default
+# Search only at provider subaccount level
+dest = client.get_destination("my-api", level=ConsumptionLevel.PROVIDER_SUBACCOUNT)
+# Search only at subscriber subaccount level
+dest = client.get_destination("my-api", level=ConsumptionLevel.SUBACCOUNT)
+# Search only at service instance level
+dest = client.get_destination("my-api", level=ConsumptionLevel.INSTANCE)
+# No level specified - API resolves automatically
 dest = client.get_destination("my-api")
 
 # Example 9: Combine level with options
 options = ConsumptionOptions(fragment_name="production", tenant="tenant-1")
-dest = client.get_destination("my-api", level=Level.SUB_ACCOUNT, options=options)
+dest = client.get_destination("my-api", level=ConsumptionLevel.SUBACCOUNT, options=options)
+
+# Example 9b: Fragment with level hint
+options = ConsumptionOptions(
+    fragment_name="my-fragment",
+    fragment_level=ConsumptionLevel.PROVIDER_SUBACCOUNT,
+)
+dest = client.get_destination("my-api", options=options)
 
 # Example 10: Optional fragment (no error if fragment does not exist)
 options = ConsumptionOptions(fragment_name="maybe-exists", fragment_optional=True)