@fluxsoft/fluxvector 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,337 @@
+interface FluxVectorConfig {
+    apiKey: string;
+    baseUrl?: string;
+    maxRetries?: number;
+    timeout?: number;
+}
+type FilterOperator = '$eq' | '$ne' | '$gt' | '$gte' | '$lt' | '$lte' | '$in' | '$nin';
+type FilterValue = string | number | boolean | string[] | number[];
+type FilterCondition = {
+    [K in FilterOperator]?: FilterValue;
+};
+type MetadataFilter = {
+    [field: string]: FilterCondition | FilterValue;
+};
+interface CreateCollectionParams {
+    name: string;
+    dimension?: number;
+    metric?: 'cosine' | 'euclidean' | 'dotproduct';
+    description?: string;
+}
+interface Collection {
+    name: string;
+    dimension: number;
+    metric: string;
+    description: string;
+    vectors_count: number;
+    created_at: string;
+    updated_at: string;
+}
+interface ListCollectionsParams {
+    cursor?: string;
+    limit?: number;
+}
+interface ListCollectionsResponse {
+    data: Collection[];
+    has_more: boolean;
+    next_cursor: string | null;
+}
+interface VectorInput {
+    id: string;
+    text?: string;
+    values?: number[];
+    metadata?: Record<string, unknown>;
+}
+interface Vector {
+    id: string;
+    text?: string;
+    values?: number[];
+    metadata?: Record<string, unknown>;
+}
+interface UpsertResponse {
+    upserted: number;
+}
+interface QueryParams {
+    collection: string;
+    text?: string;
+    vector?: number[];
+    top_k?: number;
+    filter?: MetadataFilter;
+    include_metadata?: boolean;
+    include_text?: boolean;
+    mode?: string;
+}
+interface QueryResult {
+    id: string;
+    score: number;
+    text?: string;
+    metadata?: Record<string, unknown>;
+    values?: number[];
+}
+interface QueryResponse {
+    results: QueryResult[];
+    usage: UsageInfo;
+    took_ms: number;
+}
+interface DeleteVectorsParams {
+    collection: string;
+    ids?: string[];
+    filter?: MetadataFilter;
+}
+interface FetchVectorsParams {
+    ids: string[];
+    collection: string;
+}
+interface FetchVectorsResponse {
+    vectors: Vector[];
+}
+interface SearchParams {
+    collection: string;
+    text: string;
+    top_k?: number;
+    filter?: MetadataFilter;
+    mode?: string;
+}
+interface SearchResponse {
+    results: QueryResult[];
+    usage: UsageInfo;
+    took_ms: number;
+}
+interface EmbedResponse {
+    embedding: number[];
+    dimension: number;
+    model: string;
+}
+interface EmbedBatchResponse {
+    embeddings: number[][];
+    dimension: number;
+    model: string;
+}
+interface CreateApiKeyParams {
+    name: string;
+    env?: 'live' | 'test';
+}
+interface ApiKey {
+    id: string;
+    key?: string;
+    prefix: string;
+    name: string;
+    env: string;
+    warning?: string;
+    created_at?: string;
+}
+interface UpdateApiKeyParams {
+    name: string;
+}
+interface ListApiKeysResponse {
+    data: ApiKey[];
+}
+interface UsageInfo {
+    embeddings?: number;
+    [key: string]: unknown;
+}
+interface UsageOverview {
+    plan: string;
+    period_start: string;
+    requests: number;
+    embeddings: number;
+    vectors_stored: number;
+    collections: number;
+}
+interface UsageHistoryParams {
+    days?: number;
+}
+interface UsageHistoryEntry {
+    date: string;
+    requests: number;
+    embeddings: number;
+    vectors: number;
+}
+interface UsageHistoryResponse {
+    data: UsageHistoryEntry[];
+}
+interface RequestOptions {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | undefined>;
+}
+
+declare class HttpClient {
+    private readonly config;
+    constructor(config: {
+        apiKey: string;
+        baseUrl?: string;
+        maxRetries?: number;
+        timeout?: number;
+    });
+    request<T>(options: RequestOptions): Promise<T>;
+    private buildUrl;
+    private buildError;
+    private safeJson;
+    private getRetryDelay;
+    private sleep;
+}
+
+declare class Collections {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Create a new collection.
+     */
+    create(params: CreateCollectionParams): Promise<Collection>;
+    /**
+     * List all collections with cursor-based pagination.
+     */
+    list(params?: ListCollectionsParams): Promise<ListCollectionsResponse>;
+    /**
+     * Get a collection by name.
+     */
+    get(name: string): Promise<Collection>;
+    /**
+     * Delete a collection by name.
+     */
+    delete(name: string): Promise<{
+        deleted: true;
+    }>;
+}
+
+declare class Vectors {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Upsert vectors into a collection.
+     * Automatically chunks into batches of 1000 vectors.
+     */
+    upsert(collection: string, vectors: VectorInput[]): Promise<UpsertResponse>;
+    /**
+     * Query vectors by text or vector with optional filtering.
+     */
+    query(params: QueryParams): Promise<QueryResponse>;
+    /**
+     * Delete vectors by IDs or filter.
+     */
+    delete(collection: string, options: {
+        ids?: string[];
+        filter?: MetadataFilter;
+    }): Promise<{
+        deleted: true;
+    }>;
+    /**
+     * Fetch vectors by their IDs.
+     */
+    fetch(collection: string, ids: string[]): Promise<FetchVectorsResponse>;
+}
+
+interface SearchOptions {
+    topK?: number;
+    filter?: MetadataFilter;
+    mode?: string;
+}
+declare class Search {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Semantic search across a collection.
+     * Returns matching results ranked by relevance.
+     */
+    query(collection: string, text: string, options?: SearchOptions): Promise<QueryResult[]>;
+    /**
+     * Semantic search with full response (includes usage and timing).
+     */
+    queryWithMeta(collection: string, text: string, options?: SearchOptions): Promise<SearchResponse>;
+}
+
+declare class Embeddings {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Generate an embedding for a single text.
+     */
+    create(text: string): Promise<EmbedResponse>;
+    /**
+     * Generate embeddings for multiple texts in a single request.
+     */
+    createBatch(texts: string[]): Promise<EmbedBatchResponse>;
+}
+
+declare class ApiKeys {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Create a new API key.
+     */
+    create(params: CreateApiKeyParams): Promise<ApiKey>;
+    /**
+     * List all API keys.
+     */
+    list(): Promise<ListApiKeysResponse>;
+    /**
+     * Update an API key's name.
+     */
+    update(id: string, params: UpdateApiKeyParams): Promise<ApiKey>;
+    /**
+     * Delete an API key.
+     */
+    delete(id: string): Promise<{
+        deleted: true;
+    }>;
+}
+
+declare class Usage {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Get current usage overview for the billing period.
+     */
+    get(): Promise<UsageOverview>;
+    /**
+     * Get historical usage data.
+     */
+    history(params?: UsageHistoryParams): Promise<UsageHistoryResponse>;
+}
+
+declare class FluxVectorError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string | undefined;
+    constructor(message: string, status: number, code?: string, requestId?: string);
+}
+declare class AuthenticationError extends FluxVectorError {
+    constructor(message?: string, requestId?: string);
+}
+declare class NotFoundError extends FluxVectorError {
+    constructor(message?: string, requestId?: string);
+}
+declare class RateLimitError extends FluxVectorError {
+    readonly retryAfter: number | undefined;
+    constructor(message?: string, retryAfter?: number, requestId?: string);
+}
+declare class ValidationError extends FluxVectorError {
+    constructor(message?: string, requestId?: string);
+}
+declare class ServerError extends FluxVectorError {
+    constructor(message?: string, status?: number, requestId?: string);
+}
+
+declare class FluxVector {
+    readonly collections: Collections;
+    readonly vectors: Vectors;
+    readonly embeddings: Embeddings;
+    readonly apiKeys: ApiKeys;
+    readonly usage: Usage;
+    private readonly searchResource;
+    constructor(config: FluxVectorConfig);
+    /**
+     * Semantic search across a collection.
+     *
+     * @example
+     * const results = await fv.search('products', 'comfortable shoes', {
+     *   topK: 5,
+     *   filter: { price: { $lt: 100 } },
+     * });
+     */
+    search(collection: string, text: string, options?: SearchOptions): Promise<QueryResult[]>;
+}
+
+export { type ApiKey, ApiKeys, AuthenticationError, type Collection, Collections, type CreateApiKeyParams, type CreateCollectionParams, type DeleteVectorsParams, type EmbedBatchResponse, type EmbedResponse, Embeddings, type FetchVectorsParams, type FetchVectorsResponse, type FilterCondition, type FilterOperator, type FilterValue, FluxVector, type FluxVectorConfig, FluxVectorError, HttpClient, type ListApiKeysResponse, type ListCollectionsParams, type ListCollectionsResponse, type MetadataFilter, NotFoundError, type QueryParams, type QueryResponse, type QueryResult, RateLimitError, Search, type SearchOptions, type SearchParams, type SearchResponse, ServerError, type UpdateApiKeyParams, type UpsertResponse, Usage, type UsageHistoryEntry, type UsageHistoryParams, type UsageHistoryResponse, type UsageInfo, type UsageOverview, ValidationError, type Vector, type VectorInput, Vectors };