Fize/workspace-kit

Google Docs (Habilidade de Documento na Nuvem)

Acesse a API do Google Docs com autenticação OAuth gerenciada via Maton. Crie, leia, atualize, formate e edite em lote documentos do Google Docs na nuvem.

⚠️ Distinção de Escopo: Nuvem vs. Arquivo Local:

• google-docs (Esta Habilidade): Exclusivamente para documentos online do Google Docs na nuvem (docs.google.com/document/d/{documentId}). Interage diretamente com os servidores na nuvem do Google através do proxy da API OAuth Maton.
• Habilidade docx: Para ler, criar ou editar arquivos .docx / .doc locais armazenados no disco local.

---

Início Rápido

CLI:

# Obter estrutura e conteúdo de texto do documento
maton google-docs document get <documentId>

# Criar um novo Google Doc
maton google-docs document create --title 'Especificação da Arquitetura do Projeto'

# Adicionar texto ao final do documento
maton google-docs document write <documentId> --text 'Anotações da reunião: discussão sobre o roadmap do Q3.'

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-docs/v1/documents/<documentId>')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

---

URL Base

https://api.maton.ai/google-docs/{caminho-da-api-nativa}

O Maton faz proxy das requisições para docs.googleapis.com e injeta automaticamente seu token OAuth.

---

Instalação da CLI (opcional — o agente decide)

A CLI Maton é opcional. O agente pode decidir instalá-la com base no ambiente.

macOS / Linux

curl -fsSL https://maton.ai/install.sh | bash

Windows

irm https://maton.ai/install.ps1 | iex

npm (multiplataforma)

npm install -g @maton/cli

Homebrew (macOS)

brew install maton-ai/cli/maton

Após a instalação, verifique com:

maton --version

---

Autenticação

CLI:

maton login                          # Abre o navegador para a chave da API
maton login --interactive            # Pula o navegador, cole a chave da API diretamente
maton whoami                         # Mostra o estado atual da autenticação

Manual:

1. Faça login ou crie uma conta em maton.ai
2. Vá para maton.ai/settings
3. Copie sua chave da API
4. Defina sua chave da API como MATON_API_KEY:

export MATON_API_KEY="SUA_CHAVE_DA_API"

---

Gerenciamento de Conexão

Gerencie suas conexões OAuth do Google Docs em https://api.maton.ai.

Listar Conexões

CLI:

maton connection list google-docs --status ACTIVE

maton api -X GET /connections -f app=google-docs -f status=ACTIVE

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=google-docs&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Criar Conexão

CLI:

maton connection create google-docs

maton api /connections -f app=google-docs

Python:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-docs'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Resposta:

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "google-docs"
  }
}

Abra a url retornada em um navegador para concluir a autorização OAuth.

Obter Conexão

CLI:

maton connection get {connection_id}                 # alias: maton connection view

maton api /connections/{connection_id}

Excluir Conexão

CLI:

maton connection delete {connection_id} --yes

maton api -X DELETE /connections/{connection_id}

Especificando Conexão

Se você tiver várias conexões do Google Docs, especifique qual usar:

CLI:

maton google-docs document get <documentId> --connection {connection_id}

maton api /google-docs/v1/documents/<documentId> --connection {connection_id}

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-docs/v1/documents/<documentId>')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Se você tiver várias conexões, sempre especifique a conexão para garantir que as requisições sejam enviadas para a conta correta.

---

Segurança e Permissões

• O acesso é limitado ao Google Docs dentro da conta Google conectada.
• Todas as operações de escrita e exclusão exigem aprovação explícita do usuário. Confirme o ID do recurso de destino e as modificações de conteúdo com o usuário antes de executar.

---

Referência da API

1. Obter Documento

Recupera o objeto completo do documento, incluindo título, elementos estruturais, objetos inline e formatação de parágrafos.

GET /google-docs/v1/documents/{documentId}

Parâmetros de Consulta:

• suggestionsViewMode - DEFAULT_FOR_CURRENT_ACCESS, PREVIEW_APPROVED, PREVIEW_WITHOUT_SUGGESTIONS, SUGGESTIONS_INLINE.

Exemplo CLI:

maton google-docs document get <documentId>
maton google-docs document get <documentId> --json

---

2. Criar Documento em Branco

Cria um novo Google Doc vazio com um título especificado.

POST /google-docs/v1/documents
Content-Type: application/json

{
  "title": "Revisão Técnica Trimestral"
}

Exemplo CLI:

maton google-docs document create --title 'Revisão Técnica Trimestral'

---

3. Adicionar Texto Simples ao Documento

Adiciona texto simples ao final do corpo do documento via CLI.

Exemplo CLI:

# Texto direto
maton google-docs document write <documentId> --text 'Olá, mundo!'

# Ler de um arquivo
maton google-docs document write <documentId> -F notas.md

# Pipe do stdin
 echo 'Resumo enviado por pipe' | maton google-docs document write <documentId> -F -

---

4. Atualização em Lote do Conteúdo e Estrutura do Documento (Formatação Rica)

