Metadata-Version: 2.4
Name: gcal-vcs
Version: 1.0.0
Summary: Git-like staging, diffing, and version control for Google Calendar
Project-URL: Homepage, https://github.com/thondascully/gcal-vcs
Project-URL: Documentation, https://github.com/thondascully/gcal-vcs#readme
Project-URL: Repository, https://github.com/thondascully/gcal-vcs
Project-URL: Issues, https://github.com/thondascully/gcal-vcs/issues
Author-email: Teo Honda-Scully <thondascully@berkeley.edu>
License: MIT
License-File: LICENSE
Keywords: ai-agents,calendar-api,diff,google-calendar,staging,transaction,version-control
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: flask>=2.0.0
Requires-Dist: google-api-python-client>=2.0.0
Requires-Dist: google-auth-oauthlib>=1.0.0
Requires-Dist: google-auth>=2.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

#  gcal-vcs

**Git-style version control for Google Calendar.** Scripts and AI agents are powerful, but giving them direct write access to your schedule is risky. `gcal-vcs` acts as a safety buffer: stage changes locally, preview the impact with a visual diff, and commit only when you're ready.

![gcal-vcs preview](https://res.cloudinary.com/dlghowziz/image/upload/v1769504602/Screenshot_2026-01-27_at_12.31.29_AM_nr9ump.png)

## The 2-Line Integration

Designed for zero refactoring. You wrap your existing service, and the rest of your code remains identical.

### **Before**
```python
service = build("calendar", "v3", credentials=creds)

# this hits the Google API immediately + no undo
service.events().insert(calendarId="primary", body=event_data).execute()
```

### **After**
```python
from gcal_vcs import staged

# 1. wrap ur service
service = staged(build("calendar", "v3", credentials=creds))

# 2. use the exact same API (changes are now staged locally)
service.events().insert(calendarId="primary", body=event_data).execute()

service.preview()   # opens visual diff in browser
service.commit()    # applies all changes atomically
```

-----

## Agent-First Workflows

For headless environments or AI agents, `gcal-vcs` provides programmatic oversight without forcing a browser popup:

```python
# Returns a URL to the diff UI instead of opening a browser
url = service.preview(blocking=False)

# Get a human-readable text summary for LLM validation
print(service.get_text_summary()) 

# Check changes programmatically
if service.status().total_changes < 10:
    service.commit()
else:
    service.rollback()
```

## CLI & History
Manage your calendar state directly from the terminal.
```python
gcal-vcs log              # list recent commits
gcal-vcs show <id>        # inspect a specific change set
gcal-vcs revert <id>      # undo any previous commit
gcal-vcs ui               # open the history browser
```

[Example of CLI-revert](https://github.com/user-attachments/assets/64227895-51ab-4f05-a3bb-f6e402c467ea)

## Installation
```bash
pip install gcal-vcs
```

## Requirements
* Python 3.9+
* Google Calendar API credentials



