salesforce-data-customcode 6.1.0.dev1__py3-none-any.whl → 6.1.0.dev2__py3-none-any.whl

datacustomcode/deploy.py

@@ -14,7 +14,6 @@
 # limitations under the License.
 from __future__ import annotations
 
-import copy
 from html import unescape
 import json
 import os
@@ -38,11 +37,13 @@ import requests
 
 from datacustomcode.cmd import cmd_output
 from datacustomcode.constants import REQUEST_TYPE_TO_FEATURE
+from datacustomcode.named_credential.direct.credentials import (
+    EXTERNAL_CALLOUT_CREDENTIAL,
+)
 from datacustomcode.scan import find_base_directory, get_package_type
 
 DATA_CUSTOM_CODE_PATH = "services/data/v63.0/ssot/data-custom-code"
 DATA_TRANSFORMS_PATH = "services/data/v63.0/ssot/data-transforms"
-DATA_CUSTOM_CODE_INVOKE_OPTIONS_PATH = "services/data/v67.0/ssot/data-custom-code"
 WAIT_FOR_DEPLOYMENT_TIMEOUT = 3000
 
 # Available compute types for Data Cloud deployments.
@@ -110,7 +111,6 @@ class CodeExtensionMetadata(BaseModel):
     computeType: str
     codeType: str
     functionInvokeOptions: Union[list[str], None] = None
-    invokeOptions: Union[list[str], None] = None
 
     def __init__(self, **data):
         name = data.get("name", "")
@@ -203,14 +203,7 @@ def create_deployment(
     access_token: AccessTokenResponse, metadata: CodeExtensionMetadata
 ) -> CreateDeploymentResponse:
     """Create a custom code deployment in the DataCloud."""
