feat(cbc): add CBC (Central Business Configuration) client module - #333

…h params

Replace the cert tuple parameter with symmetric cert_path/key_path params.
Add CLOUD_SDK_CBC_CERT / CLOUD_SDK_CBC_KEY env vars so PEM values can be
supplied directly (e.g. from K8s secrets) without writing to disk first —
create_client() handles the temp-file lifecycle automatically.

…nts, version bump

- Bump version to 0.54.0 (required by CI for src/ changes)
- Fix ruff format violations in _models.py and client.py
- Fix ty errors: conftest fixture return type CBCClient, test_models assert-not-None before .version
- Update test_module (15→16) and test_operation (161→163) counts for CBC module/operations

- Soften "do not instantiate" to "prefer create_client"
- Replace contradictory direct-instantiation examples with create_client usage
- Reference BTP Destination Service and env vars as credential sources
- Add tmp/ to .gitignore

`_is_local_url` auto-disabled subdomain replacement for loopback URLs.
Replace with an explicit opt-out: `replace_subdomain` now defaults to
`True`; consumers set `CLOUD_SDK_CBC_REPLACE_SUBDOMAIN=false` when
pointing at a local mock server.

- Remove `_is_local_url` from `_http.py`
- Default `replace_subdomain` to `True` in `DefaultClient.__init__`
- Update `config.py` and `user-guide.md` to document the env-var escape hatch
- Remove `TestDefaultClientLocalMode` and related tests

Binds `TenantContext | Callable[[], TenantContext]` at construction time
instead of per-call. The callable form supports multi-tenant agents where
the tenant varies per request (e.g. read from a request-scoped context var).

- `DefaultClient.__init__` and `create_client` gain `tenant_context` param
- `get_consumption_versions` and `get_configuration` drop the param
- `CBCClient` Protocol updated to match
- Integration conftest bakes tenant into the client fixture
- Tests cover callable invocation count and missing-tenant error

Redesign the CBC client around a generic core and a platform adapter layered
strictly on top of it.

Core (client.py): base_url and app_tenant_id are per-request callables; the only
credential input is an ssl.SSLContext. create_client is a thin factory. Drops
TenantContext, config.py, _http.py, and all env/cert-file machinery.

