gworkspace 0.2.1

package/dist/cli.js

@@ -0,0 +1,99 @@
+import { authorize, commandAuthLogin, commandAuthLogout, commandAuthStatus, } from './auth/index.js';
+import { resolveCredentialsPath } from './config.js';
+import { commandCalendarList } from './commands/calendar.js';
+import { commandChatMessages, commandChatSpaces } from './commands/chat.js';
+import { commandDriveGet, commandDriveRecent, commandDriveSearch } from './commands/drive.js';
+import { commandGmailGet, commandGmailSearch } from './commands/gmail.js';
+import { commandTimeDate, commandTimeNow, commandTimeZone } from './commands/time.js';
+import { optString, parseArgs } from './lib/args.js';
+import { fail } from './lib/io.js';
+import { usage } from './usage.js';
+export async function runCli(argv) {
+    const { positional, options } = parseArgs(argv);
+    const [domain, command, subcommand] = positional;
+    const helpRequested = options.help === true || options.h === true;
+    if (!domain)
+        usage();
+    if (domain === 'help')
+        usage(command);
+    if (helpRequested)
+        usage(domain);
+    if (!command && ['auth', 'calendar', 'gmail', 'drive', 'chat', 'time'].includes(domain)) {
+        usage(domain);
+    }
+    if (domain === 'auth' && command === 'status')
+        commandAuthStatus();
+    if (domain === 'auth' && command === 'login')
+        await commandAuthLogin(options);
+    if (domain === 'auth' && command === 'logout')
+        commandAuthLogout();
+    if (domain === 'time' && command === 'now')
+        commandTimeNow();
+    if (domain === 'time' && command === 'date')
+        commandTimeDate();
+    if (domain === 'time' && command === 'zone')
+        commandTimeZone();
+    const alias = domain;
+    if (alias === 'calendar_getEvents') {
+        const auth = await authorize(resolveCredentialsPath(options));
+        const patched = {
+            ...options,
+            from: optString(options, 'timeMin') || optString(options, 'from') || true,
+            to: optString(options, 'timeMax') || optString(options, 'to') || true,
+            max: optString(options, 'maxResults') || optString(options, 'max') || true,
+        };
+        await commandCalendarList(auth, patched);
+    }
+    if (alias === 'gmail_search') {
+        const auth = await authorize(resolveCredentialsPath(options));
+        await commandGmailSearch(auth, options);
+    }
+    if (alias === 'drive_search') {
+        const auth = await authorize(resolveCredentialsPath(options));
+        await commandDriveSearch(auth, options);
+    }
+    if (domain === 'calendar' && command === 'list') {
+        const auth = await authorize(resolveCredentialsPath(options));
+        await commandCalendarList(auth, {
+            ...options,
+            today: subcommand === 'today' ? true : options.today,
+        });
+    }
+    if (domain === 'gmail' && command === 'search') {
+        const auth = await authorize(resolveCredentialsPath(options));
+        await commandGmailSearch(auth, options);
+    }
+    if (domain === 'gmail' && command === 'list' && subcommand === 'today') {
+        const auth = await authorize(resolveCredentialsPath(options));
+        await commandGmailSearch(auth, { ...options, today: true });
+    }
+    if (domain === 'gmail' && command === 'get') {
+        const auth = await authorize(resolveCredentialsPath(options));
+        await commandGmailGet(auth, options);
+    }
+    if (domain === 'drive' && command === 'search') {
+        const auth = await authorize(resolveCredentialsPath(options));
+        await commandDriveSearch(auth, options);
+    }
+    if (domain === 'drive' && command === 'recent') {
+        const auth = await authorize(resolveCredentialsPath(options));
+        await commandDriveRecent(auth, options);
+    }
+    if (domain === 'drive' && command === 'get') {
+        const auth = await authorize(resolveCredentialsPath(options));
+        await commandDriveGet(auth, options);
+    }
+    if (domain === 'chat' && command === 'spaces') {
+        const auth = await authorize(resolveCredentialsPath(options));
+        await commandChatSpaces(auth, options);
+    }
+    if (domain === 'chat' && command === 'messages') {
+        const auth = await authorize(resolveCredentialsPath(options));
+        await commandChatMessages(auth, options);
+    }
+    if (domain === 'chat' && command === 'list' && subcommand === 'today') {
+        const auth = await authorize(resolveCredentialsPath(options));
+        await commandChatMessages(auth, { ...options, today: true });
+    }
+    fail(`Unknown command: ${[domain, command, subcommand].filter(Boolean).join(' ')}`);
+}

