@ever-works/linkup-plugin 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,75 @@
1
+ # @ever-works/linkup-plugin
2
+
3
+ Linkup Plugin - Web search and content extraction using Linkup API
4
+
5
+ ## Plugin metadata
6
+
7
+ | Field | Value |
8
+ | ------------ | ----------------------------- |
9
+ | ID | `linkup` |
10
+ | Category | `search` |
11
+ | Capabilities | `search`, `content-extractor` |
12
+ | Author | Ever Works Team |
13
+ | License | AGPL-3.0 |
14
+ | Built-in | yes |
15
+ | Auto-enable | no |
16
+
17
+ ## What does Linkup do?
18
+
19
+ Linkup connects AI applications to the internet, providing grounding data to enrich AI output with precision and factuality. It searches the web for relevant content and extracts clean markdown from any URL.
20
+
21
+ ## Why use it?
22
+
23
+ - **High precision search** — optimized for factual grounding of LLM responses
24
+ - **Deep search mode** — iterative search for comprehensive results when needed
25
+ - **Content extraction** — fetches clean markdown from any webpage via the /fetch endpoint
26
+ - **Domain filtering** — include or exclude specific websites from search results
27
+
28
+ ## How it works in Ever Works
29
+
30
+ During work generation, the search facade uses Linkup 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.
31
+
32
+ ## Getting started
33
+
34
+ 1. Create an account at [linkup.so](https://linkup.so)
35
+ 2. Copy your API key from the Linkup dashboard
36
+ 3. Enter the key in the **API Key** field below
37
+ 4. Linkup will be available for use during work generation
38
+
39
+ ## Settings
40
+
41
+ - **API Key** (`apiKey`) — required, secret. Your Linkup API key (also configurable via the `PLUGIN_LINKUP_API_KEY` environment variable).
42
+ - Stored at user scope so each user can supply their own credentials.
43
+ - Configuration mode is `hybrid` — admins can preset values and users may override them.
44
+
45
+ ## Troubleshooting
46
+
47
+ | Symptom | Likely cause | Fix |
48
+ | -------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
49
+ | `401 Unauthorized` / `Authentication failed` | API key missing, revoked, or wrong key entered | Re-enter the **API Key** from the Linkup dashboard, or set `PLUGIN_LINKUP_API_KEY` in the host environment for default fallback |
50
+ | `429 Too Many Requests` | Free-tier or paid quota exhausted on Linkup | Throttle calls, wait for the quota reset, or upgrade the plan in the Linkup dashboard |
51
+ | 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` |
52
+ | Plugin not used during work generation | Another search plugin is set as the default for the `search` capability | In **Settings → Plugins**, set `linkup` as the default for `search`, or disable competing search plugins |
53
+ | `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`) |
54
+ | `healthCheck` reports unhealthy | API key invalid OR Linkup 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 |
55
+
56
+ ## Local development
57
+
58
+ This plugin ships built-in with the Ever Works platform. To work on it locally from the monorepo root:
59
+
60
+ ```bash
61
+ pnpm install
62
+ pnpm --filter @ever-works/linkup-plugin build
63
+ pnpm --filter @ever-works/linkup-plugin test
64
+ ```
65
+
66
+ ## Documentation
67
+
68
+ - [Ever Works documentation](https://docs.ever.works)
69
+ - [Ever Works repository](https://github.com/ever-works/ever-works)
70
+ - [Plugin system](../../plugin/README.md)
71
+ - [Linkup homepage](https://linkup.so)
72
+
73
+ ## License
74
+
75
+ AGPL-3.0
package/package.json ADDED
@@ -0,0 +1,76 @@
1
+ {
2
+ "name": "@ever-works/linkup-plugin",
3
+ "version": "1.0.0",
4
+ "description": "Linkup Plugin - Web search and content extraction using Linkup API",
5
+ "author": {
6
+ "name": "Ever Co. LTD",
7
+ "email": "ever@ever.co",
8
+ "url": "https://ever.co"
9
+ },
10
+ "license": "AGPL-3.0",
11
+ "private": false,
12
+ "type": "module",
13
+ "main": "./dist/index.cjs",
14
+ "module": "./dist/index.js",
15
+ "types": "./dist/index.d.ts",
16
+ "exports": {
17
+ ".": {
18
+ "types": "./dist/index.d.ts",
19
+ "import": "./dist/index.js",
20
+ "require": "./dist/index.cjs"
21
+ }
22
+ },
23
+ "peerDependencies": {
24
+ "@ever-works/plugin": "1.1.0"
25
+ },
26
+ "devDependencies": {
27
+ "@types/node": "^22.0.0",
28
+ "tsup": "^8.4.0",
29
+ "typescript": "^5.7.3",
30
+ "vitest": "^4.1.0",
31
+ "@ever-works/plugin": "1.1.0"
32
+ },
33
+ "everworks": {
34
+ "plugin": {
35
+ "id": "linkup",
36
+ "name": "Linkup",
37
+ "version": "1.0.0",
38
+ "category": "search",
39
+ "capabilities": [
40
+ "search",
41
+ "content-extractor"
42
+ ],
43
+ "description": "Web search and content extraction using Linkup API. Search the web with AI-optimized precision and extract clean content from any URL.",
44
+ "author": {
45
+ "name": "Ever Works Team"
46
+ },
47
+ "license": "AGPL-3.0",
48
+ "autoEnable": false,
49
+ "defaultForCapabilities": [],
50
+ "systemPlugin": false,
51
+ "builtIn": true,
52
+ "envVars": [
53
+ {
54
+ "name": "PLUGIN_LINKUP_API_KEY",
55
+ "required": false,
56
+ "secret": true,
57
+ "description": "Linkup API key (optional - can be set via admin/user settings)"
58
+ }
59
+ ],
60
+ "distribution": "registry"
61
+ }
62
+ },
63
+ "publishConfig": {
64
+ "access": "restricted",
65
+ "registry": "https://registry.npmjs.org"
66
+ },
67
+ "scripts": {
68
+ "build": "tsc --noEmit && tsup",
69
+ "dev": "tsup --watch",
70
+ "type-check": "tsc --noEmit",
71
+ "clean": "rm -rf dist",
72
+ "test": "vitest run --passWithNoTests",
73
+ "test:watch": "vitest",
74
+ "test:coverage": "vitest run --coverage"
75
+ }
76
+ }
@@ -0,0 +1,297 @@
1
+ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
2
+ import { LinkupSearchPlugin } from '../linkup.plugin.js';
3
+ import type { PluginContext, SearchOptions, ContentExtractionOptions } from '@ever-works/plugin';
4
+
5
+ const buildContext = (settings: Record<string, unknown> = {}): PluginContext =>
6
+ ({
7
+ pluginId: 'linkup',
8
+ logger: {
9
+ log: vi.fn(),
10
+ debug: vi.fn(),
11
+ warn: vi.fn(),
12
+ error: vi.fn()
13
+ },
14
+ getSettings: vi.fn().mockResolvedValue(settings)
15
+ }) as unknown as PluginContext;
16
+
17
+ const okResponse = (body: unknown): Response =>
18
+ ({
19
+ ok: true,
20
+ status: 200,
21
+ json: () => Promise.resolve(body),
22
+ text: () => Promise.resolve(JSON.stringify(body))
23
+ }) as unknown as Response;
24
+
25
+ const errResponse = (status: number, body = 'error'): Response =>
26
+ ({
27
+ ok: false,
28
+ status,
29
+ json: () => Promise.resolve({ error: body }),
30
+ text: () => Promise.resolve(body)
31
+ }) as unknown as Response;
32
+
33
+ describe('LinkupSearchPlugin', () => {
34
+ let plugin: LinkupSearchPlugin;
35
+ let fetchMock: ReturnType<typeof vi.fn>;
36
+ const originalFetch = globalThis.fetch;
37
+
38
+ beforeEach(() => {
39
+ plugin = new LinkupSearchPlugin();
40
+ fetchMock = vi.fn();
41
+ globalThis.fetch = fetchMock as unknown as typeof fetch;
42
+ });
43
+
44
+ afterEach(() => {
45
+ globalThis.fetch = originalFetch;
46
+ vi.clearAllMocks();
47
+ });
48
+
49
+ describe('metadata', () => {
50
+ it('exposes stable identity fields', () => {
51
+ expect(plugin.id).toBe('linkup');
52
+ expect(plugin.name).toBe('Linkup');
53
+ expect(plugin.category).toBe('search');
54
+ expect(plugin.providerName).toBe('Linkup');
55
+ expect(plugin.version).toBe('1.0.0');
56
+ });
57
+
58
+ it('declares both search and content-extractor capabilities', () => {
59
+ expect(plugin.capabilities).toEqual(['search', 'content-extractor']);
60
+ });
61
+
62
+ it('uses hybrid configuration mode', () => {
63
+ expect(plugin.configurationMode).toBe('hybrid');
64
+ });
65
+ });
66
+
67
+ describe('settingsSchema', () => {
68
+ it('requires apiKey and marks it as a user-scoped secret', () => {
69
+ expect(plugin.settingsSchema.required).toContain('apiKey');
70
+ const props = plugin.settingsSchema.properties as Record<string, Record<string, unknown>>;
71
+ expect(props.apiKey['x-secret']).toBe(true);
72
+ expect(props.apiKey['x-scope']).toBe('user');
73
+ expect(props.apiKey['x-envVar']).toBe('PLUGIN_LINKUP_API_KEY');
74
+ });
75
+ });
76
+
77
+ describe('search', () => {
78
+ const opts = (overrides: Partial<SearchOptions> = {}): SearchOptions => ({
79
+ query: 'hello',
80
+ settings: { apiKey: 'k' },
81
+ ...overrides
82
+ });
83
+
84
+ it('throws when apiKey is missing', async () => {
85
+ await expect(plugin.search({ query: 'hello', settings: {} })).rejects.toThrow(/API key not configured/i);
86
+ expect(fetchMock).not.toHaveBeenCalled();
87
+ });
88
+
89
+ it('returns mapped results from data.results on success', async () => {
90
+ fetchMock.mockResolvedValueOnce(
91
+ okResponse({
92
+ results: [
93
+ { name: 'Result A', url: 'https://a.example', content: 'snippet a' },
94
+ { name: 'Result B', url: 'https://b.example', content: 'snippet b' }
95
+ ]
96
+ })
97
+ );
98
+ const r = await plugin.search(opts());
99
+ expect(r.results).toHaveLength(2);
100
+ expect(r.results[0]).toMatchObject({
101
+ title: 'Result A',
102
+ url: 'https://a.example',
103
+ snippet: 'snippet a',
104
+ position: 1
105
+ });
106
+ expect(r.totalResults).toBe(2);
107
+ expect(r.hasMore).toBe(false);
108
+ expect(typeof r.duration).toBe('number');
109
+ });
110
+
111
+ it('falls back to data.sources when results is missing', async () => {
112
+ fetchMock.mockResolvedValueOnce(
113
+ okResponse({
114
+ sources: [{ name: 'Source A', url: 'https://s.example', snippet: 'src snippet' }]
115
+ })
116
+ );
117
+ const r = await plugin.search(opts());
118
+ expect(r.results).toHaveLength(1);
119
+ expect(r.results[0]).toMatchObject({
120
+ title: 'Source A',
121
+ url: 'https://s.example',
122
+ snippet: 'src snippet'
123
+ });
124
+ });
125
+
126
+ it('forwards Bearer apiKey and JSON body with includeDomains/excludeDomains', async () => {
127
+ fetchMock.mockResolvedValueOnce(okResponse({ results: [] }));
128
+ await plugin.search(
129
+ opts({
130
+ includeDomains: ['a.com'],
131
+ excludeDomains: ['b.com']
132
+ })
133
+ );
134
+ const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
135
+ expect(url).toBe('https://api.linkup.so/v1/search');
136
+ expect(init.method).toBe('POST');
137
+ expect((init.headers as Record<string, string>).Authorization).toBe('Bearer k');
138
+ const body = JSON.parse(init.body as string);
139
+ expect(body.q).toBe('hello');
140
+ expect(body.depth).toBe('deep');
141
+ expect(body.outputType).toBe('searchResults');
142
+ expect(body.includeDomains).toEqual(['a.com']);
143
+ expect(body.excludeDomains).toEqual(['b.com']);
144
+ });
145
+
146
+ it('throws and logs when the upstream returns non-OK', async () => {
147
+ await plugin.onLoad(buildContext());
148
+ fetchMock.mockResolvedValueOnce(errResponse(500, 'oops'));
149
+ await expect(plugin.search(opts())).rejects.toThrow(/Linkup search failed with status 500/);
150
+ });
151
+ });
152
+
153
+ describe('isAvailable', () => {
154
+ it('returns false without context', async () => {
155
+ expect(await plugin.isAvailable()).toBe(false);
156
+ });
157
+
158
+ it('reflects whether settings has an apiKey', async () => {
159
+ await plugin.onLoad(buildContext({ apiKey: 'k' }));
160
+ expect(await plugin.isAvailable()).toBe(true);
161
+
162
+ await plugin.onLoad(buildContext({}));
163
+ expect(await plugin.isAvailable()).toBe(false);
164
+ });
165
+ });
166
+
167
+ describe('validateConnection', () => {
168
+ it('fails fast without an apiKey', async () => {
169
+ const r = await plugin.validateConnection({});
170
+ expect(r.success).toBe(false);
171
+ expect(r.message).toMatch(/not configured/i);
172
+ expect(fetchMock).not.toHaveBeenCalled();
173
+ });
174
+
175
+ it('returns success on a 200 response', async () => {
176
+ fetchMock.mockResolvedValueOnce(okResponse({ results: [] }));
177
+ const r = await plugin.validateConnection({ apiKey: 'k' });
178
+ expect(r.success).toBe(true);
179
+ });
180
+
181
+ it('returns failure on a non-OK response', async () => {
182
+ fetchMock.mockResolvedValueOnce(errResponse(401, 'unauthorized'));
183
+ const r = await plugin.validateConnection({ apiKey: 'k' });
184
+ expect(r.success).toBe(false);
185
+ expect(r.message).toMatch(/401/);
186
+ });
187
+
188
+ it('returns failure when fetch throws', async () => {
189
+ fetchMock.mockRejectedValueOnce(new Error('network down'));
190
+ const r = await plugin.validateConnection({ apiKey: 'k' });
191
+ expect(r.success).toBe(false);
192
+ expect(r.message).toMatch(/network down/);
193
+ });
194
+ });
195
+
196
+ describe('getRateLimitInfo', () => {
197
+ it('reports the documented Linkup rate limit', async () => {
198
+ const info = await plugin.getRateLimitInfo();
199
+ expect(info.remaining).toBe(-1);
200
+ expect(info.limit).toBe(10);
201
+ expect(info.period).toBe('second');
202
+ });
203
+ });
204
+
205
+ describe('extract', () => {
206
+ const opts = (overrides: Partial<ContentExtractionOptions> = {}): ContentExtractionOptions => ({
207
+ url: 'https://example.com/post',
208
+ settings: { apiKey: 'k' },
209
+ ...overrides
210
+ });
211
+
212
+ it('returns success with markdown and word count', async () => {
213
+ fetchMock.mockResolvedValueOnce(okResponse({ markdown: 'one two three' }));
214
+ const r = await plugin.extract(opts());
215
+ expect(r.success).toBe(true);
216
+ expect(r.url).toBe('https://example.com/post');
217
+ expect(r.markdown).toBe('one two three');
218
+ expect(r.wordCount).toBe(3);
219
+ });
220
+
221
+ it('returns failure when markdown is missing', async () => {
222
+ fetchMock.mockResolvedValueOnce(okResponse({}));
223
+ const r = await plugin.extract(opts());
224
+ expect(r.success).toBe(false);
225
+ expect(r.error).toMatch(/No content extracted/);
226
+ });
227
+
228
+ it('returns failure on a non-OK fetch response', async () => {
229
+ fetchMock.mockResolvedValueOnce(errResponse(503, 'unavailable'));
230
+ const r = await plugin.extract(opts());
231
+ expect(r.success).toBe(false);
232
+ expect(r.error).toMatch(/Linkup fetch failed with status 503/);
233
+ });
234
+
235
+ it('returns failure when fetch throws', async () => {
236
+ fetchMock.mockRejectedValueOnce(new Error('boom'));
237
+ const r = await plugin.extract(opts());
238
+ expect(r.success).toBe(false);
239
+ expect(r.error).toMatch(/boom/);
240
+ });
241
+ });
242
+
243
+ describe('extractBatch', () => {
244
+ it('runs each URL through extract', async () => {
245
+ fetchMock
246
+ .mockResolvedValueOnce(okResponse({ markdown: 'a' }))
247
+ .mockResolvedValueOnce(okResponse({ markdown: 'b' }));
248
+ const r = await plugin.extractBatch(['https://a', 'https://b'], { settings: { apiKey: 'k' } });
249
+ expect(r).toHaveLength(2);
250
+ expect(r[0].success).toBe(true);
251
+ expect(r[1].success).toBe(true);
252
+ });
253
+ });
254
+
255
+ describe('canExtract / getSupportedFormats', () => {
256
+ it('accepts http and https URLs', async () => {
257
+ expect(await plugin.canExtract('https://example.com')).toBe(true);
258
+ expect(await plugin.canExtract('http://example.com')).toBe(true);
259
+ });
260
+
261
+ it('rejects non-http schemes and invalid URLs', async () => {
262
+ expect(await plugin.canExtract('ftp://example.com')).toBe(false);
263
+ expect(await plugin.canExtract('not a url')).toBe(false);
264
+ });
265
+
266
+ it('exposes text + markdown formats', () => {
267
+ expect(plugin.getSupportedFormats()).toEqual(['text', 'markdown']);
268
+ });
269
+ });
270
+
271
+ describe('lifecycle', () => {
272
+ it('logs on load and clears context on unload', async () => {
273
+ const ctx = buildContext();
274
+ await plugin.onLoad(ctx);
275
+ expect(ctx.logger.log).toHaveBeenCalledWith('Linkup Plugin loaded');
276
+ await plugin.onUnload();
277
+ expect(await plugin.isAvailable()).toBe(false);
278
+ });
279
+ });
280
+
281
+ describe('healthCheck + manifest', () => {
282
+ it('reports healthy', async () => {
283
+ const h = await plugin.healthCheck();
284
+ expect(h.status).toBe('healthy');
285
+ });
286
+
287
+ it('returns a manifest aligned with plugin metadata', () => {
288
+ const m = plugin.getManifest();
289
+ expect(m.id).toBe('linkup');
290
+ expect(m.category).toBe('search');
291
+ expect(m.capabilities).toEqual(['search', 'content-extractor']);
292
+ expect(m.builtIn).toBe(true);
293
+ expect(m.systemPlugin).toBe(false);
294
+ expect(m.autoEnable).toBe(false);
295
+ });
296
+ });
297
+ });
package/src/index.ts ADDED
@@ -0,0 +1,2 @@
1
+ export { LinkupSearchPlugin } from './linkup.plugin.js';
2
+ export { LinkupSearchPlugin as default } from './linkup.plugin.js';