vikunja-python 0.1.0__py3-none-any.whl

vikunja_python/core/models/project.py

@@ -0,0 +1,217 @@
+"""
+Project Models for Vikunja API
+
+Covers: models.Project and related request/response types
+API endpoints: /projects, /projects/{id}
+"""
+
+from pydantic import Field, field_validator
+from datetime import datetime
+from typing import Optional, Any
+from .base import VikunjaBaseModel, User
+
+
+# ============================================================================
+# View Configuration Models (nested in Project)
+# ============================================================================
+
+class ViewFilter(VikunjaBaseModel):
+    """
+    Filter configuration for a project view.
+    
+    Used in: ProjectView.filter
+    """
+    s: Optional[str] = Field(None, description="Search term")
+    sort_by: Optional[list[str]] = Field(None, description="Fields to sort by")
+    order_by: Optional[str] = Field(None, description="Sort order (asc/desc)")
+    filter: Optional[str] = Field(None, description="Filter expression (e.g., 'done = false')")
+    filter_include_nulls: bool = Field(False, description="Include null values in filter")
+
+
+class BucketConfiguration(VikunjaBaseModel):
+    """
+    Bucket configuration for Kanban/board views.
+    
+    Used in: ProjectView.bucket_configuration
+    
+    UNKNOWN: Full structure not yet verified from API response
+    TODO: Extract from actual API call with project that has buckets configured
+    """
+    # UNKNOWN: Field definitions pending API verification
+    mode: Optional[str] = Field(None, description="Configuration mode (none/manual)")
+    # TODO: Add remaining fields after API inspection
+
+
+class ProjectView(VikunjaBaseModel):
+    """
+    View configuration within a project.
+    
+    Vikunja supports multiple view types per project:
+        - list: List view
+        - gantt: Gantt chart view  
+        - table: Table/spreadsheet view
+        - kanban: Kanban board with buckets
+    
+    Used in: Project.views[]
+    """
+    id: int = Field(..., description="Unique view identifier")
+    title: str = Field(..., description="View name/title")
+    project_id: int = Field(..., description="Parent project ID")
+    view_kind: str = Field(..., description="View type: list, gantt, table, kanban")
+    
+    # Filter configuration
+    filter: Optional[ViewFilter] = Field(None, description="View filter settings")
+    
+    # Positioning
+    position: int = Field(0, description="Display order within project")
+    
+    # Bucket configuration (for Kanban views)
+    bucket_configuration_mode: str = Field("none", description="Bucket mode: none, manual, automatic")
+    bucket_configuration: Optional[BucketConfiguration] = Field(None, description="Bucket settings")
+    default_bucket_id: int = Field(0, description="Default bucket for new tasks")
+    done_bucket_id: int = Field(0, description="Bucket for completed tasks")
+    
+    # Timestamps
+    created: datetime = Field(..., description="Creation timestamp")
+    updated: datetime = Field(..., description="Last update timestamp")
+
+
+# ============================================================================
+# Project Entity Model (18 fields from API)
+# ============================================================================
+
+class Project(VikunjaBaseModel):
+    """
+    Project model representing a project in Vikunja.
+    
+    API endpoint: GET /projects, GET /projects/{id}
+    
+    All 18 fields discovered from actual API response at v2.3.0:
+    https://vikunja.ok9.io/api/v1/projects
+    
+    Nested Objects:
+        - owner: User object (project creator)
+        - views[]: Array of ProjectView objects
+        - background_information: null or object (Unsplash background data)
+    
+    Special Values:
+        - parent_project_id: 0 = root level project
+        - position: 65536 for default Inbox project
+        - max_permission: null or int (0=read, 1=write, 2=admin)
+    """
+    
+    # Core Identification (5 fields)
+    id: int = Field(..., description="Unique project identifier")
+    title: str = Field(..., max_length=255, description="Project title")
+    description: Optional[str] = Field(None, max_length=10000, description="Project description (markdown)")
+    identifier: str = Field("", description="Short identifier/code for project")
+    hex_color: str = Field("", description="Project color (without #)")
+    
+    # Hierarchy (2 fields)
+    parent_project_id: int = Field(0, description="Parent project ID (0 = root level)")
+    owner: User = Field(..., description="Project owner/creator")
+    
+    # Status Flags (2 fields)
+    is_archived: bool = Field(False, description="Archived status")
+    is_favorite: bool = Field(False, description="Marked as favorite/starred")
+    
+    # Positioning (1 field)
+    position: int = Field(0, description="Display order (65536 for default Inbox)")
+    
+    # Settings & Configuration (4 fields)
+    background_information: Optional[Any] = Field(None, description="Background image info (Unsplash data)")
+    background_blur_hash: str = Field("", description="Blur hash for background preview")
+    views: list[ProjectView] = Field(default_factory=list, description="Configured views for this project")
+    max_permission: Optional[int] = Field(None, ge=0, le=2, description="Max permission level (0=read, 1=write, 2=admin)")
+    
+    # Timestamps (2 fields)
+    created: datetime = Field(..., description="Creation timestamp")
+    updated: datetime = Field(..., description="Last update timestamp")
+
+
+# ============================================================================
+# Project Request Models (for Create/Update operations)
+# ============================================================================
+
+class ProjectCreateRequest(VikunjaBaseModel):
+    """
+    Request body for creating a new project.
+    
+    Required fields: title
+    Optional fields: All other project properties
+    
+    API endpoint: PUT /projects
+    """
+    title: str = Field(..., min_length=1, max_length=255, description="Project title (required)")
+    
+    # Optional fields - only send if explicitly set
+    description: Optional[str] = Field(None, max_length=10000)
+    identifier: Optional[str] = None
+    hex_color: Optional[str] = None
+    
+    # Hierarchy
+    parent_project_id: Optional[int] = Field(None, description="Parent project ID (omit for root)")
+    
+    def model_dump_for_api(self) -> dict:
+        """Convert to dict, excluding None values."""
+        return self.model_dump(exclude_none=True)
+
+
+class ProjectUpdateRequest(VikunjaBaseModel):
+    """
+    Request body for updating an existing project.
+    
+    All fields optional - only provided fields are updated.
+    
+    API endpoint: POST /projects/{id} (PATCH semantics)
+    """
+    title: Optional[str] = Field(None, min_length=1, max_length=255)
+    description: Optional[str] = Field(None, max_length=10000)
+    identifier: Optional[str] = None
+    hex_color: Optional[str] = None
+    is_archived: Optional[bool] = None
+    is_favorite: Optional[bool] = None
+    
+    # Hierarchy (moving projects)
+    parent_project_id: Optional[int] = None
+    
+    def model_dump_for_api(self) -> dict:
+        """Convert to dict, excluding None values."""
+        return self.model_dump(exclude_none=True)
+
+
+# ============================================================================
+# Project List Request/Response Models
+# ============================================================================
+
+class ProjectListRequest(VikunjaBaseModel):
+    """
+    Query parameters for listing projects.
+    
+    API endpoint: GET /projects
+    
+    Pagination headers returned:
+        x-pagination-total-pages
+        x-pagination-result-count
+    """
+    # Pagination
+    page: int = Field(1, ge=1, description="Page number (1-based)")
+    per_page: int = Field(50, ge=1, le=100, description="Items per page")
+    
+    # Filtering
+    search: Optional[str] = Field(None, description="Search term for project title/description")
+    sort_by: Optional[str] = Field(None, description="Field to sort by (e.g., 'title', 'updated')")
+
+
+class ProjectListResponse(VikunjaBaseModel):
+    """
+    Response for project list operations.
+    
+    Includes pagination metadata from response headers.
+    """
+    success: bool = Field(True, description="Request succeeded")
+    projects: list[Project] = Field(default_factory=list, description="List of projects")
+    total_count: Optional[int] = Field(None, description="Total number of projects (across all pages)")
+    page: Optional[int] = Field(None, description="Current page number")
+    per_page: Optional[int] = Field(None, description="Items per page")
+    total_pages: Optional[int] = Field(None, description="Total number of pages")

