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

ParameterTypeDescription
Package optional@skirre/sdkAvailable on npm
Runtime optionalanyWorks in Node.js, Deno, Bun, Cloudflare Workers, and browsers
Dependencies optionalnoneZero 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)
});
ParameterTypeDescription
apiKey requiredstringYour Skirre API key (admin or search)
baseUrl requiredstringBase URL of your Skirre instance
timeout optionalnumberRequest timeout in milliseconds
Default: 30000
maxNetworkRetries optionalnumberNumber 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.