Skip to main content
@moss-dev/moss / MossClient

MossClient

MossClient - Async-first semantic search client for vector similarity operations. All mutations (createIndex, addDocs, deleteDocs) are async operations that run server-side and poll until complete.

Example

import { MossClient } from '@moss-dev/moss';

const client = new MossClient('your-project-id', 'your-project-key');

// Create an index with documents (polls until complete)
const result = await client.createIndex('docs', [
  { id: '1', text: 'Machine learning fundamentals' },
  { id: '2', text: 'Deep learning neural networks' }
]);

// Add docs (polls until complete)
await client.addDocs('docs', [
  { id: '3', text: 'Natural language processing' }
]);

// Query the index
await client.loadIndex('docs');
const results = await client.query('docs', 'AI and neural networks');

Constructors

Constructor

new MossClient(projectId, projectKey): MossClient
Creates a new MossClient instance.

Parameters

ParameterTypeDescription
projectIdstringYour project identifier.
projectKeystringYour project authentication key. Use the projectKey form for server-side code only.

Returns

MossClient

Constructor (custom authenticator)

new MossClient(projectId, authenticator): MossClient
Creates a new MossClient instance with a custom authenticator. Use this pattern from browser or untrusted clients where the projectKey must never be embedded in shipped code. See the Custom Authenticator guide for details.

Parameters

ParameterTypeDescription
projectIdstringYour project identifier.
authenticatorIAuthenticatorImplementation that returns a short-lived bearer token from your backend.

Methods

createIndex()

createIndex(indexName, docs, options?): Promise<MutationResult>
Creates a new index with the provided documents via async upload. Handles the full flow: init → upload → build → poll until complete. Returns when the index is ready. When all documents have pre-computed embeddings, they are serialized as raw float32 in the binary upload. When no documents have embeddings, the server generates embeddings in batches (dimension=0 flow). Mixed documents (some with embeddings, some without) are rejected.

Parameters

ParameterTypeDescription
indexNamestringName of the index to create.
docsDocumentInfo[]Documents, optionally with pre-computed embeddings.
options?CreateIndexOptionsOptional model ID and progress callback.

Returns

Promise<MutationResult> Promise that resolves to MutationResult when the index is ready.

Throws

If the index already exists or creation fails.

Example

const result = await client.createIndex('knowledge-base', [
  { id: 'doc1', text: 'Introduction to AI' },
  { id: 'doc2', text: 'Machine learning basics' }
], {
  onProgress: (p) => console.log(`${p.status} ${p.progress}%`),
});

getIndex()

getIndex(indexName): Promise<IndexInfo>
Gets information about a specific index.

Parameters

ParameterTypeDescription
indexNamestringName of the index to retrieve.

Returns

Promise<IndexInfo> Promise that resolves to IndexInfo object.

Throws

If the index does not exist.

Example

const info = await client.getIndex('knowledge-base');
console.log(`Index has ${info.docCount} documents`);

listIndexes()

listIndexes(): Promise<IndexInfo[]>
Lists all available indexes.

Returns

Promise<IndexInfo[]> Promise that resolves to array of IndexInfo objects.

Example

const indexes = await client.listIndexes();
indexes.forEach(index => {
  console.log(`${index.name}: ${index.docCount} docs`);
});

deleteIndex()

deleteIndex(indexName): Promise<boolean>
Deletes an index and all its data.

Parameters

ParameterTypeDescription
indexNamestringName of the index to delete.

Returns

Promise<boolean> Promise that resolves to true if successful.

Throws

If the index does not exist.

Example

const deleted = await client.deleteIndex('old-index');

addDocs()

addDocs(indexName, docs, options?): Promise<MutationResult>
Adds or updates documents in an index asynchronously. The index rebuild happens server-side. This method polls until the rebuild is complete and then returns.

Parameters

ParameterTypeDescription
indexNamestringName of the target index.
docsDocumentInfo[]Documents to add or update.
options?MutationOptionsOptional configuration (upsert, onProgress callback).

Returns

Promise<MutationResult> Promise that resolves to MutationResult when the operation is complete.

Throws

If the index does not exist.

Example

