@matimo/gmail 0.1.0-alpha.10

package/definition.yaml

@@ -0,0 +1,49 @@
+# Google OAuth2 Provider Definition
+#
+# This file defines the OAuth2 configuration for Google.
+# All Gmail tools reference this provider definition.
+#
+# Users can override these endpoints via:
+# 1. Runtime config (highest priority)
+# 2. Environment variables: OAUTH_GOOGLE_AUTH_URL, OAUTH_GOOGLE_TOKEN_URL, etc.
+# 3. This YAML definition (lowest priority)
+#
+# Pattern: Define once, use everywhere
+
+name: google-provider
+type: provider
+version: '1.0.0'
+
+description: |
+  Google OAuth2 Provider Configuration
+
+  All Gmail tools and Google-dependent tools use these endpoints.
+
+  Setup:
+  1. Create Google Cloud project
+  2. Enable Gmail API
+  3. Create OAuth2 credentials (web application)
+  4. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET environment variables
+  5. Set GOOGLE_REDIRECT_URI to your callback URL
+
+provider:
+  name: google
+  displayName: Google
+
+  # OAuth2 Endpoints
+  # Standard Google OAuth2 endpoints - change only if using custom proxy
+  endpoints:
+    authorizationUrl: https://accounts.google.com/o/oauth2/v2/auth
+    tokenUrl: https://oauth2.googleapis.com/token
+    revokeUrl: https://oauth2.googleapis.com/revoke
+
+  # Standard scopes for Gmail access
+  # Tools can override with their own scopes
+  defaultScopes:
+    - https://www.googleapis.com/auth/gmail.readonly
+    - https://www.googleapis.com/auth/gmail.send
+    - https://www.googleapis.com/auth/gmail.compose
+
+  # Additional metadata
+  documentation: https://developers.google.com/gmail/api
+  learnMore: https://developers.google.com/oauthplayground

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@matimo/gmail",
+  "version": "0.1.0-alpha.10",
+  "description": "Gmail tools for Matimo",
+  "type": "module",
+  "files": [
+    "tools",
+    "README.md",
+    "definition.yaml"
+  ],
+  "peerDependencies": {
+    "matimo": "0.1.0-alpha.10"
+  },
+  "devDependencies": {
+    "axios": "^1.13.4",
+    "@matimo/core": "0.1.0-alpha.10"
+  }
+}

package/tools/create-draft/definition.yaml

@@ -0,0 +1,99 @@
+name: gmail-create-draft
+description: Create a draft email in Gmail without sending it
+version: '1.0.0'
+
+parameters:
+  to:
+    type: string
+    description: Email address of the recipient(s), comma-separated for multiple recipients
+    required: true
+    example: 'user@example.com'
+
+  subject:
+    type: string
+    description: Subject line of the draft email
+    required: true
+    example: 'Draft Email'
+
+  body:
+    type: string
+    description: Email body content (plain text or HTML)
+    required: true
+    example: 'This is a draft email'
+
+  cc:
+    type: string
+    description: CC email addresses, comma-separated
+    required: false
+    example: 'cc@example.com'
+
+  bcc:
+    type: string
+    description: BCC email addresses, comma-separated
+    required: false
+    example: 'bcc@example.com'
+
+  isHtml:
+    type: boolean
+    description: Whether the body content is HTML (default is plain text)
+    required: false
+    default: false
+
+  raw:
+    type: string
+    description: 'Base64url-encoded MIME message (RFC 2822 format). If provided, overrides to/subject/body/cc/bcc parameters.'
+    required: false
+    example: 'VG8...'
+
+execution:
+  type: http
+  method: POST
+  url: 'https://www.googleapis.com/gmail/v1/users/me/drafts'
+  headers:
+    Content-Type: 'application/json'
+    Authorization: 'Bearer {GMAIL_ACCESS_TOKEN}'
+
+  # Parameter encoding: automatically convert to/subject/body to MIME format
+  parameter_encoding:
+    - source: [to, subject, body, cc, bcc, isHtml]
+      target: raw
+      encoding: mime_rfc2822_base64url
+
+  body:
+    message:
+      raw: '{raw}'
+
+authentication:
+  type: oauth2
+  provider: google
+  scopes:
+    - 'https://www.googleapis.com/auth/gmail.compose'
+
+output_schema:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Draft ID
+    message:
+      type: object
+      description: The created message object
+      properties:
+        id:
+          type: string
+        threadId:
+          type: string
+        labelIds:
+          type: array
+          items:
+            type: string
+
+error_handling:
+  retry: 3
+  backoff_type: exponential
+  initial_delay_ms: 1000
+  retryable_status_codes:
+    - 429
+    - 500
+    - 502
+    - 503

