warp-commerce-types 1.0.0__tar.gz

warp_commerce_types-1.0.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: warp-commerce-types
+Version: 1.0.0
+Summary: Formal commerce types generated from the Warp Commerce Model — typed money, validated state transitions, and the six commerce invariants. The Python twin of @warp-lang/commerce-types.
+Author: Lamar Tech
+License: MIT
+Project-URL: Homepage, https://github.com/yasirlts/warp-lang
+Project-URL: Repository, https://github.com/yasirlts/warp-lang
+Keywords: commerce,ecommerce,types,warp,pydantic,state-machine,formal-methods
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+
+# warp-commerce-types
+
+**Formal commerce types for Python — the twin of [`@warp-lang/commerce-types`](../commerce-types).**
+
+Typed money, validated state transitions, and the six commerce invariants of the
+Warp Commerce Model — as Pydantic v2 models. Both this package and the TypeScript
+package are generated from / read the **same canonical schema**
+([`../../schema`](../../schema)), so the two languages agree *by construction*:
+
+- the data shapes come from `schema/structure/*.schema.json`;
+- the legal state-machine edges come from `schema/behavior/transitions.json`;
+- the invariant definitions come from `schema/behavior/invariants.json`.
+
+```bash
+pip install warp-commerce-types
+```
+
+> **Available on PyPI as of v1.0.0.** If you're building from a pre-release
+> checkout (before v1.0.0 is live on PyPI), the line above won't resolve yet —
+> install from source instead:
+>
+> ```bash
+> # from a checkout of the warp-lang repo:
+> pip install ./packages/commerce-types-py
+> # …or editable, with dev deps, for working on the package:
+> pip install -e "./packages/commerce-types-py[dev]"
+> ```
+
+## What you get
+
+```python
+from warp_commerce_types import (
+    Money, new_commitment, transition_commitment, audit_commerce, allocate,
+)
+
+# Currency-safe money. You cannot add MAD to EUR — and minor units are correct
+# per currency (TND is 3-decimal: 1.5 TND == 1500 millimes, not 150).
+from warp_commerce_types import add, convert
+add(Money(amount=100, currency="MAD"), Money(amount=50, currency="MAD"))
+# add(Money(amount=1, currency="MAD"), Money(amount=1, currency="EUR"))  -> CurrencyMismatchError
+
+# Exact splits that always reconcile (largest-remainder, minor-unit aware):
+allocate(Money(amount=100, currency="MAD"), [1, 1, 1])
+# -> 33.34 + 33.33 + 33.33 == 100.00 exactly
+
+# State machines validate every move against the canonical transition table.
+c = new_commitment("buyer", "seller")
+r = transition_commitment(c, {"type": "Proposed"}, actor="buyer")
+assert r.ok and r.value.state.type == "Proposed"
+bad = transition_commitment(c, {"type": "Fulfilled"}, actor="buyer")
+assert not bad.ok and "Invariant 2" in bad.error   # Draft -> Fulfilled is illegal
+
+# The six invariants, as runtime checkers that return actionable violations.
+violations = audit_commerce(commitments=[c], fulfillments=[], parties=[])
+```
+
+## The model
+
+Five primitives — **Party, Value, Intent, Commitment, Fulfillment** — plus the
+v0.3 commerce vocabulary (terms, auctions, resolution, metering, evidence, …),
+all generated as Pydantic models with discriminated unions keyed on `"type"` /
+`"kind"`.
+
+| Concern | Module |
+|---------|--------|
+| Currency-safe `Money`, minor-unit math, `allocate`, `MoneyBreakdown` | `warp_commerce_types.money` |
+| Primitive constructors (`new_commitment`, `party_id`, …) | `warp_commerce_types.primitives` |
+| `transition_*` / `is_valid_*_transition`, history synthesis | `warp_commerce_types.transitions` |
+| `check_i1..i6`, `audit_commerce`, `check_loyalty_liability` | `warp_commerce_types.invariants` |
+| Generated data models | `warp_commerce_types` (re-exported) |
+| Platform adapters | `warp_commerce_types.platforms.shopify`, `…stripe` |
+
+### The six invariants
+
+1. **Value Conservation** — value is transferred, not created; no mixed currencies
+   without explicit conversion. (Fourth clause: loyalty-point liability —
+   `check_loyalty_liability`.)
+2. **State Monotonicity** — only legal transitions; terminal states never reverse.
+3. **Capacity Verification** — a buyer must be verified (`can_buy`) before Accepted.
+4. **Temporal Integrity** — commitments form before fulfillments execute;
+   append-only history; timestamps never move backward.
+5. **Identity Permanence** — identifiers are globally unique, never reused.
+6. **Commitment Tree Consistency** — a parent's value equals the sum of its
+   children, within minor-unit tolerance (build exact children with `allocate`).
+
+### `MoneyBreakdown`
+
+A total decomposed into labelled components. Construction enforces the
+`money_breakdown_sum` rule from `schema/behavior/invariants.json`: components sum
+to the total (minor-unit tolerance), all share one currency, and discount
+components are negative.
+
+```python
+from warp_commerce_types import MoneyBreakdown
+MoneyBreakdown.model_validate({
+    "components": [
+        {"kind": "subtotal", "amount": {"amount": 90, "currency": "MAD"}},
+        {"kind": "discount", "amount": {"amount": -10, "currency": "MAD"}},
+        {"kind": "tax",      "amount": {"amount": 20, "currency": "MAD"}},
+    ],
+    "total": {"amount": 100, "currency": "MAD"},
+})  # ok — components sum to 100
+```
+
+## Regenerating from the schema
+
+The models and the bundled behavior data are generated. Edit the schema, never
+the generated `_models.py`:
+
+```bash
+python scripts/generate_from_schema.py   # reads ../../schema, writes src/.../_models.py
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest        # mirrors the TS bug-fix, transition, and invariant suites
+mypy          # configured in pyproject.toml
+python -m build
+```
+
+MIT licensed. Part of the [Warp](https://github.com/yasirlts/warp-lang) project.

warp_commerce_types-1.0.0/README.md

@@ -0,0 +1,123 @@
+# warp-commerce-types
+
+**Formal commerce types for Python — the twin of [`@warp-lang/commerce-types`](../commerce-types).**
+
+Typed money, validated state transitions, and the six commerce invariants of the
+Warp Commerce Model — as Pydantic v2 models. Both this package and the TypeScript
+package are generated from / read the **same canonical schema**
+([`../../schema`](../../schema)), so the two languages agree *by construction*:
+
+- the data shapes come from `schema/structure/*.schema.json`;
+- the legal state-machine edges come from `schema/behavior/transitions.json`;
+- the invariant definitions come from `schema/behavior/invariants.json`.
+
+```bash
+pip install warp-commerce-types
+```
+
+> **Available on PyPI as of v1.0.0.** If you're building from a pre-release
+> checkout (before v1.0.0 is live on PyPI), the line above won't resolve yet —
+> install from source instead:
+>
+> ```bash
+> # from a checkout of the warp-lang repo:
+> pip install ./packages/commerce-types-py
+> # …or editable, with dev deps, for working on the package:
+> pip install -e "./packages/commerce-types-py[dev]"
+> ```
+
+## What you get
+
+```python
+from warp_commerce_types import (
+    Money, new_commitment, transition_commitment, audit_commerce, allocate,
+)
+
+# Currency-safe money. You cannot add MAD to EUR — and minor units are correct
+# per currency (TND is 3-decimal: 1.5 TND == 1500 millimes, not 150).
+from warp_commerce_types import add, convert
+add(Money(amount=100, currency="MAD"), Money(amount=50, currency="MAD"))
+# add(Money(amount=1, currency="MAD"), Money(amount=1, currency="EUR"))  -> CurrencyMismatchError
+
+# Exact splits that always reconcile (largest-remainder, minor-unit aware):
+allocate(Money(amount=100, currency="MAD"), [1, 1, 1])
+# -> 33.34 + 33.33 + 33.33 == 100.00 exactly
+
+# State machines validate every move against the canonical transition table.
+c = new_commitment("buyer", "seller")
+r = transition_commitment(c, {"type": "Proposed"}, actor="buyer")
+assert r.ok and r.value.state.type == "Proposed"
+bad = transition_commitment(c, {"type": "Fulfilled"}, actor="buyer")
+assert not bad.ok and "Invariant 2" in bad.error   # Draft -> Fulfilled is illegal
+
+# The six invariants, as runtime checkers that return actionable violations.
+violations = audit_commerce(commitments=[c], fulfillments=[], parties=[])
+```
+
+## The model
+
+Five primitives — **Party, Value, Intent, Commitment, Fulfillment** — plus the
+v0.3 commerce vocabulary (terms, auctions, resolution, metering, evidence, …),
+all generated as Pydantic models with discriminated unions keyed on `"type"` /
+`"kind"`.
+
+| Concern | Module |
+|---------|--------|
+| Currency-safe `Money`, minor-unit math, `allocate`, `MoneyBreakdown` | `warp_commerce_types.money` |
+| Primitive constructors (`new_commitment`, `party_id`, …) | `warp_commerce_types.primitives` |
+| `transition_*` / `is_valid_*_transition`, history synthesis | `warp_commerce_types.transitions` |
+| `check_i1..i6`, `audit_commerce`, `check_loyalty_liability` | `warp_commerce_types.invariants` |
+| Generated data models | `warp_commerce_types` (re-exported) |
+| Platform adapters | `warp_commerce_types.platforms.shopify`, `…stripe` |
+
+### The six invariants
+
+1. **Value Conservation** — value is transferred, not created; no mixed currencies
+   without explicit conversion. (Fourth clause: loyalty-point liability —
+   `check_loyalty_liability`.)
+2. **State Monotonicity** — only legal transitions; terminal states never reverse.
+3. **Capacity Verification** — a buyer must be verified (`can_buy`) before Accepted.
+4. **Temporal Integrity** — commitments form before fulfillments execute;
+   append-only history; timestamps never move backward.
+5. **Identity Permanence** — identifiers are globally unique, never reused.
+6. **Commitment Tree Consistency** — a parent's value equals the sum of its
+   children, within minor-unit tolerance (build exact children with `allocate`).
+
+### `MoneyBreakdown`
+
+A total decomposed into labelled components. Construction enforces the
+`money_breakdown_sum` rule from `schema/behavior/invariants.json`: components sum
+to the total (minor-unit tolerance), all share one currency, and discount
+components are negative.
+
+```python
+from warp_commerce_types import MoneyBreakdown
+MoneyBreakdown.model_validate({
+    "components": [
+        {"kind": "subtotal", "amount": {"amount": 90, "currency": "MAD"}},
+        {"kind": "discount", "amount": {"amount": -10, "currency": "MAD"}},
+        {"kind": "tax",      "amount": {"amount": 20, "currency": "MAD"}},
+    ],
+    "total": {"amount": 100, "currency": "MAD"},
+})  # ok — components sum to 100
+```
+
+## Regenerating from the schema
+
+The models and the bundled behavior data are generated. Edit the schema, never
+the generated `_models.py`:
+
+```bash
+python scripts/generate_from_schema.py   # reads ../../schema, writes src/.../_models.py
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest        # mirrors the TS bug-fix, transition, and invariant suites
+mypy          # configured in pyproject.toml
+python -m build
+```
+
+MIT licensed. Part of the [Warp](https://github.com/yasirlts/warp-lang) project.

warp_commerce_types-1.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "warp-commerce-types"
+version = "1.0.0"
+description = "Formal commerce types generated from the Warp Commerce Model — typed money, validated state transitions, and the six commerce invariants. The Python twin of @warp-lang/commerce-types."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Lamar Tech" }]
+keywords = ["commerce", "ecommerce", "types", "warp", "pydantic", "state-machine", "formal-methods"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = ["pydantic>=2"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "mypy>=1.8", "build>=1.0"]
+
+[project.urls]
+Homepage = "https://github.com/yasirlts/warp-lang"
+Repository = "https://github.com/yasirlts/warp-lang"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+warp_commerce_types = ["py.typed", "schema_data/*.json", "schema_data/VERSION"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.9"
+plugins = ["pydantic.mypy"]
+packages = ["warp_commerce_types"]
+mypy_path = "src"
+ignore_missing_imports = true

warp_commerce_types-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

warp_commerce_types-1.0.0/src/warp_commerce_types/__init__.py

@@ -0,0 +1,92 @@
+"""warp-commerce-types — the Python twin of @warp-lang/commerce-types.
+
+Formal commerce types generated from the canonical Warp Commerce Model schema
+(schema/structure/*.schema.json) v1.0.0:
+- the five primitives (Party, Value, Intent, Commitment, Fulfillment),
+- currency-safe Money + minor-unit-aware money math and MoneyBreakdown,
+- validated state transitions (the 26-transition commitment table), read from
+  schema/behavior/transitions.json — the same data the TS binding reads,
+- runtime checkers for the six commerce invariants.
+
+Platform mappings (Shopify, Stripe) are available under
+``warp_commerce_types.platforms``.
+"""
+from __future__ import annotations
+
+# Generated data models (objects + discriminated unions) + SCHEMA_VERSION.
+from ._models import *  # noqa: F401,F403
+from ._models import SCHEMA_VERSION
+
+# Money math.
+from .money import (  # noqa: F401
+    CurrencyMismatchError,
+    ZERO_DECIMAL_CURRENCIES,
+    THREE_DECIMAL_CURRENCIES,
+    add,
+    allocate,
+    compare,
+    convert,
+    currency_decimals,
+    format_money,
+    minor_unit_factor,
+    money_epsilon,
+    money_equals,
+    subtract,
+    validate_money_breakdown,
+    zero,
+)
+
+# Primitive constructors.
+from .primitives import (  # noqa: F401
+    commitment_id,
+    fulfillment_id,
+    individual,
+    intent_id,
+    new_commitment,
+    new_fulfillment,
+    new_intent,
+    now,
+    organization,
+    party_id,
+    system,
+    unverified_capacity,
+    value_id,
+)
+
+# Transitions.
+from .transitions import (  # noqa: F401
+    CapacityError,
+    InvalidTransitionError,
+    Result,
+    apply_commitment_path,
+    apply_fulfillment_path,
+    is_valid_commitment_transition,
+    is_valid_fulfillment_transition,
+    is_valid_intent_transition,
+    transition_commitment,
+    transition_fulfillment,
+    transition_intent,
+)
+
+# Invariants.
+from .invariants import (  # noqa: F401
+    InvariantViolation,
+    LoyaltyLiabilityCheck,
+    audit_commerce,
+    audit_commerce_code,
+    check_i1_value_conservation,
+    check_i2_state_monotonicity,
+    check_i3_capacity_verification,
+    check_i4_temporal_integrity,
+    check_i5_identity_permanence,
+    check_i6_tree_consistency,
+    check_loyalty_liability,
+    verify_invariant1,
+    verify_invariant2,
+    verify_invariant3,
+    verify_invariant4,
+    verify_invariant5,
+    verify_invariant6,
+)
+
+__version__ = SCHEMA_VERSION

warp_commerce_types-1.0.0/src/warp_commerce_types/_data.py

@@ -0,0 +1,46 @@
+"""Runtime loaders for the canonical behavior data (transition tables and
+invariant definitions).
+
+Both the TypeScript and Python bindings read these same JSON files, so they
+agree by construction. In a source checkout we read the canonical files under
+``schema/behavior`` directly; an installed wheel reads the build-time mirror
+bundled at ``warp_commerce_types/schema_data`` (synced from the canonical files
+by ``scripts/generate_from_schema.py``).
+"""
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict
+
+_PKG_DIR = Path(__file__).resolve().parent
+_BUNDLED = _PKG_DIR / "schema_data"
+# In a source checkout: .../warp-lang/packages/commerce-types-py/src/warp_commerce_types
+# parents[3] is the repo root that holds the canonical schema/ directory.
+_CANONICAL = _PKG_DIR.parents[3] / "schema" / "behavior"
+
+
+def _read(name: str) -> Dict[str, Any]:
+    canonical = _CANONICAL / name
+    if canonical.is_file():
+        return json.loads(canonical.read_text())
+    bundled = _BUNDLED / name
+    if bundled.is_file():
+        return json.loads(bundled.read_text())
+    raise FileNotFoundError(
+        "behavior file %r not found (looked in %s and %s); "
+        "run scripts/generate_from_schema.py" % (name, _CANONICAL, _BUNDLED)
+    )
+
+
+@lru_cache(maxsize=None)
+def transitions() -> Dict[str, Any]:
+    """The legal-transition tables (schema/behavior/transitions.json)."""
+    return _read("transitions.json")
+
+
+@lru_cache(maxsize=None)
+def invariants() -> Dict[str, Any]:
+    """The invariant definitions + money_breakdown_sum / loyalty rules."""
+    return _read("invariants.json")