@commandable/integration-data 0.0.4 → 0.0.6

package/integrations/google-calendar/handlers/list_events.js

@@ -14,6 +14,8 @@ async (input) => {
     params.set('singleEvents', String(input.singleEvents))
   if (input.orderBy)
     params.set('orderBy', input.orderBy)
+  if (input.fields)
+    params.set('fields', input.fields)
   const qs = params.toString()
   const path = `/calendars/${encodeURIComponent(input.calendarId)}/events${qs ? `?${qs}` : ''}`
   const res = await integration.fetch(path)

package/integrations/google-calendar/manifest.json

@@ -2,25 +2,24 @@
   "name": "google-calendar",
   "version": "0.1.0",
   "tools": [
-    { "name": "list_calendars", "description": "List calendars for the authenticated user.", "inputSchema": "schemas/empty.json", "handler": "handlers/list_calendars.js", "scope": "read" },
-    { "name": "get_calendar", "description": "Get a calendar by ID.", "inputSchema": "schemas/id_calendar.json", "handler": "handlers/get_calendar.js", "scope": "read" },
-    { "name": "list_events", "description": "List events in a calendar with optional time range and query.", "inputSchema": "schemas/list_events.json", "handler": "handlers/list_events.js", "scope": "read" },
-    { "name": "get_event", "description": "Get a specific event by ID from a calendar.", "inputSchema": "schemas/id_calendar_event.json", "handler": "handlers/get_event.js", "scope": "read" },
-    { "name": "list_colors", "description": "Get the color definitions for calendars and events.", "inputSchema": "schemas/empty.json", "handler": "handlers/list_colors.js", "scope": "read" },
-    { "name": "freebusy_query", "description": "Query free/busy information for calendars.", "inputSchema": "schemas/freebusy_query.json", "handler": "handlers/freebusy_query.js", "scope": "read" },
-    { "name": "list_settings", "description": "List user settings.", "inputSchema": "schemas/empty.json", "handler": "handlers/list_settings.js", "scope": "read" },
+    { "name": "list_calendars", "description": "List all calendars in the authenticated user's calendar list, including the primary calendar and any subscribed or shared calendars. Returns calendar IDs needed for list_events, create_event, and other calendar-specific tools. The primary calendar has calendarId='primary'.", "inputSchema": "schemas/empty.json", "handler": "handlers/list_calendars.js", "scope": "read" },
+    { "name": "get_calendar", "description": "Get details for a specific calendar by ID, including its summary, description, timezone, and access role. Use list_calendars to find calendar IDs.", "inputSchema": "schemas/id_calendar.json", "handler": "handlers/get_calendar.js", "scope": "read" },
+    { "name": "list_events", "description": "List events in a calendar with optional time range, text search, and pagination. Use calendarId='primary' for the user's main calendar. Set singleEvents=true and orderBy='startTime' to get recurring events expanded into individual instances in chronological order. Times must be RFC3339 format (e.g. '2024-01-15T09:00:00Z' or '2024-01-15T09:00:00-05:00'). Defaults to 25 results. Use pageToken from the response for the next page.", "inputSchema": "schemas/list_events.json", "handler": "handlers/list_events.js", "scope": "read" },
+    { "name": "get_event", "description": "Get a specific event by its ID from a calendar. Returns full event details including summary, start, end, attendees, location, description, recurrence, and status. Use list_events to find event IDs.", "inputSchema": "schemas/id_calendar_event.json", "handler": "handlers/get_event.js", "scope": "read" },
+    { "name": "list_colors", "description": "Get the set of color definitions available for calendars and events. Returns colorId values and their hex codes. Use colorId values in create_event or patch_event to color-code events.", "inputSchema": "schemas/empty.json", "handler": "handlers/list_colors.js", "scope": "read" },
+    { "name": "freebusy_query", "description": "Query free/busy availability for one or more calendars within a time range. Useful for finding open slots or checking if attendees are available. Provide timeMin, timeMax (RFC3339), and an items array of calendar IDs. Returns busy time blocks for each calendar.", "inputSchema": "schemas/freebusy_query.json", "handler": "handlers/freebusy_query.js", "scope": "read" },
+    { "name": "list_settings", "description": "List the authenticated user's Google Calendar settings, such as timezone, date format, and notification preferences.", "inputSchema": "schemas/empty.json", "handler": "handlers/list_settings.js", "scope": "read" },
 
-    { "name": "create_event", "description": "Create an event in a calendar.", "inputSchema": "schemas/create_event.json", "handler": "handlers/create_event.js", "scope": "write" },
-    { "name": "update_event", "description": "Update an event in a calendar (full update).", "inputSchema": "schemas/update_event.json", "handler": "handlers/update_event.js", "scope": "write" },
-    { "name": "patch_event", "description": "Patch fields on an event in a calendar.", "inputSchema": "schemas/patch_event.json", "handler": "handlers/patch_event.js", "scope": "write" },
-    { "name": "delete_event", "description": "Delete an event from a calendar.", "inputSchema": "schemas/id_calendar_event.json", "handler": "handlers/delete_event.js", "scope": "write" },
-    { "name": "move_event", "description": "Move an event to another calendar.", "inputSchema": "schemas/move_event.json", "handler": "handlers/move_event.js", "scope": "write" },
-    { "name": "quick_add", "description": "Create an event using natural language text.", "inputSchema": "schemas/quick_add.json", "handler": "handlers/quick_add.js", "scope": "write" },
+    { "name": "create_event", "description": "Create a new event in a calendar. Required fields: calendarId, summary, start, end. Use {dateTime, timeZone} for timed events (e.g. {\"dateTime\": \"2024-01-15T10:00:00\", \"timeZone\": \"America/New_York\"}) or {date} for all-day events (e.g. {\"date\": \"2024-01-15\"}). Optional fields: description, location, attendees (array of {email}), recurrence (RRULE strings), reminders, colorId, visibility. The calendarId field is extracted automatically; all other fields are sent as the event body.", "inputSchema": "schemas/create_event.json", "handler": "handlers/create_event.js", "scope": "write" },
+    { "name": "patch_event", "description": "Partially update an event by providing only the fields to change. All other fields are preserved. Use this as the standard event update method. Provide changes in a 'body' object along with calendarId and eventId.", "inputSchema": "schemas/patch_event.json", "handler": "handlers/patch_event.js", "scope": "write" },
+    { "name": "delete_event", "description": "Delete an event from a calendar. This permanently removes the event. For recurring events, this deletes only the specified instance. Use list_events to find event IDs.", "inputSchema": "schemas/id_calendar_event.json", "handler": "handlers/delete_event.js", "scope": "write" },
+    { "name": "move_event", "description": "Move an event from one calendar to another. Provide the source calendarId, eventId, and the destination calendarId. Returns the updated event in the destination calendar.", "inputSchema": "schemas/move_event.json", "handler": "handlers/move_event.js", "scope": "write" },
+    { "name": "quick_add", "description": "Create an event using a natural language text string. Parses the text to extract event details automatically. Examples: 'Meeting with Bob tomorrow at 3pm for 1 hour', 'Dentist appointment on Friday at 2pm', 'Weekly standup every Monday at 9am'. Requires calendarId (use 'primary') and text.", "inputSchema": "schemas/quick_add.json", "handler": "handlers/quick_add.js", "scope": "write" },
 
-    { "name": "list_acl", "description": "List ACL rules for a calendar.", "inputSchema": "schemas/id_calendar.json", "handler": "handlers/list_acl.js", "scope": "admin" },
-    { "name": "get_acl", "description": "Get a specific ACL rule by ID for a calendar.", "inputSchema": "schemas/get_acl.json", "handler": "handlers/get_acl.js", "scope": "admin" },
-    { "name": "insert_acl", "description": "Insert a new ACL rule for a calendar.", "inputSchema": "schemas/insert_acl.json", "handler": "handlers/insert_acl.js", "scope": "admin" },
-    { "name": "update_acl", "description": "Update an ACL rule for a calendar.", "inputSchema": "schemas/update_acl.json", "handler": "handlers/update_acl.js", "scope": "admin" },
-    { "name": "delete_acl", "description": "Delete an ACL rule from a calendar.", "inputSchema": "schemas/delete_acl.json", "handler": "handlers/delete_acl.js", "scope": "admin" }
+    { "name": "list_acl", "description": "List the Access Control List (ACL) rules for a calendar. Returns rules defining who has access and at what permission level (reader, writer, owner). Use get_calendar to find the calendarId.", "inputSchema": "schemas/id_calendar.json", "handler": "handlers/list_acl.js", "scope": "admin" },
+    { "name": "get_acl", "description": "Get a specific ACL rule by its rule ID for a calendar. Use list_acl to find rule IDs.", "inputSchema": "schemas/get_acl.json", "handler": "handlers/get_acl.js", "scope": "admin" },
+    { "name": "insert_acl", "description": "Add a new ACL rule to grant a user or group access to a calendar. Roles: 'reader' (view), 'writer' (view + edit events), 'owner' (full control). Scope must include type ('user', 'group', 'domain', or 'default') and optionally value (email or domain).", "inputSchema": "schemas/insert_acl.json", "handler": "handlers/insert_acl.js", "scope": "admin" },
+    { "name": "update_acl", "description": "Update an existing ACL rule to change a user's or group's permission level on a calendar. Use list_acl to find the rule ID.", "inputSchema": "schemas/update_acl.json", "handler": "handlers/update_acl.js", "scope": "admin" },
+    { "name": "delete_acl", "description": "Remove an ACL rule from a calendar, revoking the associated user's or group's access. Use list_acl to find the rule ID.", "inputSchema": "schemas/delete_acl.json", "handler": "handlers/delete_acl.js", "scope": "admin" }
   ]
 }

