@varity-labs/sdk 2.0.0-alpha.1

package/dist/modules/storage/adapters/AdapterFactory.js

@@ -0,0 +1,209 @@
+/**
+ * Varity SDK - Storage Adapter Factory
+ *
+ * Factory pattern for creating storage adapters based on backend configuration.
+ * Supports Filecoin/IPFS, multi-tier, and future S3/GCS backends.
+ */
+import { FilecoinAdapter } from './FilecoinAdapter';
+import { MultiTierAdapter } from './MultiTierAdapter';
+/**
+ * Factory for creating storage adapters
+ *
+ * Provides a unified interface for creating different storage backend adapters
+ * based on configuration. Handles validation and adapter initialization.
+ *
+ * @example
+ * ```typescript
+ * // Create Filecoin adapter
+ * const adapter = AdapterFactory.createAdapter(sdk, {
+ *   backend: StorageBackend.FILECOIN_IPFS
+ * })
+ *
+ * // Create multi-tier adapter
+ * const multiTierAdapter = AdapterFactory.createAdapter(sdk, {
+ *   backend: StorageBackend.MULTI_TIER,
+ *   multiTierConfig: {
+ *     hotTier: { backend: StorageBackend.FILECOIN_IPFS, replication: 3 },
+ *     coldTier: { backend: StorageBackend.FILECOIN_IPFS, replication: 2 },
+ *     autoTiering: { enabled: true, policy: TieringPolicy.ACCESS_BASED, checkInterval: 24 }
+ *   }
+ * })
+ * ```
+ */
+export class AdapterFactory {
+    /**
+     * Create a storage adapter based on backend type and configuration
+     *
+     * @param sdk - Varity SDK instance
+     * @param config - Adapter configuration
+     * @returns Storage adapter instance
+     * @throws {Error} If backend is unsupported or configuration is invalid
+     */
+    static createAdapter(sdk, config) {
+        switch (config.backend) {
+            case 'filecoin-ipfs':
+                return new FilecoinAdapter(sdk);
+            case 'multi-tier':
+                if (!config.multiTierConfig) {
+                    throw new Error('MultiTierStorageConfig required for MULTI_TIER backend');
+                }
+                return new MultiTierAdapter(sdk, config.multiTierConfig);
+            case 's3-compatible':
+                throw new Error('S3-compatible storage backend not yet implemented. Coming soon!');
+            case 'gcs-compatible':
+                throw new Error('GCS-compatible storage backend not yet implemented. Coming soon!');
+            case 'celestia':
+                throw new Error('Celestia storage backend not yet implemented. Coming soon!');
+            default:
+                throw new Error(`Unsupported storage backend: ${config.backend}`);
+        }
+    }
+    /**
+     * Create adapter from SDK configuration
+     *
+     * Convenience method that extracts storage configuration from SDK config
+     * and creates the appropriate adapter.
+     *
+     * @param sdk - Varity SDK instance
+     * @returns Storage adapter instance
+     */
+    static createFromSDKConfig(sdk) {
+        const sdkConfig = sdk.getConfig();
+        // Determine backend from config
+        const backend = sdkConfig.storageBackend || 'filecoin-ipfs';
+        const config = {
+            backend,
+            multiTierConfig: sdkConfig.multiTierConfig,
+            s3Config: sdkConfig.s3Config,
+            gcsConfig: sdkConfig.gcsConfig
+        };
+        return this.createAdapter(sdk, config);
+    }
+    /**
+     * Validate adapter configuration
+     *
+     * @param config - Adapter configuration
+     * @returns True if valid
+     * @throws {Error} If configuration is invalid
+     */
+    static validateConfig(config) {
+        if (!config.backend) {
+            throw new Error('Storage backend must be specified');
+        }
+        // Validate multi-tier config
+        if (config.backend === 'multi-tier') {
+            if (!config.multiTierConfig) {
+                throw new Error('MultiTierStorageConfig required for MULTI_TIER backend');
+            }
+            const mtConfig = config.multiTierConfig;
+            if (!mtConfig.hotTier || !mtConfig.coldTier) {
+                throw new Error('Both hotTier and coldTier must be configured for multi-tier storage');
+            }
+            if (!mtConfig.autoTiering) {
+                throw new Error('AutoTiering configuration required for multi-tier storage');
+            }
+        }
+        // Validate S3 config
+        if (config.backend === 's3-compatible') {
+            if (!config.s3Config) {
+                throw new Error('S3CompatibleConfig required for S3_COMPATIBLE backend');
+            }
+            const s3Config = config.s3Config;
+            if (!s3Config.endpoint || !s3Config.accessKeyId || !s3Config.secretAccessKey) {
+                throw new Error('S3 endpoint, accessKeyId, and secretAccessKey are required');
+            }
+        }
+        // Validate GCS config
+        if (config.backend === 'gcs-compatible') {
+            if (!config.gcsConfig) {
+                throw new Error('GCSCompatibleConfig required for GCS_COMPATIBLE backend');
+            }
+            const gcsConfig = config.gcsConfig;
+            if (!gcsConfig.projectId || !gcsConfig.bucket) {
+                throw new Error('GCS projectId and bucket are required');
+            }
+        }
+        return true;
+    }
+    /**
+     * Get supported backends
+     *
+     * @returns Array of supported storage backends
+     */
+    static getSupportedBackends() {
+        return [
+            'filecoin-ipfs',
+            'multi-tier'
+            // S3 and GCS coming soon
+        ];
+    }
+    /**
+     * Check if a backend is supported
+     *
+     * @param backend - Backend to check
+     * @returns True if supported
+     */
+    static isBackendSupported(backend) {
+        return this.getSupportedBackends().includes(backend);
+    }
+    /**
+     * Get backend capabilities
+     *
+     * @param backend - Storage backend
+     * @returns Capabilities object
+     */
+    static getBackendCapabilities(backend) {
+        switch (backend) {
+            case 'filecoin-ipfs':
+                return {
+                    supportsEncryption: true,
+                    supportsVersioning: true,
+                    supportsMetadata: true,
+                    supportsCopy: false,
+                    supportsMove: false,
+                    supportsPresignedUrls: false,
+                    costTier: 'low'
+                };
+            case 'multi-tier':
+                return {
+                    supportsEncryption: true,
+                    supportsVersioning: true,
+                    supportsMetadata: true,
+                    supportsCopy: true,
+                    supportsMove: true,
+                    supportsPresignedUrls: false,
+                    costTier: 'low'
+                };
+            case 's3-compatible':
+                return {
+                    supportsEncryption: true,
+                    supportsVersioning: true,
+                    supportsMetadata: true,
+                    supportsCopy: true,
+                    supportsMove: true,
+                    supportsPresignedUrls: true,
+                    costTier: 'medium'
+                };
+            case 'gcs-compatible':
+                return {
+                    supportsEncryption: true,
+                    supportsVersioning: true,
+                    supportsMetadata: true,
+                    supportsCopy: true,
+                    supportsMove: true,
+                    supportsPresignedUrls: true,
+                    costTier: 'medium'
+                };
+            default:
+                return {
+                    supportsEncryption: false,
+                    supportsVersioning: false,
+                    supportsMetadata: false,
+                    supportsCopy: false,
+                    supportsMove: false,
+                    supportsPresignedUrls: false,
+                    costTier: 'high'
+                };
+        }
+    }
+}

