# Google Chat PHP Tools Suite

A comprehensive suite of PHP tools for managing Google Chat spaces through the Google Chat API, featuring a flagship media browser application with professional design and advanced functionality.

## 🌟 Key Features

### 📱 Media Browser (Flagship Application)
- **Professional corporate web interface** for browsing Google Chat media
- **Full-resolution image support** (up to 4K: 3024×4032 pixels)  
- **Advanced caching system** (24h spaces, 1h media)
- **Server-side download proxy** to bypass CORS restrictions
- **Multi-tier user resolution** with Directory API integration
- **Professional responsive design** with glassmorphism effects
- **Query string support** for direct linking to spaces and images

### 🛠 Space Management Tools
- **spaceManager.php**: Full-featured web interface for space management
- **createSingleSpace.php**: Comprehensive space creation with members and content
- **createOnboardingSpaces.php**: Automated client onboarding space creation
- **imageRelay.php**: HTTP POST image upload handler

### 🔐 Authentication & Security
- **Domain-Wide Delegation** using service account authentication
- **Secure API access** with proper scope management
- **Protected file exclusion** via comprehensive gitignore

## 🚀 Quick Start

### Prerequisites
- PHP 8.0+
- Composer
- Google Cloud Project with Chat API enabled
- Service account with Domain-Wide Delegation

### Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/YOUR_USERNAME/google-chat-php-tools.git
   cd google-chat-php-tools
   ```

2. **Install dependencies**
   ```bash
   composer install
   ```

3. **Configure authentication**
   - Place your service account key file as `chat-space-tool-key.json`
   - Update `IMPERSONATED_USER_EMAIL` in scripts as needed

4. **Set up Domain-Wide Delegation**
   - Enable Domain-Wide Delegation for your service account
   - Authorize required scopes in Google Workspace Admin Console

### Usage

**Media Browser**
```bash
# Web interface
https://your-domain.com/path/to/mediaBrowser.php

# Direct space access
https://your-domain.com/path/to/mediaBrowser.php?space=spaces/SPACE_ID
```

**Space Management**
```bash
# Create single space
php createSingleSpace.php

# Create onboarding spaces
php createOnboardingSpaces.php client="ClientName" location="LocationName"
```

## 📚 Documentation

- **[CLAUDE.md](CLAUDE.md)**: Comprehensive developer documentation
- **[DIRECTORY_API_STATUS.md](DIRECTORY_API_STATUS.md)**: Directory API configuration guide
- **[PROTECTED_FILES.md](PROTECTED_FILES.md)**: File modification guidelines

## 🔧 Technical Details

### Dependencies
- `google/apps-chat`: ^0.11 (Google Chat API)
- `google/auth`: ^1.47 (Authentication)
- `google/apiclient`: ^2.15 (Directory API)

### Architecture
```
Client Browser → PHP Server → Google Chat API
     ↑               ↓
   Downloads    Authenticated
   via proxy     image fetch
```

### Key Technical Solutions

1. **CORS Bypass**: Server-side download proxy for secure image access
2. **Resolution Enhancement**: Google FIFE system integration for 4K images
3. **User Resolution**: Multi-tier ID-to-name resolution system
4. **Professional UI**: Corporate design with responsive layout

## 🐛 Troubleshooting

### Common Issues

**Authentication Errors**
- Verify Domain-Wide Delegation is enabled
- Check service account scopes in Google Workspace Admin
- Ensure impersonated user has proper permissions

**Image Loading Issues**
- Check CORS configuration
- Verify server-side proxy functionality
- Test with different image formats

**User Resolution Problems**
- Add Directory API scope for full name resolution
- Use fallback mapping for known users
- Check admin privileges for impersonated user

## 🤝 Contributing

This repository follows a specific file access policy:

- **mediaBrowser.php**: Can be modified directly for media browser features
- **Other PHP files**: Read-only (create new files instead of modifying)
- **Documentation**: Always keep CLAUDE.md updated with changes

## 📈 Recent Updates

### Latest Improvements (December 2025)
- Fixed critical API compatibility issues with Google Chat API v0.11
- Enhanced user resolution system with Directory API integration
- Improved error handling and debugging capabilities
- Professional UI redesign with corporate styling

## 📄 License

This project is for internal use and contains proprietary Google Chat integration tools.

## 🔗 Related Documentation

- [Google Chat API Documentation](https://developers.google.com/chat)
- [Domain-Wide Delegation Guide](https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority)
- [Google Workspace Admin Console](https://admin.google.com)

---

🤖 **Generated with [Claude Code](https://claude.ai/code)**