Google Workspace

SKILL.md

---
name: google-workspace
description: Access Google Workspace APIs (Calendar, Directory, Gmail, Drive, Docs/Sheets) via service account with domain-wide delegation.
---

# Google Workspace

Access Curacel's Google Workspace via service account:
- **Service Account:** `workspace-service-account@curacel-people.iam.gserviceaccount.com`
- **Credentials:** `.credentials/google-workspace-sa.json`
- **Default User:** `henry@curacel.ai`

## When to Use

- Calendar operations (list meetings, create events)
- Directory lookups (user info, birthdays, org structure)
- Gmail (search, send emails)
- Drive (search, download files)
- Docs/Sheets (read content, export data)

## Scripts

All scripts follow pattern: `node scripts/<service>.js <command> <user-email> [args]`

### Calendar (`calendar.js`)
- `list <email> [days]` - List events (0=today, 7=next week)
- `get <email> <event-id>` - Event details
- `create <email> <json-file>` - Create event

### Directory (`directory.js`)
- `list-users <email>` - All workspace users
- `get-user <email> <user-email>` - User details (birthdays, manager, etc.)
- `list-groups <email>` - All groups
- `get-group <email> <group-id>` - Group details

### Gmail (`gmail.js`)
- `list <email> [query]` - List messages
- `search <email> <query>` - Search (Gmail query syntax)
- `send <email> <json-file>` - Send email
- `get <email> <message-id>` - Message details

### Drive (`drive.js`)
- `list <email> [query]` - List files
- `search <email> <name>` - Search by name
- `get <email> <file-id>` - File metadata
- `download <email> <file-id> <path>` - Download file

### Docs/Sheets (`docs.js`)
- `get-doc <email> <doc-id>` - Document content
- `get-sheet <email> <sheet-id>` - Spreadsheet metadata
- `list-tabs <email> <sheet-id>` - List all tabs in a spreadsheet
- `read-range <email> <sheet-id> <range>` - Read cells (e.g., "'Tab Name'!A1:Z50")
- `read-all <email> <sheet-id> [max-rows]` - Read ALL tabs at once (default 100 rows each)
- `append-values <email> <sheet-id> <range> <json>` - Append rows

## Common Patterns

### Daily briefing
```bash
node scripts/calendar.js list henry@curacel.ai 0 | jq '.[].summary'
```

### Find user birthday
```bash
node scripts/directory.js get-user henry@curacel.ai pelumi.o@curacel.ai | jq '.organizations[0].customSchemas.employment.birthday'
```

### Search for document
```bash
node scripts/drive.js search henry@curacel.ai "OKR 2026"
```

### List tabs in a spreadsheet
```bash
node scripts/docs.js list-tabs henry@curacel.ai "SPREADSHEET_ID"
```

### Read a specific tab
```bash
node scripts/docs.js read-range henry@curacel.ai "SPREADSHEET_ID" "'Q4 Commit'!A1:Z50"
```

### Dump ALL tabs from a sheet (great for analysis)
```bash
node scripts/docs.js read-all henry@curacel.ai "SPREADSHEET_ID" 200
```

### Key Spreadsheet IDs
| Sheet | ID |
|-------|-----|
| Must Close | `1RHfR-TpPxG0DKJBnfK6VzVnARPlQkyiS3eMeUmkLnHE` |
| Investor Updates (25Q) | *(find via drive search)* |
| Team Leads Monthly | *(find via drive search)* |
| Product OKRs | *(find via drive search)* |
| Salaries | *(find via drive search)* |

## Error Handling

**"unauthorized_client"** → Check DWD config in Admin Console (Client ID: 114474628740597685495)

**"Method doesn't allow unregistered callers"** → API not enabled in GCP console

**Invalid credentials** → Verify `.credentials/google-workspace-sa.json` exists

## References

- `references/scopes.md` - Configured scopes
- `references/examples.md` - Full examples with JSON payloads