docs: drop "mirror of node-commerce" framing; describe modules standalone

vvillait88 · claude · vvillait88 · commit ae8f344e3ba5 · 2026-04-27T03:06:22.000-07:00
python-commerce stands on its own as the Python flavor of the agent commerce SDK; it doesn't need to be sold as a derivative of the Node version. Scrubbed "mirror of @agent-score/commerce" / "Mirror of node-commerce's X" / "Mirrors :func:..." across CLAUDE.md, README, examples README, identity adapters, payment helpers, signer extraction, denial helpers, address normalization, and tests. Replaced with neutral standalone descriptions; kept implementation invariants (cross-language API parity, must produce identical normalization output) intact.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,6 +1,6 @@
 # agentscore-commerce
 
-Agent commerce SDK for Python. The full merchant-side toolkit: identity gating + payment helpers + 402 builders + discovery + Stripe multichain. One install, submodule imports per concern. Mirror of `@agent-score/commerce` (Node.js) — same surface area, idiomatic Python.
+Agent commerce SDK for Python. The full merchant-side toolkit: identity gating + payment helpers + 402 builders + discovery + Stripe multichain. One install, submodule imports per concern.
 
 ## Submodules
 
@@ -27,7 +27,7 @@ Single Python package, hatchling-built, published to PyPI as `agentscore-commerc
 | `agentscore_commerce/api/` | `AgentScore` re-export |
 | `tests/` | pytest, one file per surface |
 
-Mirror of node-commerce's structure — every helper lifted from the node version's working production code.
+Every helper lifts from working production code (`agentscore/martin-estate`) — extract from real consumers, not speculation.
 
 ## Identity model
 
@@ -71,7 +71,7 @@ uv run pytest tests/
 - **Never commit .env files or secrets**
 - **Use PRs** — never push directly to main
 - **Helpers are protocol translations + configurable opinions, not opinionated frameworks**
-- **Mirror node-commerce** — keep the surface area identical so vendors switching languages have the same mental model
+- **Cross-language API parity** — keep the surface area identical between the node and python flavors so vendors switching languages have the same mental model
 
 ## Releasing
 
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 [![PyPI version](https://img.shields.io/pypi/v/agentscore-commerce.svg)](https://pypi.org/project/agentscore-commerce/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-The full merchant-side SDK for [AgentScore](https://agentscore.sh) in Python — agent commerce in one install. Identity middleware (FastAPI, Flask, Django, AIOHTTP, Sanic, ASGI), payment helpers, 402 challenge builders, MPP discovery, and Stripe multichain support. Mirror of [`@agent-score/commerce`](https://github.com/agentscore/node-commerce) — same surface, idiomatic Python.
+The full merchant-side SDK for [AgentScore](https://agentscore.sh) in Python — agent commerce in one install. Identity middleware (FastAPI, Flask, Django, AIOHTTP, Sanic, ASGI), payment helpers, 402 challenge builders, MPP discovery, and Stripe multichain support.
 
 ## Install
 
diff --git a/agentscore_commerce/identity/_denial.py b/agentscore_commerce/identity/_denial.py
@@ -1,4 +1,4 @@
-"""Universal denial helpers shared across every adapter — Python mirror of node-commerce/src/_denial.ts.
+"""Universal denial helpers shared across every adapter.
 
 What lives here:
     FIXABLE_DENIAL_REASONS / is_fixable_denial — classifier for compliance reasons that can
diff --git a/agentscore_commerce/identity/address.py b/agentscore_commerce/identity/address.py
@@ -4,8 +4,8 @@
 so DB lookups against `address_lower`-style columns work. Solana addresses are base58 and
 case-sensitive — we MUST preserve the input verbatim, never lowercase.
 
-Mirrors `core/api/src/lib/address.ts` and `node-commerce/src/identity/address.ts` so all three layers
-normalize identically. Drift here silently breaks captured-wallet resolution and signer-match.
+Must produce identical output to the API and node SDK normalizers. Drift here
+silently breaks captured-wallet resolution and signer-match.
 """
 
 from __future__ import annotations
diff --git a/agentscore_commerce/identity/aiohttp.py b/agentscore_commerce/identity/aiohttp.py
@@ -68,7 +68,7 @@ def get_assess_data(request: web.Request) -> dict[str, Any] | None:
     """Return the `/v1/assess` response the middleware stashed on the aiohttp request dict.
 
     Returns ``None`` when identity was missing or the gate short-circuited with a
-    denial. Mirrors :func:`agentscore_commerce.identity.fastapi.get_assess_data`.
+    denial.
     """
     return request.get(ASSESS_STATE_KEY)
 
diff --git a/agentscore_commerce/identity/django.py b/agentscore_commerce/identity/django.py
@@ -64,7 +64,7 @@ def get_assess_data(request: HttpRequest) -> dict[str, Any] | None:
     """Return the `/v1/assess` response the middleware stashed on the request.
 
     Returns ``None`` when identity was missing or the gate short-circuited with a
-    denial. Mirrors :func:`agentscore_commerce.identity.fastapi.get_assess_data`.
+    denial.
     """
     return getattr(request, ASSESS_STATE_KEY, None)
 
diff --git a/agentscore_commerce/identity/flask.py b/agentscore_commerce/identity/flask.py
@@ -67,7 +67,7 @@ def get_assess_data() -> dict[str, Any] | None:
     """Return the `/v1/assess` response the gate stashed on Flask's request-scoped ``g``.
 
     Returns ``None`` outside a gated request, when identity was missing, or when the gate
-    short-circuited with a denial. Mirrors :func:`agentscore_commerce.identity.fastapi.get_assess_data`.
+    short-circuited with a denial.
     """
     from flask import g
 
diff --git a/agentscore_commerce/identity/middleware.py b/agentscore_commerce/identity/middleware.py
@@ -71,7 +71,7 @@ def get_assess_data(request: Request) -> dict[str, Any] | None:
     """Return the `/v1/assess` response the middleware stashed on the request scope.
 
     Returns ``None`` when identity was missing or the gate short-circuited with a
-    denial. Mirrors :func:`agentscore_commerce.identity.fastapi.get_assess_data`.
+    denial.
     """
     state = request.scope.get("state") or {}
     return state.get(ASSESS_STATE_KEY)
diff --git a/agentscore_commerce/identity/sanic.py b/agentscore_commerce/identity/sanic.py
@@ -68,7 +68,7 @@ def get_assess_data(request: Request) -> dict[str, Any] | None:
     """Return the `/v1/assess` response the middleware stashed on ``request.ctx``.
 
     Returns ``None`` when identity was missing or the gate short-circuited with a
-    denial. Mirrors :func:`agentscore_commerce.identity.fastapi.get_assess_data`.
+    denial.
     """
     return getattr(request.ctx, ASSESS_STATE_ATTR, None)
 
diff --git a/agentscore_commerce/payment/mppx_server.py b/agentscore_commerce/payment/mppx_server.py
@@ -1,9 +1,8 @@
 """One-call MPP server setup wrapping the official `pympp` Python package.
 
-Mirror of node-commerce's `createMppxServer` factory. Wires Tempo charge,
-Tempo session (channel-based for variable-cost / streaming), and Stripe SPT
-methods from symbolic rail config — replaces the boilerplate of constructing
-each method by hand.
+Wires Tempo charge, Tempo session (channel-based for variable-cost /
+streaming), and Stripe SPT methods from symbolic rail config — replaces
+the boilerplate of constructing each method by hand.
 
 Usage::
 
@@ -115,8 +114,8 @@ async def create_mppx_server(
     Returns a configured ``Mppx`` server instance. Raises ``ImportError`` with a
     guiding install command when ``pympp`` (or a per-rail extra) is missing.
 
-    Mirror of node-commerce's ``createMppxServer``. Async because Stripe SPT method
-    construction may require an HTTP setup call to the Stripe API.
+    Async because Stripe SPT method construction may require an HTTP setup call
+    to the Stripe API.
     """
     pympp = _import_optional("pympp.server")
     if pympp is None or not hasattr(pympp, "Mppx"):
diff --git a/agentscore_commerce/payment/signer.py b/agentscore_commerce/payment/signer.py
@@ -1,10 +1,9 @@
 """Network-aware signer extraction from x402 (EVM EIP-3009) credentials.
 
-Mirror of node-commerce's `extract_payment_signer` shape — returns `{address, network}` so
-vendors can pass the network into `capture_wallet(...)` without inferring it themselves.
-For Tempo MPP and Solana SPL Token signers, callers must extract the signer themselves
-(no pip-installable equivalent of `mppx` / `@x402/svm` today) and pass it directly to
-`verify_wallet_signer_match` via the `signer=` argument.
+Returns `{address, network}` so vendors can pass the network into `capture_wallet(...)`
+without inferring it themselves. For Tempo MPP and Solana SPL Token signers, callers must
+extract the signer themselves (no pip-installable equivalent of `mppx` / `@x402/svm` today)
+and pass it directly to `verify_wallet_signer_match` via the `signer=` argument.
 """
 
 from __future__ import annotations
@@ -73,8 +72,8 @@ def extract_payment_signer(x402_payment_header: str | None) -> PaymentSigner | N
 def extract_payment_signer_address(x402_payment_header: str | None) -> str | None:
     """Address-only convenience over :func:`extract_payment_signer`.
 
-    Mirrors node-commerce's ``extractPaymentSignerAddress`` — used by gate adapters
-    where only the address matters for operator-equivalence comparison.
+    Used by gate adapters where only the address matters for operator-equivalence
+    comparison.
     """
     result = extract_payment_signer(x402_payment_header)
     return result.address if result else None
@@ -84,9 +83,8 @@ def read_x402_payment_header(headers: Mapping[str, str]) -> str | None:
     """Read the x402 payment header from a request headers mapping (case-insensitive).
 
     Tries ``payment-signature`` first, then ``x-payment`` — both names appear in the wild
-    as the binary-friendly transport name evolved. Mirrors node-commerce's
-    ``readX402PaymentHeader``; takes a mapping rather than a framework Request so the
-    same helper works across FastAPI / Flask / Django / aiohttp / Sanic / ASGI.
+    as the binary-friendly transport name evolved. Takes a mapping rather than a framework
+    Request so the same helper works across FastAPI / Flask / Django / aiohttp / Sanic / ASGI.
     """
     lower = {k.lower(): v for k, v in headers.items()}
     return lower.get("payment-signature") or lower.get("x-payment")
diff --git a/agentscore_commerce/payment/x402_server.py b/agentscore_commerce/payment/x402_server.py
@@ -1,8 +1,7 @@
 """One-call x402 server setup wrapping the official `x402` Python package.
 
-Mirror of node-commerce's `createX402Server` factory. Resolves the facilitator,
-constructs the server, registers schemes per network with v1+v2 dual-register,
-and optionally adds the Bazaar discovery extension.
+Resolves the facilitator, constructs the server, registers schemes per network
+with v1+v2 dual-register, and optionally adds the Bazaar discovery extension.
 
 Replaces ~15 lines of boilerplate with a single config call::
 
@@ -53,10 +52,7 @@ class CustomScheme:
 
 @dataclass
 class CreateX402ServerOptions:
-    """Configuration for :func:`create_x402_server`.
-
-    Mirrors the node ``CreateX402ServerOptions`` shape.
-    """
+    """Configuration for :func:`create_x402_server`."""
 
     facilitator: X402FacilitatorChoice | Any = "http"
     """Facilitator selection — ``"coinbase"`` (requires ``coinbase-x402``), ``"http"``
@@ -97,8 +93,8 @@ async def create_x402_server(
     Returns a configured ``x402ResourceServer`` instance. Raises ``ImportError``
     with a guiding install command when a required peer dep is missing.
 
-    Mirror of node-commerce's ``createX402Server``. Async because the underlying
-    ``initialize()`` call is async (talks to the facilitator).
+    Async because the underlying ``initialize()`` call is async (talks to the
+    facilitator).
     """
     rails_list = list(rails or [])
     schemes_list = list(schemes or [])
diff --git a/agentscore_commerce/stripe_multichain/mppx_stripe.py b/agentscore_commerce/stripe_multichain/mppx_stripe.py
@@ -1,8 +1,7 @@
 """Stripe SPT method wrapper for ``pympp`` server merchants.
 
-Mirror of node-commerce's ``createMppxStripe``. Wraps the ``pympp.stripe.charge(...)``
-boilerplate so vendors only declare config, not method instantiation. Returns the
-value vendors pass into ``Mppx.create(methods=[...])``.
+Wraps the ``pympp.stripe.charge(...)`` boilerplate so vendors only declare config,
+not method instantiation. Returns the value vendors pass into ``Mppx.create(methods=[...])``.
 
 Example::
 
diff --git a/examples/README.md b/examples/README.md
@@ -2,8 +2,6 @@
 
 Runnable, copy-pasteable example integrations covering the most common merchant scenarios. Each is a single-file FastAPI app you can adapt by swapping the relevant config.
 
-These mirror the Node.js examples in `agentscore/node-commerce/examples/`; the integration shape is identical, the language and idioms are different.
-
 | Example | Scenario | What it shows |
 |---|---|---|
 | [`identity_only.py`](./identity_only.py) | Compliance gate without payment | Minimal — wraps any endpoint with KYC + age + jurisdiction checks. Vendor handles their own payment. |
diff --git a/tests/test_address.py b/tests/test_address.py
@@ -1,5 +1,5 @@
-"""Address normalization tests — must mirror node-commerce's tests/address.test.ts so EVM
-and Solana addresses are normalized identically across both SDK languages."""
+"""Address normalization tests — must produce identical results to the node SDK
+so EVM and Solana addresses are normalized identically across both SDK languages."""
 
 from __future__ import annotations
 
diff --git a/tests/test_denial.py b/tests/test_denial.py
@@ -1,4 +1,4 @@
-"""Tests for the denial helpers (mirror of node-commerce/tests/denial.test.ts)."""
+"""Tests for the denial helpers."""
 
 import pytest
 
diff --git a/tests/test_payment_directive.py b/tests/test_payment_directive.py
@@ -43,7 +43,7 @@ def test_build_payment_request_blob_includes_decimals_for_node_parity():
     """
     blob = build_payment_request_blob(PaymentRequestInput(rail="tempo-mainnet", amount_usd="1.50", recipient="0xabc"))
     decoded = _decode(blob)
-    # Mirror node-commerce/src/payment/directive.ts buildPaymentRequestBlob output keys exactly
+    # Output keys must match buildPaymentRequestBlob exactly across both SDK languages
     assert set(decoded.keys()) >= {"amount", "currency", "decimals"}
     assert decoded["amount"] == "1500000"  # 1.50 USDC at 6 decimals
     assert decoded["decimals"] == 6

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-"""Universal denial helpers shared across every adapter — Python mirror of node-commerce/src/_denial.ts.`
	`1`	`+"""Universal denial helpers shared across every adapter.`
`2`	`2`
`3`	`3`	`What lives here:`
`4`	`4`	`FIXABLE_DENIAL_REASONS / is_fixable_denial — classifier for compliance reasons that can`