megaplan-sdk 0.1.0__py3-none-any.whl

megaplan_sdk/logging_config.py

@@ -0,0 +1,53 @@
+"""Logging configuration for Megaplan SDK."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+# Create logger for the SDK
+logger = logging.getLogger("megaplan_sdk")
+logger.setLevel(logging.WARNING)
+
+# Create formatter
+formatter = logging.Formatter(
+    fmt="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+
+# Create console handler
+console_handler = logging.StreamHandler()
+console_handler.setFormatter(formatter)
+logger.addHandler(console_handler)
+
+
+def setup_logging(level: str = "WARNING") -> None:
+    """Setup logging for SDK.
+
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+    """
+    logger.setLevel(getattr(logging, level.upper()))
+
+
+def sanitize_dict(data: dict[str, Any]) -> dict[str, Any]:
+    """Remove sensitive data from dict for logging.
+
+    Args:
+        data: Dictionary to sanitize.
+
+    Returns:
+        Sanitized dictionary with sensitive values redacted.
+    """
+    sensitive_keys = {
+        "password",
+        "access_token",
+        "refresh_token",
+        "Authorization",
+        "token",
+        "secret",
+        "api_key",
+        "apiKey",
+    }
+
+    return {k: "***REDACTED***" if k in sensitive_keys else v for k, v in data.items()}

megaplan_sdk/models/__init__.py

@@ -0,0 +1,22 @@
+"""Models for Megaplan SDK."""
+
+from megaplan_sdk.models.base import BaseEntity
+from megaplan_sdk.models.common import File, Meta, Pagination, SortField
+from megaplan_sdk.models.deal import Deal, ProgramState, TradeFilter
+from megaplan_sdk.models.project import Project, ProjectFilter
+from megaplan_sdk.models.task import Task, TaskFilter
+
+__all__ = [
+    "BaseEntity",
+    "Meta",
+    "Pagination",
+    "SortField",
+    "File",
+    "Task",
+    "TaskFilter",
+    "Project",
+    "ProjectFilter",
+    "Deal",
+    "TradeFilter",
+    "ProgramState",
+]

megaplan_sdk/models/base.py

@@ -0,0 +1,16 @@
+"""Base models for Megaplan SDK."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class BaseEntity(BaseModel):
+    """Base entity with contentType and id.
+
+    All Megaplan entities have contentType and id fields.
+    Link entities (for references) only contain these two fields.
+    """
+
+    content_type: str = Field(alias="contentType")
+    id: int
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")

megaplan_sdk/models/comment.py

@@ -0,0 +1,58 @@
+"""Comment model for Megaplan SDK."""
+
+from typing import Any
+
+from pydantic import ConfigDict, Field
+
+from megaplan_sdk.models.base import BaseEntity
+from megaplan_sdk.models.common import TimestampMixin
+
+
+class Comment(BaseEntity, TimestampMixin):
+    """Comment entity.
+
+    Attributes:
+        id: Comment identifier.
+        content_type: Entity content type (always "Comment").
+        subject: Parent entity (task, project, deal, etc.).
+        owner: Comment author (Employee, ContractorCompany, or ContractorHuman).
+        content: Comment text content.
+        attaches: List of attached files.
+        attaches_count: Number of attachments.
+        work_time: Work time interval (DateInterval entity with contentType, value).
+        work_date: Work date (DateTime entity with contentType, value, timestamp).
+        is_unread: Whether comment is unread.
+        is_dropped: Whether comment is deleted.
+        completed: Completion status.
+        created_at: Creation timestamp (timeCreated).
+        updated_at: Last update timestamp (timeUpdated).
+
+        Legacy fields for compatibility:
+        author: Alias for owner.
+        text: Alias for content.
+    """
+
+    content_type: str = Field(alias="contentType", default="Comment")
+    subject: BaseEntity | None = None
+    owner: BaseEntity | None = None
+    content: str | None = None
+    attaches: list[BaseEntity] | None = None
+    attaches_count: int | None = Field(alias="attachesCount", default=None)
+    work_time: dict[str, Any] | None = Field(alias="workTime", default=None)
+    work_date: dict[str, Any] | None = Field(alias="workDate", default=None)
+    is_unread: bool | None = Field(alias="isUnread", default=None)
+    is_dropped: bool | None = Field(alias="isDropped", default=None)
+    completed: int | None = None
+
+    # Legacy aliases for compatibility
+    @property
+    def author(self) -> BaseEntity | None:
+        """Alias for owner field."""
+        return self.owner
+
+    @property
+    def text(self) -> str | None:
+        """Alias for content field."""
+        return self.content
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")

megaplan_sdk/models/common.py

