owe 0.1.0__tar.gz

owe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 - 2026 Ruoyu Zhong
+
+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.

owe-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: owe
+Version: 0.1.0
+Summary: Bill splitter and tracker.
+Keywords: bill tracking,bill splitting,bill tracker,bill splitter
+Author: Ruoyu Zhong
+Author-email: Ruoyu Zhong <zhongruoyu@outlook.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Utilities
+Requires-Dist: flask>=3.1.3
+Requires-Dist: flask-cors>=6.0.2
+Requires-Dist: gunicorn>=26.0.0
+Requires-Dist: requests>=2.34.2
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/ZhongRuoyu/owe
+Project-URL: Repository, https://github.com/ZhongRuoyu/owe.git
+Description-Content-Type: text/markdown
+
+# Owe
+
+Owe is a simple web application for splitting bills and tracking who owes whom
+how much.
+
+## Overview
+
+Owe lets a group of users record debts and payments between each other.
+The Summary tab shows the minimum set of transactions needed to settle all
+outstanding balances, and provides a one-click Settle button for each.
+
+Core concepts:
+
+- Users - participants identified by email address.
+- Records - individual transactions of type `DEBT` (someone owes money) or
+  `PAYMENT` (money has been physically transferred).
+  Records can be cancelled (invalidated) if entered by mistake.
+- Summary - the net balances across all active records, reduced to the minimum
+  number of settlement transactions using
+  [a simple greedy algorithm](https://stackoverflow.com/a/15723286).
+
+## Requirements
+
+- Python 3.10 or later
+- [uv](https://github.com/astral-sh/uv) (recommended) or pip
+- (Optional) A Telegram bot token and chat ID for record notifications.
+
+## Setup
+
+You can get started with uv:
+
+```sh
+# Sync dependencies
+uv sync
+# Run the development server
+uv run flask --app owe run
+# Or run the production server with gunicorn
+uv run gunicorn "owe:create_app()"
+```
+
+Or if you prefer pip:
+
+```sh
+# Create a virtual environment
+python3 -m venv .venv
+# Activate the virtual environment
+source .venv/bin/activate
+# Install dependencies
+pip install .
+# Run the development server
+flask --app owe run
+# Or run the production server with gunicorn
+gunicorn "owe:create_app()"
+```
+
+### App factory customization
+
+The application exposes an app factory, `create_app`, with two optional
+keyword arguments:
+
+- `url_prefix`: Prefix all registered routes (e.g. `"/owe"`).
+- `api_only`: Register only the API blueprint (skip the bundled UI).
+
+For example, to run API-only routes under `/owe`:
+
+```sh
+# With Flask
+uv run flask --app "owe:create_app(api_only=True, url_prefix='/owe')" run
+
+# With gunicorn
+uv run gunicorn "owe:create_app(api_only=True, url_prefix='/owe')"
+```
+
+With this configuration, API endpoints are served under `/owe/...`.
+
+### Environment variables
+
+The application can be configured with the following environment variables:
+
+- `OWE_LOG_LEVEL`: Python logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`,
+  `CRITICAL`).
+  Default: `INFO`.
+- `OWE_DATABASE`: Path to the SQLite database file.
+  Default: `owe.db`.
+- `OWE_CURRENCY`: ISO 4217 currency code displayed in the UI.
+  Default: `USD`.
+- `OWE_REQUEST_EMAIL_HEADER`: HTTP header to trust for the authenticated user's
+  email, to be used as the creator of records.
+  When run behind Cloudflare Access, this can be set to
+  `cf-access-authenticated-user-email` so that the application can identify the
+  user by their email address.
+  When unset, the remote IP address will be used to identify the user instead.
+  Default: unset.
+- `OWE_TELEGRAM_BOT_TOKEN`: Telegram bot token for notifications.
+  Default: unset.
+- `OWE_TELEGRAM_CHAT_ID`: Telegram chat ID for notifications.
+  Default: unset.
+
+## Docker
+
+Docker images are available on Docker Hub as
+[`zhongruoyu/owe`](https://hub.docker.com/r/zhongruoyu/owe),
+and on GitHub Container Registry as
+[`ghcr.io/zhongruoyu/owe`](https://ghcr.io/zhongruoyu/owe).
+The `main` tag tracks the latest commit on the main branch.
+
+You may run the application with Docker as follows:
+
+```sh
+docker run -p 8000:8000 \
+  -v /path/to/data:/data \
+  -e OWE_DATABASE=/data/owe.db \
+  -e OWE_CURRENCY=USD \
+  zhongruoyu/owe:main --bind "0.0.0.0:8000"
+```
+
+The container image runs gunicorn and accepts its command-line arguments, so you
+can customize the server configuration (e.g. `--bind` for socket binding) using
+standard gunicorn options; run with `--help` for details.
+
+## API Endpoints
+
+The server exposes the following API endpoints:
+
+- `GET /api/config`: Get application configuration (e.g. currency).
+- `GET /api/users`: List all users.
+- `GET /api/records`: List all active and inactive records.
+- `POST /api/records`: Create a new record.
+  Request body should be JSON with the following fields:
+  - `type`: "DEBT" or "PAYMENT"
+  - `lender`: email of the lender
+  - `borrowers`: list of emails of the borrowers
+  - `amount`: total amount (will be split evenly among borrowers)
+  - `remarks`: optional remarks for the record
+- `PATCH /api/records/status`: Update the status of records.
+  Request body should be JSON with the following fields:
+  - `ids`: list of record IDs to update
+  - `active`: boolean indicating whether the records should be active or
+    inactive
+- `GET /api/summary`:
+  Get the minimum set of settlement transactions.
+
+## Utilities
+
+The package also comes with two command-line utilities:
+
+- `owe-dump`: Dump all records in the database as CSV.
+  Use `--output` to set the output file path (default: `records.csv`);
+  use `--database` to choose the SQLite database file (default: `owe.db`).
+- `owe-users`: Manage users from the command line.
+  Use `--database` to choose the SQLite database file (default: `owe.db`).
+  Usage:
+  - `owe-users [--database <path>] create <email> <name>`:
+    Add a user with the given email and name.
+  - `owe-users [--database <path>] list`: List all users.
+  - `owe-users [--database <path>] activate <email>`:
+    Activate the user with the given email.
+  - `owe-users [--database <path>] deactivate <email>`:
+    Deactivate the user with the given email.
+
+To run these utilities:
+
+```sh
+# With uv
+uv run owe-dump --output records.csv
+uv run owe-users --database owe.db list
+
+# With pip, after `pip install .`
+owe-dump --output records.csv
+owe-users --database owe.db list
+```
+
+## License
+
+This project is licensed under the MIT License.
+See the [LICENSE](LICENSE) file for details.

owe-0.1.0/README.md

@@ -0,0 +1,176 @@
+# Owe
+
+Owe is a simple web application for splitting bills and tracking who owes whom
+how much.
+
+## Overview
+
+Owe lets a group of users record debts and payments between each other.
+The Summary tab shows the minimum set of transactions needed to settle all
+outstanding balances, and provides a one-click Settle button for each.
+
+Core concepts:
+
+- Users - participants identified by email address.
+- Records - individual transactions of type `DEBT` (someone owes money) or
+  `PAYMENT` (money has been physically transferred).
+  Records can be cancelled (invalidated) if entered by mistake.
+- Summary - the net balances across all active records, reduced to the minimum
+  number of settlement transactions using
+  [a simple greedy algorithm](https://stackoverflow.com/a/15723286).
+
+## Requirements
+
+- Python 3.10 or later
+- [uv](https://github.com/astral-sh/uv) (recommended) or pip
+- (Optional) A Telegram bot token and chat ID for record notifications.
+
+## Setup
+
+You can get started with uv:
+
+```sh
+# Sync dependencies
+uv sync
+# Run the development server
+uv run flask --app owe run
+# Or run the production server with gunicorn
+uv run gunicorn "owe:create_app()"
+```
+
+Or if you prefer pip:
+
+```sh
+# Create a virtual environment
+python3 -m venv .venv
+# Activate the virtual environment
+source .venv/bin/activate
+# Install dependencies
+pip install .
+# Run the development server
+flask --app owe run
+# Or run the production server with gunicorn
+gunicorn "owe:create_app()"
+```
+
+### App factory customization
+
+The application exposes an app factory, `create_app`, with two optional
+keyword arguments:
+
+- `url_prefix`: Prefix all registered routes (e.g. `"/owe"`).
+- `api_only`: Register only the API blueprint (skip the bundled UI).
+
+For example, to run API-only routes under `/owe`:
+
+```sh
+# With Flask
+uv run flask --app "owe:create_app(api_only=True, url_prefix='/owe')" run
+
+# With gunicorn
+uv run gunicorn "owe:create_app(api_only=True, url_prefix='/owe')"
+```
+
+With this configuration, API endpoints are served under `/owe/...`.
+
+### Environment variables
+
+The application can be configured with the following environment variables:
+
+- `OWE_LOG_LEVEL`: Python logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`,
+  `CRITICAL`).
+  Default: `INFO`.
+- `OWE_DATABASE`: Path to the SQLite database file.
+  Default: `owe.db`.
+- `OWE_CURRENCY`: ISO 4217 currency code displayed in the UI.
+  Default: `USD`.
+- `OWE_REQUEST_EMAIL_HEADER`: HTTP header to trust for the authenticated user's
+  email, to be used as the creator of records.
+  When run behind Cloudflare Access, this can be set to
+  `cf-access-authenticated-user-email` so that the application can identify the
+  user by their email address.
+  When unset, the remote IP address will be used to identify the user instead.
+  Default: unset.
+- `OWE_TELEGRAM_BOT_TOKEN`: Telegram bot token for notifications.
+  Default: unset.
+- `OWE_TELEGRAM_CHAT_ID`: Telegram chat ID for notifications.
+  Default: unset.
+
+## Docker
+
+Docker images are available on Docker Hub as
+[`zhongruoyu/owe`](https://hub.docker.com/r/zhongruoyu/owe),
+and on GitHub Container Registry as
+[`ghcr.io/zhongruoyu/owe`](https://ghcr.io/zhongruoyu/owe).
+The `main` tag tracks the latest commit on the main branch.
+
+You may run the application with Docker as follows:
+
+```sh
+docker run -p 8000:8000 \
+  -v /path/to/data:/data \
+  -e OWE_DATABASE=/data/owe.db \
+  -e OWE_CURRENCY=USD \
+  zhongruoyu/owe:main --bind "0.0.0.0:8000"
+```
+
+The container image runs gunicorn and accepts its command-line arguments, so you
+can customize the server configuration (e.g. `--bind` for socket binding) using
+standard gunicorn options; run with `--help` for details.
+
+## API Endpoints
+
+The server exposes the following API endpoints:
+
+- `GET /api/config`: Get application configuration (e.g. currency).
+- `GET /api/users`: List all users.
+- `GET /api/records`: List all active and inactive records.
+- `POST /api/records`: Create a new record.
+  Request body should be JSON with the following fields:
+  - `type`: "DEBT" or "PAYMENT"
+  - `lender`: email of the lender
+  - `borrowers`: list of emails of the borrowers
+  - `amount`: total amount (will be split evenly among borrowers)
+  - `remarks`: optional remarks for the record
+- `PATCH /api/records/status`: Update the status of records.
+  Request body should be JSON with the following fields:
+  - `ids`: list of record IDs to update
+  - `active`: boolean indicating whether the records should be active or
+    inactive
+- `GET /api/summary`:
+  Get the minimum set of settlement transactions.
+
+## Utilities
+
+The package also comes with two command-line utilities:
+
+- `owe-dump`: Dump all records in the database as CSV.
+  Use `--output` to set the output file path (default: `records.csv`);
+  use `--database` to choose the SQLite database file (default: `owe.db`).
+- `owe-users`: Manage users from the command line.
+  Use `--database` to choose the SQLite database file (default: `owe.db`).
+  Usage:
+  - `owe-users [--database <path>] create <email> <name>`:
+    Add a user with the given email and name.
+  - `owe-users [--database <path>] list`: List all users.
+  - `owe-users [--database <path>] activate <email>`:
+    Activate the user with the given email.
+  - `owe-users [--database <path>] deactivate <email>`:
+    Deactivate the user with the given email.
+
+To run these utilities:
+
+```sh
+# With uv
+uv run owe-dump --output records.csv
+uv run owe-users --database owe.db list
+
+# With pip, after `pip install .`
+owe-dump --output records.csv
+owe-users --database owe.db list
+```
+
+## License
+
+This project is licensed under the MIT License.
+See the [LICENSE](LICENSE) file for details.

owe-0.1.0/owe/__init__.py

@@ -0,0 +1,20 @@
+from flask import Flask
+from flask_cors import CORS
+
+from . import app as owe_app
+from .config import load_env_config
+
+
+def create_app(
+  *,
+  url_prefix: str | None = None,
+  api_only: bool = False,
+) -> Flask:
+  """Create and configure the Flask application instance."""
+  app = Flask(__name__, static_folder=None)
+  app.config.update(load_env_config())
+  owe_app.init(app)
+  bp = owe_app.api if api_only else owe_app.app
+  app.register_blueprint(bp, url_prefix=url_prefix)
+  CORS(app)
+  return app

owe-0.1.0/owe/app.py

@@ -0,0 +1,204 @@
+import logging
+import sqlite3
+from html import escape
+from pathlib import Path
+from typing import Any, cast
+
+from flask import Blueprint, Flask, Response, current_app, request
+
+from . import database, owe
+from .config import AppConfigItems
+from .record import AggregatedRecord
+
+API_PREFIX = "/api"
+STATIC_DIR = Path(__file__).resolve().parent / "static"
+
+logger = logging.getLogger(__name__)
+
+
+def app_config() -> AppConfigItems:
+  """Return typed app config values for the current request context."""
+  return cast("AppConfigItems", current_app.config)
+
+
+def init(app: Flask) -> None:
+  """Initialize logging and database schema for the app."""
+  config = cast("AppConfigItems", app.config)
+  logging.basicConfig(
+    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    level=getattr(logging, config["LOG_LEVEL"], logging.INFO),
+  )
+  database.init(config["DATABASE"])
+
+
+def get_requester() -> str:
+  """Return requester identity from configured header or remote address."""
+  request_email_header = app_config()["REQUEST_EMAIL_HEADER"]
+  if request_email_header:
+    email = request.headers.get(request_email_header)
+    if email:
+      return email
+  return request.remote_addr or "unknown"
+
+
+app = Blueprint(
+  "owe",
+  __name__,
+  url_prefix="",
+  static_folder=STATIC_DIR,
+  static_url_path="",
+)
+
+
+@app.after_request
+def add_csp(response: Response) -> Response:
+  """Attach a strict content security policy to outgoing responses."""
+  response.headers["Content-Security-Policy"] = (
+    "default-src 'self'; "
+    "script-src 'self' https://cdnjs.cloudflare.com; "
+    "style-src 'self' https://cdnjs.cloudflare.com; "
+    "img-src 'self' data:; "
+  )
+  return response
+
+
+@app.route("/")
+def index() -> Response:
+  """Serve the single-page application entry point."""
+  return app.send_static_file("index.html")
+
+
+api = Blueprint("api", __name__, url_prefix=API_PREFIX)
+app.register_blueprint(api)
+
+
+@api.route("/config")
+def get_config() -> dict[str, Any]:
+  """Return client-facing configuration values."""
+  return {"currency": app_config()["CURRENCY"]}
+
+
+@api.route("/users")
+def get_users() -> list[dict[str, Any]]:
+  """Return active users for UI selection."""
+  users = owe.get_active_users()
+  return [user.asdict() for user in users]
+
+
+@api.route("/records")
+def get_records() -> dict[str, dict[str, Any]]:
+  """Return all records keyed by record ID as strings."""
+  records = owe.get_records()
+  return {str(record.id): record.asdict() for record in records}
+
+
+def validate_add_records_request(  # noqa: PLR0911
+  req: dict[str, Any],
+  valid_emails: set[str],
+) -> tuple[bool, str]:
+  """Validate the add-record request body and referenced user emails."""
+  for key in ["type", "lender", "borrowers", "amount", "remarks"]:
+    if key not in req:
+      return False, f"Missing field: {key}"
+
+  req_type = req["type"]
+  if not isinstance(req_type, str) or req_type not in {"DEBT", "PAYMENT"}:
+    return False, 'type must be either "DEBT" or "PAYMENT"'
+
+  lender = req["lender"]
+  if not isinstance(lender, str):
+    return False, "lender must be a string"
+
+  borrowers = req["borrowers"]
+  if (
+    not isinstance(borrowers, list)
+    or not borrowers
+    or not all(isinstance(borrower, str) for borrower in borrowers)
+  ):
+    return False, "borrowers must be a non-empty list of strings"
+
+  amount = req["amount"]
+  if not isinstance(amount, (int, float)) or amount <= 0:
+    return False, "amount must be a positive number"
+
+  remarks = req["remarks"]
+  if not isinstance(remarks, str) and remarks is not None:
+    return False, "remarks must be a string or null"
+
+  if lender not in valid_emails:
+    return False, f"Unknown lender: {escape(lender)}"
+
+  if unknown_borrowers := set(borrowers) - valid_emails:
+    borrowers_str = escape(
+      # https://github.com/astral-sh/ty/issues/521
+      ", ".join(email for email in unknown_borrowers),  # ty:ignore[no-matching-overload]
+    )
+    return False, f"Unknown borrower(s): {borrowers_str}"
+
+  return True, ""
+
+
+@api.route("/records", methods=["POST"])
+def add_records() -> tuple[dict[str, Any], int]:
+  """Create an aggregated record and persist its split entries."""
+  req = request.get_json()
+  if not req:
+    return {"success": False, "error": "Request body must be JSON"}, 400
+
+  users = owe.get_active_users()
+  valid_emails = {u.email for u in users}
+  valid, error = validate_add_records_request(req, valid_emails)
+  if not valid:
+    return {"success": False, "error": error}, 400
+
+  record = AggregatedRecord(
+    type=req["type"],
+    lender=req["lender"],
+    borrowers=req["borrowers"],
+    amount=req["amount"],
+    created_by=get_requester(),
+    remarks=req["remarks"],
+  )
+  try:
+    owe.add_records(record)
+  except sqlite3.Error:
+    logger.exception("Database error in add_records")
+    return {"success": False, "error": "Database error"}, 500
+
+  return {"success": True}, 200
+
+
+@api.route("/records/status", methods=["PATCH"])
+def set_records_active() -> tuple[dict[str, Any], int]:
+  """Update the active flag for a batch of records."""
+  req = request.get_json()
+  if not req:
+    return {"success": False, "error": "Request body must be JSON"}, 400
+
+  ids = req.get("ids", [])
+  active = req.get("active")
+  if not ids or not all(isinstance(i, int) for i in ids):
+    return {
+      "success": False,
+      "error": "ids must be a non-empty list of integers",
+    }, 400
+  if not isinstance(active, bool):
+    return {"success": False, "error": "active must be a boolean"}, 400
+
+  try:
+    owe.set_records_active(
+      ids,
+      active=active,
+      requester=get_requester(),
+    )
+  except sqlite3.Error:
+    logger.exception("Database error in set_records_active")
+    return {"success": False, "error": "Database error"}, 500
+
+  return {"success": True}, 200
+
+
+@api.route("/summary")
+def summary() -> list[owe.SummaryTransaction]:
+  """Return settlement transactions computed from net balances."""
+  return owe.get_summary()

owe-0.1.0/owe/config.py

@@ -0,0 +1,24 @@
+import os
+from pathlib import Path
+from typing import TypedDict
+
+
+class AppConfigItems(TypedDict):
+  LOG_LEVEL: str
+  DATABASE: Path
+  CURRENCY: str
+  REQUEST_EMAIL_HEADER: str | None
+  TELEGRAM_BOT_TOKEN: str | None
+  TELEGRAM_CHAT_ID: str | None
+
+
+def load_env_config() -> AppConfigItems:
+  """Load application config values from environment variables."""
+  return {
+    "LOG_LEVEL": os.getenv("OWE_LOG_LEVEL", "INFO").upper(),
+    "DATABASE": Path(os.getenv("OWE_DATABASE", "owe.db")),
+    "CURRENCY": os.getenv("OWE_CURRENCY", "USD"),
+    "REQUEST_EMAIL_HEADER": os.getenv("OWE_REQUEST_EMAIL_HEADER"),
+    "TELEGRAM_BOT_TOKEN": os.getenv("OWE_TELEGRAM_BOT_TOKEN"),
+    "TELEGRAM_CHAT_ID": os.getenv("OWE_TELEGRAM_CHAT_ID"),
+  }