@commandable/integration-data 0.4.0 → 0.4.1

package/integrations/google-docs/schemas/insert_page_break.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "documentId": { "type": "string" },
+    "index": { "type": "number", "minimum": 1 }
+  },
+  "required": ["documentId", "index"],
+  "additionalProperties": false
+}

package/integrations/google-docs/schemas/insert_page_break_after_first_match.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "documentId": { "type": "string" },
+    "findText": { "type": "string" },
+    "position": { "type": "string", "enum": ["after", "before"], "default": "after" }
+  },
+  "required": ["documentId", "findText"],
+  "additionalProperties": false
+}

package/integrations/google-docs/schemas/insert_table.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "documentId": { "type": "string" },
+    "index": { "type": "number", "minimum": 1 },
+    "rows": { "type": "number", "minimum": 1 },
+    "columns": { "type": "number", "minimum": 1 }
+  },
+  "required": ["documentId", "index", "rows", "columns"],
+  "additionalProperties": false
+}

package/integrations/google-docs/schemas/insert_table_after_first_match.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "documentId": { "type": "string" },
+    "findText": { "type": "string" },
+    "rows": { "type": "number", "minimum": 1 },
+    "columns": { "type": "number", "minimum": 1 },
+    "position": { "type": "string", "enum": ["after", "before"], "default": "after" }
+  },
+  "required": ["documentId", "findText", "rows", "columns"],
+  "additionalProperties": false
+}

package/integrations/google-docs/schemas/insert_text_after_first_match.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "documentId": { "type": "string" },
+    "findText": { "type": "string" },
+    "insertText": { "type": "string" },
+    "position": { "type": "string", "enum": ["after", "before"], "default": "after" }
+  },
+  "required": ["documentId", "findText", "insertText"],
+  "additionalProperties": false
+}

package/integrations/google-docs/schemas/insert_text_at.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "documentId": { "type": "string" },
+    "index": { "type": "number", "minimum": 1 },
+    "text": { "type": "string" }
+  },
+  "required": ["documentId", "index", "text"],
+  "additionalProperties": false
+}

package/integrations/google-docs/schemas/read_document.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["documentId"],
+  "properties": {
+    "documentId": {
+      "type": "string",
+      "description": "Google Doc documentId from URL: https://docs.google.com/document/d/{documentId}/edit"
+    }
+  },
+  "additionalProperties": false
+}

package/integrations/google-docs/schemas/replace_all_text.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "documentId": { "type": "string" },
+    "findText": { "type": "string" },
+    "replaceText": { "type": "string" },
+    "matchCase": { "type": "boolean" }
+  },
+  "required": ["documentId", "findText", "replaceText"],
+  "additionalProperties": false
+}

package/integrations/google-docs/schemas/style_first_match.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "documentId": { "type": "string" },
+    "findText": { "type": "string" },
+    "textStyle": { "type": "object" },
+    "fields": { "type": "string" }
+  },
+  "required": ["documentId", "findText", "textStyle"],
+  "additionalProperties": false
+}

package/integrations/google-docs/schemas/update_document_style.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "documentId": { "type": "string" },
+    "documentStyle": { "type": "object", "description": "Docs API DocumentStyle object" },
+    "fields": { "type": "string" }
+  },
+  "required": ["documentId", "documentStyle"],
+  "additionalProperties": false
+}

package/integrations/google-docs/schemas/update_paragraph_style.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "documentId": { "type": "string" },
+    "startIndex": { "type": "number", "minimum": 1 },
+    "endIndex": { "type": "number", "minimum": 1 },
+    "paragraphStyle": { "type": "object", "description": "Docs API ParagraphStyle object" },
+    "fields": { "type": "string" }
+  },
+  "required": ["documentId", "startIndex", "endIndex", "paragraphStyle"],
+  "additionalProperties": false
+}

package/integrations/google-docs/schemas/update_paragraph_style_for_first_match.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "documentId": { "type": "string" },
+    "findText": { "type": "string" },
+    "paragraphStyle": { "type": "object" },
+    "fields": { "type": "string" }
+  },
+  "required": ["documentId", "findText", "paragraphStyle"],
+  "additionalProperties": false
+}

package/integrations/google-docs/todo.md

