feat(google_maps): add scrape + reviews capability verbs

surfsense_backend/tests/unit/capabilities/google_maps/reviews/test_executor.py

@@ -0,0 +1,87 @@
+"""``google_maps.reviews`` executor: verb input → actor input mapping → typed items.
+
+Boundary mocked: the proprietary scraper (injected fake). NOT mocked: the verb's
+own payload→GoogleMapsReviewsInput mapping and the dict→ReviewItem wrapping.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from app.capabilities.google_maps.reviews.executor import build_reviews_executor
+from app.capabilities.google_maps.reviews.schemas import ReviewsInput, ReviewsOutput
+from app.exceptions import ForbiddenError
+from app.proprietary.platforms.google_maps import GoogleMapsReviewsInput
+from app.proprietary.platforms.google_maps.scraper import SignInRequiredError
+
+pytestmark = pytest.mark.unit
+
+
+class _FakeScraper:
+    def __init__(self, items: list[dict]):
+        self._items = items
+        self.calls: list[GoogleMapsReviewsInput] = []
+
+    async def __call__(self, actor_input: GoogleMapsReviewsInput) -> list[dict]:
+        self.calls.append(actor_input)
+        return self._items
+
+
+async def test_maps_urls_to_start_urls_and_wraps_items():
+    scraper = _FakeScraper([{"text": "Great place", "stars": 5.0}])
+    execute = build_reviews_executor(scrape_fn=scraper)
+
+    out = await execute(ReviewsInput(urls=["https://www.google.com/maps/place/x"]))
+
+    assert isinstance(out, ReviewsOutput)
+    assert len(out.items) == 1
+    assert out.items[0].text == "Great place"
+    assert out.items[0].stars == 5.0
+
+    (actor_input,) = scraper.calls
+    assert [u.url for u in actor_input.startUrls] == [
+        "https://www.google.com/maps/place/x"
+    ]
+
+
+async def test_forwards_place_ids_and_options():
+    scraper = _FakeScraper([])
+    execute = build_reviews_executor(scrape_fn=scraper)
+
+    await execute(
+        ReviewsInput(
+            place_ids=["ChIJx"],
+            max_reviews=50,
+            sort_by="highestRanking",
+            language="fr",
+            start_date="2024-01-01",
+        )
+    )
+
+    (actor_input,) = scraper.calls
+    assert actor_input.placeIds == ["ChIJx"]
+    assert actor_input.maxReviews == 50
+    assert actor_input.reviewsSort == "highestRanking"
+    assert actor_input.language == "fr"
+    assert actor_input.reviewsStartDate == "2024-01-01"
+
+
+async def test_sign_in_required_maps_to_forbidden_403():
+    async def _raise(_actor_input):
+        raise SignInRequiredError("wall hit")
+
+    execute = build_reviews_executor(scrape_fn=_raise)
+
+    with pytest.raises(ForbiddenError) as exc_info:
+        await execute(ReviewsInput(place_ids=["ChIJx"]))
+    assert exc_info.value.status_code == 403
+
+
+async def test_other_faults_propagate_for_the_door_to_map():
+    async def _boom(_actor_input):
+        raise RuntimeError("proxy exploded")
+
+    execute = build_reviews_executor(scrape_fn=_boom)
+
+    with pytest.raises(RuntimeError):
+        await execute(ReviewsInput(place_ids=["ChIJx"]))

surfsense_backend/tests/unit/capabilities/google_maps/reviews/test_schemas.py

@@ -0,0 +1,35 @@
+"""``google_maps.reviews`` input guards: a source is required and the batch is bounded."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from app.capabilities.google_maps.reviews.schemas import (
+    MAX_MAPS_REVIEW_SOURCES,
+    ReviewsInput,
+)
+
+pytestmark = pytest.mark.unit
+
+
+def test_rejects_input_with_no_source():
+    with pytest.raises(ValidationError):
+        ReviewsInput()
+
+
+def test_accepts_urls_or_place_ids():
+    assert ReviewsInput(urls=["https://maps.google.com/x"]).place_ids == []
+    assert ReviewsInput(place_ids=["ChIJx"]).urls == []
+
+
+def test_max_reviews_defaults_and_is_bounded():
+    assert ReviewsInput(place_ids=["ChIJx"]).max_reviews == 20
+    with pytest.raises(ValidationError):
+        ReviewsInput(place_ids=["ChIJx"], max_reviews=0)
+
+
+def test_rejects_more_sources_than_the_cap():
+    too_many = [f"ChIJ{i}" for i in range(MAX_MAPS_REVIEW_SOURCES + 1)]
+    with pytest.raises(ValidationError):
+        ReviewsInput(place_ids=too_many)

surfsense_backend/tests/unit/capabilities/google_maps/scrape/test_executor.py

