Notion Sdk

# /// script
# requires-python = ">=3.11"
# dependencies = ["notion-client>=2.6.0"]
# ///
"""Append and manipulate blocks in Notion pages.

Supports:
- Appending blocks to pages
- Block builder helpers for common types
- Nested block structures (toggles, callouts)

Note: Max 1000 blocks per request. Chunk larger payloads.
"""

from notion_client import Client


def append_blocks(
    client: Client,
    page_id: str,
    blocks: list[dict],
) -> dict:
    """Append blocks to an existing page.

    Args:
        client: Authenticated Notion client
        page_id: Page or block ID to append to
        blocks: List of block objects

    Returns:
        Response with created block objects

    Raises:
        ValueError: If blocks exceeds 1000 limit
    """
    if len(blocks) > 1000:
        raise ValueError("Max 1000 blocks per request. Chunk your payload.")
    return client.blocks.children.append(block_id=page_id, children=blocks)


def get_block_children(
    client: Client,
    block_id: str,
) -> list[dict]:
    """Get all children of a block (with pagination).

    Args:
        client: Authenticated Notion client
        block_id: Block or page ID

    Returns:
        List of child block objects
    """
    from notion_client.helpers import collect_paginated_api

    return collect_paginated_api(client.blocks.children.list, block_id=block_id)


def delete_block(client: Client, block_id: str) -> dict:
    """Delete a block (moves to trash).

    Args:
        client: Authenticated Notion client
        block_id: Block ID to delete

    Returns:
        Deleted block object
    """
    return client.blocks.delete(block_id=block_id)


# ============================================================================
# Block Builder Helpers
# ============================================================================


def _rich_text(text: str, bold: bool = False, italic: bool = False, code: bool = False) -> list:
    """Create rich_text array with optional formatting."""
    return [
        {
            "type": "text",
            "text": {"content": text},
            "annotations": {
                "bold": bold,
                "italic": italic,
                "code": code,
                "strikethrough": False,
                "underline": False,
                "color": "default",
            },
        }
    ]


def paragraph(text: str, bold: bool = False) -> dict:
    """Create paragraph block."""
    return {
        "type": "paragraph",
        "paragraph": {"rich_text": _rich_text(text, bold=bold)},
    }


def heading(text: str, level: int = 2) -> dict:
    """Create heading block (level 1-3).

    Args:
        text: Heading text
        level: Heading level (1, 2, or 3)

    Returns:
        Heading block object
    """
    if level not in (1, 2, 3):
        raise ValueError("Heading level must be 1, 2, or 3")
    key = f"heading_{level}"
    return {"type": key, key: {"rich_text": _rich_text(text)}}


def bullet(text: str) -> dict:
    """Create bulleted list item."""
    return {
        "type": "bulleted_list_item",
        "bulleted_list_item": {"rich_text": _rich_text(text)},
    }


def numbered(text: str) -> dict:
    """Create numbered list item."""
    return {
        "type": "numbered_list_item",
        "numbered_list_item": {"rich_text": _rich_text(text)},
    }


def todo(text: str, checked: bool = False) -> dict:
    """Create to-do checkbox item."""
    return {
        "type": "to_do",
        "to_do": {
            "rich_text": _rich_text(text),
            "checked": checked,
        },
    }


def code_block(code: str, language: str = "python") -> dict:
    """Create code block.

    Args:
        code: Code content
        language: Programming language (python, javascript, typescript, etc.)
    """
    return {
        "type": "code",
        "code": {
            "rich_text": [{"type": "text", "text": {"content": code}}],
            "language": language,
        },
    }


def divider() -> dict:
    """Create horizontal divider."""
    return {"type": "divider", "divider": {}}


def callout(text: str, emoji: str = "💡") -> dict:
    """Create callout block with emoji icon.

    Args:
        text: Callout content
        emoji: Emoji for icon (default: lightbulb)
    """
    return {
        "type": "callout",
        "callout": {
            "rich_text": _rich_text(text),
            "icon": {"type": "emoji", "emoji": emoji},
        },
    }


def quote(text: str) -> dict:
    """Create quote block."""
    return {
        "type": "quote",
        "quote": {"rich_text": _rich_text(text)},
    }


def toggle(text: str, children: list[dict] | None = None) -> dict:
    """Create toggle block with optional nested content.

    Args:
        text: Toggle header text
        children: Nested blocks inside toggle
    """
    block = {
        "type": "toggle",
        "toggle": {"rich_text": _rich_text(text)},
    }
    if children:
        block["toggle"]["children"] = children
    return block


def table_of_contents() -> dict:
    """Create table of contents block."""
    return {"type": "table_of_contents", "table_of_contents": {}}


def bookmark(url: str) -> dict:
    """Create bookmark block for a URL."""
    return {"type": "bookmark", "bookmark": {"url": url}}

# /// script
# requires-python = ">=3.11"
# dependencies = ["notion-client>=2.6.0"]
# ///
"""Create pages in Notion databases with properties and content blocks.

Supports:
- Creating pages in databases (with full property support)
- Creating sub-pages under existing pages
- Adding initial content blocks during creation

Note: Uses data_source_id per Notion API v2.6.0+ multi-source model.
For legacy databases, data_source_id == database_id.
"""

from notion_client import Client


def create_database_page(
    client: Client,
    data_source_id: str,
    properties: dict,
    children: list | None = None,
) -> dict:
    """Create a new page in a database.

    Args:
        client: Authenticated Notion client
        data_source_id: Database/data source ID (32-char UUID without dashes works too)
        properties: Property values matching database schema
        children: Optional list of block objects for initial content

    Returns:
        Created page object with id, url, properties, etc.

    Example properties:
        {
            "Name": {"title": [{"text": {"content": "Page Title"}}]},
            "Status": {"status": {"name": "In Progress"}},
            "Tags": {"multi_select": [{"name": "api"}, {"name": "python"}]},
            "Due Date": {"date": {"start": "2025-12-31"}}
        }
    """
    return client.pages.create(
        parent={"type": "data_source_id", "data_source_id": data_source_id},
        properties=properties,
        children=children or [],
    )


def create_child_page(
    client: Client,
    parent_page_id: str,
    title: str,
    children: list | None = None,
) -> dict:
    """Create a sub-page under an existing page.

    Note: Pages under pages can only have a title property.
    For full property support, use create_database_page().

    Args:
        client: Authenticated Notion client
        parent_page_id: Parent page ID
        title: Page title text
        children: Optional list of block objects for content

    Returns:
        Created page object
    """
    return client.pages.create(
        parent={"type": "page_id", "page_id": parent_page_id},
        properties={"title": [{"text": {"content": title}}]},
        children=children or [],
    )


def update_page_properties(
    client: Client,
    page_id: str,
    properties: dict,
) -> dict:
    """Update properties of an existing page.

    Args:
        client: Authenticated Notion client
        page_id: Page ID to update
        properties: Properties to update (only include changed ones)

    Returns:
        Updated page object
    """
    return client.pages.update(page_id=page_id, properties=properties)


def archive_page(client: Client, page_id: str) -> dict:
    """Move a page to trash (archive).

    Args:
        client: Authenticated Notion client
        page_id: Page ID to archive

    Returns:
        Updated page object with archived=True
    """
    return client.pages.update(page_id=page_id, archived=True)


