@commandable/integration-data 0.0.1

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

@@ -0,0 +1,72 @@
+import { beforeAll, describe, expect, it } from 'vitest'
+import { IntegrationProxy } from '../../../src/integrations/proxy.js'
+import { loadIntegrationTools } from '../../../src/integrations/dataLoader.js'
+
+// LIVE Google Docs read tests using managed OAuth
+// Required env vars:
+// - COMMANDABLE_MANAGED_OAUTH_BASE_URL
+// - COMMANDABLE_MANAGED_OAUTH_SECRET_KEY
+// - GDOCS_TEST_CONNECTION_ID (managed OAuth connection for provider 'google-docs')
+// - GDOCS_TEST_DOCUMENT_ID (an accessible document ID)
+
+const env = process.env as Record<string, string>
+const hasEnv = (...keys: string[]) => keys.every(k => !!env[k] && env[k].trim().length > 0)
+const suite = hasEnv(
+  'COMMANDABLE_MANAGED_OAUTH_BASE_URL',
+  'COMMANDABLE_MANAGED_OAUTH_SECRET_KEY',
+  'GDOCS_TEST_CONNECTION_ID',
+)
+  ? describe
+  : describe.skip
+
+suite('google-docs read handlers (live)', () => {
+  let buildReadHandler: (name: string) => ((input: any) => Promise<any>)
+
+  beforeAll(async () => {
+    const { COMMANDABLE_MANAGED_OAUTH_BASE_URL, COMMANDABLE_MANAGED_OAUTH_SECRET_KEY, GDOCS_TEST_CONNECTION_ID } = env
+
+    const proxy = new IntegrationProxy({
+      managedOAuthBaseUrl: COMMANDABLE_MANAGED_OAUTH_BASE_URL,
+      managedOAuthSecretKey: COMMANDABLE_MANAGED_OAUTH_SECRET_KEY,
+    })
+    const integrationNode = { id: 'node-gdocs', type: 'google-docs', label: 'Google Docs', connectionId: GDOCS_TEST_CONNECTION_ID } as any
+
+    const tools = loadIntegrationTools('google-docs')
+    expect(tools).toBeTruthy()
+
+    buildReadHandler = (name: string) => {
+      const tool = tools!.read.find(t => t.name === name)
+      expect(tool, `read tool ${name} exists`).toBeTruthy()
+      const integration = { fetch: (path: string, init?: RequestInit) => proxy.call(integrationNode, path, init) }
+      const build = new Function('integration', `return (${tool!.handlerCode});`)
+      return build(integration) as (input: any) => Promise<any>
+    }
+  }, 60000)
+
+  it('get_document returns metadata/content', async () => {
+    const documentId = env.GDOCS_TEST_DOCUMENT_ID
+    if (!documentId)
+      return expect(true).toBe(true)
+    const handler = buildReadHandler('get_document')
+    const result = await handler({ documentId })
+    expect(result?.documentId || result?.body?.content || result?.title).toBeTruthy()
+  }, 30000)
+
+  it('get_document_text returns plain text', async () => {
+    const documentId = env.GDOCS_TEST_DOCUMENT_ID
+    if (!documentId)
+      return expect(true).toBe(true)
+    const handler = buildReadHandler('get_document_text')
+    const result = await handler({ documentId })
+    expect(typeof result?.text === 'string').toBe(true)
+  }, 30000)
+
+  it('get_document_structured returns body JSON', async () => {
+    const documentId = env.GDOCS_TEST_DOCUMENT_ID
+    if (!documentId)
+      return expect(true).toBe(true)
+    const handler = buildReadHandler('get_document_structured')
+    const result = await handler({ documentId })
+    expect(result?.body || result?.documentId).toBeTruthy()
+  }, 30000)
+})

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

