Metadata-Version: 2.4
Name: praxicraft-shared
Version: 0.7.2
Summary: Stateless cross-product Python utilities for Praxicraft backends
Author-email: Praxicraft <support@praxicraft.com>
License: Proprietary
Project-URL: Homepage, https://github.com/praxicraft-platform/praxicraft-shared
Project-URL: Repository, https://github.com/praxicraft-platform/praxicraft-shared
Project-URL: Issues, https://github.com/praxicraft-platform/praxicraft-shared/issues
Keywords: praxicraft,jwt,auth,billing,s3,minio
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=42.0.0
Requires-Dist: requests>=2.32.0
Requires-Dist: PyJWT[crypto]>=2.8.0
Requires-Dist: boto3>=1.34.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"

# praxicraft-shared

Stateless Python utilities shared by Praxicraft backends (Practice, auth, notifications, billing, and future services). Products pin a **PyPI version**; no Django ORM, settings, or product business logic lives here.

**Planning & milestones:** [`Gamified-Application/docs/praxicraft-shared/README.md`](https://github.com/praxicraft-platform/praxicraft-practice/blob/staging/docs/praxicraft-shared/README.md)

## Prerequisites

- Python 3.11+

## Install (in a product)

Published on **[PyPI](https://pypi.org/project/praxicraft-shared/)**:

```text
praxicraft-shared==0.7.2
```

```bash
pip install praxicraft-shared==0.7.2
```

Docker / CI need no GitHub token for this package — public index only.

Local editable (sibling checkout):

```bash
pip install -e ~/Desktop/praxicraft-shared
```

## Local development

```bash
cd ~/Desktop/praxicraft-shared
pip install -e ".[dev]"
ruff check src tests
pytest
```

## Release

1. Bump `version` in `pyproject.toml` and `__version__` in `src/praxicraft_shared/__init__.py`.
2. Merge to `main`, tag `vX.Y.Z`, push the tag (or run **Publish** → workflow_dispatch with that tag).
3. GitHub Actions publishes to PyPI via Trusted Publishing and creates a GitHub Release.

## What’s in the package

| Module | Role |
| --- | --- |
| `jwt_utils` | Validate RS256 access JWTs (JWKS / PEM) |
| `auth_client` | HTTP client for `praxicraft-auth` (token exchange, me, …) |
| `org_client` | HTTP client for the auth organisation directory (org, membership, role, teams) |
| `billing_client` | HTTP client for `praxicraft-billing` (entitlements, checkout, cancel/resume) |
| `s3_client` | Injectable MinIO/S3 helpers (`make_s3_client`, put/get/presign, prefix download) |
| `notifications_client` | HTTP client for praxicraft-notifications (send, events, prefs, push, inbox) |
| `service_token` | Parse `product:token` / JSON service-token maps (no DRF) |
| `ai_service` | Thin client for `praxicraft-llm` (gateway + circuit-breaker fallback) |
| `error_envelope` | Standard success/error dict shapes |
| `events` | Event envelope helpers + `events/SCHEMA.md` |
| `email/` | Shared HTML/text email templates (rendered by notifications) |
| `secret_crypto` | Fernet encrypt/decrypt (inject key) |
| `work_email` | Email normalize / consumer-domain helpers |
| `hibp` | Have I Been Pwned password check |

`org_client` ships ahead of the auth **A7** cutover: directory reads hit `/api/v1/internal/orgs/…`, and list helpers return `[]` while an endpoint is not deployed yet, so products can pin 0.7.0 before auth exposes the API.

## Hard rules

1. Stateless — no Django models, ORM, Celery, or package-owned Redis singletons  
2. No `django.conf.settings` — callers inject URLs and keys  
3. No product logic (XP, Assess scoring, Tutor mastery)  
4. Semver via git tags + PyPI — breaking JWT/auth contracts = major bump  

## Related

- [praxicraft-auth](https://github.com/praxicraft-platform/praxicraft-auth)  
- [praxicraft-notifications](https://github.com/praxicraft-platform/praxicraft-notifications)  
- [praxicraft-llm](https://github.com/praxicraft-platform/praxicraft-llm)  
- [praxicraft-billing](https://github.com/praxicraft-platform/praxicraft-billing)  
