google-workspace

# Google Workspace Use this skill for Google Workspace tasks (Gmail, Drive, Calendar, Docs, Sheets, etc.). ## Files - `scripts/auth.js` — OAuth login/status/clear + account enumeration - `scripts/workspace.js` — JavaScript execution based API runner ## Account model (multi-account) This skill is **profile-based by email address**. - There is **no default account**. - Every API call must specify `--email <account@example.com>`. - Tokens are stored per-email under `~/.pi/google-workspace/tokens/`. Before running API calls, discover available signed-in accounts: ```bash node scripts/auth.js accounts ``` ## Usage Always use `exec` and always provide `--email`. ```bash node scripts/workspace.js exec --email user@example.com <<'JS' const me = await workspace.whoAmI(); const files = await workspace.call('drive', 'files.list', { pageSize: 5, fields: 'files(id,name,mimeType)', }); return { me, files: files.files }; JS ``` Available inside exec scripts: - `auth` (authorized OAuth client) - `google` (`googleapis` root) - `workspace.accountEmail` (selected profile email) - `workspace.call(service, methodPath, params, {version})` - `workspace.service(service, {version})` - `workspace.whoAmI()` Optional flags: - `--timeout <ms>` (default 30000, max 300000) - `--scopes s1,s2` - `--script 'return 42'` ## Agent guidance 1. Prefer one `exec` script per user request. 2. Keep payloads small (`fields`, `maxResults`, minimal props). 3. Use `Promise.all` for independent requests. 4. Never print token contents. 5. If the user did not specify an account, run `node scripts/auth.js accounts` and choose/confirm an explicit email. 6. If auth fails, first run `node scripts/auth.js accounts` to see known profiles. 7. If account mismatch is possible, run `workspace.whoAmI()` in the selected profile. 8. On 401/403/unauthorized errors, switch account (`--email ...`) or re-login that specific profile. ## Unauthorized/account-switch playbook If a request fails with unauthorized/forbidden/insufficient permissions: 1. Enumerate profiles: ```bash node scripts/auth.js accounts ``` 2. Retry with the intended account: ```bash node scripts/workspace.js exec --email correct-user@example.com <<'JS' return await workspace.whoAmI(); JS ``` 3. If token is stale or missing scopes, re-login that account: ```bash node scripts/auth.js login --email correct-user@example.com ``` 4. Retry the original request with the same `--email`. ## Short Gmail counting example ```bash node scripts/workspace.js exec --email user@example.com <<'JS' const gmail = google.gmail({ version: 'v1', auth }); let trash = 0; let pageToken; do { const res = await gmail.users.messages.list({ userId: 'me', q: 'in:trash', maxResults: 500, pageToken, fields: 'messages/id,nextPageToken', }); trash += (res.data.messages || []).length; pageToken = res.data.nextPageToken; } while (pageToken); return { currentlyInTrash: trash }; JS ``` ## Setup + auth ```bash node scripts/auth.js login --email user@example.com ``` Notes: - Dependencies auto-install on first run. - Default auth mode is **cloud** (no local `credentials.json` needed). - Optional local mode: `GOOGLE_WORKSPACE_AUTH_MODE=local` and credentials at `~/.pi/google-workspace/credentials.json`. - Useful diagnostics: ```bash node scripts/auth.js accounts node scripts/auth.js status --email user@example.com node scripts/auth.js clear --email user@example.com ```