package/integrations/google-calendar/prompt.md

@@ -0,0 +1,68 @@
+## Calendar IDs
+
+- Use `calendarId='primary'` for the authenticated user's main calendar
+- Use `list_calendars` to discover other calendar IDs (work, shared, subscribed calendars)
+- Calendar IDs typically look like email addresses (e.g. `user@example.com`) or opaque strings for subscribed calendars
+
+## Date and time format
+
+All times must be in RFC3339 format:
+- Timed events: `'2024-01-15T10:00:00-05:00'` (with timezone offset) or `'2024-01-15T15:00:00Z'` (UTC)
+- All-day events use date-only format: `'2024-01-15'`
+
+## Creating events
+
+For `create_event`, required fields are `calendarId`, `summary`, `start`, and `end`:
+
+**Timed event:**
+```json
+{
+  "calendarId": "primary",
+  "summary": "Team Meeting",
+  "start": { "dateTime": "2024-01-15T10:00:00", "timeZone": "America/New_York" },
+  "end":   { "dateTime": "2024-01-15T11:00:00", "timeZone": "America/New_York" }
+}
+```
+
+**All-day event:**
+```json
+{
+  "calendarId": "primary",
+  "summary": "Company Holiday",
+  "start": { "date": "2024-01-15" },
+  "end":   { "date": "2024-01-16" }
+}
+```
+
+Note: For all-day events, `end.date` should be the day *after* the last day (exclusive end).
+
+## Listing events in chronological order
+
+To list upcoming events in start-time order (e.g. "what's on my calendar this week"):
+- Set `singleEvents=true` to expand recurring events into individual instances
+- Set `orderBy='startTime'` (requires `singleEvents=true`)
+- Set `timeMin` to now (current ISO timestamp) and `timeMax` to the end of the desired range
+
+## Quick add
+
+`quick_add` parses natural language:
+- `"Meeting with Bob tomorrow at 3pm for 1 hour"`
+- `"Dentist appointment on Friday at 2pm"`
+- `"Weekly standup every Monday at 9am"`
+
+## Free/busy queries
+
+Use `freebusy_query` to check availability before scheduling:
+```json
+{
+  "timeMin": "2024-01-15T00:00:00Z",
+  "timeMax": "2024-01-15T23:59:59Z",
+  "items": [{ "id": "primary" }, { "id": "colleague@example.com" }]
+}
+```
+
+## Updating events
+
+- Use `update_event` for a full replacement (all fields must be provided)
+- Use `patch_event` for partial updates (only provide the fields you want to change in `body`)
+- `patch_event` is preferred when modifying one or two fields to avoid accidentally clearing others

