Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

44.4 KB
Raw Blame
"""
Tests for API Tool
"""

import json
from typing import Any
from urllib.parse import parse_qs, urlparse

import httpx
import pytest

from xagent.core.tools.adapters.vibe.api_tool import APICallArgs, APITool
from xagent.core.tools.core.api_tool import (
    APIClientCore,
    _hostname_matches_connector_domain,
    _sanitize_final_url,
    call_api,
    has_auth_credentials,
    match_known_connector_domain,
    match_known_connector_url,
)


def _single_value_query_args(url: str) -> dict[str, str]:
    return {key: values[-1] for key, values in parse_qs(urlparse(url).query).items()}


class TestMatchKnownConnectorDomain:
    def test_matches_exact_host(self):
        assert match_known_connector_domain("api.github.com") == "GitHub"

    def test_matches_subdomain_of_a_multi_tenant_service(self):
        assert match_known_connector_domain("acme.myshopify.com") == "Shopify"
        assert match_known_connector_domain("acme.zendesk.com") == "Zendesk"

    def test_matches_salesforce_and_xero(self):
        """Both are live, registered OAuth connectors that were previously
        missing from the domain list entirely, despite Salesforce being
        named explicitly in the code's own comment."""
        assert match_known_connector_domain("acme.my.salesforce.com") == "Salesforce"
        assert match_known_connector_domain("login.salesforce.com") == "Salesforce"
        assert match_known_connector_domain("api.xero.com") == "Xero"

    def test_matches_specific_google_product_hosts(self):
        assert match_known_connector_domain("gmail.googleapis.com") == "Gmail"
        assert match_known_connector_domain("googleads.googleapis.com") == "Google Ads"
        assert (
            match_known_connector_domain("analyticsdata.googleapis.com")
            == "Google Analytics"
        )
        assert (
            match_known_connector_domain("searchconsole.googleapis.com")
            == "Google Search Console"
        )

    def test_does_not_match_an_uncovered_googleapis_subdomain(self):
        """Regression: a blanket "googleapis.com" entry used to match every
        Google Cloud API subdomain, including ones with no xagent connector
        at all (Cloud Storage, BigQuery, Translate, ...) - blocking them
        with a "use the dedicated connector" message that was actively
        wrong since no such connector exists for that API."""
        assert match_known_connector_domain("storage.googleapis.com") is None
        assert match_known_connector_domain("bigquery.googleapis.com") is None

    def test_does_not_match_slack_incoming_webhook_subdomain(self):
        """hooks.slack.com (incoming webhooks) is a different,
        self-authenticating product from the credentialed Slack Web API at
        slack.com/api - the guard must not touch it even though it shares
        the slack.com suffix."""
        assert match_known_connector_domain("slack.com") == "Slack"
        assert match_known_connector_domain("hooks.slack.com") is None
        assert match_known_connector_domain("tenant.hooks.slack.com") is None

    def test_matches_search_console_on_shared_google_host_by_path(self):
        assert (
            match_known_connector_url(
                "https://www.googleapis.com/webmasters/v3/sites/example.com"
            )
            == "Google Search Console"
        )
        assert match_known_connector_url("https://www.googleapis.com/drive/v3") is None

    def test_is_case_insensitive(self):
        assert match_known_connector_domain("API.HUBAPI.COM") == "HubSpot"

    def test_does_not_match_an_unrelated_domain(self):
        assert match_known_connector_domain("httpbin.org") is None

    def test_does_not_match_a_lookalike_suffix(self):
        """ "notzendesk.com" shares a suffix with "zendesk.com" as a raw
        string but is not "*.zendesk.com" - the dot-boundary check in
        _hostname_matches_connector_domain must reject it, not just do a
        substring/endswith check on the bare strings."""
        assert match_known_connector_domain("notzendesk.com") is None

    def test_does_not_match_domain_as_a_trailing_path_look_alike(self):
        """A hostname that merely contains the target domain as a substring
        elsewhere (not as its own suffix) must not match."""
        assert (
            _hostname_matches_connector_domain(
                "zendesk.com.evil.example", "zendesk.com"
            )
            is False
        )

    def test_real_connector_base_urls_are_covered(self):
        """Keep the diagnostic inventory tied to connector-owned constants,
        including Search Console's shared-host Webmasters endpoint."""
        from xagent.web.tools.mcp.chartmogul import API_BASE_URL as chartmogul
        from xagent.web.tools.mcp.employment_hero import (
            EMPLOYMENT_HERO_BASE_URL as employment_hero,
        )
        from xagent.web.tools.mcp.github import GITHUB_BASE_URL as github
        from xagent.web.tools.mcp.google_ads import GOOGLE_ADS_BASE_URL as google_ads
        from xagent.web.tools.mcp.google_analytics import (
            ADMIN_API_BASE_URL as analytics_admin,
        )
        from xagent.web.tools.mcp.google_analytics import (
            DATA_API_BASE_URL as analytics_data,
        )
        from xagent.web.tools.mcp.google_search_console import (
            SEARCH_CONSOLE_API_BASE_URL as search_console,
        )
        from xagent.web.tools.mcp.google_search_console import (
            WEBMASTERS_API_BASE_URL as webmasters,
        )
        from xagent.web.tools.mcp.hubspot import HUBSPOT_BASE_URL as hubspot
        from xagent.web.tools.mcp.intercom import INTERCOM_BASE_URL as intercom
        from xagent.web.tools.mcp.meta_graph import GRAPH_BASE_URL as meta
        from xagent.web.tools.mcp.myob import MYOB_BASE_URL as myob
        from xagent.web.tools.mcp.onedrive import GRAPH_BASE_URL as microsoft_graph
        from xagent.web.tools.mcp.slack import SLACK_BASE_URL as slack
        from xagent.web.tools.mcp.stripe import BASE_URL as stripe
        from xagent.web.tools.mcp.zoom import ZOOM_BASE_URL as zoom

        expected = {
            chartmogul: "ChartMogul",
            employment_hero: "Employment Hero",
            github: "GitHub",
            google_ads: "Google Ads",
            analytics_admin: "Google Analytics",
            analytics_data: "Google Analytics",
            search_console: "Google Search Console",
            webmasters: "Google Search Console",
            hubspot: "HubSpot",
            intercom: "Intercom",
            meta: "Meta Graph (Facebook/Instagram)",
            myob: "MYOB",
            microsoft_graph: "Microsoft Graph (Outlook/OneDrive/Teams)",
            slack: "Slack",
            stripe: "Stripe",
            zoom: "Zoom",
        }
        for url, label in expected.items():
            assert match_known_connector_url(url) == label


