@ever-works/urlbox-plugin 1.0.0

package/README.md

@@ -0,0 +1,80 @@
+# @ever-works/urlbox-plugin
+
+Urlbox screenshot plugin for Ever Works - capture website screenshots using the Urlbox Screenshot API
+
+## Plugin metadata
+
+| Field        | Value           |
+| ------------ | --------------- |
+| ID           | `urlbox`        |
+| Category     | `screenshot`    |
+| Capabilities | `screenshot`    |
+| Author       | Ever Works Team |
+| License      | AGPL-3.0        |
+| Built-in     | no              |
+| Auto-enable  | no              |
+
+## What does Urlbox do?
+
+Urlbox is a screenshot capture API. When work items include source URLs, this plugin automatically generates preview images by capturing a screenshot of each page.
+
+## Why use it?
+
+- **Automated capture** — preview images are generated for each work item without manual effort
+- **Consistent output** — every screenshot uses the same viewport size, format, and rendering settings
+- **Ad and cookie banner blocking** — captures clean screenshots free of ads and cookie banners
+- **Retina rendering** — supports HiDPI output for crisp images on high-resolution displays
+- **Multiple formats** — supports PNG, JPG, and WebP output with configurable quality
+
+## How it works in Ever Works
+
+During work generation, the screenshot facade sends capture requests to Urlbox for items that have a source URL. The resulting images are used as item preview thumbnails. You can configure viewport dimensions, image format, quality, retina rendering, and ad/cookie blocking behavior.
+
+## Getting started
+
+1. Sign up at [urlbox.com](https://urlbox.com)
+2. Copy your API key and API secret
+3. Enable the Urlbox plugin on this page
+4. Enter your credentials in the settings below
+
+## Settings
+
+- **API Key** (required, secret) — your Urlbox API key; falls back to `PLUGIN_URLBOX_API_KEY`.
+- **API Secret** (secret) — used to generate signed render links; falls back to `PLUGIN_URLBOX_API_SECRET`.
+- **Viewport Width / Height** — default capture viewport in pixels (defaults: 1280 x 1024).
+- **Image Format** — output format: `png`, `jpg`, `jpeg`, or `webp` (default: `png`).
+- **Image Quality** — quality for lossy formats, range 1–100 (default: 80).
+- **Retina** — enable HiDPI rendering at 2x device scale factor (default: off).
+- **Block Ads** — strip ads from captured pages (default: on).
+- **Hide Cookie Banners** — remove cookie consent banners (default: on).
+
+## Troubleshooting
+
+| Symptom                                    | Likely cause                                                                                     | Fix                                                                                                                                                  |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `401` / `Authentication failed`            | API key (or signing secret) missing or wrong                                                     | Re-enter the credential(s) from the Urlbox dashboard, or set `PLUGIN_URLBOX_API_KEY` (and signing-secret env var if applicable) for default fallback |
+| Black / blank / `null` `imageUrl` returned | Target page failed to render within the configured timeout, or is blocked by anti-bot protection | Increase the timeout, enable wait-for-network-idle / `full_page` mode, or set a custom `user_agent` and `viewport`                                   |
+| Plugin not used for screenshot capture     | Another screenshot plugin is set as the default                                                  | In **Settings → Plugins**, set `urlbox` as the default for `screenshot`, or disable competing plugins                                                |
+| Quota exhausted / `429`                    | Monthly / per-minute screenshot cap reached on Urlbox                                            | Throttle calls, wait for the quota reset, or upgrade the plan in the Urlbox dashboard                                                                |
+| `healthCheck` reports unhealthy            | Credential invalid OR Urlbox 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/urlbox-plugin build
+pnpm --filter @ever-works/urlbox-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)
+- [Urlbox homepage](https://urlbox.com)
+
+## License
+
+AGPL-3.0

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@ever-works/urlbox-plugin",
+  "version": "1.0.0",
+  "description": "Urlbox screenshot plugin for Ever Works - capture website screenshots using the Urlbox Screenshot API",
+  "author": {
+    "name": "Ever Co. LTD",
+    "email": "ever@ever.co",
+    "url": "https://ever.co"
+  },
+  "license": "AGPL-3.0",
+  "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": {
+    "urlbox": "^2.2.0"
+  },
+  "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": "urlbox",
+      "name": "Urlbox",
+      "version": "1.0.0",
+      "category": "screenshot",
+      "capabilities": [
+        "screenshot"
+      ],
+      "description": "Capture website screenshots using the Urlbox Screenshot API. Supports configurable viewport sizes, formats, retina rendering, and advanced options like ad blocking and cookie banner removal.",
+      "author": {
+        "name": "Ever Works Team"
+      },
+      "license": "AGPL-3.0",
+      "systemPlugin": false,
+      "builtIn": false,
+      "envVars": [
+        {
+          "name": "PLUGIN_URLBOX_API_KEY",
+          "required": false,
+          "secret": true,
+          "description": "Urlbox API key (optional - can be set via admin/user settings)"
+        },
+        {
+          "name": "PLUGIN_URLBOX_API_SECRET",
+          "required": false,
+          "secret": true,
+          "description": "Urlbox API secret for signed render links (optional - can be set via admin/user settings)"
+        }
+      ],
+      "distribution": "registry"
+    }
+  },
+  "private": false,
+  "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__/urlbox.plugin.spec.ts

