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

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

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-07-10
+
+### Fixed
+
+- **People search** now uses `/mixed_people/api_search`; the old `/mixed_people/search` is deprecated for API callers (422). Note the new endpoint returns teaser data only (no full name/email/linkedin_url without a credit-consuming reveal). The `find_contact_by_linkedin_url` auto-creation step is retired accordingly (it warns; `create_if_missing` is a documented no-op).
+- **Deal name search** uses `q_opportunity_name`, not `q_keywords` (which Apollo silently ignores on `/opportunities/search`). `DEAL_SEARCH_FILTERS` allows `q_opportunity_name` and rejects `q_keywords`.
+- `list_contact_tasks` now filters the tasks search by `contact_ids` (the `/contacts/{id}/tasks` route was removed by Apollo — 404).
+- `list_account_jobs` resolves the account's `organization_id` and reads `/organizations/{org_id}/job_postings` (the `/accounts/{id}/job_postings` route was removed).
+
+### Added
+
+- Search-filter validation across **all** `search_*` methods: unknown filter keys raise (documented endpoints: contacts/deals/people/accounts) or warn (undocumented activity endpoints), preventing Apollo's silent-drop → unfiltered-default-page footgun.
+- `search_*` docstrings now document each filter's empirically-verified accepted format (seniority enums, `"min,max"` employee ranges, location formats, dict ranges, email-status values, canonical `linkedin_url`).
+
+### Removed
+
+- **Breaking:** `list_contact_calls` and `list_account_news` — Apollo removed the underlying routes (`/contacts/{id}/calls`, `/accounts/{id}/news`) with no working replacement.
+
+## [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.5.0}/CLAUDE.md

@@ -110,6 +110,26 @@ Apollo stores notes in ProseMirror JSON format. This library automatically conve
 - Custom URLs can be added/removed
 - Always normalize and verify matches
 
+**`accounts/search` silently drops unknown filter keys:**
+- Passing an unrecognised filter (e.g. `query=` instead of `q_organization_name=`) does **not** error — Apollo ignores it and returns an unfiltered default page (~28k accounts, "Google" first) that looks like a real match.
+- This once caused a wrong company to be attached to a deal + a duplicate account.
+- `search_accounts` guards against it: it validates `**filters` against `ACCOUNT_SEARCH_FILTERS` (`q_organization_name`, `account_stage_ids`, `account_label_ids`, `sort_by_field`, `sort_ascending`) and raises `ValueError` on unknown keys. Same silent-drop risk applies to the other `search_*` methods — pass only documented filters.
+
+**Search-filter formats (empirically verified — a wrong format is silently ignored or matches nothing, never an error):**
+- **Deal name search is `q_opportunity_name`, NOT `q_keywords`.** Apollo silently ignores `q_keywords` on `/opportunities/search` (a nonsense keyword returns *every* deal). `q_opportunity_name` is in `DEAL_SEARCH_FILTERS`; `q_keywords` is not (passing it raises).
+- **`organization_num_employees_ranges`** (people): `"min,max"` **comma** strings, e.g. `["1,10"]`, `["1000,5000"]`. A dash (`"1-10"`) is silently ignored (returns baseline).
+- **`person_seniorities`** (people): lowercase enums — `owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern`. Uppercase / free text match 0 rows.
+- **`person_locations` / `organization_locations`**: country name, 2-letter code (`"US"` == `"United States"`), or `"City, State, Country"`.
+- **`revenue_range` / `organization_num_jobs_range`**: dict `{"min": int, "max": int}`. **`contact_email_status`**: `verified | unverified | likely to engage | unavailable`.
+- **`contacts` `linkedin_url`**: must be Apollo's canonical form `http://www.linkedin.com/in/<slug>` (http, lowercased, url-encoded) or it matches nothing.
+- Full per-filter formats live in each `search_*` docstring.
+
+**`opportunities/update_roles` needs the role type NESTED under a `role` array:**
+- Correct per-entry shape: `{"contact_id": …, "is_primary": …, "role": [{"opportunity_contact_role_type_id": …, "is_primary": …}]}`.
+- Sending `opportunity_contact_role_type_id` flat on the entry (no `role` key) makes Apollo 422 with `undefined method 'map' for nil`.
+- `update_opportunity_roles` reshapes the flat `RoleAssignment` entries into this wire format; callers still pass flat entries.
+- The endpoint **replaces** the full role set and works with a normal (non-master) API key.
+
 ## Testing Strategy
 
 ### Unit Tests

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qodev-apollo-api
-Version: 0.3.2
+Version: 0.5.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.5.0}/pyproject.toml

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

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

