@fluxsoft/fluxvector 0.1.0

package/README.md

@@ -0,0 +1,234 @@
+# @fluxsoft/fluxvector
+
+Official TypeScript SDK for [FluxVector](https://fluxsoftlabs.com/fluxvector) — semantic search API by FluxSoft Labs.
+
+- Zero runtime dependencies (native `fetch`, works in Node 18+, Deno, Bun, edge runtimes)
+- Full TypeScript types for every request and response
+- Automatic retry with exponential backoff
+- Auto-chunking for large upserts
+- ESM + CJS dual package
+
+## Install
+
+```bash
+npm install @fluxsoft/fluxvector
+```
+
+```bash
+pnpm add @fluxsoft/fluxvector
+```
+
+```bash
+yarn add @fluxsoft/fluxvector
+```
+
+## Quick Start
+
+```typescript
+import { FluxVector } from '@fluxsoft/fluxvector';
+
+const fv = new FluxVector({ apiKey: 'fv_live_abc123' });
+
+// Create a collection
+await fv.collections.create({ name: 'products' });
+
+// Upsert vectors
+await fv.vectors.upsert('products', [
+  { id: 'p1', text: 'Red shoes', metadata: { price: 89 } },
+  { id: 'p2', text: 'Blue sneakers', metadata: { price: 120 } },
+]);
+
+// Search
+const results = await fv.search('products', 'comfortable shoes', {
+  topK: 5,
+  filter: { price: { $lt: 100 } },
+});
+
+for (const r of results) {
+  console.log(`${r.id}: ${r.score.toFixed(2)} — ${r.text}`);
+}
+```
+
+## Configuration
+
+```typescript
+const fv = new FluxVector({
+  apiKey: 'fv_live_abc123',     // Required
+  baseUrl: 'https://fluxvector.dev', // Default, configurable for self-hosted
+  maxRetries: 3,                // Default: 3 (retries on 429 and 5xx)
+  timeout: 30000,               // Default: 30s
+});
+```
+
+## API Reference
+
+### Collections
+
+```typescript
+// Create
+const col = await fv.collections.create({
+  name: 'products',
+  dimension: 1536,        // Optional, default: auto
+  metric: 'cosine',       // 'cosine' | 'euclidean' | 'dotproduct'
+  description: 'Product catalog',
+});
+
+// List (cursor pagination)
+const { data, has_more, next_cursor } = await fv.collections.list({ limit: 10 });
+
+// Get
+const col = await fv.collections.get('products');
+
+// Delete
+await fv.collections.delete('products');
+```
+
+### Vectors
+
+```typescript
+// Upsert (auto-chunks at 1000 vectors)
+await fv.vectors.upsert('products', [
+  { id: 'p1', text: 'Red shoes', metadata: { price: 89, category: 'footwear' } },
+  { id: 'p2', values: [0.1, 0.2, ...], metadata: { price: 120 } },
+]);
+
+// Query
+const { results, usage, took_ms } = await fv.vectors.query({
+  collection: 'products',
+  text: 'comfortable shoes',
+  top_k: 10,
+  filter: { category: { $eq: 'footwear' } },
+  include_metadata: true,
+  include_text: true,
+});
+
+// Fetch by IDs
+const { vectors } = await fv.vectors.fetch('products', ['p1', 'p2']);
+
+// Delete by IDs
+await fv.vectors.delete('products', { ids: ['p1', 'p2'] });
+
+// Delete by filter
+await fv.vectors.delete('products', { filter: { category: { $eq: 'old' } } });
+```
+
+### Search
+
+The top-level `fv.search()` is the simplest way to do semantic search:
+
+```typescript
+// Returns QueryResult[] directly
+const results = await fv.search('products', 'comfortable shoes', {
+  topK: 5,
+  filter: { price: { $lt: 100 } },
+  mode: 'hybrid',
+});
+
+// Each result: { id, score, text?, metadata? }
+```
+
+### Embeddings
+
+```typescript
+// Single text
+const { embedding, dimension, model } = await fv.embeddings.create('hello world');
+
+// Batch
+const { embeddings, dimension, model } = await fv.embeddings.createBatch([
+  'hello world',
+  'goodbye world',
+]);
+```
+
+### API Keys
+
+```typescript
+// Create
+const key = await fv.apiKeys.create({ name: 'Production', env: 'live' });
+console.log(key.key); // fv_live_xxx — shown only once
+
+// List
+const { data } = await fv.apiKeys.list();
+
+// Update
+await fv.apiKeys.update('key_123', { name: 'Renamed' });
+
+// Delete
+await fv.apiKeys.delete('key_123');
+```
+
+### Usage
+
+```typescript
+// Current period
+const usage = await fv.usage.get();
+// { plan, period_start, requests, embeddings, vectors_stored, collections }
+
+// History
+const { data } = await fv.usage.history({ days: 30 });
+// [{ date, requests, embeddings, vectors }]
+```
+
+## Filter Operators
+
+Filters use MongoDB-style operators on metadata fields:
+
+| Operator | Description |
+|----------|-------------|
+| `$eq`    | Equal to |
+| `$ne`    | Not equal to |
+| `$gt`    | Greater than |
+| `$gte`   | Greater than or equal |
+| `$lt`    | Less than |
+| `$lte`   | Less than or equal |
+| `$in`    | In array |
+| `$nin`   | Not in array |
+
+```typescript
+// Examples
+{ price: { $lt: 100 } }
+{ category: { $in: ['shoes', 'boots'] } }
+{ status: { $ne: 'archived' } }
+```
+
+## Error Handling
+
+All errors extend `FluxVectorError` with `status`, `code`, and optional `requestId`:
+
+```typescript
+import { FluxVector, AuthenticationError, NotFoundError, RateLimitError } from '@fluxsoft/fluxvector';
+
+try {
+  await fv.collections.get('missing');
+} catch (err) {
+  if (err instanceof NotFoundError) {
+    console.log('Collection does not exist');
+  } else if (err instanceof AuthenticationError) {
+    console.log('Check your API key');
+  } else if (err instanceof RateLimitError) {
+    console.log(`Retry after ${err.retryAfter}s`);
+  }
+}
+```
+
+| Error Class | Status | When |
+|-------------|--------|------|
+| `AuthenticationError` | 401 | Invalid or missing API key |
+| `NotFoundError` | 404 | Resource not found |
+| `ValidationError` | 422 | Invalid request body |
+| `RateLimitError` | 429 | Too many requests |
+| `ServerError` | 5xx | Server-side error |
+| `FluxVectorError` | any | Base class for all errors |
+
+## Retry Behavior
+
+The SDK automatically retries on 429 (rate limit) and 5xx (server errors):
+
+- Default: 3 retries with exponential backoff (500ms, 1s, 2s + jitter)
+- Respects `Retry-After` headers on 429 responses
+- Non-retryable errors (400, 401, 404, 422) fail immediately
+- Set `maxRetries: 0` to disable retries
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,495 @@
+'use strict';
+
+// src/errors.ts
+var FluxVectorError = class extends Error {
+  status;
+  code;
+  requestId;
+  constructor(message, status, code = "unknown_error", requestId) {
+    super(message);
+    this.name = "FluxVectorError";
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthenticationError = class extends FluxVectorError {
+  constructor(message = "Invalid or missing API key", requestId) {
+    super(message, 401, "authentication_error", requestId);
+    this.name = "AuthenticationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var NotFoundError = class extends FluxVectorError {
+  constructor(message = "Resource not found", requestId) {
+    super(message, 404, "not_found", requestId);
+    this.name = "NotFoundError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var RateLimitError = class extends FluxVectorError {
+  retryAfter;
+  constructor(message = "Rate limit exceeded", retryAfter, requestId) {
+    super(message, 429, "rate_limit_exceeded", requestId);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ValidationError = class extends FluxVectorError {
+  constructor(message = "Validation failed", requestId) {
+    super(message, 422, "validation_error", requestId);
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ServerError = class extends FluxVectorError {
+  constructor(message = "Internal server error", status = 500, requestId) {
+    super(message, status, "server_error", requestId);
+    this.name = "ServerError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://fluxvector.dev";
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_TIMEOUT = 3e4;
+var RETRY_STATUS_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var HttpClient = class {
+  config;
+  constructor(config) {
+    this.config = {
+      apiKey: config.apiKey,
+      baseUrl: (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
+      maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+      timeout: config.timeout ?? DEFAULT_TIMEOUT
+    };
+  }
+  async request(options) {
+    const url = this.buildUrl(options.path, options.query);
+    const headers = {
+      "Authorization": `Bearer ${this.config.apiKey}`,
+      "Content-Type": "application/json",
+      "User-Agent": "@fluxsoft/fluxvector/0.1.0"
+    };
+    const init = {
+      method: options.method,
+      headers,
+      body: options.body !== void 0 ? JSON.stringify(options.body) : void 0,
+      signal: AbortSignal.timeout(this.config.timeout)
+    };
+    let lastError;
+    for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+      if (attempt > 0) {
+        await this.sleep(this.getRetryDelay(attempt, lastError));
+      }
+      try {
+        const response = await fetch(url, init);
+        if (response.ok) {
+          return await response.json();
+        }
+        const requestId = response.headers.get("x-request-id") ?? void 0;
+        if (!RETRY_STATUS_CODES.has(response.status) || attempt === this.config.maxRetries) {
+          throw this.buildError(response.status, await this.safeJson(response), requestId);
+        }
+        lastError = this.buildError(response.status, await this.safeJson(response), requestId);
+        if (response.status === 429) {
+          const retryAfter = response.headers.get("retry-after");
+          if (retryAfter && lastError instanceof RateLimitError) {
+            lastError.retryAfter = Number(retryAfter);
+          }
+        }
+      } catch (error) {
+        if (error instanceof FluxVectorError) {
+          throw error;
+        }
+        if (attempt === this.config.maxRetries) {
+          if (error instanceof DOMException && error.name === "TimeoutError") {
+            throw new FluxVectorError("Request timed out", 0, "timeout");
+          }
+          throw new FluxVectorError(
+            error instanceof Error ? error.message : "Unknown network error",
+            0,
+            "network_error"
+          );
+        }
+        lastError = error instanceof Error ? error : new Error(String(error));
+      }
+    }
+    throw lastError ?? new FluxVectorError("Request failed after retries", 0, "retry_exhausted");
+  }
+  buildUrl(path, query) {
+    const url = new URL(`${this.config.baseUrl}${path}`);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    return url.toString();
+  }
+  buildError(status, body, requestId) {
+    const message = body?.message ?? body?.error ?? `Request failed with status ${status}`;
+    switch (status) {
+      case 401:
+        return new AuthenticationError(message, requestId);
+      case 404:
+        return new NotFoundError(message, requestId);
+      case 422:
+        return new ValidationError(message, requestId);
+      case 429: {
+        const retryAfter = body?.retry_after;
+        return new RateLimitError(message, retryAfter, requestId);
+      }
+      default:
+        if (status >= 500) {
+          return new ServerError(message, status, requestId);
+        }
+        return new FluxVectorError(message, status, "api_error", requestId);
+    }
+  }
+  async safeJson(response) {
+    try {
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+  getRetryDelay(attempt, lastError) {
+    if (lastError instanceof RateLimitError && lastError.retryAfter) {
+      return lastError.retryAfter * 1e3;
+    }
+    const base = Math.min(500 * Math.pow(2, attempt - 1), 4e3);
+    const jitter = Math.random() * base * 0.5;
+    return base + jitter;
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/resources/collections.ts
+var Collections = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Create a new collection.
+   */
+  async create(params) {
+    return this.client.request({
+      method: "POST",
+      path: "/v1/collections",
+      body: params
+    });
+  }
+  /**
+   * List all collections with cursor-based pagination.
+   */
+  async list(params) {
+    return this.client.request({
+      method: "GET",
+      path: "/v1/collections",
+      query: {
+        cursor: params?.cursor,
+        limit: params?.limit
+      }
+    });
+  }
+  /**
+   * Get a collection by name.
+   */
+  async get(name) {
+    return this.client.request({
+      method: "GET",
+      path: `/v1/collections/${encodeURIComponent(name)}`
+    });
+  }
+  /**
+   * Delete a collection by name.
+   */
+  async delete(name) {
+    return this.client.request({
+      method: "DELETE",
+      path: `/v1/collections/${encodeURIComponent(name)}`
+    });
+  }
+};
+
+// src/resources/vectors.ts
+var MAX_UPSERT_BATCH_SIZE = 1e3;
+var Vectors = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Upsert vectors into a collection.
+   * Automatically chunks into batches of 1000 vectors.
+   */
+  async upsert(collection, vectors) {
+    if (vectors.length <= MAX_UPSERT_BATCH_SIZE) {
+      return this.client.request({
+        method: "POST",
+        path: "/v1/vectors/upsert",
+        body: { collection, vectors }
+      });
+    }
+    let totalUpserted = 0;
+    for (let i = 0; i < vectors.length; i += MAX_UPSERT_BATCH_SIZE) {
+      const chunk = vectors.slice(i, i + MAX_UPSERT_BATCH_SIZE);
+      const result = await this.client.request({
+        method: "POST",
+        path: "/v1/vectors/upsert",
+        body: { collection, vectors: chunk }
+      });
+      totalUpserted += result.upserted;
+    }
+    return { upserted: totalUpserted };
+  }
+  /**
+   * Query vectors by text or vector with optional filtering.
+   */
+  async query(params) {
+    return this.client.request({
+      method: "POST",
+      path: "/v1/vectors/query",
+      body: {
+        collection: params.collection,
+        text: params.text,
+        vector: params.vector,
+        top_k: params.top_k,
+        filter: params.filter,
+        include_metadata: params.include_metadata,
+        include_text: params.include_text,
+        mode: params.mode
+      }
+    });
+  }
+  /**
+   * Delete vectors by IDs or filter.
+   */
+  async delete(collection, options) {
+    return this.client.request({
+      method: "POST",
+      path: "/v1/vectors/delete",
+      body: {
+        collection,
+        ids: options.ids,
+        filter: options.filter
+      }
+    });
+  }
+  /**
+   * Fetch vectors by their IDs.
+   */
+  async fetch(collection, ids) {
+    return this.client.request({
+      method: "GET",
+      path: "/v1/vectors/fetch",
+      query: {
+        collection,
+        ids: ids.join(",")
+      }
+    });
+  }
+};
+
+// src/resources/search.ts
+var Search = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Semantic search across a collection.
+   * Returns matching results ranked by relevance.
+   */
+  async query(collection, text, options) {
+    const response = await this.client.request({
+      method: "POST",
+      path: "/v1/search",
+      body: {
+        collection,
+        text,
+        top_k: options?.topK,
+        filter: options?.filter,
+        mode: options?.mode
+      }
+    });
+    return response.results;
+  }
+  /**
+   * Semantic search with full response (includes usage and timing).
+   */
+  async queryWithMeta(collection, text, options) {
+    return this.client.request({
+      method: "POST",
+      path: "/v1/search",
+      body: {
+        collection,
+        text,
+        top_k: options?.topK,
+        filter: options?.filter,
+        mode: options?.mode
+      }
+    });
+  }
+};
+
+// src/resources/embeddings.ts
+var Embeddings = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Generate an embedding for a single text.
+   */
+  async create(text) {
+    return this.client.request({
+      method: "POST",
+      path: "/v1/embed",
+      body: { text }
+    });
+  }
+  /**
+   * Generate embeddings for multiple texts in a single request.
+   */
+  async createBatch(texts) {
+    return this.client.request({
+      method: "POST",
+      path: "/v1/embed/batch",
+      body: { texts }
+    });
+  }
+};
+
+// src/resources/api-keys.ts
+var ApiKeys = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Create a new API key.
+   */
+  async create(params) {
+    return this.client.request({
+      method: "POST",
+      path: "/v1/api-keys",
+      body: params
+    });
+  }
+  /**
+   * List all API keys.
+   */
+  async list() {
+    return this.client.request({
+      method: "GET",
+      path: "/v1/api-keys"
+    });
+  }
+  /**
+   * Update an API key's name.
+   */
+  async update(id, params) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/v1/api-keys/${encodeURIComponent(id)}`,
+      body: params
+    });
+  }
+  /**
+   * Delete an API key.
+   */
+  async delete(id) {
+    return this.client.request({
+      method: "DELETE",
+      path: `/v1/api-keys/${encodeURIComponent(id)}`
+    });
+  }
+};
+
+// src/resources/usage.ts
+var Usage = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get current usage overview for the billing period.
+   */
+  async get() {
+    return this.client.request({
+      method: "GET",
+      path: "/v1/usage"
+    });
+  }
+  /**
+   * Get historical usage data.
+   */
+  async history(params) {
+    return this.client.request({
+      method: "GET",
+      path: "/v1/usage/history",
+      query: {
+        days: params?.days
+      }
+    });
+  }
+};
+
+// src/index.ts
+var FluxVector = class {
+  collections;
+  vectors;
+  embeddings;
+  apiKeys;
+  usage;
+  searchResource;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("FluxVector: apiKey is required");
+    }
+    const client = new HttpClient({
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl,
+      maxRetries: config.maxRetries,
+      timeout: config.timeout
+    });
+    this.collections = new Collections(client);
+    this.vectors = new Vectors(client);
+    this.searchResource = new Search(client);
+    this.embeddings = new Embeddings(client);
+    this.apiKeys = new ApiKeys(client);
+    this.usage = new Usage(client);
+  }
+  /**
+   * Semantic search across a collection.
+   *
+   * @example
+   * const results = await fv.search('products', 'comfortable shoes', {
+   *   topK: 5,
+   *   filter: { price: { $lt: 100 } },
+   * });
+   */
+  async search(collection, text, options) {
+    return this.searchResource.query(collection, text, options);
+  }
+};
+
+exports.ApiKeys = ApiKeys;
+exports.AuthenticationError = AuthenticationError;
+exports.Collections = Collections;
+exports.Embeddings = Embeddings;
+exports.FluxVector = FluxVector;
+exports.FluxVectorError = FluxVectorError;
+exports.HttpClient = HttpClient;
+exports.NotFoundError = NotFoundError;
+exports.RateLimitError = RateLimitError;
+exports.Search = Search;
+exports.ServerError = ServerError;
+exports.Usage = Usage;
+exports.ValidationError = ValidationError;
+exports.Vectors = Vectors;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map