Platform adapter (client_adapter.py): ships the SAP application-platform
provisioning defaults. The SDK owns two ContextVars (app_tenant_id_var,
tenant_subdomain_var) that the app populates; create_agent_client resolves
base_url from the tenant-mapping Destination Fragment (listing the subaccount
and matching on appTenantId, pre-PR-SAP#79 shape) and loads the provider mTLS
cert from the Destination Service. Every default is overridable via args or
CLOUD_SDK_CBC_* env vars.

CBC unit coverage 98% (adapter 100%).

get_configuration previously re-invoked the base_url callable on every
HTTP request (consumption versions + config objects + one per entity),
so a single call triggered 2+N tenant-mapping fragment lookups in the
platform adapter. Resolve base_url once at the top of the public call
and thread the resolved string into the internal methods
(_get_configuration_objects, _fetch_entity_data, _configurations_url),
mirroring how app_tenant_id is already threaded. One operation now does
one base_url resolution.

Also fix incoherent unit-test data: agent-config no longer holds
restaurant/contact/hours entities; replaced with tax-config /
tax-category / tax-rate to match the finance-domain examples used
elsewhere.

The adapter's _resolve_base_url and _load_ssl_context call Destination
Service APIs that can raise DestinationError, which leaked past the
documented CBCConfigError contract. Wrap both in try/except, re-raising
as CBCConfigError with a descriptive message and chained cause.

The adapter loaded the mTLS certificate once in create_agent_client and
baked it into the httpx.Client at construction, so a rotated or expired
certificate killed a long-lived client until the process restarted —
violating the "Credential Binding Rotation" guideline that every module
reading credentials must recover from rotation.

Make the core reload reactively. ssl_context becomes a
Callable[[], ssl.SSLContext] | None, resolved once at construction and
re-invoked only when a request fails the TLS handshake. On such a
failure the client rebuilds its httpx.Client from a fresh context under
a lock (guarding against a thundering herd) and retries the one request
once; a second failure, a non-TLS transport error, or a failing rebuild
(the cert loader raises CBCConfigError) propagates cleanly, leaving the
previous working client in place. TLS failures are detected by walking
the exception's __cause__/__context__ chain for ssl.SSLError, since httpx
surfaces an expired client cert as ReadError wrapping ssl.SSLError two
levels down. Mirrors objectstore's _execute_with_retry rotation pattern.

create_agent_client drops its ssl_context parameter and now owns cert
resolution end-to-end, passing a lambda: load_ssl_context(...) factory to
the core.

Expose the three platform resolvers as public composition helpers
(resolve_base_url, resolve_app_tenant_id, load_ssl_context) at the top
level, so a caller can keep most of the platform preset but override a
single axis via create_client instead of reimplementing the resolvers.

Also:
- resolve base_url + app_tenant_id once per get_configuration on the
  auto-version path (extract _get_consumption_versions taking resolved
  values), avoiding a double resolve that could also disagree if the
  request context changed between the two.
- rename _build_client/_rebuild_client/self._client to the _http_client
  forms, so names disambiguate the httpx client from the CBC client.
- build the client with verify=ctx if ctx is not None else True, making
  it explicit that TLS verification is never disabled.

The pre-commit ty hook checks tests/ (unlike an src-only ty run), which
surfaced 10 diagnostics in the CBC test suite.

test_client_adapter.py: create_agent_client() returns the CBCClient
Protocol, which has no private members, so accessing _ssl_factory /
_base_url / _resolve_app_tenant_id failed. Narrow to DefaultClient with
an isinstance assert before touching privates, and guard the optional
_ssl_factory before calling it.

test_client.py: orig_build = client._build_http_client is typed
() -> httpx.Client, so orig_build() was Client, not MagicMock, breaking
the .request wiring and the -> MagicMock return annotations. Align the
build helpers' return types with the method they replace (httpx.Client),
cast() the mock where .request is wired, and replace the ineffective
mypy # type: ignore[method-assign] with the repo's ty idiom
# ty: ignore[invalid-assignment].

Replace the three loose keyword args on create_agent_client
(destination_instance, cbc_cert_name, p12_password) with a single
CBCDestinationConfig settings object, addressing the PR review request
for a config object. The object lives in a new cbc/config.py, matching
the dedicated-config.py convention of the agw, adms, print, and
destination modules.

Per-field env overrides are unchanged: a value set on the config wins
over its CLOUD_SDK_CBC_* env var, which in turn falls back to the
platform default. Scoped to the adapter layer only — the core
create_client and its hardcoded timeout are untouched; a core config
object is deferred.

Also rename the private _ClientConfig (API-path holder) to _ApiPaths so
it no longer reads as a near-homonym of the new public config class.

EntityContent (the raw payload wrapper) → EntityData: names the thing it
actually holds.
EntityData (the entity container with entity_id + data) → ConfigEntity:
scoped to the config layer, mirrors get_config_object naming, and
removes ambiguity with the new EntityData.

Also rename the two accessor methods for consistency:
  ConfigObject.get_entity       → get_config_entity
  ConfigData.get_entity_data    → get_config_entity

Updated across _models.py, client.py, __init__.py, user-guide.md, and
test_models.py. No behaviour change.

REST API team confirmed:
- metadata.entityId is the correct field name (was entityName)
- content.item / content.items struct is correct (already was)
- ?appTenantId= query param is correct (already was)

Since metadata.entityId equals the entity_id already known from the URL
path, drop the metadata read entirely — entity_id is used directly.
Remove the now-redundant resolved_id fallback and the deleted
test_falls_back_to_path_entity_id_without_metadata test. Strip stale
metadata fields from remaining mock response bodies.

… to 0.59.0

Fix stale EntityData return annotation on TestConfigData._entity_data —
missed during the EntityData → ConfigEntity rename. Also bump version to
0.59.0 (upstream released 0.58.0).

Exposes _fetch_entity_data as a public client method get_entity_data(),
matching the Java SDK's getEntityData() for fetching one entity without
pulling all configuration objects. Also renames ConfigObject/ConfigData
.get_config_entity() → .get_entity_data() returning EntityData directly,
removing the ConfigEntity wrapper the caller had to unwrap every time.

- Add Args/Returns/Raises to all three CBCClient Protocol methods
  (get_consumption_versions, get_configuration, get_entity_data)
- Rename all test methods across test_client.py, test_models.py, and
  test_client_adapter.py to the documented test_<func>_<condition>_<result>
  pattern (pre-existing violations + 3 new from the prior commit)
- Strengthen ConfigData.get_entity_data test: fixture now gives each entity
  distinct data so a wrong-entity selection bug would fail the assertion
- Add BDD integration scenario for get_entity_data (CONTRIBUTING.md requires
  integration tests for new capabilities)

…AP#82

Fragment naming in the platform changed from CBC_TenantMapping_<cbcTenantId>
to CBC_TenantMapping_<tenantSubdomain> (sap-internal-sdk-python#82), enabling
a direct get_subaccount_fragment lookup by subdomain instead of listing all
fragments and filtering by appTenantId.

Update resolve_base_url to use the single direct lookup, and update all five
TestResolveBaseUrl unit tests to mock get_subaccount_fragment accordingly.