pyprocore 1.0.0__py3-none-any.whl

app.py

@@ -0,0 +1,176 @@
+"""Command-line entrypoint for Procore SDK operations."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from core.config import get_settings
+from services import (
+    download_rfi_attachments,
+    download_submittal_attachments,
+    get_rfi,
+    get_submittal,
+    list_companies,
+    list_projects,
+    list_rfis,
+    list_submittals,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line parser."""
+    parser = argparse.ArgumentParser(description="Procore SDK utility commands")
+    subcommands = parser.add_subparsers(dest="command", required=True)
+
+    subcommands.add_parser("companies", help="List companies")
+
+    projects_parser = subcommands.add_parser("projects", help="List projects")
+    projects_parser.add_argument("--company-id", type=int, default=None)
+
+    rfis_parser = subcommands.add_parser("rfis", help="List RFIs for a project")
+    rfis_parser.add_argument(
+        "--project", "--project-id", dest="project_id", type=int, required=True
+    )
+
+    rfi_parser = subcommands.add_parser("rfi", help="Get one RFI")
+    rfi_parser.add_argument(
+        "--project", "--project-id", dest="project_id", type=int, required=True
+    )
+    rfi_parser.add_argument("--id", "--rfi-id", dest="rfi_id", type=int, required=True)
+
+    rfi_download_parser = _add_alias_parser(
+        subcommands,
+        "download-rfi",
+        ["download-rfi-attachments"],
+        "download-rfi-attachments",
+        help="Download RFI attachments",
+    )
+    rfi_download_parser.add_argument(
+        "--project", "--project-id", dest="project_id", type=int, required=True
+    )
+    rfi_download_parser.add_argument(
+        "--id", "--rfi-id", dest="rfi_id", type=int, required=True
+    )
+    rfi_download_parser.add_argument("--destination-dir", type=Path, default=None)
+
+    submittals_parser = subcommands.add_parser(
+        "submittals",
+        help="List submittals for a project",
+    )
+    submittals_parser.add_argument(
+        "--project", "--project-id", dest="project_id", type=int, required=True
+    )
+
+    submittal_parser = subcommands.add_parser("submittal", help="Get one submittal")
+    submittal_parser.add_argument(
+        "--project", "--project-id", dest="project_id", type=int, required=True
+    )
+    submittal_parser.add_argument(
+        "--id", "--submittal-id", dest="submittal_id", type=int, required=True
+    )
+
+    submittal_download_parser = _add_alias_parser(
+        subcommands,
+        "download-submittal",
+        ["download-submittal-attachments"],
+        "download-submittal-attachments",
+        help="Download submittal attachments",
+    )
+    submittal_download_parser.add_argument(
+        "--project", "--project-id", dest="project_id", type=int, required=True
+    )
+    submittal_download_parser.add_argument(
+        "--id", "--submittal-id", dest="submittal_id", type=int, required=True
+    )
+    submittal_download_parser.add_argument("--destination-dir", type=Path, default=None)
+
+    return parser
+
+
+def _add_alias_parser(
+    subcommands: argparse._SubParsersAction[argparse.ArgumentParser],
+    name: str,
+    aliases: list[str],
+    legacy_name: str,
+    **kwargs: Any,
+) -> argparse.ArgumentParser:
+    """Add a subcommand with aliases when supported by argparse."""
+    parser = subcommands.add_parser(name, aliases=aliases, **kwargs)
+    parser.set_defaults(command=name, legacy_command=legacy_name)
+    return parser
+
+
+def run_command(args: argparse.Namespace) -> Any:
+    """Run a parsed CLI command and return serializable output."""
+    if args.command == "companies":
+        return list_companies()
+
+    if args.command == "projects":
+        company_id = args.company_id or get_settings().company_id
+        return list_projects(company_id)
+
+    if args.command == "rfis":
+        return list_rfis(args.project_id)
+
+    if args.command == "rfi":
+        return get_rfi(args.project_id, args.rfi_id)
+
+    if args.command == "download-rfi":
+        return [
+            str(path)
+            for path in download_rfi_attachments(
+                args.project_id,
+                args.rfi_id,
+                args.destination_dir,
+            )
+        ]
+
+    if args.command == "submittals":
+        return list_submittals(args.project_id)
+
+    if args.command == "submittal":
+        return get_submittal(args.project_id, args.submittal_id)
+
+    if args.command == "download-submittal":
+        return [
+            str(path)
+            for path in download_submittal_attachments(
+                args.project_id,
+                args.submittal_id,
+                args.destination_dir,
+            )
+        ]
+
+    raise ValueError(f"Unsupported command: {args.command}")
+
+
+def to_serializable(value: Any) -> Any:
+    """Convert SDK output into JSON-serializable data."""
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if isinstance(value, list):
+        return [to_serializable(item) for item in value]
+    if isinstance(value, tuple):
+        return [to_serializable(item) for item in value]
+    if isinstance(value, dict):
+        return {key: to_serializable(item) for key, item in value.items()}
+    if isinstance(value, Path):
+        return str(value)
+    return value
+
+
+def main() -> None:
+    """Run the CLI entrypoint."""
+    parser = build_parser()
+    args = parser.parse_args()
+    result = run_command(args)
+    print(json.dumps(to_serializable(result), indent=2, default=str))
+
+
+if __name__ == "__main__":
+    main()

