Update project

Author: Kona Shiny Phoenix

.gitignore

@@ -0,0 +1,75 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# mypy
+.mypy_cache/
+.dmypy.json
+
+# VS Code
+.vscode/
+
+# macOS
+.DS_Store
+
+# dotenv
+.env
+.env.*
+
+# Node
+node_modules/
+package-lock.json
+
+# Other
+*.log

CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to Gmail Automation Python Project
+
+Thank you for your interest in contributing!
+
+## How to Contribute
+
+1. **Fork the repository** and create your branch from `main`.
+2. **Clone your fork** and set up the project locally.
+3. **Install dependencies**:
+   ```
+   pip install -r requirements.txt
+   ```
+4. **Create a new branch** for your feature or bugfix:
+   ```
+   git checkout -b my-feature
+   ```
+5. **Write clear, PEP8-compliant code** with docstrings and type hints.
+6. **Add or update tests** in the `tests/` folder.
+7. **Run all tests** before submitting:
+   ```
+   python -m unittest discover tests
+   ```
+8. **Open a pull request** with a clear description of your changes.
+
+## Code Style
+- Follow [PEP8](https://www.python.org/dev/peps/pep-0008/) guidelines.
+- Use descriptive variable and function names.
+- Include docstrings for all public functions and classes.
+
+## Reporting Issues
+- Use [GitHub Issues](../../issues) to report bugs or request features.
+- Provide as much detail as possible.
+
+## License
+By contributing, you agree that your contributions will be licensed under the MIT License.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Konashinyphoenix
+
+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.

README.md

@@ -0,0 +1,82 @@
+# Gmail Automation Python Project
+
+This project automates Gmail workflows using Python. It fetches emails, applies user-defined rules from `rules.json`, and saves results to PostgreSQL.
+
+## Features
+- Gmail API authentication (OAuth2)
+- Fetch unread emails
+- Parse sender, subject, and snippet
+- Apply rules (label, mark as read, etc.) from `rules.json`
+- Save results to PostgreSQL
+- Unit tests for all major modules
+
+## Project Structure
+```
+app/
+  actions.py         # Gmail actions (mark as read, label)
+  auth.py            # Gmail API authentication
+  db.py              # PostgreSQL save logic
+  fetch_emails.py    # Fetch and parse emails
+  main.py            # Example orchestrator
+  rules_engine.py    # Rule loading and application
+  example_gmail_automation.py # Full workflow example
+
+tests/
+  test_fetch_emails.py
+  test_rules_engine.py
+  test_db.py
+
+rules.json           # Example rules
+requirements.txt     # Python dependencies
+```
+
+## Setup
+1. Install dependencies:
+   ```
+   pip install -r requirements.txt
+   ```
+2. Set up Gmail API credentials:
+   - Download `credentials.json` from Google Cloud Console.
+   - Place it in the project root.
+3. Set up PostgreSQL and create the `emails` table:
+   ```sql
+   CREATE TABLE emails (
+     id TEXT PRIMARY KEY,
+     from_address TEXT,
+     subject TEXT,
+     snippet TEXT,
+     timestamp TIMESTAMP,
+     actions JSONB
+   );
+   ```
+4. Edit `rules.json` to define your rules.
+
+## Running
+- Run the main workflow:
+  ```
+  python -m app.main
+  ```
+- Or run the full example:
+  ```
+  python app/example_gmail_automation.py
+  ```
+
+## Testing
+Run all tests:
+```
+python -m unittest discover tests
+```
+
+## Example `rules.json`
+```
+[
+  {
+    "criteria": {"from": "newsletter@example.com"},
+    "actions": ["applyLabel:NEWSLETTERS"]
+  },
+  {
+    "criteria": {"subject": "Invoice"},
+    "actions": ["markRead"]
+  }
+]
+```

app/actions.py

@@ -0,0 +1,41 @@
+from typing import Any
+from app.auth import get_gmail_service
+
+def mark_email_as_read(email_id: str) -> None:
+    """
+    Mark an email as read by removing the 'UNREAD' label.
+    """
+    service = get_gmail_service()
+    service.users().messages().modify(
+        userId='me',
+        id=email_id,
+        body={'removeLabelIds': ['UNREAD']}
+    ).execute()
+
+def apply_label(email_id: str, label_name: str) -> None:
+    """
+    Apply a label to an email. Create the label if it does not exist.
+    """
+    service = get_gmail_service()
+    labels_res = service.users().labels().list(userId='me').execute()
+    labels = labels_res.get('labels', [])
+    label_id = None
+    for label in labels:
+        if label['name'] == label_name:
+            label_id = label['id']
+            break
+    if not label_id:
+        create_res = service.users().labels().create(
+            userId='me',
+            body={
+                'name': label_name,
+                'labelListVisibility': 'labelShow',
+                'messageListVisibility': 'show',
+            }
+        ).execute()
+        label_id = create_res['id']
+    service.users().messages().modify(
+        userId='me',
+        id=email_id,
+        body={'addLabelIds': [label_id]}
+    ).execute()

app/auth.py

@@ -0,0 +1,25 @@
+import os
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import build
+from typing import Any
+
+SCOPES = ['https://www.googleapis.com/auth/gmail.modify']
+
+def get_gmail_service() -> Any:
+    """
+    Authenticate and return the Gmail API service.
+    """
+    creds = None
+    if os.path.exists('token.json'):
+        creds = Credentials.from_authorized_user_file('token.json', SCOPES)
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            from google.auth.transport.requests import Request
+            creds.refresh(Request())
+        else:
+            flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
+            creds = flow.run_local_server(port=0)
+        with open('token.json', 'w') as token:
+            token.write(creds.to_json())
+    return build('gmail', 'v1', credentials=creds)

app/db.py

@@ -0,0 +1,28 @@
+import os
+import psycopg2
+from typing import List, Dict, Any
+
+def save_many_emails(emails: List[Dict[str, Any]]) -> None:
+    """
+    Save a list of emails to the PostgreSQL database.
+    """
+    conn = psycopg2.connect(
+        dbname=os.getenv('DB_NAME', 'gmaildb'),
+        user=os.getenv('DB_USER', 'postgres'),
+        password=os.getenv('DB_PASSWORD', 'ksp5779'),
+        host=os.getenv('DB_HOST', 'localhost'),
+        port=os.getenv('DB_PORT', '5432')
+    )
+    cur = conn.cursor()
+    for email in emails:
+        cur.execute(
+            """
+            INSERT INTO emails (id, from_address, subject, snippet, timestamp)
+            VALUES (%s, %s, %s, %s, to_timestamp(%s / 1000.0))
+            ON CONFLICT (id) DO NOTHING
+            """,
+            (email['id'], email['from'], email['subject'], email['snippet'], email['timestamp'])
+        )
+    conn.commit()
+    cur.close()
+    conn.close()