owe 0.1.0__py3-none-any.whl

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/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/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"),
+  }

owe/database.py

@@ -0,0 +1,175 @@
+import sqlite3
+from pathlib import Path
+from textwrap import dedent
+from typing import Any
+
+from .record import Record
+from .user import User
+
+
+def dict_factory(
+  cursor: sqlite3.Cursor,
+  row: tuple[Any, ...],
+) -> dict[str, Any]:
+  """Convert a SQLite row tuple into a dict keyed by column name."""
+  return dict(
+    zip(
+      [column[0] for column in cursor.description],
+      row,
+      strict=True,
+    )
+  )
+
+
+def init(database: Path) -> None:
+  """Create database tables and views if they do not already exist."""
+  with sqlite3.connect(database) as con:
+    con.cursor().execute(
+      dedent("""
+        CREATE TABLE IF NOT EXISTS Users(
+          email  TEXT PRIMARY KEY,
+          name   TEXT UNIQUE NOT NULL,
+          active BOOLEAN DEFAULT TRUE
+        );
+      """)
+    ).execute(
+      dedent("""
+        CREATE TABLE IF NOT EXISTS Records(
+          id         INTEGER PRIMARY KEY AUTOINCREMENT,
+          type       TEXT NOT NULL,
+          lender     TEXT NOT NULL,
+          borrower   TEXT NOT NULL,
+          amount     INTEGER NOT NULL,
+          created_by TEXT NOT NULL,
+          created_at INTEGER NOT NULL,
+          remarks    TEXT,
+          active     BOOLEAN DEFAULT TRUE,
+          CHECK(type IN ('DEBT', 'PAYMENT')),
+          FOREIGN KEY(lender) REFERENCES Users(email),
+          FOREIGN KEY(borrower) REFERENCES Users(email),
+          CHECK(lender != borrower),
+          CHECK(amount > 0)
+        );
+      """)
+    ).execute(
+      dedent("""
+        CREATE VIEW IF NOT EXISTS UserBalances AS
+        WITH Deltas AS (
+          SELECT
+            lender AS user,
+            amount AS delta
+          FROM Records
+          WHERE active = TRUE
+
+          UNION ALL
+
+          SELECT
+            borrower AS user,
+            -amount AS delta
+          FROM Records
+          WHERE active = TRUE
+        )
+        SELECT
+          user,
+          SUM(delta) AS balance
+        FROM Deltas
+        GROUP BY user;
+      """)
+    )
+
+
+def get_users(database: Path, *, active_only: bool = False) -> list[User]:
+  """Fetch users from the database ordered by display name."""
+  with sqlite3.connect(database) as con:
+    con.row_factory = dict_factory
+    cur = con.cursor()
+    query = "SELECT * FROM Users"
+    if active_only:
+      query += " WHERE active = TRUE"
+    query += " ORDER BY name;"
+    rows = cur.execute(query).fetchall()
+  return [User.from_db_row(row) for row in rows]
+
+
+def add_user(database: Path, user: User) -> None:
+  """Insert a user row into the database."""
+  with sqlite3.connect(database) as con:
+    cur = con.cursor()
+    cur.execute(
+      "INSERT INTO Users(email, name, active) VALUES(?, ?, ?);",
+      user.to_insert_values(),
+    )
+
+
+def set_user_active(database: Path, email: str, *, active: bool) -> int:
+  """Set a user's active flag and return the number of updated rows."""
+  with sqlite3.connect(database) as con:
+    cur = con.cursor()
+    cur.execute(
+      "UPDATE Users SET active = ? WHERE email = ?;",
+      (active, email),
+    )
+    return cur.rowcount
+
+
+def get_records(database: Path, *, active_only: bool = False) -> list[Record]:
+  """Fetch records from the database ordered by ID."""
+  with sqlite3.connect(database) as con:
+    con.row_factory = dict_factory
+    cur = con.cursor()
+    query = "SELECT * FROM Records"
+    if active_only:
+      query += " WHERE active = TRUE"
+    query += " ORDER BY id;"
+    rows = cur.execute(query).fetchall()
+  return [Record.from_db_row(row) for row in rows]
+
+
+def add_records(database: Path, records: list[Record]) -> None:
+  """Insert records and populate generated IDs on each record object."""
+  with sqlite3.connect(database) as con:
+    cur = con.cursor()
+    cur.execute("PRAGMA foreign_keys = ON;")
+    for record in records:
+      cur.execute(
+        dedent("""
+          INSERT INTO Records(
+            type,
+            lender,
+            borrower,
+            amount,
+            created_by,
+            created_at,
+            remarks,
+            active
+          )
+          VALUES(?, ?, ?, ?, ?, ?, ?, ?);
+        """),
+        record.to_insert_values(),
+      )
+      record.id = cur.lastrowid
+
+
+def set_records_active(
+  database: Path,
+  ids: list[int],
+  *,
+  active: bool,
+) -> int:
+  """Set the active flag for record IDs and return affected row count."""
+  with sqlite3.connect(database) as con:
+    cur = con.cursor()
+    cur.executemany(
+      "UPDATE Records SET active = ? WHERE id = ?;",
+      [(active, record_id) for record_id in ids],
+    )
+    return cur.rowcount
+
+
+def get_net_balances(database: Path) -> dict[str, int]:
+  """Return per-user net balances computed from active records."""
+  with sqlite3.connect(database) as con:
+    cur = con.cursor()
+    cur.row_factory = dict_factory
+    rows = cur.execute("SELECT * FROM UserBalances;").fetchall()
+  return {row["user"]: row["balance"] for row in rows}

owe/owe.py

@@ -0,0 +1,126 @@
+import logging
+import threading
+from typing import TypedDict, cast
+
+from flask import current_app
+
+from . import database
+from .config import AppConfigItems
+from .record import AggregatedRecord, Record
+from .telegram import announce_record_status_change, announce_records
+from .user import User
+
+logger = logging.getLogger(__name__)
+
+SummaryTransaction = TypedDict(
+  "SummaryTransaction",
+  {"from": str, "to": str, "amount": int},
+)
+
+
+def app_config() -> AppConfigItems:
+  """Return typed app config values for service-layer helpers."""
+  return cast("AppConfigItems", current_app.config)
+
+
+def get_active_users() -> list[User]:
+  """Return all active users."""
+  return database.get_users(app_config()["DATABASE"], active_only=True)
+
+
+def get_records() -> list[Record]:
+  """Return all records."""
+  return database.get_records(app_config()["DATABASE"])
+
+
+def add_records(record: AggregatedRecord) -> None:
+  """Create new records and trigger notifications."""
+  config = app_config()
+  records = record.to_records()
+  database.add_records(config["DATABASE"], records)
+  logger.info(
+    "Added %d record(s) of type %s by %s",
+    len(records),
+    record.type,
+    record.created_by,
+  )
+
+  if config["TELEGRAM_BOT_TOKEN"] and config["TELEGRAM_CHAT_ID"]:
+    users = get_active_users()
+
+    threading.Thread(
+      target=announce_records,
+      args=(
+        records,
+        config["CURRENCY"],
+        users,
+        config["TELEGRAM_BOT_TOKEN"],
+        config["TELEGRAM_CHAT_ID"],
+      ),
+      daemon=False,
+    ).start()
+
+
+def set_records_active(
+  ids: list[int],
+  *,
+  active: bool,
+  requester: str,
+) -> None:
+  """Activate or cancel records and trigger notifications."""
+  config = app_config()
+  database.set_records_active(config["DATABASE"], ids, active=active)
+  action = "activated" if active else "canceled"
+  logger.info("%d records %s by %s", len(ids), action, requester)
+
+  if config["TELEGRAM_BOT_TOKEN"] and config["TELEGRAM_CHAT_ID"]:
+    records = [record for record in get_records() if record.id in set(ids)]
+    users = database.get_users(config["DATABASE"])
+    threading.Thread(
+      target=announce_record_status_change,
+      args=(
+        records,
+        config["CURRENCY"],
+        users,
+        requester,
+        config["TELEGRAM_BOT_TOKEN"],
+        config["TELEGRAM_CHAT_ID"],
+      ),
+      kwargs={"active": active},
+      daemon=False,
+    ).start()
+
+
+def get_summary() -> list[SummaryTransaction]:
+  """Return a minimized transfer plan from current balances."""
+  net_balances = database.get_net_balances(app_config()["DATABASE"])
+  creditors = [
+    (user, balance) for user, balance in net_balances.items() if balance > 0
+  ]
+  debtors = [
+    (user, -balance) for user, balance in net_balances.items() if balance < 0
+  ]
+  creditors.sort(key=lambda x: x[1], reverse=True)
+  debtors.sort(key=lambda x: x[1], reverse=True)
+
+  transactions: list[SummaryTransaction] = []
+  creditor_idx = 0
+  debtor_idx = 0
+  while creditor_idx < len(creditors) and debtor_idx < len(debtors):
+    creditor_user, credit_amount = creditors[creditor_idx]
+    debtor_user, debt_amount = debtors[debtor_idx]
+
+    transfer_amount = min(credit_amount, debt_amount)
+    if transfer_amount > 0:
+      transactions.append(
+        {"from": debtor_user, "to": creditor_user, "amount": transfer_amount}
+      )
+    creditors[creditor_idx] = (creditor_user, credit_amount - transfer_amount)
+    debtors[debtor_idx] = (debtor_user, debt_amount - transfer_amount)
+
+    if creditors[creditor_idx][1] == 0:
+      creditor_idx += 1
+    if debtors[debtor_idx][1] == 0:
+      debtor_idx += 1
+
+  return transactions

owe/record.py

@@ -0,0 +1,158 @@
+import datetime as dt
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class Record:
+  """A record representing a single transaction between two users."""
+
+  type: str
+  lender: str
+  borrower: str
+  amount: int
+  created_by: str
+  created_at: dt.datetime
+  remarks: str | None = None
+  active: bool = True
+  id: int | None = None
+
+  def to_insert_values(
+    self,
+  ) -> tuple[str, str, str, int, str, int, str | None, bool]:
+    """Return values matching the records insert statement order."""
+    return (
+      self.type,
+      self.lender,
+      self.borrower,
+      self.amount,
+      self.created_by,
+      int(self.created_at.timestamp() * 1000),
+      self.remarks,
+      self.active,
+    )
+
+  @staticmethod
+  def from_db_row(row: dict[str, Any]) -> "Record":
+    """Create a ``Record`` from a database row mapping."""
+    created_at = dt.datetime.fromtimestamp(
+      row["created_at"] / 1000, tz=dt.timezone.utc
+    )
+    return Record(
+      id=row["id"],
+      type=row["type"],
+      lender=row["lender"],
+      borrower=row["borrower"],
+      amount=row["amount"],
+      created_by=row["created_by"],
+      created_at=created_at,
+      remarks=row["remarks"],
+      active=bool(row["active"]),
+    )
+
+  @staticmethod
+  def csv_header() -> tuple[str, str, str, str, str, str, str, str, str]:
+    """Return the CSV header used for record export."""
+    return (
+      "id",
+      "type",
+      "lender",
+      "borrower",
+      "amount",
+      "created_by",
+      "created_at",
+      "remarks",
+      "active",
+    )
+
+  @staticmethod
+  def from_csv_row(row: list[str]) -> "Record":
+    """Create a ``Record`` from a CSV row."""
+    (
+      record_id,
+      record_type,
+      lender,
+      borrower,
+      amount,
+      created_by,
+      created_at,
+      remarks,
+      active,
+    ) = row
+    return Record(
+      id=int(record_id),
+      type=record_type,
+      lender=lender,
+      borrower=borrower,
+      amount=int(float(amount) * 100),
+      created_by=created_by,
+      created_at=dt.datetime.fromisoformat(created_at),
+      remarks=remarks,
+      active=bool(int(active)),
+    )
+
+  def to_csv_row(self) -> tuple[int, str, str, str, str, str, str, str, int]:
+    """Return the record encoded as a CSV row."""
+    return (
+      self.id or 0,
+      self.type,
+      self.lender,
+      self.borrower,
+      f"{self.amount / 100:.2f}",
+      self.created_by,
+      self.created_at.isoformat(timespec="milliseconds"),
+      self.remarks or "",
+      int(self.active),
+    )
+
+  def asdict(self) -> dict[str, Any]:
+    """Return a JSON-serializable representation of the record."""
+    return {
+      "id": self.id,
+      "type": self.type,
+      "lender": self.lender,
+      "borrower": self.borrower,
+      "amount": self.amount,
+      "created_by": self.created_by,
+      "created_at": int(self.created_at.timestamp() * 1000),
+      "remarks": self.remarks,
+      "active": self.active,
+    }
+
+
+def ceildiv(a: float, b: int) -> int:
+  """Divide ``a`` by ``b`` and round up."""
+  return int(-(a // -b))
+
+
+@dataclass(slots=True)
+class AggregatedRecord:
+  """
+  An aggregated record representing a single transaction that involves possibly
+  multiple users.
+  """
+
+  type: str
+  lender: str
+  borrowers: list[str]
+  amount: int
+  created_by: str
+  remarks: str | None
+
+  def to_records(self) -> list[Record]:
+    """Split an aggregated record into per-borrower ``Record`` entries."""
+    each_amount = ceildiv(self.amount, len(self.borrowers))
+    created_at = dt.datetime.now(tz=dt.timezone.utc)
+    return [
+      Record(
+        type=self.type,
+        lender=self.lender,
+        borrower=borrower,
+        amount=each_amount,
+        created_by=self.created_by,
+        created_at=created_at,
+        remarks=self.remarks,
+      )
+      for borrower in self.borrowers
+      if borrower != self.lender
+    ]