Rate Limits

1
import { HoleFoundationClient } from '@hole-foundation/sdk';
2
3
const client = new HoleFoundationClient({
4
  environment: 'https://api.theholefoundation.org',
5
  token: 'your-jwt-token'
6
});
7
8
const response = await client.vectorSearch.search({
9
  query: 'FOIA exemptions'
10
});
11
12
// Access rate limit info from headers
13
console.log('Remaining requests:', response.headers['x-ratelimit-remaining']);
14
console.log('Limit resets at:', new Date(
15
  parseInt(response.headers['x-ratelimit-reset']) * 1000
16
));

1
async function searchWithRetry(query: string, maxRetries = 3) {
2
  for (let i = 0; i < maxRetries; i++) {
3
    try {
4
      return await client.vectorSearch.search({ query });
5
    } catch (error) {
6
      if (error instanceof TheholetruthApiError &&
7
          error.status === 429) {
8
        // Get retry-after from error
9
        const resetAt = new Date(error.body.error.details.reset_at);
10
        const waitMs = resetAt.getTime() - Date.now();
11
12
        console.log(`Rate limited. Waiting ${waitMs}ms...`);
13
        await new Promise(resolve => setTimeout(resolve, waitMs));
14
        continue;
15
      }
16
      throw error;
17
    }
18
  }
19
  throw new Error('Max retries exceeded');
20
}
21
22
// Usage
23
const results = await searchWithRetry('FOIA exemptions');

1
class CachedClient {
2
  private cache = new Map<string, any>();
3
  private client: HoleFoundationClient;
4
5
  constructor(client: HoleFoundationClient) {
6
    this.client = client;
7
  }
8
9
  async search(query: string) {
10
    // Check cache
11
    if (this.cache.has(query)) {
12
      return this.cache.get(query);
13
    }
14
15
    // Call API
16
    const results = await this.client.vectorSearch.search({ query });
17
18
    // Cache for 1 hour
19
    this.cache.set(query, results);
20
    setTimeout(() => this.cache.delete(query), 60 * 60 * 1000);
21
22
    return results;
23
  }
24
}
25
26
const cachedClient = new CachedClient(client);
27
28
// First call hits API
29
const results1 = await cachedClient.search('FOIA');
30
31
// Second call uses cache
32
const results2 = await cachedClient.search('FOIA');

1
// ❌ Multiple sequential calls
2
const results1 = await client.vectorSearch.search({ query: 'FOIA' });
3
const results2 = await client.vectorSearch.search({ query: 'privacy' });
4
const results3 = await client.vectorSearch.search({ query: 'exemptions' });
5
6
// ✅ Single call with broader query, filter client-side
7
const allResults = await client.vectorSearch.search({
8
  query: 'FOIA privacy exemptions',
9
  limit: 100
10
});
11
12
// Filter results locally
13
const foiaResults = allResults.results.filter(r =>
14
  r.title.includes('FOIA')
15
);
16
const privacyResults = allResults.results.filter(r =>
17
  r.title.includes('privacy')
18
);

1
class RateLimitMonitor {
2
  private remaining = 0;
3
  private limit = 0;
4
  private resetAt = 0;
5
6
  async search(client: HoleFoundationClient, query: string) {
7
    const response = await client.vectorSearch.search({ query });
8
9
    // Update from headers
10
    this.remaining = parseInt(
11
      response.headers['x-ratelimit-remaining']
12
    );
13
    this.limit = parseInt(
14
      response.headers['x-ratelimit-limit']
15
    );
16
    this.resetAt = parseInt(
17
      response.headers['x-ratelimit-reset']
18
    );
19
20
    // Warn if low
21
    if (this.remaining < this.limit * 0.1) {
22
      console.warn(
23
        `⚠️  Low on requests: ${this.remaining}/${this.limit} remaining`
24
      );
25
    }
26
27
    return response;
28
  }
29
30
  getStatus() {
31
    const resetDate = new Date(this.resetAt * 1000);
32
    return {
33
      remaining: this.remaining,
34
      limit: this.limit,
35
      resetAt: resetDate,
36
      percentUsed: ((this.limit - this.remaining) / this.limit) * 100
37
    };
38
  }
39
}
40
41
const monitor = new RateLimitMonitor();
42
const results = await monitor.search(client, 'FOIA');
43
console.log('Rate limit status:', monitor.getStatus());

1
class PriorityQueue {
2
  private queue: Array<{
3
    fn: () => Promise<any>;
4
    priority: number;
5
  }> = [];
6
7
  private processing = false;
8
9
  async add(fn: () => Promise<any>, priority = 0) {
10
    return new Promise((resolve, reject) => {
11
      this.queue.push({
12
        fn: async () => {
13
          try {
14
            const result = await fn();
15
            resolve(result);
16
          } catch (error) {
17
            reject(error);
18
          }
19
        },
20
        priority
21
      });
22
23
      // Sort by priority (higher first)
24
      this.queue.sort((a, b) => b.priority - a.priority);
25
26
      this.process();
27
    });
28
  }
29
30
  private async process() {
31
    if (this.processing || this.queue.length === 0) return;
32
33
    this.processing = true;
34
35
    while (this.queue.length > 0) {
36
      const item = this.queue.shift()!;
37
      await item.fn();
38
39
      // Small delay between requests
40
      await new Promise(resolve => setTimeout(resolve, 100));
41
    }
42
43
    this.processing = false;
44
  }
45
}
46
47
const queue = new PriorityQueue();
48
49
// High priority
50
await queue.add(
51
  () => client.vectorSearch.search({ query: 'urgent FOIA' }),
52
  10
53
);
54
55
// Low priority
56
await queue.add(
57
  () => client.vectorSearch.search({ query: 'background research' }),
58
  1
59
);

1
class CircuitBreaker {
2
  private failures = 0;
3
  private threshold = 3;
4
  private timeout = 60000; // 1 minute
5
  private state: 'closed' | 'open' | 'half-open' = 'closed';
6
  private nextAttempt = 0;
7
8
  async execute<T>(fn: () => Promise<T>): Promise<T> {
9
    if (this.state === 'open') {
10
      if (Date.now() < this.nextAttempt) {
11
        throw new Error('Circuit breaker is open');
12
      }
13
      this.state = 'half-open';
14
    }
15
16
    try {
17
      const result = await fn();
18
19
      // Success - reset
20
      if (this.state === 'half-open') {
21
        this.state = 'closed';
22
        this.failures = 0;
23
      }
24
25
      return result;
26
    } catch (error) {
27
      this.failures++;
28
29
      if (this.failures >= this.threshold) {
30
        this.state = 'open';
31
        this.nextAttempt = Date.now() + this.timeout;
32
        console.log('Circuit breaker opened');
33
      }
34
35
      throw error;
36
    }
37
  }
38
}
39
40
const breaker = new CircuitBreaker();
41
42
// Usage
43
try {
44
  const results = await breaker.execute(() =>
45
    client.vectorSearch.search({ query: 'FOIA' })
46
  );
47
} catch (error) {
48
  console.error('Request failed or circuit is open');
49
}

1
const usage = await client.account.getUsage();
2
3
console.log('Current tier:', usage.tier);
4
console.log('Requests this month:', usage.requests_this_month);
5
console.log('Requests today:', usage.requests_today);
6
console.log('Recommendation:', usage.tier_recommendation);