@@ -0,0 +1,107 @@
+"""Common models for Megaplan SDK."""
+
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+T = TypeVar("T")
+
+
+class Pagination(BaseModel):
+    """Pagination information from API response.
+
+    Attributes:
+        count: Total number of items.
+        limit: Items per page.
+    """
+
+    count: int = 0
+    limit: int = 100
+
+
+class Meta(BaseModel):
+    """Meta information from API response.
+
+    Attributes:
+        status: HTTP status code.
+        errors: List of error details.
+        pagination: Pagination information.
+    """
+
+    status: int = 200
+    errors: list[dict[str, Any]] = Field(default_factory=list)
+    pagination: Pagination | None = None
+
+
+class ApiResponse(BaseModel, Generic[T]):
+    """Generic API response wrapper.
+
+    Attributes:
+        meta: Meta information (status, errors, pagination).
+        data: Response data (single item or list).
+    """
+
+    meta: Meta
+    data: T
+
+
+class File(BaseModel):
+    """File model for file uploads and attachments.
+
+    Attributes:
+        id: File identifier.
+        content_type: File content type.
+        path: File path.
+        mime_type: MIME type.
+        name: File name.
+        size: File size in bytes.
+    """
+
+    id: int
+    content_type: str = Field(alias="contentType", default="File")
+    path: str | None = None
+    mime_type: str | None = Field(alias="mimeType", default=None)
+    name: str | None = None
+    size: int | None = None
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+
+class DateTime(BaseModel):
+    """DateTime model for date/time fields.
+
+    Megaplan API returns dates as objects with contentType and value.
+
+    Attributes:
+        content_type: Always "DateTime".
+        value: ISO 8601 datetime string.
+    """
+
+    content_type: str = Field(alias="contentType", default="DateTime")
+    value: str
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+
+class SortField(BaseModel):
+    """Sort field for API requests.
+
+    Attributes:
+        field: Field name to sort by.
+        direction: Sort direction (asc or desc).
+    """
+
+    field: str
+    direction: str = "asc"  # asc or desc
+
+
+class TimestampMixin(BaseModel):
+    """Mixin for entities with creation and update timestamps.
+
+    Attributes:
+        created_at: Entity creation timestamp.
+        updated_at: Entity last update timestamp.
+    """
+
+    created_at: str | DateTime | None = Field(alias="createdAt", default=None)
+    updated_at: str | DateTime | None = Field(alias="updatedAt", default=None)

megaplan_sdk/models/contractor.py

@@ -0,0 +1,137 @@
+"""Contractor models for Megaplan SDK."""
+
+from typing import Any
+
+from pydantic import ConfigDict, Field
+
+from megaplan_sdk.models.base import BaseEntity
+from megaplan_sdk.models.common import TimestampMixin
+
+
+class Contractor(BaseEntity, TimestampMixin):
+    """Base contractor entity.
+
+    Attributes:
+        id: Contractor identifier.
+        content_type: Entity content type (Contractor, ContractorCompany, ContractorHuman).
+        name: Contractor name.
+        email: Email address.
+        phone: Phone number.
+        site: Website URL.
+        description: Contractor description.
+        category: Contractor category.
+        manager: Responsible manager.
+        created_at: Creation timestamp.
+        updated_at: Last update timestamp.
+        status: Contractor status.
+        tags: List of tags.
+        custom_fields: Custom field values.
+    """
+
+    content_type: str = Field(alias="contentType", default="Contractor")
+    name: str | None = None
+    email: str | None = None
+    phone: str | None = None
+    site: str | None = None
+    description: str | None = None
+    category: BaseEntity | None = None
+    manager: BaseEntity | None = None
+    status: str | None = None
+    tags: list[BaseEntity | str] | None = None  # Can be Tag entities or strings
+    custom_fields: dict[str, Any] | None = Field(alias="customFields", default=None)
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    def display_name(self) -> str:
+        """Get display name for contractor.
+
+        Returns:
+            Contractor name or fallback ID representation.
+
+        Examples:
+            >>> contractor = Contractor(id=1, name="ACME Corp")
+            >>> contractor.display_name()
+            'ACME Corp'
+        """
+        return self.name or f"Contractor#{self.id}"
+
+    def __str__(self) -> str:
+        """Return display name for string representation.
+
+        Returns:
+            Display name.
+
+        Examples:
+            >>> contractor = Contractor(id=1, name="ACME Corp")
+            >>> str(contractor)
+            'ACME Corp'
+        """
+        return self.display_name()
+
+
+class ContractorCompany(Contractor):
+    """Company contractor entity.
+
+    Attributes:
+        content_type: Entity content type (always "ContractorCompany").
+        inn: Tax identification number (INN).
+        kpp: Tax registration reason code (KPP).
+        ogrn: Primary state registration number (OGRN).
+        legal_name: Legal company name.
+        legal_address: Legal address.
+        actual_address: Actual address.
+    """
+
+    content_type: str = Field(alias="contentType", default="ContractorCompany")
+    inn: str | None = None
+    kpp: str | None = None
+    ogrn: str | None = None
+    legal_name: str | None = Field(alias="legalName", default=None)
+    legal_address: str | None = Field(alias="legalAddress", default=None)
+    actual_address: str | None = Field(alias="actualAddress", default=None)
+
+
+class ContractorHuman(Contractor):
+    """Human contractor entity (individual).
+
+    Attributes:
+        content_type: Entity content type (always "ContractorHuman").
+        first_name: First name.
+        middle_name: Middle name.
+        last_name: Last name.
+        birthday: Birth date.
+        passport: Passport information.
+    """
+
+    content_type: str = Field(alias="contentType", default="ContractorHuman")
+    first_name: str | None = Field(alias="firstName", default=None)
+    middle_name: str | None = Field(alias="middleName", default=None)
+    last_name: str | None = Field(alias="lastName", default=None)
+    birthday: str | None = None
+    passport: str | None = None
+
+    def display_name(self) -> str:
+        """Get display name for human contractor.
+
+        Returns:
+            Full name or name field or fallback ID representation.
+
+        Examples:
+            >>> human = ContractorHuman(
+            ...     id=1, first_name="John", last_name="Doe"
+            ... )
+            >>> human.display_name()
+            'John Doe'
+        """
+        # Try to build from first/last name
+        parts = []
+        if self.first_name:
+            parts.append(self.first_name)
+        if self.last_name:
+            parts.append(self.last_name)
+
+        if parts:
+            return " ".join(parts)
+
+        # Fallback to name field or ID
+        return self.name or f"Contractor#{self.id}"

