gitlytics 0.1.5__tar.gz → 0.1.6__tar.gz

{gitlytics-0.1.5 → gitlytics-0.1.6}/LICENSE

@@ -194,8 +194,22 @@
 
        http://www.apache.org/licenses/LICENSE-2.0
 
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+-------------------------------------------------------------------------
+
+"Commons Clause" License Condition v1.0
+
+The Software is provided to you by the Licensor under the License, as defined below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights under the License will not include, and the License does not grant to you, the right to Sell the Software.
+
+For purposes of the foregoing, "Sell" means practicing any or all of the rights granted to you under the License to provide to third parties, for a fee or other consideration (including without limitation fees for hosting or consulting/ support services related to the Software), a product or service whose value derives, entirely or substantially, from the functionality of the Software. Any license notice or attribution required by the License must also include this Commons Clause License Condition notice.
+
+Software: Gitlytics
+License: Apache 2.0
+Licensor: Ameya Sanjay Chopade

{gitlytics-0.1.5 → gitlytics-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitlytics
-Version: 0.1.5
+Version: 0.1.6
 Summary: Monitor and automate your GitHub repository traffic analytics.
 Author-email: Ameya Chopade <ameyaccod171@gmail.com>
 License: Apache-2.0
@@ -27,15 +27,14 @@ Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
 Requires-Dist: httpx>=0.27.0; extra == "dev"
-Requires-Dist: Faker>=20.0.0; extra == "dev"
 Requires-Dist: anyio[trio]>=4.0.0; extra == "dev"
 Dynamic: license-file
 
 <div align="center">
 
-<img src="./assets/logo.png" alt="Gitlytics Logo" width="150" />
+<img src="https://raw.githubusercontent.com/ameyac11/gitlytics/main/assets/logo.png" alt="Gitlytics Logo" width="150" />
 
-# <span style="color: #F05032">Git</span>lytics
+# Gitlytics
 ### GitHub Traffic Analytics & Automation 
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
@@ -48,6 +47,8 @@ Dynamic: license-file
 [![Live](https://img.shields.io/badge/Live%20Demo-dashboard.gitlytics.dev-success)](https://dashboard.gitlytics.dev)
 [![Docs](https://img.shields.io/badge/Docs-docs.gitlytics.dev-success)](https://docs.gitlytics.dev)
 
+<br/>Please consider giving this project a ⭐ if you find it helpful! <br/>
+
 **Beautiful GitHub traffic analytics for all your repositories — public and private.** <br/> Track views, clones, referrers, and popular paths indefinitely.
 
 ✨ **[Try the live dashboard at dashboard.gitlytics.dev](https://dashboard.gitlytics.dev)** ✨  
@@ -57,22 +58,16 @@ Dynamic: license-file
 
 > **🐍 Native Python API**
 > 
-> You can import Gitlytics natively into your own Python applications to build custom integrations, run custom cron workflows, or serve the dashboard programmatically on your own cloud servers.
+> You can import Gitlytics natively into your own Python applications to fetch live repository data like views, clones, stars, and referrers. Build custom integrations, run custom cron workflows, or serve the dashboard programmatically on your own cloud servers.
 > 
 > 📚 **[Read the Full API Documentation](https://docs.gitlytics.dev)**
 
-Please consider giving this project a ⭐ if you find it helpful!
-
 </div>
 
 ---
 
 <div align="center">
-  <img src="https://raw.githubusercontent.com/ameyac11/gitlytics/main/assets/gitlytics_thumbnail_1.png" width="49%" />
-  <img src="https://raw.githubusercontent.com/ameyac11/gitlytics/main/assets/gitlytics_thumbnail_2.png" width="49%" />
-</div>
-<div align="center">
-  <img src="https://raw.githubusercontent.com/ameyac11/gitlytics/main/assets/gitlytics_thumbnail_3.png" width="98.5%" />
+  <img src="https://raw.githubusercontent.com/ameyac11/gitlytics/main/assets/gitlytics_thumbnail_1.png" width="100%" />
 </div>
 
 ---
@@ -101,7 +96,7 @@ Please consider giving this project a ⭐ if you find it helpful!
 
 The full Gitlytics ecosystem spans across a few repositories. If you are looking for the live web dashboard or the automation cron job, check out the links below:
 
-- **[<span style="color: #F05032">Git</span>lytics Web Ecosystem](https://github.com/ameyac11/gitlytics-deployement)**: The production homepage, React Dashboard, and VitePress documentation site.
+- **[Gitlytics Web Ecosystem](https://github.com/ameyac11/gitlytics-deployement)**: The production landing page, React Dashboard, and React Documentation site.
 - ⚙️ **[Gitlytics Automation](https://github.com/ameyac11/gitlytics-github-traffic-automation)**: The GitHub Action companion tool that automates fetching and saving to defeat GitHub's 14-day traffic limit.
 
 ---
@@ -147,6 +142,9 @@ Gitlytics is powered by 3 massive command-line tools. You can run them anywhere
 Fetch your live 14-day traffic and print a beautiful ASCII table directly in your console.
 ```bash
 gitlytics fetch --token ghp_your_token_here --print-table
+
+# Fetch specific metrics only (e.g., views and clones)
+gitlytics fetch --token ghp_your_token_here --print-table --metrics views clones
 ```
 
 ### 2️⃣ `gitlytics sync` (Background Database Cron)
@@ -155,6 +153,9 @@ Tired of losing data? Use `sync` to permanently append today's traffic to a CSV
 # Sync once
 gitlytics sync --token ghp_your_token --data-dir ./data
 
+# Sync specific metrics only
+gitlytics sync --token ghp_your_token --data-dir ./data --metrics views clones
+
 # Run permanently in the background as a cron job (runs at 11:00 PM every day)
 gitlytics sync --token ghp_your_token --data-dir ./data --schedule-cron "0 23 * * *"
 ```
@@ -212,6 +213,7 @@ gitlytics.fetch_traffic(
 | `print_table` | `bool` | `False` | If `True`, formats and prints a detailed ASCII traffic table to the console. |
 | `return_format` | `str` | `"dataframe"` | The format of returned data: `"dataframe"` (Pandas DataFrame), `"timeseries"` (chart-ready nested dict), or `"summary"` (per-repo totals dict). |
 | `save_file` | `str` | `None` | Optional. File path where the fetched data will be saved (CSV or JSON). |
+| `metrics` | `list` | `None` | Optional. List of metrics to fetch (e.g., `["views", "clones"]`). |
 
 ---
 
@@ -248,6 +250,7 @@ gitlytics.sync(
 | `schedule_cron` | `str` | `None` | Optional cron expression (e.g., `"*/15 * * * *"`). If set, runs an infinite scheduler loop. |
 | `export_json` | `str` | `None` | Optional. Path to compile and export a consolidated history JSON for the frontend. |
 | `export_public_only` | `bool` | `True` | Security firewall: if `True`, strips private repository data from the compiled `export_json`. |
+| `metrics` | `list` | `None` | Optional. List of metrics to sync (e.g., `["views", "clones"]`). |
 
 ---
 
@@ -279,16 +282,33 @@ gitlytics.serve_dashboard(
 
 ## 📊 CSV Output Columns
 
-When you sync data, the local CSV databases track 13 detailed metrics:
-
-| Column | Description | Column | Description |
-|---|---|---|---|
-| `repository` | Full repo name (`user/repo`) | `stars` | Current star count |
-| `is_private` | `True` / `False` | `forks` | Current fork count |
-| `views` | Page views today | `unique_visitors` | Unique visitors today |
-| `clones` | Clone count today | `unique_cloners` | Unique cloners today |
-| `top_referrer` | Highest-traffic referral source | `top_referrer_views` | Views from top referrer |
-| `top_path` | Most visited path | `top_path_views` | Views for top path |
+When you sync data, the local CSV databases track 23 detailed metrics by default. If you customize the metrics using the `--metrics` CLI flag or `metrics` Python parameter, the CSV columns will dynamically include only the columns corresponding to your selection (along with the default `date`, `repository`, and `is_private` identification columns).
+
+| Column | Type | Description |
+|---|---|---|
+| `date` | `str` | ISO date (`YYYY-MM-DD`) for this day's traffic snapshot. |
+| `repository` | `str` | Full GitHub repository name (`owner/repo`). |
+| `is_private` | `bool` | `True` if repository is private, `False` otherwise. |
+| `views` | `int` | Total page views on this day. |
+| `unique_visitors` | `int` | Unique visitors on this day. |
+| `clones` | `int` | Total git clone operations on this day. |
+| `unique_cloners` | `int` | Unique clone clients on this day. |
+| `stars` | `int` | Current total star count snapshot. |
+| `forks` | `int` | Current total fork count snapshot. |
+| `language` | `str` | Primary programming language of the repository. |
+| `topics` | `str` | JSON array containing repository tags/topics. |
+| `watchers_count` | `int` | Total watchers of the repository. |
+| `pushed_at` | `str` | Last push ISO timestamp. |
+| `created_at` | `str` | Repository creation ISO timestamp. |
+| `open_issues_count` | `int` | Total number of open issues. |
+| `top_referrer` | `str` | Top external traffic referral source (14-day rolling window). |
+| `top_referrer_views` | `int` | Views sent by the top referrer. |
+| `top_referrer_uniques` | `int` | Uniques sent by the top referrer. |
+| `_raw_referrers` | `str` | Raw JSON array of all referral sources. |
+| `top_path` | `str` | Most visited repository file path (14-day rolling window). |
+| `top_path_views` | `int` | Views for the top path. |
+| `top_path_uniques` | `int` | Uniques for the top path. |
+| `_raw_paths` | `str` | Raw JSON array of all popular paths. |
 
 ---
 

{gitlytics-0.1.5 → gitlytics-0.1.6}/README.md

@@ -1,8 +1,8 @@
 <div align="center">
 
-<img src="./assets/logo.png" alt="Gitlytics Logo" width="150" />
+<img src="https://raw.githubusercontent.com/ameyac11/gitlytics/main/assets/logo.png" alt="Gitlytics Logo" width="150" />
 
-# <span style="color: #F05032">Git</span>lytics
+# Gitlytics
 ### GitHub Traffic Analytics & Automation 
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
@@ -15,6 +15,8 @@
 [![Live](https://img.shields.io/badge/Live%20Demo-dashboard.gitlytics.dev-success)](https://dashboard.gitlytics.dev)
 [![Docs](https://img.shields.io/badge/Docs-docs.gitlytics.dev-success)](https://docs.gitlytics.dev)
 
+<br/>Please consider giving this project a ⭐ if you find it helpful! <br/>
+
 **Beautiful GitHub traffic analytics for all your repositories — public and private.** <br/> Track views, clones, referrers, and popular paths indefinitely.
 
 ✨ **[Try the live dashboard at dashboard.gitlytics.dev](https://dashboard.gitlytics.dev)** ✨  
@@ -24,22 +26,16 @@
 
 > **🐍 Native Python API**
 > 
-> You can import Gitlytics natively into your own Python applications to build custom integrations, run custom cron workflows, or serve the dashboard programmatically on your own cloud servers.
+> You can import Gitlytics natively into your own Python applications to fetch live repository data like views, clones, stars, and referrers. Build custom integrations, run custom cron workflows, or serve the dashboard programmatically on your own cloud servers.
 > 
 > 📚 **[Read the Full API Documentation](https://docs.gitlytics.dev)**
 
-Please consider giving this project a ⭐ if you find it helpful!
-
 </div>
 
 ---
 
 <div align="center">
-  <img src="https://raw.githubusercontent.com/ameyac11/gitlytics/main/assets/gitlytics_thumbnail_1.png" width="49%" />
-  <img src="https://raw.githubusercontent.com/ameyac11/gitlytics/main/assets/gitlytics_thumbnail_2.png" width="49%" />
-</div>
-<div align="center">
-  <img src="https://raw.githubusercontent.com/ameyac11/gitlytics/main/assets/gitlytics_thumbnail_3.png" width="98.5%" />
+  <img src="https://raw.githubusercontent.com/ameyac11/gitlytics/main/assets/gitlytics_thumbnail_1.png" width="100%" />
 </div>
 
 ---
@@ -68,7 +64,7 @@ Please consider giving this project a ⭐ if you find it helpful!
 
 The full Gitlytics ecosystem spans across a few repositories. If you are looking for the live web dashboard or the automation cron job, check out the links below:
 
-- **[<span style="color: #F05032">Git</span>lytics Web Ecosystem](https://github.com/ameyac11/gitlytics-deployement)**: The production homepage, React Dashboard, and VitePress documentation site.
+- **[Gitlytics Web Ecosystem](https://github.com/ameyac11/gitlytics-deployement)**: The production landing page, React Dashboard, and React Documentation site.
 - ⚙️ **[Gitlytics Automation](https://github.com/ameyac11/gitlytics-github-traffic-automation)**: The GitHub Action companion tool that automates fetching and saving to defeat GitHub's 14-day traffic limit.
 
 ---
@@ -114,6 +110,9 @@ Gitlytics is powered by 3 massive command-line tools. You can run them anywhere
 Fetch your live 14-day traffic and print a beautiful ASCII table directly in your console.
 ```bash
 gitlytics fetch --token ghp_your_token_here --print-table
+
+# Fetch specific metrics only (e.g., views and clones)
+gitlytics fetch --token ghp_your_token_here --print-table --metrics views clones
 ```
 
 ### 2️⃣ `gitlytics sync` (Background Database Cron)
@@ -122,6 +121,9 @@ Tired of losing data? Use `sync` to permanently append today's traffic to a CSV
 # Sync once
 gitlytics sync --token ghp_your_token --data-dir ./data
 
+# Sync specific metrics only
+gitlytics sync --token ghp_your_token --data-dir ./data --metrics views clones
+
 # Run permanently in the background as a cron job (runs at 11:00 PM every day)
 gitlytics sync --token ghp_your_token --data-dir ./data --schedule-cron "0 23 * * *"
 ```
@@ -179,6 +181,7 @@ gitlytics.fetch_traffic(
 | `print_table` | `bool` | `False` | If `True`, formats and prints a detailed ASCII traffic table to the console. |
 | `return_format` | `str` | `"dataframe"` | The format of returned data: `"dataframe"` (Pandas DataFrame), `"timeseries"` (chart-ready nested dict), or `"summary"` (per-repo totals dict). |
 | `save_file` | `str` | `None` | Optional. File path where the fetched data will be saved (CSV or JSON). |
+| `metrics` | `list` | `None` | Optional. List of metrics to fetch (e.g., `["views", "clones"]`). |
 
 ---
 
@@ -215,6 +218,7 @@ gitlytics.sync(
 | `schedule_cron` | `str` | `None` | Optional cron expression (e.g., `"*/15 * * * *"`). If set, runs an infinite scheduler loop. |
 | `export_json` | `str` | `None` | Optional. Path to compile and export a consolidated history JSON for the frontend. |
 | `export_public_only` | `bool` | `True` | Security firewall: if `True`, strips private repository data from the compiled `export_json`. |
+| `metrics` | `list` | `None` | Optional. List of metrics to sync (e.g., `["views", "clones"]`). |
 
 ---
 
@@ -246,16 +250,33 @@ gitlytics.serve_dashboard(
 
 ## 📊 CSV Output Columns
 
-When you sync data, the local CSV databases track 13 detailed metrics:
-
-| Column | Description | Column | Description |
-|---|---|---|---|
-| `repository` | Full repo name (`user/repo`) | `stars` | Current star count |
-| `is_private` | `True` / `False` | `forks` | Current fork count |
-| `views` | Page views today | `unique_visitors` | Unique visitors today |
-| `clones` | Clone count today | `unique_cloners` | Unique cloners today |
-| `top_referrer` | Highest-traffic referral source | `top_referrer_views` | Views from top referrer |
-| `top_path` | Most visited path | `top_path_views` | Views for top path |
+When you sync data, the local CSV databases track 23 detailed metrics by default. If you customize the metrics using the `--metrics` CLI flag or `metrics` Python parameter, the CSV columns will dynamically include only the columns corresponding to your selection (along with the default `date`, `repository`, and `is_private` identification columns).
+
+| Column | Type | Description |
+|---|---|---|
+| `date` | `str` | ISO date (`YYYY-MM-DD`) for this day's traffic snapshot. |
+| `repository` | `str` | Full GitHub repository name (`owner/repo`). |
+| `is_private` | `bool` | `True` if repository is private, `False` otherwise. |
+| `views` | `int` | Total page views on this day. |
+| `unique_visitors` | `int` | Unique visitors on this day. |
+| `clones` | `int` | Total git clone operations on this day. |
+| `unique_cloners` | `int` | Unique clone clients on this day. |
+| `stars` | `int` | Current total star count snapshot. |
+| `forks` | `int` | Current total fork count snapshot. |
+| `language` | `str` | Primary programming language of the repository. |
+| `topics` | `str` | JSON array containing repository tags/topics. |
+| `watchers_count` | `int` | Total watchers of the repository. |
+| `pushed_at` | `str` | Last push ISO timestamp. |
+| `created_at` | `str` | Repository creation ISO timestamp. |
+| `open_issues_count` | `int` | Total number of open issues. |
+| `top_referrer` | `str` | Top external traffic referral source (14-day rolling window). |
+| `top_referrer_views` | `int` | Views sent by the top referrer. |
+| `top_referrer_uniques` | `int` | Uniques sent by the top referrer. |
+| `_raw_referrers` | `str` | Raw JSON array of all referral sources. |
+| `top_path` | `str` | Most visited repository file path (14-day rolling window). |
+| `top_path_views` | `int` | Views for the top path. |
+| `top_path_uniques` | `int` | Uniques for the top path. |
+| `_raw_paths` | `str` | Raw JSON array of all popular paths. |
 
 ---
 

{gitlytics-0.1.5 → gitlytics-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitlytics"
-version = "0.1.5"
+version = "0.1.6"
 description = "Monitor and automate your GitHub repository traffic analytics."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -51,7 +51,6 @@ dev = [
     "pytest>=8.0.0",
     "pytest-cov>=5.0.0",
     "httpx>=0.27.0",      # required by FastAPI TestClient (used in test_api.py)
-    "Faker>=20.0.0",      # used by pytest-faker plugin for generating test data
     "anyio[trio]>=4.0.0"  # async test support
 ]
 

{gitlytics-0.1.5 → gitlytics-0.1.6}/src/gitlytics/__init__.py

@@ -8,7 +8,9 @@ import json
 
 # Single source of truth for the package version.
 # Mirrors the version in pyproject.toml — keep them in sync.
-__version__ = "0.1.5"
+__version__ = "0.1.6"
+
+__all__ = ["fetch_traffic", "sync", "serve_dashboard", "__version__"]
 
 # Import the internal building blocks — users never call these directly
 from .core import fetch_traffic_data, print_repo_table
@@ -20,7 +22,7 @@ logger = logging.getLogger(__name__)
 logger.addHandler(logging.NullHandler())
 
 
-def fetch_traffic(token: str, repo_name=None, print_table: bool = False, return_format: str = "dataframe", save_file: str = None):
+def fetch_traffic(token: str, repo_name=None, print_table: bool = False, return_format: str = "dataframe", save_file: str = None, metrics: list = None):
     """
     Fetches the last 14 days of traffic data for one or all repositories.
 
@@ -35,13 +37,14 @@ def fetch_traffic(token: str, repo_name=None, print_table: bool = False, return_
             ``"summary"`` — returns a per-repo totals dict.
         save_file: Optional path to save the output. Extension determines
             format: ``.json`` writes JSON, anything else writes CSV.
+        metrics: Optional list of metrics to fetch (e.g., ``["views", "clones"]``).
 
     Returns:
         A ``pandas.DataFrame`` when ``return_format="dataframe"``, otherwise
         a ``dict`` matching the requested format.
     """
     # Hit the GitHub API and get back a tidy DataFrame (one row per day per repo)
-    df = fetch_traffic_data(token, repo_name)
+    df = fetch_traffic_data(token, repo_name, metrics)
 
     # Print the ASCII table to the console if the user asked for it
     if print_table:
@@ -79,7 +82,7 @@ def fetch_traffic(token: str, repo_name=None, print_table: bool = False, return_
     return payload
 
 
-def sync(token: str, repo_name=None, data_dir: str = "./data", output_mode: str = "monthly", schedule_cron: str = None, export_json: str = None, export_public_only: bool = True):
+def sync(token: str, repo_name=None, data_dir: str = "./data", output_mode: str = "monthly", schedule_cron: str = None, export_json: str = None, export_public_only: bool = True, metrics: list = None):
     """
     Fetches data and appends it to a local CSV database, optionally running as a permanent background daemon.
 
@@ -93,6 +96,7 @@ def sync(token: str, repo_name=None, data_dir: str = "./data", output_mode: str
         export_json: Path to export the merged historical database as a JSON file.
         export_public_only: If ``True`` (default), strips private repos from the
             exported JSON — acts as a security firewall.
+        metrics: Optional list of metrics to fetch (e.g., ``["views", "clones"]``).
     """
     # Hand off to the automation engine — it handles deduplication and schema migration
     run_sync(
@@ -102,7 +106,8 @@ def sync(token: str, repo_name=None, data_dir: str = "./data", output_mode: str
         output_mode=output_mode,
         schedule_cron=schedule_cron,
         export_json=export_json,
-        export_public_only=export_public_only
+        export_public_only=export_public_only,
+        metrics=metrics
     )
 
 
@@ -130,11 +135,21 @@ def serve_dashboard(host: str = "127.0.0.1", port: int = 8000, token: str = None
             "Install them with: pip install \"gitlytics[dashboard]\""
         )
 
-    # Pass the token and data folder to the FastAPI app via environment variables
-    if token:
-        os.environ["GITLYTICS_TOKEN"] = token
-    if data_dir:
-        os.environ["GITLYTICS_DATA_DIR"] = os.path.abspath(data_dir)
-
-    # Start the web server — it won't return until the user presses Ctrl+C
-    uvicorn.run("gitlytics.api:app", host=host, port=port, reload=False)
+    # M-7: save original values so they are restored when the server stops
+    _orig_token = os.environ.get("GITLYTICS_TOKEN")
+    _orig_data_dir = os.environ.get("GITLYTICS_DATA_DIR")
+    try:
+        if token:
+            os.environ["GITLYTICS_TOKEN"] = token
+        if data_dir:
+            os.environ["GITLYTICS_DATA_DIR"] = os.path.abspath(data_dir)
+        uvicorn.run("gitlytics.api:app", host=host, port=port, reload=False)
+    finally:
+        if _orig_token is None:
+            os.environ.pop("GITLYTICS_TOKEN", None)
+        else:
+            os.environ["GITLYTICS_TOKEN"] = _orig_token
+        if _orig_data_dir is None:
+            os.environ.pop("GITLYTICS_DATA_DIR", None)
+        else:
+            os.environ["GITLYTICS_DATA_DIR"] = _orig_data_dir

{gitlytics-0.1.5 → gitlytics-0.1.6}/src/gitlytics/api.py

@@ -2,8 +2,10 @@
 gitlytics/api.py
 Powers the FastAPI backend — serves traffic data and the React dashboard to the browser.
 """
+import hashlib
 import logging
 import os
+import time as _time
 from pathlib import Path
 
 import pandas as pd
@@ -12,14 +14,21 @@ from fastapi.responses import FileResponse, JSONResponse
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.staticfiles import StaticFiles
 
-from gitlytics.core import validate_token, get_user_profile, fetch_traffic_data
+from gitlytics.core import (
+    validate_token,
+    get_user_profile,
+    get_public_user,
+    get_public_repos,
+    fetch_traffic_data,
+    fetch_deep_stats_for_top,
+)
 from gitlytics.process import process_uploaded_csv, build_react_payload
 
 logger = logging.getLogger(__name__)
 
 app = FastAPI(title="GitHub Traffic API")
 
-# Only allow requests from localhost — this dashboard is never deployed publicly
+# Only allow requests from localhost — never deployed publicly
 _ALLOWED_ORIGINS = [
     "http://localhost",
     "http://localhost:3000",
@@ -40,14 +49,33 @@ app.add_middleware(
 )
 
 
+_auth_cache: dict = {}  # sha256_prefix -> (valid, username, expires_at)
+_AUTH_CACHE_TTL = 300  # 5 minutes
+
+
 def _get_token(token: str = None) -> str:
-    # Use the token from the request body, or fall back to the one set in the environment
-    return token or os.environ.get("GITLYTICS_TOKEN")
+    # C-2: explicit empty string must not fall through to the env token
+    if token and token.strip():
+        return token.strip()
+    return os.environ.get("GITLYTICS_TOKEN")
+
+
+def _validate_token_cached(token: str):
+    # M-1: cache validation results to avoid a double HTTP round-trip on every /api/traffic call
+    key = hashlib.sha256(token.encode()).hexdigest()[:16]
+    now = _time.time()
+    if key in _auth_cache:
+        valid, username, expires = _auth_cache[key]
+        if now < expires:
+            return valid, username
+    from gitlytics.core import validate_token
+    valid, username = validate_token(token)
+    _auth_cache[key] = (valid, username, now + _AUTH_CACHE_TTL)
+    return valid, username
 
 
 @app.get("/api/config")
 def get_config():
-    # Lets the frontend know if it's running in headless/TV mode with a pre-set token
     return {
         "has_token": bool(os.environ.get("GITLYTICS_TOKEN")),
         "has_data_dir": bool(os.environ.get("GITLYTICS_DATA_DIR"))
@@ -63,21 +91,39 @@ def auth(token: str = Body("", embed=True)):
 
     ok, username = validate_token(active_token)
     if not ok:
-        # Log a warning without echoing the token value into logs
         logger.warning("Authentication attempt failed for a provided token.")
         raise HTTPException(status_code=401, detail=username)
 
-    # Fetch the real display name and avatar URL — validate_token only gives us the login
     profile = get_user_profile(active_token)
 
     return {
         "authenticated": True,
         "username": profile["login"] or username,
-        "name": profile["name"] or username,        # Real display name, e.g. "Ameya Chopade"
-        "avatar_url": profile["avatar_url"],         # Real GitHub avatar URL
+        "name": profile["name"] or username,
+        "avatar_url": profile["avatar_url"],
+        "bio": profile.get("bio"),
+        "location": profile.get("location"),
+        "followers": profile.get("followers", 0),
+        "following": profile.get("following", 0),
     }
 
 
+@app.post("/api/username")
+def get_username_data(username: str = Body("", embed=True)):
+    """Fetches public profile and repos for any GitHub username — no token required."""
+    if not username or not username.strip():
+        raise HTTPException(status_code=400, detail="Username is required.")
+    try:
+        profile = get_public_user(username.strip())
+        repos = get_public_repos(username.strip())
+        return {"profile": profile, "repos": repos}
+    except ValueError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    except Exception as exc:
+        logger.warning(f"Username fetch failed for {username}: {exc}")
+        raise HTTPException(status_code=500, detail="Failed to fetch GitHub data.")
+
+
 @app.post("/api/traffic")
 def get_traffic(token: str = Body("", embed=True)):
     # Serve traffic data — either from the historical CSV database or live from GitHub
@@ -85,13 +131,11 @@ def get_traffic(token: str = Body("", embed=True)):
     if not active_token:
         raise HTTPException(status_code=401, detail="No token provided")
 
-    ok, _ = validate_token(active_token)
+    ok, _ = _validate_token_cached(active_token)
     if not ok:
         raise HTTPException(status_code=401, detail="Invalid token")
-
     data_dir = os.environ.get("GITLYTICS_DATA_DIR")
     if data_dir:
-        # Load from the historical CSV database (headless/TV mode)
         data_dir_path = Path(data_dir)
         csv_files = list(data_dir_path.glob("traffic_*.csv")) if data_dir_path.exists() else []
         dfs = []
@@ -102,43 +146,47 @@ def get_traffic(token: str = Body("", embed=True)):
                 logger.warning(f"Skipping unreadable CSV '{f}': {exc}")
         if dfs:
             df = pd.concat(dfs, ignore_index=True)
-            # Clean up any duplicate day-repo rows that crept in somehow
             df = df.drop_duplicates(subset=["date", "repository"], keep="last")
         else:
-            # No CSVs found — fall through to a live fetch
             df = fetch_traffic_data(active_token)
     else:
-        # Default: hit GitHub and get the live 14-day window
         df = fetch_traffic_data(active_token)
 
-    # Replace any infinity or NaN values before JSON serialisation
     df = df.replace([float('inf'), float('-inf')], None).where(pd.notnull(df), None)
 
-    # Transform the DataFrame into the array of objects the React app expects
-    payload = build_react_payload(df)
+    # Build a quick view-sum map to find the top 20 repos for deep fetching
+    repos_with_views = []
+    if not df.empty and "repository" in df.columns and "views" in df.columns:
+        for repo_name, group in df.groupby("repository"):
+            repos_with_views.append({"repository": repo_name, "total_views": int(group["views"].sum())})
+
+    # Fetch deep stats concurrently for the top 20 most-viewed repos
+    deep_stats = {}
+    if repos_with_views and active_token:
+        deep_stats = fetch_deep_stats_for_top(active_token, repos_with_views, top_n=20)
+
+    payload = build_react_payload(df, deep_stats=deep_stats)
     return payload
 
 
 @app.post("/api/upload-csv")
 def upload_csv(file: UploadFile = File(...)):
-    # Accept a user-uploaded CSV and convert it to the same format as the API response
+    # Accept a user-uploaded CSV — deep stats not available in CSV mode
     try:
         df = process_uploaded_csv(file.file)
         df = df.replace([float('inf'), float('-inf')], None).where(pd.notnull(df), None)
-        payload = build_react_payload(df)
+        payload = build_react_payload(df, deep_stats=None)
         return payload
     except Exception as e:
         raise HTTPException(status_code=400, detail=str(e))
 
 
-# ── Static file serving ───────────────────────────────────────────────────────
-# The React build output lands in gitlytics/static/ after `npm run build`
+# Static file serving
 frontend_dir = Path(__file__).parent / "static"
 
 
 @app.get("/")
 def serve_index():
-    # Serve the React app's index.html for the root URL
     index_file = frontend_dir / "index.html"
     if index_file.exists():
         return FileResponse(index_file)
@@ -150,17 +198,11 @@ def serve_index():
 
 @app.get("/{full_path:path}")
 def serve_spa_fallback(full_path: str):
-    """
-    SPA catch-all — any URL that doesn't match an API route returns index.html
-    so React Router can handle client-side navigation on hard refresh.
-    Real static assets (JS/CSS) are served by the StaticFiles mount first.
-    """
-    # Serve the actual file if it exists (e.g. a JS or CSS asset)
+    """SPA catch-all — returns index.html so React Router handles navigation."""
     asset_file = frontend_dir / full_path
     if asset_file.exists() and asset_file.is_file():
         return FileResponse(asset_file)
 
-    # For everything else (like /repos/my-repo), hand control to React Router
     index_file = frontend_dir / "index.html"
     if index_file.exists():
         return FileResponse(index_file)
@@ -171,7 +213,6 @@ def serve_spa_fallback(full_path: str):
     )
 
 
-# Mount the /assets directory for compiled JS and CSS — must come after route definitions
 assets_dir = frontend_dir / "assets"
 if assets_dir.exists():
     app.mount("/assets", StaticFiles(directory=assets_dir), name="assets")