trustrender 0.3.0__tar.gz → 0.3.1__tar.gz

{trustrender-0.3.0/src/trustrender.egg-info → trustrender-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trustrender
-Version: 0.3.0
+Version: 0.3.1
 Summary: Validate and normalize Stripe, Shopify, and custom billing data for Factur-X/ZUGFeRD
 License-Expression: MIT
 Project-URL: Homepage, https://trustrender.dev
@@ -141,6 +141,23 @@ else:
 - `normalizations`: field-level provenance (what was renamed, coerced, computed)
 - `zugferd_ready`: bool (if `zugferd=True`)
 
+## Stripe adapter
+
+Raw Stripe Invoice API responses use cents, Unix timestamps, and nested structures. The adapter handles all of it:
+
+```bash
+trustrender validate stripe_invoice.json --source stripe --zugferd
+```
+
+```python
+from trustrender import validate_invoice
+from trustrender.adapters import from_stripe
+
+result = validate_invoice(from_stripe(raw_stripe_response), zugferd=True)
+```
+
+The adapter converts cents to dollars, timestamps to dates, extracts line items from `lines.data[]`, and maps customer fields to recipient. Seller info is not included in Stripe invoices — TrustRender will flag it if required for ZUGFeRD compliance.
+
 ## What it normalizes
 
 90+ vendor field aliases across QuickBooks, Xero, Stripe, and generic CSV/ERP formats:

{trustrender-0.3.0 → trustrender-0.3.1}/README.md

@@ -99,6 +99,23 @@ else:
 - `normalizations`: field-level provenance (what was renamed, coerced, computed)
 - `zugferd_ready`: bool (if `zugferd=True`)
 
+## Stripe adapter
+
+Raw Stripe Invoice API responses use cents, Unix timestamps, and nested structures. The adapter handles all of it:
+
+```bash
+trustrender validate stripe_invoice.json --source stripe --zugferd
+```
+
+```python
+from trustrender import validate_invoice
+from trustrender.adapters import from_stripe
+
+result = validate_invoice(from_stripe(raw_stripe_response), zugferd=True)
+```
+
+The adapter converts cents to dollars, timestamps to dates, extracts line items from `lines.data[]`, and maps customer fields to recipient. Seller info is not included in Stripe invoices — TrustRender will flag it if required for ZUGFeRD compliance.
+
 ## What it normalizes
 
 90+ vendor field aliases across QuickBooks, Xero, Stripe, and generic CSV/ERP formats:

{trustrender-0.3.0 → trustrender-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trustrender"
-version = "0.3.0"
+version = "0.3.1"
 description = "Validate and normalize Stripe, Shopify, and custom billing data for Factur-X/ZUGFeRD"
 license = "MIT"
 classifiers = [

{trustrender-0.3.0 → trustrender-0.3.1}/src/trustrender/__init__.py

@@ -36,7 +36,7 @@ class RenderResult:
     trace_id: str | None = None
 
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 __all__ = [
     # Core API (always available)

trustrender-0.3.1/src/trustrender/adapters/__init__.py

@@ -0,0 +1,14 @@
+"""Source adapters for common billing platforms.
+
+Convert raw API responses into the dict shape that
+ingest_invoice() and validate_invoice() already understand.
+
+Adapters are pure functions. No network, no filesystem,
+no side effects. They do minimal structural transformation
+and leave missing data missing — the validation pipeline
+catches what's wrong.
+"""
+
+from .stripe import from_stripe
+
+__all__ = ["from_stripe"]

trustrender-0.3.1/src/trustrender/adapters/stripe.py

@@ -0,0 +1,163 @@
+"""Stripe Invoice adapter.
+
+Converts a raw Stripe Invoice API response (GET /v1/invoices/:id)
+into a dict that ingest_invoice() can normalize and validate.
+
+Key transformations:
+  - Amounts: cents (int) → dollars (float), divide by 100
+  - Dates: Unix timestamps (int) → YYYY-MM-DD strings
+  - Line items: extract from lines.data[], pull unit_amount from nested price object
+  - Customer: Stripe's customer is the buyer → maps to recipient
+  - Currency: lowercased in Stripe → uppercased for canonical
+  - Seller: NOT included in Stripe invoice objects. Adapter leaves sender empty.
+    The validation pipeline will flag missing sender data — this is correct behavior,
+    not a bug. Users must supply seller identity separately.
+
+Usage::
+
+    from trustrender import validate_invoice
+    from trustrender.adapters import from_stripe
+
+    result = validate_invoice(from_stripe(raw_stripe_response))
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+
+def from_stripe(raw: dict) -> dict:
+    """Convert raw Stripe Invoice API response to ingest-ready dict.
+
+    Args:
+        raw: The full JSON response from GET /v1/invoices/:id.
+             Amounts must be in cents (Stripe's native format).
+
+    Returns:
+        A dict ready for ingest_invoice(). Not yet canonical,
+        not yet validated — just structurally bridged.
+
+    Raises:
+        ValueError: If raw is not a dict.
+    """
+    if not isinstance(raw, dict):
+        raise ValueError(f"from_stripe expects a dict, got {type(raw).__name__}")
+
+    out: dict = {}
+
+    # ── Invoice identity ─────────────────────────────────────────
+
+    if "number" in raw:
+        out["invoice_number"] = raw["number"]
+
+    if "created" in raw and isinstance(raw["created"], (int, float)):
+        out["invoice_date"] = _unix_to_date(raw["created"])
+
+    if "due_date" in raw and isinstance(raw["due_date"], (int, float)):
+        out["due_date"] = _unix_to_date(raw["due_date"])
+
+    if "currency" in raw:
+        out["currency"] = raw["currency"].upper()
+
+    # ── Amounts (cents → dollars) ────────────────────────────────
+
+    if "subtotal" in raw and isinstance(raw["subtotal"], (int, float)):
+        out["subtotal"] = raw["subtotal"] / 100
+
+    if "tax" in raw and isinstance(raw["tax"], (int, float)):
+        out["tax_amount"] = raw["tax"] / 100
+
+    if "total" in raw and isinstance(raw["total"], (int, float)):
+        out["total"] = raw["total"] / 100
+
+    # ── Customer → recipient ─────────────────────────────────────
+    # Stripe's "customer" is the buyer. Maps to recipient, not sender.
+
+    recipient: dict = {}
+
+    if raw.get("customer_name"):
+        recipient["name"] = raw["customer_name"]
+    if raw.get("customer_email"):
+        recipient["email"] = raw["customer_email"]
+    if isinstance(raw.get("customer_address"), dict):
+        recipient["address"] = _flatten_address(raw["customer_address"])
+
+    # Expanded customer object (if customer was expanded in the API call)
+    if isinstance(raw.get("customer"), dict):
+        cust = raw["customer"]
+        if not recipient.get("name") and cust.get("name"):
+            recipient["name"] = cust["name"]
+        if not recipient.get("email") and cust.get("email"):
+            recipient["email"] = cust["email"]
+
+    if recipient:
+        out["recipient"] = recipient
+
+    # Sender is NOT available in Stripe invoice objects.
+    # The validation pipeline will flag this as blocked if sender.name is required.
+    # This is intentional — users must supply seller identity separately.
+
+    # ── Line items ───────────────────────────────────────────────
+
+    lines_obj = raw.get("lines")
+    if isinstance(lines_obj, dict) and isinstance(lines_obj.get("data"), list):
+        items = []
+        for line in lines_obj["data"]:
+            if not isinstance(line, dict):
+                continue
+            item: dict = {}
+
+            if "description" in line:
+                item["description"] = line["description"]
+            if "quantity" in line and line["quantity"] is not None:
+                item["quantity"] = line["quantity"]
+
+            # unit_amount lives on the nested price object
+            price_obj = line.get("price")
+            if isinstance(price_obj, dict):
+                ua = price_obj.get("unit_amount")
+                if isinstance(ua, (int, float)):
+                    item["unit_price"] = ua / 100
+
+            # line-level amount (cents → dollars)
+            if "amount" in line and isinstance(line["amount"], (int, float)):
+                item["line_total"] = line["amount"] / 100
+
+            if item:
+                items.append(item)
+
+        if items:
+            out["items"] = items
+
+    # ── Metadata passthrough ─────────────────────────────────────
+
+    if isinstance(raw.get("metadata"), dict) and raw["metadata"]:
+        out["_metadata"] = raw["metadata"]
+
+    return out
+
+
+def _unix_to_date(ts: int | float) -> str:
+    """Convert Unix timestamp to YYYY-MM-DD string."""
+    return datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%d")
+
+
+def _flatten_address(addr: dict) -> str:
+    """Flatten Stripe address object into a single string."""
+    parts = []
+    if addr.get("line1"):
+        parts.append(addr["line1"])
+    if addr.get("line2"):
+        parts.append(addr["line2"])
+    city_state = []
+    if addr.get("city"):
+        city_state.append(addr["city"])
+    if addr.get("state"):
+        city_state.append(addr["state"])
+    if addr.get("postal_code"):
+        city_state.append(addr["postal_code"])
+    if city_state:
+        parts.append(", ".join(city_state))
+    if addr.get("country"):
+        parts.append(addr["country"])
+    return ", ".join(parts)

{trustrender-0.3.0 → trustrender-0.3.1}/src/trustrender/cli.py

@@ -62,6 +62,7 @@ def main(argv: list[str] | None = None) -> int:
     # ── Core: validation (no render deps required) ──
     validate_cmd = sub.add_parser("validate", help="Validate invoice data before Factur-X/ZUGFeRD embedding")
     validate_cmd.add_argument("data", help="Path to JSON invoice data (use '-' for stdin)")
+    validate_cmd.add_argument("--source", choices=["stripe"], help="Apply source adapter before validation (e.g. --source stripe)")
     validate_cmd.add_argument("--zugferd", action="store_true", help="Run ZUGFeRD EN 16931 readiness checks")
     validate_cmd.add_argument("--format", choices=["text", "json"], default="text", dest="output_format", help="Output format (default: text)")
 
@@ -302,6 +303,12 @@ def _run_validate(args: argparse.Namespace) -> int:
         print(f"error: file not found: {args.data}", file=sys.stderr)
         return 1
 
+    # Apply source adapter if specified
+    if getattr(args, "source", None):
+        if args.source == "stripe":
+            from .adapters.stripe import from_stripe
+            raw = from_stripe(raw)
+
     result = validate_invoice(raw, zugferd=args.zugferd)
 
     if args.output_format == "json":

{trustrender-0.3.0 → trustrender-0.3.1/src/trustrender.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trustrender
-Version: 0.3.0
+Version: 0.3.1
 Summary: Validate and normalize Stripe, Shopify, and custom billing data for Factur-X/ZUGFeRD
 License-Expression: MIT
 Project-URL: Homepage, https://trustrender.dev
@@ -141,6 +141,23 @@ else:
 - `normalizations`: field-level provenance (what was renamed, coerced, computed)
 - `zugferd_ready`: bool (if `zugferd=True`)
 
+## Stripe adapter
+
+Raw Stripe Invoice API responses use cents, Unix timestamps, and nested structures. The adapter handles all of it:
+
+```bash
+trustrender validate stripe_invoice.json --source stripe --zugferd
+```
+
+```python
+from trustrender import validate_invoice
+from trustrender.adapters import from_stripe
+
+result = validate_invoice(from_stripe(raw_stripe_response), zugferd=True)
+```
+
+The adapter converts cents to dollars, timestamps to dates, extracts line items from `lines.data[]`, and maps customer fields to recipient. Seller info is not included in Stripe invoices — TrustRender will flag it if required for ZUGFeRD compliance.
+
 ## What it normalizes
 
 90+ vendor field aliases across QuickBooks, Xero, Stripe, and generic CSV/ERP formats:

{trustrender-0.3.0 → trustrender-0.3.1}/src/trustrender.egg-info/SOURCES.txt

@@ -27,6 +27,8 @@ src/trustrender.egg-info/dependency_links.txt
 src/trustrender.egg-info/entry_points.txt
 src/trustrender.egg-info/requires.txt
 src/trustrender.egg-info/top_level.txt
+src/trustrender/adapters/__init__.py
+src/trustrender/adapters/stripe.py
 src/trustrender/builtin_templates/einvoice.j2.typ
 src/trustrender/builtin_templates/einvoice_data.json
 src/trustrender/builtin_templates/invoice.j2.typ
@@ -50,6 +52,7 @@ src/trustrender/playground/index.html
 src/trustrender/playground/assets/index-Bsf6YnD1.css
 src/trustrender/playground/assets/index-C6K0JsLw.js
 src/trustrender/playground/assets/pdf.worker-C1breYqn.mjs
+tests/test_adapters.py
 tests/test_adversarial_corpus.py
 tests/test_audit_e2e.py
 tests/test_cli.py

trustrender-0.3.1/tests/test_adapters.py

@@ -0,0 +1,170 @@
+"""Tests for source adapters (Stripe first)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from trustrender.adapters.stripe import from_stripe
+from trustrender import validate_invoice
+
+FIXTURES = Path(__file__).parent / "fixtures" / "adapters"
+
+
+# ── from_stripe: structural transformation ───────────────────────────
+
+class TestStripeAdapter:
+
+    def test_invoice_number(self):
+        result = from_stripe({"number": "INV-001"})
+        assert result["invoice_number"] == "INV-001"
+
+    def test_amounts_cents_to_dollars(self):
+        result = from_stripe({"subtotal": 10000, "tax": 850, "total": 10850})
+        assert result["subtotal"] == 100.00
+        assert result["tax_amount"] == 8.50
+        assert result["total"] == 108.50
+
+    def test_unix_timestamps_to_dates(self):
+        result = from_stripe({"created": 1775779200, "due_date": 1778371200})
+        assert result["invoice_date"] == "2026-04-10"
+        assert result["due_date"] == "2026-05-10"
+
+    def test_currency_uppercased(self):
+        result = from_stripe({"currency": "usd"})
+        assert result["currency"] == "USD"
+
+    def test_customer_name_and_email(self):
+        result = from_stripe({
+            "customer_name": "Acme Corp",
+            "customer_email": "billing@acme.com",
+        })
+        assert result["recipient"]["name"] == "Acme Corp"
+        assert result["recipient"]["email"] == "billing@acme.com"
+
+    def test_customer_address_flattened(self):
+        result = from_stripe({
+            "customer_address": {
+                "line1": "123 Main St",
+                "city": "Chicago",
+                "state": "IL",
+                "postal_code": "60601",
+                "country": "US",
+            },
+        })
+        addr = result["recipient"]["address"]
+        assert "123 Main St" in addr
+        assert "Chicago" in addr
+        assert "IL" in addr
+
+    def test_expanded_customer_object(self):
+        result = from_stripe({
+            "customer": {
+                "name": "Expanded Corp",
+                "email": "expanded@corp.com",
+            },
+        })
+        assert result["recipient"]["name"] == "Expanded Corp"
+        assert result["recipient"]["email"] == "expanded@corp.com"
+
+    def test_line_items_extracted(self):
+        result = from_stripe({
+            "lines": {
+                "data": [
+                    {
+                        "description": "Widget",
+                        "quantity": 2,
+                        "amount": 5000,
+                        "price": {"unit_amount": 2500},
+                    },
+                ],
+            },
+        })
+        assert len(result["items"]) == 1
+        item = result["items"][0]
+        assert item["description"] == "Widget"
+        assert item["quantity"] == 2
+        assert item["unit_price"] == 25.00
+        assert item["line_total"] == 50.00
+
+    def test_no_sender_in_output(self):
+        """Stripe invoices don't include seller info. Adapter must not invent it."""
+        result = from_stripe({"number": "INV-001", "customer_name": "Buyer"})
+        assert "sender" not in result
+
+    def test_missing_fields_left_missing(self):
+        """Adapter does not guess. Missing data stays missing."""
+        result = from_stripe({})
+        assert "invoice_number" not in result
+        assert "subtotal" not in result
+        assert "items" not in result
+
+    def test_metadata_passthrough(self):
+        result = from_stripe({"metadata": {"po_number": "PO-123"}})
+        assert result["_metadata"]["po_number"] == "PO-123"
+
+    def test_rejects_non_dict(self):
+        with pytest.raises(ValueError):
+            from_stripe("not a dict")
+        with pytest.raises(ValueError):
+            from_stripe([1, 2, 3])
+
+
+# ── Full fixture: end-to-end ─────────────────────────────────────────
+
+class TestStripeEndToEnd:
+
+    def test_full_fixture_validates(self):
+        """Full Stripe invoice fixture → adapter → validate → pass (except missing sender)."""
+        raw = json.loads((FIXTURES / "stripe_invoice.json").read_text())
+        adapted = from_stripe(raw)
+        result = validate_invoice(adapted)
+
+        # Should block on missing sender (Stripe doesn't include seller)
+        assert result["status"] == "blocked"
+        blocked_rules = {e["rule_id"] for e in result["errors"] if e.get("severity") == "blocked"}
+        assert "identity.sender_name" in blocked_rules
+
+        # But everything else should be correct
+        canonical = result["canonical"]
+        assert canonical["invoice_number"] == "INV-2026-0042"
+        assert canonical["recipient"]["name"] == "Momentum Ventures LLC"
+        assert canonical["total"] == pytest.approx(643.40)
+        assert canonical["currency"] == "USD"
+        assert len(canonical["items"]) == 3
+
+    def test_full_fixture_with_sender_passes(self):
+        """Add sender to Stripe output → should pass validation."""
+        raw = json.loads((FIXTURES / "stripe_invoice.json").read_text())
+        adapted = from_stripe(raw)
+        adapted["sender"] = {"name": "Buildspace Labs Inc.", "email": "billing@buildspace.so"}
+        result = validate_invoice(adapted)
+        assert result["render_ready"] is True
+
+    def test_incomplete_fixture_blocks(self):
+        """Stripe invoice missing customer + number → blocks on multiple rules."""
+        raw = json.loads((FIXTURES / "stripe_incomplete.json").read_text())
+        adapted = from_stripe(raw)
+        result = validate_invoice(adapted)
+        assert result["status"] == "blocked"
+        blocked_rules = {e["rule_id"] for e in result["errors"] if e.get("severity") == "blocked"}
+        assert "identity.sender_name" in blocked_rules
+        assert "identity.recipient_name" in blocked_rules
+        assert "identity.invoice_number" in blocked_rules
+
+    def test_amounts_are_dollars_not_cents(self):
+        """Verify cents→dollars conversion happened correctly."""
+        raw = json.loads((FIXTURES / "stripe_invoice.json").read_text())
+        adapted = from_stripe(raw)
+
+        # Raw Stripe: subtotal=59300 (cents) → adapted should be 593.00
+        assert adapted["subtotal"] == 593.00
+        assert adapted["tax_amount"] == 50.40
+        assert adapted["total"] == 643.40
+
+        # Line items also converted
+        assert adapted["items"][0]["line_total"] == 399.00
+        assert adapted["items"][0]["unit_price"] == 399.00
+        assert adapted["items"][1]["line_total"] == 45.00