adding google drive service readme

src/ctp_slack_bot/services/GOOGLE_DRIVE_README.md

@@ -0,0 +1,228 @@
+# Google Drive Access Module
+
+This Python module provides a simplified way to interact with Google Drive, focusing on easy access to files in nested folders using path-like syntax. It handles various Google file formats and provides comprehensive metadata for files and folders.
+
+## Features
+
+- **Path-based folder access**: Access files using simple paths like `folder1/folder2/folder3`
+- **Efficient caching**: Folder IDs are cached to improve performance
+- **Comprehensive metadata**: Get detailed information about files and folders
+- **Read various file types**:
+  - Text files
+  - Google Docs
+  - VTT files
+- **Robust folder finding**: Works with exact and partial name matching
+- **Simple API**: Designed for ease of use with minimal code
+
+## Setup Instructions
+
+### 1. Create a Google Cloud Project
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
+2. Click on the project dropdown at the top of the page and select "New Project"
+3. Enter a project name and click "Create"
+4. Once created, make sure your new project is selected in the dropdown
+
+### 2. Enable the Google Drive API
+
+1. In the Google Cloud Console, navigate to "APIs & Services" > "Library" in the left sidebar
+2. Search for "Google Drive API" in the search bar
+3. Click on "Google Drive API" in the results
+4. Click the "Enable" button
+
+### 3. Create OAuth Credentials
+
+1. In the Google Cloud Console, go to "APIs & Services" > "Credentials" in the left sidebar
+2. Click "Create Credentials" at the top and select "OAuth client ID"
+3. If prompted to configure the OAuth consent screen:
+   - Choose "External" user type (or "Internal" if you're in a Google Workspace organization)
+   - Fill in the required information (App name, User support email, Developer contact email)
+   - Click "Save and Continue"
+   - Add the following scopes:
+     - `.../auth/drive` (Full access to Google Drive)
+   - Click "Save and Continue" and complete the registration
+4. Return to the "Create OAuth client ID" screen
+5. Select "Desktop application" as the Application type
+6. Enter a name for your OAuth client (e.g., "Google Drive Access Desktop")
+7. Click "Create"
+8. Download the JSON file (this is your `client_secret.json`)
+
+### 4. Project Setup
+
+1. Setup a virtual environment and install dependencies:
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+2. Place your credentials:
+   - Create a `credentials` directory in your project root
+   - Move the downloaded OAuth client JSON file to the `credentials` directory
+   - Rename it to `client_secret.json`
+
+### 5. Authentication Process
+
+When you run the application for the first time:
+1. A browser window will open automatically
+2. You'll be asked to sign in to your Google account
+3. You'll see a consent screen asking for permission to access your Google Drive
+4. After granting permission, the browser will display a success message
+5. The application will save a token file (`token.pickle`) in the credentials directory for future use
+
+## Usage Guide
+
+The `EasyGoogleDrive` class provides several methods to interact with Google Drive. Here's how to use the core functionality:
+
+### Basic Usage
+
+```python
+from google_drive_access import EasyGoogleDrive
+
+# Initialize the Google Drive client
+drive = EasyGoogleDrive()
+
+# Example folder path - replace with your actual folder path
+folder_path = "Spring-2025-BAI"
+subfolder_path = "Spring-2025-BAI/transcripts"
+```
+
+### Listing Folders
+
+```python
+# List folders in a directory
+folders = drive.get_folders_in_folder(folder_path)
+
+# Access folder properties
+for folder in folders:
+    print(f"Folder: {folder['name']}")
+    print(f"  Created: {folder.get('createdTimeFormatted', 'Unknown')}")
+    print(f"  Modified: {folder.get('modifiedTimeFormatted', 'Unknown')}")
+```
+
+### Listing Files
+
+```python
+# List files in a directory
+files = drive.get_files_in_folder(subfolder_path)
+
+# Access file properties
+for file in files:
+    print(f"File: {file['name']}")
+    print(f"  Type: {file.get('fileType', 'Unknown')}")
+    print(f"  Created: {file.get('createdTimeFormatted', 'Unknown')}")
+    print(f"  Modified: {file.get('modifiedTimeFormatted', 'Unknown')}")
+    print(f"  Size: {file.get('sizeFormatted', 'Unknown')}")
+```
+
+### Getting a Specific File
+
+```python
+# Get a specific file with metadata
+file = drive.get_file("example.txt", subfolder_path, include_metadata=True)
+
+if file:
+    print(f"File: {file['name']}")
+    print(f"  Type: {file.get('fileType', 'Unknown')}")
+    print(f"  Created: {file.get('createdTimeFormatted', 'Unknown')}")
+    print(f"  Modified: {file.get('modifiedTimeFormatted', 'Unknown')}")
+    print(f"  Size: {file.get('sizeFormatted', 'Unknown')}")
+```
+
+### Getting All Items in a Folder
+
+```python
+# Get all items (files and folders) in a folder
+all_items = drive.get_all_files_in_folder(folder_path)
+
+# Access item properties
+for item in all_items:
+    item_type = "Folder" if item.get('mimeType') == drive.MIME_TYPES['folder'] else item.get('fileType', 'Unknown')
+    print(f"Item: {item['name']} ({item_type})")
+```
+
+### Checking if a File Exists
+
+```python
+# Check if a file exists
+exists = drive.file_exists("example.txt", subfolder_path)
+print(f"File exists: {exists}")
+```
+
+### Getting File Modified Time
+
+```python
+# Get file modified time
+modified_time = drive.get_file_modified_time("example.txt", subfolder_path)
+if modified_time:
+    print(f"Last modified: {modified_time}")
+```
+
+### Reading File Content
+
+```python
+# Get file with content
+file_with_content = drive.get_file("example.txt", subfolder_path, include_content=True)
+
+if file_with_content and 'file_content' in file_with_content:
+    content = file_with_content['file_content']
+    if content:
+        print(f"Content: {content[:100]}...")  # Print first 100 characters
+```
+
+## Complete Example
+
+For a complete example of how to use the `EasyGoogleDrive` class, see the `basic_usage.py` file included in this package. This file demonstrates all the core functionality with practical examples.
+
+## Key Concepts
+
+### Path-based Folder Access
+
+The module uses a simple path-like syntax to access folders:
+
+```python
+# Access a deeply nested folder
+folder_path = "folder1/folder2/folder3"
+files = drive.get_files_in_folder(folder_path)
+```
+
+This makes it much easier to work with nested folder structures compared to using folder IDs.
+
+### Metadata Fields
+
+The module provides comprehensive metadata for files and folders, including:
+
+- **Creation and modification dates**: Both as datetime objects and formatted strings
+- **File size**: Both in bytes and human-readable format (KB, MB, GB)
+- **File type**: Simplified type based on MIME type
+- **Owner information**: Names and email addresses of file owners
+- **Sharing status**: Whether the file is shared
+- **Web links**: Direct links to view the file in a browser
+
+## Error Handling
+
+The module includes comprehensive error handling:
+
+- **Authentication errors**: Clear messages when credentials are missing or invalid
+- **Folder not found**: Helpful messages when a folder in the path cannot be found
+- **File not found**: Attempts partial name matching before giving up
+- **Decoding errors**: Handles issues with file content encoding
+
+## Dependencies
+
+- **Required**:
+  - google-auth-oauthlib
+  - google-auth-httplib2
+  - google-api-python-client
+  - python-dateutil
+
+## Security Notes
+
+- Never commit your `client_secret.json` or token files to version control
+- Add `credentials/` to your `.gitignore` file
+- Keep your credentials secure and don't share them
+- For production applications, consider using service accounts with the minimum required permissions
+
+## Contributing
+
+Feel free to contribute to this project by submitting issues or pull requests.