const result = await client.addDocs('knowledge-base', [
  { id: 'new-doc', text: 'New content to index' }
], { upsert: true });
console.log(`Job ${result.jobId} completed`);

deleteDocs()

deleteDocs(indexName, docIds, options?): Promise<MutationResult>
Deletes documents from an index by their IDs asynchronously. The index rebuild happens server-side. This method polls until the rebuild is complete and then returns.

Parameters

ParameterTypeDescription
indexNamestringName of the target index.
docIdsstring[]Array of document IDs to delete.
options?MutationOptionsOptional configuration (onProgress callback).

Returns

Promise<MutationResult> Promise that resolves to MutationResult when the operation is complete.

Throws

If the index does not exist.

Example

const result = await client.deleteDocs('knowledge-base', ['doc1', 'doc2']);
console.log(`Job ${result.jobId} completed`);

getJobStatus()

getJobStatus(jobId): Promise<JobStatusResponse>
Gets the current status of an async job.

Parameters

ParameterTypeDescription
jobIdstringThe job ID returned by createIndex, addDocs, or deleteDocs.

Returns

Promise<JobStatusResponse> Promise that resolves to JobStatusResponse with progress details.

Example

const status = await client.getJobStatus(jobId);
console.log(`${status.status}${status.progress}%`);

getDocs()

getDocs(indexName, options?): Promise<DocumentInfo[]>
Retrieves documents from an index.

Parameters

ParameterTypeDescription
indexNamestringName of the target index.
options?GetDocumentsOptionsOptional configuration for retrieval.

Returns

Promise<DocumentInfo[]> Promise that resolves to array of documents.

Throws

If the index does not exist.

Example

// Get all documents
const allDocs = await client.getDocs('knowledge-base');

// Get specific documents
const specificDocs = await client.getDocs('knowledge-base', {
  docIds: ['doc1', 'doc2']
});

loadIndex()

loadIndex(indexName, options?): Promise<string>
Downloads an index from the cloud into memory for fast local querying. How it works:
  1. Fetches the index assets from the cloud
  2. Loads the embedding model for generating query embeddings
  3. Executes a local similarity match between the query embedding and the retrieved index.
Why use this?
  • Without loadIndex(): Every query() call goes to the cloud API (~100-500ms network latency)
  • With loadIndex(): Queries run entirely in-memory (~1-10ms)
Reload behavior: If the index is already loaded, calling loadIndex() again will:
  • Stop any existing auto-refresh polling
  • Download a fresh copy from the cloud
  • Replace the in-memory index
Auto-refresh (optional): Enable autoRefresh: true to periodically poll the cloud for updates. When a newer version is detected, the index is automatically hot-swapped without interrupting queries.

Parameters

ParameterTypeDescription
indexNamestringName of the index to load.
options?LoadIndexOptionsOptional configuration including auto-refresh settings.

Returns

Promise<string> Promise that resolves to the index name.

Throws

If the index does not exist in the cloud or loading fails.

Example

// Simple load - enables fast local queries
await client.loadIndex('my-index');

// Now queries run locally (fast, no network calls)
const results = await client.query('my-index', 'search text');

// Load with auto-refresh to keep index up-to-date
await client.loadIndex('my-index', {
  autoRefresh: true,
  pollingIntervalInSeconds: 300, // Check cloud every 5 minutes
});

// Stop auto-refresh by reloading without the option
await client.loadIndex('my-index');

query()

query(indexName, query, options?): Promise<SearchResult>
Performs a semantic similarity search against the specified index. If the index has been loaded via loadIndex(), runs entirely in-memory. Otherwise, falls back to the cloud /query endpoint.

Parameters

ParameterTypeDescription
indexNamestringName of the target index to search.
querystringThe search query text.
options?QueryOptionsOptional query configuration including topK (default: 5) and embedding overrides.

Returns

Promise<SearchResult> Promise that resolves to SearchResult with matching documents.

Throws

If the specified index does not exist.

Example

const results = await client.query('knowledge-base', 'machine learning');
results.docs.forEach(doc => {
  console.log(`${doc.id}: ${doc.text} (score: ${doc.score})`);
});