@opendatalabs/vana-sdk 0.1.0-alpha.7ee7635 → 0.1.0-alpha.80df35f

package/dist/storage/providers/google-drive.d.cts

@@ -1,156 +0,0 @@
-import { StorageProvider, StorageUploadResult, StorageListOptions, StorageFile, StorageProviderConfig } from '../../types/storage.cjs';
-
-/**
- * Google Drive Storage Provider for Vana SDK
- *
- * Implements storage interface for Google Drive using OAuth2 authentication.
- * Based on patterns from dlp-ui-template with NextAuth integration.
- */
-
-interface GoogleDriveConfig {
-    /** OAuth2 access token */
-    accessToken: string;
-    /** Optional refresh token for token renewal */
-    refreshToken?: string;
-    /** OAuth2 client ID */
-    clientId?: string;
-    /** OAuth2 client secret */
-    clientSecret?: string;
-    /** Parent folder ID to upload files to */
-    folderId?: string;
-}
-/**
- * Google Drive Storage Provider with folder management capabilities
- *
- * @remarks
- * Implements storage interface for Google Drive using OAuth2 authentication.
- * Provides file upload/download operations and advanced folder management
- * including search, creation, and nested folder structures. Requires the
- * `https://www.googleapis.com/auth/drive.file` OAuth scope for full functionality.
- *
- * @category Storage
- *
- * @example
- * ```typescript
- * const googleDriveStorage = new GoogleDriveStorage({
- *   accessToken: "your-oauth-access-token",
- *   refreshToken: "your-oauth-refresh-token",
- *   clientId: "your-oauth-client-id",
- *   clientSecret: "your-oauth-client-secret",
- * });
- *
- * // Create folder structure and upload file
- * const folderId = await googleDriveStorage.findOrCreateFolder("screenshots");
- * const result = await googleDriveStorage.upload(fileBlob, "image.png");
- * ```
- */
-declare class GoogleDriveStorage implements StorageProvider {
-    private config;
-    private readonly baseUrl;
-    private readonly uploadUrl;
-    constructor(config: GoogleDriveConfig);
-    upload(file: Blob, filename?: string): Promise<StorageUploadResult>;
-    download(url: string): Promise<Blob>;
-    list(options?: StorageListOptions): Promise<StorageFile[]>;
-    delete(url: string): Promise<boolean>;
-    getConfig(): StorageProviderConfig;
-    /**
-     * Make a Google Drive file publicly readable
-     *
-     * @param fileId - Google Drive file ID
-     */
-    private makeFilePublic;
-    /**
-     * Extract file ID from various Google Drive URL formats
-     *
-     * @param url - Google Drive URL
-     * @returns File ID or null if not found
-     */
-    private extractFileId;
-    /**
-     * Searches for an existing folder by name within a specified parent folder
-     *
-     * @remarks
-     * This method queries the Google Drive API to find a folder with the exact name
-     * within the specified parent directory. Only searches for folders (not files)
-     * and excludes trashed items.
-     *
-     * @param name - The exact name of the folder to search for
-     * @param parentId - The ID of the parent folder to search within (defaults to 'root')
-     * @returns Promise that resolves to the folder ID if found, or `null` if not found
-     * @throws {StorageError} When the Google Drive API request fails
-     *
-     * @example
-     * ```typescript
-     * // Search for a folder in the root directory
-     * const folderId = await googleDriveStorage.findFolder("screenshots");
-     * if (folderId) {
-     *   console.log("Found folder:", folderId);
-     * } else {
-     *   console.log("Folder not found");
-     * }
-     *
-     * // Search for a subfolder within another folder
-     * const subFolderId = await googleDriveStorage.findFolder("roasts", parentFolderId);
-     * ```
-     */
-    findFolder(name: string, parentId?: string): Promise<string | null>;
-    /**
-     * Creates a new folder within a specified parent folder
-     *
-     * @remarks
-     * This method creates a new folder using the Google Drive API. The folder will be
-     * created with the specified name as a child of the parent folder. Requires the
-     * `https://www.googleapis.com/auth/drive.file` OAuth scope.
-     *
-     * @param name - The name for the new folder
-     * @param parentId - The ID of the parent folder where the new folder will be created (defaults to 'root')
-     * @returns Promise that resolves to the ID of the newly created folder
-     * @throws {StorageError} When the Google Drive API request fails or folder creation is denied
-     *
-     * @example
-     * ```typescript
-     * // Create a folder in the root directory
-     * const folderId = await googleDriveStorage.createFolder("my-documents");
-     * console.log("Created folder:", folderId);
-     *
-     * // Create a subfolder within another folder
-     * const subFolderId = await googleDriveStorage.createFolder("reports", parentFolderId);
-     * ```
-     */
-    createFolder(name: string, parentId?: string): Promise<string>;
-    /**
-     * Finds an existing folder by name, or creates it if it doesn't exist
-     *
-     * @remarks
-     * This is a convenience method that combines `findFolder` and `createFolder`.
-     * It first searches for an existing folder with the specified name. If found,
-     * it returns the existing folder's ID. If not found, it creates a new folder
-     * and returns the new folder's ID.
-     *
-     * @param name - The name of the folder to find or create
-     * @param parentId - The ID of the parent folder to search within or create the folder in (defaults to 'root')
-     * @returns Promise that resolves to the folder ID (either existing or newly created)
-     * @throws {StorageError} When the Google Drive API request fails
-     *
-     * @example
-     * ```typescript
-     * // Ensure a folder exists, creating it if necessary
-     * const folderId = await googleDriveStorage.findOrCreateFolder("screenshots");
-     * console.log("Folder ID:", folderId); // Will be same ID if folder already existed
-     *
-     * // Create nested folder structure
-     * const parentId = await googleDriveStorage.findOrCreateFolder("projects");
-     * const childId = await googleDriveStorage.findOrCreateFolder("vana-app", parentId);
-     * ```
-     */
-    findOrCreateFolder(name: string, parentId?: string): Promise<string>;
-    /**
-     * Refresh the access token using refresh token
-     *
-     * @returns Promise with new access token
-     */
-    refreshAccessToken(): Promise<string>;
-}
-
-export { type GoogleDriveConfig, GoogleDriveStorage };

