@ductape/sdk 0.0.4-v51 → 0.0.4-v53

package/dist/cache/cache.manager.js

@@ -0,0 +1,265 @@
+"use strict";
+/**
+ * CacheManager - Shared caching utility for all executor services
+ *
+ * Provides a two-tier caching strategy:
+ * - Redis (local/fast): Primary cache layer for reads
+ * - Remote (persistent): Backing store synced on writes/deletes/cache misses
+ *
+ * Used by: StorageService, DatabaseService, GraphService, VectorService,
+ * QuotaService, FallbackService, AgentsService, etc.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheManager = void 0;
+const crypto_js_1 = __importDefault(require("crypto-js"));
+const processorApi_service_1 = require("../api/services/processorApi.service");
+const processor_utils_1 = require("../processor/utils/processor.utils");
+/**
+ * CacheManager provides shared caching functionality for all executor services
+ *
+ * @example
+ * ```ts
+ * const cacheManager = new CacheManager({
+ *   workspace_id: 'ws-123',
+ *   public_key: 'pk-123',
+ *   user_id: 'user-123',
+ *   token: 'token',
+ *   env_type: 'prd',
+ *   redis_client: redisClient,
+ * });
+ *
+ * // Check cache before operation
+ * const cached = await cacheManager.fetch<MyData>({
+ *   cache_tag: 'my-cache',
+ *   product_tag: 'my-product',
+ *   component_tag: 'my-storage',
+ *   component_type: 'storage',
+ *   input: { fileName: 'test.pdf' },
+ *   privateKey: 'private-key',
+ *   expiry: 3600000, // 1 hour
+ * });
+ *
+ * if (cached.hit) {
+ *   return cached.data;
+ * }
+ *
+ * // Execute operation...
+ * const result = await doOperation();
+ *
+ * // Store in cache
+ * await cacheManager.store({
+ *   cache_tag: 'my-cache',
+ *   product_tag: 'my-product',
+ *   component_tag: 'my-storage',
+ *   component_type: 'storage',
+ *   input: { fileName: 'test.pdf' },
+ *   privateKey: 'private-key',
+ *   expiry: 3600000,
+ * }, result);
+ * ```
+ */
+class CacheManager {
+    constructor(config) {
+        this.config = config;
+        this.redisClient = config.redis_client || null;
+        this.processorApiService = new processorApi_service_1.ProcessorApiService(config.env_type);
+    }
+    /**
+     * Get user access credentials for API calls
+     */
+    getUserAccess() {
+        return {
+            workspace_id: this.config.workspace_id,
+            public_key: this.config.public_key,
+            user_id: this.config.user_id,
+            token: this.config.token,
+        };
+    }
+    /**
+     * Generate cache key from cache tag and input
+     */
+    generateKey(cache_tag, input) {
+        const inputStr = typeof input === 'string' ? input : JSON.stringify(input);
+        return `${cache_tag}-${crypto_js_1.default.SHA512(inputStr).toString()}`;
+    }
+    /**
+     * Check if caching is available (Redis client connected)
+     */
+    isAvailable() {
+        return this.redisClient !== null;
+    }
+    /**
+     * Fetch data from cache (Redis first, then remote on miss)
+     *
+     * @returns Cache result with hit status, data, and source
+     */
+    async fetch(options) {
+        const { cache_tag, input, privateKey, expiry } = options;
+        const key = this.generateKey(cache_tag, input);
+        // If no Redis client, skip caching entirely
+        if (!this.redisClient) {
+            return { hit: false, key, source: 'miss' };
+        }
+        try {
+            // Step 1: Check Redis cache first
+            const redisRecord = await this.redisClient.hGetAll(key);
+            if (redisRecord && redisRecord.data && redisRecord.lastUpdated) {
+                // Check expiry
+                const lastUpdated = Number(redisRecord.lastUpdated);
+                if (expiry) {
+                    const expiryTime = lastUpdated + expiry;
+                    if (Date.now() > expiryTime) {
+                        // Expired - delete from Redis and continue to remote
+                        await this.redisClient.del(key);
+                    }
+                    else {
+                        // Valid cache hit from Redis
+                        const decryptedData = (0, processor_utils_1.decrypt)(redisRecord.data, privateKey);
+                        return {
+                            hit: true,
+                            data: JSON.parse(decryptedData),
+                            key,
+                            source: 'redis',
+                        };
+                    }
+                }
+                else {
+                    // No expiry - valid cache hit
+                    const decryptedData = (0, processor_utils_1.decrypt)(redisRecord.data, privateKey);
+                    return {
+                        hit: true,
+                        data: JSON.parse(decryptedData),
+                        key,
+                        source: 'redis',
+                    };
+                }
+            }
+            // Step 2: Cache miss in Redis - check remote cache
+            const remoteRecord = await this.processorApiService.fetchRemoteCacheByKey(key, this.getUserAccess());
+            if (remoteRecord) {
+                // Found in remote cache - decrypt and return
+                const decryptedData = (0, processor_utils_1.decrypt)(remoteRecord.value, privateKey);
+                // Populate Redis cache for next time
+                await this.redisClient.hSet(key, 'data', remoteRecord.value);
+                await this.redisClient.hSet(key, 'lastUpdated', Date.now().toString());
+                return {
+                    hit: true,
+                    data: JSON.parse(decryptedData),
+                    key,
+                    source: 'remote',
+                };
+            }
+            // Step 3: Cache miss in both Redis and remote
+            return { hit: false, key, source: 'miss' };
+        }
+        catch (error) {
+            // On error, return miss and let the operation proceed
+            console.error('CacheManager fetch error:', error);
+            return { hit: false, key, source: 'miss' };
+        }
+    }
+    /**
+     * Store data in cache (both Redis and remote)
+     */
+    async store(options, data) {
+        const { cache_tag, product_tag, component_tag, component_type, input, privateKey, expiry, } = options;
+        const key = this.generateKey(cache_tag, input);
+        const timestamp = Date.now();
+        // Serialize and encrypt data
+        const serializedData = JSON.stringify(data);
+        const encryptedData = (0, processor_utils_1.encrypt)(serializedData, privateKey);
+        // Calculate expiry date if provided
+        let expiresAt;
+        if (expiry) {
+            expiresAt = new Date(timestamp + expiry);
+        }
+        try {
+            // Step 1: Write to Redis cache (if available)
+            if (this.redisClient) {
+                await this.redisClient.hSet(key, 'data', encryptedData);
+                await this.redisClient.hSet(key, 'lastUpdated', timestamp.toString());
+            }
+            // Step 2: Write to remote cache (persistent store)
+            const remotePayload = {
+                key,
+                value: encryptedData,
+                cache_tag,
+                product_tag,
+                component_tag,
+                component_type,
+                expiry: expiresAt,
+            };
+            await this.processorApiService.addToRemoteCache(remotePayload, this.getUserAccess());
+        }
+        catch (error) {
+            // Log error but don't throw - cache failure shouldn't break the operation
+            console.error('CacheManager store error:', error);
+        }
+    }
+    /**
+     * Invalidate/delete data from cache (both Redis and remote)
+     */
+    async invalidate(cache_tag, input) {
+        const key = this.generateKey(cache_tag, input);
+        try {
+            // Step 1: Delete from Redis cache (if available)
+            if (this.redisClient) {
+                await this.redisClient.del(key);
+            }
+            // Step 2: Delete from remote cache
+            await this.processorApiService.deleteCacheValue({ key }, this.getUserAccess());
+        }
+        catch (error) {
+            // Log error but don't throw
+            console.error('CacheManager invalidate error:', error);
+        }
+    }
+    /**
+     * Helper method to wrap an async operation with caching
+     *
+     * @example
+     * ```ts
+     * const result = await cacheManager.withCache(
+     *   {
+     *     cache_tag: 'my-cache',
+     *     product_tag: 'my-product',
+     *     component_tag: 'my-storage',
+     *     component_type: 'storage',
+     *     input: { fileName: 'test.pdf' },
+     *     privateKey: 'private-key',
+     *     expiry: 3600000,
+     *   },
+     *   async () => {
+     *     // Execute the actual operation
+     *     return await downloadFile('test.pdf');
+     *   }
+     * );
+     * ```
+     */
+    async withCache(options, operation) {
+        // Try to fetch from cache
+        const cached = await this.fetch(options);
+        if (cached.hit && cached.data !== undefined) {
+            return {
+                data: cached.data,
+                cached: true,
+                source: cached.source,
+            };
+        }
+        // Cache miss - execute the operation
+        const data = await operation();
+        // Store result in cache
+        await this.store(options, data);
+        return {
+            data,
+            cached: false,
+            source: 'fresh',
+        };
+    }
+}
+exports.CacheManager = CacheManager;
+exports.default = CacheManager;
+//# sourceMappingURL=cache.manager.js.map