vikunja_python/core/models/relation.py

@@ -0,0 +1,199 @@
+"""
+Task Relationship Models for Vikunja API
+
+Covers: models.TaskRelation, models.RelationKind, and related types
+API endpoints: /tasks/{id}/relations (implied - relationships are part of task CRUD)
+
+Relationship Types (12 kinds):
+- subtask/parenttask: Hierarchical parent-child relationships
+- blocking/blocked: Dependency relationships (A blocks B means B can't start until A done)
+- precedes/follows: Sequential ordering (A precedes B means A comes before B)
+- related: Generic association
+- duplicateof/duplicates: Duplicate task tracking
+- copiedfrom/copiedto: Source/destination of task copies
+
+Usage Examples:
+    # Create a subtask relationship (Task 2 is a subtask of Task 1)
+    relation = TaskRelation(
+        task_id=2,              # This task (the child/subtask)
+        other_task_id=1,        # Related task (the parent)
+        relation_kind="subtask" # This task IS A subtask of other_task
+    )
+    
+    # Create a blocking relationship (Task 1 blocks Task 2)
+    relation = TaskRelation(
+        task_id=1,              # This task (the blocker)
+        other_task_id=2,        # Blocked task (depends on this one)
+        relation_kind="blocking" # This task BLOCKS the other
+    )
+"""
+
+from pydantic import Field
+from datetime import datetime
+from typing import Optional, Literal
+from .base import VikunjaBaseModel, User
+
+
+# ============================================================================
+# Relation Kind Enum (12 types)
+# ============================================================================
+
+RelationKind = Literal[
+    "unknown",      # Default/undefined relationship
+    "subtask",       # This task IS A subtask of other_task (child → parent)
+    "parenttask",    # This task HAS OTHER as subtask (parent → child)
+    "related",       # Generic association (bidirectional)
+    "duplicateof",   # This task IS A DUPLICATE OF other_task
+    "duplicates",    # This task HAS OTHER AS duplicate (reverse of duplicateof)
+    "blocking",      # This task BLOCKS other_task (other can't start until this done)
+    "blocked",       # This task IS BLOCKED BY other_task (depends on other)
+    "precedes",      # This task COMES BEFORE other_task (sequential)
+    "follows",       # This task COMES AFTER other_task (sequential)
+    "copiedfrom",    # This task WAS COPIED FROM other_task (source)
+    "copiedto",      # This task IS A COPY IN other_task (destination)
+]
+
+# Human-readable descriptions for each relation kind
+RELATION_KIND_DESCRIPTIONS: dict[str, str] = {
+    "unknown": "Undefined relationship type",
+    "subtask": "This task is a subtask of the other task (child relationship)",
+    "parenttask": "This task has the other task as a subtask (parent relationship)",
+    "related": "Generic association between tasks",
+    "duplicateof": "This task is a duplicate of the other task",
+    "duplicates": "The other task is a duplicate of this task",
+    "blocking": "This task blocks the other task (other depends on this)",
+    "blocked": "This task is blocked by the other task (this depends on other)",
+    "precedes": "This task must be completed before the other task",
+    "follows": "This task comes after the other task in sequence",
+    "copiedfrom": "This task was copied from the other task (original)",
+    "copiedto": "This task is a copy of the other task (duplicate)",
+}
+
+
+# ============================================================================
+# Task Relation Model
+# ============================================================================
+
+class TaskRelation(VikunjaBaseModel):
+    """
+    Relationship between two tasks.
+    
+    API endpoint: Part of task CRUD, managed via /tasks/{id}/relations
+    
+    Key Concept: The relationship is FROM this task TO another task.
+    
+    Examples:
+        # Task 5 is a subtask of Task 1
+        relation = TaskRelation(
+            task_id=5,              # This task (the subtask)
+            other_task_id=1,        # Parent task
+            relation_kind="subtask" # "I am a subtask of other"
+        )
+        
+        # Task 3 blocks Task 7 (Task 7 can't start until Task 3 done)
+        relation = TaskRelation(
+            task_id=3,              # This task (the blocker)
+            other_task_id=7,        # Blocked task
+            relation_kind="blocking" # "I block the other task"
+        )
+        
+        # Task 2 is blocked by Task 4 (Task 2 depends on Task 4)
+        relation = TaskRelation(
+            task_id=2,              # This task (the one waiting)
+            other_task_id=4,        # Blocking task
+            relation_kind="blocked" # "I am blocked by the other task"
+        )
+    
+    Common Patterns:
+        - Subtask hierarchy: Use "subtask" from child to parent
+        - Dependencies: Use "blocking" for blocker, "blocked" for dependent
+        - Sequence: Use "precedes" for earlier task, "follows" for later
+    
+    Fields from API spec (models.TaskRelation):
+        - task_id: The "base" task (this task)
+        - other_task_id: The related task
+        - relation_kind: Type of relationship
+        - created: Auto-set timestamp
+        - created_by: User who created the relation
+    """
+    
+    # Core Identification (2 fields)
+    id: Optional[int] = Field(None, description="Unique relation identifier (auto-assigned)")
+    task_id: int = Field(..., description="This task's ID (the 'base' task)")
+    
+    # Relationship Definition (2 fields)
+    other_task_id: int = Field(..., description="ID of the related task")
+    relation_kind: RelationKind = Field(..., description="Type of relationship")
+    
+    # Metadata (2 fields - auto-managed by server)
+    created: Optional[datetime] = Field(None, description="Creation timestamp (read-only)")
+    created_by: Optional[User] = Field(None, description="User who created this relation")
+    
+    @property
+    def relationship_description(self) -> str:
+        """Human-readable description of this relationship."""
+        kind_desc = RELATION_KIND_DESCRIPTIONS.get(self.relation_kind, "Unknown relationship")
+        return f"Task {self.task_id} {kind_desc.lower()} (related task: {self.other_task_id})"
+
+
+# ============================================================================
+# Task Relation Request Models
+# ============================================================================
+
+class TaskRelationCreateRequest(VikunjaBaseModel):
+    """
+    Request body for creating a task relationship.
+    
+    Required fields: task_id, other_task_id, relation_kind
+    
+    API endpoint: POST /tasks/{id}/relations (implied)
+    
+    Example:
+        # Make Task 5 a subtask of Task 1
+        req = TaskRelationCreateRequest(
+            task_id=5,
+            other_task_id=1,
+            relation_kind="subtask"
+        )
+    """
+    task_id: int = Field(..., description="This task's ID (the base task)")
+    other_task_id: int = Field(..., description="Related task's ID")
+    relation_kind: RelationKind = Field(..., description="Type of relationship")
+    
+    def model_dump_for_api(self) -> dict:
+        """Convert to dict for API submission."""
+        return self.model_dump(exclude_none=True)
+
+
+class TaskRelationUpdateRequest(VikunjaBaseModel):
+    """
+    Request body for updating a task relationship.
+    
+    Only provided fields are updated.
+    
+    API endpoint: POST /tasks/{id}/relations/{relation_id} (implied)
+    """
+    other_task_id: Optional[int] = None
+    relation_kind: Optional[RelationKind] = None
+    
+    def model_dump_for_api(self) -> dict:
+        """Convert to dict, excluding None values."""
+        return self.model_dump(exclude_none=True)
+
+
+# ============================================================================
+# Task Relation Response Models
+# ============================================================================
+
+class TaskRelationListResponse(VikunjaBaseModel):
+    """Response for listing task relationships."""
+    success: bool = Field(True, description="Request succeeded")
+    relations: list[TaskRelation] = Field(default_factory=list, description="List of task relations")
+    error: Optional[str] = Field(None, description="Error message if failed")
+
+
+class TaskRelationGetResponse(VikunjaBaseModel):
+    """Response for getting a single task relationship."""
+    success: bool = Field(True, description="Request succeeded")
+    relation: Optional[TaskRelation] = Field(None, description="The task relation")
+    error: Optional[str] = Field(None, description="Error message if failed")

