@divyacon/piece-gmail 0.0.0-stage → 0.1.0

package/src/lib/actions/create-draft-reply-action.ts

@@ -0,0 +1,314 @@
+import { 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 { GmailProps } from '../common/props';
+import { createDraftReplyActionOutputSchema } from '../output-schemas';
+
+export const gmailCreateDraftReplyAction = createAction({
+  auth: gmailAuth,
+  name: 'create_draft_reply',
+  description: 'Creates a draft reply to an existing email.',
+  audience: 'human',
+  aiMetadata: {
+    description:
+      'Builds a draft reply to an existing email and saves it (unsent) in the thread, addressing the original sender (reply) or all participants (reply all) and optionally quoting the original message. Use this when a human should review and send the response rather than sending it automatically; requires the Gmail message ID of the email being replied to. Not idempotent: each call creates a new draft.',
+    idempotent: false,
+  },
+  displayName: 'Create Draft Reply',
+  props: {
+    message_id: GmailProps.message,
+    reply_type: Property.StaticDropdown({
+      displayName: 'Reply Type',
+      description:
+        'Choose whether to reply to sender only or to all recipients',
+      required: true,
+      defaultValue: 'reply',
+      options: {
+        disabled: false,
+        options: [
+          {
+            label: 'Reply (to sender only)',
+            value: 'reply',
+          },
+          {
+            label: 'Reply All (to all recipients)',
+            value: 'reply_all',
+          },
+        ],
+      },
+    }),
+    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: 'Draft Reply Body',
+      description: 'Your draft reply message content',
+      required: false,
+    }),
+    include_original_message: Property.Checkbox({
+      displayName: 'Include Original Message',
+      description: 'Include the original message content in the draft reply',
+      required: true,
+      defaultValue: true,
+    }),
+    sender_name: Property.ShortText({
+      displayName: 'Sender Name',
+      description: 'Optional sender name to display',
+      required: false,
+    }),
+    attachment: Property.File({
+      displayName: 'Attachment',
+      description: 'Optional file to attach to your draft reply',
+      required: false,
+    }),
+    attachment_name: Property.ShortText({
+      displayName: 'Attachment Name',
+      description: 'Custom name for the attachment',
+      required: false,
+    }),
+  },
+  outputSchema: createDraftReplyActionOutputSchema,
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+
+    const gmail = googleGmail({ version: 'v1', auth: authClient });
+
+    const originalMessage = await gmail.users.messages.get({
+      userId: 'me',
+      id: context.propsValue.message_id,
+      format: 'full',
+    });
+
+    if (!originalMessage.data || !originalMessage.data.payload) {
+      throw new Error('Could not fetch original message details');
+    }
+
+    const headers = originalMessage.data.payload.headers || [];
+    const headerMap = headers.reduce(
+      (acc: { [key: string]: string }, header) => {
+        if (header.name && header.value) {
+          acc[header.name.toLowerCase()] = header.value;
+        }
+        return acc;
+      },
+      {}
+    );
+
+    const originalSubject = headerMap['subject'] || '';
+    const originalFrom = headerMap['from'] || '';
+    const originalTo = headerMap['to'] || '';
+    const originalCc = headerMap['cc'] || '';
+    const originalReplyTo = headerMap['reply-to'] || '';
+    const originalMessageId = headerMap['message-id'] || '';
+    const originalReferences = headerMap['references'] || '';
+    const originalDate = headerMap['date'] || '';
+
+    let originalMessageContent = '';
+    if (context.propsValue.include_original_message) {
+      try {
+        const { parseStream } = await import('../common/data');
+
+        const originalMessageFull = await gmail.users.messages.get({
+          userId: 'me',
+          id: context.propsValue.message_id,
+          format: 'raw',
+        });
+
+        if (originalMessageFull.data.raw) {
+          const rawMessage = Buffer.from(
+            originalMessageFull.data.raw,
+            'base64'
+          ).toString('utf-8');
+          const parsedMessage = await parseStream(rawMessage);
+
+          let messageText = parsedMessage.text || '';
+          if (!messageText && parsedMessage.html) {
+            messageText = parsedMessage.html
+              .replace(/<[^>]*>/g, '')
+              .replace(/&nbsp;/g, ' ')
+              .replace(/&amp;/g, '&')
+              .replace(/&lt;/g, '<')
+              .replace(/&gt;/g, '>');
+          }
+
+          if (messageText) {
+            const quotedLines = messageText
+              .split('\n')
+              .map((line) => `> ${line.trim()}`);
+            const senderInfo = `On ${originalDate}, ${originalFrom} wrote:`;
+            originalMessageContent = `${senderInfo}\n${quotedLines.join('\n')}`;
+          }
+        }
+      } catch (error) {
+        console.warn(
+          'Could not extract original message content for quoting:',
+          error
+        );
+        originalMessageContent = `On ${originalDate}, ${originalFrom} wrote:\n> [Original message content could not be parsed]`;
+      }
+    }
+
+    const toRecipients: string[] = [];
+    const ccRecipients: string[] = [];
+
+    if (context.propsValue.reply_type === 'reply_all') {
+      const senderEmail = originalReplyTo || originalFrom;
+      if (senderEmail) {
+        toRecipients.push(senderEmail);
+      }
+
+      const currentUserEmail = await getUserEmail(context.auth, authClient);
+
+      if (originalTo) {
+        const toEmails = originalTo.split(',').map((email) => email.trim());
+        toRecipients.push(
+          ...toEmails.filter((email) => !email.includes(currentUserEmail || ''))
+        );
+      }
+
+      if (originalCc) {
+        const ccEmails = originalCc.split(',').map((email) => email.trim());
+        ccRecipients.push(
+          ...ccEmails.filter((email) => !email.includes(currentUserEmail || ''))
+        );
+      }
+    } else {
+      const senderEmail = originalReplyTo || originalFrom;
+      if (senderEmail) {
+        toRecipients.push(senderEmail);
+      }
+    }
+
+    let replySubject = originalSubject;
+    if (!replySubject.toLowerCase().startsWith('re:')) {
+      replySubject = `Re: ${replySubject}`;
+    }
+
+    let referencesHeader = originalMessageId;
+    if (originalReferences) {
+      referencesHeader = `${originalReferences} ${originalMessageId}`;
+    }
+
+    const senderEmail = await getUserEmail(context.auth, authClient);
+
+    let draftBody = context.propsValue.body || '';
+
+    if (context.propsValue.include_original_message && originalMessageContent) {
+      const separator =
+        context.propsValue.body_type === 'html'
+          ? '<br><br>--- Original Message ---<br>'
+          : '\n\n--- Original Message ---\n';
+
+      const quotedContent =
+        context.propsValue.body_type === 'html'
+          ? originalMessageContent.replace(/\n/g, '<br>')
+          : originalMessageContent;
+
+      draftBody = draftBody
+        ? `${draftBody}${separator}${quotedContent}`
+        : quotedContent;
+    }
+
+    const subjectBase64 = Buffer.from(replySubject).toString('base64');
+    const mailOptions: Mail.Options = {
+      to: toRecipients.join(', '),
+      cc: ccRecipients.length > 0 ? ccRecipients.join(', ') : undefined,
+      subject: `=?UTF-8?B?${subjectBase64}?=`,
+      text:
+        context.propsValue.body_type === 'plain_text' ? draftBody : undefined,
+      html: context.propsValue.body_type === 'html' ? draftBody : undefined,
+      attachments: [],
+      headers: [
+        {
+          key: 'In-Reply-To',
+          value: originalMessageId,
+        },
+        {
+          key: 'References',
+          value: referencesHeader,
+        },
+      ],
+    };
+
+    if (senderEmail) {
+      mailOptions.from = context.propsValue.sender_name
+        ? `${context.propsValue.sender_name} <${senderEmail}>`
+        : senderEmail;
+    }
+
+    if (context.propsValue.attachment) {
+      const lookupResult = mime.lookup(
+        context.propsValue.attachment.extension || ''
+      );
+      const attachmentOption: Attachment[] = [
+        {
+          filename:
+            context.propsValue.attachment_name ??
+            context.propsValue.attachment.filename,
+          content: context.propsValue.attachment.base64,
+          contentType: 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, '_');
+
+    const draft = await gmail.users.drafts.create({
+      userId: 'me',
+      requestBody: {
+        message: {
+          threadId: originalMessage.data.threadId || undefined,
+          raw: encodedPayload,
+        },
+      },
+    });
+
+    return {
+      ...draft.data,
+      originalMessage: {
+        id: context.propsValue.message_id,
+        subject: originalSubject,
+        from: originalFrom,
+        to: originalTo,
+        date: originalDate,
+        threadId: originalMessage.data.threadId,
+      },
+      draftDetails: {
+        replyType: context.propsValue.reply_type,
+        recipients: {
+          to: toRecipients,
+          cc: ccRecipients,
+        },
+        subject: replySubject,
+        includeOriginal: context.propsValue.include_original_message,
+      },
+    };
+  },
+});

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

