Node.js SDK Quickstart

@superinstance/tminus-client — Semantic crate discovery for your Node.js projects

Installation

npm install @superinstance/tminus-clientCopy

Quick Start

import { FleetClient } from '@superinstance/tminus-client';

const client = new FleetClient({
  baseUrl: 'https://fleet-vector-api.casey-digennaro.workers.dev',
});

// Search for crates by natural language
const results = await client.search('HTTP client with retry logic');
console.log(results); // → CrateResult[]

// Find crates similar to a known crate
const similar = await client.similar('reqwest', { topK: 5 });
console.log(similar);

// Get personalized recommendations
const recs = await client.recommend({ context: 'web scraping' });
console.log(recs);

// Check index stats
const stats = await client.stats();
console.log(stats); // → { vectorCount, dimensions, ... }Copy

API Reference

search(query, options?)

Perform a semantic search across all indexed crates.

Parameter	Type	Default	Description
query	string	—	Natural language search query
options.topK	number	10	Max results to return
options.threshold	number	0.5	Minimum similarity score (0–1)

const crates = await client.search('async runtime', { topK: 5, threshold: 0.7 });Copy

similar(name, options?)

Find crates similar to a known crate by name.

Parameter	Type	Default	Description
name	string	—	Exact crate name to find similar items for
options.topK	number	10	Max results to return

const alike = await client.similar('tokio', { topK: 3 });Copy

recommend(options)

Get crate recommendations based on a context or use case.

Parameter	Type	Default	Description
options.context	string	—	Description of your project or use case
options.topK	number	5	Max results to return

const picks = await client.recommend({ context: 'CLI tool with config parsing' });Copy

stats()

Retrieve index statistics including vector count and dimensions.

const { vectorCount, dimensions } = await client.stats();Copy

Configuration

Option	Type	Default	Description
baseUrl	string	'https://fleet-vector-api.casey-digennaro.workers.dev'	API endpoint URL
timeout	number	10000	Request timeout in milliseconds
apiKey	string	undefined	Optional API key for authenticated endpoints

const client = new FleetClient({
  baseUrl: process.env.FLEET_API_URL,
  timeout: 5000,
  apiKey: process.env.FLEET_API_KEY,
});Copy

Error Handling

import { FleetClient, FleetError } from '@superinstance/tminus-client';

try {
  const results = await client.search('database ORM');
} catch (err) {
  if (err instanceof FleetError) {
    switch (err.code) {
      case 'TIMEOUT':      console.error('Request timed out'); break;
      case 'NOT_FOUND':    console.error('Crate not found'); break;
      case 'INVALID_QUERY': console.error('Bad query'); break;
      case 'SERVER_ERROR': console.error('Server error'); break;
    }
  } else {
    throw err;
  }
}Copy

TypeScript Types

interface FleetClientOptions {
  baseUrl?: string;
  timeout?: number;
  apiKey?: string;
}

interface CrateResult {
  name: string;
  description: string;
  score: number;          // similarity score 0–1
  version?: string;
  downloads?: number;
  url?: string;
}

interface SearchOptions {
  topK?: number;
  threshold?: number;
}

interface SimilarOptions {
  topK?: number;
}

interface RecommendOptions {
  context: string;
  topK?: number;
}

interface IndexStats {
  vectorCount: number;
  dimensions: number;
  lastUpdated: string;
}

class FleetError extends Error {
  code: 'TIMEOUT' | 'NOT_FOUND' | 'INVALID_QUERY' | 'SERVER_ERROR';
  statusCode: number;
}Copy