package/dist/commands/calendar.js

@@ -0,0 +1,47 @@
+import { google } from 'googleapis';
+import { optNumber, optString } from '../lib/args.js';
+import { output } from '../lib/io.js';
+function getTodayRangeIso() {
+    const start = new Date();
+    start.setHours(0, 0, 0, 0);
+    const end = new Date(start);
+    end.setDate(end.getDate() + 1);
+    return { start: start.toISOString(), end: end.toISOString() };
+}
+export async function commandCalendarList(auth, options) {
+    const calendar = google.calendar({ version: 'v3', auth });
+    const fromOption = optString(options, 'from');
+    const toOption = optString(options, 'to');
+    const useToday = options.today === true;
+    const todayRange = getTodayRangeIso();
+    const now = new Date();
+    const from = fromOption || (useToday ? todayRange.start : now.toISOString());
+    const to = toOption || (useToday ? todayRange.end : new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000).toISOString());
+    const max = Math.max(1, Math.min(optNumber(options, 'max', 20), 250));
+    const res = await calendar.events.list({
+        calendarId: optString(options, 'calendarId') || 'primary',
+        timeMin: from,
+        timeMax: to,
+        singleEvents: true,
+        orderBy: 'startTime',
+        maxResults: max,
+    });
+    const items = res.data.items || [];
+    output({
+        ok: true,
+        action: 'calendar.list',
+        today: useToday,
+        from,
+        to,
+        count: items.length,
+        events: items.map((item) => ({
+            id: item.id,
+            status: item.status,
+            summary: item.summary,
+            description: item.description,
+            start: item.start,
+            end: item.end,
+            htmlLink: item.htmlLink,
+        })),
+    });
+}

package/dist/commands/chat.js

@@ -0,0 +1,82 @@
+import { google } from 'googleapis';
+import { optNumber, optString } from '../lib/args.js';
+import { fail, output } from '../lib/io.js';
+function getTodayStartLocal() {
+    const start = new Date();
+    start.setHours(0, 0, 0, 0);
+    return start;
+}
+function isTodayLocal(isoValue) {
+    if (typeof isoValue !== 'string')
+        return false;
+    const date = new Date(isoValue);
+    if (Number.isNaN(date.getTime()))
+        return false;
+    const start = getTodayStartLocal();
+    const end = new Date(start);
+    end.setDate(end.getDate() + 1);
+    return date >= start && date < end;
+}
+export async function commandChatSpaces(auth, options) {
+    const chat = google.chat({ version: 'v1', auth });
+    const max = Math.max(1, Math.min(optNumber(options, 'max', 20), 1000));
+    const res = await chat.spaces.list({
+        pageSize: max,
+        pageToken: optString(options, 'pageToken'),
+        filter: optString(options, 'filter'),
+    });
+    const spaces = res.data.spaces || [];
+    output({
+        ok: true,
+        action: 'chat.spaces',
+        count: spaces.length,
+        nextPageToken: res.data.nextPageToken || null,
+        spaces: spaces.map((space) => ({
+            name: space.name,
+            displayName: space.displayName,
+            spaceType: space.spaceType,
+            spaceThreadingState: space.spaceThreadingState,
+            createTime: space.createTime,
+            lastActiveTime: space.lastActiveTime,
+            membershipCount: space.membershipCount,
+            singleUserBotDm: space.singleUserBotDm,
+            externalUserAllowed: space.externalUserAllowed,
+        })),
+    });
+}
+export async function commandChatMessages(auth, options) {
+    const parent = optString(options, 'space');
+    if (!parent)
+        fail('Missing required --space for chat messages.');
+    const chat = google.chat({ version: 'v1', auth });
+    const max = Math.max(1, Math.min(optNumber(options, 'max', 20), 1000));
+    const useToday = options.today === true;
+    const res = await chat.spaces.messages.list({
+        parent,
+        pageSize: max,
+        pageToken: optString(options, 'pageToken'),
+        filter: optString(options, 'filter'),
+        orderBy: optString(options, 'orderBy') || (useToday ? 'createTime desc' : undefined),
+    });
+    const allMessages = res.data.messages || [];
+    const messages = useToday
+        ? allMessages.filter((message) => isTodayLocal(message.createTime))
+        : allMessages;
+    output({
+        ok: true,
+        action: 'chat.messages',
+        today: useToday,
+        space: parent,
+        count: messages.length,
+        nextPageToken: res.data.nextPageToken || null,
+        messages: messages.map((message) => ({
+            name: message.name,
+            createTime: message.createTime,
+            lastUpdateTime: message.lastUpdateTime,
+            sender: message.sender?.name || null,
+            thread: message.thread?.name || null,
+            text: message.text || '',
+            argumentText: message.argumentText || '',
+        })),
+    });
+}

