@soulcraft/brainy 3.50.2 → 4.0.0

package/dist/storage/adapters/s3CompatibleStorage.d.ts

@@ -3,19 +3,11 @@
  * Uses the AWS S3 client to interact with S3-compatible storage services
  * including Amazon S3, Cloudflare R2, and Google Cloud Storage
  */
-import { GraphVerb, HNSWNoun, HNSWVerb, StatisticsData } from '../../coreTypes.js';
+import { Change, HNSWNoun, HNSWVerb, HNSWNounWithMetadata, HNSWVerbWithMetadata, StatisticsData } from '../../coreTypes.js';
 import { BaseStorage } from '../baseStorage.js';
 import { OperationConfig } from '../../utils/operationUtils.js';
 type HNSWNode = HNSWNoun;
 type Edge = HNSWVerb;
-interface ChangeLogEntry {
-    timestamp: number;
-    operation: 'add' | 'update' | 'delete';
-    entityType: 'noun' | 'verb' | 'metadata';
-    entityId: string;
-    data?: any;
-    instanceId?: string;
-}
 /**
  * S3-compatible storage adapter for server environments
  * Uses the AWS S3 client to interact with S3-compatible storage services
@@ -221,7 +213,8 @@ export declare class S3CompatibleStorage extends BaseStorage {
     protected saveNode(node: HNSWNode): Promise<void>;
     /**
      * Get a noun from storage (internal implementation)
-     * Combines vector data from getNode() with metadata from getNounMetadata()
+     * v4.0.0: Returns ONLY vector data (no metadata field)
+     * Base class combines with metadata via getNoun() -> HNSWNounWithMetadata
      */
     protected getNoun_internal(id: string): Promise<HNSWNoun | null>;
     /**
@@ -297,7 +290,8 @@ export declare class S3CompatibleStorage extends BaseStorage {
     protected saveEdge(edge: Edge): Promise<void>;
     /**
      * Get a verb from storage (internal implementation)
-     * Combines vector data from getEdge() with metadata from getVerbMetadata()
+     * v4.0.0: Returns ONLY vector + core relational fields (no metadata field)
+     * Base class combines with metadata via getVerb() -> HNSWVerbWithMetadata
      */
     protected getVerb_internal(id: string): Promise<HNSWVerb | null>;
     /**
@@ -352,7 +346,7 @@ export declare class S3CompatibleStorage extends BaseStorage {
             metadata?: Record<string, any>;
         };
     }): Promise<{
-        items: GraphVerb[];
+        items: HNSWVerbWithMetadata[];
         totalCount?: number;
         hasMore: boolean;
         nextCursor?: string;
@@ -360,15 +354,15 @@ export declare class S3CompatibleStorage extends BaseStorage {
     /**
      * Get verbs by source (internal implementation)
      */