Executa mutações atômicas no texto, formatação, estilos de parágrafo, cabeçalhos/rodapés e tabelas inline do documento.

POST /google-docs/v1/documents/{documentId}:batchUpdate
Content-Type: application/json

{
  "requests": [
    {
      "insertText": {
        "location": {
          "index": 1
        },
        "text": "Sumário Executivo\n\nEste documento descreve nossa estratégia de migração para a nuvem."
      }
    }
  ]
}

Exemplo CLI:

maton api -X POST /google-docs/v1/documents/<documentId>:batchUpdate \
  -d '{"requests":[{"insertText":{"location":{"index":1},"text":"Olá Mundo\n"}}]}'

Tipos de Solicitação Comuns para batchUpdate:

1. insertText: Insere texto em um local de índice específico.
2. deleteContentRange: Exclui conteúdo dentro de um range especificado (startIndex e endIndex).
3. replaceAllText: Substituição global de texto no corpo do documento.

   {
     "replaceAllText": {
       "containsText": {
         "text": "{{NOME_DO_PROJETO}}",
         "matchCase": true
       },
       "replaceText": "SoloQueue v2.0"
     }
   }
   

4. updateTextStyle: Aplica formatação negrito, itálico, tamanho da fonte ou cor a um intervalo.
5. updateParagraphStyle: Aplica estilos de cabeçalho (HEADING_1, HEADING_2, NORMAL_TEXT).

---

Extraindo Texto Simples da Estrutura do Documento

A API do Google Docs retorna o conteúdo dentro de body.content como elementos estruturais. Para ler o texto simples de um documento via Python:

import os, json, urllib.request

req = urllib.request.Request('https://api.maton.ai/google-docs/v1/documents/<documentId>')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
doc = json.load(urllib.request.urlopen(req))

text_chunks = []
for element in doc.get('body', {}).get('content', []):
    if 'paragraph' in element:
        for elem in element['paragraph'].get('elements', []):
            if 'textRun' in elem:
                text_chunks.append(elem['textRun'].get('content', ''))

print("".join(text_chunks))

---

Exemplos de Código

CLI

# Criar um documento
maton google-docs document create --title 'Planejamento da Sprint'

# Escrever anotações iniciais no documento
maton google-docs document write <documentId> --text 'Metas da Sprint 42:\n- Lançar Auth\n- Testes de velocidade'

# Inspecionar a estrutura do documento em JSON
maton google-docs document get <documentId> --json

JavaScript

// Obter metadados e conteúdo do documento
const response = await fetch(
  'https://api.maton.ai/google-docs/v1/documents/<documentId>',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const doc = await response.json();
console.log(doc.title);

// Criar um novo documento
const createResponse = await fetch(
  'https://api.maton.ai/google-docs/v1/documents',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'RFC: Gateway de Habilidades de IA'
    })
  }
);
const newDoc = await createResponse.json();
console.log('ID do documento criado:', newDoc.documentId);

Python

import os
import requests

# Obter documento
response = requests.get(
    'https://api.maton.ai/google-docs/v1/documents/<documentId>',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
doc = response.json()
print(doc.get('title'))

# Criar documento
create_response = requests.post(
    'https://api.maton.ai/google-docs/v1/documents',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={'title': 'RFC: Gateway de Habilidades de IA'}
)
print('Criado:', create_response.json().get('documentId'))

---

Notas

• IDs de documentos são strings opacas (extraídas da URL https://docs.google.com/document/d/<documentId>/edit).
• maton google-docs document write anexa texto simples ao final do corpo do documento. Para inserir texto em índices específicos, substituir texto ou aplicar estilos de cabeçalho/negrito, use batchUpdate.
• IMPORTANTE: Ao usar comandos curl, use curl -g quando as URLs contiverem colchetes para desabilitar a análise de glob.
• IMPORTANTE: Ao direcionar a saída do curl para jq ou outros comandos, variáveis de ambiente como $MATON_API_KEY podem não se expandir corretamente em alguns ambientes de shell. Você pode receber erros "Chave de API inválida" ao fazer pipe.

---

Tratamento de Erros

Status	Significado
400	Conexão do Google Docs ausente ou payload da requisição malformado
401	Chave da API Maton inválida ou ausente
404	ID do Google Doc não encontrado ou acesso negado
429	Limite de taxa excedido
5xx	Erro do backend da API do Google Docs

Solução de Problemas: Problemas com Chave da API

CLI:

maton whoami
maton connection list google-docs

Manual:

echo $MATON_API_KEY
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Solução de Problemas: Nome do Aplicativo Inválido

1. Certifique-se de que seu caminho de URL comece com google-docs. Por exemplo:

• Correto: https://api.maton.ai/google-docs/v1/documents/<documentId>
• Incorreto: https://api.maton.ai/docs/v1/documents/<documentId>

---

Recursos

• Documentação da API REST do Google Docs v1
• Referência de Atualização em Lote do Google Docs
• Manual da CLI Maton para Google Docs
• Comunidade Maton
• Suporte Maton