endee 1.0.1-beta.1 → 1.0.2

package/README.md

@@ -8,6 +8,7 @@ Endee is a TypeScript client for a vector database designed for maximum speed an
 - **Fast ANN Searches**: Efficient similarity searches on vector data
 - **Multiple Distance Metrics**: Support for cosine, L2, and inner product distance metrics
 - **Metadata Support**: Attach and search with metadata and filters
+- **Client-Side Encryption**: Optional AES-256 encryption for your metadata
 - **High Performance**: Optimized for speed and efficiency
 - **Modern ES Modules**: Native ES module support with proper tree-shaking
 
@@ -17,13 +18,21 @@ Endee is a TypeScript client for a vector database designed for maximum speed an
 npm install endee
 ```
 
+## Getting Your Auth Token
+
+1. Go to the [Endee Dashboard](https://dapp.endee.io)
+2. Sign up or log in to your account
+3. Navigate to **API Keys** section
+4. Click **Generate New Token**
+5. Copy the generated auth token and store it securely
+
 ## Quick Start
 
 ```typescript
 import { Endee } from "endee";
 
-// Initialize client with your API token
-const endee = new Endee("user_id:api_token:region");
+// Initialize client with your Auth token
+const endee = new Endee("<auth-token>");
 
 // Create a new index
 await endee.createIndex({
@@ -47,8 +56,7 @@ await index.upsert([
 // Query similar vectors
 const results = await index.query({
   vector: [0.2, 0.3, 0.4 /* ... */], // Query vector
-  topK: 10,
-  filter: { category: { eq: "reference" } }, // Optional filter
+  topK: 10
 });
 
 // Process results
@@ -66,7 +74,7 @@ for (const item of results) {
 import { Endee } from "endee";
 
 // Production with specific region
-const endee = new Endee("user_id:api_token:region");
+const endee = new Endee("<auth-token>");
 
 // Local development (defaults to http://127.0.0.1:8080/api/v1)
 const endee = new Endee();
@@ -82,10 +90,10 @@ const indexes = await endee.listIndexes();
 await endee.createIndex({
   name: "my_custom_index",
   dimension: 384,
-  spaceType: "l2", // space type
+  spaceType: "l2", // space type (cosine, l2, ip)
   M: 32, // M: Graph connectivity parameter
-  efCon: 200, // efCon: Construction-time parameter
-  useFp16: true // useFp16: Use half-precision for storage optimization
+  efCon: 256, // efCon: Construction-time parameter
+  precision: "medium" // precision: "medium" | "high" | "ultra-high" | "fp16"
 });
 
 // Delete an index
@@ -117,14 +125,14 @@ await index.upsert([
 const results = await index.query({
   vector: [/* ... */], // Query vector
   topK: 5, // Number of results to return
-  filter: { tags: "important" }, // Filter for matching
+  filter: [{ tags: { "$eq": "important" } }], // Filter array with operators
   ef: 128, // Runtime parameter for search quality
   includeVectors: true, // Include vector data in results
 });
 
 // Delete vectors
 await index.deleteVector("vec1");
-await index.deleteWithFilter({ visibility: "public" });
+await index.deleteWithFilter({ visibility: { "$eq": "public" } });
 
 // Get a specific vector
 const vector = await index.getVector("vec1");
@@ -134,6 +142,78 @@ const description = await index.describe();
 console.log(description);
 ```
 
+## Filtering
+
+Endee supports structured filtering using operators like `$eq`, `$in`, and `$range`. For detailed documentation on filtering, see the [official documentation](https://docs.endee.io/sdks/typescript/usage#filtered-querying).
+
+## Encryption
+
+Endee supports optional client-side encryption for your metadata using AES-256-CBC. When encryption is enabled, your metadata is encrypted before being sent to the server and decrypted when retrieved. The encryption key never leaves your environment.
+
+### Generating an Encryption Key
+
+```typescript
+import { Endee } from "endee";
+
+const endee = new Endee("<your-auth-token>");
+
+// Generate a secure 256-bit encryption key
+const key = endee.generateKey();
+
+```
+
+> **Important**: Store your encryption key securely. If you lose the key, you will not be able to decrypt your data. The key is a 64-character hexadecimal string (256 bits).
+
+### Creating an Encrypted Index
+
+```typescript
+// Create an index with encryption enabled
+await endee.createIndex({
+  name: "encrypted_index",
+  dimension: 128,
+  spaceType: "cosine",
+  key: key // Pass your encryption key
+});
+```
+
+### Working with Encrypted Data
+
+```typescript
+// Get index reference with encryption key
+const index = await endee.getIndex("encrypted_index", key);
+
+// Insert vectors - metadata will be automatically encrypted
+await index.upsert([
+  {
+    id: "secret_doc",
+    vector: [0.1, 0.2, 0.3 /* ... */], // Your vector data,
+    meta: { 
+      content: "This is sensitive information",
+      userId: "user123"
+    },
+  },
+]);
+
+// Query vectors - metadata will be automatically decrypted
+const results = await index.query({
+  vector: [0.2, 0.4, 0.3 /* ... */], // Your query data,
+  topK: 10,
+});
+
+// Results contain decrypted metadata
+for (const item of results) {
+  console.log(item.meta); // { content: "This is sensitive information", userId: "user123" }
+}
+```
+
+### Key Points
+
+- **Encryption is optional**: Only enable it if you need to protect sensitive metadata
+- **Key management is your responsibility**: Store keys securely (e.g., environment variables, secret managers)
+- **Vectors are not encrypted**: Only metadata is encrypted; vector data remains searchable
+- **Key verification**: The system verifies the key checksum when accessing an encrypted index
+- **No key recovery**: Lost keys cannot be recovered; encrypted data becomes inaccessible
+
 ## TypeScript Types
 
 The package includes comprehensive TypeScript types:

package/dist/types/index.d.ts

@@ -8,7 +8,7 @@ export interface CreateIndexOptions {
     spaceType?: SpaceType;
     M?: number;
     key?: string;
-    precision?: "medium" | "high" | "low";
+    precision?: "medium" | "high" | "ultra-high" | "fp16";
     efCon?: number;
     version?: number;
 }
@@ -20,7 +20,7 @@ export interface VectorItem {
 }
 export interface QueryOptions {
     vector: number[];
-    topK?: number;
+    topK: number;
     filter?: Array<Record<string, unknown>> | null;
     ef?: number;
     includeVectors?: boolean;

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,IAAI,GAAG,IAAI,CAAC;AAE/C,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAC,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAC/C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,SAAS,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,SAAS,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,CAAC,EAAE,MAAM,CAAC;CACX"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,IAAI,GAAG,IAAI,CAAC;AAE/C,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAC,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,CAAC;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAC/C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,SAAS,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,SAAS,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,CAAC,EAAE,MAAM,CAAC;CACX"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "endee",
-  "version": "1.0.1-beta.1",
+  "version": "1.0.2",
   "description": "TypeScript client for encrypted vector database with maximum security and speed",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",