paycascade-sdk 0.1.1__py3-none-any.whl

paycascade_sdk/__init__.py

@@ -0,0 +1,40 @@
+# Copyright (c) 2026 BitBerry Labs. SPDX-License-Identifier: MIT
+"""PayCascade customer-side SDK: cache and access middleware."""
+
+from paycascade_sdk.auth_intercept import (
+	DEFAULT_EXEMPT_ROUTES,
+	DEFAULT_MAX_STALENESS_SECONDS,
+	DEFAULT_READ_METHODS,
+	AccessDecision,
+	CachedSubscriptionState,
+	EscalationLevel,
+	FailPolicy,
+	InMemoryStateCache,
+	PayCascadeClient,
+	StateCache,
+	StatePoller,
+	calculate_jittered_interval,
+	enforce_cached_state,
+	initialize_state_cache,
+	is_route_exempt,
+	refresh_subscription_state,
+)
+
+__all__ = [
+	"DEFAULT_EXEMPT_ROUTES",
+	"DEFAULT_MAX_STALENESS_SECONDS",
+	"DEFAULT_READ_METHODS",
+	"AccessDecision",
+	"CachedSubscriptionState",
+	"EscalationLevel",
+	"FailPolicy",
+	"InMemoryStateCache",
+	"PayCascadeClient",
+	"StateCache",
+	"StatePoller",
+	"calculate_jittered_interval",
+	"enforce_cached_state",
+	"initialize_state_cache",
+	"is_route_exempt",
+	"refresh_subscription_state",
+]

paycascade_sdk/auth_intercept.py