vikunja_python/core/models/task.py

@@ -0,0 +1,261 @@
+"""
+Task Models for Vikunja API
+
+Covers: models.Task and related request/response types
+API endpoints: /tasks, /projects/{id}/tasks, /tasks/{id}
+"""
+
+from pydantic import Field, field_validator, model_validator
+from datetime import datetime
+from typing import Optional, Any
+from .base import VikunjaBaseModel, User, Label
+
+
+# ============================================================================
+# Task Entity Model (27 fields from API)
+# ============================================================================
+
+class Task(VikunjaBaseModel):
+    """
+    Task model representing a single task in Vikunja.
+    
+    API endpoint: GET /tasks, GET /tasks/{id}
+    
+    All 27 fields discovered from actual API response at v2.3.0:
+    https://vikunja.ok9.io/api/v1/tasks
+    
+    Date Format: ISO 8601 with timezone (e.g., "2026-04-27T14:51:09-05:00")
+    Default Dates: "0001-01-01T00:00:00Z" represents null/unset
+    
+    Nested Objects:
+        - assignees[]: User objects
+        - labels[]: Full Label objects  
+        - created_by: User object
+        - related_tasks: dict (relation types)
+    
+    Nullable Fields (return null in API):
+        - attachments, reminders, reactions
+    """
+    
+    # Core Identification (6 fields)
+    id: int = Field(..., description="Unique task identifier")
+    title: str = Field(..., max_length=255, description="Task title (required)")
+    description: Optional[str] = Field(None, max_length=10000, description="Task description (markdown)")
+    identifier: str = Field(..., description="Task identifier within project (e.g., '#1')")
+    index: float = Field(0.0, description="Task index for ordering within view/bucket")
+    project_id: int = Field(..., description="Parent project ID")
+    
+    # Status Fields (3 fields)
+    done: bool = Field(False, description="Completion status")
+    done_at: Optional[datetime] = Field(None, description="Timestamp when task was marked done")
+    percent_done: float = Field(0.0, ge=0.0, le=100.0, description="Completion percentage (0-100)")
+    
+    # Priority & Importance (3 fields)
+    priority: int = Field(0, ge=0, le=5, description="Task priority (0-5, higher = more important)")
+    is_favorite: bool = Field(False, description="Marked as favorite/starred")
+    hex_color: str = Field("", description="Custom hex color for task (without #)")
+    
+    # Date/Time Fields (6 fields) - All ISO 8601 with timezone
+    created: datetime = Field(..., description="Creation timestamp")
+    updated: datetime = Field(..., description="Last update timestamp")
+    due_date: Optional[datetime] = Field(None, description="Due date/time")
+    start_date: Optional[datetime] = Field(None, description="Start date/time")
+    end_date: Optional[datetime] = Field(None, description="End date/time")
+    
+    # Note: "0001-01-01T00:00:00Z" is returned for unset dates - handle in validator
+    
+    # Recurrence Fields (2 fields)
+    repeat_after: int = Field(0, ge=0, description="Recurrence interval in seconds")
+    repeat_mode: int = Field(0, description="Recurrence mode (1=after completion, 2=after original due date)")
+    
+    # Positioning Fields (3 fields) - For Kanban/board views
+    bucket_id: int = Field(0, description="Bucket ID in board view")
+    position: float = Field(0.0, description="Position within bucket")
+    
+    # Nested Objects (4 fields)
+    assignees: Optional[list[User]] = Field(default_factory=list, description="Users assigned to this task")
+    labels: Optional[list[Label]] = Field(default_factory=list, description="Labels/tags on this task")
+    created_by: Optional[User] = Field(None, description="User who created this task")
+    related_tasks: Optional[dict[str, Any]] = Field(default_factory=dict, description="Related tasks by relation type")
+    subtasks: Optional[list['Task']] = Field(default_factory=list, description="Subtasks of this task (requires expand=subtasks)")
+    
+    # Nullable Fields (3 fields) - May be null in API response
+    attachments: Optional[list[Any]] = Field(None, description="File attachments (requires expand=attachments)")
+    reminders: Optional[list[Any]] = Field(None, description="Task reminders (requires expand=reminders)")
+    reactions: Optional[list[Any]] = Field(None, description="Emoji reactions (requires expand=reactions)")
+    
+    # Custom Fields (1 field) - UNKNOWN: Full structure not verified
+    custom_fields: Optional[dict[str, Any]] = Field(None, description="Custom field values")
+    
+    # Expanded Fields (not in base task summary, but available via expand)
+    comment_count: Optional[int] = Field(None, description="Count of comments on this task")
+    is_unread: Optional[bool] = Field(None, description="Whether the task is unread for the current user")
+    buckets: Optional[list[dict[str, Any]]] = Field(None, description="Kanban buckets this task belongs to")
+    
+    @model_validator(mode='after')
+    def populate_subtasks_from_relations(self) -> 'Task':
+        """Populate subtasks field from related_tasks['subtask'] if expanded."""
+        if not self.subtasks and self.related_tasks and "subtask" in self.related_tasks:
+            rels = self.related_tasks["subtask"]
+            if rels and isinstance(rels, list) and len(rels) > 0:
+                # API might return dicts or Task objects
+                # Use type(self) to avoid circular imports during definition
+                cls = type(self)
+                self.subtasks = [cls(**r) if isinstance(r, dict) else r for r in rels]
+        return self
+
+    @field_validator('start_date', 'end_date', mode='before')
+    @classmethod
+    def handle_default_dates(cls, v):
+        """Convert '0001-01-01T00:00:00Z' to None for unset dates."""
+        if v == "0001-01-01T00:00:00Z":
+            return None
+        return v
+    
+    @field_validator('due_date', 'done_at', mode='before')
+    @classmethod
+    def parse_datetime(cls, v):
+        """Parse ISO 8601 datetime strings."""
+        if v is None or v == "":
+            return None
+        # Handle timezone offset format (e.g., -05:00)
+        if isinstance(v, str):
+            try:
+                # Python 3.11+ handles timezone offsets natively
+                return datetime.fromisoformat(v)
+            except ValueError:
+                return None
+        return v
+
+
+# ============================================================================
+# Task Request Models (for Create/Update operations)
+# ============================================================================
+
+class TaskCreateRequest(VikunjaBaseModel):
+    """
+    Request body for creating a new task.
+    
+    Required fields: title
+    Optional fields: All other task properties
+    
+    API endpoint: POST /tasks, POST /projects/{id}/tasks
+    """
+    title: str = Field(..., min_length=1, max_length=255, description="Task title (required)")
+    
+    # Optional fields - only send if explicitly set
+    description: Optional[str] = Field(None, max_length=10000)
+    priority: Optional[int] = Field(None, ge=0, le=5)
+    due_date: Optional[datetime] = None
+    start_date: Optional[datetime] = None
+    end_date: Optional[datetime] = None
+    done: Optional[bool] = Field(None, description="Set initial completion status")
+    
+    # Recurrence
+    repeat_after: Optional[int] = Field(None, ge=0)
+    repeat_mode: Optional[int] = Field(None)
+    
+    # Assignments (IDs, not full objects)
+    assignee_ids: Optional[list[int]] = Field(None, description="User IDs to assign")
+    label_ids: Optional[list[int]] = Field(None, description="Label IDs to apply")
+    
+    # Positioning
+    bucket_id: Optional[int] = None
+    project_id: Optional[int] = None
+    
+    def model_dump_for_api(self) -> dict:
+        """
+        Convert to dict, excluding None values.
+        
+        Vikunja API expects only provided fields - don't send nulls.
+        """
+        return self.model_dump(exclude_none=True)
+
+
+class TaskUpdateRequest(VikunjaBaseModel):
+    """
+    Request body for updating an existing task.
+    
+    All fields optional - only provided fields are updated.
+    
+    API endpoint: POST /tasks/{id} (PATCH semantics)
+    """
+    title: Optional[str] = Field(None, min_length=1, max_length=255)
+    description: Optional[str] = Field(None, max_length=10000)
+    priority: Optional[int] = Field(None, ge=0, le=5)
+    done: Optional[bool] = None
+    due_date: Optional[datetime] = None
+    start_date: Optional[datetime] = None
+    end_date: Optional[datetime] = None
+    percent_done: Optional[float] = Field(None, ge=0.0, le=100.0)
+    is_favorite: Optional[bool] = None
+    hex_color: Optional[str] = None
+    
+    # Recurrence
+    repeat_after: Optional[int] = Field(None, ge=0)
+    repeat_mode: Optional[int] = None
+    
+    # Positioning
+    bucket_id: Optional[int] = None
+    position: Optional[float] = None
+    
+    def model_dump_for_api(self) -> dict:
+        """Convert to dict, excluding None values."""
+        return self.model_dump(exclude_none=True)
+
+
+# ============================================================================
+# Task List Request/Response Models
+# ============================================================================
+
+class TaskListRequest(VikunjaBaseModel):
+    """
+    Query parameters for listing tasks.
+    
+    API endpoint: GET /tasks, GET /projects/{id}/tasks
+    
+    Pagination headers returned:
+        x-pagination-total-pages
+        x-pagination-result-count
+    """
+    # Filtering
+    project_id: Optional[int] = Field(None, description="Filter by project ID")
+    filter: Optional[str] = Field(None, description="Vikunja filter syntax (e.g., 'done = false')")
+    filter_timezone: Optional[str] = Field(None, description="Timezone for date filters")
+    filter_include_nulls: bool = Field(False, description="Include null-valued fields in filter")
+    
+    # Pagination
+    page: int = Field(1, ge=1, description="Page number (1-based)")
+    per_page: int = Field(50, ge=1, le=100, description="Items per page")
+    
+    # Sorting
+    sort_by: Optional[list[str]] = Field(None, description="Fields to sort by (e.g., ['due_date', 'priority'])")
+    order_by: Optional[str] = Field(None, pattern="^(asc|desc)$", description="Sort order")
+    
+    # Expansion (fetch nested objects)
+    expand: Optional[list[str]] = Field(
+        None, 
+        description=(
+            "Expand nested objects to include metadata in summaries. "
+            "Valid: subtasks, comments, reactions, buckets, comment_count, is_unread. "
+            "Invalid (412): attachments, reminders, assignees — explicitly marked as do-not-use for listing. "
+            "Note: list_tasks() returns summaries only (no full descriptions). Use get_task() for full details."
+        )
+    )
+
+
+class TaskListResponse(VikunjaBaseModel):
+    """
+    Response for task list operations.
+    
+    Includes pagination metadata from response headers.
+    """
+    success: bool = Field(True, description="Request succeeded")
+    tasks: list[Task] = Field(default_factory=list, description="List of tasks")
+    total_count: Optional[int] = Field(None, description="Total number of tasks (across all pages)")
+    page: Optional[int] = Field(None, description="Current page number")
+    per_page: Optional[int] = Field(None, description="Items per page")
+    total_pages: Optional[int] = Field(None, description="Total number of pages")
+
+# Rebuild model for recursive subtasks
+Task.model_rebuild()