@@ -46,6 +46,116 @@ from .utils import markdown_to_prosemirror, normalize_linkedin_url, prosemirror_
 
 logger = logging.getLogger(__name__)
 
+# ---------------------------------------------------------------------------
+# Search-filter allowlists
+#
+# Apollo's /search endpoints *silently drop* unrecognised filter keys and return
+# an unfiltered default page that looks like a real match (e.g. a typo'd
+# ``query=`` on accounts returned ~28k rows, "Google" first). To stop that, each
+# search method validates its ``**filters`` against the relevant allowlist below.
+#
+# Endpoints with a documented, stable flat-filter vocabulary are validated
+# *strictly* (raise on unknown). The activity endpoints below have no published
+# filter docs, so an over-tight allowlist would reject valid filters — those are
+# validated *leniently* (log a warning, still send the request). See
+# ``_validate_search_filters``.
+# ---------------------------------------------------------------------------
+
+# Strict (raise on unknown) — documented flat-filter endpoints.
+ACCOUNT_SEARCH_FILTERS = frozenset(
+    {
+        "q_organization_name",
+        "account_stage_ids",
+        "account_label_ids",
+        "sort_by_field",
+        "sort_ascending",
+    }
+)
+CONTACT_SEARCH_FILTERS = frozenset(
+    {
+        "q_keywords",
+        "contact_stage_ids",
+        "contact_label_ids",
+        "linkedin_url",
+        "sort_by_field",
+        "sort_ascending",
+    }
+)
+DEAL_SEARCH_FILTERS = frozenset(
+    {
+        # Deal *name* search is q_opportunity_name — NOT q_keywords, which Apollo
+        # silently ignores for /opportunities/search (verified: a nonsense keyword
+        # still returned every deal).
+        "q_opportunity_name",
+        "opportunity_stage_ids",
+        "sort_by_field",
+        "sort_ascending",
+    }
+)
+# search_people passes *everything* (incl. page/per_page) through **filters, so
+# those are part of the allowlist here (unlike the methods with explicit args).
+PEOPLE_SEARCH_FILTERS = frozenset(
+    {
+        "q_keywords",
+        "person_titles",
+        "include_similar_titles",
+        "person_seniorities",
+        "person_locations",
+        "organization_locations",
+        "organization_ids",
+        "organization_num_employees_ranges",
+        "q_organization_domains_list",
+        "revenue_range",
+        "currently_using_all_of_technology_uids",
+        "currently_using_any_of_technology_uids",
+        "currently_not_using_any_of_technology_uids",
+        "q_organization_job_titles",
+        "organization_job_locations",
+        "organization_num_jobs_range",
+        "organization_job_posted_at_range",
+        "contact_email_status",
+        "page",
+        "per_page",
+    }
+)
+
+# Lenient (warn on unknown) — undocumented activity endpoints. Seeded from known
+# usage; incompleteness only costs a log line, never a broken call.
+NOTE_SEARCH_FILTERS = frozenset({"contact_ids", "account_ids", "opportunity_ids", "q_keywords"})
+CALL_SEARCH_FILTERS = frozenset({"contact_ids", "account_ids", "user_ids", "q_keywords"})
+TASK_SEARCH_FILTERS = frozenset({"contact_ids", "account_ids", "opportunity_ids", "q_keywords"})
+EMAIL_SEARCH_FILTERS = frozenset({"contact_ids", "emailer_campaign_ids", "q_keywords"})
+CONVERSATION_SEARCH_FILTERS = frozenset({"q_keywords"})
+CALENDAR_EVENT_SEARCH_FILTERS = frozenset({"contact_ids", "user_ids", "q_keywords"})
+
+
+def _validate_search_filters(
+    filters: dict, allowed: frozenset[str], resource: str, *, strict: bool
+) -> None:
+    """Guard against Apollo silently dropping unknown ``**filters`` keys.
+
+    Apollo ignores unrecognised keys on its /search endpoints and returns an
+    unfiltered default page that looks like a real match. When ``strict``, raise
+    ``ValueError`` on any unknown key (documented endpoints); otherwise log a
+    warning and let the request through (undocumented endpoints, where the full
+    valid set isn't published and a hard allowlist would reject valid filters).
+    """
+    unknown = set(filters) - allowed
+    if not unknown:
+        return
+    # Strict allowlists are authoritative ("Supported filters"); lenient ones are
+    # seeded from known usage and may be incomplete ("Known filters"), so the
+    # wording doesn't imply the warned-about key is definitely invalid.
+    label = "Supported filters" if strict else "Known filters"
+    msg = (
+        f"Unknown {resource} search filter(s): {', '.join(sorted(unknown))}. "
+        f"Apollo silently ignores unrecognised keys and returns an unfiltered "
+        f"default page. {label}: {', '.join(sorted(allowed))}."
+    )
+    if strict:
+        raise ValueError(msg)
+    logger.warning(msg)
+
 
 class ApolloClient:
     """Async Apollo.io API client with context manager support."""