# Property builder helpers for common types
def title_property(text: str) -> dict:
    """Build title property value."""
    return {"title": [{"text": {"content": text}}]}


def rich_text_property(text: str) -> dict:
    """Build rich_text property value."""
    return {"rich_text": [{"text": {"content": text}}]}


def select_property(option_name: str) -> dict:
    """Build select property value."""
    return {"select": {"name": option_name}}


def multi_select_property(option_names: list[str]) -> dict:
    """Build multi_select property value."""
    return {"multi_select": [{"name": name} for name in option_names]}


def date_property(start: str, end: str | None = None) -> dict:
    """Build date property value (ISO 8601 format)."""
    date_obj = {"start": start}
    if end:
        date_obj["end"] = end
    return {"date": date_obj}


def checkbox_property(checked: bool) -> dict:
    """Build checkbox property value."""
    return {"checkbox": checked}


def number_property(value: int | float) -> dict:
    """Build number property value."""
    return {"number": value}


def url_property(url: str) -> dict:
    """Build URL property value."""
    return {"url": url}


def status_property(status_name: str) -> dict:
    """Build status property value."""
    return {"status": {"name": status_name}}


def relation_property(page_ids: list[str]) -> dict:
    """Build relation property value."""
    return {"relation": [{"id": pid} for pid in page_ids]}

# /// script
# requires-python = ">=3.11"
# dependencies = ["notion-client>=2.6.0"]
# ///
"""Notion API client wrapper with validation and retry logic.

This module provides:
- Client initialization with token
- Token validation against Notion API
- Retry wrapper with rate limit and error handling
"""

import time
from notion_client import Client, APIResponseError, APIErrorCode


def get_client(token: str) -> Client:
    """Initialize authenticated Notion client.

    Args:
        token: Notion integration token (starts with ntn_ or secret_)

    Returns:
        Authenticated Client instance
    """
    return Client(auth=token)


def validate_token(token: str) -> tuple[bool, str]:
    """Test token validity by calling /users/me endpoint.

    Args:
        token: Notion integration token to validate

    Returns:
        Tuple of (success: bool, message: str)
    """
    # Format validation
    if not token.startswith(("ntn_", "secret_")):
        return (False, "Token must start with 'ntn_' or 'secret_'")

    try:
        client = get_client(token)
        user = client.users.me()
        bot_name = user.get("name", "Unknown")
        return (True, f"Authenticated as: {bot_name}")
    except APIResponseError as e:
        if e.code == APIErrorCode.Unauthorized:
            return (False, "Token invalid or expired")
        return (False, f"API error: {e.message}")
    except Exception as e:
        return (False, f"Connection failed: {str(e)}")


def api_call_with_retry(func, *args, max_retries: int = 3, **kwargs):
    """Execute API call with rate limit handling and exponential backoff.

    Handles:
    - 429 Rate Limited: Waits per Retry-After header
    - 500 Server Error: Exponential backoff retry

    Args:
        func: API method to call (e.g., client.pages.create)
        *args: Positional arguments for func
        max_retries: Maximum retry attempts (default: 3)
        **kwargs: Keyword arguments for func

    Returns:
        API response from func

    Raises:
        APIResponseError: On non-retryable errors
        RuntimeError: When max retries exceeded
    """
    for attempt in range(max_retries):
        try:
            return func(*args, **kwargs)
        except APIResponseError as e:
            if e.code == APIErrorCode.RateLimited:
                # Respect Retry-After header from Notion
                retry_after = 1
                if hasattr(e, "additional_data") and e.additional_data:
                    retry_after = int(e.additional_data.get("retry_after", 1))
                print(f"Rate limited. Waiting {retry_after}s...")
                time.sleep(retry_after)
            elif e.code in [APIErrorCode.InternalServerError]:
                if attempt < max_retries - 1:
                    wait = 2**attempt  # Exponential backoff: 1, 2, 4 seconds
                    print(f"Server error. Retrying in {wait}s...")
                    time.sleep(wait)
                else:
                    raise
            else:
                # Non-retryable error (auth, validation, not found)
                raise
    raise RuntimeError(f"Max retries ({max_retries}) exceeded")


if __name__ == "__main__":
    import os
    import sys

    token = os.environ.get("NOTION_TOKEN")
    if not token:
        print("Error: NOTION_TOKEN environment variable not set")
        sys.exit(1)

    success, message = validate_token(token)
    print(message)
    sys.exit(0 if success else 1)

# /// script
# requires-python = ">=3.11"
# dependencies = ["notion-client>=2.6.0"]
# ///
"""Query Notion databases with filters and sorting.

Supports:
- Database queries with filters and sorts
- Workspace-wide search
- Pagination via helper functions

Note: Uses data_sources.query per Notion API v2.6.0+ multi-source model.
For legacy databases, data_source_id == database_id.
"""

from notion_client import Client
from notion_client.helpers import collect_paginated_api


def query_data_source(
    client: Client,
    data_source_id: str,
    filter_obj: dict | None = None,
    sorts: list | None = None,
) -> list[dict]:
    """Query database with optional filters and sorting.

    Args:
        client: Authenticated Notion client
        data_source_id: Database/data source ID
        filter_obj: Filter object (see filter builders below)
        sorts: List of sort objects

    Returns:
        List of page objects matching query

    Example:
        results = query_data_source(
            client,
            "abc123...",
            filter_obj=checkbox_filter("Done", False),
            sorts=[{"property": "Created", "direction": "descending"}]
        )
    """
    kwargs = {"data_source_id": data_source_id}
    if filter_obj:
        kwargs["filter"] = filter_obj
    if sorts:
        kwargs["sorts"] = sorts

    return collect_paginated_api(client.data_sources.query, **kwargs)


def search_workspace(
    client: Client,
    query: str,
    filter_type: str | None = None,
) -> list[dict]:
    """Search across workspace by title.

    Args:
        client: Authenticated Notion client
        query: Search query string
        filter_type: "page" or "database" to filter results

    Returns:
        List of matching pages and/or databases
    """
    params: dict = {"query": query}
    if filter_type:
        params["filter"] = {"value": filter_type, "property": "object"}
    return collect_paginated_api(client.search, **params)


def get_page(client: Client, page_id: str) -> dict:
    """Retrieve a single page by ID.

    Args:
        client: Authenticated Notion client
        page_id: Page ID

    Returns:
        Page object with properties
    """
    return client.pages.retrieve(page_id=page_id)


def get_database(client: Client, database_id: str) -> dict:
    """Retrieve database schema (properties, title).

    Args:
        client: Authenticated Notion client
        database_id: Database ID

    Returns:
        Database object with properties schema
    """
    return client.databases.retrieve(database_id=database_id)


# ============================================================================
# Filter Builders
# ============================================================================


def checkbox_filter(property_name: str, equals: bool) -> dict:
    """Filter by checkbox property.

    Example: checkbox_filter("Done", True) -> only checked items
    """
    return {"property": property_name, "checkbox": {"equals": equals}}


