@commandable/integration-data 0.0.5 → 0.0.6

package/integrations/google-drive/handlers/list_files.js

@@ -0,0 +1,15 @@
+async (input) => {
+  const params = new URLSearchParams()
+  const qParts = ['trashed = false']
+  if (input.folderId)
+    qParts.push(`'${input.folderId}' in parents`)
+  params.set('q', qParts.join(' and '))
+  params.set('fields', input.fields || 'nextPageToken,files(id,name,mimeType,modifiedTime,size,parents)')
+  params.set('pageSize', String(input.pageSize || 50))
+  if (input.pageToken)
+    params.set('pageToken', input.pageToken)
+  if (input.orderBy)
+    params.set('orderBy', input.orderBy)
+  const res = await integration.fetch(`/files?${params.toString()}`)
+  return await res.json()
+}

package/integrations/google-drive/handlers/search_files.js

@@ -0,0 +1,20 @@
+async (input) => {
+  const params = new URLSearchParams()
+  const qParts = []
+  if (input.query)
+    qParts.push(input.query)
+  if (input.name)
+    qParts.push(`name contains '${input.name.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`)
+  if (input.mimeType)
+    qParts.push(`mimeType = '${input.mimeType}'`)
+  if (!input.includeTrashed)
+    qParts.push('trashed = false')
+  if (qParts.length > 0)
+    params.set('q', qParts.join(' and '))
+  params.set('fields', input.fields || 'nextPageToken,files(id,name,mimeType,modifiedTime,size,parents)')
+  params.set('pageSize', String(input.pageSize || 20))
+  if (input.pageToken)
+    params.set('pageToken', input.pageToken)
+  const res = await integration.fetch(`/files?${params.toString()}`)
+  return await res.json()
+}

package/integrations/google-drive/handlers/share_file.js

@@ -0,0 +1,20 @@
+async (input) => {
+  const fileId = encodeURIComponent(input.fileId)
+  const params = new URLSearchParams()
+  if (input.sendNotificationEmail !== undefined)
+    params.set('sendNotificationEmail', String(input.sendNotificationEmail))
+  if (input.emailMessage)
+    params.set('emailMessage', input.emailMessage)
+  const body = {
+    role: input.role,
+    type: input.type,
+  }
+  if (input.emailAddress) body.emailAddress = input.emailAddress
+  if (input.domain) body.domain = input.domain
+  const qs = params.toString()
+  const res = await integration.fetch(`/files/${fileId}/permissions${qs ? `?${qs}` : ''}`, {
+    method: 'POST',
+    body,
+  })
+  return await res.json()
+}

package/integrations/google-drive/manifest.json

@@ -2,41 +2,68 @@
   "name": "google-drive",
   "version": "0.1.0",
   "tools": [
+    {
+      "name": "list_files",
+      "description": "List files in a Google Drive folder or across all of Drive. Returns id, name, mimeType, modifiedTime, size, and parents for each file. Excludes trashed files by default. Use folderId to scope to a specific folder. For name- or type-based search, use search_files instead. Defaults to 50 results per page; use pageToken from the response for the next page.",
+      "inputSchema": "schemas/list_files.json",
+      "handler": "handlers/list_files.js",
+      "scope": "read"
+    },
+    {
+      "name": "search_files",
+      "description": "Search Google Drive for files by name, MIME type, or raw Drive query syntax. Use the 'name' shorthand for simple name searches (e.g. name='quarterly report'). Use 'mimeType' to filter by type. Use 'query' for advanced Drive search expressions (e.g. \"modifiedTime > '2024-01-01'\" or \"'folderId' in parents and mimeType='application/pdf'\"). All provided filters are combined with AND. Defaults to 20 results per page.",
+      "inputSchema": "schemas/search_files.json",
+      "handler": "handlers/search_files.js",
+      "scope": "read"
+    },
+    {
+      "name": "get_file",
+      "description": "Get metadata for a Drive file or folder by ID. Returns id, name, mimeType, modifiedTime, createdTime, size, parents, trashed status, and webViewLink by default. To read the actual file contents, use get_file_content. To find a file by name, use search_files.",
+      "inputSchema": "schemas/get_file.json",
+      "handler": "handlers/get_file.js",
+      "scope": "read"
+    },
+    {
+      "name": "get_file_content",
+      "description": "Read the text content of a Drive file. For Google Workspace files (Docs, Sheets, Slides), automatically exports to text/plain or text/csv. Pass the 'mimeType' from get_file or search_files results to enable automatic export format detection. Use 'exportMimeType' to override the format (e.g. 'text/html' for formatted HTML, 'text/csv' for Sheets data). Returns {fileId, mimeType, content} for text files. Binary files (PDFs, images) return a message suggesting an export format.",
+      "inputSchema": "schemas/get_file_content.json",
+      "handler": "handlers/get_file_content.js",
+      "scope": "read"
+    },
     {
       "name": "create_folder",
-      "description": "Create a folder in Google Drive.",
+      "description": "Create a new folder in Google Drive. Optionally nest it inside a parent folder using parentId. Returns the created folder's metadata including its ID, which can be used as a parentId for subsequent file creation.",
       "inputSchema": "schemas/create_folder.json",
       "handler": "handlers/create_folder.js",
       "scope": "write"
     },
     {
       "name": "create_file",
-      "description": "Create a Drive file (including Google Docs/Sheets/Slides) optionally inside a parent folder.",
+      "description": "Create a new Drive file (metadata only -- no content upload). To create a Google Workspace file, use the appropriate mimeType: 'application/vnd.google-apps.document' for Docs, 'application/vnd.google-apps.spreadsheet' for Sheets, 'application/vnd.google-apps.presentation' for Slides. Optionally place it in a folder with parentId. Returns the created file's metadata including its ID.",
       "inputSchema": "schemas/create_file.json",
       "handler": "handlers/create_file.js",
       "scope": "write"
     },
     {
       "name": "move_file",
-      "description": "Move a file to a different parent folder (add/remove parents).",
+      "description": "Move a file or folder to a different parent folder by updating its parents. Provide the destination folder ID as addParents and optionally the current parent ID as removeParents (to remove it from the old location). Get the current parents from get_file.",
       "inputSchema": "schemas/move_file.json",
       "handler": "handlers/move_file.js",
       "scope": "write"
     },
     {
-      "name": "get_file",
-      "description": "Get a Drive file’s metadata by fileId.",
-      "inputSchema": "schemas/get_file.json",
-      "handler": "handlers/get_file.js",
-      "scope": "read"
+      "name": "share_file",
+      "description": "Share a Drive file or folder with a specific user, group, domain, or make it publicly accessible. Use type='user' with emailAddress for individual sharing. Use type='anyone' with role='reader' to create a public view link. Use type='domain' with domain for organization-wide sharing. Returns the created permission resource.",
+      "inputSchema": "schemas/share_file.json",
+      "handler": "handlers/share_file.js",
+      "scope": "write"
     },
     {
       "name": "delete_file",
-      "description": "Permanently delete a Drive file or folder by fileId.",
+      "description": "Permanently and immediately delete a Drive file or folder by ID. This bypasses Trash and cannot be undone. To move to Trash instead, use the Google Drive UI or modify file properties. Use search_files or list_files to find file IDs.",
       "inputSchema": "schemas/delete_file.json",
       "handler": "handlers/delete_file.js",
       "scope": "write"
     }
   ]
 }
-

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/__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)
+      })
+    })
+  }
+})