@mcinteerj/openclaw-gmail 1.3.1 → 1.4.1

package/src/auth.ts

@@ -0,0 +1,217 @@
+import { OAuth2Client } from "google-auth-library";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import http from "node:http";
+import { execFile } from "node:child_process";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+export interface OAuthCredentials {
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+}
+
+/**
+ * Read gog CLI's credentials.json to reuse its OAuth client_id/client_secret.
+ * Returns null if the file doesn't exist or is malformed.
+ */
+export function readGogCredentials(): { clientId: string; clientSecret: string } | null {
+  const credPath = path.join(os.homedir(), ".config", "gogcli", "credentials.json");
+  try {
+    const raw = fs.readFileSync(credPath, "utf-8");
+    const data = JSON.parse(raw);
+    if (typeof data.client_id === "string" && typeof data.client_secret === "string") {
+      return { clientId: data.client_id, clientSecret: data.client_secret };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve OAuth credentials from config, falling back to gog's credentials.json
+ * for client_id/client_secret.
+ *
+ * Returns full credentials (including refreshToken) only if all three parts are available.
+ * Returns null if refresh token is missing (caller should run the OAuth flow).
+ */
+export function resolveOAuthCredentials(
+  accountEmail: string,
+  cfg: OpenClawConfig,
+): OAuthCredentials | null {
+  const accounts = (cfg.channels as any)?.["openclaw-gmail"]?.accounts;
+  const account = accounts?.[accountEmail] ?? Object.values(accounts ?? {}).find(
+    (a: any) => a.email === accountEmail,
+  );
+
+  const oauth = (account as any)?.oauth;
+  if (oauth?.clientId && oauth?.clientSecret && oauth?.refreshToken) {
+    return {
+      clientId: oauth.clientId,
+      clientSecret: oauth.clientSecret,
+      refreshToken: oauth.refreshToken,
+    };
+  }
+
+  // If we have a refresh token in config but client creds come from gog
+  if (oauth?.refreshToken) {
+    const gogCreds = readGogCredentials();
+    if (gogCreds) {
+      return {
+        clientId: oauth.clientId || gogCreds.clientId,
+        clientSecret: oauth.clientSecret || gogCreds.clientSecret,
+        refreshToken: oauth.refreshToken,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve just the client_id/client_secret pair (without refresh token).
+ * Useful for initiating the OAuth flow.
+ */
+export function resolveClientCredentials(
+  accountEmail: string,
+  cfg: OpenClawConfig,
+): { clientId: string; clientSecret: string } | null {
+  const accounts = (cfg.channels as any)?.["openclaw-gmail"]?.accounts;
+  const account = accounts?.[accountEmail] ?? Object.values(accounts ?? {}).find(
+    (a: any) => a.email === accountEmail,
+  );
+
+  const oauth = (account as any)?.oauth;
+  if (oauth?.clientId && oauth?.clientSecret) {
+    return { clientId: oauth.clientId, clientSecret: oauth.clientSecret };
+  }
+
+  return readGogCredentials();
+}
+
+/**
+ * Create an authenticated OAuth2Client with auto-refresh.
+ */
+export function createOAuth2Client(creds: OAuthCredentials): OAuth2Client {
+  const client = new OAuth2Client(creds.clientId, creds.clientSecret);
+  client.setCredentials({ refresh_token: creds.refreshToken });
+  return client;
+}
+
+/**
+ * Open a URL in the user's default browser.
+ */
+function openBrowser(url: string): void {
+  const cmd = process.platform === "darwin" ? "open" : "xdg-open";
+  execFile(cmd, [url], (err) => {
+    if (err) {
+      // If browser open fails, the URL is already printed to console
+    }
+  });
+}
+
+/**
+ * Run the browser-based OAuth2 consent flow.
+ *
+ * 1. Starts a local HTTP server on 127.0.0.1
+ * 2. Opens the consent URL in the user's browser
+ * 3. Waits for the redirect callback with the auth code
+ * 4. Exchanges the code for tokens
+ * 5. Returns the refresh_token
+ */
+export async function runOAuthFlow(
+  clientId: string,
+  clientSecret: string,
+  opts?: { port?: number },
+): Promise<string> {
+  const port = opts?.port ?? 0; // 0 = OS picks a free port
+
+  return new Promise<string>((resolve, reject) => {
+    const server = http.createServer();
+
+    const timeout = setTimeout(() => {
+      server.close();
+      reject(new Error("OAuth flow timed out after 5 minutes"));
+    }, 5 * 60 * 1000);
+
+    server.listen(port, "127.0.0.1", () => {
+      const addr = server.address();
+      if (!addr || typeof addr === "string") {
+        clearTimeout(timeout);
+        server.close();
+        reject(new Error("Failed to start local OAuth server"));
+        return;
+      }
+
+      const redirectUri = `http://127.0.0.1:${addr.port}/callback`;
+      const oauth2Client = new OAuth2Client(clientId, clientSecret, redirectUri);
+
+      const authUrl = oauth2Client.generateAuthUrl({
+        access_type: "offline",
+        scope: ["https://mail.google.com/"],
+        prompt: "consent",
+      });
+
+      console.log(`\nOpen this URL in your browser to authorize:\n\n  ${authUrl}\n`);
+      openBrowser(authUrl);
+
+      server.on("request", async (req, res) => {
+        if (!req.url?.startsWith("/callback")) {
+          res.writeHead(404);
+          res.end("Not found");
+          return;
+        }
+
+        const url = new URL(req.url, `http://127.0.0.1:${addr.port}`);
+        const code = url.searchParams.get("code");
+        const error = url.searchParams.get("error");
+
+        if (error) {
+          res.writeHead(200, { "Content-Type": "text/html" });
+          res.end("<h1>Authorization denied</h1><p>You can close this tab.</p>");
+          clearTimeout(timeout);
+          server.close();
+          reject(new Error(`OAuth authorization denied: ${error}`));
+          return;
+        }
+
+        if (!code) {
+          res.writeHead(400, { "Content-Type": "text/html" });
+          res.end("<h1>Missing authorization code</h1>");
+          return;
+        }
+
+        try {
+          const { tokens } = await oauth2Client.getToken(code);
+          if (!tokens.refresh_token) {
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end("<h1>Error</h1><p>No refresh token received. Try revoking access at <a href='https://myaccount.google.com/permissions'>Google Account Permissions</a> and retry.</p>");
+            clearTimeout(timeout);
+            server.close();
+            reject(new Error("No refresh_token received. Revoke app access and retry with prompt=consent."));
+            return;
+          }
+
+          res.writeHead(200, { "Content-Type": "text/html" });
+          res.end("<h1>Authorization successful!</h1><p>You can close this tab and return to the terminal.</p>");
+          clearTimeout(timeout);
+          server.close();
+          resolve(tokens.refresh_token);
+        } catch (err) {
+          res.writeHead(500, { "Content-Type": "text/html" });
+          res.end("<h1>Token exchange failed</h1><p>Check the terminal for details.</p>");
+          clearTimeout(timeout);
+          server.close();
+          reject(err);
+        }
+      });
+    });
+
+    server.on("error", (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+  });
+}

package/src/channel.ts

@@ -21,27 +21,27 @@ import { setGmailRuntime, getGmailRuntime } from "./runtime.js";
 import { sendGmailText, type GmailOutboundContext } from "./outbound.js";
 import { gmailThreading } from "./threading.js";
 import { normalizeGmailTarget, isGmailThreadId, isAllowed } from "./normalize.js";
-import { parseInboundGmail, type GogPayload } from "./inbound.js";
-import { monitorGmail, quarantineMessage } from "./monitor.js";
-import { extractAttachments } from "./attachments.js";
+import { monitorGmail } from "./monitor.js";
 import { Semaphore } from "./semaphore.js";
+import { createGmailClient, type GmailClient } from "./gmail-client.js";
 import crypto from "node:crypto";
 
 const meta = {
   id: "gmail",
   label: "Gmail",
-  selectionLabel: "Gmail (gog)",
+  selectionLabel: "Gmail",
   detailLabel: "Gmail",
   docsPath: "/channels/gmail",
   docsLabel: "gmail",
-  blurb: "Uses gog for secure Gmail access.",
+  blurb: "Gmail integration via direct API or gog CLI.",
   systemImage: "envelope",
   order: 100,
   showConfigured: true,
 };
 
-// Map to store active account contexts
+// Map to store active account contexts and their clients
 const activeAccounts = new Map<string, ChannelGatewayContext<ResolvedGmailAccount>>();
+const activeClients = new Map<string, GmailClient>();
 
 // Limit concurrent dispatches to avoid memory spikes
 const dispatchSemaphore = new Semaphore(5);
@@ -93,6 +93,7 @@ function buildGmailMsgContext(
 async function dispatchGmailMessage(
   ctx: ChannelGatewayContext<ResolvedGmailAccount>,
   msg: InboundMessage,
+  client: GmailClient,
 ) {
   const { account, accountId, cfg, log } = ctx;
   const runtime = getGmailRuntime();
@@ -101,7 +102,7 @@ async function dispatchGmailMessage(
   await dispatchSemaphore.run(async () => {
     try {
       log?.info(`[gmail][${requestId}] Dispatching message ${msg.channelMessageId} from ${msg.sender.id}`);
-      
+
       // Build the dispatch context
       const ctxPayload = buildGmailMsgContext(msg, account, cfg);
       const gmailCfg = cfg.channels?.gmail as GmailConfig | undefined;
@@ -109,10 +110,10 @@ async function dispatchGmailMessage(
       // Build reply dispatcher options using gateway's reply capability
       const deliver = async (payload: { text: string }) => {
         const originalSubject = msg.raw?.subject ||
-                               msg.raw?.headers?.subject || 
+                               msg.raw?.headers?.subject ||
                                msg.raw?.payload?.headers?.find((h: any) => h.name.toLowerCase() === "subject")?.value;
-        
-        const replySubject = originalSubject 
+
+        const replySubject = originalSubject
           ? (originalSubject.toLowerCase().startsWith("re:") ? originalSubject : `Re: ${originalSubject}`)
           : "Re: ";
 
@@ -124,6 +125,7 @@ async function dispatchGmailMessage(
           threadId: msg.threadId,
           replyToId: msg.channelMessageId,
           subject: replySubject,
+          client,
         });
       };
 
@@ -188,6 +190,16 @@ export const gmailPlugin: ChannelPlugin<ResolvedGmailAccount> = {
               historyId: { type: "string" },
               delegate: { type: "string" },
               archiveOnReply: { type: "boolean", default: true },
+              backend: { type: "string", enum: ["gog", "api"] },
+              oauth: {
+                type: "object",
+                properties: {
+                  clientId: { type: "string" },
+                  clientSecret: { type: "string" },
+                  refreshToken: { type: "string" },
+                },
+                required: ["clientId", "clientSecret", "refreshToken"],
+              },
             },
             required: ["email"],
           },
@@ -237,7 +249,12 @@ export const gmailPlugin: ChannelPlugin<ResolvedGmailAccount> = {
   outbound: {
     deliveryMode: "gateway",
     textChunkLimit: 8000,
-    sendText: sendGmailText,
+    sendText: (ctx: any) => {
+      const account = resolveGmailAccount(ctx.cfg, ctx.accountId);
+      const emailKey = account.email?.toLowerCase();
+      const client = (emailKey && activeClients.get(emailKey)) || createGmailClient(account, ctx.cfg);
+      return sendGmailText({ ...ctx, client });
+    },
     resolveTarget: ({ to, allowFrom }) => {
       const trimmed = to?.trim() ?? "";
       const normalized = normalizeGmailTarget(trimmed);
@@ -300,8 +317,10 @@ export const gmailPlugin: ChannelPlugin<ResolvedGmailAccount> = {
         "### Attachments",
         "- **Location**: All attachments are stored in \`.attachments/{{threadId}}/\` relative to your workspace.",
         "- **Auto-Download**: Files under 5MB are already there. The message text contains their paths.",
-        "- **Manual Download**: For larger files (listed with an ID), download them to that same folder:",
-        `- Command: \`mkdir -p .attachments/{{threadId}} && gog gmail attachment <messageId> <attachmentId> --account ${account.email} --out .attachments/{{threadId}}/<filename>\``,
+        "- **Manual Download**: For larger files (listed with an ID), download them to that same folder.",
+        ...(account.backend === "api"
+          ? ["- The attachment download tool is available as part of the Gmail API client."]
+          : [`- Command: \`mkdir -p .attachments/{{threadId}} && gog gmail attachment <messageId> <attachmentId> --account ${account.email} --out .attachments/{{threadId}}/<filename>\``]),
       ];
     },
   },
@@ -310,15 +329,19 @@ export const gmailPlugin: ChannelPlugin<ResolvedGmailAccount> = {
     supportsAction: ({ action }: { action: string }) => action === "send",
     handleAction: async (ctx: any) => {
       if (ctx.action !== "send") return { ok: false, error: new Error(`Unsupported action: ${ctx.action}`) };
-      
+
       const { params, accountId, cfg, toolContext } = ctx;
+      const account = resolveGmailAccount(cfg, accountId);
+      const emailKey = account.email?.toLowerCase();
+      const client = (emailKey && activeClients.get(emailKey)) || createGmailClient(account, cfg);
+
       const to = (params.target || params.to) as string;
       const text = params.message as string;
-      
+
       const isThread = isGmailThreadId(to);
       let subject = params.subject as string | undefined;
       let replyToId: string | undefined;
-      
+
       if (isThread && toolContext?.currentThreadTs) {
           replyToId = toolContext.currentThreadTs;
       }
@@ -331,8 +354,9 @@ export const gmailPlugin: ChannelPlugin<ResolvedGmailAccount> = {
         threadId: isThread ? to : undefined,
         replyToId,
         subject,
+        client,
       });
-      
+
       return { ok: true, content: [{ type: "text", text: "Message sent via Gmail." }] };
     },
   },
@@ -340,8 +364,12 @@ export const gmailPlugin: ChannelPlugin<ResolvedGmailAccount> = {
     startAccount: async (ctx) => {
       ctx.log?.info(`[gmail] Account ${ctx.account.accountId} started`);
 
-      if (ctx.account.email) {
-        activeAccounts.set(ctx.account.email.toLowerCase(), ctx);
+      const client = createGmailClient(ctx.account, ctx.cfg);
+      const emailKey = ctx.account.email?.toLowerCase();
+
+      if (emailKey) {
+        activeAccounts.set(emailKey, ctx);
+        activeClients.set(emailKey, client);
       }
 
       ctx.setStatus({ accountId: ctx.accountId, running: true, connected: true });
@@ -355,11 +383,12 @@ export const gmailPlugin: ChannelPlugin<ResolvedGmailAccount> = {
       await monitorGmail({
         account: ctx.account,
         onMessage: async (msg) => {
-          await dispatchGmailMessage(ctx, msg);
+          await dispatchGmailMessage(ctx, msg, client);
         },
         signal,
         log: ctx.log,
         setStatus: ctx.setStatus,
+        client,
       }).catch((err) => {
         if (!signal.aborted) {
           ctx.log?.error(`[gmail] Monitor error: ${String(err)}`);
@@ -367,8 +396,9 @@ export const gmailPlugin: ChannelPlugin<ResolvedGmailAccount> = {
       });
 
       // Cleanup after monitor exits
-      if (ctx.account.email) {
-        activeAccounts.delete(ctx.account.email.toLowerCase());
+      if (emailKey) {
+        activeAccounts.delete(emailKey);
+        activeClients.delete(emailKey);
       }
       ctx.setStatus({ accountId: ctx.accountId, running: false, connected: false });
     },

package/src/config.ts

@@ -16,6 +16,12 @@ export const GmailAccountSchema = z.object({
   allowOutboundTo: z.array(z.string()).optional(), // Who we can SEND to (if not set, falls back to allowFrom)
   threadReplyPolicy: z.enum(["open", "allowlist", "sender-only"]).optional(), // Default: "open" for backwards compat
   archiveOnReply: z.boolean().optional(), // Archive thread after reply (default: true)
+  backend: z.enum(["gog", "api"]).optional(), // Gmail backend: gog CLI (default) or googleapis
+  oauth: z.object({
+    clientId: z.string(),
+    clientSecret: z.string(),
+    refreshToken: z.string(),
+  }).optional(), // OAuth2 credentials for API backend
 });
 
 export const GmailConfigSchema = z.object({

package/src/gmail-client.ts

@@ -0,0 +1,50 @@
+import type { ResolvedGmailAccount } from "./accounts.js";
+import type { ThreadResponse } from "./quoting.js";
+import type { GogSearchMessage } from "./inbound.js";
+import { GogGmailClient } from "./gog-client.js";
+import { ApiGmailClient } from "./api-client.js";
+import { resolveOAuthCredentials, createOAuth2Client } from "./auth.js";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+export interface GmailClient {
+  send(opts: {
+    account?: string;
+    to?: string;
+    subject: string;
+    textBody: string;
+    htmlBody?: string;
+    threadId?: string;
+    replyToMessageId?: string;
+    replyAll?: boolean;
+  }): Promise<void>;
+
+  getThread(threadId: string, opts?: { full?: boolean }): Promise<ThreadResponse | null>;
+  getMessage(messageId: string): Promise<Record<string, unknown> | null>;
+  searchMessages(query: string, opts?: { maxResults?: number; includeBody?: boolean }): Promise<GogSearchMessage[]>;
+  searchThreads(query: string, opts?: { maxResults?: number }): Promise<Record<string, unknown> | null>;
+  modifyLabels(id: string, opts: { add?: string[]; remove?: string[] }): Promise<void>;
+  modifyThreadLabels(threadId: string, opts: { add?: string[]; remove?: string[] }): Promise<void>;
+  listLabels(): Promise<{ id: string; name: string }[]>;
+  createLabel(name: string): Promise<void>;
+  downloadAttachment(messageId: string, attachmentId: string, outPath: string): Promise<void>;
+  getSendAs(): Promise<{ displayName?: string; email: string; isPrimary?: boolean }[]>;
+}
+
+export function createGmailClient(account: ResolvedGmailAccount, cfg?: OpenClawConfig): GmailClient {
+  if (account.backend === "api") {
+    if (!cfg) {
+      throw new Error(`API backend requires config to resolve OAuth credentials for ${account.email}`);
+    }
+    const creds = resolveOAuthCredentials(account.email, cfg);
+    if (!creds) {
+      throw new Error(
+        `No OAuth credentials found for ${account.email}. ` +
+        `Run onboarding or set oauth.clientId, oauth.clientSecret, and oauth.refreshToken in config.`,
+      );
+    }
+    const auth = createOAuth2Client(creds);
+    return new ApiGmailClient(auth);
+  }
+
+  return new GogGmailClient(account.email);
+}