@opendatalabs/vana-sdk 0.1.0-alpha.d6bebb0 → 0.1.0-alpha.d7fc764

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

@@ -0,0 +1,156 @@
+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/google-drive.d.ts

@@ -0,0 +1,156 @@
+import { StorageProvider, StorageUploadResult, StorageListOptions, StorageFile, StorageProviderConfig } from '../../types/storage.js';
+
+/**
+ * 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 };