@hasna/connectors 0.0.1

package/connectors/connect-exa/src/api/client.ts

@@ -0,0 +1,171 @@
+import type { ExaConfig, OutputFormat } from '../types';
+import { ExaApiError } from '../types';
+
+const DEFAULT_BASE_URL = 'https://api.exa.ai';
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown> | unknown[] | string;
+  headers?: Record<string, string>;
+  format?: OutputFormat;
+}
+
+export class ExaClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+
+  constructor(config: ExaConfig) {
+    if (!config.apiKey) {
+      throw new Error('API key is required');
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    const url = new URL(`${this.baseUrl}${path}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  /**
+   * Make an authenticated request to Exa API
+   * Exa uses x-api-key header for authentication
+   */
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {} } = options;
+
+    const url = this.buildUrl(path, params);
+
+    const requestHeaders: Record<string, string> = {
+      'x-api-key': this.apiKey,
+      'Accept': 'application/json',
+      ...headers,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      requestHeaders['Content-Type'] = 'application/json';
+    }
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    // Handle 204 No Content
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    // Parse response
+    let data: unknown;
+    const contentType = response.headers.get('content-type') || '';
+
+    if (contentType.includes('application/json')) {
+      const text = await response.text();
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = text;
+        }
+      }
+    } else {
+      data = await response.text();
+    }
+
+    // Handle errors
+    if (!response.ok) {
+      const errorMessage = typeof data === 'object' && data !== null
+        ? JSON.stringify(data)
+        : String(data || response.statusText);
+      throw new ExaApiError(errorMessage, response.status);
+    }
+
+    return data as T;
+  }
+
+  /**
+   * Make a streaming request (for answer endpoint)
+   */
+  async *requestStream(path: string, body: Record<string, unknown>): AsyncGenerator<string> {
+    const url = this.buildUrl(path);
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'x-api-key': this.apiKey,
+        'Content-Type': 'application/json',
+        'Accept': 'text/event-stream',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new ExaApiError(text || response.statusText, response.status);
+    }
+
+    if (!response.body) {
+      throw new ExaApiError('No response body for streaming', 500);
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        yield decoder.decode(value, { stream: true });
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown> | unknown[] | string | object, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body: body as Record<string, unknown>, params });
+  }
+
+  async put<T>(path: string, body?: Record<string, unknown> | object, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PUT', body: body as Record<string, unknown>, params });
+  }
+
+  async patch<T>(path: string, body?: Record<string, unknown> | object, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PATCH', body: body as Record<string, unknown>, params });
+  }
+
+  async delete<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE', params });
+  }
+
+  /**
+   * Get a preview of the API key (for display/debugging)
+   */
+  getApiKeyPreview(): string {
+    if (this.apiKey.length > 10) {
+      return `${this.apiKey.substring(0, 6)}...${this.apiKey.substring(this.apiKey.length - 4)}`;
+    }
+    return '***';
+  }
+}

package/connectors/connect-exa/src/api/contents.ts

@@ -0,0 +1,150 @@
+import type { ExaClient } from './client';
+import type { ContentsRequest, ContentsResponse, TextContentsOptions, HighlightsContentsOptions, SummaryContentsOptions } from '../types';
+
+/**
+ * Contents API - Retrieve page contents, text, highlights, and summaries
+ */
+export class ContentsApi {
+  constructor(private readonly client: ExaClient) {}
+
+  /**
+   * Get contents for multiple URLs or IDs
+   */
+  async get(request: ContentsRequest): Promise<ContentsResponse> {
+    const body: Record<string, unknown> = {};
+
+    if (request.ids?.length) {
+      body.ids = request.ids;
+    }
+    if (request.urls?.length) {
+      body.urls = request.urls;
+    }
+    if (request.text !== undefined) {
+      body.text = request.text;
+    }
+    if (request.highlights !== undefined) {
+      body.highlights = request.highlights;
+    }
+    if (request.summary !== undefined) {
+      body.summary = request.summary;
+    }
+
+    return this.client.post<ContentsResponse>('/contents', body);
+  }
+
+  /**
+   * Get text content from URLs
+   */
+  async getText(
+    urls: string[],
+    options: TextContentsOptions = {}
+  ): Promise<ContentsResponse> {
+    return this.get({
+      urls,
+      text: Object.keys(options).length > 0 ? options : true,
+    });
+  }
+
+  /**
+   * Get text content from result IDs
+   */
+  async getTextByIds(
+    ids: string[],
+    options: TextContentsOptions = {}
+  ): Promise<ContentsResponse> {
+    return this.get({
+      ids,
+      text: Object.keys(options).length > 0 ? options : true,
+    });
+  }
+
+  /**
+   * Get highlights from URLs
+   */
+  async getHighlights(
+    urls: string[],
+    options: HighlightsContentsOptions = {}
+  ): Promise<ContentsResponse> {
+    return this.get({
+      urls,
+      highlights: Object.keys(options).length > 0 ? options : true,
+    });
+  }
+
+  /**
+   * Get highlights from result IDs
+   */
+  async getHighlightsByIds(
+    ids: string[],
+    options: HighlightsContentsOptions = {}
+  ): Promise<ContentsResponse> {
+    return this.get({
+      ids,
+      highlights: Object.keys(options).length > 0 ? options : true,
+    });
+  }
+
+  /**
+   * Get summaries from URLs
+   */
+  async getSummaries(
+    urls: string[],
+    options: SummaryContentsOptions = {}
+  ): Promise<ContentsResponse> {
+    return this.get({
+      urls,
+      summary: Object.keys(options).length > 0 ? options : true,
+    });
+  }
+
+  /**
+   * Get summaries from result IDs
+   */
+  async getSummariesByIds(
+    ids: string[],
+    options: SummaryContentsOptions = {}
+  ): Promise<ContentsResponse> {
+    return this.get({
+      ids,
+      summary: Object.keys(options).length > 0 ? options : true,
+    });
+  }
+
+  /**
+   * Get all content types (text, highlights, summary) from URLs
+   */
+  async getAll(
+    urls: string[],
+    options: {
+      text?: TextContentsOptions | boolean;
+      highlights?: HighlightsContentsOptions | boolean;
+      summary?: SummaryContentsOptions | boolean;
+    } = {}
+  ): Promise<ContentsResponse> {
+    return this.get({
+      urls,
+      text: options.text ?? true,
+      highlights: options.highlights ?? true,
+      summary: options.summary ?? true,
+    });
+  }
+
+  /**
+   * Get all content types from result IDs
+   */
+  async getAllByIds(
+    ids: string[],
+    options: {
+      text?: TextContentsOptions | boolean;
+      highlights?: HighlightsContentsOptions | boolean;
+      summary?: SummaryContentsOptions | boolean;
+    } = {}
+  ): Promise<ContentsResponse> {
+    return this.get({
+      ids,
+      text: options.text ?? true,
+      highlights: options.highlights ?? true,
+      summary: options.summary ?? true,
+    });
+  }
+}

package/connectors/connect-exa/src/api/context.ts

@@ -0,0 +1,84 @@
+import type { ExaClient } from './client';
+import type { CodeContextOptions, CodeContextResponse } from '../types';
+
+/**
+ * Context API - Code context search for programming queries
+ */
+export class ContextApi {
+  constructor(private readonly client: ExaClient) {}
+
+  /**
+   * Search for code context
+   * Optimized for programming-related queries to find relevant documentation,
+   * tutorials, examples, and technical content
+   */
+  async search(options: CodeContextOptions): Promise<CodeContextResponse> {
+    const body: Record<string, unknown> = {
+      query: options.query,
+      tokensNum: options.tokensNum ?? 'dynamic',
+    };
+
+    return this.client.post<CodeContextResponse>('/context', body);
+  }
+
+  /**
+   * Quick search with default options
+   */
+  async query(query: string): Promise<CodeContextResponse> {
+    return this.search({ query });
+  }
+
+  /**
+   * Search with a specific token limit
+   */
+  async queryWithTokens(query: string, tokensNum: number | 'dynamic'): Promise<CodeContextResponse> {
+    return this.search({ query, tokensNum });
+  }
+
+  /**
+   * Search for API documentation
+   */
+  async searchApiDocs(library: string, topic?: string): Promise<CodeContextResponse> {
+    const query = topic ? `${library} ${topic} API documentation` : `${library} API documentation`;
+    return this.search({ query });
+  }
+
+  /**
+   * Search for code examples
+   */
+  async searchExamples(topic: string, language?: string): Promise<CodeContextResponse> {
+    const query = language ? `${topic} ${language} code examples` : `${topic} code examples`;
+    return this.search({ query });
+  }
+
+  /**
+   * Search for tutorials
+   */
+  async searchTutorials(topic: string): Promise<CodeContextResponse> {
+    return this.search({ query: `${topic} tutorial guide` });
+  }
+
+  /**
+   * Search for best practices
+   */
+  async searchBestPractices(topic: string): Promise<CodeContextResponse> {
+    return this.search({ query: `${topic} best practices guidelines` });
+  }
+
+  /**
+   * Search for troubleshooting information
+   */
+  async searchTroubleshooting(issue: string): Promise<CodeContextResponse> {
+    return this.search({ query: `${issue} solution fix troubleshoot` });
+  }
+
+  /**
+   * Get context as a string (useful for LLM prompts)
+   * Returns the formatted response from Exa's context API
+   */
+  async getContextString(query: string, options: { tokensNum?: number | 'dynamic' } = {}): Promise<string> {
+    const { tokensNum } = options;
+    const response = await this.search({ query, tokensNum });
+    return response.response;
+  }
+}

package/connectors/connect-exa/src/api/index.ts

@@ -0,0 +1,77 @@
+import type { ExaConfig } from '../types';
+import { ExaClient } from './client';
+import { SearchApi } from './search';
+import { ContentsApi } from './contents';
+import { SimilarApi } from './similar';
+import { AnswerApi } from './answer';
+import { ContextApi } from './context';
+import { ResearchApi } from './research';
+import { WebsetsApi } from './websets';
+import { TeamApi } from './team';
+
+/**
+ * Exa AI Search API client
+ * Provides access to all Exa API endpoints
+ */
+export class Exa {
+  private readonly client: ExaClient;
+
+  // API modules
+  public readonly search: SearchApi;
+  public readonly contents: ContentsApi;
+  public readonly similar: SimilarApi;
+  public readonly answer: AnswerApi;
+  public readonly context: ContextApi;
+  public readonly research: ResearchApi;
+  public readonly websets: WebsetsApi;
+  public readonly team: TeamApi;
+
+  constructor(config: ExaConfig) {
+    this.client = new ExaClient(config);
+    this.search = new SearchApi(this.client);
+    this.contents = new ContentsApi(this.client);
+    this.similar = new SimilarApi(this.client);
+    this.answer = new AnswerApi(this.client);
+    this.context = new ContextApi(this.client);
+    this.research = new ResearchApi(this.client);
+    this.websets = new WebsetsApi(this.client);
+    this.team = new TeamApi(this.client);
+  }
+
+  /**
+   * Create a client from environment variables
+   * Looks for EXA_API_KEY
+   */
+  static fromEnv(): Exa {
+    const apiKey = process.env.EXA_API_KEY;
+
+    if (!apiKey) {
+      throw new Error('EXA_API_KEY environment variable is required');
+    }
+    return new Exa({ apiKey });
+  }
+
+  /**
+   * Get a preview of the API key (for debugging)
+   */
+  getApiKeyPreview(): string {
+    return this.client.getApiKeyPreview();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): ExaClient {
+    return this.client;
+  }
+}
+
+export { ExaClient } from './client';
+export { SearchApi } from './search';
+export { ContentsApi } from './contents';
+export { SimilarApi } from './similar';
+export { AnswerApi } from './answer';
+export { ContextApi } from './context';
+export { ResearchApi } from './research';
+export { WebsetsApi } from './websets';
+export { TeamApi } from './team';

package/connectors/connect-exa/src/api/research.ts

@@ -0,0 +1,154 @@
+import type { ExaClient } from './client';
+import type {
+  ResearchTask,
+  ResearchCreateOptions,
+  ResearchListParams,
+  ResearchListResponse,
+} from '../types';
+
+/**
+ * Research API - Async research tasks for comprehensive investigations
+ */
+export class ResearchApi {
+  constructor(private readonly client: ExaClient) {}
+
+  /**
+   * Create a new research task
+   */
+  async create(options: ResearchCreateOptions): Promise<ResearchTask> {
+    const body: Record<string, unknown> = {
+      query: options.query,
+    };
+
+    if (options.depth) {
+      body.depth = options.depth;
+    }
+
+    return this.client.post<ResearchTask>('/research', body);
+  }
+
+  /**
+   * Get a research task by ID
+   */
+  async get(taskId: string): Promise<ResearchTask> {
+    return this.client.get<ResearchTask>(`/research/${taskId}`);
+  }
+
+  /**
+   * List research tasks
+   */
+  async list(params: ResearchListParams = {}): Promise<ResearchListResponse> {
+    const queryParams: Record<string, string | number | boolean | undefined> = {};
+
+    if (params.limit !== undefined) {
+      queryParams.limit = params.limit;
+    }
+    if (params.offset !== undefined) {
+      queryParams.offset = params.offset;
+    }
+    if (params.status) {
+      queryParams.status = params.status;
+    }
+
+    return this.client.get<ResearchListResponse>('/research', queryParams);
+  }
+
+  /**
+   * Cancel a research task
+   */
+  async cancel(taskId: string): Promise<ResearchTask> {
+    return this.client.post<ResearchTask>(`/research/${taskId}/cancel`);
+  }
+
+  /**
+   * Create a basic research task
+   */
+  async createBasic(query: string): Promise<ResearchTask> {
+    return this.create({ query, depth: 'basic' });
+  }
+
+  /**
+   * Create a thorough research task
+   */
+  async createThorough(query: string): Promise<ResearchTask> {
+    return this.create({ query, depth: 'thorough' });
+  }
+
+  /**
+   * Create a comprehensive research task
+   */
+  async createComprehensive(query: string): Promise<ResearchTask> {
+    return this.create({ query, depth: 'comprehensive' });
+  }
+
+  /**
+   * Wait for a research task to complete
+   * Polls the task status until it's completed, failed, or timeout
+   */
+  async waitForCompletion(
+    taskId: string,
+    options: {
+      pollIntervalMs?: number;
+      timeoutMs?: number;
+    } = {}
+  ): Promise<ResearchTask> {
+    const { pollIntervalMs = 5000, timeoutMs = 300000 } = options;
+    const startTime = Date.now();
+
+    while (true) {
+      const task = await this.get(taskId);
+
+      if (task.status === 'completed' || task.status === 'failed') {
+        return task;
+      }
+
+      if (Date.now() - startTime > timeoutMs) {
+        throw new Error(`Research task ${taskId} timed out after ${timeoutMs}ms`);
+      }
+
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+    }
+  }
+
+  /**
+   * Create and wait for a research task to complete
+   */
+  async createAndWait(
+    options: ResearchCreateOptions,
+    waitOptions: {
+      pollIntervalMs?: number;
+      timeoutMs?: number;
+    } = {}
+  ): Promise<ResearchTask> {
+    const task = await this.create(options);
+    return this.waitForCompletion(task.id, waitOptions);
+  }
+
+  /**
+   * List pending tasks
+   */
+  async listPending(limit?: number): Promise<ResearchListResponse> {
+    return this.list({ status: 'pending', limit });
+  }
+
+  /**
+   * List running tasks
+   */
+  async listRunning(limit?: number): Promise<ResearchListResponse> {
+    return this.list({ status: 'running', limit });
+  }
+
+  /**
+   * List completed tasks
+   */
+  async listCompleted(limit?: number): Promise<ResearchListResponse> {
+    return this.list({ status: 'completed', limit });
+  }
+
+  /**
+   * List failed tasks
+   */
+  async listFailed(limit?: number): Promise<ResearchListResponse> {
+    return this.list({ status: 'failed', limit });
+  }
+}