Add model classes

Activity, CheckResult, DayType, OAuthTokens, RequestResult, RequestType (enum),
FeedbackCategory (enum), VoiceCodePair -- frozen dataclasses with from_api_response
factory methods matching PHP reference.

Co-Authored-By: claude-flow <ruv@ruv.net>

Author: Allow2CEO

allow2_service/models/__init__.py

@@ -0,0 +1,21 @@
+"""Allow2 SDK data models."""
+
+from allow2_service.models.activity import Activity
+from allow2_service.models.check_result import CheckResult
+from allow2_service.models.day_type import DayType
+from allow2_service.models.feedback_category import FeedbackCategory
+from allow2_service.models.oauth_tokens import OAuthTokens
+from allow2_service.models.request_result import RequestResult
+from allow2_service.models.request_type import RequestType
+from allow2_service.models.voice_code_pair import VoiceCodePair
+
+__all__ = [
+    "Activity",
+    "CheckResult",
+    "DayType",
+    "FeedbackCategory",
+    "OAuthTokens",
+    "RequestResult",
+    "RequestType",
+    "VoiceCodePair",
+]

allow2_service/models/activity.py

@@ -0,0 +1,55 @@
+"""Represents the permission state of a single activity from a check result."""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field
+from typing import Any, ClassVar, Dict
+
+
+@dataclass(frozen=True)
+class Activity:
+    """Represents the permission state of a single activity from a check result.
+
+    Attributes:
+        id: The activity ID.
+        name: Human-readable activity name.
+        allowed: Whether this activity is currently allowed.
+        remaining: Remaining seconds for this activity.
+        banned: Whether this activity is banned indefinitely.
+        time_block_allowed: Whether the current time block permits this activity.
+    """
+
+    # Well-known activity IDs (class variables, not dataclass fields)
+    SCREEN_TIME: ClassVar[int] = 8
+    GAMING: ClassVar[int] = 3
+    INTERNET: ClassVar[int] = 1
+    SOCIAL: ClassVar[int] = 6
+
+    id: int
+    name: str
+    allowed: bool
+    remaining: int
+    banned: bool
+    time_block_allowed: bool
+
+    @staticmethod
+    def from_array(data: Dict[str, Any]) -> Activity:
+        """Create from a single activity entry in the API check response.
+
+        Args:
+            data: Activity dictionary from the API response.
+
+        Returns:
+            An Activity instance.
+        """
+        return Activity(
+            id=int(data.get("id", 0)),
+            name=str(data.get("activity", data.get("name", ""))),
+            allowed=bool(data.get("allowed", False)),
+            remaining=int(data.get("remaining", 0)),
+            banned=bool(data.get("banned", False)),
+            time_block_allowed=bool(
+                data.get("timeblock", data.get("timeBlockAllowed", True))
+            ),
+        )

allow2_service/models/check_result.py

@@ -0,0 +1,116 @@
+"""Result of a permission check from the Allow2 service API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from allow2_service.models.activity import Activity
+from allow2_service.models.day_type import DayType
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """Result of a permission check from the Allow2 service API.
+
+    Contains the overall allowed status, per-activity breakdown,
+    and current/upcoming day type information.
+
+    Attributes:
+        allowed: Whether the child is globally allowed right now.
+        activities: Per-activity permission breakdown.
+        today_day_type: The current day type.
+        tomorrow_day_type: The upcoming day type (if provided).
+        raw: The raw API response for advanced use.
+    """
+
+    allowed: bool
+    activities: List[Activity]
+    today_day_type: Optional[DayType]
+    tomorrow_day_type: Optional[DayType]
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    def get_activity(self, activity_id: int) -> Optional[Activity]:
+        """Get a specific activity by ID, or None if not present.
+
+        Args:
+            activity_id: The activity ID to look up.
+
+        Returns:
+            The matching Activity, or None.
+        """
+        for activity in self.activities:
+            if activity.id == activity_id:
+                return activity
+        return None
+
+    def is_activity_allowed(self, activity_id: int) -> bool:
+        """Check whether a specific activity is allowed.
+
+        Args:
+            activity_id: The activity ID to check.
+
+        Returns:
+            True if the activity is present and allowed.
+        """
+        activity = self.get_activity(activity_id)
+        return activity is not None and activity.allowed
+
+    def get_remaining_seconds(self, activity_id: int) -> int:
+        """Get remaining seconds for a specific activity.
+
+        Args:
+            activity_id: The activity ID to check.
+
+        Returns:
+            Remaining seconds, or 0 if activity not found.
+        """
+        activity = self.get_activity(activity_id)
+        return activity.remaining if activity is not None else 0
+
+    @staticmethod
+    def from_api_response(response: Dict[str, Any]) -> CheckResult:
+        """Build from the raw API response.
+
+        Args:
+            response: The decoded JSON response from /serviceapi/check.
+
+        Returns:
+            A CheckResult instance.
+        """
+        activities: List[Activity] = []
+        raw_activities = response.get("activities", [])
+
+        for act_data in raw_activities:
+            activities.append(Activity.from_array(act_data))
+
+        today_day_type: Optional[DayType] = None
+        if "dayType" in response:
+            today_day_type = DayType.from_array(response["dayType"])
+        elif "today" in response:
+            today_day_type = DayType.from_array(response["today"])
+
+        tomorrow_day_type: Optional[DayType] = None
+        if "tomorrowDayType" in response:
+            tomorrow_day_type = DayType.from_array(response["tomorrowDayType"])
+        elif "tomorrow" in response:
+            tomorrow_day_type = DayType.from_array(response["tomorrow"])
+
+        # Global "allowed" is true only if ALL activities are allowed
+        allowed = True
+        for act in activities:
+            if not act.allowed:
+                allowed = False
+                break
+
+        # Override with explicit server value if present
+        if "allowed" in response:
+            allowed = bool(response["allowed"])
+
+        return CheckResult(
+            allowed=allowed,
+            activities=activities,
+            today_day_type=today_day_type,
+            tomorrow_day_type=tomorrow_day_type,
+            raw=response,
+        )

allow2_service/models/day_type.py

@@ -0,0 +1,34 @@
+"""Represents a day type in the Allow2 system (e.g., School Day, Weekend, Holiday)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict
+
+
+@dataclass(frozen=True)
+class DayType:
+    """Represents a day type in the Allow2 system.
+
+    Attributes:
+        id: The day type ID.
+        name: Human-readable name (e.g., "School Day", "Weekend").
+    """
+
+    id: int
+    name: str
+
+    @staticmethod
+    def from_array(data: Dict[str, Any]) -> DayType:
+        """Create from API response data.
+
+        Args:
+            data: Day type dictionary from the API response.
+
+        Returns:
+            A DayType instance.
+        """
+        return DayType(
+            id=int(data["id"]),
+            name=str(data["name"]),
+        )

