cloudy-salesforce 0.2.0__py3-none-any.whl

cloudy_salesforce/__init__.py

@@ -0,0 +1,33 @@
+"""Typed Salesforce client with query, CRUD, and codegen."""
+
+from cloudy_salesforce.client import (
+    JwtBearerAuthentication,
+    SalesforceClient,
+    SessionAuthentication,
+    UsernamePasswordAuthentication,
+)
+from cloudy_salesforce.collections import DmlResult, delete, insert, update, upsert
+from cloudy_salesforce.exceptions import SalesforceError
+from cloudy_salesforce.query import query, soql_query
+from cloudy_salesforce.sobjects import SObjects, parse_sobject_response, sobject
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "SalesforceClient",
+    "UsernamePasswordAuthentication",
+    "JwtBearerAuthentication",
+    "SessionAuthentication",
+    "query",
+    "soql_query",
+    "insert",
+    "update",
+    "upsert",
+    "delete",
+    "DmlResult",
+    "SalesforceError",
+    "sobject",
+    "SObjects",
+    "parse_sobject_response",
+    "__version__",
+]

cloudy_salesforce/client/__init__.py

@@ -0,0 +1,13 @@
+from .auth import (
+    JwtBearerAuthentication,
+    SessionAuthentication,
+    UsernamePasswordAuthentication,
+)
+from .salesforceclient import SalesforceClient
+
+__all__ = [
+    "SalesforceClient",
+    "UsernamePasswordAuthentication",
+    "JwtBearerAuthentication",
+    "SessionAuthentication",
+]

cloudy_salesforce/client/auth.py

