Luigit
repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

pi/agent/skills/google-workspace/references/workflows.md

Raw
Rendered preview

Google Workspace workflows

  • Scripts run from this skill directory; use node scripts/....
  • scripts/auth.js handles login, account status, account enumeration, and token clearing.
  • scripts/workspace.js accepts only exec; each execution requires --email.
  • Tokens are stored per email under ~/.pi/google-workspace/tokens/.

Select an account

  • No account is implicit; if the user did not name one, list signed-in profiles and ask which one to use.
node scripts/auth.js accounts
  • Verify identity with workspace.whoAmI() when account mismatch is possible.
  • Never print token contents.

Execute API requests

  • Keep one execution per request where practical; request only needed fields and use Promise.all for independent calls.
  • Use Google Workspace developer docs, the API Explorer, and OAuth scope reference for current services, methods, parameters, versions, and required scopes.
  • The execution context exposes auth, google, workspace.accountEmail, workspace.call(service, methodPath, params, {version}), workspace.service(service, {version}), and workspace.whoAmI().
  • --timeout <ms> defaults to 30000 and is capped at 300000; --scopes s1,s2 selects scopes; --script 'return 42' supplies inline code.
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
  • For direct client access, google is the googleapis root and auth is the authorized OAuth client.
  • Example counting Gmail trash across pages:
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

Auth and recovery

  • Login explicitly for the selected account with node scripts/auth.js login --email user@example.com.
  • Dependencies are installed automatically on first use; default auth mode is cloud.
  • Local auth is optional: set GOOGLE_WORKSPACE_AUTH_MODE=local and provide ~/.pi/google-workspace/credentials.json.
  • node scripts/auth.js status --email ... reports account and token metadata without token values; clear --email ... removes that account's token.
  • On 401/403/unauthorized/insufficient-permission errors, inspect known profiles, verify the intended email, then sign in that profile again only if needed; retry with the same --email.
  • Never print OAuth token contents or request them from the user.
# Google Workspace workflows

- Scripts run from this skill directory; use `node scripts/...`.
- `scripts/auth.js` handles login, account status, account enumeration, and token clearing.
- `scripts/workspace.js` accepts only `exec`; each execution requires `--email`.
- Tokens are stored per email under `~/.pi/google-workspace/tokens/`.

## Select an account

- No account is implicit; if the user did not name one, list signed-in profiles and ask which one to use.

```sh
node scripts/auth.js accounts
```

- Verify identity with `workspace.whoAmI()` when account mismatch is possible.
- Never print token contents.

## Execute API requests

- Keep one execution per request where practical; request only needed fields and use `Promise.all` for independent calls.
- Use [Google Workspace developer docs](https://developers.google.com/workspace), the [API Explorer](https://developers.google.com/apis-explorer), and [OAuth scope reference](https://developers.google.com/identity/protocols/oauth2/scopes) for current services, methods, parameters, versions, and required scopes.
- The execution context exposes `auth`, `google`, `workspace.accountEmail`, `workspace.call(service, methodPath, params, {version})`, `workspace.service(service, {version})`, and `workspace.whoAmI()`.
- `--timeout <ms>` defaults to 30000 and is capped at 300000; `--scopes s1,s2` selects scopes; `--script 'return 42'` supplies inline code.

```sh
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
```

- For direct client access, `google` is the `googleapis` root and `auth` is the authorized OAuth client.
- Example counting Gmail trash across pages:

```sh
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
```

## Auth and recovery

- Login explicitly for the selected account with `node scripts/auth.js login --email user@example.com`.
- Dependencies are installed automatically on first use; default auth mode is cloud.
- Local auth is optional: set `GOOGLE_WORKSPACE_AUTH_MODE=local` and provide `~/.pi/google-workspace/credentials.json`.
- `node scripts/auth.js status --email ...` reports account and token metadata without token values; `clear --email ...` removes that account's token.
- On 401/403/unauthorized/insufficient-permission errors, inspect known profiles, verify the intended email, then sign in that profile again only if needed; retry with the same `--email`.
- Never print OAuth token contents or request them from the user.