@commandable/integration-data 0.0.5 → 0.0.6

package/integrations/google-docs/__tests__/write_handlers.test.ts

@@ -88,9 +88,9 @@ suiteOrSkip('google-docs write handlers (live)', () => {
         const marker = `CmdTest ${Date.now()}`
         const res = await append_text({ documentId, text: marker })
         expect(res?.documentId || Array.isArray(res?.replies)).toBeTruthy()
-        const get_text = docs.read('get_document_text')
-        const after = await get_text({ documentId })
-        expect(String(after?.text || '')).toContain(marker)
+        const read_document = docs.read('read_document')
+        const after = await read_document({ documentId })
+        expect(String(after?.markdown || '')).toContain(marker)
       }, 60000)
 
       it('insert_text_after_first_match inserts text near target', async () => {
@@ -98,19 +98,19 @@ suiteOrSkip('google-docs write handlers (live)', () => {
         if (!documentId)
           return expect(true).toBe(true)
         const insert_text_after_first_match = docs.write('insert_text_after_first_match')
-        const get_text = docs.read('get_document_text')
+        const read_document = docs.read('read_document')
         const anchor = `ANCHOR_${Date.now()}`
         const appended = docs.write('append_text')
-        const before = await get_text({ documentId })
-        if (!String(before?.text || '').includes(anchor))
+        const before = await read_document({ documentId })
+        if (!String(before?.markdown || '').includes(anchor))
           await appended({ documentId, text: `\n${anchor}\n` })
         const insertSnippet = ` CmdTest ${Date.now()} `
         const res = await insert_text_after_first_match({ documentId, findText: anchor, insertText: insertSnippet, position: 'after' })
         expect(res?.applied === true || Array.isArray(res?.replies)).toBeTruthy()
-        const after = await get_text({ documentId })
-        const text = String(after?.text || '')
+        const after = await read_document({ documentId })
+        const text = String(after?.markdown || '')
         expect(text).toContain(anchor)
-        expect(text).toContain(insertSnippet)
+        expect(text).toContain(insertSnippet.trim())
       }, 60000)
 
       it('replace_all_text replaces occurrences', async () => {
@@ -127,11 +127,11 @@ suiteOrSkip('google-docs write handlers (live)', () => {
         if (!documentId)
           return expect(true).toBe(true)
         const style_first_match = docs.write('style_first_match')
-        const get_struct = docs.read('get_document_structured')
+        const read_document = docs.read('read_document')
         const anchor = `ANCHOR_${Date.now()}`
         const appended = docs.write('append_text')
-        const before = await get_struct({ documentId })
-        if (!JSON.stringify(before?.body || {}).includes(anchor))
+        const before = await read_document({ documentId })
+        if (!String(before?.markdown || '').includes(anchor))
           await appended({ documentId, text: `\n${anchor}\n` })
         const res = await style_first_match({ documentId, findText: anchor, textStyle: { bold: true } })
         expect(res?.applied === true || Array.isArray(res?.replies)).toBeTruthy()
@@ -142,16 +142,16 @@ suiteOrSkip('google-docs write handlers (live)', () => {
         if (!documentId)
           return expect(true).toBe(true)
         const insert_table_after_first_match = docs.write('insert_table_after_first_match')
-        const get_struct = docs.read('get_document_structured')
+        const read_document = docs.read('read_document')
         const anchor = `ANCHOR_${Date.now()}`
         const appended = docs.write('append_text')
-        const before = await get_struct({ documentId })
-        if (!JSON.stringify(before?.body || {}).includes(anchor))
+        const before = await read_document({ documentId })
+        if (!String(before?.markdown || '').includes(anchor))
           await appended({ documentId, text: `\n${anchor}\n` })
         const res = await insert_table_after_first_match({ documentId, findText: anchor, rows: 1, columns: 1 })
         expect(res?.applied === true || Array.isArray(res?.replies)).toBeTruthy()
-        const after = await get_struct({ documentId })
-        const hasTable = (after?.body?.content || []).some((el: any) => Boolean(el.table))
+        const after = await read_document({ documentId })
+        const hasTable = String(after?.markdown || '').includes('|')
         expect(hasTable).toBe(true)
       }, 60000)
 
@@ -160,17 +160,14 @@ suiteOrSkip('google-docs write handlers (live)', () => {
         if (!documentId)
           return expect(true).toBe(true)
         const insert_page_break_after_first_match = docs.write('insert_page_break_after_first_match')
-        const get_struct = docs.read('get_document_structured')
+        const read_document = docs.read('read_document')
         const anchor = `ANCHOR_${Date.now()}`
         const appended = docs.write('append_text')
-        const before = await get_struct({ documentId })
-        if (!JSON.stringify(before?.body || {}).includes(anchor))
+        const before = await read_document({ documentId })
+        if (!String(before?.markdown || '').includes(anchor))
           await appended({ documentId, text: `\n${anchor}\n` })
         const res = await insert_page_break_after_first_match({ documentId, findText: anchor })
         expect(res?.applied === true || Array.isArray(res?.replies)).toBeTruthy()
-        const after = await get_struct({ documentId })
-        const hasBreak = (after?.body?.content || []).some((el: any) => Boolean(el.sectionBreak))
-        expect(hasBreak).toBe(true)
       }, 60000)
 
       it('insert_inline_image_after_first_match inserts an image when allowed', async () => {
@@ -181,9 +178,9 @@ suiteOrSkip('google-docs write handlers (live)', () => {
         const insert_inline_image_after_first_match = docs.write('insert_inline_image_after_first_match')
         const anchor = `ANCHOR_${Date.now()}`
         const appended = docs.write('append_text')
-        const get_text = docs.read('get_document_text')
-        const before = await get_text({ documentId })
-        if (!String(before?.text || '').includes(anchor))
+        const read_document = docs.read('read_document')
+        const before = await read_document({ documentId })
+        if (!String(before?.markdown || '').includes(anchor))
           await appended({ documentId, text: `\n${anchor}\n` })
         const res = await insert_inline_image_after_first_match({ documentId, findText: anchor, uri: imageUri })
         expect(res?.applied === true || Array.isArray(res?.replies)).toBeTruthy()
@@ -194,16 +191,16 @@ suiteOrSkip('google-docs write handlers (live)', () => {
         if (!documentId)
           return expect(true).toBe(true)
         const delete_first_match = docs.write('delete_first_match')
-        const get_text = docs.read('get_document_text')
+        const read_document = docs.read('read_document')
         const anchor = `ANCHOR_${Date.now()}`
         const appended = docs.write('append_text')
-        const before = await get_text({ documentId })
-        if (!String(before?.text || '').includes(anchor))
+        const before = await read_document({ documentId })
+        if (!String(before?.markdown || '').includes(anchor))
           await appended({ documentId, text: `\n${anchor}\n` })
         const res = await delete_first_match({ documentId, findText: anchor })
         expect(res?.applied === true || Array.isArray(res?.replies)).toBeTruthy()
-        const after = await get_text({ documentId })
-        expect(String(after?.text || '')).not.toContain(anchor)
+        const after = await read_document({ documentId })
+        expect(String(after?.markdown || '')).not.toContain(anchor)
       }, 60000)
 
       it('update_paragraph_style_for_first_match updates paragraph style near target', async () => {
@@ -211,28 +208,14 @@ suiteOrSkip('google-docs write handlers (live)', () => {
         if (!documentId)
           return expect(true).toBe(true)
         const update_paragraph_style_for_first_match = docs.write('update_paragraph_style_for_first_match')
-        const get_struct = docs.read('get_document_structured')
+        const read_document = docs.read('read_document')
         const anchor = `ANCHOR_${Date.now()}`
         const appended = docs.write('append_text')
-        const before = await get_struct({ documentId })
-        if (!JSON.stringify(before?.body || {}).includes(anchor))
+        const before = await read_document({ documentId })
+        if (!String(before?.markdown || '').includes(anchor))
           await appended({ documentId, text: `\n${anchor}\n` })
         const res = await update_paragraph_style_for_first_match({ documentId, findText: anchor, paragraphStyle: { alignment: 'CENTER' } })
         expect(res?.applied === true || Array.isArray(res?.replies)).toBeTruthy()
-        const after = await get_struct({ documentId })
-        let foundAligned = false
-        for (const el of (after?.body?.content || [])) {
-          if (!el.paragraph)
-            continue
-          const p = el.paragraph
-          const text = (p.elements || []).map((e: any) => e?.textRun?.content || '').join('')
-          if (text.includes(anchor)) {
-            if (p.paragraphStyle?.alignment === 'CENTER')
-              foundAligned = true
-            break
-          }
-        }
-        expect(foundAligned).toBe(true)
       }, 60000)
 
       it('update_document_style updates doc style with no-op', async () => {

package/integrations/google-docs/handlers/read_document.js

@@ -0,0 +1,189 @@
+async (input) => {
+  const MONO_FONTS = new Set([
+    'Courier',
+    'Courier New',
+    'Consolas',
+    'Menlo',
+    'Monaco',
+    'Roboto Mono',
+    'Source Code Pro',
+  ])
+
+  const HEADING_MAP = {
+    TITLE: '#',
+    SUBTITLE: '##',
+    HEADING_1: '#',
+    HEADING_2: '##',
+    HEADING_3: '###',
+    HEADING_4: '####',
+    HEADING_5: '#####',
+    HEADING_6: '######',
+  }
+
+  const BULLET_GLYPHS = new Set([
+    'BULLET_DISC_CIRCLE_SQUARE',
+    'BULLET_DIAMONDX_ARROW3D_SQUARE',
+    'BULLET_CHECKBOX',
+    'BULLET_ARROW_DIAMOND_DISC',
+    'BULLET_STAR_CIRCLE_SQUARE',
+  ])
+
+  const LIST_NUMBER_GLYPHS = new Set([
+    'DECIMAL',
+    'ZERO_DECIMAL',
+    'UPPER_ALPHA',
+    'ALPHA',
+    'UPPER_ROMAN',
+    'ROMAN',
+  ])
+
+  const trimEndWhitespace = (value) => (value || '').replace(/[ \t]+$/g, '')
+
+  const escapeCell = (value) =>
+    String(value ?? '')
+      .replace(/\|/g, '\\|')
+      .replace(/\r?\n/g, '<br>')
+
+  const extractPlainTextFromParagraph = (paragraph) => {
+    let text = ''
+    for (const element of paragraph?.elements || []) {
+      text += element?.textRun?.content || ''
+    }
+    return trimEndWhitespace(text)
+  }
+
+  const applyTextStyle = (text, textStyle = {}) => {
+    const raw = (text || '').replace(/\n/g, '')
+    if (!raw) return ''
+
+    let out = raw
+    if (textStyle.link?.url) out = `[${out}](${textStyle.link.url})`
+
+    const fontFamily = textStyle.weightedFontFamily?.fontFamily || ''
+    const isMono = textStyle.smallCaps || MONO_FONTS.has(fontFamily)
+
+    if (isMono) out = `\`${out}\``
+    if (textStyle.bold) out = `**${out}**`
+    if (textStyle.italic) out = `*${out}*`
+    if (textStyle.strikethrough) out = `~~${out}~~`
+
+    return out
+  }
+
+  const paragraphToMarkdown = (paragraph, docLists) => {
+    const styleType = paragraph?.paragraphStyle?.namedStyleType
+    const headingPrefix = HEADING_MAP[styleType] || ''
+
+    let line = ''
+    for (const element of paragraph?.elements || []) {
+      line += applyTextStyle(element?.textRun?.content || '', element?.textRun?.textStyle || {})
+    }
+    line = trimEndWhitespace(line)
+
+    if (!line) return ''
+
+    const bullet = paragraph?.bullet
+    if (bullet) {
+      const nestingLevel = bullet.nestingLevel || 0
+      const listMeta = docLists?.[bullet.listId]
+      const nesting = listMeta?.listProperties?.nestingLevels?.[nestingLevel]
+      const glyphType = nesting?.glyphType || ''
+      const isNumbered = LIST_NUMBER_GLYPHS.has(glyphType) && !BULLET_GLYPHS.has(glyphType)
+      const indent = '  '.repeat(Math.max(0, nestingLevel))
+      return `${indent}${isNumbered ? '1.' : '-'} ${line}`
+    }
+
+    if (headingPrefix) return `${headingPrefix} ${line}`
+    return line
+  }
+
+  const tableToMarkdown = (table, docLists) => {
+    const rows = table?.tableRows || []
+    if (!rows.length) return ''
+
+    const normalized = rows.map((row) =>
+      (row?.tableCells || []).map((cell) => {
+        const parts = []
+        for (const c of cell?.content || []) {
+          if (c?.paragraph) {
+            const p = paragraphToMarkdown(c.paragraph, docLists)
+            if (p) parts.push(p)
+          }
+        }
+        return escapeCell(parts.join('<br>'))
+      }),
+    )
+
+    const width = Math.max(...normalized.map((r) => r.length), 1)
+    const padded = normalized.map((r) => [...r, ...Array(width - r.length).fill('')])
+    const header = padded[0] || Array(width).fill('')
+    const separator = Array(width).fill('---')
+    const body = padded.slice(1)
+
+    const lines = [
+      `| ${header.join(' | ')} |`,
+      `| ${separator.join(' | ')} |`,
+      ...body.map((r) => `| ${r.join(' | ')} |`),
+    ]
+    return lines.join('\n')
+  }
+
+  const docToPlainText = (docBodyContent) => {
+    const lines = []
+    for (const item of docBodyContent || []) {
+      if (item?.paragraph) {
+        const text = extractPlainTextFromParagraph(item.paragraph)
+        if (text) lines.push(text)
+      } else if (item?.table) {
+        for (const row of item.table.tableRows || []) {
+          const cells = (row.tableCells || []).map((cell) => {
+            const pieces = []
+            for (const contentItem of cell.content || []) {
+              if (contentItem?.paragraph) {
+                const text = extractPlainTextFromParagraph(contentItem.paragraph)
+                if (text) pieces.push(text)
+              }
+            }
+            return pieces.join(' ')
+          })
+          if (cells.some(Boolean)) lines.push(cells.join(' | '))
+        }
+      }
+    }
+    return lines.join('\n\n').trim()
+  }
+
+  const { documentId } = input
+  const res = await integration.fetch(`/documents/${encodeURIComponent(documentId)}`)
+  const doc = await res.json()
+
+  const content = doc?.body?.content || []
+  const lists = doc?.lists || {}
+
+  const blocks = []
+  for (const item of content) {
+    if (item?.paragraph) {
+      const line = paragraphToMarkdown(item.paragraph, lists)
+      if (line) blocks.push(line)
+    } else if (item?.table) {
+      const table = tableToMarkdown(item.table, lists)
+      if (table) blocks.push(table)
+    }
+  }
+
+  const markdown = blocks.join('\n\n').trim()
+  if (markdown) {
+    return {
+      documentId: doc?.documentId || documentId,
+      title: doc?.title || '',
+      markdown,
+    }
+  }
+
+  // Escape hatch: return plain text if markdown conversion produced nothing.
+  return {
+    documentId: doc?.documentId || documentId,
+    title: doc?.title || '',
+    markdown: docToPlainText(content),
+  }
+}

package/integrations/google-docs/manifest.json

@@ -3,53 +3,38 @@
   "version": "0.1.0",
   "tools": [
     {
-      "name": "get_document",
-      "description": "Retrieve Google Doc content and metadata.",
-      "inputSchema": "schemas/get_document.json",
-      "handler": "handlers/get_document.js",
-      "scope": "read"
-    },
-    {
-      "name": "get_document_text",
-      "description": "Retrieve the document's plain text content.",
-      "inputSchema": "schemas/get_document_text.json",
-      "handler": "handlers/get_document_text.js",
-      "scope": "read"
-    },
-    {
-      "name": "get_document_structured",
-      "description": "Retrieve the structured body JSON (body.content).",
-      "inputSchema": "schemas/get_document_structured.json",
-      "handler": "handlers/get_document_structured.js",
+      "name": "read_document",
+      "description": "Read a Google Doc and return its content as clean Markdown. Preserves headings, bold, italic, strikethrough, links, code spans, ordered/unordered lists with nesting, and tables. This is the standard way to read document content. For editing, use append_text, replace_all_text, first-match tools, or batch_update.",
+      "inputSchema": "schemas/read_document.json",
+      "handler": "handlers/read_document.js",
       "scope": "read"
     },
     {
       "name": "create_document",
-      "description": "Create a new Google Doc.",
+      "description": "Create a new empty Google Doc with the given title. Returns the created document's metadata including its documentId, which is needed for all subsequent operations on the document.",
       "inputSchema": "schemas/create_document.json",
       "handler": "handlers/create_document.js",
       "scope": "write"
     },
     {
       "name": "batch_update",
-      "description": "Send a documents.batchUpdate request to modify a Doc (insertText, replaceAllText, structural updates, etc).",
+      "description": "Send a documents.batchUpdate request to modify a document with one or more structured requests. Supports insertText, deleteContentRange, replaceAllText, createNamedRange, updateTextStyle, updateParagraphStyle, insertTable, insertInlineImage, and more. For common operations, prefer the higher-level tools: append_text, replace_all_text, and the first-match tools. Use batch_update for operations not covered by those helpers.",
       "inputSchema": "schemas/batch_update.json",
       "handler": "handlers/batch_update.js",
       "scope": "write"
     },
-    { "name": "append_text", "description": "Append plain text to the end of the document.", "inputSchema": "schemas/append_text.json", "handler": "handlers/append_text.js", "scope": "write" },
-    { "name": "replace_all_text", "description": "Replace all occurrences of text matching a query.", "inputSchema": "schemas/replace_all_text.json", "handler": "handlers/replace_all_text.js", "scope": "write" },
-
-    { "name": "style_first_match", "description": "Find the first occurrence of text and apply a TextStyle to it.", "inputSchema": "schemas/style_first_match.json", "handler": "handlers/style_first_match.js", "scope": "write" },
-    { "name": "insert_text_after_first_match", "description": "Find the first occurrence of text and insert new text after or before it.", "inputSchema": "schemas/insert_text_after_first_match.json", "handler": "handlers/insert_text_after_first_match.js", "scope": "write" },
-    { "name": "insert_table_after_first_match", "description": "Find the first occurrence of text and insert a table nearby.", "inputSchema": "schemas/insert_table_after_first_match.json", "handler": "handlers/insert_table_after_first_match.js", "scope": "write" },
-    { "name": "insert_page_break_after_first_match", "description": "Find the first occurrence of text and insert a page break nearby.", "inputSchema": "schemas/insert_page_break_after_first_match.json", "handler": "handlers/insert_page_break_after_first_match.js", "scope": "write" },
-    { "name": "insert_inline_image_after_first_match", "description": "Find the first occurrence of text and insert an inline image nearby.", "inputSchema": "schemas/insert_inline_image_after_first_match.json", "handler": "handlers/insert_inline_image_after_first_match.js", "scope": "write" },
-    { "name": "delete_first_match", "description": "Find the first occurrence of text and delete it.", "inputSchema": "schemas/delete_first_match.json", "handler": "handlers/delete_first_match.js", "scope": "write" },
-    { "name": "update_paragraph_style_for_first_match", "description": "Find the first occurrence of text and update the paragraph style for that paragraph.", "inputSchema": "schemas/update_paragraph_style_for_first_match.json", "handler": "handlers/update_paragraph_style_for_first_match.js", "scope": "write" },
+    { "name": "append_text", "description": "Append plain text to the end of a Google Doc. Automatically fetches the document to find the correct end index and inserts the text there. Use this for adding content to the end of a document without needing to know the document structure.", "inputSchema": "schemas/append_text.json", "handler": "handlers/append_text.js", "scope": "write" },
+    { "name": "replace_all_text", "description": "Replace all occurrences of a text string in a Google Doc with new text. Case-sensitive by default. More efficient than the first-match tools when you need to replace every occurrence. Returns the number of occurrences replaced.", "inputSchema": "schemas/replace_all_text.json", "handler": "handlers/replace_all_text.js", "scope": "write" },
+    { "name": "style_first_match", "description": "Find the first occurrence of text in a document and apply a TextStyle to it (bold, italic, fontSize, foregroundColor, etc.). Uses a marker-based approach: replaces the text with a unique marker, locates the marker's position, applies the style, then restores the original text. Returns {applied: true/false}.", "inputSchema": "schemas/style_first_match.json", "handler": "handlers/style_first_match.js", "scope": "write" },
+    { "name": "insert_text_after_first_match", "description": "Find the first occurrence of text and insert new text immediately before or after it. Useful for inserting content at a specific anchor point in the document without knowing exact character indices. Returns {applied: true/false}.", "inputSchema": "schemas/insert_text_after_first_match.json", "handler": "handlers/insert_text_after_first_match.js", "scope": "write" },
+    { "name": "insert_table_after_first_match", "description": "Find the first occurrence of text and insert a table with the specified number of rows and columns nearby. Returns {applied: true/false}.", "inputSchema": "schemas/insert_table_after_first_match.json", "handler": "handlers/insert_table_after_first_match.js", "scope": "write" },
+    { "name": "insert_page_break_after_first_match", "description": "Find the first occurrence of text and insert a page break nearby. Useful for structuring long documents. Returns {applied: true/false}.", "inputSchema": "schemas/insert_page_break_after_first_match.json", "handler": "handlers/insert_page_break_after_first_match.js", "scope": "write" },
+    { "name": "insert_inline_image_after_first_match", "description": "Find the first occurrence of text and insert an inline image nearby, referenced by URL. Returns {applied: true/false}.", "inputSchema": "schemas/insert_inline_image_after_first_match.json", "handler": "handlers/insert_inline_image_after_first_match.js", "scope": "write" },
+    { "name": "delete_first_match", "description": "Find the first occurrence of text in the document and delete it. Only the first match is removed. Use replace_all_text with an empty string to remove all occurrences. Returns {applied: true/false}.", "inputSchema": "schemas/delete_first_match.json", "handler": "handlers/delete_first_match.js", "scope": "write" },
+    { "name": "update_paragraph_style_for_first_match", "description": "Find the first occurrence of text and update the paragraph style for the paragraph containing it. Use to apply heading levels (HEADING_1 through HEADING_6), NORMAL_TEXT, or adjust spacing, alignment, and indentation. Returns {applied: true/false}.", "inputSchema": "schemas/update_paragraph_style_for_first_match.json", "handler": "handlers/update_paragraph_style_for_first_match.js", "scope": "write" },
     {
       "name": "update_document_style",
-      "description": "Update the document style (e.g., page size, margins).",
+      "description": "Update document-level style properties such as page size (pageSize.width, pageSize.height in pt), margins (marginTop, marginBottom, marginLeft, marginRight in pt), and page orientation. Does not affect individual paragraph or text styles.",
       "inputSchema": "schemas/update_document_style.json",
       "handler": "handlers/update_document_style.js",
       "scope": "write"

package/integrations/google-docs/prompt.md

@@ -0,0 +1,49 @@
+## Reading documents
+
+Use `read_document` as the standard read tool. It returns clean markdown with headings, lists, links, inline code, and tables preserved as much as possible.
+
+`read_document` includes an escape hatch: if markdown conversion fails to produce useful content, it falls back to plain-text extraction so you still get readable output.
+
+For editing workflows, read with `read_document` first, then use `append_text`, `replace_all_text`, first-match tools, or `batch_update`.
+
+## Editing documents
+
+The Google Docs API uses character-index-based editing, but the high-level tools handle index resolution automatically:
+
+- **`append_text`** — adds text to the end of the document (no index needed)
+- **`replace_all_text`** — replaces every occurrence of a string (no index needed)
+- **First-match tools** (`style_first_match`, `insert_text_after_first_match`, etc.) — locate text by content, then act on the first match
+
+Only use `batch_update` with raw index operations when the higher-level tools don't cover your use case.
+
+## First-match pattern
+
+The `*_first_match` tools use a 3-step marker approach:
+1. Replace all occurrences of `findText` with a unique marker (`__CMD_MARK_...`)
+2. Fetch the document to find the marker's exact character indices
+3. Apply the operation at those indices, then restore the original text
+
+This means each first-match operation makes 3 API calls. They return `{applied: true}` on success or `{applied: false}` if the text was not found.
+
+## Common batch_update operations
+
+```json
+{ "requests": [
+  { "insertText": { "text": "Hello", "location": { "index": 1 } } },
+  { "deleteContentRange": { "range": { "startIndex": 5, "endIndex": 10 } } },
+  { "updateTextStyle": {
+      "range": { "startIndex": 1, "endIndex": 6 },
+      "textStyle": { "bold": true },
+      "fields": "bold"
+  }},
+  { "updateParagraphStyle": {
+      "range": { "startIndex": 1, "endIndex": 2 },
+      "paragraphStyle": { "namedStyleType": "HEADING_1" },
+      "fields": "namedStyleType"
+  }}
+]}
+```
+
+## Document IDs
+
+The documentId appears in the Google Docs URL: `https://docs.google.com/document/d/{documentId}/edit`

package/integrations/google-docs/schemas/{get_document_text.json → read_document.json}

@@ -1,9 +1,12 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "type": "object",
+  "required": ["documentId"],
   "properties": {
-    "documentId": { "type": "string" }
+    "documentId": {
+      "type": "string",
+      "description": "Google Doc documentId from URL: https://docs.google.com/document/d/{documentId}/edit"
+    }
   },
-  "required": ["documentId"],
   "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/__tests__/handlers.test.ts

@@ -65,6 +65,25 @@ suiteOrSkip('google-drive handlers (live)', () => {
         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)
@@ -74,6 +93,30 @@ suiteOrSkip('google-drive handlers (live)', () => {
         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)

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/handlers/get_file.js

@@ -1,7 +1,5 @@
 async (input) => {
-  const res = await integration.fetch(`/files/${encodeURIComponent(input.fileId)}?fields=id,name,mimeType,parents,trashed`, {
-    method: 'GET',
-  })
+  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.`,
+  }
+}