gcal-pro

Google 日历集成，用于查看、创建和管理日历事件。当用户询问他们的日程安排、想要添加/编辑/删除事件、检查可用性或需要晨间简报时使用。支持自然语言，例如“明天我的日历上有什么？”或“安排周五中午与亚历克斯共进午餐。”免费套餐提供读取访问权限；专业级（12 美元）增加了创建/编辑/删除和晨间简报。

# gcal-pro

Manage Google Calendar through natural conversation.

## Quick Reference

| Action | Command | Tier |
|--------|---------|------|
| View today | `python scripts/gcal_core.py today` | Free |
| View tomorrow | `python scripts/gcal_core.py tomorrow` | Free |
| View week | `python scripts/gcal_core.py week` | Free |
| Search events | `python scripts/gcal_core.py search -q "meeting"` | Free |
| List calendars | `python scripts/gcal_core.py calendars` | Free |
| Find free time | `python scripts/gcal_core.py free` | Free |
| Quick add | `python scripts/gcal_core.py quick -q "Lunch Friday noon"` | Pro |
| Delete event | `python scripts/gcal_core.py delete --id EVENT_ID -y` | Pro |
| Morning brief | `python scripts/gcal_core.py brief` | Pro |

## Setup

**First-time setup required:**

1. User must create Google Cloud project and OAuth credentials
2. Save `client_secret.json` to `~/.config/gcal-pro/`
3. Run authentication:
   ```bash
   python scripts/gcal_auth.py auth
   ```
4. Browser opens → user grants calendar access → done

**Check auth status:**
```bash
python scripts/gcal_auth.py status
```

## Tiers

### Free Tier
- View events (today, tomorrow, week, month)
- Search events
- List calendars
- Find free time slots

### Pro Tier ($12 one-time)
- Everything in Free, plus:
- Create events
- Quick add (natural language)
- Update/reschedule events
- Delete events
- Morning brief via cron

## Usage Patterns

### Viewing Schedule

When user asks "What's on my calendar?" or "What do I have today?":

```bash
cd /path/to/gcal-pro
python scripts/gcal_core.py today
```

For specific ranges:
- "tomorrow" → `python scripts/gcal_core.py tomorrow`
- "this week" → `python scripts/gcal_core.py week`
- "meetings with Alex" → `python scripts/gcal_core.py search -q "Alex"`

### Creating Events (Pro)

When user says "Add X to my calendar" or "Schedule Y":

**Option 1: Quick add (natural language)**
```bash
python scripts/gcal_core.py quick -q "Lunch with Alex Friday at noon"
```

**Option 2: Structured create (via Python)**
```python
from scripts.gcal_core import create_event, parse_datetime

create_event(
    summary="Lunch with Alex",
    start=parse_datetime("Friday noon"),
    location="Cafe Roma",
    confirmed=True  # Set False to show confirmation prompt
)
```

### Modifying Events (Pro)

**⚠️ CONFIRMATION REQUIRED for destructive actions!**

Before deleting or significantly modifying an event, ALWAYS confirm with the user:

1. Show event details
2. Ask "Should I delete/reschedule this?"
3. Only proceed with `confirmed=True` or `-y` flag after user confirms

**Delete:**
```bash
# First, find the event
python scripts/gcal_core.py search -q "dentist"
# Shows event ID

# Then delete (with user confirmation)
python scripts/gcal_core.py delete --id abc123xyz -y
```

### Finding Free Time

When user asks "When am I free?" or "Find time for a 1-hour meeting":

```bash
python scripts/gcal_core.py free
```

### Morning Brief (Pro + Cron)

Set up via Clawdbot cron to send daily agenda:

```python
from scripts.gcal_core import generate_morning_brief
print(generate_morning_brief())
```

**Cron setup example:**
- Schedule: 8:00 AM daily
- Action: Run `python scripts/gcal_core.py brief`
- Delivery: Send output to user's messaging channel

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| "client_secret.json not found" | Setup incomplete | Complete Google Cloud setup |
| "Token refresh failed" | Expired/revoked | Run `python scripts/gcal_auth.py auth --force` |
| "requires Pro tier" | Free user attempting write | Prompt upgrade or explain limitation |
| "Event not found" | Invalid event ID | Search for correct event first |

## Timezone Handling

- All times are interpreted in user's local timezone (default: America/New_York)
- When user specifies timezone (e.g., "2 PM EST"), honor it
- Display times in user's local timezone
- Store in ISO 8601 format with timezone

## Response Formatting

**For event lists, use this format:**

```
📅 **Monday, January 27**
  • 9:00 AM — Team standup
  • 12:00 PM — Lunch with Alex 📍 Cafe Roma
  • 3:00 PM — Client call

📅 **Tuesday, January 28**
  • 10:00 AM — Dentist appointment 📍 123 Main St
```

**For confirmations:**

```
✓ Event created: "Lunch with Alex"
  📅 Friday, Jan 31 at 12:00 PM
  📍 Cafe Roma
```

**For morning brief:**

```
☀️ Good morning! Here's your day:
📆 Monday, January 27, 2026

You have 3 events today:
  • 9:00 AM — Team standup
  • 12:00 PM — Lunch with Alex
  • 3:00 PM — Client call

👀 Tomorrow: 2 events
```

