Metadata-Version: 2.4
Name: paycascade-sdk
Version: 0.1.2
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
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: httpx>=0.27.0
Dynamic: license-file

# PayCascade Python SDK

The SDK is a customer-side helper for polling the PayCascade state API and
making access decisions from a local cache. It is publicly installable from
PyPI under the MIT License and is also included in the self-hosted Dev Kit.
The SDK is not required to run the Dev Kit server.

Install the public package from the default PyPI index:

```sh
python -m pip install paycascade-sdk
```

Anyone can install, use, modify, and redistribute the SDK under the MIT
License. Package downloads are not gated by a hosted subscription. Calling
PayCascade's hosted API still requires a valid API key and applicable hosted
service entitlement. In a source checkout or Dev Kit snapshot, install locally
with:

```sh
python -m pip install ./sdk
```

The SDK is distributed under the [MIT License](LICENSE.md); that license
covers only the SDK and grants no rights to the server or BitBerry Labs
trademarks. The SDK requires Python 3.11 or newer and `httpx`. It polls the PayCascade
state API and offers client-side access-decision helpers; it does not receive
or process Stripe webhooks. Stripe sends customer billing webhooks to the
PayCascade service. The SDK does not enforce policy in your application
automatically: your application must call the decision helper and apply the
result to its own routes and user experience.

## Example

Keep the API key on your application server; never ship it to a browser or
mobile client. Replace the example values with the PayCascade API base URL,
tenant API key, and PayCascade subscription ID that your application has
registered.

```python
import logging
import os
from uuid import UUID

from paycascade_sdk import (
    FailPolicy,
    InMemoryStateCache,
    PayCascadeClient,
    StatePoller,
    enforce_cached_state,
)

logger = logging.getLogger(__name__)
subscription_id = UUID(os.environ["PAYCASCADE_SUBSCRIPTION_ID"])
client = PayCascadeClient(
    base_url=os.environ["PAYCASCADE_API_URL"],
    api_key=os.environ["PAYCASCADE_API_KEY"],
)
cache = InMemoryStateCache()


def report_poll_error(subscription_id: str, error: Exception) -> None:
    logger.warning("PayCascade state refresh failed for %s: %s", subscription_id, error)


poller = StatePoller(
    client=client,
    cache=cache,
    subscription_ids=[subscription_id],
    interval_seconds=300,
    on_error=report_poll_error,
)
poller.start()

try:
    # In your request handler, use the authenticated user's mapped subscription.
    decision = enforce_cached_state(
        subscription_id=subscription_id,
        cache=cache,
        path="/reports",
        method="GET",
        fail_policy=FailPolicy.FAIL_OPEN,
    )
    if not decision.allowed:
        # Return your application's own payment/recovery response.
        ...
finally:
    poller.stop()
    client.close()
```

`StatePoller.start()` refreshes immediately and then polls at the configured
interval with jitter. Provide `on_error` so refresh failures are observable.
For multi-process applications, each process has its own in-memory cache;
polling frequency and API load should be planned accordingly.

## Access-policy behavior

- The default `FAIL_OPEN` policy allows access when state is missing or stale.
  `FAIL_CLOSED` blocks access in those cases. Choose deliberately for your
  product and communicate failure behavior to users.
- Healthy and soft-warning states allow access; the warning state can be used
  to show a recovery notice. Restricted state permits configured read methods
  and blocks mutations. Hard-locked and grace-period-expired states deny
  protected access.
- Recovery routes such as `/billing`, `/stripe/portal-session`, and `/logout`
  are exempt by default. Customize exemptions to preserve a usable payment
  recovery path.
- Protect against forged or mismatched subscription IDs by looking up the
  PayCascade subscription ID from your own authenticated account records.
- The cache is process-local and not a security boundary. Your application is
  responsible for authorization, mapping users to subscriptions, and presenting
  access decisions.
