certinext 0.1.2a2__py3-none-any.whl

certinext/__init__.py

@@ -0,0 +1,88 @@
+# Copyright 2026 University of Maine System
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""CertiNext API client library.
+
+Typical usage::
+
+    import certinext
+
+    sess = certinext.session(
+        client_id="YOUR_ACCOUNT_NUMBER",
+        client_secret="YOUR_CLIENT_SECRET",
+    )
+
+    for domain in sess.domain.get_list():
+        print(domain)
+
+Known API limitations (vendor bugs, pending fix):
+    - The ``search`` parameter to :meth:`~certinext.domains.DomainAccessor.get_list`
+      is ignored — all domains are returned regardless. Use ``pattern`` for
+      client-side filtering.
+    - Passing both ``domain_status`` and ``dcv_status`` to
+      :meth:`~certinext.domains.DomainAccessor.get_list` returns a 400 error.
+      :meth:`~certinext.domains.DomainAccessor.list_pending_dcv` works around this
+      by fetching all domains and filtering client-side.
+
+Errors:
+    All API errors raise :class:`CertiNextAPIError` (a subclass of
+    :class:`requests.HTTPError`) with ``.status_code`` (int) and ``.body``
+    (dict or str) attributes for inspection.
+"""
+
+from .client import CertiNextClient
+from .domains import VALID_DCV_METHODS, DcvInfo, DcvMethod, DcvStatus, Domain, DomainAccessor, DomainStatus
+from .exceptions import CertiNextAPIError
+from .session import CertiNextSession
+
+
+def session(
+    base_url: str = "https://us-api.certinext.io",
+    token_url: str = "https://us-api.certinext.io/oauth/token",
+    client_id: str = "",
+    client_secret: str = "",
+    scope: str = "",
+) -> CertiNextSession:
+    """Create and return a new `CertiNextSession`.
+
+    This is the recommended entry point for the library. The session obtains
+    and caches an OAuth 2.0 bearer token automatically.
+
+    Args:
+        base_url: CertiNext API base URL. Defaults to the US production endpoint.
+        token_url: OAuth 2.0 token endpoint URL.
+        client_id: Your CertiNext account number (used as the OAuth client ID).
+        client_secret: OAuth client secret generated in the CertiNext portal
+            under Integrations → APIs → OAuth mode.
+        scope: Optional OAuth scope string. Leave empty if not required.
+
+    Returns:
+        A configured `CertiNextSession` ready to make API calls.
+    """
+    return CertiNextSession(base_url, token_url, client_id, client_secret, scope)
+
+
+__all__ = [
+    "session",
+    "CertiNextAPIError",
+    "CertiNextClient",
+    "CertiNextSession",
+    "Domain",
+    "DomainAccessor",
+    "DcvInfo",
+    "DcvMethod",
+    "DcvStatus",
+    "DomainStatus",
+    "VALID_DCV_METHODS",
+]

certinext/_keyring.py

@@ -0,0 +1,37 @@
+"""Keyring helpers for CertiNext credential resolution.
+
+Provides lightweight wrappers around the optional ``keyring`` package.
+All functions silently degrade when keyring is not installed rather than
+raising an ImportError, so callers do not need to guard the import.
+"""
+
+
+def keyring_service(base: str, profile: str | None) -> str:
+    """Return the keyring service name for a given base and optional profile.
+
+    Args:
+        base: Base service name (e.g. ``'certinext'``).
+        profile: Profile suffix, or None for the default profile.
+
+    Returns:
+        ``'base-profile'`` when profile is set, otherwise ``'base'``.
+    """
+    return f"{base}-{profile}" if profile else base
+
+
+def keyring_get(service: str, key: str) -> str | None:
+    """Return a stored keyring value, or None if keyring is unavailable or unset.
+
+    Args:
+        service: Keyring service name.
+        key: Keyring key (username field).
+
+    Returns:
+        The stored string, or None on any failure.
+    """
+    try:
+        import keyring
+        value = keyring.get_password(service, key)
+        return value if isinstance(value, str) else None
+    except Exception:
+        return None

certinext/auth.py

@@ -0,0 +1,84 @@
+# Copyright 2026 University of Maine System
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import time
+from typing import Optional
+
+import requests
+
+
+class OAuth2ClientCredentials:
+    """Manages an OAuth 2.0 Client Credentials bearer token.
+
+    Fetches a token on first use and caches it, automatically refreshing it
+    60 seconds before expiry so callers always receive a valid token.
+    """
+
+    def __init__(self, token_url: str, client_id: str, client_secret: str, scope: str = "") -> None:
+        """
+        Args:
+            token_url: Full URL of the OAuth 2.0 token endpoint.
+            client_id: OAuth client ID (your CertiNext account number).
+            client_secret: OAuth client secret.
+            scope: Optional space-separated OAuth scopes.
+        """
+        self.token_url = token_url
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.scope = scope
+        self._access_token: Optional[str] = None
+        self._expires_at: float = 0.0
+
+    def get_token(self) -> str:
+        """Return a valid bearer token, fetching a new one if necessary.
+
+        Returns:
+            A current OAuth access token string.
+
+        Raises:
+            RuntimeError: If the token endpoint returns an error or non-JSON response.
+        """
+        if self._access_token and time.time() < self._expires_at - 60:
+            return self._access_token
+        self._fetch_token()
+        assert self._access_token is not None
+        return self._access_token
+
+    def _fetch_token(self) -> None:
+        """Request a new token from the token endpoint and cache it."""
+        data = {
+            "grant_type": "client_credentials",
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+        }
+        if self.scope:
+            data["scope"] = self.scope
+
+        resp = requests.post(self.token_url, data=data)
+        if not resp.ok:
+            raise RuntimeError(
+                f"Token request failed: {resp.status_code} {resp.reason}\n"
+                f"URL: {resp.url}\n"
+                f"Body: {resp.text!r}"
+            )
+        try:
+            payload = resp.json()
+        except Exception as exc:
+            raise RuntimeError(
+                f"Token endpoint returned non-JSON (status {resp.status_code})\n"
+                f"URL: {resp.url}\n"
+                f"Body: {resp.text!r}"
+            ) from exc
+        self._access_token = payload["access_token"]
+        self._expires_at = time.time() + payload.get("expires_in", 3600)

certinext/client.py

@@ -0,0 +1,162 @@
+# Copyright 2026 University of Maine System
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Any, cast
+
+import requests
+
+from .auth import OAuth2ClientCredentials
+from .exceptions import CertiNextAPIError
+
+
+class CertiNextClient:
+    """Low-level HTTP client for the CertiNext REST API.
+
+    Handles authentication automatically by delegating to
+    `OAuth2ClientCredentials`. All requests include a Bearer token and
+    JSON content-type headers. HTTP errors raise `CertiNextAPIError`.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token_url: str,
+        client_id: str,
+        client_secret: str,
+        scope: str = "",
+    ) -> None:
+        """
+        Args:
+            base_url: CertiNext API base URL (e.g. ``https://us-api.certinext.io``).
+            token_url: OAuth 2.0 token endpoint URL.
+            client_id: OAuth client ID (your CertiNext account number).
+            client_secret: OAuth client secret.
+            scope: Optional OAuth scope string.
+        """
+        self.base_url = base_url.rstrip("/")
+        self._auth = OAuth2ClientCredentials(token_url, client_id, client_secret, scope)
+        self._session = requests.Session()
+
+    def _headers(self) -> dict[str, str]:
+        """Build request headers with a fresh bearer token."""
+        return {
+            "Authorization": f"Bearer {self._auth.get_token()}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+
+    def _raise_api_error(self, resp: requests.Response) -> None:
+        """Raise CertiNextAPIError if the response has a non-2xx status.
+
+        Preserves the API response body (parsed JSON or raw text) so callers
+        can inspect what the server actually returned.
+
+        Args:
+            resp: The HTTP response to check.
+
+        Raises:
+            CertiNextAPIError: On a non-2xx response. Provides ``.status_code`` and ``.body``.
+        """
+        try:
+            resp.raise_for_status()
+        except requests.HTTPError as exc:
+            try:
+                body: dict[str, Any] | str = resp.json()
+            except Exception:
+                body = resp.text
+            raise CertiNextAPIError(resp.status_code, body, response=resp) from exc
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any] | list[Any]:
+        """Send a GET request and return the parsed JSON response.
+
+        Args:
+            path: API path relative to ``base_url`` (e.g. ``/api/certinext/v2/domains``).
+            params: Optional query-string parameters.
+
+        Returns:
+            Parsed JSON response as a dict or list.
+
+        Raises:
+            CertiNextAPIError: On a non-2xx response. Provides ``.status_code`` and ``.body``.
+        """
+        resp = self._session.get(f"{self.base_url}{path}", headers=self._headers(), params=params)
+        self._raise_api_error(resp)
+        return cast(dict[str, Any], resp.json())
+
+    def post(self, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Send a POST request with an optional JSON body and return the parsed response.
+
+        Args:
+            path: API path relative to ``base_url``.
+            json: Optional request body to serialize as JSON.
+
+        Returns:
+            Parsed JSON response as a dict.
+
+        Raises:
+            CertiNextAPIError: On a non-2xx response. Provides ``.status_code`` and ``.body``.
+        """
+        resp = self._session.post(f"{self.base_url}{path}", headers=self._headers(), json=json)
+        self._raise_api_error(resp)
+        return cast(dict[str, Any], resp.json())
+
+    def put(self, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Send a PUT request with an optional JSON body and return the parsed response.
+
+        Args:
+            path: API path relative to ``base_url``.
+            json: Optional request body to serialize as JSON.
+
+        Returns:
+            Parsed JSON response as a dict.
+
+        Raises:
+            CertiNextAPIError: On a non-2xx response. Provides ``.status_code`` and ``.body``.
+        """
+        resp = self._session.put(f"{self.base_url}{path}", headers=self._headers(), json=json)
+        self._raise_api_error(resp)
+        return cast(dict[str, Any], resp.json())
+
+    def patch(self, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Send a PATCH request with an optional JSON body and return the parsed response.
+
+        Args:
+            path: API path relative to ``base_url``.
+            json: Optional request body to serialize as JSON.
+
+        Returns:
+            Parsed JSON response as a dict.
+
+        Raises:
+            CertiNextAPIError: On a non-2xx response. Provides ``.status_code`` and ``.body``.
+        """
+        resp = self._session.patch(f"{self.base_url}{path}", headers=self._headers(), json=json)
+        self._raise_api_error(resp)
+        return cast(dict[str, Any], resp.json())
+
+    def delete(self, path: str) -> dict[str, Any] | None:
+        """Send a DELETE request and return the parsed response body if present.
+
+        Args:
+            path: API path relative to ``base_url``.
+
+        Returns:
+            Parsed JSON response as a dict, or ``None`` if the response has no body.
+
+        Raises:
+            CertiNextAPIError: On a non-2xx response. Provides ``.status_code`` and ``.body``.
+        """
+        resp = self._session.delete(f"{self.base_url}{path}", headers=self._headers())
+        self._raise_api_error(resp)
+        return resp.json() if resp.content else None