@divyacon/piece-google-drive 0.0.0-stage → 0.1.1

package/src/lib/action/drive-delete-file.ts

@@ -0,0 +1,36 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { googleDriveAuth, createGoogleClient } from '../auth';
+import { drive as googleDrive } from '@googleapis/drive';
+
+export const driveDeleteFile = createAction({
+  auth: googleDriveAuth,
+  name: 'drive_delete_file',
+  displayName: 'Delete File Permanently',
+  description: 'Permanently delete a Drive file by ID, bypassing the trash.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Permanently deletes a file by ID, bypassing the trash — unrecoverable. Use only when permanent removal is intended; for reversible deletion prefer drive_trash_file. A repeat call fails because the file no longer exists.',
+    idempotent: false,
+  },
+  props: {
+    file_id: Property.ShortText({
+      displayName: 'File ID',
+      description:
+        'The ID of the file to permanently delete. Resolve it via drive_search_files or drive_get_file.',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+
+    const drive = googleDrive({ version: 'v3', auth: authClient });
+
+    const response = await drive.files.delete({
+      fileId: context.propsValue.file_id,
+      supportsAllDrives: true,
+    });
+
+    return response.data;
+  },
+});

package/src/lib/action/drive-delete-reply.ts

@@ -0,0 +1,65 @@
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { googleDriveAuth, createGoogleClient } from '../auth';
+import { drive as googleDrive } from '@googleapis/drive';
+import { driveDeleteReplyOutputSchema } from '../output-schemas';
+
+export const driveDeleteReply = createAction({
+  auth: googleDriveAuth,
+  name: 'drive_delete_reply',
+  displayName: 'Delete Reply',
+  description: 'Permanently delete a reply on a Drive comment by ID.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Permanently deletes a reply by ID (resolve via drive_list_replies). Use to remove a reply you control; to edit it instead use drive_update_reply. A repeat call fails because the reply is already gone, so it is not safe to retry blindly.',
+    idempotent: false,
+  },
+  outputSchema: driveDeleteReplyOutputSchema,
+  props: {
+    file_id: Property.ShortText({
+      displayName: 'File ID',
+      description:
+        'The ID of the file the comment belongs to. Resolve it via drive_search_files or drive_get_file.',
+      required: true,
+    }),
+    comment_id: Property.ShortText({
+      displayName: 'Comment ID',
+      description: 'The ID of the parent comment. Resolve it via drive_list_comments.',
+      required: true,
+    }),
+    reply_id: Property.ShortText({
+      displayName: 'Reply ID',
+      description: 'The ID of the reply to delete. Resolve it via drive_list_replies.',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { file_id, comment_id, reply_id } = context.propsValue;
+
+    const authClient = await createGoogleClient(context.auth);
+
+    const drive = googleDrive({ version: 'v3', auth: authClient });
+
+    try {
+      await drive.replies.delete({
+        fileId: file_id,
+        commentId: comment_id,
+        replyId: reply_id,
+      });
+
+      return { success: true, reply_id };
+    } catch (error: any) {
+      if (error.code === 404) {
+        throw new Error(
+          `File, comment, or reply not found (file ID: ${file_id}, comment ID: ${comment_id}, reply ID: ${reply_id}). It may already be deleted. Resolve the reply ID via drive_list_replies.`
+        );
+      }
+      if (error.code === 403) {
+        throw new Error(
+          `Permission denied deleting reply ${reply_id} on file ${file_id}. You can only delete your own replies.`
+        );
+      }
+      throw error;
+    }
+  },
+});

package/src/lib/action/drive-delete-shared-drive.ts

@@ -0,0 +1,57 @@
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { googleDriveAuth, createGoogleClient } from '../auth';
+import { drive as googleDrive } from '@googleapis/drive';
+import { driveDeleteSharedDriveOutputSchema } from '../output-schemas';
+
+export const driveDeleteSharedDrive = createAction({
+  auth: googleDriveAuth,
+  name: 'drive_delete_shared_drive',
+  displayName: 'Delete Shared Drive',
+  description: 'Permanently delete a shared drive by ID.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Permanently deletes a shared drive by ID (it must already be empty). Irreversible. Use only to remove a no-longer-needed shared drive. A repeat call fails because the drive no longer exists.',
+    idempotent: false,
+  },
+  outputSchema: driveDeleteSharedDriveOutputSchema,
+  props: {
+    drive_id: Property.ShortText({
+      displayName: 'Shared Drive ID',
+      description: 'The ID of the shared drive to delete. Resolve it via drive_list_shared_drives.',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { drive_id } = context.propsValue;
+
+    const authClient = await createGoogleClient(context.auth);
+
+    const drive = googleDrive({ version: 'v3', auth: authClient });
+
+    try {
+      await drive.drives.delete({
+        driveId: drive_id,
+      });
+
+      return { deleted: true, driveId: drive_id };
+    } catch (error: any) {
+      if (error.code === 404) {
+        throw new Error(
+          `Shared drive not found (ID: ${drive_id}). It may have already been deleted. Resolve a valid ID via drive_list_shared_drives.`
+        );
+      }
+      if (error.code === 400) {
+        throw new Error(
+          `Cannot delete shared drive ${drive_id}: it must be empty before deletion. Remove or trash all of its files first.`
+        );
+      }
+      if (error.code === 403) {
+        throw new Error(
+          `Permission denied deleting shared drive ${drive_id}. You must be an organizer of this drive.`
+        );
+      }
+      throw error;
+    }
+  },
+});

package/src/lib/action/drive-download-file.ts

@@ -0,0 +1,38 @@
+import { googleDriveAuth } from '../auth';
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { downloadFileFromDrive } from '../common/get-file-content';
+import { driveDownloadFileOutputSchema } from '../output-schemas';
+
+export const driveDownloadFile = createAction({
+  auth: googleDriveAuth,
+  name: 'drive_download_file',
+  displayName: 'Download File Content',
+  description: 'Read a selected file from google drive file',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      "Downloads a Drive file's bytes by ID and returns a file reference; native Google files (Docs/Sheets/Slides) are auto-exported to their default Office format. Use to retrieve content of a file you have the ID for (obtain it from `drive_search_files` or `drive_get_file`). Read-only.",
+    idempotent: true,
+  },
+  outputSchema: driveDownloadFileOutputSchema,
+  props: {
+    file_id: Property.ShortText({
+      displayName: 'File ID',
+      description:
+        'The ID of the file to download. Resolve it via `drive_search_files` or `drive_get_file`.',
+      required: true,
+    }),
+    destination_file_name: Property.ShortText({
+      displayName: 'Destination File name',
+      required: false,
+    }),
+  },
+  run: async ({ auth, propsValue, files }) => {
+    return downloadFileFromDrive(
+      auth,
+      files,
+      propsValue.file_id,
+      propsValue.destination_file_name
+    );
+  },
+});

package/src/lib/action/drive-empty-trash.ts

@@ -0,0 +1,47 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { googleDriveAuth, createGoogleClient } from '../auth';
+import { drive as googleDrive } from '@googleapis/drive';
+import { driveEmptyTrashOutputSchema } from '../output-schemas';
+
+export const driveEmptyTrash = createAction({
+  auth: googleDriveAuth,
+  name: 'drive_empty_trash',
+  displayName: 'Empty Trash',
+  description: 'Permanently delete ALL files in the trash (irreversible, account-wide).',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'DESTRUCTIVE: permanently deletes EVERY file currently in the trash — this is an irreversible, account-wide purge (not a single file), or scoped to one shared drive if `drive_id` is given. The entire trash is emptied, so any file the user trashed is gone for good. Use only as a deliberate cleanup step; to remove a single file reversibly use `drive_trash_file`, and to permanently remove one specific file use `drive_delete_file`. Not safe to retry casually — it purges whatever is in the trash at call time.',
+    idempotent: false,
+  },
+  outputSchema: driveEmptyTrashOutputSchema,
+  props: {
+    drive_id: Property.ShortText({
+      displayName: 'Shared Drive ID',
+      description:
+        'Optional. Restrict the purge to a single shared drive\'s trash (resolve via drive_list_shared_drives). Leave empty to empty the entire My Drive trash for the connected account.',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const { drive_id } = context.propsValue;
+
+    const authClient = await createGoogleClient(context.auth);
+    const drive = googleDrive({ version: 'v3', auth: authClient });
+
+    try {
+      await drive.files.emptyTrash({
+        ...(drive_id ? { driveId: drive_id } : {}),
+      });
+
+      return { success: true, driveId: drive_id ?? null };
+    } catch (error: any) {
+      if (error.code === 403) {
+        throw new Error(
+          'Permission denied emptying the trash. You may lack permission to empty this trash.'
+        );
+      }
+      throw error;
+    }
+  },
+});

package/src/lib/action/drive-export-workspace-file.ts

@@ -0,0 +1,129 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { googleDriveAuth, createGoogleClient } from '../auth';
+import { drive as googleDrive } from '@googleapis/drive';
+import { extension } from 'mime-types';
+import { driveExportWorkspaceFileOutputSchema } from '../output-schemas';
+
+export const driveExportWorkspaceFile = createAction({
+  auth: googleDriveAuth,
+  name: 'drive_export_workspace_file',
+  displayName: 'Export Google Doc/Sheet/Slides',
+  description:
+    'Export a native Google Workspace file (Doc/Sheet/Slides) to a chosen format.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Exports a native Google Workspace file (Doc/Sheet/Slides) to a caller-chosen format and returns the bytes. Use when you need a specific format such as PDF, HTML, CSV, or Markdown; for the default rendition or for ordinary binary files use `drive_download_file`. The chosen format must match the source type (Doc formats for a Doc, Sheet formats for a Sheet, etc.). Read-only. Export size is capped at ~10 MB by Drive.',
+    idempotent: true,
+  },
+  outputSchema: driveExportWorkspaceFileOutputSchema,
+  props: {
+    file_id: Property.ShortText({
+      displayName: 'File ID',
+      description:
+        'The ID of the native Google Workspace file to export. Resolve it via `drive_search_files` or `drive_get_file`.',
+      required: true,
+    }),
+    mime_type: Property.StaticDropdown({
+      displayName: 'Export Format',
+      description:
+        'The target format. It must match the source type: Doc formats for a Google Doc, Sheet formats for a Google Sheet, Slides formats for Google Slides. An incompatible pairing returns an error.',
+      required: true,
+      options: {
+        options: [
+          // Google Docs
+          {
+            label: 'Word (DOCX) — Docs',
+            value:
+              'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+          },
+          { label: 'PDF — Docs/Sheets/Slides', value: 'application/pdf' },
+          { label: 'HTML — Docs', value: 'text/html' },
+          { label: 'Plain Text (TXT) — Docs', value: 'text/plain' },
+          { label: 'Rich Text (RTF) — Docs', value: 'application/rtf' },
+          {
+            label: 'OpenDocument Text (ODT) — Docs',
+            value: 'application/vnd.oasis.opendocument.text',
+          },
+          { label: 'EPUB — Docs', value: 'application/epub+zip' },
+          { label: 'Markdown (MD) — Docs', value: 'text/markdown' },
+          // Google Sheets
+          {
+            label: 'Excel (XLSX) — Sheets',
+            value:
+              'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+          },
+          { label: 'CSV — Sheets', value: 'text/csv' },
+          { label: 'TSV — Sheets', value: 'text/tab-separated-values' },
+          {
+            label: 'OpenDocument Spreadsheet (ODS) — Sheets',
+            value: 'application/vnd.oasis.opendocument.spreadsheet',
+          },
+          // Google Slides
+          {
+            label: 'PowerPoint (PPTX) — Slides',
+            value:
+              'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+          },
+          {
+            label: 'OpenDocument Presentation (ODP) — Slides',
+            value: 'application/vnd.oasis.opendocument.presentation',
+          },
+          { label: 'PNG — Slides', value: 'image/png' },
+          { label: 'SVG — Slides', value: 'image/svg+xml' },
+        ],
+      },
+    }),
+  },
+  async run(context) {
+    const { file_id, mime_type } = context.propsValue;
+
+    const authClient = await createGoogleClient(context.auth);
+    const drive = googleDrive({ version: 'v3', auth: authClient });
+
+    try {
+      const result = await drive.files.export(
+        {
+          fileId: file_id,
+          mimeType: mime_type,
+        },
+        {
+          responseType: 'arraybuffer',
+        }
+      );
+
+      const extensionResult = extension(mime_type);
+      const fileExtension = extensionResult ? '.' + extensionResult : '';
+
+      return context.files.write({
+        fileName: file_id + fileExtension,
+        data: Buffer.from(result.data as any),
+      });
+    } catch (error: any) {
+      // exportSizeLimitExceeded is a 403 but distinct from a permission denial.
+      const reason =
+        error?.errors?.[0]?.reason ?? error?.response?.data?.error?.errors?.[0]?.reason;
+      if (reason === 'exportSizeLimitExceeded') {
+        throw new Error(
+          `Export failed: the file exceeds Drive's ~10 MB export size limit (file ID: ${file_id}). Use drive_download_file to fetch the source directly instead.`
+        );
+      }
+      if (error.code === 403) {
+        throw new Error(
+          `Permission denied exporting file ${file_id}. You may lack access to this file.`
+        );
+      }
+      if (error.code === 400) {
+        throw new Error(
+          `Invalid export for file ${file_id}: the chosen format does not match the source type, or this is not a native Google Workspace file. Use drive_download_file for ordinary binary files.`
+        );
+      }
+      if (error.code === 404) {
+        throw new Error(
+          `File not found (ID: ${file_id}). Resolve a valid ID via drive_search_files or drive_get_file.`
+        );
+      }
+      throw error;
+    }
+  },
+});

package/src/lib/action/drive-get-about.ts

@@ -0,0 +1,40 @@
+import { createAction } from '@agnocon/pieces-framework';
+import { googleDriveAuth, createGoogleClient } from '../auth';
+import { drive as googleDrive } from '@googleapis/drive';
+import { driveGetAboutOutputSchema } from '../output-schemas';
+
+export const driveGetAbout = createAction({
+  auth: googleDriveAuth,
+  name: 'drive_get_about',
+  displayName: 'Get Account & Storage Info',
+  description: 'Get the authenticated Drive account, storage quota, and supported formats.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Returns the authenticated user\'s Drive info: account identity, storage quota and usage, and supported import/export formats. Use to check available space before a large upload, confirm which account is connected, or look up valid export MIME types. Read-only.',
+    idempotent: true,
+  },
+  outputSchema: driveGetAboutOutputSchema,
+  props: {},
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+
+    const drive = googleDrive({ version: 'v3', auth: authClient });
+
+    try {
+      // about.get requires a fields parameter or the API returns 400.
+      const response = await drive.about.get({
+        fields: 'user,storageQuota,maxImportSizes,exportFormats',
+      });
+
+      return response.data;
+    } catch (error: any) {
+      if (error.code === 403) {
+        throw new Error(
+          'Permission denied fetching Drive account info. The connection may lack the required Drive scope.'
+        );
+      }
+      throw error;
+    }
+  },
+});

package/src/lib/action/drive-get-file.ts

@@ -0,0 +1,40 @@
+import { googleDriveAuth, createGoogleClient } from '../auth';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { drive as googleDrive } from '@googleapis/drive';
+import { driveGetFileOutputSchema } from '../output-schemas';
+
+export const driveGetFile = createAction({
+  auth: googleDriveAuth,
+  name: 'drive_get_file',
+  displayName: 'Get File or Folder',
+  description: 'Get a file folder for files/sub-folders',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Fetches metadata for a single file or folder by its exact ID (name, MIME type, parents, owners, links). Use when you already have an ID (e.g. from a trigger or `drive_search_files`) and need its details, including its parent folder IDs. Read-only and safe to retry.',
+    idempotent: true,
+  },
+  outputSchema: driveGetFileOutputSchema,
+  props: {
+    file_id: Property.ShortText({
+      displayName: 'File / Folder ID',
+      description:
+        'The ID of the file/folder to fetch. Resolve it via `drive_search_files` or `drive_list_files`.',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const authClient = await createGoogleClient(context.auth);
+    const drive = googleDrive({ version: 'v3', auth: authClient });
+    const response = await drive.files.get({
+      fileId: context.propsValue.file_id,
+      supportsAllDrives: true,
+    });
+
+    if (response.data) {
+      return response.data;
+    } else {
+      return null;
+    }
+  },
+});

package/src/lib/action/drive-get-reply.ts

@@ -0,0 +1,67 @@
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { googleDriveAuth, createGoogleClient } from '../auth';
+import { drive as googleDrive } from '@googleapis/drive';
+import { driveGetReplyOutputSchema } from '../output-schemas';
+
+export const driveGetReply = createAction({
+  auth: googleDriveAuth,
+  name: 'drive_get_reply',
+  displayName: 'Get Reply',
+  description: 'Fetch a single reply on a Drive comment by ID.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Fetches a single reply by ID, including its author, content, and action. Use when you already have a replyId (resolve it via drive_list_replies) and need that one reply\'s details. Read-only.',
+    idempotent: true,
+  },
+  outputSchema: driveGetReplyOutputSchema,
+  props: {
+    file_id: Property.ShortText({
+      displayName: 'File ID',
+      description:
+        'The ID of the file the comment belongs to. Resolve it via drive_search_files or drive_get_file.',
+      required: true,
+    }),
+    comment_id: Property.ShortText({
+      displayName: 'Comment ID',
+      description: 'The ID of the parent comment. Resolve it via drive_list_comments.',
+      required: true,
+    }),
+    reply_id: Property.ShortText({
+      displayName: 'Reply ID',
+      description: 'The ID of the reply to fetch. Resolve it via drive_list_replies.',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { file_id, comment_id, reply_id } = context.propsValue;
+
+    const authClient = await createGoogleClient(context.auth);
+
+    const drive = googleDrive({ version: 'v3', auth: authClient });
+
+    try {
+      // The Drive replies endpoints require a fields parameter or the API returns 400.
+      const response = await drive.replies.get({
+        fileId: file_id,
+        commentId: comment_id,
+        replyId: reply_id,
+        fields: '*',
+      });
+
+      return response.data;
+    } catch (error: any) {
+      if (error.code === 404) {
+        throw new Error(
+          `File, comment, or reply not found (file ID: ${file_id}, comment ID: ${comment_id}, reply ID: ${reply_id}). Resolve the reply ID via drive_list_replies.`
+        );
+      }
+      if (error.code === 403) {
+        throw new Error(
+          `Permission denied fetching reply ${reply_id} on file ${file_id}. You may lack access to this file.`
+        );
+      }
+      throw error;
+    }
+  },
+});

package/src/lib/action/drive-get-shared-drive.ts

@@ -0,0 +1,52 @@
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { googleDriveAuth, createGoogleClient } from '../auth';
+import { drive as googleDrive } from '@googleapis/drive';
+import { driveGetSharedDriveOutputSchema } from '../output-schemas';
+
+export const driveGetSharedDrive = createAction({
+  auth: googleDriveAuth,
+  name: 'drive_get_shared_drive',
+  displayName: 'Get Shared Drive',
+  description: 'Fetch metadata for one shared drive by ID.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Fetches metadata and capabilities for one shared drive by ID (resolve the ID via drive_list_shared_drives). Use to inspect a shared drive\'s settings before modifying it. Read-only.',
+    idempotent: true,
+  },
+  outputSchema: driveGetSharedDriveOutputSchema,
+  props: {
+    drive_id: Property.ShortText({
+      displayName: 'Shared Drive ID',
+      description: 'The ID of the shared drive. Resolve it via drive_list_shared_drives.',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { drive_id } = context.propsValue;
+
+    const authClient = await createGoogleClient(context.auth);
+
+    const drive = googleDrive({ version: 'v3', auth: authClient });
+
+    try {
+      const response = await drive.drives.get({
+        driveId: drive_id,
+      });
+
+      return response.data;
+    } catch (error: any) {
+      if (error.code === 404) {
+        throw new Error(
+          `Shared drive not found (ID: ${drive_id}). Resolve a valid ID via drive_list_shared_drives.`
+        );
+      }
+      if (error.code === 403) {
+        throw new Error(
+          `Permission denied accessing shared drive ${drive_id}. You may not be a member of this drive.`
+        );
+      }
+      throw error;
+    }
+  },
+});

package/src/lib/action/drive-list-comments.ts

@@ -0,0 +1,61 @@
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { googleDriveAuth, createGoogleClient } from '../auth';
+import { drive as googleDrive } from '@googleapis/drive';
+import { driveListCommentsOutputSchema } from '../output-schemas';
+
+export const driveListComments = createAction({
+  auth: googleDriveAuth,
+  name: 'drive_list_comments',
+  displayName: 'List Comments',
+  description: 'List the comments on a Drive file.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Lists the comments on a file with each comment\'s id, author, content, and resolved state. Use to read discussion on a file or to resolve a commentId before replying (drive_create_reply) or listing its replies (drive_list_replies). Read-only.',
+    idempotent: true,
+  },
+  outputSchema: driveListCommentsOutputSchema,
+  props: {
+    file_id: Property.ShortText({
+      displayName: 'File ID',
+      description:
+        'The ID of the file whose comments to list. Resolve it via drive_search_files or drive_get_file.',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { file_id } = context.propsValue;
+
+    const authClient = await createGoogleClient(context.auth);
+
+    const drive = googleDrive({ version: 'v3', auth: authClient });
+
+    try {
+      // The Drive comments endpoints require a fields parameter or the API returns 400.
+      const response = await drive.comments.list({
+        fileId: file_id,
+        fields: '*',
+        includeDeleted: false,
+      });
+
+      const comments = response.data.comments ?? [];
+
+      return {
+        comments,
+        count: comments.length,
+      };
+    } catch (error: any) {
+      if (error.code === 404) {
+        throw new Error(
+          `File not found (ID: ${file_id}). Resolve a valid ID via drive_search_files or drive_get_file.`
+        );
+      }
+      if (error.code === 403) {
+        throw new Error(
+          `Permission denied listing comments for file ${file_id}. You may lack access to this file.`
+        );
+      }
+      throw error;
+    }
+  },
+});