@opendatalabs/vana-sdk/dist/storage/providers/ipfs.d.ts

A TypeScript library for interacting with Vana Network smart contracts.

import { type StorageProvider, type StorageUploadResult, type StorageFile, type StorageListOptions, type StorageProviderConfig } from "../index";
export interface IpfsConfig {
    /** IPFS API endpoint for uploads */
    apiEndpoint: string;
    /** Gateway URL for downloads (optional, defaults to public gateway) */
    gatewayUrl?: string;
    /** Additional headers for API requests */
    headers?: Record<string, string>;
}
/**
 * Connects to any standard IPFS node or service provider
 *
 * @remarks
 * This provider implements the standard IPFS HTTP API (`/api/v0/add`) and works
 * with any IPFS-compatible service. It provides the essential IPFS operations
 * (upload/download) while maintaining the immutable, content-addressed nature
 * of IPFS. Use static factory methods for common providers like Infura or local nodes.
 *
 * @category Storage
 *
 * @example
 * ```typescript
 * // Use with Infura (recommended for production)
 * const ipfsStorage = IpfsStorage.forInfura({
 *   projectId: "your-project-id",
 *   projectSecret: "your-project-secret"
 * });
 *
 * // Use with local IPFS node
 * const localStorage = IpfsStorage.forLocalNode();
 *
 * // Upload file and get CID
 * const result = await ipfsStorage.upload(fileBlob, "document.pdf");
 * console.log("Uploaded to IPFS:", result.url);
 * ```
 */
export declare class IpfsStorage implements StorageProvider {
    private config;
    private readonly gatewayUrl;
    private readonly hasAuth;
    constructor(config: IpfsConfig);
    /**
     * Creates an IPFS storage instance configured for Infura
     *
     * @remarks
     * Infura provides reliable, scalable IPFS infrastructure with global availability.
     * This factory method automatically configures the correct endpoints and authentication
     * for Infura's IPFS service.
     *
     * @param credentials - Infura project credentials
     * @param credentials.projectId - Your Infura project ID
     * @param credentials.projectSecret - Your Infura project secret
     * @returns Configured IpfsStorage instance for Infura
     *
     * @example
     * ```typescript
     * const ipfsStorage = IpfsStorage.forInfura({
     *   projectId: "2FVGj8UJP5v8ZcnX9K5L7M8c",
     *   projectSecret: "a7f2c1e5b8d9f3a6e4c8b2d7f9e1a4c3"
     * });
     *
     * const result = await ipfsStorage.upload(fileBlob);
     * ```
     */
    static forInfura(credentials: {
        projectId: string;
        projectSecret: string;
    }): IpfsStorage;
    /**
     * Creates an IPFS storage instance configured for a local IPFS node
     *
     * @remarks
     * This factory method configures the storage provider to connect to a local IPFS node,
     * typically running on your development machine or server. Assumes standard ports
     * (5001 for API, 8080 for gateway) unless otherwise specified.
     *
     * @param options - Local node configuration options
     * @param options.url - Base URL of the local IPFS node (defaults to http://localhost:5001)
     * @returns Configured IpfsStorage instance for local node
     *
     * @example
     * ```typescript
     * // Use default localhost configuration
     * const localStorage = IpfsStorage.forLocalNode();
     *
     * // Use custom local node URL
     * const customStorage = IpfsStorage.forLocalNode({
     *   url: "http://192.168.1.100:5001"
     * });
     *
     * const result = await localStorage.upload(fileBlob, "local-file.txt");
     * ```
     */
    static forLocalNode(options?: {
        url?: string;
    }): IpfsStorage;
    /**
     * Uploads a file to IPFS and returns the content identifier (CID)
     *
     * @remarks
     * This method uploads the file to the configured IPFS endpoint using the standard
     * `/api/v0/add` API. The file is content-addressed, meaning the same file will
     * always produce the same CID regardless of when or where it's uploaded.
     *
     * @param file - The file to upload to IPFS
     * @param filename - Optional filename (for metadata purposes only)
     * @returns Promise that resolves to StorageUploadResult with IPFS gateway URL
     * @throws {StorageError} When the upload fails or no CID is returned
     *
     * @example
     * ```typescript
     * const result = await ipfsStorage.upload(fileBlob, "report.pdf");
     * console.log("File uploaded to IPFS:", result.url);
     * // Example URL: "https://gateway.pinata.cloud/ipfs/QmTzQ1JRkWErjk39mryYw2WVrgBMe2B36gRq8GCL8qCACj"
     * ```
     */
    upload(file: Blob, filename?: string): Promise<StorageUploadResult>;
    /**
     * Downloads a file from IPFS using its content identifier (CID)
     *
     * @remarks
     * This method retrieves the file from IPFS using the configured gateway.
     * It accepts various formats including raw CIDs, ipfs:// URLs, and gateway URLs.
     * The file is downloaded from the globally distributed IPFS network.
     *
     * @param cid - The IPFS content identifier, ipfs:// URL, or gateway URL
     * @returns Promise that resolves to the downloaded file content
     * @throws {StorageError} When the download fails or CID format is invalid
     *
     * @example
     * ```typescript
     * // Download using raw CID
     * const file = await ipfsStorage.download("QmTzQ1JRkWErjk39mryYw2WVrgBMe2B36gRq8GCL8qCACj");
     *
     * // Download using ipfs:// URL
     * const file2 = await ipfsStorage.download("ipfs://QmTzQ1JRkWErjk39mryYw2WVrgBMe2B36gRq8GCL8qCACj");
     *
     * // Create download link
     * const url = URL.createObjectURL(file);
     * ```
     */
    download(cid: string): Promise<Blob>;
    list(_options?: StorageListOptions): Promise<StorageFile[]>;
    delete(_url: string): Promise<boolean>;
    getConfig(): StorageProviderConfig;
    /**
     * Build download URL from CID or existing URL
     *
     * @param cid - IPFS CID or URL
     * @returns Gateway URL for download
     */
    private buildDownloadUrl;
    /**
     * Basic CID validation
     *
     * @param cid - Content identifier to validate
     * @returns True if CID appears valid
     */
    private isValidCID;
}