This installs `googleapis` (Google API client) and `mupdf` (PDF text extraction for email attachments).

### Step 2: Create a Google Cloud Project

1. Go to [Google Cloud Console](https://console.cloud.google.com) and create a new project (or use an existing one)
2. Enable the **Google Calendar API** and **Gmail API**:
   - Go to **APIs & Services → Library**
   - Search for "Google Calendar API" → click **Enable**
   - Search for "Gmail API" → click **Enable**

### Step 3: Configure the OAuth Consent Screen

1. Go to **Google Auth Platform → Audience** ([direct link](https://console.cloud.google.com/auth/audience))
2. If prompted, configure the consent screen:
   - **App name**: anything (e.g., "OpenClaw")
   - **User support email**: your email
   - **Scopes**: skip (the auth script requests scopes at runtime)
3. If your app is in **Testing** publishing status (the default), add every Google account you want to authorize as a **test user**:
   - Under **Test users**, click **Add users**
   - Enter the email addresses of each account you'll connect
   - Save

> **⚠️ Important:** Apps in "Testing" status have a **7-day token expiry**. To get long-lived tokens, publish your app to "Production" in the Audience settings. For personal Gmail accounts (External user type), you can skip Google's verification review — you'll just see an "unverified app" warning during consent. This is fine for personal use.

### Step 4: Create OAuth Credentials

1. Go to **Google Auth Platform → Clients** ([direct link](https://console.cloud.google.com/auth/clients))
2. Click **Create Client** → choose **Desktop app** as the application type
3. Name it whatever you like (e.g., "OpenClaw")
4. Click **Create** and **download the credentials JSON**
5. Run the setup script:

This copies your credentials to `~/.openclaw/google-workspace-byok/credentials.json`.

### Step 5: Authorize Google Accounts

For each Google account you want to connect:

The `<label>` is a friendly name you'll use to reference this account (e.g., "personal", "work", "household").

**Auth flow:**
1. The script prints an authorization URL
2. Open the URL in your browser and sign in with the Google account
3. Grant the requested permissions
4. You'll be redirected to `http://localhost/...` — **the page won't load, and that's expected**
5. Copy the **full URL** from your browser's address bar and paste it back into the script
6. The script exchanges the code for tokens and saves them

**Scopes requested (default — read/write):**
- `calendar` — Full read/write access to Google Calendar
- `gmail.readonly` — Read-only access to Gmail

Pass `--readonly` to request read-only calendar access instead.

Tokens are stored in `~/.openclaw/google-workspace-byok/tokens/<label>.json`.

## Usage

All scripts are in `{baseDir}/scripts/`. Run them with `node`.

### Calendar

Gmail search uses the same query syntax as the Gmail web search box (e.g., `is:unread`, `from:`, `newer_than:1d`, `has:attachment`).

### Reading PDF Attachments

The skill includes `mupdf` for extracting text from PDF attachments — useful for newsletters, invoices, school letters, etc. It handles multilingual text (Japanese, Chinese, etc.) well.

> **Note:** `mupdf` is an ESM module — use `node --input-type=module` with `import` syntax, not `require()`.

### Account Management

# List all calendars
node {baseDir}/scripts/calendar.js --account <label> --action list-calendars

# List upcoming events (default: next 7 days, primary calendar)
node {baseDir}/scripts/calendar.js --account <label> --action events

# List events with options
node {baseDir}/scripts/calendar.js --account <label> --action events --calendar <calendarId> --days <number> --max <number>

# Get a specific event
node {baseDir}/scripts/calendar.js --account <label> --action get-event --calendar <calendarId> --event-id <eventId>

# Check free/busy
node {baseDir}/scripts/calendar.js --account <label> --action freebusy --days <number>

# List recent emails (default: 10)
node {baseDir}/scripts/gmail.js --account <label> --action list

# Search emails
node {baseDir}/scripts/gmail.js --account <label> --action list --query "from:[email protected]" --max 20

# Read a specific email (includes attachment metadata with IDs)
node {baseDir}/scripts/gmail.js --account <label> --action read --message-id <messageId>

# Download all attachments from an email
node {baseDir}/scripts/gmail.js --account <label> --action attachment --message-id <messageId> --out-dir /tmp/attachments

# Download a specific attachment
node {baseDir}/scripts/gmail.js --account <label> --action attachment --message-id <messageId> --attachment-id <id> --out-dir /tmp

# List labels
node {baseDir}/scripts/gmail.js --account <label> --action labels

# 1. Download the attachment
mkdir -p /tmp/attachments
node {baseDir}/scripts/gmail.js --account <label> --action attachment --message-id <id> --out-dir /tmp/attachments

# 2. Extract text from the PDF
node --input-type=module -e "
import * as mupdf from '{baseDir}/scripts/node_modules/mupdf/dist/mupdf.js';
import fs from 'fs';
const data = fs.readFileSync('/tmp/attachments/filename.pdf');
const doc = mupdf.Document.openDocument(data, 'application/pdf');
for (let i = 0; i < doc.countPages(); i++) {
  const page = doc.loadPage(i);
  console.log(page.toStructuredText('preserve-whitespace').asText());
}
"

# List configured accounts
node {baseDir}/scripts/accounts.js --action list

# Check token status
node {baseDir}/scripts/accounts.js --action status --account <label>

~/.openclaw/google-workspace-byok/
├── credentials.json          # Your GCP OAuth credentials
└── tokens/
    ├── personal.json          # Token for "personal" account
    └── work.json              # Token for "work" account