mail-intake/mcp_docs/modules/mail_intake.adapters.gmail.json

{
  "module": "mail_intake.adapters.gmail",
  "content": {
    "path": "mail_intake.adapters.gmail",
    "docstring": "Gmail adapter implementation for Mail Intake.\n\nThis module provides a **Gmail-specific implementation** of the\n`MailIntakeAdapter` contract.\n\nIt is the only place in the codebase where:\n- `googleapiclient` is imported\n- Gmail REST API semantics are known\n- Low-level `.execute()` calls are made\n\nAll Gmail-specific behavior must be strictly contained within this module.",
    "objects": {
      "Iterator": {
        "name": "Iterator",
        "kind": "alias",
        "path": "mail_intake.adapters.gmail.Iterator",
        "signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>",
        "docstring": null
      },
      "Dict": {
        "name": "Dict",
        "kind": "alias",
        "path": "mail_intake.adapters.gmail.Dict",
        "signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
        "docstring": null
      },
      "Any": {
        "name": "Any",
        "kind": "alias",
        "path": "mail_intake.adapters.gmail.Any",
        "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
        "docstring": null
      },
      "build": {
        "name": "build",
        "kind": "alias",
        "path": "mail_intake.adapters.gmail.build",
        "signature": "<bound method Alias.signature of Alias('build', 'googleapiclient.discovery.build')>",
        "docstring": null
      },
      "HttpError": {
        "name": "HttpError",
        "kind": "alias",
        "path": "mail_intake.adapters.gmail.HttpError",
        "signature": "<bound method Alias.signature of Alias('HttpError', 'googleapiclient.errors.HttpError')>",
        "docstring": null
      },
      "MailIntakeAdapter": {
        "name": "MailIntakeAdapter",
        "kind": "class",
        "path": "mail_intake.adapters.gmail.MailIntakeAdapter",
        "signature": "<bound method Alias.signature of Alias('MailIntakeAdapter', 'mail_intake.adapters.base.MailIntakeAdapter')>",
        "docstring": "Base adapter interface for mail providers.\n\nThis interface defines the minimal contract required to:\n- Discover messages matching a query\n- Retrieve full message payloads\n- Retrieve full thread payloads\n\nAdapters are intentionally read-only and must not mutate provider state.",
        "members": {
          "iter_message_refs": {
            "name": "iter_message_refs",
            "kind": "function",
            "path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs",
            "signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
            "docstring": "Iterate over lightweight message references matching a query.\n\nImplementations must yield dictionaries containing at least:\n- ``message_id``: Provider-specific message identifier\n- ``thread_id``: Provider-specific thread identifier\n\nArgs:\n    query: Provider-specific query string used to filter messages.\n\nYields:\n    Dictionaries containing message and thread identifiers.\n\nExample yield:\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }"
          },
          "fetch_message": {
            "name": "fetch_message",
            "kind": "function",
            "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message",
            "signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
            "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n    message_id: Provider-specific message identifier.\n\nReturns:\n    Provider-native message payload\n    (e.g., Gmail message JSON structure)."
          },
          "fetch_thread": {
            "name": "fetch_thread",
            "kind": "function",
            "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread",
            "signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
            "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n    thread_id: Provider-specific thread identifier.\n\nReturns:\n    Provider-native thread payload."
          }
        }
      },
      "MailIntakeAdapterError": {
        "name": "MailIntakeAdapterError",
        "kind": "class",
        "path": "mail_intake.adapters.gmail.MailIntakeAdapterError",
        "signature": "<bound method Alias.signature of Alias('MailIntakeAdapterError', 'mail_intake.exceptions.MailIntakeAdapterError')>",
        "docstring": "Errors raised by mail provider adapters.\n\nRaised when a provider adapter encounters API errors,\ntransport failures, or invalid provider responses."
      },
      "MailIntakeAuthProvider": {
        "name": "MailIntakeAuthProvider",
        "kind": "class",
        "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider",
        "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nAuthentication providers encapsulate all logic required to:\n- Acquire credentials from an external provider\n- Refresh or revalidate credentials as needed\n- Handle authentication-specific failure modes\n- Coordinate with credential persistence layers where applicable\n\nMail adapters must treat returned credentials as opaque and\nprovider-specific, relying only on the declared credential type\nexpected by the adapter.",
        "members": {
          "get_credentials": {
            "name": "get_credentials",
            "kind": "function",
            "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider.get_credentials",
            "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
            "docstring": "Retrieve valid, provider-specific credentials.\n\nThis method is synchronous by design and represents the sole\nentry point through which adapters obtain authentication\nmaterial.\n\nImplementations must either return credentials of the declared\ntype ``T`` that are valid at the time of return or raise an\nauthentication-specific exception.\n\nReturns:\n    Credentials of type ``T`` suitable for immediate use by the\n    corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated."
          }
        }
      },
      "MailIntakeGmailAdapter": {
        "name": "MailIntakeGmailAdapter",
        "kind": "class",
        "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter",
        "signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 25, 172)>",
        "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nThis class is the ONLY place where:\n- googleapiclient is imported\n- Gmail REST semantics are known\n- .execute() is called\n\nDesign constraints:\n- Must remain thin and imperative\n- Must not perform parsing or interpretation\n- Must not expose Gmail-specific types beyond this class",
        "members": {
          "service": {
            "name": "service",
            "kind": "attribute",
            "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service",
            "signature": null,
            "docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n    Initialized Gmail API service instance.\n\nRaises:\n    MailIntakeAdapterError: If the Gmail service cannot be initialized."
          },
          "iter_message_refs": {
            "name": "iter_message_refs",
            "kind": "function",
            "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs",
            "signature": "<bound method Function.signature of Function('iter_message_refs', 82, 122)>",
            "docstring": "Iterate over message references matching the query.\n\nArgs:\n    query: Gmail search query string.\n\nYields:\n    Dictionaries containing:\n    - ``message_id``: Gmail message ID\n    - ``thread_id``: Gmail thread ID\n\nRaises:\n    MailIntakeAdapterError: If the Gmail API returns an error."
          },
          "fetch_message": {
            "name": "fetch_message",
            "kind": "function",
            "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message",
            "signature": "<bound method Function.signature of Function('fetch_message', 124, 147)>",
            "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n    message_id: Gmail message identifier.\n\nReturns:\n    Provider-native Gmail message payload.\n\nRaises:\n    MailIntakeAdapterError: If the Gmail API returns an error."
          },
          "fetch_thread": {
            "name": "fetch_thread",
            "kind": "function",
            "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread",
            "signature": "<bound method Function.signature of Function('fetch_thread', 149, 172)>",
            "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n    thread_id: Gmail thread identifier.\n\nReturns:\n    Provider-native Gmail thread payload.\n\nRaises:\n    MailIntakeAdapterError: If the Gmail API returns an error."
          }
        }
      }
    }
  }
}