core/api_client_reports.py

"""Reports & Action Items API methods for ChainShiftClient.

Mixin class extracted from api_client.py.
Methods access self._get, self._post, self._patch, self._delete, self.base_url from the parent class.
"""


class ReportsApiMixin:
    """Reports (HTML, data) and Action Items APIs."""

    # ========================================================================
    # Reports API (HTML Report Generation)
    # ========================================================================

    def get_report_overview(
        self, campaign_id: int, start_date: str | None = None, end_date: str | None = None,
    ) -> dict:
        """GET /api/v1/reports/{campaign_id}/overview"""
        params = {}
        if start_date:
            params["start_date"] = start_date
        if end_date:
            params["end_date"] = end_date
        return self._get(f"/api/v1/reports/{campaign_id}/overview", params or None)

    def get_report_visibility(
        self, campaign_id: int, start_date: str | None = None, end_date: str | None = None,
    ) -> dict:
        """GET /api/v1/reports/{campaign_id}/visibility"""
        params = {}
        if start_date:
            params["start_date"] = start_date
        if end_date:
            params["end_date"] = end_date
        return self._get(f"/api/v1/reports/{campaign_id}/visibility", params or None)

    def get_report_citations(
        self, campaign_id: int, start_date: str | None = None,
        end_date: str | None = None, limit: int = 30,
    ) -> dict:
        """GET /api/v1/reports/{campaign_id}/citations"""
        params: dict = {"limit": limit}
        if start_date:
            params["start_date"] = start_date
        if end_date:
            params["end_date"] = end_date
        return self._get(f"/api/v1/reports/{campaign_id}/citations", params)

    def get_report_citation_trends(
        self, campaign_id: int, start_date: str | None = None,
        end_date: str | None = None, limit: int = 20,
    ) -> dict:
        """GET /api/v1/reports/{campaign_id}/citation-trends"""
        params: dict = {"limit": limit}
        if start_date:
            params["start_date"] = start_date
        if end_date:
            params["end_date"] = end_date
        return self._get(f"/api/v1/reports/{campaign_id}/citation-trends", params)

    def get_report_content_types(
        self, campaign_id: int, start_date: str | None = None, end_date: str | None = None,
    ) -> dict:
        """GET /api/v1/reports/{campaign_id}/content-types"""
        params = {}
        if start_date:
            params["start_date"] = start_date
        if end_date:
            params["end_date"] = end_date
        return self._get(f"/api/v1/reports/{campaign_id}/content-types", params or None)

    def get_report_sentiment(self, campaign_id: int) -> dict:
        """GET /api/v1/reports/{campaign_id}/sentiment"""
        return self._get(f"/api/v1/reports/{campaign_id}/sentiment")

    def get_report_homepage_citations(
        self, campaign_id: int, start_date: str | None = None,
        end_date: str | None = None, homepage_urls: str | None = None,
    ) -> dict:
        """GET /api/v1/reports/{campaign_id}/homepage-citations"""
        params = {}
        if start_date:
            params["start_date"] = start_date
        if end_date:
            params["end_date"] = end_date
        if homepage_urls:
            params["homepage_urls"] = homepage_urls
        return self._get(f"/api/v1/reports/{campaign_id}/homepage-citations", params or None)

    def generate_html_report(
        self,
        campaign_id: int,
        start_date: str | None = None,
        end_date: str | None = None,
        features: list[str] | None = None,
        enable_insights: bool = False,
        output_mode: str = "url",
    ) -> dict:
        """Generate HTML report. POST /api/v1/reports/{campaign_id}/html"""
        body: dict = {"output_mode": output_mode, "enable_insights": enable_insights}
        if start_date:
            body["start_date"] = start_date
        if end_date:
            body["end_date"] = end_date
        if features:
            body["features"] = features
        return self._post(f"/api/v1/reports/{campaign_id}/html", body)

    def build_html_feature(
        self,
        campaign_id: int,
        feature: str,
        start_date: str | None = None,
        end_date: str | None = None,
        enable_insights: bool = False,
        enable_action_items: bool = False,
        homepage_urls: list[str] | None = None,
        period: str = "1w",
    ) -> dict:
        """Build a single report feature. POST /api/v1/reports/{campaign_id}/html/build-feature"""
        body: dict = {"feature": feature, "enable_insights": enable_insights, "period": period}
        if start_date:
            body["start_date"] = start_date
        if end_date:
            body["end_date"] = end_date
        if enable_action_items:
            body["enable_action_items"] = enable_action_items
        if homepage_urls:
            body["homepage_urls"] = homepage_urls
        return self._post(f"/api/v1/reports/{campaign_id}/html/build-feature", body)

    def render_html_report(
        self,
        campaign_id: int,
        features_data: list[dict],
        title: str | None = None,
        subtitle: str | None = None,
        start_date: str | None = None,
        end_date: str | None = None,
        enable_insights: bool = False,
        enable_action_items: bool = False,
        output_mode: str = "url",
    ) -> dict:
        """Assemble and render final HTML report. POST /api/v1/reports/{campaign_id}/html/render"""
        body: dict = {
            "features_data": features_data,
            "output_mode": output_mode,
            "enable_insights": enable_insights,
        }
        if title:
            body["title"] = title
        if subtitle:
            body["subtitle"] = subtitle
        if start_date:
            body["start_date"] = start_date
        if end_date:
            body["end_date"] = end_date
        if enable_action_items:
            body["enable_action_items"] = enable_action_items
        return self._post(f"/api/v1/reports/{campaign_id}/html/render", body)

    def get_html_report_history(self, campaign_id: int, page: int = 1, page_size: int = 20) -> dict:
        """Get HTML report history. GET /api/v1/reports/{campaign_id}/html/history"""
        return self._get(f"/api/v1/reports/{campaign_id}/html/history", {"page": page, "page_size": page_size})

    def get_html_report_detail(self, campaign_id: int, report_id: str) -> dict:
        """Get HTML report detail. GET /api/v1/reports/{campaign_id}/html/{report_id}"""
        return self._get(f"/api/v1/reports/{campaign_id}/html/{report_id}")

    # ========================================================================
    # Action Items APIs (ADR-018 Phase 2)
    # ========================================================================

    def save_action_items(
        self,
        campaign_id: int,
        items: list[dict],
        report_id: str | None = None,
    ) -> dict:
        """Save action items from report. POST /api/v1/action-items"""
        body: dict = {"campaign_id": campaign_id, "items": items}
        if report_id:
            body["report_id"] = report_id
        return self._post("/api/v1/action-items", body)

    def update_action_item(self, item_id: str, data: dict) -> dict:
        """Update action item. PATCH /api/v1/action-items/{item_id}"""
        return self._patch(f"/api/v1/action-items/{item_id}", data)

    def delete_action_item(self, item_id: str) -> dict:
        """Delete action item. DELETE /api/v1/action-items/{item_id}"""
        return self._delete(f"/api/v1/action-items/{item_id}")

    def export_action_item_html(self, item_id: str) -> dict:
        """Export action item as HTML. GET /api/v1/action-items/{item_id}/export/html"""
        return self._get(f"/api/v1/action-items/{item_id}/export/html")