@hypercubed/web-search

web-search

Intent

Unified web search for any Kody agent. Tries Brave Search first, then free Worker-safe fallbacks. Normalized {provider, results: {title, url, snippet}[]} shape.

Setup (required for Brave)

1. Create secret BraveSearch at /account/secrets/new — paste your BSA... key from https://api.search.brave.com/app/keys (scope: User).
2. In the secret, add Allowed sites: api.search.brave.com
3. Add Allowed packages: web-search (select @hypercubed/web-search or your fork) — required even for self-authored packages when editing the secret.
4. Placeholder is {{secret:BraveSearch}} (singular, per docs/use/secrets-and-values.md), not {{secrets...}}.

Without the secret/host allowlist, the package falls back to DuckDuckGo Instant (curated) then Wikipedia (both Worker-safe but weaker than Brave).

Usage

import { search } from '@hypercubed/web-search'
const { provider, results } = await search('Block Goose AI agent', 5)

Prose: "Use my web-search package to search for 'X'"

Fallback order