vikunja-python 0.1.0__py3-none-any.whl

vikunja_python/core/models/link_sharing.py

@@ -0,0 +1,138 @@
+"""
+Link Sharing Models
+
+Models for project link sharing functionality.
+Based on Vikunja API v2.3.0 specification.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import IntEnum
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SharingType(IntEnum):
+    """Types of link sharing for projects."""
+    
+    UNDEFINED = 0
+    """Undefined sharing type"""
+    
+    WITHOUT_PASSWORD = 1
+    """Shared without password protection"""
+    
+    WITH_PASSWORD = 2
+    """Shared with password protection"""
+
+
+class Permission(IntEnum):
+    """Permission levels for project sharing."""
+    
+    READ_ONLY = 0
+    """Read-only access - can view but not modify"""
+    
+    READ_WRITE = 1
+    """Write access - can create, update, delete own items"""
+    
+    ADMIN = 2
+    """Admin access - full control including member management"""
+
+
+class User(BaseModel):
+    """User representation for link sharing."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    id: int = Field(..., description="The unique user ID")
+    username: str = Field(..., description="The username")
+    name: str = Field(..., description="The full name of the user")
+    email: Optional[str] = Field(None, description="The email address of the user")
+
+
+class LinkSharing(BaseModel):
+    """Link sharing configuration for a project.
+    
+    Represents a public share link that allows access to a project without
+    requiring user authentication. Can be password-protected.
+    """
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    id: int = Field(..., description="The ID of the shared thing")
+    hash: str = Field(..., description="The public id to get this shared project")
+    name: str = Field(..., description="The name of this link share. All actions someone takes while being authenticated with that link will be attributed to this name.")
+    permission: Permission = Field(
+        Permission.READ_ONLY, 
+        description="The permission this project is shared with. 0 = Read only, 1 = Read & Write, 2 = Admin."
+    )
+    sharing_type: SharingType = Field(
+        SharingType.UNDEFINED, 
+        description="The kind of this link. 0 = undefined, 1 = without password, 2 = with password."
+    )
+    shared_by: Optional[User] = Field(None, description="The user who shared this project")
+    created: datetime = Field(..., description="A timestamp when this project was shared. You cannot change this value.")
+    updated: datetime = Field(..., description="A timestamp when this share was last updated. You cannot change this value.")
+    
+    # Password is write-only - can be set but not retrieved after creation
+    password: Optional[str] = Field(None, description="The password of this link share. You can only set it, not retrieve it after the link share has been created.")
+
+
+class LinkSharingCreateRequest(BaseModel):
+    """Request to create a new link share for a project."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    name: str = Field(..., max_length=255, description="The name of this link share")
+    password: Optional[str] = Field(None, description="Optional password for the link share. If provided, sharing_type will be set to WITH_PASSWORD.")
+    permission: Optional[Permission] = Field(
+        Permission.READ_ONLY, 
+        description="The permission level for this share. 0 = Read only, 1 = Read & Write, 2 = Admin."
+    )
+
+
+class LinkSharingUpdateRequest(BaseModel):
+    """Request to update an existing link share."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    name: Optional[str] = Field(None, max_length=255, description="The name of this link share")
+    password: Optional[str] = Field(None, description="New password for the link share. Set to empty string to remove password protection.")
+    permission: Optional[Permission] = Field(
+        None, 
+        description="The permission level for this share. 0 = Read only, 1 = Read & Write, 2 = Admin."
+    )
+
+
+class LinkSharingListResponse(BaseModel):
+    """Response containing a list of link shares."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    shares: list[LinkSharing] = Field(default_factory=list, description="List of link shares")
+
+
+class LinkSharingGetResponse(BaseModel):
+    """Response containing a single link share."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    share: LinkSharing = Field(..., description="The link share details (password not included)")
+
+
+class LinkSharingCreateResponse(BaseModel):
+    """Response from creating a link share."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    share: LinkSharing = Field(..., description="The created link share")
+    public_url: str = Field(..., description="The public URL for accessing this shared project")
+
+
+class LinkSharingDeleteResponse(BaseModel):
+    """Response from deleting a link share."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    success: bool = Field(..., description="Whether the deletion was successful")

