widget lib changes

app/main.py

@@ -22,6 +22,7 @@ from app.events.controllers.router import router as events_router
 from app.reports.controllers.router import router as reports_router
 from app.dashboard.controllers.router import router as dashboard_router
 from app.kpi_cache.controllers.router import router as kpi_cache_router
+from app.widget_collection.router import router as widget_collection_router
 
 # Init logging
 setup_logging(level=settings.LOG_LEVEL.strip().upper())
@@ -45,6 +46,9 @@ async def lifespan(app: FastAPI):
     )
     await kpi_col.create_index([("merchant_id", 1)], background=True, name="kpi_cache_merchant_id")
     await kpi_col.create_index([("expires_at", 1)], background=True, name="kpi_cache_expires_at")
+    # Ensure MongoDB index for analytics_widget_collection
+    wc_col = db["analytics_widget_collection"]
+    await wc_col.create_index("widget_id", unique=True, background=True, name="widget_id_unique")
     logger.info("Analytics Microservice started", extra={"event": "service_ready"})
     yield
     logger.info("Shutting down Analytics Microservice", extra={"event": "service_stopping"})
@@ -133,6 +137,7 @@ app.include_router(events_router)
 app.include_router(reports_router)
 app.include_router(dashboard_router)
 app.include_router(kpi_cache_router)
+app.include_router(widget_collection_router)
 
 
 @app.get("/health", tags=["health"])

app/widget_collection/__init__.py

@@ -0,0 +1 @@
+# widget_collection module

app/widget_collection/model.py

@@ -0,0 +1,22 @@
+"""MongoDB document model for analytics_widget_collection."""
+from typing import Any, Dict, Optional
+from pydantic import BaseModel
+
+
+class DataConfig(BaseModel):
+    source: str
+    params: Dict[str, Any] = {}
+
+
+class WidgetCollectionDocument(BaseModel):
+    widget_id: str
+    type: str = "kpi"
+    title: str
+    category: str
+    unit: Optional[str] = None
+    description: Optional[str] = None
+    drill_down_url: Optional[str] = None
+    data_config: DataConfig
+
+    class Config:
+        populate_by_name = True

app/widget_collection/router.py

@@ -0,0 +1,70 @@
+"""FastAPI router for widget_collection endpoints."""
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from app.core.logging import get_logger
+from app.dependencies.auth import get_current_user, TokenUser
+from app.dependencies.kpi_permissions import require_dashboard_view
+from app.widget_collection.schemas import ListWidgetCollectionRequest, UpdateWidgetRolesRequest
+from app.widget_collection.service import WidgetCollectionService
+
+logger = get_logger(__name__)
+
+router = APIRouter(prefix="/widget-collection", tags=["Widget Collection"])
+
+
+@router.post("/list")
+async def list_widgets(
+    payload: ListWidgetCollectionRequest,
+    current_user: TokenUser = Depends(require_dashboard_view),
+):
+    """
+    List widget collection documents with optional projection_list.
+    Requires: permissions.dashboard.view
+    """
+    filters: dict = {}
+    if payload.filters:
+        if payload.filters.category:
+            filters["category"] = payload.filters.category
+        if payload.filters.type:
+            filters["type"] = payload.filters.type
+
+    docs = await WidgetCollectionService.list_widgets(
+        filters=filters,
+        skip=payload.skip,
+        limit=payload.limit,
+        projection_list=payload.projection_list,
+    )
+    return {"success": True, "data": docs, "count": len(docs)}
+
+
+@router.get("/{widget_id}")
+async def get_widget(
+    widget_id: str,
+    current_user: TokenUser = Depends(require_dashboard_view),
+):
+    """Fetch a single widget config document by widget_id."""
+    doc = await WidgetCollectionService.get_widget(widget_id)
+    if not doc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Widget not found")
+    return {"success": True, "data": doc}
+
+
+@router.put("/{widget_id}")
+async def update_widget(
+    widget_id: str,
+    payload: UpdateWidgetRolesRequest,
+    current_user: TokenUser = Depends(require_dashboard_view),
+):
+    """Update data_config for a widget."""
+    update_data: dict = {}
+    if payload.data_config is not None:
+        update_data["data_config"] = payload.data_config
+
+    if not update_data:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Nothing to update")
+
+    updated = await WidgetCollectionService.update_widget(widget_id, update_data)
+    if not updated:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Widget not found")
+
+    return {"success": True, "message": "Widget updated"}

app/widget_collection/schemas.py

