plansom-sdk 0.0.1__py3-none-any.whl

plansom_sdk/__init__.py

@@ -0,0 +1,21 @@
+"""Plansom SDK — Python client for be3's v3 API."""
+
+from ._version import __version__
+from .client import Plansom
+from .async_client import PlansomAsync
+from .exceptions import (
+    PlansomError,
+    PlansomAPIError,
+    PlansomAuthError,
+    PlansomConnectionError,
+)
+
+__all__ = [
+    "Plansom",
+    "PlansomAsync",
+    "PlansomError",
+    "PlansomAPIError",
+    "PlansomAuthError",
+    "PlansomConnectionError",
+    "__version__",
+]

plansom_sdk/_version.py

@@ -0,0 +1,6 @@
+"""Single source of truth for the package version, kept separate from
+__init__.py so leaf modules (e.g. transport/http.py, for the User-Agent
+header) can import it without risking a circular import through the
+package's own __init__.py."""
+
+__version__ = "0.0.1"

plansom_sdk/async_client.py

@@ -0,0 +1,67 @@
+"""Plansom SDK — asynchronous client. Mirrors client.py."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .auth import AuthStrategy, OAuthTokenAuth
+from .resources.goals import AsyncGoals
+from .resources.organizations import AsyncOrganizations
+from .resources.search import AsyncSearch
+from .resources.tasks import AsyncTasks
+from .resources.teams import AsyncTeams
+from .resources.users import AsyncUsers
+from .transport.http import DEFAULT_BASE_URL, AsyncTransport
+from .transport.retry import RetryConfig
+
+
+def _require_auth(auth: Optional[AuthStrategy]):
+    async def get_token() -> str:
+        if auth is None:
+            raise RuntimeError("PlansomAsync(auth=...) is required to make API calls.")
+        return await auth.async_get_token()
+
+    return get_token
+
+
+class PlansomAsync:
+    """Asynchronous Plansom API client.
+
+    Usage:
+        from plansom_sdk import PlansomAsync
+        from plansom_sdk.auth import OAuthTokenAuth
+
+        client = PlansomAsync(auth=await OAuthTokenAuth.from_authorization_code_async(...))
+        page = await client.goals.list(organization=org_id)
+    """
+
+    def __init__(
+        self,
+        auth: Optional[AuthStrategy] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout_ms: Optional[int] = None,
+        retry_config: Optional[RetryConfig] = None,
+    ) -> None:
+        resolved_base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        if isinstance(auth, OAuthTokenAuth) and auth.base_url != resolved_base_url:
+            raise ValueError(
+                f"PlansomAsync is configured for {resolved_base_url!r} but its OAuthTokenAuth is "
+                f"configured for {auth.base_url!r} — resource calls and token refresh would "
+                f"silently hit different environments."
+            )
+        self._transport = AsyncTransport(
+            _require_auth(auth), base_url=base_url, timeout_ms=timeout_ms, retry_config=retry_config
+        )
+        self.goals = AsyncGoals(self._transport)
+        self.tasks = AsyncTasks(self._transport)
+        self.users = AsyncUsers(self._transport)
+        self.teams = AsyncTeams(self._transport)
+        self.organizations = AsyncOrganizations(self._transport)
+        self.search = AsyncSearch(self._transport)
+
+    async def __aenter__(self) -> "PlansomAsync":
+        return self
+
+    async def __aexit__(self, *exc_info) -> None:
+        await self._transport.aclose()

plansom_sdk/auth.py

@@ -0,0 +1,265 @@
+"""Authentication for the Plansom SDK.
+
+Two strategies: `APIKeyAuth`, for a caller acting as its own Plansom account
+(not yet available — be3 has not shipped key issuance), and `OAuthTokenAuth`,
+for third-party software acting on behalf of its own end-users (live).
+`/o/token/` (django-oauth-toolkit, confidential clients only — every
+registered app gets a `client_secret`, no PKCE/public-client path) issues and
+refreshes tokens scoped to `read:goals_tasks`. OAuth-authenticated requests
+are served by the same `/api/v3/goals/` and `/api/v3/tasks/` endpoints as any
+other authenticated caller, so no OAuth-specific routing exists elsewhere in
+the SDK.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+import httpx
+
+from .exceptions import wrap_http_error
+from .transport.http import DEFAULT_BASE_URL
+
+# Refresh this long before actual expiry so a request never races a token
+# that's valid when checked but expired by the time be3 receives it.
+_TOKEN_EXPIRY_SKEW_SECONDS = 60
+
+_TOKEN_PATH = "/o/token/"
+
+
+class AuthStrategy(ABC):
+    """Base interface every auth strategy implements. `get_token()` returns
+    the raw bearer token value sent as `Authorization: Bearer <token>` on
+    every request (see `transport/http.py`)."""
+
+    @abstractmethod
+    def get_token(self) -> str:
+        raise NotImplementedError
+
+    async def async_get_token(self) -> str:
+        """Default: delegate to the sync path — correct for strategies with
+        no I/O (e.g. `APIKeyAuth`, a plain in-memory return). Override when a
+        real async implementation is needed so the async client never blocks
+        the event loop on a sync HTTP call — see `OAuthTokenAuth`, whose
+        refresh does a real POST to `/o/token/`.
+        """
+        return self.get_token()
+
+
+class APIKeyAuth(AuthStrategy):
+    """For a caller acting as its own Plansom account.
+
+    Intended usage once be3 ships "Profile -> API Keys -> Generate API Key":
+
+        client = Plansom(auth=APIKeyAuth(api_key="pk_live_..."))
+
+    PENDING: be3 does not yet issue API keys.
+    """
+
+    def __init__(self, api_key: str) -> None:
+        self.api_key = api_key
+
+    def get_token(self) -> str:
+        raise NotImplementedError(
+            "API Key authentication is not yet available — be3 has not shipped "
+            "the API Key issuance endpoint yet."
+        )
+
+
+class OAuthTokenAuth(AuthStrategy):
+    """For third-party software acting on behalf of its own end-users.
+
+    Running the browser redirect/consent step and storing the resulting
+    tokens is the third-party app's own job, not the SDK's. What the SDK does
+    own: exchanging an authorization code for a token
+    (`from_authorization_code`) and keeping that token fresh
+    (`get_token`/`async_get_token` refresh transparently, on demand, using
+    the refresh token — no background timers).
+
+    Already have a token (e.g. restored from your own storage) and just want
+    to use it:
+
+        auth = OAuthTokenAuth("existing-access-token")
+        client = Plansom(auth=auth)
+
+    Have a refresh token too, and want the SDK to refresh automatically once
+    the access token nears expiry:
+
+        auth = OAuthTokenAuth(
+            "existing-access-token",
+            refresh_token="...",
+            expires_at=...,  # datetime, tz-aware
+            client_id="...",
+            client_secret="...",
+        )
+
+    Starting from an authorization code (the common case — right after your
+    redirect handler receives `?code=...`):
+
+        auth = OAuthTokenAuth.from_authorization_code(
+            code=request.GET["code"],
+            client_id="...",
+            client_secret="...",
+            redirect_uri="https://myapp.example/oauth/callback",
+        )
+        client = Plansom(auth=auth)
+
+    `refresh_token`/`expires_at`/`client_id`/`client_secret` are all
+    optional: without them (e.g. a bare access token with no refresh
+    material), `get_token`/`async_get_token` just return the token as-is —
+    an eventual 401 from be3 surfaces as `PlansomAuthError`, same as any
+    other auth failure.
+
+    `base_url` (internal use only) must match the `base_url` given to
+    `Plansom`/`PlansomAsync`, or construction raises `ValueError`.
+    """
+
+    def __init__(
+        self,
+        access_token: str,
+        *,
+        refresh_token: Optional[str] = None,
+        expires_at: Optional[datetime] = None,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        base_url: Optional[str] = None,
+    ) -> None:
+        self.access_token = access_token
+        self.refresh_token = refresh_token
+        self.expires_at = expires_at
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self._base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def get_token(self) -> str:
+        if self._needs_refresh():
+            self._refresh_sync()
+        return self.access_token
+
+    async def async_get_token(self) -> str:
+        if self._needs_refresh():
+            await self._refresh_async()
+        return self.access_token
+
+    def _can_refresh(self) -> bool:
+        return bool(self.refresh_token and self.client_id and self.client_secret)
+
+    def _needs_refresh(self) -> bool:
+        if self.expires_at is None or not self._can_refresh():
+            return False
+        return datetime.now(timezone.utc) >= self.expires_at - timedelta(
+            seconds=_TOKEN_EXPIRY_SKEW_SECONDS
+        )
+
+    def _refresh_params(self) -> dict:
+        return {
+            "grant_type": "refresh_token",
+            "refresh_token": self.refresh_token,
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+        }
+
+    def _apply_token_response(self, body: dict) -> None:
+        self.access_token = body["access_token"]
+        self.refresh_token = body.get("refresh_token", self.refresh_token)
+        expires_in = body.get("expires_in")
+        self.expires_at = (
+            datetime.now(timezone.utc) + timedelta(seconds=expires_in)
+            if expires_in is not None
+            else None
+        )
+
+    def _refresh_sync(self) -> None:
+        with httpx.Client() as http_client:
+            response = http_client.post(f"{self._base_url}{_TOKEN_PATH}", data=self._refresh_params())
+        if response.status_code >= 400:
+            raise wrap_http_error(response)
+        self._apply_token_response(response.json())
+
+    async def _refresh_async(self) -> None:
+        async with httpx.AsyncClient() as http_client:
+            response = await http_client.post(f"{self._base_url}{_TOKEN_PATH}", data=self._refresh_params())
+        if response.status_code >= 400:
+            raise wrap_http_error(response)
+        self._apply_token_response(response.json())
+
+    @classmethod
+    def from_authorization_code(
+        cls,
+        *,
+        code: str,
+        client_id: str,
+        client_secret: str,
+        redirect_uri: str,
+        base_url: Optional[str] = None,
+    ) -> "OAuthTokenAuth":
+        """Exchange an authorization code for a token. Call this once, right
+        after your redirect handler receives `?code=...`."""
+        resolved_base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        with httpx.Client() as http_client:
+            response = http_client.post(
+                f"{resolved_base_url}{_TOKEN_PATH}",
+                data={
+                    "grant_type": "authorization_code",
+                    "code": code,
+                    "redirect_uri": redirect_uri,
+                    "client_id": client_id,
+                    "client_secret": client_secret,
+                },
+            )
+        if response.status_code >= 400:
+            raise wrap_http_error(response)
+        return cls._from_token_response(
+            response.json(), client_id=client_id, client_secret=client_secret, base_url=resolved_base_url
+        )
+
+    @classmethod
+    async def from_authorization_code_async(
+        cls,
+        *,
+        code: str,
+        client_id: str,
+        client_secret: str,
+        redirect_uri: str,
+        base_url: Optional[str] = None,
+    ) -> "OAuthTokenAuth":
+        """Async counterpart of `from_authorization_code`, for callers
+        exchanging the code from inside an async redirect handler."""
+        resolved_base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        async with httpx.AsyncClient() as http_client:
+            response = await http_client.post(
+                f"{resolved_base_url}{_TOKEN_PATH}",
+                data={
+                    "grant_type": "authorization_code",
+                    "code": code,
+                    "redirect_uri": redirect_uri,
+                    "client_id": client_id,
+                    "client_secret": client_secret,
+                },
+            )
+        if response.status_code >= 400:
+            raise wrap_http_error(response)
+        return cls._from_token_response(
+            response.json(), client_id=client_id, client_secret=client_secret, base_url=resolved_base_url
+        )
+
+    @classmethod
+    def _from_token_response(cls, body: dict, *, client_id: str, client_secret: str, base_url: str) -> "OAuthTokenAuth":
+        expires_in = body.get("expires_in")
+        expires_at = (
+            datetime.now(timezone.utc) + timedelta(seconds=expires_in) if expires_in is not None else None
+        )
+        return cls(
+            body["access_token"],
+            refresh_token=body.get("refresh_token"),
+            expires_at=expires_at,
+            client_id=client_id,
+            client_secret=client_secret,
+            base_url=base_url,
+        )

