google-mcp/gdocs/docs_helpers.py

"""
Google Docs Helper Functions

This module provides utility functions for common Google Docs operations
to simplify the implementation of document editing tools.
"""

import logging
from typing import Dict, Any, Optional

logger = logging.getLogger(__name__)


def _normalize_color(
    color: Optional[str], param_name: str
) -> Optional[Dict[str, float]]:
    """
    Normalize a user-supplied color into Docs API rgbColor format.

    Supports only hex strings in the form "#RRGGBB".
    """
    if color is None:
        return None

    if not isinstance(color, str):
        raise ValueError(f"{param_name} must be a hex string like '#RRGGBB'")

    if len(color) != 7 or not color.startswith("#"):
        raise ValueError(f"{param_name} must be a hex string like '#RRGGBB'")

    hex_color = color[1:]
    if any(c not in "0123456789abcdefABCDEF" for c in hex_color):
        raise ValueError(f"{param_name} must be a hex string like '#RRGGBB'")

    r = int(hex_color[0:2], 16) / 255
    g = int(hex_color[2:4], 16) / 255
    b = int(hex_color[4:6], 16) / 255
    return {"red": r, "green": g, "blue": b}


def build_text_style(
    bold: bool = None,
    italic: bool = None,
    underline: bool = None,
    font_size: int = None,
    font_family: str = None,
    text_color: str = None,
    background_color: str = None,
    link_url: str = None,
) -> tuple[Dict[str, Any], list[str]]:
    """
    Build text style object for Google Docs API requests.

    Args:
        bold: Whether text should be bold
        italic: Whether text should be italic
        underline: Whether text should be underlined
        font_size: Font size in points
        font_family: Font family name
        text_color: Text color as hex string "#RRGGBB"
        background_color: Background (highlight) color as hex string "#RRGGBB"
        link_url: Hyperlink URL (http/https)

    Returns:
        Tuple of (text_style_dict, list_of_field_names)
    """
    text_style = {}
    fields = []

    if bold is not None:
        text_style["bold"] = bold
        fields.append("bold")

    if italic is not None:
        text_style["italic"] = italic
        fields.append("italic")

    if underline is not None:
        text_style["underline"] = underline
        fields.append("underline")

    if font_size is not None:
        text_style["fontSize"] = {"magnitude": font_size, "unit": "PT"}
        fields.append("fontSize")

    if font_family is not None:
        text_style["weightedFontFamily"] = {"fontFamily": font_family}
        fields.append("weightedFontFamily")

    if text_color is not None:
        rgb = _normalize_color(text_color, "text_color")
        text_style["foregroundColor"] = {"color": {"rgbColor": rgb}}
        fields.append("foregroundColor")

    if background_color is not None:
        rgb = _normalize_color(background_color, "background_color")
        text_style["backgroundColor"] = {"color": {"rgbColor": rgb}}
        fields.append("backgroundColor")

    if link_url is not None:
        text_style["link"] = {"url": link_url}
        fields.append("link")

    return text_style, fields


