@hasna/connectors 0.0.1

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

@@ -0,0 +1,153 @@
+import type { ExaClient } from './client';
+import type { SearchOptions, SearchResponse, SearchCategory } from '../types';
+
+/**
+ * Search API - Web search with neural, keyword, or auto modes
+ */
+export class SearchApi {
+  constructor(private readonly client: ExaClient) {}
+
+  /**
+   * Perform a web search
+   * Supports neural (semantic), keyword, or auto (hybrid) search modes
+   */
+  async search(options: SearchOptions): Promise<SearchResponse> {
+    const body: Record<string, unknown> = {
+      query: options.query,
+    };
+
+    if (options.useAutoprompt !== undefined) {
+      body.useAutoprompt = options.useAutoprompt;
+    }
+    if (options.type) {
+      body.type = options.type;
+    }
+    if (options.category) {
+      body.category = options.category;
+    }
+    if (options.numResults !== undefined) {
+      body.numResults = options.numResults;
+    }
+    if (options.includeDomains?.length) {
+      body.includeDomains = options.includeDomains;
+    }
+    if (options.excludeDomains?.length) {
+      body.excludeDomains = options.excludeDomains;
+    }
+    if (options.startCrawlDate) {
+      body.startCrawlDate = options.startCrawlDate;
+    }
+    if (options.endCrawlDate) {
+      body.endCrawlDate = options.endCrawlDate;
+    }
+    if (options.startPublishedDate) {
+      body.startPublishedDate = options.startPublishedDate;
+    }
+    if (options.endPublishedDate) {
+      body.endPublishedDate = options.endPublishedDate;
+    }
+    if (options.includeText?.length) {
+      body.includeText = options.includeText;
+    }
+    if (options.excludeText?.length) {
+      body.excludeText = options.excludeText;
+    }
+    if (options.contents) {
+      body.contents = options.contents;
+    }
+
+    return this.client.post<SearchResponse>('/search', body);
+  }
+
+  /**
+   * Neural search (semantic/AI-powered)
+   */
+  async neural(query: string, options: Omit<SearchOptions, 'query' | 'type'> = {}): Promise<SearchResponse> {
+    return this.search({ ...options, query, type: 'neural' });
+  }
+
+  /**
+   * Keyword search (traditional)
+   */
+  async keyword(query: string, options: Omit<SearchOptions, 'query' | 'type'> = {}): Promise<SearchResponse> {
+    return this.search({ ...options, query, type: 'keyword' });
+  }
+
+  /**
+   * Auto search (hybrid - lets Exa decide)
+   */
+  async auto(query: string, options: Omit<SearchOptions, 'query' | 'type'> = {}): Promise<SearchResponse> {
+    return this.search({ ...options, query, type: 'auto' });
+  }
+
+  /**
+   * Search with autoprompt enabled (Exa will optimize the query)
+   */
+  async searchWithAutoprompt(query: string, options: Omit<SearchOptions, 'query' | 'useAutoprompt'> = {}): Promise<SearchResponse> {
+    return this.search({ ...options, query, useAutoprompt: true });
+  }
+
+  /**
+   * Search within a specific category
+   */
+  async searchCategory(
+    query: string,
+    category: SearchCategory,
+    options: Omit<SearchOptions, 'query' | 'category'> = {}
+  ): Promise<SearchResponse> {
+    return this.search({ ...options, query, category });
+  }
+
+  /**
+   * Search and get contents inline
+   */
+  async searchAndContents(
+    query: string,
+    options: Omit<SearchOptions, 'query'> = {}
+  ): Promise<SearchResponse> {
+    const contentsOptions = options.contents || { text: true };
+    return this.search({ ...options, query, contents: contentsOptions });
+  }
+
+  /**
+   * Search with domain filtering
+   */
+  async searchDomains(
+    query: string,
+    options: {
+      includeDomains?: string[];
+      excludeDomains?: string[];
+      numResults?: number;
+    } = {}
+  ): Promise<SearchResponse> {
+    return this.search({
+      query,
+      includeDomains: options.includeDomains,
+      excludeDomains: options.excludeDomains,
+      numResults: options.numResults,
+    });
+  }
+
+  /**
+   * Search with date filtering
+   */
+  async searchDateRange(
+    query: string,
+    options: {
+      startCrawlDate?: string;
+      endCrawlDate?: string;
+      startPublishedDate?: string;
+      endPublishedDate?: string;
+      numResults?: number;
+    } = {}
+  ): Promise<SearchResponse> {
+    return this.search({
+      query,
+      startCrawlDate: options.startCrawlDate,
+      endCrawlDate: options.endCrawlDate,
+      startPublishedDate: options.startPublishedDate,
+      endPublishedDate: options.endPublishedDate,
+      numResults: options.numResults,
+    });
+  }
+}

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