@@ -183,11 +293,23 @@ class ApolloClient:
         Args:
             page: Page number (default 1)
             limit: Results per page (default 100, max 100)
-            **filters: Additional filters (q_keywords, contact_stage_ids, linkedin_url, etc.)
+            **filters: Contact search filters (see ``CONTACT_SEARCH_FILTERS``):
+
+                - ``q_keywords`` (str): free-text over name / title / company / email.
+                - ``contact_stage_ids`` (list[str]): stage IDs (see ``get_contact_stages``).
+                - ``contact_label_ids`` (list[str]): label / list IDs.
+                - ``linkedin_url`` (str): must be Apollo's **canonical** form —
+                  ``http://www.linkedin.com/in/<slug>`` (http, lowercased,
+                  url-encoded). A near-miss silently matches nothing.
+                - ``sort_by_field`` (str): ``contact_last_activity_date`` |
+                  ``contact_email_last_opened_at`` | ``contact_email_last_clicked_at`` |
+                  ``contact_created_at`` | ``contact_updated_at``.
+                - ``sort_ascending`` (bool).
 
         Returns:
             Paginated response with Contact items
         """
+        _validate_search_filters(filters, CONTACT_SEARCH_FILTERS, "contact", strict=True)
         data = {"page": page, "per_page": min(limit, 100), **filters}
         result = await self._post("/contacts/search", data)
 
@@ -265,21 +387,27 @@ class ApolloClient:
         create_if_missing: bool = False,
         contact_stage_id: str | None = None,
     ) -> str | None:
-        """Find contact using 3-tier fallback strategy.
+        """Find an existing contact by LinkedIn URL (2-tier lookup).
 
         Strategy:
-        1. Search by LinkedIn URL (exact match)
-        2. Fallback to name search (if unique match)
-        3. People database search for auto-creation (if enabled)
+        1. Search existing contacts by LinkedIn URL (exact match).
+        2. Fall back to a name search among existing contacts (unique match whose
+           normalized URL equals the target).
+
+        Auto-creation from Apollo's people database (the former Step 3) is no
+        longer possible: ``/mixed_people/api_search`` returns teaser data only
+        (no ``linkedin_url``, an obfuscated last name, no email), so a URL match
+        can never succeed and there isn't enough data to create a usable contact.
 
         Args:
             linkedin_url: LinkedIn profile URL
-            person_name: Person's full name (for fallback search)
-            create_if_missing: Auto-create from people database if not found
-            contact_stage_id: Stage ID to assign when creating
+            person_name: Person's full name (for the fallback search)
+            create_if_missing: Deprecated no-op — retained for backwards
+                compatibility. Logs a warning when set; never creates a contact.
+            contact_stage_id: Deprecated no-op (was only used for auto-creation).
 
         Returns:
-            Contact ID if found/created, None otherwise
+            Contact ID if found, None otherwise.
         """
         normalized_url = normalize_linkedin_url(linkedin_url)
 
@@ -308,34 +436,18 @@ class ApolloClient:
                 # Ambiguous - multiple contacts with same name and URL
                 return None
 
-        # Step 3: People database search for auto-creation
+        # Auto-creation from the people database is no longer possible — Apollo's
+        # /mixed_people/api_search returns teaser data (no linkedin_url, obfuscated
+        # last name, no email), so a URL match can't be made nor a usable contact
+        # created. Warn instead of silently doing nothing.
         if create_if_missing and person_name:
