@opendatalabs/vana-sdk/dist/storage/providers/pinata.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 PinataConfig {
    /** Pinata JWT token for authentication */
    jwt: string;
    /** Optional custom gateway URL (defaults to https://gateway.pinata.cloud) */
    gatewayUrl?: string;
}
export interface PinataListQuery {
    /** Maximum number of results to return */
    limit?: number;
    /** Offset for pagination */
    offset?: number;
    /** Filter by name pattern */
    namePattern?: string;
}
export interface PinataFile {
    /** Pin identifier */
    id: string;
    /** File name */
    name: string;
    /** IPFS CID */
    cid: string;
    /** File size in bytes */
    size: number;
    /** Creation timestamp */
    createdAt: Date;
    /** Optional metadata */
    metadata?: object;
}
/**
 * Manages IPFS storage through Pinata's enhanced API.
 *
 * @remarks
 * Extends standard IPFS with additional features like file listing,
 * deletion (unpinning), and rich metadata. Production-ready managed
 * service with guaranteed availability. The "it just works" solution
 * for developers who want full CRUD operations on IPFS without
 * managing infrastructure.
 *
 * @category Storage
 * @example
 * ```typescript
 * const storage = new PinataStorage({
 *   jwt: "your-jwt-token"
 * });
 *
 * // Upload with metadata
 * const result = await storage.upload(blob, "file.json");
 * console.log(`Pinned at: ${result.url}`);
 *
 * // List and manage files
 * const files = await storage.list({ limit: 10 });
 *
 * // Delete file
 * await pinataStorage.delete(cid);
 * ```
 */
export declare class PinataStorage implements StorageProvider {
    private config;
    private readonly apiUrl;
    private readonly gatewayUrl;
    constructor(config: PinataConfig);
    /**
     * Uploads a file to IPFS via Pinata and returns the CID
     *
     * @remarks
     * This method uploads the file to Pinata's IPFS service with enhanced metadata support.
     * The file is pinned to ensure availability and can include custom metadata for
     * organization and querying. The metadata is stored alongside the file for later retrieval.
     *
     * @param file - The file to upload to IPFS
     * @param filename - Optional custom filename
     * @returns Promise that resolves to the IPFS CID (content identifier)
     * @throws {StorageError} When the upload fails or no CID is returned
     *
     * @example
     * ```typescript
     * const cid = await pinataStorage.upload(fileBlob, {
     *   name: "user-document.pdf",
     *   metadata: {
     *     userId: "user-123",
     *     category: "documents",
     *     uploadDate: new Date().toISOString()
     *   }
     * });
     * console.log("File pinned to IPFS:", cid);
     * ```
     */
    upload(file: Blob, filename?: string): Promise<StorageUploadResult>;
    download(cid: string): Promise<Blob>;
    /**
     * Lists files uploaded to Pinata with optional filtering
     *
     * @remarks
     * This method retrieves a list of files that have been uploaded to Pinata,
     * filtered to only include files uploaded by the Vana SDK. You can further
     * filter results by name pattern, limit results, or paginate through them.
     *
     * @param options - Optional query parameters for filtering and pagination
     * @param options.limit - Maximum number of results to return (default: 10)
     * @param options.offset - Number of results to skip for pagination
     * @param options.namePattern - Filter files by name pattern
     * @returns Promise that resolves to an array of PinataFile objects
     * @throws {StorageError} When the list operation fails
     *
     * @example
     * ```typescript
     * // List all files
     * const allFiles = await pinataStorage.list();
     *
     * // List with pagination and filtering
     * const filteredFiles = await pinataStorage.list({
     *   limit: 20,
     *   offset: 10,
     *   namePattern: "document"
     * });
     *
     * filteredFiles.forEach(file => {
     *   console.log(`${file.name} (${file.size} bytes): ${file.cid}`);
     * });
     * ```
     */
    list(options?: StorageListOptions): Promise<StorageFile[]>;
    /**
     * Deletes a file from Pinata by unpinning it from IPFS
     *
     * @remarks
     * This method removes the file from your Pinata account by unpinning it,
     * which means it will no longer be guaranteed to be available on the IPFS network.
     * Note that if the file is pinned elsewhere or cached by other nodes, it may still
     * be accessible for some time.
     *
     * @param url - The IPFS URL or content identifier of the file to delete
     * @returns Promise that resolves when the file is successfully unpinned
     * @throws {StorageError} When the deletion fails or CID format is invalid
     *
     * @example
     * ```typescript
     * // Delete a file by CID
     * await pinataStorage.delete("QmTzQ1JRkWErjk39mryYw2WVrgBMe2B36gRq8GCL8qCACj");
     * console.log("File unpinned from Pinata");
     *
     * // Delete after listing
     * const files = await pinataStorage.list();
     * for (const file of files) {
     *   if (file.name.includes("temp")) {
     *     await pinataStorage.delete(file.cid);
     *   }
     * }
     * ```
     */
    delete(url: string): Promise<boolean>;
    getConfig(): StorageProviderConfig;
    /**
     * Extract CID from URL or return as-is
     *
     * @param url - URL or CID string
     * @returns CID string
     */
    private extractCidFromUrl;
    /**
     * Basic CID validation
     *
     * @param cid - Content identifier to validate
     * @returns True if CID appears valid
     */
    private isValidCID;
}