sfq 0.0.41__tar.gz → 0.0.43__tar.gz

{sfq-0.0.41 → sfq-0.0.43}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sfq
-Version: 0.0.41
+Version: 0.0.43
 Summary: Python wrapper for the Salesforce's Query API.
 Author-email: David Moruzzi <sfq.pypi@dmoruzi.com>
 Keywords: salesforce,salesforce query
@@ -25,6 +25,7 @@ For more varied workflows, consider using an alternative like [Simple Salesforce
 - Simplified query execution for Salesforce instances.
 - Integration with Salesforce authentication via refresh tokens.
 - Option to interact with Salesforce Tooling API for more advanced queries.
+- Platform Events support (list available & publish single/batch).
   
 ## Installation
 
@@ -110,6 +111,36 @@ print(sf.get_sobject_prefixes(key_type="name"))
 >>> {'AIApplication': '0Pp', 'AIApplicationConfig': '6S9', 'AIInsightAction': '9qd', 'AIInsightFeedback': '9bq', 'AIInsightReason': '0T2', 'AIInsightValue': '9qc', ...}
 ```
 
+### Platform Events
+
+Platform Events allow publishing and subscribing to real-time events. Requires a custom Platform Event (e.g., 'sfq__e' with fields like 'text__c').
+
+```python
+from sfq import SFAuth
+
+sf = SFAuth(
+    instance_url="https://example-dev-ed.trailblaze.my.salesforce.com",
+    client_id="your-client-id-here",
+    client_secret="your-client-secret-here",
+    refresh_token="your-refresh-token-here"
+)
+
+# List available events
+events = sf.list_events()
+print(events)  # e.g., ['sfq__e']
+
+# Publish single event
+result = sf.publish('sfq__e', {'text__c': 'Hello Event!'})
+print(result)  # {'success': True, 'id': '2Ee...'}
+
+# Publish batch
+events_data = [
+    {'text__c': 'Batch 1 message'},
+    {'text__c': 'Batch 2 message'}
+]
+batch_result = sf.publish_batch(events_data, 'sfq__e')
+print(batch_result['results'])  # List of results
+
 ## How to Obtain Salesforce Tokens
 
 To use the `sfq` library, you'll need a **client ID** and **refresh token**. The easiest way to obtain these is by using the Salesforce CLI:
@@ -183,4 +214,3 @@ To use the `sfq` library, you'll need a **client ID** and **refresh token**. The
 - **Security**: Safeguard your client_id, client_secret, and refresh_token diligently, as they provide access to your Salesforce environment. Avoid sharing or exposing them in unsecured locations.
 - **Efficient Data Retrieval**: The `query` and `cquery` function automatically handles pagination, simplifying record retrieval across large datasets. It's recommended to use the `LIMIT` clause in queries to control the volume of data returned.
 - **Advanced Tooling Queries**: Utilize the `tooling_query` function to access the Salesforce Tooling API. This option is designed for performing complex operations, enhancing your data management capabilities.
-

{sfq-0.0.41 → sfq-0.0.43}/README.md

@@ -9,6 +9,7 @@ For more varied workflows, consider using an alternative like [Simple Salesforce
 - Simplified query execution for Salesforce instances.
 - Integration with Salesforce authentication via refresh tokens.
 - Option to interact with Salesforce Tooling API for more advanced queries.
+- Platform Events support (list available & publish single/batch).
   
 ## Installation
 
@@ -94,6 +95,36 @@ print(sf.get_sobject_prefixes(key_type="name"))
 >>> {'AIApplication': '0Pp', 'AIApplicationConfig': '6S9', 'AIInsightAction': '9qd', 'AIInsightFeedback': '9bq', 'AIInsightReason': '0T2', 'AIInsightValue': '9qc', ...}
 ```
 
+### Platform Events
+
+Platform Events allow publishing and subscribing to real-time events. Requires a custom Platform Event (e.g., 'sfq__e' with fields like 'text__c').
+
+```python
+from sfq import SFAuth
+
+sf = SFAuth(
+    instance_url="https://example-dev-ed.trailblaze.my.salesforce.com",
+    client_id="your-client-id-here",
+    client_secret="your-client-secret-here",
+    refresh_token="your-refresh-token-here"
+)
+
+# List available events
+events = sf.list_events()
+print(events)  # e.g., ['sfq__e']
+
+# Publish single event
+result = sf.publish('sfq__e', {'text__c': 'Hello Event!'})
+print(result)  # {'success': True, 'id': '2Ee...'}
+
+# Publish batch
+events_data = [
+    {'text__c': 'Batch 1 message'},
+    {'text__c': 'Batch 2 message'}
+]
+batch_result = sf.publish_batch(events_data, 'sfq__e')
+print(batch_result['results'])  # List of results
+
 ## How to Obtain Salesforce Tokens
 
 To use the `sfq` library, you'll need a **client ID** and **refresh token**. The easiest way to obtain these is by using the Salesforce CLI:
@@ -167,4 +198,3 @@ To use the `sfq` library, you'll need a **client ID** and **refresh token**. The
 - **Security**: Safeguard your client_id, client_secret, and refresh_token diligently, as they provide access to your Salesforce environment. Avoid sharing or exposing them in unsecured locations.
 - **Efficient Data Retrieval**: The `query` and `cquery` function automatically handles pagination, simplifying record retrieval across large datasets. It's recommended to use the `LIMIT` clause in queries to control the volume of data returned.
 - **Advanced Tooling Queries**: Utilize the `tooling_query` function to access the Salesforce Tooling API. This option is designed for performing complex operations, enhancing your data management capabilities.
-

{sfq-0.0.41 → sfq-0.0.43}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sfq"
-version = "0.0.41"
+version = "0.0.43"
 description = "Python wrapper for the Salesforce's Query API."
 readme = "README.md"
 authors = [{ name = "David Moruzzi", email = "sfq.pypi@dmoruzi.com" }]

{sfq-0.0.41 → sfq-0.0.43}/src/sfq/__init__.py

@@ -3,13 +3,16 @@
 """
 
 import webbrowser
-from typing import Any, Dict, Iterable, List, Literal, Optional
+from typing import Any, Dict, Generator, Iterable, List, Literal, Optional
 from urllib.parse import quote
 
 # Import new modular components
 from .auth import AuthManager
 from .crud import CRUDClient
 
+# Import platform events support
+from .platform_events import PlatformEventsClient
+
 # Re-export all public classes and functions for backward compatibility
 from .exceptions import (
     APIError,
@@ -28,6 +31,9 @@ from .soap import SOAPClient
 from .utils import get_logger, records_to_html_table
 from .debug_cleanup import DebugCleanup
 
+# Re-export PlatformEventsClient for direct import
+from .platform_events import PlatformEventsClient
+
 # Define public API for documentation tools
 __all__ = [
     "SFAuth",
@@ -43,9 +49,10 @@ __all__ = [
     "ConfigurationError",
     # Package metadata
     "__version__",
+    "PlatformEventsClient",
 ]
 
-__version__ = "0.0.41"
+__version__ = "0.0.43"
 """
 ### `__version__`
 
@@ -63,7 +70,7 @@ class _SFTokenAuth:
         access_token: str,
         api_version: str = "v64.0",
         token_endpoint: str = "/services/oauth2/token",
-        user_agent: str = "sfq/0.0.41",
+        user_agent: str = "sfq/0.0.43",
         sforce_client: str = "_auto",
         proxy: str = "_auto",
     ) -> None:
@@ -107,7 +114,7 @@ class SFAuth:
         access_token: Optional[str] = None,
         token_expiration_time: Optional[float] = None,
         token_lifetime: int = 15 * 60,
-        user_agent: str = "sfq/0.0.41",
+        user_agent: str = "sfq/0.0.43",
         sforce_client: str = "_auto",
         proxy: str = "_auto",
     ) -> None:
@@ -171,8 +178,14 @@ class SFAuth:
         # Initialize the DebugCleanup
         self._debug_cleanup = DebugCleanup(sf_auth=self)
 
+        # Initialize the PlatformEventsClient
+        self._platform_events_client = PlatformEventsClient(
+            http_client=self._http_client,
+            api_version=api_version,
+        )
+
         # Store version information
-        self.__version__ = "0.0.41"
+        self.__version__ = "0.0.43"
         """
         ### `__version__`
         
@@ -353,6 +366,15 @@ class SFAuth:
         """
         return self._auth_manager.org_id
 
+    @property
+    def platform_events(self):
+        """
+        Access to the PlatformEventsClient for advanced usage.
+
+        :return: The PlatformEventsClient instance.
+        """
+        return self._platform_events_client
+
     @property
     def user_id(self) -> Optional[str]:
         """
@@ -618,3 +640,63 @@ class SFAuth:
         if "records" in items:
             items = items["records"]
         return records_to_html_table(items, headers=headers, styled=styled)
+
+    def list_events(self) -> Optional[List[str]]:
+        """
+        List available Platform Events in the Salesforce org.
+
+        :return: List of event API names (e.g., ['sfq__e']) or None on failure.
+        """
+        return self._platform_events_client.list_events()
+
+    def publish(
+        self,
+        event_name: str,
+        event_data: Dict[str, Any],
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Publish a single Platform Event.
+
+        :param event_name: The API name of the Platform Event (e.g., 'sfq__e').
+        :param event_data: Dict of field values for the event (e.g., {'text__c': 'value'}).
+        :return: Response dict with 'success', 'id', etc., or None on failure.
+        """
+        self._refresh_token_if_needed()
+        return self._platform_events_client.publish(event_name, event_data)
+
+    def publish_batch(
+        self,
+        events: List[Dict[str, Any]],
+        event_name: str,
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Publish a batch of Platform Events.
+
+        :param events: List of event data dicts (each with field values).
+        :param event_name: The API name of the Platform Event (e.g., 'sfq__e').
+        :return: Dict with 'results': list of individual results, or None on failure.
+        """
+        self._refresh_token_if_needed()
+        return self._platform_events_client.publish_batch(events, event_name)
+
+    def _subscribe(
+        self,
+        event_name: str,
+        queue_timeout: int = 90,
+        max_runtime: Optional[int] = None,
+    ) -> Generator[Dict[str, Any], None, None]:
+        """
+        Subscribe to a Platform Event topic and yield incoming events.
+
+        Uses the CometD long-polling Streaming API. Topic format:
+        '/event/{EventName}'.
+
+        :param event_name: The Platform Event API name (e.g., 'MyEvent__e')
+        :param queue_timeout: Seconds to wait for messages before heartbeat log
+        :param max_runtime: Max seconds to listen (None for unlimited)
+        :yields: Event dicts with channel and data
+        """
+        self._refresh_token_if_needed()
+        yield from self._platform_events_client.subscribe(
+            event_name, queue_timeout=queue_timeout, max_runtime=max_runtime
+        )

{sfq-0.0.41 → sfq-0.0.43}/src/sfq/http_client.py

@@ -29,7 +29,7 @@ class HTTPClient:
     def __init__(
         self,
         auth_manager: AuthManager,
-        user_agent: str = "sfq/0.0.41",
+        user_agent: str = "sfq/0.0.43",
         sforce_client: str = "_auto",
         high_api_usage_threshold: int = 80,
     ) -> None:

sfq-0.0.43/src/sfq/platform_events.py

@@ -0,0 +1,380 @@
+"""
+Platform Events client module for the SFQ library.
+
+This module provides operations for Salesforce Platform Events including
+listing available events, publishing events, and subscribing to events
+using the Streaming API.
+"""
+
+import json
+import http.client
+import time
+import warnings
+from queue import Empty, Queue
+from urllib.parse import urlparse
+
+from typing import Any, Dict, Generator, List, Optional
+
+from .http_client import HTTPClient
+from .query import QueryClient
+from .utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class PlatformEventsClient:
+    """
+    Manages Platform Events operations for Salesforce API communication.
+
+    This class encapsulates listing available Platform Events, publishing
+    event records, and subscribing to real-time events via CometD streaming.
+    Platform Events must end with the `__e` suffix for custom events.
+    """
+
+    def __init__(
+        self,
+        http_client: HTTPClient,
+        api_version: str,
+    ) -> None:
+        """
+        Initialize the PlatformEventsClient with HTTP client and API version.
+
+        :param http_client: HTTPClient instance for making requests
+        :param api_version: Salesforce API version to use
+        """
+        self.http_client = http_client
+        self.api_version = api_version
+        self.query_client = QueryClient(self.http_client, api_version=self.api_version)
+
+    def list_events(self) -> Optional[List[str]]:
+        """
+        List all available Platform Events in the Salesforce org.
+
+        Uses the REST API to get all sObjects and filter those ending with '__e'.
+
+        :return: List of event names or None on failure
+        """
+        endpoint = f"/services/data/{self.api_version}/sobjects/"
+
+        status_code, data = self.http_client.send_authenticated_request(
+            method="GET",
+            endpoint=endpoint,
+        )
+
+        if status_code != 200 or not data:
+            logger.error("Failed to query for sObjects: HTTP %s - %s", status_code, data)
+            return None
+
+        try:
+            response = json.loads(data)
+            sobjects = response.get("sobjects", [])
+            events = [sobj["name"] for sobj in sobjects if sobj["name"].endswith("__e")]
+
+            logger.debug("Retrieved %d Platform Events: %r", len(events), events)
+            return events
+        except json.JSONDecodeError as e:
+            logger.error("Failed to parse sObjects response: %s", e)
+            return None
+
+    def publish(
+        self,
+        event_name: str,
+        event_data: Dict[str, Any],
+        batch_size: int = 200,
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Publish a single or batch of Platform Events via REST API.
+
+        Posts event data to /sobjects/{EventName}__e. Supports batching
+        for multiple events by passing a list in event_data under 'records'.
+
+        :param event_name: The Platform Event API name (e.g., 'MyEvent__e')
+        :param event_data: Dict of field-value pairs or {'records': [list of dicts]}
+        :param batch_size: Batch size for composite API (default 200)
+        :return: Response dict or None on failure
+        """
+        if not event_name.endswith("__e"):
+            logger.error("Event name must end with '__e': %s", event_name)
+            return None
+
+        sobject = event_name
+        records = event_data.get("records", [event_data]) if isinstance(event_data, dict) else [event_data]
+
+        endpoint = f"/services/data/{self.api_version}/sobjects/{sobject}"
+
+        # For single event, direct POST
+        if len(records) == 1:
+            status_code, data = self.http_client.send_authenticated_request(
+                method="POST",
+                endpoint=endpoint,
+                body=json.dumps(records[0]),
+            )
+            if status_code == 201 and data:
+                result = json.loads(data)
+                logger.debug("Published event '%s': %r", event_name, result)
+                return result
+            else:
+                logger.error("Publish failed for '%s': HTTP %s - %s", event_name, status_code, data)
+                return None
+
+        # For batch, use composite/tree or loop with threading (simple loop for now)
+        results = []
+        for record in records:
+            status_code, data = self.http_client.send_authenticated_request(
+                method="POST",
+                endpoint=endpoint,
+                body=json.dumps(record),
+            )
+            if status_code == 201 and data:
+                results.append(json.loads(data))
+            else:
+                logger.warning("Failed to publish record in batch: HTTP %s - %s", status_code, data)
+                results.append({"error": data or f"HTTP {status_code}"})
+
+        logger.debug("Published batch of %d events for '%s'", len(results), event_name)
+        return {"results": results}
+
+    def publish_batch(
+        self,
+        events: List[Dict[str, Any]],
+        event_name: str,
+        batch_size: int = 200,
+        max_workers: Optional[int] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Publish multiple Platform Events in batches with optional threading.
+
+        :param events: List of event data dicts
+        :param event_name: The Platform Event API name
+        :param batch_size: Records per batch
+        :param max_workers: Max threads for concurrent publishes
+        :return: Dict of results or None on failure
+        """
+        if not event_name.endswith("__e"):
+            logger.error("Event name must end with '__e': %s", event_name)
+            return None
+
+        # Reuse publish logic but force batch mode
+        batch_data = {"records": events}
+        return self.publish(event_name, batch_data, batch_size)
+
+    def subscribe(
+        self,
+        event_name: str,
+        queue_timeout: int = 90,
+        max_runtime: Optional[int] = 10,
+    ) -> Generator[Dict[str, Any], None, None]:
+        """
+        Subscribe to a Platform Event topic and yield incoming events.
+
+        Uses the CometD long-polling Streaming API. Topic format:
+        '/event/{EventName}'.
+
+        :param event_name: The Platform Event API name (e.g., 'MyEvent__e')
+        :param queue_timeout: Seconds to wait for messages before heartbeat log
+        :param max_runtime: Max seconds to listen (None for unlimited)
+        :yields: Event dicts with channel and data
+        """
+        if not event_name.endswith("__e"):
+            logger.error("Event name must end with '__e': %s", event_name)
+            return
+
+        topic = f"/event/{event_name}"
+
+        # Refresh token
+        self.http_client.refresh_token_and_update_auth()
+
+        if not self.http_client.auth_manager.access_token:
+            logger.error("No access token available for event stream.")
+            return
+
+        start_time = time.time()
+        message_queue = Queue()
+        msg_count = 0
+
+        instance_url = self.http_client.auth_manager.instance_url
+        api_version = self.api_version
+        user_agent = self.http_client.user_agent
+        sforce_client = self.http_client.sforce_client
+
+        headers = {
+            "Authorization": f"Bearer {self.http_client.auth_manager.access_token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": user_agent,
+            "Sforce-Call-Options": f"client={sforce_client}",
+        }
+
+        parsed_url = urlparse(instance_url)
+        conn = http.client.HTTPSConnection(parsed_url.netloc)
+        _API_VERSION = api_version.removeprefix("v")
+        client_id = ""
+
+        try:
+            logger.debug("Starting handshake with Salesforce CometD server.")
+            handshake_payload = json.dumps(
+                {
+                    "id": str(msg_count + 1),
+                    "version": "1.0",
+                    "minimumVersion": "1.0",
+                    "channel": "/meta/handshake",
+                    "supportedConnectionTypes": ["long-polling"],
+                    "advice": {"timeout": 60000, "interval": 0},
+                }
+            )
+            conn.request(
+                "POST",
+                f"/cometd/{_API_VERSION}/meta/handshake",
+                body=handshake_payload,
+                headers=headers,
+            )
+            response = conn.getresponse()
+            if response.status != 200:
+                logger.error("Handshake failed: HTTP %d", response.status)
+                return
+            hand_data = json.loads(response.read().decode("utf-8"))
+            if not hand_data or not hand_data[0].get("successful"):
+                logger.error("Handshake failed: %s", hand_data)
+                return
+
+            client_id = hand_data[0]["clientId"]
+            # Extract cookie from handshake response
+            for name, value in response.getheaders():
+                if name.lower() == "set-cookie" and "BAYEUX_BROWSER=" in value:
+                    _bayeux_browser_cookie = value.split("BAYEUX_BROWSER=")[1].split(";")[0]
+                    headers["Cookie"] = f"BAYEUX_BROWSER={_bayeux_browser_cookie}"
+                    break
+
+            logger.debug(f"Handshake successful, client ID: {client_id}")
+
+            logger.debug(f"Subscribing to topic: {topic}")
+            subscribe_message = {
+                "channel": "/meta/subscribe",
+                "clientId": client_id,
+                "subscription": topic,
+                "id": str(msg_count + 1),
+            }
+            conn.request(
+                "POST",
+                f"/cometd/{_API_VERSION}/subscribe",
+                body=json.dumps(subscribe_message),
+                headers=headers,
+            )
+            response = conn.getresponse()
+            if response.status != 200:
+                logger.error("Subscription failed: HTTP %d", response.status)
+                return
+            sub_response = json.loads(response.read().decode("utf-8"))
+            if not sub_response or not sub_response[0].get("successful"):
+                logger.error("Subscription failed: %s", sub_response)
+                return
+
+            # Check for cookie in subscribe response headers
+            for name, value in response.getheaders():
+                if name.lower() == "set-cookie" and "BAYEUX_BROWSER=" in value:
+                    bayeux = value.split("BAYEUX_BROWSER=")[1].split(";")[0]
+                    headers["Cookie"] = f"BAYEUX_BROWSER={bayeux}"
+                    break
+
+            logger.info(f"Successfully subscribed to topic: {topic}")
+
+            while True:
+                if max_runtime and (time.time() - start_time > max_runtime):
+                    logger.info(f"Disconnecting after max_runtime={max_runtime} seconds")
+                    break
+
+                logger.debug("Sending connection message.")
+                connect_payload = json.dumps(
+                    [
+                        {
+                            "channel": "/meta/connect",
+                            "clientId": client_id,
+                            "connectionType": "long-polling",
+                            "id": str(msg_count + 1),
+                        }
+                    ]
+                )
+
+                max_retries = 5
+                attempt = 0
+                while attempt < max_retries:
+                    try:
+                        conn.request(
+                            "POST",
+                            f"/cometd/{_API_VERSION}/meta/connect",
+                            body=connect_payload,
+                            headers=headers,
+                        )
+                        response = conn.getresponse()
+                        if response.status != 200:
+                            logger.warning(f"Connect failed: HTTP {response.status}")
+                            attempt += 1
+                            continue
+                        msg_count += 1
+
+                        events = json.loads(response.read().decode("utf-8"))
+                        for event in events:
+                            if event.get("channel") == topic and "data" in event:
+                                logger.debug(f"Event received for topic {topic}")
+                                message_queue.put(event)
+                        break
+                    except Exception as e:
+                        logger.warning(f"Connection error (attempt {attempt + 1}): {e}")
+                        if conn:
+                            conn.close()
+                        conn = http.client.HTTPSConnection(parsed_url.netloc)
+                        wait_time = min(2 ** attempt, 60)
+                        time.sleep(wait_time)
+                        attempt += 1
+                else:
+                    logger.error("Max retries reached. Exiting event stream.")
+                    break
+
+                while True:
+                    try:
+                        msg = message_queue.get(timeout=queue_timeout)
+                        yield msg
+                    except Empty:
+                        logger.debug(f"Heartbeat: no message in last {queue_timeout} seconds")
+                        break
+        except Exception as err:
+            logger.exception("Subscription error for topic '%s': %s", topic, err)
+        finally:
+            if client_id:
+                try:
+                    logger.debug(f"Disconnecting from server with client ID: {client_id}")
+                    disconnect_payload = json.dumps(
+                        [
+                            {
+                                "channel": "/meta/disconnect",
+                                "clientId": client_id,
+                                "id": str(msg_count + 1),
+                            }
+                        ]
+                    )
+                    conn.request(
+                        "POST",
+                        f"/cometd/{_API_VERSION}/meta/disconnect",
+                        body=disconnect_payload,
+                        headers=headers,
+                    )
+                    response = conn.getresponse()
+                    _ = response.read().decode("utf-8")
+                except Exception as e:
+                    logger.warning(f"Exception during disconnect: {e}")
+            if conn:
+                conn.close()
+
+
+def get_platform_events_client(
+    http_client: HTTPClient,
+    api_version: str,
+) -> PlatformEventsClient:
+    """
+    Factory function to create a PlatformEventsClient instance.
+
+    :param http_client: HTTPClient instance
+    :param api_version: API version
+    :return: New PlatformEventsClient
+    """
+    return PlatformEventsClient(http_client, api_version)