stapel-orders 0.1.0__tar.gz

stapel_orders-0.1.0/CONFIG.MD

@@ -0,0 +1,27 @@
+# CONFIG.MD — stapel-orders
+
+Config registry for **stapel-orders**. One row per configuration key the
+module reads, its **source** (`env` = the process environment / the
+`STAPEL_ORDERS` settings dict), what it is for, whether it is required, and
+its default.
+
+Every key is read through `orders_settings` (`stapel_orders.conf`, namespace
+`STAPEL_ORDERS`). Resolution order per key: `settings.STAPEL_ORDERS` dict →
+a flat Django setting of the same name → environment variable → the default
+below. `CHECKOUT_REQUIRES_ACCOUNT` and `PAYMENT` are CTO-facing config axes.
+
+## stapel-orders
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| PURCHASABLE_TYPES | settings | what can be bought: {type_name: {"resolve": "<comm function>"}} merged over the empty built-ins; None removes a type. Empty is system check E001. | yes | {} |
+| CHECKOUT_REQUIRES_ACCOUNT | env | axis: a guest (anonymous account) is refused at checkout with `error.403.checkout_requires_account`. Not derived from the posture. | no | true |
+| MAX_LINE_QUANTITY | env | cap on one line's quantity; feeds the money-bound proof (E005). | no | 999 |
+| MAX_LINES_PER_CART | env | cap on distinct lines per cart; feeds the money-bound proof (E005). | no | 100 |
+| CART_TTL_DAYS | env | carts untouched this long are purged (beat entry / `manage.py purge_carts`). | no | 30 |
+| BASE_CURRENCY | env | reporting currency of `Order.total_base`. | no | USD |
+| TOTAL_BASE_CONVERTER | settings | dotted path `(amount, currency, base) -> Decimal or None` computing `total_base`; default asks `currencies.convert`, NULL when unanswered. | no | stapel_orders.money.currencies_converter |
+| PAYMENT | env | axis: `none` (orders stay unpaid, staff confirm) or `mock` (paid at once; prototype stage only, E002/W002), or a registered provider name; a dotted path only from the settings module. | no | none |
+| OWNER_CANCELLABLE_STATUSES | settings | statuses from which the buyer may cancel their own order. | no | ("new",) |
+| NOTIFY | env | best-effort buyer notifications `orders.placed` / `orders.status_changed`. | no | true |
+| ORDER_URL_TEMPLATE | env | `{order_id}` / `{number}` template for notification links; empty = no link. | no | "" |

stapel_orders-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stapel contributors
+
+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.

