@opendatalabs/vana-sdk
Version:
A TypeScript library for interacting with Vana Network smart contracts.
184 lines (183 loc) • 6.62 kB
TypeScript
/**
* Provides user-defined storage operations through callback functions.
*
* @remarks
* This module implements a flexible storage provider that delegates all
* operations to user-provided callbacks. It enables custom storage
* integrations without modifying the SDK, supporting any backend including
* HTTP APIs, WebSocket servers, cloud storage services, or local filesystems.
*
* @category Storage
* @module storage/providers/callback-storage
*/
import type { StorageCallbacks } from "../../types/config";
import { type StorageProvider, type StorageUploadResult, type StorageFile, type StorageListOptions, type StorageProviderConfig } from "../../types/storage";
/**
* Delegates storage operations to user-provided callback functions.
*
* @remarks
* This provider enables custom storage integrations by delegating all
* operations to user-defined callbacks. It follows the same flexible
* pattern as relayer callbacks, allowing implementations via HTTP,
* WebSocket, direct cloud APIs, local filesystem, or any other backend.
*
* The provider validates callback results and wraps errors in consistent
* `StorageError` types for uniform error handling across the SDK.
*
* @example
* ```typescript
* // HTTP-based implementation
* const httpCallbacks: StorageCallbacks = {
* async upload(blob, filename) {
* const formData = new FormData();
* formData.append('file', blob, filename);
* const response = await fetch('/api/storage/upload', {
* method: 'POST',
* body: formData
* });
* const data = await response.json();
* return {
* url: data.url,
* size: blob.size,
* contentType: blob.type
* };
* },
* async download(identifier) {
* const response = await fetch(`/api/storage/download/${identifier}`);
* return response.blob();
* }
* };
*
* const storage = new CallbackStorage(httpCallbacks);
*
* // Direct S3 implementation
* const s3Callbacks: StorageCallbacks = {
* async upload(blob, filename) {
* const url = await getPresignedUploadUrl(filename);
* await fetch(url, { method: 'PUT', body: blob });
* return {
* url: `s3://my-bucket/${filename}`,
* size: blob.size,
* contentType: blob.type
* };
* },
* async download(identifier) {
* const url = await getPresignedDownloadUrl(identifier);
* const response = await fetch(url);
* return response.blob();
* }
* };
* ```
*
* @category Storage
*/
export declare class CallbackStorage implements StorageProvider {
private readonly callbacks;
/**
* Creates a new callback-based storage provider.
*
* @param callbacks - User-provided storage operation callbacks.
* Must include at minimum `upload` and `download` functions.
* @throws {Error} If required callbacks are missing
*/
constructor(callbacks: StorageCallbacks);
/**
* Uploads a file using the user-provided callback.
*
* @param file - The blob to upload.
* Can be any Blob-compatible object including File.
* @param filename - Optional filename for the upload.
* If not provided, callback may generate a name.
* @returns Upload result containing URL and metadata
*
* @throws {StorageError} With code 'INVALID_UPLOAD_RESULT' if callback returns invalid data
* @throws {StorageError} With code 'UPLOAD_ERROR' if upload fails
*
* @example
* ```typescript
* const file = new File(['content'], 'data.json');
* const result = await storage.upload(file);
* console.log('Uploaded to:', result.url);
* ```
*/
upload(file: Blob, filename?: string): Promise<StorageUploadResult>;
/**
* Downloads a file using the user-provided callback.
*
* @param url - The URL or identifier to download.
* If `extractIdentifier` callback is provided, it will be used to extract the identifier.
* @returns The downloaded file as a Blob
*
* @throws {StorageError} With code 'INVALID_DOWNLOAD_RESULT' if callback returns non-Blob
* @throws {StorageError} With code 'DOWNLOAD_ERROR' if download fails
*
* @example
* ```typescript
* const blob = await storage.download('https://storage.example.com/file123');
* const text = await blob.text();
* ```
*/
download(url: string): Promise<Blob>;
/**
* Lists files using the user-provided callback.
*
* @param options - Optional list options.
* @param options.namePattern - Pattern to filter files by name.
* Implementation depends on callback.
* @param options.limit - Maximum number of files to return.
* Implementation depends on callback.
* @returns Array of storage file metadata
*
* @throws {StorageError} With code 'NOT_SUPPORTED' if list callback not provided
* @throws {StorageError} With code 'LIST_ERROR' if listing fails
*
* @remarks
* This operation is optional and only available if a `list` callback
* is provided during construction.
*
* @example
* ```typescript
* const files = await storage.list({ namePattern: '*.json' });
* files.forEach(file => console.log(file.name, file.size));
* ```
*/
list(options?: StorageListOptions): Promise<StorageFile[]>;
/**
* Deletes a file using the user-provided callback.
*
* @param url - The URL or identifier to delete.
* If `extractIdentifier` callback is provided, it will be used to extract the identifier.
* @returns True if deletion succeeded, false otherwise
*
* @throws {StorageError} With code 'NOT_SUPPORTED' if delete callback not provided
* @throws {StorageError} With code 'DELETE_ERROR' if deletion fails
*
* @remarks
* This operation is optional and only available if a `delete` callback
* is provided during construction.
*
* @example
* ```typescript
* const deleted = await storage.delete('https://storage.example.com/file123');
* if (deleted) {
* console.log('File deleted successfully');
* }
* ```
*/
delete(url: string): Promise<boolean>;
/**
* Returns the provider's configuration and capabilities.
*
* @returns Configuration object indicating supported features
*
* @example
* ```typescript
* const config = storage.getConfig();
* if (config.features.list) {
* // List operation is supported
* const files = await storage.list();
* }
* ```
*/
getConfig(): StorageProviderConfig;
}