@divyacon/piece-gmail 0.0.0-stage → 0.1.0

package/src/lib/actions/send-email-action.ts

@@ -0,0 +1,213 @@
+import { ApFile, createAction, Property } from '@agnocon/pieces-framework';
+import mime from 'mime-types';
+import MailComposer from 'nodemailer/lib/mail-composer';
+import Mail, { Attachment } from 'nodemailer/lib/mailer';
+import { gmailAuth, createGoogleClient, getUserEmail } from '../auth';
+import { gmail as googleGmail } from '@googleapis/gmail';
+import { sendEmailActionOutputSchema } from '../output-schemas';
+
+export const gmailSendEmailAction = createAction({
+  auth: gmailAuth,
+  name: 'send_email',
+  description: 'Send an email through a Gmail account',
+  audience: 'human',
+  aiMetadata: {
+    description:
+      'Composes and sends a new email from the connected Gmail account to one or more recipients, with optional CC/BCC, attachments, and plain-text or HTML body. Use this to originate a fresh message; to answer an existing thread prefer Reply to Email instead, or pass an original Message-ID to send this message into that existing thread. Set the draft flag to save it as a draft instead of sending. Not idempotent: each call sends (or drafts) a separate message.',
+    idempotent: false,
+  },
+  displayName: 'Send Email',
+  props: {
+    receiver: Property.Array({
+      displayName: 'Receiver Email (To)',
+      description: undefined,
+      required: true,
+    }),
+    cc: Property.Array({
+      displayName: 'CC Email',
+      description: undefined,
+      required: false,
+    }),
+    bcc: Property.Array({
+      displayName: 'BCC Email',
+      description: undefined,
+      required: false,
+    }),
+    subject: Property.ShortText({
+      displayName: 'Subject',
+      description: undefined,
+      required: true,
+    }),
+    body_type: Property.StaticDropdown({
+      displayName: 'Body Type',
+      required: true,
+      defaultValue: 'plain_text',
+      options: {
+        disabled: false,
+        options: [
+          {
+            label: 'plain text',
+            value: 'plain_text',
+          },
+          {
+            label: 'html',
+            value: 'html',
+          },
+        ],
+      },
+    }),
+    body: Property.ShortText({
+      displayName: 'Body',
+      description: 'Body for the email you want to send',
+      required: true,
+    }),
+    reply_to: Property.Array({
+      displayName: 'Reply-To Email',
+      description: 'Email address to set as the "Reply-To" header',
+      required: false,
+    }),
+    sender_name: Property.ShortText({
+      displayName: 'Sender Name',
+      required: false,
+    }),
+    from: Property.ShortText({
+      displayName: 'Sender Email',
+      description:
+        "The address must be listed in your GMail account's settings",
+      required: false,
+    }),
+    attachments: Property.Array({
+      displayName: 'Attachments',
+      required: false,
+      properties: {
+        file: Property.File({
+          displayName: 'File',
+          description: 'File to attach to the email you want to send.',
+          required: true,
+        }),
+        name: Property.ShortText({
+          displayName: 'Attachment Name',
+          description: 'In case you want to change the name of the attachment.',
+          required: false,
+        }),
+      },
+    }),
+    in_reply_to: Property.ShortText({
+      displayName: 'In reply to',
+      description: 'Reply to this Message-ID',
+      required: false,
+    }),
+    draft: Property.Checkbox({
+      displayName: 'Create draft',
+      description: 'Create draft without sending the actual email',
+      required: true,
+      defaultValue: false,
+    }),
+  },
+  outputSchema: sendEmailActionOutputSchema,
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+
+    const gmail = googleGmail({ version: 'v1', auth: authClient });
+
+    const subjectBase64 = Buffer.from(context.propsValue['subject']).toString(
+      'base64'
+    );
+    const attachments = context.propsValue.attachments as {
+      file: ApFile;
+      name: string | undefined;
+    }[];
+    const replyTo = context.propsValue['reply_to']?.filter(
+      (email) => email !== ''
+    );
+    const receiver = context.propsValue['receiver']?.filter(
+      (email) => email !== ''
+    );
+    const cc = context.propsValue['cc']?.filter((email) => email !== '');
+    const bcc = context.propsValue['bcc']?.filter((email) => email !== '');
+    const mailOptions: Mail.Options = {
+      to: receiver.join(', '), // Join all email addresses with a comma
+      cc: cc ? cc.join(', ') : undefined,
+      bcc: bcc ? bcc.join(', ') : undefined,
+      subject: `=?UTF-8?B?${subjectBase64}?=`,
+      replyTo: replyTo ? replyTo.join(', ') : '',
+      text:
+        context.propsValue.body_type === 'plain_text'
+          ? context.propsValue['body']
+          : undefined,
+      html:
+        context.propsValue.body_type === 'html'
+          ? context.propsValue['body']
+          : undefined,
+      attachments: [],
+    };
+    let threadId = undefined;
+    if (context.propsValue.in_reply_to) {
+      mailOptions.headers = [
+        {
+          key: 'References',
+          value: context.propsValue.in_reply_to,
+        },
+        {
+          key: 'In-Reply-To',
+          value: context.propsValue.in_reply_to,
+        },
+      ];
+      const messages = await gmail.users.messages.list({
+        userId: 'me',
+        q: `Rfc822msgid:${context.propsValue.in_reply_to}`,
+      });
+      threadId = messages.data.messages?.[0].threadId;
+    }
+
+    const senderEmail =
+      context.propsValue.from || (await getUserEmail(context.auth, authClient));
+    if (senderEmail) {
+      mailOptions.from = context.propsValue.sender_name
+        ? `${context.propsValue['sender_name']} <${senderEmail}>`
+        : senderEmail;
+    }
+
+    if (attachments && attachments.length > 0) {
+      const attachmentOption: Attachment[] = attachments.map(
+        ({ file, name }) => {
+          const lookupResult = mime.lookup(
+            file.extension ? file.extension : ''
+          );
+          return {
+            filename: name ?? file.filename,
+            content: file?.base64,
+            contentType: lookupResult ? lookupResult : undefined,
+            encoding: 'base64',
+          };
+        }
+      );
+
+      mailOptions.attachments = attachmentOption;
+    }
+
+    const mail: any = new MailComposer(mailOptions).compile();
+    mail.keepBcc = true;
+    const mailBody = await mail.build();
+
+    const encodedPayload = Buffer.from(mailBody)
+      .toString('base64')
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_');
+
+    if (context.propsValue.draft) {
+      return await gmail.users.drafts.create({
+        userId: 'me',
+        requestBody: { message: { threadId, raw: encodedPayload } },
+      });
+    } else {
+      return await gmail.users.messages.send({
+        userId: 'me',
+        requestBody: {
+          threadId,
+          raw: encodedPayload,
+        },
+      });
+    }
+  },
+});