-            people_result = await self._post(
-                "/mixed_people/search",
-                {
-                    "q_keywords": person_name,
-                    "per_page": 10,
-                },
+            logger.warning(
+                "find_contact_by_linkedin_url: create_if_missing is no longer supported — "
+                "Apollo's people search returns teaser data without linkedin_url, so no "
+                "contact was created for %r. Use enrichment/reveal + create_contact instead.",
+                person_name,
             )
 
-            people = people_result.get("people", [])
-            for person in people:
-                person_url = person.get("linkedin_url", "")
-                if person_url and normalize_linkedin_url(person_url) == normalized_url:
-                    # Create contact from people database
-                    create_data = {
-                        "first_name": person.get("first_name", ""),
-                        "last_name": person.get("last_name", ""),
-                        "linkedin_url": person.get("linkedin_url"),
-                        "title": person.get("title"),
-                        "person_id": person.get("id"),
-                    }
-                    if contact_stage_id:
-                        create_data["contact_stage_id"] = contact_stage_id
-
-                    created = await self.create_contact(**create_data)
-                    return created.id
-
         return None
 
     # ========================================================================
@@ -350,11 +462,26 @@ 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: Account search filters (see ``ACCOUNT_SEARCH_FILTERS``):
+
+                - ``q_organization_name`` (str): company-name keyword.
+                - ``account_stage_ids`` (list[str]): account stage IDs.
+                - ``account_label_ids`` (list[str]): label / list IDs.
+                - ``sort_by_field`` (str): ``account_last_activity_date`` |
+                  ``account_created_at`` | ``account_updated_at``.
+                - ``sort_ascending`` (bool).
 
         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.
         """
+        _validate_search_filters(filters, ACCOUNT_SEARCH_FILTERS, "account", strict=True)
         data = {"page": page, "per_page": min(limit, 100), **filters}
         result = await self._post("/accounts/search", data)
 
@@ -391,11 +518,20 @@ class ApolloClient:
         Args:
             page: Page number (default 1)
             limit: Results per page (default 100, max 100)
-            **filters: Additional filters (opportunity_stage_ids, q_keywords, etc.)
+            **filters: Deal search filters (see ``DEAL_SEARCH_FILTERS``):
+
+                - ``q_opportunity_name`` (str): deal-name keyword. **Use this, not
+                  ``q_keywords``** — Apollo silently ignores ``q_keywords`` on
+                  ``/opportunities/search`` (it returns every deal).
+                - ``opportunity_stage_ids`` (list[str]): deal stage IDs (see
+                  ``list_all_stages``).
+                - ``sort_by_field`` (str): ``amount`` | ``is_closed`` | ``is_won``.
+                - ``sort_ascending`` (bool).
 
         Returns:
             Paginated response with Deal items
         """
+        _validate_search_filters(filters, DEAL_SEARCH_FILTERS, "deal", strict=True)
         data = {"page": page, "per_page": min(limit, 100), **filters}
         result = await self._post("/opportunities/search", data)
 
@@ -420,6 +556,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 +700,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))
 
@@ -600,13 +774,53 @@ class ApolloClient:
     async def search_people(self, **filters) -> dict:
         """Search people in Apollo's global database.
 
+        Uses ``/mixed_people/api_search``; the older ``/mixed_people/search`` is
+        deprecated for API callers (returns 422). Note that this endpoint returns
+        **teaser data only** — ``first_name``, ``last_name_obfuscated``, ``title``
+        and ``organization``, but not full name / email / linkedin_url (those
+        require a separate enrichment/reveal step and consume credits).
+
         Args:
-            **filters: Search filters (q_keywords, person_titles, person_locations, etc.)
+            **filters: People search filters (see ``PEOPLE_SEARCH_FILTERS``).
+                Formats matter — a wrong format is silently ignored or matches
+                nothing rather than erroring:
+
+                - ``q_keywords`` (str): free text.
+                - ``person_titles`` (list[str]): job titles, e.g. ``["CEO", "VP Sales"]``.
+                  ``include_similar_titles`` (bool): broaden to related titles.
+                - ``person_seniorities`` (list[str]): **lowercase enums** —
+                  ``owner, founder, c_suite, partner, vp, head, director, manager,
+                  senior, entry, intern``. Uppercase / free text (``"VP"``,
+                  ``"vice president"``) match **0** rows.
+                - ``person_locations`` / ``organization_locations`` (list[str]):
+                  person / company location. Accepts a country name, a 2-letter
+                  country code (``"US"`` == ``"United States"``), or
+                  ``"City, State, Country"``.
+                - ``organization_num_employees_ranges`` (list[str]): company-size
+                  buckets as **"min,max"** strings, e.g. ``["1,10"]``,
+                  ``["1000,5000"]``. A dash (``"1-10"``) is **silently ignored**.
+                - ``q_organization_domains_list`` (list[str]): company domains,
+                  e.g. ``["acme.com"]``. ``organization_ids`` (list[str]): Apollo org IDs.
+                - ``contact_email_status`` (list[str]): ``verified``, ``unverified``,
+                  ``likely to engage``, ``unavailable``.
+                - ``revenue_range`` / ``organization_num_jobs_range`` (dict):
+                  ``{"min": int, "max": int}``.
+                - ``organization_job_posted_at_range`` (dict): ``{"min": "YYYY-MM-DD",
+                  "max": "YYYY-MM-DD"}``.
+                - ``currently_using_any_of_technology_uids`` /
+                  ``currently_using_all_of_technology_uids`` /
+                  ``currently_not_using_any_of_technology_uids`` (list[str]): tech
+                  UIDs, e.g. ``["salesforce"]``.
+                - ``q_organization_job_titles`` (list[str]),
+                  ``organization_job_locations`` (list[str]).
+                - ``page`` / ``per_page`` (int): pagination (this method has no
+                  explicit page/limit args — pass them as filters).
 
         Returns:
-            Search results dictionary
+            Raw Apollo response dict: ``people`` (list) and ``total_entries`` (int).
         """