class TestHasAuthCredentials:
    def test_true_for_authorization_header(self):
        assert has_auth_credentials(
            "https://api.hubapi.com/x", {"Authorization": "Bearer tok"}
        )

    def test_true_for_service_specific_credential_header(self):
        """Not every connector's direct-call convention uses the literal
        "Authorization" header name - matching must key off any header
        whose name looks credential-shaped, not an exact-name allowlist."""
        assert has_auth_credentials(
            "https://acme.myshopify.com/x",
            {"X-Shopify-Access-Token": "shpat_abc"},
        )

    def test_true_for_auth_query_param_in_final_request_url(self):
        assert has_auth_credentials("https://maps.googleapis.com/x?key=AIza123", None)

    def test_true_for_hyphenated_api_key_query_param(self):
        """The header-marker list already recognized both "api-key" and
        "apikey" spellings; the query-param list was missing the hyphenated
        one, so a real credential passed as ?api-key=... was incorrectly
        treated as no-credential-attached."""
        assert has_auth_credentials("https://api.hubapi.com/x?api-key=secret", None)

    def test_true_for_basic_auth_userinfo_in_url(self):
        """HTTP Basic-Auth credentials embedded directly in the URL
        (user:pass@host) are a legitimate, already-authenticated call shape
        that headers/query-param checks alone can't see."""
        assert has_auth_credentials("https://user:[email protected]/x", None)

    def test_false_when_nothing_looks_like_a_credential(self):
        assert not has_auth_credentials(
            "https://api.hubapi.com/x?limit=10",
            {"Content-Type": "application/json"},
        )

    def test_false_for_no_arguments_at_all(self):
        assert not has_auth_credentials("https://api.hubapi.com/x", None)

    def test_false_for_blank_header_value(self):
        """A header whose NAME looks credential-shaped but whose VALUE is
        blank carries nothing real - e.g. {"Authorization": ""}, which a
        caller could send by accident (an unresolved template variable,
        say). Treating the name alone as proof of a credential would skip
        the connector hint on a 401 caused by exactly that missing value."""
        assert not has_auth_credentials(
            "https://api.hubapi.com/x", {"Authorization": ""}
        )
        assert not has_auth_credentials("https://api.hubapi.com/x?api_key=", None)

    def test_false_for_authority_header(self):
        """ "authority" (the HTTP/2 pseudo-header carrying the target host,
        set automatically by many HTTP/2 clients and proxies - not a
        credential) must not be treated as a credential."""
        assert not has_auth_credentials(
            "https://api.hubapi.com/x",
            {"Content-Type": "application/json", "authority": "api.hubapi.com"},
        )

    def test_false_for_other_headers_merely_containing_auth_as_a_substring(self):
        """Regression: the marker list used to include the bare "auth" and
        "signature" substrings, which matched non-credential headers like
        "X-Author", "X-OAuth-Client-Id" (a public client id, not a secret),
        and GitHub's outbound "X-Hub-Signature-256" webhook-verification
        header - silently treating an actually-unauthenticated call as
        credentialed and defeating the guard entirely."""
        assert not has_auth_credentials(
            "https://api.github.com/x",
            {"X-Author": "[email protected]"},
        )
        assert not has_auth_credentials(
            "https://api.github.com/x",
            {"X-OAuth-Client-Id": "public-id"},
        )
        assert not has_auth_credentials(
            "https://api.github.com/x",
            {"X-Hub-Signature-256": "sha256=abc"},
        )

    def test_ignores_non_string_header_keys(self):
        assert not has_auth_credentials("https://api.hubapi.com/x", {1: "x"})  # type: ignore[dict-item]


