sfdctrust 0.1.0__py3-none-any.whl

sfdctrust/__init__.py

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            sfdctrust
+:Synopsis:          Primary module for the sfdctrust package
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff (via GPT-6.1 Sol)
+:Modified Date:     04 Nov 2026
+"""
+
+from ._async_client import AsyncTrustCenterClient
+from ._client import TrustCenterClient
+from ._exceptions import (
+    APIStatusError,
+    AuthenticationError,
+    ConfigurationError,
+    MalformedResponseError,
+    NetworkError,
+    NotFoundError,
+    PaginationError,
+    PATPersistenceError,
+    PATProbeResult,
+    PATRefreshAmbiguousError,
+    PATRefreshPendingError,
+    RateLimitError,
+    RequestTimeoutError,
+    TrustCenterError,
+)
+from ._pat_refresh import PATRefreshResult
+from ._pat_store import AsyncPATStore, PATStore, PATStoreRecord
+from ._version import __version__
+
+__all__ = [
+    '__version__',
+    'TrustCenterClient',
+    'AsyncTrustCenterClient',
+    'TrustCenterError',
+    'ConfigurationError',
+    'NetworkError',
+    'RequestTimeoutError',
+    'APIStatusError',
+    'AuthenticationError',
+    'RateLimitError',
+    'NotFoundError',
+    'MalformedResponseError',
+    'PaginationError',
+    'PATStore',
+    'AsyncPATStore',
+    'PATStoreRecord',
+    'PATRefreshResult',
+    'PATProbeResult',
+    'PATRefreshPendingError',
+    'PATRefreshAmbiguousError',
+    'PATPersistenceError',
+]

sfdctrust/_async_client.py

@@ -0,0 +1,132 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            sfdctrust._async_client
+:Synopsis:          Asynchronous My Trust Center client
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff (via GPT-6.1 Sol)
+:Modified Date:     04 Nov 2026
+"""
+
+from __future__ import annotations
+
+from typing import Self
+
+import httpx
+
+from ._async_pat_refresh import _AsyncStoredPAT
+from ._async_transport import _AsyncTransport
+from ._auth import PATAuth, _Unset
+from ._exceptions import ConfigurationError
+from ._pat_refresh import PATRefreshResult, _validate_refresh_days
+from ._pat_store import AsyncPATStore
+from .resources._async_events import AsyncEventsResource
+from .resources._async_status import AsyncStatusResource
+from .resources._async_tenants import AsyncTenantsResource
+
+
+class AsyncTrustCenterClient:
+    """Asynchronous client for the Salesforce My Trust Center API.
+
+    Construction makes no network requests. The SDK owns its transport and
+    closes its default HTTP client on context exit or :meth:`aclose`.
+
+    :param pat: Personal access token without the Bearer prefix.
+    :param http_client: Trusted async HTTPX client whose lifecycle and TLS, proxy,
+                        hook, and transport settings remain the caller's responsibility.
+    :param max_retries: Additional SDK attempts per request, from 0 through 5.
+    :raises ConfigurationError: If the PAT or retry limit is invalid.
+    """
+
+    def __init__(self, pat: str, *, http_client: httpx.AsyncClient | None = None, max_retries: int = 2) -> None:
+        self._initialize(PATAuth(pat), http_client, max_retries)
+
+    def _initialize(self, auth: PATAuth | _AsyncStoredPAT, http_client: httpx.AsyncClient | None, max_retries: int) -> None:
+        self._stored_pat = auth if isinstance(auth, _AsyncStoredPAT) else None
+        self._transport = _AsyncTransport(
+            auth.read_auth if isinstance(auth, _AsyncStoredPAT) else auth, client=http_client, max_retries=max_retries
+        )
+        self.tenants = AsyncTenantsResource(self._transport)
+        self.status = AsyncStatusResource(self._transport)
+        self.events = AsyncEventsResource(self._transport)
+
+    @classmethod
+    def from_env(
+        cls, *, pat: str | None | _Unset = _Unset.PAT, http_client: httpx.AsyncClient | None = None, max_retries: int = 2
+    ) -> Self:
+        """Create a client using ``SFDCTRUST_PAT`` or an explicit override.
+
+        :param pat: An explicit override. Omitting it selects the environment.
+                    Explicit ``None`` or any invalid override raises immediately.
+        :param http_client: Optional caller-owned, trusted async HTTPX client.
+        :param max_retries: Additional SDK attempts per request, from 0 through 5.
+        :returns: A configured client.
+        :raises ConfigurationError: If the selected PAT is absent or invalid, or the retry limit is invalid.
+        """
+        auth = PATAuth.from_env(pat=pat)
+        client = cls.__new__(cls)
+        client._initialize(auth, http_client, max_retries)
+        return client
+
+    @classmethod
+    async def from_store(
+        cls, store: AsyncPATStore, *, http_client: httpx.AsyncClient | None = None, max_retries: int = 2
+    ) -> Self:
+        """Load an explicitly configured, seeded PAT store for one lineage.
+
+        :param store: Trusted durable adapter shared by all rotators of this PAT.
+        :param http_client: Optional caller-owned, trusted async HTTPX client. Its
+                            transport and hooks must never replay a refresh.
+        :param max_retries: Additional SDK attempts per eligible read, from 0 through 5.
+        :returns: A configured client.
+        :raises ConfigurationError: If the store is unsuitable, unreadable,
+                                    unseeded, or the retry limit is invalid.
+        :raises PATRefreshPendingError: If the store has an unresolved rotation.
+        """
+        auth = await _AsyncStoredPAT.open(store)
+        client = cls.__new__(cls)
+        client._initialize(auth, http_client, max_retries)
+        return client
+
+    async def refresh_pat(self, *, expires_in_days: int | None = None) -> PATRefreshResult:
+        """Explicitly rotate a stored PAT once and activate its durable replacement.
+
+        Cancellation propagates. If the replacement was received, keep this client
+        available to reconcile an interrupted commit with :meth:`retry_pat_persistence`.
+
+        :param expires_in_days: Replacement lifetime from 1 through 30.
+                                None omits the body and uses Salesforce's default.
+        :returns: A secret-free result indicating whether response metadata validated.
+        :raises ConfigurationError: If the client uses a static credential, the
+                                    lifetime is invalid, or the store is unreadable.
+        :raises PATRefreshPendingError: If a pending or competing operation blocks rotation.
+        :raises AuthenticationError: If Salesforce rejected refresh with HTTP 401.
+        :raises RateLimitError: If Salesforce rejected refresh with HTTP 429.
+        :raises PATRefreshAmbiguousError: If Salesforce may have rotated without a usable replacement.
+        :raises PATPersistenceError: If a required durable state transition cannot be confirmed.
+        """
+        if self._stored_pat is None:
+            raise ConfigurationError('PAT refresh requires a store-backed client.')
+        _validate_refresh_days(expires_in_days)
+        return await self._stored_pat.refresh(self._transport, expires_in_days)
+
+    async def retry_pat_persistence(self) -> PATRefreshResult:
+        """Reconcile or retry saving a replacement held by this client, using only store I/O.
+
+        :returns: The original secret-free result once durable storage is confirmed.
+        :raises ConfigurationError: If this client has no replacement awaiting persistence.
+        :raises PATRefreshPendingError: If another PAT operation is running on this client.
+        :raises PATPersistenceError: If the replacement still cannot be confirmed or saved.
+        """
+        if self._stored_pat is None:
+            raise ConfigurationError('PAT persistence requires a store-backed client.')
+        return await self._stored_pat.retry_persistence()
+
+    async def aclose(self) -> None:
+        """Close SDK-owned HTTP connections."""
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()