-        return await self._post("/mixed_people/search", filters)
+        _validate_search_filters(filters, PEOPLE_SEARCH_FILTERS, "people", strict=True)
+        return await self._post("/mixed_people/api_search", filters)
 
     # ========================================================================
     # NOTES
@@ -625,6 +839,7 @@ class ApolloClient:
         Returns:
             Paginated response with Note items (content converted to Markdown)
         """
+        _validate_search_filters(filters, NOTE_SEARCH_FILTERS, "note", strict=False)
         data = {"page": page, "per_page": min(limit, 100), **filters}
         result = await self._post("/notes/search", data)
 
@@ -710,6 +925,7 @@ class ApolloClient:
         Returns:
             Paginated response with Call items
         """
+        _validate_search_filters(filters, CALL_SEARCH_FILTERS, "call", strict=False)
         data = {"page": page, "per_page": min(limit, 100), **filters}
         result = await self._post("/phone_calls/search", data)
 
@@ -749,6 +965,7 @@ class ApolloClient:
         Returns:
             Paginated response with specific Task subclass items
         """
+        _validate_search_filters(filters, TASK_SEARCH_FILTERS, "task", strict=False)
         data: dict[str, Any] = {"page": page, "per_page": min(limit, 100), **filters}
         if task_type_cds is not None:
             data["task_type_cds"] = task_type_cds
@@ -792,6 +1009,7 @@ class ApolloClient:
         Returns:
             Paginated response with Email items
         """
+        _validate_search_filters(filters, EMAIL_SEARCH_FILTERS, "email", strict=False)
         data = {"page": page, "per_page": min(limit, 100), **filters}
         result = await self._post("/emailer_messages/search", data)
 
@@ -1106,29 +1324,20 @@ class ApolloClient:
         )
         return EmailerMessage.model_validate(result.get("emailer_message", result))
 
-    async def list_contact_calls(self, contact_id: str) -> list[Call]:
-        """List calls for a contact.
-
-        Args:
-            contact_id: Contact ID
-
-        Returns:
-            List of Call models
-        """
-        result = await self._get(f"/contacts/{contact_id}/calls")
-        return [Call.model_validate(c) for c in result.get("calls", [])]
-
     async def list_contact_tasks(self, contact_id: str) -> list[Task]:
         """List tasks for a contact.
 
+        Apollo removed the ``/contacts/{id}/tasks`` sub-resource route (now 404),
+        so this filters the tasks search by ``contact_ids`` instead.
+
         Args:
             contact_id: Contact ID
 
         Returns:
             List of Task subclasses matching each task's type
         """
-        result = await self._get(f"/contacts/{contact_id}/tasks")
-        return [resolve_task(t) for t in result.get("tasks", [])]
+        result = await self.search_tasks(contact_ids=[contact_id])
+        return result.items
 
     # ========================================================================
     # CALENDAR EVENTS
@@ -1147,6 +1356,9 @@ class ApolloClient:
         Returns:
             Paginated response with CalendarEvent items
         """
+        _validate_search_filters(
+            filters, CALENDAR_EVENT_SEARCH_FILTERS, "calendar event", strict=False
+        )
         data = {"page": page, "per_page": min(limit, 100), **filters}
         result = await self._post("/calendar_events/search", data)
 
@@ -1176,6 +1388,7 @@ class ApolloClient:
         Returns:
             Paginated response with Conversation items
         """
+        _validate_search_filters(filters, CONVERSATION_SEARCH_FILTERS, "conversation", strict=False)
         data = {"page": page, "per_page": min(limit, 25), **filters}
         result = await self._post("/conversations/search", data)
 
@@ -1205,29 +1418,25 @@ class ApolloClient:
     # NEWS & JOBS
     # ========================================================================
 
-    async def list_account_news(self, account_id: str) -> list[dict]:
-        """List news articles for an account.
-
-        Args:
-            account_id: Account ID
-
-        Returns:
-            List of news article dictionaries
-        """
-        result = await self._get(f"/accounts/{account_id}/news")
-        return result.get("news", [])
-
     async def list_account_jobs(self, account_id: str) -> list[dict]:
         """List job postings for an account.
 
+        Apollo removed the ``/accounts/{id}/job_postings`` sub-resource route (now
+        404). Job postings live on the linked *organization*, so this resolves the
+        account's ``organization_id`` and reads ``/organizations/{org_id}/job_postings``.
+
         Args:
-            account_id: Account ID
+            account_id: CRM account ID (its linked organization holds the postings).
 
         Returns:
-            List of job posting dictionaries
+            List of job posting dictionaries (empty if the account has no linked
+            organization).
         """
