Add core SDK modules

Allow2Client facade, OAuth2Manager, PermissionChecker, TokenStorageInterface,
CacheInterface, HttpClient, and HttpResponse -- ported from PHP reference with
matching API surface.

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

Author: Allow2CEO

allow2_service/__init__.py

@@ -0,0 +1,63 @@
+"""Allow2 Parental Freedom Service SDK for Python.
+
+Server-side integration for websites and web applications with user accounts.
+Handles OAuth2 pairing, permission checking, all 3 request types,
+voice codes (offline approval), and feedback via the Allow2 Service API.
+
+See https://developer.allow2.com for documentation.
+"""
+
+from allow2_service.cache_interface import CacheInterface
+from allow2_service.client import Allow2Client
+from allow2_service.http_client import HttpClient
+from allow2_service.http_response import HttpResponse
+from allow2_service.token_storage import TokenStorageInterface
+
+from allow2_service.exceptions import (
+    Allow2Error,
+    ApiError,
+    TokenExpiredError,
+    UnpairedError,
+)
+
+from allow2_service.models import (
+    Activity,
+    CheckResult,
+    DayType,
+    FeedbackCategory,
+    OAuthTokens,
+    RequestResult,
+    RequestType,
+    VoiceCodePair,
+)
+
+from allow2_service.voice_code import VoiceCode
+
+__version__ = "2.0.0a1"
+
+__all__ = [
+    # Client
+    "Allow2Client",
+    # Interfaces
+    "CacheInterface",
+    "TokenStorageInterface",
+    # HTTP
+    "HttpClient",
+    "HttpResponse",
+    # Exceptions
+    "Allow2Error",
+    "ApiError",
+    "TokenExpiredError",
+    "UnpairedError",
+    # Models
+    "Activity",
+    "CheckResult",
+    "DayType",
+    "FeedbackCategory",
+    "OAuthTokens",
+    "RequestResult",
+    "RequestType",
+    "VoiceCodePair",
+    # Voice Code
+    "VoiceCode",
+]

allow2_service/cache_interface.py