def select_filter(property_name: str, equals: str) -> dict:
    """Filter by select property value.

    Example: select_filter("Priority", "High")
    """
    return {"property": property_name, "select": {"equals": equals}}


def status_filter(property_name: str, equals: str) -> dict:
    """Filter by status property value.

    Example: status_filter("Status", "In Progress")
    """
    return {"property": property_name, "status": {"equals": equals}}


def text_contains_filter(property_name: str, contains: str) -> dict:
    """Filter rich_text or title containing substring.

    Example: text_contains_filter("Name", "API")
    """
    return {"property": property_name, "rich_text": {"contains": contains}}


def date_after_filter(property_name: str, after: str) -> dict:
    """Filter date property after given date (ISO 8601).

    Example: date_after_filter("Due Date", "2025-01-01")
    """
    return {"property": property_name, "date": {"after": after}}


def date_before_filter(property_name: str, before: str) -> dict:
    """Filter date property before given date (ISO 8601)."""
    return {"property": property_name, "date": {"before": before}}


def number_greater_than_filter(property_name: str, value: int | float) -> dict:
    """Filter number property greater than value."""
    return {"property": property_name, "number": {"greater_than": value}}


def number_less_than_filter(property_name: str, value: int | float) -> dict:
    """Filter number property less than value."""
    return {"property": property_name, "number": {"less_than": value}}


def and_filter(*filters: dict) -> dict:
    """Combine multiple filters with AND logic.

    Example: and_filter(
        checkbox_filter("Done", False),
        status_filter("Status", "In Progress")
    )
    """
    return {"and": list(filters)}


def or_filter(*filters: dict) -> dict:
    """Combine multiple filters with OR logic."""
    return {"or": list(filters)}


# ============================================================================
# Sort Builders
# ============================================================================


def sort_by_property(property_name: str, direction: str = "ascending") -> dict:
    """Create sort object for a property.

    Args:
        property_name: Property to sort by
        direction: "ascending" or "descending"
    """
    return {"property": property_name, "direction": direction}


def sort_by_created_time(direction: str = "descending") -> dict:
    """Sort by creation timestamp."""
    return {"timestamp": "created_time", "direction": direction}


def sort_by_last_edited_time(direction: str = "descending") -> dict:
    """Sort by last edit timestamp."""
    return {"timestamp": "last_edited_time", "direction": direction}

# /// script
# requires-python = ">=3.11"
# dependencies = ["pytest>=8.0.0", "notion-client>=2.6.0"]
# ///
"""Tests for block builder functions.

Oracle Source: Notion API Reference - Block Object
https://developers.notion.com/reference/block

Test Principles Applied:
- Oracles from domain rules (Notion API docs), NOT code behavior
- Black-box: Test public interface against oracle
- White-box: Test internal structure matches API spec
- Invalid inputs must raise exceptions
- Deterministic with documented tolerances
"""

import pytest
import sys
from pathlib import Path

# Add scripts to path for imports
sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))

from add_blocks import (
    paragraph,
    heading,
    bullet,
    numbered,
    todo,
    code_block,
    divider,
    callout,
    quote,
    toggle,
    table_of_contents,
    bookmark,
    append_blocks,
)


# =============================================================================
# ORACLES: Structures defined by Notion API documentation (independent source)
# =============================================================================

class NotionBlockOracle:
    """Oracle structures from Notion API Reference.

    Source: https://developers.notion.com/reference/block
    Retrieved: 2025-12-23

    Note: Oracles show REQUIRED fields only. Optional fields (color, children)
    are omitted per API docs stating they default when not provided.
    """

    @staticmethod
    def paragraph(text: str) -> dict:
        """Oracle: Paragraph block structure per API docs."""
        return {
            "type": "paragraph",
            "paragraph": {
                "rich_text": [{"type": "text", "text": {"content": text}}]
            }
        }

    @staticmethod
    def heading(text: str, level: int) -> dict:
        """Oracle: Heading block structure per API docs."""
        key = f"heading_{level}"
        return {
            "type": key,
            key: {
                "rich_text": [{"type": "text", "text": {"content": text}}]
            }
        }

    @staticmethod
    def bulleted_list_item(text: str) -> dict:
        """Oracle: Bulleted list item structure per API docs."""
        return {
            "type": "bulleted_list_item",
            "bulleted_list_item": {
                "rich_text": [{"type": "text", "text": {"content": text}}]
            }
        }

    @staticmethod
    def numbered_list_item(text: str) -> dict:
        """Oracle: Numbered list item structure per API docs."""
        return {
            "type": "numbered_list_item",
            "numbered_list_item": {
                "rich_text": [{"type": "text", "text": {"content": text}}]
            }
        }

    @staticmethod
    def to_do(text: str, checked: bool) -> dict:
        """Oracle: To-do block structure per API docs."""
        return {
            "type": "to_do",
            "to_do": {
                "rich_text": [{"type": "text", "text": {"content": text}}],
                "checked": checked
            }
        }

    @staticmethod
    def code(content: str, language: str) -> dict:
        """Oracle: Code block structure per API docs."""
        return {
            "type": "code",
            "code": {
                "rich_text": [{"type": "text", "text": {"content": content}}],
                "language": language
            }
        }

    @staticmethod
    def callout_block(text: str, emoji: str) -> dict:
        """Oracle: Callout block structure per API docs."""
        return {
            "type": "callout",
            "callout": {
                "rich_text": [{"type": "text", "text": {"content": text}}],
                "icon": {"type": "emoji", "emoji": emoji}
            }
        }

    @staticmethod
    def quote_block(text: str) -> dict:
        """Oracle: Quote block structure per API docs."""
        return {
            "type": "quote",
            "quote": {
                "rich_text": [{"type": "text", "text": {"content": text}}]
            }
        }

    @staticmethod
    def divider_block() -> dict:
        """Oracle: Divider block structure per API docs."""
        return {"type": "divider", "divider": {}}

    @staticmethod
    def bookmark_block(url: str) -> dict:
        """Oracle: Bookmark block structure per API docs."""
        return {"type": "bookmark", "bookmark": {"url": url}}


# =============================================================================
# INTEGRITY TESTS: First principles validation
# =============================================================================

class TestBlockBuilderIntegrity:
    """Integrity tests validating first principles."""

    def test_all_blocks_have_type_field(self):
        """First principle: All blocks must have 'type' field."""
        blocks = [
            paragraph("test"),
            heading("test", 1),
            bullet("test"),
            numbered("test"),
            todo("test"),
            code_block("test"),
            divider(),
            callout("test"),
            quote("test"),
            toggle("test"),
            table_of_contents(),
            bookmark("https://example.com"),
        ]
        for block in blocks:
            assert "type" in block, f"Block missing 'type' field: {block}"

    def test_all_blocks_have_matching_type_key(self):
        """First principle: Block has key matching its type value."""
        blocks = [
            paragraph("test"),
            heading("test", 2),
            bullet("test"),
            divider(),
        ]
        for block in blocks:
            block_type = block["type"]
            assert block_type in block, f"Block missing key for type '{block_type}'"

    def test_text_blocks_have_rich_text_array(self):
        """First principle: Text-containing blocks have rich_text array."""
        text_blocks = [
            ("paragraph", paragraph("test")),
            ("heading_2", heading("test", 2)),
            ("bulleted_list_item", bullet("test")),
            ("numbered_list_item", numbered("test")),
            ("to_do", todo("test")),
            ("quote", quote("test")),
            ("callout", callout("test")),
        ]
        for block_type, block in text_blocks:
            content = block[block_type]
            assert "rich_text" in content, f"{block_type} missing rich_text"
            assert isinstance(content["rich_text"], list), f"{block_type} rich_text not array"


