@divyacon/piece-gmail 0.0.0-stage → 0.1.0

package/src/lib/actions/get-label-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 { gmailGetLabelActionOutputSchema } from '../output-schemas';
+
+export const gmailGetLabelAction = createAction({
+  auth: gmailAuth,
+  name: 'gmail_get_label',
+  displayName: 'Get Label',
+  description:
+    'Get a single label by its ID, including message and thread counts.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Fetches a single label by its label ID, returning its name, type, visibility, color, and message/thread counts. Use this to inspect a label or read how many messages carry it; obtain the label ID from List Labels. Idempotent: a read-only lookup that does not modify the mailbox.',
+    idempotent: true,
+  },
+  props: {
+    label_id: Property.ShortText({
+      displayName: 'Label ID',
+      description: 'The ID of the label to read (obtain from List Labels).',
+      required: true,
+    }),
+  },
+  outputSchema: gmailGetLabelActionOutputSchema,
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+    const gmail = googleGmail({ version: 'v1', auth: authClient });
+
+    try {
+      const response = await gmail.users.labels.get({
+        userId: 'me',
+        id: context.propsValue.label_id,
+      });
+      return response.data;
+    } catch (error: any) {
+      if (error.code === 403) {
+        throw new Error(
+          'Insufficient permissions to read the label. Ensure the gmail.readonly scope is granted.'
+        );
+      } else if (error.code === 404) {
+        throw new Error(
+          `Label not found: "${context.propsValue.label_id}". Use List Labels to find a valid label ID.`
+        );
+      } else if (error.code === 429) {
+        throw new Error(
+          'Gmail API rate limit exceeded. Please try again later.'
+        );
+      }
+      throw new Error(`Failed to get label: ${error.message}`);
+    }
+  },
+});

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

@@ -0,0 +1,52 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { gmailAuth, createGoogleClient } from '../auth';
+import { gmail as googleGmail } from '@googleapis/gmail';
+import { convertAttachment, parseStream } from '../common/data';
+import { gmailGetMailActionOutputSchema } from '../output-schemas';
+
+export const gmailGetEmailAction = createAction({
+  auth: gmailAuth,
+  name: 'gmail_get_mail',
+  description: 'Get an email via Id.',
+  audience: 'human',
+  aiMetadata: {
+    description:
+      'Fetches a single email by its Gmail message ID and returns its parsed contents, including headers, body, and decoded attachments. Use this to read the full details of a specific known message, typically after a trigger or search yields its ID. Idempotent: a read-only lookup that does not modify the mailbox.',
+    idempotent: true,
+  },
+  displayName: 'Get Email',
+  props: {
+    message_id: Property.ShortText({
+      displayName: 'Message ID',
+      description: 'The messageId of the mail to read.',
+      required: true,
+    }),
+  },
+  outputSchema: gmailGetMailActionOutputSchema,
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+
+    const gmail = googleGmail({ version: 'v1', auth: authClient });
+
+    const rawMailResponse = await gmail.users.messages.get({
+      userId: 'me',
+      id: context.propsValue.message_id!,
+      format: 'raw',
+    });
+
+    const parsedMailResponse = await parseStream(
+      Buffer.from(rawMailResponse.data.raw as string, 'base64').toString(
+        'utf-8'
+      )
+    );
+
+    return {
+      id: context.propsValue.message_id,
+      ...parsedMailResponse,
+      attachments: await convertAttachment(
+        parsedMailResponse.attachments,
+        context.files
+      ),
+    };
+  },
+});

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

@@ -0,0 +1,39 @@
+import { createAction } from '@agnocon/pieces-framework';
+import { gmailAuth, createGoogleClient } from '../auth';
+import { gmail as googleGmail } from '@googleapis/gmail';
+import { gmailGetProfileActionOutputSchema } from '../output-schemas';
+
+export const gmailGetProfileAction = createAction({
+  auth: gmailAuth,
+  name: 'gmail_get_profile',
+  displayName: 'Get Profile',
+  description: 'Get the connected mailbox profile.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Returns the connected mailbox profile: the account email address, total message and thread counts, and the current history ID. Use this to confirm which account is connected or to obtain the starting history ID for List History. Idempotent: a read-only lookup that does not modify the mailbox.',
+    idempotent: true,
+  },
+  props: {},
+  outputSchema: gmailGetProfileActionOutputSchema,
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+    const gmail = googleGmail({ version: 'v1', auth: authClient });
+
+    try {
+      const response = await gmail.users.getProfile({ userId: 'me' });
+      return response.data;
+    } catch (error: any) {
+      if (error.code === 403) {
+        throw new Error(
+          'Insufficient permissions to read the profile. 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 get profile: ${error.message}`);
+    }
+  },
+});

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