@@ -0,0 +1,171 @@
+import logging
+import time
+from abc import ABC, abstractmethod
+from pathlib import Path
+from xml.sax.saxutils import escape
+
+import jwt
+import requests
+from requests.exceptions import HTTPError
+
+logger = logging.getLogger(__name__)
+
+JWT_BEARER_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:jwt-bearer"
+
+
+class BaseAuthentication(ABC):
+    def __init__(self, session: requests.Session, instance_url: str):
+        self.session = session
+        self.instance_url = instance_url
+
+    @abstractmethod
+    def authenticate(self) -> tuple[requests.Session, str]:
+        pass
+
+    @staticmethod
+    def get_headers(access_token: str) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {access_token}",
+            "Content-Type": "application/json",
+        }
+
+
+class UsernamePasswordAuthentication(BaseAuthentication):
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        security_token: str,
+        login_url: str = "https://login.salesforce.com",
+        api_version: str = "v61.0",
+    ):
+        self.username = username
+        self.password = password
+        self.security_token = security_token
+        self.login_url = login_url
+        self.api_version = api_version
+        session, instance_url = self.authenticate()
+        super().__init__(session, instance_url)
+
+    def authenticate(self) -> tuple[requests.Session, str]:
+        session = requests.Session()
+        soap_version = self.api_version.removeprefix("v")
+        auth_url = f"{self.login_url}/services/Soap/u/{soap_version}"
+        headers = {"Content-Type": "text/xml", "SOAPAction": "login"}
+        escaped_username = escape(self.username)
+        escaped_password = escape(f"{self.password}{self.security_token}")
+        soap_body = f"""
+        <env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
+            <env:Body>
+                <n1:login xmlns:n1="urn:partner.soap.sforce.com">
+                    <n1:username>{escaped_username}</n1:username>
+                    <n1:password>{escaped_password}</n1:password>
+                </n1:login>
+            </env:Body>
+        </env:Envelope>
+        """
+        try:
+            response = session.post(
+                auth_url, headers=headers, data=soap_body, timeout=30
+            )
+            response.raise_for_status()
+            response_content = response.content.decode("utf-8")
+            if "faultstring" in response_content:
+                raise Exception(f"SOAP Fault: {response_content}")
+            access_token = self._extract_access_token(response_content)
+            instance_url = self._extract_instance_url(response_content)
+            logger.info("Authentication successful")
+            session.headers.update(self.get_headers(access_token))
+            return session, instance_url
+        except HTTPError as http_err:
+            logger.error(f"HTTP error occurred: {http_err}")
+            raise
+        except Exception as err:
+            logger.error(f"Other error occurred: {err}")
+            raise
+
+    def _extract_tag(self, response_content: str, tag: str) -> str:
+        start_tag = f"<{tag}>"
+        end_tag = f"</{tag}>"
+        start_index = response_content.find(start_tag)
+        end_index = response_content.find(end_tag)
+        if start_index == -1 or end_index == -1:
+            raise ValueError(f"SOAP response missing <{tag}>")
+        return response_content[start_index + len(start_tag) : end_index]
+
+    def _extract_access_token(self, response_content: str) -> str:
+        return self._extract_tag(response_content, "sessionId")
+
+    def _extract_instance_url(self, response_content: str) -> str:
+        server_url = self._extract_tag(response_content, "serverUrl")
+        return server_url.split("/services")[0]
+
+
+class SessionAuthentication(BaseAuthentication):
+    def __init__(self, access_token: str, instance_url: str):
+        self.access_token = access_token
+        session = requests.Session()
+        session.headers.update(self.get_headers(access_token))
+        super().__init__(session, instance_url)
+
+    def authenticate(self) -> tuple[requests.Session, str]:
+        return self.session, self.instance_url
+
+
+class JwtBearerAuthentication(BaseAuthentication):
+    def __init__(
+        self,
+        client_id: str,
+        username: str,
+        private_key: str | None = None,
+        *,
+        private_key_path: str | None = None,
+        login_url: str = "https://login.salesforce.com",
+    ):
+        self.client_id = client_id
+        self.username = username
+        self.login_url = login_url
+        if private_key is not None:
+            self.private_key = private_key
+        elif private_key_path is not None:
+            self.private_key = Path(private_key_path).read_text(encoding="utf-8")
+        else:
+            raise ValueError("Either private_key or private_key_path is required")
+        session, instance_url = self.authenticate()
+        super().__init__(session, instance_url)
+
+    def _build_assertion(self) -> str:
+        payload = {
+            "iss": self.client_id,
+            "sub": self.username,
+            "aud": self.login_url,
+            "exp": int(time.time()) + 180,
+        }
+        return jwt.encode(payload, self.private_key, algorithm="RS256")
+
+    def authenticate(self) -> tuple[requests.Session, str]:
+        session = requests.Session()
+        token_url = f"{self.login_url}/services/oauth2/token"
+        assertion = self._build_assertion()
+        try:
+            response = session.post(
+                token_url,
+                data={
+                    "grant_type": JWT_BEARER_GRANT_TYPE,
+                    "assertion": assertion,
+                },
+                timeout=30,
+            )
+            response.raise_for_status()
+            token_data = response.json()
+            access_token = token_data["access_token"]
+            instance_url = token_data["instance_url"]
+            logger.info("JWT bearer authentication successful")
+            session.headers.update(self.get_headers(access_token))
+            return session, instance_url
+        except HTTPError as http_err:
+            logger.error(f"HTTP error occurred: {http_err}")
+            raise
+        except Exception as err:
+            logger.error(f"Other error occurred: {err}")
+            raise

cloudy_salesforce/client/config.py