@@ -0,0 +1,22 @@
+"""Request/response schemas for widget_collection endpoints."""
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class WidgetCollectionFilters(BaseModel):
+    category: Optional[str] = None
+    type: Optional[str] = None
+
+
+class ListWidgetCollectionRequest(BaseModel):
+    filters: Optional[WidgetCollectionFilters] = None
+    skip: int = Field(0, ge=0)
+    limit: int = Field(100, ge=1, le=500)
+    projection_list: Optional[List[str]] = Field(
+        None,
+        description="List of fields to include in response"
+    )
+
+
+class UpdateWidgetRolesRequest(BaseModel):
+    data_config: Optional[Dict[str, Any]] = None

app/widget_collection/service.py

@@ -0,0 +1,62 @@
+"""CRUD service for analytics_widget_collection MongoDB collection."""
+from typing import Any, Dict, List, Optional
+
+from app.nosql import get_database
+from app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+COLLECTION = "analytics_widget_collection"
+
+
+class WidgetCollectionService:
+
+    @staticmethod
+    async def list_widgets(
+        filters: Dict[str, Any],
+        skip: int = 0,
+        limit: int = 100,
+        projection_list: Optional[List[str]] = None,
+    ) -> List[Any]:
+        db = get_database()
+        col = db[COLLECTION]
+
+        projection: Optional[Dict[str, int]] = None
+        if projection_list:
+            projection = {field: 1 for field in projection_list}
+            projection["_id"] = 0
+
+        cursor = col.find(filters, projection).skip(skip).limit(limit)
+        docs = await cursor.to_list(length=limit)
+
+        if projection_list:
+            return docs
+
+        # Strip MongoDB _id for clean output
+        for doc in docs:
+            doc.pop("_id", None)
+        return docs
+
+    @staticmethod
+    async def get_widget(widget_id: str) -> Optional[Dict[str, Any]]:
+        db = get_database()
+        col = db[COLLECTION]
+        doc = await col.find_one({"widget_id": widget_id}, {"_id": 0})
+        return doc
+
+    @staticmethod
+    async def update_widget(widget_id: str, update_data: Dict[str, Any]) -> bool:
+        db = get_database()
+        col = db[COLLECTION]
+        result = await col.update_one({"widget_id": widget_id}, {"$set": update_data})
+        return result.matched_count > 0
+
+    @staticmethod
+    async def upsert_widget(doc: Dict[str, Any]) -> None:
+        db = get_database()
+        col = db[COLLECTION]
+        await col.update_one(
+            {"widget_id": doc["widget_id"]},
+            {"$set": doc},
+            upsert=True,
+        )

scripts/seed_widget_collection.py

@@ -0,0 +1,66 @@
+"""
+Seed script — populates analytics_widget_collection in MongoDB.
+
+Derives all documents from KPI_WIDGET_REGISTRY (single source of truth).
+Run from the analytics-ms root:
+    python -m scripts.seed_widget_collection
+"""
+import asyncio
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from app.core.config import settings  # noqa: E402
+from app.nosql import connect_to_mongo, close_mongo_connection, get_database  # noqa: E402
+from app.kpi_cache.constants import KPI_WIDGET_REGISTRY  # noqa: E402
+
+COLLECTION = "dashboard_widgets"
+
+
+def _build_document(widget_id: str, meta: dict) -> dict:
+    return {
+        "widget_id": widget_id,
+        "type": "kpi",
+        "title": meta.get("title", widget_id),
+        "category": meta.get("category", ""),
+        "unit": meta.get("unit"),
+        "description": meta.get("description"),
+        "drill_down_url": meta.get("drill_down_url"),
+        "data_config": {
+            "source": "merchant_kpi_stats",
+            "params": {
+                "widget": widget_id,
+                "period_window": "mtd",
+                "unit": meta.get("unit", "count"),
+            },
+        },
+    }
+
+
+async def seed():
+    await connect_to_mongo()
+    db = get_database()
+    col = db[COLLECTION]
+
+    # Ensure unique index on widget_id
+    await col.create_index("widget_id", unique=True, background=True, name="widget_id_unique")
+
+    docs = [_build_document(wid, meta) for wid, meta in KPI_WIDGET_REGISTRY.items()]
+
+    upserted = 0
+    for doc in docs:
+        result = await col.update_one(
+            {"widget_id": doc["widget_id"]},
+            {"$set": doc},
+            upsert=True,
+        )
+        if result.upserted_id or result.modified_count:
+            upserted += 1
+
+    print(f"Seeded {upserted}/{len(docs)} widget collection documents into '{COLLECTION}'.")
+    await close_mongo_connection()
+
+
+if __name__ == "__main__":
+    asyncio.run(seed())