@@ -0,0 +1,138 @@
+import type { ExaClient } from './client';
+import type { FindSimilarOptions, FindSimilarResponse, SearchCategory } from '../types';
+
+/**
+ * Similar API - Find pages similar to a given URL
+ */
+export class SimilarApi {
+  constructor(private readonly client: ExaClient) {}
+
+  /**
+   * Find pages similar to a URL
+   */
+  async find(options: FindSimilarOptions): Promise<FindSimilarResponse> {
+    const body: Record<string, unknown> = {
+      url: options.url,
+    };
+
+    if (options.numResults !== undefined) {
+      body.numResults = options.numResults;
+    }
+    if (options.includeDomains?.length) {
+      body.includeDomains = options.includeDomains;
+    }
+    if (options.excludeDomains?.length) {
+      body.excludeDomains = options.excludeDomains;
+    }
+    if (options.startCrawlDate) {
+      body.startCrawlDate = options.startCrawlDate;
+    }
+    if (options.endCrawlDate) {
+      body.endCrawlDate = options.endCrawlDate;
+    }
+    if (options.startPublishedDate) {
+      body.startPublishedDate = options.startPublishedDate;
+    }
+    if (options.endPublishedDate) {
+      body.endPublishedDate = options.endPublishedDate;
+    }
+    if (options.includeText?.length) {
+      body.includeText = options.includeText;
+    }
+    if (options.excludeText?.length) {
+      body.excludeText = options.excludeText;
+    }
+    if (options.excludeSourceDomain !== undefined) {
+      body.excludeSourceDomain = options.excludeSourceDomain;
+    }
+    if (options.category) {
+      body.category = options.category;
+    }
+    if (options.contents) {
+      body.contents = options.contents;
+    }
+
+    return this.client.post<FindSimilarResponse>('/findSimilar', body);
+  }
+
+  /**
+   * Find similar pages with a specific limit
+   */
+  async findWithLimit(url: string, numResults: number): Promise<FindSimilarResponse> {
+    return this.find({ url, numResults });
+  }
+
+  /**
+   * Find similar pages excluding the source domain
+   */
+  async findExcludingSource(url: string, numResults?: number): Promise<FindSimilarResponse> {
+    return this.find({ url, numResults, excludeSourceDomain: true });
+  }
+
+  /**
+   * Find similar pages within specific domains
+   */
+  async findInDomains(
+    url: string,
+    includeDomains: string[],
+    numResults?: number
+  ): Promise<FindSimilarResponse> {
+    return this.find({ url, includeDomains, numResults });
+  }
+
+  /**
+   * Find similar pages excluding specific domains
+   */
+  async findExcludingDomains(
+    url: string,
+    excludeDomains: string[],
+    numResults?: number
+  ): Promise<FindSimilarResponse> {
+    return this.find({ url, excludeDomains, numResults });
+  }
+
+  /**
+   * Find similar pages in a specific category
+   */
+  async findInCategory(
+    url: string,
+    category: SearchCategory,
+    numResults?: number
+  ): Promise<FindSimilarResponse> {
+    return this.find({ url, category, numResults });
+  }
+
+  /**
+   * Find similar pages and get contents inline
+   */
+  async findWithContents(
+    url: string,
+    options: Omit<FindSimilarOptions, 'url'> = {}
+  ): Promise<FindSimilarResponse> {
+    const contentsOptions = options.contents || { text: true };
+    return this.find({ ...options, url, contents: contentsOptions });
+  }
+
+  /**
+   * Find similar pages within a date range
+   */
+  async findDateRange(
+    url: string,
+    options: {
+      startCrawlDate?: string;
+      endCrawlDate?: string;
+      startPublishedDate?: string;
+      endPublishedDate?: string;
+      numResults?: number;
+    }
+  ): Promise<FindSimilarResponse> {
+    return this.find({
+      url,
+      startCrawlDate: options.startCrawlDate,
+      endCrawlDate: options.endCrawlDate,
+      startPublishedDate: options.startPublishedDate,
+      endPublishedDate: options.endPublishedDate,
+      numResults: options.numResults,
+    });
+  }
+}

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

