@ever-works/exa-plugin 1.0.0 → 1.0.3

package/dist/index.cjs

@@ -0,0 +1,390 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var exaJs = require('exa-js');
+var net = require('net');
+
+// src/exa.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/exa.plugin.ts
+var SEARCH_TYPES = ["auto", "neural", "keyword"];
+var CATEGORIES = ["", "company", "research paper", "news", "tweet", "personal site", "github"];
+var TIME_RANGE_DAYS = {
+  day: 1,
+  week: 7,
+  month: 30,
+  year: 365
+};
+var API_KEY_ERROR = "Exa API key not configured. Set it in plugin settings or via PLUGIN_EXA_API_KEY environment variable.";
+var ExaSearchPlugin = class {
+  id = "exa";
+  name = "Exa";
+  version = "1.0.0";
+  category = "search";
+  capabilities = ["search", "content-extractor"];
+  providerName = "Exa";
+  settingsSchema = {
+    type: "object",
+    properties: {
+      apiKey: {
+        type: "string",
+        title: "API Key",
+        description: "Your Exa API key. Get one at https://exa.ai",
+        "x-secret": true,
+        "x-envVar": "PLUGIN_EXA_API_KEY",
+        "x-scope": "user"
+      },
+      searchType: {
+        type: "string",
+        title: "Search Type",
+        description: "Search mode: auto (recommended), neural (semantic), or keyword (traditional)",
+        enum: [...SEARCH_TYPES],
+        default: "auto"
+      },
+      maxResults: {
+        type: "number",
+        title: "Default Max Results",
+        description: "Default maximum number of results per search",
+        default: 10,
+        minimum: 1,
+        maximum: 100
+      },
+      category: {
+        type: "string",
+        title: "Category Filter",
+        description: "Optionally restrict results to a specific category",
+        enum: [...CATEGORIES],
+        default: ""
+      }
+    },
+    required: ["apiKey"]
+  };
+  configurationMode = "hybrid";
+  context;
+  // ============================================================================
+  // ISearchPlugin Interface
+  // ============================================================================
+  async search(options) {
+    const client = this.getClient(options.settings);
+    const startTime = Date.now();
+    const searchType = options.settings?.searchType || "auto";
+    const limit = options.limit || options.settings?.maxResults || 10;
+    const category = options.settings?.category || "";
+    const searchOptions = {
+      numResults: limit,
+      type: searchType
+    };
+    if (category) {
+      searchOptions.category = category;
+    }
+    if (options.includeDomains && options.includeDomains.length > 0) {
+      searchOptions.includeDomains = [...options.includeDomains];
+    }
+    if (options.excludeDomains && options.excludeDomains.length > 0) {
+      searchOptions.excludeDomains = [...options.excludeDomains];
+    }
+    if (options.timeRange && options.timeRange !== "all") {
+      const days = TIME_RANGE_DAYS[options.timeRange];
+      if (days) {
+        const startDate = new Date(Date.now() - days * 24 * 60 * 60 * 1e3);
+        searchOptions.startPublishedDate = startDate.toISOString();
+      }
+    }
+    try {
+      const response = await client.search(options.query, searchOptions);
+      const results = response.results.map((r, index) => ({
+        title: r.title || "",
+        url: r.url || "",
+        publishedDate: r.publishedDate,
+        source: r.author,
+        faviconUrl: r.favicon,
+        position: index + 1
+      }));
+      return {
+        results,
+        query: options.query,
+        totalResults: results.length,
+        hasMore: false,
+        duration: Date.now() - startTime
+      };
+    } catch (error) {
+      this.context?.logger.error(`Exa failed: ${error instanceof Error ? error.message : String(error)}`);
+      throw error;
+    }
+  }
+  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: "Exa API key is not configured." };
+    }
+    try {
+      const client = this.getClient(settings);
+      await client.search("test", { numResults: 1 });
+      return { success: true, message: "Exa connection verified." };
+    } catch (error) {
+      return {
+        success: false,
+        message: `Exa connection failed: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
+  }
+  async getRateLimitInfo() {
+    return {
+      remaining: -1,
+      limit: -1,
+      period: "month"
+    };
+  }
+  // ============================================================================
+  // IContentExtractorPlugin Interface
+  // ============================================================================
+  async extract(options) {
+    const startTime = Date.now();
+    if (!isSafeWebhookUrl(options.url)) {
+      return {
+        success: false,
+        url: options.url,
+        error: `URL host is not safe to extract (SSRF guard blocked: ${options.url})`,
+        duration: Date.now() - startTime
+      };
+    }
+    try {
+      const client = this.getClient(options.settings);
+      const response = await client.getContents([options.url], { text: true, livecrawl: "fallback" });
+      if (!response.results || response.results.length === 0) {
+        return {
+          success: false,
+          url: options.url,
+          error: "No content extracted",
+          duration: Date.now() - startTime
+        };
+      }
+      const result = response.results[0];
+      const text = result.text || "";
+      return {
+        success: true,
+        url: options.url,
+        finalUrl: result.url !== options.url ? result.url : void 0,
+        content: text,
+        title: result.title || void 0,
+        duration: Date.now() - startTime,
+        wordCount: text ? text.split(/\s+/).length : 0
+      };
+    } catch (error) {
+      return {
+        success: false,
+        url: options.url,
+        error: error instanceof Error ? error.message : String(error),
+        duration: Date.now() - startTime
+      };
+    }
+  }
+  async extractBatch(urls, options) {
+    const startTime = Date.now();
+    const results = new Array(urls.length);
+    const safeUrls = [];
+    const safeIndexes = [];
+    urls.forEach((url, index) => {
+      if (isSafeWebhookUrl(url)) {
+        safeUrls.push(url);
+        safeIndexes.push(index);
+      } else {
+        results[index] = {
+          success: false,
+          url,
+          error: `URL host is not safe to extract (SSRF guard blocked: ${url})`,
+          duration: Date.now() - startTime
+        };
+      }
+    });
+    if (safeUrls.length === 0) {
+      return results;
+    }
+    try {
+      const client = this.getClient(options?.settings);
+      const response = await client.getContents([...safeUrls], { text: true, livecrawl: "fallback" });
+      response.results.forEach((result, i) => {
+        const originalIndex = safeIndexes[i];
+        const text = result.text || "";
+        const requestedUrl = safeUrls[i] || result.url;
+        results[originalIndex] = {
+          success: true,
+          url: requestedUrl,
+          finalUrl: result.url !== requestedUrl ? result.url : void 0,
+          content: text,
+          title: result.title || void 0,
+          duration: Date.now() - startTime,
+          wordCount: text ? text.split(/\s+/).length : 0
+        };
+      });
+      safeIndexes.forEach((originalIndex, i) => {
+        if (!results[originalIndex]) {
+          results[originalIndex] = {
+            success: false,
+            url: safeUrls[i],
+            error: "No content extracted",
+            duration: Date.now() - startTime
+          };
+        }
+      });
+      return results;
+    } catch (error) {
+      safeIndexes.forEach((originalIndex, i) => {
+        results[originalIndex] = {
+          success: false,
+          url: safeUrls[i],
+          error: error instanceof Error ? error.message : String(error),
+          duration: Date.now() - startTime
+        };
+      });
+      return results;
+    }
+  }
+  async canExtract(url) {
+    try {
+      const parsed = new URL(url);
+      return parsed.protocol === "http:" || parsed.protocol === "https:";
+    } catch {
+      return false;
+    }
+  }
+  getSupportedFormats() {
+    return ["text"];
+  }
+  // ============================================================================
+  // IPlugin Lifecycle
+  // ============================================================================
+  getClient(settings) {
+    const apiKey = settings?.apiKey;
+    if (!apiKey) {
+      throw new Error(API_KEY_ERROR);
+    }
+    return new exaJs.Exa(apiKey);
+  }
+  async onLoad(context) {
+    this.context = context;
+    context.logger.log("Exa Plugin loaded");
+  }
+  async onUnload() {
+    this.context = void 0;
+  }
+  async healthCheck() {
+    return {
+      status: "healthy",
+      message: "Exa plugin is ready (API key required for operations)",
+      checkedAt: Date.now()
+    };
+  }
+  getManifest() {
+    return {
+      id: this.id,
+      name: this.name,
+      version: this.version,
+      description: "AI-native search and content extraction using the Exa API",
+      category: this.category,
+      capabilities: [...this.capabilities],
+      author: { name: "Ever Works Team" },
+      license: "AGPL-3.0",
+      builtIn: true,
+      systemPlugin: false,
+      autoEnable: false,
+      readme: [
+        "## What does Exa do?",
+        "",
+        "Exa is an AI-native search engine that understands meaning, not just keywords. It offers neural search (semantic understanding), keyword search (traditional matching), and an auto mode that picks the best approach for each query. It can also extract clean text content from web pages.",
+        "",
+        "## Why use it?",
+        "",
+        "- **Neural search** \u2014 finds results based on meaning, not just keyword matching",
+        "- **Content extraction** \u2014 pulls clean text from any web page URL",
+        "- **Category filtering** \u2014 restrict to companies, research papers, news, tweets, GitHub repos, or personal sites",
+        "- **Domain control** \u2014 include or exclude specific domains from results",
+        "- **Time filtering** \u2014 find results from the last day, week, month, or year",
+        "",
+        "## How it works in Ever Works",
+        "",
+        "When enabled and set as the active search provider, Exa is used during work generation to find information about each item. Its neural search mode is particularly useful for finding semantically relevant content that keyword-based engines might miss. The content extraction capability can pull text from web pages for enriching work items.",
+        "",
+        "## Getting started",
+        "",
+        "1. Create an account at [exa.ai](https://exa.ai)",
+        "2. Copy your API key from the Exa dashboard",
+        "3. Enter the key in the **API Key** field below",
+        "4. Choose your preferred search type (auto recommended)",
+        "5. Enable this plugin to use it for work generation"
+      ].join("\n"),
+      homepage: "https://exa.ai"
+    };
+  }
+};
+
+exports.ExaSearchPlugin = ExaSearchPlugin;
+exports.default = ExaSearchPlugin;

package/dist/index.d.cts

@@ -0,0 +1,28 @@
+import { IPlugin, ISearchPlugin, IContentExtractorPlugin, PluginCategory, JsonSchema, SearchOptions, SearchResponse, ConnectionValidationResult, RateLimitInfo, ContentExtractionOptions, ContentExtractionResult, PluginContext, PluginHealthCheck, PluginManifest } from '@ever-works/plugin';
+
+declare class ExaSearchPlugin implements IPlugin, ISearchPlugin, IContentExtractorPlugin {
+    readonly id = "exa";
+    readonly name = "Exa";
+    readonly version = "1.0.0";
+    readonly category: PluginCategory;
+    readonly capabilities: readonly string[];
+    readonly providerName = "Exa";
+    readonly settingsSchema: JsonSchema;
+    readonly configurationMode: 'admin-only' | 'user-required' | 'hybrid';
+    private context?;
+    search(options: SearchOptions): Promise<SearchResponse>;
+    isAvailable(): Promise<boolean>;
+    validateConnection(settings: Record<string, unknown>): Promise<ConnectionValidationResult>;
+    getRateLimitInfo(): Promise<RateLimitInfo>;
+    extract(options: ContentExtractionOptions): Promise<ContentExtractionResult>;
+    extractBatch(urls: readonly string[], options?: Partial<ContentExtractionOptions>): Promise<readonly ContentExtractionResult[]>;
+    canExtract(url: string): Promise<boolean>;
+    getSupportedFormats(): readonly ('text' | 'html' | 'markdown')[];
+    private getClient;
+    onLoad(context: PluginContext): Promise<void>;
+    onUnload(): Promise<void>;
+    healthCheck(): Promise<PluginHealthCheck>;
+    getManifest(): PluginManifest;
+}
+
+export { ExaSearchPlugin, ExaSearchPlugin as default };

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { IPlugin, ISearchPlugin, IContentExtractorPlugin, PluginCategory, JsonSchema, SearchOptions, SearchResponse, ConnectionValidationResult, RateLimitInfo, ContentExtractionOptions, ContentExtractionResult, PluginContext, PluginHealthCheck, PluginManifest } from '@ever-works/plugin';
+
+declare class ExaSearchPlugin implements IPlugin, ISearchPlugin, IContentExtractorPlugin {
+    readonly id = "exa";
+    readonly name = "Exa";
+    readonly version = "1.0.0";
+    readonly category: PluginCategory;
+    readonly capabilities: readonly string[];
+    readonly providerName = "Exa";
+    readonly settingsSchema: JsonSchema;
+    readonly configurationMode: 'admin-only' | 'user-required' | 'hybrid';
+    private context?;
+    search(options: SearchOptions): Promise<SearchResponse>;
+    isAvailable(): Promise<boolean>;
+    validateConnection(settings: Record<string, unknown>): Promise<ConnectionValidationResult>;
+    getRateLimitInfo(): Promise<RateLimitInfo>;
+    extract(options: ContentExtractionOptions): Promise<ContentExtractionResult>;
+    extractBatch(urls: readonly string[], options?: Partial<ContentExtractionOptions>): Promise<readonly ContentExtractionResult[]>;
+    canExtract(url: string): Promise<boolean>;
+    getSupportedFormats(): readonly ('text' | 'html' | 'markdown')[];
+    private getClient;
+    onLoad(context: PluginContext): Promise<void>;
+    onUnload(): Promise<void>;
+    healthCheck(): Promise<PluginHealthCheck>;
+    getManifest(): PluginManifest;
+}
+
+export { ExaSearchPlugin, ExaSearchPlugin as default };