vikunja-python 0.1.0__py3-none-any.whl

vikunja_python/core/models/__init__.py

@@ -0,0 +1,377 @@
+"""
+Vikunja Pydantic Models - Package Exports
+
+This package provides Pydantic v2 models for the Vikunja API (v2.3.0).
+Models are the source of truth for all API interactions.
+
+Usage:
+    from vikunja_python.models import Task, Project, TaskCreateRequest
+    
+    # Create a task
+    task = TaskCreateRequest(title="My Task", priority=3)
+"""
+
+# Base configuration and shared models
+from .base import (
+    VikunjaBaseModel,
+    User,
+    ErrorDetail,
+    Message,
+    Token,
+    PaginationInfo,
+    ListResponse,
+)
+
+# Task models
+from .task import (
+    Task,
+    TaskCreateRequest,
+    TaskUpdateRequest,
+    TaskListRequest,
+    TaskListResponse,
+)
+
+# Project models
+from .project import (
+    Project,
+    ProjectCreateRequest,
+    ProjectUpdateRequest,
+    ProjectListRequest,
+    ProjectListResponse,
+    ProjectView,
+    ViewFilter,
+    BucketConfiguration,
+)
+
+# Filter models
+from .filter import (
+    SavedFilter,
+    SavedFilterCreateRequest,
+    SavedFilterUpdateRequest,
+    SavedFilterListResponse,
+    SavedFilterGetResponse,
+    TaskCollection,
+)
+
+# Label models
+from .label import (
+    Label,
+    LabelCreateRequest,
+    LabelUpdateRequest,
+    LabelListResponse,
+    LabelGetResponse,
+    LabelCreateResponse,
+    LabelUpdateResponse,
+)
+
+# Task expansion models (comments, attachments, reminders)
+from .task_expansion import (
+    TaskComment,
+    TaskAttachment,
+    TaskReminder,
+    ReminderRelation,
+    TaskCommentsResponse,
+    TaskAttachmentsResponse,
+    TaskRemindersResponse,
+)
+
+# Relationship models
+from .relation import (
+    RelationKind,
+    RELATION_KIND_DESCRIPTIONS,
+    TaskRelation,
+    TaskRelationCreateRequest,
+    TaskRelationUpdateRequest,
+    TaskRelationListResponse,
+    TaskRelationGetResponse,
+)
+
+# User and Team models
+from .user import (
+    # Core user models
+    User,
+    UserSettings,
+    UserWithSettings,
+    
+    # Permission enum
+    Permission,
+    PERMISSION_DESCRIPTIONS,
+    
+    # Auth request models
+    LoginRequest,
+    RegisterRequest,
+    EmailUpdateRequest,
+    PasswordResetRequest,
+    
+    # TOTP models
+    TOTPSetupResponse,
+    TOTPPasscodeRequest,
+    
+    # Project user models
+    ProjectUser,
+    ProjectUserCreateRequest,
+    ProjectUserUpdateRequest,
+    
+    # Team models
+    TeamUser,
+    TeamMember,
+    Team,
+    TeamCreateRequest,
+    TeamUpdateRequest,
+    TeamWithPermission,
+    TeamProject,
+    
+    # Response models
+    UserGetResponse,
+    LoginResponse,
+    TeamListResponse,
+    TeamGetResponse,
+    ProjectUserListResponse,
+)
+
+# CSV Import and Migration models
+from .migration import (
+    # CSV Task Attribute enum
+    TaskAttribute,
+    AttrTitle,
+    AttrDescription,
+    AttrDueDate,
+    AttrStartDate,
+    AttrEndDate,
+    AttrDone,
+    AttrPriority,
+    AttrLabels,
+    AttrProject,
+    AttrReminder,
+    AttrIgnore,
+    
+    # CSV Import models
+    ColumnMapping,
+    DetectionResult,
+    PreviewTask,
+    PreviewResult,
+    
+    # Migration models
+    MigrationStatus,
+    MicrosoftTodoMigrationRequest,
+    TodoistMigrationRequest,
+    TrelloMigrationRequest,
+    
+    # Response models
+    CSVImportResponse,
+    MigrationResponse,
+    MigrationStatusResponse,
+)
+
+# Webhook models
+from .webhook import (
+    # Webhook Event types
+    WebhookEvent,
+    TaskCreated,
+    TaskUpdated,
+    TaskDeleted,
+    TaskCompleted,
+    TaskUncompleted,
+    CommentCreated,
+    CommentUpdated,
+    CommentDeleted,
+    
+    # Webhook models
+    Webhook,
+    WebhookCreateRequest,
+    WebhookUpdateRequest,
+    
+    # Response models
+    WebhookListResponse,
+    WebhookGetResponse,
+    WebhookCreateResponse,
+    WebhookDeleteResponse,
+)
+
+# API Token models (Phase 5 - High Priority)
+from .api_token import (
+    # Enums
+    Permission as APIPermission,
+    SharingType as APISharingType,
+    
+    # Core models
+    RouteDetail,
+    APITokenRoute,
+    APIToken,
+    
+    # Request models
+    APITokenCreateRequest,
+    APITokenUpdateRequest,
+    
+    # Response models
+    APITokenListResponse,
+    APITokenGetResponse,
+    APITokenCreateResponse,
+    APITokenDeleteResponse,
+)
+
+# Bulk Assignment models (Phase 5 - High Priority)
+from .bulk_assignees import (
+    User as BulkUser,
+    BulkAssignees,
+    BulkAssigneesCreateRequest,
+    BulkAssigneesResponse,
+    BulkTask,
+    BulkTaskResponse,
+)
+
+# Link Sharing models (Phase 5 - High Priority)
+from .link_sharing import (
+    # Enums
+    SharingType,
+    Permission as LinkPermission,
+    
+    # Core models
+    LinkSharing,
+    
+    # Request models
+    LinkSharingCreateRequest,
+    LinkSharingUpdateRequest,
+    
+    # Response models
+    LinkSharingListResponse,
+    LinkSharingGetResponse,
+    LinkSharingCreateResponse,
+    LinkSharingDeleteResponse,
+)
+
+__all__ = [
+    # Base models
+    "VikunjaBaseModel",
+    "User",
+    "ErrorDetail",
+    "Message",
+    "Token",
+    "PaginationInfo",
+    "ListResponse",
+    
+    # Task models
+    "Task",
+    "TaskCreateRequest",
+    "TaskUpdateRequest",
+    "TaskListRequest",
+    "TaskListResponse",
+    
+    # Project models
+    "Project",
+    "ProjectCreateRequest",
+    "ProjectUpdateRequest",
+    "ProjectListRequest",
+    "ProjectListResponse",
+    "ProjectView",
+    "ViewFilter",
+    "BucketConfiguration",
+    
+    # Filter models
+    "SavedFilter",
+    "SavedFilterCreateRequest",
+    "SavedFilterUpdateRequest",
+    "SavedFilterListResponse",
+    "SavedFilterGetResponse",
+    "TaskCollection",
+    
+    # Label models
+    "Label",
+    "LabelCreateRequest",
+    "LabelUpdateRequest",
+    "LabelListResponse",
+    "LabelGetResponse",
+    "LabelCreateResponse",
+    "LabelUpdateResponse",
+    
+    # Task expansion models (comments, attachments, reminders)
+    "TaskComment",
+    "TaskAttachment",
+    "TaskReminder",
+    "ReminderRelation",
+    "TaskCommentsResponse",
+    "TaskAttachmentsResponse",
+    "TaskRemindersResponse",
+    
+    # Relationship models
+    "RelationKind",
+    "RELATION_KIND_DESCRIPTIONS",
+    "TaskRelation",
+    "TaskRelationCreateRequest",
+    "TaskRelationUpdateRequest",
+    "TaskRelationListResponse",
+    "TaskRelationGetResponse",
+    
+    # User and Team models
+    "User",
+    "UserSettings",
+    "UserWithSettings",
+    "Permission",
+    "PERMISSION_DESCRIPTIONS",
+    "LoginRequest",
+    "RegisterRequest",
+    "EmailUpdateRequest",
+    "PasswordResetRequest",
+    "TOTPSetupResponse",
+    "TOTPPasscodeRequest",
+    "ProjectUser",
+    "ProjectUserCreateRequest",
+    "ProjectUserUpdateRequest",
+    "TeamUser",
+    "TeamMember",
+    "Team",
+    "TeamCreateRequest",
+    "TeamUpdateRequest",
+    "TeamWithPermission",
+    "TeamProject",
+    "UserGetResponse",
+    "LoginResponse",
+    "TeamListResponse",
+    "TeamGetResponse",
+    "ProjectUserListResponse",
+    
+    # CSV Import and Migration models
+    "TaskAttribute",
+    "AttrTitle",
+    "AttrDescription",
+    "AttrDueDate",
+    "AttrStartDate",
+    "AttrEndDate",
+    "AttrDone",
+    "AttrPriority",
+    "AttrLabels",
+    "AttrProject",
+    "AttrReminder",
+    "AttrIgnore",
+    "ColumnMapping",
+    "DetectionResult",
+    "PreviewTask",
+    "PreviewResult",
+    "MigrationStatus",
+    "MicrosoftTodoMigrationRequest",
+    "TodoistMigrationRequest",
+    "TrelloMigrationRequest",
+    "CSVImportResponse",
+    "MigrationResponse",
+    "MigrationStatusResponse",
+    
+    # Webhook models
+    "WebhookEvent",
+    "TaskCreated",
+    "TaskUpdated",
+    "TaskDeleted",
+    "TaskCompleted",
+    "TaskUncompleted",
+    "CommentCreated",
+    "CommentUpdated",
+    "CommentDeleted",
+    "Webhook",
+    "WebhookCreateRequest",
+    "WebhookUpdateRequest",
+    "WebhookListResponse",
+    "WebhookGetResponse",
+    "WebhookCreateResponse",
+    "WebhookDeleteResponse",
+]
+
+__version__ = "0.6.0"