@@ -0,0 +1,165 @@
+import type { ExaClient } from './client';
+import type {
+  ApiKey,
+  ApiKeyCreateOptions,
+  ApiKeyUpdateOptions,
+  ApiKeyUsage,
+  ApiKeyListResponse,
+} from '../types';
+
+/**
+ * Team API - API key management
+ */
+export class TeamApi {
+  constructor(private readonly client: ExaClient) {}
+
+  /**
+   * List all API keys
+   */
+  async listKeys(): Promise<ApiKeyListResponse> {
+    return this.client.get<ApiKeyListResponse>('/team/api-keys');
+  }
+
+  /**
+   * Create a new API key
+   */
+  async createKey(options: ApiKeyCreateOptions): Promise<ApiKey> {
+    const body: Record<string, unknown> = {
+      name: options.name,
+    };
+
+    if (options.rateLimit !== undefined) {
+      body.rateLimit = options.rateLimit;
+    }
+    if (options.monthlyLimit !== undefined) {
+      body.monthlyLimit = options.monthlyLimit;
+    }
+
+    return this.client.post<ApiKey>('/team/api-keys', body);
+  }
+
+  /**
+   * Get an API key by ID
+   */
+  async getKey(keyId: string): Promise<ApiKey> {
+    return this.client.get<ApiKey>(`/team/api-keys/${keyId}`);
+  }
+
+  /**
+   * Update an API key
+   */
+  async updateKey(keyId: string, options: ApiKeyUpdateOptions): Promise<ApiKey> {
+    const body: Record<string, unknown> = {};
+
+    if (options.name !== undefined) {
+      body.name = options.name;
+    }
+    if (options.rateLimit !== undefined) {
+      body.rateLimit = options.rateLimit;
+    }
+    if (options.monthlyLimit !== undefined) {
+      body.monthlyLimit = options.monthlyLimit;
+    }
+
+    return this.client.patch<ApiKey>(`/team/api-keys/${keyId}`, body);
+  }
+
+  /**
+   * Delete an API key
+   */
+  async deleteKey(keyId: string): Promise<void> {
+    await this.client.delete<void>(`/team/api-keys/${keyId}`);
+  }
+
+  /**
+   * Get usage for an API key
+   */
+  async getKeyUsage(keyId: string, period?: string): Promise<ApiKeyUsage> {
+    const params: Record<string, string | number | boolean | undefined> = {};
+    if (period) {
+      params.period = period;
+    }
+
+    return this.client.get<ApiKeyUsage>(`/team/api-keys/${keyId}/usage`, params);
+  }
+
+  /**
+   * Get usage for all API keys
+   */
+  async getAllUsage(period?: string): Promise<ApiKeyUsage[]> {
+    const params: Record<string, string | number | boolean | undefined> = {};
+    if (period) {
+      params.period = period;
+    }
+
+    const response = await this.client.get<{ usage: ApiKeyUsage[] }>('/team/usage', params);
+    return response.usage;
+  }
+
+  // ============================================
+  // Convenience Methods
+  // ============================================
+
+  /**
+   * Create a key with rate limiting
+   */
+  async createRateLimitedKey(name: string, rateLimit: number): Promise<ApiKey> {
+    return this.createKey({ name, rateLimit });
+  }
+
+  /**
+   * Create a key with monthly limit
+   */
+  async createMonthlyLimitedKey(name: string, monthlyLimit: number): Promise<ApiKey> {
+    return this.createKey({ name, monthlyLimit });
+  }
+
+  /**
+   * Create a fully limited key
+   */
+  async createLimitedKey(
+    name: string,
+    rateLimit: number,
+    monthlyLimit: number
+  ): Promise<ApiKey> {
+    return this.createKey({ name, rateLimit, monthlyLimit });
+  }
+
+  /**
+   * Rename an API key
+   */
+  async renameKey(keyId: string, name: string): Promise<ApiKey> {
+    return this.updateKey(keyId, { name });
+  }
+
+  /**
+   * Update rate limit for an API key
+   */
+  async updateRateLimit(keyId: string, rateLimit: number): Promise<ApiKey> {
+    return this.updateKey(keyId, { rateLimit });
+  }
+
+  /**
+   * Update monthly limit for an API key
+   */
+  async updateMonthlyLimit(keyId: string, monthlyLimit: number): Promise<ApiKey> {
+    return this.updateKey(keyId, { monthlyLimit });
+  }
+
+  /**
+   * List keys and their usage
+   */
+  async listKeysWithUsage(period?: string): Promise<Array<ApiKey & { usage?: ApiKeyUsage }>> {
+    const [keysResponse, usageList] = await Promise.all([
+      this.listKeys(),
+      this.getAllUsage(period),
+    ]);
+
+    const usageMap = new Map(usageList.map(u => [u.keyId, u]));
+
+    return keysResponse.keys.map(key => ({
+      ...key,
+      usage: usageMap.get(key.id),
+    }));
+  }
+}

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

