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

datacustomcode/client.py

@@ -29,6 +29,7 @@ from datacustomcode.einstein_predictions_config import spark_einstein_prediction
 from datacustomcode.file.path.default import DefaultFindFilePath
 from datacustomcode.io.reader.base import BaseDataCloudReader
 from datacustomcode.llm_gateway_config import spark_llm_gateway_config
+from datacustomcode.named_credential_config import spark_named_credential_config
 from datacustomcode.spark.default import DefaultSparkSessionProvider
 
 if TYPE_CHECKING:
@@ -41,6 +42,9 @@ if TYPE_CHECKING:
     from datacustomcode.io.reader.base import BaseDataCloudReader
     from datacustomcode.io.writer.base import BaseDataCloudWriter, WriteMode
     from datacustomcode.llm_gateway.spark_base import SparkLLMGateway
+    from datacustomcode.named_credential.spark_base import SparkNamedCredential
+    from datacustomcode.named_credential.types.http_request import HTTPRequest
+    from datacustomcode.named_credential.types.http_response import HTTPResponse
     from datacustomcode.spark.base import BaseSparkSessionProvider
 
 
@@ -118,6 +122,21 @@ def _build_spark_einstein_predictions() -> "SparkEinsteinPredictions":
     return cfg.to_object()
 
 
+def _build_spark_named_credential() -> "SparkNamedCredential":
+    """Instantiate the SDK-configured :class:`SparkNamedCredential`.
+
+    Raises:
+        RuntimeError: If no ``spark_named_credential_config`` has been loaded.
+    """
+    cfg = spark_named_credential_config.spark_named_credential_config
+    if cfg is None:
+        raise RuntimeError(
+            "spark_named_credential_config is not configured. Add a "
+            "'spark_named_credential_config' section to config.yaml."
+        )
+    return cfg.to_object()
+
+
 def einstein_predict_col(
     model_api_name: str,
     prediction_type: "PredictionType",
@@ -167,6 +186,40 @@ def einstein_predict_col(
     )
 
 
+def named_credential_request_col(
+    request: "HTTPRequest",
+    body: Optional["Column"] = None,
+) -> "Column":
+    """Build a Spark Column that makes one Named Credential callout per row.
+
+    The endpoint, method, and headers are fixed for the call (taken from
+    ``request``); only ``body`` varies per row. Use this instead of
+    :meth:`Client.named_credential_request` when the callout runs across a
+    DataFrame so each row is dispatched independently rather than one-shot on
+    the driver.
+
+    The returned Column yields a struct ``{status, response, error_code,
+    error_message}`` for each row. ``response`` is itself a struct
+    ``{status_code, body, headers}``. Use ``[...]`` to pick a field, e.g.
+    ``named_credential_request_col(...)["response"]["status_code"]``. A transport
+    failure sets ``status`` to ``ERROR`` and populates ``error_message`` (a non-2xx
+    HTTP response is still ``SUCCESS`` with its code in ``response.status_code``),
+    so a single bad row does not abort the whole Spark job.
+
+    Args:
+        request: The callout template — its symbolic reference, method, and
+            headers are applied to every row.
+        body: Optional per-row ``Column`` holding the request body as a
+            string (or null for no body).
+
+    Returns:
+        A Spark ``Column`` of ``StructType`` with fields ``status``,
+        ``response``, ``error_code``, and ``error_message``.
+    """
+    named_credential = Client()._get_spark_named_credential()
+    return named_credential.request_col(request, body=body)
+
+
 class DataCloudObjectType(Enum):
     DLO = "dlo"
     DMO = "dmo"
@@ -228,6 +281,7 @@ class Client:
         spark_llm_gateway: Optional custom :class:`SparkLLMGateway`.
         spark_einstein_predictions: Optional custom
             :class:`SparkEinsteinPredictions`.
+        spark_named_credential: Optional custom :class:`SparkNamedCredential`.
 
     Example:
     >>> client = Client()
@@ -243,6 +297,7 @@ class Client:
     _file: DefaultFindFilePath
     _spark_llm_gateway: Optional[SparkLLMGateway]
     _spark_einstein_predictions: Optional[SparkEinsteinPredictions]
+    _spark_named_credential: Optional[SparkNamedCredential]
     _data_layer_history: dict[DataCloudObjectType, set[str]]
     _code_type: str
 
@@ -253,6 +308,7 @@ class Client:
         spark_provider: Optional[BaseSparkSessionProvider] = None,
         spark_llm_gateway: Optional[SparkLLMGateway] = None,
         spark_einstein_predictions: Optional[SparkEinsteinPredictions] = None,
+        spark_named_credential: Optional[SparkNamedCredential] = None,
         code_type: str = "script",
     ) -> Client:
 