allow2_service/models/feedback_category.py

@@ -0,0 +1,14 @@
+"""Categories for feedback submissions."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class FeedbackCategory(Enum):
+    """Categories for feedback submissions."""
+
+    BUG = "bug"
+    FEATURE_REQUEST = "feature_request"
+    NOT_WORKING = "not_working"
+    OTHER = "other"

allow2_service/models/oauth_tokens.py

@@ -0,0 +1,81 @@
+"""Value object representing an OAuth2 token set."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Dict
+
+
+@dataclass(frozen=True)
+class OAuthTokens:
+    """Value object representing an OAuth2 token set.
+
+    Attributes:
+        access_token: The OAuth2 access token.
+        refresh_token: The OAuth2 refresh token.
+        expires_at: Unix timestamp when the access token expires.
+    """
+
+    access_token: str
+    refresh_token: str
+    expires_at: int
+
+    def is_expired(self, buffer_seconds: int = 300) -> bool:
+        """Check whether the access token has expired or is about to expire.
+
+        Args:
+            buffer_seconds: Seconds before actual expiry to consider "expired"
+                (default 300 = 5 min).
+
+        Returns:
+            True if the token should be refreshed.
+        """
+        return int(time.time()) >= (self.expires_at - buffer_seconds)
+
+    @staticmethod
+    def from_api_response(response: Dict[str, Any]) -> OAuthTokens:
+        """Create from an API token response.
+
+        Args:
+            response: Dictionary with ``access_token``, ``refresh_token``,
+                and ``expires_in`` keys.
+
+        Returns:
+            An OAuthTokens instance.
+        """
+        return OAuthTokens(
+            access_token=response["access_token"],
+            refresh_token=response["refresh_token"],
+            expires_at=int(time.time()) + int(response["expires_in"]),
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to dictionary for storage.
+
+        Returns:
+            Dictionary with ``access_token``, ``refresh_token``,
+            and ``expires_at`` keys.
+        """
+        return {
+            "access_token": self.access_token,
+            "refresh_token": self.refresh_token,
+            "expires_at": self.expires_at,
+        }
+
+    @staticmethod
+    def from_dict(data: Dict[str, Any]) -> OAuthTokens:
+        """Reconstitute from stored dictionary.
+
+        Args:
+            data: Dictionary with ``access_token``, ``refresh_token``,
+                and ``expires_at`` keys.
+
+        Returns:
+            An OAuthTokens instance.
+        """
+        return OAuthTokens(
+            access_token=data["access_token"],
+            refresh_token=data["refresh_token"],
+            expires_at=int(data["expires_at"]),
+        )

allow2_service/models/request_result.py

@@ -0,0 +1,50 @@
+"""Result of creating a request (more time, day type change, or ban lift)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict
+
+
+@dataclass(frozen=True)
+class RequestResult:
+    """Result of creating a request (more time, day type change, or ban lift).
+
+    Attributes:
+        request_id: The unique request identifier.
+        status_secret: Secret for polling the request status.
+        status: Current status string ("pending", "approved", or "denied").
+    """
+
+    request_id: str
+    status_secret: str
+    status: str
+
+    @staticmethod
+    def from_api_response(response: Dict[str, Any]) -> RequestResult:
+        """Create from API response.
+
+        Args:
+            response: Dictionary with ``requestId``, ``statusSecret``,
+                and optionally ``status`` keys.
+
+        Returns:
+            A RequestResult instance.
+        """
+        return RequestResult(
+            request_id=str(response["requestId"]),
+            status_secret=str(response["statusSecret"]),
+            status=str(response.get("status", "pending")),
+        )
+
+    def is_pending(self) -> bool:
+        """Whether the request is still pending."""
+        return self.status == "pending"
+
+    def is_approved(self) -> bool:
+        """Whether the request was approved."""
+        return self.status == "approved"
+
+    def is_denied(self) -> bool:
+        """Whether the request was denied."""
+        return self.status == "denied"