@plosson/agentio 0.4.3 → 0.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plosson/agentio",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "CLI for LLM agents to interact with communication and tracking services",
   "type": "module",
   "license": "MIT",

package/src/auth/oauth.ts

@@ -44,7 +44,14 @@ const GTASKS_SCOPES = [
   'https://www.googleapis.com/auth/userinfo.email',     // get email for profile naming
 ];
 
-const SCOPES: Record<'gmail' | 'gchat' | 'gdocs' | 'gdrive-readonly' | 'gdrive-full' | 'gcal' | 'gtasks', string[]> = {
+const GSHEETS_SCOPES = [
+  'https://www.googleapis.com/auth/spreadsheets',       // full access to spreadsheets
+  'https://www.googleapis.com/auth/drive.file',         // create/access files created by this app
+  'https://www.googleapis.com/auth/drive.readonly',     // list spreadsheets, export, copy
+  'https://www.googleapis.com/auth/userinfo.email',     // get email for profile naming
+];
+
+const SCOPES: Record<'gmail' | 'gchat' | 'gdocs' | 'gdrive-readonly' | 'gdrive-full' | 'gcal' | 'gtasks' | 'gsheets', string[]> = {
   gmail: GMAIL_SCOPES,
   gchat: GCHAT_SCOPES,
   gdocs: GDOCS_SCOPES,
@@ -52,9 +59,10 @@ const SCOPES: Record<'gmail' | 'gchat' | 'gdocs' | 'gdrive-readonly' | 'gdrive-f
   'gdrive-full': GDRIVE_FULL_SCOPES,
   gcal: GCAL_SCOPES,
   gtasks: GTASKS_SCOPES,
+  gsheets: GSHEETS_SCOPES,
 };
 
-export type OAuthService = 'gmail' | 'gchat' | 'gdocs' | 'gdrive-readonly' | 'gdrive-full' | 'gcal' | 'gtasks';
+export type OAuthService = 'gmail' | 'gchat' | 'gdocs' | 'gdrive-readonly' | 'gdrive-full' | 'gcal' | 'gtasks' | 'gsheets';
 
 export async function performOAuthFlow(
   service: OAuthService

package/src/commands/gsheets.ts

@@ -0,0 +1,365 @@
+import { Command } from 'commander';
+import { writeFile } from 'fs/promises';
+import { google } from 'googleapis';
+import { createGoogleAuth } from '../auth/token-manager';
+import { setCredentials } from '../auth/token-store';
+import { setProfile } from '../config/config-manager';
+import { createProfileCommands } from '../utils/profile-commands';
+import { createClientGetter } from '../utils/client-factory';
+import { performOAuthFlow } from '../auth/oauth';
+import { GSheetsClient } from '../services/gsheets/client';
+import {
+  printGSheetsList,
+  printGSheetsMetadata,
+  printGSheetsValues,
+  printGSheetsUpdateResult,
+  printGSheetsAppendResult,
+  printGSheetsClearResult,
+  printGSheetsCreated,
+} from '../utils/output';
+import { CliError, handleError } from '../utils/errors';
+import type { GSheetsCredentials } from '../types/gsheets';
+
+const getGSheetsClient = createClientGetter<GSheetsCredentials, GSheetsClient>({
+  service: 'gsheets',
+  createClient: (credentials) => new GSheetsClient(credentials),
+});
+
+/**
+ * Parse values from CLI arguments or JSON
+ * Supports two formats:
+ * - Simple: comma-separated rows, pipe-separated cells (e.g., "a|b|c,d|e|f")
+ * - JSON: 2D array (e.g., '[["a","b"],["c","d"]]')
+ */
+function parseValues(valueArgs: string[], valuesJson?: string): unknown[][] {
+  if (valuesJson) {
+    try {
+      const parsed = JSON.parse(valuesJson);
+      if (!Array.isArray(parsed)) {
+        throw new Error('JSON must be a 2D array');
+      }
+      return parsed;
+    } catch (err) {
+      throw new CliError('INVALID_PARAMS', `Invalid JSON values: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+
+  if (valueArgs.length === 0) {
+    throw new CliError('INVALID_PARAMS', 'No values provided', 'Provide values as args or via --values-json');
+  }
+
+  // Parse simple format: comma-separated rows, pipe-separated cells
+  const rawValues = valueArgs.join(' ');
+  const rows = rawValues.split(',');
+  return rows.map((row) => {
+    const cells = row.trim().split('|');
+    return cells.map((cell) => cell.trim());
+  });
+}
+
+export function registerGSheetsCommands(program: Command): void {
+  const gsheets = program.command('gsheets').description('Google Sheets operations');
+
+  gsheets
+    .command('list')
+    .description('List recent spreadsheets')
+    .option('--profile <name>', 'Profile name')
+    .option('--limit <n>', 'Number of spreadsheets', '10')
+    .option('--query <query>', 'Drive search query filter')
+    .addHelpText(
+      'after',
+      `
+Query Syntax Examples:
+
+  Name search:
+    --query "name contains 'budget'"      Spreadsheets with "budget" in name
+    --query "name = 'Q1 Report'"          Exact name match
+
+  Ownership:
+    --query "'me' in owners"              Spreadsheets you own
+    --query "'user@example.com' in owners"
+
+  Date filters:
+    --query "modifiedTime > '2024-01-01'" Modified after date
+    --query "createdTime > '2024-01-01'"  Created after date
+
+  Combined:
+    --query "name contains 'sales' and modifiedTime > '2024-01-01'"
+`
+    )
+    .action(async (options) => {
+      try {
+        const { client } = await getGSheetsClient(options.profile);
+        const spreadsheets = await client.list({
+          limit: parseInt(options.limit, 10),
+          query: options.query,
+        });
+        printGSheetsList(spreadsheets);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gsheets
+    .command('get')
+    .argument('<spreadsheet-id-or-url>', 'Spreadsheet ID or URL')
+    .argument('<range>', 'Range in A1 notation (e.g., Sheet1!A1:B10)')
+    .description('Get values from a range')
+    .option('--profile <name>', 'Profile name')
+    .option('--dimension <dim>', 'Major dimension: ROWS or COLUMNS')
+    .option('--render <opt>', 'Value render: FORMATTED_VALUE, UNFORMATTED_VALUE, or FORMULA')
+    .action(async (spreadsheetId: string, range: string, options) => {
+      try {
+        const { client } = await getGSheetsClient(options.profile);
+        const result = await client.get(spreadsheetId, range, {
+          majorDimension: options.dimension,
+          valueRenderOption: options.render,
+        });
+        printGSheetsValues(result);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gsheets
+    .command('update')
+    .argument('<spreadsheet-id-or-url>', 'Spreadsheet ID or URL')
+    .argument('<range>', 'Range in A1 notation (e.g., Sheet1!A1:B2)')
+    .argument('[values...]', 'Values (comma-separated rows, pipe-separated cells)')
+    .description('Update values in a range')
+    .option('--profile <name>', 'Profile name')
+    .option('--values-json <json>', 'Values as JSON 2D array')
+    .option('--input <opt>', 'Value input option: RAW or USER_ENTERED', 'USER_ENTERED')
+    .addHelpText(
+      'after',
+      `
+Value Formats:
+
+  Simple format (comma = row separator, pipe = cell separator):
+    agentio gsheets update <id> Sheet1!A1:B2 "a|b,c|d"
+    Results in:
+      A1=a  B1=b
+      A2=c  B2=d
+
+  JSON format:
+    agentio gsheets update <id> Sheet1!A1:B2 --values-json '[["a","b"],["c","d"]]'
+
+Input Options:
+  RAW          - Values are stored exactly as entered (no parsing)
+  USER_ENTERED - Values are parsed as if typed in the UI (formulas, dates, etc.)
+`
+    )
+    .action(async (spreadsheetId: string, range: string, valueArgs: string[], options) => {
+      try {
+        const values = parseValues(valueArgs, options.valuesJson);
+        const { client } = await getGSheetsClient(options.profile);
+        const result = await client.update(spreadsheetId, range, values, {
+          valueInputOption: options.input,
+        });
+        printGSheetsUpdateResult(result);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gsheets
+    .command('append')
+    .argument('<spreadsheet-id-or-url>', 'Spreadsheet ID or URL')
+    .argument('<range>', 'Range in A1 notation (e.g., Sheet1!A:C)')
+    .argument('[values...]', 'Values (comma-separated rows, pipe-separated cells)')
+    .description('Append values to a range')
+    .option('--profile <name>', 'Profile name')
+    .option('--values-json <json>', 'Values as JSON 2D array')
+    .option('--input <opt>', 'Value input option: RAW or USER_ENTERED', 'USER_ENTERED')
+    .option('--insert <opt>', 'Insert data option: OVERWRITE or INSERT_ROWS')
+    .addHelpText(
+      'after',
+      `
+Value Formats:
+
+  Simple format (comma = row separator, pipe = cell separator):
+    agentio gsheets append <id> Sheet1!A:C "a|b|c,d|e|f"
+    Appends two rows to columns A, B, C
+
+  JSON format:
+    agentio gsheets append <id> Sheet1!A:C --values-json '[["a","b","c"],["d","e","f"]]'
+
+Insert Options:
+  OVERWRITE   - New data overwrites existing data in the areas it is written
+  INSERT_ROWS - Rows are inserted for the new data
+`
+    )
+    .action(async (spreadsheetId: string, range: string, valueArgs: string[], options) => {
+      try {
+        const values = parseValues(valueArgs, options.valuesJson);
+        const { client } = await getGSheetsClient(options.profile);
+        const result = await client.append(spreadsheetId, range, values, {
+          valueInputOption: options.input,
+          insertDataOption: options.insert,
+        });
+        printGSheetsAppendResult(result);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gsheets
+    .command('clear')
+    .argument('<spreadsheet-id-or-url>', 'Spreadsheet ID or URL')
+    .argument('<range>', 'Range in A1 notation (e.g., Sheet1!A1:B10)')
+    .description('Clear values in a range')
+    .option('--profile <name>', 'Profile name')
+    .action(async (spreadsheetId: string, range: string, options) => {
+      try {
+        const { client } = await getGSheetsClient(options.profile);
+        const result = await client.clear(spreadsheetId, range);
+        printGSheetsClearResult(result);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gsheets
+    .command('metadata')
+    .argument('<spreadsheet-id-or-url>', 'Spreadsheet ID or URL')
+    .description('Get spreadsheet metadata')
+    .option('--profile <name>', 'Profile name')
+    .action(async (spreadsheetId: string, options) => {
+      try {
+        const { client } = await getGSheetsClient(options.profile);
+        const metadata = await client.metadata(spreadsheetId);
+        printGSheetsMetadata(metadata);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gsheets
+    .command('create')
+    .argument('<title>', 'Spreadsheet title')
+    .description('Create a new spreadsheet')
+    .option('--profile <name>', 'Profile name')
+    .option('--sheets <names>', 'Comma-separated sheet names to create')
+    .action(async (title: string, options) => {
+      try {
+        const { client } = await getGSheetsClient(options.profile);
+        const sheetNames = options.sheets ? options.sheets.split(',').map((n: string) => n.trim()) : undefined;
+        const result = await client.create(title, sheetNames);
+        printGSheetsCreated(result);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gsheets
+    .command('copy')
+    .argument('<spreadsheet-id-or-url>', 'Spreadsheet ID or URL')
+    .argument('<title>', 'New spreadsheet title')
+    .description('Copy a spreadsheet')
+    .option('--profile <name>', 'Profile name')
+    .option('--parent <folder-id>', 'Destination folder ID')
+    .action(async (spreadsheetId: string, title: string, options) => {
+      try {
+        const { client } = await getGSheetsClient(options.profile);
+        const result = await client.copy(spreadsheetId, title, options.parent);
+        printGSheetsCreated(result);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gsheets
+    .command('export')
+    .argument('<spreadsheet-id-or-url>', 'Spreadsheet ID or URL')
+    .description('Export a spreadsheet to a file')
+    .option('--profile <name>', 'Profile name')
+    .requiredOption('--output <path>', 'Output file path')
+    .option('--format <fmt>', 'Export format: xlsx, pdf, csv, ods, tsv', 'xlsx')
+    .addHelpText(
+      'after',
+      `
+Export Formats:
+  xlsx - Microsoft Excel (default)
+  pdf  - PDF document
+  csv  - Comma-separated values (first sheet only)
+  ods  - OpenDocument Spreadsheet
+  tsv  - Tab-separated values (first sheet only)
+
+Examples:
+  agentio gsheets export <id> --output report.xlsx
+  agentio gsheets export <id> --output data.csv --format csv
+`
+    )
+    .action(async (spreadsheetId: string, options) => {
+      try {
+        const { client } = await getGSheetsClient(options.profile);
+        const format = options.format.toLowerCase();
+
+        if (!['xlsx', 'pdf', 'csv', 'ods', 'tsv'].includes(format)) {
+          throw new CliError('INVALID_PARAMS', `Unknown format: ${format}`, 'Use xlsx, pdf, csv, ods, or tsv');
+        }
+
+        const result = await client.export(spreadsheetId, format as 'xlsx' | 'pdf' | 'csv' | 'ods' | 'tsv');
+        await writeFile(options.output, result.data);
+        console.log(`Exported to ${options.output}`);
+        console.log(`  Format: ${format}`);
+        console.log(`  Size: ${result.data.length} bytes`);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  // Profile management
+  const profile = createProfileCommands<GSheetsCredentials>(gsheets, {
+    service: 'gsheets',
+    displayName: 'Google Sheets',
+    getExtraInfo: (credentials) => (credentials?.email ? ` - ${credentials.email}` : ''),
+  });
+
+  profile
+    .command('add')
+    .description('Add a new Google Sheets profile')
+    .option('--profile <name>', 'Profile name (auto-detected from email if not provided)')
+    .action(async (options) => {
+      try {
+        console.error('Starting OAuth flow for Google Sheets...\n');
+
+        const tokens = await performOAuthFlow('gsheets');
+        const auth = createGoogleAuth(tokens);
+
+        // Fetch user email for profile naming
+        let userEmail: string;
+        try {
+          const oauth2 = google.oauth2({ version: 'v2', auth });
+          const userInfo = await oauth2.userinfo.get();
+          userEmail = userInfo.data.email || '';
+          if (!userEmail) {
+            throw new Error('No email returned');
+          }
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          throw new CliError('AUTH_FAILED', `Failed to fetch user email: ${errorMessage}`, 'Ensure the account has an email address');
+        }
+
+        const profileName = options.profile || userEmail;
+
+        const credentials: GSheetsCredentials = {
+          accessToken: tokens.access_token,
+          refreshToken: tokens.refresh_token,
+          expiryDate: tokens.expiry_date,
+          tokenType: tokens.token_type,
+          scope: tokens.scope,
+          email: userEmail,
+        };
+
+        await setProfile('gsheets', profileName);
+        await setCredentials('gsheets', profileName, credentials);
+
+        console.log(`\nSuccess! Profile "${profileName}" configured.`);
+        console.log(`   Email: ${userEmail}`);
+        console.log(`   Test with: agentio gsheets list --profile ${profileName}`);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+}

package/src/index.ts

@@ -10,6 +10,7 @@ import { registerGDocsCommands } from './commands/gdocs';
 import { registerGDriveCommands } from './commands/gdrive';
 import { registerGitHubCommands } from './commands/github';
 import { registerGmailCommands } from './commands/gmail';
+import { registerGSheetsCommands } from './commands/gsheets';
 import { registerGTasksCommands } from './commands/gtasks';
 import { registerJiraCommands } from './commands/jira';
 import { registerRssCommands } from './commands/rss';
@@ -51,6 +52,7 @@ registerGDocsCommands(program);
 registerGDriveCommands(program);
 registerGitHubCommands(program);
 registerGmailCommands(program);
+registerGSheetsCommands(program);
 registerGTasksCommands(program);
 registerJiraCommands(program);
 registerRssCommands(program);

package/src/services/gsheets/client.ts

@@ -0,0 +1,362 @@
+import { google } from 'googleapis';
+import type { sheets_v4, drive_v3 } from 'googleapis';
+import { CliError, httpStatusToErrorCode, type ErrorCode } from '../../utils/errors';
+import type { ServiceClient, ValidationResult } from '../../types/service';
+import { GOOGLE_OAUTH_CONFIG } from '../../config/credentials';
+import type {
+  GSheetsCredentials,
+  GSheetsSpreadsheet,
+  GSheetsSheet,
+  GSheetsGetOptions,
+  GSheetsGetResult,
+  GSheetsUpdateOptions,
+  GSheetsUpdateResult,
+  GSheetsAppendOptions,
+  GSheetsAppendResult,
+  GSheetsClearResult,
+  GSheetsCreateResult,
+  GSheetsListOptions,
+  GSheetsListItem,
+} from '../../types/gsheets';
+
+export class GSheetsClient implements ServiceClient {
+  private credentials: GSheetsCredentials;
+  private sheets: sheets_v4.Sheets;
+  private drive: drive_v3.Drive;
+
+  constructor(credentials: GSheetsCredentials) {
+    this.credentials = credentials;
+    const auth = this.createOAuthClient();
+    this.sheets = google.sheets({ version: 'v4', auth });
+    this.drive = google.drive({ version: 'v3', auth });
+  }
+
+  async validate(): Promise<ValidationResult> {
+    try {
+      await this.drive.files.list({
+        pageSize: 1,
+        q: "mimeType='application/vnd.google-apps.spreadsheet'",
+      });
+      return { valid: true, info: this.credentials.email };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      if (message.includes('invalid_grant') || message.includes('Token has been expired or revoked')) {
+        return { valid: false, error: 'refresh token expired, re-authenticate' };
+      }
+      return { valid: false, error: message };
+    }
+  }
+
+  async list(options: GSheetsListOptions = {}): Promise<GSheetsListItem[]> {
+    const { limit = 10, query } = options;
+
+    try {
+      let q = "mimeType='application/vnd.google-apps.spreadsheet' and trashed=false";
+      if (query) {
+        q += ` and ${query}`;
+      }
+
+      const response = await this.drive.files.list({
+        pageSize: Math.min(limit, 100),
+        q,
+        fields: 'files(id,name,owners,createdTime,modifiedTime,webViewLink)',
+        orderBy: 'modifiedTime desc',
+      });
+
+      const files = response.data.files || [];
+      return files.map((file) => ({
+        id: file.id!,
+        title: file.name || 'Untitled',
+        owner: file.owners?.[0]?.displayName || file.owners?.[0]?.emailAddress || undefined,
+        createdTime: file.createdTime || undefined,
+        modifiedTime: file.modifiedTime || undefined,
+        webViewLink: file.webViewLink || `https://docs.google.com/spreadsheets/d/${file.id}`,
+      }));
+    } catch (err) {
+      this.throwApiError(err, 'list spreadsheets');
+    }
+  }
+
+  async get(spreadsheetIdOrUrl: string, range: string, options: GSheetsGetOptions = {}): Promise<GSheetsGetResult> {
+    const spreadsheetId = this.extractSpreadsheetId(spreadsheetIdOrUrl);
+    const cleanedRange = this.cleanRange(range);
+
+    try {
+      const call = this.sheets.spreadsheets.values.get({
+        spreadsheetId,
+        range: cleanedRange,
+        majorDimension: options.majorDimension,
+        valueRenderOption: options.valueRenderOption,
+      });
+
+      const response = await call;
+
+      return {
+        range: response.data.range || cleanedRange,
+        values: (response.data.values as unknown[][]) || [],
+      };
+    } catch (err) {
+      this.throwApiError(err, 'get values');
+    }
+  }
+
+  async update(
+    spreadsheetIdOrUrl: string,
+    range: string,
+    values: unknown[][],
+    options: GSheetsUpdateOptions = {}
+  ): Promise<GSheetsUpdateResult> {
+    const spreadsheetId = this.extractSpreadsheetId(spreadsheetIdOrUrl);
+    const cleanedRange = this.cleanRange(range);
+    const valueInputOption = options.valueInputOption || 'USER_ENTERED';
+
+    try {
+      const response = await this.sheets.spreadsheets.values.update({
+        spreadsheetId,
+        range: cleanedRange,
+        valueInputOption,
+        requestBody: {
+          values,
+        },
+      });
+
+      return {
+        updatedRange: response.data.updatedRange || cleanedRange,
+        updatedRows: response.data.updatedRows || 0,
+        updatedColumns: response.data.updatedColumns || 0,
+        updatedCells: response.data.updatedCells || 0,
+      };
+    } catch (err) {
+      this.throwApiError(err, 'update values');
+    }
+  }
+
+  async append(
+    spreadsheetIdOrUrl: string,
+    range: string,
+    values: unknown[][],
+    options: GSheetsAppendOptions = {}
+  ): Promise<GSheetsAppendResult> {
+    const spreadsheetId = this.extractSpreadsheetId(spreadsheetIdOrUrl);
+    const cleanedRange = this.cleanRange(range);
+    const valueInputOption = options.valueInputOption || 'USER_ENTERED';
+
+    try {
+      const response = await this.sheets.spreadsheets.values.append({
+        spreadsheetId,
+        range: cleanedRange,
+        valueInputOption,
+        insertDataOption: options.insertDataOption,
+        requestBody: {
+          values,
+        },
+      });
+
+      const updates = response.data.updates;
+      return {
+        updatedRange: updates?.updatedRange || cleanedRange,
+        updatedRows: updates?.updatedRows || 0,
+        updatedColumns: updates?.updatedColumns || 0,
+        updatedCells: updates?.updatedCells || 0,
+      };
+    } catch (err) {
+      this.throwApiError(err, 'append values');
+    }
+  }
+
+  async clear(spreadsheetIdOrUrl: string, range: string): Promise<GSheetsClearResult> {
+    const spreadsheetId = this.extractSpreadsheetId(spreadsheetIdOrUrl);
+    const cleanedRange = this.cleanRange(range);
+
+    try {
+      const response = await this.sheets.spreadsheets.values.clear({
+        spreadsheetId,
+        range: cleanedRange,
+      });
+
+      return {
+        clearedRange: response.data.clearedRange || cleanedRange,
+      };
+    } catch (err) {
+      this.throwApiError(err, 'clear values');
+    }
+  }
+
+  async metadata(spreadsheetIdOrUrl: string): Promise<GSheetsSpreadsheet> {
+    const spreadsheetId = this.extractSpreadsheetId(spreadsheetIdOrUrl);
+
+    try {
+      const response = await this.sheets.spreadsheets.get({
+        spreadsheetId,
+      });
+
+      const props = response.data.properties!;
+      const sheets: GSheetsSheet[] = (response.data.sheets || []).map((sheet) => ({
+        id: sheet.properties?.sheetId || 0,
+        title: sheet.properties?.title || 'Untitled',
+        rowCount: sheet.properties?.gridProperties?.rowCount || 0,
+        columnCount: sheet.properties?.gridProperties?.columnCount || 0,
+      }));
+
+      return {
+        id: response.data.spreadsheetId!,
+        title: props.title || 'Untitled',
+        locale: props.locale || undefined,
+        timeZone: props.timeZone || undefined,
+        url: response.data.spreadsheetUrl || `https://docs.google.com/spreadsheets/d/${spreadsheetId}`,
+        sheets,
+      };
+    } catch (err) {
+      this.throwApiError(err, 'get metadata');
+    }
+  }
+
+  async create(title: string, sheetNames?: string[]): Promise<GSheetsCreateResult> {
+    try {
+      const sheets: sheets_v4.Schema$Sheet[] | undefined = sheetNames?.map((name) => ({
+        properties: {
+          title: name.trim(),
+        },
+      }));
+
+      const response = await this.sheets.spreadsheets.create({
+        requestBody: {
+          properties: {
+            title,
+          },
+          sheets,
+        },
+      });
+
+      return {
+        id: response.data.spreadsheetId!,
+        title: response.data.properties?.title || title,
+        url: response.data.spreadsheetUrl || `https://docs.google.com/spreadsheets/d/${response.data.spreadsheetId}`,
+      };
+    } catch (err) {
+      this.throwApiError(err, 'create spreadsheet');
+    }
+  }
+
+  async copy(spreadsheetIdOrUrl: string, newTitle: string, parentFolderId?: string): Promise<GSheetsCreateResult> {
+    const spreadsheetId = this.extractSpreadsheetId(spreadsheetIdOrUrl);
+
+    try {
+      const response = await this.drive.files.copy({
+        fileId: spreadsheetId,
+        requestBody: {
+          name: newTitle,
+          parents: parentFolderId ? [parentFolderId] : undefined,
+        },
+        fields: 'id,name,webViewLink',
+      });
+
+      return {
+        id: response.data.id!,
+        title: response.data.name || newTitle,
+        url: response.data.webViewLink || `https://docs.google.com/spreadsheets/d/${response.data.id}`,
+      };
+    } catch (err) {
+      this.throwApiError(err, 'copy spreadsheet');
+    }
+  }
+
+  async export(
+    spreadsheetIdOrUrl: string,
+    format: 'xlsx' | 'pdf' | 'csv' | 'ods' | 'tsv'
+  ): Promise<{ data: Buffer; mimeType: string; extension: string }> {
+    const spreadsheetId = this.extractSpreadsheetId(spreadsheetIdOrUrl);
+
+    const formatMap: Record<string, { mimeType: string; extension: string }> = {
+      xlsx: {
+        mimeType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        extension: '.xlsx',
+      },
+      pdf: { mimeType: 'application/pdf', extension: '.pdf' },
+      csv: { mimeType: 'text/csv', extension: '.csv' },
+      ods: { mimeType: 'application/vnd.oasis.opendocument.spreadsheet', extension: '.ods' },
+      tsv: { mimeType: 'text/tab-separated-values', extension: '.tsv' },
+    };
+
+    const formatInfo = formatMap[format];
+    if (!formatInfo) {
+      throw new CliError('INVALID_PARAMS', `Unknown export format: ${format}`, 'Use xlsx, pdf, csv, ods, or tsv');
+    }
+
+    try {
+      const response = await this.drive.files.export(
+        { fileId: spreadsheetId, mimeType: formatInfo.mimeType },
+        { responseType: 'arraybuffer' }
+      );
+
+      return {
+        data: Buffer.from(response.data as ArrayBuffer),
+        mimeType: formatInfo.mimeType,
+        extension: formatInfo.extension,
+      };
+    } catch (err) {
+      this.throwApiError(err, 'export spreadsheet');
+    }
+  }
+
+  private extractSpreadsheetId(idOrUrl: string): string {
+    // Handle URLs like https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit
+    const urlMatch = idOrUrl.match(/\/spreadsheets\/d\/([a-zA-Z0-9_-]+)/);
+    if (urlMatch) return urlMatch[1];
+
+    // Handle other URL formats
+    const idMatch = idOrUrl.match(/id=([a-zA-Z0-9_-]+)/);
+    if (idMatch) return idMatch[1];
+
+    // Assume it's already an ID
+    return idOrUrl;
+  }
+
+  private cleanRange(range: string): string {
+    // Some shells escape ! to \! (bash history expansion), which breaks API calls
+    return range.replace(/\\!/g, '!');
+  }
+
+  private createOAuthClient() {
+    const oauth2Client = new google.auth.OAuth2(
+      GOOGLE_OAUTH_CONFIG.clientId,
+      GOOGLE_OAUTH_CONFIG.clientSecret
+    );
+
+    oauth2Client.setCredentials({
+      access_token: this.credentials.accessToken,
+      refresh_token: this.credentials.refreshToken,
+      expiry_date: this.credentials.expiryDate,
+    });
+
+    return oauth2Client;
+  }
+
+  private throwApiError(err: unknown, operation: string): never {
+    const code = this.getErrorCode(err);
+    const message = this.getErrorMessage(err);
+    throw new CliError(code, `Failed to ${operation}: ${message}`);
+  }
+
+  private getErrorCode(err: unknown): ErrorCode {
+    if (err && typeof err === 'object') {
+      const error = err as Record<string, unknown>;
+      const code = error.code || error.status;
+      if (typeof code === 'number') return httpStatusToErrorCode(code);
+    }
+    return 'API_ERROR';
+  }
+
+  private getErrorMessage(err: unknown): string {
+    if (err && typeof err === 'object') {
+      const error = err as Record<string, unknown>;
+      const code = error.code || error.status;
+      if (code === 401) return 'OAuth token expired or invalid';
+      if (code === 403) return 'Insufficient permissions to access this spreadsheet';
+      if (code === 404) return 'Spreadsheet not found';
+      if (code === 429) return 'Rate limit exceeded, please try again later';
+      if (error.message && typeof error.message === 'string') return error.message;
+    }
+    return err instanceof Error ? err.message : String(err);
+  }
+}