# =============================================================================
# BLACK-BOX TESTS: Public interface against oracle
# =============================================================================

class TestBlockBuildersBlackBox:
    """Black-box tests: Verify output matches Notion API oracle."""

    def test_paragraph_matches_oracle(self):
        """Paragraph block output matches Notion API specification."""
        result = paragraph("Hello world")
        oracle = NotionBlockOracle.paragraph("Hello world")
        # Compare structure (our impl may have extra annotations)
        assert result["type"] == oracle["type"]
        assert result["paragraph"]["rich_text"][0]["text"]["content"] == "Hello world"

    def test_heading_1_matches_oracle(self):
        """Heading 1 block output matches Notion API specification."""
        result = heading("Title", 1)
        oracle = NotionBlockOracle.heading("Title", 1)
        assert result["type"] == oracle["type"] == "heading_1"
        assert result["heading_1"]["rich_text"][0]["text"]["content"] == "Title"

    def test_heading_2_matches_oracle(self):
        """Heading 2 block output matches Notion API specification."""
        result = heading("Subtitle", 2)
        assert result["type"] == "heading_2"
        assert result["heading_2"]["rich_text"][0]["text"]["content"] == "Subtitle"

    def test_heading_3_matches_oracle(self):
        """Heading 3 block output matches Notion API specification."""
        result = heading("Section", 3)
        assert result["type"] == "heading_3"
        assert result["heading_3"]["rich_text"][0]["text"]["content"] == "Section"

    def test_bullet_matches_oracle(self):
        """Bulleted list item matches Notion API specification."""
        result = bullet("List item")
        oracle = NotionBlockOracle.bulleted_list_item("List item")
        assert result["type"] == oracle["type"]
        assert result["bulleted_list_item"]["rich_text"][0]["text"]["content"] == "List item"

    def test_numbered_matches_oracle(self):
        """Numbered list item matches Notion API specification."""
        result = numbered("Step one")
        oracle = NotionBlockOracle.numbered_list_item("Step one")
        assert result["type"] == oracle["type"]
        assert result["numbered_list_item"]["rich_text"][0]["text"]["content"] == "Step one"

    def test_todo_unchecked_matches_oracle(self):
        """To-do (unchecked) matches Notion API specification."""
        result = todo("Task", checked=False)
        oracle = NotionBlockOracle.to_do("Task", False)
        assert result["type"] == oracle["type"]
        assert result["to_do"]["checked"] == False
        assert result["to_do"]["rich_text"][0]["text"]["content"] == "Task"

    def test_todo_checked_matches_oracle(self):
        """To-do (checked) matches Notion API specification."""
        result = todo("Done task", checked=True)
        oracle = NotionBlockOracle.to_do("Done task", True)
        assert result["to_do"]["checked"] == True

    def test_code_block_matches_oracle(self):
        """Code block matches Notion API specification."""
        result = code_block("print('hello')", language="python")
        oracle = NotionBlockOracle.code("print('hello')", "python")
        assert result["type"] == oracle["type"]
        assert result["code"]["language"] == "python"
        assert result["code"]["rich_text"][0]["text"]["content"] == "print('hello')"

    def test_divider_matches_oracle(self):
        """Divider block matches Notion API specification."""
        result = divider()
        oracle = NotionBlockOracle.divider_block()
        assert result == oracle

    def test_callout_matches_oracle(self):
        """Callout block matches Notion API specification."""
        result = callout("Important note", emoji="⚠️")
        oracle = NotionBlockOracle.callout_block("Important note", "⚠️")
        assert result["type"] == oracle["type"]
        assert result["callout"]["icon"]["emoji"] == "⚠️"
        assert result["callout"]["rich_text"][0]["text"]["content"] == "Important note"

    def test_quote_matches_oracle(self):
        """Quote block matches Notion API specification."""
        result = quote("Famous quote")
        oracle = NotionBlockOracle.quote_block("Famous quote")
        assert result["type"] == oracle["type"]
        assert result["quote"]["rich_text"][0]["text"]["content"] == "Famous quote"

    def test_bookmark_matches_oracle(self):
        """Bookmark block matches Notion API specification."""
        result = bookmark("https://example.com")
        oracle = NotionBlockOracle.bookmark_block("https://example.com")
        assert result == oracle


# =============================================================================
# WHITE-BOX TESTS: Internal structure validation
# =============================================================================

class TestBlockBuildersWhiteBox:
    """White-box tests: Verify internal structure details."""

    def test_paragraph_bold_annotation(self):
        """Paragraph with bold=True sets annotation correctly."""
        result = paragraph("Bold text", bold=True)
        annotations = result["paragraph"]["rich_text"][0]["annotations"]
        assert annotations["bold"] == True

    def test_callout_icon_structure(self):
        """Callout icon has correct nested structure."""
        result = callout("Note", emoji="💡")
        icon = result["callout"]["icon"]
        assert icon["type"] == "emoji"
        assert icon["emoji"] == "💡"

    def test_toggle_accepts_children(self):
        """Toggle block can include nested children."""
        child = paragraph("Nested content")
        result = toggle("Click to expand", children=[child])
        assert "children" in result["toggle"]
        assert result["toggle"]["children"] == [child]

    def test_toggle_without_children_has_no_children_key(self):
        """Toggle without children omits children key."""
        result = toggle("Empty toggle")
        assert "children" not in result["toggle"]

    def test_code_block_preserves_whitespace(self):
        """Code block preserves whitespace and newlines."""
        code_content = "def foo():\n    return 42"
        result = code_block(code_content)
        assert result["code"]["rich_text"][0]["text"]["content"] == code_content


# =============================================================================
# INVALID INPUT TESTS: Must raise exceptions
# =============================================================================

class TestBlockBuildersInvalidInputs:
    """Invalid input tests: Verify proper exception handling."""

    def test_heading_invalid_level_raises(self):
        """Heading with invalid level (not 1-3) raises ValueError."""
        with pytest.raises(ValueError, match="level must be 1, 2, or 3"):
            heading("Title", 4)

        with pytest.raises(ValueError, match="level must be 1, 2, or 3"):
            heading("Title", 0)

    def test_append_blocks_exceeds_limit_raises(self):
        """Appending more than 1000 blocks raises ValueError."""
        # Create 1001 blocks
        blocks = [paragraph(f"Block {i}") for i in range(1001)]

        # Mock client (we just need to test the validation)
        class MockClient:
            pass

        with pytest.raises(ValueError, match="Max 1000 blocks"):
            append_blocks(MockClient(), "page-id", blocks)


# =============================================================================
# EDGE CASES AND BOUNDARY TESTS
# =============================================================================