@@ -0,0 +1,47 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { GmailRequests } from '../common/data';
+import { GmailMessageFormat } from '../common/models';
+import { gmailAuth, getAccessToken } from '../auth';
+import { gmailGetThreadActionOutputSchema } from '../output-schemas';
+
+export const gmailGetThread = createAction({
+  auth: gmailAuth,
+  name: 'gmail_get_thread',
+  description: 'Get a thread from your Gmail account via Id',
+  displayName: 'Get Thread',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Fetches an entire email conversation by its Gmail thread ID, returning every message in the thread. Use this to read a full conversation or to discover the message IDs within a thread before replying; obtain the thread ID from Search Email or List Threads. Idempotent: a read-only lookup that does not modify the mailbox.',
+    idempotent: true,
+  },
+  props: {
+    thread_id: Property.ShortText({
+      displayName: 'Thread ID',
+      description: 'The thread Id of the mail to read',
+      required: true,
+    }),
+    format: Property.StaticDropdown<GmailMessageFormat>({
+      displayName: 'Format',
+      description: 'Format of the mail',
+      required: false,
+      defaultValue: 'full',
+      options: {
+        disabled: false,
+        options: [
+          { value: GmailMessageFormat.MINIMAL, label: 'Minimal' },
+          { value: GmailMessageFormat.FULL, label: 'Full' },
+          { value: GmailMessageFormat.RAW, label: 'Raw' },
+          { value: GmailMessageFormat.METADATA, label: 'Metadata' },
+        ],
+      },
+    }),
+  },
+  outputSchema: gmailGetThreadActionOutputSchema,
+  run: async ({ auth, propsValue: { format, thread_id } }) =>
+    await GmailRequests.getThread({
+      access_token: await getAccessToken(auth),
+      thread_id,
+      format: format ?? GmailMessageFormat.FULL,
+    }),
+});

package/src/lib/actions/list-drafts-action.ts

@@ -0,0 +1,72 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { gmailAuth, createGoogleClient } from '../auth';
+import { gmail as googleGmail } from '@googleapis/gmail';
+import { gmailListDraftsActionOutputSchema } from '../output-schemas';
+
+export const gmailListDraftsAction = createAction({
+  auth: gmailAuth,
+  name: 'gmail_list_drafts',
+  displayName: 'List Drafts',
+  description: 'List draft emails in the mailbox.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Lists draft emails in the connected mailbox, returning each draft ID and its associated message. This is the resolver for obtaining draft IDs used by Get Draft, Update Draft, Send Draft, and Delete Draft. Optionally narrow with a Gmail search query and bound with Max Results. Idempotent: a read-only listing that does not modify the mailbox.',
+    idempotent: true,
+  },
+  props: {
+    query: Property.ShortText({
+      displayName: 'Search Query',
+      description:
+        'Optional Gmail search query to filter drafts (e.g. "subject:invoice").',
+      required: false,
+    }),
+    max_results: Property.Number({
+      displayName: 'Max Results',
+      description: 'Maximum number of drafts to return (1-500).',
+      required: false,
+      defaultValue: 20,
+    }),
+  },
+  outputSchema: gmailListDraftsActionOutputSchema,
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+    const gmail = googleGmail({ version: 'v1', auth: authClient });
+
+    const maxResults = Math.min(
+      Math.max(context.propsValue.max_results || 20, 1),
+      500
+    );
+
+    try {
+      const response = await gmail.users.drafts.list({
+        userId: 'me',
+        maxResults,
+        ...(context.propsValue.query?.trim()
+          ? { q: context.propsValue.query.trim() }
+          : {}),
+      });
+
+      const drafts = response.data.drafts || [];
+      return {
+        drafts,
+        count: drafts.length,
+        resultSizeEstimate: response.data.resultSizeEstimate,
+        ...(response.data.nextPageToken
+          ? { nextPageToken: response.data.nextPageToken }
+          : {}),
+      };
+    } catch (error: any) {
+      if (error.code === 403) {
+        throw new Error(
+          'Insufficient permissions to list drafts. Ensure the gmail.readonly scope is granted.'
+        );
+      } else if (error.code === 429) {
+        throw new Error(
+          'Gmail API rate limit exceeded. Please try again later.'
+        );
+      }
+      throw new Error(`Failed to list drafts: ${error.message}`);
+    }
+  },
+});