def build_paragraph_style(
    heading_level: int = None,
    alignment: str = None,
    line_spacing: float = None,
    indent_first_line: float = None,
    indent_start: float = None,
    indent_end: float = None,
    space_above: float = None,
    space_below: float = None,
    named_style_type: str = None,
) -> tuple[Dict[str, Any], list[str]]:
    """
    Build paragraph style object for Google Docs API requests.

    Args:
        heading_level: Heading level 0-6 (0 = NORMAL_TEXT, 1-6 = HEADING_N)
        alignment: Text alignment - 'START', 'CENTER', 'END', or 'JUSTIFIED'
        line_spacing: Line spacing multiplier (1.0 = single, 2.0 = double)
        indent_first_line: First line indent in points
        indent_start: Left/start indent in points
        indent_end: Right/end indent in points
        space_above: Space above paragraph in points
        space_below: Space below paragraph in points
        named_style_type: Direct named style (TITLE, SUBTITLE, HEADING_1..6, NORMAL_TEXT).
                          Takes precedence over heading_level when both are provided.

    Returns:
        Tuple of (paragraph_style_dict, list_of_field_names)
    """
    paragraph_style = {}
    fields = []

    if named_style_type is not None:
        valid_styles = [
            "NORMAL_TEXT", "TITLE", "SUBTITLE",
            "HEADING_1", "HEADING_2", "HEADING_3",
            "HEADING_4", "HEADING_5", "HEADING_6",
        ]
        if named_style_type not in valid_styles:
            raise ValueError(
                f"Invalid named_style_type '{named_style_type}'. "
                f"Must be one of: {', '.join(valid_styles)}"
            )
        paragraph_style["namedStyleType"] = named_style_type
        fields.append("namedStyleType")
    elif heading_level is not None:
        if heading_level < 0 or heading_level > 6:
            raise ValueError("heading_level must be between 0 (normal text) and 6")
        if heading_level == 0:
            paragraph_style["namedStyleType"] = "NORMAL_TEXT"
        else:
            paragraph_style["namedStyleType"] = f"HEADING_{heading_level}"
        fields.append("namedStyleType")

    if alignment is not None:
        valid_alignments = ["START", "CENTER", "END", "JUSTIFIED"]
        alignment_upper = alignment.upper()
        if alignment_upper not in valid_alignments:
            raise ValueError(
                f"Invalid alignment '{alignment}'. Must be one of: {valid_alignments}"
            )
        paragraph_style["alignment"] = alignment_upper
        fields.append("alignment")

    if line_spacing is not None:
        if line_spacing <= 0:
            raise ValueError("line_spacing must be positive")
        paragraph_style["lineSpacing"] = line_spacing * 100
        fields.append("lineSpacing")

    if indent_first_line is not None:
        paragraph_style["indentFirstLine"] = {
            "magnitude": indent_first_line,
            "unit": "PT",
        }
        fields.append("indentFirstLine")

    if indent_start is not None:
        paragraph_style["indentStart"] = {"magnitude": indent_start, "unit": "PT"}
        fields.append("indentStart")

    if indent_end is not None:
        paragraph_style["indentEnd"] = {"magnitude": indent_end, "unit": "PT"}
        fields.append("indentEnd")

    if space_above is not None:
        paragraph_style["spaceAbove"] = {"magnitude": space_above, "unit": "PT"}
        fields.append("spaceAbove")

    if space_below is not None:
        paragraph_style["spaceBelow"] = {"magnitude": space_below, "unit": "PT"}
        fields.append("spaceBelow")

    return paragraph_style, fields


def create_insert_text_request(
    index: int, text: str, tab_id: Optional[str] = None
) -> Dict[str, Any]:
    """
    Create an insertText request for Google Docs API.

    Args:
        index: Position to insert text
        text: Text to insert
        tab_id: Optional ID of the tab to target

    Returns:
        Dictionary representing the insertText request
    """
    location = {"index": index}
    if tab_id:
        location["tabId"] = tab_id
    return {"insertText": {"location": location, "text": text}}


def create_insert_text_segment_request(
    index: int, text: str, segment_id: str, tab_id: Optional[str] = None
) -> Dict[str, Any]:
    """
    Create an insertText request for Google Docs API with segmentId (for headers/footers).

    Args:
        index: Position to insert text
        text: Text to insert
        segment_id: Segment ID (for targeting headers/footers)
        tab_id: Optional ID of the tab to target

    Returns:
        Dictionary representing the insertText request with segmentId and optional tabId
    """
    location = {"segmentId": segment_id, "index": index}
    if tab_id:
        location["tabId"] = tab_id
    return {
        "insertText": {
            "location": location,
            "text": text,
        }
    }


def create_delete_range_request(
    start_index: int, end_index: int, tab_id: Optional[str] = None
) -> Dict[str, Any]:
    """
    Create a deleteContentRange request for Google Docs API.

    Args:
        start_index: Start position of content to delete
        end_index: End position of content to delete
        tab_id: Optional ID of the tab to target

    Returns:
        Dictionary representing the deleteContentRange request
    """
    range_obj = {"startIndex": start_index, "endIndex": end_index}
    if tab_id:
        range_obj["tabId"] = tab_id
    return {"deleteContentRange": {"range": range_obj}}