class TestSanitizeFinalUrl:
    """Regression: final_url reports the real post-redirect response URL,
    but the raw URL can itself carry a credential - an api_key_query
    auth_token merged into the query string, or Basic-Auth userinfo a
    caller embedded directly in the URL. Only the host identifies which
    connector answered, so everything else must be stripped before this
    value leaves _make_request."""

    def test_strips_query_string_credential(self):
        assert (
            _sanitize_final_url(
                httpx.URL("https://api.hubapi.com/crm/v3/deals?api_key=secret")
            )
            == "https://api.hubapi.com/crm/v3/deals"
        )

    def test_strips_basic_auth_userinfo(self):
        assert (
            _sanitize_final_url(
                httpx.URL("https://user:[email protected]/crm/v3/deals")
            )
            == "https://api.hubapi.com/crm/v3/deals"
        )

    def test_strips_both_userinfo_and_query_credential(self):
        assert (
            _sanitize_final_url(
                httpx.URL("https://user:[email protected]/path?api_key=secret")
            )
            == "https://example.com/path"
        )

    def test_preserves_port(self):
        assert (
            _sanitize_final_url(httpx.URL("https://example.com:8443/path?key=secret"))
            == "https://example.com:8443/path"
        )

    def test_no_op_for_a_url_with_nothing_to_strip(self):
        assert (
            _sanitize_final_url(httpx.URL("https://api.hubapi.com/crm/v3/deals"))
            == "https://api.hubapi.com/crm/v3/deals"
        )

    def test_ipv6_host_stays_bracketed(self):
        """Regression: a hand-rolled string-based implementation (urlparse
        + reassembling "host:port" by hand) drops the brackets an IPv6
        literal needs, producing a URL later code can't even re-parse
        (urlparse("https://::1:8443/x").hostname is None). Using
        httpx.URL.copy_with keeps the URL in one already-bracket-aware
        type throughout."""
        assert (
            _sanitize_final_url(httpx.URL("https://[::1]:8443/path?api_key=secret"))
            == "https://[::1]:8443/path"
        )


@pytest.fixture
def mock_httpbin(monkeypatch: pytest.MonkeyPatch) -> None:
    async def mock_make_request(
        self: APIClientCore,
        *,
        url: str,
        method: str,
        headers: dict[str, str],
        params: dict[str, Any] | None,
        data: str | bytes | None,
        timeout: int,
        proxy_url: str | None,
        allow_redirects: bool,
    ) -> dict[str, Any]:
        parsed = urlparse(url)
        path = parsed.path
        body: dict[str, Any]
        status_code = 200

        if path == "/get":
            body = {"args": _single_value_query_args(url)}
        elif path == "/post":
            parsed_data = json.loads(
                data.decode() if isinstance(data, bytes) else data or "{}"
            )
            body = {"json": parsed_data}
        elif path == "/bearer":
            token = headers.get("Authorization", "").removeprefix("Bearer ")
            body = {"authenticated": bool(token), "token": token}
        elif path == "/headers":
            body = {"headers": headers}
        elif path.startswith("/status/"):
            status_code = int(path.removeprefix("/status/"))
            body = {}
        else:
            status_code = 404
            body = {}

        # A "__redirected_to__" query param lets a test simulate httpx
        # having followed a cross-host redirect before landing on this
        # response - the real _make_request reports response.url (the
        # final, post-redirect URL) here, which can differ from the
        # request's starting url.
        final_url = _single_value_query_args(url).get("__redirected_to__", url)

        # Mirror httpx's own redirect behavior (see
        # httpx.Client._redirect_headers) closely enough for these tests:
        # Authorization is dropped when the redirect crosses hosts, and a
        # redirect target's own query string (not the original request's)
        # is what the final request carries - final_url above already is
        # that target URL, so no extra query handling is needed here.
        final_headers = dict(headers)
        if urlparse(final_url).hostname != parsed.hostname:
            final_headers.pop("Authorization", None)
        final_request_has_credential = has_auth_credentials(final_url, final_headers)

        return {
            "success": 200 <= status_code < 300,
            "status_code": status_code,
            "headers": {"content-type": "application/json"},
            "body": body,
            "error": None if 200 <= status_code < 300 else f"HTTP {status_code}",
            "final_url": final_url,
            "final_request_has_credential": final_request_has_credential,
        }

    monkeypatch.setattr(APIClientCore, "_make_request", mock_make_request)