@@ -0,0 +1,57 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { gmailAuth, createGoogleClient } from '../auth';
+import { gmail as googleGmail } from '@googleapis/gmail';
+
+export const gmailDeleteDraftAction = createAction({
+  auth: gmailAuth,
+  name: 'gmail_delete_draft',
+  displayName: 'Delete Draft',
+  description: 'Permanently delete a draft email by its ID.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Permanently removes a draft email by its draft ID. This only deletes the unsent draft (not a sent message) but the draft itself is not recoverable. Obtain the draft ID from List Drafts. Idempotent: if no draft matches the ID (already removed, or an invalid ID) it returns deleted:false instead of failing — check that flag rather than assuming a delete happened.',
+    idempotent: true,
+  },
+  props: {
+    draft_id: Property.ShortText({
+      displayName: 'Draft ID',
+      description: 'The ID of the draft to delete (obtain from List Drafts).',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+    const gmail = googleGmail({ version: 'v1', auth: authClient });
+
+    try {
+      await gmail.users.drafts.delete({
+        userId: 'me',
+        id: context.propsValue.draft_id,
+      });
+      return {
+        success: true,
+        deleted: true,
+        draftId: context.propsValue.draft_id,
+      };
+    } catch (error: any) {
+      if (error.code === 403) {
+        throw new Error(
+          'Insufficient permissions to delete a draft. Ensure the gmail.compose scope is granted.'
+        );
+      } else if (error.code === 404) {
+        return {
+          success: false,
+          deleted: false,
+          draftId: context.propsValue.draft_id,
+          message: `No draft with ID "${context.propsValue.draft_id}" was found — it may already be deleted, or the ID is invalid. Verify with List Drafts.`,
+        };
+      } else if (error.code === 429) {
+        throw new Error(
+          'Gmail API rate limit exceeded. Please try again later.'
+        );
+      }
+      throw new Error(`Failed to delete draft: ${error.message}`);
+    }
+  },
+});

package/src/lib/actions/forward-message-action.ts

@@ -0,0 +1,159 @@
+import { ApFile, createAction, Property } from '@agnocon/pieces-framework';
+import { gmailAuth, createGoogleClient, getUserEmail } from '../auth';
+import { gmail as googleGmail } from '@googleapis/gmail';
+import { GmailMime } from '../common/mime';
+import { parseStream } from '../common/data';
+import { gmailForwardMessageActionOutputSchema } from '../output-schemas';
+
+export const gmailForwardMessageAction = createAction({
+  auth: gmailAuth,
+  name: 'gmail_forward_message',
+  displayName: 'Forward Message',
+  description: 'Forward an existing email to new recipients.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Forwards an existing email to one or more new recipients, quoting the original sender, subject, and body beneath an optional added note. Requires the Gmail message ID of the email to forward (obtain from Search Email or Get Message). Performs two calls: it fetches the original message, then sends the forwarded copy. Not idempotent: each call sends a new forwarded message.',
+    idempotent: false,
+  },
+  props: {
+    message_id: Property.ShortText({
+      displayName: 'Message ID',
+      description:
+        'The Gmail message ID to forward (obtain from Search Email or Get Message).',
+      required: true,
+    }),
+    receiver: Property.Array({
+      displayName: 'Receiver Email (To)',
+      description: 'One or more recipients to forward the email to.',
+      required: true,
+    }),
+    cc: Property.Array({
+      displayName: 'CC Email',
+      required: false,
+    }),
+    bcc: Property.Array({
+      displayName: 'BCC Email',
+      required: false,
+    }),
+    note: Property.LongText({
+      displayName: 'Note',
+      description: 'Optional message to add above the forwarded content.',
+      required: false,
+    }),
+    sender_name: Property.ShortText({
+      displayName: 'Sender Name',
+      required: false,
+    }),
+  },
+  outputSchema: gmailForwardMessageActionOutputSchema,
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+    const gmail = googleGmail({ version: 'v1', auth: authClient });
+
+    try {
+      const original = await gmail.users.messages.get({
+        userId: 'me',
+        id: context.propsValue.message_id,
+        format: 'raw',
+      });
+
+      if (!original.data.raw) {
+        throw new Error('Could not fetch the original message to forward.');
+      }
+
+      const parsed = await parseStream(
+        Buffer.from(original.data.raw, 'base64').toString('utf-8')
+      );
+
+      const originalSubject = parsed.subject || '';
+      const forwardSubject = originalSubject.toLowerCase().startsWith('fwd:')
+        ? originalSubject
+        : `Fwd: ${originalSubject}`;
+
+      const originalFrom =
+        typeof parsed.from?.text === 'string' ? parsed.from.text : '';
+      const originalTo =
+        parsed.to && !Array.isArray(parsed.to) ? parsed.to.text : '';
+      const originalDate = parsed.date ? parsed.date.toUTCString() : '';
+
+      const note = context.propsValue.note
+        ? `${context.propsValue.note}\n\n`
+        : '';
+      const htmlAsText = parsed.html ? parsed.html.replace(/<[^>]*>/g, '') : '';
+      const originalBody = parsed.text || htmlAsText || '';
+      const quotedBody = originalBody
+        .split('\n')
+        .map((line) => `> ${line}`)
+        .join('\n');
+      const forwardedBody =
+        `${note}---------- Forwarded message ----------\n` +
+        `From: ${originalFrom}\n` +
+        `Date: ${originalDate}\n` +
+        `Subject: ${originalSubject}\n` +
+        `To: ${originalTo}\n\n` +
+        `${quotedBody}`;
+
+      const receiver = (context.propsValue.receiver as string[]).filter(
+        (email) => email !== ''
+      );
+      const cc = (context.propsValue.cc as string[] | undefined)?.filter(
+        (email) => email !== ''
+      );
+      const bcc = (context.propsValue.bcc as string[] | undefined)?.filter(
+        (email) => email !== ''
+      );
+
+      const senderEmail = await getUserEmail(context.auth, authClient);
+      const from = senderEmail
+        ? context.propsValue.sender_name
+          ? `${context.propsValue.sender_name} <${senderEmail}>`
+          : senderEmail
+        : undefined;
+
+      const forwardedAttachments = (parsed.attachments || [])
+        .filter((attachment) => attachment.content)
+        .map((attachment) => ({
+          file: new ApFile(
+            attachment.filename ?? `attachment-${Date.now()}`,
+            Buffer.from(attachment.content),
+            attachment.filename?.split('.').pop()
+          ),
+          name: attachment.filename ?? undefined,
+        }));
+
+      const raw = await GmailMime.buildRawMessage({
+        to: receiver,
+        cc,
+        bcc,
+        from,
+        subject: forwardSubject,
+        bodyType: 'plain_text',
+        body: forwardedBody,
+        attachments: forwardedAttachments,
+      });
+
+      const response = await gmail.users.messages.send({
+        userId: 'me',
+        requestBody: { raw },
+      });
+
+      return response.data;
+    } catch (error: any) {
+      if (error.code === 403) {
+        throw new Error(
+          'Insufficient permissions to forward the message. Ensure the gmail.send and gmail.readonly scopes are granted.'
+        );
+      } else if (error.code === 404) {
+        throw new Error(
+          `Original message not found: "${context.propsValue.message_id}". Use Search Email to find a valid message ID.`
+        );
+      } else if (error.code === 429) {
+        throw new Error(
+          'Gmail API rate limit exceeded. Please try again later.'
+        );
+      }
+      throw new Error(`Failed to forward message: ${error.message}`);
+    }
+  },
+});