package/dist/modules/storage/adapters/FilecoinAdapter.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Varity SDK - Filecoin/IPFS Storage Adapter
+ *
+ * Implements IStorageAdapter for Filecoin/IPFS storage via Pinata API.
+ * Extracted from StorageModule to enable multi-backend support.
+ */
+import type { VaritySDK } from '../../../core/VaritySDK';
+import { type UploadOptions, type StorageResult, type StorageItem, type ListOptions, type StorageMetadata } from '@varity-labs/types';
+import { BaseStorageAdapter } from './IStorageAdapter';
+/**
+ * Filecoin/IPFS adapter implementation using Pinata API
+ *
+ * This adapter handles all Filecoin/IPFS operations including:
+ * - Pinning content to IPFS
+ * - Retrieving content via IPFS gateways
+ * - Managing pins (list, delete)
+ * - Gateway URL generation
+ *
+ * @example
+ * ```typescript
+ * const adapter = new FilecoinAdapter(sdk)
+ * const result = await adapter.upload(Buffer.from('Hello World'), {
+ *   layer: StorageLayer.CUSTOMER_DATA,
+ *   tier: StorageTier.HOT,
+ *   pin: true
+ * })
+ * console.log('CID:', result.identifier)
+ * ```
+ */
+export declare class FilecoinAdapter extends BaseStorageAdapter {
+    private sdk;
+    constructor(sdk: VaritySDK);
+    /**
+     * Upload data to Filecoin/IPFS via backend API
+     *
+     * @param data - Data to upload (Buffer, string, Blob)
+     * @param options - Upload options including layer, tier, metadata
+     * @returns Storage result with CID and gateway URL
+     */
+    upload(data: Buffer | string | Blob, options: UploadOptions): Promise<StorageResult>;
+    /**
+     * Download data from Filecoin/IPFS
+     *
+     * @param identifier - CID (Content Identifier)
+     * @returns Downloaded data as Buffer
+     */
+    download(identifier: string): Promise<Buffer>;
+    /**
+     * Delete (unpin) data from Filecoin/IPFS
+     *
+     * @param identifier - CID to unpin
+     */
+    delete(identifier: string): Promise<void>;
+    /**
+     * Check if data exists on Filecoin/IPFS
+     *
+     * @param identifier - CID to check
+     * @returns True if exists, false otherwise
+     */
+    exists(identifier: string): Promise<boolean>;
+    /**
+     * List pinned objects
+     *
+     * @param options - List filtering options
+     * @returns Array of storage items
+     */
+    list(options?: ListOptions): Promise<StorageItem[]>;
+    /**
+     * Get metadata for a pinned object
+     *
+     * @param identifier - CID to get metadata for
+     * @returns Storage metadata
+     */
+    getMetadata(identifier: string): Promise<StorageMetadata>;
+    /**
+     * Get access URL for a CID
+     *
+     * @param identifier - CID
+     * @param expiresIn - Not used for IPFS (always public)
+     * @returns Gateway URL
+     */
+    getAccessUrl(identifier: string, expiresIn?: number): Promise<string>;
+    /**
+     * Health check for Filecoin/IPFS backend
+     *
+     * @returns Health status with latency
+     */
+    healthCheck(): Promise<{
+        healthy: boolean;
+        latencyMs: number;
+        error?: string;
+    }>;
+}
+//# sourceMappingURL=FilecoinAdapter.d.ts.map