class TestBlockBuildersEdgeCases:
    """Edge case and boundary tests."""

    def test_empty_paragraph(self):
        """Empty paragraph is valid."""
        result = paragraph("")
        assert result["paragraph"]["rich_text"][0]["text"]["content"] == ""

    def test_multiline_code_block(self):
        """Multi-line code is preserved."""
        code = """def example():
    x = 1
    y = 2
    return x + y"""
        result = code_block(code)
        assert "\n" in result["code"]["rich_text"][0]["text"]["content"]

    def test_unicode_emoji_in_callout(self):
        """Unicode emoji in callout is preserved."""
        emojis = ["💡", "⚠️", "✅", "🚀", "📝"]
        for emoji in emojis:
            result = callout("Test", emoji=emoji)
            assert result["callout"]["icon"]["emoji"] == emoji

    def test_url_with_query_params_in_bookmark(self):
        """Bookmark preserves URL with query parameters."""
        url = "https://example.com/page?foo=bar&baz=qux#section"
        result = bookmark(url)
        assert result["bookmark"]["url"] == url

    def test_exactly_1000_blocks_is_valid(self):
        """Exactly 1000 blocks is within limit (boundary test)."""
        blocks = [paragraph(f"Block {i}") for i in range(1000)]
        # This should not raise - we can't fully test without mocking Client
        assert len(blocks) == 1000


if __name__ == "__main__":
    pytest.main([__file__, "-v"])

# /// script
# requires-python = ">=3.11"
# dependencies = ["pytest>=8.0.0", "notion-client>=2.6.0"]
# ///
"""Tests for Notion client wrapper functions.

Oracle Source: Notion API Reference - Authentication
https://developers.notion.com/reference/authentication

Test Principles Applied:
- Oracles from domain rules (token format per Notion docs)
- Black-box: Test validation against expected formats
- Invalid inputs must raise exceptions or return failure
- Deterministic with documented tolerances
"""

import pytest
import sys
from pathlib import Path
from unittest.mock import Mock, patch

# Add scripts to path for imports
sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))

from notion_wrapper import validate_token, get_client, api_call_with_retry


# =============================================================================
# ORACLES: Token format rules from Notion API documentation
# =============================================================================

class NotionAuthOracle:
    """Oracle for Notion authentication rules.

    Source: https://developers.notion.com/reference/authentication
    Retrieved: 2025-12-23

    Token formats:
    - Internal integration: starts with "secret_" (legacy) or "ntn_" (new)
    - OAuth: starts with specific prefix
    """

    VALID_PREFIXES = ("ntn_", "secret_")

    @classmethod
    def is_valid_format(cls, token: str) -> bool:
        """Oracle: Check if token has valid format per API docs."""
        return token.startswith(cls.VALID_PREFIXES)


# =============================================================================
# INTEGRITY TESTS: First principles validation
# =============================================================================

class TestClientIntegrity:
    """Integrity tests for client functions."""

    def test_get_client_returns_client_object(self):
        """First principle: get_client returns a Client instance."""
        # We can't import Client directly without the package,
        # but we can verify get_client is callable
        from notion_wrapper import get_client
        assert callable(get_client)

    def test_validate_token_returns_tuple(self):
        """First principle: validate_token returns (bool, str) tuple."""
        # Test with obviously invalid token (format check before API call)
        result = validate_token("invalid_token")
        assert isinstance(result, tuple)
        assert len(result) == 2
        assert isinstance(result[0], bool)
        assert isinstance(result[1], str)


# =============================================================================
# BLACK-BOX TESTS: Token format validation against oracle
# =============================================================================

class TestTokenFormatValidation:
    """Black-box tests for token format validation."""

    def test_ntn_prefix_is_valid_format(self):
        """Token starting with 'ntn_' is valid format per API docs."""
        token = "ntn_abc123def456"
        assert NotionAuthOracle.is_valid_format(token)

    def test_secret_prefix_is_valid_format(self):
        """Token starting with 'secret_' is valid format per API docs."""
        token = "secret_abc123def456"
        assert NotionAuthOracle.is_valid_format(token)

    def test_other_prefix_is_invalid_format(self):
        """Token with other prefix is invalid format per API docs."""
        invalid_tokens = [
            "invalid_token",
            "bearer_abc123",
            "api_key_xyz",
            "abc123",
            "",
        ]
        for token in invalid_tokens:
            assert not NotionAuthOracle.is_valid_format(token)

    def test_validate_token_rejects_invalid_format(self):
        """validate_token rejects tokens with invalid format."""
        result = validate_token("invalid_format_token")
        success, message = result
        assert success is False
        assert "ntn_" in message or "secret_" in message


# =============================================================================
# WHITE-BOX TESTS: Validate internal logic
# =============================================================================

class TestValidateTokenWhiteBox:
    """White-box tests for validate_token internal logic."""

    def test_format_check_happens_before_api_call(self):
        """Format validation occurs before making API request."""
        # This test verifies we don't make unnecessary API calls
        # for obviously invalid tokens
        result = validate_token("bad_token")
        success, message = result

        # Should fail with format message, not API error
        assert success is False
        assert "must start with" in message.lower() or "ntn_" in message

    def test_valid_format_but_invalid_token_fails_gracefully(self):
        """Token with valid format but invalid value fails gracefully."""
        # This would fail at the API level, not format level
        # We can't test actual API without mocking
        result = validate_token("ntn_this_is_not_real_but_has_valid_format")
        success, message = result

        # Should fail (either connection or auth error)
        # The exact error depends on network availability
        assert success is False


# =============================================================================
# RETRY LOGIC TESTS (with mocking)
# =============================================================================

class TestRetryLogic:
    """Tests for api_call_with_retry function."""

    def test_successful_call_returns_immediately(self):
        """Successful API call returns without retry."""
        mock_func = Mock(return_value={"status": "ok"})
        result = api_call_with_retry(mock_func, "arg1", kwarg1="value1")

        assert result == {"status": "ok"}
        assert mock_func.call_count == 1
        mock_func.assert_called_with("arg1", kwarg1="value1")

    def test_non_retryable_error_raises_immediately(self):
        """Non-retryable errors raise without retry attempts."""
        from notion_client import APIResponseError, APIErrorCode

        # Create a real exception instance by subclassing
        class MockNotFoundError(APIResponseError):
            def __init__(self):
                self.code = APIErrorCode.ObjectNotFound
                self.message = "Object not found"

        mock_func = Mock(side_effect=MockNotFoundError())

        with pytest.raises(APIResponseError):
            api_call_with_retry(mock_func, max_retries=3)

        # Should only try once for non-retryable errors
        assert mock_func.call_count == 1

    def test_max_retries_exceeded_raises(self):
        """Exceeding max retries raises RuntimeError."""
        from notion_client import APIResponseError, APIErrorCode

        # Create a real exception instance by subclassing
        class MockRateLimitError(APIResponseError):
            def __init__(self):
                self.code = APIErrorCode.RateLimited
                self.message = "Rate limited"
                self.additional_data = {"retry_after": 0}  # No wait for testing

        mock_func = Mock(side_effect=MockRateLimitError())

        with pytest.raises(RuntimeError, match="Max retries"):
            api_call_with_retry(mock_func, max_retries=3)

        # Should have tried 3 times
        assert mock_func.call_count == 3