@@ -0,0 +1,228 @@
+import type { ExaClient } from './client';
+import type {
+  Webset,
+  WebsetCreateOptions,
+  WebsetListParams,
+  WebsetListResponse,
+  WebsetItem,
+  WebsetItemsResponse,
+  WebsetEnrichment,
+  WebsetEnrichmentCreateOptions,
+} from '../types';
+
+/**
+ * Websets API - Entity search result sets
+ */
+export class WebsetsApi {
+  constructor(private readonly client: ExaClient) {}
+
+  /**
+   * Create a new webset
+   */
+  async create(options: WebsetCreateOptions): Promise<Webset> {
+    const body: Record<string, unknown> = {
+      searches: options.searches,
+    };
+
+    if (options.externalId) {
+      body.externalId = options.externalId;
+    }
+
+    return this.client.post<Webset>('/websets', body);
+  }
+
+  /**
+   * Get a webset by ID
+   */
+  async get(websetId: string): Promise<Webset> {
+    return this.client.get<Webset>(`/websets/${websetId}`);
+  }
+
+  /**
+   * List websets
+   */
+  async list(params: WebsetListParams = {}): Promise<WebsetListResponse> {
+    const queryParams: Record<string, string | number | boolean | undefined> = {};
+
+    if (params.limit !== undefined) {
+      queryParams.limit = params.limit;
+    }
+    if (params.cursor) {
+      queryParams.cursor = params.cursor;
+    }
+    if (params.status) {
+      queryParams.status = params.status;
+    }
+
+    return this.client.get<WebsetListResponse>('/websets', queryParams);
+  }
+
+  /**
+   * Delete a webset
+   */
+  async delete(websetId: string): Promise<void> {
+    await this.client.delete<void>(`/websets/${websetId}`);
+  }
+
+  /**
+   * Cancel a running webset
+   */
+  async cancel(websetId: string): Promise<Webset> {
+    return this.client.post<Webset>(`/websets/${websetId}/cancel`);
+  }
+
+  // ============================================
+  // Webset Items
+  // ============================================
+
+  /**
+   * List items in a webset
+   */
+  async listItems(
+    websetId: string,
+    params: { limit?: number; cursor?: string } = {}
+  ): Promise<WebsetItemsResponse> {
+    const queryParams: Record<string, string | number | boolean | undefined> = {};
+
+    if (params.limit !== undefined) {
+      queryParams.limit = params.limit;
+    }
+    if (params.cursor) {
+      queryParams.cursor = params.cursor;
+    }
+
+    return this.client.get<WebsetItemsResponse>(`/websets/${websetId}/items`, queryParams);
+  }
+
+  /**
+   * Get a specific item in a webset
+   */
+  async getItem(websetId: string, itemId: string): Promise<WebsetItem> {
+    return this.client.get<WebsetItem>(`/websets/${websetId}/items/${itemId}`);
+  }
+
+  /**
+   * Get all items in a webset (handles pagination)
+   */
+  async getAllItems(websetId: string): Promise<WebsetItem[]> {
+    const allItems: WebsetItem[] = [];
+    let cursor: string | undefined;
+
+    do {
+      const response = await this.listItems(websetId, { cursor, limit: 100 });
+      allItems.push(...response.items);
+      cursor = response.hasMore ? response.cursor : undefined;
+    } while (cursor);
+
+    return allItems;
+  }
+
+  // ============================================
+  // Webset Enrichments
+  // ============================================
+
+  /**
+   * Create an enrichment for a webset
+   */
+  async createEnrichment(
+    websetId: string,
+    options: WebsetEnrichmentCreateOptions
+  ): Promise<WebsetEnrichment> {
+    return this.client.post<WebsetEnrichment>(`/websets/${websetId}/enrichments`, {
+      name: options.name,
+      description: options.description,
+      format: options.format,
+    });
+  }
+
+  /**
+   * List enrichments for a webset
+   */
+  async listEnrichments(websetId: string): Promise<WebsetEnrichment[]> {
+    const response = await this.client.get<{ enrichments: WebsetEnrichment[] }>(
+      `/websets/${websetId}/enrichments`
+    );
+    return response.enrichments;
+  }
+
+  /**
+   * Get a specific enrichment
+   */
+  async getEnrichment(websetId: string, enrichmentId: string): Promise<WebsetEnrichment> {
+    return this.client.get<WebsetEnrichment>(
+      `/websets/${websetId}/enrichments/${enrichmentId}`
+    );
+  }
+
+  /**
+   * Delete an enrichment
+   */
+  async deleteEnrichment(websetId: string, enrichmentId: string): Promise<void> {
+    await this.client.delete<void>(`/websets/${websetId}/enrichments/${enrichmentId}`);
+  }
+
+  // ============================================
+  // Convenience Methods
+  // ============================================
+
+  /**
+   * Wait for a webset to complete
+   */
+  async waitForCompletion(
+    websetId: string,
+    options: {
+      pollIntervalMs?: number;
+      timeoutMs?: number;
+    } = {}
+  ): Promise<Webset> {
+    const { pollIntervalMs = 5000, timeoutMs = 600000 } = options;
+    const startTime = Date.now();
+
+    while (true) {
+      const webset = await this.get(websetId);
+
+      if (webset.status === 'completed' || webset.status === 'failed' || webset.status === 'canceled') {
+        return webset;
+      }
+
+      if (Date.now() - startTime > timeoutMs) {
+        throw new Error(`Webset ${websetId} timed out after ${timeoutMs}ms`);
+      }
+
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+    }
+  }
+
+  /**
+   * Create a webset and wait for it to complete
+   */
+  async createAndWait(
+    options: WebsetCreateOptions,
+    waitOptions: {
+      pollIntervalMs?: number;
+      timeoutMs?: number;
+    } = {}
+  ): Promise<Webset> {
+    const webset = await this.create(options);
+    return this.waitForCompletion(webset.id, waitOptions);
+  }
+
+  /**
+   * Create a simple webset with a single search
+   */
+  async createSimple(
+    query: string,
+    entityType: string,
+    numResults?: number
+  ): Promise<Webset> {
+    return this.create({
+      searches: [
+        {
+          query,
+          entity: { type: entityType },
+          numResults,
+        },
+      ],
+    });
+  }
+}