Google oauth support + fix tools for API v1 (#7780)

Author: deepu105

.gitignore

@@ -48,3 +48,5 @@ docs/api_refs/typedoc.json
 credentials.json
 **/typedoc.json
 .vercel
+
+bun.lock

docs/core_docs/docs/integrations/tools/gmail.mdx

@@ -10,9 +10,17 @@ The Gmail Tool allows your agent to create and view messages from a linked email
 
 ## Setup
 
-You will need to get an API key from [Google here](https://developers.google.com/gmail/api/guides)
-and [enable the new Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com).
-Then, set the environment variables for `GMAIL_CLIENT_EMAIL`, and either `GMAIL_PRIVATE_KEY`, or `GMAIL_KEYFILE`.
+You can authenticate via two methods:
+
+1. Provide an access token, obtained via OAuth2 token exchange, to the credentials object.
+   This can be a string or a function so that token expiry and validation can be handled.
+   This can be done using an Identity Provider that supports getting access tokens from federated connections.
+   This is the most secure method as the access and scope will be limited to the specific end user.
+   This method will be more appropriate when using the tool in an application that is meant to be used by end
+   users with their own Gmail account.
+2. You will need to get an API key from [Google here](https://developers.google.com/gmail/api/guides)
+   and [enable the new Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com).
+   Then, set the environment variables for `GMAIL_CLIENT_EMAIL`, and either `GMAIL_PRIVATE_KEY`, or `GMAIL_KEYFILE`.
 
 To use the Gmail Tool you need to install the following official peer dependency:
 

examples/src/tools/gmail.ts

@@ -20,8 +20,10 @@ export async function run() {
   //     credentials: {
   //       clientEmail: process.env.GMAIL_CLIENT_EMAIL,
   //       privateKey: process.env.GMAIL_PRIVATE_KEY,
+  //       // Either (privateKey + clientEmail) or accessToken is required
+  //       accessToken: "an access token or function to get access token",
   //     },
-  //     scopes: ["https://mail.google.com/"],
+  //     scopes: ["https://mail.google.com/"], // Not required if using access token
   //   };
 
   // For custom parameters, uncomment the code above, replace the values with your own, and pass it to the tools below

libs/langchain-community/src/tools/gmail/base.ts

@@ -1,5 +1,4 @@
 import { gmail_v1, google } from "googleapis";
-import { z } from "zod";
 import { StructuredTool } from "@langchain/core/tools";
 import { getEnvironmentVariable } from "@langchain/core/utils/env";
 
@@ -9,73 +8,125 @@ export interface GmailBaseToolParams {
     privateKey?: string;
     keyfile?: string;
     subject?: string;
+    // support string and async function to handle token validation and expiration
+    accessToken?: string | (() => Promise<string>);
   };
   scopes?: string[];
 }
 
 export abstract class GmailBaseTool extends StructuredTool {
-  private CredentialsSchema = z
-    .object({
-      clientEmail: z
-        .string()
-        .min(1)
-        .default(getEnvironmentVariable("GMAIL_CLIENT_EMAIL") ?? ""),
-      privateKey: z
-        .string()
-        .default(getEnvironmentVariable("GMAIL_PRIVATE_KEY") ?? ""),
-      keyfile: z
-        .string()
-        .default(getEnvironmentVariable("GMAIL_KEYFILE") ?? ""),
-      subject: z
-        .string()
-        .default(getEnvironmentVariable("GMAIL_SUBJECT") ?? ""),
-    })
-    .refine(
-      (credentials) =>
-        credentials.privateKey !== "" || credentials.keyfile !== "",
-      {
-        message:
-          "Missing GMAIL_PRIVATE_KEY or GMAIL_KEYFILE to interact with Gmail",
-      }
-    );
-
-  private GmailBaseToolParamsSchema = z
-    .object({
-      credentials: this.CredentialsSchema.default({}),
-      scopes: z.array(z.string()).default(["https://mail.google.com/"]),
-    })
-    .default({});
-
   name = "Gmail";
 
   description = "A tool to send and view emails through Gmail";
 
-  protected gmail: gmail_v1.Gmail;
+  protected params: GmailBaseToolParams;
+
+  protected gmail?: gmail_v1.Gmail;
 
-  constructor(fields?: Partial<GmailBaseToolParams>) {
+  constructor(
+    { credentials, scopes }: GmailBaseToolParams = {
+      credentials: {
+        clientEmail: getEnvironmentVariable("GMAIL_CLIENT_EMAIL"),
+        privateKey: getEnvironmentVariable("GMAIL_PRIVATE_KEY"),
+        keyfile: getEnvironmentVariable("GMAIL_KEYFILE"),
+        subject: getEnvironmentVariable("GMAIL_SUBJECT"),
+      },
+      scopes: ["https://mail.google.com/"],
+    }
+  ) {
     super(...arguments);
 
-    const { credentials, scopes } =
-      this.GmailBaseToolParamsSchema.parse(fields);
+    if (!credentials) {
+      throw new Error("Missing credentials to authenticate to Gmail");
+    }
+
+    if (!credentials.accessToken) {
+      if (!credentials.clientEmail) {
+        throw new Error("Missing GMAIL_CLIENT_EMAIL to interact with Gmail");
+      }
+
+      if (!credentials.privateKey && !credentials.keyfile) {
+        throw new Error(
+          "Missing GMAIL_PRIVATE_KEY or GMAIL_KEYFILE or accessToken to interact with Gmail"
+        );
+      }
+    }
+
+    this.params = { credentials, scopes };
+  }
+
+  async getGmailClient() {
+    const { credentials, scopes } = this.params;
+
+    if (credentials?.accessToken) {
+      // always return a new instance so that we don't end up using expired access tokens
+      const auth = new google.auth.OAuth2();
+      const accessToken =
+        typeof credentials.accessToken === "function"
+          ? await credentials.accessToken()
+          : credentials.accessToken;
+
+      auth.setCredentials({
+        // get fresh access token if a function is provided
+        access_token: accessToken,
+      });
+      return google.gmail({ version: "v1", auth });
+    }
 
-    this.gmail = this.getGmail(
+    // when not using access token its ok to use singleton instance
+    if (this.gmail) {
+      return this.gmail;
+    }
+
+    const auth = new google.auth.JWT(
+      credentials?.clientEmail,
+      credentials?.keyfile,
+      credentials?.privateKey,
       scopes,
-      credentials.clientEmail,
-      credentials.privateKey,
-      credentials.keyfile,
-      credentials.subject
+      credentials?.subject
     );
+
+    this.gmail = google.gmail({ version: "v1", auth });
+    return this.gmail;
   }
 
-  private getGmail(
-    scopes: string[],
-    email: string,
-    key?: string,
-    keyfile?: string,
-    subject?: string
-  ) {
-    const auth = new google.auth.JWT(email, keyfile, key, scopes, subject);
+  parseHeaderAndBody(payload: gmail_v1.Schema$MessagePart | undefined) {
+    if (!payload) {
+      return { body: "" };
+    }
 
-    return google.gmail({ version: "v1", auth });
+    const headers = payload.headers || [];
+
+    const subject = headers.find((header) => header.name === "Subject");
+    const sender = headers.find((header) => header.name === "From");
+
+    let body = "";
+    if (payload.parts) {
+      body = payload.parts
+        .map((part) =>
+          part.mimeType === "text/plain"
+            ? this.decodeBody(part.body?.data ?? "")
+            : ""
+        )
+        .join("");
+    } else if (payload.body?.data) {
+      body = this.decodeBody(payload.body.data);
+    }
+
+    return { subject, sender, body };
+  }
+
+  decodeBody(body: string) {
+    if (body) {
+      try {
+        // Gmail uses URL-safe base64 encoding, so we need to handle it properly
+        // Replace URL-safe characters and decode
+        return atob(body.replace(/-/g, "+").replace(/_/g, "/"));
+      } catch (error) {
+        // Keep the original encoded body if decoding fails
+        return body;
+      }
+    }
+    return "";
   }
 }

libs/langchain-community/src/tools/gmail/create_draft.ts

@@ -56,7 +56,9 @@ export class GmailCreateDraft extends GmailBaseTool {
       bcc
     );
 
-    const response = await this.gmail.users.drafts.create({
+    const gmail = await this.getGmailClient();
+
+    const response = await gmail.users.drafts.create({
       userId: "me",
       requestBody: create_message,
     });

libs/langchain-community/src/tools/gmail/descriptions.ts

@@ -78,42 +78,37 @@ Example Output:
 "Message sent. Message Id: unique_message_id_string"
 `;
 
-export const SEARCH_DESCRIPTION = `A tool for searching email messages or threads in Gmail using a specific query. It offers the flexibility to choose between messages and threads as the search resource.
+export const SEARCH_DESCRIPTION = `A tool for searching Gmail messages or threads using a specific query. Offers the flexibility to choose between messages and threads as the search resource.
 
-INPUT example:
+INPUT:
 {
-  "query": "specific search query",
+  "query": "search query",
   "maxResults": 10, // Optional: number of results to return
   "resource": "messages" // Optional: can be "messages" or "threads"
 }
 
 OUTPUT:
-The output is a JSON list of either email messages or threads, depending on the specified resource, that matches the search query. For 'messages', the output includes details like the message ID, thread ID, snippet, body, subject, and sender of each message. For 'threads', it includes the thread ID, snippet, body, subject, and sender of the first message in each thread. If no data is returned, or if the specified resource is invalid, the tool throws an error with a relevant message.
-
-Example Output for 'messages':
-"Result for the query 'specific search query':
-[
-  {
-    'id': 'message_id',
-    'threadId': 'thread_id',
-    'snippet': 'message snippet',
-    'body': 'message body',
-    'subject': 'message subject',
-    'sender': 'sender's email'
-  },
-  ... (other messages matching the query)
+JSON list of matching email messages or threads based on the specified resource. If no data is returned, or if the specified resource is invalid, throw error with a relevant message.
+
+Example result for messages:
+"[{
+  'id': 'message_id',
+  'threadId': 'thread_id',
+  'snippet': 'message snippet',
+  'body': 'message body',
+  'subject': 'message subject',
+  'sender': 'message sender'
+}, 
+... (other messages matching the query)
 ]"
 
-Example Output for 'threads':
-"Result for the query 'specific search query':
-[
-  {
-    'id': 'thread_id',
-    'snippet': 'thread snippet',
-    'body': 'first message body',
-    'subject': 'first message subject',
-    'sender': 'first message sender'
-  },
-  ... (other threads matching the query)
-]"
-`;
+Example result for threads:
+"[{
+  'id': 'thread_id',
+  'snippet': 'thread snippet',
+  'body': 'first message body',
+  'subject': 'first message subject',
+  'sender': 'first message sender'
+},
+... (other threads matching the query)
+]"`;

libs/langchain-community/src/tools/gmail/get_message.ts

@@ -18,13 +18,15 @@ export class GmailGetMessage extends GmailBaseTool {
   async _call(arg: z.output<typeof this.schema>) {
     const { messageId } = arg;
 
-    const message = await this.gmail.users.messages.get({
+    const gmail = await this.getGmailClient();
+
+    const { data } = await gmail.users.messages.get({
       userId: "me",
+      format: "full",
+
       id: messageId,
     });
 
-    const { data } = message;
-
     if (!data) {
       throw new Error("No data returned from Gmail");
     }
@@ -41,21 +43,17 @@ export class GmailGetMessage extends GmailBaseTool {
       throw new Error("No headers returned from Gmail");
     }
 
-    const subject = headers.find((header) => header.name === "Subject");
+    const { subject, sender, body } = this.parseHeaderAndBody(payload);
 
     if (!subject) {
       throw new Error("No subject returned from Gmail");
     }
 
-    const body = headers.find((header) => header.name === "Body");
-
     if (!body) {
       throw new Error("No body returned from Gmail");
     }
 
-    const from = headers.find((header) => header.name === "From");
-
-    if (!from) {
+    if (!sender) {
       throw new Error("No from returned from Gmail");
     }
 
@@ -81,8 +79,8 @@ export class GmailGetMessage extends GmailBaseTool {
 
     return `Result for the prompt ${messageId} \n${JSON.stringify({
       subject: subject.value,
-      body: body.value,
-      from: from.value,
+      body,
+      from: sender.value,
       to: to.value,
       date: date.value,
       messageId: messageIdHeader.value,