# Google Woekspace app setup

# Setting Up Gmail Per Hermes Profile

Each Hermes profile authenticates to its own Google account via OAuth. This guide covers the one-time Google Cloud setup, then the per-profile authorization.

---

## Prerequisites

- A Hermes profile for each Gmail account you want to connect
- Access to the Google Cloud Console

## Step 1: Create Google OAuth Credentials (one-time)

Do this once in the Google Cloud Console. The same OAuth client can be used across all profiles — each profile just signs in with a different Google account during the auth flow.

1. Go to [Google Cloud Console → Project Selector](https://console.cloud.google.com/projectselector2/home/dashboard)
2. Create or select a project
3. Enable the APIs you need from the [API Library](https://console.cloud.google.com/apis/library):
   - Gmail API
   - Google Calendar API
   - Google Drive API
   - Google Sheets API
   - Google Docs API
   - Google Slides API
   - People API (contacts)
4. Go to [Credentials](https://console.cloud.google.com/apis/credentials)
   - Create Credentials → OAuth 2.0 Client ID
   - Application type: **Desktop app**
   - Click Create
5. If the app is in Testing mode, add each Google account you want to connect as a test user:
   - Go to [Audience](https://console.cloud.google.com/auth/audience)
   - Test users → Add users → add each Gmail address
6. Download the JSON file

> The client secret is just your app's identity — it doesn't grant access to any account by itself. Access comes from the per-profile auth flow where you sign in with a specific Google account.

## Step 2: Place the client secret file

Put the downloaded JSON file in a shared location:

```bash
cp ~/Downloads/client_secret_*.json ~/.hermes/shared/google-app-secret.json
```

## Step 3: Authorize each profile

Run these commands for **each profile** you want to connect. Replace `<profile>` with the profile name (e.g. `james`, `gabriel`, `helios-ai`).

**Important:** Use the Hermes venv Python (`~/.hermes/hermes-agent/venv/bin/python`), not system `python3` — the Google libraries require Python 3.10+ and the system Python is 3.9.

### 3a. Install the client secret into the profile

```bash
HERMES_HOME=~/.hermes/profiles/<profile> ~/.hermes/hermes-agent/venv/bin/python ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/setup.py --client-secret ~/.hermes/shared/google-app-secret.json
```

### 3b. Get the authorization URL

```bash
HERMES_HOME=~/.hermes/profiles/<profile> ~/.hermes/hermes-agent/venv/bin/python ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/setup.py --auth-url
```

This prints an OAuth URL. Open it in your browser and sign in with the Gmail account you want this profile to use.

> **Note:** After approving, the browser will likely show an error on `http://localhost:1` — this is expected. Copy the ENTIRE URL from the browser address bar.

> **Note:** The `--services` and `--format json` flags are NOT supported in the current version. The setup script uses a fixed set of scopes covering all Google Workspace APIs.

### 3c. Exchange the authorization code

Paste the redirect URL (or just the code) back:

```bash
HERMES_HOME=~/.hermes/profiles/<profile> ~/.hermes/hermes-agent/venv/bin/python ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/setup.py --auth-code "PASTE_REDIRECT_URL_HERE"
```

### 3d. Verify it worked

```bash
HERMES_HOME=~/.hermes/profiles/<profile> ~/.hermes/hermes-agent/venv/bin/python ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/setup.py --check
```

Should print `AUTHENTICATED`.

## Step 4: Test it

```bash
GAPI=~/.hermes/hermes-agent/venv/bin/python

# Search unread emails
HERMES_HOME=~/.hermes/profiles/<profile> $GAPI ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/google_api.py gmail search "is:unread" --max 5

# List calendar events
HERMES_HOME=~/.hermes/profiles/<profile> $GAPI ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/google_api.py calendar list
```

## Step 5: Repeat for each profile

Run Steps 3a–3d again for each profile, signing in with a different Gmail account each time. Each profile stores its own token at:

```
~/.hermes/profiles/<profile>/google_token.json
```

## File Locations Per Profile

| File | Path | Purpose |
|---|---|---|
| Client secret | `~/.hermes/profiles/<profile>/google_client_secret.json` | OAuth client credentials (copied from shared file) |
| OAuth token | `~/.hermes/profiles/<profile>/google_token.json` | Authenticated session (unique per profile) |

## How It Works

| Piece | Role |
|---|---|
| Client secret | Your app's identity — "I am Hermes app". Shared across all profiles. |
| Auth flow (browser sign-in) | Pick which Google account to connect. Done once per profile. |
| Token (`google_token.json`) | Proof that a specific Gmail account authorized the app. One per profile. |

One client secret, many tokens — each token tied to whichever Google account signed in during that profile's auth flow.

## Troubleshooting

| Problem | Fix |
|---|---|
| `NOT_AUTHENTICATED` | Run Steps 3b–3d again |
| `REFRESH_FAILED` | Token revoked or expired — redo Steps 3b–3d |
| `HttpError 403: access_denied` | Add the Gmail address as a test user in [Google Cloud Console → Audience](https://console.cloud.google.com/auth/audience) |
| `HttpError 403: Insufficient Permission` | Missing API scope — revoke and redo |
| `ModuleNotFoundError` / `No matching distribution` | Use the Hermes venv Python: `~/.hermes/hermes-agent/venv/bin/python` |
| `zsh: no such file or directory: python` | Don't use the `GSETUP` variable pattern in zsh. Call the venv Python directly with `HERMES_HOME=...` prefix |

## Revoking Access

To disconnect a profile's Gmail and re-authorize with a different account:

```bash
# Revoke
HERMES_HOME=~/.hermes/profiles/<profile> ~/.hermes/hermes-agent/venv/bin/python ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/setup.py --revoke

# Re-authorize (Steps 3b–3d)
HERMES_HOME=~/.hermes/profiles/<profile> ~/.hermes/hermes-agent/venv/bin/python ~/.hermes/profiles/<profile>/skills/productivity/google-workspace/scripts/setup.py --auth-url
```

## Quick Reference: All Commands For One Profile

```bash
PROFILE=james
HH="HERMES_HOME=~/.hermes/profiles/$PROFILE"
PY=~/.hermes/hermes-agent/venv/bin/python
SCRIPT=~/.hermes/profiles/$PROFILE/skills/productivity/google-workspace/scripts/setup.py

# 1. Install client secret
$HH $PY $SCRIPT --client-secret ~/.hermes/shared/google-app-secret.json

# 2. Get auth URL (sign in with the Gmail account for this profile)
$HH $PY $SCRIPT --auth-url

# 3. Exchange code (paste the redirect URL)
$HH $PY $SCRIPT --auth-code "http://localhost:1/?code=4/0A..."

# 4. Verify
$HH $PY $SCRIPT --check

# 5. Test Gmail
GAPI=~/.hermes/profiles/$PROFILE/skills/productivity/google-workspace/scripts/google_api.py
$HH $PY $GAPI gmail search "is:unread" --max 5
```