@ever-works/urlbox-plugin 1.0.0 → 1.0.3

package/dist/index.cjs

@@ -0,0 +1,394 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var Urlbox = require('urlbox');
+var net = require('net');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var Urlbox__default = /*#__PURE__*/_interopDefault(Urlbox);
+
+// src/urlbox.plugin.ts
+function isSafeWebhookUrl(rawUrl) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    return false;
+  }
+  let host = url.hostname.toLowerCase();
+  if (host.startsWith("[") && host.endsWith("]")) {
+    host = host.slice(1, -1);
+  }
+  if (CLOUD_METADATA_HOSTNAMES.has(host)) {
+    return false;
+  }
+  const ipKind = net.isIP(host);
+  if (ipKind === 4 && isPrivateIPv4(host)) return false;
+  if (ipKind === 6 && isPrivateIPv6(host)) return false;
+  return true;
+}
+var CLOUD_METADATA_HOSTNAMES = /* @__PURE__ */ new Set([
+  // GCP
+  "metadata.google.internal",
+  "metadata.goog",
+  // AWS
+  "instance-data",
+  "instance-data.ec2.internal",
+  // Azure
+  "metadata.azure.internal"
+]);
+function isPrivateIPv4(ip) {
+  const parts = ip.split(".").map((p) => Number(p));
+  if (parts.length !== 4 || parts.some((n) => Number.isNaN(n))) return false;
+  const [a, b] = parts;
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 0) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 192 && b === 0 && parts[2] === 0) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a >= 224) return true;
+  return false;
+}
+function isPrivateIPv6(ip) {
+  const lower = ip.toLowerCase();
+  if (lower === "::1" || lower === "::") return true;
+  if (lower.startsWith("fc") || lower.startsWith("fd")) return true;
+  const firstHextet = lower.split(":", 1)[0];
+  if (/^[0-9a-f]{1,4}$/.test(firstHextet)) {
+    const group0 = parseInt(firstHextet, 16);
+    if ((group0 & 65472) === 65152) return true;
+  }
+  if (lower.startsWith("::ffff:")) {
+    const v4 = lower.slice("::ffff:".length);
+    if (net.isIP(v4) === 4) return isPrivateIPv4(v4);
+  }
+  return false;
+}
+
+// src/urlbox.plugin.ts
+var UrlboxPlugin = class {
+  constructor() {
+    this.id = "urlbox";
+    this.name = "Urlbox";
+    this.version = "1.0.0";
+    this.category = "screenshot";
+    this.capabilities = ["screenshot"];
+    this.providerName = "Urlbox";
+    this.settingsSchema = {
+      type: "object",
+      properties: {
+        apiKey: {
+          type: "string",
+          title: "API Key",
+          description: "Your Urlbox API key. Get one at https://urlbox.com",
+          "x-secret": true,
+          "x-envVar": "PLUGIN_URLBOX_API_KEY",
+          "x-scope": "user"
+        },
+        apiSecret: {
+          type: "string",
+          title: "API Secret",
+          description: "Your Urlbox API secret for signed render links (recommended for security)",
+          "x-secret": true,
+          "x-envVar": "PLUGIN_URLBOX_API_SECRET",
+          "x-scope": "user"
+        },
+        viewportWidth: {
+          type: "number",
+          title: "Viewport Width",
+          description: "Default viewport width in pixels",
+          default: 1280,
+          minimum: 320,
+          maximum: 3840,
+          "x-envVar": "PLUGIN_URLBOX_VIEWPORT_WIDTH"
+        },
+        viewportHeight: {
+          type: "number",
+          title: "Viewport Height",
+          description: "Default viewport height in pixels",
+          default: 1024,
+          minimum: 200,
+          maximum: 2160,
+          "x-envVar": "PLUGIN_URLBOX_VIEWPORT_HEIGHT"
+        },
+        format: {
+          type: "string",
+          title: "Image Format",
+          description: "Default output image format",
+          enum: ["png", "jpg", "jpeg", "webp"],
+          default: "png",
+          "x-envVar": "PLUGIN_URLBOX_FORMAT"
+        },
+        fullPage: {
+          type: "boolean",
+          title: "Full Page",
+          description: "Capture full page by default",
+          default: false
+        },
+        quality: {
+          type: "number",
+          title: "Image Quality",
+          description: "Image quality for lossy formats (1-100)",
+          default: 80,
+          minimum: 1,
+          maximum: 100
+        },
+        retina: {
+          type: "boolean",
+          title: "Retina",
+          description: "Enable retina/HiDPI rendering (2x device scale factor)",
+          default: false
+        },
+        blockAds: {
+          type: "boolean",
+          title: "Block Ads",
+          description: "Block ads when capturing screenshots",
+          default: true
+        },
+        hideCookieBanners: {
+          type: "boolean",
+          title: "Hide Cookie Banners",
+          description: "Hide cookie consent banners when capturing screenshots",
+          default: true
+        }
+      },
+      required: ["apiKey"]
+    };
+    this.configurationMode = "hybrid";
+  }
+  async capture(options) {
+    const settings = this.mergeSettings(options.settings);
+    if (!isSafeWebhookUrl(options.url)) {
+      return {
+        success: false,
+        error: `URL host is not safe to capture (SSRF guard blocked: ${options.url})`
+      };
+    }
+    try {
+      const client = this.createClient(settings);
+      const renderOptions = this.buildOptions(options, settings);
+      const renderUrl = client.generateRenderLink(renderOptions);
+      const response = await fetch(renderUrl);
+      if (!response.ok) {
+        throw new Error(`Urlbox render failed with status ${response.status}`);
+      }
+      const arrayBuffer = await response.arrayBuffer();
+      const buffer = Buffer.from(arrayBuffer);
+      return {
+        success: true,
+        imageBuffer: buffer,
+        imageBase64: buffer.toString("base64"),
+        imageUrl: renderUrl,
+        width: options.viewportWidth ?? settings.viewportWidth ?? 1280,
+        height: options.viewportHeight ?? settings.viewportHeight ?? 1024,
+        fileSize: buffer.length
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.context?.logger.error(`Urlbox capture failed: ${errorMessage}`);
+      return {
+        success: false,
+        error: errorMessage
+      };
+    }
+  }
+  async getScreenshotUrl(options) {
+    const settings = this.mergeSettings(options.settings);
+    if (!isSafeWebhookUrl(options.url)) {
+      this.context?.logger.error(`Urlbox URL generation blocked by SSRF guard for unsafe URL: ${options.url}`);
+      return null;
+    }
+    try {
+      const client = this.createClient(settings);
+      const renderOptions = this.buildOptions(options, settings);
+      return client.generateRenderLink(renderOptions);
+    } catch (error) {
+      this.context?.logger.error(
+        `Urlbox URL generation failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+      return null;
+    }
+  }
+  async isAvailable() {
+    if (!this.context) return false;
+    const settings = await this.context.getSettings();
+    return Boolean(settings?.apiKey);
+  }
+  async validateConnection(settings) {
+    const apiKey = settings.apiKey;
+    if (!apiKey) {
+      return { success: false, message: "Urlbox API key is not configured." };
+    }
+    try {
+      const resolvedSettings = this.mergeSettings(settings);
+      const client = this.createClient(resolvedSettings);
+      const url = client.generateRenderLink({ url: "https://example.com" });
+      if (url && url.includes("api.urlbox.com")) {
+        return { success: true, message: "Urlbox connection verified." };
+      }
+      return { success: false, message: "Urlbox credentials appear invalid." };
+    } catch (error) {
+      return {
+        success: false,
+        message: `Urlbox connection failed: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
+  }
+  async validateCredentials() {
+    if (!this.context) {
+      return {
+        valid: false,
+        message: "Plugin not initialized"
+      };
+    }
+    try {
+      const settings = await this.context.getSettings();
+      const resolvedSettings = this.mergeSettings(settings);
+      if (!resolvedSettings.apiKey) {
+        return {
+          valid: false,
+          message: "API key is not configured"
+        };
+      }
+      const client = this.createClient(resolvedSettings);
+      const url = client.generateRenderLink({ url: "https://example.com" });
+      if (url && url.includes("api.urlbox.com")) {
+        return {
+          valid: true,
+          message: "Credentials are valid"
+        };
+      }
+      return {
+        valid: false,
+        message: "Invalid credentials format"
+      };
+    } catch (error) {
+      return {
+        valid: false,
+        message: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  getSupportedFormats() {
+    return ["png", "jpg", "jpeg", "webp"];
+  }
+  getMaxDimensions() {
+    return { width: 3840, height: 2160 };
+  }
+  createClient(settings) {
+    const apiKey = settings.apiKey;
+    const apiSecret = settings.apiSecret ?? "";
+    if (!apiKey) {
+      throw new Error(
+        "Urlbox API key not configured. Set it in plugin settings or via PLUGIN_URLBOX_API_KEY environment variable."
+      );
+    }
+    return Urlbox__default.default(apiKey, apiSecret);
+  }
+  buildOptions(options, settings) {
+    const format = options.format ?? settings.format ?? "png";
+    const renderOptions = {
+      url: options.url,
+      width: options.viewportWidth ?? settings.viewportWidth ?? 1280,
+      height: options.viewportHeight ?? settings.viewportHeight ?? 1024,
+      format,
+      full_page: options.fullPage ?? settings.fullPage ?? false,
+      quality: settings.quality ?? 80,
+      retina: settings.retina ?? false,
+      block_ads: options.blockAds ?? settings.blockAds ?? true,
+      hide_cookie_banners: options.blockCookieBanners ?? settings.hideCookieBanners ?? true
+    };
+    if (options.delay !== void 0) {
+      renderOptions.delay = options.delay;
+    }
+    if (options.waitForSelector) {
+      renderOptions.selector = options.waitForSelector;
+    }
+    if (options.userAgent) {
+      renderOptions.user_agent = options.userAgent;
+    }
+    return renderOptions;
+  }
+  mergeSettings(settings) {
+    return {
+      apiKey: settings?.apiKey,
+      apiSecret: settings?.apiSecret,
+      viewportWidth: settings?.viewportWidth ?? 1280,
+      viewportHeight: settings?.viewportHeight ?? 1024,
+      format: settings?.format ?? "png",
+      fullPage: settings?.fullPage ?? false,
+      quality: settings?.quality ?? 80,
+      retina: settings?.retina ?? false,
+      blockAds: settings?.blockAds ?? true,
+      hideCookieBanners: settings?.hideCookieBanners ?? true
+    };
+  }
+  async onLoad(context) {
+    this.context = context;
+    context.logger.log("Urlbox Plugin loaded");
+  }
+  async onUnload() {
+    this.context = void 0;
+  }
+  async healthCheck() {
+    return {
+      status: "healthy",
+      message: "Urlbox plugin is ready (API key required for operations)",
+      checkedAt: Date.now()
+    };
+  }
+  getManifest() {
+    return {
+      id: this.id,
+      name: this.name,
+      version: this.version,
+      description: "Automatically capture website screenshots for your work items",
+      category: this.category,
+      capabilities: [...this.capabilities],
+      author: { name: "Ever Works Team" },
+      license: "AGPL-3.0",
+      builtIn: false,
+      systemPlugin: false,
+      readme: [
+        "## 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** \u2014 preview images are generated for each work item without manual effort",
+        "- **Consistent output** \u2014 every screenshot uses the same viewport size, format, and rendering settings",
+        "- **Ad and cookie banner blocking** \u2014 captures clean screenshots free of ads and cookie banners",
+        "- **Retina rendering** \u2014 supports HiDPI output for crisp images on high-resolution displays",
+        "- **Multiple formats** \u2014 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"
+      ].join("\n"),
+      homepage: "https://urlbox.com",
+      icon: {
+        type: "url",
+        value: "https://urlbox.com/apple-touch-icon.png"
+      }
+    };
+  }
+};
+
+exports.UrlboxPlugin = UrlboxPlugin;
+exports.default = UrlboxPlugin;

package/dist/index.d.cts

@@ -0,0 +1,32 @@
+import { IPlugin, IScreenshotPlugin, PluginCategory, JsonSchema, ScreenshotOptions, ScreenshotResult, ConnectionValidationResult, ScreenshotValidationResult, ScreenshotFormat, PluginContext, PluginHealthCheck, PluginManifest } from '@ever-works/plugin';
+
+declare class UrlboxPlugin implements IPlugin, IScreenshotPlugin {
+    readonly id = "urlbox";
+    readonly name = "Urlbox";
+    readonly version = "1.0.0";
+    readonly category: PluginCategory;
+    readonly capabilities: readonly string[];
+    readonly providerName = "Urlbox";
+    readonly settingsSchema: JsonSchema;
+    readonly configurationMode: 'admin-only' | 'user-required' | 'hybrid';
+    private context?;
+    capture(options: ScreenshotOptions): Promise<ScreenshotResult>;
+    getScreenshotUrl(options: ScreenshotOptions): Promise<string | null>;
+    isAvailable(): Promise<boolean>;
+    validateConnection(settings: Record<string, unknown>): Promise<ConnectionValidationResult>;
+    validateCredentials(): Promise<ScreenshotValidationResult>;
+    getSupportedFormats(): readonly ScreenshotFormat[];
+    getMaxDimensions(): {
+        width: number;
+        height: number;
+    };
+    private createClient;
+    private buildOptions;
+    private mergeSettings;
+    onLoad(context: PluginContext): Promise<void>;
+    onUnload(): Promise<void>;
+    healthCheck(): Promise<PluginHealthCheck>;
+    getManifest(): PluginManifest;
+}
+
+export { UrlboxPlugin, UrlboxPlugin as default };

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { IPlugin, IScreenshotPlugin, PluginCategory, JsonSchema, ScreenshotOptions, ScreenshotResult, ConnectionValidationResult, ScreenshotValidationResult, ScreenshotFormat, PluginContext, PluginHealthCheck, PluginManifest } from '@ever-works/plugin';
+
+declare class UrlboxPlugin implements IPlugin, IScreenshotPlugin {
+    readonly id = "urlbox";
+    readonly name = "Urlbox";
+    readonly version = "1.0.0";
+    readonly category: PluginCategory;
+    readonly capabilities: readonly string[];
+    readonly providerName = "Urlbox";
+    readonly settingsSchema: JsonSchema;
+    readonly configurationMode: 'admin-only' | 'user-required' | 'hybrid';
+    private context?;
+    capture(options: ScreenshotOptions): Promise<ScreenshotResult>;
+    getScreenshotUrl(options: ScreenshotOptions): Promise<string | null>;
+    isAvailable(): Promise<boolean>;
+    validateConnection(settings: Record<string, unknown>): Promise<ConnectionValidationResult>;
+    validateCredentials(): Promise<ScreenshotValidationResult>;
+    getSupportedFormats(): readonly ScreenshotFormat[];
+    getMaxDimensions(): {
+        width: number;
+        height: number;
+    };
+    private createClient;
+    private buildOptions;
+    private mergeSettings;
+    onLoad(context: PluginContext): Promise<void>;
+    onUnload(): Promise<void>;
+    healthCheck(): Promise<PluginHealthCheck>;
+    getManifest(): PluginManifest;
+}
+
+export { UrlboxPlugin, UrlboxPlugin as default };