qodev-apollo-api 0.3.2__tar.gz → 0.4.0__tar.gz

{qodev_apollo_api-0.3.2 → qodev_apollo_api-0.4.0}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-09
+
+### Added
+
+- `create_deal(name, **fields)` creates a deal/opportunity via `POST /opportunities`. `name` is the only required field; optional `owner_id`, `account_id`, `amount`, `opportunity_stage_id`, `closed_date` are forwarded as-is. Requires a **master** API key (non-master keys return 403). Live-verified against the real API.
+
+### Fixed
+
+- `update_opportunity_roles(...)` now sends Apollo's expected **nested** role shape — `{"contact_id": …, "is_primary": …, "role": [{"opportunity_contact_role_type_id": …, "is_primary": …}]}` — instead of the flat `opportunity_contact_role_type_id` on the entry. The flat shape made Apollo 422 with `undefined method 'map' for nil`, so setting a contact's role on a deal failed every time. The public `RoleAssignment` interface is unchanged (callers still pass flat entries).
+- `search_accounts(**filters)` now validates filter keys against an allowlist (`q_organization_name`, `account_stage_ids`, `account_label_ids`, `sort_by_field`, `sort_ascending`) and raises `ValueError` on unknown keys. Apollo silently ignores unrecognised keys and returns an unfiltered default page that looks like a real match (e.g. `query="…"` returned ~28k accounts, "Google" first) — fail-loud now prevents wrong-account attribution.
+
 ## [0.3.2] - 2026-07-08
 
 ### Fixed

