Google Workspace Integration

Unified Gmail and Calendar management skill for PAI with 1Password-first security, OAuth authentication, and natural language CLI operations.

TypeScriptGoogle APIsOAuthCLIPAI

Google Workspace Integration

A unified Gmail and Calendar management system built as a PAI skill, enabling natural language email triage, meeting scheduling, and inbox management through a deterministic CLI tool.

Overview

This project bridges Google Workspace APIs with PAI’s skill architecture, allowing AI-orchestrated email and calendar operations through a TypeScript CLI. It follows the CLI-first principle: every operation is a deterministic command that AI wraps with intelligence.

Key Features

Email Management

  • Search and filter using Gmail query syntax
  • Read, archive, star, label messages
  • Send emails and create drafts with AI-assisted composition
  • Inbox triage with priority categorization

Calendar Management

  • List upcoming events with date range filtering
  • Create meetings with attendee invitations
  • Check availability (free/busy queries)
  • Respond to invitations (accept/decline/tentative)

Security Model

  • 1Password-first - All secrets stored in 1Password Automation Secrets vault
  • Hybrid authentication - Service account for reads, OAuth for writes
  • Zero filesystem credentials - Ephemeral access tokens in memory only
  • Automatic token refresh - 1-hour TTL with transparent renewal

Architecture

The integration uses a hybrid authentication approach:

  • Read operations use a service account token for non-interactive, automatic access
  • Write operations use OAuth with refresh tokens stored in 1Password
User -> CLI -> Service Account Token (~/.op-tokens/dev.token)
     -> 1Password (OAuth creds) -> Google OAuth -> Refresh Token (1Password)
     -> Access Token (memory, 1hr TTL) -> Gmail/Calendar APIs

What I Learned

  • OAuth flow complexity - Google’s OAuth consent screen and token management has many edge cases
  • 1Password CLI integration - Using op read for runtime secret injection is elegant but requires careful token management
  • Service account limitations - Can read but not send emails on behalf of personal accounts without domain-wide delegation
  • CLI design patterns - Subcommand architecture (workspace mail list, workspace calendar create) scales well