SDKs
The official TypeScript SDK provides a typed, ergonomic client for the Skirre API. It handles authentication, retries, and error handling out of the box.
TypeScript SDK
| Parameter | Type | Description |
|---|---|---|
| Package optional | @skirre/sdk | Available on npm |
| Runtime optional | any | Works in Node.js, Deno, Bun, Cloudflare Workers, and browsers |
| Dependencies optional | none | Zero external dependencies, uses native fetch |
Installation
text
npm install @skirre/sdk # or pnpm add @skirre/sdk # or bun add @skirre/sdk
Initialization
text
import { Skirre } from '@skirre/sdk'; const skirre = new Skirre({ apiKey: 'sk_search_live_...', baseUrl: 'https://search.example.com', timeout: 30_000, // optional, ms (default: 30s) maxNetworkRetries: 2, // optional (default: 2) });
| Parameter | Type | Description |
|---|---|---|
| apiKey required | string | Your Skirre API key (admin or search) |
| baseUrl required | string | Base URL of your Skirre instance |
| timeout optional | number | Request timeout in milliseconds Default: 30000 |
| maxNetworkRetries optional | number | Number of automatic retries on failure Default: 2 |
Basic Usage
text
// Create an index await skirre.createIndex({ uid: 'products', primary_key: 'id', searchable_attributes: [ { name: 'title', weight: 3.0 }, { name: 'description', weight: 1.0 }, ], filterable_attributes: [ { name: 'brand', field_type: 'string' }, { name: 'price', field_type: 'number' }, ], sortable_attributes: ['price'], }); // List all indices const indices = await skirre.listIndices(); // Delete an index await skirre.deleteIndex('products');
Index Handle
Use skirre.index(uid) to get a handle for a specific index. The handle provides
methods for documents, search, settings, and analytics without repeating the index UID.
text
const idx = skirre.index('products'); // Add documents await idx.addDocuments([ { id: '1', title: 'Running Shoes', brand: 'Nike', price: 12000 }, { id: '2', title: 'Trail Runners', brand: 'Salomon', price: 16000 }, ]); // Search const results = await idx.search('running shoes', { filter: "price < 15000", limit: 10, }); console.log(results.hits); // Partial update await idx.updateDocuments([{ id: '1', price: 11000 }]); // Get a single document const doc = await idx.getDocument('1'); // Delete documents await idx.deleteDocument('1'); await idx.deleteBatch({ ids: ['2', '3'] }); await idx.deleteByFilter({ filter: "brand = 'Discontinued'" }); // Settings const settings = await idx.getSettings(); await idx.updateSettings({ synonyms: { shoes: ['sneakers', 'kicks'] } }); // Analytics const topQueries = await idx.getTopQueries({ days: 7, limit: 20 }); const noResults = await idx.getNoResultQueries({ days: 7 });
Error Handling
The SDK throws SkirreError for API errors with structured error information:
text
import { Skirre, SkirreError } from '@skirre/sdk'; try { await idx.search('test'); } catch (err) { if (err instanceof SkirreError) { console.log(err.status); // 429 console.log(err.code); // "rate_limited" console.log(err.message); // "Rate limit exceeded..." } }
Automatic Retries
The SDK automatically retries requests that fail with 429 (rate limited) or 5xx (server error) status codes. Retries use exponential backoff with jitter:
- Attempt 1: 0.5s + jitter
- Attempt 2: 1s + jitter
- Attempt 3: 2s + jitter
- Attempt 4: 4s + jitter (capped at 5s)
If the server returns a Retry-After header, the SDK respects it (capped at 60s).
Configure the maximum number of retries with maxNetworkRetries.