package/dist/commands/drive.js

@@ -0,0 +1,52 @@
+import { google } from 'googleapis';
+import { optNumber, optString } from '../lib/args.js';
+import { fail, output } from '../lib/io.js';
+export async function commandDriveSearch(auth, options) {
+    const drive = google.drive({ version: 'v3', auth });
+    const max = Math.max(1, Math.min(optNumber(options, 'max', 20), 200));
+    const res = await drive.files.list({
+        q: optString(options, 'query') || 'trashed = false',
+        pageSize: max,
+        fields: 'files(id,name,mimeType,modifiedTime,owners,webViewLink),nextPageToken',
+        includeItemsFromAllDrives: true,
+        supportsAllDrives: true,
+    });
+    const files = res.data.files || [];
+    output({
+        ok: true,
+        action: 'drive.search',
+        count: files.length,
+        nextPageToken: res.data.nextPageToken || null,
+        files,
+    });
+}
+export async function commandDriveRecent(auth, options) {
+    const drive = google.drive({ version: 'v3', auth });
+    const max = Math.max(1, Math.min(optNumber(options, 'max', 20), 200));
+    const res = await drive.files.list({
+        q: 'trashed = false',
+        orderBy: 'modifiedTime desc',
+        pageSize: max,
+        fields: 'files(id,name,mimeType,modifiedTime,owners,webViewLink),nextPageToken',
+        includeItemsFromAllDrives: true,
+        supportsAllDrives: true,
+    });
+    output({
+        ok: true,
+        action: 'drive.recent',
+        count: (res.data.files || []).length,
+        files: res.data.files || [],
+    });
+}
+export async function commandDriveGet(auth, options) {
+    const id = optString(options, 'id');
+    if (!id)
+        fail('Missing required --id for drive get.');
+    const drive = google.drive({ version: 'v3', auth });
+    const res = await drive.files.get({
+        fileId: id,
+        fields: 'id,name,mimeType,modifiedTime,owners,webViewLink,size',
+        supportsAllDrives: true,
+    });
+    output({ ok: true, action: 'drive.get', file: res.data });
+}

package/dist/commands/gmail.js

