From ccd4d82194c0b2f153757d2db61272cfd8522e6e Mon Sep 17 00:00:00 2001
From: "Arthur K." <me@wzray.com>
Date: Mon, 2 Mar 2026 05:02:37 +0300
Subject: [PATCH] docs: add readme and example .env

---
 .env.example |   8 ++++
 README.md    | 103 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 111 insertions(+)
 create mode 100644 .env.example
 create mode 100644 README.md

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..356e109
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,8 @@
+# HTTP server port
+PORT=80
+
+# Trigger background token refresh when usage reaches threshold percent
+USAGE_REFRESH_THRESHOLD=85
+
+# Persistent data directory (tokens, screenshots)
+DATA_DIR=/data
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7c38f5c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,103 @@
+# megapt
+
+HTTP service that returns an active ChatGPT access token.
+
+The service can:
+- restore/refresh a saved token from `/data`
+- auto-register a new ChatGPT account when needed
+- get verification email from a disposable mail provider (`temp-mail.org`)
+- expose token and usage info via HTTP endpoint
+
+
+## Endpoints
+
+- `GET /token` - legacy route (defaults to `chatgpt` provider)
+- `GET /chatgpt/token` - explicit provider route
+
+Example response:
+
+```json
+{
+  "token": "<access_token>",
+  "limit": {
+    "used_percent": 0,
+    "remaining_percent": 100,
+    "exhausted": false,
+    "needs_refresh": false
+  },
+  "usage": {
+    "primary_window": {
+      "used_percent": 0,
+      "limit_window_seconds": 604800,
+      "reset_after_seconds": 604800,
+      "reset_at": 1772987784
+    },
+    "secondary_window": null
+  }
+}
+```
+
+
+## Environment variables
+
+See `.env.example`.
+
+- `PORT` - HTTP port for the service
+- `USAGE_REFRESH_THRESHOLD` - percent threshold to trigger background token rotation
+- `DATA_DIR` - directory for persistent data (`chatgpt_tokens.json`, screenshots, etc.)
+
+
+## Local run
+
+Requirements:
+- Python 3.14+
+- Playwright Chromium dependencies
+
+Install and run:
+
+```bash
+uv sync --frozen --no-dev
+./.venv/bin/python -m playwright install --with-deps chromium
+PYTHONPATH=./src ./.venv/bin/python src/server.py
+```
+
+Then request token:
+
+```bash
+curl http://127.0.0.1:8080/chatgpt/token
+```
+
+
+## Docker deployment
+
+Build image:
+
+```bash
+docker build -t megapt:latest .
+```
+
+Run container:
+
+```bash
+docker run -d \
+  --name megapt \
+  --restart unless-stopped \
+  --env-file .env \
+  -v ./data:/data \
+  -p 80:80 \
+  megapt:latest
+```
+
+Check logs:
+
+```bash
+docker logs -f megapt
+```
+
+
+## Notes
+
+- Service performs a startup token check and tries to recover token automatically.
+- Token write path is synchronized (single-writer lock) to avoid parallel re-registration.
+- Browser runs in virtual display (`Xvfb`) inside container.
+- Keep `/data` persistent between restarts.