@ductape/sdk 0.0.4-v51 → 0.0.4-v52

package/dist/vector/types/vector.interface.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Vector Operation Types
+ *
+ * Interfaces for vector CRUD operations.
+ */
+import { DistanceMetric } from './enums';
+/**
+ * Vector metadata (can store any JSON-serializable data)
+ */
+export type VectorMetadata = Record<string, unknown>;
+/**
+ * Vector representation
+ */
+export interface IVector {
+    /** Unique vector ID */
+    id: string;
+    /** Vector values (embedding) */
+    values: number[];
+    /** Sparse vector values (for hybrid search) */
+    sparseValues?: ISparseVector;
+    /** Associated metadata */
+    metadata?: VectorMetadata;
+}
+/**
+ * Sparse vector representation
+ */
+export interface ISparseVector {
+    /** Non-zero indices */
+    indices: number[];
+    /** Values at those indices */
+    values: number[];
+}
+/**
+ * Options for upserting vectors
+ */
+export interface IUpsertVectorsOptions {
+    /** Vectors to upsert */
+    vectors: IVector[];
+    /** Namespace (for multi-tenancy) */
+    namespace?: string;
+    /** Wait for index to update */
+    wait?: boolean;
+}
+/**
+ * Upsert result
+ */
+export interface IUpsertVectorsResult {
+    /** Number of vectors upserted */
+    upsertedCount: number;
+    /** IDs of upserted vectors */
+    upsertedIds?: string[];
+}
+/**
+ * Metadata filter operators
+ */
+export interface IMetadataFilter {
+    /** Field to filter on */
+    field: string;
+    /** Operator */
+    operator: MetadataFilterOperator;
+    /** Value to compare */
+    value: unknown;
+}
+/**
+ * Supported filter operators
+ */
+export type MetadataFilterOperator = '$eq' | '$ne' | '$gt' | '$gte' | '$lt' | '$lte' | '$in' | '$nin' | '$exists' | '$contains' | '$startsWith' | '$endsWith';
+/**
+ * Combined filter with logical operators
+ */
+export interface IMetadataFilterGroup {
+    /** AND conditions */
+    $and?: Array<IMetadataFilter | IMetadataFilterGroup>;
+    /** OR conditions */
+    $or?: Array<IMetadataFilter | IMetadataFilterGroup>;
+    /** NOT condition */
+    $not?: IMetadataFilter | IMetadataFilterGroup;
+}
+/**
+ * Options for querying vectors
+ */
+export interface IQueryVectorsOptions {
+    /** Query vector */
+    vector: number[];
+    /** Number of results to return */
+    topK: number;
+    /** Namespace */
+    namespace?: string;
+    /** Metadata filter */
+    filter?: IMetadataFilter | IMetadataFilterGroup;
+    /** Include vector values in results */
+    includeValues?: boolean;
+    /** Include metadata in results */
+    includeMetadata?: boolean;
+    /** Minimum similarity score threshold */
+    minScore?: number;
+    /** Sparse vector for hybrid search */
+    sparseVector?: ISparseVector;
+    /** Alpha for hybrid search (0 = pure sparse, 1 = pure dense) */
+    alpha?: number;
+}
+/**
+ * Query match result
+ */
+export interface IQueryMatch {
+    /** Vector ID */
+    id: string;
+    /** Similarity score */
+    score: number;
+    /** Vector values (if requested) */
+    values?: number[];
+    /** Metadata (if requested) */
+    metadata?: VectorMetadata;
+}
+/**
+ * Query result
+ */
+export interface IQueryVectorsResult {
+    /** Matching vectors */
+    matches: IQueryMatch[];
+    /** Namespace queried */
+    namespace?: string;
+    /** Query execution time in ms */
+    queryTime?: number;
+}
+/**
+ * Options for fetching vectors by ID
+ */
+export interface IFetchVectorsOptions {
+    /** Vector IDs to fetch */
+    ids: string[];
+    /** Namespace */
+    namespace?: string;
+    /** Include vector values */
+    includeValues?: boolean;
+}
+/**
+ * Fetch result
+ */
+export interface IFetchVectorsResult {
+    /** Fetched vectors keyed by ID */
+    vectors: Record<string, IVector | null>;
+    /** Namespace */
+    namespace?: string;
+}
+/**
+ * Options for updating a vector
+ */
+export interface IUpdateVectorOptions {
+    /** Vector ID */
+    id: string;
+    /** New vector values (optional) */
+    values?: number[];
+    /** Sparse vector values (optional) */
+    sparseValues?: ISparseVector;
+    /** Metadata to set (replaces existing) */
+    setMetadata?: VectorMetadata;
+    /** Metadata to merge (updates existing) */
+    mergeMetadata?: VectorMetadata;
+    /** Namespace */
+    namespace?: string;
+}
+/**
+ * Update result
+ */
+export interface IUpdateVectorResult {
+    /** Whether update was successful */
+    success: boolean;
+    /** Updated vector ID */
+    id: string;
+}
+/**
+ * Options for deleting vectors
+ */
+export interface IDeleteVectorsOptions {
+    /** Specific IDs to delete */
+    ids?: string[];
+    /** Delete all vectors matching filter */
+    filter?: IMetadataFilter | IMetadataFilterGroup;
+    /** Delete all vectors in namespace */
+    deleteAll?: boolean;
+    /** Namespace */
+    namespace?: string;
+}
+/**
+ * Delete result
+ */
+export interface IDeleteVectorsResult {
+    /** Number of vectors deleted */
+    deletedCount: number;
+    /** IDs of deleted vectors (if available) */
+    deletedIds?: string[];
+}
+/**
+ * Options for listing vectors
+ */
+export interface IListVectorsOptions {
+    /** Namespace */
+    namespace?: string;
+    /** Prefix filter for IDs */
+    prefix?: string;
+    /** Maximum results */
+    limit?: number;
+    /** Pagination cursor */
+    cursor?: string;
+}
+/**
+ * List result
+ */
+export interface IListVectorsResult {
+    /** Vector IDs */
+    ids: string[];
+    /** Pagination cursor for next page */
+    nextCursor?: string;
+    /** Total count (if available) */
+    total?: number;
+    /** Namespace */
+    namespace?: string;
+}
+/**
+ * Namespace information
+ */
+export interface INamespaceInfo {
+    /** Namespace name */
+    name: string;
+    /** Number of vectors */
+    vectorCount: number;
+}
+/**
+ * List namespaces result
+ */
+export interface IListNamespacesResult {
+    /** Namespaces */
+    namespaces: INamespaceInfo[];
+}
+/**
+ * Index information
+ */
+export interface IVectorIndexInfo {
+    /** Index name */
+    name: string;
+    /** Vector dimensions */
+    dimensions: number;
+    /** Distance metric */
+    metric: DistanceMetric;
+    /** Total vector count */
+    vectorCount: number;
+    /** Index status */
+    status: 'ready' | 'initializing' | 'scaling' | 'terminating';
+    /** Pod type (for managed services) */
+    podType?: string;
+    /** Replicas */
+    replicas?: number;
+    /** Created timestamp */
+    createdAt?: number;
+}
+/**
+ * Options for creating an index
+ */
+export interface ICreateIndexOptions {
+    /** Index name */
+    name: string;
+    /** Vector dimensions */
+    dimensions: number;
+    /** Distance metric */
+    metric?: DistanceMetric;
+    /** Cloud region */
+    region?: string;
+    /** Pod type (for managed services) */
+    podType?: string;
+    /** Number of replicas */
+    replicas?: number;
+    /** Additional options */
+    options?: Record<string, unknown>;
+}
+/**
+ * Create index result
+ */
+export interface ICreateIndexResult {
+    /** Whether creation was successful */
+    success: boolean;
+    /** Index name */
+    name: string;
+    /** Host endpoint */
+    host?: string;
+}
+/**
+ * Options for deleting an index
+ */
+export interface IDeleteIndexOptions {
+    /** Index name */
+    name: string;
+}
+/**
+ * Delete index result
+ */
+export interface IDeleteIndexResult {
+    /** Whether deletion was successful */
+    success: boolean;
+}
+/**
+ * Index statistics
+ */
+export interface IVectorIndexStats {
+    /** Total vector count */
+    vectorCount: number;
+    /** Index fullness (0-1) */
+    indexFullness?: number;
+    /** Namespace statistics */
+    namespaces?: Record<string, {
+        vectorCount: number;
+    }>;
+    /** Dimensions */
+    dimensions: number;
+}

