qodev-apollo-api 0.2.1__tar.gz → 0.3.0__tar.gz

{qodev_apollo_api-0.2.1 → qodev_apollo_api-0.3.0}/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-08
+
+### Added
+
+- `ApolloClient.update_opportunity_roles(opportunity_id, roles)` — `POST /opportunities/update_roles`. Sets the contact roles on a deal (replaces the full set; read the current roles from `get_deal(...).opportunity_contact_roles` and modify). Returns the updated `Deal`. Surfaces the previously curl-only role-management endpoint.
+- `ApolloClient.list_custom_fields()` — `GET /typed_custom_fields`. Returns the account/contact/opportunity custom field definitions as a new `CustomField` model (`id`, `modality`, `name`, `type`, `picklist_options`, `mapped_crm_field`).
+- `CustomField` model, exported from the package root.
+
 ## [0.2.1] - 2026-07-01
 
 ### Fixed

{qodev_apollo_api-0.2.1 → qodev_apollo_api-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qodev-apollo-api
-Version: 0.2.1
+Version: 0.3.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.2.1 → qodev_apollo_api-0.3.0}/pyproject.toml

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

{qodev_apollo_api-0.2.1 → qodev_apollo_api-0.3.0}/src/qodev_apollo_api/__init__.py

@@ -35,6 +35,7 @@ from .models import (
     CrmJob,
     CrmNote,
     Currency,
+    CustomField,
     Deal,
     Email,
     EmailerMessage,
@@ -111,6 +112,7 @@ __all__ = [
     "CrmJob",
     "CrmNote",
     "Currency",
+    "CustomField",
     "Deal",
     "Email",
     "EmailParticipant",
@@ -151,4 +153,4 @@ __all__ = [
     "resolve_task",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{qodev_apollo_api-0.2.1 → qodev_apollo_api-0.3.0}/src/qodev_apollo_api/client.py

@@ -3,12 +3,14 @@
 Type-safe async wrapper for Apollo.io API.
 """
 
+import logging
 import os
 from datetime import datetime
 from types import TracebackType
 from typing import Any
 
 import httpx
+from pydantic import ValidationError
 
 from .exceptions import APIError, AuthenticationError, RateLimitError
 from .models import (
@@ -20,6 +22,7 @@ from .models import (
     ContactDetail,
     Conversation,
     ConversationDetail,
+    CustomField,
     Deal,
     Email,
     EmailerMessage,
@@ -40,6 +43,8 @@ from .models import (
 )
 from .utils import markdown_to_prosemirror, normalize_linkedin_url, prosemirror_to_markdown
 
+logger = logging.getLogger(__name__)
+
 
 class ApolloClient:
     """Async Apollo.io API client with context manager support."""
@@ -516,6 +521,47 @@ class ApolloClient:
             page=1,
         )
 
+    async def update_opportunity_roles(self, opportunity_id: str, roles: list[dict]) -> Deal:
+        """Set the contact roles on a deal/opportunity (undocumented endpoint).
+
+        This **replaces** the full set of contact roles on the opportunity, so
+        callers should pass the complete desired set (read the current roles from
+        ``get_deal(...).opportunity_contact_roles`` and modify them). Each entry is
+        a dict with ``contact_id`` and, optionally, ``opportunity_contact_role_type_id``
+        and ``is_primary``::
+
+            roles = [
+                {"contact_id": "abc", "opportunity_contact_role_type_id": "t1", "is_primary": True},
+                {"contact_id": "def", "is_primary": False},
+            ]
+
+        Args:
+            opportunity_id: The opportunity/deal ID.
+            roles: The complete list of contact-role entries to set.
+
+        Returns:
+            The updated Deal.
+        """
+        data = {"opportunity_id": opportunity_id, "roles": roles}
+        result = await self._post("/opportunities/update_roles", data)
+        return Deal.model_validate(result.get("opportunity", result))
+
+    # ========================================================================
+    # CUSTOM FIELDS
+    # ========================================================================
+
+    async def list_custom_fields(self) -> list[CustomField]:
+        """List all typed custom field definitions (undocumented endpoint).
+
+        Returns definitions for custom fields across every modality (contact,
+        account, opportunity). Use ``modality`` to filter client-side.
+
+        Returns:
+            List of CustomField definitions.
+        """
+        result = await self._get("/typed_custom_fields")
+        return [CustomField.model_validate(f) for f in result.get("typed_custom_fields", [])]
+
     # ========================================================================
     # ENRICHMENT
     # ========================================================================
@@ -709,7 +755,14 @@ class ApolloClient:
             data["multi_sort"] = [{field: {"order": order}} for field, order in sort]
         result = await self._post("/tasks/search", data)
 
-        tasks = [resolve_task(t) for t in result.get("tasks", [])]
+        tasks: list[Task] = []
+        for raw in result.get("tasks", []):
+            try:
+                tasks.append(resolve_task(raw))
+            except ValidationError:
+                # A single structurally-invalid row (e.g. missing id) must not sink the whole
+                # page — skip it so the rest of the results stay usable.
+                logger.warning("Skipping unparseable task id=%s", raw.get("id"), exc_info=True)
         pagination = result.get("pagination", {})
 
         return PaginatedResponse[Task](

{qodev_apollo_api-0.2.1 → qodev_apollo_api-0.3.0}/src/qodev_apollo_api/models.py

@@ -640,6 +640,21 @@ class Stage(ApolloModel):
     team_id: str | None = None
 
 
+class CustomField(ApolloModel):
+    """A typed custom field definition (from GET /typed_custom_fields).
+
+    ``modality`` is the entity the field belongs to (e.g. "contact", "account",
+    "opportunity"); ``type`` is the value type (e.g. "text", "date", "picklist").
+    """
+
+    id: str
+    modality: str | None = None
+    name: str | None = None
+    type: str | None = None
+    picklist_options: list[str] = Field(default_factory=list)
+    mapped_crm_field: str | None = None
+
+
 # ============================================================================
 # ACTIVITY MODELS
 # ============================================================================
@@ -823,8 +838,14 @@ class BaseTask(ApolloModel):
     title: str | None = None
     subject: str | None = None
     type: TaskType | None = None
-    priority: TaskPriority | None = None
-    status: TaskStatus | None = None
+    # Kept as raw strings, not the TaskStatus/TaskPriority enums: Apollo returns values the
+    # library doesn't model (status: skipped/archived/…; priority occasionally outside
+    # high/medium/low). A strict enum here broke deserialization — a task with e.g.
+    # status="skipped" failed the discriminated union AND resolve_task's OtherTask fallback
+    # (which inherits these fields), so a single such row raised for the *whole* search page.
+    # Compare against TaskStatus.* / TaskPriority.* — StrEnum equality still holds.
+    priority: str | None = None
+    status: str | None = None
     due_at: datetime | None = None
     note: str | None = None
     answered: bool | None = None

{qodev_apollo_api-0.2.1 → qodev_apollo_api-0.3.0}/tests/test_client.py

@@ -21,6 +21,7 @@ from qodev_apollo_api.models import (
     ContactDetail,
     Conversation,
     ConversationDetail,
+    CustomField,
     Deal,
     Email,
     EmailerMessage,
@@ -305,6 +306,38 @@ async def test_search_tasks(client: ApolloClient):
     assert client._client.request.call_args[0] == ("POST", "/tasks/search")
 
 
+async def test_search_tasks_returns_task_with_unmodelled_status(client: ApolloClient):
+    """Regression: a task whose status Apollo returns but the library doesn't model
+    (skipped/archived/…) is returned with the raw status — not dropped, not raised. This
+    is what broke the LinkedIn connect batch: a single skipped task sank the whole page."""
+    client._client.request.return_value = _make_response(
+        {
+            "tasks": [{"id": "t1", "type": "linkedin_step_connect", "status": "skipped"}],
+            "pagination": {"total_entries": 1},
+        }
+    )
+
+    result = await client.search_tasks()
+
+    assert len(result.items) == 1
+    assert result.items[0].status == "skipped"
+
+
+async def test_search_tasks_skips_unparseable_row(client: ApolloClient):
+    """A structurally-invalid row (missing id) is skipped, not fatal — the rest of the page
+    is still returned."""
+    client._client.request.return_value = _make_response(
+        {
+            "tasks": [{"type": "call"}, {"id": "t2", "type": "call"}],
+            "pagination": {"total_entries": 2},
+        }
+    )
+
+    result = await client.search_tasks()
+
+    assert [t.id for t in result.items] == ["t2"]
+
+
 async def test_search_tasks_with_sort(client: ApolloClient):
     """Test search_tasks with sort parameter generates multi_sort payload."""
     client._client.request.return_value = _make_response(
@@ -586,6 +619,53 @@ async def test_list_opportunity_contact_role_types(client: ApolloClient):
     assert call_args[1]["json"] == {}
 
 
+async def test_update_opportunity_roles(client: ApolloClient):
+    """Test POST /opportunities/update_roles returns the updated Deal with the roles body."""
+    client._client.request.return_value = _make_response(
+        {"opportunity": {"id": "d1", "name": "Big Deal"}}
+    )
+
+    roles = [
+        {"contact_id": "c1", "opportunity_contact_role_type_id": "rt1", "is_primary": True},
+        {"contact_id": "c2", "is_primary": False},
+    ]
+    result = await client.update_opportunity_roles("d1", roles)
+
+    assert isinstance(result, Deal)
+    assert result.id == "d1"
+
+    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}
+
+
+async def test_list_custom_fields(client: ApolloClient):
+    """Test GET /typed_custom_fields returns list[CustomField]."""
+    client._client.request.return_value = _make_response(
+        {
+            "typed_custom_fields": [
+                {"id": "f1", "modality": "contact", "name": "First Message", "type": "date"},
+                {
+                    "id": "f2",
+                    "modality": "opportunity",
+                    "name": "Region",
+                    "type": "picklist",
+                    "picklist_options": ["EU", "US"],
+                },
+            ]
+        }
+    )
+
+    result = await client.list_custom_fields()
+
+    assert len(result) == 2
+    assert all(isinstance(f, CustomField) for f in result)
+    assert result[0].name == "First Message"
+    assert result[1].picklist_options == ["EU", "US"]
+
+    assert client._client.request.call_args[0] == ("GET", "/typed_custom_fields")
+
+
 async def test_get_contact_stages(client: ApolloClient):
     """Test GET /contact_stages returns list[dict]."""
     client._client.request.return_value = _make_response(

{qodev_apollo_api-0.2.1 → qodev_apollo_api-0.3.0}/tests/test_models.py

@@ -60,6 +60,7 @@ from qodev_apollo_api.models import (
     PhoneEntry,
     Pipeline,
     Stage,
+    TaskStatus,
     TaskType,
     Technology,
     TranscriptSegment,
@@ -890,6 +891,22 @@ def test_resolve_task_unknown_type_falls_back_to_other_task():
     assert result.id == "1"
 
 
+def test_resolve_task_preserves_unmodelled_status():
+    """A status Apollo returns but the library doesn't model (skipped/archived/…) must
+    deserialize as the raw string rather than raise — otherwise a single such task sinks a
+    whole tasks/search page (it fails the union AND the OtherTask fallback)."""
+    result = resolve_task({"id": "1", "type": "linkedin_step_connect", "status": "skipped"})
+    assert result.status == "skipped"
+    # comparison against the known-value enum still works via StrEnum equality
+    assert result.status != TaskStatus.SCHEDULED
+
+
+def test_resolve_task_preserves_unmodelled_priority():
+    """Same guarantee for priority (values outside high/medium/low)."""
+    result = resolve_task({"id": "1", "type": "linkedin_step_connect", "priority": "none"})
+    assert result.priority == "none"
+
+
 def test_task_with_full_emailer_message():
     """Test EmailTask with complete emailer_message including scheduling fields."""
     task = EmailTask.model_validate(

{qodev_apollo_api-0.2.1 → qodev_apollo_api-0.3.0}/uv.lock

@@ -407,7 +407,7 @@ wheels = [
 
 [[package]]
 name = "qodev-apollo-api"
-version = "0.2.1"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },