Explain get_billing_period default arguments

f49f9b4 Fix Google OAuth user info extraction
446c74e Fix ImportError when running Streamlit app directly
bdfca6b Initial scaffold for Octoco Dash

commit bdfca6b4bdf29f7c02f2eb9dd0a4558c59072ce2
Author: G-J van Rooyen <g-j@octoco.ltd>
Date:   Fri Jan 23 18:12:06 2026 +0200

    Initial scaffold for Octoco Dash

    Streamlit dashboard for analyzing Amp usage across Octoco projects,
    designed to help understand how agentic coding affects consultancy
    unit economics.

    Core features implemented:
    - Google OAuth with @octoco.ltd domain restriction and allowlist
    - SUPERADMIN env var for bootstrap access
    - SQLite database with SQLAlchemy models for threads, repos, users
    - Amp API client with OAuth2 client credentials flow
    - Incremental thread sync from Amp API
    - Project list view with thread counts and costs
    - Project detail view with per-user breakdown
    - 19th-18th billing cycle date picker
    - CLI for user management (add-user, remove-user, list-users)
    - Fly.io deployment configuration (jnb region)

    Agent-thread: https://ampcode.com/threads/T-019be72e-c92e-736a-8e1f-424871f2a9cb
    Co-authored-by: Amp <amp@octoco.ltd>

diff --git a/src/octoco_dash/billing.py b/src/octoco_dash/billing.py
new file mode 100644
index 0000000..d5431f5
--- /dev/null
+++ b/src/octoco_dash/billing.py
@@ -0,0 +1,125 @@
+from datetime import date, timedelta
+
+from sqlalchemy import func
+from sqlalchemy.orm import Session
+
+from .db.models import Repository, Thread, User, thread_repositories
+
+
+def get_billing_period(reference_date: date | None = None) -> tuple[date, date]:
+    if reference_date is None:
+        reference_date = date.today()
+
+    if reference_date.day >= 19:
+        start = reference_date.replace(day=19)
+        if reference_date.month == 12:
+            end = reference_date.replace(year=reference_date.year + 1, month=1, day=18)
+        else:
+            end = reference_date.replace(month=reference_date.month + 1, day=18)
+    else:
+        if reference_date.month == 1:
+            start = reference_date.replace(year=reference_date.year - 1, month=12, day=19)
+        else:
+            start = reference_date.replace(month=reference_date.month - 1, day=19)
+        end = reference_date.replace(day=18)
+
+    return start, end
+
+
+def get_previous_billing_periods(count: int = 6) -> list[tuple[date, date]]:
+    periods = []
+    ref = date.today()
+
+    for _ in range(count):
+        start, end = get_billing_period(ref)
+        periods.append((start, end))
+        ref = start - timedelta(days=1)
+
+    return periods
+
+
+def get_project_summary(
+    session: Session,
+    start_date: date,
+    end_date: date,
+) -> list[dict]:
+    results = (
+        session.query(
+            Repository.url,
+            Repository.display_name,
+            func.count(Thread.id).label("thread_count"),
+            func.sum(Thread.usage_usd).label("total_usage"),
+        )
+        .join(thread_repositories, Repository.url == thread_repositories.c.repository_url)
+        .join(Thread, Thread.id == thread_repositories.c.thread_id)
+        .filter(Thread.created_at >= start_date)
+        .filter(Thread.created_at <= end_date)
+        .group_by(Repository.url, Repository.display_name)
+        .order_by(func.sum(Thread.usage_usd).desc())
+        .all()
+    )
+
+    return [
+        {
+            "repo_url": r.url,
+            "display_name": r.display_name or r.url.split("/")[-1] if r.url else "Unknown",
+            "thread_count": r.thread_count,
+            "total_usage": r.total_usage or 0.0,
+        }
+        for r in results
+    ]
+
+
+def get_project_details(
+    session: Session,
+    repo_url: str,
+    start_date: date,
+    end_date: date,
+) -> dict:
+    threads = (
+        session.query(Thread)
+        .join(thread_repositories, Thread.id == thread_repositories.c.thread_id)
+        .filter(thread_repositories.c.repository_url == repo_url)
+        .filter(Thread.created_at >= start_date)
+        .filter(Thread.created_at <= end_date)
+        .all()
+    )
+
+    user_breakdown = {}
+    for thread in threads:
+        user_id = thread.creator_user_id or "unknown"
+        if user_id not in user_breakdown:
+            user = session.get(User, user_id) if user_id != "unknown" else None
+            user_breakdown[user_id] = {
+                "user_id": user_id,
+                "name": user.name if user else None,
+                "email": user.email if user else None,
+                "thread_count": 0,
+                "total_usage": 0.0,
+            }
+        user_breakdown[user_id]["thread_count"] += 1
+        user_breakdown[user_id]["total_usage"] += thread.usage_usd or 0.0
+
+    repo = session.get(Repository, repo_url)
+
+    return {
+        "repo_url": repo_url,
+        "display_name": repo.display_name if repo else repo_url.split("/")[-1],
+        "thread_count": len(threads),
+        "total_usage": sum(t.usage_usd or 0 for t in threads),
+        "users": sorted(
+            user_breakdown.values(),
+            key=lambda x: x["total_usage"],
+            reverse=True,
+        ),
+        "threads": [
+            {
+                "id": t.id,
+                "title": t.title,
+                "created_at": t.created_at,
+                "usage_usd": t.usage_usd,
+                "creator_user_id": t.creator_user_id,
+            }
+            for t in sorted(threads, key=lambda x: x.created_at or x.id, reverse=True)
+        ],
+    }