vikunja_python/core/models/migration.py

@@ -0,0 +1,404 @@
+"""
+CSV Import and Migration Models for Vikunja API
+
+Covers: csv.* (CSV import), migration.Status, microsofttodo.*, todoist.*, trello.*
+
+CSV Import Workflow:
+1. Upload CSV file → GET /import/csv/preview
+2. Get DetectionResult with suggested column mappings
+3. Submit ColumnMapping to configure import
+4. POST /import/csv to complete import
+
+Migration Workflow:
+1. Authenticate with external service (Microsoft Todo, Todoist, Trello)
+2. POST /migration/{service} with auth code
+3. Monitor migration status via GET /migration/status
+
+Supported Migration Sources:
+- Microsoft Todo
+- Todoist  
+- Trello
+"""
+
+from pydantic import Field
+from datetime import datetime
+from typing import Optional, List, Any
+from .base import VikunjaBaseModel
+
+
+# ============================================================================
+# CSV Task Attribute Enum (11 values)
+# ============================================================================
+
+TaskAttribute = str
+"""CSV column attribute mapping.
+
+API spec: csv.TaskAttribute
+
+Enum Values:
+    "title" - Task title (AttrTitle)
+    "description" - Task description (AttrDescription)
+    "due_date" - Due date field (AttrDueDate)
+    "start_date" - Start date field (AttrStartDate)
+    "end_date" - End date field (AttrEndDate)
+    "done" - Completion status (AttrDone)
+    "priority" - Priority level (AttrPriority)
+    "labels" - Labels/Tags (AttrLabels)
+    "project" - Project assignment (AttrProject)
+    "reminder" - Reminder date/time (AttrReminder)
+    "ignore" - Skip this column (AttrIgnore)
+
+Usage:
+    from models.migration import TaskAttribute
+    
+    # Map CSV columns to task attributes
+    mapping = ColumnMapping(
+        attribute=TaskAttribute("title"),
+        column_name="Task Name",
+        column_index=0
+    )
+"""
+
+# Named constants for clarity
+AttrTitle = "title"
+AttrDescription = "description"
+AttrDueDate = "due_date"
+AttrStartDate = "start_date"
+AttrEndDate = "end_date"
+AttrDone = "done"
+AttrPriority = "priority"
+AttrLabels = "labels"
+AttrProject = "project"
+AttrReminder = "reminder"
+AttrIgnore = "ignore"
+
+
+# ============================================================================
+# CSV Import Models
+# ============================================================================
+
+class ColumnMapping(VikunjaBaseModel):
+    """
+    Mapping between a CSV column and a task attribute.
+    
+    API endpoint: Part of CSV import configuration
+    
+    Maps a specific column from the uploaded CSV file to a Vikunja task attribute.
+    
+    Fields from API spec (csv.ColumnMapping):
+        - attribute: The task attribute to map to
+        - column_index: Zero-based index of the column in CSV
+        - column_name: Human-readable name of the column
+    
+    Example from API response:
+        {
+            "attribute": "title",
+            "column_index": 0,
+            "column_name": "Task Name"
+        }
+    
+    Usage:
+        # Map first column to task title
+        mapping = ColumnMapping(
+            attribute=AttrTitle,
+            column_index=0,
+            column_name="Task Name"
+        )
+        
+        # Ignore a column (e.g., notes that don't map to any field)
+        ignore_mapping = ColumnMapping(
+            attribute=AttrIgnore,
+            column_index=5,
+            column_name="Internal Notes"
+        )
+    """
+    
+    # Core Mapping (3 fields)
+    attribute: TaskAttribute = Field(
+        ..., 
+        description="Task attribute to map this column to"
+    )
+    column_index: int = Field(..., ge=0, description="Zero-based column index in CSV")
+    column_name: str = Field(..., description="Human-readable column name")
+
+
+class DetectionResult(VikunjaBaseModel):
+    """
+    CSV file detection and analysis result.
+    
+    API endpoint: GET /import/csv/preview
+    
+    Returned when uploading a CSV file for import. Contains detected format
+    information and suggested column mappings.
+    
+    Fields from API spec (csv.DetectionResult):
+        - columns: List of column names from first row
+        - delimiter: Detected delimiter (comma, semicolon, tab, etc.)
+        - quote_char: Detected quote character
+        - date_format: Detected date format string
+        - preview_rows: Sample data rows (typically 5-10 rows)
+        - suggested_mapping: Auto-detected column-to-attribute mappings
+    
+    Example from API response:
+        {
+            "columns": ["Task Name", "Description", "Due Date", "Done"],
+            "delimiter": ",",
+            "quote_char": "\"",
+            "date_format": "%Y-%m-%d",
+            "preview_rows": [
+                ["Buy milk", "Groceries", "2024-01-20", "false"],
+                ["Write report", "Work", "2024-01-25", "true"]
+            ],
+            "suggested_mapping": [
+                {"attribute": "title", "column_index": 0, "column_name": "Task Name"},
+                {"attribute": "description", "column_index": 1, "column_name": "Description"},
+                {"attribute": "due_date", "column_index": 2, "column_name": "Due Date"},
+                {"attribute": "done", "column_index": 3, "column_name": "Done"}
+            ]
+        }
+    
+    Usage:
+        # Get detection result after uploading CSV
+        detection = DetectionResult.model_validate(api_response)
+        
+        # Use suggested mappings or customize
+        for mapping in detection.suggested_mapping:
+            print(f"Column '{mapping.column_name}' → {mapping.attribute}")
+    """
+    
+    # Format Detection (4 fields)
+    columns: Optional[List[str]] = Field(
+        None, 
+        description="Column names from first row of CSV"
+    )
+    delimiter: Optional[str] = Field(None, description="Detected field delimiter")
+    quote_char: Optional[str] = Field(None, description="Detected quote character")
+    date_format: Optional[str] = Field(None, description="Detected date format string")
+    
+    # Preview Data (1 field)
+    preview_rows: Optional[List[List[str]]] = Field(
+        None, 
+        description="Sample data rows from CSV"
+    )
+    
+    # Suggested Mappings (1 field)
+    suggested_mapping: Optional[List[ColumnMapping]] = Field(
+        None, 
+        description="Auto-detected column-to-attribute mappings"
+    )
+
+
+class PreviewTask(VikunjaBaseModel):
+    """
+    A single task preview from CSV import.
+    
+    API endpoint: Part of PreviewResult
+    
+    Represents how a row from the CSV file will be imported as a task.
+    
+    Fields from API spec (csv.PreviewTask):
+        - title: Task title
+        - description: Task description
+        - due_date: Due date string
+        - start_date: Start date string
+        - end_date: End date string
+        - done: Completion status
+        - priority: Priority level
+        - labels: List of label names
+        - project: Project name
+    
+    Example from API response:
+        {
+            "title": "Buy milk",
+            "description": "Groceries",
+            "due_date": "2024-01-20",
+            "start_date": null,
+            "end_date": null,
+            "done": false,
+            "priority": 0,
+            "labels": ["shopping"],
+            "project": "Personal"
+        }
+    """
+    
+    # Core Task Fields (3 fields)
+    title: Optional[str] = Field(None, description="Task title")
+    description: Optional[str] = Field(None, description="Task description")
+    done: Optional[bool] = Field(None, description="Completion status")
+    
+    # Date Fields (3 fields)
+    due_date: Optional[str] = Field(None, description="Due date string")
+    start_date: Optional[str] = Field(None, description="Start date string")
+    end_date: Optional[str] = Field(None, description="End date string")
+    
+    # Additional Fields (3 fields)
+    priority: Optional[int] = Field(None, ge=0, description="Priority level")
+    labels: Optional[List[str]] = Field(None, description="List of label names")
+    project: Optional[str] = Field(None, description="Project name")
+
+
+class PreviewResult(VikunjaBaseModel):
+    """
+    CSV import preview result.
+    
+    API endpoint: GET /import/csv/preview
+    
+    Shows how the uploaded CSV file will be imported, with all tasks parsed.
+    
+    Fields from API spec (csv.PreviewResult):
+        - tasks: List of parsed tasks from CSV rows
+        - total_rows: Total number of rows in CSV
+    
+    Example from API response:
+        {
+            "tasks": [
+                {"title": "Buy milk", "done": false, ...},
+                {"title": "Write report", "done": true, ...}
+            ],
+            "total_rows": 25
+        }
+    
+    Usage:
+        # Get preview after uploading CSV and configuring mappings
+        preview = PreviewResult.model_validate(api_response)
+        
+        print(f"Importing {preview.total_rows} tasks:")
+        for task in preview.tasks:
+            status = "✓" if task.done else "○"
+            print(f"  {status} {task.title}")
+    """
+    
+    # Preview Data (2 fields)
+    tasks: Optional[List[PreviewTask]] = Field(
+        None, 
+        description="List of parsed tasks from CSV rows"
+    )
+    total_rows: Optional[int] = Field(None, ge=0, description="Total number of rows in CSV")
+
+
+# ============================================================================
+# Migration Status Model
+# ============================================================================
+
+class MigrationStatus(VikunjaBaseModel):
+    """
+    Status of an ongoing migration from external service.
+    
+    API endpoint: GET /migration/status
+    
+    Tracks the progress of a migration job (Microsoft Todo, Todoist, Trello).
+    
+    Fields from API spec (migration.Status):
+        - id: Unique migration job identifier
+        - migrator_name: Name of the migration source (e.g., "todoist")
+        - started_at: When migration began
+        - finished_at: When migration completed (null if still running)
+    
+    Example from API response:
+        {
+            "id": 42,
+            "migrator_name": "todoist",
+            "started_at": "2024-01-15T10:30:00Z",
+            "finished_at": "2024-01-15T10:32:15Z"
+        }
+    
+    Usage:
+        # Check migration status
+        status = MigrationStatus.model_validate(api_response)
+        
+        if status.finished_at:
+            print(f"Migration completed at {status.finished_at}")
+        else:
+            print(f"Migration in progress since {status.started_at}")
+    """
+    
+    # Core Identification (2 fields)
+    id: Optional[int] = Field(None, description="Unique migration job ID")
+    migrator_name: Optional[str] = Field(
+        None, 
+        description="Name of migration source (e.g., 'todoist', 'microsofttodo', 'trello')"
+    )
+    
+    # Timing (2 fields)
+    started_at: Optional[datetime] = Field(None, description="Migration start timestamp")
+    finished_at: Optional[datetime] = Field(None, description="Migration completion timestamp")
+
+
+# ============================================================================
+# External Service Migration Models
+# ============================================================================
+
+class MicrosoftTodoMigrationRequest(VikunjaBaseModel):
+    """
+    Request body for Microsoft Todo migration.
+    
+    API endpoint: POST /migration/microsofttodo
+    
+    Required fields: code (OAuth authorization code)
+    
+    UNKNOWN: Full request structure requires API testing - only 'code' field confirmed
+    
+    Example:
+        req = MicrosoftTodoMigrationRequest(code="auth_code_from_oauth")
+    """
+    # Confirmed field from API spec
+    code: Optional[str] = Field(None, description="OAuth authorization code from Microsoft Todo")
+
+
+class TodoistMigrationRequest(VikunjaBaseModel):
+    """
+    Request body for Todoist migration.
+    
+    API endpoint: POST /migration/todoist
+    
+    Required fields: code (OAuth authorization code)
+    
+    UNKNOWN: Full request structure requires API testing - only 'code' field confirmed
+    
+    Example:
+        req = TodoistMigrationRequest(code="auth_code_from_oauth")
+    """
+    # Confirmed field from API spec
+    code: Optional[str] = Field(None, description="OAuth authorization code from Todoist")
+
+
+class TrelloMigrationRequest(VikunjaBaseModel):
+    """
+    Request body for Trello migration.
+    
+    API endpoint: POST /migration/trello
+    
+    Required fields: code (OAuth authorization code)
+    
+    UNKNOWN: Full request structure requires API testing - only 'code' field confirmed
+    
+    Example:
+        req = TrelloMigrationRequest(code="auth_code_from_oauth")
+    """
+    # Confirmed field from API spec
+    code: Optional[str] = Field(None, description="OAuth authorization code from Trello")
+
+
+# ============================================================================
+# Response Models
+# ============================================================================
+
+class CSVImportResponse(VikunjaBaseModel):
+    """Response for CSV import operations."""
+    success: bool = Field(True, description="Request succeeded")
+    imported_tasks: Optional[int] = Field(None, description="Number of tasks imported")
+    error: Optional[str] = Field(None, description="Error message if failed")
+
+
+class MigrationResponse(VikunjaBaseModel):
+    """Response for migration initiation."""
+    success: bool = Field(True, description="Request succeeded")
+    migration_id: Optional[int] = Field(None, description="Migration job ID")
+    error: Optional[str] = Field(None, description="Error message if failed")
+
+
+class MigrationStatusResponse(VikunjaBaseModel):
+    """Response for migration status check."""
+    success: bool = Field(True, description="Request succeeded")
+    status: Optional[MigrationStatus] = Field(None, description="Migration status")
+    error: Optional[str] = Field(None, description="Error message if failed")