package/src/lib/actions/get-attachment-action.ts

@@ -0,0 +1,83 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { gmailAuth, createGoogleClient } from '../auth';
+import { gmail as googleGmail } from '@googleapis/gmail';
+import { gmailGetAttachmentActionOutputSchema } from '../output-schemas';
+
+export const gmailGetAttachmentAction = createAction({
+  auth: gmailAuth,
+  name: 'gmail_get_attachment',
+  displayName: 'Get Attachment',
+  description: 'Download an email attachment by message ID and attachment ID.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      "Fetches one email attachment's raw bytes by message ID + attachment ID, returning a stored file plus size. Note: Get Message already returns each attachment's downloaded content directly, so prefer that; use this only when you separately hold a raw Gmail attachment ID (from the message payload parts) and need the bytes on their own. Get the message ID from Search Email. Idempotent: a read-only fetch that does not modify the mailbox.",
+    idempotent: true,
+  },
+  props: {
+    message_id: Property.ShortText({
+      displayName: 'Message ID',
+      description:
+        'The Gmail message ID the attachment belongs to (obtain from Search Email or Get Message).',
+      required: true,
+    }),
+    attachment_id: Property.ShortText({
+      displayName: 'Attachment ID',
+      description:
+        'The raw Gmail attachment ID, taken from the message payload parts (parts[].body.attachmentId of a full-format message). Note: Get Message returns attachment content directly, so this field is only needed for the raw-ID fetch path.',
+      required: true,
+    }),
+    file_name: Property.ShortText({
+      displayName: 'File Name',
+      description: 'Optional name to give the downloaded file.',
+      required: false,
+    }),
+  },
+  outputSchema: gmailGetAttachmentActionOutputSchema,
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+    const gmail = googleGmail({ version: 'v1', auth: authClient });
+
+    try {
+      const response = await gmail.users.messages.attachments.get({
+        userId: 'me',
+        messageId: context.propsValue.message_id,
+        id: context.propsValue.attachment_id,
+      });
+
+      const data = response.data.data;
+      if (!data) {
+        throw new Error('Attachment returned no data.');
+      }
+
+      const fileName =
+        context.propsValue.file_name ||
+        `attachment-${context.propsValue.attachment_id}`;
+      const fileUrl = await context.files.write({
+        fileName,
+        data: Buffer.from(data, 'base64'),
+      });
+
+      return {
+        fileName,
+        size: response.data.size,
+        data: fileUrl,
+      };
+    } catch (error: any) {
+      if (error.code === 403) {
+        throw new Error(
+          'Insufficient permissions to read the attachment. Ensure the gmail.readonly scope is granted.'
+        );
+      } else if (error.code === 404) {
+        throw new Error(
+          'Attachment or message not found. Verify the message ID and attachment ID via Get Message.'
+        );
+      } else if (error.code === 429) {
+        throw new Error(
+          'Gmail API rate limit exceeded. Please try again later.'
+        );
+      }
+      throw new Error(`Failed to get attachment: ${error.message}`);
+    }
+  },
+});

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