@@ -0,0 +1,72 @@
+import { google } from 'googleapis';
+import { optNumber, optString } from '../lib/args.js';
+import { fail, output } from '../lib/io.js';
+function formatGmailDate(d) {
+    const year = d.getFullYear();
+    const month = `${d.getMonth() + 1}`.padStart(2, '0');
+    const day = `${d.getDate()}`.padStart(2, '0');
+    return `${year}/${month}/${day}`;
+}
+function getTodayGmailQuery() {
+    const start = new Date();
+    start.setHours(0, 0, 0, 0);
+    const end = new Date(start);
+    end.setDate(end.getDate() + 1);
+    return `after:${formatGmailDate(start)} before:${formatGmailDate(end)}`;
+}
+export async function commandGmailSearch(auth, options) {
+    const gmail = google.gmail({ version: 'v1', auth });
+    const max = Math.max(1, Math.min(optNumber(options, 'max', 20), 100));
+    const baseQuery = optString(options, 'query') || '';
+    const useToday = options.today === true;
+    const query = useToday ? `${baseQuery} ${getTodayGmailQuery()}`.trim() : baseQuery;
+    const res = await gmail.users.messages.list({
+        userId: 'me',
+        q: query,
+        maxResults: max,
+        pageToken: optString(options, 'pageToken'),
+    });
+    const messages = res.data.messages || [];
+    output({
+        ok: true,
+        action: 'gmail.search',
+        today: useToday,
+        query,
+        count: messages.length,
+        nextPageToken: res.data.nextPageToken || null,
+        messages: messages.map((m) => ({ id: m.id, threadId: m.threadId })),
+    });
+}
+export async function commandGmailGet(auth, options) {
+    const id = optString(options, 'id');
+    if (!id)
+        fail('Missing required --id for gmail get.');
+    const gmail = google.gmail({ version: 'v1', auth });
+    const res = await gmail.users.messages.get({
+        userId: 'me',
+        id,
+        format: 'metadata',
+        metadataHeaders: ['From', 'To', 'Subject', 'Date'],
+    });
+    const headers = res.data.payload?.headers || [];
+    const map = headers.reduce((acc, h) => {
+        if (h.name && h.value)
+            acc[h.name.toLowerCase()] = h.value;
+        return acc;
+    }, {});
+    output({
+        ok: true,
+        action: 'gmail.get',
+        message: {
+            id: res.data.id,
+            threadId: res.data.threadId,
+            labelIds: res.data.labelIds || [],
+            snippet: res.data.snippet || '',
+            subject: map.subject || '',
+            from: map.from || '',
+            to: map.to || '',
+            date: map.date || '',
+            internalDate: res.data.internalDate || null,
+        },
+    });
+}

package/dist/commands/time.js

@@ -0,0 +1,31 @@
+import { output } from '../lib/io.js';
+export function commandTimeNow() {
+    const now = new Date();
+    const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    output({
+        ok: true,
+        action: 'time.now',
+        utc: now.toISOString(),
+        localDate: now.toLocaleDateString('en-CA', { timeZone }),
+        localTime: now.toLocaleTimeString('en-GB', { hour12: false, timeZone }),
+        timeZone,
+    });
+}
+export function commandTimeDate() {
+    const now = new Date();
+    const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    output({
+        ok: true,
+        action: 'time.date',
+        utc: now.toISOString().slice(0, 10),
+        local: now.toLocaleDateString('en-CA', { timeZone }),
+        timeZone,
+    });
+}
+export function commandTimeZone() {
+    output({
+        ok: true,
+        action: 'time.zone',
+        timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    });
+}

package/dist/config.js

@@ -0,0 +1,23 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { optString } from './lib/args.js';
+export const SCOPES = [
+    'https://www.googleapis.com/auth/calendar.readonly',
+    'https://www.googleapis.com/auth/gmail.readonly',
+    'https://www.googleapis.com/auth/drive.readonly',
+    'https://www.googleapis.com/auth/chat.spaces.readonly',
+    'https://www.googleapis.com/auth/chat.messages.readonly',
+];
+export const CONFIG_DIR = process.env.GWORKSPACE_CONFIG_DIR ||
+    path.join(os.homedir(), '.config', 'gworkspace');
+export const TOKEN_PATH = path.join(CONFIG_DIR, 'token.json');
+export const CREDENTIALS_PATH = process.env.GOOGLE_OAUTH_CREDENTIALS ||
+    path.join(CONFIG_DIR, 'credentials.json');
+export function ensureConfigDir() {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+}
+export function resolveCredentialsPath(options) {
+    const fromOption = optString(options, 'credentials');
+    return fromOption ? path.resolve(fromOption) : CREDENTIALS_PATH;
+}