@@ -260,6 +316,7 @@ class Client:
             cls._instance = super().__new__(cls)
             cls._instance._spark_llm_gateway = spark_llm_gateway
             cls._instance._spark_einstein_predictions = spark_einstein_predictions
+            cls._instance._spark_named_credential = spark_named_credential
             # Initialize Readers and Writers from config
             # and/or provided reader and writer
             if reader is None or writer is None:
@@ -474,6 +531,41 @@ class Client:
             self._spark_einstein_predictions = _build_spark_einstein_predictions()
         return self._spark_einstein_predictions
 
+    def named_credential_request(
+        self,
+        request: "HTTPRequest",
+        body: Optional[str] = None,
+    ) -> "HTTPResponse":
+        """Issue a one-shot Named Credential external callout. This is the
+        scalar counterpart to :func:`named_credential_request_col`: it runs
+        **once** on the driver — not per row. Use the column helper method
+        instead when you want to fan a callout out across every row of a
+        DataFrame.
+
+        Example:
+
+            >>> from datacustomcode.named_credential.types.http_request_builder \\
+            ...     import HTTPRequestBuilder
+            >>> request = (
+            ...     HTTPRequestBuilder().set_url("callout:NC/search").build()
+            ... )
+            >>> response = Client().named_credential_request(request)
+
+        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.
+        """
+        return self._get_spark_named_credential().request(request, body=body)
+
+    def _get_spark_named_credential(self) -> SparkNamedCredential:
+        if self._spark_named_credential is None:
+            self._spark_named_credential = _build_spark_named_credential()
+        return self._spark_named_credential
+
     def _validate_data_layer_history_does_not_contain(
         self, data_cloud_object_type: DataCloudObjectType
     ) -> None:

datacustomcode/config.yaml

@@ -34,3 +34,9 @@ llm_gateway_config:
 
 spark_llm_gateway_config:
   type_config_name: DefaultSparkLLMGateway
+
+named_credential_config:
+  type_config_name: DefaultNamedCredential
+
+spark_named_credential_config:
+  type_config_name: DefaultSparkNamedCredential

datacustomcode/deploy.py

@@ -37,6 +37,9 @@ 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"
@@ -236,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(
@@ -598,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)

datacustomcode/einstein_predictions/spark_default.py

@@ -39,6 +39,9 @@ if TYPE_CHECKING:
 _STATUS_SUCCESS = "SUCCESS"
 _STATUS_ERROR = "ERROR"
 
+# HTTP status considered a successful prediction call.
+_HTTP_OK = 200
+
 
 class DefaultSparkEinsteinPredictions(SparkEinsteinPredictions):
 
@@ -104,6 +107,8 @@ class DefaultSparkEinsteinPredictions(SparkEinsteinPredictions):
 
         def _predict(values_row: Any) -> Dict[str, Optional[str]]:
             if values_row is None:
