@cli4ai/gmail 1.0.11 → 1.0.13

package/cli4ai.json

@@ -1,10 +1,10 @@
 {
   "name": "gmail",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "Gmail CLI tool for messages, threads, and drafts",
   "author": "cliforai",
-  "license": "MIT",
-  "entry": "run.ts",
+  "license": "BUSL-1.1",
+  "entry": "dist/run.js",
   "runtime": "node",
   "keywords": [
     "gmail",

package/dist/lib/api.d.ts

@@ -0,0 +1,91 @@
+import { gmail_v1 } from 'googleapis';
+import type { OAuth2Client } from 'google-auth-library';
+/** 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;
+}
+/**
+ * Authorize and get OAuth2 client
+ */
+export declare function authorize(): Promise<OAuth2Client>;
+/**
+ * Get Gmail API client
+ */
+export declare function getGmail(): Promise<gmail_v1.Gmail>;
+/**
+ * Output data to console
+ */
+export declare function output(data: unknown, options?: OutputOptions): void;
+/**
+ * Format date
+ */
+export declare function formatDate(timestamp: string | number | undefined | null): string | null;
+/**
+ * Decode base64url to Buffer (for binary attachments)
+ */
+export declare function decodeBase64Url(str: string | undefined | null): Buffer;
+/**
+ * Decode base64url to UTF-8 string (for text content)
+ */
+export declare function decodeBase64UrlToString(str: string | undefined | null): string;
+/**
+ * Encode to base64url
+ */
+export declare function encodeBase64Url(str: string): string;
+/**
+ * Extract headers from message
+ */
+export declare function extractHeaders(headers: Array<{
+    name: string;
+    value: string;
+}> | undefined): EmailHeaders;
+/**
+ * Extract body from message parts
+ */
+export declare function extractBody(payload: MessagePayload | undefined): string;
+/**
+ * Clean email body for display
+ */
+export declare function cleanBody(body: string, maxLength?: number | null): string;

package/dist/lib/api.js

@@ -0,0 +1,240 @@
+import fs from 'fs';
+import path from 'path';
+import { google } from 'googleapis';
+import readline from 'readline';
+import { homedir } from 'os';
+// SECURITY: Store credentials in user's home directory, not in node_modules
+const GMAIL_CONFIG_DIR = path.join(homedir(), '.cli4ai', 'gmail');
+// Paths for credentials and token (env vars override for flexibility)
+const CREDENTIALS_PATH = process.env.GMAIL_CREDENTIALS_PATH || path.join(GMAIL_CONFIG_DIR, 'credentials.json');
+const TOKEN_PATH = process.env.GMAIL_TOKEN_PATH || path.join(GMAIL_CONFIG_DIR, 'token.json');
+/**
+ * Ensure the gmail config directory exists with secure permissions
+ */
+function ensureConfigDir() {
+    if (!fs.existsSync(GMAIL_CONFIG_DIR)) {
+        fs.mkdirSync(GMAIL_CONFIG_DIR, { recursive: true, mode: 0o700 });
+    }
+}
+// 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 = null;
+let authClient = null;
+/**
+ * Get new token via OAuth flow
+ */
+async function getNewToken(oAuth2Client) {
+    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) => {
+            rl.close();
+            oAuth2Client.getToken(code, (err, token) => {
+                if (err) {
+                    reject(new Error(`Error retrieving access token: ${err.message}`));
+                    return;
+                }
+                oAuth2Client.setCredentials(token);
+                ensureConfigDir();
+                fs.writeFileSync(TOKEN_PATH, JSON.stringify(token), { mode: 0o600 });
+                console.error('Token stored to', TOKEN_PATH);
+                resolve();
+            });
+        });
+    });
+}
+/**
+ * Authorize and get OAuth2 client
+ */
+export async function authorize() {
+    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), { mode: 0o600 });
+        });
+        // Try to refresh token if it might be expired
+        try {
+            await oAuth2Client.getAccessToken();
+        }
+        catch (err) {
+            const error = err;
+            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() {
+    if (gmailClient)
+        return gmailClient;
+    const auth = await authorize();
+    gmailClient = google.gmail({ version: 'v1', auth });
+    return gmailClient;
+}
+/**
+ * Output data to console
+ */
+export function output(data, options = {}) {
+    if (options.raw) {
+        console.log(JSON.stringify(data, null, 2));
+    }
+    else if (options.compact && Array.isArray(data)) {
+        data.forEach((item) => {
+            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) {
+    if (!timestamp)
+        return null;
+    const date = new Date(parseInt(String(timestamp)));
+    return date.toISOString().replace('T', ' ').slice(0, 16);
+}
+/**
+ * Decode base64url to Buffer (for binary attachments)
+ */
+export function decodeBase64Url(str) {
+    if (!str)
+        return Buffer.alloc(0);
+    // Replace URL-safe characters and add padding
+    let normalized = str.replace(/-/g, '+').replace(/_/g, '/');
+    while (normalized.length % 4)
+        normalized += '=';
+    return Buffer.from(normalized, 'base64');
+}
+/**
+ * Decode base64url to UTF-8 string (for text content)
+ */
+export function decodeBase64UrlToString(str) {
+    return decodeBase64Url(str).toString('utf-8');
+}
+/**
+ * Encode to base64url
+ */
+export function encodeBase64Url(str) {
+    return Buffer.from(str)
+        .toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}
+/**
+ * Extract headers from message
+ */
+export function extractHeaders(headers) {
+    const result = {};
+    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('-', '_');
+            result[key] = header.value;
+        }
+    }
+    return result;
+}
+/**
+ * Extract body from message parts
+ */
+export function extractBody(payload) {
+    if (!payload)
+        return '';
+    // Simple message with direct body
+    if (payload.body?.data) {
+        return decodeBase64UrlToString(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 decodeBase64UrlToString(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 = decodeBase64UrlToString(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, maxLength) {
+    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;
+}

package/dist/lib/attachments.d.ts

@@ -0,0 +1,35 @@
+import { type OutputOptions } from './api.js';
+/** Attachment info */
+export interface AttachmentInfo {
+    filename: string;
+    mimeType?: string;
+    size: number;
+    attachmentId?: string | null;
+    partId?: string;
+}
+/** Download result */
+export interface DownloadResult {
+    ok: boolean;
+    filename: string;
+    savedTo?: string;
+    size?: number;
+    error?: string;
+}
+/** Download all result */
+export interface DownloadAllResult {
+    ok: boolean;
+    message?: string;
+    downloaded: DownloadResult[];
+}
+/**
+ * List attachments in a message
+ */
+export declare function list(messageId: string, options?: OutputOptions): Promise<AttachmentInfo[]>;
+/**
+ * Download an attachment
+ */
+export declare function download(messageId: string, filename?: string, outputPath?: string, options?: OutputOptions): Promise<DownloadResult>;
+/**
+ * Download all attachments from a message
+ */
+export declare function downloadAll(messageId: string, outputDir?: string, options?: OutputOptions): Promise<DownloadAllResult>;

package/dist/lib/attachments.js

@@ -0,0 +1,148 @@
+import fs from 'fs';
+import path from 'path';
+import { getGmail, output, decodeBase64Url } from './api.js';
+/**
+ * Extract attachment info from message payload
+ */
+function extractAttachmentInfo(payload, attachments = []) {
+    if (!payload)
+        return attachments;
+    // Check if this part is an attachment
+    if (payload.filename && payload.filename.length > 0) {
+        attachments.push({
+            filename: payload.filename,
+            mimeType: payload.mimeType,
+            size: payload.body?.size || 0,
+            attachmentId: payload.body?.attachmentId || null,
+            partId: payload.partId
+        });
+    }
+    // Recursively check parts
+    if (payload.parts) {
+        for (const part of payload.parts) {
+            extractAttachmentInfo(part, attachments);
+        }
+    }
+    return attachments;
+}
+/**
+ * List attachments in a message
+ */
+export async function list(messageId, options = {}) {
+    const gmail = await getGmail();
+    const res = await gmail.users.messages.get({
+        userId: 'me',
+        id: messageId,
+        format: 'full'
+    });
+    const attachments = extractAttachmentInfo(res.data.payload);
+    output(attachments, options);
+    return attachments;
+}
+/**
+ * Download an attachment
+ */
+export async function download(messageId, filename, outputPath, options = {}) {
+    const gmail = await getGmail();
+    // Get message to find attachment
+    const res = await gmail.users.messages.get({
+        userId: 'me',
+        id: messageId,
+        format: 'full'
+    });
+    const attachments = extractAttachmentInfo(res.data.payload);
+    // Find the attachment by filename (or get first if not specified)
+    let attachment;
+    if (filename) {
+        attachment = attachments.find(a => a.filename.toLowerCase() === filename.toLowerCase() ||
+            a.filename.toLowerCase().includes(filename.toLowerCase()));
+    }
+    else if (attachments.length === 1) {
+        attachment = attachments[0];
+    }
+    if (!attachment) {
+        throw new Error(`Attachment not found: ${filename || '(no attachments)'}`);
+    }
+    if (!attachment.attachmentId) {
+        throw new Error(`Attachment ${attachment.filename} has no downloadable content`);
+    }
+    // Get the attachment data
+    const attachmentRes = await gmail.users.messages.attachments.get({
+        userId: 'me',
+        messageId: messageId,
+        id: attachment.attachmentId
+    });
+    // Decode and save
+    const data = decodeBase64Url(attachmentRes.data.data);
+    // SECURITY: Sanitize filename to prevent path traversal
+    const safeFilename = path.basename(attachment.filename);
+    const savePath = outputPath || safeFilename;
+    fs.writeFileSync(savePath, data);
+    const result = {
+        ok: true,
+        filename: attachment.filename,
+        savedTo: path.resolve(savePath),
+        size: attachment.size
+    };
+    output(result, options);
+    return result;
+}
+/**
+ * Download all attachments from a message
+ */
+export async function downloadAll(messageId, outputDir, options = {}) {
+    const gmail = await getGmail();
+    // Ensure output directory exists
+    const dir = outputDir || '.';
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    // Get message
+    const res = await gmail.users.messages.get({
+        userId: 'me',
+        id: messageId,
+        format: 'full'
+    });
+    const attachments = extractAttachmentInfo(res.data.payload);
+    if (attachments.length === 0) {
+        const result = { ok: true, message: 'No attachments found', downloaded: [] };
+        output(result, options);
+        return result;
+    }
+    const downloaded = [];
+    for (const attachment of attachments) {
+        if (!attachment.attachmentId)
+            continue;
+        try {
+            const attachmentRes = await gmail.users.messages.attachments.get({
+                userId: 'me',
+                messageId: messageId,
+                id: attachment.attachmentId
+            });
+            const data = decodeBase64Url(attachmentRes.data.data);
+            // SECURITY: Sanitize filename to prevent path traversal
+            const safeFilename = path.basename(attachment.filename);
+            const savePath = path.join(dir, safeFilename);
+            fs.writeFileSync(savePath, data);
+            downloaded.push({
+                ok: true,
+                filename: attachment.filename,
+                savedTo: path.resolve(savePath),
+                size: attachment.size
+            });
+        }
+        catch (err) {
+            downloaded.push({
+                ok: false,
+                filename: attachment.filename,
+                error: err.message
+            });
+        }
+    }
+    const result = {
+        ok: true,
+        downloaded
+    };
+    output(result, options);
+    return result;
+}

package/dist/lib/drafts.d.ts

@@ -0,0 +1,89 @@
+import { type OutputOptions } from './api.js';
+/** Attachment path */
+export interface AttachmentPath {
+    path: string;
+    mimeType?: string;
+}
+/** Draft data */
+export interface DraftData {
+    id: string;
+    messageId?: string;
+    threadId?: string;
+    to: string;
+    cc?: string | null;
+    subject: string;
+    snippet?: string;
+    body?: string;
+}
+/** Draft result */
+export interface DraftResult {
+    ok: boolean;
+    id?: string;
+    messageId?: string;
+    threadId?: string;
+    to?: string;
+    subject?: string;
+    inReplyTo?: string;
+    deleted?: string;
+    sentDraft?: string;
+}
+/** Draft options */
+export interface DraftOptions extends OutputOptions {
+    cc?: string;
+    bcc?: string;
+    attach?: string | string[];
+    limit?: number;
+}
+/**
+ * Create multipart message with attachment
+ */
+export declare function createMultipartMessage({ to, cc, bcc, subject, body, inReplyTo, references, attachments }: {
+    to: string;
+    cc?: string;
+    bcc?: string;
+    subject: string;
+    body: string;
+    inReplyTo?: string;
+    references?: string;
+    attachments?: AttachmentPath[];
+}): string;
+/**
+ * Simple message without attachments
+ */
+export declare function createSimpleMessage({ to, cc, bcc, subject, body, inReplyTo, references }: {
+    to: string;
+    cc?: string;
+    bcc?: string;
+    subject: string;
+    body: string;
+    inReplyTo?: string;
+    references?: string;
+}): string;
+/**
+ * List all drafts
+ */
+export declare function list(options?: DraftOptions): Promise<DraftData[]>;
+/**
+ * Get a draft
+ */
+export declare function get(draftId: string, options?: OutputOptions): Promise<DraftData>;
+/**
+ * Create a new draft
+ */
+export declare function create(to: string, subject: string, body: string, options?: DraftOptions): Promise<DraftResult>;
+/**
+ * Create a draft reply to a message
+ */
+export declare function createReply(messageId: string, body: string, options?: DraftOptions): Promise<DraftResult>;
+/**
+ * Update a draft
+ */
+export declare function update(draftId: string, to: string, subject: string, body: string, options?: DraftOptions): Promise<DraftResult>;
+/**
+ * Delete a draft
+ */
+export declare function remove(draftId: string, options?: OutputOptions): Promise<DraftResult>;
+/**
+ * Send a draft
+ */
+export declare function send(draftId: string, options?: OutputOptions): Promise<DraftResult>;