nosible 0.1.5

package/src/client.ts

@@ -0,0 +1,762 @@
+/**
+ * Nosible AI Search API Client
+ *
+ * A comprehensive TypeScript client for interacting with the Nosible AI-powered search engine.
+ * This client provides fast, comprehensive, and bulk search capabilities across web-scale data,
+ * along with URL scraping and topic trend analysis features.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import { NosibleClient } from 'nosible-js';
+ *
+ * // Initialize with API key
+ * const client = new NosibleClient('your-api-key');
+ *
+ * // Or use environment variable NOSIBLE_API_KEY
+ * const client = new NosibleClient();
+ *
+ * // Perform a fast search
+ * const results = await client.fastSearch({
+ *   question: 'Who has invested in Nosible?',
+ *   nResults: 15
+ * });
+ *
+ * // Perform AI-powered search
+ * const aiResults = await client.aiSearch({
+ *   question: 'What are the latest trends in AI technology?',
+ *   instruction: 'Focus on recent developments and breakthrough innovations'
+ * });
+ *
+ * // Scrape a URL
+ * const webpage = await client.scrapeUrl('https://example.com');
+ *
+ * // Analyze topic trends
+ * const trends = await client.topicTrend('artificial intelligence');
+ * ```
+ */
+
+import {type SqlFilter} from "./search/sqlFilter";
+import {
+  Search,
+  userSearchParamsSchema,
+  clientDefaultSearchParamsSchema,
+  type ClientDefaultSearchParamsType,
+  type ClientSearchParamsSchema,
+  type UserAiSearchParamsType,
+  type UserSearchParamsType,
+} from "./search/search";
+import {WebPageData} from "./scrape/webPageData";
+import {TopicTrend} from "./topicTrend/topicTrend";
+import type {BulkResType, ScrapeFullRes, SearchResType} from "./api/schemas";
+import {getLimiters, getUserPlan, type Plan} from "./utils/userPlan";
+import type Bottleneck from "bottleneck";
+import {OpenAI} from "openai";
+import z from "zod";
+import {createResultSet} from "./search/resultFactory";
+import {createResult} from "./search/resultFactory";
+import type {ResultSet} from "./search/resultSet";
+import {bulkSearchDownload} from "./search/bulkSearch";
+import {
+  callNosibleApi,
+  validateFastSearchParams,
+  validateBulkSearchParams,
+} from "./api/index";
+import {SearchSet} from "./search/searchSet";
+
+const fastSearchesParamsSchema = z.union([
+  userSearchParamsSchema.omit({question: true}).extend({
+    questions: z.array(z.string()),
+  }),
+  z.instanceof(SearchSet),
+]);
+
+export type FastSearchesParamsType = z.infer<typeof fastSearchesParamsSchema>;
+
+/**
+ * Nosible API Client
+ *
+ * Main client class for interacting with the Nosible AI Search API.
+ * Provides methods for fast search, standard search, and bulk search operations.
+ *
+ * @example
+ * ```typescript
+ * // Initialize with API key
+ * const client = new Nosible('your-api-key');
+ *
+ * // Or use environment variable NOSIBLE_API_KEY
+ * const client = new Nosible();
+ *
+ * // Perform a fast search
+ * const results = await client.fastSearch({
+ *   question: 'Who has invested in Nosible?',
+ *   nResults: 15
+ * });
+ * ```
+ */
+const nosibleClientParams = z.union([
+  z.string(),
+  z.object({
+    apiKey: z.string(),
+    llmApiKey: z.string().optional(),
+    openAiBaseURL: z.string().optional(),
+    sentimentModel: z.string().optional(),
+    expansionsModel: z.string().optional(),
+    searchDefaults: clientDefaultSearchParamsSchema.optional(),
+  }),
+]);
+
+/**
+ * Configuration options for initializing the NosibleClient.
+ *
+ * Can be provided as a string (API key only) or as an object with detailed configuration.
+ *
+ * @example
+ * ```typescript
+ * // Simple string API key
+ * const client = new NosibleClient('your-api-key');
+ *
+ * // Object with both API keys
+ * const client = new NosibleClient({
+ *   apiKey: 'your-nosible-api-key',
+ *   llmApiKey: 'your-openrouter-api-key' // Optional, for LLM features
+ * });
+ * ```
+ */
+export type NosibleClientParams = z.infer<typeof nosibleClientParams>;
+/**
+ * Nosible API Client
+ *
+ * The main client class for interacting with the Nosible AI Search API. This class provides
+ * a comprehensive interface for performing various types of searches, scraping web content,
+ * and analyzing topic trends.
+ *
+ * Features:
+ * - **Fast Search**: Quick, optimized searches with configurable result limits (10-100 results)
+ * - **AI Search**: Advanced AI-powered searches with custom instructions
+ * - **Bulk Search**: Large-scale searches for extensive data collection (1000-10000 results)
+ * - **URL Scraping**: Extract structured content from web pages
+ * - **Topic Trends**: Analyze trending topics and their popularity over time
+ *
+ * The client automatically handles rate limiting, request validation, and response parsing.
+ * It also supports optional OpenRouter integration for enhanced LLM capabilities.
+ *
+ * @example
+ * ```typescript
+ * // Initialize with API key
+ * const client = new NosibleClient('your-api-key');
+ *
+ * // Or use environment variable NOSIBLE_API_KEY
+ * const client = new NosibleClient();
+ *
+ * // Initialize with default search parameters
+ * const clientWithDefaults = new NosibleClient({
+ *   apiKey: 'your-api-key',
+ *   searchDefaults: {
+ *     nResults: 20,
+ *     algorithm: 'hybrid-2',
+ *     continent: 'North America'
+ *   }
+ * });
+ *
+ * // Perform a fast search (will use defaults from client)
+ * const results = await clientWithDefaults.fastSearch({
+ *   question: 'Who has invested in Nosible?'
+ *   // nResults, algorithm, and continent will use defaults
+ * });
+ *
+ * // Perform a fast search
+ * const results = await client.fastSearch({
+ *   question: 'Who has invested in Nosible?',
+ *   nResults: 15
+ * });
+ *
+ * // Access search results
+ * console.log(`Found ${results.length} results`);
+ * results.forEach(result => {
+ *   console.log(`Title: ${result.title}`);
+ *   console.log(`URL: ${result.url}`);
+ *   console.log(`Content: ${result.content.substring(0, 200)}...`);
+ * });
+ * ```
+ */
+export class NosibleClient {
+  /** Base URL for the Nosible API */
+  private baseUrl: string = "https://www.nosible.ai/search/v2";
+  /** Your Nosible API key for authentication */
+  private apiKey: string;
+  /** Optional OpenAI client for LLM integration via OpenRouter */
+  public llmClient: OpenAI | undefined;
+  /** LLM model to use for expansions */
+  public expansionsModel: string = "openai/gpt-4o";
+  /** Default search parameters to apply to all searches */
+  private searchDefaults: ClientDefaultSearchParamsType | undefined;
+  /** User plan information determining rate limits and quotas */
+  private plan: Plan;
+  /** Rate limiters for different API endpoints to prevent quota exceeded errors */
+  private limiters: {
+    /** Rate limiter for URL scraping operations */
+    scrapeUrl: Bottleneck;
+    /** Rate limiter for bulk search operations */
+    bulk: Bottleneck;
+    /** Rate limiter for fast search operations */
+    fast: Bottleneck;
+  };
+
+  /**
+   * Creates a new NosibleClient instance.
+   *
+   * The client can be initialized in several ways:
+   * - With a string API key
+   * - With an object containing API keys
+   * - With no parameters (uses environment variables)
+   *
+   * Environment variables:
+   * - `NOSIBLE_API_KEY`: Your Nosible API key (required if no params provided)
+   * - `LLM_API_KEY`: Optional OpenRouter API key for LLM features
+   *
+   * @param params - Configuration options. Can be a string API key or an object with detailed configuration.
+   *
+   * @throws {Error} When no valid API key is provided
+   *
+   * @example
+   * ```typescript
+   * // Initialize with string API key
+   * const client = new NosibleClient('your-api-key');
+   *
+   * // Initialize with object configuration
+   * const client = new NosibleClient({
+   *   apiKey: 'your-nosible-api-key',
+   *   llmApiKey: 'your-openrouter-api-key'
+   * });
+   *
+   * // Initialize with default search parameters
+   * const client = new NosibleClient({
+   *   apiKey: 'your-nosible-api-key',
+   *   searchDefaults: {
+   *     nResults: 20,
+   *     algorithm: 'hybrid-2',
+   *     continent: 'North America'
+   *   }
+   * });
+   *
+   * // Initialize using environment variables
+   * const client = new NosibleClient();
+   * ```
+   */
+  constructor(params?: NosibleClientParams) {
+    /** Extract API key from string parameter */
+    let apiKeyToUse: string | undefined;
+    /** Extract OpenRouter API key for optional LLM integration */
+    let llmApiKeyToUse: string | undefined;
+    let openAiBaseURL: string | undefined;
+    let searchDefaultsToUse: ClientDefaultSearchParamsType | undefined;
+
+    if (typeof params === "string") {
+      // string param provided
+      apiKeyToUse = params;
+    } else if (params) {
+      // object params provided
+      apiKeyToUse = params.apiKey;
+      llmApiKeyToUse = params.llmApiKey;
+      openAiBaseURL = params.openAiBaseURL;
+      searchDefaultsToUse = params.searchDefaults;
+    } else {
+      // no params provided - use environment variables
+      apiKeyToUse = process.env.NOSIBLE_API_KEY;
+      llmApiKeyToUse = process.env.LLM_API_KEY;
+    }
+
+    /** Validate and set the Nosible API key */
+    if (!apiKeyToUse) {
+      throw new Error("API key is required");
+    } else {
+      this.verifyAndSetApiKey(apiKeyToUse);
+    }
+
+    /** Initialize OpenAI client for LLM integration if OpenRouter API key is provided */
+    if (llmApiKeyToUse) {
+      this.llmClient = new OpenAI({
+        apiKey: llmApiKeyToUse,
+        baseURL: openAiBaseURL,
+      });
+    }
+
+    /** Store API key, default search params, and initialize rate limiters based on user plan */
+    this.apiKey = apiKeyToUse;
+    this.searchDefaults = searchDefaultsToUse;
+    this.plan = getUserPlan(this.apiKey);
+    this.limiters = getLimiters(this.apiKey);
+  }
+
+  /**
+   * Merges default search parameters with provided search parameters.
+   *
+   * Provided parameters take precedence over default parameters.
+   *
+   * @param params - The search parameters provided by the user
+   * @returns Merged search parameters with defaults applied
+   * @private
+   */
+  private mergeWithDefaultSearch(
+    params: UserSearchParamsType
+  ): UserSearchParamsType {
+    if (!this.searchDefaults) {
+      return params;
+    }
+
+    // Merge default search params with provided params
+    // Provided params take precedence over defaults
+    return {
+      ...this.searchDefaults,
+      ...params,
+    };
+  }
+
+  /**
+   * Validates and sets the API key for the client.
+   *
+   * The API key must be in the format "key_id|secret_key" with exactly one pipe separator.
+   * This format allows for key identification and authentication.
+   *
+   * @param apiKey - The API key to validate and set
+   * @throws {Error} When the API key is missing or has invalid format
+   * @private
+   */
+  private verifyAndSetApiKey(apiKey: string | undefined) {
+    if (!apiKey) {
+      throw new Error("API key is required");
+    }
+    /** Split API key to validate format (should be "key_id|secret_key") */
+    const splits = apiKey.split("|");
+    if (splits.length !== 2) {
+      throw new Error(
+        "API key is invalid - expected format 'key_id|secret_key'"
+      );
+    }
+    this.apiKey = apiKey;
+  }
+
+  /**
+   * Makes an authenticated HTTP request to the Nosible API.
+   *
+   * This private method handles all HTTP communication with the API, including
+   * authentication headers, request body serialization, and error handling.
+   *
+   * @param endpoint - The API endpoint to call (relative to baseUrl)
+   * @param body - The request body to send as JSON
+   * @returns The parsed JSON response from the API
+   * @throws {Error} When the HTTP request fails or returns an error status
+   * @private
+   */
+  private async _request(endpoint: string, body: any): Promise<any> {
+    return callNosibleApi({
+      endpoint,
+      body,
+      apiKey: this.apiKey,
+    });
+  }
+
+  /**
+   * Performs a fast search query with optimized performance.
+   *
+   * Fast search is designed for quick, efficient queries with smaller result sets.
+   * It's ideal for real-time applications, autocomplete features, or when you need
+   * rapid responses with a limited number of highly relevant results.
+   *
+   * Features:
+   * - Optimized for speed (10-100 results)
+   * - Supports advanced filtering and search algorithms
+   * - Rate limited to prevent quota exceeded errors
+   * - Returns structured ResultSet with metadata
+   *
+   * @param params - Search parameters including question, filters, and result count
+   * @returns Promise resolving to a ResultSet containing search results and metadata
+   *
+   * @example
+   * ```typescript
+   * // Basic fast search
+   * const results = await client.fastSearch({
+   *   question: 'latest AI technology trends',
+   *   nResults: 20
+   * });
+   *
+   * // Advanced fast search with filters
+   * const filteredResults = await client.fastSearch({
+   *   question: 'machine learning startups',
+   *   nResults: 50,
+   *   algorithm: 'hybrid-2',
+   *   minSimilarity: 0.7,
+   *   mustInclude: ['artificial intelligence', 'funding'],
+   *   mustExclude: ['cryptocurrency'],
+   *   continent: 'North America'
+   * });
+   *
+   * // Process results
+   * console.log(`Found ${results.length} results`);
+   * for (const result of results) {
+   *   console.log(`Title: ${result.title}`);
+   *   console.log(`URL: ${result.url}`);
+   *   console.log(`Similarity: ${result.similarity}`);
+   * }
+   * ```
+   */
+  public async fastSearch(
+    params: ClientSearchParamsSchema
+  ): Promise<ResultSet> {
+    let search: Search;
+
+    // Type guard to check if we have a Search instance
+    const hasSearchInstance = (
+      params: ClientSearchParamsSchema
+    ): params is {search: Search} => {
+      return "search" in params;
+    };
+
+    if (hasSearchInstance(params)) {
+      // Use provided Search instance
+      if (params.search instanceof Search) {
+        search = params.search;
+      } else {
+        throw new Error("Invalid search parameter provided.");
+      }
+    } else {
+      // Create new Search instance from params
+      // Merge with default search parameters before creating Search instance
+      const mergedParams = this.mergeWithDefaultSearch(params);
+      search = new Search(mergedParams);
+    }
+
+    /** Generate search body from Search instance */
+    const body = await search.searchBody({client: this});
+
+    /** Validate search body */
+    const validatedBody = validateFastSearchParams(body);
+
+    /** Make API request and parse response */
+    const {message, query, response} = (await this._request(
+      "fast-search",
+      validatedBody
+    )) as SearchResType;
+
+    const results = response.map((result) => {
+      const fullResult = {...query, ...result};
+      return fullResult;
+    });
+    /** Wrap response in ResultSet for enhanced functionality */
+    const resultSet = createResultSet(this, results);
+    return resultSet;
+  }
+
+  public async fastSearches(
+    params: FastSearchesParamsType
+  ): Promise<ResultSet[]> {
+    let searchSet: SearchSet;
+
+    // Handle SearchSet input
+    if (params instanceof SearchSet) {
+      searchSet = params;
+    } else {
+      // Handle questions array with shared search parameters
+      const {questions, ...sharedParams} = params;
+
+      // Merge shared parameters with default search parameters
+      const mergedSharedParams = this.mergeWithDefaultSearch(sharedParams);
+
+      // Create Search instances for each question using merged shared parameters
+      const searches = questions.map(
+        (question) => new Search({question, ...mergedSharedParams})
+      );
+
+      searchSet = new SearchSet(searches);
+    }
+
+    // Execute fastSearch for all searches in parallel
+    const results = await Promise.all(
+      searchSet.searches.map((search) => this.fastSearch({search}))
+    );
+
+    return results;
+  }
+
+  /**
+   * Performs an AI-powered search with custom instructions.
+   *
+   * AI search leverages advanced language models to understand complex queries
+   * and custom instructions, providing more contextually relevant results.
+   * This method is ideal for nuanced searches that require understanding intent,
+   * context, or specific analytical requirements.
+   *
+   * Features:
+   * - Natural language understanding of complex queries
+   * - Custom instructions for specialized search behavior
+   * - Context-aware result ranking and filtering
+   * - Rate limited for optimal performance
+   *
+   * @param params - AI search parameters including question and custom instructions
+   * @returns Promise resolving to a ResultSet containing AI-enhanced search results
+   *
+   * @example
+   * ```typescript
+   * // Basic AI search
+   * const results = await client.aiSearch({
+   *   question: 'What are the environmental impacts of renewable energy?',
+   *   instruction: 'Focus on recent studies and quantitative data'
+   * });
+   *
+   * // AI search with specific analytical focus
+   * const analysisResults = await client.aiSearch({
+   *   question: 'company financial performance',
+   *   instruction: 'Compare revenue growth and profit margins across quarters',
+   *   nResults: 25,
+   *   algorithm: 'hybrid-3'
+   * });
+   *
+   * // AI search for competitive analysis
+   * const competitiveResults = await client.aiSearch({
+   *   question: 'competitors in the cloud computing market',
+   *   instruction: 'Identify key players, market share, and competitive advantages'
+   * });
+   * ```
+   */
+  public async aiSearch(params: UserAiSearchParamsType): Promise<ResultSet> {
+    /** Execute AI search within rate limiter */
+    /** Make direct API request with AI search parameters */
+    const json = (await this._request("search", params)) as SearchResType;
+    /** Wrap response in ResultSet for enhanced functionality */
+
+    const results = json.response.map((result) => {
+      const fullResult = {...json.query, ...result};
+      return fullResult;
+    });
+    const resultSet = createResultSet(this, results);
+    return resultSet;
+  }
+
+  /**
+   * Performs a bulk search for large-scale data collection.
+   *
+   * Bulk search is designed for comprehensive data gathering and analysis tasks.
+   * It supports large result sets (1000-10000 results) and provides efficient
+   * download mechanisms for extensive datasets. Results are encrypted and
+   * downloaded asynchronously for optimal performance.
+   *
+   * Features:
+   * - Large-scale data collection (1000-10000 results)
+   * - Encrypted result delivery for security
+   * - Asynchronous download processing
+   * - Comprehensive filtering and search options
+   * - Rate limited for optimal server performance
+   * - Supports both raw parameters and Search instances
+   *
+   * @param params - Bulk search parameters including question or search instance, with comprehensive filtering options
+   * @returns Promise resolving to a ResultSet containing bulk search results
+   *
+   * @example
+   * ```typescript
+   * // Basic bulk search
+   * const results = await client.bulkSearch({
+   *   question: 'all articles about artificial intelligence',
+   *   nResults: 5000
+   * });
+   *
+   * // Bulk search with comprehensive filtering
+   * const filteredResults = await client.bulkSearch({
+   *   question: 'technology company funding rounds',
+   *   nResults: 10000,
+   *   algorithm: 'hybrid-3',
+   *   minSimilarity: 0.6,
+   *   continent: 'North America',
+   *   region: 'Silicon Valley',
+   *   mustInclude: ['venture capital', 'funding', 'investment'],
+   *   mustExclude: ['cryptocurrency', 'NFT'],
+   *   nProbes: 8,
+   *   nContextify: 512
+   * });
+   *
+   * // Bulk search using a Search instance
+   * const search = new Search({
+   *   question: 'renewable energy developments',
+   *   nResults: 7500,
+   *   algorithm: 'hybrid-2'
+   * });
+   * const searchResults = await client.bulkSearch({ search });
+   *
+   * // Process bulk results
+   * console.log(`Retrieved ${results.length} results`);
+   * const data = results.toJSON(); // Convert to JSON for analysis
+   * ```
+   */
+  public async bulkSearch(
+    params: ClientSearchParamsSchema
+  ): Promise<ResultSet> {
+    let search: Search;
+
+    // Type guard to check if we have a Search instance
+    const hasSearchInstance = (
+      params: ClientSearchParamsSchema
+    ): params is {search: Search} => {
+      return "search" in params;
+    };
+
+    if (hasSearchInstance(params)) {
+      // Use provided Search instance
+      if (params.search instanceof Search) {
+        search = params.search;
+      } else {
+        throw new Error("Invalid search parameter provided.");
+      }
+    } else {
+      // Create new Search instance from params
+      // Merge with default search parameters before creating Search instance
+      const mergedParams = this.mergeWithDefaultSearch(params);
+      search = new Search(mergedParams);
+    }
+
+    /** Generate search body from Search instance */
+    const body = await search.searchBody({client: this});
+
+    /** Validate search body for bulk search */
+    const validatedBody = validateBulkSearchParams(body);
+
+    /** Request bulk search and get encrypted file location */
+    const fileLocation = (await this._request(
+      "bulk-search",
+      validatedBody
+    )) as BulkResType;
+
+    /** Download and decrypt the bulk search results */
+    const json = (await bulkSearchDownload({
+      downloadFrom: fileLocation.download_from,
+      decryptUsing: fileLocation.decrypt_using,
+    })) as SearchResType;
+    const results = json.response.map((result) => {
+      const fullResult = {...json.query, ...result};
+      return fullResult;
+    });
+    /** Wrap response in ResultSet for enhanced functionality */
+    const resultSet = createResultSet(this, results);
+    return resultSet;
+  }
+
+  /**
+   * Scrapes and extracts structured content from a web URL.
+   *
+   * This method fetches the content of a web page and extracts structured information
+   * including title, description, main content, metadata, and other relevant details.
+   * The scraping is optimized for clean content extraction and handles various
+   * website structures and formats.
+   *
+   * Features:
+   * - Clean content extraction from web pages
+   * - Structured data including metadata and content
+   * - Handles various website formats and structures
+   * - Rate limited to respect website policies
+   * - Returns WebPage object with enhanced functionality
+   *
+   * @param url - The URL to scrape and extract content from
+   * @returns Promise resolving to a WebPage object containing structured content
+   *
+   * @example
+   * ```typescript
+   * // Basic URL scraping
+   * const webpage = await client.scrapeUrl('https://example.com/article');
+   *
+   * // Access scraped content
+   * console.log(`Title: ${webpage.title}`);
+   * console.log(`Description: ${webpage.description}`);
+   * console.log(`Author: ${webpage.author}`);
+   * console.log(`Published: ${webpage.published}`);
+   * console.log(`Content length: ${webpage.content.length} characters`);
+   *
+   * // Extract specific content sections
+   * const mainContent = webpage.content;
+   * const bestChunk = webpage.bestChunk; // Most relevant content chunk
+   *
+   * // Use in combination with search
+   * const searchResults = await client.fastSearch({
+   *   question: 'artificial intelligence news',
+   *   nResults: 10
+   * });
+   *
+   * // Scrape the top result
+   * if (searchResults.length > 0) {
+   *   const topArticle = await client.scrapeUrl(searchResults[0].url);
+   *   console.log(`Full article: ${topArticle.content}`);
+   * }
+   * ```
+   */
+  public async scrapeUrl(url: string): Promise<WebPageData> {
+    /** Execute URL scraping within rate limiter */
+    return this.limiters.scrapeUrl.schedule(async () => {
+      /** Make API request to scrape the URL */
+      const json = (await this._request("scrape-url", {url})) as ScrapeFullRes;
+      /** Wrap response in WebPage object for enhanced functionality */
+      const webPage = new WebPageData(this, json.response);
+      return webPage;
+    });
+  }
+
+  /**
+   * Analyzes topic trends and popularity over time.
+   *
+   * This method provides insights into how a topic's popularity and relevance
+   * changes over time. It's useful for market research, content strategy,
+   * trend analysis, and understanding topic momentum.
+   *
+   * Features:
+   * - Historical trend analysis for any topic
+   * - Popularity metrics and temporal patterns
+   * - Optional SQL filtering for refined analysis
+   * - Returns TopicTrend object with analytical data
+   *
+   * @param query - The topic or query to analyze trends for
+   * @param sqlFilter - Optional SQL filter to refine the trend analysis
+   * @returns Promise resolving to a TopicTrend object containing trend analysis data
+   *
+   * @example
+   * ```typescript
+   * // Basic trend analysis
+   * const trends = await client.topicTrend('artificial intelligence');
+   *
+   * // Access trend data
+   * console.log(`Topic: ${trends.query}`);
+   * console.log(`Data points: ${trends.data.length}`);
+   * trends.data.forEach(point => {
+   *   console.log(`Date: ${point.date}, Popularity: ${point.popularity}`);
+   * });
+   *
+   * // Trend analysis with filtering
+   * const filteredTrends = await client.topicTrend(
+   *   'machine learning',
+   *   'continent = "North America" AND published >= "2023-01-01"'
+   * );
+   *
+   * // Analyze multiple related topics
+   * const topics = ['AI', 'machine learning', 'deep learning', 'neural networks'];
+   * for (const topic of topics) {
+   *   const trend = await client.topicTrend(topic);
+   *   console.log(`${topic} trend analysis complete`);
+   * }
+   *
+   * // Use trend data for content strategy
+   * const trendingTopics = ['blockchain', 'quantum computing', 'renewable energy'];
+   * const trendAnalyses = await Promise.all(
+   *   trendingTopics.map(topic => client.topicTrend(topic))
+   * );
+   * ```
+   */
+  public async topicTrend(
+    query: string,
+    sqlFilter?: SqlFilter
+  ): Promise<TopicTrend> {
+    /** Prepare request body with query and optional SQL filter */
+    const body = {query, sql_filter: sqlFilter};
+    /** Make API request for trend analysis */
+    const json = await this._request("topic-trend", body);
+    /** Wrap response in TopicTrend object for enhanced functionality */
+    const topicTrend = new TopicTrend(json);
+    return topicTrend;
+  }
+}