Metadata-Version: 2.4
Name: praxicraft-shared
Version: 0.8.1
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, support, Tutor, LLM clients). Products pin a **PyPI version**. No Django ORM, settings, or product business logic lives here.

| | |
| --- | --- |
| PyPI | https://pypi.org/project/praxicraft-shared/ |
| Current version | `0.8.1` (see `pyproject.toml`) |
| Python | 3.11+ |

## Contents

1. [About](#about)
2. [Install in a product](#install-in-a-product)
3. [Local development](#local-development)
4. [What’s in the package](#whats-in-the-package)
5. [Release](#release)
6. [Docs and deeper integrations](#docs-and-deeper-integrations)

---

## About

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  

Planning history: [Practice shared docs](https://github.com/praxicraft-platform/praxicraft-practice/blob/staging/docs/praxicraft-shared/README.md).

---

## Install in a product

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

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

Docker / CI need no GitHub token — 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
```

---

## What’s in the package

| Module | Role |
| --- | --- |
| `jwt_utils` | Validate RS256 access JWTs (JWKS / PEM) |
| `auth_client` | HTTP client for praxicraft-auth |
| `org_client` | Auth organisation directory |
| `billing_client` | Entitlements, checkout, cancel/resume |
| `notifications_client` | Send, events, prefs, push, inbox |
| `support_client` | Support tickets API |
| `ai_service` | Thin client for praxicraft-llm (chat, streaming, tools, `get_speech_audio`) |
| `s3_client` | Injectable MinIO/S3 helpers |
| `service_token` | Parse `product:token` / JSON maps |
| `error_envelope` | Standard success/error shapes |
| `events` | Event envelope helpers |
| `email/` | Shared HTML/text email templates (rendered by notifications) |
| `secret_crypto` | Fernet encrypt/decrypt (inject key) |
| `work_email` / `hibp` | Email helpers / HIBP check |

---

## Release

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

Pushing `main` alone runs **CI** only — it does **not** publish to PyPI until a `v*` tag exists.

---

## Docs and deeper integrations

| Link | Topic |
| --- | --- |
| [notifications PRODUCT-INTEGRATION](https://github.com/praxicraft-platform/praxicraft-notifications/blob/main/docs/PRODUCT-INTEGRATION.md) | How products call `notifications_client` |
| [support PRODUCT-INTEGRATION](https://github.com/praxicraft-platform/praxicraft-support/blob/main/docs/PRODUCT-INTEGRATION.md) | How products call `support_client` |
| [auth README](https://github.com/praxicraft-platform/praxicraft-auth#readme) | Application registry + JWT |
| [billing README](https://github.com/praxicraft-platform/praxicraft-billing#readme) | Entitlements client |
| [Tutor README](https://github.com/praxicraft-platform/praxicraft-tutor#readme) | End-to-end product wiring |
| [praxicraft-llm](https://github.com/praxicraft-platform/praxicraft-llm) | Gateway tokens for `ai_service` |
