@smcllns/gmail 0.1.1

package/README.md

@@ -0,0 +1,164 @@
+# @smcllns/gmail
+
+A fork of [@mariozechner/gmcli](https://github.com/badlogic/gmcli) designed for use with Claude Code and other AI coding agents.
+
+## Why This Fork?
+
+The original gmcli is excellent but requests full Gmail access (`mail.google.com` scope). This fork:
+
+1. **Narrows OAuth scopes** for safer agent usage:
+   - `gmail.readonly` - Read messages, threads, settings
+   - `gmail.labels` - Create, update, delete labels
+   - No send/compose permissions at the API level
+
+2. **Restricts dangerous operations** in the CLI:
+   - `send`, `drafts create`, `drafts send`, `drafts delete` are blocked
+   - Returns guidance directing users to the Gmail web interface
+   - Prevents AI agents from sending emails without human review
+
+3. **Simplifies CLI for agent usage**:
+   - Renamed binary from `gmcli` to `gmail`
+   - Default account config so commands don't require email prefix
+   - Usage: `bunx @smcllns/gmail <command>` or `npx @smcllns/gmail <command>`
+
+## Installation
+
+```bash
+npm install -g @smcllns/gmail
+```
+
+Or use directly with bunx/npx:
+
+```bash
+bunx @smcllns/gmail <command>
+```
+
+## Setup
+
+### 1. Create OAuth Credentials
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project (or select existing)
+3. Enable the Gmail API
+4. Go to "APIs & Services" → "Credentials"
+5. Create "OAuth client ID" → "Desktop app"
+6. Download the credentials JSON file
+
+### 2. Configure the CLI
+
+```bash
+# Set credentials (once per machine)
+gmail accounts credentials ~/Downloads/credentials.json
+
+# Add your Gmail account
+gmail accounts add you@gmail.com
+
+# The first account is automatically set as default
+# Or set manually:
+gmail config default you@gmail.com
+```
+
+## Usage
+
+```
+gmail - Gmail CLI for Claude Code agents
+
+USAGE
+
+  gmail accounts <action>              Account management
+  gmail config <action>                Configuration management
+  gmail <command> [options]            Gmail operations (uses default account)
+  gmail --account <email> <command>    Gmail operations with specific account
+
+ACCOUNT COMMANDS
+
+  gmail accounts credentials <file.json>    Set OAuth credentials (once)
+  gmail accounts list                       List configured accounts
+  gmail accounts add <email> [--manual]     Add account (--manual for browserless OAuth)
+  gmail accounts remove <email>             Remove account
+
+CONFIG COMMANDS
+
+  gmail config default <email>         Set default account for all commands
+  gmail config show                    Show current configuration
+
+GMAIL COMMANDS
+
+  gmail search <query> [--max N] [--page TOKEN]
+      Search threads using Gmail query syntax.
+      Returns: thread ID, date, sender, subject, labels.
+
+      Query examples:
+        in:inbox, in:sent, in:drafts, in:trash
+        is:unread, is:starred, is:important
+        from:sender@example.com, to:recipient@example.com
+        subject:keyword, has:attachment, filename:pdf
+        after:2024/01/01, before:2024/12/31
+        label:Work, label:UNREAD
+        Combine: "in:inbox is:unread from:boss@company.com"
+
+  gmail thread <threadId> [--download]
+      Get thread with all messages.
+      Shows: Message-ID, headers, body, attachments.
+      --download saves attachments to ~/.gmail-cli/attachments/
+
+  gmail labels list
+      List all labels with ID, name, and type.
+
+  gmail labels <threadIds...> [--add L] [--remove L]
+      Modify labels on threads (comma-separated for multiple).
+      Accepts label names or IDs (names are case-insensitive).
+      System labels: INBOX, UNREAD, STARRED, IMPORTANT, TRASH, SPAM
+
+  gmail drafts list
+      List all drafts. Returns: draft ID, message ID.
+
+  gmail drafts get <draftId> [--download]
+      View draft with attachments.
+      --download saves attachments to ~/.gmail-cli/attachments/
+
+  gmail url <threadIds...>
+      Generate Gmail web URLs for threads.
+      Uses canonical URL format with email parameter.
+
+RESTRICTED OPERATIONS
+
+  gmail send            - Returns guidance to use Gmail web interface
+  gmail drafts create   - Returns guidance to use Gmail web interface
+  gmail drafts send     - Returns guidance to use Gmail web interface
+  gmail drafts delete   - Returns guidance to use Gmail web interface
+
+EXAMPLES
+
+  gmail search "in:inbox is:unread"
+  gmail search "from:boss@company.com" --max 50
+  gmail thread 19aea1f2f3532db5
+  gmail thread 19aea1f2f3532db5 --download
+  gmail labels list
+  gmail labels abc123 --add Work --remove UNREAD
+  gmail url 19aea1f2f3532db5
+
+DATA STORAGE
+
+  ~/.gmail-cli/credentials.json   OAuth client credentials
+  ~/.gmail-cli/accounts.json      Account tokens
+  ~/.gmail-cli/config.json        CLI configuration (default account)
+  ~/.gmail-cli/attachments/       Downloaded attachments
+```
+
+## Key Differences from Upstream
+
+| Feature | @mariozechner/gmcli | @smcllns/gmail |
+|---------|---------------------|----------------|
+| OAuth scopes | Full access (`mail.google.com`) | Read-only + labels |
+| Send email | ✅ Supported | ❌ Blocked (returns guidance) |
+| Create drafts | ✅ Supported | ❌ Blocked |
+| Send drafts | ✅ Supported | ❌ Blocked |
+| Delete drafts | ✅ Supported | ❌ Blocked |
+| Binary name | `gmcli` | `gmail` |
+| Default account | Not supported | ✅ `gmail config default` |
+| Data directory | `~/.gmcli/` | `~/.gmail-cli/` |
+
+## License
+
+MIT

package/dist/account-storage.d.ts

@@ -0,0 +1,22 @@
+import type { EmailAccount } from "./types.js";
+export declare class AccountStorage {
+    private accounts;
+    constructor();
+    private ensureConfigDir;
+    private loadAccounts;
+    private saveAccounts;
+    addAccount(account: EmailAccount): void;
+    getAccount(email: string): EmailAccount | undefined;
+    getAllAccounts(): EmailAccount[];
+    deleteAccount(email: string): boolean;
+    hasAccount(email: string): boolean;
+    setCredentials(clientId: string, clientSecret: string): void;
+    getCredentials(): {
+        clientId: string;
+        clientSecret: string;
+    } | null;
+    setDefaultAccount(email: string): void;
+    getDefaultAccount(): string | null;
+    private loadConfig;
+}
+//# sourceMappingURL=account-storage.d.ts.map

package/dist/account-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-storage.d.ts","sourceRoot":"","sources":["../src/account-storage.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAO/C,qBAAa,cAAc;IAC1B,OAAO,CAAC,QAAQ,CAAwC;;IAOxD,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,YAAY;IAIpB,UAAU,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAKvC,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAInD,cAAc,IAAI,YAAY,EAAE;IAIhC,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAMrC,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIlC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAI5D,cAAc,IAAI;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IASnE,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMtC,iBAAiB,IAAI,MAAM,GAAG,IAAI;IAKlC,OAAO,CAAC,UAAU;CAQlB"}

package/dist/account-storage.js

@@ -0,0 +1,87 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+const CONFIG_DIR = path.join(os.homedir(), ".gmail-cli");
+const ACCOUNTS_FILE = path.join(CONFIG_DIR, "accounts.json");
+const CREDENTIALS_FILE = path.join(CONFIG_DIR, "credentials.json");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+export class AccountStorage {
+    accounts = new Map();
+    constructor() {
+        this.ensureConfigDir();
+        this.loadAccounts();
+    }
+    ensureConfigDir() {
+        if (!fs.existsSync(CONFIG_DIR)) {
+            fs.mkdirSync(CONFIG_DIR, { recursive: true });
+        }
+    }
+    loadAccounts() {
+        if (fs.existsSync(ACCOUNTS_FILE)) {
+            try {
+                const data = JSON.parse(fs.readFileSync(ACCOUNTS_FILE, "utf8"));
+                for (const account of data) {
+                    this.accounts.set(account.email, account);
+                }
+            }
+            catch {
+                // Ignore
+            }
+        }
+    }
+    saveAccounts() {
+        fs.writeFileSync(ACCOUNTS_FILE, JSON.stringify(Array.from(this.accounts.values()), null, 2));
+    }
+    addAccount(account) {
+        this.accounts.set(account.email, account);
+        this.saveAccounts();
+    }
+    getAccount(email) {
+        return this.accounts.get(email);
+    }
+    getAllAccounts() {
+        return Array.from(this.accounts.values());
+    }
+    deleteAccount(email) {
+        const deleted = this.accounts.delete(email);
+        if (deleted)
+            this.saveAccounts();
+        return deleted;
+    }
+    hasAccount(email) {
+        return this.accounts.has(email);
+    }
+    setCredentials(clientId, clientSecret) {
+        fs.writeFileSync(CREDENTIALS_FILE, JSON.stringify({ clientId, clientSecret }, null, 2));
+    }
+    getCredentials() {
+        if (!fs.existsSync(CREDENTIALS_FILE))
+            return null;
+        try {
+            return JSON.parse(fs.readFileSync(CREDENTIALS_FILE, "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    setDefaultAccount(email) {
+        const config = this.loadConfig();
+        config.defaultAccount = email;
+        fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+    }
+    getDefaultAccount() {
+        const config = this.loadConfig();
+        return config.defaultAccount || null;
+    }
+    loadConfig() {
+        if (!fs.existsSync(CONFIG_FILE))
+            return {};
+        try {
+            return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+        }
+        catch {
+            return {};
+        }
+    }
+}
+//# sourceMappingURL=account-storage.js.map

package/dist/account-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-storage.js","sourceRoot":"","sources":["../src/account-storage.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}