package/src/types/config.ts

@@ -37,6 +37,7 @@ export interface Config {
     gcal?: string[];
     gtasks?: string[];
     gchat?: string[];
+    gsheets?: string[];
     github?: string[];
     jira?: string[];
     slack?: string[];
@@ -49,4 +50,4 @@ export interface Config {
   gateway?: GatewayConfig;
 }
 
-export type ServiceName = 'gdocs' | 'gdrive' | 'gmail' | 'gcal' | 'gtasks' | 'gchat' | 'github' | 'jira' | 'slack' | 'telegram' | 'whatsapp' | 'discourse' | 'sql';
+export type ServiceName = 'gdocs' | 'gdrive' | 'gmail' | 'gcal' | 'gtasks' | 'gchat' | 'gsheets' | 'github' | 'jira' | 'slack' | 'telegram' | 'whatsapp' | 'discourse' | 'sql';

package/src/types/gsheets.ts

@@ -0,0 +1,81 @@
+export interface GSheetsCredentials {
+  accessToken: string;
+  refreshToken?: string;
+  expiryDate?: number;
+  tokenType: string;
+  scope?: string;
+  email: string;
+}
+
+export interface GSheetsSpreadsheet {
+  id: string;
+  title: string;
+  locale?: string;
+  timeZone?: string;
+  url: string;
+  sheets: GSheetsSheet[];
+}
+
+export interface GSheetsSheet {
+  id: number;
+  title: string;
+  rowCount: number;
+  columnCount: number;
+}
+
+export interface GSheetsGetOptions {
+  majorDimension?: 'ROWS' | 'COLUMNS';
+  valueRenderOption?: 'FORMATTED_VALUE' | 'UNFORMATTED_VALUE' | 'FORMULA';
+}
+
+export interface GSheetsGetResult {
+  range: string;
+  values: unknown[][];
+}
+
+export interface GSheetsUpdateOptions {
+  valueInputOption?: 'RAW' | 'USER_ENTERED';
+}
+
+export interface GSheetsUpdateResult {
+  updatedRange: string;
+  updatedRows: number;
+  updatedColumns: number;
+  updatedCells: number;
+}
+
+export interface GSheetsAppendOptions {
+  valueInputOption?: 'RAW' | 'USER_ENTERED';
+  insertDataOption?: 'OVERWRITE' | 'INSERT_ROWS';
+}
+
+export interface GSheetsAppendResult {
+  updatedRange: string;
+  updatedRows: number;
+  updatedColumns: number;
+  updatedCells: number;
+}
+
+export interface GSheetsClearResult {
+  clearedRange: string;
+}
+
+export interface GSheetsCreateResult {
+  id: string;
+  title: string;
+  url: string;
+}
+
+export interface GSheetsListOptions {
+  limit?: number;
+  query?: string;
+}
+
+export interface GSheetsListItem {
+  id: string;
+  title: string;
+  owner?: string;
+  createdTime?: string;
+  modifiedTime?: string;
+  webViewLink: string;
+}

package/src/utils/output.ts

@@ -405,6 +405,87 @@ export function printGDocCreated(result: GDocsCreateResult): void {
   console.log(`Link: ${result.webViewLink}`);
 }
 
+// Google Sheets specific formatters
+import type {
+  GSheetsListItem,
+  GSheetsSpreadsheet,
+  GSheetsGetResult,
+  GSheetsUpdateResult,
+  GSheetsAppendResult,
+  GSheetsClearResult,
+  GSheetsCreateResult,
+} from '../types/gsheets';
+
+export function printGSheetsList(spreadsheets: GSheetsListItem[]): void {
+  if (spreadsheets.length === 0) {
+    console.log('No spreadsheets found');
+    return;
+  }
+
+  console.log(`Spreadsheets (${spreadsheets.length})\n`);
+
+  for (let i = 0; i < spreadsheets.length; i++) {
+    const sheet = spreadsheets[i];
+    console.log(`[${i + 1}] ${sheet.title}`);
+    console.log(`    ID: ${sheet.id}`);
+    if (sheet.owner) console.log(`    Owner: ${sheet.owner}`);
+    if (sheet.modifiedTime) console.log(`    Modified: ${sheet.modifiedTime}`);
+    console.log(`    Link: ${sheet.webViewLink}`);
+    console.log('');
+  }
+}
+
+export function printGSheetsMetadata(spreadsheet: GSheetsSpreadsheet): void {
+  console.log(`ID: ${spreadsheet.id}`);
+  console.log(`Title: ${spreadsheet.title}`);
+  if (spreadsheet.locale) console.log(`Locale: ${spreadsheet.locale}`);
+  if (spreadsheet.timeZone) console.log(`TimeZone: ${spreadsheet.timeZone}`);
+  console.log(`URL: ${spreadsheet.url}`);
+  console.log('');
+  console.log('Sheets:');
+
+  for (const sheet of spreadsheet.sheets) {
+    console.log(`  [${sheet.id}] ${sheet.title} (${sheet.rowCount} rows x ${sheet.columnCount} cols)`);
+  }
+}
+
+export function printGSheetsValues(result: GSheetsGetResult): void {
+  if (result.values.length === 0) {
+    console.log('No data found');
+    return;
+  }
+
+  console.log(`Range: ${result.range}\n`);
+
+  for (const row of result.values) {
+    const cells = row.map((cell) => String(cell ?? ''));
+    console.log(cells.join('\t'));
+  }
+}
+
+export function printGSheetsUpdateResult(result: GSheetsUpdateResult): void {
+  console.log(`Updated ${result.updatedCells} cells in ${result.updatedRange}`);
+  console.log(`  Rows: ${result.updatedRows}`);
+  console.log(`  Columns: ${result.updatedColumns}`);
+}
+
+export function printGSheetsAppendResult(result: GSheetsAppendResult): void {
+  console.log(`Appended ${result.updatedCells} cells to ${result.updatedRange}`);
+  console.log(`  Rows: ${result.updatedRows}`);
+  console.log(`  Columns: ${result.updatedColumns}`);
+}
+
+export function printGSheetsClearResult(result: GSheetsClearResult): void {
+  console.log(`Cleared ${result.clearedRange}`);
+}
+
+export function printGSheetsCreated(result: GSheetsCreateResult): void {
+  console.log('Spreadsheet created');
+  console.log(`ID: ${result.id}`);
+  console.log(`Title: ${result.title}`);
+  console.log(`URL: ${result.url}`);
+}
+
 // Google Drive specific formatters
 function getShortMimeType(mimeType: string): string {
   const shortTypes: Record<string, string> = {