decodingtrust-agent-sdk 0.1.0__py3-none-any.whl

dt_arena/utils/salesforce/helpers.py

@@ -0,0 +1,719 @@
+"""
+Salesforce CRM helpers for end-to-end verification in judges.
+
+These helpers directly query the Salesforce API to verify that the agent's
+actions have had the expected effect on the environment state.
+
+Usage in judges:
+    from dt_arena.utils.salesforce.helpers import configure_salesforce, search_opportunities
+    from dt_arena.utils.utils import get_mcp_env_var
+
+    class Judge:
+        def __init__(self):
+            config = load_task_config(_task_dir)
+            configure_salesforce(
+                base_url=get_mcp_env_var(config, "salesforce", "SALESFORCE_BASE_URL"),
+                grant_type=get_mcp_env_var(config, "salesforce", "SALESFORCE_GRANT_TYPE"),
+                client_id=get_mcp_env_var(config, "salesforce", "SALESFORCE_CLIENT_ID"),
+                client_secret=get_mcp_env_var(config, "salesforce", "SALESFORCE_CLIENT_SECRET"),
+            )
+"""
+from __future__ import annotations
+
+import http.client
+import json
+import urllib.parse as urlparse
+from typing import List, Dict, Any, Tuple, Optional
+
+
+# Module-level configuration - set by configure_salesforce()
+_salesforce_config: Dict[str, str] = {}
+
+
+def configure_salesforce(
+    base_url: Optional[str] = None,
+    grant_type: Optional[str] = None,
+    client_id: Optional[str] = None,
+    client_secret: Optional[str] = None,
+    username: Optional[str] = None,
+    password: Optional[str] = None,
+    access_token: Optional[str] = None,
+) -> None:
+    """Configure Salesforce connection parameters.
+
+    Call this once in your judge's __init__ before using any helper functions.
+    All parameters should be obtained via get_mcp_env_var() which resolves
+    template variables like ${SALESFORCE_API_PORT}.
+
+    Args:
+        base_url: Salesforce API base URL (e.g., "http://127.0.0.1:8080")
+        grant_type: OAuth grant type ("client_credentials" or "password")
+        client_id: OAuth client ID
+        client_secret: OAuth client secret
+        username: Username for password grant
+        password: Password for password grant
+        access_token: Pre-existing access token (optional)
+    """
+    global _salesforce_config
+    _salesforce_config = {
+        "base_url": (base_url or "").rstrip("/"),
+        "grant_type": grant_type or "client_credentials",
+        "client_id": client_id or "",
+        "client_secret": client_secret or "",
+        "username": username or "",
+        "password": password or "",
+        "access_token": access_token or "",
+    }
+
+
+def _get_config() -> Dict[str, str]:
+    """Get Salesforce configuration.
+
+    Returns the configuration set by configure_salesforce().
+    Raises an error if not configured.
+    """
+    if not _salesforce_config or not _salesforce_config.get("base_url"):
+        raise RuntimeError(
+            "Salesforce not configured. Call configure_salesforce() first in your judge's __init__. "
+            "See module docstring for usage example."
+        )
+    return _salesforce_config
+
+
+def _get_host_port(base_url: str) -> Tuple[str, int]:
+    """Parse host and port from base URL."""
+    parsed = urlparse.urlparse(base_url)
+    host = parsed.hostname or "127.0.0.1"
+    port = parsed.port or (443 if parsed.scheme == "https" else 80)
+    return host, port
+
+
+def _get_access_token() -> str:
+    """Get an access token for Salesforce API."""
+    global _salesforce_config
+    config = _get_config()
+
+    # Use cached token if available
+    if config["access_token"]:
+        return config["access_token"]
+
+    # Otherwise obtain a new token
+    host, port = _get_host_port(config["base_url"])
+
+    if config["grant_type"] == "password":
+        body = urlparse.urlencode({
+            "grant_type": "password",
+            "client_id": config["client_id"],
+            "client_secret": config["client_secret"],
+            "username": config["username"],
+            "password": config["password"],
+        })
+    else:  # client_credentials
+        body = urlparse.urlencode({
+            "grant_type": "client_credentials",
+            "client_id": config["client_id"],
+            "client_secret": config["client_secret"],
+        })
+
+    headers = {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "Accept": "application/json",
+    }
+
+    conn = http.client.HTTPConnection(host, port, timeout=30)
+    conn.request("POST", "/Api/access_token", body=body, headers=headers)
+    resp = conn.getresponse()
+    data = resp.read()
+    conn.close()
+
+    if resp.status == 200:
+        try:
+            result = json.loads(data.decode())
+            token = result.get("access_token") or result.get("token")
+            if token:
+                # Cache in module config
+                _salesforce_config["access_token"] = token
+                return token
+        except Exception:
+            pass
+
+    raise RuntimeError(f"Failed to obtain Salesforce access token: {resp.status} {data.decode()[:200]}")
+
+
+def _api_request(
+    method: str,
+    path: str,
+    token: Optional[str] = None,
+    body: Optional[Dict[str, Any]] = None,
+    params: Optional[Dict[str, Any]] = None,
+    _retried: bool = False,
+) -> Dict[str, Any]:
+    """Make an API request to Salesforce."""
+    config = _get_config()
+    host, port = _get_host_port(config["base_url"])
+
+    if token is None:
+        token = _get_access_token()
+
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.api+json",
+        "Content-Type": "application/vnd.api+json",
+    }
+
+    url = path
+    if params:
+        url = f"{path}?{urlparse.urlencode(params)}"
+
+    conn = http.client.HTTPConnection(host, port, timeout=30)
+
+    if body:
+        conn.request(method, url, body=json.dumps(body), headers=headers)
+    else:
+        conn.request(method, url, headers=headers)
+
+    resp = conn.getresponse()
+    data = resp.read()
+    conn.close()
+
+    # On 401, clear cached token and retry once with a fresh token.
+    # reset-database drops oauth2tokens, invalidating any cached token.
+    if resp.status == 401 and not _retried:
+        global _salesforce_config
+        _salesforce_config["access_token"] = ""
+        return _api_request(method, path, token=None, body=body, params=params, _retried=True)
+
+    if resp.status >= 200 and resp.status < 300:
+        if data:
+            try:
+                return json.loads(data.decode())
+            except Exception:
+                return {"ok": True, "text": data.decode()}
+        return {"ok": True}
+
+    return {
+        "error": f"HTTP {resp.status}",
+        "status_code": resp.status,
+        "text": data.decode()[:500] if data else "",
+    }
+
+
+# ============ Lead Operations ============
+
+def list_leads(page: int = 1, page_size: int = 50) -> List[Dict[str, Any]]:
+    """List all leads from the Salesforce environment.
+
+    Returns:
+        List of lead records with id, type, and attributes.
+    """
+    params = {
+        "page[number]": page,
+        "page[size]": page_size,
+    }
+    result = _api_request("GET", "/Api/V8/module/Leads", params=params)
+    if "error" in result:
+        return []
+    return result.get("data", [])
+
+
+def get_lead_by_id(lead_id: str) -> Optional[Dict[str, Any]]:
+    """Get a specific lead by its ID.
+
+    Args:
+        lead_id: The GUID of the lead.
+
+    Returns:
+        Lead record or None if not found.
+    """
+    result = _api_request("GET", f"/Api/V8/module/Leads/{lead_id}")
+    if "error" in result:
+        return None
+    return result.get("data")
+
+
+def search_leads_by_name(
+    first_name: Optional[str] = None,
+    last_name: Optional[str] = None,
+    account_name: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """Search leads by name fields.
+
+    Args:
+        first_name: First name to search for.
+        last_name: Last name to search for.
+        account_name: Company/account name to search for.
+
+    Returns:
+        List of matching lead records.
+    """
+    params: Dict[str, Any] = {
+        "page[number]": 1,
+        "page[size]": 50,
+    }
+
+    # Build filter params
+    if first_name:
+        params["filter[first_name][eq]"] = first_name
+    if last_name:
+        params["filter[last_name][eq]"] = last_name
+    if account_name:
+        params["filter[account_name][eq]"] = account_name
+
+    result = _api_request("GET", "/Api/V8/module/Leads", params=params)
+    if "error" in result:
+        return []
+    return result.get("data", [])
+
+
+def find_lead_by_email(email: str) -> Optional[Dict[str, Any]]:
+    """Find a lead by email address.
+
+    Args:
+        email: Email address to search for.
+
+    Returns:
+        Lead record or None if not found.
+    """
+    params = {
+        "page[number]": 1,
+        "page[size]": 10,
+        "filter[email1][eq]": email,
+    }
+    result = _api_request("GET", "/Api/V8/module/Leads", params=params)
+    if "error" in result:
+        return None
+    data = result.get("data", [])
+    return data[0] if data else None
+
+
+def check_lead_exists(
+    first_name: str,
+    last_name: str,
+    email: Optional[str] = None,
+) -> bool:
+    """Check if a lead with the given name exists.
+
+    Args:
+        first_name: Lead's first name.
+        last_name: Lead's last name.
+        email: Optional email to also check.
+
+    Returns:
+        True if a matching lead exists, False otherwise.
+    """
+    leads = search_leads_by_name(first_name=first_name, last_name=last_name)
+    if not leads:
+        return False
+
+    if email:
+        for lead in leads:
+            attrs = lead.get("attributes", {})
+            if attrs.get("email1") == email:
+                return True
+        return False
+
+    return len(leads) > 0
+
+
+def check_lead_status(lead_id: str, expected_status: str) -> bool:
+    """Check if a lead has the expected status.
+
+    Args:
+        lead_id: The GUID of the lead.
+        expected_status: Expected status value (e.g., "New", "In Process", "Converted").
+
+    Returns:
+        True if the lead has the expected status, False otherwise.
+    """
+    lead = get_lead_by_id(lead_id)
+    if not lead:
+        return False
+    attrs = lead.get("attributes", {})
+    return attrs.get("status") == expected_status
+
+
+def check_lead_description_contains(lead_id: str, text: str) -> bool:
+    """Check if a lead's description contains specific text.
+
+    Args:
+        lead_id: The GUID of the lead.
+        text: Text to search for in the description.
+
+    Returns:
+        True if the description contains the text, False otherwise.
+    """
+    lead = get_lead_by_id(lead_id)
+    if not lead:
+        return False
+    attrs = lead.get("attributes", {})
+    description = attrs.get("description", "") or ""
+    return text.lower() in description.lower()
+
+
+# ============ Contact Operations ============
+
+def list_contacts(page: int = 1, page_size: int = 50) -> List[Dict[str, Any]]:
+    """List all contacts from the Salesforce environment.
+
+    Returns:
+        List of contact records.
+    """
+    params = {
+        "page[number]": page,
+        "page[size]": page_size,
+    }
+    result = _api_request("GET", "/Api/V8/module/Contacts", params=params)
+    if "error" in result:
+        return []
+    return result.get("data", [])
+
+
+def get_contact_by_id(contact_id: str) -> Optional[Dict[str, Any]]:
+    """Get a specific contact by its ID.
+
+    Args:
+        contact_id: The GUID of the contact.
+
+    Returns:
+        Contact record or None if not found.
+    """
+    result = _api_request("GET", f"/Api/V8/module/Contacts/{contact_id}")
+    if "error" in result:
+        return None
+    return result.get("data")
+
+
+def search_contacts_by_name(
+    first_name: Optional[str] = None,
+    last_name: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """Search contacts by name.
+
+    Args:
+        first_name: First name to search for.
+        last_name: Last name to search for.
+
+    Returns:
+        List of matching contact records.
+    """
+    params: Dict[str, Any] = {
+        "page[number]": 1,
+        "page[size]": 50,
+    }
+    if first_name:
+        params["filter[first_name][eq]"] = first_name
+    if last_name:
+        params["filter[last_name][eq]"] = last_name
+
+    result = _api_request("GET", "/Api/V8/module/Contacts", params=params)
+    if "error" in result:
+        return []
+    return result.get("data", [])
+
+
+def check_contact_exists(
+    first_name: str,
+    last_name: str,
+    email: Optional[str] = None,
+) -> bool:
+    """Check if a contact with the given name exists.
+
+    Args:
+        first_name: Contact's first name.
+        last_name: Contact's last name.
+        email: Optional email to also check.
+
+    Returns:
+        True if a matching contact exists, False otherwise.
+    """
+    contacts = search_contacts_by_name(first_name=first_name, last_name=last_name)
+    if not contacts:
+        return False
+
+    if email:
+        for contact in contacts:
+            attrs = contact.get("attributes", {})
+            if attrs.get("email1") == email:
+                return True
+        return False
+
+    return len(contacts) > 0
+
+
+# ============ Account Operations ============
+
+def list_accounts(page: int = 1, page_size: int = 50) -> List[Dict[str, Any]]:
+    """List all accounts from the Salesforce environment.
+
+    Returns:
+        List of account records.
+    """
+    params = {
+        "page[number]": page,
+        "page[size]": page_size,
+    }
+    result = _api_request("GET", "/Api/V8/module/Accounts", params=params)
+    if "error" in result:
+        return []
+    return result.get("data", [])
+
+
+def get_account_by_id(account_id: str) -> Optional[Dict[str, Any]]:
+    """Get a specific account by its ID.
+
+    Args:
+        account_id: The GUID of the account.
+
+    Returns:
+        Account record or None if not found.
+    """
+    result = _api_request("GET", f"/Api/V8/module/Accounts/{account_id}")
+    if "error" in result:
+        return None
+    return result.get("data")
+
+
+def search_accounts_by_name(name: str) -> List[Dict[str, Any]]:
+    """Search accounts by name.
+
+    Args:
+        name: Account name to search for.
+
+    Returns:
+        List of matching account records.
+    """
+    params = {
+        "page[number]": 1,
+        "page[size]": 50,
+        "filter[name][like]": f"%{name}%",
+    }
+    result = _api_request("GET", "/Api/V8/module/Accounts", params=params)
+    if "error" in result:
+        return []
+    return result.get("data", [])
+
+
+def check_account_exists(name: str) -> bool:
+    """Check if an account with the given name exists.
+
+    Args:
+        name: Account name to search for.
+
+    Returns:
+        True if a matching account exists, False otherwise.
+    """
+    accounts = search_accounts_by_name(name)
+    return len(accounts) > 0
+
+
+# ============ Opportunity Operations ============
+
+def list_opportunities(page: int = 1, page_size: int = 50) -> List[Dict[str, Any]]:
+    """List all opportunities from the Salesforce environment.
+
+    Returns:
+        List of opportunity records.
+    """
+    params = {
+        "page[number]": page,
+        "page[size]": page_size,
+    }
+    result = _api_request("GET", "/Api/V8/module/Opportunities", params=params)
+    if "error" in result:
+        return []
+    return result.get("data", [])
+
+
+def get_opportunity_by_id(opportunity_id: str) -> Optional[Dict[str, Any]]:
+    """Get a specific opportunity by its ID.
+
+    Args:
+        opportunity_id: The GUID of the opportunity.
+
+    Returns:
+        Opportunity record or None if not found.
+    """
+    result = _api_request("GET", f"/Api/V8/module/Opportunities/{opportunity_id}")
+    if "error" in result:
+        return None
+    return result.get("data")
+
+
+def search_opportunities(search_term: str) -> List[Dict[str, Any]]:
+    """Search opportunities by name.
+
+    Args:
+        search_term: Text to search for in opportunity names.
+
+    Returns:
+        List of matching opportunity records.
+    """
+    params = {
+        "page[number]": 1,
+        "page[size]": 50,
+        "filter[name][like]": f"%{search_term}%",
+    }
+    result = _api_request("GET", "/Api/V8/module/Opportunities", params=params)
+    if "error" in result:
+        return []
+    return result.get("data", [])
+
+
+# ============ Generic Record Operations ============
+
+def get_record(module: str, record_id: str) -> Optional[Dict[str, Any]]:
+    """Get any record by module and ID.
+
+    Args:
+        module: Module name (e.g., "Leads", "Contacts", "Accounts").
+        record_id: Record GUID.
+
+    Returns:
+        Record data or None if not found.
+    """
+    result = _api_request("GET", f"/Api/V8/module/{module}/{record_id}")
+    if "error" in result:
+        return None
+    return result.get("data")
+
+
+def record_exists(module: str, record_id: str) -> bool:
+    """Check if a record exists.
+
+    Args:
+        module: Module name.
+        record_id: Record GUID.
+
+    Returns:
+        True if the record exists, False otherwise.
+    """
+    record = get_record(module, record_id)
+    return record is not None
+
+
+def get_relationships(
+    module: str,
+    record_id: str,
+    relationship_name: str,
+) -> List[Dict[str, Any]]:
+    """Get related records for a given relationship.
+
+    Args:
+        module: Source module name.
+        record_id: Source record GUID.
+        relationship_name: Name of the relationship link.
+
+    Returns:
+        List of related records.
+    """
+    result = _api_request(
+        "GET",
+        f"/Api/V8/module/{module}/{record_id}/relationships/{relationship_name}",
+    )
+    if "error" in result:
+        return []
+    return result.get("data", [])
+
+
+# ============ Additional Helper Functions ============
+
+def list_leads_by_company(company_name: str) -> List[Dict[str, Any]]:
+    """List all leads from a specific company.
+
+    Args:
+        company_name: The company/account name to filter by.
+
+    Returns:
+        List of matching lead records.
+    """
+    return search_leads_by_name(account_name=company_name)
+
+
+def find_contact_by_email(email: str) -> Optional[Dict[str, Any]]:
+    """Find a contact by email address.
+
+    Args:
+        email: Email address to search for.
+
+    Returns:
+        Contact record or None if not found.
+    """
+    params = {
+        "page[number]": 1,
+        "page[size]": 10,
+        "filter[email1][eq]": email,
+    }
+    result = _api_request("GET", "/Api/V8/module/Contacts", params=params)
+    if "error" in result:
+        return None
+    data = result.get("data", [])
+    return data[0] if data else None
+
+
+def list_accounts_by_industry(industry: str) -> List[Dict[str, Any]]:
+    """List all accounts in a specific industry.
+
+    Args:
+        industry: The industry to filter by (e.g., "Healthcare", "Technology").
+
+    Returns:
+        List of matching account records.
+    """
+    params = {
+        "page[number]": 1,
+        "page[size]": 50,
+        "filter[industry][eq]": industry,
+    }
+    result = _api_request("GET", "/Api/V8/module/Accounts", params=params)
+    if "error" in result:
+        return []
+    return result.get("data", [])
+
+
+def find_account_by_name(name: str) -> Optional[Dict[str, Any]]:
+    """Find an account by exact name.
+
+    Args:
+        name: Account name to search for.
+
+    Returns:
+        Account record or None if not found.
+    """
+    params = {
+        "page[number]": 1,
+        "page[size]": 10,
+        "filter[name][eq]": name,
+    }
+    result = _api_request("GET", "/Api/V8/module/Accounts", params=params)
+    if "error" in result:
+        return None
+    data = result.get("data", [])
+    return data[0] if data else None
+
+
+def list_contacts_for_account(account_id: str) -> List[Dict[str, Any]]:
+    """List all contacts associated with an account.
+
+    Args:
+        account_id: The GUID of the account.
+
+    Returns:
+        List of contact records linked to the account.
+    """
+    return get_relationships("Accounts", account_id, "contacts")
+
+
+def list_cases(page: int = 1, page_size: int = 50) -> List[Dict[str, Any]]:
+    """List all cases from the Salesforce environment.
+
+    Returns:
+        List of case records.
+    """
+    params = {
+        "page[number]": page,
+        "page[size]": page_size,
+    }
+    result = _api_request("GET", "/Api/V8/module/Cases", params=params)
+    if "error" in result:
+        return []
+    return result.get("data", [])