Скилл google-docs: создание и редактирование документов

--- name: google-docs description: | Google Docs API integration with managed OAuth. Create documents, insert text, apply formatting, and manage content. Use this skill when users want to interact with Google Docs. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). compatibility: Requires network access and valid Maton API key metadata: author: maton version: "1.0" clawdbot: emoji: 🧠 requires: env: - MATON_API_KEY --- # Google Docs Access the Google Docs API with managed OAuth authentication. Create documents, insert and format text, and manage document content. ## Quick Start ```bash # Get document python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.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 ``` ## Base URL ``` https://gateway.maton.ai/google-docs/{native-api-path} ``` Replace `{native-api-path}` with the actual Google Docs API endpoint path. The gateway proxies requests to `docs.googleapis.com` and automatically injects your OAuth token. ## Authentication All requests require the Maton API key in the Authorization header: ``` Authorization: Bearer $MATON_API_KEY ``` **Environment Variable:** Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## Connection Management Manage your Google OAuth connections at `https://ctrl.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.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 ``` ### Create Connection ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'google-docs'}).encode() req = urllib.request.Request('https://ctrl.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 ``` ### Get Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "google-docs", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple Google Docs connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-docs/v1/documents/{documentId}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If omitted, the gateway uses the default (oldest) active connection. ## API Reference ### Get Document ```bash GET /google-docs/v1/documents/{documentId} ``` ### Create Document ```bash POST /google-docs/v1/documents Content-Type: application/json { "title": "New Document" } ``` ### Batch Update Document ```bash POST /google-docs/v1/documents/{documentId}:batchUpdate Content-Type: application/json { "requests": [ { "insertText": { "location": {"index": 1}, "text": "Hello, World!" } } ] } ``` ## Common batchUpdate Requests ### Insert Text ```json { "insertText": { "location": {"index": 1}, "text": "Text to insert" } } ``` ### Delete Content ```json { "deleteContentRange": { "range": { "startIndex": 1, "endIndex": 10 } } } ``` ### Replace All Text ```json { "replaceAllText": { "containsText": { "text": "{{placeholder}}", "matchCase": true }, "replaceText": "replacement value" } } ``` ### Insert Table ```json { "insertTable": { "location": {"index": 1}, "rows": 3, "columns": 3 } } ``` ### Update Text Style ```json { "updateTextStyle": { "range": { "startIndex": 1, "endIndex": 10 }, "textStyle": { "bold": true, "fontSize": {"magnitude": 14, "unit": "PT"} }, "fields": "bold,fontSize" } } ``` ### Insert Page Break ```json { "insertPageBreak": { "location": {"index": 1} } } ``` ## Code Examples ### JavaScript ```javascript // Create document const response = await fetch( 'https://gateway.maton.ai/google-docs/v1/documents', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.MATON_API_KEY}` }, body: JSON.stringify({ title: 'New Document' }) } ); // Insert text await fetch( `https://gateway.maton.ai/google-docs/v1/documents/${docId}:batchUpdate`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.MATON_API_KEY}` }, body: JSON.stringify({ requests: [{ insertText: { location: { index: 1 }, text: 'Hello!' } }] }) } ); ``` ### Python ```python import os import requests # Create document response = requests.post( 'https://gateway.maton.ai/google-docs/v1/documents', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, json={'title': 'New Document'} ) ``` ## Notes - Index positions are 1-based (document starts at index 1) - Use `endOfSegmentLocation` to append at end - Multiple requests in batchUpdate are applied atomically - Get document first to find correct indices for updates - The `fields` parameter in style updates uses field mask syntax - IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets (`fields[]`, `sort[]`, `records[]`) to disable glob parsing - IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping. ## Error Handling | Status | Meaning | |--------|---------| | 400 | Missing Google Docs connection | | 401 | Invalid or missing Maton API key | | 429 | Rate limited (10 req/sec per account) | | 4xx/5xx | Passthrough error from Google Docs API | ### Troubleshooting: API Key Issues 1. Check that the `MATON_API_KEY` environment variable is set: ```bash echo $MATON_API_KEY ``` 2. Verify the API key is valid by listing connections: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.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 ``` ### Troubleshooting: Invalid App Name 1. Ensure your URL path starts with `google-docs`. For example: - Correct: `https://gateway.maton.ai/google-docs/v1/documents/{documentId}` - Incorrect: `https://gateway.maton.ai/docs/v1/documents/{documentId}` ## Resources - [Docs API Overview](https://developers.google.com/docs/api/how-tos/overview) - [Get Document](https://developers.google.com/docs/api/reference/rest/v1/documents/get) - [Create Document](https://developers.google.com/docs/api/reference/rest/v1/documents/create) - [Batch Update](https://developers.google.com/docs/api/reference/rest/v1/documents/batchUpdate) - [Request Types](https://developers.google.com/docs/api/reference/rest/v1/documents/request) - [Document Structure](https://developers.google.com/docs/api/concepts/structure) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:support@maton.ai)