@@ -0,0 +1,115 @@
+"""``google_maps.scrape`` executor: verb input → actor input mapping → typed items.
+
+Boundary mocked: the proprietary scraper (injected fake). NOT mocked: the verb's
+own payload→GoogleMapsScrapeInput mapping and the dict→PlaceItem wrapping.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from app.capabilities.google_maps.scrape.executor import build_scrape_executor
+from app.capabilities.google_maps.scrape.schemas import ScrapeInput, ScrapeOutput
+from app.exceptions import ForbiddenError
+from app.proprietary.platforms.google_maps import GoogleMapsScrapeInput
+from app.proprietary.platforms.google_maps.scraper import SignInRequiredError
+
+pytestmark = pytest.mark.unit
+
+
+class _FakeScraper:
+    """Records the actor input it was called with and returns canned items."""
+
+    def __init__(self, items: list[dict]):
+        self._items = items
+        self.calls: list[GoogleMapsScrapeInput] = []
+
+    async def __call__(self, actor_input: GoogleMapsScrapeInput) -> list[dict]:
+        self.calls.append(actor_input)
+        return self._items
+
+
+async def test_maps_queries_and_wraps_items():
+    scraper = _FakeScraper([{"title": "Blue Bottle", "placeId": "abc"}])
+    execute = build_scrape_executor(scrape_fn=scraper)
+
+    out = await execute(ScrapeInput(search_queries=["coffee"], location="Austin"))
+
+    assert isinstance(out, ScrapeOutput)
+    assert len(out.items) == 1
+    assert out.items[0].title == "Blue Bottle"
+    assert out.items[0].placeId == "abc"
+
+    (actor_input,) = scraper.calls
+    assert actor_input.searchStringsArray == ["coffee"]
+    assert actor_input.locationQuery == "Austin"
+
+
+async def test_maps_urls_and_place_ids():
+    scraper = _FakeScraper([])
+    execute = build_scrape_executor(scrape_fn=scraper)
+
+    await execute(
+        ScrapeInput(
+            urls=["https://www.google.com/maps/place/x"],
+            place_ids=["ChIJxxxx"],
+        )
+    )
+
+    (actor_input,) = scraper.calls
+    assert [u.url for u in actor_input.startUrls] == [
+        "https://www.google.com/maps/place/x"
+    ]
+    assert actor_input.placeIds == ["ChIJxxxx"]
+
+
+async def test_max_places_maps_to_per_search_cap():
+    scraper = _FakeScraper([])
+    execute = build_scrape_executor(scrape_fn=scraper)
+
+    await execute(ScrapeInput(search_queries=["x"], max_places=25))
+
+    (actor_input,) = scraper.calls
+    assert actor_input.maxCrawledPlacesPerSearch == 25
+
+
+async def test_forwards_detail_review_and_image_options():
+    scraper = _FakeScraper([])
+    execute = build_scrape_executor(scrape_fn=scraper)
+
+    await execute(
+        ScrapeInput(
+            search_queries=["x"],
+            include_details=True,
+            max_reviews=5,
+            max_images=3,
+            language="fr",
+        )
+    )
+
+    (actor_input,) = scraper.calls
+    assert actor_input.scrapePlaceDetailPage is True
+    assert actor_input.maxReviews == 5
+    assert actor_input.maxImages == 3
+    assert actor_input.language == "fr"
+
+
+async def test_sign_in_required_maps_to_forbidden_403():
+    async def _raise(_actor_input):
+        raise SignInRequiredError("wall hit")
+
+    execute = build_scrape_executor(scrape_fn=_raise)
+
+    with pytest.raises(ForbiddenError) as exc_info:
+        await execute(ScrapeInput(search_queries=["x"]))
+    assert exc_info.value.status_code == 403
+
+
+async def test_other_faults_propagate_for_the_door_to_map():
+    async def _boom(_actor_input):
+        raise RuntimeError("proxy exploded")
+
+    execute = build_scrape_executor(scrape_fn=_boom)
+
+    with pytest.raises(RuntimeError):
+        await execute(ScrapeInput(search_queries=["x"]))

surfsense_backend/tests/unit/capabilities/google_maps/scrape/test_schemas.py

@@ -0,0 +1,36 @@
+"""``google_maps.scrape`` input guards: a source is required and the batch is bounded."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from app.capabilities.google_maps.scrape.schemas import (
+    MAX_MAPS_SOURCES,
+    ScrapeInput,
+)
+
+pytestmark = pytest.mark.unit
+
+
+def test_rejects_input_with_no_source():
+    with pytest.raises(ValidationError):
+        ScrapeInput()
+
+
+def test_accepts_any_single_source():
+    assert ScrapeInput(search_queries=["coffee"]).urls == []
+    assert ScrapeInput(urls=["https://maps.google.com/x"]).place_ids == []
+    assert ScrapeInput(place_ids=["ChIJx"]).search_queries == []
+
+
+def test_max_places_defaults_and_is_bounded():
+    assert ScrapeInput(search_queries=["x"]).max_places == 10
+    with pytest.raises(ValidationError):
+        ScrapeInput(search_queries=["x"], max_places=0)
+
+
+def test_rejects_more_sources_than_the_cap():
+    too_many = [f"q{i}" for i in range(MAX_MAPS_SOURCES + 1)]
+    with pytest.raises(ValidationError):
+        ScrapeInput(search_queries=too_many)

surfsense_backend/tests/unit/capabilities/google_maps/test_registry.py

@@ -0,0 +1,32 @@
+"""The google_maps namespace registers each verb as one Capability the doors/agent read."""
+
+from __future__ import annotations
+
+import pytest
+
+from app.capabilities import (
+    google_maps,  # noqa: F401  — importing the namespace registers its verbs
+)
+from app.capabilities.core.store import get_capability
+from app.capabilities.google_maps.reviews.schemas import ReviewsInput, ReviewsOutput
+from app.capabilities.google_maps.scrape.schemas import ScrapeInput, ScrapeOutput
+
+pytestmark = pytest.mark.unit
+
+
+def test_google_maps_scrape_is_registered_and_free():
+    cap = get_capability("google_maps.scrape")
+
+    assert cap.name == "google_maps.scrape"
+    assert cap.input_schema is ScrapeInput
+    assert cap.output_schema is ScrapeOutput
+    assert cap.billing_unit is None
+
+
+def test_google_maps_reviews_is_registered_and_free():
+    cap = get_capability("google_maps.reviews")
+
+    assert cap.name == "google_maps.reviews"
+    assert cap.input_schema is ReviewsInput
+    assert cap.output_schema is ReviewsOutput
+    assert cap.billing_unit is None