class TestAPIClientCore:
    """Test core API client functionality"""

    @pytest.mark.asyncio
    async def test_get_request(self, mock_httpbin: None):
        """Test basic GET request"""
        client = APIClientCore()
        result = await client.call_api(
            url="https://httpbin.org/get",
            method="GET",
            params={"test": "value"},
        )

        assert result["success"] is True
        assert result["status_code"] == 200
        assert "body" in result
        assert result["body"]["args"]["test"] == "value"

    @pytest.mark.asyncio
    async def test_post_json_request(self, mock_httpbin: None):
        """Test POST request with JSON body"""
        client = APIClientCore()
        result = await client.call_api(
            url="https://httpbin.org/post",
            method="POST",
            body={"name": "test", "value": 123},
        )

        assert result["success"] is True
        assert result["status_code"] == 200
        assert result["body"]["json"]["name"] == "test"
        assert result["body"]["json"]["value"] == 123

    @pytest.mark.asyncio
    async def test_bearer_auth(self, mock_httpbin: None):
        """Test Bearer token authentication"""
        client = APIClientCore()
        result = await client.call_api(
            url="https://httpbin.org/bearer",
            method="GET",
            auth_type="bearer",
            auth_token="test-token-123",
        )

        assert result["success"] is True
        assert result["status_code"] == 200
        assert result["body"]["authenticated"] is True
        assert result["body"]["token"] == "test-token-123"

    @pytest.mark.asyncio
    async def test_api_key_query_auth(self, mock_httpbin: None):
        """Test API key in query parameters using convenience function"""
        result = await call_api(
            url="https://httpbin.org/get",
            method="GET",
            auth_type="api_key_query",
            auth_token="test-key-123",
        )

        assert result["success"] is True
        assert result["status_code"] == 200
        # Verify the api_key was added to query params
        assert result["body"]["args"]["api_key"] == "test-key-123"

    @pytest.mark.asyncio
    async def test_api_key_query_custom_param(self, mock_httpbin: None):
        """Test API key in custom query parameter"""
        result = await call_api(
            url="https://httpbin.org/get",
            method="GET",
            auth_type="api_key_query",
            auth_token="test-key-123",
            api_key_param="token",
        )

        assert result["success"] is True
        assert result["status_code"] == 200
        # Verify the custom param was added to query params
        assert result["body"]["args"]["token"] == "test-key-123"

    @pytest.mark.asyncio
    async def test_api_key_query_auth_type_is_case_insensitive(
        self, mock_httpbin: None
    ):
        """Regression: this check used to be an exact-case string compare,
        unlike _prepare_headers' auth_type.lower() handling of bearer/
        basic/api_key just below it and has_auth_credentials' own lower()
        call - auth_type="API_KEY_QUERY" (or any non-lowercase spelling)
        would silently attach no credential here while has_auth_credentials
        reported one was present, suppressing the connector hint for
        exactly the resulting unauthenticated 401/403."""
        result = await call_api(
            url="https://httpbin.org/get",
            method="GET",
            auth_type="API_KEY_QUERY",
            auth_token="test-key-123",
        )

        assert result["success"] is True
        assert result["body"]["args"]["api_key"] == "test-key-123"

    @pytest.mark.asyncio
    async def test_custom_headers(self, mock_httpbin: None):
        """Test custom headers"""
        client = APIClientCore()
        result = await client.call_api(
            url="https://httpbin.org/headers",
            method="GET",
            headers={"X-Custom-Header": "custom-value"},
        )

        assert result["success"] is True
        assert result["status_code"] == 200
        assert "X-Custom-Header" in result["body"]["headers"]

    @pytest.mark.asyncio
    async def test_invalid_url(self):
        """Test invalid URL handling"""
        client = APIClientCore()
        result = await client.call_api(url="not-a-valid-url")

        assert result["success"] is False
        assert "error" in result

    @pytest.mark.asyncio
    async def test_url_httpx_rejects_after_merging_params_does_not_raise(self):
        """Regression: _is_valid_url's cheap urlparse-based check (scheme +
        non-empty netloc) lets through a URL httpx.URL() itself later
        rejects (e.g. a non-numeric port) - only reachable once query
        params get merged into the URL, since a request with none never
        reaches that merge step. That merge used to run outside the retry
        loop's try/except, so it raised straight out of call_api instead of
        returning the documented dict shape."""
        client = APIClientCore()
        result = await client.call_api(
            url="http://example.com:abc/path", params={"q": "1"}
        )

        assert result["success"] is False
        assert result["status_code"] == 0
        assert isinstance(result["error"], str)

    @pytest.mark.asyncio
    async def test_retry_mechanism(self, monkeypatch: pytest.MonkeyPatch):
        """Network exceptions are retried and the successful third call is returned."""
        client = APIClientCore(default_retry_count=2)
        call_count = 0

        async def flaky_request(**kwargs):
            nonlocal call_count
            call_count += 1
            if call_count < 3:
                raise httpx.ConnectError("temporary failure")
            return {
                "success": True,
                "status_code": 200,
                "headers": {},
                "body": {"ok": True},
                "error": None,
            }

        monkeypatch.setattr(client, "_make_request", flaky_request)
        result = await client.call_api(url="https://example.com/data")

        assert call_count == 3
        assert result["success"] is True
        assert result["status_code"] == 200