def create_format_text_request(
    start_index: int,
    end_index: int,
    bold: bool = None,
    italic: bool = None,
    underline: bool = None,
    font_size: int = None,
    font_family: str = None,
    text_color: str = None,
    background_color: str = None,
    link_url: str = None,
    tab_id: Optional[str] = None,
) -> Optional[Dict[str, Any]]:
    """
    Create an updateTextStyle request for Google Docs API.

    Args:
        start_index: Start position of text to format
        end_index: End position of text to format
        bold: Whether text should be bold
        italic: Whether text should be italic
        underline: Whether text should be underlined
        font_size: Font size in points
        font_family: Font family name
        text_color: Text color as hex string "#RRGGBB"
        background_color: Background (highlight) color as hex string "#RRGGBB"
        link_url: Hyperlink URL (http/https)
        tab_id: Optional ID of the tab to target

    Returns:
        Dictionary representing the updateTextStyle request, or None if no styles provided
    """
    text_style, fields = build_text_style(
        bold,
        italic,
        underline,
        font_size,
        font_family,
        text_color,
        background_color,
        link_url,
    )

    if not text_style:
        return None

    range_obj = {"startIndex": start_index, "endIndex": end_index}
    if tab_id:
        range_obj["tabId"] = tab_id

    return {
        "updateTextStyle": {
            "range": range_obj,
            "textStyle": text_style,
            "fields": ",".join(fields),
        }
    }


def create_update_paragraph_style_request(
    start_index: int,
    end_index: int,
    heading_level: int = None,
    alignment: str = None,
    line_spacing: float = None,
    indent_first_line: float = None,
    indent_start: float = None,
    indent_end: float = None,
    space_above: float = None,
    space_below: float = None,
    tab_id: Optional[str] = None,
    named_style_type: str = None,
) -> Optional[Dict[str, Any]]:
    """
    Create an updateParagraphStyle request for Google Docs API.

    Args:
        start_index: Start position of paragraph range
        end_index: End position of paragraph range
        heading_level: Heading level 0-6 (0 = NORMAL_TEXT, 1-6 = HEADING_N)
        alignment: Text alignment - 'START', 'CENTER', 'END', or 'JUSTIFIED'
        line_spacing: Line spacing multiplier (1.0 = single, 2.0 = double)
        indent_first_line: First line indent in points
        indent_start: Left/start indent in points
        indent_end: Right/end indent in points
        space_above: Space above paragraph in points
        space_below: Space below paragraph in points
        tab_id: Optional ID of the tab to target
        named_style_type: Direct named style (TITLE, SUBTITLE, HEADING_1..6, NORMAL_TEXT)

    Returns:
        Dictionary representing the updateParagraphStyle request, or None if no styles provided
    """
    paragraph_style, fields = build_paragraph_style(
        heading_level,
        alignment,
        line_spacing,
        indent_first_line,
        indent_start,
        indent_end,
        space_above,
        space_below,
        named_style_type,
    )

    if not paragraph_style:
        return None

    range_obj = {"startIndex": start_index, "endIndex": end_index}
    if tab_id:
        range_obj["tabId"] = tab_id

    return {
        "updateParagraphStyle": {
            "range": range_obj,
            "paragraphStyle": paragraph_style,
            "fields": ",".join(fields),
        }
    }


def create_find_replace_request(
    find_text: str,
    replace_text: str,
    match_case: bool = False,
    tab_id: Optional[str] = None,
) -> Dict[str, Any]:
    """
    Create a replaceAllText request for Google Docs API.

    Args:
        find_text: Text to find
        replace_text: Text to replace with
        match_case: Whether to match case exactly
        tab_id: Optional ID of the tab to target

    Returns:
        Dictionary representing the replaceAllText request
    """
    request = {
        "replaceAllText": {
            "containsText": {"text": find_text, "matchCase": match_case},
            "replaceText": replace_text,
        }
    }
    if tab_id:
        request["replaceAllText"]["tabsCriteria"] = {"tabIds": [tab_id]}
    return request