package/src/lib/actions/stop-watch-action.ts

@@ -0,0 +1,37 @@
+import { createAction } from '@agnocon/pieces-framework';
+import { gmailAuth, createGoogleClient } from '../auth';
+import { gmail as googleGmail } from '@googleapis/gmail';
+
+export const gmailStopWatchAction = createAction({
+  auth: gmailAuth,
+  name: 'gmail_stop_watch',
+  displayName: 'Stop Watch',
+  description: 'Stop push notifications on the mailbox.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Stops any active push (Cloud Pub/Sub) notifications for the connected mailbox. Use this to cancel a previously started watch. Takes no parameters. Idempotent: stopping when no watch is active is a no-op.',
+    idempotent: true,
+  },
+  props: {},
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+    const gmail = googleGmail({ version: 'v1', auth: authClient });
+
+    try {
+      await gmail.users.stop({ userId: 'me' });
+      return { success: true };
+    } catch (error: any) {
+      if (error.code === 403) {
+        throw new Error(
+          'Insufficient permissions to stop the watch. Ensure a read scope (e.g. gmail.readonly) is granted.'
+        );
+      } else if (error.code === 429) {
+        throw new Error(
+          'Gmail API rate limit exceeded. Please try again later.'
+        );
+      }
+      throw new Error(`Failed to stop watch: ${error.message}`);
+    }
+  },
+});