@pytest.fixture
def mock_transport(monkeypatch: pytest.MonkeyPatch):
    """Injects an httpx.MockTransport into every httpx.AsyncClient built
    inside _make_request, exercising the REAL request/response path
    (unlike mock_httpbin, which monkeypatches _make_request itself away) -
    needed to verify behavior that depends on the real httpx.Response,
    like final_url/final_request_has_credential gating below."""

    def _install(handler):
        original_init = httpx.AsyncClient.__init__

        def patched_init(self, *args, **kwargs):
            kwargs["transport"] = httpx.MockTransport(handler)
            original_init(self, *args, **kwargs)

        monkeypatch.setattr(httpx.AsyncClient, "__init__", patched_init)

    return _install


class TestFinalUrlCredentialGating:
    """Regression: final_url and final_request_has_credential are only
    ever read by the adapter's connector-domain hint, which only fires for
    a 401/403 (see api_tool.py's run_json_async) - _make_request should
    skip computing them entirely for any other status, not just skip
    using them once computed."""

    @pytest.mark.asyncio
    async def test_not_computed_for_a_2xx_response(self, mock_transport):
        mock_transport(lambda request: httpx.Response(200, json={"ok": True}))

        result = await APIClientCore().call_api(url="https://example.com/ok")

        assert result["success"] is True
        assert result.get("final_url") is None
        assert result.get("final_request_has_credential") is None

    @pytest.mark.asyncio
    async def test_computed_for_a_401_response(self, mock_transport):
        mock_transport(lambda request: httpx.Response(401, json={"error": "nope"}))

        result = await APIClientCore().call_api(url="https://api.hubapi.com/x")

        assert result["status_code"] == 401
        assert result["final_url"] == "https://api.hubapi.com/x"
        assert result["final_request_has_credential"] is False


class TestCredentialFreeLogging:
    """Regression: call_api's own request/completion logs, and the
    adapter's connector-hint log, used to interpolate the raw URL - which
    can carry a real credential (Basic-Auth userinfo a caller embedded, or
    an api_key_query auth_token merged into the query string before the
    request runs). For CustomApiTool in particular, that URL can hold a
    real decrypted, persisted secret (see api_tool_adapter.py's
    _replace_secrets/decrypt_value), so this isn't just a hypothetical -
    every one of these log lines needed the same redaction final_url
    already got."""

    @pytest.mark.asyncio
    async def test_startup_log_does_not_leak_basic_auth_userinfo(
        self, mock_httpbin: None, caplog: pytest.LogCaptureFixture
    ):
        caplog.set_level("INFO")
        await call_api(url="https://user:[email protected]/get")

        assert "leaked-secret" not in caplog.text

    @pytest.mark.asyncio
    async def test_completion_log_does_not_leak_api_key_query_credential(
        self, mock_httpbin: None, caplog: pytest.LogCaptureFixture
    ):
        caplog.set_level("INFO")
        await call_api(
            url="https://httpbin.org/get",
            auth_type="api_key_query",
            auth_token="leaked-secret",
        )

        assert "leaked-secret" not in caplog.text

    @pytest.mark.asyncio
    async def test_logs_redact_all_arbitrary_query_values(
        self, mock_httpbin: None, caplog: pytest.LogCaptureFixture
    ):
        """This call site accepts arbitrary params, so it cannot rely on the
        incomplete keyword inventory tracked by open issue #2356."""
        caplog.set_level("INFO")
        await call_api(
            url="https://httpbin.org/get?client_secret=url-secret",
            params={"subscription-key": "param-secret", "q": "ordinary-value"},
        )

        assert "url-secret" not in caplog.text
        assert "param-secret" not in caplog.text
        assert "ordinary-value" not in caplog.text

    @pytest.mark.asyncio
    async def test_invalid_merged_url_error_does_not_leak_query_values(self):
        result = await call_api(
            url="http://example.com:abc/path?client_secret=url-secret",
            params={"q": "ordinary-value"},
        )

        assert "url-secret" not in result["error"]
        assert "ordinary-value" not in result["error"]

    @pytest.mark.asyncio
    async def test_adapter_rejects_url_userinfo_without_logging_credential(
        self, mock_httpbin: None, caplog: pytest.LogCaptureFixture
    ):
        """Legacy URL-userinfo calls now fail closed before dispatch; error
        and diagnostic messages must still redact the rejected credential."""
        caplog.set_level("INFO")
        tool = APITool()
        result = await tool.run_json_async(
            {
                "url": "https://user:[email protected]/status/401"
                "?__redirected_to__=https://api.hubapi.com/crm/v3/deals/1"
            }
        )

        assert result["success"] is False
        assert result["status_code"] == 0
        assert "leaked-secret" not in result["error"]
        assert "leaked-secret" not in caplog.text