def create_insert_table_request(
    index: int, rows: int, columns: int, tab_id: Optional[str] = None
) -> Dict[str, Any]:
    """
    Create an insertTable request for Google Docs API.

    Args:
        index: Position to insert table
        rows: Number of rows
        columns: Number of columns
        tab_id: Optional ID of the tab to target

    Returns:
        Dictionary representing the insertTable request
    """
    location = {"index": index}
    if tab_id:
        location["tabId"] = tab_id
    return {"insertTable": {"location": location, "rows": rows, "columns": columns}}


def create_insert_page_break_request(
    index: int, tab_id: Optional[str] = None
) -> Dict[str, Any]:
    """
    Create an insertPageBreak request for Google Docs API.

    Args:
        index: Position to insert page break
        tab_id: Optional ID of the tab to target

    Returns:
        Dictionary representing the insertPageBreak request
    """
    location = {"index": index}
    if tab_id:
        location["tabId"] = tab_id
    return {"insertPageBreak": {"location": location}}


def create_insert_doc_tab_request(
    title: str, index: int, parent_tab_id: Optional[str] = None
) -> Dict[str, Any]:
    """
    Create an addDocumentTab request for Google Docs API.

    Args:
        title: Title of the new tab
        index: Position to insert the tab
        parent_tab_id: Optional ID of the parent tab to nest under

    Returns:
        Dictionary representing the addDocumentTab request
    """
    tab_properties: Dict[str, Any] = {
        "title": title,
        "index": index,
    }
    if parent_tab_id:
        tab_properties["parentTabId"] = parent_tab_id
    return {
        "addDocumentTab": {
            "tabProperties": tab_properties,
        }
    }


def create_delete_doc_tab_request(tab_id: str) -> Dict[str, Any]:
    """
    Create a deleteDocumentTab request for Google Docs API.

    Args:
        tab_id: ID of the tab to delete

    Returns:
        Dictionary representing the deleteDocumentTab request
    """
    return {"deleteTab": {"tabId": tab_id}}


def create_update_doc_tab_request(tab_id: str, title: str) -> Dict[str, Any]:
    """
    Create an updateDocumentTab request for Google Docs API.

    Args:
        tab_id: ID of the tab to update
        title: New title for the tab

    Returns:
        Dictionary representing the updateDocumentTab request
    """
    return {
        "updateDocumentTabProperties": {
            "tabProperties": {
                "tabId": tab_id,
                "title": title,
            },
            "fields": "title",
        }
    }


def create_insert_image_request(
    index: int,
    image_uri: str,
    width: int = None,
    height: int = None,
    tab_id: Optional[str] = None,
) -> Dict[str, Any]:
    """
    Create an insertInlineImage request for Google Docs API.

    Args:
        index: Position to insert image
        image_uri: URI of the image (Drive URL or public URL)
        width: Image width in points
        height: Image height in points
        tab_id: Optional ID of the tab to target

    Returns:
        Dictionary representing the insertInlineImage request
    """
    location = {"index": index}
    if tab_id:
        location["tabId"] = tab_id

    request = {"insertInlineImage": {"location": location, "uri": image_uri}}

    # Add size properties if specified
    object_size = {}
    if width is not None:
        object_size["width"] = {"magnitude": width, "unit": "PT"}
    if height is not None:
        object_size["height"] = {"magnitude": height, "unit": "PT"}

    if object_size:
        request["insertInlineImage"]["objectSize"] = object_size

    return request