@@ -0,0 +1,18 @@
+## Future: Native markdown export via Drive API
+
+Google Drive `files.export` now supports `text/markdown` as an export MIME type for Google Docs (added July 2024). This could replace the custom Docs API -> markdown conversion in `read_document` with a single API call:
+
+```
+GET https://www.googleapis.com/drive/v3/files/{fileId}/export?mimeType=text/markdown
+```
+
+### Why we're not using it yet
+
+- The `google-docs` integration's base URL points to `docs.googleapis.com/v1`, not the Drive API. Calling Drive export would require either a proxy enhancement to allow cross-API calls or hardcoding the Drive URL in the handler.
+- The custom conversion (ported from taylorwilsdon's approach) keeps the integration self-contained within the Docs API.
+
+### When to revisit
+
+- If we add cross-provider fetch support to the proxy/handler runtime.
+- If the custom markdown conversion proves unreliable or hard to maintain.
+- The Drive export requires `drive.readonly` scope (already included in the docs credential config).

package/integrations/google-drive/README.md

@@ -0,0 +1,26 @@
+# Google Drive
+
+**9 tools**
+
+![Google Drive tests](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/theomccabe/771bd329f303087690c522afa1baa6f3/raw/test-google-drive.json)
+
+## Credential variants
+
+| Variant | Label |
+|---|---|
+| `service_account` | Service Account (recommended) _(default)_ |
+| `oauth_token` | OAuth Access Token (short-lived) |
+
+## Tools
+
+| Tool | Scope | Description |
+|---|---|---|
+| `list_files` | read | List files in a Google Drive folder or across all of Drive. Returns id, name, mimeType, m… |
+| `search_files` | read | Search Google Drive for files by name, MIME type, or raw Drive query syntax. Use the 'nam… |
+| `get_file` | read | Get metadata for a Drive file or folder by ID. Returns id, name, mimeType, modifiedTime, … |
+| `get_file_content` | read | Read the text content of a Drive file. For Google Workspace files (Docs, Sheets, Slides),… |
+| `create_folder` | write | Create a new folder in Google Drive. Optionally nest it inside a parent folder using pare… |
+| `create_file` | write | Create a new Drive file (metadata only -- no content upload). To create a Google Workspac… |
+| `move_file` | write | Move a file or folder to a different parent folder by updating its parents. Provide the d… |
+| `share_file` | write | Share a Drive file or folder with a specific user, group, domain, or make it publicly acc… |
+| `delete_file` | write | Permanently and immediately delete a Drive file or folder by ID. This bypasses Trash and … |

package/integrations/google-drive/__tests__/handlers.test.ts

@@ -0,0 +1,145 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { createCredentialStore, createIntegrationNode, createProxy, createToolbox, safeCleanup } from '../../__tests__/liveHarness.js'
+
+// LIVE Google Drive tests -- runs once per available credential variant.
+// Required env vars (at least one):
+// - GOOGLE_SERVICE_ACCOUNT_JSON  (service_account variant)
+// - GOOGLE_TOKEN                 (oauth_token variant)
+
+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-drive handlers (live)', () => {
+  for (const variant of variants) {
+    describe(`variant: ${variant.key}`, () => {
+      const ctx: { folderId?: string, fileId?: string, destFolderId?: string } = {}
+      let drive: ReturnType<typeof createToolbox>
+
+      beforeAll(async () => {
+        const credentialStore = createCredentialStore(async () => variant.credentials())
+        const proxy = createProxy(credentialStore)
+        drive = createToolbox(
+          'google-drive',
+          proxy,
+          createIntegrationNode('google-drive', { label: 'Google Drive', credentialId: 'google-drive-creds', credentialVariant: variant.key }),
+          variant.key,
+        )
+
+        const folder = await drive.write('create_folder')({ name: `CmdTest Drive ${Date.now()}` })
+        ctx.folderId = folder?.id
+        expect(ctx.folderId).toBeTruthy()
+
+        const destFolder = await drive.write('create_folder')({ name: `CmdTest Drive Dest ${Date.now()}` })
+        ctx.destFolderId = destFolder?.id
+        expect(ctx.destFolderId).toBeTruthy()
+
+        const file = await drive.write('create_file')({
+          name: `CmdTest File ${Date.now()}`,
+          mimeType: 'application/vnd.google-apps.document',
+          parentId: ctx.folderId,
+        })
+        ctx.fileId = file?.id
+        expect(ctx.fileId).toBeTruthy()
+      }, 60000)
+
+      afterAll(async () => {
+        await safeCleanup(async () => ctx.fileId ? drive.write('delete_file')({ fileId: ctx.fileId }) : Promise.resolve())
+        await safeCleanup(async () => ctx.folderId ? drive.write('delete_file')({ fileId: ctx.folderId }) : Promise.resolve())
+        await safeCleanup(async () => ctx.destFolderId ? drive.write('delete_file')({ fileId: ctx.destFolderId }) : Promise.resolve())
+      }, 60000)
+
+      it('list_files returns files in folder', async () => {
+        if (!ctx.folderId)
+          return expect(true).toBe(true)
+        const result = await drive.read('list_files')({ folderId: ctx.folderId })
+        expect(Array.isArray(result?.files)).toBe(true)
+        expect(result?.files.some((f: any) => f?.id === ctx.fileId)).toBe(true)
+      }, 30000)
+
+      it('search_files finds file by name', async () => {
+        if (!ctx.fileId)
+          return expect(true).toBe(true)
+        const meta = await drive.read('get_file')({ fileId: ctx.fileId })
+        const name = meta?.name
+        if (!name)
+          return expect(true).toBe(true)
+        const result = await drive.read('search_files')({ name: name.slice(0, 10) })
+        expect(Array.isArray(result?.files)).toBe(true)
+      }, 30000)
+
+      it('get_file returns file metadata', async () => {
+        if (!ctx.fileId)
+          return expect(true).toBe(true)
+        const result = await drive.read('get_file')({ fileId: ctx.fileId })
+        expect(result?.id).toBe(ctx.fileId)
+        expect(typeof result?.name).toBe('string')
+        expect(typeof result?.mimeType).toBe('string')
+      }, 30000)
+
+      it('get_file_content exports a Google Doc as text', async () => {
+        if (!ctx.fileId)
+          return expect(true).toBe(true)
+        const result = await drive.read('get_file_content')({
+          fileId: ctx.fileId,
+          mimeType: 'application/vnd.google-apps.document',
+        })
+        expect(result?.fileId).toBe(ctx.fileId)
+        // A newly created empty doc may have empty content -- just verify the shape
+        expect(result?.content !== undefined || result?.message !== undefined).toBe(true)
+      }, 30000)
+
+      it('share_file shares a file with anyone reader', async () => {
+        if (!ctx.fileId)
+          return expect(true).toBe(true)
+        const result = await drive.write('share_file')({
+          fileId: ctx.fileId,
+          role: 'reader',
+          type: 'anyone',
+          sendNotificationEmail: false,
+        })
+        expect(result?.id || result?.role).toBeTruthy()
+      }, 30000)
+
+      it('move_file moves the file to a different folder', async () => {
+        if (!ctx.fileId || !ctx.destFolderId || !ctx.folderId)
+          return expect(true).toBe(true)
+        const result = await drive.write('move_file')({
+          fileId: ctx.fileId,
+          addParents: ctx.destFolderId,
+          removeParents: ctx.folderId,
+        })
+        expect(result?.id).toBe(ctx.fileId)
+        const meta = await drive.read('get_file')({ fileId: ctx.fileId })
+        expect(meta?.parents).toContain(ctx.destFolderId)
+      }, 30000)
+
+      it('delete_file deletes a file permanently', async () => {
+        const tempFile = await drive.write('create_file')({
+          name: `CmdTest Temp ${Date.now()}`,
+          mimeType: 'application/vnd.google-apps.document',
+        })
+        const tempId = tempFile?.id
+        expect(tempId).toBeTruthy()
+        await drive.write('delete_file')({ fileId: tempId })
+        await expect(drive.read('get_file')({ fileId: tempId })).rejects.toThrow()
+      }, 30000)
+    })
+  }
+})

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

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

package/integrations/google-drive/credentials.json

@@ -0,0 +1,59 @@
+{
+  "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": "Optional user email to impersonate when using Google Workspace domain-wide delegation."
+          },
+          "scopes": {
+            "type": "array",
+            "title": "OAuth scopes (optional)",
+            "description": "Optional override for OAuth scopes. Defaults to drive.",
+            "items": { "type": "string" }
+          }
+        },
+        "required": ["serviceAccountJson"],
+        "additionalProperties": false
+      },
+      "injection": {
+        "headers": {
+          "Authorization": "Bearer {{token}}"
+        }
+      },
+      "preprocess": "google_service_account",
+      "healthCheck": { "path": "/files?pageSize=1&fields=files%28id%29" }
+    },
+    "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 drive scope."
+          }
+        },
+        "required": ["token"],
+        "additionalProperties": false
+      },
+      "injection": {
+        "headers": {
+          "Authorization": "Bearer {{token}}"
+        }
+      },
+      "healthCheck": { "path": "/files?pageSize=1&fields=files%28id%29" }
+    }
+  },
+  "default": "service_account"
+}

package/integrations/google-drive/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 the scope: `https://www.googleapis.com/auth/drive`
+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 use, prefer the Service Account variant.

package/integrations/google-drive/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 **Google Drive 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. Share the Drive folders/files you want to access with the service account's `client_email`
+
+For Google Workspace users: optionally configure domain-wide delegation and set `subject` to the user's email.

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

@@ -0,0 +1,15 @@
+async (input) => {
+  const body = {
+    name: input.name,
+    mimeType: input.mimeType,
+  }
+  if (input.parentId)
+    body.parents = [input.parentId]
+
+  const res = await integration.fetch('/files', {
+    method: 'POST',
+    body,
+  })
+  return await res.json()
+}
+

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

@@ -0,0 +1,15 @@
+async (input) => {
+  const body = {
+    name: input.name,
+    mimeType: 'application/vnd.google-apps.folder',
+  }
+  if (input.parentId)
+    body.parents = [input.parentId]
+
+  const res = await integration.fetch('/files', {
+    method: 'POST',
+    body,
+  })
+  return await res.json()
+}
+

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

@@ -0,0 +1,14 @@
+async (input) => {
+  const res = await integration.fetch(`/files/${encodeURIComponent(input.fileId)}`, {
+    method: 'DELETE',
+  })
+  if (res.status === 204)
+    return { success: true, status: 204 }
+  try {
+    return await res.json()
+  }
+  catch {
+    return { success: res.ok, status: res.status }
+  }
+}
+

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

@@ -0,0 +1,5 @@
+async (input) => {
+  const fields = input.fields || 'id,name,mimeType,modifiedTime,createdTime,size,parents,trashed,webViewLink'
+  const res = await integration.fetch(`/files/${encodeURIComponent(input.fileId)}?fields=${encodeURIComponent(fields)}`)
+  return await res.json()
+}

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

@@ -0,0 +1,41 @@
+async (input) => {
+  const fileId = encodeURIComponent(input.fileId)
+  const googleExportMap = {
+    'application/vnd.google-apps.document': 'text/plain',
+    'application/vnd.google-apps.spreadsheet': 'text/csv',
+    'application/vnd.google-apps.presentation': 'text/plain',
+    'application/vnd.google-apps.drawing': 'image/svg+xml',
+    'application/vnd.google-apps.script': 'application/vnd.google-apps.script+json',
+  }
+  const exportMimeType = input.exportMimeType
+    || (input.mimeType ? googleExportMap[input.mimeType] : null)
+    || null
+
+  let res
+  if (exportMimeType) {
+    res = await integration.fetch(`/files/${fileId}/export?mimeType=${encodeURIComponent(exportMimeType)}`)
+  }
+  else {
+    res = await integration.fetch(`/files/${fileId}?alt=media`)
+  }
+
+  const contentType = res.headers?.get?.('content-type') || ''
+  const isText = contentType.startsWith('text/')
+    || contentType.includes('json')
+    || contentType.includes('csv')
+    || contentType.includes('xml')
+    || contentType.includes('javascript')
+
+  if (isText) {
+    const content = await res.text()
+    return { fileId: input.fileId, mimeType: contentType, content }
+  }
+
+  // Binary content: inform the agent it needs a text export
+  return {
+    fileId: input.fileId,
+    mimeType: contentType,
+    content: null,
+    message: `Binary content (${contentType}). To get readable text, provide exportMimeType='text/plain' for documents, 'text/csv' for spreadsheets, or 'text/html'. For PDFs and images this is not possible via export.`,
+  }
+}

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/move_file.js

@@ -0,0 +1,12 @@
+async (input) => {
+  const params = new URLSearchParams()
+  params.set('addParents', input.addParents)
+  if (input.removeParents)
+    params.set('removeParents', input.removeParents)
+
+  const res = await integration.fetch(`/files/${encodeURIComponent(input.fileId)}?${params.toString()}`, {
+    method: 'PATCH',
+  })
+  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()
+}