package/dist/vector/types/vector.interface.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Vector Operation Types
+ *
+ * Interfaces for vector CRUD operations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=vector.interface.js.map

package/dist/vector/types/vector.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector.interface.js","sourceRoot":"","sources":["../../../src/vector/types/vector.interface.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

package/dist/vector/utils/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Vector Utils Index
+ *
+ * Export utility classes.
+ */
+export { VectorError } from './vector-error';

package/dist/vector/utils/index.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Vector Utils Index
+ *
+ * Export utility classes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VectorError = void 0;
+var vector_error_1 = require("./vector-error");
+Object.defineProperty(exports, "VectorError", { enumerable: true, get: function () { return vector_error_1.VectorError; } });
+//# sourceMappingURL=index.js.map

package/dist/vector/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/vector/utils/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,+CAA6C;AAApC,2GAAA,WAAW,OAAA"}

package/dist/vector/utils/vector-error.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Vector Error
+ *
+ * Error class for vector database operations.
+ */
+import { VectorErrorType, VectorDBType } from '../types';
+/**
+ * Custom error class for vector database operations
+ */
+export declare class VectorError extends Error {
+    /** Error type */
+    readonly type: VectorErrorType;
+    /** Vector database type */
+    readonly dbType?: VectorDBType;
+    /** Original error */
+    readonly originalError?: Error;
+    /** Additional context */
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, type?: VectorErrorType, options?: {
+        dbType?: VectorDBType;
+        originalError?: Error;
+        context?: Record<string, unknown>;
+    });
+    /**
+     * Create a connection error
+     */
+    static connectionError(message: string, dbType?: VectorDBType, originalError?: Error): VectorError;
+    /**
+     * Create a configuration error
+     */
+    static configurationError(message: string, context?: Record<string, unknown>): VectorError;
+    /**
+     * Create an authentication error
+     */
+    static authenticationError(message: string, dbType?: VectorDBType): VectorError;
+    /**
+     * Create a collection not found error
+     */
+    static collectionNotFoundError(collectionName: string, dbType?: VectorDBType): VectorError;
+    /**
+     * Create a vector not found error
+     */
+    static vectorNotFoundError(vectorId: string, dbType?: VectorDBType): VectorError;
+    /**
+     * Create a dimension mismatch error
+     */
+    static dimensionMismatchError(expected: number, actual: number, dbType?: VectorDBType): VectorError;
+    /**
+     * Create an invalid operation error
+     */
+    static invalidOperationError(message: string, dbType?: VectorDBType): VectorError;
+    /**
+     * Create a rate limit error
+     */
+    static rateLimitError(message: string, dbType?: VectorDBType, retryAfter?: number): VectorError;
+    /**
+     * Create a timeout error
+     */
+    static timeoutError(operation: string, timeoutMs: number, dbType?: VectorDBType): VectorError;
+    /**
+     * Wrap an unknown error
+     */
+    static fromUnknown(error: unknown, dbType?: VectorDBType, context?: Record<string, unknown>): VectorError;
+    /**
+     * Convert to JSON
+     */
+    toJSON(): Record<string, unknown>;
+}
+export default VectorError;