def create_bullet_list_request(
    start_index: int,
    end_index: int,
    list_type: str = "UNORDERED",
    nesting_level: int = None,
    paragraph_start_indices: Optional[list[int]] = None,
    doc_tab_id: Optional[str] = None,
) -> list[Dict[str, Any]]:
    """
    Create requests to apply bullet list formatting with optional nesting.

    Google Docs infers list nesting from leading tab characters. To set a nested
    level, this helper inserts literal tab characters before each targeted
    paragraph, then calls createParagraphBullets. This is a Docs API workaround
    and does temporarily mutate content/index positions while the batch executes.

    Args:
        start_index: Start of text range to convert to list
        end_index: End of text range to convert to list
        list_type: Type of list ("UNORDERED" or "ORDERED")
        nesting_level: Nesting level (0-8, where 0 is top level). If None or 0, no tabs added.
        paragraph_start_indices: Optional paragraph start positions for ranges with
            multiple paragraphs. If omitted, only start_index is tab-prefixed.
        doc_tab_id: Optional ID of the tab to target

    Returns:
        List of request dictionaries (insertText for nesting tabs if needed,
        then createParagraphBullets)
    """
    bullet_preset = (
        "BULLET_DISC_CIRCLE_SQUARE"
        if list_type == "UNORDERED"
        else "NUMBERED_DECIMAL_ALPHA_ROMAN"
    )

    # Validate nesting level
    if nesting_level is not None:
        if not isinstance(nesting_level, int):
            raise ValueError("nesting_level must be an integer between 0 and 8")
        if nesting_level < 0 or nesting_level > 8:
            raise ValueError("nesting_level must be between 0 and 8")

    requests = []

    # Insert tabs for nesting if needed (nesting_level > 0).
    # For multi-paragraph ranges, callers should provide paragraph_start_indices.
    if nesting_level and nesting_level > 0:
        tabs = "\t" * nesting_level
        paragraph_starts = paragraph_start_indices or [start_index]
        paragraph_starts = sorted(set(paragraph_starts))

        if any(not isinstance(idx, int) for idx in paragraph_starts):
            raise ValueError("paragraph_start_indices must contain only integers")

        original_start = start_index
        original_end = end_index
        inserted_char_count = 0

        for paragraph_start in paragraph_starts:
            adjusted_start = paragraph_start + inserted_char_count
            requests.append(
                create_insert_text_request(adjusted_start, tabs, doc_tab_id)
            )
            inserted_char_count += nesting_level

        # Keep createParagraphBullets range aligned to the same logical content.
        start_index += (
            sum(1 for idx in paragraph_starts if idx < original_start) * nesting_level
        )
        end_index += (
            sum(1 for idx in paragraph_starts if idx < original_end) * nesting_level
        )

    # Create the bullet list
    range_obj = {"startIndex": start_index, "endIndex": end_index}
    if doc_tab_id:
        range_obj["tabId"] = doc_tab_id

    requests.append(
        {
            "createParagraphBullets": {
                "range": range_obj,
                "bulletPreset": bullet_preset,
            }
        }
    )

    return requests


def validate_operation(operation: Dict[str, Any]) -> tuple[bool, str]:
    """
    Validate a batch operation dictionary.

    Args:
        operation: Operation dictionary to validate

    Returns:
        Tuple of (is_valid, error_message)
    """
    op_type = operation.get("type")
    if not op_type:
        return False, "Missing 'type' field"

    # Validate required fields for each operation type
    required_fields = {
        "insert_text": ["index", "text"],
        "delete_text": ["start_index", "end_index"],
        "replace_text": ["start_index", "end_index", "text"],
        "format_text": ["start_index", "end_index"],
        "update_paragraph_style": ["start_index", "end_index"],
        "insert_table": ["index", "rows", "columns"],
        "insert_page_break": ["index"],
        "find_replace": ["find_text", "replace_text"],
        "insert_doc_tab": ["title", "index"],
        "delete_doc_tab": ["tab_id"],
        "update_doc_tab": ["tab_id", "title"],
    }

    if op_type not in required_fields:
        return False, f"Unsupported operation type: {op_type or 'None'}"

    for field in required_fields[op_type]:
        if field not in operation:
            return False, f"Missing required field: {field}"

    return True, ""