package/src/lib/actions/list-history-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 { gmailListHistoryActionOutputSchema } from '../output-schemas';
+
+export const gmailListHistoryAction = createAction({
+  auth: gmailAuth,
+  name: 'gmail_list_history',
+  displayName: 'List History',
+  description: 'List mailbox changes since a given history ID.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Returns the incremental change log (messages added, deleted, or relabeled) since a given starting history ID. Use this to detect what changed in the mailbox since a previous checkpoint; obtain the starting history ID from Get Profile (or a prior run). Idempotent: a read-only listing that does not modify the mailbox.',
+    idempotent: true,
+  },
+  props: {
+    start_history_id: Property.ShortText({
+      displayName: 'Start History ID',
+      description:
+        'Return changes after this history ID (obtain from Get Profile or a previous history result).',
+      required: true,
+    }),
+    history_types: Property.StaticMultiSelectDropdown({
+      displayName: 'History Types',
+      description: 'Limit results to these change types (leave empty for all).',
+      required: false,
+      options: {
+        disabled: false,
+        options: [
+          { label: 'Message Added', value: 'messageAdded' },
+          { label: 'Message Deleted', value: 'messageDeleted' },
+          { label: 'Label Added', value: 'labelAdded' },
+          { label: 'Label Removed', value: 'labelRemoved' },
+        ],
+      },
+    }),
+    max_results: Property.Number({
+      displayName: 'Max Results',
+      description: 'Maximum number of history records to return (1-500).',
+      required: false,
+      defaultValue: 100,
+    }),
+  },
+  outputSchema: gmailListHistoryActionOutputSchema,
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+    const gmail = googleGmail({ version: 'v1', auth: authClient });
+
+    const maxResults = Math.min(
+      Math.max(context.propsValue.max_results || 100, 1),
+      500
+    );
+    const historyTypes = context.propsValue.history_types as
+      | string[]
+      | undefined;
+
+    try {
+      const response = await gmail.users.history.list({
+        userId: 'me',
+        startHistoryId: context.propsValue.start_history_id,
+        maxResults,
+        ...(historyTypes && historyTypes.length > 0 ? { historyTypes } : {}),
+      });
+      return response.data;
+    } catch (error: any) {
+      if (error.code === 403) {
+        throw new Error(
+          'Insufficient permissions to read history. Ensure the gmail.readonly scope is granted.'
+        );
+      } else if (error.code === 404) {
+        throw new Error(
+          'The start history ID is too old or invalid. Fetch a fresh history ID from Get Profile.'
+        );
+      } else if (error.code === 429) {
+        throw new Error(
+          'Gmail API rate limit exceeded. Please try again later.'
+        );
+      }
+      throw new Error(`Failed to list history: ${error.message}`);
+    }
+  },
+});

package/src/lib/actions/list-labels-action.ts

