docs: add readme and example .env

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.