+                # An entirely null features struct is not the normal per-feature null
+                # case; surface it directly rather than masking it (debuggability).
                 return {
                     "status": _STATUS_ERROR,
                     "response": None,
@@ -181,6 +186,21 @@ def _call_predictions(
     return predictions.predict(request)
 
 
+def _null_feature_name(features: Dict[str, Any]) -> Optional[str]:
+    """Return the name of the first null feature value, or ``None``."""
+    for name, value in features.items():
+        if value is None:
+            return name
+    return None
+
+
+def _null_feature_message(name: str) -> str:
+    return (
+        f"Feature '{name}' has null value. Use coalesce() or when() to handle "
+        f"nulls before calling einstein_predict."
+    )
+
+
 def _invoke_predictions(
     predictions: "EinsteinPredictions",
     model_api_name: str,
@@ -190,18 +210,40 @@ def _invoke_predictions(
 ) -> Dict[str, Any]:
     from datacustomcode.einstein_predictions.errors import EinsteinPredictionsCallError
 
-    response = _call_predictions(
-        predictions, model_api_name, prediction_type, features, settings
-    )
-    if not response.is_success:
-        error_code = _extract_error_code(response)
+    null_feature = _null_feature_name(features)
+    if null_feature is not None:
+        message = _null_feature_message(null_feature)
+        raise EinsteinPredictionsCallError(
+            f"Einstein Predictions call failed: {message}",
+            status=None,
+            error_code=None,
+            error_message=message,
+        )
+
+    try:
+        response = _call_predictions(
+            predictions, model_api_name, prediction_type, features, settings
+        )
+    except EinsteinPredictionsCallError:
+        raise
+    except Exception as exc:
+        # Transport/build failures: surface the real error (no masking) so local
+        # runs stay debuggable. error_code stays None since there is no HTTP status.
+        raise EinsteinPredictionsCallError(
+            f"Einstein Predictions call failed: {exc}",
+            status=None,
+            error_code=None,
+            error_message=str(exc),
+        ) from exc
+
+    if response.status_code != _HTTP_OK:
+        error_message = json.dumps(response.data) if response.data is not None else None
         raise EinsteinPredictionsCallError(
             f"Einstein Predictions call failed: "
-            f"status_code={response.status_code}, "
-            f"error_code={error_code!r}, message={response.data!r}",
+            f"status_code={response.status_code}, message={error_message!r}",
             status=response.status_code,
-            error_code=error_code,
-            error_message=str(response.data) if response.data else None,
+            error_code=str(response.status_code),
+            error_message=error_message,
         )
     return response.data or {}
 
@@ -213,27 +255,46 @@ def _invoke_predictions_as_struct(
     features: Dict[str, Any],
     settings: Optional[Dict[str, Any]],
 ) -> Dict[str, Optional[str]]:
-    response = _call_predictions(
-        predictions, model_api_name, prediction_type, features, settings
-    )
-    if not response.is_success:
+    # (a) Customer-actionable data condition — surface the actionable message directly.
+    null_feature = _null_feature_name(features)
+    if null_feature is not None:
         return {
             "status": _STATUS_ERROR,
             "response": None,
-            "error_code": _extract_error_code(response),
-            "error_message": str(response.data) if response.data else None,
+            "error_code": None,
+            "error_message": _null_feature_message(null_feature),
         }
-    return {
-        "status": _STATUS_SUCCESS,
-        "response": json.dumps(response.data) if response.data is not None else None,
-        "error_code": None,
-        "error_message": None,
-    }
 
+    # (b) Transport/build failures — surface the real error (no masking) so local
+    # runs stay debuggable. error_code stays None since there is no HTTP status.
+    try:
+        response = _call_predictions(
+            predictions, model_api_name, prediction_type, features, settings
+        )
+    except Exception as exc:
+        return {
+            "status": _STATUS_ERROR,
+            "response": None,
+            "error_code": None,
+            "error_message": str(exc),
+        }
 
-def _extract_error_code(response: "PredictionResponse") -> Optional[str]:
-    if response.data:
-        error_code = response.data.get("errorCode")
-        if error_code is not None:
-            return str(error_code)
-    return None
+    if response.status_code == _HTTP_OK:
+        return {
+            "status": _STATUS_SUCCESS,
+            "response": (
+                json.dumps(response.data) if response.data is not None else None
+            ),
+            "error_code": None,
+            "error_message": None,
+        }
+
+    # (c) Non-200 SFAP HTTP error: error_code = status code, error_message = data JSON.
+    return {
+        "status": _STATUS_ERROR,
+        "response": None,
+        "error_code": str(response.status_code),
+        "error_message": (
+            json.dumps(response.data) if response.data is not None else None
+        ),
+    }

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/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