-        result = await self._get(f"/accounts/{account_id}/job_postings")
-        return result.get("job_postings", [])
+        account = await self.get_account(account_id)
+        if not account.organization_id:
+            return []
+        result = await self._get(f"/organizations/{account.organization_id}/job_postings")
+        return result.get("organization_job_postings", [])
 
     # ========================================================================
     # USAGE & RATE LIMITS

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

@@ -251,6 +251,107 @@ 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"
+
+
+# --- Generalized search-filter validation (strict raise vs lenient warn) ------
+
+
+@pytest.mark.parametrize(
+    "method,good_filter",
+    [
+        ("search_contacts", {"q_keywords": "x"}),
+        ("search_deals", {"opportunity_stage_ids": ["s1"]}),
+        ("search_people", {"person_titles": ["CEO"]}),
+    ],
+)
+async def test_strict_search_methods_reject_unknown_filter(client, method, good_filter):
+    """contacts/deals/people raise on an unknown key (like accounts) and never call Apollo."""
+    client._client.request.return_value = _make_response({})
+    with pytest.raises(ValueError, match=r"Unknown .* search filter"):
+        await getattr(client, method)(query="typo")
+    client._client.request.assert_not_called()
+
+    # A documented filter passes validation and reaches Apollo.
+    await getattr(client, method)(**good_filter)
+    assert client._client.request.called
+
+
+async def test_search_people_allows_page_and_per_page(client: ApolloClient):
+    """search_people has no explicit page/limit, so page/per_page are valid filters."""
+    client._client.request.return_value = _make_response({"people": [], "contacts": []})
+    await client.search_people(q_keywords="x", page=2, per_page=50)
+    assert client._client.request.call_args[1]["json"]["per_page"] == 50
+
+
+@pytest.mark.parametrize(
+    "method,endpoint_key",
+    [
+        ("search_notes", "notes"),
+        ("search_calls", "phone_calls"),
+        ("search_tasks", "tasks"),
+        ("search_emails", "emailer_messages"),
+        ("search_conversations", "conversations"),
+        ("search_calendar_events", "calendar_events"),
+    ],
+)
+async def test_lenient_search_methods_warn_but_still_send(client, method, endpoint_key, caplog):
+    """Activity endpoints log a warning on an unknown key but still send the request."""
+    client._client.request.return_value = _make_response({endpoint_key: [], "pagination": {}})
+
+    with caplog.at_level("WARNING", logger="qodev_apollo_api.client"):
+        await getattr(client, method)(bogus_filter="x")
+
+    assert any("Unknown" in r.message and "search filter" in r.message for r in caplog.records)
+    # Lenient: the request is still sent (unknown key forwarded, not blocked).
+    assert client._client.request.called
+    assert client._client.request.call_args[1]["json"]["bogus_filter"] == "x"
+
+
+async def test_lenient_search_method_no_warn_on_known_filter(client, caplog):
+    """A known activity filter passes without a warning."""
+    client._client.request.return_value = _make_response({"notes": [], "pagination": {}})
+    with caplog.at_level("WARNING", logger="qodev_apollo_api.client"):
+        await client.search_notes(contact_ids=["c1"])
+    assert not any("Unknown" in r.message for r in caplog.records)
+
+
 async def test_search_deals(client: ApolloClient):
     """Test POST /opportunities/search returns PaginatedResponse[Deal]."""
     client._client.request.return_value = _make_response(
@@ -267,6 +368,20 @@ async def test_search_deals(client: ApolloClient):
     assert isinstance(result.items[0], Deal)
     assert result.items[0].name == "Big Deal"
 
+
+async def test_search_deals_name_filter_is_q_opportunity_name(client: ApolloClient):
+    """Deal name search is ``q_opportunity_name``; ``q_keywords`` is silently ignored
+    by Apollo for /opportunities/search, so it's not an accepted filter (raises)."""
+    client._client.request.return_value = _make_response(
+        {"opportunities": [], "pagination": {"total_entries": 0}}
+    )
+
+    await client.search_deals(q_opportunity_name="NORRIQ")
+    assert client._client.request.call_args[1]["json"]["q_opportunity_name"] == "NORRIQ"
+
+    with pytest.raises(ValueError, match="Unknown deal search filter"):
+        await client.search_deals(q_keywords="NORRIQ")
+
     assert client._client.request.call_args[0] == ("POST", "/opportunities/search")
 
 
@@ -533,6 +648,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 +795,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 +815,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):
@@ -703,24 +871,14 @@ async def test_get_contact_stages(client: ApolloClient):
     client._client.request.assert_called_once_with("GET", "/contact_stages")
 
 