@@ -0,0 +1,34 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { loadIntegrationManifest } from '../../../src/integrations/dataLoader.js'
+
+function escapeRegExp(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+describe('google-docs static usage parity', () => {
+  it('every manifest tool is referenced in tests via build*(name)', () => {
+    const manifest = loadIntegrationManifest('google-docs')!
+    const toolNames = (manifest.tools as any[]).map(t => t.name)
+
+    const testsDir = fileURLToPath(new URL('.', import.meta.url))
+    expect(existsSync(testsDir)).toBe(true)
+    const testFiles = readdirSync(testsDir)
+      .filter(f => /\.test\.(t|j)s$/.test(f) && !f.includes('usage_parity.test'))
+      .map(f => resolve(testsDir, f))
+
+    const fileContents = testFiles.map(f => readFileSync(f, 'utf8'))
+
+    const missing: string[] = []
+    for (const name of toolNames) {
+      const nameRe = new RegExp(`build(?:Read|Write|Admin)?(?:Handler)?\\(\\s*['\"\`]${escapeRegExp(name)}['\"\`]\\s*\\)`, 'm')
+      const found = fileContents.some(src => nameRe.test(src))
+      if (!found)
+        missing.push(name)
+    }
+
+    expect(missing, `Missing handler usages in tests: ${missing.join(', ')}`).toEqual([])
+  })
+})

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

@@ -0,0 +1,249 @@
+import { beforeAll, describe, expect, it } from 'vitest'
+import { IntegrationProxy } from '../../../src/integrations/proxy.js'
+import { loadIntegrationTools } from '../../../src/integrations/dataLoader.js'
+
+// LIVE Google Docs write tests using managed OAuth
+// Required env vars:
+// - COMMANDABLE_MANAGED_OAUTH_BASE_URL
+// - COMMANDABLE_MANAGED_OAUTH_SECRET_KEY
+// - GDOCS_TEST_CONNECTION_ID (managed OAuth connection for provider 'google-docs')
+// - GDOCS_TEST_DOCUMENT_ID (target document ID with write access) OR GDOCS_ALLOW_CREATE to create
+
+interface Ctx {
+  documentId?: string
+}
+
+const env = process.env as Record<string, string>
+const hasEnv = (...keys: string[]) => keys.every(k => !!env[k] && env[k].trim().length > 0)
+const suite = hasEnv(
+  'COMMANDABLE_MANAGED_OAUTH_BASE_URL',
+  'COMMANDABLE_MANAGED_OAUTH_SECRET_KEY',
+  'GDOCS_TEST_CONNECTION_ID',
+)
+  ? describe
+  : describe.skip
+
+suite('google-docs write handlers (live)', () => {
+  const ctx: Ctx = {}
+  let buildWriteHandler: (name: string) => ((input: any) => Promise<any>)
+  let buildReadHandler: (name: string) => ((input: any) => Promise<any>)
+
+  beforeAll(async () => {
+    const { COMMANDABLE_MANAGED_OAUTH_BASE_URL, COMMANDABLE_MANAGED_OAUTH_SECRET_KEY, GDOCS_TEST_CONNECTION_ID, GDOCS_TEST_DOCUMENT_ID } = env
+
+    const proxy = new IntegrationProxy({
+      managedOAuthBaseUrl: COMMANDABLE_MANAGED_OAUTH_BASE_URL,
+      managedOAuthSecretKey: COMMANDABLE_MANAGED_OAUTH_SECRET_KEY,
+    })
+    const integrationNode = { id: 'node-gdocs', type: 'google-docs', label: 'Google Docs', connectionId: GDOCS_TEST_CONNECTION_ID } as any
+
+    const tools = loadIntegrationTools('google-docs')
+    expect(tools).toBeTruthy()
+
+    buildWriteHandler = (name: string) => {
+      const tool = tools!.write.find(t => t.name === name)
+      expect(tool, `write tool ${name} exists`).toBeTruthy()
+      const integration = { fetch: (path: string, init?: RequestInit) => proxy.call(integrationNode, path, init) }
+      const build = new Function('integration', `return (${tool!.handlerCode});`)
+      return build(integration) as (input: any) => Promise<any>
+    }
+
+    buildReadHandler = (name: string) => {
+      const tool = tools!.read.find(t => t.name === name)
+      expect(tool, `read tool ${name} exists`).toBeTruthy()
+      const integration = { fetch: (path: string, init?: RequestInit) => proxy.call(integrationNode, path, init) }
+      const build = new Function('integration', `return (${tool!.handlerCode});`)
+      return build(integration) as (input: any) => Promise<any>
+    }
+
+    ctx.documentId = GDOCS_TEST_DOCUMENT_ID
+  }, 60000)
+
+  it('create_document creates a document when allowed', async () => {
+    if (!process.env.GDOCS_ALLOW_CREATE)
+      return expect(true).toBe(true)
+    const create_document = buildWriteHandler('create_document')
+    const res = await create_document({ title: `CmdTest Doc ${Date.now()}` })
+    expect(res?.documentId).toBeTruthy()
+  }, 60000)
+
+  it('batch_update can perform a trivial replaceAllText no-op', async () => {
+    const documentId = process.env.GDOCS_TEST_DOCUMENT_ID
+    if (!documentId)
+      return expect(true).toBe(true)
+    const batch_update = buildWriteHandler('batch_update')
+    const res = await batch_update({ documentId, requests: [
+      { replaceAllText: { containsText: { text: '___unlikely___', matchCase: true }, replaceText: '___unlikely___' } },
+    ] })
+    expect(Array.isArray(res?.replies) || res?.documentId).toBeTruthy()
+  }, 60000)
+
+  it('append_text appends content', async () => {
+    const documentId = process.env.GDOCS_TEST_DOCUMENT_ID
+    if (!documentId)
+      return expect(true).toBe(true)
+    const append_text = buildWriteHandler('append_text')
+    const marker = `CmdTest ${Date.now()}`
+    const res = await append_text({ documentId, text: marker })
+    expect(res?.documentId || Array.isArray(res?.replies)).toBeTruthy()
+    const get_text = buildReadHandler('get_document_text')
+    const after = await get_text({ documentId })
+    expect(String(after?.text || '')).toContain(marker)
+  }, 60000)
+
+  it('insert_text_after_first_match inserts text near target', async () => {
+    const documentId = process.env.GDOCS_TEST_DOCUMENT_ID
+    if (!documentId)
+      return expect(true).toBe(true)
+    const insert_text_after_first_match = buildWriteHandler('insert_text_after_first_match')
+    const get_text = buildReadHandler('get_document_text')
+    const anchor = `ANCHOR_${Date.now()}`
+    const appended = buildWriteHandler('append_text')
+    const before = await get_text({ documentId })
+    if (!String(before?.text || '').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 || '')
+    expect(text).toContain(anchor)
+    expect(text).toContain(insertSnippet)
+  }, 60000)
+
+  it('replace_all_text replaces occurrences', async () => {
+    const documentId = process.env.GDOCS_TEST_DOCUMENT_ID
+    if (!documentId)
+      return expect(true).toBe(true)
+    const replace_all_text = buildWriteHandler('replace_all_text')
+    const res = await replace_all_text({ documentId, findText: '___unlikely___', replaceText: '___unlikely___', matchCase: true })
+    expect(res?.documentId || Array.isArray(res?.replies)).toBeTruthy()
+  }, 60000)
+
+  it('style_first_match applies style to first match', async () => {
+    const documentId = process.env.GDOCS_TEST_DOCUMENT_ID
+    if (!documentId)
+      return expect(true).toBe(true)
+    const style_first_match = buildWriteHandler('style_first_match')
+    const get_struct = buildReadHandler('get_document_structured')
+    const anchor = `ANCHOR_${Date.now()}`
+    const appended = buildWriteHandler('append_text')
+    const before = await get_struct({ documentId })
+    const hasAnchorBefore = JSON.stringify(before?.body || {}).includes(anchor)
+    if (!hasAnchorBefore)
+      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()
+  }, 60000)
+
+  it('insert_table_after_first_match inserts a table near target', async () => {
+    const documentId = process.env.GDOCS_TEST_DOCUMENT_ID
+    if (!documentId)
+      return expect(true).toBe(true)
+    const insert_table_after_first_match = buildWriteHandler('insert_table_after_first_match')
+    const get_struct = buildReadHandler('get_document_structured')
+    const anchor = `ANCHOR_${Date.now()}`
+    const appended = buildWriteHandler('append_text')
+    const before = await get_struct({ documentId })
+    const hasAnchorBefore = JSON.stringify(before?.body || {}).includes(anchor)
+    if (!hasAnchorBefore)
+      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))
+    expect(hasTable).toBe(true)
+  }, 60000)
+
+  it('insert_page_break_after_first_match inserts a break near target', async () => {
+    const documentId = process.env.GDOCS_TEST_DOCUMENT_ID
+    if (!documentId)
+      return expect(true).toBe(true)
+    const insert_page_break_after_first_match = buildWriteHandler('insert_page_break_after_first_match')
+    const get_struct = buildReadHandler('get_document_structured')
+    const anchor = `ANCHOR_${Date.now()}`
+    const appended = buildWriteHandler('append_text')
+    const before = await get_struct({ documentId })
+    const hasAnchorBefore = JSON.stringify(before?.body || {}).includes(anchor)
+    if (!hasAnchorBefore)
+      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 () => {
+    if (!process.env.GDOCS_TEST_DOCUMENT_ID || !process.env.GDOCS_TEST_IMAGE_URI)
+      return expect(true).toBe(true)
+    const documentId = process.env.GDOCS_TEST_DOCUMENT_ID
+    const insert_inline_image_after_first_match = buildWriteHandler('insert_inline_image_after_first_match')
+    const anchor = `ANCHOR_${Date.now()}`
+    const appended = buildWriteHandler('append_text')
+    const get_text = buildReadHandler('get_document_text')
+    const before = await get_text({ documentId })
+    if (!String(before?.text || '').includes(anchor))
+      await appended({ documentId, text: `\n${anchor}\n` })
+    const res = await insert_inline_image_after_first_match({ documentId, findText: anchor, uri: process.env.GDOCS_TEST_IMAGE_URI!, altText: 'CmdTest' })
+    expect(res?.applied === true || Array.isArray(res?.replies)).toBeTruthy()
+  }, 60000)
+
+  it('delete_first_match deletes a small span (no-op ok)', async () => {
+    const documentId = process.env.GDOCS_TEST_DOCUMENT_ID
+    if (!documentId)
+      return expect(true).toBe(true)
+    const delete_first_match = buildWriteHandler('delete_first_match')
+    const get_text = buildReadHandler('get_document_text')
+    const anchor = `ANCHOR_${Date.now()}`
+    const appended = buildWriteHandler('append_text')
+    const before = await get_text({ documentId })
+    if (!String(before?.text || '').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)
+  }, 60000)
+
+  it('update_paragraph_style_for_first_match updates paragraph style near target', async () => {
+    const documentId = process.env.GDOCS_TEST_DOCUMENT_ID
+    if (!documentId)
+      return expect(true).toBe(true)
+    const update_paragraph_style_for_first_match = buildWriteHandler('update_paragraph_style_for_first_match')
+    const get_struct = buildReadHandler('get_document_structured')
+    const anchor = `ANCHOR_${Date.now()}`
+    const appended = buildWriteHandler('append_text')
+    const before = await get_struct({ documentId })
+    const hasAnchorBefore = JSON.stringify(before?.body || {}).includes(anchor)
+    if (!hasAnchorBefore)
+      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 })
+    // find the paragraph containing anchor and verify alignment
+    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 () => {
+    const documentId = process.env.GDOCS_TEST_DOCUMENT_ID
+    if (!documentId)
+      return expect(true).toBe(true)
+    const update_document_style = buildWriteHandler('update_document_style')
+    const res = await update_document_style({ documentId, documentStyle: { useFirstPageHeaderFooter: false } })
+    expect(res?.documentId || Array.isArray(res?.replies)).toBeTruthy()
+  }, 60000)
+})