megaplan_sdk/models/deal.py

@@ -0,0 +1,96 @@
+"""Deal models for Megaplan SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from megaplan_sdk.models.base import BaseEntity
+from megaplan_sdk.models.common import DateTime, TimestampMixin
+
+
+class TradeFilter(BaseModel):
+    """Trade filter configuration for deals.
+
+    Can be used as filter ID (integer) or filter configuration (dict).
+    """
+
+    id: int | None = None
+    config: dict[str, Any] | None = None
+
+
+class ProgramState(BaseModel):
+    """Program state model.
+
+    Represents a state in a deal program.
+    """
+
+    id: int
+    content_type: str = Field(alias="contentType", default="ProgramState")
+    name: str | None = None
+    program: BaseEntity | None = None
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    def __str__(self) -> str:
+        """Return state name for display.
+
+        Returns:
+            State name or fallback ID representation.
+
+        Examples:
+            >>> state = ProgramState(id=1, name="In Progress")
+            >>> str(state)
+            'In Progress'
+        """
+        return self.name or f"State#{self.id}"
+
+
+class Deal(TimestampMixin):
+    """Deal model.
+
+    Represents a deal in Megaplan with all its properties.
+    """
+
+    id: int
+    content_type: str = Field(alias="contentType", default="Deal")
+    name: str | None = None
+    program: BaseEntity | None = None
+    state: ProgramState | None = None
+    contractor: BaseEntity | None = None
+    responsible: BaseEntity | None = None
+    sum_base: float | None = Field(alias="sumBase", default=None)
+    currency: BaseEntity | None = None
+    deadline: str | DateTime | dict[str, Any] | None = None  # Can be DateOnly, DateTime, or string
+    description: str | None = None
+    tags: list[BaseEntity] | None = None
+    attaches: list[BaseEntity] | None = None
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+
+class DealFullDetails(BaseModel):
+    """Full deal details with all related entities.
+
+    Attributes:
+        deal: Main deal entity.
+        comments: List of comments (if requested).
+        history: Change history entries (if requested).
+        status_history: Status change history (if requested).
+        auditors: List of auditors (if requested).
+        responsible_details: Full responsible employee details (if requested).
+        contractor_details: Full contractor details (if requested).
+        related_tasks: Tasks related to this deal (if requested).
+    """
+
+    deal: Deal
+    comments: list[Any] | None = None
+    history: list[dict[str, Any]] | None = None
+    status_history: list[dict[str, Any]] | None = None
+    auditors: list[dict[str, Any]] | None = None
+    responsible_details: Any | None = None
+    contractor_details: Any | None = None
+    related_tasks: list[Any] | None = None
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")

megaplan_sdk/models/department.py

@@ -0,0 +1,40 @@
+"""Department model for Megaplan SDK."""
+
+from pydantic import ConfigDict, Field
+
+from megaplan_sdk.models.base import BaseEntity
+from megaplan_sdk.models.common import TimestampMixin
+
+
+class Department(BaseEntity, TimestampMixin):
+    """Department entity.
+
+    Attributes:
+        id: Department identifier.
+        content_type: Entity content type (always "Department").
+        name: Department name.
+        parent: Parent department (if nested structure).
+        manager: Department manager (Employee reference).
+        created_at: Creation timestamp.
+        updated_at: Last update timestamp.
+    """
+
+    content_type: str = Field(alias="contentType", default="Department")
+    name: str | None = None
+    parent: BaseEntity | None = None
+    manager: BaseEntity | None = None
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    def __str__(self) -> str:
+        """Return department name for display.
+
+        Returns:
+            Department name or fallback ID representation.
+
+        Examples:
+            >>> dept = Department(id=1, name="Engineering")
+            >>> str(dept)
+            'Engineering'
+        """
+        return self.name or f"Department#{self.id}"

megaplan_sdk/models/employee.py

@@ -0,0 +1,117 @@
+"""Employee model for Megaplan SDK."""
+
+from typing import Any
+
+from pydantic import ConfigDict, Field
+
+from megaplan_sdk.models.base import BaseEntity
+from megaplan_sdk.models.common import DateTime, TimestampMixin
+
+
+class Employee(BaseEntity, TimestampMixin):
+    """Employee entity.
+
+    Attributes:
+        id: Employee identifier.
+        content_type: Entity content type (always "Employee").
+        first_name: First name.
+        middle_name: Middle name.
+        last_name: Last name.
+        email: Email address.
+        phone: Phone number.
+        position: Job position.
+        department: Department entity.
+        manager: Direct manager entity.
+        birthday: Birth date (DateOnly entity with year, month, day fields).
+        hired_at: Hire date.
+        fired_at: Termination date.
+        status: Employment status (EmployeeStatus entity with name, masterType).
+        avatar: Avatar image entity.
+        is_admin: Whether employee has admin rights.
+        is_client: Whether this is a client account.
+        access_role: Access role entity.
+        created_at: Creation timestamp.
+        updated_at: Last update timestamp.
+        custom_fields: Custom field values.
+    """
+
+    content_type: str = Field(alias="contentType", default="Employee")
+    first_name: str | None = Field(alias="firstName", default=None)
+    middle_name: str | None = Field(alias="middleName", default=None)
+    last_name: str | None = Field(alias="lastName", default=None)
+    email: str | None = None
+    phone: str | None = None
+    position: str | None = None
+    department: BaseEntity | None = None
+    manager: BaseEntity | None = None
+    birthday: dict[str, Any] | None = None  # DateOnly entity (year, month, day)
+    hired_at: str | DateTime | None = Field(alias="hiredAt", default=None)
+    fired_at: str | DateTime | None = Field(alias="firedAt", default=None)
+    status: BaseEntity | None = None  # EmployeeStatus entity
+    avatar: BaseEntity | None = None
+    is_admin: bool | None = Field(alias="isAdmin", default=None)
+    is_client: bool | None = Field(alias="isClient", default=None)
+    access_role: BaseEntity | None = Field(alias="accessRole", default=None)
+    custom_fields: dict[str, Any] | None = Field(alias="customFields", default=None)
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    def full_name(self, include_middle: bool = True) -> str:
+        """Get full name of the employee.
+
+        Args:
+            include_middle: Include middle name (default: True).
+
+        Returns:
+            Full name string.
+
+        Examples:
+            >>> employee = Employee(
+            ...     id=1, first_name="John", middle_name="A", last_name="Doe"
+            ... )
+            >>> employee.full_name()
+            'John A Doe'
+            >>> employee.full_name(include_middle=False)
+            'John Doe'
+        """
+        parts = []
+        if self.first_name:
+            parts.append(self.first_name)
+        if include_middle and self.middle_name:
+            parts.append(self.middle_name)
+        if self.last_name:
+            parts.append(self.last_name)
+        return " ".join(parts) if parts else f"Employee#{self.id}"
+
+    def display_name(self) -> str:
+        """Get display name with position.
+
+        Returns:
+            Full name with position in parentheses.
+
+        Examples:
+            >>> employee = Employee(
+            ...     id=1, first_name="John", last_name="Doe", position="CEO"
+            ... )
+            >>> employee.display_name()
+            'John Doe (CEO)'
+        """
+        name = self.full_name(include_middle=False)
+        if self.position:
+            return f"{name} ({self.position})"
+        return name
+
+    def __str__(self) -> str:
+        """Return display name for string representation.
+
+        Returns:
+            Display name with position.
+
+        Examples:
+            >>> employee = Employee(
+            ...     id=1, first_name="John", last_name="Doe", position="CEO"
+            ... )
+            >>> str(employee)
+            'John Doe (CEO)'
+        """
+        return self.display_name()