@@ -0,0 +1,166 @@
+"""Load `.cloudy_config` and build authentication from alias definitions."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from dotenv import find_dotenv, load_dotenv
+
+from .auth import (
+    BaseAuthentication,
+    JwtBearerAuthentication,
+    SessionAuthentication,
+    UsernamePasswordAuthentication,
+)
+
+DEFAULT_CLOUDY_CONFIG_PATH = ".cloudy_config"
+
+DEFAULT_CLOUDY_CONFIG_EXAMPLE = """{
+  "auth": {
+    "default_alias": "prod",
+    "aliases": {
+      "prod": {
+        "type": "basic",
+        "login_url": "https://login.salesforce.com",
+        "credentials": {
+          "username": "SF_USERNAME",
+          "password": "SF_PASSWORD",
+          "security_token": "SF_SECURITY_TOKEN"
+        }
+      },
+      "sandbox": {
+        "type": "basic",
+        "sandbox": true,
+        "credentials": {
+          "username": "SF_USERNAME",
+          "password": "SF_PASSWORD",
+          "security_token": "SF_SECURITY_TOKEN"
+        }
+      },
+      "jwt": {
+        "type": "jwt",
+        "login_url": "https://login.salesforce.com",
+        "credentials": {
+          "client_id": "SF_CLIENT_ID",
+          "username": "SF_USERNAME",
+          "private_key": "SF_PRIVATE_KEY"
+        }
+      },
+      "session": {
+        "type": "session",
+        "credentials": {
+          "access_token": "SF_ACCESS_TOKEN",
+          "instance_url": "SF_INSTANCE_URL"
+        }
+      }
+    }
+  },
+  "sobjects": ["Account", "Contact", "Opportunity"]
+}
+"""
+
+DEFAULT_ENV_EXAMPLE = """SF_USERNAME=
+SF_PASSWORD=
+SF_SECURITY_TOKEN=
+SF_CLIENT_ID=
+SF_PRIVATE_KEY=
+SF_ACCESS_TOKEN=
+SF_INSTANCE_URL=
+"""
+
+
+def get_login_url(alias: dict) -> str:
+    if "login_url" in alias:
+        return alias["login_url"]
+    if alias.get("sandbox"):
+        return "https://test.salesforce.com"
+    return "https://login.salesforce.com"
+
+
+def load_cloudy_config(path: str = DEFAULT_CLOUDY_CONFIG_PATH) -> dict:
+    config_path = Path(path)
+    try:
+        with config_path.open("r", encoding="utf-8") as file:
+            config = json.load(file)
+    except FileNotFoundError:
+        raise FileNotFoundError(f"{path} not found") from None
+
+    if not config or "auth" not in config:
+        raise ValueError("Invalid .cloudy_config: missing auth section")
+
+    return config
+
+
+def resolve_alias(config: dict, alias_name: str) -> dict:
+    auth_details = config["auth"]
+    if alias_name == "default":
+        alias_name = auth_details["default_alias"]
+
+    aliases = auth_details.get("aliases")
+    if not aliases or alias_name not in aliases:
+        raise ValueError(f"Unknown auth alias: {alias_name}")
+
+    return aliases[alias_name]
+
+
+def _require_env(var_name: str) -> str:
+    value = os.getenv(var_name)
+    if value is None:
+        raise ValueError(f"Missing required environment variable: {var_name}")
+    return value
+
+
+def build_auth_from_alias(
+    alias: dict,
+    *,
+    api_version: str | None = None,
+) -> BaseAuthentication:
+    if alias["type"] == "basic":
+        load_dotenv(dotenv_path=find_dotenv(raise_error_if_not_found=True))
+        credentials = alias["credentials"]
+        username_var = credentials["username"]
+        password_var = credentials["password"]
+        token_var = credentials["security_token"]
+
+        username = _require_env(username_var)
+        password = _require_env(password_var)
+        security_token = _require_env(token_var)
+
+        kwargs: dict[str, str] = {
+            "username": username,
+            "password": password,
+            "security_token": security_token,
+            "login_url": get_login_url(alias),
+        }
+        effective_api_version = api_version or alias.get("api_version")
+        if effective_api_version is not None:
+            kwargs["api_version"] = effective_api_version
+        return UsernamePasswordAuthentication(**kwargs)
+
+    if alias["type"] == "jwt":
+        load_dotenv(dotenv_path=find_dotenv(raise_error_if_not_found=True))
+        credentials = alias["credentials"]
+        client_id = _require_env(credentials["client_id"])
+        username = _require_env(credentials["username"])
+
+        jwt_kwargs: dict[str, str] = {
+            "client_id": client_id,
+            "username": username,
+            "login_url": get_login_url(alias),
+        }
+        if "private_key_path" in credentials:
+            jwt_kwargs["private_key_path"] = credentials["private_key_path"]
+        else:
+            jwt_kwargs["private_key"] = _require_env(credentials["private_key"])
+        return JwtBearerAuthentication(**jwt_kwargs)
+
+    if alias["type"] == "session":
+        load_dotenv(dotenv_path=find_dotenv(raise_error_if_not_found=True))
+        credentials = alias["credentials"]
+        access_token = _require_env(credentials["access_token"])
+        instance_url = _require_env(credentials["instance_url"])
+        return SessionAuthentication(access_token, instance_url)
+
+    raise ValueError(f"Auth type not supported yet: {alias['type']}")

cloudy_salesforce/client/salesforceclient.py

@@ -0,0 +1,201 @@
+import logging
+import time
+from typing import Any, NoReturn
+
+import requests
+from requests.exceptions import HTTPError
+
+from cloudy_salesforce.exceptions import SalesforceError
+
+from .auth import BaseAuthentication
+from .config import build_auth_from_alias, load_cloudy_config, resolve_alias
+
+logger = logging.getLogger(__name__)
+
+_RATE_LIMIT_RETRY_DELAYS = (0.5, 1.0)
+
+
+def _raise_salesforce_error(http_err: HTTPError) -> NoReturn:
+    """Convert an HTTPError into a structured SalesforceError."""
+    response = http_err.response
+    status_code = response.status_code if response is not None else None
+
+    if response is None:
+        raise SalesforceError(
+            str(http_err),
+            status_code=status_code,
+        ) from http_err
+
+    try:
+        body = response.json()
+    except ValueError:
+        raise SalesforceError(
+            response.text or str(http_err),
+            status_code=status_code,
+            response_body=response.text,
+        ) from http_err
+
+    if isinstance(body, list) and body and isinstance(body[0], dict):
+        entry = body[0]
+        raise SalesforceError(
+            entry.get("message", str(http_err)),
+            status_code=status_code,
+            error_code=entry.get("errorCode"),
+            response_body=body,
+        ) from http_err
+
+    if isinstance(body, dict) and ("errorCode" in body or "message" in body):
+        raise SalesforceError(
+            body.get("message", str(http_err)),
+            status_code=status_code,
+            error_code=body.get("errorCode"),
+            response_body=body,
+        ) from http_err
+
+    raise SalesforceError(
+        str(http_err),
+        status_code=status_code,
+        response_body=body,
+    ) from http_err
+
+
+def _extract_error_code(http_err: HTTPError) -> str | None:
+    response = http_err.response
+    if response is None:
+        return None
+    try:
+        body = response.json()
+    except ValueError:
+        return None
+    if isinstance(body, list) and body and isinstance(body[0], dict):
+        return body[0].get("errorCode")
+    if isinstance(body, dict):
+        return body.get("errorCode")
+    return None
+
+
+def _is_rate_limited(http_err: HTTPError) -> bool:
+    response = http_err.response
+    if response is not None and response.status_code == 429:
+        return True
+    return _extract_error_code(http_err) == "REQUEST_LIMIT_EXCEEDED"
+
+
+class SalesforceClient:
+    DEFAULT_API_VERSION = "v61.0"
+    _default_instance = None
+
+    def __init__(
+        self,
+        auth_strategy: BaseAuthentication,
+        api_version: str = DEFAULT_API_VERSION,
+        *,
+        default: bool = False,
+    ):
+        if not isinstance(auth_strategy, BaseAuthentication):
+            raise TypeError(
+                "auth_strategy must be an instance of a subclass of BaseAuthentication"
+            )
+        self.auth_strategy = auth_strategy
+        self.api_version = api_version
+
+        if default:
+            self.__class__._default_instance = self
+
+    @classmethod
+    def set_default_instance(
+        cls,
+        auth_strategy: BaseAuthentication,
+        api_version: str = DEFAULT_API_VERSION,
+    ):
+        """
+        Sets the default SalesforceClient instance.
+
+        :param auth_strategy: An instance of a subclass of BaseAuthentication.
+        :param api_version: Salesforce REST API version (e.g. "v61.0").
+        """
+        cls(auth_strategy, api_version=api_version, default=True)
+
+    @classmethod
+    def get_default_instance(cls):
+        """
+        Retrieves the default SalesforceClient instance.
+
+        :return: The default SalesforceClient instance.
+        :raises ValueError: If the default instance has not been set.
+        """
+        if cls._default_instance is None:
+            raise ValueError("Default instance not set")
+        return cls._default_instance
+
+    @classmethod
+    def from_config(
+        cls,
+        alias: str = "default",
+        path: str = ".cloudy_config",
+        *,
+        default: bool = False,
+        api_version: str | None = None,
+    ) -> "SalesforceClient":
+        config = load_cloudy_config(path)
+        alias_config = resolve_alias(config, alias)
+
+        effective_api_version = api_version
+        if effective_api_version is None:
+            effective_api_version = alias_config.get(
+                "api_version", cls.DEFAULT_API_VERSION
+            )
+
+        auth = build_auth_from_alias(
+            alias_config, api_version=effective_api_version
+        )
+        return cls(
+            auth,
+            api_version=effective_api_version,
+            default=default,
+        )
+
+    def get_session(self) -> requests.Session:
+        return self.auth_strategy.session
+
+    def get_instance_url(self) -> str:
+        return self.auth_strategy.instance_url
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        body: dict | None = None,
+        params: dict | None = None,
+    ) -> dict[str, Any] | list[dict[str, Any]]:
+        if url.startswith("http://") or url.startswith("https://"):
+            request_url = url
+        else:
+            request_url = f"{self.get_instance_url()}{url}"
+        last_http_err: HTTPError | None = None
+        for attempt in range(len(_RATE_LIMIT_RETRY_DELAYS) + 1):
+            try:
+                response = self.get_session().request(
+                    method, request_url, json=body, params=params, timeout=30
+                )
+                response.raise_for_status()
+                if not response.content:
+                    return {}
+                return response.json()
+
+            except HTTPError as http_err:
+                last_http_err = http_err
+                if attempt < len(_RATE_LIMIT_RETRY_DELAYS) and _is_rate_limited(
+                    http_err
+                ):
+                    time.sleep(_RATE_LIMIT_RETRY_DELAYS[attempt])
+                    continue
+                logger.error(f"HTTP error occurred during query: {http_err}")
+                _raise_salesforce_error(http_err)
+            except Exception as err:
+                logger.error(f"Other error occurred during query: {err}")
+                raise
+
+        if last_http_err is not None:
+            _raise_salesforce_error(last_http_err)
+        raise RuntimeError("request failed without HTTP error")

cloudy_salesforce/collections/__init__.py

@@ -0,0 +1,35 @@
+from .crud_operations import (
+    DeleteProps,
+    InsertProps,
+    UpdateProps,
+    UpsertProps,
+    collections,
+    delete,
+    insert,
+    update,
+    upsert,
+)
+from .return_functions import (
+    build_dml_results,
+    dml_results_only,
+    records_and_response,
+    success_failure,
+)
+from .types import DmlResult
+
+__all__ = [
+    "DeleteProps",
+    "DmlResult",
+    "InsertProps",
+    "UpdateProps",
+    "UpsertProps",
+    "build_dml_results",
+    "collections",
+    "delete",
+    "dml_results_only",
+    "insert",
+    "records_and_response",
+    "success_failure",
+    "update",
+    "upsert",
+]