{qodev_apollo_api-0.3.2 → qodev_apollo_api-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qodev-apollo-api
-Version: 0.3.2
+Version: 0.4.0
 Summary: Async Python client for Apollo.io CRM API
 Project-URL: Homepage, https://github.com/qodevai/apollo-api
 Project-URL: Repository, https://github.com/qodevai/apollo-api

{qodev_apollo_api-0.3.2 → qodev_apollo_api-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qodev-apollo-api"
-version = "0.3.2"
+version = "0.4.0"
 description = "Async Python client for Apollo.io CRM API"
 readme = "README.md"
 authors = [

{qodev_apollo_api-0.3.2 → qodev_apollo_api-0.4.0}/src/qodev_apollo_api/client.py

@@ -46,6 +46,20 @@ from .utils import markdown_to_prosemirror, normalize_linkedin_url, prosemirror_
 
 logger = logging.getLogger(__name__)
 
+# Filters accepted by POST /accounts/search (besides page/per_page, which are
+# passed explicitly). Apollo *silently drops* unrecognised keys and returns an
+# unfiltered default page, so we validate against this allowlist and raise
+# instead of returning wrong data. See ``ApolloClient.search_accounts``.
+ACCOUNT_SEARCH_FILTERS = frozenset(
+    {
+        "q_organization_name",
+        "account_stage_ids",
+        "account_label_ids",
+        "sort_by_field",
+        "sort_ascending",
+    }
+)
+
 
 class ApolloClient:
     """Async Apollo.io API client with context manager support."""
@@ -350,11 +364,32 @@ class ApolloClient:
         Args:
             page: Page number (default 1)
             limit: Results per page (default 100, max 100)
-            **filters: Additional filters (q_organization_name, account_stage_ids, etc.)
+            **filters: Search filters. Must be keys Apollo actually supports
+                (see ``ACCOUNT_SEARCH_FILTERS``): ``q_organization_name``,
+                ``account_stage_ids``, ``account_label_ids``, ``sort_by_field``,
+                ``sort_ascending``.
 
         Returns:
             Paginated response with Account items
+
+        Raises:
+            ValueError: If an unrecognised filter key is passed. Apollo silently
+                ignores unknown keys and returns an unfiltered default page (which
+                looks like a real match), so we fail loudly instead of returning the
+                wrong accounts. Note ``query=`` is **not** a valid filter — use
+                ``q_organization_name=`` to search by name.
         """
+        unknown = set(filters) - ACCOUNT_SEARCH_FILTERS
+        if unknown:
+            raise ValueError(
+                "Unknown account search filter(s): "
+                + ", ".join(sorted(unknown))
+                + ". Apollo silently ignores unrecognised keys and returns an unfiltered "
+                "default page. Supported filters: "
+                + ", ".join(sorted(ACCOUNT_SEARCH_FILTERS))
+                + " (to search by name use q_organization_name=)."
+            )
+
         data = {"page": page, "per_page": min(limit, 100), **filters}
         result = await self._post("/accounts/search", data)
 
@@ -420,6 +455,25 @@ class ApolloClient:
         result = await self._get(f"/opportunities/{deal_id}")
         return Deal.model_validate(result.get("opportunity", {}))
 
+    async def create_deal(self, name: str, **fields) -> Deal:
+        """Create a new deal/opportunity.
+
+        Note:
+            Apollo requires a **master** API key for this endpoint; a non-master
+            key returns 403. ``name`` is the only required field.
+
+        Args:
+            name: Human-readable deal name (required).
+            **fields: Additional fields (owner_id, account_id, amount,
+                opportunity_stage_id, closed_date [YYYY-MM-DD], etc.).
+
+        Returns:
+            The created Deal model.
+        """
+        data = {"name": name, **fields}
+        result = await self._post("/opportunities", data)
+        return Deal.model_validate(result.get("opportunity", result))
+
     # ========================================================================
     # PIPELINES & STAGES
     # ========================================================================
@@ -545,7 +599,26 @@ class ApolloClient:
         Returns:
             The updated Deal.
         """
-        data = {"opportunity_id": opportunity_id, "roles": roles}
+        # Apollo's endpoint expects each entry's role type *nested* under a ``role``
+        # array — sending ``opportunity_contact_role_type_id`` flat on the entry (with
+        # no ``role`` key) makes the server call ``.map`` on nil and 422 with
+        # "undefined method 'map' for nil". Reshape the flat RoleAssignment entries
+        # into the wire format the server actually accepts.
+        wire_roles: list[dict] = []
+        for entry in roles:
+            # RoleAssignment types is_primary as a bool; default to False when omitted.
+            # Avoid bool(...) coercion, which would turn a stray truthy non-bool (e.g.
+            # the string "false") into True.
+            is_primary = entry.get("is_primary", False)
+            role_obj: dict[str, Any] = {"is_primary": is_primary}
+            role_type_id = entry.get("opportunity_contact_role_type_id")
+            if role_type_id:
+                role_obj["opportunity_contact_role_type_id"] = role_type_id
+            wire_roles.append(
+                {"contact_id": entry["contact_id"], "is_primary": is_primary, "role": [role_obj]}
+            )
+
+        data = {"opportunity_id": opportunity_id, "roles": wire_roles}
         result = await self._post("/opportunities/update_roles", data)
         return Deal.model_validate(result.get("opportunity", result))
 

{qodev_apollo_api-0.3.2 → qodev_apollo_api-0.4.0}/tests/test_client.py

@@ -251,6 +251,45 @@ async def test_search_accounts(client: ApolloClient):
     assert result.items[0].name == "Acme Corp"
 
 
+async def test_search_accounts_rejects_unknown_filter(client: ApolloClient):
+    """An unrecognised filter raises instead of returning a wrong default page.
+
+    Regression: Apollo silently drops unknown keys (e.g. ``query=``) and returns
+    an unfiltered default list that looks like a real match.
+    """
+    with pytest.raises(ValueError, match="Unknown account search filter"):
+        await client.search_accounts(query="Red and Bundle")
+
+    # The bad request must never reach Apollo.
+    client._client.request.assert_not_called()
+
+
+async def test_search_accounts_error_names_the_bad_key_and_suggests_fix(client: ApolloClient):
+    """The message names the offending key and points to q_organization_name."""
+    with pytest.raises(ValueError, match=r"query.*q_organization_name"):
+        await client.search_accounts(query="x")
+
+
+async def test_search_accounts_allows_documented_filters(client: ApolloClient):
+    """All allowlisted keys pass validation and reach the request body."""
+    client._client.request.return_value = _make_response(
+        {"accounts": [], "pagination": {"total_entries": 0}}
+    )
+
+    await client.search_accounts(
+        q_organization_name="Acme",
+        account_stage_ids=["s1"],
+        account_label_ids=["l1"],
+        sort_by_field="account_created_at",
+        sort_ascending=True,
+    )
+
+    body = client._client.request.call_args[1]["json"]
+    assert body["q_organization_name"] == "Acme"
+    assert body["account_stage_ids"] == ["s1"]
+    assert body["sort_by_field"] == "account_created_at"
+
+
 async def test_search_deals(client: ApolloClient):
     """Test POST /opportunities/search returns PaginatedResponse[Deal]."""
     client._client.request.return_value = _make_response(
@@ -533,6 +572,43 @@ async def test_get_deal(client: ApolloClient):
     client._client.request.assert_called_once_with("GET", "/opportunities/d1")
 
 
+async def test_create_deal(client: ApolloClient):
+    """Test POST /opportunities returns the created Deal with name + extra fields in the body."""
+    client._client.request.return_value = _make_response(
+        {"opportunity": {"id": "d9", "name": "New Deal", "amount": "1000"}}
+    )
+
+    result = await client.create_deal(
+        "New Deal", owner_id="o1", account_id="a1", amount=1000, opportunity_stage_id="st1"
+    )
+
+    assert isinstance(result, Deal)
+    assert result.id == "d9"
+
+    call_args = client._client.request.call_args
+    assert call_args[0] == ("POST", "/opportunities")
+    assert call_args[1]["json"] == {
+        "name": "New Deal",
+        "owner_id": "o1",
+        "account_id": "a1",
+        "amount": 1000,
+        "opportunity_stage_id": "st1",
+    }
+
+
+async def test_create_deal_name_only(client: ApolloClient):
+    """Only ``name`` is required; the body carries nothing else."""
+    client._client.request.return_value = _make_response(
+        {"opportunity": {"id": "d10", "name": "Minimal"}}
+    )
+
+    result = await client.create_deal("Minimal")
+
+    assert isinstance(result, Deal)
+    assert result.id == "d10"
+    assert client._client.request.call_args[1]["json"] == {"name": "Minimal"}
+
+
 async def test_get_pipeline(client: ApolloClient):
     """Test GET /opportunity_pipelines/{id} returns Pipeline."""
     client._client.request.return_value = _make_response(
@@ -643,7 +719,11 @@ async def test_list_opportunity_contact_role_types(client: ApolloClient):
 
 
 async def test_update_opportunity_roles(client: ApolloClient):
-    """Test POST /opportunities/update_roles returns the updated Deal with the roles body."""
+    """The flat RoleAssignment entries are reshaped into Apollo's nested ``role`` wire format.
+
+    Regression: sending ``opportunity_contact_role_type_id`` flat on the entry (no
+    ``role`` key) makes Apollo 422 with "undefined method 'map' for nil".
+    """
     client._client.request.return_value = _make_response(
         {"opportunity": {"id": "d1", "name": "Big Deal"}}
     )
@@ -659,7 +739,19 @@ async def test_update_opportunity_roles(client: ApolloClient):
 
     call_args = client._client.request.call_args
     assert call_args[0] == ("POST", "/opportunities/update_roles")
-    assert call_args[1]["json"] == {"opportunity_id": "d1", "roles": roles}
+    assert call_args[1]["json"] == {
+        "opportunity_id": "d1",
+        "roles": [
+            {
+                "contact_id": "c1",
+                "is_primary": True,
+                "role": [{"is_primary": True, "opportunity_contact_role_type_id": "rt1"}],
+            },
+            # No role type → the nested role object carries only is_primary (never a
+            # flat/absent role type, which is what triggered the nil.map crash).
+            {"contact_id": "c2", "is_primary": False, "role": [{"is_primary": False}]},
+        ],
+    }
 
 
 async def test_list_custom_fields(client: ApolloClient):