package/dist/modules/storage/adapters/FilecoinAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilecoinAdapter.d.ts","sourceRoot":"","sources":["../../../../src/modules/storage/adapters/FilecoinAdapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,eAAgB,SAAQ,kBAAkB;IACrD,OAAO,CAAC,GAAG,CAAW;gBAEV,GAAG,EAAE,SAAS;IAK1B;;;;;;OAMG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAqD1F;;;;;OAKG;IACG,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BnD;;;;OAIG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB/C;;;;;OAKG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASlD;;;;;OAKG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAsCzD;;;;;OAKG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAiC/D;;;;;;OAMG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAM3E;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAsBtF"}

package/dist/modules/storage/adapters/FilecoinAdapter.js

@@ -0,0 +1,263 @@
+/**
+ * Varity SDK - Filecoin/IPFS Storage Adapter
+ *
+ * Implements IStorageAdapter for Filecoin/IPFS storage via Pinata API.
+ * Extracted from StorageModule to enable multi-backend support.
+ */
+import { StorageBackend, StorageTier } from '@varity-labs/types';
+import { BaseStorageAdapter } from './IStorageAdapter';
+/**
+ * Filecoin/IPFS adapter implementation using Pinata API
+ *
+ * This adapter handles all Filecoin/IPFS operations including:
+ * - Pinning content to IPFS
+ * - Retrieving content via IPFS gateways
+ * - Managing pins (list, delete)
+ * - Gateway URL generation
+ *
+ * @example
+ * ```typescript
+ * const adapter = new FilecoinAdapter(sdk)
+ * const result = await adapter.upload(Buffer.from('Hello World'), {
+ *   layer: StorageLayer.CUSTOMER_DATA,
+ *   tier: StorageTier.HOT,
+ *   pin: true
+ * })
+ * console.log('CID:', result.identifier)
+ * ```
+ */
+export class FilecoinAdapter extends BaseStorageAdapter {
+    constructor(sdk) {
+        super(StorageBackend.FILECOIN_IPFS);
+        this.sdk = sdk;
+    }
+    /**
+     * Upload data to Filecoin/IPFS via backend API
+     *
+     * @param data - Data to upload (Buffer, string, Blob)
+     * @param options - Upload options including layer, tier, metadata
+     * @returns Storage result with CID and gateway URL
+     */
+    async upload(data, options) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        // Convert data to appropriate format
+        let uploadData;
+        if (data instanceof Buffer) {
+            uploadData = data.toString('base64');
+        }
+        else if (data instanceof Blob) {
+            const buffer = await data.arrayBuffer();
+            uploadData = Buffer.from(buffer).toString('base64');
+        }
+        else {
+            uploadData = data;
+        }
+        // Call backend API to pin to IPFS
+        const response = await fetch(`${apiEndpoint}/api/v1/storage/pin`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            },
+            body: JSON.stringify({
+                data: uploadData,
+                metadata: {
+                    layer: options.layer,
+                    tier: options.tier || StorageTier.HOT,
+                    timestamp: Date.now(),
+                    contentType: options.contentType || 'application/octet-stream',
+                    ...options.metadata
+                }
+            })
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Upload failed: ${response.statusText} - ${errorText}`);
+        }
+        const result = await response.json();
+        return {
+            identifier: result.cid,
+            gatewayUrl: result.gatewayUrl || `https://gateway.pinata.cloud/ipfs/${result.cid}`,
+            size: result.size || 0,
+            hash: result.hash || result.cid,
+            timestamp: Date.now(),
+            backend: StorageBackend.FILECOIN_IPFS,
+            tier: options.tier || StorageTier.HOT,
+            layer: options.layer
+        };
+    }
+    /**
+     * Download data from Filecoin/IPFS
+     *
+     * @param identifier - CID (Content Identifier)
+     * @returns Downloaded data as Buffer
+     */
+    async download(identifier) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const response = await fetch(`${apiEndpoint}/api/v1/storage/retrieve/${identifier}`, {
+            method: 'GET',
+            headers: {
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            }
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Download failed: ${response.statusText} - ${errorText}`);
+        }
+        // Check content type to determine if it's binary or text
+        const contentType = response.headers.get('content-type') || '';
+        if (contentType.includes('application/json') || contentType.includes('text/')) {
+            const text = await response.text();
+            return Buffer.from(text);
+        }
+        else {
+            const arrayBuffer = await response.arrayBuffer();
+            return Buffer.from(arrayBuffer);
+        }
+    }
+    /**
+     * Delete (unpin) data from Filecoin/IPFS
+     *
+     * @param identifier - CID to unpin
+     */
+    async delete(identifier) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const response = await fetch(`${apiEndpoint}/api/v1/storage/unpin/${identifier}`, {
+            method: 'DELETE',
+            headers: {
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            }
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Delete failed: ${response.statusText} - ${errorText}`);
+        }
+    }
+    /**
+     * Check if data exists on Filecoin/IPFS
+     *
+     * @param identifier - CID to check
+     * @returns True if exists, false otherwise
+     */
+    async exists(identifier) {
+        try {
+            await this.getMetadata(identifier);
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    /**
+     * List pinned objects
+     *
+     * @param options - List filtering options
+     * @returns Array of storage items
+     */
+    async list(options) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const queryParams = new URLSearchParams();
+        if (options?.prefix)
+            queryParams.append('prefix', options.prefix);
+        if (options?.maxResults)
+            queryParams.append('limit', options.maxResults.toString());
+        if (options?.continuationToken)
+            queryParams.append('pageToken', options.continuationToken);
+        if (options?.startAfter)
+            queryParams.append('startAfter', options.startAfter);
+        const response = await fetch(`${apiEndpoint}/api/v1/storage/list?${queryParams}`, {
+            headers: {
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            }
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`List failed: ${response.statusText} - ${errorText}`);
+        }
+        const data = await response.json();
+        return (data.items || []).map((item) => ({
+            identifier: item.cid,
+            key: item.cid,
+            size: item.size || 0,
+            lastModified: new Date(item.timestamp || Date.now()),
+            etag: item.hash || item.cid,
+            metadata: item.metadata,
+            tier: item.metadata?.tier,
+            encrypted: item.metadata?.encrypted || false
+        }));
+    }
+    /**
+     * Get metadata for a pinned object
+     *
+     * @param identifier - CID to get metadata for
+     * @returns Storage metadata
+     */
+    async getMetadata(identifier) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const response = await fetch(`${apiEndpoint}/api/v1/storage/metadata/${identifier}`, {
+            headers: {
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            }
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Get metadata failed: ${response.statusText} - ${errorText}`);
+        }
+        const data = await response.json();
+        return {
+            identifier: identifier,
+            size: data.size || 0,
+            contentType: data.contentType || 'application/octet-stream',
+            lastModified: new Date(data.timestamp || Date.now()),
+            etag: data.hash || identifier,
+            customMetadata: data.metadata || {},
+            tier: data.metadata?.tier,
+            layer: data.metadata?.layer,
+            encrypted: data.metadata?.encrypted || false
+        };
+    }
+    /**
+     * Get access URL for a CID
+     *
+     * @param identifier - CID
+     * @param expiresIn - Not used for IPFS (always public)
+     * @returns Gateway URL
+     */
+    async getAccessUrl(identifier, expiresIn) {
+        // For IPFS, always return public gateway URL
+        // Note: expiresIn is ignored since IPFS gateways are public
+        return `https://gateway.pinata.cloud/ipfs/${identifier}`;
+    }
+    /**
+     * Health check for Filecoin/IPFS backend
+     *
+     * @returns Health status with latency
+     */
+    async healthCheck() {
+        const startTime = Date.now();
+        try {
+            const apiEndpoint = this.sdk.getAPIEndpoint();
+            const response = await fetch(`${apiEndpoint}/health`, {
+                method: 'GET'
+            });
+            const latencyMs = Date.now() - startTime;
+            return {
+                healthy: response.ok,
+                latencyMs,
+                error: response.ok ? undefined : `HTTP ${response.status}: ${response.statusText}`
+            };
+        }
+        catch (error) {
+            return {
+                healthy: false,
+                latencyMs: Date.now() - startTime,
+                error: error instanceof Error ? error.message : 'Unknown error'
+            };
+        }
+    }
+}