package/dist/vector/utils/vector-error.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Vector Error
+ *
+ * Error class for vector database operations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VectorError = void 0;
+const types_1 = require("../types");
+/**
+ * Custom error class for vector database operations
+ */
+class VectorError extends Error {
+    constructor(message, type = types_1.VectorErrorType.UNKNOWN_ERROR, options) {
+        super(message);
+        this.name = 'VectorError';
+        this.type = type;
+        this.dbType = options === null || options === void 0 ? void 0 : options.dbType;
+        this.originalError = options === null || options === void 0 ? void 0 : options.originalError;
+        this.context = options === null || options === void 0 ? void 0 : options.context;
+        // Preserve stack trace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, VectorError);
+        }
+    }
+    /**
+     * Create a connection error
+     */
+    static connectionError(message, dbType, originalError) {
+        return new VectorError(message, types_1.VectorErrorType.CONNECTION_ERROR, {
+            dbType,
+            originalError,
+        });
+    }
+    /**
+     * Create a configuration error
+     */
+    static configurationError(message, context) {
+        return new VectorError(message, types_1.VectorErrorType.CONFIGURATION_ERROR, { context });
+    }
+    /**
+     * Create an authentication error
+     */
+    static authenticationError(message, dbType) {
+        return new VectorError(message, types_1.VectorErrorType.AUTHENTICATION_ERROR, { dbType });
+    }
+    /**
+     * Create a collection not found error
+     */
+    static collectionNotFoundError(collectionName, dbType) {
+        return new VectorError(`Collection '${collectionName}' not found`, types_1.VectorErrorType.COLLECTION_NOT_FOUND, { dbType, context: { collection: collectionName } });
+    }
+    /**
+     * Create a vector not found error
+     */
+    static vectorNotFoundError(vectorId, dbType) {
+        return new VectorError(`Vector '${vectorId}' not found`, types_1.VectorErrorType.VECTOR_NOT_FOUND, { dbType, context: { vectorId } });
+    }
+    /**
+     * Create a dimension mismatch error
+     */
+    static dimensionMismatchError(expected, actual, dbType) {
+        return new VectorError(`Dimension mismatch: expected ${expected}, got ${actual}`, types_1.VectorErrorType.DIMENSION_MISMATCH, { dbType, context: { expected, actual } });
+    }
+    /**
+     * Create an invalid operation error
+     */
+    static invalidOperationError(message, dbType) {
+        return new VectorError(message, types_1.VectorErrorType.INVALID_OPERATION, { dbType });
+    }
+    /**
+     * Create a rate limit error
+     */
+    static rateLimitError(message, dbType, retryAfter) {
+        return new VectorError(message, types_1.VectorErrorType.RATE_LIMIT_ERROR, {
+            dbType,
+            context: { retryAfter },
+        });
+    }
+    /**
+     * Create a timeout error
+     */
+    static timeoutError(operation, timeoutMs, dbType) {
+        return new VectorError(`Operation '${operation}' timed out after ${timeoutMs}ms`, types_1.VectorErrorType.TIMEOUT_ERROR, { dbType, context: { operation, timeoutMs } });
+    }
+    /**
+     * Wrap an unknown error
+     */
+    static fromUnknown(error, dbType, context) {
+        if (error instanceof VectorError) {
+            return error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        const originalError = error instanceof Error ? error : undefined;
+        return new VectorError(message, types_1.VectorErrorType.UNKNOWN_ERROR, {
+            dbType,
+            originalError,
+            context,
+        });
+    }
+    /**
+     * Convert to JSON
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            type: this.type,
+            message: this.message,
+            dbType: this.dbType,
+            context: this.context,
+            stack: this.stack,
+        };
+    }
+}
+exports.VectorError = VectorError;
+exports.default = VectorError;
+//# sourceMappingURL=vector-error.js.map

package/dist/vector/utils/vector-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-error.js","sourceRoot":"","sources":["../../../src/vector/utils/vector-error.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,oCAAyD;AAEzD;;GAEG;AACH,MAAa,WAAY,SAAQ,KAAK;IAUpC,YACE,OAAe,EACf,OAAwB,uBAAe,CAAC,aAAa,EACrD,OAIC;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,CAAC;QAC9B,IAAI,CAAC,aAAa,GAAG,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,aAAa,CAAC;QAC5C,IAAI,CAAC,OAAO,GAAG,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,CAAC;QAEhC,uBAAuB;QACvB,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,eAAe,CACpB,OAAe,EACf,MAAqB,EACrB,aAAqB;QAErB,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,uBAAe,CAAC,gBAAgB,EAAE;YAChE,MAAM;YACN,aAAa;SACd,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,kBAAkB,CACvB,OAAe,EACf,OAAiC;QAEjC,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,uBAAe,CAAC,mBAAmB,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IACpF,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,mBAAmB,CACxB,OAAe,EACf,MAAqB;QAErB,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,uBAAe,CAAC,oBAAoB,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACpF,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,uBAAuB,CAC5B,cAAsB,EACtB,MAAqB;QAErB,OAAO,IAAI,WAAW,CACpB,eAAe,cAAc,aAAa,EAC1C,uBAAe,CAAC,oBAAoB,EACpC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,cAAc,EAAE,EAAE,CACpD,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,mBAAmB,CACxB,QAAgB,EAChB,MAAqB;QAErB,OAAO,IAAI,WAAW,CACpB,WAAW,QAAQ,aAAa,EAChC,uBAAe,CAAC,gBAAgB,EAChC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,EAAE,CAClC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,sBAAsB,CAC3B,QAAgB,EAChB,MAAc,EACd,MAAqB;QAErB,OAAO,IAAI,WAAW,CACpB,gCAAgC,QAAQ,SAAS,MAAM,EAAE,EACzD,uBAAe,CAAC,kBAAkB,EAClC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,CAC1C,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,qBAAqB,CAC1B,OAAe,EACf,MAAqB;QAErB,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,uBAAe,CAAC,iBAAiB,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACjF,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,cAAc,CACnB,OAAe,EACf,MAAqB,EACrB,UAAmB;QAEnB,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,uBAAe,CAAC,gBAAgB,EAAE;YAChE,MAAM;YACN,OAAO,EAAE,EAAE,UAAU,EAAE;SACxB,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,YAAY,CACjB,SAAiB,EACjB,SAAiB,EACjB,MAAqB;QAErB,OAAO,IAAI,WAAW,CACpB,cAAc,SAAS,qBAAqB,SAAS,IAAI,EACzD,uBAAe,CAAC,aAAa,EAC7B,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,CAC9C,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,WAAW,CAChB,KAAc,EACd,MAAqB,EACrB,OAAiC;QAEjC,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,MAAM,aAAa,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QAEjE,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,uBAAe,CAAC,aAAa,EAAE;YAC7D,MAAM;YACN,aAAa;YACb,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC;IACJ,CAAC;CACF;AAvLD,kCAuLC;AAED,kBAAe,WAAW,CAAC"}