package/src/lib/actions/update-draft-action.ts

@@ -0,0 +1,211 @@
+import { ApFile, createAction, Property } from '@agnocon/pieces-framework';
+import { gmailAuth, createGoogleClient, getUserEmail } from '../auth';
+import { gmail as googleGmail } from '@googleapis/gmail';
+import { GmailMime, RawMimeAttachment } from '../common/mime';
+import { gmailUpdateDraftActionOutputSchema } from '../output-schemas';
+import { parseStream } from '../common/data';
+import { AddressObject } from 'mailparser';
+
+export const gmailUpdateDraftAction = createAction({
+  auth: gmailAuth,
+  name: 'gmail_update_draft',
+  displayName: 'Update Draft',
+  description: 'Replace the content of an existing draft email.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Updates an existing draft (subject, body, recipients, attachments) by its draft ID. Subject and body are required and replace the previous values; omitted recipients (To/CC/BCC), attachments, and the thread association are preserved from the existing draft rather than cleared. Obtain the draft ID from List Drafts. Not idempotent in effect: each call rewrites the draft with the supplied content.',
+    idempotent: false,
+  },
+  props: {
+    draft_id: Property.ShortText({
+      displayName: 'Draft ID',
+      description: 'The ID of the draft to update (obtain from List Drafts).',
+      required: true,
+    }),
+    receiver: Property.Array({
+      displayName: 'Receiver Email (To)',
+      required: false,
+    }),
+    cc: Property.Array({
+      displayName: 'CC Email',
+      required: false,
+    }),
+    bcc: Property.Array({
+      displayName: 'BCC Email',
+      required: false,
+    }),
+    subject: Property.ShortText({
+      displayName: 'Subject',
+      required: true,
+    }),
+    body_type: Property.StaticDropdown({
+      displayName: 'Body Type',
+      required: true,
+      defaultValue: 'plain_text',
+      options: {
+        disabled: false,
+        options: [
+          { label: 'plain text', value: 'plain_text' },
+          { label: 'html', value: 'html' },
+        ],
+      },
+    }),
+    body: Property.LongText({
+      displayName: 'Body',
+      description: 'New body for the draft email.',
+      required: true,
+    }),
+    sender_name: Property.ShortText({
+      displayName: 'Sender Name',
+      required: false,
+    }),
+    from: Property.ShortText({
+      displayName: 'Sender Email',
+      description:
+        "The address must be listed in your Gmail account's settings.",
+      required: false,
+    }),
+    thread_id: Property.ShortText({
+      displayName: 'Thread ID',
+      description:
+        'Optional thread ID to keep this draft attached to a conversation (obtain from Search Email or Get Thread).',
+      required: false,
+    }),
+    attachments: Property.Array({
+      displayName: 'Attachments',
+      required: false,
+      properties: {
+        file: Property.File({
+          displayName: 'File',
+          description: 'File to attach to the draft.',
+          required: true,
+        }),
+        name: Property.ShortText({
+          displayName: 'Attachment Name',
+          description: 'Optional name to override the attachment filename.',
+          required: false,
+        }),
+      },
+    }),
+  },
+  outputSchema: gmailUpdateDraftActionOutputSchema,
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+    const gmail = googleGmail({ version: 'v1', auth: authClient });
+
+    try {
+      let receiver = (
+        context.propsValue.receiver as string[] | undefined
+      )?.filter((email) => email !== '');
+      let cc = (context.propsValue.cc as string[] | undefined)?.filter(
+        (email) => email !== ''
+      );
+      let bcc = (context.propsValue.bcc as string[] | undefined)?.filter(
+        (email) => email !== ''
+      );
+      let threadId = context.propsValue.thread_id || undefined;
+      const newAttachments = context.propsValue.attachments as
+        | { file: ApFile; name?: string }[]
+        | undefined;
+      let preservedAttachments: RawMimeAttachment[] = [];
+
+      // A draft update replaces the whole message, so recover the recipients,
+      // attachments, and thread link from the existing draft when the caller
+      // omits them — otherwise editing only the body would silently strip the
+      // BCC list or attachments and detach the draft from its conversation.
+      // BCC is stripped from `metadata`/`full` responses, so recovering it
+      // (and the attachment content) requires the raw MIME of the draft.
+      if (
+        !receiver?.length ||
+        !cc?.length ||
+        !bcc?.length ||
+        !threadId ||
+        !newAttachments?.length
+      ) {
+        const existing = await gmail.users.drafts.get({
+          userId: 'me',
+          id: context.propsValue.draft_id,
+          format: 'raw',
+        });
+        const message = existing.data.message;
+        threadId = threadId ?? message?.threadId ?? undefined;
+
+        if (message?.raw) {
+          const parsed = await parseStream(
+            Buffer.from(message.raw, 'base64').toString('utf-8')
+          );
+          if (!receiver?.length) receiver = addressesOf(parsed.to);
+          if (!cc?.length) cc = addressesOf(parsed.cc);
+          if (!bcc?.length) bcc = addressesOf(parsed.bcc);
+          if (!newAttachments?.length) {
+            preservedAttachments = parsed.attachments.map((attachment) => ({
+              filename: attachment.filename,
+              content: attachment.content,
+              contentType: attachment.contentType,
+            }));
+          }
+        }
+      }
+
+      const senderEmail =
+        context.propsValue.from ||
+        (await getUserEmail(context.auth, authClient));
+      const from = senderEmail
+        ? context.propsValue.sender_name
+          ? `${context.propsValue.sender_name} <${senderEmail}>`
+          : senderEmail
+        : undefined;
+
+      const raw = await GmailMime.buildRawMessage({
+        to: receiver,
+        cc,
+        bcc,
+        from,
+        subject: context.propsValue.subject,
+        bodyType: context.propsValue.body_type as 'plain_text' | 'html',
+        body: context.propsValue.body,
+        attachments: newAttachments?.length
+          ? newAttachments
+          : preservedAttachments,
+      });
+
+      const response = await gmail.users.drafts.update({
+        userId: 'me',
+        id: context.propsValue.draft_id,
+        requestBody: {
+          message: {
+            raw,
+            threadId,
+          },
+        },
+      });
+
+      return response.data;
+    } catch (error: any) {
+      if (error.code === 403) {
+        throw new Error(
+          'Insufficient permissions to update a draft. Ensure the gmail.compose scope is granted.'
+        );
+      } else if (error.code === 404) {
+        throw new Error(
+          `Draft not found: "${context.propsValue.draft_id}". Use List Drafts to find a valid draft ID.`
+        );
+      } else if (error.code === 429) {
+        throw new Error(
+          'Gmail API rate limit exceeded. Please try again later.'
+        );
+      }
+      throw new Error(`Failed to update draft: ${error.message}`);
+    }
+  },
+});
+
+function addressesOf(
+  address: AddressObject | AddressObject[] | undefined
+): string[] {
+  return (Array.isArray(address) ? address : address ? [address] : [])
+    .flatMap((addressObject) => addressObject.value)
+    .map((emailAddress) => emailAddress.address)
+    .filter((emailAddress): emailAddress is string => !!emailAddress);
+}