plansom_sdk/client.py

@@ -0,0 +1,67 @@
+"""Plansom SDK — synchronous client."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .auth import AuthStrategy, OAuthTokenAuth
+from .resources.goals import Goals
+from .resources.organizations import Organizations
+from .resources.search import Search
+from .resources.tasks import Tasks
+from .resources.teams import Teams
+from .resources.users import Users
+from .transport.http import DEFAULT_BASE_URL, SyncTransport
+from .transport.retry import RetryConfig
+
+
+def _require_auth(auth: Optional[AuthStrategy]):
+    def get_token() -> str:
+        if auth is None:
+            raise RuntimeError("Plansom(auth=...) is required to make API calls.")
+        return auth.get_token()
+
+    return get_token
+
+
+class Plansom:
+    """Synchronous Plansom API client.
+
+    Usage:
+        from plansom_sdk import Plansom
+        from plansom_sdk.auth import OAuthTokenAuth
+
+        client = Plansom(auth=OAuthTokenAuth.from_authorization_code(...))
+        page = client.goals.list(organization=org_id)
+    """
+
+    def __init__(
+        self,
+        auth: Optional[AuthStrategy] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout_ms: Optional[int] = None,
+        retry_config: Optional[RetryConfig] = None,
+    ) -> None:
+        resolved_base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        if isinstance(auth, OAuthTokenAuth) and auth.base_url != resolved_base_url:
+            raise ValueError(
+                f"Plansom is configured for {resolved_base_url!r} but its OAuthTokenAuth is "
+                f"configured for {auth.base_url!r} — resource calls and token refresh would "
+                f"silently hit different environments."
+            )
+        self._transport = SyncTransport(
+            _require_auth(auth), base_url=base_url, timeout_ms=timeout_ms, retry_config=retry_config
+        )
+        self.goals = Goals(self._transport)
+        self.tasks = Tasks(self._transport)
+        self.users = Users(self._transport)
+        self.teams = Teams(self._transport)
+        self.organizations = Organizations(self._transport)
+        self.search = Search(self._transport)
+
+    def __enter__(self) -> "Plansom":
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        self._transport.close()

plansom_sdk/exceptions.py

@@ -0,0 +1,72 @@
+"""Typed exceptions for the Plansom SDK.
+
+`wrap_http_error` builds a typed exception straight from an `httpx.Response`,
+so callers only ever need to catch this package's own hierarchy.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+
+class PlansomError(Exception):
+    """Base class for all errors raised by the Plansom SDK."""
+
+
+class PlansomConnectionError(PlansomError):
+    """Network-level failure (timeout, DNS, connection reset) — no response was
+    received from be3 at all, so there's no status code to classify."""
+
+    def __init__(self, message: str, *, source: Exception) -> None:
+        super().__init__(message)
+        self.source = source
+
+
+class PlansomAPIError(PlansomError):
+    """be3 returned an error response."""
+
+    def __init__(self, message: str, status_code: int, body: str) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+class PlansomAuthError(PlansomAPIError):
+    """401 / 403 — missing, invalid, or insufficiently-scoped credentials."""
+
+
+class PlansomNotFoundError(PlansomAPIError):
+    """404 — resource does not exist, or isn't visible to the caller."""
+
+
+class PlansomRateLimitError(PlansomAPIError):
+    """429 — too many requests."""
+
+
+class PlansomValidationError(PlansomAPIError):
+    """400 — request rejected by be3's validation."""
+
+
+class PlansomServerError(PlansomAPIError):
+    """5xx — be3 failed unexpectedly."""
+
+
+_STATUS_CODE_MAP = {
+    400: PlansomValidationError,
+    401: PlansomAuthError,
+    403: PlansomAuthError,
+    404: PlansomNotFoundError,
+    429: PlansomRateLimitError,
+}
+
+
+def wrap_http_error(response: httpx.Response) -> PlansomAPIError:
+    """Translate a non-2xx httpx.Response into the SDK's exception hierarchy."""
+    error_cls = _STATUS_CODE_MAP.get(response.status_code)
+    if error_cls is None:
+        error_cls = PlansomServerError if response.status_code >= 500 else PlansomAPIError
+    return error_cls(
+        f"be3 returned {response.status_code} for {response.request.method} {response.request.url}",
+        response.status_code,
+        response.text,
+    )