-    protected getVerbsBySource_internal(sourceId: string): Promise<GraphVerb[]>;
+    protected getVerbsBySource_internal(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get verbs by target (internal implementation)
      */
-    protected getVerbsByTarget_internal(targetId: string): Promise<GraphVerb[]>;
+    protected getVerbsByTarget_internal(targetId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get verbs by type (internal implementation)
      */
-    protected getVerbsByType_internal(type: string): Promise<GraphVerb[]>;
+    protected getVerbsByType_internal(type: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Delete a verb from storage (internal implementation)
      */
@@ -392,6 +386,28 @@ export declare class S3CompatibleStorage extends BaseStorage {
      * All metadata operations use this internally via base class routing
      */
     protected deleteObjectFromPath(path: string): Promise<void>;
+    /**
+     * Batch delete multiple objects from S3-compatible storage
+     * Deletes up to 1000 objects per batch (S3 limit)
+     * Handles throttling, retries, and partial failures
+     *
+     * @param keys - Array of object keys (paths) to delete
+     * @param options - Configuration options for batch deletion
+     * @returns Statistics about successful and failed deletions
+     */
+    batchDelete(keys: string[], options?: {
+        maxRetries?: number;
+        retryDelayMs?: number;
+        continueOnError?: boolean;
+    }): Promise<{
+        totalRequested: number;
+        successfulDeletes: number;
+        failedDeletes: number;
+        errors: Array<{
+            key: string;
+            error: string;
+        }>;
+    }>;
     /**
      * Primitive operation: List objects under path prefix
      * All metadata operations use this internally via base class routing
@@ -498,7 +514,7 @@ export declare class S3CompatibleStorage extends BaseStorage {
      * @param maxEntries Maximum number of entries to return (default: 1000)
      * @returns Array of change log entries
      */
-    getChangesSince(sinceTimestamp: number, maxEntries?: number): Promise<ChangeLogEntry[]>;
+    getChangesSince(sinceTimestamp: number, maxEntries?: number): Promise<Change[]>;
     /**
      * Clean up old change log entries to prevent unlimited growth
      * @param olderThanTimestamp Remove entries older than this timestamp
@@ -542,7 +558,7 @@ export declare class S3CompatibleStorage extends BaseStorage {
             metadata?: Record<string, any>;
         };
     }): Promise<{
-        items: HNSWNoun[];
+        items: HNSWNounWithMetadata[];
         totalCount?: number;
         hasMore: boolean;
         nextCursor?: string;
@@ -609,5 +625,136 @@ export declare class S3CompatibleStorage extends BaseStorage {
         entryPointId: string | null;
         maxLevel: number;
     } | null>;
+    /**
+     * Set S3 lifecycle policy for automatic tier transitions and deletions (v4.0.0)
+     * Automates cost optimization by moving old data to cheaper storage classes
+     *
+     * S3 Storage Classes:
+     * - Standard: $0.023/GB/month - Frequent access
+     * - Standard-IA: $0.0125/GB/month - Infrequent access (46% cheaper)
+     * - Glacier Instant: $0.004/GB/month - Archive with instant retrieval (83% cheaper)
+     * - Glacier Flexible: $0.0036/GB/month - Archive with 1-5 min retrieval (84% cheaper)
+     * - Glacier Deep Archive: $0.00099/GB/month - Long-term archive (96% cheaper!)
+     *
+     * @param options - Lifecycle policy configuration
+     * @returns Promise that resolves when policy is set
+     *
+     * @example
+     * // Auto-archive old vectors for 96% cost savings
+     * await storage.setLifecyclePolicy({
+     *   rules: [
+     *     {
+     *       id: 'archive-old-vectors',
+     *       prefix: 'entities/nouns/vectors/',
+     *       status: 'Enabled',
+     *       transitions: [
+     *         { days: 30, storageClass: 'STANDARD_IA' },
+     *         { days: 90, storageClass: 'GLACIER' },
+     *         { days: 365, storageClass: 'DEEP_ARCHIVE' }
+     *       ],
+     *       expiration: { days: 730 }
+     *     }
+     *   ]
+     * })
+     */
+    setLifecyclePolicy(options: {
+        rules: Array<{
+            id: string;
+            prefix: string;
+            status: 'Enabled' | 'Disabled';
+            transitions?: Array<{
+                days: number;
+                storageClass: 'STANDARD_IA' | 'ONEZONE_IA' | 'INTELLIGENT_TIERING' | 'GLACIER' | 'DEEP_ARCHIVE' | 'GLACIER_IR';
+            }>;
+            expiration?: {
+                days: number;
+            };
+        }>;
+    }): Promise<void>;
+    /**
+     * Get the current S3 lifecycle policy
+     *
+     * @returns Promise that resolves to the current policy or null if not set
+     *
+     * @example
+     * const policy = await storage.getLifecyclePolicy()
+     * if (policy) {
+     *   console.log(`Found ${policy.rules.length} lifecycle rules`)
+     * }
+     */
+    getLifecyclePolicy(): Promise<{
+        rules: Array<{
+            id: string;
+            prefix: string;
+            status: string;
+            transitions?: Array<{
+                days: number;
+                storageClass: string;
+            }>;
+            expiration?: {
+                days: number;
+            };
+        }>;
+    } | null>;
+    /**
+     * Remove the S3 lifecycle policy
+     * All automatic tier transitions and deletions will stop
+     *
+     * @returns Promise that resolves when policy is removed
+     *
+     * @example
+     * await storage.removeLifecyclePolicy()
+     * console.log('Lifecycle policy removed - auto-archival disabled')
+     */
+    removeLifecyclePolicy(): Promise<void>;
+    /**
+     * Enable S3 Intelligent-Tiering for automatic cost optimization (v4.0.0)
+     * Automatically moves objects between access tiers based on usage patterns
+     *
+     * Intelligent-Tiering automatically saves up to 95% on storage costs:
+     * - Frequent Access: $0.023/GB (same as Standard)
+     * - Infrequent Access: $0.0125/GB (after 30 days no access)
+     * - Archive Instant Access: $0.004/GB (after 90 days no access)
+     * - Archive Access: $0.0036/GB (after 180 days no access, optional)
+     * - Deep Archive Access: $0.00099/GB (after 180 days no access, optional)
+     *
+     * No retrieval fees, no operational overhead, automatic optimization!
+     *
+     * @param prefix - Object prefix to apply Intelligent-Tiering (e.g., 'entities/nouns/vectors/')
+     * @param configId - Configuration ID (default: 'brainy-intelligent-tiering')
+     * @returns Promise that resolves when configuration is set
+     *
+     * @example
+     * // Enable Intelligent-Tiering for all vectors
+     * await storage.enableIntelligentTiering('entities/')
+     */
+    enableIntelligentTiering(prefix?: string, configId?: string): Promise<void>;
+    /**
+     * Get S3 Intelligent-Tiering configurations
+     *
+     * @returns Promise that resolves to array of configurations
+     *
+     * @example
+     * const configs = await storage.getIntelligentTieringConfigs()
+     * for (const config of configs) {
+     *   console.log(`Config: ${config.id}, Status: ${config.status}`)
+     * }
+     */
+    getIntelligentTieringConfigs(): Promise<Array<{
+        id: string;
+        status: string;
+        prefix?: string;
+    }>>;
+    /**
+     * Disable S3 Intelligent-Tiering
+     *
+     * @param configId - Configuration ID to remove (default: 'brainy-intelligent-tiering')
+     * @returns Promise that resolves when configuration is removed
+     *
+     * @example
+     * await storage.disableIntelligentTiering()
+     * console.log('Intelligent-Tiering disabled')
+     */
+    disableIntelligentTiering(configId?: string): Promise<void>;
 }
 export {};