{"_id":"@dpopsuev/alef-adapter-web","_rev":"2-40889303bebf828cad36e1db8d98bdb8","name":"@dpopsuev/alef-adapter-web","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@dpopsuev/alef-adapter-web","version":"0.0.1","keywords":["agent","organ","web","fetch","search","html"],"author":{"name":"Daniel Popsuevich"},"license":"MIT","_id":"@dpopsuev/alef-adapter-web@0.0.1","maintainers":[{"name":"dpopsuev","email":"dpopsuev@redhat.com"}],"homepage":"https://github.com/dpopsuev/alef#readme","bugs":{"url":"https://github.com/dpopsuev/alef/issues"},"dist":{"shasum":"1dcd912935a79cafbac2d26ca33e0430dac96755","tarball":"https://registry.npmjs.org/@dpopsuev/alef-adapter-web/-/alef-adapter-web-0.0.1.tgz","fileCount":12,"integrity":"sha512-BsqDxdf3Sc67dAInB3nsNiKju0hbuQ9gKJLRuMu7MdbsthT20oaAZ/zYjbpH2SRYI1p/hap9/GKbcSb0pQECvQ==","signatures":[{"sig":"MEUCIHjLeBIC7Cbl1+ImCYS7sxAv6gP7TNeOS006Gd8beiI1AiEA8/SqRtX4RwdLIqv7sMt2OrTXUKtk4Bb/LGH3jV88ZTQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":46066},"main":"./src/index.ts","type":"module","_from":"file:dpopsuev-alef-adapter-web-0.0.1.tgz","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./src/index.ts","source":"./src/index.ts","default":"./src/index.ts"}},"scripts":{"dev":"npx tsc -p tsconfig.build.json --watch --preserveWatchOutput","test":"vitest --run","build":"npx tsc -p tsconfig.build.json","clean":"shx rm -rf dist"},"_npmUser":{"name":"dpopsuev","email":"dpopsuev@redhat.com"},"_resolved":"/tmp/7158d1f69ba120215627c3ab07d2b592/dpopsuev-alef-adapter-web-0.0.1.tgz","_integrity":"sha512-BsqDxdf3Sc67dAInB3nsNiKju0hbuQ9gKJLRuMu7MdbsthT20oaAZ/zYjbpH2SRYI1p/hap9/GKbcSb0pQECvQ==","repository":{"url":"git+https://github.com/dpopsuev/alef.git","type":"git","directory":"packages/organ-web"},"_npmVersion":"10.9.7","description":"Web organ — fetch pages and search the web. Supports Brave, Tavily, Exa, and DuckDuckGo.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^4.4.3","@dpopsuev/web-spider":"^0.10.5","@dpopsuev/alef-kernel":"0.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"shx":"^0.4.0","vitest":"^4.1.6","typescript":"^5.9.2","@types/node":"^24.3.0","@dpopsuev/alef-testkit":"0.0.1"},"_npmOperationalInternal":{"tmp":"tmp/alef-adapter-web_0.0.1_1782397787772_0.6861799694867237","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Deprecated — package renamed, do not install"}},"time":{"created":"2026-06-25T14:29:47.658Z","modified":"2026-06-25T15:43:07.184Z","0.0.1":"2026-06-25T14:29:47.950Z"},"bugs":{"url":"https://github.com/dpopsuev/alef/issues"},"author":{"name":"Daniel Popsuevich"},"license":"MIT","homepage":"https://github.com/dpopsuev/alef#readme","keywords":["agent","organ","web","fetch","search","html"],"repository":{"url":"git+https://github.com/dpopsuev/alef.git","type":"git","directory":"packages/organ-web"},"description":"Web organ — fetch pages and search the web. Supports Brave, Tavily, Exa, and DuckDuckGo.","maintainers":[{"name":"dpopsuev","email":"dpopsuev@redhat.com"}],"readme":"# @dpopsuev/alef-organ-web\n\nWeb organ for Alef agents — fetch pages and search the web.\n\n## Features\n\n- **web.fetch**: Fetch web pages and convert to plain text or raw HTML\n- **web.search**: Search the web with multiple engines (Brave, Tavily, Exa, DuckDuckGo)\n- **No external dependencies**: Uses Node.js built-in `fetch`\n- **Resilient**: Automatic fallback through search engines\n- **Extensible**: Register custom search engines\n\n## Installation\n\n```bash\nnpm install @dpopsuev/alef-organ-web\n```\n\n## Usage\n\n### Basic Setup\n\n```typescript\nimport { createWebOrgan } from \"@dpopsuev/alef-organ-web\";\n\nconst webOrgan = createWebOrgan({\n  defaultTimeoutMs: 15000, // optional\n});\n```\n\n### In Agent Blueprints\n\nAdd to your `agent.yaml`:\n\n```yaml\norgans:\n  - name: web\n```\n\nOr use the built-in alias in code:\n\n```typescript\nimport { materializeBlueprint } from \"@dpopsuev/alef-runner\";\n\nconst result = await materializeBlueprint(definition, {\n  cwd: process.cwd(),\n});\n// \"web\" resolves to @dpopsuev/alef-organ-web automatically\n```\n\n## Tools\n\n### web.fetch\n\nFetch a web page and return its content as plain text or raw HTML.\n\n**Parameters:**\n- `url` (string, required): The URL to fetch. Must start with `http://` or `https://`.\n- `format` (enum, optional): Output format. `\"text\"` (default) or `\"html\"`.\n- `timeoutMs` (number, optional): Request timeout in milliseconds. Default: 15000.\n\n**Returns:**\n- `content` (string): The page content (plain text or HTML)\n- `title` (string): Page title extracted from `<title>` tag\n- `url` (string): Final URL after redirects\n- `statusCode` (number): HTTP status code\n- `truncated` (boolean): Whether content was truncated\n\n**Example:**\n\n```typescript\n{\n  type: \"web.fetch\",\n  payload: {\n    url: \"https://example.com\",\n    format: \"text\",\n    timeoutMs: 10000,\n  }\n}\n```\n\n### web.search\n\nSearch the web and return ranked results with URLs, titles, and snippets.\n\n**Parameters:**\n- `query` (string, required): The search query. Natural language questions work well.\n- `numResults` (number, optional): Maximum number of results to return. Default: 10.\n- `engine` (enum, optional): Specific search engine to use: `\"brave\"`, `\"tavily\"`, `\"exa\"`, or `\"ddg\"`. Omit to use auto-fallback.\n\n**Returns:**\n- `query` (string): The search query that was executed\n- `results` (array): List of search results\n  - `url` (string): Result URL\n  - `title` (string): Result title\n  - `snippet` (string): Short description from the search engine\n  - `publishedAt` (string, optional): Publication date if available\n- `hint` (string, optional): Guidance for next steps\n\n**Example:**\n\n```typescript\n{\n  type: \"web.search\",\n  payload: {\n    query: \"TypeScript programming language\",\n    numResults: 5,\n  }\n}\n```\n\n## Search Engines\n\nThe organ supports multiple search engines with automatic fallback:\n\n### Brave Search\n- **Requires**: `BRAVE_SEARCH_API_KEY` environment variable\n- **Docs**: https://brave.com/search/api/\n- **Priority**: First in fallback chain\n\n### Tavily Search\n- **Requires**: `TAVILY_API_KEY` environment variable\n- **Docs**: https://tavily.com/\n- **Priority**: Second in fallback chain\n\n### Exa Search\n- **Requires**: `EXA_API_KEY` environment variable\n- **Docs**: https://exa.ai/\n- **Features**: Neural/semantic search\n- **Priority**: Third in fallback chain\n\n### DuckDuckGo Instant Answer\n- **Requires**: No API key (free)\n- **Docs**: https://duckduckgo.com/api\n- **Priority**: Last resort fallback\n- **Note**: Best-effort API, may return fewer results\n\n## Fallback Behavior\n\nWhen no `engine` is specified, `web.search` tries engines in this order:\n\n1. **Brave** (if `BRAVE_SEARCH_API_KEY` is set)\n2. **Tavily** (if `TAVILY_API_KEY` is set)\n3. **Exa** (if `EXA_API_KEY` is set)\n4. **DuckDuckGo** (always available, no key needed)\n\nEach engine is tried until one returns results. If all return empty, the last error is thrown (or empty results returned).\n\n## Environment Variables\n\n```bash\n# Optional: Set one or more for better search results\nexport BRAVE_SEARCH_API_KEY=\"your-brave-key\"\nexport TAVILY_API_KEY=\"your-tavily-key\"\nexport EXA_API_KEY=\"your-exa-key\"\n\n# DuckDuckGo requires no key\n```\n\n## Advanced Usage\n\n### Custom Search Engine\n\nYou can register custom search engines:\n\n```typescript\nimport { registerSearchEngine } from \"@dpopsuev/alef-organ-web\";\nimport type { ISearchEngine, SearchQuery, WebSearchResult } from \"@dpopsuev/alef-organ-web\";\n\nclass MySearchEngine implements ISearchEngine {\n  async search(req: SearchQuery): Promise<WebSearchResult[]> {\n    // Your implementation\n    return [\n      {\n        url: \"https://example.com\",\n        title: \"Example\",\n        snippet: \"Example snippet\",\n      },\n    ];\n  }\n}\n\nregisterSearchEngine(\"my-engine\", (key) => new MySearchEngine());\n```\n\n### Direct Search (Non-Organ Usage)\n\n```typescript\nimport { webSearch, defaultSearchEngine } from \"@dpopsuev/alef-organ-web\";\n\n// Quick one-off search\nconst results = await webSearch(\"TypeScript features\", { numResults: 5 });\n\n// Or use the engine directly\nconst engine = defaultSearchEngine();\nconst results2 = await engine.search({ query: \"Alef agent framework\", numResults: 10 });\n```\n\n## Testing\n\n```bash\nnpm test                  # Unit tests (no network calls)\nnpm test -- search-integration.test.ts  # Integration tests (requires API keys)\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}