auth/__init__.py

@@ -0,0 +1,45 @@
+"""Authentication utilities for the Procore SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "OAuthClient",
+    "OAuthTokenResponse",
+    "StoredToken",
+    "TokenManager",
+    "TokenStore",
+    "get_access_token",
+    "load_token",
+    "save_token",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily expose auth objects without creating import cycles."""
+    if name in {"OAuthClient", "OAuthTokenResponse"}:
+        from auth.oauth import OAuthClient, OAuthTokenResponse
+
+        return {"OAuthClient": OAuthClient, "OAuthTokenResponse": OAuthTokenResponse}[
+            name
+        ]
+
+    if name in {"TokenManager", "get_access_token"}:
+        from auth.token_manager import TokenManager, get_access_token
+
+        return {"TokenManager": TokenManager, "get_access_token": get_access_token}[
+            name
+        ]
+
+    if name in {"StoredToken", "TokenStore", "load_token", "save_token"}:
+        from auth.token_store import StoredToken, TokenStore, load_token, save_token
+
+        return {
+            "StoredToken": StoredToken,
+            "TokenStore": TokenStore,
+            "load_token": load_token,
+            "save_token": save_token,
+        }[name]
+
+    raise AttributeError(f"module 'auth' has no attribute {name!r}")

auth/oauth.py