@@ -0,0 +1,53 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { gmailAuth, createGoogleClient } from '../auth';
+import { gmail as googleGmail } from '@googleapis/gmail';
+import { gmailGetDraftActionOutputSchema } from '../output-schemas';
+
+export const gmailGetDraftAction = createAction({
+  auth: gmailAuth,
+  name: 'gmail_get_draft',
+  displayName: 'Get Draft',
+  description: 'Get a single draft email by its ID.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Fetches a single draft email by its draft ID, returning the draft and its underlying message. Use this to inspect a draft before sending or updating it; obtain the draft ID from List Drafts. Idempotent: a read-only lookup that does not modify the mailbox.',
+    idempotent: true,
+  },
+  props: {
+    draft_id: Property.ShortText({
+      displayName: 'Draft ID',
+      description: 'The ID of the draft to read (obtain from List Drafts).',
+      required: true,
+    }),
+  },
+  outputSchema: gmailGetDraftActionOutputSchema,
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+    const gmail = googleGmail({ version: 'v1', auth: authClient });
+
+    try {
+      const response = await gmail.users.drafts.get({
+        userId: 'me',
+        id: context.propsValue.draft_id,
+        format: 'full',
+      });
+      return response.data;
+    } catch (error: any) {
+      if (error.code === 403) {
+        throw new Error(
+          'Insufficient permissions to read drafts. Ensure the gmail.readonly 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 get draft: ${error.message}`);
+    }
+  },
+});