-async def test_list_contact_calls(client: ApolloClient):
-    """Test GET /contacts/{id}/calls returns list[Call]."""
-    client._client.request.return_value = _make_response(
-        {"calls": [{"id": "call1"}, {"id": "call2"}]}
-    )
-
-    result = await client.list_contact_calls("c1")
-
-    assert isinstance(result, list)
-    assert len(result) == 2
-    assert all(isinstance(c, Call) for c in result)
-    client._client.request.assert_called_once_with("GET", "/contacts/c1/calls")
-
-
 async def test_list_contact_tasks(client: ApolloClient):
-    """Test GET /contacts/{id}/tasks returns list[Task]."""
+    """list_contact_tasks filters the tasks search by contact_ids (the old
+    /contacts/{id}/tasks route was removed by Apollo — now 404)."""
     client._client.request.return_value = _make_response(
-        {"tasks": [{"id": "t1", "type": "call"}, {"id": "t2", "type": "contact_action_item"}]}
+        {
+            "tasks": [{"id": "t1", "type": "call"}, {"id": "t2", "type": "contact_action_item"}],
+            "pagination": {"total_entries": 2},
+        }
     )
 
     result = await client.list_contact_tasks("c1")
@@ -728,35 +886,40 @@ async def test_list_contact_tasks(client: ApolloClient):
     assert isinstance(result, list)
     assert len(result) == 2
     assert all(isinstance(t, BaseTask) for t in result)
-    client._client.request.assert_called_once_with("GET", "/contacts/c1/tasks")
+    call_args = client._client.request.call_args
+    assert call_args[0] == ("POST", "/tasks/search")
+    assert call_args[1]["json"]["contact_ids"] == ["c1"]
 
 
-async def test_list_account_news(client: ApolloClient):
-    """Test GET /accounts/{id}/news returns list[dict]."""
-    client._client.request.return_value = _make_response(
-        {"news": [{"title": "Big news"}, {"title": "Small news"}]}
-    )
+async def test_list_account_jobs(client: ApolloClient):
+    """list_account_jobs resolves the account's organization_id then reads
+    /organizations/{org_id}/job_postings (the old /accounts/{id}/job_postings
+    route was removed by Apollo — now 404)."""
+    client._client.request.side_effect = [
+        _make_response({"account": {"id": "a1", "organization_id": "org9"}}),
+        _make_response(
+            {"organization_job_postings": [{"title": "Engineer"}, {"title": "Designer"}]}
+        ),
+    ]
 
-    result = await client.list_account_news("a1")
+    result = await client.list_account_jobs("a1")
 
-    assert isinstance(result, list)
-    assert len(result) == 2
-    assert result[0]["title"] == "Big news"
-    client._client.request.assert_called_once_with("GET", "/accounts/a1/news")
+    assert [j["title"] for j in result] == ["Engineer", "Designer"]
+    assert client._client.request.call_args_list[0][0] == ("GET", "/accounts/a1")
+    assert client._client.request.call_args_list[1][0] == (
+        "GET",
+        "/organizations/org9/job_postings",
+    )
 
 
-async def test_list_account_jobs(client: ApolloClient):
-    """Test GET /accounts/{id}/job_postings returns list[dict]."""
-    client._client.request.return_value = _make_response(
-        {"job_postings": [{"title": "Engineer"}, {"title": "Designer"}]}
-    )
+async def test_list_account_jobs_no_organization(client: ApolloClient):
+    """An account with no linked organization returns [] without a second call."""
+    client._client.request.return_value = _make_response({"account": {"id": "a1"}})
 
     result = await client.list_account_jobs("a1")
 
-    assert isinstance(result, list)
-    assert len(result) == 2
-    assert result[0]["title"] == "Engineer"
-    client._client.request.assert_called_once_with("GET", "/accounts/a1/job_postings")
+    assert result == []
+    client._client.request.assert_called_once_with("GET", "/accounts/a1")
 
 
 # ============================================================================
@@ -1197,17 +1360,17 @@ async def test_enrich_person(client: ApolloClient):
 
 
 async def test_search_people(client: ApolloClient):
