@commandable/integration-data 0.0.5 → 0.0.7

package/integrations/google-drive/prompt.md

@@ -0,0 +1,59 @@
+## File and folder IDs
+
+Drive file and folder IDs appear in the URL:
+- Files: `https://drive.google.com/file/d/{fileId}/view`
+- Folders: `https://drive.google.com/drive/folders/{folderId}`
+- Google Docs: `https://docs.google.com/document/d/{documentId}/edit`
+
+Use `search_files` or `list_files` to find IDs programmatically.
+
+## MIME types for Google Workspace files
+
+When creating files with `create_file`, use these MIME types:
+
+| File type | MIME type |
+|---|---|
+| Google Doc | `application/vnd.google-apps.document` |
+| Google Sheet | `application/vnd.google-apps.spreadsheet` |
+| Google Slides | `application/vnd.google-apps.presentation` |
+| Google Forms | `application/vnd.google-apps.form` |
+| Google Folder | `application/vnd.google-apps.folder` |
+
+## Drive search query syntax
+
+The `query` parameter in `search_files` uses the Drive search syntax:
+
+- `name contains 'budget'` — file name contains string
+- `name = 'exact name'` — exact file name match
+- `mimeType = 'application/pdf'` — filter by MIME type
+- `mimeType != 'application/vnd.google-apps.folder'` — exclude folders
+- `'folderId' in parents` — files in a specific folder
+- `modifiedTime > '2024-01-01T00:00:00'` — modified after date (RFC3339)
+- `trashed = true` — only trashed files
+- `starred = true` — only starred files
+- `sharedWithMe = true` — files shared with the user
+
+Combine with `and`, `or`, `not`: `name contains 'report' and mimeType = 'application/pdf' and modifiedTime > '2024-01-01T00:00:00'`
+
+## Reading file contents
+
+1. Use `search_files` or `list_files` to find the file (note its `id` and `mimeType`)
+2. Call `get_file_content` with `fileId` and `mimeType`
+   - For Google Workspace files, the `mimeType` triggers automatic export
+   - For text/CSV/JSON files, content is returned directly
+
+## Export formats
+
+Google Workspace files must be exported (they have no binary content):
+
+| Source | Default export | Alternative exports |
+|---|---|---|
+| Google Docs | `text/plain` | `text/html`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/pdf` |
+| Google Sheets | `text/csv` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `application/pdf` |
+| Google Slides | `text/plain` | `application/vnd.openxmlformats-officedocument.presentationml.presentation`, `application/pdf` |
+
+## Sharing files
+
+- Individual user: `share_file` with `type='user'`, `role='writer'`, `emailAddress='user@example.com'`
+- Anyone with link: `share_file` with `type='anyone'`, `role='reader'`
+- Whole domain: `share_file` with `type='domain'`, `role='reader'`, `domain='example.com'`

package/integrations/google-drive/schemas/get_file.json

@@ -4,7 +4,7 @@
   "required": ["fileId"],
   "additionalProperties": false,
   "properties": {
-    "fileId": { "type": "string" }
+    "fileId": { "type": "string", "description": "Drive file or folder ID. Use search_files or list_files to find file IDs." },
+    "fields": { "type": "string", "description": "Comma-separated list of fields to return. Defaults to 'id,name,mimeType,modifiedTime,createdTime,size,parents,trashed,webViewLink'. See the Drive API fields reference for all available fields." }
   }
 }
-

package/integrations/google-drive/schemas/get_file_content.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["fileId"],
+  "properties": {
+    "fileId": { "type": "string", "description": "Drive file ID. Use search_files or list_files to find file IDs." },
+    "mimeType": { "type": "string", "description": "The file's MIME type, obtained from get_file or search_files. Required for Google Workspace files (Docs, Sheets, Slides) to trigger automatic text export. Google Docs files start with 'application/vnd.google-apps.'." },
+    "exportMimeType": { "type": "string", "description": "Override the export format. For Google Docs: 'text/plain', 'text/html', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'. For Sheets: 'text/csv', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'. For Slides: 'text/plain', 'application/vnd.openxmlformats-officedocument.presentationml.presentation'. For any: 'application/pdf'." }
+  },
+  "additionalProperties": false
+}

package/integrations/google-drive/schemas/list_files.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "folderId": { "type": "string", "description": "Parent folder ID to list contents of. Omit to list files across all of Drive (not scoped to a folder). Use search_files with query=\"'root' in parents\" to list only root-level files." },
+    "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Maximum results per page. Defaults to 50. Use pageToken from the response for the next page." },
+    "pageToken": { "type": "string", "description": "Page token from a previous list_files response to retrieve the next page of results." },
+    "orderBy": { "type": "string", "description": "Sort order. Examples: 'modifiedTime desc', 'name', 'createdTime desc'. Default is unspecified." },
+    "fields": { "type": "string", "description": "Override the fields returned in each file. Defaults to 'nextPageToken,files(id,name,mimeType,modifiedTime,size,parents)'." }
+  },
+  "additionalProperties": false
+}

package/integrations/google-drive/schemas/search_files.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "query": { "type": "string", "description": "Raw Drive query string using the Drive search syntax. Examples: \"name contains 'budget' and mimeType = 'application/vnd.google-apps.spreadsheet'\", \"modifiedTime > '2024-01-01'\", \"'folderId' in parents\". Combined with name/mimeType shorthand via AND." },
+    "name": { "type": "string", "description": "Shorthand for name-based search. Translates to \"name contains 'value'\". Combined with query and mimeType via AND." },
+    "mimeType": { "type": "string", "description": "Filter by MIME type. Common values: 'application/vnd.google-apps.document' (Docs), 'application/vnd.google-apps.spreadsheet' (Sheets), 'application/vnd.google-apps.presentation' (Slides), 'application/vnd.google-apps.folder' (folders), 'application/pdf', 'text/plain'." },
+    "includeTrashed": { "type": "boolean", "description": "Include trashed files in results. Defaults to false (trashed files excluded)." },
+    "pageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20, "description": "Maximum results per page. Defaults to 20. Use pageToken from the response for the next page." },
+    "pageToken": { "type": "string", "description": "Page token from a previous search_files response to retrieve the next page of results." },
+    "fields": { "type": "string", "description": "Override the fields returned in each file. Defaults to 'nextPageToken,files(id,name,mimeType,modifiedTime,size,parents)'." }
+  },
+  "additionalProperties": false
+}

package/integrations/google-drive/schemas/share_file.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["fileId", "role", "type"],
+  "properties": {
+    "fileId": { "type": "string", "description": "Drive file or folder ID to share." },
+    "role": {
+      "type": "string",
+      "enum": ["reader", "commenter", "writer", "organizer", "owner"],
+      "description": "Permission level. 'reader' = view only, 'commenter' = view + comment, 'writer' = edit, 'organizer' = organize in shared drives, 'owner' = full ownership transfer."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["user", "group", "domain", "anyone"],
+      "description": "Grantee type. 'user' requires emailAddress, 'group' requires emailAddress, 'domain' requires domain, 'anyone' grants access to all (use role='reader' for public link)."
+    },
+    "emailAddress": { "type": "string", "description": "Email address of the user or group to share with. Required when type is 'user' or 'group'." },
+    "domain": { "type": "string", "description": "Domain to share with (e.g. 'example.com'). Required when type is 'domain'." },
+    "sendNotificationEmail": { "type": "boolean", "description": "Whether to send a notification email to the new recipient. Defaults to true. Set to false to share silently." },
+    "emailMessage": { "type": "string", "description": "Custom message to include in the notification email." }
+  },
+  "additionalProperties": false
+}

package/integrations/google-gmail/.env.test.example

@@ -0,0 +1,11 @@
+# Gmail live integration tests
+# Shared Google credentials live in /.env.test.google — set those up first.
+#
+# Optional seed IDs — the suite will discover them automatically if omitted
+GMAIL_TEST_MESSAGE_ID=
+GMAIL_TEST_THREAD_ID=
+# Email address to use for send/reply tests (must be accessible by the credential)
+GMAIL_TEST_SEND_TO=
+# Optional: specific message/thread to delete in delete tests
+GMAIL_TEST_DELETE_MESSAGE_ID=
+GMAIL_TEST_DELETE_THREAD_ID=

package/integrations/google-gmail/README.md

@@ -0,0 +1,49 @@
+# Gmail
+
+**25 tools** across 2 toolsets
+
+![Gmail tests](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/theomccabe/771bd329f303087690c522afa1baa6f3/raw/test-google-gmail.json)
+
+## Credential variants
+
+| Variant | Label |
+|---|---|
+| `service_account` | Service Account (recommended) _(default)_ |
+| `oauth_token` | OAuth Access Token (short-lived) |
+
+## Toolsets
+
+| Toolset | Description |
+|---|---|
+| `email` | Search, read, compose, and send emails and drafts |
+| `organize` | Label, archive, trash, and delete messages and threads |
+
+## Tools
+
+| Tool | Scope | Toolset | Description |
+|---|---|---|---|
+| `get_profile` | read | `email` | Get mailbox profile details for the authenticated user, including email address, messages… |
+| `list_messages` | read | `email` | List message IDs matching a Gmail search query or label filters. Returns only IDs and thr… |
+| `read_email` | read | `email` | Read an email by message ID and return a flat, decoded result with subject, from, to, cc,… |
+| `get_message` | read | `email` | Get the raw Gmail message resource by message ID. Returns the full nested payload includi… |
+| `list_threads` | read | `email` | List thread IDs matching a Gmail search query or label filters. Similar to list_messages … |
+| `get_thread` | read | `email` | Get a full thread resource by thread ID, including all messages in the conversation. Use … |
+| `list_drafts` | read | `email` | List drafts in the mailbox. Returns draft IDs and the nested message ID. Use get_draft to… |
+| `get_draft` | read | `email` | Get a draft by draft ID. Returns the draft object including the nested message resource. … |
+| `send_email` | write | `email` | Send an email by providing flat fields: to, subject, and body. Handles MIME encoding and … |
+| `create_draft_email` | write | `email` | Create a draft email using flat fields: subject, body, and optionally to, cc, bcc. Handle… |
+| `delete_draft` | write | `email` | Permanently delete a draft by its draft ID. Use list_drafts to find draft IDs. This canno… |
+| `send_draft` | write | `email` | Send an existing draft by draft ID, or send a one-off draft payload (provide raw instead … |
+| `list_labels` | read | `organize` | List all labels in the user's mailbox, including system labels (INBOX, SENT, DRAFT, SPAM,… |
+| `get_label` | read | `organize` | Get details for a specific label by its label ID. Returns name, type, visibility settings… |
+| `modify_message` | write | `organize` | Add or remove labels on a single message. Provide addLabelIds, removeLabelIds, or both. C… |
+| `trash_message` | write | `organize` | Move a message to the Trash. The message is not permanently deleted and can be restored w… |
+| `untrash_message` | write | `organize` | Restore a message from Trash back to the Inbox. Use list_messages with labelIds=['TRASH']… |
+| `delete_message` | write | `organize` | Permanently and immediately delete a message by ID. This cannot be undone. For recoverabl… |
+| `modify_thread` | write | `organize` | Add or remove labels on all messages in a thread at once. Provide addLabelIds, removeLabe… |
+| `trash_thread` | write | `organize` | Move an entire thread to Trash. All messages in the thread are trashed. Can be reversed w… |
+| `untrash_thread` | write | `organize` | Restore an entire thread from Trash. Use list_threads with labelIds=['TRASH'] to find tra… |
+| `delete_thread` | write | `organize` | Permanently and immediately delete an entire thread and all its messages. This cannot be … |
+| `create_label` | admin | `organize` | Create a new mailbox label with optional visibility and color settings. Label names must … |
+| `update_label` | admin | `organize` | Update (patch) an existing mailbox label's name, color, or visibility settings by label I… |
+| `delete_label` | admin | `organize` | Permanently delete a mailbox label by label ID. Messages with this label will have it rem… |

package/integrations/google-gmail/__tests__/get_handlers.test.ts

@@ -0,0 +1,134 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { createCredentialStore, createIntegrationNode, createProxy, createToolbox, safeCleanup } from '../../__tests__/liveHarness.js'
+
+const env = process.env as Record<string, string | undefined>
+
+interface VariantConfig {
+  key: string
+  credentials: () => Record<string, string>
+}
+
+const variants: VariantConfig[] = [
+  {
+    key: 'service_account',
+    credentials: () => ({ serviceAccountJson: env.GOOGLE_SERVICE_ACCOUNT_JSON || '', subject: env.GOOGLE_IMPERSONATE_SUBJECT || '' }),
+  },
+  {
+    key: 'oauth_token',
+    credentials: () => ({ token: env.GOOGLE_TOKEN || '' }),
+  },
+].filter(v => Object.values(v.credentials()).some(val => val.trim().length > 0))
+
+const suiteOrSkip = variants.length > 0 ? describe : describe.skip
+
+suiteOrSkip('google-gmail read handlers (live)', () => {
+  for (const variant of variants) {
+    describe(`variant: ${variant.key}`, () => {
+      const ctx: { email?: string, labelId?: string, messageId?: string, threadId?: string, draftId?: string } = {}
+      let gmail: ReturnType<typeof createToolbox>
+
+      beforeAll(async () => {
+        const credentialStore = createCredentialStore(async () => variant.credentials())
+        const proxy = createProxy(credentialStore)
+        gmail = createToolbox(
+          'google-gmail',
+          proxy,
+          createIntegrationNode('google-gmail', { label: 'Google Gmail', credentialId: 'google-gmail-creds', credentialVariant: variant.key }),
+          variant.key,
+        )
+
+        const profile = await gmail.read('get_profile')({})
+        ctx.email = profile?.emailAddress
+
+        const labels = await gmail.read('list_labels')({})
+        ctx.labelId = labels?.labels?.[0]?.id
+
+        const listedMessages = await gmail.read('list_messages')({ maxResults: 5 })
+        ctx.messageId = listedMessages?.messages?.[0]?.id
+        if (ctx.messageId) {
+          const msg = await gmail.read('get_message')({ messageId: ctx.messageId, format: 'minimal' })
+          ctx.threadId = msg?.threadId
+        }
+
+        if (ctx.email) {
+          const draft = await gmail.write('create_draft_email')({
+            to: ctx.email,
+            subject: `CmdTest Gmail Draft ${Date.now()}`,
+            body: 'Draft created by integration live tests.',
+          })
+          ctx.draftId = draft?.id
+        }
+      }, 60000)
+
+      afterAll(async () => {
+        await safeCleanup(async () => ctx.draftId ? gmail.write('delete_draft')({ draftId: ctx.draftId }) : Promise.resolve())
+      }, 30000)
+
+      it('get_profile returns mailbox profile', async () => {
+        const result = await gmail.read('get_profile')({})
+        expect(result?.emailAddress || result?.messagesTotal !== undefined).toBeTruthy()
+      }, 30000)
+
+      it('list_labels returns labels', async () => {
+        const result = await gmail.read('list_labels')({})
+        expect(Array.isArray(result?.labels)).toBe(true)
+      }, 30000)
+
+      it('get_label returns a label when available', async () => {
+        if (!ctx.labelId)
+          return expect(true).toBe(true)
+        const result = await gmail.read('get_label')({ labelId: ctx.labelId })
+        expect(result?.id).toBe(ctx.labelId)
+      }, 30000)
+
+      it('list_messages returns messages list', async () => {
+        const result = await gmail.read('list_messages')({ maxResults: 10 })
+        expect(result?.resultSizeEstimate !== undefined || Array.isArray(result?.messages)).toBe(true)
+      }, 30000)
+
+      it('get_message returns a message when available', async () => {
+        if (!ctx.messageId)
+          return expect(true).toBe(true)
+        const result = await gmail.read('get_message')({ messageId: ctx.messageId, format: 'full' })
+        expect(result?.id).toBe(ctx.messageId)
+      }, 30000)
+
+      it('list_threads returns threads list', async () => {
+        const result = await gmail.read('list_threads')({ maxResults: 10 })
+        expect(result?.resultSizeEstimate !== undefined || Array.isArray(result?.threads)).toBe(true)
+      }, 30000)
+
+      it('get_thread returns a thread when available', async () => {
+        if (!ctx.threadId)
+          return expect(true).toBe(true)
+        const result = await gmail.read('get_thread')({ threadId: ctx.threadId, format: 'full' })
+        expect(result?.id).toBe(ctx.threadId)
+      }, 30000)
+
+      it('list_drafts returns drafts list', async () => {
+        const result = await gmail.read('list_drafts')({ maxResults: 10 })
+        expect(result?.resultSizeEstimate !== undefined || Array.isArray(result?.drafts)).toBe(true)
+      }, 30000)
+
+      it('get_draft returns draft details when available', async () => {
+        if (!ctx.draftId)
+          return expect(true).toBe(true)
+        const result = await gmail.read('get_draft')({ draftId: ctx.draftId })
+        expect(result?.id).toBe(ctx.draftId)
+      }, 30000)
+
+      it('read_email returns flat decoded message when a message is available', async () => {
+        if (!ctx.messageId)
+          return expect(true).toBe(true)
+        const result = await gmail.read('read_email')({ messageId: ctx.messageId })
+        expect(result?.id).toBe(ctx.messageId)
+        expect(typeof result?.subject).toBe('string')
+        expect(typeof result?.from).toBe('string')
+        expect(typeof result?.date).toBe('string')
+        expect(typeof result?.snippet).toBe('string')
+        expect(typeof result?.body).toBe('string')
+        expect(Array.isArray(result?.labelIds)).toBe(true)
+      }, 30000)
+    })
+  }
+})

package/integrations/google-gmail/__tests__/usage_parity.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest'
+import { getMissingToolUsages } from '../../__tests__/usageParity.js'
+
+describe('google-gmail static usage parity', () => {
+  it('every manifest tool is referenced in tests', () => {
+    const missing = getMissingToolUsages({ integrationName: 'google-gmail', importMetaUrl: import.meta.url })
+    expect(missing, `Missing handler usages in tests: ${missing.join(', ')}`).toEqual([])
+  })
+})

package/integrations/google-gmail/__tests__/write_and_admin_handlers.test.ts

@@ -0,0 +1,211 @@
+import { Buffer } from 'node:buffer'
+import { beforeAll, describe, expect, it } from 'vitest'
+import { createCredentialStore, createIntegrationNode, createProxy, createToolbox, safeCleanup } from '../../__tests__/liveHarness.js'
+
+const env = process.env as Record<string, string | undefined>
+
+interface VariantConfig {
+  key: string
+  credentials: () => Record<string, string>
+}
+
+const variants: VariantConfig[] = [
+  {
+    key: 'service_account',
+    credentials: () => ({ serviceAccountJson: env.GOOGLE_SERVICE_ACCOUNT_JSON || '', subject: env.GOOGLE_IMPERSONATE_SUBJECT || '' }),
+  },
+  {
+    key: 'oauth_token',
+    credentials: () => ({ token: env.GOOGLE_TOKEN || '' }),
+  },
+].filter(v => Object.values(v.credentials()).some(val => val.trim().length > 0))
+
+const suiteOrSkip = variants.length > 0 ? describe : describe.skip
+
+function makeRawMessage(toEmail: string, subject: string, text: string): string {
+  const mime = [
+    `To: ${toEmail}`,
+    `Subject: ${subject}`,
+    'MIME-Version: 1.0',
+    'Content-Type: text/plain; charset=UTF-8',
+    '',
+    text,
+  ].join('\r\n')
+  return Buffer.from(mime, 'utf8').toString('base64url')
+}
+
+suiteOrSkip('google-gmail write/admin handlers (live)', () => {
+  for (const variant of variants) {
+    describe(`variant: ${variant.key}`, () => {
+      const ctx: { email?: string, inboxLabelId?: string, messageId?: string, threadId?: string } = {}
+      let gmail: ReturnType<typeof createToolbox>
+
+      beforeAll(async () => {
+        const credentialStore = createCredentialStore(async () => variant.credentials())
+        const proxy = createProxy(credentialStore)
+        gmail = createToolbox(
+          'google-gmail',
+          proxy,
+          createIntegrationNode('google-gmail', { label: 'Google Gmail', credentialId: 'google-gmail-creds', credentialVariant: variant.key }),
+          variant.key,
+        )
+
+        const profile = await gmail.read('get_profile')({})
+        ctx.email = profile?.emailAddress
+
+        const labels = await gmail.read('list_labels')({})
+        ctx.inboxLabelId = labels?.labels?.find((l: any) => l?.name === 'INBOX')?.id || labels?.labels?.[0]?.id
+
+        const listedMessages = await gmail.read('list_messages')({ maxResults: 5 })
+        ctx.messageId = env.GMAIL_TEST_MESSAGE_ID || listedMessages?.messages?.[0]?.id
+        if (ctx.messageId) {
+          const msg = await gmail.read('get_message')({ messageId: ctx.messageId, format: 'minimal' })
+          ctx.threadId = env.GMAIL_TEST_THREAD_ID || msg?.threadId
+        }
+      }, 60000)
+
+      it('create_draft_email -> get_draft -> delete_draft', async () => {
+        if (!ctx.email)
+          return expect(true).toBe(true)
+        const created = await gmail.write('create_draft_email')({
+          to: ctx.email,
+          subject: `CmdTest Gmail Draft ${Date.now()}`,
+          body: 'Draft created by write tests.',
+        })
+        const draftId = created?.id
+        expect(draftId).toBeTruthy()
+        const got = await gmail.read('get_draft')({ draftId })
+        expect(got?.id).toBe(draftId)
+        const deleted = await gmail.write('delete_draft')({ draftId })
+        expect(deleted?.success === true || deleted === '').toBe(true)
+      }, 60000)
+
+      it('modify_message -> trash_message -> untrash_message on an existing message', async () => {
+        // Create a fresh draft so we own the message — avoids stale/trashed inbox IDs
+        const draft = await gmail.write('create_draft_email')({
+          to: ctx.email || 'noreply@example.com',
+          subject: `CmdTest Trash ${Date.now()}`,
+          body: 'Temporary message for trash/untrash test.',
+        })
+        const messageId = draft?.message?.id
+        const draftId = draft?.id
+        expect(messageId).toBeTruthy()
+        try {
+          const modified = await gmail.write('modify_message')({
+            messageId,
+            addLabelIds: ctx.inboxLabelId ? [ctx.inboxLabelId] : undefined,
+          })
+          expect(modified?.id).toBe(messageId)
+          const trashed = await gmail.write('trash_message')({ messageId })
+          expect(trashed?.id).toBe(messageId)
+          const untrashed = await gmail.write('untrash_message')({ messageId })
+          expect(untrashed?.id).toBe(messageId)
+        }
+        finally {
+          await safeCleanup(async () => draftId ? gmail.write('delete_draft')({ draftId }) : Promise.resolve())
+        }
+      }, 60000)
+
+      it('modify_thread -> trash_thread -> untrash_thread on an existing thread', async () => {
+        // Create a fresh draft so we own the thread — avoids stale inbox IDs
+        const draft = await gmail.write('create_draft_email')({
+          to: ctx.email || 'noreply@example.com',
+          subject: `CmdTest Thread Trash ${Date.now()}`,
+          body: 'Temporary message for thread trash/untrash test.',
+        })
+        const threadId = draft?.message?.threadId
+        const draftId = draft?.id
+        expect(threadId).toBeTruthy()
+        try {
+          const modified = await gmail.write('modify_thread')({
+            threadId,
+            addLabelIds: ctx.inboxLabelId ? [ctx.inboxLabelId] : undefined,
+          })
+          expect(modified?.id).toBe(threadId)
+          const trashed = await gmail.write('trash_thread')({ threadId })
+          expect(trashed?.id).toBe(threadId)
+          const untrashed = await gmail.write('untrash_thread')({ threadId })
+          expect(untrashed?.id).toBe(threadId)
+        }
+        finally {
+          await safeCleanup(async () => draftId ? gmail.write('delete_draft')({ draftId }) : Promise.resolve())
+        }
+      }, 60000)
+
+      it('create_label -> update_label -> delete_label', async () => {
+        const created = await gmail.admin('create_label')({
+          name: `CmdTest Label ${Date.now()}`,
+          labelListVisibility: 'labelShow',
+          messageListVisibility: 'show',
+        })
+        const labelId = created?.id
+        expect(labelId).toBeTruthy()
+        const updated = await gmail.admin('update_label')({
+          labelId,
+          name: `CmdTest Label Updated ${Date.now()}`,
+          labelListVisibility: 'labelHide',
+        })
+        expect(updated?.id).toBe(labelId)
+        const deleted = await gmail.admin('delete_label')({ labelId })
+        expect(deleted?.success === true || deleted === '').toBe(true)
+      }, 60000)
+
+      it('send_email sends mail when GMAIL_TEST_SEND_TO is set', async () => {
+        const to = env.GMAIL_TEST_SEND_TO
+        if (!to)
+          return expect(true).toBe(true)
+        const sent = await gmail.write('send_email')({
+          to,
+          subject: `CmdTest Gmail send_email ${Date.now()}`,
+          body: 'Message sent by integration live test via send_email.',
+        })
+        expect(sent?.id).toBeTruthy()
+      }, 60000)
+
+      it('send_draft sends mail when GMAIL_TEST_SEND_TO is set', async () => {
+        const to = env.GMAIL_TEST_SEND_TO
+        if (!to)
+          return expect(true).toBe(true)
+        const created = await gmail.write('create_draft_email')({
+          to,
+          subject: `CmdTest Gmail send_draft ${Date.now()}`,
+          body: 'Draft sent by integration live test.',
+        })
+        const draftId = created?.id
+        expect(draftId).toBeTruthy()
+        const sent = await gmail.write('send_draft')({ draftId })
+        expect(sent?.id || sent?.threadId).toBeTruthy()
+      }, 60000)
+
+      it('delete_message deletes message when GMAIL_TEST_DELETE_MESSAGE_ID is set', async () => {
+        const deleteMessageId = env.GMAIL_TEST_DELETE_MESSAGE_ID
+        if (!deleteMessageId)
+          return expect(true).toBe(true)
+        const deleted = await gmail.write('delete_message')({ messageId: deleteMessageId })
+        expect(deleted?.success === true || deleted === '').toBe(true)
+      }, 60000)
+
+      it('delete_thread deletes thread when GMAIL_TEST_DELETE_THREAD_ID is set', async () => {
+        const deleteThreadId = env.GMAIL_TEST_DELETE_THREAD_ID
+        if (!deleteThreadId)
+          return expect(true).toBe(true)
+        const deleted = await gmail.write('delete_thread')({ threadId: deleteThreadId })
+        expect(deleted?.success === true || deleted === '').toBe(true)
+      }, 60000)
+
+      it('send_draft supports raw payload mode', async () => {
+        const to = env.GMAIL_TEST_SEND_TO
+        if (!to)
+          return expect(true).toBe(true)
+        const raw = makeRawMessage(to, `CmdTest Gmail send_draft raw ${Date.now()}`, 'Raw payload draft-send mode.')
+        const sent = await gmail.write('send_draft')({ raw })
+        expect(sent?.id || sent?.threadId).toBeTruthy()
+      }, 60000)
+
+      it('cleanup helper remains available for optional future cleanup', async () => {
+        await safeCleanup(async () => Promise.resolve())
+        expect(true).toBe(true)
+      })
+    })
+  }
+})

package/integrations/google-gmail/credentials.json

@@ -0,0 +1,57 @@
+{
+  "variants": {
+    "service_account": {
+      "label": "Service Account (recommended)",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "serviceAccountJson": {
+            "type": "string",
+            "title": "Service Account JSON",
+            "description": "Full service account key JSON (contents of the downloaded JSON file from Google Cloud)."
+          },
+          "subject": {
+            "type": "string",
+            "title": "Subject / impersonated user (optional)",
+            "description": "User email to impersonate via Google Workspace domain-wide delegation. Usually required for mailbox access."
+          },
+          "scopes": {
+            "type": "array",
+            "title": "OAuth scopes (optional)",
+            "description": "Optional override for OAuth scopes. Defaults to full Gmail access.",
+            "items": { "type": "string" }
+          }
+        },
+        "required": ["serviceAccountJson"],
+        "additionalProperties": false
+      },
+      "injection": {
+        "headers": {
+          "Authorization": "Bearer {{token}}"
+        }
+      },
+      "preprocess": "google_service_account"
+    },
+    "oauth_token": {
+      "label": "OAuth Access Token (short-lived)",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "token": {
+            "type": "string",
+            "title": "OAuth Access Token",
+            "description": "Short-lived Google OAuth access token with Gmail scopes."
+          }
+        },
+        "required": ["token"],
+        "additionalProperties": false
+      },
+      "injection": {
+        "headers": {
+          "Authorization": "Bearer {{token}}"
+        }
+      }
+    }
+  },
+  "default": "service_account"
+}

package/integrations/google-gmail/credentials_hint_oauth_token.md

@@ -0,0 +1,8 @@
+Obtain a short-lived Google OAuth access token:
+
+1. Use the Google OAuth 2.0 Playground (`https://developers.google.com/oauthplayground/`) or your own OAuth flow
+2. Select scopes such as `https://www.googleapis.com/auth/gmail.modify` (and `https://www.googleapis.com/auth/gmail.send` if sending mail)
+3. Exchange the authorization code for an access token
+4. Paste the access token here
+
+Note: OAuth access tokens are short-lived (typically 1 hour). For long-running automation, prefer the Service Account variant with Workspace delegation.

package/integrations/google-gmail/credentials_hint_service_account.md

@@ -0,0 +1,10 @@
+Set up a Google Cloud Service Account:
+
+1. Open the [Google Cloud Console](https://console.cloud.google.com/)
+2. Enable the **Gmail API** for your project
+3. Go to **IAM & Admin -> Service Accounts** and create a new service account
+4. Under **Keys**, click **Add Key -> Create new key -> JSON** and download the file
+5. Paste the full contents of the JSON file here
+6. For Google Workspace mailboxes, configure domain-wide delegation and set `subject` to the target user's email
+
+For personal Gmail accounts, use the OAuth token variant instead.