@@ -0,0 +1,353 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { UrlboxPlugin } from '../urlbox.plugin.js';
+import type { PluginContext, ScreenshotOptions } from '@ever-works/plugin';
+
+// Mock the urlbox module
+// urlbox exports a factory function: Urlbox(apiKey, apiSecret) => { generateRenderLink(options) }
+vi.mock('urlbox', () => {
+	const mockGenerateRenderLink = vi
+		.fn()
+		.mockReturnValue('https://api.urlbox.com/v1/render?url=https%3A%2F%2Fexample.com&width=1280');
+
+	const mockUrlboxFactory = vi.fn().mockReturnValue({
+		generateRenderLink: mockGenerateRenderLink
+	});
+
+	return {
+		default: mockUrlboxFactory
+	};
+});
+
+// Mock global fetch
+const mockFetchResponse = {
+	ok: true,
+	status: 200,
+	arrayBuffer: vi.fn().mockResolvedValue(new ArrayBuffer(100))
+};
+
+vi.stubGlobal('fetch', vi.fn().mockResolvedValue(mockFetchResponse));
+
+describe('UrlboxPlugin', () => {
+	let plugin: UrlboxPlugin;
+	let mockContext: PluginContext;
+
+	beforeEach(() => {
+		plugin = new UrlboxPlugin();
+		mockContext = {
+			pluginId: 'urlbox',
+			logger: {
+				log: vi.fn(),
+				error: vi.fn(),
+				warn: vi.fn(),
+				debug: vi.fn()
+			},
+			cache: {} as any,
+			http: {} as any,
+			env: {} as any,
+			envVars: {} as any,
+			services: {} as any,
+			getSettings: vi.fn().mockResolvedValue({}),
+			getResolvedSettings: vi.fn().mockResolvedValue({}),
+			onEvent: vi.fn(),
+			emitEvent: vi.fn(),
+			registerCustomCapability: vi.fn(),
+			getCustomCapability: vi.fn(),
+			hasCustomCapability: vi.fn(),
+			listCustomCapabilities: vi.fn()
+		};
+	});
+
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	describe('Plugin Metadata', () => {
+		it('should have correct plugin metadata', () => {
+			expect(plugin.id).toBe('urlbox');
+			expect(plugin.name).toBe('Urlbox');
+			expect(plugin.version).toBe('1.0.0');
+			expect(plugin.category).toBe('screenshot');
+		});
+
+		it('should have screenshot capability', () => {
+			expect(plugin.capabilities).toContain('screenshot');
+		});
+
+		it('should have provider name', () => {
+			expect(plugin.providerName).toBe('Urlbox');
+		});
+
+		it('should have hybrid configuration mode', () => {
+			expect(plugin.configurationMode).toBe('hybrid');
+		});
+	});
+
+	describe('Settings Schema', () => {
+		it('should define apiKey as required', () => {
+			expect(plugin.settingsSchema.required).toContain('apiKey');
+		});
+
+		it('should mark apiKey as secret', () => {
+			const properties = plugin.settingsSchema.properties as Record<string, any>;
+			expect(properties.apiKey['x-secret']).toBe(true);
+		});
+
+		it('should mark apiSecret as secret', () => {
+			const properties = plugin.settingsSchema.properties as Record<string, any>;
+			expect(properties.apiSecret['x-secret']).toBe(true);
+		});
+
+		it('should have environment variable fallbacks', () => {
+			const properties = plugin.settingsSchema.properties as Record<string, any>;
+			expect(properties.apiKey['x-envVar']).toBe('PLUGIN_URLBOX_API_KEY');
+			expect(properties.apiSecret['x-envVar']).toBe('PLUGIN_URLBOX_API_SECRET');
+			expect(properties.viewportWidth['x-envVar']).toBe('PLUGIN_URLBOX_VIEWPORT_WIDTH');
+			expect(properties.viewportHeight['x-envVar']).toBe('PLUGIN_URLBOX_VIEWPORT_HEIGHT');
+			expect(properties.format['x-envVar']).toBe('PLUGIN_URLBOX_FORMAT');
+		});
+
+		it('should have default values for viewport settings', () => {
+			const properties = plugin.settingsSchema.properties as Record<string, any>;
+			expect(properties.viewportWidth.default).toBe(1280);
+			expect(properties.viewportHeight.default).toBe(1024);
+		});
+
+		it('should have default values for format and blocking options', () => {
+			const properties = plugin.settingsSchema.properties as Record<string, any>;
+			expect(properties.format.default).toBe('png');
+			expect(properties.fullPage.default).toBe(false);
+			expect(properties.blockAds.default).toBe(true);
+			expect(properties.hideCookieBanners.default).toBe(true);
+		});
+
+		it('should have quality setting with correct bounds', () => {
+			const properties = plugin.settingsSchema.properties as Record<string, any>;
+			expect(properties.quality.default).toBe(80);
+			expect(properties.quality.minimum).toBe(1);
+			expect(properties.quality.maximum).toBe(100);
+		});
+
+		it('should have retina setting defaulting to false', () => {
+			const properties = plugin.settingsSchema.properties as Record<string, any>;
+			expect(properties.retina.default).toBe(false);
+		});
+
+		it('should have format enum with supported formats', () => {
+			const properties = plugin.settingsSchema.properties as Record<string, any>;
+			expect(properties.format.enum).toEqual(['png', 'jpg', 'jpeg', 'webp']);
+		});
+	});
+
+	describe('IScreenshotPlugin - capture', () => {
+		it('should capture screenshot successfully with settings', async () => {
+			await plugin.onLoad(mockContext);
+
+			const options: ScreenshotOptions = {
+				url: 'https://example.com',
+				settings: {
+					apiKey: 'test-api-key',
+					apiSecret: 'test-api-secret'
+				}
+			};
+
+			const result = await plugin.capture(options);
+
+			expect(result.success).toBe(true);
+			expect(result.imageBuffer).toBeDefined();
+			expect(result.imageBase64).toBeDefined();
+			expect(result.imageUrl).toBeDefined();
+		});
+
+		it('should fail when API key is not configured', async () => {
+			await plugin.onLoad(mockContext);
+
+			const options: ScreenshotOptions = {
+				url: 'https://example.com',
+				settings: {}
+			};
+
+			const result = await plugin.capture(options);
+
+			expect(result.success).toBe(false);
+			expect(result.error).toContain('API key not configured');
+		});
+
+		it('should use provided viewport dimensions', async () => {
+			await plugin.onLoad(mockContext);
+
+			const options: ScreenshotOptions = {
+				url: 'https://example.com',
+				viewportWidth: 1920,
+				viewportHeight: 1080,
+				settings: {
+					apiKey: 'test-key'
+				}
+			};
+
+			const result = await plugin.capture(options);
+
+			expect(result.success).toBe(true);
+			expect(result.width).toBe(1920);
+			expect(result.height).toBe(1080);
+		});
+	});
+
+	describe('IScreenshotPlugin - getScreenshotUrl', () => {
+		it('should generate URL with settings', async () => {
+			await plugin.onLoad(mockContext);
+
+			const options: ScreenshotOptions = {
+				url: 'https://example.com',
+				settings: {
+					apiKey: 'test-key'
+				}
+			};
+
+			const url = await plugin.getScreenshotUrl(options);
+
+			expect(url).toBeDefined();
+			expect(url).toContain('api.urlbox.com');
+		});
+
+		it('should generate render link with API secret', async () => {
+			await plugin.onLoad(mockContext);
+
+			const options: ScreenshotOptions = {
+				url: 'https://example.com',
+				settings: {
+					apiKey: 'test-key',
+					apiSecret: 'test-secret'
+				}
+			};
+
+			const url = await plugin.getScreenshotUrl(options);
+
+			expect(url).toBeDefined();
+			expect(url).toContain('api.urlbox.com');
+		});
+
+		it('should return null when API key is missing', async () => {
+			await plugin.onLoad(mockContext);
+
+			const options: ScreenshotOptions = {
+				url: 'https://example.com',
+				settings: {}
+			};
+
+			const url = await plugin.getScreenshotUrl(options);
+
+			expect(url).toBeNull();
+		});
+	});
+
+	describe('IScreenshotPlugin - isAvailable', () => {
+		it('should return true when API key is configured', async () => {
+			(mockContext.getSettings as ReturnType<typeof vi.fn>).mockResolvedValue({ apiKey: 'test-key' });
+			await plugin.onLoad(mockContext);
+			const available = await plugin.isAvailable();
+			expect(available).toBe(true);
+		});
+
+		it('should return false when not loaded', async () => {
+			const available = await plugin.isAvailable();
+			expect(available).toBe(false);
+		});
+	});
+
+	describe('IScreenshotPlugin - validateCredentials', () => {
+		it('should return invalid when plugin not initialized', async () => {
+			const result = await plugin.validateCredentials();
+
+			expect(result.valid).toBe(false);
+			expect(result.message).toContain('not initialized');
+		});
+
+		it('should return invalid when API key not configured', async () => {
+			vi.mocked(mockContext.getSettings).mockResolvedValue({});
+			await plugin.onLoad(mockContext);
+
+			const result = await plugin.validateCredentials();
+
+			expect(result.valid).toBe(false);
+			expect(result.message).toContain('API key is not configured');
+		});
+
+		it('should return valid when credentials are configured', async () => {
+			vi.mocked(mockContext.getSettings).mockResolvedValue({
+				apiKey: 'test-key'
+			});
+			await plugin.onLoad(mockContext);
+
+			const result = await plugin.validateCredentials();
+
+			expect(result.valid).toBe(true);
+		});
+	});
+
+	describe('IScreenshotPlugin - getSupportedFormats', () => {
+		it('should return supported formats', () => {
+			const formats = plugin.getSupportedFormats();
+
+			expect(formats).toContain('png');
+			expect(formats).toContain('jpg');
+			expect(formats).toContain('jpeg');
+			expect(formats).toContain('webp');
+		});
+	});
+
+	describe('IScreenshotPlugin - getMaxDimensions', () => {
+		it('should return maximum viewport dimensions', () => {
+			const dimensions = plugin.getMaxDimensions();
+
+			expect(dimensions.width).toBe(3840);
+			expect(dimensions.height).toBe(2160);
+		});
+	});
+
+	describe('Lifecycle', () => {
+		it('should log on load', async () => {
+			await plugin.onLoad(mockContext);
+			expect(mockContext.logger.log).toHaveBeenCalledWith('Urlbox Plugin loaded');
+		});
+
+		it('should clear context on unload', async () => {
+			await plugin.onLoad(mockContext);
+			await plugin.onUnload();
+			// Context should be cleared - validateCredentials should fail
+			const result = await plugin.validateCredentials();
+			expect(result.valid).toBe(false);
+			expect(result.message).toContain('not initialized');
+		});
+	});
+
+	describe('healthCheck', () => {
+		it('should return healthy status', async () => {
+			const health = await plugin.healthCheck();
+
+			expect(health.status).toBe('healthy');
+			expect(health.checkedAt).toBeDefined();
+		});
+	});
+
+	describe('getManifest', () => {
+		it('should return correct manifest', () => {
+			const manifest = plugin.getManifest();
+
+			expect(manifest.id).toBe('urlbox');
+			expect(manifest.name).toBe('Urlbox');
+			expect(manifest.version).toBe('1.0.0');
+			expect(manifest.category).toBe('screenshot');
+			expect(manifest.capabilities).toContain('screenshot');
+			expect(manifest.builtIn).toBe(false);
+			expect(manifest.systemPlugin).toBe(false);
+		});
+
+		it('should have icon configuration', () => {
+			const manifest = plugin.getManifest();
+
+			expect(manifest.icon).toBeDefined();
+			expect(manifest.icon?.type).toBe('url');
+			expect(manifest.icon?.value).toBe('https://urlbox.com/apple-touch-icon.png');
+		});
+	});
+});

package/src/index.ts

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