package/integrations/google-docs/credentials.json

@@ -0,0 +1,36 @@
+{
+  "schema": {
+    "type": "object",
+    "properties": {
+      "token": {
+        "type": "string",
+        "title": "OAuth Access Token (optional)",
+        "description": "Google OAuth access token to use as a Bearer token (typically short-lived)."
+      },
+      "serviceAccountJson": {
+        "type": "string",
+        "title": "Service Account JSON (recommended)",
+        "description": "Full service account key JSON (contents of the downloaded JSON file)."
+      },
+      "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.",
+        "items": { "type": "string" }
+      }
+    },
+    "required": [],
+    "additionalProperties": false
+  },
+  "injection": {
+    "headers": {
+      "Authorization": "Bearer {{token}}"
+    }
+  }
+}
+

package/integrations/google-docs/credentials_hint.md

@@ -0,0 +1,9 @@
+Recommended: use a Google service account.
+
+- Create a service account in Google Cloud
+- Download a JSON key
+- Paste the JSON into `serviceAccountJson` (or use `env:GOOGLE_SERVICE_ACCOUNT_JSON`)
+- Share your test document with the service account `client_email`
+
+You can also paste a short-lived OAuth access token into `token`, but it will expire.
+

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

@@ -0,0 +1,12 @@
+async (input) => {
+  const { documentId, text } = input
+  // Get doc to find end index
+  const metaRes = await integration.fetch(`/documents/${encodeURIComponent(documentId)}`)
+  const meta = await metaRes.json()
+  const endIndex = meta?.body?.content?.[meta.body.content.length - 1]?.endIndex || 1
+  const res = await integration.fetch(`/documents/${encodeURIComponent(documentId)}:batchUpdate`, {
+    method: 'POST',
+    body: { requests: [{ insertText: { text, location: { index: endIndex - 1 } } }] },
+  })
+  return await res.json()
+}

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

