@mcinteerj/openclaw-gmail 1.3.1 → 1.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mcinteerj/openclaw-gmail",
-  "version": "1.3.1",
-  "description": "Gmail channel plugin for OpenClaw - uses gog CLI for secure Gmail access",
+  "version": "1.4.0",
+  "description": "Gmail channel plugin for OpenClaw - direct API or gog CLI",
   "type": "module",
   "main": "index.ts",
   "author": "Jake McInteer <mcinteerj@gmail.com>",
@@ -24,11 +24,11 @@
     "channel": {
       "id": "openclaw-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
@@ -41,9 +41,12 @@
     "README.md"
   ],
   "dependencies": {
+    "@googleapis/gmail": "^16.1.1",
     "dompurify": "^3.2.3",
+    "google-auth-library": "^10.5.0",
     "jsdom": "^25.0.1",
     "marked": "^15.0.6",
+    "nodemailer": "^8.0.1",
     "proper-lockfile": "^4.1.2",
     "sanitize-html": "^2.14.0",
     "zod": "^4.3.5"

package/src/accounts.ts

@@ -10,6 +10,12 @@ export interface ResolvedGmailAccount extends ResolvedChannelAccount {
   historyId?: string;
   delegate?: string;
   pollIntervalMs?: number;
+  backend?: "gog" | "api";
+  oauth?: {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+  };
 }
 
 export function resolveGmailAccount(
@@ -42,6 +48,8 @@ export function resolveGmailAccount(
     delegate: account.delegate,
     allowFrom: account.allowFrom,
     pollIntervalMs: account.pollIntervalMs,
+    backend: account.backend,
+    oauth: account.oauth,
   };
 }
 

package/src/api-client.ts

@@ -0,0 +1,406 @@
+import { gmail as gmailApi, type gmail_v1 } from "@googleapis/gmail";
+import type { OAuth2Client } from "google-auth-library";
+import fs from "node:fs/promises";
+import type { GmailClient } from "./gmail-client.js";
+import type { ThreadResponse, GogRawMessage } from "./quoting.js";
+import type { GogSearchMessage } from "./inbound.js";
+import { buildMimeMessage } from "./mime.js";
+import { parseEmailAddresses } from "./outbound-check.js";
+
+/**
+ * Gmail API client using googleapis library directly.
+ * Implements GmailClient interface for the "api" backend.
+ */
+export class ApiGmailClient implements GmailClient {
+  private gmail: gmail_v1.Gmail;
+
+  constructor(auth: OAuth2Client) {
+    this.gmail = gmailApi({ version: "v1", auth });
+  }
+
+  async send(opts: {
+    account?: string;
+    to?: string;
+    subject: string;
+    textBody: string;
+    htmlBody?: string;
+    threadId?: string;
+    replyToMessageId?: string;
+    replyAll?: boolean;
+  }): Promise<void> {
+    const selfEmail = opts.account || "";
+    let to = opts.to || "";
+    let cc: string | undefined;
+    let inReplyTo: string | undefined;
+    let references: string | undefined;
+
+    // For thread replies, resolve recipients and threading headers
+    if (opts.threadId) {
+      const replyCtx = await this.resolveReplyContext(
+        opts.threadId,
+        selfEmail,
+        opts.replyAll ?? false,
+      );
+      if (replyCtx) {
+        to = replyCtx.to;
+        cc = replyCtx.cc;
+        inReplyTo = replyCtx.inReplyTo;
+        references = replyCtx.references;
+      }
+    }
+
+    if (!to) {
+      throw new Error("Cannot send: no recipient resolved");
+    }
+
+    const mime = await buildMimeMessage({
+      from: selfEmail,
+      to,
+      cc,
+      subject: opts.subject,
+      text: opts.textBody,
+      html: opts.htmlBody,
+      inReplyTo,
+      references,
+    });
+
+    await this.gmail.users.messages.send({
+      userId: "me",
+      requestBody: {
+        raw: mime.toString("base64url"),
+        threadId: opts.threadId,
+      },
+    });
+  }
+
+  /**
+   * Resolve reply recipients and threading headers from the last message in a thread.
+   */
+  private async resolveReplyContext(
+    threadId: string,
+    selfEmail: string,
+    replyAll: boolean,
+  ): Promise<{ to: string; cc?: string; inReplyTo?: string; references?: string } | null> {
+    const thread = await this.getThread(threadId, { full: true });
+    if (!thread || thread.messages.length === 0) return null;
+
+    const lastMsg = thread.messages[thread.messages.length - 1];
+
+    // Resolve To: reply to the sender of the last message
+    const to = lastMsg.from;
+
+    // For reply-all, Cc = everyone from To + Cc minus self and the new To
+    let cc: string | undefined;
+    if (replyAll) {
+      const selfLower = selfEmail.toLowerCase();
+      const toAddresses = parseEmailAddresses(to);
+      const toLower = new Set(toAddresses.map((a) => a.email.toLowerCase()));
+
+      const ccCandidates: string[] = [];
+      for (const field of [lastMsg.to, lastMsg.cc]) {
+        if (!field) continue;
+        const addresses = parseEmailAddresses(field);
+        for (const addr of addresses) {
+          if (addr.email.toLowerCase() !== selfLower && !toLower.has(addr.email.toLowerCase())) {
+            ccCandidates.push(addr.name ? `${addr.name} <${addr.email}>` : addr.email);
+            toLower.add(addr.email.toLowerCase()); // dedupe
+          }
+        }
+      }
+      if (ccCandidates.length > 0) {
+        cc = ccCandidates.join(", ");
+      }
+    }
+
+    // Resolve In-Reply-To and References from the last message
+    // We need the raw Message-ID header — fetch it from the API directly
+    let messageId: string | undefined;
+    try {
+      const res = await this.gmail.users.messages.get({
+        userId: "me",
+        id: lastMsg.id,
+        format: "metadata",
+        metadataHeaders: ["Message-ID", "References"],
+      });
+      const headers = res.data.payload?.headers || [];
+      messageId = headers.find((h) => h.name?.toLowerCase() === "message-id")?.value ?? undefined;
+      const existingRefs = headers.find((h) => h.name?.toLowerCase() === "references")?.value;
+      if (messageId) {
+        return {
+          to,
+          cc,
+          inReplyTo: messageId,
+          references: existingRefs ? `${existingRefs} ${messageId}` : messageId,
+        };
+      }
+    } catch {
+      // Fall through — send without threading headers
+    }
+
+    return { to, cc };
+  }
+
+  async getThread(threadId: string, opts?: { full?: boolean }): Promise<ThreadResponse | null> {
+    try {
+      const res = await this.gmail.users.threads.get({
+        userId: "me",
+        id: threadId,
+        format: opts?.full ? "full" : "metadata",
+      });
+
+      const thread = res.data;
+      if (!thread || !thread.messages) return null;
+
+      return {
+        id: thread.id!,
+        historyId: thread.historyId!,
+        messages: thread.messages.map((msg) => {
+          const raw = mapApiMessage(msg);
+          return parseRawToThreadMessage(raw);
+        }),
+      };
+    } catch (err: any) {
+      if (err?.code === 404) return null;
+      throw err;
+    }
+  }
+
+  async getMessage(messageId: string): Promise<Record<string, unknown> | null> {
+    try {
+      const res = await this.gmail.users.messages.get({
+        userId: "me",
+        id: messageId,
+        format: "full",
+      });
+
+      // Wrap in { message: ... } to match gog output shape consumed by monitor.ts
+      return { message: mapApiMessage(res.data) };
+    } catch (err: any) {
+      if (err?.code === 404) return null;
+      throw err;
+    }
+  }
+
+  async searchMessages(
+    query: string,
+    opts?: { maxResults?: number; includeBody?: boolean },
+  ): Promise<GogSearchMessage[]> {
+    const res = await this.gmail.users.messages.list({
+      userId: "me",
+      q: query,
+      maxResults: opts?.maxResults ?? 50,
+    });
+
+    const ids = res.data.messages || [];
+    if (ids.length === 0) return [];
+
+    // Fetch full message details in parallel (N+1 pattern)
+    const messages = await Promise.all(
+      ids.map(async (m) => {
+        try {
+          const detail = await this.gmail.users.messages.get({
+            userId: "me",
+            id: m.id!,
+            format: "full",
+          });
+          return detail.data;
+        } catch {
+          return null;
+        }
+      }),
+    );
+
+    return messages
+      .filter((m): m is gmail_v1.Schema$Message => m !== null)
+      .map((msg) => {
+        const headers = msg.payload?.headers || [];
+        const getH = (n: string) =>
+          headers.find((h) => h.name?.toLowerCase() === n.toLowerCase())?.value || "";
+
+        const body = extractPlainText(msg.payload ?? {});
+
+        return {
+          id: msg.id!,
+          threadId: msg.threadId!,
+          date: getH("Date"),
+          from: getH("From"),
+          subject: getH("Subject"),
+          body,
+          labels: msg.labelIds || [],
+        };
+      });
+  }
+
+  async searchThreads(
+    query: string,
+    opts?: { maxResults?: number },
+  ): Promise<Record<string, unknown> | null> {
+    const res = await this.gmail.users.threads.list({
+      userId: "me",
+      q: query,
+      maxResults: opts?.maxResults ?? 50,
+    });
+    return res.data as Record<string, unknown>;
+  }
+
+  async modifyLabels(id: string, opts: { add?: string[]; remove?: string[] }): Promise<void> {
+    await this.gmail.users.messages.modify({
+      userId: "me",
+      id,
+      requestBody: {
+        addLabelIds: opts.add,
+        removeLabelIds: opts.remove,
+      },
+    });
+  }
+
+  async modifyThreadLabels(
+    threadId: string,
+    opts: { add?: string[]; remove?: string[] },
+  ): Promise<void> {
+    await this.gmail.users.threads.modify({
+      userId: "me",
+      id: threadId,
+      requestBody: {
+        addLabelIds: opts.add,
+        removeLabelIds: opts.remove,
+      },
+    });
+  }
+
+  async listLabels(): Promise<{ id: string; name: string }[]> {
+    const res = await this.gmail.users.labels.list({ userId: "me" });
+    return (res.data.labels || []).map((l) => ({
+      id: l.id!,
+      name: l.name!,
+    }));
+  }
+
+  async createLabel(name: string): Promise<void> {
+    await this.gmail.users.labels.create({
+      userId: "me",
+      requestBody: { name },
+    });
+  }
+
+  async downloadAttachment(
+    messageId: string,
+    attachmentId: string,
+    outPath: string,
+  ): Promise<void> {
+    const res = await this.gmail.users.messages.attachments.get({
+      userId: "me",
+      messageId,
+      id: attachmentId,
+    });
+    // Gmail API returns base64url-encoded data
+    const buf = Buffer.from(res.data.data!, "base64url");
+    await fs.writeFile(outPath, buf);
+  }
+
+  async getSendAs(): Promise<{ displayName?: string; email: string; isPrimary?: boolean }[]> {
+    const res = await this.gmail.users.settings.sendAs.list({ userId: "me" });
+    return (res.data.sendAs || []).map((s) => ({
+      displayName: s.displayName || undefined,
+      email: s.sendAsEmail!,
+      isPrimary: s.isPrimary || false,
+    }));
+  }
+}
+
+// ── Response mapping helpers ──────────────────────────────────────────
+
+/**
+ * Map Gmail API Schema$Message to GogRawMessage shape.
+ * This keeps all downstream consumers (quoting.ts, inbound.ts, monitor.ts) working
+ * without changes.
+ */
+function mapApiMessage(msg: gmail_v1.Schema$Message): GogRawMessage {
+  return {
+    id: msg.id!,
+    threadId: msg.threadId!,
+    internalDate: msg.internalDate!,
+    labelIds: msg.labelIds || [],
+    payload: mapPayload(msg.payload ?? {}),
+  };
+}
+
+function mapPayload(
+  p: gmail_v1.Schema$MessagePart,
+): GogRawMessage["payload"] {
+  return {
+    headers: (p.headers || []).map((h) => ({
+      name: h.name!,
+      value: h.value!,
+    })),
+    parts: p.parts?.map((part) => ({
+      body: part.body?.data ? { data: part.body.data } : undefined,
+      mimeType: part.mimeType!,
+    })),
+    body: p.body?.data ? { data: p.body.data } : undefined,
+  };
+}
+
+/**
+ * Parse a GogRawMessage into a ThreadMessage (same logic as quoting.ts:parseGogMessage).
+ */
+function parseRawToThreadMessage(raw: GogRawMessage) {
+  const getH = (name: string) =>
+    raw.payload.headers.find((h) => h.name.toLowerCase() === name.toLowerCase())?.value;
+
+  const body = extractPlainFromRaw(raw);
+  const bodyHtml = extractHtmlFromRaw(raw);
+
+  return {
+    id: raw.id,
+    threadId: raw.threadId,
+    date: getH("Date") || new Date(parseInt(raw.internalDate)).toISOString(),
+    from: getH("From") || "",
+    to: getH("To"),
+    cc: getH("Cc"),
+    subject: getH("Subject") || "",
+    body,
+    bodyHtml,
+    labels: raw.labelIds,
+  };
+}
+
+function extractPlainFromRaw(raw: GogRawMessage): string {
+  if (raw.payload.parts) {
+    const plain = raw.payload.parts.find((p) => p.mimeType === "text/plain");
+    if (plain?.body?.data) return Buffer.from(plain.body.data, "base64").toString("utf-8");
+  }
+  if (raw.payload.body?.data) return Buffer.from(raw.payload.body.data, "base64").toString("utf-8");
+  return "";
+}
+
+function extractHtmlFromRaw(raw: GogRawMessage): string {
+  if (raw.payload.parts) {
+    const html = raw.payload.parts.find((p) => p.mimeType === "text/html");
+    if (html?.body?.data) return Buffer.from(html.body.data, "base64").toString("utf-8");
+  }
+  if (raw.payload.body?.data) return Buffer.from(raw.payload.body.data, "base64").toString("utf-8");
+  return "";
+}
+
+/**
+ * Extract plain text body from a Gmail API MessagePart.
+ */
+function extractPlainText(part: gmail_v1.Schema$MessagePart): string {
+  if (part.mimeType === "text/plain" && part.body?.data) {
+    return Buffer.from(part.body.data, "base64").toString("utf-8");
+  }
+  if (part.parts) {
+    // multipart/alternative: prefer text/plain
+    if (part.mimeType === "multipart/alternative") {
+      const plain = part.parts.find((p) => p.mimeType === "text/plain");
+      if (plain) return extractPlainText(plain);
+    }
+    // Recurse into sub-parts
+    for (const sub of part.parts) {
+      const text = extractPlainText(sub);
+      if (text) return text;
+    }
+  }
+  return "";
+}

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);
+    });
+  });
+}