-    """Test POST /mixed_people/search."""
+    """Test POST /mixed_people/api_search (the old /mixed_people/search is deprecated)."""
     client._client.request.return_value = _make_response(
-        {"people": [{"id": "p1", "name": "Alice"}]}
+        {"people": [{"id": "p1", "first_name": "Alice"}], "total_entries": 1}
     )
 
     result = await client.search_people(q_keywords="Alice")
 
-    assert result == {"people": [{"id": "p1", "name": "Alice"}]}
+    assert result == {"people": [{"id": "p1", "first_name": "Alice"}], "total_entries": 1}
 
     call_args = client._client.request.call_args
-    assert call_args[0] == ("POST", "/mixed_people/search")
+    assert call_args[0] == ("POST", "/mixed_people/api_search")
     payload = call_args[1]["json"]
     assert payload["q_keywords"] == "Alice"
 
@@ -1361,82 +1524,38 @@ async def test_find_by_linkedin_url_step2_ambiguous(client: ApolloClient):
     assert result is None
 
 
-async def test_find_by_linkedin_url_step3_create(client: ApolloClient):
-    """Test people DB match → creates contact."""
+async def test_find_by_linkedin_url_create_if_missing_is_noop(client: ApolloClient, caplog):
+    """create_if_missing no longer auto-creates: Apollo's api_search returns teaser
+    data (no linkedin_url), so the former Step 3 is gone. It warns and returns None,
+    and never POSTs to /contacts."""
     step1_response = _make_response({"contacts": [], "pagination": {"total_entries": 0}})
-    # Step 2: Name search — no URL match
     step2_response = _make_response({"contacts": [], "pagination": {"total_entries": 0}})
-    # Step 3: People DB search
-    step3_response = _make_response(
-        {
-            "people": [
-                {
-                    "id": "person_1",
-                    "first_name": "Alice",
-                    "last_name": "Smith",
-                    "linkedin_url": "https://www.linkedin.com/in/alice",
-                    "title": "CTO",
-                }
-            ]
-        }
-    )
-    # Step 3: Create contact
-    step4_response = _make_response(
-        {"contact": {"id": "c_new", "first_name": "Alice", "last_name": "Smith"}}
-    )
-    client._client.request.side_effect = [
-        step1_response,
-        step2_response,
-        step3_response,
-        step4_response,
-    ]
-
-    result = await client.find_contact_by_linkedin_url(
-        "https://www.linkedin.com/in/alice",
-        person_name="Alice Smith",
-        create_if_missing=True,
-        contact_stage_id="stage_1",
-    )
+    client._client.request.side_effect = [step1_response, step2_response]
 
-    assert result == "c_new"
+    with caplog.at_level("WARNING", logger="qodev_apollo_api.client"):
+        result = await client.find_contact_by_linkedin_url(
+            "https://www.linkedin.com/in/alice",
+            person_name="Alice Smith",
+            create_if_missing=True,
+            contact_stage_id="stage_1",
+        )
 
-    # Verify create_contact was called with correct data
-    create_call = client._client.request.call_args_list[3]
-    assert create_call[0] == ("POST", "/contacts")
-    payload = create_call[1]["json"]
-    assert payload["first_name"] == "Alice"
-    assert payload["last_name"] == "Smith"
-    assert payload["person_id"] == "person_1"
-    assert payload["contact_stage_id"] == "stage_1"
+    assert result is None
+    # Only the two lookup searches ran — no people-search POST, no contact creation.
+    assert client._client.request.call_count == 2
+    assert all(call[0][1] != "/contacts" for call in client._client.request.call_args_list)
+    assert any("create_if_missing is no longer supported" in r.message for r in caplog.records)
 
 
 async def test_find_by_linkedin_url_not_found(client: ApolloClient):
-    """Test all three steps fail → None."""
+    """Both existing-contact lookups fail → None."""
     step1_response = _make_response({"contacts": [], "pagination": {"total_entries": 0}})
     step2_response = _make_response({"contacts": [], "pagination": {"total_entries": 0}})
-    # Step 3: People DB — no URL match
-    step3_response = _make_response(
-        {
-            "people": [
-                {
-                    "id": "person_1",
-                    "first_name": "Bob",
-                    "last_name": "Jones",
-                    "linkedin_url": "https://www.linkedin.com/in/bob",
-                }
-            ]
-        }
-    )
-    client._client.request.side_effect = [
-        step1_response,
-        step2_response,
-        step3_response,
-    ]
+    client._client.request.side_effect = [step1_response, step2_response]
 
     result = await client.find_contact_by_linkedin_url(
         "https://www.linkedin.com/in/alice",
         person_name="Alice Smith",
-        create_if_missing=True,
     )
 
     assert result is None

{qodev_apollo_api-0.3.2 → qodev_apollo_api-0.5.0}/uv.lock

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