@aspects/sdk

TypeScript SDK for the Aspects.dev vector index API — a database that supports sparse vector queries where some dimensions of the search vector may be left undefined.

Installation

npm install @aspects/sdk

Quick Start

import { AspectsClient, AspectsApiError } from '@aspects/sdk';

const client = new AspectsClient({
  basePath: 'https://api.aspects.dev',
  apiKey: 'your-api-key',
});

Usage

All API methods are available directly on the client — no need for sub-namespaces.

Indexes

// List all indexes
const { data } = await client.listIndexes();

// Create an index
await client.createIndex('my-index', {
  aspects: [{ name: 'color' }, { name: 'size' }],
  hnsw: { m: 16, efConstruction: 200 },
});

// Get index details
const index = await client.getIndex('my-index');

// Search an index
const results = await client.searchIndex('my-index', {
  query: { color: [0.1, 0.9, 0.3] },
});

// Delete an index
await client.deleteIndex('my-index');

Documents

// Upload documents
await client.uploadDocs('my-index', {
  data: [
    { id: 'doc-1', aspects: { color: [0.1, 0.9, 0.3], size: [0.5] } },
    { id: 'doc-2', aspects: { color: [0.8, 0.2, 0.1] } },
  ],
});

// Get a single document
const doc = await client.getDoc('my-index', 'doc-1');

// List documents
const docs = await client.getDocs('my-index');

Error Handling

HTTP errors are automatically parsed and thrown as AspectsApiError with the server's error message:

import { AspectsApiError } from '@aspects/sdk';

try {
  await client.getIndex('nonexistent');
} catch (err) {
  if (err instanceof AspectsApiError) {
    console.error(err.message);  // Server error message
    console.error(err.status);   // HTTP status code (e.g. 404)
    console.error(err.response); // Parsed ErrorResponse object
  }
}

Configuration

The client accepts all standard configuration options:

const client = new AspectsClient({
  basePath: 'https://api.aspects.dev',  // API base URL
  apiKey: 'your-api-key',               // API key authentication
  headers: { 'X-Custom': 'value' },     // Custom headers on every request
  middleware: [/* custom middleware */], // Additional middleware
  fetchApi: customFetch,                // Custom fetch implementation
});

Development

Regenerate the SDK from the OpenAPI spec

npm run generate

Build

npm run build

Publishing

In order to publish a new version of the SDK, there are a few steps to follow:

1. Update the version number in package.json according to semver rules.
2. Build the SDK using npm run build.
3. Ensure you have an npm account and are logged in via the command line (npm login), or are using the .npmrc file with the correct auth token.
4. Publish the package to npm using npm publish.

License

MIT