package/dist/cache/cache.manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.manager.js","sourceRoot":"","sources":["../../src/cache/cache.manager.ts"],"names":[],"mappings":"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"}

package/dist/cache/cache.service.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Ductape Cache Service
+ *
+ * Provides SDK methods for managing cache values including
+ * fetching, setting, and deleting cache entries.
+ *
+ * Supports a two-tier caching strategy:
+ * - Redis (local/fast): Primary cache layer for reads
+ * - Remote (persistent): Backing store synced on writes/deletes/cache misses
+ */
+import { ICacheServiceConfig, ICacheValue, IFetchCacheValuesOptions, IFetchCacheValuesResult, IFetchCacheDashboardOptions, ICacheDashboardMetrics, IClearCacheValueOptions, IClearCacheValuesOptions, IClearCacheValuesResult, ISetCacheValueOptions, IGetCacheValueOptions } from './types';
+/**
+ * Custom error class for cache operations
+ */
+export declare class CacheError extends Error {
+    code: string;
+    originalError?: unknown;
+    constructor(message: string, code: string, originalError?: unknown);
+}
+/**
+ * CacheService provides methods for managing remote cache values
+ *
+ * @example
+ * ```ts
+ * import { CacheService } from '@ductape/sdk';
+ *
+ * const cache = new CacheService({
+ *   workspace_id: 'your-workspace-id',
+ *   public_key: 'your-public-key',
+ *   user_id: 'your-user-id',
+ *   token: 'your-token',
+ *   env_type: 'prd',
+ * });
+ *
+ * // Fetch cache values
+ * const values = await cache.fetchValues({
+ *   product: 'my-product',
+ *   cache: 'user-cache',
+ *   page: 1,
+ *   limit: 20,
+ * });
+ *
+ * // Get a specific value
+ * const value = await cache.get({ key: 'user:123' });
+ *
+ * // Set a value
+ * await cache.set({
+ *   product: 'my-product',
+ *   cache: 'user-cache',
+ *   key: 'user:123',
+ *   value: JSON.stringify({ name: 'John' }),
+ * });
+ *
+ * // Clear a value
+ * await cache.clear({ key: 'user:123' });
+ * ```
+ */
+export declare class CacheService {
+    private productBuilderService;
+    private processorApiService;
+    private envType;
+    private workspaceId;
+    private publicKey;
+    private userId;
+    private token;
+    private productId;
+    /** Redis client for local caching */
+    private redisClient;
+    /** Whether Redis is connected */
+    private redisConnected;
+    constructor(config: ICacheServiceConfig);
+    /**
+     * Connect to Redis for local caching
+     * This enables the two-tier caching strategy where Redis is checked first
+     *
+     * @example
+     * ```ts
+     * await cache.connectRedis('redis://localhost:6379');
+     * ```
+     */
+    connectRedis(url: string): Promise<void>;
+    /**
+     * Disconnect from Redis
+     */
+    disconnectRedis(): Promise<void>;
+    /**
+     * Check if Redis is connected
+     */
+    isRedisConnected(): boolean;
+    /**
+     * Update service configuration (used after authentication)
+     */
+    updateConfig(config: Partial<ICacheServiceConfig>): void;
+    /**
+     * Get user access credentials for API calls
+     */
+    private getUserAccess;
+    /**
+     * Fetch paginated cache values
+     *
+     * @example
+     * ```ts
+     * const values = await cache.fetchValues({
+     *   product: 'my-product',
+     *   cache: 'user-cache',
+     *   env: 'production',
+     *   page: 1,
+     *   limit: 20,
+     * });
+     * ```
+     */
+    fetchValues(options: IFetchCacheValuesOptions): Promise<IFetchCacheValuesResult>;
+    /**
+     * Fetch cache dashboard metrics
+     *
+     * @example
+     * ```ts
+     * const dashboard = await cache.fetchDashboard({
+     *   product: 'my-product',
+     *   cache: 'user-cache',
+     *   env: 'production',
+     * });
+     * ```
+     */
+    fetchDashboard(options: IFetchCacheDashboardOptions): Promise<ICacheDashboardMetrics>;
+    /**
+     * Get a cache value by key
+     *
+     * Uses two-tier caching strategy:
+     * 1. Check Redis cache first (fast, local)
+     * 2. On cache miss, fetch from remote and populate Redis
+     *
+     * @example
+     * ```ts
+     * const value = await cache.get({ key: 'user:123' });
+     * if (value) {
+     *   console.log('Cached data:', JSON.parse(value.value));
+     * }
+     * ```
+     */
+    get(options: IGetCacheValueOptions): Promise<ICacheValue | null>;
+    /**
+     * Set a cache value
+     *
+     * Writes to both Redis (local) and remote (persistent) cache
+     *
+     * @example
+     * ```ts
+     * await cache.set({
+     *   product: 'my-product',
+     *   cache: 'user-cache',
+     *   key: 'user:123',
+     *   value: JSON.stringify({ name: 'John', email: 'john@example.com' }),
+     *   expiry: new Date(Date.now() + 3600000), // 1 hour from now
+     * });
+     * ```
+     */
+    set(options: ISetCacheValueOptions): Promise<boolean>;
+    /**
+     * Clear a cache value by key
+     *
+     * Deletes from both Redis (local) and remote (persistent) cache
+     *
+     * @example
+     * ```ts
+     * const cleared = await cache.clear({ key: 'user:123' });
+     * console.log('Cleared:', cleared);
+     * ```
+     */
+    clear(options: IClearCacheValueOptions): Promise<boolean>;
+    /**
+     * Clear all cache values for a product/cache combination
+     *
+     * @example
+     * ```ts
+     * const result = await cache.clearAll({
+     *   product: 'my-product',
+     *   cache: 'user-cache',
+     *   env: 'production',
+     * });
+     * console.log('Cleared:', result.cleared, 'values');
+     * ```
+     */
+    clearAll(options: IClearCacheValuesOptions): Promise<IClearCacheValuesResult>;
+}
+export default CacheService;