# =============================================================================
# EDGE CASES
# =============================================================================

class TestClientEdgeCases:
    """Edge case tests for client functions."""

    def test_empty_token_is_invalid(self):
        """Empty string token is rejected."""
        result = validate_token("")
        success, _ = result
        assert success is False

    def test_whitespace_only_token_is_invalid(self):
        """Whitespace-only token is rejected."""
        result = validate_token("   ")
        success, _ = result
        assert success is False

    def test_token_with_valid_prefix_but_short(self):
        """Short token with valid prefix is still format-valid."""
        # Format is valid, but API will reject
        result = validate_token("ntn_")
        # Format check passes, but API call fails
        success, _ = result
        assert success is False  # API rejects

    def test_case_sensitivity_of_prefix(self):
        """Token prefix is case-sensitive."""
        # NTN_ is NOT valid (must be lowercase)
        result = validate_token("NTN_abc123")
        success, _ = result
        assert success is False


if __name__ == "__main__":
    pytest.main([__file__, "-v"])

# /// script
# requires-python = ">=3.11"
# dependencies = ["pytest>=8.0.0", "notion-client>=2.6.0"]
# ///
"""Tests for filter builder functions.

Oracle Source: Notion API Reference - Database Query Filter
https://developers.notion.com/reference/post-database-query-filter

Test Principles Applied:
- Oracles from domain rules (Notion API docs), NOT code behavior
- Black-box: Test public interface against oracle
- White-box: Test internal structure matches API spec
- Invalid inputs must raise exceptions
- Deterministic with documented tolerances
"""

import pytest
import sys
from pathlib import Path

# Add scripts to path for imports
sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))

from query_database import (
    checkbox_filter,
    select_filter,
    status_filter,
    text_contains_filter,
    date_after_filter,
    date_before_filter,
    number_greater_than_filter,
    number_less_than_filter,
    and_filter,
    or_filter,
    sort_by_property,
    sort_by_created_time,
    sort_by_last_edited_time,
)


# =============================================================================
# ORACLES: Structures defined by Notion API documentation (independent source)
# =============================================================================

class NotionFilterOracle:
    """Oracle structures from Notion API Reference.

    Source: https://developers.notion.com/reference/post-database-query-filter
    Retrieved: 2025-12-23
    """

    @staticmethod
    def checkbox(property_name: str, equals: bool) -> dict:
        """Oracle: Checkbox filter structure per API docs."""
        return {
            "property": property_name,
            "checkbox": {"equals": equals}
        }

    @staticmethod
    def select(property_name: str, equals: str) -> dict:
        """Oracle: Select filter structure per API docs."""
        return {
            "property": property_name,
            "select": {"equals": equals}
        }

    @staticmethod
    def status(property_name: str, equals: str) -> dict:
        """Oracle: Status filter structure per API docs."""
        return {
            "property": property_name,
            "status": {"equals": equals}
        }

    @staticmethod
    def rich_text_contains(property_name: str, contains: str) -> dict:
        """Oracle: Rich text contains filter structure per API docs."""
        return {
            "property": property_name,
            "rich_text": {"contains": contains}
        }

    @staticmethod
    def date_after(property_name: str, after: str) -> dict:
        """Oracle: Date after filter structure per API docs."""
        return {
            "property": property_name,
            "date": {"after": after}
        }

    @staticmethod
    def date_before(property_name: str, before: str) -> dict:
        """Oracle: Date before filter structure per API docs."""
        return {
            "property": property_name,
            "date": {"before": before}
        }

    @staticmethod
    def number_gt(property_name: str, value: int | float) -> dict:
        """Oracle: Number greater than filter structure per API docs."""
        return {
            "property": property_name,
            "number": {"greater_than": value}
        }

    @staticmethod
    def number_lt(property_name: str, value: int | float) -> dict:
        """Oracle: Number less than filter structure per API docs."""
        return {
            "property": property_name,
            "number": {"less_than": value}
        }

    @staticmethod
    def compound_and(*filters: dict) -> dict:
        """Oracle: AND compound filter structure per API docs."""
        return {"and": list(filters)}

    @staticmethod
    def compound_or(*filters: dict) -> dict:
        """Oracle: OR compound filter structure per API docs."""
        return {"or": list(filters)}


# =============================================================================
# INTEGRITY TESTS: First principles validation
# =============================================================================

class TestFilterBuilderIntegrity:
    """Integrity tests validating first principles."""

    def test_all_simple_filters_have_property_field(self):
        """First principle: Simple filters must have 'property' field."""
        filters = [
            checkbox_filter("Done", True),
            select_filter("Status", "Active"),
            status_filter("Status", "Done"),
            text_contains_filter("Title", "test"),
            date_after_filter("Date", "2025-01-01"),
            date_before_filter("Date", "2025-12-31"),
            number_greater_than_filter("Count", 10),
            number_less_than_filter("Count", 100),
        ]
        for f in filters:
            assert "property" in f, f"Filter missing 'property' field: {f}"

    def test_compound_filters_have_correct_key(self):
        """First principle: Compound filters use 'and'/'or' key."""
        f1 = checkbox_filter("A", True)
        f2 = checkbox_filter("B", False)

        and_result = and_filter(f1, f2)
        or_result = or_filter(f1, f2)

        assert "and" in and_result
        assert "or" in or_result

    def test_compound_filters_contain_arrays(self):
        """First principle: Compound filter values are arrays."""
        f1 = checkbox_filter("A", True)
        f2 = checkbox_filter("B", False)

        and_result = and_filter(f1, f2)
        or_result = or_filter(f1, f2)

        assert isinstance(and_result["and"], list)
        assert isinstance(or_result["or"], list)


# =============================================================================
# BLACK-BOX TESTS: Public interface against oracle
# =============================================================================