package/tools/delete-message/definition.yaml

@@ -0,0 +1,38 @@
+name: gmail-delete-message
+description: Permanently delete a message from Gmail (cannot be undone)
+version: '1.0.0'
+
+parameters:
+  messageId:
+    type: string
+    description: ID of the message to delete
+    required: true
+    example: '187a65b7f3f2f11e'
+
+execution:
+  type: http
+  method: DELETE
+  url: 'https://www.googleapis.com/gmail/v1/users/me/messages/{messageId}'
+  headers:
+    Authorization: 'Bearer {GMAIL_ACCESS_TOKEN}'
+  note: 'Immediately and permanently deletes the message. This operation cannot be undone. Use trash instead if you want to allow recovery.'
+
+authentication:
+  type: oauth2
+  provider: google
+  scopes:
+    - 'https://www.googleapis.com/auth/gmail.modify'
+
+output_schema:
+  type: object
+  description: Empty response on successful deletion (204 No Content). The executor may return an empty body for 204 responses.
+
+error_handling:
+  retry: 3
+  backoff_type: exponential
+  initial_delay_ms: 1000
+  retryable_status_codes:
+    - 429
+    - 500
+    - 502
+    - 503

package/tools/get-message/definition.yaml

@@ -0,0 +1,90 @@
+name: gmail-get-message
+description: Get full details of a specific Gmail message including headers and body
+version: '1.0.0'
+
+parameters:
+  messageId:
+    type: string
+    description: ID of the message to retrieve
+    required: true
+    example: '187a65b7f3f2f11e'
+
+  format:
+    type: string
+    enum:
+      - minimal
+      - full
+      - raw
+    description: Format of the message to return
+    required: false
+    default: full
+    example: full
+
+  metadataHeaders:
+    type: string
+    description: Comma-separated headers to include in metadata (when format=minimal)
+    required: false
+    example: 'From,Subject,Date'
+
+execution:
+  type: http
+  method: GET
+  url: 'https://www.googleapis.com/gmail/v1/users/me/messages/{messageId}'
+  query_params:
+    format: '{format}'
+    metadataHeaders: '{metadataHeaders}'
+  headers:
+    Authorization: 'Bearer {GMAIL_ACCESS_TOKEN}'
+    Accept: 'application/json'
+
+authentication:
+  type: oauth2
+  provider: google
+  scopes:
+    - 'https://www.googleapis.com/auth/gmail.readonly'
+
+output_schema:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Message ID
+    threadId:
+      type: string
+      description: Thread ID
+    labelIds:
+      type: array
+      items:
+        type: string
+      description: Array of label IDs applied to this message
+    snippet:
+      type: string
+      description: Short snippet of the message text
+    sizeEstimate:
+      type: number
+      description: Estimated size of the message in bytes
+    headers:
+      type: object
+      description: Message headers (From, To, Subject, Date, etc.)
+    body:
+      type: object
+      description: Message body with data and mimeType
+      properties:
+        mimeType:
+          type: string
+        data:
+          type: string
+          description: Message body data (base64 encoded if raw format)
+    error:
+      type: string
+      description: Error message if request failed
+
+error_handling:
+  retry: 3
+  backoff_type: exponential
+  initial_delay_ms: 1000
+  retryable_status_codes:
+    - 429
+    - 500
+    - 502
+    - 503

package/tools/list-messages/definition.yaml

