Brave SDK

TypeScript SDK for Brave Search APIs.

Installation

npm install @microfox/brave

Environment Variables

To use this package, you need to set the following environment variables:

BRAVE_API_KEY: Your Brave Search API key. Obtain this by subscribing to a plan (including the free plan) at https://brave.com/search/api/. (Required)

Quick Start

import { createBraveSDK } from '@microfox/brave';

// Initialize with API key
const braveSDK = createBraveSDK({
  apiKey: process.env.BRAVE_API_KEY,
});

// Or use environment variable
const braveSDK = createBraveSDK(); // Uses BRAVE_API_KEY from environment

Batch Requests ( DO NOT USE PROMISE.All )

Free Plan Ratelimit: 1 request per second
Pro Plan Ratelimit: 20 requests per second

When making multiple requests, use sequential processing instead to avoid hitting rate limits, generally using a await new Promise(resolve => setTimeout(resolve, 1000)) is a good patternt o delay in bettween requests.

const queries = ['search query 1', 'search query 2'];

// ❌ Don't do this ( Promise.all will hit 429 due to rate limiting. )
const contentPromises = userTopics.topics.map(async topic => {
  const results = await braveSDK.webSearch({ q: topic, count: 5 });
  return results.search?.results || [];
});
const contentResults = await Promise.all(contentPromises);

// ✅ Do this instead ( use batchWebSearch )
const contentResults = await braveSdk.batchWebSearch(
  userTopics.topics.map(topic => ({
    q: topic,
    count: 5,
  })),
); // deafault delay of 1 second

// ✅ or Do this instead
const contentResults = [];
for (const topic of topics) {
  const results = await braveSDK.webSearch({ q: topic, count: 5 });
  await new Promise(resolve => setTimeout(resolve, 1000)); // delay by 1 seconds
  contentResults.push({ query: topic, results: results.web?.results });
}

API Reference

For detailed documentation on all available functions and their parameters, please refer to the following files:

Best Practices

Always use sequential processing for multiple requests to respect rate limits
Handle API errors appropriately
Consider caching responses when appropriate
Monitor rate limit headers in responses for quota management