class TestFilterBuildersBlackBox:
    """Black-box tests: Verify output matches Notion API oracle."""

    def test_checkbox_filter_true_matches_oracle(self):
        """Checkbox filter (true) matches Notion API specification."""
        result = checkbox_filter("Done", True)
        oracle = NotionFilterOracle.checkbox("Done", True)
        assert result == oracle

    def test_checkbox_filter_false_matches_oracle(self):
        """Checkbox filter (false) matches Notion API specification."""
        result = checkbox_filter("Archived", False)
        oracle = NotionFilterOracle.checkbox("Archived", False)
        assert result == oracle

    def test_select_filter_matches_oracle(self):
        """Select filter matches Notion API specification."""
        result = select_filter("Priority", "High")
        oracle = NotionFilterOracle.select("Priority", "High")
        assert result == oracle

    def test_status_filter_matches_oracle(self):
        """Status filter matches Notion API specification."""
        result = status_filter("Status", "In Progress")
        oracle = NotionFilterOracle.status("Status", "In Progress")
        assert result == oracle

    def test_text_contains_filter_matches_oracle(self):
        """Text contains filter matches Notion API specification."""
        result = text_contains_filter("Name", "API")
        oracle = NotionFilterOracle.rich_text_contains("Name", "API")
        assert result == oracle

    def test_date_after_filter_matches_oracle(self):
        """Date after filter matches Notion API specification."""
        result = date_after_filter("Due Date", "2025-01-01")
        oracle = NotionFilterOracle.date_after("Due Date", "2025-01-01")
        assert result == oracle

    def test_date_before_filter_matches_oracle(self):
        """Date before filter matches Notion API specification."""
        result = date_before_filter("Created", "2025-12-31")
        oracle = NotionFilterOracle.date_before("Created", "2025-12-31")
        assert result == oracle

    def test_number_greater_than_filter_matches_oracle(self):
        """Number greater than filter matches Notion API specification."""
        result = number_greater_than_filter("Score", 90)
        oracle = NotionFilterOracle.number_gt("Score", 90)
        assert result == oracle

    def test_number_less_than_filter_matches_oracle(self):
        """Number less than filter matches Notion API specification."""
        result = number_less_than_filter("Age", 30)
        oracle = NotionFilterOracle.number_lt("Age", 30)
        assert result == oracle

    def test_and_filter_matches_oracle(self):
        """AND compound filter matches Notion API specification."""
        f1 = checkbox_filter("Done", True)
        f2 = number_greater_than_filter("Days", 10)

        result = and_filter(f1, f2)
        oracle = NotionFilterOracle.compound_and(f1, f2)
        assert result == oracle

    def test_or_filter_matches_oracle(self):
        """OR compound filter matches Notion API specification."""
        f1 = text_contains_filter("Tag", "A")
        f2 = text_contains_filter("Tag", "B")

        result = or_filter(f1, f2)
        oracle = NotionFilterOracle.compound_or(f1, f2)
        assert result == oracle


# =============================================================================
# WHITE-BOX TESTS: Internal structure validation
# =============================================================================

class TestFilterBuildersWhiteBox:
    """White-box tests: Verify internal structure details."""

    def test_nested_compound_filter(self):
        """Nested compound filters maintain correct structure."""
        # Build: (A AND B) OR C
        a = checkbox_filter("A", True)
        b = select_filter("B", "opt")
        c = status_filter("C", "Done")

        inner = and_filter(a, b)
        outer = or_filter(inner, c)

        assert "or" in outer
        assert len(outer["or"]) == 2
        assert "and" in outer["or"][0]

    def test_filter_preserves_property_name_exactly(self):
        """Filter preserves property name with exact casing/spacing."""
        result = select_filter("My Custom Property", "Value")
        assert result["property"] == "My Custom Property"

    def test_number_filter_preserves_float(self):
        """Number filter preserves float precision."""
        result = number_greater_than_filter("Score", 3.14159)
        assert result["number"]["greater_than"] == 3.14159


# =============================================================================
# SORT BUILDER TESTS
# =============================================================================

class TestSortBuilders:
    """Tests for sort builder functions."""

    def test_sort_by_property_ascending(self):
        """Sort by property (ascending) creates correct structure."""
        result = sort_by_property("Name", "ascending")
        assert result == {"property": "Name", "direction": "ascending"}

    def test_sort_by_property_descending(self):
        """Sort by property (descending) creates correct structure."""
        result = sort_by_property("Date", "descending")
        assert result == {"property": "Date", "direction": "descending"}

    def test_sort_by_created_time(self):
        """Sort by created_time creates correct structure."""
        result = sort_by_created_time("descending")
        assert result == {"timestamp": "created_time", "direction": "descending"}

    def test_sort_by_last_edited_time(self):
        """Sort by last_edited_time creates correct structure."""
        result = sort_by_last_edited_time("ascending")
        assert result == {"timestamp": "last_edited_time", "direction": "ascending"}

    def test_sort_default_direction(self):
        """Sort functions have sensible defaults."""
        # created_time defaults to descending (most recent first)
        result = sort_by_created_time()
        assert result["direction"] == "descending"


# =============================================================================
# EDGE CASES AND COMPOUND FILTER TESTS
# =============================================================================

class TestFilterEdgeCases:
    """Edge case and complex filter tests."""

    def test_empty_and_filter(self):
        """AND filter with no arguments creates empty array."""
        result = and_filter()
        assert result == {"and": []}

    def test_single_item_compound(self):
        """Compound filter with single item is valid."""
        f = checkbox_filter("Done", True)
        result = and_filter(f)
        assert result == {"and": [f]}

    def test_many_items_in_compound(self):
        """Compound filter supports many items."""
        filters = [checkbox_filter(f"Prop{i}", True) for i in range(10)]
        result = and_filter(*filters)
        assert len(result["and"]) == 10

    def test_deeply_nested_compounds(self):
        """Deeply nested compound filters work correctly."""
        # ((A AND B) OR (C AND D)) AND E
        a = checkbox_filter("A", True)
        b = checkbox_filter("B", True)
        c = checkbox_filter("C", True)
        d = checkbox_filter("D", True)
        e = checkbox_filter("E", True)

        ab = and_filter(a, b)
        cd = and_filter(c, d)
        ab_or_cd = or_filter(ab, cd)
        final = and_filter(ab_or_cd, e)

        assert "and" in final
        assert len(final["and"]) == 2
        assert "or" in final["and"][0]

    def test_unicode_in_property_names(self):
        """Unicode characters in property names are preserved."""
        result = select_filter("状態", "完了")  # Japanese: Status, Done
        assert result["property"] == "状態"
        assert result["select"]["equals"] == "完了"

    def test_special_characters_in_text_filter(self):
        """Special characters in text filter are preserved."""
        result = text_contains_filter("Title", "Hello! @#$%^&*()")
        assert result["rich_text"]["contains"] == "Hello! @#$%^&*()"


if __name__ == "__main__":
    pytest.main([__file__, "-v"])

# /// script
# requires-python = ">=3.11"
# dependencies = ["pytest>=8.0.0", "notion-client>=2.6.0"]
# ///
"""Integration tests for Notion API operations.

These tests make REAL API calls to Notion.
Requires NOTION_TOKEN environment variable.

Test Database: Books & Audiobooks (8eacdd87-6c53-431a-9dec-55932ac571b5)
Properties: Name (title), Author (rich_text), Format (select), Tags (multi_select),
            Status (select), Date Read (date), Rating (number), Audio Page (url)

Test Principles:
- Integration tests verify end-to-end API behavior
- Created resources are cleaned up after tests
- Tests are idempotent and can run repeatedly
"""

import os
import sys
import time
import pytest
from pathlib import Path

# Add scripts to path for imports
sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))

from notion_wrapper import get_client, validate_token, api_call_with_retry
from create_page import (
    create_database_page,
    title_property,
    rich_text_property,
    number_property,
    select_property,
)
from add_blocks import paragraph, heading, bullet, divider, append_blocks
from query_database import number_greater_than_filter


# =============================================================================
# FIXTURES
# =============================================================================

# Test database ID (Books & Audiobooks)
TEST_DATABASE_ID = "8eacdd87-6c53-431a-9dec-55932ac571b5"


@pytest.fixture(scope="module")
def notion_token():
    """Get Notion token from environment."""
    token = os.environ.get("NOTION_TOKEN")
    if not token:
        pytest.skip("NOTION_TOKEN not set - skipping integration tests")
    return token