@@ -0,0 +1,387 @@
+# Copyright (c) 2026 BitBerry Labs. SPDX-License-Identifier: MIT
+"""Customer-side SDK cache and access middleware for PayCascade.
+
+Provides background polling of the PayCascade hosted GET /api/v1/state endpoint,
+in-memory caching with jitter, and request-level access enforcement policies.
+This module is part of the standalone `paycascade-sdk` package and must never
+import from `app/` or require server-side dependencies.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from enum import Enum
+import random
+import threading
+import time
+from typing import Any, Callable, Sequence
+from uuid import UUID
+import httpx
+
+
+class EscalationLevel(str, Enum):
+	HEALTHY = "HEALTHY"
+	SOFT_WARNING = "SOFT_WARNING"
+	SCOPE_RESTRICTED = "SCOPE_RESTRICTED"
+	HARD_LOCKED = "HARD_LOCKED"
+	GRACE_PERIOD_EXPIRED = "GRACE_PERIOD_EXPIRED"
+
+
+class FailPolicy(str, Enum):
+	FAIL_OPEN = "FAIL_OPEN"
+	FAIL_CLOSED = "FAIL_CLOSED"
+
+
+@dataclass(frozen=True)
+class CachedSubscriptionState:
+	subscription_id: str
+	level: EscalationLevel
+	failed_at: datetime | None
+	retry_count: int
+	evaluated_at: datetime
+	cached_at: datetime
+
+	def is_stale(self, max_staleness_seconds: float, now: datetime | None = None) -> bool:
+		current_time = now or datetime.now(timezone.utc)
+		cached_time = self.cached_at
+		if cached_time.tzinfo is None:
+			cached_time = cached_time.replace(tzinfo=timezone.utc)
+		if current_time.tzinfo is None:
+			current_time = current_time.replace(tzinfo=timezone.utc)
+		age = (current_time - cached_time).total_seconds()
+		return age > max_staleness_seconds
+
+
+@dataclass(frozen=True)
+class AccessDecision:
+	allowed: bool
+	level: EscalationLevel | None
+	reason: str
+	warning: bool = False
+	is_stale: bool = False
+	is_exempt_route: bool = False
+
+
+DEFAULT_EXEMPT_ROUTES: tuple[str, ...] = (
+	"/billing",
+	"/stripe/portal-session",
+	"/logout",
+)
+
+DEFAULT_READ_METHODS: tuple[str, ...] = ("GET", "HEAD", "OPTIONS")
+DEFAULT_MAX_STALENESS_SECONDS: float = 86400.0  # 24 hours
+
+
+class StateCache:
+	"""Interface / base class for customer subscription state caching."""
+
+	def get(self, subscription_id: str) -> CachedSubscriptionState | None:
+		raise NotImplementedError
+
+	def set(self, state: CachedSubscriptionState) -> None:
+		raise NotImplementedError
+
+
+class InMemoryStateCache(StateCache):
+	"""Thread-safe in-memory cache for subscription states."""
+
+	def __init__(self) -> None:
+		self._lock = threading.RLock()
+		self._cache: dict[str, CachedSubscriptionState] = {}
+
+	def get(self, subscription_id: str) -> CachedSubscriptionState | None:
+		with self._lock:
+			return self._cache.get(str(subscription_id))
+
+	def set(self, state: CachedSubscriptionState) -> None:
+		with self._lock:
+			self._cache[str(state.subscription_id)] = state
+
+	def clear(self) -> None:
+		with self._lock:
+			self._cache.clear()
+
+
+def parse_iso_datetime(value: str | None) -> datetime | None:
+	if value is None:
+		return None
+	# Normalize Z to +00:00 for fromisoformat compatibility
+	clean_value = value.replace("Z", "+00:00")
+	dt = datetime.fromisoformat(clean_value)
+	if dt.tzinfo is None:
+		dt = dt.replace(tzinfo=timezone.utc)
+	return dt.astimezone(timezone.utc)
+
+
+class PayCascadeClient:
+	"""Client for interacting with the PayCascade hosted API contract."""
+
+	def __init__(
+		self,
+		base_url: str,
+		api_key: str,
+		http_client: httpx.Client | None = None,
+		timeout: float = 10.0,
+	) -> None:
+		self.base_url = base_url.rstrip("/")
+		self.api_key = api_key
+		self.timeout = timeout
+		self._client = http_client or httpx.Client(timeout=timeout)
+		self._owns_client = http_client is None
+
+	def close(self) -> None:
+		if self._owns_client:
+			self._client.close()
+
+	def fetch_state(self, subscription_id: str | UUID) -> CachedSubscriptionState:
+		url = f"{self.base_url}/api/v1/state"
+		headers = {
+			"Authorization": f"Bearer {self.api_key}",
+			"Accept": "application/json",
+		}
+		params = {"subscription_id": str(subscription_id)}
+
+		response = self._client.get(url, headers=headers, params=params)
+		response.raise_for_status()
+		data = response.json()
+
+		now = datetime.now(timezone.utc)
+		return CachedSubscriptionState(
+			subscription_id=str(data["subscription_id"]),
+			level=EscalationLevel(data["level"]),
+			failed_at=parse_iso_datetime(data.get("failed_at")),
+			retry_count=int(data["retry_count"]),
+			evaluated_at=parse_iso_datetime(data["evaluated_at"]) or now,
+			cached_at=now,
+		)
+
+
+def calculate_jittered_interval(interval_seconds: float, jitter_ratio: float = 0.2) -> float:
+	"""Compute a randomized interval with +/- jitter_ratio spread."""
+	if jitter_ratio <= 0.0:
+		return interval_seconds
+	jitter_bound = interval_seconds * jitter_ratio
+	return random.uniform(interval_seconds - jitter_bound, interval_seconds + jitter_bound)
+
+
+class StatePoller:
+	"""Background poller that periodically refreshes subscription state into a cache."""
+
+	def __init__(
+		self,
+		client: PayCascadeClient,
+		cache: StateCache,
+		subscription_ids: Sequence[str | UUID] | Callable[[], Sequence[str | UUID]],
+		interval_seconds: float = 300.0,
+		jitter_ratio: float = 0.2,
+		on_error: Callable[[str, Exception], None] | None = None,
+	) -> None:
+		self.client = client
+		self.cache = cache
+		self.subscription_ids = subscription_ids
+		self.interval_seconds = interval_seconds
+		self.jitter_ratio = jitter_ratio
+		self.on_error = on_error
+		self._stop_event = threading.Event()
+		self._thread: threading.Thread | None = None
+
+	def _get_subscription_ids(self) -> Sequence[str | UUID]:
+		if callable(self.subscription_ids):
+			return self.subscription_ids()
+		return self.subscription_ids
+
+	def refresh_all(self) -> dict[str, CachedSubscriptionState]:
+		refreshed: dict[str, CachedSubscriptionState] = {}
+		for sub_id in self._get_subscription_ids():
+			sub_id_str = str(sub_id)
+			try:
+				state = self.client.fetch_state(sub_id_str)
+				self.cache.set(state)
+				refreshed[sub_id_str] = state
+			except Exception as exc:
+				if self.on_error:
+					self.on_error(sub_id_str, exc)
+		return refreshed
+
+	def run_loop(self) -> None:
+		while not self._stop_event.is_set():
+			self.refresh_all()
+			delay = calculate_jittered_interval(self.interval_seconds, self.jitter_ratio)
+			if self._stop_event.wait(timeout=max(0.01, delay)):
+				break
+
+	def start(self) -> None:
+		if self._thread is not None and self._thread.is_alive():
+			return
+		self._stop_event.clear()
+		self._thread = threading.Thread(target=self.run_loop, daemon=True, name="PayCascadeStatePoller")
+		self._thread.start()
+
+	def stop(self, timeout: float = 5.0) -> None:
+		self._stop_event.set()
+		if self._thread is not None and self._thread.is_alive():
+			self._thread.join(timeout=timeout)
+
+
+def is_route_exempt(path: str, exempt_routes: Sequence[str] = DEFAULT_EXEMPT_ROUTES) -> bool:
+	"""Check if request path matches or is a subpath of an exempt recovery route."""
+	normalized_path = "/" + path.strip("/") if not path.startswith("/") else path
+	for exempt in exempt_routes:
+		normalized_exempt = "/" + exempt.strip("/") if not exempt.startswith("/") else exempt
+		if normalized_path == normalized_exempt or normalized_path.startswith(f"{normalized_exempt}/"):
+			return True
+	return False
+
+
+def enforce_cached_state(
+	subscription_id: str | UUID,
+	cache: StateCache,
+	path: str,
+	method: str = "GET",
+	exempt_routes: Sequence[str] = DEFAULT_EXEMPT_ROUTES,
+	fail_policy: FailPolicy = FailPolicy.FAIL_OPEN,
+	max_staleness_seconds: float = DEFAULT_MAX_STALENESS_SECONDS,
+	read_methods: Sequence[str] = DEFAULT_READ_METHODS,
+	now: datetime | None = None,
+) -> AccessDecision:
+	"""Enforce access control policies based strictly on cached state."""
+	sub_id_str = str(subscription_id)
+
+	# 1. Exempt recovery routes always bypass enforcement
+	if is_route_exempt(path, exempt_routes):
+		cached = cache.get(sub_id_str)
+		level = cached.level if cached else None
+		return AccessDecision(
+			allowed=True,
+			level=level,
+			reason="Route is exempt from payment access controls",
+			warning=False,
+			is_stale=False,
+			is_exempt_route=True,
+		)
+
+	cached = cache.get(sub_id_str)
+
+	# 2. Cache miss handling
+	if cached is None:
+		if fail_policy == FailPolicy.FAIL_OPEN:
+			return AccessDecision(
+				allowed=True,
+				level=None,
+				reason="Cache miss: fail-open policy allowed request",
+				warning=False,
+				is_stale=False,
+				is_exempt_route=False,
+			)
+		return AccessDecision(
+			allowed=False,
+			level=None,
+			reason="Cache miss: fail-closed policy blocked request",
+			warning=False,
+			is_stale=False,
+			is_exempt_route=False,
+		)
+
+	# 3. Staleness evaluation
+	is_stale = cached.is_stale(max_staleness_seconds=max_staleness_seconds, now=now)
+	if is_stale:
+		if fail_policy == FailPolicy.FAIL_OPEN:
+			return AccessDecision(
+				allowed=True,
+				level=cached.level,
+				reason=f"Cached state is stale (> {max_staleness_seconds}s): fail-open policy allowed request",
+				warning=True,
+				is_stale=True,
+				is_exempt_route=False,
+			)
+		return AccessDecision(
+			allowed=False,
+			level=cached.level,
+			reason=f"Cached state is stale (> {max_staleness_seconds}s): fail-closed policy blocked request",
+			warning=False,
+			is_stale=True,
+			is_exempt_route=False,
+		)
+
+	# 4. Active escalation level enforcement
+	normalized_method = method.upper()
+	level = cached.level
+
+	if level == EscalationLevel.HEALTHY:
+		return AccessDecision(
+			allowed=True,
+			level=level,
+			reason="Subscription is healthy",
+			warning=False,
+			is_stale=False,
+		)
+
+	if level == EscalationLevel.SOFT_WARNING:
+		return AccessDecision(
+			allowed=True,
+			level=level,
+			reason="Payment delinquent (soft warning): access allowed with warning indicator",
+			warning=True,
+			is_stale=False,
+		)
+
+	if level == EscalationLevel.SCOPE_RESTRICTED:
+		if normalized_method in (m.upper() for m in read_methods):
+			return AccessDecision(
+				allowed=True,
+				level=level,
+				reason="Payment delinquent (scope restricted): read access allowed",
+				warning=True,
+				is_stale=False,
+			)
+		return AccessDecision(
+			allowed=False,
+			level=level,
+			reason="Payment delinquent (scope restricted): mutating write operations are blocked",
+			warning=True,
+			is_stale=False,
+		)
+
+	if level == EscalationLevel.HARD_LOCKED:
+		return AccessDecision(
+			allowed=False,
+			level=level,
+			reason="Payment delinquent (hard locked): protected application access is blocked",
+			warning=True,
+			is_stale=False,
+		)
+
+	if level == EscalationLevel.GRACE_PERIOD_EXPIRED:
+		return AccessDecision(
+			allowed=False,
+			level=level,
+			reason="Grace period expired: protected application access is blocked",
+			warning=False,
+			is_stale=False,
+		)
+
+	# Fallback safety guard
+	return AccessDecision(
+		allowed=False,
+		level=level,
+		reason=f"Unknown escalation level: {level}",
+		warning=False,
+		is_stale=False,
+	)
+
+
+def initialize_state_cache() -> StateCache:
+	"""Helper factory to create a default in-memory state cache."""
+	return InMemoryStateCache()
+
+
+def refresh_subscription_state(
+	client: PayCascadeClient,
+	cache: StateCache,
+	subscription_id: str | UUID,
+) -> CachedSubscriptionState:
+	"""Synchronously refresh and cache subscription state for a single subscription."""
+	state = client.fetch_state(subscription_id)
+	cache.set(state)
+	return state

paycascade_sdk-0.1.1.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: paycascade-sdk
+Version: 0.1.1
+Summary: Customer-side cache and access middleware for the PayCascade hosted billing-state API.
+Author: BitBerry Labs
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+License-File: LICENSE.md
+Requires-Dist: httpx>=0.27.0
+Dynamic: license-file

paycascade_sdk-0.1.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+paycascade_sdk/__init__.py,sha256=CAnqlEGsY_SnthyKWljXV-bhFNR-Wm0xTGacy0Q91CY,914
+paycascade_sdk/auth_intercept.py,sha256=Rkp0z9ut8OECBuw3pkh9PWJhlmE4EXf7DVUZPf-d380,11204
+paycascade_sdk-0.1.1.dist-info/licenses/LICENSE.md,sha256=PO_mgqJjeQn1eDM0cRNP-uIqxZDrZhM1y8G_ORR6BNI,1372
+paycascade_sdk-0.1.1.dist-info/METADATA,sha256=XA41YZ7AqULkXHLCCzNMDaIop6Oz86-VVAJ5hOsXFvc,759
+paycascade_sdk-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+paycascade_sdk-0.1.1.dist-info/top_level.txt,sha256=XWU_tQqPJogAFHCyJ-Bjfjyr7WpVJ1sp_qrT4IkwQKg,15
+paycascade_sdk-0.1.1.dist-info/RECORD,,

paycascade_sdk-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

paycascade_sdk-0.1.1.dist-info/licenses/LICENSE.md

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 BitBerry Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+SCOPE: This license applies only to the PayCascade customer SDK files in this
+directory and the corresponding SDK package. It does not license the PayCascade
+server or any other files in the repository, and it grants no rights to
+BitBerry Labs trademarks. The root LICENSE.md governs all other files.

paycascade_sdk-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+paycascade_sdk