vikunja_python/core/models/api_token.py

@@ -0,0 +1,131 @@
+"""
+API Token Management Models
+
+Models for managing Vikunja API tokens, including creation, listing, and permission details.
+Based on Vikunja API v2.3.0 specification.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import IntEnum
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Permission(IntEnum):
+    """Permission levels for API tokens and 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 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 RouteDetail(BaseModel):
+    """API route detail for token permissions."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    method: str = Field(..., description="HTTP method (GET, POST, PUT, DELETE)")
+    path: str = Field(..., description="API path pattern")
+
+
+class APITokenRoute(BaseModel):
+    """API token route definition."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    # Note: API spec shows empty object - may be populated with route details
+    # Placeholder for future expansion when /routes endpoint is fully documented
+    pass
+
+
+class APIToken(BaseModel):
+    """API token representation.
+    
+    Represents an API key that can be used to authenticate requests to the Vikunja API.
+    The actual token value is only visible immediately after creation.
+    """
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    id: int = Field(..., description="The unique, numeric id of this api key")
+    title: str = Field(..., max_length=255, description="A human-readable name for this token")
+    created: datetime = Field(..., description="A timestamp when this api key was created. You cannot change this value.")
+    expires_at: Optional[datetime] = Field(None, description="The date when this key expires. Null means no expiration.")
+    permissions: dict = Field(default_factory=dict, description="The permissions this token has. Possible values are available via the /routes endpoint and consist of HTTP method + path combinations.")
+    
+    # The actual token value - only visible after creation
+    # This field is typically set only on create response
+    token: Optional[str] = Field(None, description="The actual api key. Only visible after creation. Store this securely!")
+
+
+class APITokenCreateRequest(BaseModel):
+    """Request to create a new API token."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    title: str = Field(..., max_length=255, description="A human-readable name for this token")
+    expires_at: Optional[datetime] = Field(None, description="The date when this key expires. Null means no expiration.")
+    permissions: Optional[Dict[str, List[str]]] = Field(None, description="Map of resource names to lists of allowed actions (e.g., {'projects': ['create', 'read_all']}). If null, grants all permissions.")
+
+
+class APITokenUpdateRequest(BaseModel):
+    """Request to update an API token."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    title: Optional[str] = Field(None, max_length=255, description="A human-readable name for this token")
+    expires_at: Optional[datetime] = Field(None, description="The date when this key expires. Null means no expiration.")
+
+
+class APITokenListResponse(BaseModel):
+    """Response containing a list of API tokens."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    tokens: list[APIToken] = Field(default_factory=list, description="List of API tokens")
+
+
+class APITokenGetResponse(BaseModel):
+    """Response containing a single API token (with sensitive data)."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    token: APIToken = Field(..., description="The API token details")
+
+
+class APITokenCreateResponse(BaseModel):
+    """Response from creating an API token (includes the actual token value)."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    token: APIToken = Field(..., description="The created API token with the actual token value")
+    warning: Optional[str] = Field(None, description="Warning message about storing the token securely")
+
+
+class APITokenDeleteResponse(BaseModel):
+    """Response from deleting an API token."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    success: bool = Field(..., description="Whether the deletion was successful")

vikunja_python/core/models/auth.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Dict, List, Optional
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class APIPermissions(BaseModel):
+    model_config = ConfigDict(extra='ignore')
+
+    # Using a dict of lists to represent the structure discovered in the PUT request
+    # e.g., {"projects": ["create", "delete"], "tasks": ["read_all"]}
+    # We'll use a generic Dict for the actual implementation to handle the vast array of keys.
+    pass
+
+
+class APIToken(BaseModel):
+    model_config = ConfigDict(extra='ignore')
+
+    id: int
+    title: str
+    token: str
+    permissions: Dict[str, List[str]]
+    expires_at: Optional[datetime] = None
+    created: datetime
+    updated: Optional[datetime] = None
+
+
+class APITokenCreateRequest(BaseModel):
+    model_config = ConfigDict(extra='ignore')
+
+    title: str
+    permissions: Dict[str, List[str]]
+    expires_at: Optional[datetime] = None