# Cloud Storage Services - Usage Guide

This guide shows you how to use the cloud storage services (Google Drive) that you have configured.

## Required Configuration

Before using the services, make sure you have:

1. **Google Workspace Configuration** set up in the system
2. **Valid Service Account Key** with Drive API permissions
3. **Organization domain** configured correctly

## Available Services

### 1. CloudStorageService

The main service for handling files and documents:

```php
use App\Services\CloudServices\CloudStorageService;
use App\Services\CloudServices\CloudServiceFactory;
use Domain\CloudService\Models\CloudServiceConfiguration;

// Get configuration
$configuration = CloudServiceConfiguration::where('provider', CloudServiceProvider::GOOGLE)->first();

// Create service
$storageService = new CloudStorageService(
    new CloudServiceFactory(),
    $configuration
);
```

### 2. File Operations

#### Upload File
```php
// Upload file contents
$fileId = $storageService->uploadFile('documents/report.pdf', $fileContents);

// Upload from local file
$fileId = $storageService->uploadFileFromPath('/local/path/file.pdf', 'documents/file.pdf');

// Upload from UploadedFile (Laravel)
$fileId = $storageService->uploadFileFromUpload($request->file('file'), 'documents/file.pdf');
```

#### Download File
```php
$fileContents = $storageService->downloadFile('documents/report.pdf');
```

#### Delete File
```php
$success = $storageService->deleteFile('documents/report.pdf');
```

#### Get URL
```php
$fileUrl = $storageService->getFileUrl('documents/report.pdf');
```

### 3. Folder Operations

#### Create Folder
```php
$folderId = $storageService->createFolder('My Folder');
```

#### List Files
```php
$files = $storageService->listFiles('/'); // List files in root
$files = $storageService->listFiles('My Folder'); // List files in specific folder
```

### 4. Document Operations

#### Create Google Doc
```php
$documentId = $storageService->createDocument('My Document');
$documentId = $storageService->createDocument('My Document', $folderId); // In specific folder
```

#### Create Google Sheets
```php
$spreadsheetId = $storageService->createSpreadsheet('My Spreadsheet');
$spreadsheetId = $storageService->createSpreadsheet('My Spreadsheet', $folderId);
```

#### Get Edit URL
```php
$editUrl = $storageService->getDocumentEditUrl($documentId);
```

### 5. Share Files

```php
$permissions = [
    [
        'type' => 'user',
        'role' => 'writer',
        'email' => 'user@example.com'
    ],
    [
        'type' => 'anyone',
        'role' => 'reader'
    ]
];

$storageService->shareFile($fileId, $permissions);
```

## HTTP API

You can also use the services through HTTP endpoints:

### Upload File
```bash
POST /setup/cloud-storage/upload
Content-Type: multipart/form-data

file: [file]
path: documents/file.pdf
```

### Create Document
```bash
POST /setup/cloud-storage/document
Content-Type: application/json

{
    "name": "My Document",
    "folder_id": "optional_folder_id"
}
```

### Create Spreadsheet
```bash
POST /setup/cloud-storage/spreadsheet
Content-Type: application/json

{
    "name": "My Spreadsheet",
    "folder_id": "optional_folder_id"
}
```

### List Files
```bash
GET /setup/cloud-storage/files?path=/
```

### Create Folder
```bash
POST /setup/cloud-storage/folder
Content-Type: application/json

{
    "path": "My New Folder"
}
```

### Share File
```bash
POST /setup/cloud-storage/share
Content-Type: application/json

{
    "file_id": "file_id_here",
    "permissions": [
        {
            "type": "user",
            "role": "writer",
            "email": "user@example.com"
        }
    ]
}
```

## Practical Examples

### Example 1: Upload and Share Document
```php
// Upload document
$fileId = $storageService->uploadFile('documents/report.pdf', $pdfContents);

// Share with team
$permissions = [
    ['type' => 'user', 'role' => 'writer', 'email' => 'team@company.com'],
    ['type' => 'user', 'role' => 'reader', 'email' => 'client@company.com']
];

$storageService->shareFile($fileId, $permissions);

// Get shareable URL
$shareUrl = $storageService->getFileUrl('documents/report.pdf');
```

### Example 2: Create Document and Spreadsheet
```php
// Create project folder
$folderId = $storageService->createFolder('Project ABC');

// Create document in folder
$documentId = $storageService->createDocument('Specifications', $folderId);
$documentUrl = $storageService->getDocumentEditUrl($documentId);

// Create spreadsheet in folder
$spreadsheetId = $storageService->createSpreadsheet('Budget', $folderId);
$spreadsheetUrl = $storageService->getDocumentEditUrl($spreadsheetId);
```

### Example 3: List and Organize Files
```php
// List files in root
$rootFiles = $storageService->listFiles('/');

// Create folder structure
$projectsId = $storageService->createFolder('Projects');
$documentsId = $storageService->createFolder('Documents');

// List files in specific folder
$projectFiles = $storageService->listFiles('Projects');
```

## Error Handling

Services throw exceptions when errors occur:

```php
try {
    $fileId = $storageService->uploadFile('file.pdf', $contents);
} catch (Exception $e) {
    // Handle error
    Log::error('Error uploading file: ' . $e->getMessage());
}
```

## Permissions and Roles

### Permission Types
- `user`: Specific user by email
- `group`: Google Workspace group
- `domain`: All users in the domain
- `anyone`: Anyone with the link

### Available Roles
- `reader`: Read only
- `writer`: Read and write
- `commenter`: Read and comment
- `owner`: Owner (only for transferring ownership)

## Important Notes

1. **Size Limits**: Files have a default limit of 10MB
2. **Authentication**: The service uses the configured service account
3. **Domain**: Files are created in the configured organization domain
4. **Permissions**: Make sure the service account has the necessary permissions in Google Workspace

## Troubleshooting

### Error: "Configuration not found"
- Verify that you have an active Google Workspace configuration
- Make sure the provider is `google`

### Error: "Invalid credentials"
- Verify that the service account key is valid
- Confirm that the organization domain is correct

### Error: "File not found"
- Verify that the file path is correct
- Make sure the file exists in Google Drive

### Error: "Permission denied"
- Verify that the service account has permissions in Google Workspace
- Confirm that the necessary APIs are enabled