package/dist/index.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from './cli.js';
+import { fail } from './lib/io.js';
+runCli(process.argv.slice(2)).catch((error) => {
+    const msg = error instanceof Error ? error.message : String(error);
+    fail('Command failed.', msg);
+});

package/dist/lib/args.js

@@ -0,0 +1,65 @@
+export function parseArgs(argv) {
+    const positional = [];
+    const options = {};
+    const setOpt = (key, value) => {
+        const current = options[key];
+        if (current === undefined) {
+            options[key] = value;
+            return;
+        }
+        if (Array.isArray(current)) {
+            options[key] = [...current, value];
+            return;
+        }
+        options[key] = [current, value];
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (!token)
+            continue;
+        if (token === '--') {
+            positional.push(...argv.slice(i + 1));
+            break;
+        }
+        if (token === '-h') {
+            setOpt('help', true);
+            setOpt('h', true);
+            continue;
+        }
+        if (!token.startsWith('--')) {
+            positional.push(token);
+            continue;
+        }
+        const eq = token.indexOf('=');
+        if (eq > 2) {
+            setOpt(token.slice(2, eq), token.slice(eq + 1));
+            continue;
+        }
+        const key = token.slice(2);
+        const next = argv[i + 1];
+        if (!next || next.startsWith('--')) {
+            setOpt(key, true);
+            continue;
+        }
+        setOpt(key, next);
+        i += 1;
+    }
+    return { positional, options };
+}
+export function optString(options, key) {
+    const value = options[key];
+    if (value === undefined || typeof value === 'boolean')
+        return undefined;
+    if (Array.isArray(value))
+        return String(value[value.length - 1]);
+    return String(value);
+}
+export function optNumber(options, key, fallback) {
+    const raw = optString(options, key);
+    if (!raw)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isNaN(parsed))
+        return fallback;
+    return parsed;
+}

package/dist/lib/io.js

@@ -0,0 +1,11 @@
+export function output(payload, code = 0) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    process.exit(code);
+}
+export function fail(message, details) {
+    output({
+        ok: false,
+        error: message,
+        details: details ?? null,
+    }, 1);
+}

package/dist/lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/usage.js

