@pi-unipi/web-api 0.1.0

package/src/providers/perplexity.ts

@@ -0,0 +1,191 @@
+/**
+ * @unipi/web-api — Perplexity provider
+ *
+ * Paid search and summarization provider using Perplexity API.
+ * Supports search, read, and summarize capabilities.
+ * Requires API key (PERPLEXITY_API_KEY environment variable).
+ */
+
+import type {
+  WebProvider,
+  SearchResult,
+  ReadResult,
+  SummarizeResult,
+  ProviderConfig,
+} from "./base.js";
+import { registry } from "./registry.js";
+
+/** Perplexity API response format */
+interface PerplexityResponse {
+  choices: Array<{
+    message: {
+      content: string;
+    };
+    citations?: Array<{
+      url: string;
+    }>;
+  }>;
+}
+
+/**
+ * Search via Perplexity.
+ * @param query - Search query
+ * @param apiKey - Perplexity API key
+ * @returns Array of search results
+ */
+async function searchPerplexity(query: string, apiKey: string): Promise<SearchResult[]> {
+  const response = await fetch("https://api.perplexity.ai/chat/completions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model: "llama-3.1-sonar-small-128k-online",
+      messages: [
+        {
+          role: "system",
+          content: "You are a search assistant. Return search results as a JSON array with objects containing 'title', 'url', and 'snippet' fields.",
+        },
+        {
+          role: "user",
+          content: query,
+        },
+      ],
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Perplexity search failed: ${response.status} ${response.statusText}`);
+  }
+
+  const data = (await response.json()) as PerplexityResponse;
+  const content = data.choices[0]?.message?.content || "[]";
+
+  try {
+    // Parse JSON from response
+    const jsonMatch = content.match(/\[[\s\S]*\]/);
+    if (jsonMatch) {
+      return JSON.parse(jsonMatch[0]);
+    }
+  } catch {
+    // Fall back to extracting from text
+  }
+
+  // Fallback: create single result from response
+  const citations = data.choices[0]?.citations || [];
+  return citations.map((citation, i) => ({
+    title: `Result ${i + 1}`,
+    url: citation.url,
+    snippet: content.substring(0, 200),
+  }));
+}
+
+/**
+ * Summarize via Perplexity.
+ * @param url - URL to summarize
+ * @param prompt - Custom prompt
+ * @param apiKey - Perplexity API key
+ * @returns Summarized content
+ */
+async function summarizePerplexity(
+  url: string,
+  prompt: string | undefined,
+  apiKey: string
+): Promise<SummarizeResult> {
+  const systemPrompt = prompt || "Summarize the content of this URL concisely, highlighting key points.";
+
+  const response = await fetch("https://api.perplexity.ai/chat/completions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model: "llama-3.1-sonar-small-128k-online",
+      messages: [
+        {
+          role: "system",
+          content: systemPrompt,
+        },
+        {
+          role: "user",
+          content: `Summarize this URL: ${url}`,
+        },
+      ],
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Perplexity summarize failed: ${response.status} ${response.statusText}`);
+  }
+
+  const data = (await response.json()) as PerplexityResponse;
+  const summary = data.choices[0]?.message?.content || "";
+
+  return {
+    url: url,
+    summary: summary,
+    prompt: prompt,
+  };
+}
+
+/** Perplexity provider implementation */
+const perplexityProvider: WebProvider = {
+  id: "perplexity",
+  name: "Perplexity",
+  capabilities: ["search", "read", "summarize"],
+  requiresApiKey: true,
+  apiKeyEnv: "PERPLEXITY_API_KEY",
+  ranking: {
+    search: 5,
+    read: 3,
+    summarize: 1,
+  },
+  config: {},
+
+  async search(query: string, config?: ProviderConfig): Promise<SearchResult[]> {
+    const apiKey = config?.apiKey || process.env.PERPLEXITY_API_KEY;
+    if (!apiKey) {
+      throw new Error("Perplexity requires an API key. Set PERPLEXITY_API_KEY environment variable or configure via /unipi:web-settings");
+    }
+    return searchPerplexity(query, apiKey);
+  },
+
+  async read(url: string, config?: ProviderConfig): Promise<ReadResult> {
+    const apiKey = config?.apiKey || process.env.PERPLEXITY_API_KEY;
+    if (!apiKey) {
+      throw new Error("Perplexity requires an API key. Set PERPLEXITY_API_KEY environment variable or configure via /unipi:web-settings");
+    }
+
+    const result = await summarizePerplexity(url, "Extract and return the full content of this URL as markdown.", apiKey);
+
+    return {
+      url: url,
+      content: result.summary,
+      contentType: "markdown",
+    };
+  },
+
+  async summarize(url: string, prompt?: string, config?: ProviderConfig): Promise<SummarizeResult> {
+    const apiKey = config?.apiKey || process.env.PERPLEXITY_API_KEY;
+    if (!apiKey) {
+      throw new Error("Perplexity requires an API key. Set PERPLEXITY_API_KEY environment variable or configure via /unipi:web-settings");
+    }
+    return summarizePerplexity(url, prompt, apiKey);
+  },
+
+  async validateApiKey(apiKey: string): Promise<boolean> {
+    try {
+      await searchPerplexity("test", apiKey);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+};
+
+// Register provider
+registry.register(perplexityProvider);
+
+export { perplexityProvider };

package/src/providers/registry.ts

@@ -0,0 +1,128 @@
+/**
+ * @unipi/web-api — Provider registry
+ *
+ * Registry for managing web providers.
+ * Handles registration, retrieval, and ranked selection.
+ */
+
+import type {
+  WebProvider,
+  WebCapability,
+  ProviderConfig,
+} from "./base.js";
+
+/**
+ * ProviderRegistry manages all registered web providers.
+ *
+ * Provides methods to:
+ * - Register providers
+ * - Retrieve providers by ID
+ * - Get providers for a specific capability
+ * - Get ranked providers for smart selection
+ */
+export class ProviderRegistry {
+  private providers: Map<string, WebProvider> = new Map();
+
+  /**
+   * Register a provider.
+   * @param provider - Provider to register
+   */
+  register(provider: WebProvider): void {
+    if (this.providers.has(provider.id)) {
+      throw new Error(`Provider "${provider.id}" is already registered`);
+    }
+    this.providers.set(provider.id, provider);
+  }
+
+  /**
+   * Unregister a provider.
+   * @param providerId - Provider ID to unregister
+   */
+  unregister(providerId: string): void {
+    this.providers.delete(providerId);
+  }
+
+  /**
+   * Get a provider by ID.
+   * @param providerId - Provider ID
+   * @returns Provider or undefined
+   */
+  getProvider(providerId: string): WebProvider | undefined {
+    return this.providers.get(providerId);
+  }
+
+  /**
+   * Get all registered providers.
+   * @returns Array of all providers
+   */
+  getAllProviders(): WebProvider[] {
+    return Array.from(this.providers.values());
+  }
+
+  /**
+   * Get providers that support a specific capability.
+   * @param capability - Capability to filter by
+   * @returns Array of providers with the capability
+   */
+  getProvidersForCapability(capability: WebCapability): WebProvider[] {
+    return this.getAllProviders().filter((p) =>
+      p.capabilities.includes(capability)
+    );
+  }
+
+  /**
+   * Get ranked providers for a specific capability.
+   * Sorted by ranking (lower = better/simpler/cheaper).
+   * @param capability - Capability to rank by
+   * @returns Array of providers sorted by ranking
+   */
+  getRankedProviders(capability: WebCapability): WebProvider[] {
+    return this.getProvidersForCapability(capability)
+      .filter((p) => p.ranking[capability] > 0)
+      .sort((a, b) => a.ranking[capability] - b.ranking[capability]);
+  }
+
+  /**
+   * Get the best provider for a capability (lowest rank).
+   * @param capability - Capability to find best provider for
+   * @returns Best provider or undefined
+   */
+  getBestProvider(capability: WebCapability): WebProvider | undefined {
+    const ranked = this.getRankedProviders(capability);
+    return ranked[0];
+  }
+
+  /**
+   * Get a provider by rank for a capability.
+   * @param capability - Capability to search
+   * @param rank - Desired rank (1-based)
+   * @returns Provider at that rank or undefined
+   */
+  getProviderByRank(capability: WebCapability, rank: number): WebProvider | undefined {
+    const ranked = this.getRankedProviders(capability);
+    return ranked.find((p) => p.ranking[capability] === rank);
+  }
+
+  /**
+   * Get enabled providers based on configuration.
+   * @param configMap - Map of provider ID to config
+   * @returns Array of enabled providers
+   */
+  getEnabledProviders(configMap: Map<string, ProviderConfig>): WebProvider[] {
+    return this.getAllProviders().filter((p) => {
+      const config = configMap.get(p.id);
+      return config?.enabled !== false;
+    });
+  }
+
+  /**
+   * Get provider count.
+   * @returns Number of registered providers
+   */
+  get count(): number {
+    return this.providers.size;
+  }
+}
+
+/** Singleton registry instance */
+export const registry = new ProviderRegistry();

package/src/providers/serpapi.ts

@@ -0,0 +1,86 @@
+/**
+ * @unipi/web-api — SerpAPI provider
+ *
+ * Paid search provider using SerpAPI for Google search results.
+ * Requires API key (SERPAPI_KEY environment variable).
+ */
+
+import type {
+  WebProvider,
+  SearchResult,
+  ProviderConfig,
+} from "./base.js";
+import { registry } from "./registry.js";
+
+/** SerpAPI response format */
+interface SerpAPIResponse {
+  organic_results: Array<{
+    title: string;
+    link: string;
+    snippet: string;
+  }>;
+}
+
+/**
+ * Search via SerpAPI.
+ * @param query - Search query
+ * @param apiKey - SerpAPI key
+ * @returns Array of search results
+ */
+async function searchSerpAPI(query: string, apiKey: string): Promise<SearchResult[]> {
+  const url = new URL("https://serpapi.com/search");
+  url.searchParams.set("q", query);
+  url.searchParams.set("api_key", apiKey);
+  url.searchParams.set("engine", "google");
+
+  const response = await fetch(url.toString());
+
+  if (!response.ok) {
+    throw new Error(`SerpAPI search failed: ${response.status} ${response.statusText}`);
+  }
+
+  const data = (await response.json()) as SerpAPIResponse;
+
+  return (data.organic_results || []).map((item) => ({
+    title: item.title,
+    url: item.link,
+    snippet: item.snippet,
+  }));
+}
+
+/** SerpAPI provider implementation */
+const serpapiProvider: WebProvider = {
+  id: "serpapi",
+  name: "SerpAPI",
+  capabilities: ["search"],
+  requiresApiKey: true,
+  apiKeyEnv: "SERPAPI_KEY",
+  ranking: {
+    search: 3,
+    read: 0,
+    summarize: 0,
+  },
+  config: {},
+
+  async search(query: string, config?: ProviderConfig): Promise<SearchResult[]> {
+    const apiKey = config?.apiKey || process.env.SERPAPI_KEY;
+    if (!apiKey) {
+      throw new Error("SerpAPI requires an API key. Set SERPAPI_KEY environment variable or configure via /unipi:web-settings");
+    }
+    return searchSerpAPI(query, apiKey);
+  },
+
+  async validateApiKey(apiKey: string): Promise<boolean> {
+    try {
+      const results = await searchSerpAPI("test", apiKey);
+      return Array.isArray(results);
+    } catch {
+      return false;
+    }
+  },
+};
+
+// Register provider
+registry.register(serpapiProvider);
+
+export { serpapiProvider };

package/src/providers/tavily.ts

@@ -0,0 +1,95 @@
+/**
+ * @unipi/web-api — Tavily provider
+ *
+ * Paid search provider using Tavily API for AI-optimized search results.
+ * Requires API key (TAVILY_API_KEY environment variable).
+ */
+
+import type {
+  WebProvider,
+  SearchResult,
+  ProviderConfig,
+} from "./base.js";
+import { registry } from "./registry.js";
+
+/** Tavily API response format */
+interface TavilyResponse {
+  results: Array<{
+    title: string;
+    url: string;
+    content: string;
+  }>;
+}
+
+/**
+ * Search via Tavily.
+ * @param query - Search query
+ * @param apiKey - Tavily API key
+ * @returns Array of search results
+ */
+async function searchTavily(query: string, apiKey: string): Promise<SearchResult[]> {
+  const url = "https://api.tavily.com/search";
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      api_key: apiKey,
+      query: query,
+      search_depth: "basic",
+      include_answer: false,
+      include_raw_content: false,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Tavily search failed: ${response.status} ${response.statusText}`);
+  }
+
+  const data = (await response.json()) as TavilyResponse;
+
+  return (data.results || []).map((item) => ({
+    title: item.title,
+    url: item.url,
+    snippet: item.content,
+  }));
+}
+
+/** Tavily provider implementation */
+const tavilyProvider: WebProvider = {
+  id: "tavily",
+  name: "Tavily",
+  capabilities: ["search"],
+  requiresApiKey: true,
+  apiKeyEnv: "TAVILY_API_KEY",
+  ranking: {
+    search: 4,
+    read: 0,
+    summarize: 0,
+  },
+  config: {},
+
+  async search(query: string, config?: ProviderConfig): Promise<SearchResult[]> {
+    const apiKey = config?.apiKey || process.env.TAVILY_API_KEY;
+    if (!apiKey) {
+      throw new Error("Tavily requires an API key. Set TAVILY_API_KEY environment variable or configure via /unipi:web-settings");
+    }
+    return searchTavily(query, apiKey);
+  },
+
+  async validateApiKey(apiKey: string): Promise<boolean> {
+    try {
+      const results = await searchTavily("test", apiKey);
+      return Array.isArray(results);
+    } catch {
+      return false;
+    }
+  },
+};
+
+// Register provider
+registry.register(tavilyProvider);
+
+export { tavilyProvider };