fetch2gmail 1.0.1__tar.gz → 1.0.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. fetch2gmail-1.0.3/PKG-INFO +286 -0
  2. fetch2gmail-1.0.3/README.md +255 -0
  3. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/pyproject.toml +2 -1
  4. fetch2gmail-1.0.3/src/fetch2gmail.egg-info/PKG-INFO +286 -0
  5. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetch2gmail.egg-info/SOURCES.txt +1 -0
  6. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetch2gmail.egg-info/requires.txt +1 -0
  7. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/auth_server.py +1 -1
  8. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/cli.py +93 -0
  9. fetch2gmail-1.0.3/src/fetcher/ui_auth.py +57 -0
  10. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/web_ui.py +54 -9
  11. fetch2gmail-1.0.1/PKG-INFO +0 -679
  12. fetch2gmail-1.0.1/README.md +0 -649
  13. fetch2gmail-1.0.1/src/fetch2gmail.egg-info/PKG-INFO +0 -679
  14. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/LICENSE +0 -0
  15. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/setup.cfg +0 -0
  16. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetch2gmail.egg-info/dependency_links.txt +0 -0
  17. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetch2gmail.egg-info/entry_points.txt +0 -0
  18. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetch2gmail.egg-info/top_level.txt +0 -0
  19. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/__init__.py +0 -0
  20. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/auth_ui.py +0 -0
  21. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/config.py +0 -0
  22. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/env_file.py +0 -0
  23. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/gmail_client.py +0 -0
  24. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/imap_client.py +0 -0
  25. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/log_buffer.py +0 -0
  26. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/run.py +0 -0
  27. {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/state.py +0 -0
@@ -0,0 +1,286 @@
1
+ Metadata-Version: 2.4
2
+ Name: fetch2gmail
3
+ Version: 1.0.3
4
+ Summary: Self-hosted email fetcher: IMAP to Gmail API import with idempotent state tracking
5
+ Author: Fetch2Gmail Contributors
6
+ License-Expression: MIT
7
+ Keywords: email,imap,gmail,fetch,self-hosted
8
+ Classifier: Development Status :: 4 - Beta
9
+ Classifier: Environment :: Console
10
+ Classifier: Intended Audience :: End Users/Desktop
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Programming Language :: Python :: 3.11
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: Topic :: Communications :: Email
15
+ Requires-Python: >=3.11
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Requires-Dist: google-auth>=2.23.0
19
+ Requires-Dist: google-auth-oauthlib>=1.1.0
20
+ Requires-Dist: google-api-python-client>=2.100.0
21
+ Requires-Dist: fastapi>=0.104.0
22
+ Requires-Dist: uvicorn[standard]>=0.24.0
23
+ Requires-Dist: python-dotenv>=1.0.0
24
+ Requires-Dist: python-multipart>=0.0.6
25
+ Requires-Dist: cryptography>=42.0.0
26
+ Requires-Dist: bcrypt>=4.0.0
27
+ Provides-Extra: dev
28
+ Requires-Dist: pytest>=7.0; extra == "dev"
29
+ Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
30
+ Dynamic: license-file
31
+
32
+ # Fetch2Gmail
33
+
34
+ Self-hosted email fetcher: **IMAP (ISP mailbox) → Gmail API import**. Replaces Gmail’s deprecated POP3 fetch.
35
+
36
+ - Polls an ISP mailbox via **IMAPS** (port 993).
37
+ - Imports messages with **Gmail API** (not SMTP); applies a Gmail label, preserves headers and date.
38
+ - Deletes from ISP only after Gmail confirms import. **Idempotent** (UID + message hash).
39
+
40
+ **Requirements:** Python 3.11+, IMAP credentials, Google Cloud project with Gmail API and OAuth2 (Web application).
41
+
42
+ ---
43
+
44
+ ## Use case 1: Headless Debian server
45
+
46
+ You use a **computer with a browser** (to get the token) and a **Debian server** (Odroid, Raspberry Pi, etc.) where the app runs. Follow the steps in order.
47
+
48
+ ### On a computer with a browser (Windows or Linux)
49
+
50
+ **Step 1. Get credentials.json from Google Cloud**
51
+
52
+ 1. Go to [Google Cloud Console](https://console.cloud.google.com/) → create or select a project.
53
+ 2. **APIs & Services → Library** → search “Gmail API” → **Enable**.
54
+ 3. **OAuth consent screen**: External → add app name → **Scopes** → add `https://www.googleapis.com/auth/gmail.modify` → **Test users** → add the Gmail address that will receive the imported mail.
55
+ 4. **Credentials → Create credentials → OAuth client ID** → Application type **Web application**.
56
+ 5. **Authorized redirect URIs** → add `http://127.0.0.1:8765/auth/gmail/callback` and `http://localhost:8765/auth/gmail/callback`.
57
+ 6. Create → download the JSON. Save it as **credentials.json** in a folder (e.g. Desktop or `~/fetch2gmail-auth`).
58
+
59
+ **Step 2. Install Python 3.11+ and pipx**
60
+
61
+ - **Windows:** Install [Python 3.11+](https://www.python.org/downloads/) (check “Add Python to PATH”). Open Command Prompt or PowerShell: `pip install pipx` then `pipx ensurepath`. Close and reopen the terminal.
62
+ - **Linux:** `sudo apt install pipx` then `pipx ensurepath`. Reopen the terminal (or run `source ~/.bashrc`) so `~/.local/bin` is on PATH.
63
+
64
+ **Step 3. Install fetch2gmail**
65
+
66
+ ```bash
67
+ pipx install fetch2gmail
68
+ ```
69
+
70
+ **Step 4. Get the token**
71
+
72
+ In the **same folder** where **credentials.json** is, run:
73
+
74
+ ```bash
75
+ fetch2gmail auth
76
+ ```
77
+
78
+ A browser opens. Sign in with the **Gmail account that will receive the imported mail** and click Allow. **token.json** is saved in that folder. Press **Ctrl+C** to stop the auth server.
79
+
80
+ **Step 5. Copy these two files to the server**
81
+
82
+ Copy **credentials.json** and **token.json** to your Debian server. You will put them in the app data directory in the next section.
83
+
84
+ ---
85
+
86
+ ### On the Debian server
87
+
88
+ **Step 6. Create the data directory and add the files**
89
+
90
+ Pick one directory for all app files (e.g. `/opt/fetch2gmail` or `/home/odroid/fetch2gmail`). Create it and put **credentials.json** and **token.json** there:
91
+
92
+ ```bash
93
+ sudo mkdir -p /opt/fetch2gmail
94
+ sudo chown "$USER" /opt/fetch2gmail
95
+ # Copy credentials.json and token.json into /opt/fetch2gmail (from step 5)
96
+ ```
97
+
98
+ Use the same path in the steps below (replace `/opt/fetch2gmail` and the username if you use something else).
99
+
100
+ **Step 7. Install pipx and fetch2gmail on the server**
101
+
102
+ Run these from **any directory** (you do not need to be in `/opt/fetch2gmail`):
103
+
104
+ ```bash
105
+ sudo apt install pipx
106
+ pipx ensurepath
107
+ # Log out and back in (or source ~/.bashrc) so ~/.local/bin is on PATH
108
+ pipx install fetch2gmail
109
+ ```
110
+
111
+ The app will find your token and files in `/opt/fetch2gmail` because in step 9 you install a single systemd service that sets **WorkingDirectory** and **FETCH2GMAIL_CONFIG** to that directory. For step 8 you **cd** into `/opt/fetch2gmail` before running `set-ui-password` so the password file is stored there.
112
+
113
+ **Step 8. Set the UI username and password**
114
+
115
+ Run once so only you can access the web UI (username and hashed password are stored in **.ui_auth**):
116
+
117
+ ```bash
118
+ cd /opt/fetch2gmail
119
+ fetch2gmail set-ui-password
120
+ ```
121
+
122
+ Enter a username and password when prompted.
123
+
124
+ **Step 9. Install and enable the systemd service (one service: web UI + background fetch)**
125
+
126
+ One service runs the web UI and polls your ISP mailbox on a schedule (every 5 minutes by default). Generate the unit file and install it:
127
+
128
+ ```bash
129
+ fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail -o /tmp/fetch2gmail.service
130
+ sudo mv /tmp/fetch2gmail.service /etc/systemd/system/fetch2gmail.service
131
+ sudo systemctl daemon-reload
132
+ sudo systemctl enable fetch2gmail
133
+ sudo systemctl start fetch2gmail
134
+ ```
135
+
136
+ Replace **YOUR_USER** with the user that owns `/opt/fetch2gmail` (e.g. `odroid`). Replace **/opt/fetch2gmail** if you used a different data directory. The command finds `fetch2gmail` on your PATH; if it is elsewhere, add `--exec /path/to/fetch2gmail`.
137
+
138
+ Alternatively, print the unit file and pipe it into place:
139
+
140
+ ```bash
141
+ fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
142
+ sudo systemctl daemon-reload
143
+ sudo systemctl enable fetch2gmail
144
+ sudo systemctl start fetch2gmail
145
+ ```
146
+
147
+ **Step 10. Configure ISP mail in the web UI**
148
+
149
+ Open **http://\<server-ip\>:8765** in your browser (e.g. http://192.168.1.10:8765). Log in with the UI username and password from step 8. You will see the **initial setup** form. Enter your IMAP host, username, password, mailbox, and Gmail label, then click **Create config**. The app stores your password securely and will poll your ISP mailbox on a schedule (every 5 minutes by default). You do not need to edit any config file by hand.
150
+
151
+ **Done.** To watch logs: `journalctl -u fetch2gmail -f`.
152
+
153
+ ---
154
+
155
+ ## Use case 2: Device with a browser (one machine)
156
+
157
+ Everything runs on **one machine** (laptop or desktop) that has a browser. You sign in with Google in the web UI — the redirect works because you open the UI on localhost. You do **not** need to run `fetch2gmail auth` or set a UI password. Follow the steps in order.
158
+
159
+ **Step 1. Get credentials.json from Google Cloud**
160
+
161
+ Same as Use case 1, step 1. Save **credentials.json** in a folder you will use as the app data directory (e.g. `~/fetch2gmail`).
162
+
163
+ **Step 2. Install Python 3.11+ and pipx**
164
+
165
+ Same as Use case 1, step 2 (Windows or Linux).
166
+
167
+ **Step 3. Install fetch2gmail**
168
+
169
+ ```bash
170
+ pipx install fetch2gmail
171
+ ```
172
+
173
+ **Step 4. Create the data directory and add credentials**
174
+
175
+ Create the folder and put **credentials.json** there (you do not have a token yet):
176
+
177
+ ```bash
178
+ mkdir -p ~/fetch2gmail
179
+ # Copy credentials.json into ~/fetch2gmail
180
+ ```
181
+
182
+ Use the same path in the steps below (replace `~/fetch2gmail` if you use something else).
183
+
184
+ **Step 5. Install and enable the systemd service**
185
+
186
+ Same as Use case 1, step 9: one service (web UI + background fetch). Replace **YOUR_USER** and the path with yours:
187
+
188
+ ```bash
189
+ fetch2gmail install-service --user YOUR_USER --dir /home/YOUR_USER/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
190
+ sudo systemctl daemon-reload
191
+ sudo systemctl enable fetch2gmail
192
+ sudo systemctl start fetch2gmail
193
+ ```
194
+
195
+ **Step 6. Sign in with Google in the web UI**
196
+
197
+ Open **http://127.0.0.1:8765** in your browser (**use localhost** so the Google OAuth redirect works). You will see **Sign in with Google** — click it, sign in with the Gmail account that will receive the imported mail, and click Allow. The app saves **token.json** in your data directory. You are now signed in.
198
+
199
+ **Step 7. Configure ISP mail in the web UI**
200
+
201
+ Use the **initial setup** form to enter your IMAP host, username, password, mailbox, and Gmail label, then click **Create config**. The app stores your password securely and the timer runs the fetch on the schedule you set (every 5 minutes by default).
202
+
203
+ **Done.**
204
+
205
+ ---
206
+
207
+ ## Reference
208
+
209
+ ### OAuth redirect URI
210
+
211
+ Your Google OAuth client must use **Web application** (not Desktop) and have these **Authorized redirect URIs**:
212
+
213
+ - `http://127.0.0.1:8765/auth/gmail/callback`
214
+ - `http://localhost:8765/auth/gmail/callback`
215
+
216
+ Google does not allow redirect URIs that use an IP address. That is why the token must be obtained on a machine where the app can use localhost (Use case 1 steps 1–4 on a PC; Use case 2 on the same machine).
217
+
218
+ ### Poll interval
219
+
220
+ The app runs the fetch every 5 minutes by default (background poller in the same process as the web UI). You can change the interval in the web UI (Config) or in **config.json** (`poll_interval_minutes`).
221
+
222
+ ### Data directory
223
+
224
+ All app files live in **one directory**: **config.json**, **credentials.json**, **token.json**, and optionally **.env** (IMAP password; the UI can store it for you). The app creates **state.db** and **.ui_auth** there. Set **WorkingDirectory** and **FETCH2GMAIL_CONFIG** to this directory in systemd.
225
+
226
+ ### Security
227
+
228
+ - Do not commit **credentials.json**, **token.json**, or **config.json** with secrets. Restrict file permissions to the user running the service.
229
+ - On the server, the UI is protected by the username and password you set with **`fetch2gmail set-ui-password`** (stored as a hash in **.ui_auth**). There is no Google sign-in on the server when **token.json** is already there.
230
+ - The Gmail scope requested is **gmail.modify** (read and modify labels/messages only).
231
+
232
+ ### CLI
233
+
234
+ | Command | Purpose |
235
+ |--------|---------|
236
+ | `fetch2gmail auth` | Get **token.json** on a machine with a browser (opens http://127.0.0.1:8765). |
237
+ | `fetch2gmail set-ui-password` | Set UI username and password (hash in **.ui_auth**). |
238
+ | `fetch2gmail install-service` | Generate systemd unit file (one service: web UI + background fetch). Use `--user`, `--dir`, and optionally `--output` or pipe to `sudo tee`. |
239
+ | `fetch2gmail serve` | Run the web UI (default: localhost only; use `--host 0.0.0.0` to bind to all interfaces). |
240
+ | `fetch2gmail run` | Run one fetch cycle. |
241
+ | `fetch2gmail run --dry-run` | Connect to ISP and show what would be imported; no Gmail import, no delete. |
242
+
243
+ ### Uninstall (computer used only for token)
244
+
245
+ After copying **credentials.json** and **token.json** to the server, you can remove fetch2gmail from that computer: `pipx uninstall fetch2gmail`. Reinstall with `pipx install fetch2gmail` if you need to run `fetch2gmail auth` again later.
246
+
247
+ ---
248
+
249
+ ## Development / testing from source
250
+
251
+ To run from a git clone (e.g. to test changes before pushing):
252
+
253
+ 1. **Clone and go into the repo:**
254
+ ```bash
255
+ git clone https://github.com/yourusername/fetch2gmail.git
256
+ cd fetch2gmail
257
+ ```
258
+
259
+ 2. **Create and activate a virtual environment:**
260
+ - **Linux / macOS:** `python3 -m venv .venv` then `source .venv/bin/activate`
261
+ - **Windows (PowerShell):** `python -m venv .venv` then `.venv\Scripts\Activate.ps1`
262
+ - **Windows (Command Prompt):** `python -m venv .venv` then `.venv\Scripts\activate.bat`
263
+
264
+ 3. **Install the package in editable mode** (so changes in the repo are used when you run the app):
265
+ ```bash
266
+ pip install -e .
267
+ ```
268
+ Optional, for tests: `pip install -e ".[dev]"`
269
+
270
+ 4. **Run and test** (use the same terminal with the venv active):
271
+ - `fetch2gmail serve` — web UI at http://127.0.0.1:8765
272
+ - `fetch2gmail auth` — get token (put **credentials.json** in the current directory first)
273
+ - `fetch2gmail run` or `fetch2gmail run --dry-run` — if you have **config.json** and secrets set up
274
+
275
+ 5. **Before pushing: test the build** so the package still builds and you catch errors:
276
+ ```bash
277
+ pip install build
278
+ python -m build
279
+ ```
280
+ This creates `dist/` with the sdist and wheel. See **docs/PUBLISHING.md** for Test PyPI and release steps.
281
+
282
+ ---
283
+
284
+ ## License
285
+
286
+ MIT. See **LICENSE**.
@@ -0,0 +1,255 @@
1
+ # Fetch2Gmail
2
+
3
+ Self-hosted email fetcher: **IMAP (ISP mailbox) → Gmail API import**. Replaces Gmail’s deprecated POP3 fetch.
4
+
5
+ - Polls an ISP mailbox via **IMAPS** (port 993).
6
+ - Imports messages with **Gmail API** (not SMTP); applies a Gmail label, preserves headers and date.
7
+ - Deletes from ISP only after Gmail confirms import. **Idempotent** (UID + message hash).
8
+
9
+ **Requirements:** Python 3.11+, IMAP credentials, Google Cloud project with Gmail API and OAuth2 (Web application).
10
+
11
+ ---
12
+
13
+ ## Use case 1: Headless Debian server
14
+
15
+ You use a **computer with a browser** (to get the token) and a **Debian server** (Odroid, Raspberry Pi, etc.) where the app runs. Follow the steps in order.
16
+
17
+ ### On a computer with a browser (Windows or Linux)
18
+
19
+ **Step 1. Get credentials.json from Google Cloud**
20
+
21
+ 1. Go to [Google Cloud Console](https://console.cloud.google.com/) → create or select a project.
22
+ 2. **APIs & Services → Library** → search “Gmail API” → **Enable**.
23
+ 3. **OAuth consent screen**: External → add app name → **Scopes** → add `https://www.googleapis.com/auth/gmail.modify` → **Test users** → add the Gmail address that will receive the imported mail.
24
+ 4. **Credentials → Create credentials → OAuth client ID** → Application type **Web application**.
25
+ 5. **Authorized redirect URIs** → add `http://127.0.0.1:8765/auth/gmail/callback` and `http://localhost:8765/auth/gmail/callback`.
26
+ 6. Create → download the JSON. Save it as **credentials.json** in a folder (e.g. Desktop or `~/fetch2gmail-auth`).
27
+
28
+ **Step 2. Install Python 3.11+ and pipx**
29
+
30
+ - **Windows:** Install [Python 3.11+](https://www.python.org/downloads/) (check “Add Python to PATH”). Open Command Prompt or PowerShell: `pip install pipx` then `pipx ensurepath`. Close and reopen the terminal.
31
+ - **Linux:** `sudo apt install pipx` then `pipx ensurepath`. Reopen the terminal (or run `source ~/.bashrc`) so `~/.local/bin` is on PATH.
32
+
33
+ **Step 3. Install fetch2gmail**
34
+
35
+ ```bash
36
+ pipx install fetch2gmail
37
+ ```
38
+
39
+ **Step 4. Get the token**
40
+
41
+ In the **same folder** where **credentials.json** is, run:
42
+
43
+ ```bash
44
+ fetch2gmail auth
45
+ ```
46
+
47
+ A browser opens. Sign in with the **Gmail account that will receive the imported mail** and click Allow. **token.json** is saved in that folder. Press **Ctrl+C** to stop the auth server.
48
+
49
+ **Step 5. Copy these two files to the server**
50
+
51
+ Copy **credentials.json** and **token.json** to your Debian server. You will put them in the app data directory in the next section.
52
+
53
+ ---
54
+
55
+ ### On the Debian server
56
+
57
+ **Step 6. Create the data directory and add the files**
58
+
59
+ Pick one directory for all app files (e.g. `/opt/fetch2gmail` or `/home/odroid/fetch2gmail`). Create it and put **credentials.json** and **token.json** there:
60
+
61
+ ```bash
62
+ sudo mkdir -p /opt/fetch2gmail
63
+ sudo chown "$USER" /opt/fetch2gmail
64
+ # Copy credentials.json and token.json into /opt/fetch2gmail (from step 5)
65
+ ```
66
+
67
+ Use the same path in the steps below (replace `/opt/fetch2gmail` and the username if you use something else).
68
+
69
+ **Step 7. Install pipx and fetch2gmail on the server**
70
+
71
+ Run these from **any directory** (you do not need to be in `/opt/fetch2gmail`):
72
+
73
+ ```bash
74
+ sudo apt install pipx
75
+ pipx ensurepath
76
+ # Log out and back in (or source ~/.bashrc) so ~/.local/bin is on PATH
77
+ pipx install fetch2gmail
78
+ ```
79
+
80
+ The app will find your token and files in `/opt/fetch2gmail` because in step 9 you install a single systemd service that sets **WorkingDirectory** and **FETCH2GMAIL_CONFIG** to that directory. For step 8 you **cd** into `/opt/fetch2gmail` before running `set-ui-password` so the password file is stored there.
81
+
82
+ **Step 8. Set the UI username and password**
83
+
84
+ Run once so only you can access the web UI (username and hashed password are stored in **.ui_auth**):
85
+
86
+ ```bash
87
+ cd /opt/fetch2gmail
88
+ fetch2gmail set-ui-password
89
+ ```
90
+
91
+ Enter a username and password when prompted.
92
+
93
+ **Step 9. Install and enable the systemd service (one service: web UI + background fetch)**
94
+
95
+ One service runs the web UI and polls your ISP mailbox on a schedule (every 5 minutes by default). Generate the unit file and install it:
96
+
97
+ ```bash
98
+ fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail -o /tmp/fetch2gmail.service
99
+ sudo mv /tmp/fetch2gmail.service /etc/systemd/system/fetch2gmail.service
100
+ sudo systemctl daemon-reload
101
+ sudo systemctl enable fetch2gmail
102
+ sudo systemctl start fetch2gmail
103
+ ```
104
+
105
+ Replace **YOUR_USER** with the user that owns `/opt/fetch2gmail` (e.g. `odroid`). Replace **/opt/fetch2gmail** if you used a different data directory. The command finds `fetch2gmail` on your PATH; if it is elsewhere, add `--exec /path/to/fetch2gmail`.
106
+
107
+ Alternatively, print the unit file and pipe it into place:
108
+
109
+ ```bash
110
+ fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
111
+ sudo systemctl daemon-reload
112
+ sudo systemctl enable fetch2gmail
113
+ sudo systemctl start fetch2gmail
114
+ ```
115
+
116
+ **Step 10. Configure ISP mail in the web UI**
117
+
118
+ Open **http://\<server-ip\>:8765** in your browser (e.g. http://192.168.1.10:8765). Log in with the UI username and password from step 8. You will see the **initial setup** form. Enter your IMAP host, username, password, mailbox, and Gmail label, then click **Create config**. The app stores your password securely and will poll your ISP mailbox on a schedule (every 5 minutes by default). You do not need to edit any config file by hand.
119
+
120
+ **Done.** To watch logs: `journalctl -u fetch2gmail -f`.
121
+
122
+ ---
123
+
124
+ ## Use case 2: Device with a browser (one machine)
125
+
126
+ Everything runs on **one machine** (laptop or desktop) that has a browser. You sign in with Google in the web UI — the redirect works because you open the UI on localhost. You do **not** need to run `fetch2gmail auth` or set a UI password. Follow the steps in order.
127
+
128
+ **Step 1. Get credentials.json from Google Cloud**
129
+
130
+ Same as Use case 1, step 1. Save **credentials.json** in a folder you will use as the app data directory (e.g. `~/fetch2gmail`).
131
+
132
+ **Step 2. Install Python 3.11+ and pipx**
133
+
134
+ Same as Use case 1, step 2 (Windows or Linux).
135
+
136
+ **Step 3. Install fetch2gmail**
137
+
138
+ ```bash
139
+ pipx install fetch2gmail
140
+ ```
141
+
142
+ **Step 4. Create the data directory and add credentials**
143
+
144
+ Create the folder and put **credentials.json** there (you do not have a token yet):
145
+
146
+ ```bash
147
+ mkdir -p ~/fetch2gmail
148
+ # Copy credentials.json into ~/fetch2gmail
149
+ ```
150
+
151
+ Use the same path in the steps below (replace `~/fetch2gmail` if you use something else).
152
+
153
+ **Step 5. Install and enable the systemd service**
154
+
155
+ Same as Use case 1, step 9: one service (web UI + background fetch). Replace **YOUR_USER** and the path with yours:
156
+
157
+ ```bash
158
+ fetch2gmail install-service --user YOUR_USER --dir /home/YOUR_USER/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
159
+ sudo systemctl daemon-reload
160
+ sudo systemctl enable fetch2gmail
161
+ sudo systemctl start fetch2gmail
162
+ ```
163
+
164
+ **Step 6. Sign in with Google in the web UI**
165
+
166
+ Open **http://127.0.0.1:8765** in your browser (**use localhost** so the Google OAuth redirect works). You will see **Sign in with Google** — click it, sign in with the Gmail account that will receive the imported mail, and click Allow. The app saves **token.json** in your data directory. You are now signed in.
167
+
168
+ **Step 7. Configure ISP mail in the web UI**
169
+
170
+ Use the **initial setup** form to enter your IMAP host, username, password, mailbox, and Gmail label, then click **Create config**. The app stores your password securely and the timer runs the fetch on the schedule you set (every 5 minutes by default).
171
+
172
+ **Done.**
173
+
174
+ ---
175
+
176
+ ## Reference
177
+
178
+ ### OAuth redirect URI
179
+
180
+ Your Google OAuth client must use **Web application** (not Desktop) and have these **Authorized redirect URIs**:
181
+
182
+ - `http://127.0.0.1:8765/auth/gmail/callback`
183
+ - `http://localhost:8765/auth/gmail/callback`
184
+
185
+ Google does not allow redirect URIs that use an IP address. That is why the token must be obtained on a machine where the app can use localhost (Use case 1 steps 1–4 on a PC; Use case 2 on the same machine).
186
+
187
+ ### Poll interval
188
+
189
+ The app runs the fetch every 5 minutes by default (background poller in the same process as the web UI). You can change the interval in the web UI (Config) or in **config.json** (`poll_interval_minutes`).
190
+
191
+ ### Data directory
192
+
193
+ All app files live in **one directory**: **config.json**, **credentials.json**, **token.json**, and optionally **.env** (IMAP password; the UI can store it for you). The app creates **state.db** and **.ui_auth** there. Set **WorkingDirectory** and **FETCH2GMAIL_CONFIG** to this directory in systemd.
194
+
195
+ ### Security
196
+
197
+ - Do not commit **credentials.json**, **token.json**, or **config.json** with secrets. Restrict file permissions to the user running the service.
198
+ - On the server, the UI is protected by the username and password you set with **`fetch2gmail set-ui-password`** (stored as a hash in **.ui_auth**). There is no Google sign-in on the server when **token.json** is already there.
199
+ - The Gmail scope requested is **gmail.modify** (read and modify labels/messages only).
200
+
201
+ ### CLI
202
+
203
+ | Command | Purpose |
204
+ |--------|---------|
205
+ | `fetch2gmail auth` | Get **token.json** on a machine with a browser (opens http://127.0.0.1:8765). |
206
+ | `fetch2gmail set-ui-password` | Set UI username and password (hash in **.ui_auth**). |
207
+ | `fetch2gmail install-service` | Generate systemd unit file (one service: web UI + background fetch). Use `--user`, `--dir`, and optionally `--output` or pipe to `sudo tee`. |
208
+ | `fetch2gmail serve` | Run the web UI (default: localhost only; use `--host 0.0.0.0` to bind to all interfaces). |
209
+ | `fetch2gmail run` | Run one fetch cycle. |
210
+ | `fetch2gmail run --dry-run` | Connect to ISP and show what would be imported; no Gmail import, no delete. |
211
+
212
+ ### Uninstall (computer used only for token)
213
+
214
+ After copying **credentials.json** and **token.json** to the server, you can remove fetch2gmail from that computer: `pipx uninstall fetch2gmail`. Reinstall with `pipx install fetch2gmail` if you need to run `fetch2gmail auth` again later.
215
+
216
+ ---
217
+
218
+ ## Development / testing from source
219
+
220
+ To run from a git clone (e.g. to test changes before pushing):
221
+
222
+ 1. **Clone and go into the repo:**
223
+ ```bash
224
+ git clone https://github.com/yourusername/fetch2gmail.git
225
+ cd fetch2gmail
226
+ ```
227
+
228
+ 2. **Create and activate a virtual environment:**
229
+ - **Linux / macOS:** `python3 -m venv .venv` then `source .venv/bin/activate`
230
+ - **Windows (PowerShell):** `python -m venv .venv` then `.venv\Scripts\Activate.ps1`
231
+ - **Windows (Command Prompt):** `python -m venv .venv` then `.venv\Scripts\activate.bat`
232
+
233
+ 3. **Install the package in editable mode** (so changes in the repo are used when you run the app):
234
+ ```bash
235
+ pip install -e .
236
+ ```
237
+ Optional, for tests: `pip install -e ".[dev]"`
238
+
239
+ 4. **Run and test** (use the same terminal with the venv active):
240
+ - `fetch2gmail serve` — web UI at http://127.0.0.1:8765
241
+ - `fetch2gmail auth` — get token (put **credentials.json** in the current directory first)
242
+ - `fetch2gmail run` or `fetch2gmail run --dry-run` — if you have **config.json** and secrets set up
243
+
244
+ 5. **Before pushing: test the build** so the package still builds and you catch errors:
245
+ ```bash
246
+ pip install build
247
+ python -m build
248
+ ```
249
+ This creates `dist/` with the sdist and wheel. See **docs/PUBLISHING.md** for Test PyPI and release steps.
250
+
251
+ ---
252
+
253
+ ## License
254
+
255
+ MIT. See **LICENSE**.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "fetch2gmail"
7
- version = "1.0.1"
7
+ version = "1.0.3"
8
8
  description = "Self-hosted email fetcher: IMAP to Gmail API import with idempotent state tracking"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -30,6 +30,7 @@ dependencies = [
30
30
  "python-dotenv>=1.0.0",
31
31
  "python-multipart>=0.0.6",
32
32
  "cryptography>=42.0.0",
33
+ "bcrypt>=4.0.0",
33
34
  ]
34
35
 
35
36
  [project.optional-dependencies]