@@ -0,0 +1,43 @@
+import { createAction } from '@agnocon/pieces-framework';
+import { gmailAuth, createGoogleClient } from '../auth';
+import { gmail as googleGmail } from '@googleapis/gmail';
+import { gmailListLabelsActionOutputSchema } from '../output-schemas';
+
+export const gmailListLabelsAction = createAction({
+  auth: gmailAuth,
+  name: 'gmail_list_labels',
+  displayName: 'List Labels',
+  description: 'List all labels in the mailbox.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Lists every label in the mailbox (both system labels like INBOX/UNREAD/STARRED and user-created labels) with their IDs, names, and types. This is the primary resolver for label IDs — look up a label ID by name here before passing it to Get Label or any label-aware action. Idempotent: a read-only listing that does not modify the mailbox.',
+    idempotent: true,
+  },
+  props: {},
+  outputSchema: gmailListLabelsActionOutputSchema,
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+    const gmail = googleGmail({ version: 'v1', auth: authClient });
+
+    try {
+      const response = await gmail.users.labels.list({ userId: 'me' });
+      const labels = response.data.labels || [];
+      return {
+        labels,
+        count: labels.length,
+      };
+    } catch (error: any) {
+      if (error.code === 403) {
+        throw new Error(
+          'Insufficient permissions to list labels. Ensure the gmail.readonly scope is granted.'
+        );
+      } else if (error.code === 429) {
+        throw new Error(
+          'Gmail API rate limit exceeded. Please try again later.'
+        );
+      }
+      throw new Error(`Failed to list labels: ${error.message}`);
+    }
+  },
+});

package/src/lib/actions/list-threads-action.ts

@@ -0,0 +1,89 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { gmailAuth, createGoogleClient } from '../auth';
+import { gmail as googleGmail } from '@googleapis/gmail';
+import { gmailListThreadsActionOutputSchema } from '../output-schemas';
+
+export const gmailListThreadsAction = createAction({
+  auth: gmailAuth,
+  name: 'gmail_list_threads',
+  displayName: 'List Threads',
+  description: 'List email conversation threads in the mailbox.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Lists email conversation threads matching an optional Gmail search query and label filter, returning each thread ID and snippet. This is the resolver for obtaining thread IDs used by Get Thread and Reply to Thread. Resolve label IDs with List Labels. Idempotent: a read-only listing that does not modify the mailbox.',
+    idempotent: true,
+  },
+  props: {
+    query: Property.ShortText({
+      displayName: 'Search Query',
+      description:
+        'Optional Gmail search query to filter threads (e.g. "from:boss@example.com is:unread").',
+      required: false,
+    }),
+    label_ids: Property.Array({
+      displayName: 'Label IDs',
+      description:
+        'Optional list of label IDs to filter by (resolve via List Labels; system labels like INBOX, UNREAD are valid).',
+      required: false,
+    }),
+    include_spam_trash: Property.Checkbox({
+      displayName: 'Include Spam & Trash',
+      description: 'Include threads from Spam and Trash in the results.',
+      required: false,
+      defaultValue: false,
+    }),
+    max_results: Property.Number({
+      displayName: 'Max Results',
+      description: 'Maximum number of threads to return (1-500).',
+      required: false,
+      defaultValue: 20,
+    }),
+  },
+  outputSchema: gmailListThreadsActionOutputSchema,
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+    const gmail = googleGmail({ version: 'v1', auth: authClient });
+
+    const maxResults = Math.min(
+      Math.max(context.propsValue.max_results || 20, 1),
+      500
+    );
+    const labelIds = (
+      context.propsValue.label_ids as string[] | undefined
+    )?.filter((id) => id !== '');
+
+    try {
+      const response = await gmail.users.threads.list({
+        userId: 'me',
+        maxResults,
+        includeSpamTrash: context.propsValue.include_spam_trash,
+        ...(context.propsValue.query?.trim()
+          ? { q: context.propsValue.query.trim() }
+          : {}),
+        ...(labelIds && labelIds.length > 0 ? { labelIds } : {}),
+      });
+
+      const threads = response.data.threads || [];
+      return {
+        threads,
+        count: threads.length,
+        resultSizeEstimate: response.data.resultSizeEstimate,
+        ...(response.data.nextPageToken
+          ? { nextPageToken: response.data.nextPageToken }
+          : {}),
+      };
+    } catch (error: any) {
+      if (error.code === 403) {
+        throw new Error(
+          'Insufficient permissions to list threads. Ensure the gmail.readonly scope is granted.'
+        );
+      } else if (error.code === 429) {
+        throw new Error(
+          'Gmail API rate limit exceeded. Please try again later.'
+        );
+      }
+      throw new Error(`Failed to list threads: ${error.message}`);
+    }
+  },
+});