vikunja_python/core/models/phase6_medium.py

@@ -0,0 +1,74 @@
+"""Phase 6: Medium Priority Models (Bucket, Reaction, Subscription)"""
+from pydantic import BaseModel, Field, ConfigDict
+from enum import IntEnum
+from datetime import datetime
+from typing import Optional
+from vikunja_python.core.models.base import User
+
+class ReactionKind(IntEnum):
+    """Reaction kinds as defined by Vikunja API."""
+    HEART = 1
+    THUMBS_UP = 2
+    FACE_WITH_TEARS_OF_JOY = 3
+
+class Reaction(BaseModel):
+    """Reaction on a task or comment."""
+    model_config = ConfigDict(extra='ignore')
+    value: str = Field(..., description="The emoji reaction value (e.g., Unicode emoji)")
+    user: Optional[User] = Field(None, description="The user who reacted")
+    created: datetime = Field(..., description="Timestamp of the reaction")
+
+class ReactionCreateRequest(BaseModel):
+    """Request to create a new reaction."""
+    model_config = ConfigDict(extra='ignore')
+    value: str = Field(..., description="The emoji reaction value")
+
+class ReactionMapEntry(BaseModel):
+    """A single entry in a reaction map."""
+    value: str
+    count: int
+
+class SubscriptionType(IntEnum):
+    """Types of subscriptions available."""
+    TASK = 1
+    PROJECT = 2
+
+class Subscription(BaseModel):
+    """A subscription to a task or project."""
+    model_config = ConfigDict(extra='ignore')
+    id: int
+    type: SubscriptionType = Field(..., description="The type of the subscription")
+    entity_id: int = Field(..., description="The ID of the subscribed task or project")
+    created: datetime = Field(..., description="Timestamp of creation")
+
+class SubscriptionCreateRequest(BaseModel):
+    """Request to create a new subscription."""
+    model_config = ConfigDict(extra='ignore')
+    type: SubscriptionType = Field(..., description="The type of the subscription")
+    entity_id: int = Field(..., description="The ID of the subscribed task or project")
+
+class Bucket(BaseModel):
+    """A bucket (column) in a Kanban board."""
+    model_config = ConfigDict(extra='ignore')
+    id: int
+    title: str = Field(..., description="The title of the bucket")
+    color: str | None = Field(None, description="Hex color of the bucket")
+    position: int = Field(..., description="Position in the board")
+
+class BucketCreateRequest(BaseModel):
+    """Request to create a new bucket."""
+    model_config = ConfigDict(extra='ignore')
+    title: str = Field(..., description="The title of the bucket")
+    color: str | None = Field(None, description="Hex color of the bucket")
+
+class BucketUpdateRequest(BaseModel):
+    """Request to update an existing bucket."""
+    model_config = ConfigDict(extra='ignore')
+    title: str | None = Field(None, description="The updated title")
+    color: str | None = Field(None, description="The updated color")
+    position: int | None = Field(None, description="The updated position")
+
+class BucketMoveRequest(BaseModel):
+    """Request to move a bucket."""
+    model_config = ConfigDict(extra='ignore')
+    new_position: int = Field(..., description="The new position of the bucket")