@@ -0,0 +1,42 @@
+"""Interface for caching permission check results."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class CacheInterface(ABC):
+    """Interface for caching permission check results.
+
+    Simple key-value cache with TTL support. Values are serialized strings.
+    """
+
+    @abstractmethod
+    def get(self, key: str) -> Optional[str]:
+        """Retrieve a cached value by key.
+
+        Args:
+            key: Cache key.
+
+        Returns:
+            The cached value, or None if not found or expired.
+        """
+
+    @abstractmethod
+    def set(self, key: str, value: str, ttl: int = 60) -> None:
+        """Store a value in cache.
+
+        Args:
+            key: Cache key.
+            value: Value to cache.
+            ttl: Time-to-live in seconds (default 60).
+        """
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """Delete a cached value.
+
+        Args:
+            key: Cache key.
+        """

allow2_service/checker.py

@@ -0,0 +1,226 @@
+"""Checks child permissions via the Allow2 Service API.
+
+Results are cached per user for a configurable TTL to avoid
+excessive API calls during a single page load or request cycle.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional, Union
+
+from allow2_service.cache_interface import CacheInterface
+from allow2_service.exceptions.api_error import ApiError
+from allow2_service.exceptions.unpaired import UnpairedError
+from allow2_service.http_response import HttpResponse
+from allow2_service.models.check_result import CheckResult
+
+
+class PermissionChecker:
+    """Checks child permissions via the Allow2 Service API."""
+
+    DEFAULT_CACHE_TTL = 60
+
+    def __init__(
+        self,
+        http_client: Any,
+        cache: CacheInterface,
+        service_host: str,
+        cache_ttl: int = DEFAULT_CACHE_TTL,
+    ) -> None:
+        self._http_client = http_client
+        self._cache = cache
+        self._service_host = service_host
+        self._cache_ttl = cache_ttl
+
+    def check(
+        self,
+        access_token: str,
+        user_id: str,
+        activities: List[Any],
+        timezone: Optional[str] = None,
+        log: bool = True,
+        use_cache: bool = True,
+    ) -> CheckResult:
+        """Check permissions for a user's linked child account.
+
+        Activities can be specified in several formats:
+
+        1. List of dicts (Allow2 API format):
+           ``[{"id": 1, "log": True}, {"id": 3, "log": True}]``
+
+        2. Simple list of activity IDs (auto-expanded with log=True):
+           ``[1, 3, 8]``
+
+        3. Legacy dict format:
+           ``{1: 1, 3: 1, 8: 1}``
+
+        Args:
+            access_token: Valid OAuth2 access token.
+            user_id: The integrating application's user ID (for cache keying).
+            activities: Activity IDs to check (see format options above).
+            timezone: IANA timezone (e.g., "Australia/Brisbane").
+            log: Whether to log usage (default True).
+            use_cache: Whether to use cached results (default True).
+
+        Returns:
+            The permission check result.
+
+        Raises:
+            UnpairedError: If the API returns 401/403 (account unlinked).
+            ApiError: On other API failures.
+        """
+        activities = self._normalize_activities(activities)
+
+        # Check cache first
+        if use_cache:
+            cache_key = self._build_cache_key(user_id, activities)
+            cached = self._cache.get(cache_key)
+
+            if cached is not None:
+                try:
+                    data = json.loads(cached)
+                    return CheckResult.from_api_response(data)
+                except (json.JSONDecodeError, ValueError):
+                    self._cache.delete(cache_key)
+
+        payload: Dict[str, Any] = {
+            "access_token": access_token,
+            "activities": activities,
+            "log": log,
+        }
+
+        if timezone is not None:
+            payload["tz"] = timezone
+
+        response: HttpResponse = self._http_client.post(
+            self._service_host + "/serviceapi/check",
+            payload,
+        )
+
+        # 401/403 = unpaired
+        if response.is_unauthorized():
+            raise UnpairedError(user_id)
+
+        if not response.is_success():
+            body = None
+            try:
+                body = response.json()
+            except (json.JSONDecodeError, ValueError):
+                pass
+            raise ApiError(
+                message="Permission check failed: HTTP %d" % response.status_code,
+                http_status_code=response.status_code,
+                response_body=body,
+            )
+
+        data = response.json()
+        result = CheckResult.from_api_response(data)
+
+        # Cache the raw response
+        if use_cache:
+            cache_key = self._build_cache_key(user_id, activities)
+            self._cache.set(cache_key, json.dumps(data), self._cache_ttl)
+
+        return result
+
+    def is_allowed(
+        self,
+        access_token: str,
+        user_id: str,
+        activity_ids: List[int],
+        timezone: Optional[str] = None,
+    ) -> bool:
+        """Convenience method: check if specific activities are all allowed.
+
+        Args:
+            access_token: Valid OAuth2 access token.
+            user_id: The integrating application's user ID.
+            activity_ids: Activity IDs to check.
+            timezone: IANA timezone.
+
+        Returns:
+            True if all specified activities are allowed.
+
+        Raises:
+            UnpairedError: If the API returns 401/403.
+            ApiError: On other API failures.
+        """
+        result = self.check(access_token, user_id, activity_ids, timezone)
+
+        for activity in result.activities:
+            if not activity.allowed:
+                return False
+
+        return True
+
+    def invalidate_cache(self, user_id: str, activities: List[Any]) -> None:
+        """Invalidate the cached check result for a user.
+
+        Args:
+            user_id: The integrating application's user ID.
+            activities: The same activities list used in check().
+        """
+        cache_key = self._build_cache_key(user_id, activities)
+        self._cache.delete(cache_key)
+
+    @staticmethod
+    def _normalize_activities(
+        activities: Union[List[Any], Dict[int, Any]],
+    ) -> List[Dict[str, Any]]:
+        """Normalize activities into the standard list-of-dicts format.
+
+        Accepts:
+        - ``[{"id": 1, "log": True}, ...]`` -- passed through as-is
+        - ``[1, 3, 8]`` -- expanded to ``[{"id": 1, "log": True}, ...]``
+        - ``{1: 1, 3: 1}`` -- legacy dict format, converted
+
+        Args:
+            activities: Activities in any supported format.
+
+        Returns:
+            Normalized list of activity dicts.
+        """
+        # Handle dict input (legacy associative format)
+        if isinstance(activities, dict):
+            normalized: List[Dict[str, Any]] = []
+            for act_id, flag in activities.items():
+                normalized.append({"id": int(act_id), "log": bool(flag)})
+            return normalized
+
+        if not activities:
+            return []
+
+        first_value = activities[0]
+
+        # Format 1: list of dicts [{"id": 1, "log": True}, ...]
+        if isinstance(first_value, dict) and "id" in first_value:
+            return list(activities)
+
+        # Format 2: simple list of IDs [1, 3, 8]
+        normalized = []
+        for act_id in activities:
+            normalized.append({"id": int(act_id), "log": True})
+        return normalized
+
+    @staticmethod
+    def _build_cache_key(user_id: str, activities: List[Any]) -> str:
+        """Build a deterministic cache key for a user + activities combination.
+
+        Args:
+            user_id: The user ID.
+            activities: Normalized activities list.
+
+        Returns:
+            A cache key string.
+        """
+        ids = []
+        for a in activities:
+            if isinstance(a, int):
+                ids.append(a)
+            else:
+                ids.append(a["id"])
+        ids.sort()
+        act_suffix = "_".join(str(i) for i in ids)
+
+        return "allow2_check_%s_%s" % (user_id, act_suffix)