package/src/lib/auth.ts

@@ -0,0 +1,116 @@
+import {
+  AppConnectionValueForAuthProperty,
+  PieceAuth,
+  Property,
+} from '@agnocon/pieces-framework';
+import { AppConnectionType } from '@agnocon/pieces-framework';
+import { oauth2 as googleOauth2 } from '@googleapis/oauth2';
+import { JWT, OAuth2Client } from 'google-auth-library';
+
+const gmailServiceAccountScopes = [
+  'https://www.googleapis.com/auth/gmail.send',
+  'https://www.googleapis.com/auth/gmail.readonly',
+  'https://www.googleapis.com/auth/gmail.compose',
+];
+
+export const gmailScopes = [...gmailServiceAccountScopes, 'email'];
+
+export const gmailAuth = [
+  PieceAuth.OAuth2({
+    description: '',
+    authUrl: 'https://accounts.google.com/o/oauth2/auth',
+    tokenUrl: 'https://oauth2.googleapis.com/token',
+    required: true,
+    scope: gmailScopes,
+  }),
+  PieceAuth.CustomAuth({
+    displayName: 'Service Account (Advanced)',
+    description:
+      'Authenticate via service account from https://console.cloud.google.com/ > IAM & Admin > Service Accounts > Create Service Account > Keys > Add key.  <br> <br> You can optionally use domain-wide delegation (https://support.google.com/a/answer/162106?hl=en#zippy=%2Cset-up-domain-wide-delegation-for-a-client) to access Gmail without adding the service account to each mailbox. <br> <br> **Note:** A user email with domain-wide delegation is required for Gmail service account access.',
+    required: true,
+    props: {
+      serviceAccount: Property.LongText({
+        displayName: 'Service Account JSON Key',
+        required: true,
+      }),
+      userEmail: Property.ShortText({
+        displayName: 'User Email',
+        required: true,
+        description:
+          'Email address of the user to impersonate. Required for Gmail service account access via domain-wide delegation.',
+      }),
+    },
+    validate: async ({ auth }) => {
+      try {
+        await getAccessToken({
+          type: AppConnectionType.CUSTOM_AUTH,
+          props: { ...auth },
+        });
+      } catch (e) {
+        return {
+          valid: false,
+          error: (e as Error).message,
+        };
+      }
+      return {
+        valid: true,
+      };
+    },
+  }),
+];
+
+export type GmailAuthValue = AppConnectionValueForAuthProperty<
+  typeof gmailAuth
+>;
+
+export async function createGoogleClient(
+  auth: GmailAuthValue
+): Promise<OAuth2Client> {
+  if (auth.type === AppConnectionType.CUSTOM_AUTH) {
+    let serviceAccount;
+    try {
+      serviceAccount = JSON.parse(auth.props.serviceAccount);
+    } catch {
+      throw new Error(
+        'Invalid Service Account JSON Key. Please provide a valid JSON string.'
+      );
+    }
+    return new JWT({
+      email: serviceAccount.client_email,
+      key: serviceAccount.private_key,
+      scopes: gmailServiceAccountScopes,
+      subject: auth.props.userEmail?.trim() || undefined,
+    });
+  }
+  const authClient = new OAuth2Client();
+  authClient.setCredentials(auth);
+  return authClient;
+}
+
+export const getAccessToken = async (auth: GmailAuthValue): Promise<string> => {
+  if (auth.type === AppConnectionType.CUSTOM_AUTH) {
+    const googleClient = await createGoogleClient(auth);
+    const response = await googleClient.getAccessToken();
+    if (response.token) {
+      return response.token;
+    } else {
+      throw new Error(
+        'Could not retrieve access token from service account json'
+      );
+    }
+  }
+  return auth.access_token;
+};
+
+export async function getUserEmail(
+  auth: GmailAuthValue,
+  authClient: OAuth2Client
+): Promise<string | undefined> {
+  if (auth.type === AppConnectionType.CUSTOM_AUTH) {
+    return auth.props.userEmail?.trim();
+  }
+  return (
+    (await googleOauth2({ version: 'v2', auth: authClient }).userinfo.get())
+      .data.email ?? undefined
+  );
+}