@@ -0,0 +1,13 @@
+async (input) => {
+  const { documentId, requests, writeControl, includeTabStops } = input
+  const params = new URLSearchParams()
+  if (includeTabStops !== undefined)
+    params.set('includeTabStops', String(includeTabStops))
+  const qs = params.toString()
+  const path = `/documents/${encodeURIComponent(documentId)}:batchUpdate${qs ? `?${qs}` : ''}`
+  const body = { requests }
+  if (writeControl)
+    body.writeControl = writeControl
+  const res = await integration.fetch(path, { method: 'POST', body })
+  return await res.json()
+}

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

@@ -0,0 +1,9 @@
+async (input) => {
+  const { title, ...rest } = input
+  const body = {}
+  if (title !== undefined)
+    body.title = title
+  Object.assign(body, rest)
+  const res = await integration.fetch(`/documents`, { method: 'POST', body })
+  return await res.json()
+}

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

@@ -0,0 +1,50 @@
+async (input) => {
+  const { documentId, findText } = input
+  const marker = `__CMD_MARK_${Date.now()}__`
+  const replaceRes = await integration.fetch(`/documents/${encodeURIComponent(documentId)}:batchUpdate`, {
+    method: 'POST',
+    body: { requests: [{ replaceAllText: { containsText: { text: findText, matchCase: false }, replaceText: marker } }] },
+  })
+  await replaceRes.json()
+
+  const getRes = await integration.fetch(`/documents/${encodeURIComponent(documentId)}`)
+  const doc = await getRes.json()
+  let startIndex = -1
+  let endIndex = -1
+  for (const el of (doc?.body?.content || [])) {
+    const p = el.paragraph
+    if (!p)
+      continue
+    for (const e of (p.elements || [])) {
+      const t = e?.textRun?.content
+      if (!t)
+        continue
+      const idx = t.indexOf(marker)
+      if (idx >= 0) {
+        const elStart = e.startIndex || 1
+        startIndex = elStart + idx
+        endIndex = startIndex + marker.length
+        break
+      }
+    }
+    if (startIndex >= 0)
+      break
+  }
+  if (startIndex < 0) {
+    const confirm = await integration.fetch(`/documents/${encodeURIComponent(documentId)}`)
+    const got = await confirm.json()
+    return { documentId: got?.documentId || documentId, applied: false, replies: [] }
+  }
+
+  const requests = []
+  requests.push({ deleteContentRange: { range: { startIndex, endIndex } } })
+  // also clean any remaining markers
+  requests.push({ replaceAllText: { containsText: { text: marker, matchCase: true }, replaceText: '' } })
+  const res = await integration.fetch(`/documents/${encodeURIComponent(documentId)}:batchUpdate`, { method: 'POST', body: { requests } })
+  const out = await res.json()
+  if (out?.documentId || Array.isArray(out?.replies))
+    return { ...out, applied: true }
+  const confirm = await integration.fetch(`/documents/${encodeURIComponent(documentId)}`)
+  const got = await confirm.json()
+  return { documentId: got?.documentId || documentId, applied: true, replies: Array.isArray(out?.replies) ? out.replies : [] }
+}

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