package/dist/storage/providers/ipfs.d.cts

@@ -1,163 +0,0 @@
-import { StorageProvider, StorageUploadResult, StorageListOptions, StorageFile, StorageProviderConfig } from '../../types/storage.cjs';
-
-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);
- * ```
- */
-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;
-}
-
-export { type IpfsConfig, IpfsStorage };

package/dist/storage/providers/pinata.d.cts

@@ -1,173 +0,0 @@
-import { StorageProvider, StorageUploadResult, StorageListOptions, StorageFile, StorageProviderConfig } from '../../types/storage.cjs';
-
-interface PinataConfig {
-    /** Pinata JWT token for authentication */
-    jwt: string;
-    /** Optional custom gateway URL (defaults to https://gateway.pinata.cloud) */
-    gatewayUrl?: string;
-}
-interface PinataListQuery {
-    /** Maximum number of results to return */
-    limit?: number;
-    /** Offset for pagination */
-    offset?: number;
-    /** Filter by name pattern */
-    namePattern?: string;
-}
-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;
-}
-/**
- * Provides managed IPFS storage with full-featured API via Pinata
- *
- * @remarks
- * This provider uses Pinata's enhanced IPFS service, which extends standard IPFS
- * with additional features like file listing, deletion (unpinning), and rich metadata.
- * It's the "it just works" solution for developers who want full CRUD operations
- * on IPFS without managing infrastructure.
- *
- * @category Storage
- *
- * @example
- * ```typescript
- * const pinataStorage = new PinataStorage({
- *   jwt: "your-pinata-jwt-token"
- * });
- *
- * // Upload with metadata
- * const cid = await pinataStorage.upload(fileBlob, {
- *   name: "user-avatar.png",
- *   metadata: { userId: "123", category: "avatar" }
- * });
- *
- * // List files with query
- * const files = await pinataStorage.list({ limit: 10 });
- *
- * // Delete file
- * await pinataStorage.delete(cid);
- * ```
- */
-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;
-}
-
-export { type PinataConfig, type PinataFile, type PinataListQuery, PinataStorage };

package/dist/types/blockchain.d.cts

@@ -1,52 +0,0 @@
-import { Hash, Address } from 'viem';
-
-/**
- * Core blockchain types for the Vana SDK
- */
-
-/**
- * Represents a transaction that has been submitted to the blockchain
- * This is what contract calls return before confirmation
- */
-interface TransactionRequest {
-    /** Transaction hash */
-    hash: Hash;
-    /** Account that initiated the transaction */
-    from: Address;
-    /** Contract that was called */
-    contractName: string;
-    /** Function that was called */
-    functionName: string;
-    /** Function arguments (for debugging/logging) */
-    args?: readonly unknown[];
-}
-/**
- * Options for waiting for transaction confirmation
- */
-interface TransactionWaitOptions {
-    /** Number of confirmations to wait for (default: 1) */
-    confirmations?: number;
-    /** Timeout in milliseconds (default: 30000) */
-    timeout?: number;
-    /** Polling interval in milliseconds (default: 4000) */
-    pollingInterval?: number;
-}
-/**
- * Base result for all confirmed transactions
- */
-interface TransactionResult {
-    /** Transaction hash */
-    transactionHash: Hash;
-    /** Block number where transaction was included */
-    blockNumber: bigint;
-    /** Gas used by the transaction */
-    gasUsed: bigint;
-    /** Account that initiated the transaction */
-    from: Address;
-    /** Contract that was called */
-    contractName: string;
-    /** Function that was called */
-    functionName: string;
-}
-
-export type { TransactionRequest, TransactionResult, TransactionWaitOptions };

package/dist/types/chains.d.cts

@@ -1,34 +0,0 @@
-import { Chain } from 'viem';
-
-/**
- * Supported Vana chain IDs
- */
-type VanaChainId = 14800 | 1480;
-/**
- * Supported Vana chains
- */
-type VanaChain = Chain & {
-    id: VanaChainId;
-};
-/**
- * Chain configuration mapping
- */
-type ChainConfig = {
-    [K in VanaChainId]: VanaChain;
-};
-/**
- * Type guard to check if a chain ID is supported
- *
- * @param chainId - The chain ID to validate
- * @returns True if the chain ID is a supported Vana chain ID
- */
-declare function isVanaChainId(chainId: number): chainId is VanaChainId;
-/**
- * Type guard to check if a chain is a Vana chain
- *
- * @param chain - The chain object to validate
- * @returns True if the chain is a supported Vana chain
- */
-declare function isVanaChain(chain: Chain): chain is VanaChain;
-
-export { type ChainConfig, type VanaChain, type VanaChainId, isVanaChain, isVanaChainId };