@@ -0,0 +1,90 @@
+import { CREDENTIALS_PATH, TOKEN_PATH } from './config.js';
+const HELP = {
+    auth: {
+        summary: 'Authenticate gw with Google Workspace',
+        commands: [
+            'gw auth login [--credentials path/to/credentials.json] [--no-open]',
+            'gw auth status',
+            'gw auth logout',
+        ],
+    },
+    calendar: {
+        summary: 'Read calendar events',
+        commands: [
+            'gw calendar list --from <ISO> --to <ISO> [--calendarId primary] [--max 20]',
+            'gw calendar list today [--calendarId primary] [--max 20]',
+            'gw calendar_getEvents --timeMin <ISO> --timeMax <ISO> [--calendarId primary]',
+        ],
+    },
+    gmail: {
+        summary: 'Search and read Gmail messages',
+        commands: [
+            'gw gmail search --query "newer_than:7d" [--max 20]',
+            'gw gmail list today [--max 20]',
+            'gw gmail get --id <messageId>',
+            'gw gmail_search --query "..." --max 20',
+        ],
+    },
+    drive: {
+        summary: 'Search and inspect Drive files',
+        commands: [
+            'gw drive search --query "trashed = false" [--max 20]',
+            'gw drive recent [--max 20]',
+            'gw drive get --id <fileId>',
+            'gw drive_search --query "..." --max 20',
+        ],
+    },
+    chat: {
+        summary: 'Read Google Chat spaces and messages',
+        commands: [
+            'gw chat spaces [--max 20] [--filter "spaceType = SPACE"]',
+            'gw chat messages --space spaces/<spaceId> [--max 20]',
+            'gw chat list today --space spaces/<spaceId> [--max 20]',
+        ],
+    },
+    time: {
+        summary: 'Print local time context',
+        commands: ['gw time now', 'gw time date', 'gw time zone'],
+    },
+};
+function printText(text) {
+    process.stdout.write(`${text}\n`);
+    process.exit(0);
+}
+export function usage(topic) {
+    const normalized = topic?.trim().toLowerCase();
+    const selected = normalized ? HELP[normalized] : undefined;
+    if (selected) {
+        const topicName = normalized;
+        const commands = selected.commands.map((line) => `  ${line}`).join('\n');
+        printText([
+            `${topicName.toUpperCase()} COMMANDS`,
+            commands,
+            '',
+            'LEARN MORE',
+            `  Use \`gw ${topicName} --help\` for command usage.`,
+        ].join('\n'));
+    }
+    const core = Object.entries(HELP)
+        .map(([name, def]) => `  ${name.padEnd(14)}${def.summary}`)
+        .join('\n');
+    printText([
+        'Work seamlessly with Google Workspace from the command line.',
+        '',
+        'USAGE',
+        '  gw <command> <subcommand> [flags]',
+        '',
+        'CORE COMMANDS',
+        core,
+        '',
+        'FLAGS',
+        '  --help    Show help for command',
+        '',
+        'CONFIG FILES',
+        `  credentials: ${CREDENTIALS_PATH}`,
+        `  token:       ${TOKEN_PATH}`,
+        '',
+        'LEARN MORE',
+        '  Use `gw <command> --help` for more information about a command.',
+    ].join('\n'));
+}

package/docs/auth.md

@@ -0,0 +1,56 @@
+# Auth Flow
+
+`gw auth login` uses a browser OAuth loop with Google Desktop OAuth credentials:
+
+1. Start a localhost callback server on a random free port.
+2. Generate Google OAuth URL with the configured scopes.
+3. Open the browser automatically.
+4. Receive callback at `/oauth2callback`.
+5. Exchange auth code for tokens and store token JSON.
+
+## Files
+
+- Credentials: `~/.config/gworkspace/credentials.json` (default)
+- Token: `~/.config/gworkspace/token.json`
+
+Use an explicit credentials path:
+
+```bash
+gw auth login --credentials /path/to/credentials.json
+```
+
+Or env var:
+
+```bash
+export GOOGLE_OAUTH_CREDENTIALS=/path/to/credentials.json
+```
+
+## Flags
+
+- `--no-open`: prints/uses auth URL without auto-launching browser.
+- `--credentials`: explicit Desktop OAuth credentials file path.
+
+## Create Credentials (Google Cloud Console)
+
+1. Open Google Cloud Console, select or create a project.
+2. Enable APIs you need: Calendar, Gmail, Drive, Google Chat.
+3. Configure OAuth consent screen.
+4. Go to Credentials -> Create Credentials -> OAuth client ID.
+5. Select Application type `Desktop app`.
+6. Download the JSON and save it as `~/.config/gworkspace/credentials.json`.
+
+## Scope updates
+
+If new scopes are added (for example Chat read-only scopes), your existing token may not include them.
+Run:
+
+```bash
+gw auth logout
+gw auth login
+```
+
+## Troubleshooting
+
+- `Credentials file not found`: create/download Desktop OAuth credentials and pass `--credentials`, or place the file at `~/.config/gworkspace/credentials.json`.
+- `Invalid credentials file`: use Desktop OAuth client JSON with `installed` or `web` payload.
+- `Authentication timed out`: reopen login and complete consent in browser within 5 minutes.