matimo-gmail 0.1.2__tar.gz → 0.2.0__tar.gz

{matimo_gmail-0.1.2 → matimo_gmail-0.2.0}/.gitignore

@@ -58,7 +58,6 @@ temp/
 
 # Personal scratch notes / working docs — not part of the shipped repo
 .local-notes/
-typescript/examples/mcp/matimo-tools/.matimo-approvals.json
 typescript/examples/mcp/matimo-tools/fetch-weather/definition.yaml
 typescript/examples/mcp/matimo-tools/npm_downloads/definition.yaml
 typescript/examples/mcp/matimo-tools/skills/ecosystem-health/SKILL.md
@@ -68,3 +67,6 @@ typescript/packages/cli/.matimo/certs/server.crt
 typescript/packages/cli/.matimo/certs/server.key
 typescript/examples/mcp/.matimo/certs/server.crt
 typescript/examples/mcp/.matimo/certs/server.key
+
+# HITL approval manifests are per-machine state (HMAC-signed approvals); never commit one
+**/.matimo-approvals.json

matimo_gmail-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ROAIQ TECHNOLOGIES PRIVATE LIMITED
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{matimo_gmail-0.1.2 → matimo_gmail-0.2.0}/PKG-INFO

@@ -1,23 +1,24 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: matimo-gmail
-Version: 0.1.2
+Version: 0.2.0
 Summary: Matimo provider — Gmail tools (send, list, read, delete emails)
 License: MIT
+License-File: LICENSE
 Keywords: agents,ai,gmail,matimo,tools
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.11
 Requires-Python: >=3.11
-Requires-Dist: matimo-core<0.2.0,>=0.1.0
+Requires-Dist: matimo-core<0.3.0,>=0.2.0
 Description-Content-Type: text/markdown
 
 # matimo-gmail
 
