@opendatalabs/vana-sdk
Version:
A TypeScript library for interacting with Vana Network smart contracts.
153 lines (152 loc) • 6.22 kB
TypeScript
/**
* 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.
*/
import { type StorageProvider, type StorageUploadResult, type StorageFile, type StorageListOptions, type StorageProviderConfig } from "../index";
export 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");
* ```
*/
export 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>;
}