From feba2eb0b8df855ea1d24840b6ad624279d2f97f Mon Sep 17 00:00:00 2001 From: aperezmarquez Date: Tue, 5 May 2026 12:51:30 +0000 Subject: [PATCH 1/2] Added: Python script to generate the token.pickle file for the use of the polling system --- app/src/polling/generate_token.py | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 app/src/polling/generate_token.py diff --git a/app/src/polling/generate_token.py b/app/src/polling/generate_token.py new file mode 100644 index 0000000..c87a70b --- /dev/null +++ b/app/src/polling/generate_token.py @@ -0,0 +1,30 @@ +import pickle +import os +from google_auth_oauthlib.flow import InstalledAppFlow + +SCOPES = ["https://www.googleapis.com/auth/gmail.modify"] + + +def generate_token(): + creds = None + + client_secrets_file = "../../token.json" + + if not os.path.exists(client_secrets_file): + print( + f"Error: '{client_secrets_file}' not found. Please follow the Google Cloud Setup guide." + ) + return + + print("Opening browser for authentication...") + flow = InstalledAppFlow.from_client_secrets_file(client_secrets_file, SCOPES) + creds = flow.run_local_server(port=0) + + with open("token.pickle", "wb") as token: + pickle.dump(creds, token) + + print("\nSuccess: 'token.pickle' has been generated!") + + +if __name__ == "__main__": + generate_token() From 736c4384f0729ff2ee01ca216aab38a537445fcf Mon Sep 17 00:00:00 2001 From: aperezmarquez Date: Tue, 5 May 2026 12:52:17 +0000 Subject: [PATCH 2/2] Added: Documentation for the polling system --- app/src/polling/README.md | 30 ++++++++++ app/src/polling/docs/google_cloud_setup.md | 52 ++++++++++++++++ app/src/polling/docs/token_generation.md | 69 ++++++++++++++++++++++ 3 files changed, 151 insertions(+) create mode 100644 app/src/polling/README.md create mode 100644 app/src/polling/docs/google_cloud_setup.md create mode 100644 app/src/polling/docs/token_generation.md diff --git a/app/src/polling/README.md b/app/src/polling/README.md new file mode 100644 index 0000000..659a0e9 --- /dev/null +++ b/app/src/polling/README.md @@ -0,0 +1,30 @@ +# Gmail Polling System + +This module is responsible for performing periodic queries (polling) to the Gmail API to detect, process, and manage emails automatically. + +## Overview +The system utilizes official Google libraries to authenticate, list messages, and download their content. For this component to function correctly, it is mandatory to configure the environment in the **Google Cloud Console** and generate local access credentials. + +--- + +## Environment Setup + +To get this system up and running, you must follow these two mandatory configuration processes: + +### 1. Google Cloud Project Configuration +Before running the code, you must enable the Gmail API and configure the OAuth consent screen in the Google Console. +* **Detailed Guide:** [Google Cloud Setup](./docs/google_cloud_setup.md) + +### 2. Access Token Generation (`token.pickle`) +The system uses a session file called `token.pickle` to avoid manual login every time the script is executed. +* **Step-by-Step Instructions:** [Token Generation and Credentials](./docs/token_generation.md) + +--- + +## Installation + +Ensure you have the necessary dependencies installed before running the service (if the requirements.txt is installed correctly there shouldn't be a problem): + +```bash +pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib +``` diff --git a/app/src/polling/docs/google_cloud_setup.md b/app/src/polling/docs/google_cloud_setup.md new file mode 100644 index 0000000..037bcdc --- /dev/null +++ b/app/src/polling/docs/google_cloud_setup.md @@ -0,0 +1,52 @@ +# Google Cloud Setup for Gmail API + +This guide provides a step-by-step walkthrough for configuring your Google Cloud project and obtaining the necessary credentials for the Gmail Polling System. + +--- + +## 1. Project Creation and API Activation +To begin, you must create a project in the **Google Cloud Console**. This project acts as the container for your application's API configuration and billing settings. + +1. Navigate to the [Google Cloud Console](https://console.cloud.google.com/). +2. Create a new project (e.g., "Gmail-Polling-Service"). +3. Go to the **APIs & Services** section from the sidebar. +4. Click on **Enable APIs and Services** and search for **"Gmail API"**. +5. Select it and click **Enable**. Once enabled, you will see the API status as "Enabled" in the dashboard. + +--- + +## 2. OAuth Consent Screen Configuration +Before generating credentials, you must define how the application requests access to user data. + +1. Navigate to **APIs & Services > OAuth Consent Screen**. +2. Select **User Type** (typically "External" for development or testing). +3. Provide the required branding information (App Name, User Support Email). +4. In the **Scopes** (Data Access) section, click **Add or Remove Scopes**. +5. Add the following specific permissions required for this system: + * `.../auth/gmail.send`: Allows the application to send emails on your behalf. + * `.../auth/gmail.readonly`: Allows the application to view email messages and settings. +6. Ensure your email address is added to the **Test Users** section to allow access during the development phase. + +--- + +## 3. Generating OAuth 2.0 Credentials +Once the consent screen is configured, you need to create the client credentials that your code will use to identify itself. + +1. Navigate to **APIs & Services > Credentials**. +2. Click on **+ Create Credentials** at the top of the screen. +3. Select **OAuth Client ID**. +4. Choose **Desktop App** as the Application Type. +5. Assign a name to your credential (e.g., "Gmail Polling Client"). + +--- + +## 4. Downloading the Credentials File +After creating the OAuth Client ID, a dialog will appear with your Client ID and Client Secret. + +1. **Crucial Step:** Click the **Download JSON** button. +2. The downloaded file contains sensitive configuration data. +3. **Rename** this file to `token.json`. +4. Place the `token.json` file in the **app directory** of the project. + +> [!WARNING] +> **Security Reminder:** The `token.json` file grants access to your Google Cloud Project. Never commit this file to public version control systems (like GitHub). Verify it is listed in your `.gitignore`. diff --git a/app/src/polling/docs/token_generation.md b/app/src/polling/docs/token_generation.md new file mode 100644 index 0000000..22b63ca --- /dev/null +++ b/app/src/polling/docs/token_generation.md @@ -0,0 +1,69 @@ +# Token Generation Guide + +To authenticate the system with the Gmail API, you must generate a `token.pickle` file. This process **must be performed on your local machine** (not via Docker) because the script needs to open a physical web browser window to complete the Google OAuth2 flow. + +--- + +## Prerequisites + +Before starting, ensure you have: +1. Followed the [Google Cloud Setup](./google_cloud_setup.md) guide. +2. Placed your `token.json` in the appropriate directory. + +> [!IMPORTANT] +> You must run this locally, as a headless Docker container cannot open a browser window for you to log in. + +--- + +## Method A: Using the Project Environment + +If you have already set up the full project locally with all dependencies: + +1. Open your terminal in the project root. +2. Ensure your `requirements.txt` dependencies are installed: + ```bash + pip install -r requirements.txt + ``` +3. Run the whole project from the app directory: + ```bash + uvicorn main:app --reload + ``` + +--- + +## Method B: Using a Clean Virtual Environment (Recommended) + +If you want to generate the token without setting up the entire project: + +1. Create and activate a virtual environment: + ```bash + python -m venv venv + source venv/bin/activate # On Windows: venv\Scripts\activate + ``` +2. Install only the necessary libraries for the token creation: + ```bash + pip install google-auth-oauthlib google-api-python-client + ``` +3. Run the script inside the directory app/src/polling: + ```bash + python generate_token.py + ``` + +--- + +## The Authentication Flow + +Regardless of the method chosen, the following will happen during the process: + +* **Browser Redirection:** A tab will automatically open in your default web browser. +* **Google Login:** You must log in using the **exact same Gmail account** that you added as a "Test User" in the Google Cloud Console. +* **Permissions:** You will see a prompt asking for permission to access your Gmail data (specifically the `gmail.modify` scope). Click **Allow**. +* **Completion:** Once the browser displays the message "The authentication flow has completed," you can safely close the tab. + +The script will then generate the `token.pickle` file in your local directory, you will need to move it into the app directory: +```bash +mv token.pickle ../../ +``` + +> [!CAUTION] +> If you ever change the API Scopes in your code, you must delete the existing token.pickle and repeat this local process to grant the new permissions.