@pytest.fixture(scope="module")
def client(notion_token):
    """Create authenticated Notion client."""
    return get_client(notion_token)


@pytest.fixture
def cleanup_pages(client):
    """Fixture to track and cleanup created pages."""
    created_page_ids = []

    yield created_page_ids

    # Cleanup: Archive all created pages
    for page_id in created_page_ids:
        try:
            client.pages.update(page_id, archived=True)
        except Exception:
            pass  # Best effort cleanup


# =============================================================================
# TOKEN VALIDATION TESTS
# =============================================================================

class TestTokenValidation:
    """Integration tests for token validation."""

    def test_valid_token_authenticates(self, notion_token):
        """Valid token successfully authenticates."""
        success, message = validate_token(notion_token)
        assert success is True
        assert "Authenticated as" in message

    def test_invalid_token_fails(self):
        """Invalid token (valid format) fails authentication."""
        success, message = validate_token("ntn_invalid_token_12345")
        assert success is False
        # Should fail with API error, not format error
        assert "ntn_" not in message or "secret_" not in message


# =============================================================================
# DATABASE QUERY TESTS (Read-only, safe to run repeatedly)
# =============================================================================

class TestDatabaseQuery:
    """Integration tests for database queries."""

    def test_query_database_returns_results(self, client):
        """Query returns results from the database."""
        results = api_call_with_retry(
            client.data_sources.query,
            TEST_DATABASE_ID,
            page_size=5
        )

        assert "results" in results
        assert isinstance(results["results"], list)
        # Database has content
        assert len(results["results"]) > 0

    def test_query_database_with_filter(self, client):
        """Query with filter returns filtered results."""
        # Query for books with rating > 0 (should reduce result count)
        results = api_call_with_retry(
            client.data_sources.query,
            TEST_DATABASE_ID,
            filter=number_greater_than_filter("Rating", 0),
            page_size=10
        )

        assert "results" in results
        # All results should have rating > 0
        for row in results["results"]:
            rating = row["properties"]["Rating"]["number"]
            if rating is not None:
                assert rating > 0

    def test_query_database_with_pagination(self, client):
        """Query respects page_size limit."""
        results = api_call_with_retry(
            client.data_sources.query,
            TEST_DATABASE_ID,
            page_size=2
        )

        # Should return at most 2 results
        assert len(results["results"]) <= 2

        # If more results exist, should have next_cursor
        if results.get("has_more"):
            assert results.get("next_cursor") is not None

    def test_query_returns_expected_properties(self, client):
        """Query results contain expected property types."""
        results = api_call_with_retry(
            client.data_sources.query,
            TEST_DATABASE_ID,
            page_size=1
        )

        if results["results"]:
            row = results["results"][0]
            props = row["properties"]

            # Verify expected properties exist
            assert "Name" in props
            assert props["Name"]["type"] == "title"

            assert "Rating" in props
            assert props["Rating"]["type"] == "number"

            assert "Author" in props
            assert props["Author"]["type"] == "rich_text"


# =============================================================================
# PAGE CREATION TESTS (Creates and cleans up pages)
# =============================================================================

class TestPageCreation:
    """Integration tests for page creation."""

    def test_create_page_in_database(self, client, cleanup_pages):
        """Create a page in the database with properties."""
        # Create test page
        properties = {
            "Name": title_property("[TEST] Integration Test Book"),
            "Author": rich_text_property("Test Author"),
            "Rating": number_property(5),
        }

        page = api_call_with_retry(
            create_database_page,
            client,
            TEST_DATABASE_ID,
            properties
        )

        # Track for cleanup
        cleanup_pages.append(page["id"])

        # Verify page was created
        assert "id" in page
        assert page["object"] == "page"

        # Verify properties were set
        assert page["properties"]["Name"]["title"][0]["plain_text"] == "[TEST] Integration Test Book"
        assert page["properties"]["Rating"]["number"] == 5

    def test_create_page_with_select_property(self, client, cleanup_pages):
        """Create a page with select property."""
        properties = {
            "Name": title_property("[TEST] Book with Format"),
            "Format": select_property("Physical"),
        }

        page = api_call_with_retry(
            create_database_page,
            client,
            TEST_DATABASE_ID,
            properties
        )

        cleanup_pages.append(page["id"])

        # Verify select was set
        format_prop = page["properties"]["Format"]["select"]
        assert format_prop is not None
        assert format_prop["name"] == "Physical"


# =============================================================================
# BLOCK APPEND TESTS (Creates page, adds blocks, cleans up)
# =============================================================================

class TestBlockAppend:
    """Integration tests for block operations."""

    def test_append_blocks_to_page(self, client, cleanup_pages):
        """Append blocks to a newly created page."""
        # Create a test page first
        properties = {
            "Name": title_property("[TEST] Page with Blocks"),
        }

        page = api_call_with_retry(
            create_database_page,
            client,
            TEST_DATABASE_ID,
            properties
        )
        cleanup_pages.append(page["id"])

        # Append blocks
        blocks = [
            heading("Test Heading", 1),
            paragraph("This is a test paragraph."),
            bullet("First bullet point"),
            bullet("Second bullet point"),
            divider(),
            paragraph("Content after divider."),
        ]

        result = api_call_with_retry(
            append_blocks,
            client,
            page["id"],
            blocks
        )

        # Verify blocks were added
        assert "results" in result
        assert len(result["results"]) == 6

        # Verify block types
        assert result["results"][0]["type"] == "heading_1"
        assert result["results"][1]["type"] == "paragraph"
        assert result["results"][2]["type"] == "bulleted_list_item"
        assert result["results"][4]["type"] == "divider"

    def test_retrieve_appended_blocks(self, client, cleanup_pages):
        """Retrieve blocks after appending to verify persistence."""
        # Create page with blocks
        properties = {"Name": title_property("[TEST] Page for Block Retrieval")}

        page = api_call_with_retry(
            create_database_page,
            client,
            TEST_DATABASE_ID,
            properties
        )
        cleanup_pages.append(page["id"])

        # Append a paragraph
        blocks = [paragraph("Persistent paragraph content")]
        api_call_with_retry(append_blocks, client, page["id"], blocks)

        # Small delay for API consistency
        time.sleep(0.5)

        # Retrieve blocks
        children = api_call_with_retry(
            client.blocks.children.list,
            page["id"]
        )

        assert len(children["results"]) >= 1
        block = children["results"][0]
        assert block["type"] == "paragraph"
        assert block["paragraph"]["rich_text"][0]["plain_text"] == "Persistent paragraph content"


# =============================================================================
# RATE LIMIT TESTS (Verify retry logic works)
# =============================================================================

class TestRateLimitHandling:
    """Tests for rate limit handling (implicit in rapid operations)."""

    def test_rapid_queries_succeed(self, client):
        """Multiple rapid queries succeed with retry logic."""
        # Make several queries rapidly - retry logic should handle any rate limits
        for i in range(5):
            results = api_call_with_retry(
                client.data_sources.query,
                TEST_DATABASE_ID,
                page_size=1
            )
            assert "results" in results

        # If we get here, rate limit handling worked


if __name__ == "__main__":
    pytest.main([__file__, "-v"])