sfdctrust/_async_pat_refresh.py

@@ -0,0 +1,151 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            sfdctrust._async_pat_refresh
+:Synopsis:          Asynchronous store coordination for explicit PAT rotation
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff (via GPT-6.1 Sol)
+:Modified Date:     04 Nov 2026
+"""
+
+from __future__ import annotations
+
+from asyncio import Lock
+from typing import Self
+from uuid import UUID, uuid4
+
+from ._async_transport import _AsyncTransport
+from ._auth import PATAuth
+from ._exceptions import AuthenticationError, ConfigurationError, PATPersistenceError, PATRefreshPendingError, RateLimitError
+from ._pat_refresh import (
+    PATRefreshResult,
+    _matches_replacement,
+    _probe_error,
+    _replacement_write,
+    _require_ready,
+    _UnconfirmedWrite,
+)
+from ._pat_store import AsyncPATStore, PATStoreRecord
+
+
+class _AsyncStoredPAT:
+    def __init__(self, store: AsyncPATStore) -> None:
+        try:
+            suitable = isinstance(store, AsyncPATStore) and callable(store.load) and callable(store.compare_and_swap)
+        except Exception:
+            suitable = False
+        if not suitable:
+            raise ConfigurationError('A versioned async PAT store adapter is required.')
+        self._store = store
+        self._operation = Lock()
+        self._unconfirmed: _UnconfirmedWrite | None = None
+        self._loaded: tuple[UUID, PATAuth]
+
+    @classmethod
+    async def open(cls, store: AsyncPATStore) -> Self:
+        state = cls(store)
+        record = await state._load()
+        _require_ready(record)
+        state._activate(record)
+        return state
+
+    async def _load(self) -> PATStoreRecord:
+        try:
+            record = await self._store.load()
+        except Exception:
+            record = None
+        if type(record) is PATStoreRecord:
+            return record
+        raise ConfigurationError('The PAT store could not supply a valid seeded record.')
+
+    async def _swap(self, revision: UUID, attempt: UUID | None, replacement: PATStoreRecord, failure: str) -> bool:
+        try:
+            changed = await self._store.compare_and_swap(
+                expected_revision=revision, expected_attempt=attempt, replacement=replacement
+            )
+        except Exception:
+            changed = None
+        if type(changed) is bool:
+            return changed
+        raise PATPersistenceError(failure)
+
+    def _activate(self, record: PATStoreRecord) -> None:
+        self._loaded = (record.revision, PATAuth(record.get_pat()))
+
+    async def read_auth(self) -> PATAuth:
+        if self._unconfirmed is not None:
+            raise PATPersistenceError('Retry persistence before using this client.')
+        revision, auth = self._loaded
+        record = await self._load()
+        _require_ready(record)
+        if record.revision != revision:
+            raise ConfigurationError('The stored PAT changed. Recreate the store-backed client to reload it.')
+        return auth
+
+    async def refresh(self, transport: _AsyncTransport, days: int | None) -> PATRefreshResult:
+        if self._operation.locked():
+            raise PATRefreshPendingError('A PAT operation is already in progress on this client.')
+        async with self._operation:
+            if self._unconfirmed is not None:
+                raise PATPersistenceError('Retry persistence before refreshing again.')
+            return await self._refresh(transport, days)
+
+    async def _refresh(self, transport: _AsyncTransport, days: int | None) -> PATRefreshResult:
+        current = await self._load()
+        _require_ready(current)
+        old_pat = current.get_pat()
+        auth = PATAuth(old_pat)
+        attempt = uuid4()
+        pending = PATStoreRecord(current.revision, old_pat, attempt)
+        failure = 'Could not confirm the pending marker. No refresh was sent.'
+        if not await self._swap(current.revision, None, pending, failure):
+            raise PATRefreshPendingError('The PAT store changed before refresh. No refresh was sent.')
+
+        async with transport.refresh_once(auth, days) as (status, payload):
+            write = _replacement_write(current, attempt, payload)
+            # Retain the replacement before response cleanup or durable commit can suspend.
+            self._unconfirmed = write
+
+        if status in (401, 429):
+            failure = f'Refresh returned HTTP {status}, but the pending marker could not be cleared.'
+            if not await self._swap(current.revision, attempt, current, failure):
+                raise PATPersistenceError(failure)
+            if status == 401:
+                raise AuthenticationError()
+            raise RateLimitError()
+
+        if write is None:
+            raise _probe_error(await transport.probe_once(auth))
+        return await self._commit(write)
+
+    async def _commit(self, write: _UnconfirmedWrite) -> PATRefreshResult:
+        failure = 'Could not confirm durable storage of the replacement. Retry persistence on this client.'
+        if not await self._swap(write.revision, write.attempt, write.replacement, failure):
+            raise PATPersistenceError(failure)
+        return self._finish(write)
+
+    def _finish(self, write: _UnconfirmedWrite) -> PATRefreshResult:
+        self._activate(write.replacement)
+        self._unconfirmed = None
+        return write.result
+
+    async def retry_persistence(self) -> PATRefreshResult:
+        if self._operation.locked():
+            raise PATRefreshPendingError('A PAT operation is already in progress on this client.')
+        async with self._operation:
+            write = self._unconfirmed
+            if write is None:
+                raise ConfigurationError('This client has no replacement awaiting persistence.')
+            return await self._reconcile(write)
+
+    async def _reconcile(self, write: _UnconfirmedWrite) -> PATRefreshResult:
+        try:
+            current = await self._load()
+        except ConfigurationError:
+            current = None
+        if current is None:
+            raise PATPersistenceError('Could not read the PAT store to confirm the replacement.')
+        if current.revision == write.revision and current.pending_attempt == write.attempt:
+            return await self._commit(write)
+        if _matches_replacement(current, write):
+            return self._finish(write)
+        raise PATPersistenceError('The store changed while persistence was unresolved. Reconcile the store before use.')

sfdctrust/_async_transport.py

@@ -0,0 +1,129 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            sfdctrust._async_transport
+:Synopsis:          Native asynchronous HTTP transport for My Trust Center
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff (via GPT-6.1 Sol)
+:Modified Date:     04 Nov 2026
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import AbstractAsyncContextManager, asynccontextmanager, suppress
+from typing import Any
+
+import httpx
+
+from ._auth import PATAuth
+from ._transport import (
+    _BASE,
+    _READ_EXCEPTIONS,
+    _REFRESH_URL,
+    _build_request,
+    _can_retry,
+    _decode_json,
+    _decode_refresh,
+    _destination,
+    _pool_limits,
+    _QueryParams,
+    _read_failure,
+    _refresh_body,
+    _request_timeout,
+    _retry_delay,
+    _status_failure,
+    _validate_max_retries,
+)
+
+type _PATResponse = tuple[int | None, dict[str, object] | None]
+
+
+@asynccontextmanager
+async def _closing_response(response: httpx.Response) -> AsyncIterator[httpx.Response]:
+    try:
+        yield response
+    except asyncio.CancelledError:
+        with suppress(Exception):
+            await response.aclose()
+        raise
+    except BaseException:
+        await response.aclose()
+        raise
+    else:
+        await response.aclose()
+
+
+class _AsyncTransport:
+    def __init__(
+        self,
+        auth: PATAuth | Callable[[], Awaitable[PATAuth]],
+        *,
+        client: httpx.AsyncClient | None = None,
+        max_retries: int = 2,
+    ) -> None:
+        self._max_retries = _validate_max_retries(max_retries)
+        self._auth = auth
+        self._timeout = _request_timeout(None)
+        self._owns_client = client is None
+        self._client = httpx.AsyncClient(trust_env=False, limits=_pool_limits()) if client is None else client
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def _send(self, request: httpx.Request, auth: PATAuth) -> httpx.Response:
+        return await self._client.send(request, auth=auth, follow_redirects=False, stream=True)
+
+    def refresh_once(self, auth: PATAuth, days: int | None) -> AbstractAsyncContextManager[_PATResponse]:
+        """Expose the decoded response before awaiting any further cleanup."""
+        return self._pat_operation('POST', _REFRESH_URL, auth, json_body=_refresh_body(days))
+
+    async def probe_once(self, auth: PATAuth) -> int | None:
+        async with self._pat_operation('GET', _destination('/tenants'), auth) as (status, _):
+            return status
+
+    @asynccontextmanager
+    async def _pat_operation(
+        self, method: str, url: httpx.URL, auth: PATAuth, *, json_body: dict[str, int] | None = None
+    ) -> AsyncIterator[_PATResponse]:
+        response = None
+        status = None
+        payload = None
+        try:
+            try:
+                response = await self._send(_build_request(method, url, self._timeout, json_body=json_body), auth)
+                status = response.status_code
+                if method == 'POST' and response.is_success:
+                    payload = _decode_refresh(await response.aread())
+            except Exception:
+                # Hooks and custom transports can raise errors containing credentials.
+                payload = None
+            yield status, payload
+        finally:
+            if response is not None:
+                with suppress(Exception):
+                    await response.aclose()
+
+    async def request(self, method: str, path: str, *, params: _QueryParams | None = None, json_body: Any = None) -> Any:
+        url = _destination(path)
+        method = method.upper()
+        retryable = _can_retry(method, url.path.removeprefix(_BASE.path))
+
+        for attempt in range(self._max_retries + 1):
+            request = _build_request(method, url, self._timeout, params=params, json_body=json_body)
+            auth = self._auth if isinstance(self._auth, PATAuth) else await self._auth()
+            try:
+                async with _closing_response(await self._send(request, auth)) as response:
+                    if response.is_success:
+                        return _decode_json(await response.aread())
+                    error, transient, retry_after = _status_failure(response)
+            except _READ_EXCEPTIONS as exc:
+                error, transient = _read_failure(exc)
+                retry_after = None
+
+            if not retryable or not transient or attempt == self._max_retries:
+                raise error
+            await asyncio.sleep(_retry_delay(attempt, retry_after))
+
+        raise AssertionError('Unreachable retry state.')

sfdctrust/_auth.py

@@ -0,0 +1,96 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            sfdctrust._auth
+:Synopsis:          Internal PAT validation and single-request Bearer authentication
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff (via GPT-6.1 Sol)
+:Modified Date:     04 Nov 2026
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Generator
+from enum import Enum
+from typing import NoReturn, Self
+
+import httpx
+from pydantic import SecretStr
+
+from ._constants import DEFAULT_BASE_URL
+from ._exceptions import ConfigurationError
+
+
+class _Unset(Enum):
+    PAT = 'unset'
+
+
+def _validate_pat(pat: object) -> None:
+    if not isinstance(pat, str) or not pat or any(not 0x21 <= ord(char) <= 0x7E for char in pat):
+        raise ConfigurationError('PAT must be a nonempty string of visible ASCII characters without whitespace.')
+
+
+class PATAuth(httpx.Auth):
+    """Internal HTTPX authentication using an explicitly supplied PAT.
+
+    Construction performs no I/O and does not inspect the environment. PATs
+    are opaque, nonempty strings of visible ASCII characters; whitespace and
+    control characters are rejected, never stripped. No JWT parsing occurs.
+    Ordinary representations redact the secret, and pickling is disabled.
+
+    This component only attaches credentials. It does not translate HTTP
+    statuses, retry, or refresh a PAT. Future transport code must disable
+    redirects; HTTPX handles redirect requests outside this auth flow.
+
+    :param pat: The PAT itself, without a Bearer prefix.
+    :raises ConfigurationError: If the PAT is missing, blank, or unsafe for a header.
+    """
+
+    def __init__(self, pat: str) -> None:
+        _validate_pat(pat)
+        self._pat = SecretStr(pat)
+
+    @classmethod
+    def from_env(cls, *, pat: str | None | _Unset = _Unset.PAT) -> Self:
+        """Read only ``SFDCTRUST_PAT``, unless an override is supplied.
+
+        An explicit override wins without reading the environment. Empty,
+        blank, and explicitly supplied ``None`` overrides fail validation;
+        they never fall back to the environment. No credential files or
+        ``.env`` files are read, and the environment is never modified.
+
+        :param pat: Optional explicit override; omission selects the environment.
+        :returns: A validated authentication object.
+        :raises ConfigurationError: If the selected credential is invalid or absent.
+        """
+        selected = os.environ.get('SFDCTRUST_PAT') if pat is _Unset.PAT else pat
+        if not isinstance(selected, str):
+            raise ConfigurationError('PAT must be a nonempty string of visible ASCII characters without whitespace.')
+        return cls(selected)
+
+    def __repr__(self) -> str:
+        return f'{type(self).__name__}(pat=**********)'
+
+    def __getstate__(self) -> NoReturn:
+        """Prevent accidental credential serialization through pickle."""
+        raise TypeError('PAT authentication objects cannot be serialized.')
+
+    def auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response, None]:
+        """Attach the PAT once, only to the production HTTPS origin.
+
+        :param request: The request to authenticate.
+        :yields: The request with its Authorization header replaced.
+        :raises ConfigurationError: If the destination is outside the allowed origin
+            or contains URL user information.
+        """
+        destination = request.url
+        production = httpx.URL(DEFAULT_BASE_URL)
+        if (
+            destination.scheme != production.scheme
+            or destination.host != production.host
+            or destination.port != production.port
+            or destination.userinfo
+        ):
+            raise ConfigurationError('PAT authentication requires the production HTTPS origin without URL user information.')
+        request.headers['Authorization'] = f'Bearer {self._pat.get_secret_value()}'
+        yield request

sfdctrust/_client.py

@@ -0,0 +1,126 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            sfdctrust._client
+:Synopsis:          Synchronous My Trust Center client
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff (via GPT-6.1 Sol)
+:Modified Date:     04 Nov 2026
+"""
+
+from __future__ import annotations
+
+from typing import Self
+
+import httpx
+
+from ._auth import PATAuth, _Unset
+from ._exceptions import ConfigurationError
+from ._pat_refresh import PATRefreshResult, _StoredPAT, _validate_refresh_days
+from ._pat_store import PATStore
+from ._transport import _Transport
+from .resources.events import EventsResource
+from .resources.status import StatusResource
+from .resources.tenants import TenantsResource
+
+
+class TrustCenterClient:
+    """Synchronous client for the Salesforce My Trust Center API.
+
+    Construction makes no network requests. The SDK owns its transport and
+    closes its default HTTP client on context exit or :meth:`close`.
+
+    :param pat: Personal access token without the Bearer prefix.
+    :param http_client: Trusted HTTPX client whose lifecycle and TLS, proxy,
+                        hook, and transport settings remain the caller's responsibility.
+    :param max_retries: Additional SDK attempts per request, from 0 through 5.
+    :raises ConfigurationError: If the PAT or retry limit is invalid.
+    """
+
+    def __init__(self, pat: str, *, http_client: httpx.Client | None = None, max_retries: int = 2) -> None:
+        self._initialize(PATAuth(pat), http_client, max_retries)
+
+    def _initialize(self, auth: PATAuth | _StoredPAT, http_client: httpx.Client | None, max_retries: int) -> None:
+        self._stored_pat = auth if isinstance(auth, _StoredPAT) else None
+        self._transport = _Transport(
+            auth.read_auth if isinstance(auth, _StoredPAT) else auth, client=http_client, max_retries=max_retries
+        )
+        self.tenants = TenantsResource(self._transport)
+        self.status = StatusResource(self._transport)
+        self.events = EventsResource(self._transport)
+
+    @classmethod
+    def from_env(
+        cls, *, pat: str | None | _Unset = _Unset.PAT, http_client: httpx.Client | None = None, max_retries: int = 2
+    ) -> Self:
+        """Create a client using ``SFDCTRUST_PAT`` or an explicit override.
+
+        :param pat: An explicit override. Omitting it selects the environment.
+                    Explicit ``None`` or any invalid override raises immediately.
+        :param http_client: Optional caller-owned, trusted HTTPX client.
+        :param max_retries: Additional SDK attempts per request, from 0 through 5.
+        :returns: A configured client.
+        :raises ConfigurationError: If the selected PAT is absent or invalid, or the retry limit is invalid.
+        """
+        auth = PATAuth.from_env(pat=pat)
+        client = cls.__new__(cls)
+        client._initialize(auth, http_client, max_retries)
+        return client
+
+    @classmethod
+    def from_store(cls, store: PATStore, *, http_client: httpx.Client | None = None, max_retries: int = 2) -> Self:
+        """Load an explicitly configured, seeded PAT store for one lineage.
+
+        :param store: Trusted durable adapter shared by all rotators of this PAT.
+        :param http_client: Optional caller-owned, trusted HTTPX client. Its
+                            transport and hooks must never replay a refresh.
+        :param max_retries: Additional SDK attempts per eligible read, from 0 through 5.
+        :returns: A configured client.
+        :raises ConfigurationError: If the store is unsuitable, unreadable,
+                                    unseeded, or the retry limit is invalid.
+        :raises PATRefreshPendingError: If the store has an unresolved rotation.
+        """
+        auth = _StoredPAT(store)
+        client = cls.__new__(cls)
+        client._initialize(auth, http_client, max_retries)
+        return client
+
+    def refresh_pat(self, *, expires_in_days: int | None = None) -> PATRefreshResult:
+        """Explicitly rotate a stored PAT once and activate its durable replacement.
+
+        :param expires_in_days: Replacement lifetime from 1 through 30.
+                                None omits the body and uses Salesforce's default.
+        :returns: A secret-free result indicating whether response metadata validated.
+        :raises ConfigurationError: If the client uses a static credential, the
+                                    lifetime is invalid, or the store is unreadable.
+        :raises PATRefreshPendingError: If a pending or competing operation blocks rotation.
+        :raises AuthenticationError: If Salesforce rejected refresh with HTTP 401.
+        :raises RateLimitError: If Salesforce rejected refresh with HTTP 429.
+        :raises PATRefreshAmbiguousError: If Salesforce may have rotated without a usable replacement.
+        :raises PATPersistenceError: If a required durable state transition cannot be confirmed.
+        """
+        if self._stored_pat is None:
+            raise ConfigurationError('PAT refresh requires a store-backed client.')
+        _validate_refresh_days(expires_in_days)
+        return self._stored_pat.refresh(self._transport, expires_in_days)
+
+    def retry_pat_persistence(self) -> PATRefreshResult:
+        """Reconcile or retry saving a replacement held by this client, using only store I/O.
+
+        :returns: The original secret-free result once durable storage is confirmed.
+        :raises ConfigurationError: If this client has no replacement awaiting persistence.
+        :raises PATRefreshPendingError: If another PAT operation is running on this client.
+        :raises PATPersistenceError: If the replacement still cannot be confirmed or saved.
+        """
+        if self._stored_pat is None:
+            raise ConfigurationError('PAT persistence requires a store-backed client.')
+        return self._stored_pat.retry_persistence()
+
+    def close(self) -> None:
+        """Close SDK-owned HTTP connections."""
+        self._transport.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()