feat: support SerpBase search

[oritwoen]

Adds SerpBase as opt-in Google SERP provider behind SERPBASE_API_KEY. Search stays simple: web by default, category can pick images, news, or videos, and maxResults just trims returned page because SerpBase docs don't expose a limit param.

SerpBase returns business errors inside JSON, sometimes with HTTP 200, so adapter checks status itself instead of trusting HTTP only. Docs and Pi/OpenCode/AI surfaces know about provider now. No issue - fixed directly.

[cubic-dev-ai]

No issues found across 15 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant API as API / Tool Invocation
    participant Resolver as resolve.ts
    participant Registry as registry.ts
    participant Provider as serpbase.ts
    participant SerpBaseAPI as SerpBase API
    participant ErrorHandler as errors.ts

    Note over API,ErrorHandler: NEW: SerpBase provider integration

    API->>Resolver: search(query, options)
    Resolver->>Resolver: detectAvailableProviders()
    Resolver->>Resolver: NEW: check SERPBASE_API_KEY env var
    alt SERPBASE_API_KEY set
        Resolver->>Registry: get provider factory for 'serpbase'
        Registry-->>Resolver: factory
        Resolver->>Provider: create(ProviderConfig{apiKey, baseURL})
        Provider-->>Resolver: SerpBaseProvider instance
    end

    alt Provider selected = 'serpbase'
        API->>Provider: search(query, { category, maxResults })
        Provider->>Provider: NEW: endpointForCategory(category)
        alt category = 'images'
            Provider->>Provider: endpoint = '/google/images'
        else category = 'news'
            Provider->>Provider: endpoint = '/google/news'
        else category = 'videos'
            Provider->>Provider: endpoint = '/google/videos'
        else default (web)
            Provider->>Provider: endpoint = '/google/search'
        end
        Provider->>Provider: build SerpBaseSearchRequest body
        Provider->>SerpBaseAPI: POST {baseURL}{endpoint} with 'X-API-Key' header
        SerpBaseAPI-->>Provider: SerpBaseSearchResponse (JSON)
        Provider->>Provider: NEW: assertSerpBaseSuccess(response)
        alt response.status != 0
            alt status = 1001
                Provider->>ErrorHandler: throw AuthError
            else status = 1029
                Provider->>ErrorHandler: throw RateLimitError(60)
            else status = 1020
                Provider->>ErrorHandler: throw AskwebError(insufficient credits)
            else other
                Provider->>ErrorHandler: throw AskwebError
            end
            ErrorHandler-->>Provider: error
            Provider-->>API: normalized error
        else response.status = 0 (success)
            Provider->>Provider: NEW: resultsForResponse(search_type)
            alt search_type = 'images'
                Provider->>Provider: use response.images[]
            else search_type = 'news'
                Provider->>Provider: use response.news[]
            else search_type = 'videos'
                Provider->>Provider: use response.videos[]
            else default
                Provider->>Provider: use response.organic[]
            end
            Provider->>Provider: NEW: mapResult() - transform to SearchResult
            Provider->>Provider: NEW: slice(0, clampMaxResults(maxResults))
            Provider-->>API: SearchResult[]
        end
    end

    Note over API,ErrorHandler: SerpBase uses business-level status codes inside JSON body<br/>rather than relying solely on HTTP status codes

Loading

<sub>Requires human review: This PR adds a new SerpBase search provider with 171 lines of core implementation logic including network calls, response parsing, error handling, and result mapping, which carries moderate risk of breakage or edge cases that warrant human review.

Re-trigger cubic</sub>