@ever-works/jina-plugin 1.0.0

package/README.md

@@ -0,0 +1,71 @@
+# @ever-works/jina-plugin
+
+Jina AI Plugin - Web search and content extraction using Jina AI APIs
+
+## Plugin metadata
+
+| Field        | Value                         |
+| ------------ | ----------------------------- |
+| ID           | `jina`                        |
+| Category     | `content-extractor`           |
+| Capabilities | `search`, `content-extractor` |
+| Author       | Ever Works Team               |
+| License      | AGPL-3.0                      |
+| Built-in     | yes                           |
+| Auto-enable  | no                            |
+
+## What does Jina AI do?
+
+Jina AI provides web search with LLM-optimized results and content extraction that converts any web page into clean markdown.
+
+## Why use it?
+
+- **Web search** — search the web and get results with content already extracted
+- **Content extraction** — converts pages to clean markdown, strips ads and navigation
+- **Domain filtering** — restrict search to specific domains
+
+## How it works in Ever Works
+
+During work generation, Jina finds relevant information about each item via search and extracts clean content from web pages for enriching descriptions.
+
+## Getting started
+
+1. Get an API key at [jina.ai](https://jina.ai)
+2. Enter the key in the **API Key** field below
+3. Enable the plugin
+
+## Settings
+
+- **API Key** (`apiKey`) — required, secret. Your Jina API key (also configurable via the `PLUGIN_JINA_API_KEY` environment variable).
+- 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` / `403` from the extractor               | API key / token missing or revoked                                                               | Re-enter the credential from the Jina AI dashboard, or set `PLUGIN_JINA_API_KEY` in the host environment for default fallback                                             |
+| `Failed to extract content` for a specific URL | Page requires authentication, JavaScript rendering, or a custom client (Notion, PDF, login wall) | Verify the URL is publicly reachable; if it requires JavaScript/auth, switch to a more capable extractor (`scrapfly` / `notion-extractor` / `pdf-extractor`) for that URL |
+| Plugin not used during extraction              | Another content-extractor plugin is set as the default                                           | In **Settings → Plugins**, set `jina` as the default for `content-extractor`, or disable competing plugins                                                                |
+| `healthCheck` reports unhealthy                | Credential invalid OR Jina AI endpoint unreachable from the host                                 | Verify the credential with a manual call to the upstream API 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/jina-plugin build
+pnpm --filter @ever-works/jina-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)
+- [Jina AI homepage](https://jina.ai)
+
+## License
+
+AGPL-3.0

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@ever-works/jina-plugin",
+  "version": "1.0.0",
+  "description": "Jina AI Plugin - Web search and content extraction using Jina AI APIs",
+  "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"
+    }
+  },
+  "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": "jina",
+      "name": "Jina AI",
+      "version": "1.0.0",
+      "category": "content-extractor",
+      "capabilities": [
+        "search",
+        "content-extractor"
+      ],
+      "description": "Web search and content extraction using Jina AI APIs. Search via s.jina.ai and extract content via r.jina.ai, no SDK needed.",
+      "author": {
+        "name": "Ever Works Team"
+      },
+      "license": "AGPL-3.0",
+      "autoEnable": false,
+      "systemPlugin": false,
+      "builtIn": true,
+      "envVars": [
+        {
+          "name": "PLUGIN_JINA_API_KEY",
+          "required": true,
+          "secret": true,
+          "description": "Jina API key"
+        }
+      ],
+      "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__/jina.plugin.spec.ts

@@ -0,0 +1,318 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { JinaReaderPlugin } from '../jina.plugin.js';
+import type { PluginContext, SearchOptions, ContentExtractionOptions } from '@ever-works/plugin';
+
+const buildContext = (settings: Record<string, unknown> = {}): PluginContext =>
+	({
+		pluginId: 'jina',
+		logger: {
+			log: vi.fn(),
+			debug: vi.fn(),
+			warn: vi.fn(),
+			error: vi.fn()
+		},
+		getSettings: vi.fn().mockResolvedValue(settings)
+	}) as unknown as PluginContext;
+
+const okResponse = (body: unknown): Response =>
+	({
+		ok: true,
+		status: 200,
+		statusText: 'OK',
+		json: () => Promise.resolve(body),
+		text: () => Promise.resolve(JSON.stringify(body))
+	}) as unknown as Response;
+
+const errResponse = (status: number, statusText = 'error'): Response =>
+	({
+		ok: false,
+		status,
+		statusText,
+		json: () => Promise.resolve({}),
+		text: () => Promise.resolve(statusText)
+	}) as unknown as Response;
+
+describe('JinaReaderPlugin', () => {
+	let plugin: JinaReaderPlugin;
+	let fetchMock: ReturnType<typeof vi.fn>;
+	const originalFetch = globalThis.fetch;
+
+	beforeEach(() => {
+		plugin = new JinaReaderPlugin();
+		fetchMock = vi.fn();
+		globalThis.fetch = fetchMock as unknown as typeof fetch;
+	});
+
+	afterEach(() => {
+		globalThis.fetch = originalFetch;
+		vi.clearAllMocks();
+	});
+
+	describe('metadata', () => {
+		it('exposes stable identity fields', () => {
+			expect(plugin.id).toBe('jina');
+			expect(plugin.name).toBe('Jina AI');
+			expect(plugin.version).toBe('1.0.0');
+			expect(plugin.category).toBe('content-extractor');
+			expect(plugin.providerName).toBe('Jina');
+		});
+
+		it('declares both search and content-extractor capabilities', () => {
+			expect(plugin.capabilities).toEqual(['search', 'content-extractor']);
+		});
+	});
+
+	describe('settingsSchema', () => {
+		it('requires apiKey and marks it as user-scoped secret', () => {
+			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_JINA_API_KEY');
+		});
+	});
+
+	describe('search', () => {
+		const opts = (overrides: Partial<SearchOptions> = {}): SearchOptions => ({
+			query: 'hello',
+			settings: { apiKey: 'k' },
+			...overrides
+		});
+
+		it('returns mapped results with derived hostname source', async () => {
+			fetchMock.mockResolvedValueOnce(
+				okResponse({
+					data: [
+						{
+							title: 'Example',
+							url: 'https://www.example.com/post',
+							description: 'snippet here',
+							date: '2026-01-01'
+						}
+					]
+				})
+			);
+
+			const r = await plugin.search(opts({ limit: 5, region: 'us', language: 'en' }));
+
+			expect(r.results).toHaveLength(1);
+			expect(r.results[0]).toMatchObject({
+				title: 'Example',
+				url: 'https://www.example.com/post',
+				snippet: 'snippet here',
+				position: 1,
+				publishedDate: '2026-01-01',
+				source: 'www.example.com'
+			});
+
+			const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+			expect(url).toBe('https://s.jina.ai/');
+			expect(init.method).toBe('POST');
+			expect((init.headers as Record<string, string>).Authorization).toBe('Bearer k');
+			const body = JSON.parse(init.body as string);
+			expect(body.q).toBe('hello');
+			expect(body.num).toBe(5);
+			expect(body.gl).toBe('us');
+			expect(body.hl).toBe('en');
+		});
+
+		it('forwards X-Site header for the first includeDomain', async () => {
+			fetchMock.mockResolvedValueOnce(okResponse({ data: [] }));
+			await plugin.search(opts({ includeDomains: ['a.com', 'b.com'] }));
+			const init = fetchMock.mock.calls[0][1] as RequestInit;
+			expect((init.headers as Record<string, string>)['X-Site']).toBe('a.com');
+		});
+
+		it('handles missing data array safely', async () => {
+			fetchMock.mockResolvedValueOnce(okResponse({}));
+			const r = await plugin.search(opts());
+			expect(r.results).toEqual([]);
+			expect(r.totalResults).toBe(0);
+		});
+
+		it('throws and logs on non-OK upstream', async () => {
+			await plugin.onLoad(buildContext());
+			fetchMock.mockResolvedValueOnce(errResponse(503, 'Service Unavailable'));
+			await expect(plugin.search(opts())).rejects.toThrow(/Jina Search API returned 503/);
+		});
+	});
+
+	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);
+			expect(fetchMock).not.toHaveBeenCalled();
+		});
+
+		it('returns success on a 200 response', async () => {
+			fetchMock.mockResolvedValueOnce(okResponse({ data: [] }));
+			const r = await plugin.validateConnection({ apiKey: 'k' });
+			expect(r.success).toBe(true);
+		});
+
+		it('returns failure on a non-OK response', async () => {
+			fetchMock.mockResolvedValueOnce(errResponse(401, 'Unauthorized'));
+			const r = await plugin.validateConnection({ apiKey: 'k' });
+			expect(r.success).toBe(false);
+			expect(r.message).toMatch(/401/);
+		});
+
+		it('returns failure when fetch throws', async () => {
+			fetchMock.mockRejectedValueOnce(new Error('boom'));
+			const r = await plugin.validateConnection({ apiKey: 'k' });
+			expect(r.success).toBe(false);
+			expect(r.message).toMatch(/boom/);
+		});
+	});
+
+	describe('extract', () => {
+		const opts = (overrides: Partial<ContentExtractionOptions> = {}): ContentExtractionOptions => ({
+			url: 'https://example.com/post',
+			settings: { apiKey: 'k' },
+			...overrides
+		});
+
+		it('returns success with title, content, images, links, metadata, wordCount, readingTime', async () => {
+			fetchMock.mockResolvedValueOnce(
+				okResponse({
+					data: {
+						title: 'Title',
+						url: 'https://example.com/post',
+						content: 'one two three four five',
+						description: 'desc',
+						publishedTime: '2026-01-01',
+						images: { 'alt one': 'https://img/1.png' },
+						links: { 'link one': 'https://target.example' },
+						metadata: { lang: 'en' }
+					}
+				})
+			);
+
+			const r = await plugin.extract(opts());
+			expect(r.success).toBe(true);
+			expect(r.title).toBe('Title');
+			expect(r.markdown).toBe('one two three four five');
+			expect(r.wordCount).toBe(5);
+			expect(r.readingTime).toBe(1);
+			expect(r.images).toHaveLength(1);
+			expect(r.images?.[0]).toMatchObject({ src: 'https://img/1.png', alt: 'alt one' });
+			expect(r.links?.[0]).toMatchObject({ href: 'https://target.example', text: 'link one' });
+			expect(r.metadata).toMatchObject({
+				description: 'desc',
+				publishedDate: '2026-01-01',
+				language: 'en'
+			});
+		});
+
+		it('exposes finalUrl when SDK returns a different URL', async () => {
+			fetchMock.mockResolvedValueOnce(
+				okResponse({
+					data: {
+						title: 't',
+						url: 'https://example.com/redirected',
+						content: 'hi'
+					}
+				})
+			);
+			const r = await plugin.extract(opts());
+			expect(r.finalUrl).toBe('https://example.com/redirected');
+		});
+
+		it('returns failure when content is missing', async () => {
+			fetchMock.mockResolvedValueOnce(okResponse({ data: { title: 't', url: 'u' } }));
+			const r = await plugin.extract(opts());
+			expect(r.success).toBe(false);
+			expect(r.error).toMatch(/No content/);
+		});
+
+		it('returns failure when upstream returns non-OK', async () => {
+			fetchMock.mockResolvedValueOnce(errResponse(429, 'Too Many Requests'));
+			const r = await plugin.extract(opts());
+			expect(r.success).toBe(false);
+			expect(r.error).toMatch(/429/);
+		});
+
+		it('omits images when includeImages is false', async () => {
+			fetchMock.mockResolvedValueOnce(
+				okResponse({
+					data: {
+						title: 't',
+						url: 'u',
+						content: 'hi',
+						images: { foo: 'https://i' }
+					}
+				})
+			);
+			const r = await plugin.extract(opts({ includeImages: false }));
+			expect(r.images).toBeUndefined();
+		});
+	});
+
+	describe('extractBatch', () => {
+		it('chunks URLs into batches of 5', async () => {
+			const urls = Array.from({ length: 7 }, (_, i) => `https://example.com/${i}`);
+			for (const u of urls) {
+				fetchMock.mockResolvedValueOnce(okResponse({ data: { title: 't', url: u, content: 'a b' } }));
+			}
+			const r = await plugin.extractBatch(urls, { settings: { apiKey: 'k' } });
+			expect(r).toHaveLength(7);
+			expect(r.every((x) => x.success === true)).toBe(true);
+			expect(fetchMock).toHaveBeenCalledTimes(7);
+		});
+	});
+
+	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('Jina AI Reader 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('jina');
+			expect(m.category).toBe('content-extractor');
+			expect(m.capabilities).toEqual(['search', 'content-extractor']);
+			expect(m.builtIn).toBe(true);
+		});
+	});
+});

package/src/index.ts

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