-    # invokeOptions only binds at v67.0; route there when it is set so the
-    # option isn't silently dropped. Everything else stays on v63.0.
-    code_custom_code_path = (
-        DATA_CUSTOM_CODE_INVOKE_OPTIONS_PATH
-        if metadata.invokeOptions
-        else DATA_CUSTOM_CODE_PATH
-    )
-    url = _join_strip_url(access_token.instance_url, code_custom_code_path)
+    url = _join_strip_url(access_token.instance_url, DATA_CUSTOM_CODE_PATH)
     body = dict[str, Any](
         {
             "label": metadata.name,
@@ -223,8 +216,6 @@ def create_deployment(
     )
     if metadata.functionInvokeOptions:
         body["functionInvokeOptions"] = metadata.functionInvokeOptions
-    if metadata.invokeOptions:
-        body["invokeOptions"] = metadata.invokeOptions
     logger.debug(f"Creating deployment {metadata.name}...")
     try:
         response = _make_api_call(
@@ -248,6 +239,8 @@ DEPENDENCIES_ARCHIVE_PATH = os.path.join(
 )
 PY_FILES_PATH = os.path.join("payload", "py-files")
 ZIP_FILE_NAME = "deployment.zip"
+# Local-only files that must never be packaged into the deployment zip.
+EXCLUDED_FILES = (".DS_Store", EXTERNAL_CALLOUT_CREDENTIAL)
 
 
 def prepare_dependency_archive(
@@ -400,30 +393,6 @@ class DataTransformConfig(BaseConfig):
     dataspace: str
     permissions: Permissions
     dataObjects: Optional[list[DataObject]] = None
-    streamingSource: Optional[StreamingSource] = None
-
-    @property
-    def is_streaming(self) -> bool:
-        return self.streamingSource is not None
-
-    @model_validator(mode="after")
-    def _validate_layers(self) -> "DataTransformConfig":
-        read_is_dlo = isinstance(self.permissions.read, DloPermission)
-        write_is_dlo = isinstance(self.permissions.write, DloPermission)
-        if self.is_streaming:
-            if not write_is_dlo:
-                raise ValueError(
-                    "A streaming transform must write to a DLO "
-                    "(permissions.write must be a 'dlo' entry)."
-                )
-        elif read_is_dlo != write_is_dlo:
-            raise ValueError(
-                "permissions.read and permissions.write must both reference "
-                "DLOs or both reference DMOs (got "
-                f"read={type(self.permissions.read).__name__}, "
-                f"write={type(self.permissions.write).__name__})"
-            )
-        return self
 
 
 class FunctionConfig(BaseConfig):
@@ -438,15 +407,23 @@ class DmoPermission(BaseModel):
     dmo: list[str]
 
 
-class StreamingSource(BaseModel):
-    type: str
-    name: str
-
-
 class Permissions(BaseModel):
     read: Union[DloPermission, DmoPermission]
     write: Union[DloPermission, DmoPermission]
 
+    @model_validator(mode="after")
+    def _no_mixed_layers(self) -> "Permissions":
+        read_is_dlo = isinstance(self.read, DloPermission)
+        write_is_dlo = isinstance(self.write, DloPermission)
+        if read_is_dlo != write_is_dlo:
+            raise ValueError(
+                "permissions.read and permissions.write must both reference "
+                "DLOs or both reference DMOs (got "
+                f"read={type(self.read).__name__}, "
+                f"write={type(self.write).__name__})"
+            )
+        return self
+
 
 def _permission_entries(perm: Union[DloPermission, DmoPermission]) -> list[str]:
     """Return the list of object names regardless of layer (DLO or DMO)."""
@@ -518,9 +495,7 @@ def create_data_transform(
 ) -> dict:
     """Create a data transform in the DataCloud."""
     script_name = metadata.name
-    # Deep copy: the template's nested nodes/sources/macros dicts would
-    # otherwise be shared across calls and accumulate entries between deploys.
-    request_hydrated = copy.deepcopy(DATA_TRANSFORM_REQUEST_TEMPLATE)
+    request_hydrated = DATA_TRANSFORM_REQUEST_TEMPLATE.copy()
 
     # Add nodes for each write entry (DLO or DMO)
     for i, name in enumerate(
@@ -563,7 +538,7 @@ def create_data_transform(
         "definition": definition,
         "label": f"{metadata.name}",
         "name": f"{metadata.name}",
-        "type": "STREAMING" if data_transform_config.is_streaming else "BATCH",
+        "type": "BATCH",
         "dataSpaceName": data_transform_config.dataspace,
     }
 
@@ -628,9 +603,9 @@ def zip(
 
     with zipfile.ZipFile(ZIP_FILE_NAME, "w", zipfile.ZIP_DEFLATED) as zipf:
         for root, dirs, files in os.walk(directory):
-            # Skip .DS_Store files when adding to zip
+            # Skip .DS_Store and local credentials.
             for file in files:
-                if file != ".DS_Store":
+                if file not in EXCLUDED_FILES:
                     abs_path = os.path.join(root, file)
                     arcname = os.path.relpath(abs_path, directory)
                     zipf.write(abs_path, arcname)
@@ -646,18 +621,9 @@ def deploy_full(
     callback=None,
 ) -> AccessTokenResponse:
     """Deploy a data transform in the DataCloud."""
-    from datacustomcode.constants import SCRIPT_USE_IN_FEATURE_STREAMING
-
     # prepare payload
     config = get_config(directory)
 
-    if (
-        isinstance(config, DataTransformConfig)
-        and config.is_streaming
-        and not metadata.invokeOptions
-    ):
-        metadata.invokeOptions = [SCRIPT_USE_IN_FEATURE_STREAMING]
-
     # create deployment and upload payload
     deployment = create_deployment(access_token, metadata)
     zip(directory, docker_network, metadata.codeType)

datacustomcode/function/runtime.py

@@ -23,6 +23,8 @@ from datacustomcode.file.path.default import DefaultFindFilePath
 from datacustomcode.function.base import BaseRuntime
 from datacustomcode.llm_gateway.base import LLMGateway
 from datacustomcode.llm_gateway_config import llm_gateway_config
+from datacustomcode.named_credential.base import NamedCredential
+from datacustomcode.named_credential_config import named_credential_config
 
 
 class Runtime(BaseRuntime):
@@ -69,6 +71,7 @@ class Runtime(BaseRuntime):
         self._llm_gateway: Optional[LLMGateway] = None
         self._file = DefaultFindFilePath()
         self._einstein_predictions: Optional[EinsteinPredictions] = None
+        self._named_credential: Optional[NamedCredential] = None
 
     @property
     def llm_gateway(self) -> LLMGateway:
@@ -98,3 +101,16 @@ class Runtime(BaseRuntime):
                 einstein_predictions_config.einstein_predictions_config.to_object()
             )
         return self._einstein_predictions
+
+    @property
+    def named_credential(self) -> NamedCredential:
+        if self._named_credential is None:
+            if named_credential_config.named_credential_config is None:
+                raise RuntimeError(
+                    "Named Credential is not configured. Add "
+                    "'named_credential_config' section to config.yaml"
+                )
+            self._named_credential = (
+                named_credential_config.named_credential_config.to_object()
+            )
+        return self._named_credential

datacustomcode/io/reader/base.py

@@ -41,45 +41,3 @@ class BaseDataCloudReader(BaseDataAccessLayer):
         name: str,
         schema: Union[AtomicType, StructType, str, None] = None,
     ) -> PySparkDataFrame: ...
-
-    def read_dlo_deltas(self) -> PySparkDataFrame:
-        """Read the streaming change feed (deltas) for a Data Lake Object.
-
-        This is the streaming counterpart to :meth:`read_dlo`. It returns a
-        streaming DataFrame over the change feed the Data Cloud runtime
-        publishes for a streaming (``DELTA_SYNC``) transform. Concrete
-        streaming behavior is provided by the deployed Data Cloud runtime; the
-        base implementation raises :class:`NotImplementedError` so local
-        readers that do not support streaming fail clearly.
-
-        Returns:
-            A streaming PySpark DataFrame over the DLO change feed.
-
-        Raises:
-            NotImplementedError: If the active reader does not support streaming
-                deltas (e.g. the local development readers).
-        """
-        raise NotImplementedError(
-            "read_dlo_deltas is only supported when running in the Data Cloud "
-            "streaming runtime; the local reader does not support streaming "
-            "deltas."
-        )
-
-    def read_dmo_deltas(self) -> PySparkDataFrame:
-        """Read the streaming change feed (deltas) for a Data Model Object.
-
-        Streaming counterpart to :meth:`read_dmo`. See :meth:`read_dlo_deltas`
-        for behavior and the local-development caveat.
-
-        Returns:
-            A streaming PySpark DataFrame over the DMO change feed.
-
-        Raises:
-            NotImplementedError: If the active reader does not support streaming
-                deltas (e.g. the local development readers).
-        """
-        raise NotImplementedError(
-            "read_dmo_deltas is only supported when running in the Data Cloud "
-            "streaming runtime; the local reader does not support streaming "
-            "deltas."
-        )

datacustomcode/io/writer/base.py

@@ -22,7 +22,6 @@ from datacustomcode.io.base import BaseDataAccessLayer
 
 if TYPE_CHECKING:
     from pyspark.sql import DataFrame as PySparkDataFrame, SparkSession
-    from pyspark.sql.streaming import StreamingQuery
 
 
 class WriteMode(str, Enum):
@@ -58,35 +57,3 @@ class BaseDataCloudWriter(BaseDataAccessLayer):
     def write_to_dmo(
         self, name: str, dataframe: PySparkDataFrame, write_mode: WriteMode
     ) -> None: ...
-
-    def write_dlo_deltas(
-        self, name: str, dataframe: PySparkDataFrame
-    ) -> StreamingQuery:
-        """Write a streaming DataFrame of deltas to a Data Lake Object.
-
-        Streaming counterpart to :meth:`write_to_dlo`. Starts a streaming query
-        that writes each micro-batch to the target DLO via the Data Cloud
-        streaming sink and returns the resulting ``StreamingQuery`` handle. The
-        runtime owns the trigger and checkpoint location; callers pass only the
-        table name. Concrete streaming behavior is provided by the deployed
-        Data Cloud runtime; the base implementation raises
-        :class:`NotImplementedError`.
-
-        Args:
-            name: Target Data Lake Object name.
-            dataframe: Streaming PySpark DataFrame produced from a
-                ``read_dlo_deltas`` / ``read_dmo_deltas`` source.
-
-        Returns:
-            The started ``StreamingQuery``; the caller drives its lifecycle
-            (typically ``query.awaitTermination()``).
-
-        Raises:
-            NotImplementedError: If the active writer does not support streaming
-                deltas (e.g. the local development writers).
-        """
-        raise NotImplementedError(
-            "write_dlo_deltas is only supported when running in the Data Cloud "
-            "streaming runtime; the local writer does not support streaming "
-            "deltas."
-        )

datacustomcode/named_credential/__init__.py

@@ -0,0 +1,26 @@
+# Copyright (c) 2025, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from datacustomcode.named_credential.base import NamedCredential
+from datacustomcode.named_credential.default import DefaultNamedCredential
+from datacustomcode.named_credential.spark_base import SparkNamedCredential
+from datacustomcode.named_credential.spark_default import DefaultSparkNamedCredential
+
+__all__ = [
+    "DefaultNamedCredential",
+    "DefaultSparkNamedCredential",
+    "NamedCredential",
+    "SparkNamedCredential",
+]

datacustomcode/named_credential/base.py

@@ -0,0 +1,54 @@
+# Copyright (c) 2025, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Optional
+
+from datacustomcode.mixin import UserExtendableNamedConfigMixin
+
+if TYPE_CHECKING:
+    from datacustomcode.named_credential.types.http_request import HTTPRequest
+    from datacustomcode.named_credential.types.http_response import HTTPResponse
+
+
+class NamedCredential(ABC, UserExtendableNamedConfigMixin):
+    CONFIG_NAME: str
+
+    def __init__(self, **kwargs):
+        pass
+
+    @abstractmethod
+    def request(
+        self,
+        request: HTTPRequest,
+        body: Optional[str] = None,
+    ) -> HTTPResponse:
+        """Make an external callout through a Named Credential.
+
+        The endpoint and its authentication are resolved server-side from the
+        Named Credential referenced by ``request.url``; the function never sees
+        the external credential.
+
+        Args:
+            request: The callout request
+            body: Optional request body. Set the
+                ``Content-Type`` header to match the format; the SDK
+                does not assume or inject one.
+
+        Returns:
+            The external service's response.
+        """
+        ...

datacustomcode/named_credential/default.py

@@ -0,0 +1,93 @@
+# Copyright (c) 2025, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import (
+    Any,
+    Dict,
+    Optional,
+)
+
+from datacustomcode.named_credential.base import NamedCredential
+from datacustomcode.named_credential.types.http_request import HTTPRequest
+from datacustomcode.named_credential.types.http_response import HTTPResponse
+from datacustomcode.named_credential.types.http_response_builder import (
+    HTTPResponseBuilder,
+)
+
+
+class DefaultNamedCredential(NamedCredential):
+    """
+    Executes the callout directly via :class:`DirectCalloutTransport`, resolving
+    the URL from the Named Credential Connect API (falling back to
+    ``external_callout_config.json``) and injecting auth from the same file.
+    """
+
+    CONFIG_NAME = "DefaultNamedCredential"
+
+    def __init__(
+        self,
+        credentials_profile: str = "default",
+        sf_cli_org: Optional[str] = None,
+        credential_file: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._credentials_profile = credentials_profile
+        self._sf_cli_org = sf_cli_org
+        self._credential_file = credential_file
+        self._transport: Optional[Any] = None
+
+    def request(
+        self,
+        request: HTTPRequest,
+        body: Optional[str] = None,
+    ) -> HTTPResponse:
+        # Body and response are treated as opaque strings; the SDK makes no
+        # assumption about their format (JSON, XML, text, ...).
+        callout_request = {
+            "path": request.url,
+            "method": request.method,
+            "headers": dict(request.headers),
+            "body": body if body is not None else "",
+        }
+        callout_response = self._callout(callout_request)
+        return HTTPResponseBuilder.build(
+            {
+                "status_code": callout_response.get("status_code"),
+                "headers": callout_response.get("headers", {}),
+                "body": callout_response.get("body") or "",
+            }
+        )
+
+    def _callout(self, callout_request: Dict[str, Any]) -> Dict[str, Any]:
+        """Execute the callout via the transport.
+
+        Returns a dict with ``status_code``, ``headers``, and ``body``.
+        """
+        result: Dict[str, Any] = self._get_transport().callout(callout_request)
+        return result
+
+    def _get_transport(self) -> Any:
+        if self._transport is None:
+            from datacustomcode.named_credential.direct.transport import (
+                DirectCalloutTransport,
+            )
+
+            self._transport = DirectCalloutTransport(
+                credentials_profile=self._credentials_profile,
+                sf_cli_org=self._sf_cli_org,
+                credential_file=self._credential_file,
+            )
+        return self._transport

datacustomcode/named_credential/direct/__init__.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2025, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Named Credential callout path.
+
+This resolves the endpoint via the NamedCredential Connect API
+and injects auth from a developer-provided ``external_callout_config.json``
+"""

datacustomcode/named_credential/direct/auth.py

@@ -0,0 +1,63 @@
+# Copyright (c) 2025, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Inject external credential auth into an outgoing request.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+)
+
+from requests.auth import AuthBase
+
+from datacustomcode.named_credential.direct.credentials import AuthType
+
+if TYPE_CHECKING:
+    from requests.models import PreparedRequest
+
+
+class DynamicAuthHandler(AuthBase):
+    def __init__(self, cred_config: Dict[str, Any]) -> None:
+        self.config = cred_config
+        self.auth_type = cred_config.get("auth_type")
+
+    def __call__(self, request: PreparedRequest) -> PreparedRequest:
+        if self.auth_type == AuthType.BASIC.value:
+            user = self.config.get("username", "")
+            pwd = self.config.get("password", "")
+            token = base64.b64encode(f"{user}:{pwd}".encode()).decode()
+            request.headers["Authorization"] = f"Basic {token}"
+
+        elif self.auth_type == AuthType.CUSTOM.value:
+            for name, value in self.config.get("custom_headers", {}).items():
+                request.headers[name] = value
+
+        elif self.auth_type in (AuthType.OAUTH.value, AuthType.JWT.value):
+            bearer = self.config.get("access_token") or self.config.get("token")
+            if not bearer:
+                raise ValueError(
+                    f"'{self.auth_type}' auth requires an 'access_token' or 'token'."
+                )
+            request.headers["Authorization"] = f"Bearer {bearer}"
+
+        else:
+            raise ValueError(f"Unsupported auth_type '{self.auth_type}'.")
+
+        return request

datacustomcode/named_credential/direct/credentials.py

@@ -0,0 +1,121 @@
+# Copyright (c) 2025, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Load developer credentials for direct callouts from ``external_callout_config.json``.
+
+The file lives in the parent of the payload folder so it is never packaged in
+the deployment zip. Its ``credentials`` section is keyed by callout reference
+(``callout:<NamedCredential>``); each value carries a mandatory ``auth_type``
+and an optional ``target_url``.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+import json
+import os
+from pathlib import Path
+from typing import (
+    Any,
+    Dict,
+    Optional,
+)
+
+# Default file name; discovered in the parent of the payload folder.
+EXTERNAL_CALLOUT_CREDENTIAL = "external_callout_config.json"
+# Absolute-path override, primarily for tests and non-standard layouts.
+CREDENTIAL_FILE_ENV_VAR = "DATACUSTOMCODE_EXTERNAL_CALLOUT_CONFIG"
+
+
+class AuthType(str, Enum):
+    """External Credential auth types supported by External Services."""
+
+    BASIC = "Basic"
+    CUSTOM = "Custom"
+    JWT = "Jwt"
+    OAUTH = "OAuth"
+
+
+class CredentialError(RuntimeError):
+    """Raised when credentials cannot be found or are invalid."""
+
+
+def _discover_credential_file() -> Optional[Path]:
+    """Find the config file via env override, then by walking up from cwd."""
+    override = os.environ.get(CREDENTIAL_FILE_ENV_VAR)
+    if override:
+        return Path(override)
+
+    for directory in (Path.cwd(), *Path.cwd().parents):
+        candidate = directory / EXTERNAL_CALLOUT_CREDENTIAL
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+class CredentialStore:
+    """Reads ``external_callout_config.json`` and returns per-callout config."""
+
+    def __init__(self, credential_file: Optional[str] = None) -> None:
+        self._explicit_path = Path(credential_file) if credential_file else None
+        self._credentials: Optional[Dict[str, Dict[str, Any]]] = None
+
+    def _load(self) -> Dict[str, Dict[str, Any]]:
+        if self._credentials is not None:
+            return self._credentials
+
+        path = self._explicit_path or _discover_credential_file()
+        if path is None or not path.is_file():
+            raise CredentialError(
+                f"Could not find '{EXTERNAL_CALLOUT_CREDENTIAL}'. Place it in the "
+                f"parent of your payload folder, or set "
+                f"${CREDENTIAL_FILE_ENV_VAR} to its path."
+            )
+        try:
+            with open(path, "r") as f:
+                data = json.load(f)
+        except (OSError, json.JSONDecodeError) as exc:
+            raise CredentialError(f"Failed to read '{path}': {exc}") from exc
+
+        # Per-callout entries live under the ``credentials`` section, leaving
+        # room for other config sections alongside them in the future.
+        credentials = data.get("credentials") if isinstance(data, dict) else None
+        if not isinstance(credentials, dict):
+            raise CredentialError(
+                f"'{path}' must be a JSON object with a 'credentials' section "
+                f"keyed by callout reference."
+            )
+        self._credentials = credentials
+        return credentials
+
+    def get(self, callout_key: str) -> Dict[str, Any]:
+        """Return the config for a callout key (e.g. ``callout:AWS_S3_Service``).
+
+        Raises:
+            CredentialError: if the key is missing or has no ``auth_type``.
+        """
+        credentials = self._load()
+        config = credentials.get(callout_key)
+        if config is None:
+            raise CredentialError(
+                f"No credential configuration found for '{callout_key}'. "
+                f"Add it to the 'credentials' section of "
+                f"'{EXTERNAL_CALLOUT_CREDENTIAL}'."
+            )
+        if not isinstance(config, dict) or not config.get("auth_type"):
+            raise CredentialError(
+                f"Credential for '{callout_key}' is missing the mandatory "
+                f"'auth_type' field."
+            )
+        return config