## File Locations

```
~/.config/gcal-pro/
├── client_secret.json   # OAuth app credentials (user provides)
├── token.json           # User's access token (auto-generated)
└── license.json         # Pro license (if purchased)
```

## Integration with Clawdbot

This skill works with:
- **Cron**: Schedule morning briefs
- **Memory**: Store calendar preferences
- **Messaging**: Deliver briefs via Telegram/WhatsApp/etc.

## Upgrade Prompt

When a Free user attempts a Pro action, respond:

> ⚠️ Creating events requires **gcal-pro Pro** ($12 one-time).
> 
> Pro includes: Create, edit, delete events + morning briefs.
> 
> 👉 Upgrade: [gumroad-link]
> 
> For now, I can show you your schedule (free) — want to see today's events?

---

## 中文说明

# gcal-pro

通过自然对话管理 Google 日历。

## 快速参考

| 操作 | 命令 | 套餐 |
|--------|---------|------|
| 查看今天 | `python scripts/gcal_core.py today` | 免费 |
| 查看明天 | `python scripts/gcal_core.py tomorrow` | 免费 |
| 查看本周 | `python scripts/gcal_core.py week` | 免费 |
| 搜索事件 | `python scripts/gcal_core.py search -q "meeting"` | 免费 |
| 列出日历 | `python scripts/gcal_core.py calendars` | 免费 |
| 查找空闲时间 | `python scripts/gcal_core.py free` | 免费 |
| 快速添加 | `python scripts/gcal_core.py quick -q "Lunch Friday noon"` | 专业版 |
| 删除事件 | `python scripts/gcal_core.py delete --id EVENT_ID -y` | 专业版 |
| 晨间简报 | `python scripts/gcal_core.py brief` | 专业版 |

## 设置

**需要首次设置：**

1. 用户必须创建 Google Cloud 项目和 OAuth 凭据
2. 将 `client_secret.json` 保存到 `~/.config/gcal-pro/`
3. 运行身份验证：
   ```bash
   python scripts/gcal_auth.py auth
   ```
4. 浏览器打开 → 用户授予日历访问权限 → 完成

**检查身份验证状态：**
```bash
python scripts/gcal_auth.py status
```

## 套餐

### 免费套餐
- 查看事件（今天、明天、本周、本月）
- 搜索事件
- 列出日历
- 查找空闲时间段

### 专业套餐（一次性 12 美元）
- 包含免费套餐的所有功能，外加：
- 创建事件
- 快速添加（自然语言）
- 更新/重新安排事件
- 删除事件
- 通过 cron 推送晨间简报

## 使用模式

### 查看日程

当用户询问“我的日历上有什么？”或“我今天有什么安排？”时：

```bash
cd /path/to/gcal-pro
python scripts/gcal_core.py today
```

针对特定时间范围：
- “明天” → `python scripts/gcal_core.py tomorrow`
- “本周” → `python scripts/gcal_core.py week`
- “与 Alex 的会议” → `python scripts/gcal_core.py search -q "Alex"`

### 创建事件（专业版）

当用户说“将 X 添加到我的日历”或“安排 Y”时：

**选项 1：快速添加（自然语言）**
```bash
python scripts/gcal_core.py quick -q "Lunch with Alex Friday at noon"
```

**选项 2：结构化创建（通过 Python）**
```python
from scripts.gcal_core import create_event, parse_datetime

create_event(
    summary="Lunch with Alex",
    start=parse_datetime("Friday noon"),
    location="Cafe Roma",
    confirmed=True  # Set False to show confirmation prompt
)
```

### 修改事件（专业版）

**⚠️ 破坏性操作需要确认！**

在删除或大幅修改事件之前，请始终与用户确认：

1. 显示事件详情
2. 询问“我应该删除/重新安排这个吗？”
3. 仅在用户确认后使用 `confirmed=True` 或 `-y` 标志继续

**删除：**
```bash
# First, find the event
python scripts/gcal_core.py search -q "dentist"
# Shows event ID

# Then delete (with user confirmation)
python scripts/gcal_core.py delete --id abc123xyz -y
```

### 查找空闲时间

当用户询问“我什么时候有空？”或“为一个 1 小时的会议找时间”时：

```bash
python scripts/gcal_core.py free
```

### 晨间简报（专业版 + Cron）

通过 Clawdbot cron 设置以发送每日议程：

```python
from scripts.gcal_core import generate_morning_brief
print(generate_morning_brief())
```

**Cron 设置示例：**
- 计划：每天上午 8:00
- 操作：运行 `python scripts/gcal_core.py brief`
- 投递：将输出发送到用户的消息渠道

## 错误处理

| 错误 | 原因 | 解决方案 |
|-------|-------|----------|
| "client_secret.json not found" | 设置未完成 | 完成 Google Cloud 设置 |
| "Token refresh failed" | 已过期/已撤销 | 运行 `python scripts/gcal_auth.py auth --force` |
| "requires Pro tier" | 免费用户尝试写入 | 提示升级或说明限制 |
| "Event not fou