stapel_orders-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: stapel-orders
+Version: 0.1.0
+Summary: Cart, checkout and orders for the Stapel framework
+License: MIT
+Project-URL: Homepage, https://github.com/usestapel/stapel-orders
+Project-URL: Repository, https://github.com/usestapel/stapel-orders
+Project-URL: Documentation, https://github.com/usestapel/stapel-orders#readme
+Project-URL: Changelog, https://github.com/usestapel/stapel-orders/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/usestapel/stapel-orders/issues
+Keywords: django,stapel,orders,cart,checkout,ecommerce
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<1.0,>=0.95.0
+Provides-Extra: all
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-django; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: stapel-tools<1,>=0.76.0; extra == "test"
+Requires-Dist: jsonschema>=4; extra == "test"
+Dynamic: license-file
+
+<!-- Generated by stapel-readme from docs/readme.md + docs/*.json. Do not edit this file; edit docs/readme.md and re-run `make readme`. -->
+
+# stapel-orders
+
+[![CI](https://img.shields.io/github/actions/workflow/status/usestapel/stapel-orders/ci.yml?branch=main&logo=github&label=CI)](https://github.com/usestapel/stapel-orders/actions/workflows/ci.yml?query=branch%3Amain)
+[![coverage](https://img.shields.io/codecov/c/github/usestapel/stapel-orders?branch=main&logo=codecov&label=coverage)](https://app.codecov.io/gh/usestapel/stapel-orders)
+[![pypi](https://img.shields.io/pypi/v/stapel-orders?logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/stapel-orders/)
+[![downloads](https://static.pepy.tech/badge/stapel-orders/month)](https://pepy.tech/project/stapel-orders)
+[![python](https://img.shields.io/pypi/pyversions/stapel-orders?logo=python&logoColor=white)](https://pypi.org/project/stapel-orders/)
+[![license](https://img.shields.io/github/license/usestapel/stapel-orders)](https://github.com/usestapel/stapel-orders/blob/main/LICENSE)
+[![llms.txt](https://img.shields.io/badge/llms.txt-blue)](https://github.com/usestapel/stapel-orders/blob/main/docs/llms.txt)
+
+> Cart, checkout and orders over opaque purchasables. A host registers what can be bought (purchasable_type -> a keyed-batch resolver Function answering title, price, currency, availability); the cart snapshots each line when it is added, so reading a cart never calls the product owner. Checkout re-prices every line, refuses with the refreshed cart when anything drifted, and places an order idempotently on a client key, emptying the cart and announcing orders.order.placed with its lines. Orders follow a staff-driven lifecycle with buyer cancel; payment is a provider seam (none, mock) whose outcome arrives as the payment.completed fact.
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps that deploy as a monolith or as microservices without changing module code.
+
+## Install
+
+```bash
+pip install stapel-orders
+```
+
+## At a glance
+
+| Fact | Value |
+|---|---|
+| Version | `0.1.0` |
+| Python | `>=3.11` (3.11, 3.12, 3.13, 3.14) |
+| HTTP operations | 10 |
+| Config axes | 2 |
+| Usage surface | 11 |
+| Extension points | 7 |
+| Error codes | 54 |
+| Documented flows | 4 |
+| Fleet dependencies | [`stapel-auth`](https://github.com/usestapel/stapel-auth) (optional) · [`stapel-core`](https://github.com/usestapel/stapel-core) · [`stapel-currencies`](https://github.com/usestapel/stapel-currencies) (optional) · [`stapel-listings`](https://github.com/usestapel/stapel-listings) (optional) |
+
+## Documentation
+
+[OpenAPI](https://github.com/usestapel/stapel-orders/blob/main/docs/schema.json) · [capabilities.json](https://github.com/usestapel/stapel-orders/blob/main/docs/capabilities.json) · [llms.txt (for agents)](https://github.com/usestapel/stapel-orders/blob/main/docs/llms.txt)
+
+## What this is
+
+Cart, checkout and orders for a Stapel shop — over **opaque purchasables**.
+The module ships knowing nothing about what is sold: a host registers each
+purchasable type with a comm Function that resolves a keyed batch of keys to
+title, price, currency and availability. Orders never imports a product
+model, so a listing, a spare part from a custom app, or anything else is
+bought through one cart.
+
+## Quick start
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "stapel_orders",
+]
+
+STAPEL_ORDERS = {
+    "PURCHASABLE_TYPES": {
+        "listing": {"resolve": "listings.purchasables"},  # stapel-shop preset default
+    },
+}
+
+# urls.py
+path("orders/api/", include("stapel_orders.urls"))   # -> /orders/api/v1/...
+
+# settings.py — the abandoned-cart purge (Celery optional)
+from stapel_orders.beat import get_orders_beat_schedule
+CELERY_BEAT_SCHEDULE = {**get_orders_beat_schedule()}
+```
+
+A custom product type is one resolver and one registration:
+
+```python
+from stapel_core.comm import function
+
+@function("parts.purchasables")
+def purchasables(payload):
+    parts = Part.objects.filter(pk__in=payload["keys"])
+    return {str(p.pk): {"title": p.name, "price": str(p.price), "currency": "USD",
+                        "available": p.stock > 0, "max_quantity": p.stock,
+                        "seller_id": None, "image": None, "url": f"/parts/{p.pk}"}
+            for p in parts}
+
+# AppConfig.ready()
+from stapel_orders.registry import register_purchasable_type
+register_purchasable_type("part", {"resolve": "parts.purchasables"})
+```
+
+## Concepts
+
+- **Purchasable** — an opaque pair `(purchasable_type, purchasable_key)`.
+  The resolver answers on add and at checkout only; a cart line is a
+  snapshot, so `GET cart/` makes zero comm calls.
+- **Cart** — one per user. A stapel-auth guest is a user too, and
+  `user.merged` folds the guest's cart into the account on sign-in (same
+  item summed, capped at `MAX_LINE_QUANTITY`). One currency per cart; a line
+  in another currency is refused, never converted.
+- **Checkout** — one idempotent call (`idempotency_key`). Every line is
+  re-priced; a changed price, a vanished item or short stock refreshes the
+  cart and refuses with it in `params.cart`, so the shopper is never charged
+  a number they did not see. Guests are asked to sign in unless
+  `CHECKOUT_REQUIRES_ACCOUNT` is off.
+- **Order** — `new → confirmed → shipped → completed`, cancel from `new` by
+  the buyer (`OWNER_CANCELLABLE_STATUSES`), staff for the rest, `needs_review`
+  when a payment does not match. History is anchor-paginated.
+- **Money** — `Decimal` inside, strings on the wire. Line and cart limits
+  are a proof that a total cannot overflow its column
+  (`tests/test_money_bounds.py`, system check `E005`).
+- **Payment** — a provider seam: `none` (staff confirm by hand) or `mock`
+  (prototype posture only). The outcome always arrives as
+  `payment.completed`, the one path that marks an order paid.
+- **GDPR** — erasure deletes carts and pseudonymizes the person on orders;
+  amounts stay.
+
+## License
+
+MIT — see [LICENSE](https://github.com/usestapel/stapel-orders/blob/main/LICENSE).
+
+---
+
+<sub>This page is assembled by `stapel-readme` from `docs/readme.md` plus the contract artifacts in `docs/`. Edit the prose in `docs/readme.md`; the badges, facts and links above and below it are generated — do not hand-edit `README.md`.</sub>

stapel_orders-0.1.0/README.md

@@ -0,0 +1,122 @@
+<!-- Generated by stapel-readme from docs/readme.md + docs/*.json. Do not edit this file; edit docs/readme.md and re-run `make readme`. -->
+
+# stapel-orders
+
+[![CI](https://img.shields.io/github/actions/workflow/status/usestapel/stapel-orders/ci.yml?branch=main&logo=github&label=CI)](https://github.com/usestapel/stapel-orders/actions/workflows/ci.yml?query=branch%3Amain)
+[![coverage](https://img.shields.io/codecov/c/github/usestapel/stapel-orders?branch=main&logo=codecov&label=coverage)](https://app.codecov.io/gh/usestapel/stapel-orders)
+[![pypi](https://img.shields.io/pypi/v/stapel-orders?logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/stapel-orders/)
+[![downloads](https://static.pepy.tech/badge/stapel-orders/month)](https://pepy.tech/project/stapel-orders)
+[![python](https://img.shields.io/pypi/pyversions/stapel-orders?logo=python&logoColor=white)](https://pypi.org/project/stapel-orders/)
+[![license](https://img.shields.io/github/license/usestapel/stapel-orders)](https://github.com/usestapel/stapel-orders/blob/main/LICENSE)
+[![llms.txt](https://img.shields.io/badge/llms.txt-blue)](https://github.com/usestapel/stapel-orders/blob/main/docs/llms.txt)
+
+> Cart, checkout and orders over opaque purchasables. A host registers what can be bought (purchasable_type -> a keyed-batch resolver Function answering title, price, currency, availability); the cart snapshots each line when it is added, so reading a cart never calls the product owner. Checkout re-prices every line, refuses with the refreshed cart when anything drifted, and places an order idempotently on a client key, emptying the cart and announcing orders.order.placed with its lines. Orders follow a staff-driven lifecycle with buyer cancel; payment is a provider seam (none, mock) whose outcome arrives as the payment.completed fact.
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps that deploy as a monolith or as microservices without changing module code.
+
+## Install
+
+```bash
+pip install stapel-orders
+```
+
+## At a glance
+
+| Fact | Value |
+|---|---|
+| Version | `0.1.0` |
+| Python | `>=3.11` (3.11, 3.12, 3.13, 3.14) |
+| HTTP operations | 10 |
+| Config axes | 2 |
+| Usage surface | 11 |
+| Extension points | 7 |
+| Error codes | 54 |
+| Documented flows | 4 |
+| Fleet dependencies | [`stapel-auth`](https://github.com/usestapel/stapel-auth) (optional) · [`stapel-core`](https://github.com/usestapel/stapel-core) · [`stapel-currencies`](https://github.com/usestapel/stapel-currencies) (optional) · [`stapel-listings`](https://github.com/usestapel/stapel-listings) (optional) |
+
+## Documentation
+
+[OpenAPI](https://github.com/usestapel/stapel-orders/blob/main/docs/schema.json) · [capabilities.json](https://github.com/usestapel/stapel-orders/blob/main/docs/capabilities.json) · [llms.txt (for agents)](https://github.com/usestapel/stapel-orders/blob/main/docs/llms.txt)
+
+## What this is
+
+Cart, checkout and orders for a Stapel shop — over **opaque purchasables**.
+The module ships knowing nothing about what is sold: a host registers each
+purchasable type with a comm Function that resolves a keyed batch of keys to
+title, price, currency and availability. Orders never imports a product
+model, so a listing, a spare part from a custom app, or anything else is
+bought through one cart.
+
+## Quick start
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "stapel_orders",
+]
+
+STAPEL_ORDERS = {
+    "PURCHASABLE_TYPES": {
+        "listing": {"resolve": "listings.purchasables"},  # stapel-shop preset default
+    },
+}
+
+# urls.py
+path("orders/api/", include("stapel_orders.urls"))   # -> /orders/api/v1/...
+
+# settings.py — the abandoned-cart purge (Celery optional)
+from stapel_orders.beat import get_orders_beat_schedule
+CELERY_BEAT_SCHEDULE = {**get_orders_beat_schedule()}
+```
+
+A custom product type is one resolver and one registration:
+
+```python
+from stapel_core.comm import function
+
+@function("parts.purchasables")
+def purchasables(payload):
+    parts = Part.objects.filter(pk__in=payload["keys"])
+    return {str(p.pk): {"title": p.name, "price": str(p.price), "currency": "USD",
+                        "available": p.stock > 0, "max_quantity": p.stock,
+                        "seller_id": None, "image": None, "url": f"/parts/{p.pk}"}
+            for p in parts}
+
+# AppConfig.ready()
+from stapel_orders.registry import register_purchasable_type
+register_purchasable_type("part", {"resolve": "parts.purchasables"})
+```
+
+## Concepts
+
+- **Purchasable** — an opaque pair `(purchasable_type, purchasable_key)`.
+  The resolver answers on add and at checkout only; a cart line is a
+  snapshot, so `GET cart/` makes zero comm calls.
+- **Cart** — one per user. A stapel-auth guest is a user too, and
+  `user.merged` folds the guest's cart into the account on sign-in (same
+  item summed, capped at `MAX_LINE_QUANTITY`). One currency per cart; a line
+  in another currency is refused, never converted.
+- **Checkout** — one idempotent call (`idempotency_key`). Every line is
+  re-priced; a changed price, a vanished item or short stock refreshes the
+  cart and refuses with it in `params.cart`, so the shopper is never charged
+  a number they did not see. Guests are asked to sign in unless
+  `CHECKOUT_REQUIRES_ACCOUNT` is off.
+- **Order** — `new → confirmed → shipped → completed`, cancel from `new` by
+  the buyer (`OWNER_CANCELLABLE_STATUSES`), staff for the rest, `needs_review`
+  when a payment does not match. History is anchor-paginated.
+- **Money** — `Decimal` inside, strings on the wire. Line and cart limits
+  are a proof that a total cannot overflow its column
+  (`tests/test_money_bounds.py`, system check `E005`).
+- **Payment** — a provider seam: `none` (staff confirm by hand) or `mock`
+  (prototype posture only). The outcome always arrives as
+  `payment.completed`, the one path that marks an order paid.
+- **GDPR** — erasure deletes carts and pseudonymizes the person on orders;
+  amounts stay.
+
+## License
+
+MIT — see [LICENSE](https://github.com/usestapel/stapel-orders/blob/main/LICENSE).
+
+---
+
+<sub>This page is assembled by `stapel-readme` from `docs/readme.md` plus the contract artifacts in `docs/`. Edit the prose in `docs/readme.md`; the badges, facts and links above and below it are generated — do not hand-edit `README.md`.</sub>

stapel_orders-0.1.0/__init__.py

@@ -0,0 +1,31 @@
+"""stapel-orders — Cart, checkout and orders for the Stapel framework.
+
+Public API (lazily exported, PEP 562 — importing this package never pulls
+in Django or requires configured settings):
+
+- ``orders_settings`` — resolved app settings (``stapel_orders.conf``).
+"""
+
+__all__ = [
+    "orders_settings",
+]
+
+# name -> submodule that defines it. Resolution is deferred until first
+# attribute access so that `import stapel_orders` stays Django-free.
+_LAZY_EXPORTS = {
+    "orders_settings": ".conf",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_EXPORTS:
+        from importlib import import_module
+
+        value = getattr(import_module(_LAZY_EXPORTS[name], __name__), name)
+        globals()[name] = value  # cache for subsequent lookups
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_orders-0.1.0/_capabilities.py

@@ -0,0 +1,36 @@
+"""stapel-orders capabilities.json emitter — thin shim over stapel_tools.capabilities."""
+from pathlib import Path
+
+from stapel_tools.capabilities import axis_group_rules, run_capabilities_cli
+
+
+def main(argv=None):
+    from stapel_orders._codegen import _configure
+
+    _configure()
+    from stapel_orders.conf import DEFAULTS
+    from stapel_orders.urls import GATE_REGISTRY
+
+    # Two CTO-facing axes, both behavioural (no endpoint is unmounted):
+    # CHECKOUT_REQUIRES_ACCOUNT (guest checkout) and PAYMENT (none | mock |
+    # a registered provider). PURCHASABLE_TYPES is the extension seam.
+    axes = {"CHECKOUT_REQUIRES_ACCOUNT", "PAYMENT"}
+    return run_capabilities_cli(
+        argv,
+        repo=Path(__file__).resolve().parent,
+        canonical_prefix="/orders/api/v1",
+        defaults=DEFAULTS,
+        registry=GATE_REGISTRY,
+        is_axis=lambda k: k in axes,
+        axis_group=axis_group_rules(
+            exact={
+                "CHECKOUT_REQUIRES_ACCOUNT": "orders.checkout",
+                "PAYMENT": "orders.payment",
+            }
+        ),
+        prog="stapel-orders-capabilities",
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stapel_orders-0.1.0/_codegen.py

@@ -0,0 +1,120 @@
+"""stapel-orders contract-emission harness (contract-pipeline.md §2-3).
+
+Emits the module's own contract triad into ``docs/`` from a single-module
+``{orders + core}`` Django instance mounted at the canonical
+``orders/api/v1/`` prefix:
+
+  docs/schema.json   drf-spectacular OpenAPI, this module only, canonical prefix
+  docs/flows.json    generate_flow_docs machine artifact ([] — no @flow_step here)
+  docs/errors.json   generate_error_keys registry
+
+The *mechanism* is stapel_tools.codegen (shared, unchanged); this file is the
+thin per-module *config* that wires the module's settings + canonical mount.
+
+Usage:
+    python -m stapel_orders._codegen --out docs        # `make contract`
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+
+def _configure() -> None:
+    """Configure + boot the single-module Django instance for emission."""
+    repo_root = os.path.dirname(os.path.abspath(__file__))
+    sys.path[:] = [p for p in sys.path if os.path.abspath(p or os.getcwd()) != repo_root]
+
+    from django.conf import settings
+
+    if not settings.configured:
+        from stapel_orders._codegen_settings import settings_kwargs
+
+        settings.configure(
+            **settings_kwargs(root_urlconf="stapel_orders.codegen_urls", contract=True)
+        )
+
+    import django
+
+    django.setup()
+
+    from drf_spectacular.settings import spectacular_settings
+
+    from stapel_orders._codegen_settings import CODEGEN_SCHEMA_PATH_PREFIX
+
+    spectacular_settings.SCHEMA_PATH_PREFIX = CODEGEN_SCHEMA_PATH_PREFIX
+
+    # Stable enum component names (stapel-schema-lint SCH004).
+    from drf_spectacular.plumbing import _load_enum_name_overrides
+
+    from stapel_orders._codegen_settings import enum_name_overrides
+
+    spectacular_settings.ENUM_NAME_OVERRIDES = enum_name_overrides()
+    _load_enum_name_overrides.cache_clear()
+
+    # Register drf-spectacular's JWT cookie-auth extension explicitly (a real
+    # host triggers this as a side effect of wiring its Swagger URLs). Without
+    # it, the protected endpoints
+    # would emit without their `security: [{"JWTCookieAuth": []}]` entry — a
+    # real contract gap. Applied per stapel-calendar's precedent.
+    from stapel_core.django.openapi.swagger import _register_jwt_auth_extension
+
+    _register_jwt_auth_extension()
+
+
+def _require_python_312() -> None:
+    """Abort emission if not running the pinned 3.12 interpreter.
+
+    drf-spectacular's rendering of component descriptions (``Optional[X]`` vs
+    ``X | None``) depends on the Python minor version — contracts emitted on
+    anything other than 3.12 (the CI/monolith pin) produce false diffs.
+    """
+    if sys.version_info[:2] != (3, 12):
+        got = f"{sys.version_info.major}.{sys.version_info.minor}"
+        raise SystemExit(
+            f"stapel-orders contract emission ABORTED: running Python {got}, "
+            "but contracts must be emitted on Python 3.12 (the CI/monolith "
+            "pin). drf-spectacular renders component descriptions (Optional[X] "
+            "vs X | None) differently across Python minor versions, so emitting "
+            "on any other minor produces false diffs against the committed "
+            "docs/*.json. Re-run under a 3.12 interpreter."
+        )
+
+
+def main(argv: list[str] | None = None) -> int:
+    _require_python_312()
+
+    parser = argparse.ArgumentParser(
+        prog="stapel-orders-contract",
+        description="Emit this module's contract triad (schema.json + flows.json "
+        "+ errors.json) into --out, canonical /orders/api/v1/ prefix.",
+    )
+    parser.add_argument(
+        "--out",
+        default="docs",
+        help="Output directory for the triad (default: docs).",
+    )
+    args = parser.parse_args(argv)
+
+    _configure()
+
+    from stapel_tools.codegen import emit_errors, emit_flows, emit_schema
+
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    paths = emit_schema(out / "schema.json")
+    flows = emit_flows(out / "flows.json")
+    errors = emit_errors(out / "errors.json")
+
+    print(
+        f"stapel-orders contract: {paths} paths, {flows} flows, {errors} error keys "
+        f"→ {out}/",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stapel_orders-0.1.0/_codegen_settings.py

@@ -0,0 +1,104 @@
+"""Single-module Django settings shared by the test suite and contract emission.
+
+One copy, so the harness that emits ``docs/schema.json`` and the tests that
+prove it can never drift in INSTALLED_APPS or comm config. The production
+``REST_FRAMEWORK`` (exception handler, schema class) is used by both: the
+error envelope the tests assert is the one a host serves.
+"""
+from __future__ import annotations
+
+#: The resolver Function the test catalog provides (tests/catalog.py).
+TEST_RESOLVER = "orders_test.purchasables"
+
+
+def settings_kwargs(
+    *,
+    root_urlconf: str = "stapel_orders.tests.urls",
+    contract: bool = False,
+) -> dict:
+    rest_framework = {
+        "DEFAULT_RENDERER_CLASSES": ["rest_framework.renderers.JSONRenderer"],
+        "DEFAULT_SCHEMA_CLASS": "stapel_core.django.openapi.schemas.PermissionAwareAutoSchema",
+        "EXCEPTION_HANDLER": "stapel_core.django.api.errors.stapel_exception_handler",
+    }
+    if contract:
+        rest_framework.update({
+            "DEFAULT_AUTHENTICATION_CLASSES": [
+                "stapel_core.django.jwt.authentication.JWTCookieAuthentication",
+            ],
+            "DEFAULT_PERMISSION_CLASSES": [
+                "stapel_core.django.api.permissions.IsServiceRequest",
+                "stapel_core.django.api.permissions.IsSuperUser",
+            ],
+            "DEFAULT_RENDERER_CLASSES": [
+                "rest_framework.renderers.JSONRenderer",
+                "rest_framework.renderers.BrowsableAPIRenderer",
+            ],
+        })
+    return dict(
+        SECRET_KEY="test-secret-key-not-for-production",
+        INSTALLED_APPS=[
+            "django.contrib.contenttypes",
+            "django.contrib.auth",
+            "django.contrib.sessions",
+            "django.contrib.admin",
+            "django.contrib.messages",
+            "stapel_core.django.apps.CommonDjangoConfig",
+            "stapel_core.django.users",
+            "rest_framework",
+            "drf_spectacular",
+            "stapel_orders",
+        ],
+        AUTH_USER_MODEL="users.User",
+        DATABASES={"default": {"ENGINE": "django.db.backends.sqlite3", "NAME": ":memory:"}},
+        DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
+        USE_TZ=True,
+        ROOT_URLCONF=root_urlconf,
+        CACHES={"default": {"BACKEND": "django.core.cache.backends.locmem.LocMemCache"}},
+        STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
+        STAPEL_COMM={
+            "OUTBOX_ENABLED": False,
+            "ACTION_TRANSPORT": "inprocess",
+            "VALIDATE_SCHEMAS": True,
+        },
+        STAPEL_ORDERS={
+            "PURCHASABLE_TYPES": {"item": {"resolve": TEST_RESOLVER}},
+        },
+        TEMPLATES=[{
+            "BACKEND": "django.template.backends.django.DjangoTemplates",
+            "APP_DIRS": True,
+            "OPTIONS": {"context_processors": [
+                "django.template.context_processors.request",
+                "django.contrib.auth.context_processors.auth",
+                "django.contrib.messages.context_processors.messages",
+            ]},
+        }],
+        MIDDLEWARE=[
+            "django.contrib.sessions.middleware.SessionMiddleware",
+            "django.contrib.auth.middleware.AuthenticationMiddleware",
+            "django.contrib.messages.middleware.MessageMiddleware",
+        ],
+        MIGRATION_MODULES={"users": None},
+        REST_FRAMEWORK=rest_framework,
+    )
+
+
+#: Forced on drf-spectacular's singleton so a single-module instance derives
+#: the same operation ids as a multi-module aggregate.
+CODEGEN_SCHEMA_PATH_PREFIX = "/"
+
+
+def enum_name_overrides() -> dict:
+    """Stable enum component names (stapel-schema-lint SCH004).
+
+    ``OrderStatus`` is carried by ``OrderResponse.status`` and
+    ``OrderTransitionRequest.to``; naming both sets keeps the react pair's
+    generated types from being renamed by an unrelated edit. Called after
+    ``django.setup()``.
+    """
+    from stapel_orders.models import OrderStatus, PaymentStatus
+
+    return {
+        "OrderStatusEnum": OrderStatus,
+        "PaymentStatusEnum": PaymentStatus,
+    }