@@ -0,0 +1,166 @@
+"""OAuth helpers for authenticating with Procore.
+
+The functions in this module exchange authorization codes and refresh tokens
+for Procore OAuth access tokens. Configuration is loaded from ``core.config``;
+callers never pass client secrets directly.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import requests
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, field_validator
+
+from core.config import ProcoreSettings, get_settings
+from core.exceptions import AuthenticationError
+
+TOKEN_ENDPOINT_PATH = "/oauth/token"
+DEFAULT_TIMEOUT_SECONDS = 30
+
+
+class OAuthTokenResponse(BaseModel):
+    """Validated OAuth token payload returned by Procore."""
+
+    access_token: SecretStr
+    token_type: str = Field(default="Bearer", min_length=1)
+    expires_in: int = Field(..., gt=0)
+    refresh_token: SecretStr | None = None
+    scope: str | None = None
+    created_at: int | None = None
+
+    model_config = ConfigDict(extra="allow")
+
+    @field_validator("token_type")
+    @classmethod
+    def _normalize_token_type(cls, value: str) -> str:
+        """Normalize token type values for downstream Authorization headers."""
+        return value.strip()
+
+
+class OAuthClient:
+    """Client for Procore OAuth token operations."""
+
+    def __init__(
+        self,
+        settings: ProcoreSettings | None = None,
+        session: requests.Session | None = None,
+        timeout_seconds: int = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        """Initialize the OAuth client.
+
+        Args:
+            settings: Optional settings instance. Defaults to environment-backed
+                settings from ``get_settings()``.
+            session: Optional HTTP session. A new ``requests.Session`` is used
+                when omitted.
+            timeout_seconds: Request timeout for token calls.
+        """
+        self._settings = settings or get_settings()
+        self._session = session or requests.Session()
+        self._timeout_seconds = timeout_seconds
+
+    def exchange_authorization_code(
+        self, authorization_code: str
+    ) -> OAuthTokenResponse:
+        """Exchange an OAuth authorization code for access and refresh tokens.
+
+        Args:
+            authorization_code: The authorization code returned by Procore.
+
+        Returns:
+            A validated OAuth token response.
+
+        Raises:
+            AuthenticationError: If the exchange fails or the response is invalid.
+        """
+        code = authorization_code.strip()
+        if not code:
+            raise AuthenticationError("Authorization code is required.")
+
+        payload = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "client_id": self._settings.client_id,
+            "client_secret": self._settings.client_secret.get_secret_value(),
+            "redirect_uri": self._settings.redirect_uri,
+        }
+        return self._request_token(payload)
+
+    def refresh_access_token(self, refresh_token: str) -> OAuthTokenResponse:
+        """Refresh an expired OAuth access token.
+
+        Args:
+            refresh_token: The current refresh token.
+
+        Returns:
+            A validated OAuth token response.
+
+        Raises:
+            AuthenticationError: If the refresh fails or the response is invalid.
+        """
+        token = refresh_token.strip()
+        if not token:
+            raise AuthenticationError("Refresh token is required.")
+
+        payload = {
+            "grant_type": "refresh_token",
+            "refresh_token": token,
+            "client_id": self._settings.client_id,
+            "client_secret": self._settings.client_secret.get_secret_value(),
+        }
+        return self._request_token(payload)
+
+    def _request_token(self, payload: dict[str, str]) -> OAuthTokenResponse:
+        """Send a token request and validate the response."""
+        token_url = f"{self._settings.login_url}{TOKEN_ENDPOINT_PATH}"
+
+        try:
+            response = self._session.post(
+                token_url,
+                data=payload,
+                headers={
+                    "Accept": "application/json",
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+                timeout=self._timeout_seconds,
+            )
+        except requests.RequestException as exc:
+            raise AuthenticationError(f"OAuth token request failed: {exc}") from exc
+
+        if not response.ok:
+            raise AuthenticationError(self._format_error_response(response))
+
+        try:
+            response_data: dict[str, Any] = response.json()
+        except ValueError as exc:
+            raise AuthenticationError(
+                "OAuth token response was not valid JSON."
+            ) from exc
+
+        try:
+            return OAuthTokenResponse.model_validate(response_data)
+        except ValueError as exc:
+            raise AuthenticationError(
+                f"OAuth token response was invalid: {exc}"
+            ) from exc
+
+    @staticmethod
+    def _format_error_response(response: requests.Response) -> str:
+        """Build a safe error message without exposing credentials."""
+        try:
+            body = response.json()
+        except ValueError:
+            body = response.text
+
+        return f"OAuth token request failed with status {response.status_code}: {body}"
+
+
+def exchange_authorization_code(authorization_code: str) -> OAuthTokenResponse:
+    """Exchange an authorization code using default environment configuration."""
+    return OAuthClient().exchange_authorization_code(authorization_code)
+
+
+def refresh_access_token(refresh_token: str) -> OAuthTokenResponse:
+    """Refresh an access token using default environment configuration."""
+    return OAuthClient().refresh_access_token(refresh_token)

auth/token_manager.py

@@ -0,0 +1,106 @@
+"""High-level OAuth token management for the Procore SDK.
+
+The token manager is the only authentication object the rest of the
+application should need. It loads saved tokens, detects expiry, refreshes when
+needed, and returns a plain access token string for HTTP clients.
+"""
+
+from __future__ import annotations
+
+from auth.oauth import OAuthClient, OAuthTokenResponse
+from auth.token_store import StoredToken, TokenStore
+from core.exceptions import AuthenticationError
+
+
+class TokenManager:
+    """Manage loading, refreshing, and saving Procore OAuth tokens."""
+
+    def __init__(
+        self,
+        token_store: TokenStore | None = None,
+        oauth_client: OAuthClient | None = None,
+    ) -> None:
+        """Initialize the token manager.
+
+        Args:
+            token_store: Optional token persistence backend.
+            oauth_client: Optional OAuth client used for token refreshes.
+        """
+        self._token_store = token_store or TokenStore()
+        self._oauth_client = oauth_client or OAuthClient()
+
+    def get_access_token(self, force_refresh: bool = False) -> str:
+        """Return a valid access token, refreshing it when necessary.
+
+        Args:
+            force_refresh: Refresh the token even if the stored token has not
+                reached its refresh window.
+
+        Returns:
+            The current bearer access token as a plain string.
+
+        Raises:
+            AuthenticationError: If no token exists or refresh cannot complete.
+        """
+        token = self._token_store.load()
+        if token is None:
+            raise AuthenticationError(
+                "No Procore token is stored. Complete OAuth authorization first."
+            )
+
+        if force_refresh or token.is_expired():
+            token = self.refresh_token(token)
+
+        return token.access_token.get_secret_value()
+
+    def refresh_token(self, token: StoredToken | None = None) -> StoredToken:
+        """Refresh the stored access token and persist the replacement.
+
+        Args:
+            token: Optional token to refresh. Defaults to the currently stored
+                token.
+
+        Returns:
+            The refreshed stored token.
+
+        Raises:
+            AuthenticationError: If no refresh token is available.
+        """
+        current_token = token or self._token_store.load()
+        if current_token is None:
+            raise AuthenticationError("No Procore token is available to refresh.")
+
+        if current_token.refresh_token is None:
+            raise AuthenticationError("No Procore refresh token is available.")
+
+        refresh_token = current_token.refresh_token.get_secret_value()
+        refreshed_response = self._oauth_client.refresh_access_token(refresh_token)
+        refreshed_token = StoredToken.from_oauth_response(
+            refreshed_response,
+            existing_refresh_token=refresh_token,
+        )
+        self._token_store.save(refreshed_token)
+        return refreshed_token
+
+    def save_oauth_response(self, token_response: OAuthTokenResponse) -> StoredToken:
+        """Persist the token returned by an initial OAuth exchange.
+
+        Args:
+            token_response: OAuth response returned after exchanging an
+                authorization code.
+
+        Returns:
+            The stored token representation.
+        """
+        token = StoredToken.from_oauth_response(token_response)
+        self._token_store.save(token)
+        return token
+
+    def clear_token(self) -> None:
+        """Remove the saved token from the local token store."""
+        self._token_store.clear()
+
+
+def get_access_token() -> str:
+    """Return a valid access token using the default token manager."""
+    return TokenManager().get_access_token()

auth/token_store.py

@@ -0,0 +1,158 @@
+"""Persistent storage for Procore OAuth tokens.
+
+The token store owns file IO only. It validates token payloads, returns
+``None`` when no token has been saved yet, and writes updates atomically so a
+partial process failure does not corrupt the token file.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, field_validator
+
+from core.exceptions import AuthenticationError
+
+DEFAULT_EXPIRY_SKEW_SECONDS = 60
+DEFAULT_TOKEN_FILE = Path(__file__).resolve().parent / "token_store.json"
+
+
+class StoredToken(BaseModel):
+    """OAuth token data persisted by the SDK."""
+
+    access_token: SecretStr
+    expires_at: int = Field(..., gt=0)
+    refresh_token: SecretStr | None = None
+    token_type: str = Field(default="Bearer", min_length=1)
+    scope: str | None = None
+
+    model_config = ConfigDict(extra="allow")
+
+    @field_validator("token_type")
+    @classmethod
+    def _normalize_token_type(cls, value: str) -> str:
+        """Normalize token type values for Authorization headers."""
+        return value.strip()
+
+    @classmethod
+    def from_oauth_response(
+        cls,
+        token_response: Any,
+        existing_refresh_token: str | None = None,
+    ) -> "StoredToken":
+        """Create a stored token from an OAuth response model or mapping.
+
+        Args:
+            token_response: OAuth response returned by ``auth.oauth``.
+            existing_refresh_token: Refresh token to reuse if a refresh response
+                does not include a replacement.
+
+        Returns:
+            A validated token suitable for persistence.
+        """
+        if isinstance(token_response, BaseModel):
+            payload = token_response.model_dump(mode="python")
+        else:
+            payload = dict(token_response)
+
+        refresh_token = payload.get("refresh_token") or existing_refresh_token
+        expires_in = int(payload["expires_in"])
+
+        return cls(
+            access_token=payload["access_token"],
+            refresh_token=refresh_token,
+            token_type=payload.get("token_type", "Bearer"),
+            scope=payload.get("scope"),
+            expires_at=int(time.time()) + expires_in,
+        )
+
+    def is_expired(self, skew_seconds: int = DEFAULT_EXPIRY_SKEW_SECONDS) -> bool:
+        """Return whether the token is expired or inside the refresh window."""
+        return int(time.time()) >= self.expires_at - skew_seconds
+
+    def to_public_dict(self) -> dict[str, Any]:
+        """Serialize token values for local persistence."""
+        data = self.model_dump(mode="json")
+        data["access_token"] = self.access_token.get_secret_value()
+        if self.refresh_token is not None:
+            data["refresh_token"] = self.refresh_token.get_secret_value()
+        return data
+
+
+class TokenStore:
+    """File-backed token persistence for the Procore SDK."""
+
+    def __init__(self, path: Path | str = DEFAULT_TOKEN_FILE) -> None:
+        """Initialize the store.
+
+        Args:
+            path: Token file path. Defaults to ``auth/token_store.json``.
+        """
+        self._path = Path(path)
+
+    @property
+    def path(self) -> Path:
+        """Return the token store file path."""
+        return self._path
+
+    def load(self) -> StoredToken | None:
+        """Load a saved token from disk.
+
+        Returns:
+            The saved token, or ``None`` when no token has been stored.
+
+        Raises:
+            AuthenticationError: If the token file exists but is unreadable or
+                malformed.
+        """
+        if not self._path.exists() or self._path.stat().st_size == 0:
+            return None
+
+        try:
+            raw = json.loads(self._path.read_text(encoding="utf-8"))
+        except OSError as exc:
+            raise AuthenticationError(f"Unable to read token store: {exc}") from exc
+        except json.JSONDecodeError as exc:
+            raise AuthenticationError("Token store contains invalid JSON.") from exc
+
+        if raw == {}:
+            return None
+
+        try:
+            return StoredToken.model_validate(raw)
+        except ValueError as exc:
+            raise AuthenticationError(
+                f"Token store contains invalid token data: {exc}"
+            ) from exc
+
+    def save(self, token: StoredToken) -> None:
+        """Persist a token to disk atomically."""
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        temporary_path = self._path.with_suffix(f"{self._path.suffix}.tmp")
+        payload = json.dumps(token.to_public_dict(), indent=2, sort_keys=True)
+
+        try:
+            temporary_path.write_text(f"{payload}\n", encoding="utf-8")
+            temporary_path.replace(self._path)
+        except OSError as exc:
+            raise AuthenticationError(f"Unable to save token store: {exc}") from exc
+
+    def clear(self) -> None:
+        """Delete the saved token file when it exists."""
+        try:
+            self._path.unlink(missing_ok=True)
+        except OSError as exc:
+            raise AuthenticationError(f"Unable to clear token store: {exc}") from exc
+
+
+def load_token() -> StoredToken | None:
+    """Load the default stored token."""
+    return TokenStore().load()
+
+
+def save_token(token: StoredToken) -> None:
+    """Save a token to the default token store."""
+    TokenStore().save(token)