package/integrations/google-calendar/schemas/id_calendar_event.json

@@ -1,8 +1,10 @@
 {
+  "$schema": "http://json-schema.org/draft-07/schema#",
   "type": "object",
   "properties": {
-    "calendarId": { "type": "string", "description": "Calendar ID (use 'primary' for primary)." },
-    "eventId": { "type": "string", "description": "Event ID." }
+    "calendarId": { "type": "string", "description": "Calendar ID. Use 'primary' for the user's main calendar." },
+    "eventId": { "type": "string", "description": "Event ID. Obtained from list_events results." },
+    "fields": { "type": "string", "description": "Partial response fields selector to reduce response size. Example: 'id,summary,start,end,attendees'." }
   },
   "required": ["calendarId", "eventId"],
   "additionalProperties": false

package/integrations/google-calendar/schemas/list_events.json

@@ -1,14 +1,16 @@
 {
+  "$schema": "http://json-schema.org/draft-07/schema#",
   "type": "object",
   "properties": {
-    "calendarId": { "type": "string", "description": "Calendar ID (use 'primary' for primary)." },
-    "timeMin": { "type": "string", "description": "RFC3339 start time" },
-    "timeMax": { "type": "string", "description": "RFC3339 end time" },
-    "q": { "type": "string", "description": "Free-text search query" },
-    "maxResults": { "type": "integer", "minimum": 1, "maximum": 2500 },
-    "pageToken": { "type": "string" },
-    "singleEvents": { "type": "boolean", "description": "Expand recurring events" },
-    "orderBy": { "type": "string", "enum": ["startTime", "updated"] }
+    "calendarId": { "type": "string", "description": "Calendar ID. Use 'primary' for the user's main calendar. Find other calendar IDs via list_calendars." },
+    "timeMin": { "type": "string", "description": "Start of the time range (RFC3339 format, e.g. '2024-01-15T00:00:00Z' or '2024-01-15T09:00:00-05:00'). Only events ending after this time are returned." },
+    "timeMax": { "type": "string", "description": "End of the time range (RFC3339 format). Only events starting before this time are returned." },
+    "q": { "type": "string", "description": "Free-text search query matching event summary, description, location, and attendee details." },
+    "maxResults": { "type": "integer", "minimum": 1, "maximum": 2500, "default": 25, "description": "Maximum number of events to return. Defaults to 25. Use pageToken from the response for the next page." },
+    "pageToken": { "type": "string", "description": "Page token from a previous list_events response to retrieve the next page of results." },
+    "singleEvents": { "type": "boolean", "description": "Expand recurring events into individual instances. Set to true with orderBy='startTime' to get events in chronological order." },
+    "orderBy": { "type": "string", "enum": ["startTime", "updated"], "description": "Sort order. 'startTime' requires singleEvents=true. 'updated' sorts by last modification time." },
+    "fields": { "type": "string", "description": "Partial response fields selector to reduce response size. Example: 'items(id,summary,start,end,attendees)'. See Calendar API fields reference." }
   },
   "required": ["calendarId"],
   "additionalProperties": false

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

@@ -16,7 +16,7 @@ interface VariantConfig {
 const variants: VariantConfig[] = [
   {
     key: 'service_account',
-    credentials: () => ({ serviceAccountJson: env.GOOGLE_SERVICE_ACCOUNT_JSON || '' }),
+    credentials: () => ({ serviceAccountJson: env.GOOGLE_SERVICE_ACCOUNT_JSON || '', subject: env.GOOGLE_IMPERSONATE_SUBJECT || '' }),
   },
   {
     key: 'oauth_token',
@@ -70,28 +70,13 @@ suiteOrSkip('google-docs read handlers (live)', () => {
         await safeCleanup(async () => drive.write('delete_file')({ fileId: folderId }))
       }, 60000)
 
-      it('get_document returns metadata/content', async () => {
+      it('read_document returns markdown content', async () => {
         if (!documentId)
           return expect(true).toBe(true)
-        const handler = docs.read('get_document')
+        const handler = docs.read('read_document')
         const result = await handler({ documentId })
-        expect(result?.documentId || result?.body?.content || result?.title).toBeTruthy()
-      }, 30000)
-
-      it('get_document_text returns plain text', async () => {
-        if (!documentId)
-          return expect(true).toBe(true)
-        const handler = docs.read('get_document_text')
-        const result = await handler({ documentId })
-        expect(typeof result?.text === 'string').toBe(true)
-      }, 30000)
-
-      it('get_document_structured returns body JSON', async () => {
-        if (!documentId)
-          return expect(true).toBe(true)
-        const handler = docs.read('get_document_structured')
-        const result = await handler({ documentId })
-        expect(result?.body || result?.documentId).toBeTruthy()
+        expect(result?.documentId || result?.title).toBeTruthy()
+        expect(typeof result?.markdown).toBe('string')
       }, 30000)
     })
   }

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

@@ -16,7 +16,7 @@ interface VariantConfig {
 const variants: VariantConfig[] = [
   {
     key: 'service_account',
-    credentials: () => ({ serviceAccountJson: env.GOOGLE_SERVICE_ACCOUNT_JSON || '' }),
+    credentials: () => ({ serviceAccountJson: env.GOOGLE_SERVICE_ACCOUNT_JSON || '', subject: env.GOOGLE_IMPERSONATE_SUBJECT || '' }),
   },
   {
     key: 'oauth_token',
@@ -49,7 +49,9 @@ suiteOrSkip('google-docs write handlers (live)', () => {
           variant.key,
         )
 
-        const folder = await drive.write('create_folder')({ name: `CmdTest Docs Write ${Date.now()}` })
+        const folder = await drive.write('create_folder')({
+          name: `CmdTest Docs Write ${Date.now()}`,
+        })
         ctx.folderId = folder?.id
         expect(ctx.folderId).toBeTruthy()
 
@@ -86,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 () => {
@@ -96,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 () => {
@@ -125,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()
@@ -140,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)
 
@@ -158,31 +160,29 @@ 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 () => {
-        if (!ctx.documentId || !process.env.GDOCS_TEST_IMAGE_URI)
+        if (!ctx.documentId)
           return expect(true).toBe(true)
         const documentId = ctx.documentId
+        const imageUri = 'https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png'
         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: process.env.GDOCS_TEST_IMAGE_URI!, altText: 'CmdTest' })
+        const res = await insert_inline_image_after_first_match({ documentId, findText: anchor, uri: imageUri })
         expect(res?.applied === true || Array.isArray(res?.replies)).toBeTruthy()
       }, 60000)
 
@@ -191,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 () => {
@@ -208,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/insert_inline_image_after_first_match.js

@@ -34,7 +34,7 @@ async (input) => {
     return { ok: true }
 
   const requests = []
-  requests.push({ insertInlineImage: { location: { index: baseIndex }, uri, altTextTitle: altText } })
+  requests.push({ insertInlineImage: { location: { index: baseIndex }, uri } })
   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/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),
+  }
+}