@cli4ai/gmail 1.0.5 → 1.0.7

package/cli4ai.json

@@ -1,6 +1,6 @@
 {
   "name": "gmail",
-  "version": "1.0.4",
+  "version": "1.0.7",
   "description": "Gmail CLI tool for messages, threads, and drafts",
   "author": "cliforai",
   "license": "MIT",
@@ -39,6 +39,16 @@
     "google-auth-library": "^9.0.0",
     "commander": "^14.0.0"
   },
+  "env": {
+    "GMAIL_CREDENTIALS_PATH": {
+      "required": true,
+      "description": "Path to Google OAuth credentials.json file (download from Google Cloud Console)"
+    },
+    "GMAIL_TOKEN_PATH": {
+      "required": false,
+      "description": "Path to store OAuth token (defaults to package directory)"
+    }
+  },
   "mcp": {
     "enabled": true,
     "transport": "stdio"

package/lib/api.test.ts

@@ -0,0 +1,287 @@
+import { describe, test, expect, mock, beforeEach, afterEach, spyOn } from 'bun:test';
+import {
+  formatDate,
+  decodeBase64Url,
+  encodeBase64Url,
+  extractHeaders,
+  extractBody,
+  cleanBody,
+  output,
+  type MessagePayload,
+  type EmailHeaders
+} from './api';
+
+describe('gmail/lib/api', () => {
+  describe('formatDate', () => {
+    test('should format timestamp to readable date', () => {
+      // 1704067200000 = 2024-01-01 00:00:00 UTC
+      const result = formatDate('1704067200000');
+      expect(result).toBe('2024-01-01 00:00');
+    });
+
+    test('should handle timestamp as number', () => {
+      const result = formatDate(1704067200000);
+      expect(result).toBe('2024-01-01 00:00');
+    });
+
+    test('should return null for undefined', () => {
+      expect(formatDate(undefined)).toBeNull();
+    });
+
+    test('should return null for null', () => {
+      expect(formatDate(null)).toBeNull();
+    });
+  });
+
+  describe('decodeBase64Url', () => {
+    test('should decode base64url encoded string', () => {
+      // 'Hello World' in base64url
+      const encoded = 'SGVsbG8gV29ybGQ';
+      const result = decodeBase64Url(encoded);
+      expect(result).toBe('Hello World');
+    });
+
+    test('should handle URL-safe characters', () => {
+      // Contains - and _ instead of + and /
+      const encoded = 'PDw_Pz4-'; // <<??>>
+      const result = decodeBase64Url(encoded);
+      expect(result).toBe('<<??>>');
+    });
+
+    test('should handle missing padding', () => {
+      // Without = padding
+      const encoded = 'SGVsbG8';
+      const result = decodeBase64Url(encoded);
+      expect(result).toBe('Hello');
+    });
+
+    test('should return empty string for undefined', () => {
+      expect(decodeBase64Url(undefined)).toBe('');
+    });
+
+    test('should return empty string for null', () => {
+      expect(decodeBase64Url(null)).toBe('');
+    });
+
+    test('should return empty string for empty string', () => {
+      expect(decodeBase64Url('')).toBe('');
+    });
+  });
+
+  describe('encodeBase64Url', () => {
+    test('should encode string to base64url', () => {
+      const result = encodeBase64Url('Hello World');
+      expect(result).toBe('SGVsbG8gV29ybGQ');
+    });
+
+    test('should replace + with -', () => {
+      // A string that would produce + in standard base64
+      const result = encodeBase64Url('<<??>>');
+      expect(result).not.toContain('+');
+      expect(result).toContain('-');
+    });
+
+    test('should replace / with _', () => {
+      // A string that would produce / in standard base64
+      const result = encodeBase64Url('<<??>>');
+      expect(result).not.toContain('/');
+    });
+
+    test('should remove padding', () => {
+      const result = encodeBase64Url('Hello');
+      expect(result).not.toContain('=');
+    });
+
+    test('should be reversible', () => {
+      const original = 'Test message with special chars: éà';
+      const encoded = encodeBase64Url(original);
+      const decoded = decodeBase64Url(encoded);
+      expect(decoded).toBe(original);
+    });
+  });
+
+  describe('extractHeaders', () => {
+    test('should extract email headers', () => {
+      const headers = [
+        { name: 'From', value: 'sender@example.com' },
+        { name: 'To', value: 'recipient@example.com' },
+        { name: 'Subject', value: 'Test Subject' },
+        { name: 'Date', value: '2024-01-01' }
+      ];
+      const result = extractHeaders(headers);
+      expect(result.from).toBe('sender@example.com');
+      expect(result.to).toBe('recipient@example.com');
+      expect(result.subject).toBe('Test Subject');
+      expect(result.date).toBe('2024-01-01');
+    });
+
+    test('should handle Message-ID header', () => {
+      const headers = [
+        { name: 'Message-ID', value: '<123@example.com>' }
+      ];
+      const result = extractHeaders(headers);
+      expect(result.message_id).toBe('<123@example.com>');
+    });
+
+    test('should handle Reply-To header', () => {
+      const headers = [
+        { name: 'Reply-To', value: 'reply@example.com' }
+      ];
+      const result = extractHeaders(headers);
+      expect(result.reply_to).toBe('reply@example.com');
+    });
+
+    test('should ignore unknown headers', () => {
+      const headers = [
+        { name: 'X-Custom-Header', value: 'custom value' },
+        { name: 'From', value: 'sender@example.com' }
+      ];
+      const result = extractHeaders(headers);
+      expect(result.from).toBe('sender@example.com');
+      expect(Object.keys(result)).not.toContain('x_custom_header');
+    });
+
+    test('should return empty object for undefined headers', () => {
+      const result = extractHeaders(undefined);
+      expect(result).toEqual({});
+    });
+
+    test('should return empty object for empty array', () => {
+      const result = extractHeaders([]);
+      expect(result).toEqual({});
+    });
+  });
+
+  describe('extractBody', () => {
+    test('should extract body from simple message', () => {
+      const payload: MessagePayload = {
+        body: { data: 'SGVsbG8gV29ybGQ' } // 'Hello World'
+      };
+      const result = extractBody(payload);
+      expect(result).toBe('Hello World');
+    });
+
+    test('should prefer text/plain from multipart', () => {
+      const payload: MessagePayload = {
+        parts: [
+          { mimeType: 'text/html', body: { data: 'PGh0bWw-SGVsbG88L2h0bWw-' } },
+          { mimeType: 'text/plain', body: { data: 'SGVsbG8' } }
+        ]
+      };
+      const result = extractBody(payload);
+      expect(result).toBe('Hello');
+    });
+
+    test('should fall back to text/html if no text/plain', () => {
+      const payload: MessagePayload = {
+        parts: [
+          { mimeType: 'text/html', body: { data: 'PGI-SGVsbG88L2I-' } } // <b>Hello</b>
+        ]
+      };
+      const result = extractBody(payload);
+      // HTML tags should be stripped
+      expect(result).toContain('Hello');
+    });
+
+    test('should handle nested parts', () => {
+      const payload: MessagePayload = {
+        parts: [
+          {
+            mimeType: 'multipart/alternative',
+            parts: [
+              { mimeType: 'text/plain', body: { data: 'SGVsbG8' } }
+            ]
+          }
+        ]
+      };
+      const result = extractBody(payload);
+      expect(result).toBe('Hello');
+    });
+
+    test('should return empty string for undefined payload', () => {
+      expect(extractBody(undefined)).toBe('');
+    });
+
+    test('should return empty string for empty payload', () => {
+      expect(extractBody({})).toBe('');
+    });
+  });
+
+  describe('cleanBody', () => {
+    test('should remove excessive whitespace', () => {
+      const body = 'Hello    World';
+      const result = cleanBody(body);
+      expect(result).toBe('Hello World');
+    });
+
+    test('should normalize line breaks', () => {
+      const body = 'Hello\r\nWorld';
+      const result = cleanBody(body);
+      expect(result).toBe('Hello\nWorld');
+    });
+
+    test('should collapse multiple newlines', () => {
+      const body = 'Hello\n\n\n\nWorld';
+      const result = cleanBody(body);
+      expect(result).toBe('Hello\n\nWorld');
+    });
+
+    test('should trim whitespace', () => {
+      const body = '  Hello World  ';
+      const result = cleanBody(body);
+      expect(result).toBe('Hello World');
+    });
+
+    test('should truncate to maxLength', () => {
+      const body = 'Hello World This is a long message';
+      const result = cleanBody(body, 10);
+      expect(result).toBe('Hello Worl...');
+    });
+
+    test('should not truncate when maxLength is null', () => {
+      const body = 'Hello World';
+      const result = cleanBody(body, null);
+      expect(result).toBe('Hello World');
+    });
+
+    test('should return empty string for empty input', () => {
+      expect(cleanBody('')).toBe('');
+    });
+  });
+
+  describe('output', () => {
+    let consoleSpy: ReturnType<typeof spyOn>;
+    let logs: string[];
+
+    beforeEach(() => {
+      logs = [];
+      consoleSpy = spyOn(console, 'log').mockImplementation((msg: string) => {
+        logs.push(msg);
+      });
+    });
+
+    afterEach(() => {
+      consoleSpy.mockRestore();
+    });
+
+    test('should output JSON by default', () => {
+      output({ test: 'data' });
+      expect(logs[0]).toContain('"test": "data"');
+    });
+
+    test('should output raw JSON when raw option is true', () => {
+      output({ test: 'data' }, { raw: true });
+      expect(logs[0]).toContain('"test": "data"');
+    });
+
+    test('should output compact format for message arrays', () => {
+      const messages = [
+        { date: '2024-01-01', from: 'sender@test.com', subject: 'Test Subject' }
+      ];
+      output(messages, { compact: true });
+      expect(logs[0]).toContain('[2024-01-01]');
+      expect(logs[0]).toContain('sender@test.com');
+      expect(logs[0]).toContain('Test Subject');
+    });
+  });
+});

package/lib/api.ts

@@ -0,0 +1,299 @@
+import fs from 'fs';
+import path from 'path';
+import { google, gmail_v1 } from 'googleapis';
+import readline from 'readline';
+import type { OAuth2Client } from 'google-auth-library';
+
+// Load env from root .env
+const SCRIPT_DIR = path.dirname(import.meta.dir);
+const ENV_FILE = path.join(SCRIPT_DIR, '../.env');
+if (fs.existsSync(ENV_FILE)) {
+  const envContent = fs.readFileSync(ENV_FILE, 'utf-8');
+  envContent.split('\n').forEach(line => {
+    const [key, ...vals] = line.split('=');
+    if (key && !key.startsWith('#')) {
+      process.env[key.trim()] = vals.join('=').trim();
+    }
+  });
+}
+
+// Paths for credentials and token
+const CREDENTIALS_PATH = process.env.GMAIL_CREDENTIALS_PATH || path.join(SCRIPT_DIR, 'credentials.json');
+const TOKEN_PATH = process.env.GMAIL_TOKEN_PATH || path.join(SCRIPT_DIR, 'token.json');
+
+// Scopes for Gmail access
+const SCOPES = [
+  'https://www.googleapis.com/auth/gmail.modify',
+  'https://www.googleapis.com/auth/gmail.compose',
+  'https://www.googleapis.com/auth/gmail.send'
+];
+
+let gmailClient: gmail_v1.Gmail | null = null;
+let authClient: OAuth2Client | null = null;
+
+/** Output options */
+export interface OutputOptions {
+  raw?: boolean;
+  compact?: boolean;
+  body?: boolean;
+  fullBody?: boolean;
+  attach?: string | string[];
+  cc?: string;
+  bcc?: string;
+  limit?: number;
+  query?: string;
+}
+
+/** Message output data for compact display */
+export interface MessageOutputData {
+  date?: string | null;
+  from?: string;
+  subject?: string;
+}
+
+/** Email headers */
+export interface EmailHeaders {
+  from?: string;
+  to?: string;
+  cc?: string;
+  bcc?: string;
+  subject?: string;
+  date?: string;
+  reply_to?: string;
+  message_id?: string;
+  references?: string;
+}
+
+/** Message payload */
+export interface MessagePayload {
+  headers?: Array<{ name: string; value: string }>;
+  body?: { data?: string; size?: number; attachmentId?: string };
+  parts?: MessagePayload[];
+  mimeType?: string;
+  filename?: string;
+  partId?: string;
+}
+
+/**
+ * Get new token via OAuth flow
+ */
+async function getNewToken(oAuth2Client: OAuth2Client): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const authUrl = oAuth2Client.generateAuthUrl({
+      access_type: 'offline',
+      scope: SCOPES,
+    });
+    console.error('Authorize this app by visiting this url:');
+    console.error(authUrl);
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stderr,
+    });
+
+    rl.question('Enter the code from that page here: ', (code: string) => {
+      rl.close();
+      oAuth2Client.getToken(code, (err, token) => {
+        if (err) {
+          reject(new Error(`Error retrieving access token: ${err.message}`));
+          return;
+        }
+        oAuth2Client.setCredentials(token!);
+        fs.writeFileSync(TOKEN_PATH, JSON.stringify(token));
+        console.error('Token stored to', TOKEN_PATH);
+        resolve();
+      });
+    });
+  });
+}
+
+/**
+ * Authorize and get OAuth2 client
+ */
+export async function authorize(): Promise<OAuth2Client> {
+  if (authClient) return authClient;
+
+  if (!fs.existsSync(CREDENTIALS_PATH)) {
+    throw new Error(`Credentials not found at ${CREDENTIALS_PATH}. Run: cli4ai secrets init gmail`);
+  }
+
+  const content = fs.readFileSync(CREDENTIALS_PATH, 'utf-8');
+  const credentials = JSON.parse(content);
+  const { client_secret, client_id, redirect_uris } = credentials.installed || credentials.web;
+
+  const oAuth2Client = new google.auth.OAuth2(
+    client_id,
+    client_secret,
+    redirect_uris[0]
+  );
+
+  // Try to load existing token
+  if (fs.existsSync(TOKEN_PATH)) {
+    const token = JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf-8'));
+    oAuth2Client.setCredentials(token);
+
+    // Set up automatic token refresh
+    oAuth2Client.on('tokens', (tokens) => {
+      const currentToken = JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf-8'));
+      const newToken = { ...currentToken, ...tokens };
+      fs.writeFileSync(TOKEN_PATH, JSON.stringify(newToken));
+    });
+
+    // Try to refresh token if it might be expired
+    try {
+      await oAuth2Client.getAccessToken();
+    } catch (err) {
+      const error = err as Error;
+      if (error.message.includes('invalid_grant') || error.message.includes('Token has been expired')) {
+        console.error('Token expired. Re-authenticating...');
+        fs.unlinkSync(TOKEN_PATH);
+        await getNewToken(oAuth2Client);
+      } else {
+        throw err;
+      }
+    }
+  } else {
+    await getNewToken(oAuth2Client);
+  }
+
+  authClient = oAuth2Client;
+  return oAuth2Client;
+}
+
+/**
+ * Get Gmail API client
+ */
+export async function getGmail(): Promise<gmail_v1.Gmail> {
+  if (gmailClient) return gmailClient;
+
+  const auth = await authorize();
+  gmailClient = google.gmail({ version: 'v1', auth });
+  return gmailClient;
+}
+
+/**
+ * Output data to console
+ */
+export function output(data: unknown, options: OutputOptions = {}): void {
+  if (options.raw) {
+    console.log(JSON.stringify(data, null, 2));
+  } else if (options.compact && Array.isArray(data)) {
+    data.forEach((item: MessageOutputData) => {
+      if (item.date && item.from && item.subject) {
+        const from = item.from.slice(0, 30).padEnd(30);
+        const subject = item.subject.slice(0, 50);
+        console.log(`[${item.date}] ${from} ${subject}`);
+      } else {
+        console.log(JSON.stringify(item));
+      }
+    });
+  } else {
+    console.log(JSON.stringify(data, null, 2));
+  }
+}
+
+/**
+ * Format date
+ */
+export function formatDate(timestamp: string | number | undefined | null): string | null {
+  if (!timestamp) return null;
+  const date = new Date(parseInt(String(timestamp)));
+  return date.toISOString().replace('T', ' ').slice(0, 16);
+}
+
+/**
+ * Decode base64url
+ */
+export function decodeBase64Url(str: string | undefined | null): string {
+  if (!str) return '';
+  // Replace URL-safe characters and add padding
+  let normalized = str.replace(/-/g, '+').replace(/_/g, '/');
+  while (normalized.length % 4) normalized += '=';
+  return Buffer.from(normalized, 'base64').toString('utf-8');
+}
+
+/**
+ * Encode to base64url
+ */
+export function encodeBase64Url(str: string): string {
+  return Buffer.from(str)
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+/**
+ * Extract headers from message
+ */
+export function extractHeaders(headers: Array<{ name: string; value: string }> | undefined): EmailHeaders {
+  const result: EmailHeaders = {};
+  const headerNames = ['From', 'To', 'Subject', 'Date', 'Cc', 'Bcc', 'Reply-To', 'Message-ID', 'References'];
+
+  for (const header of headers || []) {
+    if (headerNames.includes(header.name)) {
+      const key = header.name.toLowerCase().replace('-', '_') as keyof EmailHeaders;
+      result[key] = header.value;
+    }
+  }
+  return result;
+}
+
+/**
+ * Extract body from message parts
+ */
+export function extractBody(payload: MessagePayload | undefined): string {
+  if (!payload) return '';
+
+  // Simple message with direct body
+  if (payload.body?.data) {
+    return decodeBase64Url(payload.body.data);
+  }
+
+  // Multipart message
+  if (payload.parts) {
+    // Prefer text/plain, fall back to text/html
+    for (const part of payload.parts) {
+      if (part.mimeType === 'text/plain' && part.body?.data) {
+        return decodeBase64Url(part.body.data);
+      }
+    }
+    for (const part of payload.parts) {
+      if (part.mimeType === 'text/html' && part.body?.data) {
+        // Strip HTML tags for plain text
+        const html = decodeBase64Url(part.body.data);
+        return html.replace(/<[^>]*>/g, '').replace(/\s+/g, ' ').trim();
+      }
+    }
+    // Recursively check nested parts
+    for (const part of payload.parts) {
+      if (part.parts) {
+        const body = extractBody(part);
+        if (body) return body;
+      }
+    }
+  }
+
+  return '';
+}
+
+/**
+ * Clean email body for display
+ */
+export function cleanBody(body: string, maxLength?: number | null): string {
+  if (!body) return '';
+
+  // Remove excessive whitespace
+  let cleaned = body
+    .replace(/\r\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/[ \t]+/g, ' ')
+    .trim();
+
+  // Truncate if needed
+  if (maxLength && cleaned.length > maxLength) {
+    cleaned = cleaned.slice(0, maxLength) + '...';
+  }
+
+  return cleaned;
+}