@ivfuture/search-saas-server-sdk

@search-saas/server-sdk

A TypeScript SDK for the Search SaaS Management API. This package provides a clean, type-safe interface for managing search infrastructure, projects, collections, and document indexing operations.

🚀 Installation

npm install @search-saas/server-sdk
# or
yarn add @search-saas/server-sdk
# or
pnpm add @search-saas/server-sdk

📖 Quick Start

import { SearchEngineSDK } from '@search-saas/server-sdk';

// Initialize the SDK
const sdk = new SearchEngineSDK({
  apiBaseUrl: 'https://your-api.example.com/api/v1',
  token: 'your-api-token',
  logLevel: 'info'
});

// Create a project and get a search token
const { projectId, searchToken } = await sdk.createProject('my-app');

// Create a collection
await sdk.createCollection({
  name: 'products',
  fields: [
    { name: 'id', type: 'string' },
    { name: 'title', type: 'string' },
    { name: 'price', type: 'float' },
    { name: 'category', type: 'string', facet: true }
  ],
  default_sorting_field: 'title'
});

// Index documents (async operation)
const job = await sdk.emplaceDocuments('products', [
  { id: '1', title: 'iPhone 15', price: 999.99, category: 'Electronics' },
  { id: '2', title: 'MacBook Pro', price: 1999.99, category: 'Electronics' }
]);

console.log(`Documents queued for indexing: ${job.jobId}`);

🔧 Configuration

SearchEngineSDKOptions

interface SearchEngineSDKOptions {
  /** API base URL for the management API */
  apiBaseUrl?: string;
  /** API token for authentication */
  token: string;
  /** Connection timeout in seconds (default: 30) */
  connectionTimeoutSeconds?: number;
  /** Retry interval in seconds (default: 1) */
  retryIntervalSeconds?: number;
  /** Number of retries for failed requests (default: 3) */
  numRetries?: number;
  /** Log level for SDK operations */
  logLevel?: 'debug' | 'info' | 'warn' | 'error';
}

Environment Variables

# Required
API_SEARCH_ENGINE_TOKEN=your-api-token

# Optional
SEARCH_API_BASE_URL=https://your-api.example.com/api/v1

📚 API Reference

Project Management

createProject(name: string): Promise<CreateProjectResponse>

Creates a new search project and returns a search token for client SDK usage.

const result = await sdk.createProject('my-ecommerce-app');
// Returns: { projectId, searchToken, name, createdAt }

listProjects(): Promise<Project[]>

Lists all projects for the current tenant.

getProject(id: string): Promise<Project>

Gets details for a specific project.

deleteProject(id: string): Promise<void>

Deletes a project and all associated data.

Collection Management

createCollection(schema: TypesenseCollectionSchema): Promise<void>

Creates a new collection with the specified schema.

await sdk.createCollection({
  name: 'products',
  fields: [
    { name: 'id', type: 'string' },
    { name: 'title', type: 'string' },
    { name: 'description', type: 'string' },
    { name: 'price', type: 'float' },
    { name: 'category', type: 'string', facet: true },
    { name: 'in_stock', type: 'bool', facet: true }
  ],
  default_sorting_field: 'title'
});

listCollections(): Promise<CollectionSummary[]>

Lists all collections with metadata.

getCollection(name: string): Promise<CollectionSummary>

Gets details for a specific collection.

updateCollection(name: string, patch: Partial<TypesenseCollectionSchema>): Promise<void>

Updates a collection schema.

deleteCollection(name: string): Promise<void>

Deletes a collection and all its documents.

Document Operations

Note: All document operations are asynchronous and return immediately with a job ID. Documents are processed in the background via a message queue.

emplaceDocuments(collection: string, documents: Record<string, any>[]): Promise<IndexResponse>

Indexes documents into a collection.

const job = await sdk.emplaceDocuments('products', [
  {
    id: 'prod-001',
    title: 'Wireless Headphones',
    description: 'High-quality wireless headphones with noise cancellation',
    price: 199.99,
    category: 'Electronics',
    in_stock: true
  }
]);

console.log(`Job ID: ${job.jobId}, Status: ${job.status}`);

deleteDocuments(collection: string, ids: string[]): Promise<IndexResponse>

Deletes documents from a collection.

const job = await sdk.deleteDocuments('products', ['prod-001', 'prod-002']);

getIndexingJobStatus(jobId: string): Promise<IndexResponse>

Gets the status of an indexing job.

Analytics & Statistics

getStats(): Promise<TenantStats>

Gets overall tenant statistics.

const stats = await sdk.getStats();
console.log(`Collections: ${stats.totalCollections}, Documents: ${stats.totalDocuments}`);

getCollectionStats(collection: string): Promise<CollectionSummary>

Gets statistics for a specific collection.

Health & Diagnostics

healthCheck(): Promise<{ status: string; timestamp: string }>

Checks if the management API is healthy.

🔄 Integration with Client SDK

The search token returned by createProject() is used with the client SDK for search operations:

// Server-side: Create project and get token
const { searchToken } = await sdk.createProject('my-app');

// Client-side: Use token for searches
import { TypeSenseProvider } from '@search-saas/client-sdk';

<TypeSenseProvider config={{
  nodes: [{ host: 'localhost', port: 8108, protocol: 'http' }],
  apiKey: searchToken // Use the token from createProject
}}>
  <App />
</TypeSenseProvider>

🛠️ Error Handling

The SDK includes comprehensive error handling with automatic retries:

try {
  await sdk.createCollection(schema);
} catch (error) {
  if (error.message.includes('401')) {
    console.error('Invalid API token');
  } else if (error.message.includes('429')) {
    console.error('Rate limit exceeded');
  } else {
    console.error('API Error:', error.message);
  }
}

🐛 Debug Mode

Enable debug logging to see detailed HTTP requests:

const sdk = new SearchEngineSDK({
  token: 'your-token',
  logLevel: 'debug' // Shows all HTTP requests and responses
});

🏗️ Architecture

This SDK is a pure HTTP client that communicates with the Search SaaS Management API. It handles:

• ✅ Authentication via Bearer tokens
• ✅ Automatic retries with exponential backoff
• ✅ Request/response logging for debugging
• ✅ Type safety with TypeScript
• ✅ Error handling with meaningful messages

📄 License

MIT

🤝 Contributing

See the main repository README for contribution guidelines.

🔗 Related Packages

• @search-saas/client-sdk - React hooks for search functionality
• @search-saas/shared - Shared types and interfaces