gsuite-sdk 0.1.0__py3-none-any.whl

gsuite_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,384 @@
+Metadata-Version: 2.4
+Name: gsuite-sdk
+Version: 0.1.0
+Summary: Unified Google Workspace SDK - Gmail, Calendar, Drive, Sheets
+Author-email: Pablo Alaniz <alanizpablo@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/PabloAlaniz/google-suite
+Project-URL: Repository, https://github.com/PabloAlaniz/google-suite
+Project-URL: Documentation, https://github.com/PabloAlaniz/google-suite#readme
+Keywords: google,workspace,gmail,calendar,drive,sheets,oauth,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-auth>=2.27.0
+Requires-Dist: google-auth-oauthlib>=1.2.0
+Requires-Dist: google-api-python-client>=2.114.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pydantic-settings>=2.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Provides-Extra: cloudrun
+Requires-Dist: google-cloud-secret-manager>=2.18.0; extra == "cloudrun"
+Provides-Extra: all
+Requires-Dist: fastapi>=0.109.0; extra == "all"
+Requires-Dist: uvicorn>=0.27.0; extra == "all"
+Requires-Dist: typer>=0.9.0; extra == "all"
+Requires-Dist: rich>=13.7.0; extra == "all"
+Dynamic: license-file
+
+# Google Suite
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Unified Python SDK for Google Workspace APIs with Clean Architecture.
+
+## Features
+
+- 🔐 **Unified Auth** - Single OAuth flow for all Google APIs
+- 📧 **Gmail** - Send, receive, search, labels, attachments
+- 📅 **Calendar** - Events, calendars, scheduling
+- 📁 **Drive** - Files, folders, sharing, upload/download
+- 📊 **Sheets** - Read, write, append, format, batch operations
+- 🚀 **REST API** - Single FastAPI gateway for all services
+- 💻 **CLI** - Unified command-line interface
+
+## Installation
+
+```bash
+pip install gsuite-sdk
+```
+
+Optional extras:
+```bash
+pip install gsuite-sdk[cloudrun]  # Google Cloud Secret Manager support
+pip install gsuite-sdk[all]       # All optional dependencies (FastAPI, CLI)
+```
+
+## Quick Start
+
+### Prerequisites
+
+You need OAuth credentials from Google Cloud Console. See [Getting Credentials](docs/GETTING_CREDENTIALS.md) for a step-by-step guide.
+
+### Authentication
+
+```python
+from gsuite_core import GoogleAuth
+
+# OAuth (interactive, opens browser)
+auth = GoogleAuth()
+auth.authenticate()
+
+# Or with service account
+auth = GoogleAuth.from_service_account("service-account.json")
+```
+
+### Gmail
+
+```python
+from gsuite_gmail import Gmail, query
+
+gmail = Gmail(auth)
+
+# Get unread messages with fluent API
+for message in gmail.get_unread():
+    print(f"{message.sender}: {message.subject}")
+    message.mark_as_read().archive()  # Fluent chaining!
+
+# Send email with signature
+gmail.send(
+    to=["recipient@example.com"],
+    subject="Hello",
+    body="World",
+    signature=True,  # Appends your Gmail signature
+)
+
+# Search with query builder (inspired by simplegmail)
+messages = gmail.search(
+    query.newer_than(days=7) & query.has_attachment() & query.from_("boss@company.com")
+)
+
+# Or use construct_query for dict-style
+messages = gmail.search(query.construct_query(
+    unread=True,
+    newer_than=(7, "day"),
+    labels=["Work"],
+))
+```
+
+### Drive
+
+```python
+from gsuite_drive import Drive
+
+drive = Drive(auth)
+
+# List files
+for file in drive.list_files():
+    print(f"{file.name} ({file.mime_type})")
+
+# Upload
+uploaded = drive.upload("document.pdf")
+print(f"Uploaded: {uploaded.web_view_link}")
+
+# Download
+file = drive.get("file_id")
+file.download("local_copy.pdf")
+
+# Create folder and upload into it
+folder = drive.create_folder("My Folder")
+drive.upload("file.txt", parent_id=folder.id)
+```
+
+### Calendar
+
+```python
+from gsuite_calendar import Calendar
+
+calendar = Calendar(auth)
+
+# Get upcoming events
+events = calendar.get_upcoming(days=7)
+for event in events:
+    print(f"{event.start}: {event.summary}")
+
+# Create event
+calendar.create_event(
+    summary="Meeting",
+    start="2026-01-30T10:00:00",
+    end="2026-01-30T11:00:00",
+)
+```
+
+### REST API
+
+```bash
+# Start unified API server
+gsuite serve --port 8080
+
+# Or with Docker
+docker run -p 8080:8080 gsuite-api
+```
+
+```bash
+# All services under one roof
+curl http://localhost:8080/gmail/messages/unread
+curl http://localhost:8080/calendar/events/upcoming
+curl http://localhost:8080/drive/files
+```
+
+**Interactive API docs available at `/docs` when server is running.** See [API Documentation](#api-documentation) section below for details.
+
+### CLI
+
+```bash
+# Authentication
+gsuite auth login              # Opens browser for OAuth
+gsuite auth status             # Check auth status
+gsuite auth export             # Export token for Cloud Run
+
+# Gmail
+gsuite gmail list --unread     # List unread messages
+gsuite gmail read MSG_ID       # Read specific message
+gsuite gmail send --to user@example.com --subject "Hi" --body "Hello"
+gsuite gmail search "from:boss has:attachment"
+gsuite gmail labels            # List all labels
+
+# Calendar  
+gsuite calendar list --days 7  # Upcoming events
+gsuite calendar today          # Today's events
+gsuite calendar week           # Week view
+gsuite calendar create "Meeting" --start "2026-01-30 10:00"
+gsuite calendar calendars      # List calendars
+
+# Server
+gsuite serve --port 8080       # Start REST API
+gsuite status                  # Overall status
+```
+
+## Architecture
+
+```
+google-suite/
+├── packages/
+│   ├── core/           # Shared auth, config, token storage
+│   ├── gmail/          # Gmail client + query builder
+│   ├── calendar/       # Calendar client
+│   ├── drive/          # Drive client (upload, download, share)
+│   └── sheets/         # Sheets client (planned)
+├── api/                # Unified FastAPI REST gateway
+├── cli/                # Unified CLI (Typer + Rich)
+├── skill/              # AI agent skill (OpenClaw compatible)
+└── tests/              # Integration tests
+```
+
+### Design Principles
+
+- **Clean Architecture** - Domain entities, interfaces, infrastructure separation
+- **Provider Agnostic** - Swap implementations via interfaces
+- **Shared Auth** - One OAuth flow grants access to all services
+- **Independent Packages** - Install only what you need
+- **Unified Gateway** - Single API/CLI for all services
+
+## AI Agent Skill
+
+This repo includes an [OpenClaw](https://openclaw.ai)-compatible skill for AI agents:
+
+```
+skill/
+├── SKILL.md      # Usage documentation for agents
+└── skill.json    # Skill metadata
+```
+
+Agents can use this skill to interact with Google Workspace on behalf of users.
+
+## Standalone Repos
+
+This monorepo consolidates and extends these standalone projects:
+
+- [Gmail-API](https://github.com/PabloAlaniz/Gmail-API) - Standalone Gmail API
+- [Calendar-API](https://github.com/PabloAlaniz/Calendar-API) - Standalone Calendar API
+
+The standalone repos remain functional for existing deployments.
+
+## Configuration
+
+Environment variables (prefix `GSUITE_`):
+
+| Variable | Description |
+|----------|-------------|
+| `GSUITE_CREDENTIALS_FILE` | OAuth credentials JSON path |
+| `GSUITE_TOKEN_STORAGE` | `sqlite` or `secretmanager` |
+| `GSUITE_TOKEN_DB_PATH` | SQLite token database path |
+| `GSUITE_GCP_PROJECT_ID` | GCP project (for Secret Manager) |
+| `GSUITE_API_KEY` | API key for REST endpoints |
+
+## Development
+
+```bash
+# Clone
+git clone https://github.com/PabloAlaniz/google-suite.git
+cd google-suite
+
+# Install all packages in dev mode
+pip install -e "packages/core[dev]"
+pip install -e "packages/gmail[dev]"
+pip install -e "packages/calendar[dev]"
+pip install -e "api[dev]"
+pip install -e "cli[dev]"
+
+# Run tests
+pytest
+
+# Lint
+ruff check packages api cli
+```
+
+## Deployment
+
+### Cloud Run (GCP)
+
+Deploy the REST API to Cloud Run with Secret Manager for token storage:
+
+```bash
+# Build and push Docker image
+gcloud builds submit --tag gcr.io/YOUR_PROJECT/gsuite-api
+
+# Deploy to Cloud Run
+gcloud run deploy gsuite-api \
+  --image gcr.io/YOUR_PROJECT/gsuite-api \
+  --platform managed \
+  --region us-central1 \
+  --set-env-vars GSUITE_TOKEN_STORAGE=secretmanager \
+  --set-env-vars GSUITE_GCP_PROJECT_ID=YOUR_PROJECT \
+  --allow-unauthenticated  # or use --no-allow-unauthenticated + IAM
+```
+
+**Note:** For Secret Manager token storage, ensure your Cloud Run service account has `secretmanager.versions.access` permission.
+
+### Docker Compose
+
+For local development or self-hosted deployment:
+
+```yaml
+version: '3.8'
+services:
+  gsuite-api:
+    build: .
+    ports:
+      - "8080:8080"
+    environment:
+      GSUITE_CREDENTIALS_FILE: /secrets/credentials.json
+      GSUITE_TOKEN_DB_PATH: /data/tokens.db
+      GSUITE_API_KEY: your-api-key-here
+    volumes:
+      - ./credentials.json:/secrets/credentials.json:ro
+      - ./data:/data
+```
+
+## API Documentation
+
+When running the REST API server, interactive API docs are available at:
+
+- **Swagger UI**: `http://localhost:8080/docs`
+- **ReDoc**: `http://localhost:8080/redoc`
+
+## Troubleshooting
+
+### Token refresh failed
+
+**Problem:** `TokenRefreshError: Failed to refresh token`
+
+**Solution:**
+- Delete the token database: `rm ~/.gsuite/tokens.db` (or your configured path)
+- Re-authenticate: `gsuite auth login`
+- For service accounts, verify the JSON file hasn't expired
+
+### Missing scopes
+
+**Problem:** `HttpError 403: Insufficient Permission`
+
+**Solution:**
+- Check required scopes in error message
+- Re-authenticate with additional scopes:
+  ```bash
+  gsuite auth login --scopes gmail.readonly,calendar,drive
+  ```
+- Or update `GSUITE_DEFAULT_SCOPES` environment variable
+
+### Credentials not found
+
+**Problem:** `CredentialsNotFoundError: OAuth credentials file not found`
+
+**Solution:**
+- Download OAuth credentials from [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
+- Save as `credentials.json` in working directory
+- Or set `GSUITE_CREDENTIALS_FILE` environment variable
+
+### Import errors
+
+**Problem:** `ModuleNotFoundError: No module named 'gsuite_gmail'`
+
+**Solution:**
+- Install the package: `pip install gsuite-gmail`
+- Or for development: `pip install -e "packages/gmail[dev]"`
+
+## License
+
+MIT - see [LICENSE](LICENSE)
+
+## Author
+
+Pablo Alaniz ([@PabloAlaniz](https://github.com/PabloAlaniz))

gsuite_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,42 @@
+gsuite_calendar/__init__.py,sha256=bv5jfO0_cCq6Al7trpeE4qAlvghn9zweTYUEZN0g1TI,291
+gsuite_calendar/calendar_entity.py,sha256=banQQ4LpCgwnWmdBh_3cjduDTzp2fmBhsIqjZzU5ybw,755
+gsuite_calendar/client.py,sha256=fQQ6mxpjnIS2a6X6CO3Ff8wTcw8o-R4Ske--gVb-geI,8402
+gsuite_calendar/event.py,sha256=7PnK2WhzeutEk6A93ERZSJ7Hq879_OfJ0RggF9-vJLc,1482
+gsuite_calendar/parser.py,sha256=f5VkMBgDIire8bDauUm1_a0uvgqafwTdIu3QcKRuLWI,3762
+gsuite_calendar/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gsuite_core/__init__.py,sha256=xPn5DxeRFn7D9bOd7HpMZKyWv6Nyvxz4kDbYQAQX_HE,1469
+gsuite_core/api_utils.py,sha256=NhZ--DI5WVPcyyK54csUgwMlbww-hZDhYYOseUkOvSk,5548
+gsuite_core/config.py,sha256=ESriNwCTQe58YjtkREXQSMAYEUfLOVS048XWn6oMcZQ,2552
+gsuite_core/exceptions.py,sha256=oPStsB50CiPGmazR8g_RgPLWjunaR5NiEawUJ3Zk1c4,3217
+gsuite_core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gsuite_core/auth/__init__.py,sha256=KbwMpy8SpSMOsGGuEdNCA90ktkYqVuE_7_8sqsUiGvg,155
+gsuite_core/auth/oauth.py,sha256=pXO7wm-ysGmW29kXxzi8raqE05CrDZizwkfSIr-G3-g,7748
+gsuite_core/auth/scopes.py,sha256=DTw6x1J58eLCHfZXBok7-j0JNJLfrs7L8EuchvxtQ0Q,2587
+gsuite_core/storage/__init__.py,sha256=pTwqi3yBamP30A84_qUpupnkVIuVUtN8skSwMJz7ok0,344
+gsuite_core/storage/base.py,sha256=oP707l7Be9LveNT5N9jQ6DJLw5-ieDH-pOpano8RCkQ,1395
+gsuite_core/storage/secretmanager.py,sha256=xLCYPrplnSrtwBm67PFf33zlMTdbNLhr_BdVsLChGts,4626
+gsuite_core/storage/sqlite.py,sha256=gkHrBnc0heF_k-B5kvgrA9149bqEIHSjDzXxjkm0iFI,2694
+gsuite_drive/__init__.py,sha256=4v_CJa09r3aw3EiGjjNd76d3y5btsxol2jAFNeZlvvw,211
+gsuite_drive/client.py,sha256=ltq7Pk5KG7_OWMfJKKVyv2DdvFw9rhn3YWEehm2L-KA,11333
+gsuite_drive/file.py,sha256=gRzoZQZwyaHhkgt8TrfV0kUhNVLyOXeE-2R8IAThEew,2668
+gsuite_drive/parser.py,sha256=dWD3v03u6x_ks5XFsrzOmbw8m2ob-vFCH9SqcBmR0d0,1969
+gsuite_drive/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gsuite_gmail/__init__.py,sha256=1xCk4i9Ydi6sTNP-wO4LFD2hnVKP-zCS0QNuYG11nm8,345
+gsuite_gmail/client.py,sha256=bR-cQc8UJH-N253HAltLUnbLRSlEZIj8_1eGk7KiD-w,12158
+gsuite_gmail/label.py,sha256=Dc2cFAsR-eII0qgouJAfofwlfjlqFq5_kNAVjP_kUxg,1232
+gsuite_gmail/message.py,sha256=UCmum5DgMKKiB7YEG4zj_q-_qdNt1RFjfBNkdDJ0mZQ,6577
+gsuite_gmail/parser.py,sha256=JeEfNkgpJdJFIQ2LXLrd7Wmr3xl2M7-uFM901o_84v8,4802
+gsuite_gmail/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gsuite_gmail/query.py,sha256=9UHSm6agDbQ-gAJcEd-CG7DucQ83eOMqr-xY2toCzf8,5812
+gsuite_gmail/thread.py,sha256=MiWsKgrtlvBIET3DEwZgEYVl_6L3qPRQfo3iRKYUyJw,1366
+gsuite_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=25xFe8kmZ3TZzs93SbzlDP_OHHkT5lsANRqQ_Ao2A0M,1069
+gsuite_sheets/__init__.py,sha256=llrLdudKQqoVQKhJE5GVMT_ibJr30vdjXZqrNjqQnXU,279
+gsuite_sheets/client.py,sha256=m1PLd0fgTHIJYWnmLldR4SCnAQtEAWs0XeqUu087mqk,10662
+gsuite_sheets/parser.py,sha256=jQcTcfwG6uYnlyXKOE5yv6Oc6nNVrgEs2nck1xLTxOQ,2267
+gsuite_sheets/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gsuite_sheets/spreadsheet.py,sha256=3YFQHEVw2U9KaV-fsBzkXy-mTCygbJA1HZ2edgtxY-U,2674
+gsuite_sheets/worksheet.py,sha256=stD8ZUArs3-h4yYsS_XnjcKBvjUTikz3pLvxOHyET-c,5789
+gsuite_sdk-0.1.0.dist-info/METADATA,sha256=D5yY2KzdCM6tnixIzsV3hiZze5pw05cU70vfyurmMOk,10775
+gsuite_sdk-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+gsuite_sdk-0.1.0.dist-info/top_level.txt,sha256=owr7_TnX3SwC7hcmPZ0rmMqvKY16AiyfWf2HTJFf3Gs,68
+gsuite_sdk-0.1.0.dist-info/RECORD,,

gsuite_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gsuite_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pablo Alaniz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gsuite_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,5 @@
+gsuite_calendar
+gsuite_core
+gsuite_drive
+gsuite_gmail
+gsuite_sheets

gsuite_sheets/__init__.py

@@ -0,0 +1,13 @@
+"""Google Suite Sheets - Simple Sheets API client."""
+
+__version__ = "0.1.0"
+
+from gsuite_sheets.client import Sheets
+from gsuite_sheets.spreadsheet import Spreadsheet
+from gsuite_sheets.worksheet import Worksheet
+
+__all__ = [
+    "Sheets",
+    "Spreadsheet",
+    "Worksheet",
+]