-> Gmail tools for [Matimo](https://matimo.dev) — send, list, read, and delete emails.
+> Gmail tools for [Matimo](https://matimo.dev) - send, list, read, and delete emails.
 
 [![PyPI](https://img.shields.io/pypi/v/matimo-gmail)](https://pypi.org/project/matimo-gmail/)
-[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://docs.matimo.dev)
 
 ---
 
@@ -33,12 +34,12 @@ pip install matimo matimo-gmail
 
 | Tool | Description |
 |------|-------------|
-| `send-email` | Send an email (to, subject, body, cc, bcc, html) |
-| `list-messages` | List messages with optional query/label filters |
-| `get-message` | Get full message content by ID |
-| `get-attachment` | Fetch a message attachment by ID (base64url-encoded) |
-| `create-draft` | Create a draft email |
-| `delete-message` | Move message to trash |
+| `gmail-send-email` | Send an email (to, subject, body, cc, bcc, html) |
+| `gmail-list-messages` | List messages with optional query/label filters |
+| `gmail-get-message` | Get full message content by ID |
+| `gmail-get-attachment` | Fetch a message attachment by ID (base64url-encoded) |
+| `gmail-create-draft` | Create a draft email |
+| `gmail-delete-message` | Move message to trash |
 
 ---
 
@@ -53,14 +54,14 @@ async def main():
     matimo = await Matimo.init(get_tools_path())
 
     # Send an email
-    await matimo.execute('send-email', {
+    await matimo.execute('gmail-send-email', {
         'to': 'user@example.com',
         'subject': 'Hello from Matimo',
         'body': 'This message was sent by an AI agent.',
     })
 
     # List recent messages
-    result = await matimo.execute('list-messages', {
+    result = await matimo.execute('gmail-list-messages', {
         'query': 'is:unread',
         'max_results': 10,
     })
@@ -76,8 +77,6 @@ Gmail tools use OAuth2. Set your credentials via environment variables:
 
 ```bash
 export GMAIL_ACCESS_TOKEN="ya29.your-oauth2-access-token"
-# Or use a service account
-export GMAIL_SERVICE_ACCOUNT_JSON="/path/to/service-account.json"
 ```
 
 ### Getting an Access Token (OAuth2)

{matimo_gmail-0.1.2 → matimo_gmail-0.2.0}/README.md

@@ -1,9 +1,9 @@
 # matimo-gmail
 
-> Gmail tools for [Matimo](https://matimo.dev) — send, list, read, and delete emails.
+> Gmail tools for [Matimo](https://matimo.dev) - send, list, read, and delete emails.
 
 [![PyPI](https://img.shields.io/pypi/v/matimo-gmail)](https://pypi.org/project/matimo-gmail/)
-[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://docs.matimo.dev)
 
 ---
 
@@ -19,12 +19,12 @@ pip install matimo matimo-gmail
 
 | Tool | Description |
 |------|-------------|
-| `send-email` | Send an email (to, subject, body, cc, bcc, html) |
-| `list-messages` | List messages with optional query/label filters |
-| `get-message` | Get full message content by ID |
-| `get-attachment` | Fetch a message attachment by ID (base64url-encoded) |
-| `create-draft` | Create a draft email |
-| `delete-message` | Move message to trash |
+| `gmail-send-email` | Send an email (to, subject, body, cc, bcc, html) |
+| `gmail-list-messages` | List messages with optional query/label filters |
+| `gmail-get-message` | Get full message content by ID |
+| `gmail-get-attachment` | Fetch a message attachment by ID (base64url-encoded) |
+| `gmail-create-draft` | Create a draft email |
+| `gmail-delete-message` | Move message to trash |
 
 ---
 
@@ -39,14 +39,14 @@ async def main():
     matimo = await Matimo.init(get_tools_path())
 
     # Send an email
-    await matimo.execute('send-email', {
+    await matimo.execute('gmail-send-email', {
         'to': 'user@example.com',
         'subject': 'Hello from Matimo',
         'body': 'This message was sent by an AI agent.',
     })
 
     # List recent messages
-    result = await matimo.execute('list-messages', {
+    result = await matimo.execute('gmail-list-messages', {
         'query': 'is:unread',
         'max_results': 10,
     })
@@ -62,8 +62,6 @@ Gmail tools use OAuth2. Set your credentials via environment variables:
 
 ```bash
 export GMAIL_ACCESS_TOKEN="ya29.your-oauth2-access-token"
-# Or use a service account
-export GMAIL_SERVICE_ACCOUNT_JSON="/path/to/service-account.json"
 ```
 
 ### Getting an Access Token (OAuth2)

{matimo_gmail-0.1.2 → matimo_gmail-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matimo-gmail"
-version = "0.1.2"
+version = "0.2.0"
 description = "Matimo provider — Gmail tools (send, list, read, delete emails)"
 readme = "README.md"
 license = { text = "MIT" }
@@ -17,7 +17,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
 ]
 dependencies = [
-    "matimo-core>=0.1.0,<0.2.0",
+    "matimo-core>=0.2.0,<0.3.0",
 ]
 
 [project.entry-points."matimo.providers"]

matimo_gmail-0.2.0/src/matimo_gmail/skills/gmail/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: gmail
+description: "Complete guide to all Gmail tools — inbox management, search, sending, drafts, and attachments."
+version: "1.1.0"
+license: "MIT"
+metadata:
+  category: "Communication"
+  difficulty: "beginner"
+  apply-to: "gmail-send-email gmail-list-messages gmail-get-message gmail-get-attachment gmail-create-draft gmail-delete-message"
+  author: "Matimo"
+  tags: "gmail,email,inbox,google"
+---
+
+# Gmail
+
+Complete guide to using Matimo's Gmail tools for sending emails, inbox management, search, drafts, and attachments.
+
+## All Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `gmail-send-email` | Send a new email |
+| `gmail-list-messages` | List/search messages with Gmail query syntax and label filters |
+| `gmail-get-message` | Get full details of a message (headers, body, attachment metadata) |
+| `gmail-get-attachment` | Fetch a message attachment's raw data by ID |
+| `gmail-create-draft` | Create a draft email without sending it |
+| `gmail-delete-message` | Permanently delete a message |
+
+## Authentication
+
+Gmail tools use OAuth2. Required scopes:
+- `https://www.googleapis.com/auth/gmail.readonly` — for listing/reading messages and attachments
+- `https://www.googleapis.com/auth/gmail.send` — for sending
+- `https://www.googleapis.com/auth/gmail.compose` — for drafts
+- `https://www.googleapis.com/auth/gmail.modify` — for deleting messages
+
+Environment variable: `GMAIL_ACCESS_TOKEN` (or `GMAIL_CLIENT_ID` / `GMAIL_CLIENT_SECRET` / `GMAIL_REFRESH_TOKEN` when using the OAuth2 provider flow).
+
+---
+
+## Sending Emails
+
+Use `gmail-send-email` with:
+- `to` (required) — recipient email or comma-separated list
+- `subject` (required) — email subject
+- `body` (required) — email body (supports HTML via `isHtml`)
+- `cc`, `bcc` — optional recipients
+
+**Best practices:**
+- Always include a meaningful subject
+- Keep body concise; use HTML for formatting
+- Handle bounces — validate addresses before sending
+
+---
+
+## Drafts
+
+Use `gmail-create-draft` with the same parameters as `gmail-send-email` (`to`, `subject`, `body`, `cc`, `bcc`, `isHtml`) to stage an email for manual review before sending.
+
+---
+
+## Inbox Management
+
+### Listing and Searching Messages
+
+`gmail-list-messages` handles both listing and search — pass Gmail's advanced query syntax via `query`, plus `labelIds`, `maxResults`, `pageToken`, and `includeSpamTrash`.
+
+| Operator | Example | Purpose |
+|----------|---------|---------|
+| `from:` | `from:alice@acme.com` | From specific sender |
+| `to:` | `to:team@acme.com` | Sent to |
+| `subject:` | `subject:invoice` | In subject line |
+| `has:attachment` | | Has attachments |
+| `is:unread` | | Unread messages |
+| `is:starred` | | Starred messages |
+| `after:` | `after:2024/01/01` | Date filter |
+| `before:` | `before:2024/06/01` | Date filter |
+| `label:` | `label:work` | By label |
+| `filename:` | `filename:pdf` | Attachment type |
+| `-` | `-from:noreply` | Exclude results |
+
+Combine operators: `from:alice has:attachment after:2024/01/01`. Common label IDs for `labelIds`: `INBOX`, `SENT`, `TRASH`, `SPAM`, `DRAFT`, `STARRED`, `UNREAD` (system labels) or custom user labels.
+
+### Getting Message Details
+
+Use `gmail-get-message` with `messageId` to retrieve full headers, body, and attachment metadata (`payload.parts[].body.attachmentId`).
+
+### Fetching Attachments
+
+Use `gmail-get-attachment` with `messageId` and `attachmentId` (from `gmail-get-message`'s payload parts) to retrieve the attachment's `size` and base64url-encoded `data`.
+
+---
+
+## Common Workflows
+
+### Daily Inbox Triage
+1. List unread emails: `gmail-list-messages` with `labelIds: "UNREAD"`
+2. Search for priority: `gmail-list-messages` with `query: "is:important"`
+3. Get details on flagged items: `gmail-get-message` for each
+4. Pull any attachments: `gmail-get-attachment` using `attachmentId` values from step 3
+
+### Email Notification
+1. Send email: `gmail-send-email` with formatted body
+2. Verify delivery by searching: `gmail-list-messages` with `query: "in:sent subject:..."`
+
+---
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| 401 `Unauthorized` | Invalid or expired token | Refresh OAuth2 token |
+| 403 `Insufficient Permission` | Missing scope | Add required Gmail scope |
+| 400 `Invalid to header` | Bad email address | Validate email format |
+| 429 `Rate limit` | Too many requests | Gmail API: 250 quota units/sec |

{matimo_gmail-0.1.2 → matimo_gmail-0.2.0}/src/matimo_gmail/tools/delete-message/definition.yaml

@@ -1,6 +1,7 @@
 name: gmail-delete-message
 description: Permanently delete a message from Gmail (cannot be undone)
 version: '1.0.0'
+requires_approval: true
 
 parameters:
   messageId: