aio-sf 0.1.0b1__py3-none-any.whl → 0.1.0b3__py3-none-any.whl

{aio_salesforce → aio_sf}/__init__.py

@@ -1,27 +1,28 @@
 """aio-salesforce: Async Salesforce library for Python with Bulk API 2.0 support."""
 
-__version__ = "0.1.0b1"
 __author__ = "Jonas"
 __email__ = "charlie@callaway.cloud"
 
-# Connection functionality
-from .connection import (  # noqa: F401
-    SalesforceConnection,
+# Client functionality
+from .api.client import SalesforceClient  # noqa: F401
+from .api.auth import (  # noqa: F401
     SalesforceAuthError,
     AuthStrategy,
     ClientCredentialsAuth,
     RefreshTokenAuth,
     StaticTokenAuth,
+    SfdxCliAuth,
 )
 
-# Core package only exports connection functionality
-# Users import exporter functions directly: from aio_salesforce.exporter import bulk_query
+# Core package only exports client functionality
+# Users import exporter functions directly: from aio_sf.exporter import bulk_query
 
 __all__ = [
-    "SalesforceConnection",
+    "SalesforceClient",
     "SalesforceAuthError",
     "AuthStrategy",
     "ClientCredentialsAuth",
     "RefreshTokenAuth",
     "StaticTokenAuth",
+    "SfdxCliAuth",
 ]

{aio_salesforce → aio_sf}/api/__init__.py

@@ -5,6 +5,7 @@ This package provides organized access to Salesforce APIs:
 - describe: Object and organization describe/metadata
 - bulk_v2: Bulk API v2 for large data operations
 - query: SOQL queries and QueryMore operations
+- collections: Bulk record operations (insert, update, upsert, delete)
 """
 
 # Import API clients and types from organized submodules
@@ -15,6 +16,21 @@ from .bulk_v2 import (
     BulkJobStatus,
     BulkJobError,
 )
+from .collections import (
+    CollectionsAPI,
+    CollectionError,
+    CollectionRequest,
+    CollectionResult,
+    CollectionResponse,
+    InsertCollectionRequest,
+    UpdateCollectionRequest,
+    UpsertCollectionRequest,
+    DeleteCollectionRequest,
+    CollectionInsertResponse,
+    CollectionUpdateResponse,
+    CollectionUpsertResponse,
+    CollectionDeleteResponse,
+)
 from .describe import (
     DescribeAPI,
     FieldInfo,
@@ -25,7 +41,11 @@ from .describe import (
     RecordTypeInfo,
     SObjectDescribe,
     SObjectInfo,
+)
+from .types import (
     SalesforceAttributes,
+    SalesforceRecord,
+    GenericSalesforceRecord,
 )
 from .query import (
     QueryAPI,
@@ -39,6 +59,7 @@ from .query import (
 __all__ = [
     # API Clients
     "BulkV2API",
+    "CollectionsAPI",
     "DescribeAPI",
     "QueryAPI",
     # Bulk v2 Types
@@ -46,6 +67,19 @@ __all__ = [
     "BulkJobInfo",
     "BulkJobStatus",
     "BulkJobError",
+    # Collections Types
+    "CollectionError",
+    "CollectionRequest",
+    "CollectionResult",
+    "CollectionResponse",
+    "InsertCollectionRequest",
+    "UpdateCollectionRequest",
+    "UpsertCollectionRequest",
+    "DeleteCollectionRequest",
+    "CollectionInsertResponse",
+    "CollectionUpdateResponse",
+    "CollectionUpsertResponse",
+    "CollectionDeleteResponse",
     # Describe Types
     "FieldInfo",
     "LimitInfo",
@@ -56,6 +90,8 @@ __all__ = [
     "SObjectDescribe",
     "SObjectInfo",
     "SalesforceAttributes",
+    "SalesforceRecord",
+    "GenericSalesforceRecord",
     # Query Types
     "QueryResult",
     "QueryResponse",

aio_sf/api/auth/__init__.py

@@ -0,0 +1,16 @@
+"""Authentication strategies for Salesforce API."""
+
+from .base import AuthStrategy, SalesforceAuthError
+from .client_credentials import ClientCredentialsAuth
+from .refresh_token import RefreshTokenAuth
+from .static_token import StaticTokenAuth
+from .sfdx_cli import SfdxCliAuth
+
+__all__ = [
+    "AuthStrategy",
+    "SalesforceAuthError",
+    "ClientCredentialsAuth",
+    "RefreshTokenAuth",
+    "StaticTokenAuth",
+    "SfdxCliAuth",
+]

aio_sf/api/auth/base.py

@@ -0,0 +1,43 @@
+"""Base authentication strategy and exceptions."""
+
+import time
+from abc import ABC, abstractmethod
+from typing import Optional
+
+import httpx
+
+
+class SalesforceAuthError(Exception):
+    """Raised when authentication fails or tokens are invalid."""
+
+    pass
+
+
+class AuthStrategy(ABC):
+    """Abstract base class for Salesforce authentication strategies."""
+
+    def __init__(self, instance_url: str | None = None):
+        self.instance_url = instance_url.rstrip("/") if instance_url else None
+        self.access_token: Optional[str] = None
+        self.expires_at: Optional[int] = None
+
+    @abstractmethod
+    async def authenticate(self, http_client: httpx.AsyncClient) -> str:
+        """Authenticate and return access token."""
+        pass
+
+    @abstractmethod
+    async def refresh_if_needed(self, http_client: httpx.AsyncClient) -> str:
+        """Refresh token if needed and return access token."""
+        pass
+
+    @abstractmethod
+    def can_refresh(self) -> bool:
+        """Return True if this strategy can refresh expired tokens."""
+        pass
+
+    def is_token_expired(self) -> bool:
+        """Check if the current token is expired."""
+        if not self.expires_at:
+            return False
+        return self.expires_at <= int(time.time())

aio_sf/api/auth/client_credentials.py

@@ -0,0 +1,94 @@
+"""OAuth Client Credentials authentication strategy."""
+
+import base64
+import logging
+from urllib.parse import urljoin
+
+import httpx
+
+from .base import AuthStrategy, SalesforceAuthError
+
+logger = logging.getLogger(__name__)
+
+
+class ClientCredentialsAuth(AuthStrategy):
+    """OAuth Client Credentials authentication strategy."""
+
+    def __init__(self, instance_url: str, client_id: str, client_secret: str):
+        super().__init__(instance_url)
+        self.client_id = client_id
+        self.client_secret = client_secret
+
+    async def authenticate(self, http_client: httpx.AsyncClient) -> str:
+        """Authenticate using OAuth client credentials flow."""
+        logger.info("Getting Salesforce access token using client credentials")
+
+        oauth_url = urljoin(self.instance_url, "/services/oauth2/token")
+        data = {
+            "grant_type": "client_credentials",
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+        }
+
+        oauth_headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Accept": "application/json",
+        }
+
+        try:
+            response = await http_client.post(
+                oauth_url, data=data, headers=oauth_headers
+            )
+            response.raise_for_status()
+            token_data = response.json()
+            self.access_token = token_data["access_token"]
+
+            # Get token expiration information
+            await self._get_token_expiration(http_client)
+
+            logger.info("Successfully obtained Salesforce access token")
+            return self.access_token
+
+        except httpx.HTTPError as e:
+            logger.error(f"HTTP error getting access token: {e}")
+            raise SalesforceAuthError(f"Authentication failed: {e}")
+        except Exception as e:
+            logger.error(f"Unexpected error getting access token: {e}")
+            raise SalesforceAuthError(f"Authentication failed: {e}")
+
+    async def refresh_if_needed(self, http_client: httpx.AsyncClient) -> str:
+        """Refresh token if needed (always re-authenticate for client credentials)."""
+        if self.access_token and not self.is_token_expired():
+            return self.access_token
+        return await self.authenticate(http_client)
+
+    def can_refresh(self) -> bool:
+        """Client credentials can always re-authenticate."""
+        return True
+
+    async def _get_token_expiration(self, http_client: httpx.AsyncClient) -> None:
+        """Get token expiration time via introspection."""
+        introspect_url = urljoin(self.instance_url, "/services/oauth2/introspect")
+        introspect_data = {
+            "token": self.access_token,
+            "token_type_hint": "access_token",
+        }
+
+        auth_string = base64.b64encode(
+            f"{self.client_id}:{self.client_secret}".encode("utf-8")
+        ).decode("utf-8")
+
+        introspect_response = await http_client.post(
+            introspect_url,
+            data=introspect_data,
+            headers={
+                "Authorization": f"Basic {auth_string}",
+                "Content-Type": "application/x-www-form-urlencoded",
+                "Accept": "application/json",
+            },
+        )
+        introspect_response.raise_for_status()
+        introspect_data = introspect_response.json()
+
+        # Set expiration time with 30 second buffer
+        self.expires_at = introspect_data["exp"] - 30

aio_sf/api/auth/refresh_token.py

@@ -0,0 +1,114 @@
+"""OAuth Refresh Token authentication strategy."""
+
+import base64
+import logging
+from urllib.parse import urljoin
+
+import httpx
+
+from .base import AuthStrategy, SalesforceAuthError
+
+logger = logging.getLogger(__name__)
+
+
+class RefreshTokenAuth(AuthStrategy):
+    """OAuth Refresh Token authentication strategy."""
+
+    def __init__(
+        self,
+        instance_url: str,
+        access_token: str,
+        refresh_token: str,
+        client_id: str,
+        client_secret: str,
+    ):
+        super().__init__(instance_url)
+        self.access_token = access_token
+        self.refresh_token = refresh_token
+        self.client_id = client_id
+        self.client_secret = client_secret
+
+    async def authenticate(self, http_client: httpx.AsyncClient) -> str:
+        """Use the provided access token (refresh if needed)."""
+        if self.access_token and not self.is_token_expired():
+            return self.access_token
+        return await self._refresh_token(http_client)
+
+    async def refresh_if_needed(self, http_client: httpx.AsyncClient) -> str:
+        """Refresh token if needed."""
+        if self.access_token and not self.is_token_expired():
+            return self.access_token
+        return await self._refresh_token(http_client)
+
+    def can_refresh(self) -> bool:
+        """Refresh token auth can refresh tokens."""
+        return bool(self.refresh_token)
+
+    async def _refresh_token(self, http_client: httpx.AsyncClient) -> str:
+        """Refresh the access token using the refresh token."""
+        logger.info("Refreshing Salesforce access token using refresh token")
+
+        oauth_url = urljoin(self.instance_url, "/services/oauth2/token")
+        data = {
+            "grant_type": "refresh_token",
+            "refresh_token": self.refresh_token,
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+        }
+
+        oauth_headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Accept": "application/json",
+        }
+
+        try:
+            response = await http_client.post(
+                oauth_url, data=data, headers=oauth_headers
+            )
+            response.raise_for_status()
+            token_data = response.json()
+            self.access_token = token_data["access_token"]
+
+            # Update refresh token if a new one is provided
+            if "refresh_token" in token_data:
+                self.refresh_token = token_data["refresh_token"]
+
+            # Get token expiration information
+            await self._get_token_expiration(http_client)
+
+            logger.info("Successfully refreshed Salesforce access token")
+            return self.access_token
+
+        except httpx.HTTPError as e:
+            logger.error(f"HTTP error refreshing access token: {e}")
+            raise SalesforceAuthError(f"Token refresh failed: {e}")
+        except Exception as e:
+            logger.error(f"Unexpected error refreshing access token: {e}")
+            raise SalesforceAuthError(f"Token refresh failed: {e}")
+
+    async def _get_token_expiration(self, http_client: httpx.AsyncClient) -> None:
+        """Get token expiration time via introspection."""
+        introspect_url = urljoin(self.instance_url, "/services/oauth2/introspect")
+        introspect_data = {
+            "token": self.access_token,
+            "token_type_hint": "access_token",
+        }
+
+        auth_string = base64.b64encode(
+            f"{self.client_id}:{self.client_secret}".encode("utf-8")
+        ).decode("utf-8")
+
+        introspect_response = await http_client.post(
+            introspect_url,
+            data=introspect_data,
+            headers={
+                "Authorization": f"Basic {auth_string}",
+                "Content-Type": "application/x-www-form-urlencoded",
+                "Accept": "application/json",
+            },
+        )
+        introspect_response.raise_for_status()
+        introspect_data = introspect_response.json()
+
+        # Set expiration time with 30 second buffer
+        self.expires_at = introspect_data["exp"] - 30

aio_sf/api/auth/sfdx_cli.py

@@ -0,0 +1,119 @@
+"""SFDX CLI authentication strategy."""
+
+import asyncio
+import json
+import logging
+import re
+import time
+from typing import Dict, Any
+
+import httpx
+
+from .base import AuthStrategy, SalesforceAuthError
+
+logger = logging.getLogger(__name__)
+
+
+class SfdxCliAuth(AuthStrategy):
+    """SFDX CLI authentication strategy using 'sf org display' command."""
+
+    def __init__(self, username_or_alias: str):
+        """
+        Initialize SFDX CLI authentication strategy.
+
+        :param username_or_alias: Salesforce org username or alias configured in SFDX CLI
+        """
+        # We'll get the instance URL from the CLI command
+        super().__init__(None)
+        self.username_or_alias = username_or_alias
+        self._ansi_escape = re.compile(r"\x1B[@-_][0-?]*[ -/]*[@-~]")
+
+    async def authenticate(self, http_client: httpx.AsyncClient) -> str:
+        """Get access token from SFDX CLI."""
+        logger.info(
+            f"Getting Salesforce access token from SFDX CLI for {self.username_or_alias}"
+        )
+
+        try:
+            # Execute the SFDX command asynchronously
+            token_info = await self._execute_sfdx_command()
+
+            # Extract token and instance URL
+            self.access_token = token_info["accessToken"]
+            self.instance_url = token_info["instanceUrl"].rstrip("/")
+
+            # SFDX tokens typically have a reasonable expiration time
+            # We'll set a conservative 1-hour expiration to trigger refresh
+            self.expires_at = int(time.time()) + 3600
+
+            logger.info("Successfully obtained Salesforce access token from SFDX CLI")
+            return self.access_token
+
+        except Exception as e:
+            logger.error(f"Error getting access token from SFDX CLI: {e}")
+            raise SalesforceAuthError(f"SFDX CLI authentication failed: {e}")
+
+    async def refresh_if_needed(self, http_client: httpx.AsyncClient) -> str:
+        """Refresh token if needed (re-execute CLI command)."""
+        if self.access_token and not self.is_token_expired():
+            return self.access_token
+        return await self.authenticate(http_client)
+
+    def can_refresh(self) -> bool:
+        """SFDX CLI can always re-authenticate."""
+        return True
+
+    async def _execute_sfdx_command(self) -> Dict[str, Any]:
+        """
+        Execute the SFDX CLI command asynchronously and parse the result.
+
+        :returns: Dictionary containing accessToken and instanceUrl
+        :raises: SalesforceAuthError if command fails or output is invalid
+        """
+        cmd = f"sf org display -o {self.username_or_alias} --json"
+
+        try:
+            # Run the command asynchronously
+            process = await asyncio.create_subprocess_shell(
+                cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+            )
+
+            stdout, stderr = await process.communicate()
+
+            if process.returncode != 0:
+                error_msg = stderr.decode().strip() if stderr else "Unknown error"
+                raise SalesforceAuthError(f"SFDX command failed: {error_msg}")
+
+            # Clean ANSI escape sequences from output
+            cleaned_output = self._ansi_escape.sub("", stdout.decode())
+
+            # Parse JSON response
+            try:
+                sfdx_info = json.loads(cleaned_output)
+            except json.JSONDecodeError as e:
+                raise SalesforceAuthError(f"Invalid JSON response from SFDX CLI: {e}")
+
+            # Validate response structure
+            if "result" not in sfdx_info:
+                raise SalesforceAuthError("SFDX CLI response missing 'result' field")
+
+            result = sfdx_info["result"]
+
+            if "accessToken" not in result:
+                raise SalesforceAuthError(
+                    "SFDX CLI response missing 'accessToken' field"
+                )
+
+            if "instanceUrl" not in result:
+                raise SalesforceAuthError(
+                    "SFDX CLI response missing 'instanceUrl' field"
+                )
+
+            return result
+
+        except asyncio.TimeoutError:
+            raise SalesforceAuthError("SFDX CLI command timed out")
+        except FileNotFoundError:
+            raise SalesforceAuthError(
+                "SFDX CLI not found. Please ensure Salesforce CLI is installed and in PATH"
+            )

aio_sf/api/auth/static_token.py

@@ -0,0 +1,31 @@
+"""Static access token authentication strategy."""
+
+import httpx
+
+from .base import AuthStrategy, SalesforceAuthError
+
+
+class StaticTokenAuth(AuthStrategy):
+    """Static access token authentication strategy (no refresh capability)."""
+
+    def __init__(self, instance_url: str, access_token: str):
+        super().__init__(instance_url)
+        self.access_token = access_token
+
+    async def authenticate(self, http_client: httpx.AsyncClient) -> str:
+        """Return the static access token."""
+        if not self.access_token:
+            raise SalesforceAuthError("No access token available")
+        return self.access_token
+
+    async def refresh_if_needed(self, http_client: httpx.AsyncClient) -> str:
+        """Cannot refresh static tokens."""
+        if self.is_token_expired():
+            raise SalesforceAuthError(
+                "Access token has expired and no refresh capability is available."
+            )
+        return await self.authenticate(http_client)
+
+    def can_refresh(self) -> bool:
+        """Static tokens cannot be refreshed."""
+        return False

{aio_salesforce → aio_sf}/api/bulk_v2/client.py

@@ -14,7 +14,7 @@ from .types import (
 )
 
 if TYPE_CHECKING:
-    from ...connection import SalesforceConnection
+    from ..client import SalesforceClient
 
 logger = logging.getLogger(__name__)
 
@@ -22,12 +22,12 @@ logger = logging.getLogger(__name__)
 class BulkV2API:
     """Salesforce Bulk API v2 methods."""
 
-    def __init__(self, connection: "SalesforceConnection"):
-        self.connection = connection
+    def __init__(self, client: "SalesforceClient"):
+        self.client = client
 
     def _get_base_url(self, api_version: Optional[str] = None) -> str:
         """Get the base URL for Bulk API v2 requests."""
-        return self.connection.get_base_url(api_version)
+        return self.client.get_base_url(api_version)
 
     def _get_job_url(self, job_id: str, api_version: Optional[str] = None) -> str:
         """Get the URL for a specific bulk job."""
@@ -57,7 +57,7 @@ class BulkV2API:
 
         :param soql_query: The SOQL query to execute
         :param all_rows: If True, includes deleted and archived records (queryAll)
-        :param api_version: API version to use (defaults to connection version)
+        :param api_version: API version to use (defaults to client version)
         :returns: Job information
         """
         job_url = self._get_jobs_url(api_version)
@@ -67,7 +67,7 @@ class BulkV2API:
             "contentType": "CSV",
         }
 
