@ever-works/valyu-plugin 1.0.0

package/README.md

@@ -0,0 +1,77 @@
+# @ever-works/valyu-plugin
+
+Valyu Plugin - Web search and content extraction using Valyu API
+
+## Plugin metadata
+
+| Field        | Value                         |
+| ------------ | ----------------------------- |
+| ID           | `valyu`                       |
+| Category     | `search`                      |
+| Capabilities | `search`, `content-extractor` |
+| Author       | Ever Works Team               |
+| License      | AGPL-3.0                      |
+| Built-in     | yes                           |
+| Auto-enable  | no                            |
+
+## What does Valyu do?
+
+Valyu is an AI-native search and content extraction service that searches across web and proprietary data sources. It returns results optimized for AI applications and RAG pipelines, providing the source material that Ever Works uses to generate accurate work items.
+
+## Why use it?
+
+- **Multi-source search** — search across web, proprietary datasets (arXiv, PubMed, financial data), and news
+- **AI-optimized results** — returns content formatted for AI processing with relevance scoring
+- **Content extraction** — pulls clean text and markdown from web pages
+- **Domain filtering** — include or exclude specific websites from search results
+- **Date filtering** — restrict results to specific time periods
+
+## How it works in Ever Works
+
+During work generation, the search facade uses Valyu to find information about each item, discover relevant source URLs, and extract content from web pages. This powers automatic descriptions, source URL resolution, and content enrichment across the generation pipeline.
+
+## Getting started
+
+1. Create an account at [valyu.ai](https://valyu.ai)
+2. Copy your API key from the Valyu dashboard
+3. Enter the key in the **API Key** field below
+4. Valyu will be used during work generation when selected as the search provider
+
+## Settings
+
+- **API Key** (`apiKey`) — required, secret. Your Valyu API key (also configurable via the `PLUGIN_VALYU_API_KEY` environment variable).
+- **Response Length** (`responseLength`) — optional, one of `short` (~25k chars), `medium` (~50k, default), `large` (~100k), or `max` (unlimited). Controls content volume per result.
+- API key is stored at user scope so each user can supply their own credentials.
+- Configuration mode is `hybrid` — admins can preset values and users may override them.
+
+## Troubleshooting
+
+| Symptom                                      | Likely cause                                                            | Fix                                                                                                                                                       |
+| -------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `401 Unauthorized` / `Authentication failed` | API key missing, revoked, or wrong key entered                          | Re-enter the **API Key** from the Valyu dashboard, or set `PLUGIN_VALYU_API_KEY` in the host environment for default fallback                             |
+| `429 Too Many Requests`                      | Free-tier or paid quota exhausted on Valyu                              | Throttle calls, wait for the quota reset, or upgrade the plan in the Valyu dashboard                                                                      |
+| Empty / sparse results                       | Query is too restrictive, time-range or domain filters are too narrow   | Broaden the query, relax `time_range` / `safesearch` / `include_domains` / `exclude_domains` filters, or raise `max_results`                              |
+| Plugin not used during work generation       | Another search plugin is set as the default for the `search` capability | In **Settings → Plugins**, set `valyu` as the default for `search`, or disable competing search plugins                                                   |
+| `Failed to extract content` for a URL        | Page is gated by login, Cloudflare, or robots.txt; URL is malformed     | Verify the URL is publicly reachable; for protected pages enable a different `content-extractor` plugin (`scrapfly`, `notion-extractor`, `pdf-extractor`) |
+| `healthCheck` reports unhealthy              | API key invalid OR Valyu endpoint unreachable from the host             | Verify the key with a manual `curl` against the documented endpoint and confirm outbound HTTPS is allowed by the firewall                                 |
+
+## Local development
+
+This plugin ships built-in with the Ever Works platform. To work on it locally from the monorepo root:
+
+```bash
+pnpm install
+pnpm --filter @ever-works/valyu-plugin build
+pnpm --filter @ever-works/valyu-plugin test
+```
+
+## Documentation
+
+- [Ever Works documentation](https://docs.ever.works)
+- [Ever Works repository](https://github.com/ever-works/ever-works)
+- [Plugin system](../../plugin/README.md)
+- [Valyu homepage](https://valyu.ai)
+
+## License
+
+AGPL-3.0

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@ever-works/valyu-plugin",
+  "version": "1.0.0",
+  "description": "Valyu Plugin - Web search and content extraction using Valyu API",
+  "author": {
+    "name": "Ever Co. LTD",
+    "email": "ever@ever.co",
+    "url": "https://ever.co"
+  },
+  "license": "AGPL-3.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "dependencies": {
+    "valyu-js": "^2.5.4"
+  },
+  "peerDependencies": {
+    "@ever-works/plugin": "1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.0",
+    "@ever-works/plugin": "1.1.0"
+  },
+  "everworks": {
+    "plugin": {
+      "id": "valyu",
+      "name": "Valyu",
+      "version": "1.0.0",
+      "category": "search",
+      "capabilities": [
+        "search",
+        "content-extractor"
+      ],
+      "description": "AI-native search and content extraction using the Valyu API. Supports web, proprietary, and news search with optional content extraction from URLs.",
+      "author": {
+        "name": "Ever Works Team"
+      },
+      "license": "AGPL-3.0",
+      "autoEnable": false,
+      "systemPlugin": false,
+      "builtIn": true,
+      "envVars": [
+        {
+          "name": "PLUGIN_VALYU_API_KEY",
+          "required": false,
+          "secret": true,
+          "description": "Valyu API key (optional - can be set via admin/user settings)"
+        }
+      ],
+      "distribution": "registry"
+    }
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc --noEmit && tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/__tests__/valyu.plugin.spec.ts

@@ -0,0 +1,321 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { PluginContext, SearchOptions, ContentExtractionOptions } from '@ever-works/plugin';
+
+const { searchMock, contentsMock, ValyuCtorMock } = vi.hoisted(() => {
+	const search = vi.fn();
+	const contents = vi.fn();
+	const ctor = vi.fn().mockImplementation(function () {
+		return { search, contents };
+	});
+	return { searchMock: search, contentsMock: contents, ValyuCtorMock: ctor };
+});
+
+vi.mock('valyu-js', () => ({
+	Valyu: ValyuCtorMock
+}));
+
+const { ValyuSearchPlugin } = await import('../valyu.plugin.js');
+
+const buildContext = (settings: Record<string, unknown> = {}): PluginContext =>
+	({
+		pluginId: 'valyu',
+		logger: {
+			log: vi.fn(),
+			debug: vi.fn(),
+			warn: vi.fn(),
+			error: vi.fn()
+		},
+		getSettings: vi.fn().mockResolvedValue(settings)
+	}) as unknown as PluginContext;
+
+describe('ValyuSearchPlugin', () => {
+	let plugin: ValyuSearchPlugin;
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		plugin = new ValyuSearchPlugin();
+	});
+
+	describe('metadata', () => {
+		it('exposes stable identity fields', () => {
+			expect(plugin.id).toBe('valyu');
+			expect(plugin.name).toBe('Valyu');
+			expect(plugin.version).toBe('1.0.0');
+			expect(plugin.category).toBe('search');
+			expect(plugin.providerName).toBe('Valyu');
+		});
+
+		it('declares both search and content-extractor capabilities', () => {
+			expect(plugin.capabilities).toEqual(['search', 'content-extractor']);
+		});
+
+		it('uses hybrid configuration mode', () => {
+			expect(plugin.configurationMode).toBe('hybrid');
+		});
+	});
+
+	describe('settingsSchema', () => {
+		it('requires apiKey and exposes a responseLength enum', () => {
+			expect(plugin.settingsSchema.required).toContain('apiKey');
+			const props = plugin.settingsSchema.properties as Record<string, Record<string, unknown>>;
+			expect(props.apiKey['x-secret']).toBe(true);
+			expect(props.apiKey['x-envVar']).toBe('PLUGIN_VALYU_API_KEY');
+			expect(props.responseLength.default).toBe('medium');
+			expect(props.responseLength.enum).toEqual(['short', 'medium', 'large', 'max']);
+		});
+	});
+
+	describe('search', () => {
+		const opts = (overrides: Partial<SearchOptions> = {}): SearchOptions => ({
+			query: 'hello',
+			settings: { apiKey: 'k' },
+			...overrides
+		});
+
+		it('throws when apiKey is missing', async () => {
+			await expect(plugin.search({ query: 'hello', settings: {} })).rejects.toThrow(/API key not configured/i);
+			expect(ValyuCtorMock).not.toHaveBeenCalled();
+		});
+
+		it('maps SDK results to SearchResult shape', async () => {
+			searchMock.mockResolvedValueOnce({
+				results: [
+					{
+						title: 'Example',
+						url: 'https://example.com',
+						content: 'snippet text',
+						relevance_score: 0.7,
+						source: 'web',
+						description: 'desc',
+						publication_date: '2026-01-01'
+					}
+				]
+			});
+			const r = await plugin.search(opts());
+
+			expect(ValyuCtorMock).toHaveBeenCalledWith('k');
+			expect(r.results).toHaveLength(1);
+			expect(r.results[0]).toMatchObject({
+				title: 'Example',
+				url: 'https://example.com',
+				snippet: 'snippet text',
+				position: 1,
+				publishedDate: '2026-01-01'
+			});
+			expect(r.results[0].metadata).toMatchObject({
+				relevanceScore: 0.7,
+				source: 'web',
+				description: 'desc'
+			});
+			expect(r.totalResults).toBe(1);
+			expect(r.hasMore).toBe(false);
+		});
+
+		it('coerces non-string content to string', async () => {
+			searchMock.mockResolvedValueOnce({
+				results: [{ title: 't', url: 'https://e', content: { foo: 'bar' } }]
+			});
+			const r = await plugin.search(opts());
+			expect(typeof r.results[0].snippet).toBe('string');
+		});
+
+		it('forwards limit, responseLength, and country code', async () => {
+			searchMock.mockResolvedValueOnce({ results: [] });
+			await plugin.search(
+				opts({
+					limit: 7,
+					region: 'us',
+					settings: { apiKey: 'k', responseLength: 'large' }
+				})
+			);
+			expect(searchMock).toHaveBeenCalledWith(
+				'hello',
+				expect.objectContaining({
+					searchType: 'all',
+					maxNumResults: 7,
+					responseLength: 'large',
+					countryCode: 'US'
+				})
+			);
+		});
+
+		it('uses includedSources when includeDomains is set', async () => {
+			searchMock.mockResolvedValueOnce({ results: [] });
+			await plugin.search(opts({ includeDomains: ['a.com'] }));
+			expect(searchMock.mock.calls[0][1]).toMatchObject({ includedSources: ['a.com'] });
+		});
+
+		it('uses excludeSources when only excludeDomains is set', async () => {
+			searchMock.mockResolvedValueOnce({ results: [] });
+			await plugin.search(opts({ excludeDomains: ['b.com'] }));
+			expect(searchMock.mock.calls[0][1]).toMatchObject({ excludeSources: ['b.com'] });
+		});
+
+		it('translates timeRange into start/end ISO date strings', async () => {
+			searchMock.mockResolvedValueOnce({ results: [] });
+			await plugin.search(opts({ timeRange: 'week' }));
+			const call = searchMock.mock.calls[0][1];
+			expect(call.startDate).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+			expect(call.endDate).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+		});
+
+		it('skips date filters when timeRange is "all"', async () => {
+			searchMock.mockResolvedValueOnce({ results: [] });
+			await plugin.search(opts({ timeRange: 'all' }));
+			const call = searchMock.mock.calls[0][1];
+			expect(call.startDate).toBeUndefined();
+			expect(call.endDate).toBeUndefined();
+		});
+
+		it('logs and rethrows on SDK failure', async () => {
+			const ctx = buildContext();
+			await plugin.onLoad(ctx);
+			searchMock.mockRejectedValueOnce(new Error('boom'));
+			await expect(plugin.search(opts())).rejects.toThrow(/boom/);
+			expect(ctx.logger.error).toHaveBeenCalled();
+		});
+	});
+
+	describe('isAvailable', () => {
+		it('returns false without context', async () => {
+			expect(await plugin.isAvailable()).toBe(false);
+		});
+
+		it('reflects whether settings has an apiKey', async () => {
+			await plugin.onLoad(buildContext({ apiKey: 'k' }));
+			expect(await plugin.isAvailable()).toBe(true);
+
+			await plugin.onLoad(buildContext({}));
+			expect(await plugin.isAvailable()).toBe(false);
+		});
+	});
+
+	describe('validateConnection', () => {
+		it('fails fast without apiKey', async () => {
+			const r = await plugin.validateConnection({});
+			expect(r.success).toBe(false);
+			expect(r.message).toMatch(/not configured/i);
+		});
+
+		it('returns success when SDK search works', async () => {
+			searchMock.mockResolvedValueOnce({ results: [] });
+			const r = await plugin.validateConnection({ apiKey: 'k' });
+			expect(r.success).toBe(true);
+		});
+
+		it('returns failure when SDK search rejects', async () => {
+			searchMock.mockRejectedValueOnce(new Error('bad key'));
+			const r = await plugin.validateConnection({ apiKey: 'k' });
+			expect(r.success).toBe(false);
+			expect(r.message).toMatch(/bad key/);
+		});
+	});
+
+	describe('extract', () => {
+		const opts = (overrides: Partial<ContentExtractionOptions> = {}): ContentExtractionOptions => ({
+			url: 'https://example.com/post',
+			settings: { apiKey: 'k' },
+			...overrides
+		});
+
+		it('returns success with markdown and word count', async () => {
+			contentsMock.mockResolvedValueOnce({
+				results: [
+					{
+						url: 'https://example.com/post',
+						title: 'Title',
+						content: 'one two three'
+					}
+				]
+			});
+			const r = await plugin.extract(opts());
+			expect(r.success).toBe(true);
+			expect(r.title).toBe('Title');
+			expect(r.markdown).toBe('one two three');
+			expect(r.wordCount).toBe(3);
+		});
+
+		it('returns failure when no results are produced', async () => {
+			contentsMock.mockResolvedValueOnce({ results: [] });
+			const r = await plugin.extract(opts());
+			expect(r.success).toBe(false);
+			expect(r.error).toMatch(/No content extracted/);
+		});
+
+		it('returns failure when SDK throws', async () => {
+			contentsMock.mockRejectedValueOnce(new Error('extract failed'));
+			const r = await plugin.extract(opts());
+			expect(r.success).toBe(false);
+			expect(r.error).toMatch(/extract failed/);
+		});
+	});
+
+	describe('extractBatch', () => {
+		it('chunks URLs into batches of 10 and aggregates results', async () => {
+			const urls = Array.from({ length: 12 }, (_, i) => `https://example.com/${i}`);
+			contentsMock
+				.mockResolvedValueOnce({
+					results: urls.slice(0, 10).map((u) => ({ url: u, title: 't', content: 'a b' }))
+				})
+				.mockResolvedValueOnce({
+					results: urls.slice(10).map((u) => ({ url: u, title: 't', content: 'c d e' }))
+				});
+
+			const r = await plugin.extractBatch(urls, { settings: { apiKey: 'k' } });
+			expect(contentsMock).toHaveBeenCalledTimes(2);
+			expect(r).toHaveLength(12);
+			expect(r[0]).toMatchObject({ success: true, wordCount: 2 });
+			expect(r[10]).toMatchObject({ success: true, wordCount: 3 });
+		});
+
+		it('returns per-URL failures when the batch call throws', async () => {
+			contentsMock.mockRejectedValueOnce(new Error('batch failed'));
+			const r = await plugin.extractBatch(['https://a', 'https://b'], { settings: { apiKey: 'k' } });
+			expect(r).toHaveLength(2);
+			expect(r.every((x) => x.success === false)).toBe(true);
+		});
+	});
+
+	describe('canExtract / getSupportedFormats', () => {
+		it('accepts http and https URLs', async () => {
+			expect(await plugin.canExtract('https://example.com')).toBe(true);
+			expect(await plugin.canExtract('http://example.com')).toBe(true);
+		});
+
+		it('rejects non-http schemes and invalid URLs', async () => {
+			expect(await plugin.canExtract('ftp://example.com')).toBe(false);
+			expect(await plugin.canExtract('garbage')).toBe(false);
+		});
+
+		it('exposes text + markdown formats', () => {
+			expect(plugin.getSupportedFormats()).toEqual(['text', 'markdown']);
+		});
+	});
+
+	describe('lifecycle', () => {
+		it('logs on load and clears context on unload', async () => {
+			const ctx = buildContext();
+			await plugin.onLoad(ctx);
+			expect(ctx.logger.log).toHaveBeenCalledWith('Valyu Plugin loaded');
+			await plugin.onUnload();
+			expect(await plugin.isAvailable()).toBe(false);
+		});
+	});
+
+	describe('healthCheck + manifest', () => {
+		it('reports healthy', async () => {
+			const h = await plugin.healthCheck();
+			expect(h.status).toBe('healthy');
+		});
+
+		it('returns a manifest aligned with plugin metadata', () => {
+			const m = plugin.getManifest();
+			expect(m.id).toBe('valyu');
+			expect(m.category).toBe('search');
+			expect(m.capabilities).toEqual(['search', 'content-extractor']);
+			expect(m.builtIn).toBe(true);
+			expect(m.systemPlugin).toBe(false);
+			expect(m.autoEnable).toBe(false);
+		});
+	});
+});

package/src/index.ts

@@ -0,0 +1,2 @@
+export { ValyuSearchPlugin } from './valyu.plugin.js';
+export { ValyuSearchPlugin as default } from './valyu.plugin.js';