class TestAPITool:
    """Test APITool adapter"""

    def test_tool_metadata(self):
        """Test tool metadata"""
        tool = APITool()

        assert tool.name == "api_call"
        assert "HTTP requests to arbitrary APIs" in tool.description
        assert "dedicated MCP connector" in tool.description
        assert "api" in tool.tags
        assert "http" in tool.tags
        assert tool.category.value == "web_tools"

    def test_args_schema(self):
        """Test argument schema"""
        tool = APITool()
        args_type = tool.args_type()

        assert args_type == APICallArgs

        # Validate args
        args = APICallArgs.model_validate(
            {
                "url": "https://api.example.com",
                "method": "POST",
                "body": {"test": "value"},
            }
        )
        assert args.url == "https://api.example.com"
        assert args.method == "POST"
        assert args.body == {"test": "value"}

    @pytest.mark.asyncio
    async def test_api_call_execution(self, monkeypatch):
        """Test API tool wrapper delegates to client core"""
        tool = APITool()

        async def mock_call_api(**kwargs):
            assert kwargs["url"] == "https://httpbin.org/get"
            assert kwargs["method"] == "GET"
            assert kwargs["params"] == {"test": "value"}
            return {
                "success": True,
                "status_code": 200,
                "headers": {"content-type": "application/json"},
                "body": {"ok": True},
                "error": None,
            }

        monkeypatch.setattr(tool._client, "call_api", mock_call_api)

        result = await tool.run_json_async(
            {
                "url": "https://httpbin.org/get",
                "method": "GET",
                "params": {"test": "value"},
            }
        )

        assert result["success"] is True
        assert result["status_code"] == 200

    @pytest.mark.asyncio
    async def test_api_call_with_auth(self, monkeypatch):
        """Test API call forwards authentication args"""
        tool = APITool()

        async def mock_call_api(**kwargs):
            assert kwargs["auth_type"] == "bearer"
            assert kwargs["auth_token"] == "test-token"
            return {
                "success": True,
                "status_code": 200,
                "headers": {},
                "body": {"authenticated": True},
                "error": None,
            }

        monkeypatch.setattr(tool._client, "call_api", mock_call_api)

        result = await tool.run_json_async(
            {
                "url": "https://httpbin.org/bearer",
                "method": "GET",
                "auth_type": "bearer",
                "auth_token": "test-token",
            }
        )

        assert result["success"] is True
        assert result["status_code"] == 200

    @pytest.mark.asyncio
    async def test_api_call_with_post_body(self, monkeypatch):
        """Test API call forwards POST body and headers"""
        tool = APITool()

        async def mock_call_api(**kwargs):
            assert kwargs["method"] == "POST"
            assert kwargs["body"] == {"name": "test", "value": 123}
            assert kwargs["headers"] == {"Content-Type": "application/json"}
            return {
                "success": True,
                "status_code": 200,
                "headers": {},
                "body": {"name": "test", "value": 123},
                "error": None,
            }

        monkeypatch.setattr(tool._client, "call_api", mock_call_api)

        result = await tool.run_json_async(
            {
                "url": "https://httpbin.org/post",
                "method": "POST",
                "body": {"name": "test", "value": 123},
                "headers": {"Content-Type": "application/json"},
            }
        )

        assert result["success"] is True
        assert result["status_code"] == 200

    @pytest.mark.asyncio
    async def test_api_call_with_api_key_query(self, monkeypatch):
        """Test API key query options are forwarded via tool"""
        tool = APITool()

        async def mock_call_api(**kwargs):
            assert kwargs["auth_type"] == "api_key_query"
            assert kwargs["auth_token"] == "my-secret-key-123"
            assert kwargs["api_key_param"] == "key"
            return {
                "success": True,
                "status_code": 200,
                "headers": {},
                "body": {"args": {"key": "my-secret-key-123"}},
                "error": None,
            }

        monkeypatch.setattr(tool._client, "call_api", mock_call_api)

        result = await tool.run_json_async(
            {
                "url": "https://httpbin.org/get",
                "method": "GET",
                "auth_type": "api_key_query",
                "auth_token": "my-secret-key-123",
                "api_key_param": "key",
            }
        )

        assert result["success"] is True
        assert result["status_code"] == 200
        assert result["body"]["args"]["key"] == "my-secret-key-123"

    @pytest.mark.asyncio
    async def test_public_credential_less_call_to_known_connector_domain_succeeds(
        self, mock_httpbin: None
    ):
        """The core regression this whole design is for: a domain covered
        by a dedicated connector (GitHub) can still have genuinely public,
        credential-less endpoints (e.g. GET /repos/{owner}/{repo}). An
        earlier pre-flight version of this guard blocked every
        credential-less call to a known connector domain outright,
        converting a legitimate 200 into a synthetic local failure. The
        request must actually be attempted and its real 2xx returned
        untouched."""
        tool = APITool()
        result = await tool.run_json_async(
            {"url": "https://api.github.com/get", "method": "GET"}
        )

        assert result["success"] is True
        assert result["status_code"] == 200

    @pytest.mark.asyncio
    async def test_annotates_a_real_401_with_connector_hint_when_uncredentialed(
        self, mock_httpbin: None
    ):
        """A request that actually reached a known connector domain and
        actually got a 401/403 back, with no credential this tool
        recognizes, gets that real status/body preserved plus a hint
        pointing at the dedicated connector tools - not a synthetic
        pre-flight refusal."""
        tool = APITool()
        result = await tool.run_json_async(
            {"url": "https://api.hubapi.com/status/401", "method": "PATCH"}
        )

        assert result["success"] is False
        assert result["status_code"] == 401
        assert "HubSpot" in result["error"]
        assert "connector tools" in result["error"]

    @pytest.mark.asyncio
    async def test_annotates_a_real_401_on_a_multi_tenant_subdomain(
        self, mock_httpbin: None
    ):
        """Multi-tenant connectors (Zendesk, Shopify, etc.) are matched by
        domain suffix, not just the exact host."""
        tool = APITool()
        result = await tool.run_json_async(
            {"url": "https://acme.zendesk.com/status/403"}
        )

        assert result["status_code"] == 403
        assert "Zendesk" in result["error"]

    @pytest.mark.asyncio
    async def test_does_not_annotate_a_401_with_credentials_attached(
        self, mock_httpbin: None
    ):
        """A caller that already attached its own credential - even if that
        credential turns out to be invalid and the real call still 401s -
        genuinely intended a direct call, so the hint (which exists to
        explain an UNEXPLAINED 401) must not be added."""
        tool = APITool()
        result = await tool.run_json_async(
            {
                "url": "https://api.hubapi.com/status/401",
                "auth_type": "bearer",
                "auth_token": "a-private-app-token-that-happens-to-be-invalid",
            }
        )

        assert result["status_code"] == 401
        assert "connector tools" not in (result.get("error") or "")

    @pytest.mark.asyncio
    async def test_does_not_annotate_a_non_401_403_status(self, mock_httpbin: None):
        """Only 401/403 are ambiguous ("is this a broken connection or a
        missing credential?"); any other status is left exactly as the
        server returned it."""
        tool = APITool()
        result = await tool.run_json_async({"url": "https://api.hubapi.com/status/500"})

        assert result["status_code"] == 500
        assert "connector tools" not in (result.get("error") or "")

    @pytest.mark.asyncio
    async def test_does_not_annotate_an_unrelated_domain(self, mock_httpbin: None):
        tool = APITool()
        result = await tool.run_json_async({"url": "https://httpbin.org/status/401"})

        assert result["status_code"] == 401
        assert "connector tools" not in (result.get("error") or "")

    @pytest.mark.asyncio
    async def test_annotates_a_trailing_dot_host(self, mock_httpbin: None):
        """A trailing "." is a valid DNS root-label marker for the same
        host (api.hubapi.com. == api.hubapi.com); the hint must still
        apply, not silently skip a spelling a caller could legitimately
        send."""
        tool = APITool()
        result = await tool.run_json_async(
            {"url": "https://api.hubapi.com./status/401"}
        )

        assert "HubSpot" in result["error"]

    @pytest.mark.asyncio
    async def test_annotates_based_on_the_post_redirect_host_not_the_original(
        self, mock_httpbin: None
    ):
        """Regression: allow_redirects defaults to True, so the response
        that actually comes back can be from a different host than the URL
        the caller started with. A request that starts on an unrelated host
        and redirects to a known connector domain, which then 401s, must
        still get the hint - matching against the original URL's host
        (unrelated here) would silently miss it."""
        tool = APITool()
        result = await tool.run_json_async(
            {
                "url": "https://httpbin.org/status/401"
                "?__redirected_to__=https://api.hubapi.com/crm/v3/deals/1"
            }
        )

        assert "HubSpot" in result["error"]

    @pytest.mark.asyncio
    async def test_annotates_when_a_cross_origin_redirect_drops_the_original_credential(
        self, mock_httpbin: None
    ):
        """Regression: httpx strips the Authorization header when a
        redirect crosses hosts (see httpx.Client._redirect_headers). A
        request that started out credentialed can still land on a known
        connector host with nothing attached on the actual final request -
        the hint must reflect that, not the caller's original (now-
        stripped) credential."""
        tool = APITool()
        result = await tool.run_json_async(
            {
                "url": "https://httpbin.org/status/401"
                "?__redirected_to__=https://api.hubapi.com/crm/v3/deals/1",
                "auth_type": "bearer",
                "auth_token": "original-host-token",
            }
        )

        assert "HubSpot" in result["error"]

    @pytest.mark.asyncio
    async def test_real_cross_origin_redirect_drops_authorization_and_adds_hint(
        self, mock_transport
    ):
        final_requests: list[httpx.Request] = []

        def handler(request: httpx.Request) -> httpx.Response:
            if request.url.host == "origin.example.com":
                return httpx.Response(
                    302,
                    headers={"location": "https://api.hubapi.com/crm/v3/deals/1"},
                )
            final_requests.append(request)
            return httpx.Response(401, json={"message": "unauthorized"})

        mock_transport(handler)
        result = await APITool().run_json_async(
            {
                "url": "https://origin.example.com/start",
                "auth_type": "bearer",
                "auth_token": "origin-only-token",
            }
        )

        assert len(final_requests) == 1
        assert "authorization" not in final_requests[0].headers
        assert result["status_code"] == 401
        assert "HubSpot" in result["error"]

    @pytest.mark.asyncio
    async def test_does_not_annotate_when_a_same_origin_redirect_keeps_the_credential(
        self, mock_httpbin: None
    ):
        """Control for the cross-origin case above: a same-origin redirect
        does not strip Authorization, so a genuinely still-credentialed
        request must keep suppressing the hint."""
        tool = APITool()
        result = await tool.run_json_async(
            {
                "url": "https://api.hubapi.com/status/401"
                "?__redirected_to__=https://api.hubapi.com/crm/v3/deals/1",
                "auth_type": "bearer",
                "auth_token": "still-valid-token",
            }
        )

        assert "connector tools" not in (result.get("error") or "")

    @pytest.mark.asyncio
    async def test_real_same_origin_redirect_keeps_authorization_and_skips_hint(
        self, mock_transport
    ):
        final_requests: list[httpx.Request] = []

        def handler(request: httpx.Request) -> httpx.Response:
            if request.url.path == "/start":
                return httpx.Response(302, headers={"location": "/crm/v3/deals/1"})
            final_requests.append(request)
            return httpx.Response(401, json={"message": "unauthorized"})

        mock_transport(handler)
        result = await APITool().run_json_async(
            {
                "url": "https://api.hubapi.com/start",
                "auth_type": "bearer",
                "auth_token": "same-origin-token",
            }
        )

        assert len(final_requests) == 1
        assert final_requests[0].headers["authorization"] == "Bearer same-origin-token"
        assert result["status_code"] == 401
        assert "connector tools" not in (result.get("error") or "")

    @pytest.mark.asyncio
    async def test_does_not_annotate_when_redirected_off_a_known_connector_host(
        self, mock_httpbin: None
    ):
        """Symmetric regression: a request starting on a known connector
        host that redirects OFF that host to an unrelated 401 must not get
        a hint naming the original (wrong) service."""
        tool = APITool()
        result = await tool.run_json_async(
            {
                "url": "https://api.github.com/status/401"
                "?__redirected_to__=https://httpbin.org/status/401"
            }
        )

        assert "connector tools" not in (result.get("error") or "")

    @pytest.mark.asyncio
    async def test_hint_does_not_produce_a_run_on_sentence(self, mock_httpbin: None):
        """The existing error text ("HTTP 401") has no trailing punctuation,
        so appending the hint sentence directly after it would otherwise
        read as one run-on sentence - a period must be inserted between
        them."""
        tool = APITool()
        result = await tool.run_json_async({"url": "https://api.hubapi.com/status/401"})

        assert result["error"].startswith("HTTP 401. This looks like")

    @pytest.mark.asyncio
    async def test_malformed_url_does_not_crash(self):
        """A malformed URL (invalid IPv6 host syntax) must still come back
        as a normal structured result - not an uncaught exception. This URL
        fails core's own validation (_is_valid_url) before a real request is
        ever attempted, so status_code is 0 and the connector-hint check
        never runs at all."""
        tool = APITool()
        result = await tool.run_json_async({"url": "https://[::1"})

        assert result["success"] is False
        assert result["status_code"] == 0
        assert isinstance(result.get("error"), str)

    @pytest.mark.asyncio
    async def test_hint_failure_preserves_the_real_http_response(
        self, monkeypatch: pytest.MonkeyPatch
    ):
        tool = APITool()

        async def mock_call_api(**kwargs):
            return {
                "success": False,
                "status_code": 401,
                "headers": {"x-request-id": "request-1"},
                "body": {"message": "unauthorized"},
                "error": "HTTP 401",
                "final_url": "https://api.hubapi.com/crm/v3/deals/1",
                "final_request_has_credential": False,
            }

        def broken_hint(*args, **kwargs):
            raise ValueError("diagnostic failure")

        monkeypatch.setattr(tool._client, "call_api", mock_call_api)
        monkeypatch.setattr(
            tool, "_hint_known_connector_if_uncredentialed", broken_hint
        )

        result = await tool.run_json_async({"url": "https://api.hubapi.com/x"})

        assert result == {
            "success": False,
            "status_code": 401,
            "headers": {"x-request-id": "request-1"},
            "body": {"message": "unauthorized"},
            "error": "HTTP 401",
        }

    def test_return_value_formatting(self):
        """Test return value formatting"""
        tool = APITool()

        # Success case
        success_result = {
            "success": True,
            "status_code": 200,
            "body": {"result": "success"},
        }
        formatted = tool.return_value_as_string(success_result)
        assert "✅" in formatted
        assert "200" in formatted

        # Error case
        error_result = {
            "success": False,
            "error": "Connection failed",
        }
        formatted = tool.return_value_as_string(error_result)
        assert "❌" in formatted
        assert "Connection failed" in formatted


class TestConvenienceFunctions:
    """Test convenience functions"""

    @pytest.mark.asyncio
    async def test_call_api_function(self, mock_httpbin: None):
        """Test convenience call_api function"""
        result = await call_api(
            url="https://httpbin.org/get",
            method="GET",
            params={"test": "value"},
        )

        assert result["success"] is True
        assert result["status_code"] == 200