@@ -0,0 +1,12 @@
+async (input) => {
+  const { documentId, suggestionsViewMode, includeTabsAndSpaces } = input
+  const params = new URLSearchParams()
+  if (suggestionsViewMode)
+    params.set('suggestionsViewMode', String(suggestionsViewMode))
+  if (includeTabsAndSpaces !== undefined)
+    params.set('includeTabsAndSpaces', String(includeTabsAndSpaces))
+  const qs = params.toString()
+  const path = `/documents/${encodeURIComponent(documentId)}${qs ? `?${qs}` : ''}`
+  const res = await integration.fetch(path)
+  return await res.json()
+}

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

@@ -0,0 +1,6 @@
+async (input) => {
+  const { documentId } = input
+  const res = await integration.fetch(`/documents/${encodeURIComponent(documentId)}`)
+  const doc = await res.json()
+  return { documentId: doc?.documentId || documentId, body: doc?.body }
+}

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

@@ -0,0 +1,17 @@
+async (input) => {
+  const { documentId } = input
+  const res = await integration.fetch(`/documents/${encodeURIComponent(documentId)}`)
+  const doc = await res.json()
+  const content = doc?.body?.content || []
+  let text = ''
+  for (const el of content) {
+    const paragraphs = el.paragraph ? [el.paragraph] : []
+    for (const p of paragraphs) {
+      for (const e of p.elements || []) {
+        text += e.textRun?.content || ''
+      }
+      text += '\n'
+    }
+  }
+  return { documentId: doc?.documentId || documentId, text }
+}

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