-        response = await self.connection.post(job_url, json=job_data)
+        response = await self.client.post(job_url, json=job_data)
         response.raise_for_status()
         job_info = response.json()
 
@@ -85,11 +85,11 @@ class BulkV2API:
         Get the status of a bulk job.
 
         :param job_id: The job ID
-        :param api_version: API version to use (defaults to connection version)
+        :param api_version: API version to use (defaults to client version)
         :returns: Job status information
         """
         status_url = self._get_job_url(job_id, api_version)
-        response = await self.connection.get(status_url)
+        response = await self.client.get(status_url)
         response.raise_for_status()
         return response.json()
 
@@ -106,7 +106,7 @@ class BulkV2API:
         :param job_id: The job ID
         :param locator: Query locator for pagination (optional)
         :param max_records: Maximum number of records to fetch
-        :param api_version: API version to use (defaults to connection version)
+        :param api_version: API version to use (defaults to client version)
         :returns: Tuple of (CSV response text, next locator or None)
         """
         results_url = self._get_job_results_url(job_id, api_version)
@@ -114,7 +114,7 @@ class BulkV2API:
         if locator:
             params["locator"] = locator
 
-        response = await self.connection.get(results_url, params=params)
+        response = await self.client.get(results_url, params=params)
         response.raise_for_status()
 
         # Get next locator from headers
@@ -137,7 +137,7 @@ class BulkV2API:
         :param job_id: The job ID to monitor
         :param poll_interval: Time in seconds between status checks
         :param timeout: Maximum time to wait (None for no timeout)
-        :param api_version: API version to use (defaults to connection version)
+        :param api_version: API version to use (defaults to client version)
         :returns: Final job status
         :raises TimeoutError: If job doesn't complete within timeout
         :raises Exception: If job fails
@@ -187,7 +187,7 @@ class BulkV2API:
         :param all_rows: If True, includes deleted and archived records
         :param poll_interval: Time in seconds between status checks
         :param timeout: Maximum time to wait (None for no timeout)
-        :param api_version: API version to use (defaults to connection version)
+        :param api_version: API version to use (defaults to client version)
         :returns: Final job status
         """
         # Create the job