Merge pull request #1 from mikechao/image-search

Add image search

README.md

@@ -1,6 +1,6 @@
 # Brave Search API Wrapper
 
-A fully typed Brave Search API wrapper, providing easy access to web search, local POI search, and automatic polling for AI-generated web search summary feature.
+A fully typed Brave Search API wrapper, providing easy access to web search, image search, local POI search, and automatic polling for AI-generated web search summary feature.
 
 ## Installation
 
@@ -109,6 +109,20 @@ const descriptionResults = await braveSearch.localDescriptionsSearch(["poi_id1",
 console.log(descriptionResults);
 ```
 
+### Image Search 
+
+Perform an image search using the `imageSearch` method. Your IDE will provide type hints for the parameters and return types.
+
+```typescript
+const imageSearchResults = await braveSearch.imageSearch("Golden Gate Bridge", {
+  count: 5,
+  safesearch: "off",
+  search_lang: "en",
+  country: "US",
+});
+console.log(imageSearchResults);
+```
+
 ## Search Options
 
 The library supports various search options as defined in the Brave Search API documentation. For a complete list of options and their descriptions, please refer to the [Brave Search API Documentation](https://api.search.brave.com/app/documentation/web-search/).

src/braveSearch.ts

@@ -20,6 +20,8 @@ const DEFAULT_MAX_POLL_ATTEMPTS = 20;
 
 import {
   BraveSearchOptions,
+  ImageSearchApiResponse,
+  ImageSearchOptions,
   LocalDescriptionsSearchApiResponse,
   LocalPoiSearchApiResponse,
   PollingOptions,
@@ -49,7 +51,7 @@ class BraveSearchError extends Error {
 
 /**
  * The main class for interacting with the Brave Search API, holding API key for all the requests made with it.
- * It provides methods for web search, local POI search, and summarization.
+ * It provides methods for web search, image search, local POI search, and summarization.
  */
 class BraveSearch {
   private apiKey: string;
@@ -99,6 +101,36 @@ class BraveSearch {
     }
   }
 
+  /**
+   * Performs an image search using the provided query and options.
+   * @param query The search query string.
+   * @param options Optional settings to configure the search behavior.
+   * @returns A promise that resolves to the image search results.
+   */
+  async imageSearch(
+    query: string,
+    options: ImageSearchOptions = {},
+    signal?: AbortSignal,
+  ): Promise<ImageSearchApiResponse> {
+    const params = new URLSearchParams({
+      q: query,
+      ...this.formatOptions(options),
+    })
+    try {
+      const response = await axios.get<ImageSearchApiResponse>(
+        `${this.baseUrl}/images/search?${params.toString()}`,
+        {
+          headers: this.getHeaders(),
+          signal,
+        }
+      )
+      return response.data;
+    } catch (error) {
+      const handledError = this.handleApiError(error);
+      throw handledError;
+    }
+  }
+
   /**
    * Executes a web search for the provided query and polls for a summary
    * if the query is eligible for a summary and summarizer key is provided in the web search response.
@@ -290,9 +322,11 @@ export {
   BraveSearch,
   BraveSearchError,
   type BraveSearchOptions,
+  type ImageSearchOptions,
   type LocalDescriptionsSearchApiResponse,
   type LocalPoiSearchApiResponse,
   type SummarizerOptions,
   type SummarizerSearchApiResponse,
   type WebSearchApiResponse,
+  type ImageSearchApiResponse,
 };

src/types.ts

@@ -2598,3 +2598,100 @@ export interface Image {
    */
   properties: ImageProperties;
 }
+
+  /**
+   * Options for image search
+   * 
+   * https://api-dashboard.search.brave.com/app/documentation/image-search/query
+   */
+  export interface ImageSearchOptions extends Pick<BraveSearchOptions, 'country' | 'search_lang' | 'safesearch' | 'spellcheck' | 'count'> {
+  }
+
+  /**
+   * Response from the Brave Search API for an Image search
+   * 
+   * https://api-dashboard.search.brave.com/app/documentation/image-search/responses
+   */
+  export interface ImageSearchApiResponse {
+    /**
+     * The type of search API result. The value is always images.
+     * @type {string}
+     */
+    type: 'images'
+    /**
+     * Image search query string.
+     * @type {Query}
+     */
+    query: Query
+    /**
+     * The list of image results for the given query.
+     * @type {ImageResult[]}
+     */
+    results: ImageResult[]
+  }
+
+  /**
+   * A model representing an image result for the requested query.
+   * 
+   * https://api-dashboard.search.brave.com/app/documentation/image-search/responses#ImageResult
+   */
+  export interface ImageResult {
+    /**
+     * The type of image search API result. The value is always image_result.
+     * @type {string}
+     */
+    type: 'image_result'
+    /**
+     * The title of the image.
+     * @type {string} 
+     */
+    title: string
+    /**
+     * The original page url where the image was found.
+     * @type {string}
+     */
+    url: string
+    /**
+     * The source domain where the image was found.
+     * @type {string}
+     */
+    source: string
+    /**
+     * The iso date time when the page was last fetched. The format is YYYY-MM-DDTHH:MM:SSZ
+     * @type {string}
+     */
+    page_fetched: string
+    /**
+     * The thumbnail for the image.
+     * @type {Thumbnail}
+     */
+    thumbnail: Thumbnail
+    /**
+     * Metadata for the image
+     * @type {Properties}
+     */
+    properties: Properties
+    /**
+     * Aggregated information on the url associated with the image search result.
+     * @type {MetaUrl}
+     */
+    meta_url: MetaUrl
+  }
+
+  /**
+   * Metadata on an image.
+   * 
+   * https://api-dashboard.search.brave.com/app/documentation/image-search/responses#Properties
+   */
+  export interface Properties {
+    /**
+     * The image URL.
+     * @type {string}
+     */
+    url: string
+    /**
+     * The lower resolution placeholder image url.
+     * @type {string}
+     */
+    placeholder: string
+  }