@@ -0,0 +1,41 @@
+async (input) => {
+  const { documentId, findText, uri, altText, position } = input
+  const marker = `__CMD_MARK_${Date.now()}__`
+  const replaceRes = await integration.fetch(`/documents/${encodeURIComponent(documentId)}:batchUpdate`, {
+    method: 'POST',
+    body: { requests: [{ replaceAllText: { containsText: { text: findText, matchCase: false }, replaceText: marker } }] },
+  })
+  await replaceRes.json()
+
+  const getRes = await integration.fetch(`/documents/${encodeURIComponent(documentId)}`)
+  const doc = await getRes.json()
+  let baseIndex = -1
+  for (const el of (doc?.body?.content || [])) {
+    const p = el.paragraph
+    if (!p)
+      continue
+    for (const e of (p.elements || [])) {
+      const t = e?.textRun?.content
+      if (!t)
+        continue
+      const idx = t.indexOf(marker)
+      if (idx >= 0) {
+        const elStart = e.startIndex || 1
+        const startIndex = elStart + idx
+        const endIndex = startIndex + marker.length
+        baseIndex = position === 'before' ? startIndex : endIndex
+        break
+      }
+    }
+    if (baseIndex >= 0)
+      break
+  }
+  if (baseIndex < 0)
+    return { ok: true }
+
+  const requests = []
+  requests.push({ insertInlineImage: { location: { index: baseIndex }, uri, altTextTitle: altText } })
+  requests.push({ replaceAllText: { containsText: { text: marker, matchCase: true }, replaceText: findText } })
+  const res = await integration.fetch(`/documents/${encodeURIComponent(documentId)}:batchUpdate`, { method: 'POST', body: { requests } })
+  return await res.json()
+}

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

@@ -0,0 +1,49 @@
+async (input) => {
+  const { documentId, findText, position } = input
+  const marker = `__CMD_MARK_${Date.now()}__`
+  const replaceRes = await integration.fetch(`/documents/${encodeURIComponent(documentId)}:batchUpdate`, {
+    method: 'POST',
+    body: { requests: [{ replaceAllText: { containsText: { text: findText, matchCase: false }, replaceText: marker } }] },
+  })
+  await replaceRes.json()
+
+  const getRes = await integration.fetch(`/documents/${encodeURIComponent(documentId)}`)
+  const doc = await getRes.json()
+  let baseIndex = -1
+  for (const el of (doc?.body?.content || [])) {
+    const p = el.paragraph
+    if (!p)
+      continue
+    for (const e of (p.elements || [])) {
+      const t = e?.textRun?.content
+      if (!t)
+        continue
+      const idx = t.indexOf(marker)
+      if (idx >= 0) {
+        const elStart = e.startIndex || 1
+        const startIndex = elStart + idx
+        const endIndex = startIndex + marker.length
+        baseIndex = position === 'before' ? startIndex : endIndex
+        break
+      }
+    }
+    if (baseIndex >= 0)
+      break
+  }
+  if (baseIndex < 0) {
+    const confirm = await integration.fetch(`/documents/${encodeURIComponent(documentId)}`)
+    const got = await confirm.json()
+    return { documentId: got?.documentId || documentId, applied: false, replies: [] }
+  }
+
+  const requests = []
+  requests.push({ insertPageBreak: { location: { index: baseIndex } } })
+  requests.push({ replaceAllText: { containsText: { text: marker, matchCase: true }, replaceText: findText } })
+  const res = await integration.fetch(`/documents/${encodeURIComponent(documentId)}:batchUpdate`, { method: 'POST', body: { requests } })
+  const out = await res.json()
+  if (out?.documentId || Array.isArray(out?.replies))
+    return { ...out, applied: true }
+  const confirm = await integration.fetch(`/documents/${encodeURIComponent(documentId)}`)
+  const got = await confirm.json()
+  return { documentId: got?.documentId || documentId, applied: true, replies: Array.isArray(out?.replies) ? out.replies : [] }
+}