Skip to content

Add SerpBase Google search modes - #46

Merged
mavam merged 5 commits into
mainfrom
add-serpbase
Sep 10, 2026
Merged

mavam merged 5 commits into
mainfrom
add-serpbase

Conversation

@mavam

@mavam mavam commented Sep 10, 2026

Copy link
Copy Markdown
Owner

🔍 Problem

  • SerpBase users cannot use their existing API key through webfox, including Google's specialized search endpoints.

🛠️ Solution

  • Cover all six endpoints through the existing search capability and one web_search tool: search, images, news, videos, maps, and maps-detail.
  • Expose typed native options and mode-aware validation/defaults. Maps Detail takes feature IDs from Maps Search in queries, without dummy queries or additional tools.
  • Include media URLs, sources, feature IDs, contact information, and place details in model-visible text; retain richer metadata in JSON. Connect provider guidance to tool descriptions.
  • Keep each input to one page or place, with local result limiting, cancellation, and business-status-aware retries. SerpBase defaults to a 120-second overall deadline; explicit request/configuration deadlines take precedence and other providers are unchanged. Use direct HTTP with no additional SDK dependency.

💬 Review

  • 471 tests pass locally, including fake-timer checks of cancellation deadlines and timeout precedence. Wire tests cover all six endpoints; Pi tests verify only web_search is registered and follow a feature ID from model-visible Maps output into Maps Detail.
  • PR CI is green on Node.js 22, 24, and 26, including formatting and the installed CLI/Pi package smoke test.
  • Manual CI with a live Maps search passed on commit 8f3a302, using the environment-scoped SERPBASE_API_KEY. Latest local news/maps retries with the longer default returned upstream 1503: service unavailable, rather than a client timeout.
  • Real local API checks passed for every endpoint, including Maps → Maps Detail, plus desktop/mobile and page-2 organic results. Initial detail timeout and concurrent-call throttling were observed; a sequential detail retry succeeded.
  • Live responses exposed a Google navigation-logo artifact and ambiguous video time fields. Narrow regression-tested handling excludes the navigation asset and avoids inventing publication dates or durations.
  • Empty result lists still have no per-result context; upstream data quality, latency, and account limits remain provider-dependent.

Closes #45

Support Google organic search with existing SerpBase credentials through
the library, CLI, and Pi provider registry. Use direct HTTP because there
is no suitable standalone TypeScript SDK.

Preserve page-relative ranks and SERP context without fetching additional
pages. Classify business-status failures even on HTTP 200 and propagate
cancellation through the shared runtime. Cover native options, wire
requests, CLI configuration, and failures, and wire the live CI secret.
Keep Google search, images, news, videos, maps, and place details behind
web_search. Maps detail inputs are feature IDs from maps results, not
dummy queries or a new harness tool.

Validate native controls by mode and drop incompatible inherited defaults
when switching modes. Connect provider guidance to tool descriptions and
surface media URLs, feature IDs, and place information in text output.

Cover every endpoint with wire tests and the Maps follow-up through Pi.
Handle the navigation-logo and ambiguous video-time artifacts observed
in live API responses without inventing dates or durations.
@mavam
mavam had a problem deploying to Live provider tests September 10, 2026 11:02 — with GitHub Actions Failure
The generic Node.js documentation query legitimately returns no places.
Use a geographic business query when testing SerpBase Maps so the live
check exercises place results rather than failing on an empty search.
@mavam
mavam deployed to Live provider tests September 10, 2026 11:07 — with GitHub Actions Active
@mavam mavam changed the title Add SerpBase Google search Add SerpBase Google search modes Sep 10, 2026
Use a 120-second provider default across SerpBase search modes instead
of cutting off slower news and maps responses at 30 seconds. Explicit
request and execution settings still take precedence, and other providers
retain their existing deadlines.

Test the actual cancellation deadlines and precedence with fake timers.
@mavam
mavam merged commit e66589c into main Sep 10, 2026
6 checks passed
@mavam
mavam deleted the add-serpbase branch September 10, 2026 11:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add SerpBase as a search provider (hosted Google SERP API)

1 participant