@@ -0,0 +1,84 @@
+name: gmail-list-messages
+description: List messages from Gmail mailbox with filtering and pagination
+version: '1.0.0'
+
+parameters:
+  query:
+    type: string
+    description: Gmail search query (e.g., 'from:user@example.com', 'subject:hello', 'is:unread')
+    required: false
+    example: 'is:unread'
+
+  maxResults:
+    type: number
+    description: Maximum number of messages to return (1-500, defaults to 100)
+    required: false
+    default: 100
+    example: 20
+
+  pageToken:
+    type: string
+    description: Page token for pagination
+    required: false
+    example: 'NEXT_PAGE_TOKEN'
+
+  includeSpamTrash:
+    type: boolean
+    description: Include spam and trash in results (defaults to false)
+    required: false
+    default: false
+
+  labelIds:
+    type: string
+    description: Comma-separated label IDs to filter by
+    required: false
+    example: 'INBOX,IMPORTANT'
+
+execution:
+  type: http
+  method: GET
+  url: 'https://www.googleapis.com/gmail/v1/users/me/messages'
+  query_params:
+    q: '{query}'
+    maxResults: '{maxResults}'
+    pageToken: '{pageToken}'
+    includeSpamTrash: '{includeSpamTrash}'
+    labelIds: '{labelIds}'
+  headers:
+    Authorization: 'Bearer {GMAIL_ACCESS_TOKEN}'
+
+authentication:
+  type: oauth2
+  provider: google
+  scopes:
+    - 'https://www.googleapis.com/auth/gmail.readonly'
+
+output_schema:
+  type: object
+  properties:
+    messages:
+      type: array
+      description: List of message objects (contains only id and threadId)
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+          threadId:
+            type: string
+    nextPageToken:
+      type: string
+      description: Token for fetching next page of results
+    resultSizeEstimate:
+      type: number
+      description: Estimated total number of results
+
+error_handling:
+  retry: 3
+  backoff_type: exponential
+  initial_delay_ms: 1000
+  retryable_status_codes:
+    - 429
+    - 500
+    - 502
+    - 503

package/tools/send-email/definition.yaml

@@ -0,0 +1,95 @@
+name: gmail-send-email
+description: Send an email using Gmail API with MIME format encoding
+version: '1.0.0'
+
+parameters:
+  to:
+    type: string
+    description: Email address of the recipient(s), comma-separated for multiple recipients
+    required: true
+    example: 'user@example.com'
+
+  subject:
+    type: string
+    description: Subject line of the email
+    required: true
+    example: 'Hello from Matimo'
+
+  body:
+    type: string
+    description: Email body content (plain text or HTML)
+    required: true
+    example: 'This is a test email from Matimo'
+
+  cc:
+    type: string
+    description: CC email addresses, comma-separated
+    required: false
+    example: 'cc@example.com'
+
+  bcc:
+    type: string
+    description: BCC email addresses, comma-separated
+    required: false
+    example: 'bcc@example.com'
+
+  isHtml:
+    type: boolean
+    description: Whether the body content is HTML (default is plain text)
+    required: false
+    default: false
+
+  raw:
+    type: string
+    description: 'Base64url-encoded MIME message (RFC 2822 format). If provided, overrides to/subject/body/cc/bcc parameters.'
+    required: false
+    example: 'VG8...'
+
+execution:
+  type: http
+  method: POST
+  url: 'https://www.googleapis.com/gmail/v1/users/me/messages/send'
+  headers:
+    Content-Type: 'application/json'
+    Authorization: 'Bearer {GMAIL_ACCESS_TOKEN}'
+
+  # Parameter encoding: automatically convert to/subject/body to MIME format
+  parameter_encoding:
+    - source: [to, subject, body, cc, bcc, isHtml]
+      target: raw
+      encoding: mime_rfc2822_base64url
+
+  body:
+    raw: '{raw}'
+
+authentication:
+  type: oauth2
+  provider: google
+  scopes:
+    - 'https://www.googleapis.com/auth/gmail.send'
+
+output_schema:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Message ID of the sent email
+    threadId:
+      type: string
+      description: Thread ID of the sent email
+    labelIds:
+      type: array
+      items:
+        type: string
+      description: Label IDs applied to the message
+
+error_handling:
+  retry: 3
+  backoff_type: exponential
+  initial_delay_ms: 1000
+  max_delay_ms: 10000
+  retryable_status_codes:
+    - 429
+    - 500
+    - 502
+    - 503