offering-protocol 0.1.0__tar.gz → 0.1.1__tar.gz

{offering_protocol-0.1.0 → offering_protocol-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: offering-protocol
-Version: 0.1.0
+Version: 0.1.1
 Summary: Official Python SDK for the Offering Discovery Protocol
 Project-URL: Documentation, https://www.offeringprotocol.org/
 Project-URL: Issues, https://github.com/offering-protocol/odp-python/issues
@@ -281,6 +281,10 @@ its Actions can advertise enrollment, payment, and trust protocols, but ODP does
 credentials, invoke Actions, submit payments, or implement trust protocols. Applications compose
 the appropriate protocol clients around an Action resolved through ODP.
 
+`parse_service_document` is the strict current-version Service parser. Agent inspection and
+Directory results filter unrecognized enrollment, payment, and trust descriptors while retaining
+strict validation for recognized descriptors.
+
 ## Errors and validation
 
 Each role exposes typed errors:

{offering_protocol-0.1.0 → offering_protocol-0.1.1}/README.md

@@ -252,6 +252,10 @@ its Actions can advertise enrollment, payment, and trust protocols, but ODP does
 credentials, invoke Actions, submit payments, or implement trust protocols. Applications compose
 the appropriate protocol clients around an Action resolved through ODP.
 
+`parse_service_document` is the strict current-version Service parser. Agent inspection and
+Directory results filter unrecognized enrollment, payment, and trust descriptors while retaining
+strict validation for recognized descriptors.
+
 ## Errors and validation
 
 Each role exposes typed errors:

{offering_protocol-0.1.0 → offering_protocol-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "offering-protocol"
-version = "0.1.0"
+version = "0.1.1"
 description = "Official Python SDK for the Offering Discovery Protocol"
 readme = "README.md"
 requires-python = ">=3.11"

{offering_protocol-0.1.0 → offering_protocol-0.1.1}/src/offering_protocol/agent/client.py

@@ -21,18 +21,30 @@ from offering_protocol.core import (
     OfferingSearchRequest,
     Operation,
     Page,
+    ProblemDetails,
     Representation,
     ServiceDocument,
     build_operation_url,
     derive_service_origin,
-    parse_collection,
-    parse_collection_page,
-    parse_offering,
-    parse_offering_page,
-    parse_problem_response,
-    parse_service_document,
+    parse_agent_service_document,
     resolve_continuation,
 )
+from offering_protocol.core import (
+    parse_collection as parse_collection_strict,
+)
+from offering_protocol.core import (
+    parse_collection_page as parse_collection_page_strict,
+)
+from offering_protocol.core import (
+    parse_offering as parse_offering_strict,
+)
+from offering_protocol.core import (
+    parse_offering_page as parse_offering_page_strict,
+)
+from offering_protocol.core import (
+    parse_problem_response as parse_problem_response_strict,
+)
+from offering_protocol.core.validation import _normalize_agent_response
 from offering_protocol.directory.transport import (
     HttpRequest,
     HttpResponse,
@@ -136,10 +148,10 @@ class ServiceClient:
             b"",
             _MAXIMUM_DOCUMENT_BYTES,
             self._cache_fallbacks.service_document,
-            parse_service_document,
+            parse_agent_service_document,
         )
         return Inspection(
-            document=parse_service_document(response.body),
+            document=parse_agent_service_document(response.body),
             final_url=response.final_url,
             freshness=response.freshness,
             requested_url=requested_url,
@@ -571,6 +583,33 @@ def _operation_parser(operation: Operation) -> object:
     return parse_offering_page
 
 
+def parse_collection(data: bytes | str) -> Collection:
+    return parse_collection_strict(_normalize_body(data, "collection"))
+
+
+def parse_offering(data: bytes | str) -> Offering:
+    return parse_offering_strict(_normalize_body(data, "offering"))
+
+
+def parse_collection_page(data: bytes | str) -> Page[Collection]:
+    return parse_collection_page_strict(_normalize_body(data, "collection-page"))
+
+
+def parse_offering_page(data: bytes | str) -> OfferingPage[Offering]:
+    return parse_offering_page_strict(_normalize_body(data, "offering-page"))
+
+
+def parse_problem_response(data: bytes | str, status: int) -> ProblemDetails:
+    return parse_problem_response_strict(_normalize_body(data, "problem"), status)
+
+
+def _normalize_body(data: bytes | str, kind: str) -> str:
+    raw = json.loads(data)
+    if not isinstance(raw, dict):
+        return data.decode() if isinstance(data, bytes) else data
+    return json.dumps(_normalize_agent_response(raw, kind), separators=(",", ":"))
+
+
 def _encode(value: object) -> bytes:
     if not hasattr(value, "model_dump_json"):
         raise TypeError("ODP model is not serializable")

{offering_protocol-0.1.0 → offering_protocol-0.1.1}/src/offering_protocol/agent/details.py

@@ -53,7 +53,7 @@ class DiscoveredAction:
     http: DiscoveredHttpAction | None
     id: str
     openapi: DiscoveredOpenApiAction | None
-    rel: ActionRelation
+    rel: ActionRelation | str
 
 
 @dataclass(frozen=True, slots=True)

{offering_protocol-0.1.0 → offering_protocol-0.1.1}/src/offering_protocol/core/__init__.py

@@ -16,6 +16,7 @@ from offering_protocol.core.references import (
 from offering_protocol.core.validation import (
     OdpValidationError,
     ValidationIssue,
+    parse_agent_service_document,
     parse_collection,
     parse_collection_page,
     parse_collection_search_request,
@@ -44,6 +45,7 @@ __all__ = [
     "is_local_resource_identifier",
     "operation_method",
     "operation_path",
+    "parse_agent_service_document",
     "parse_collection",
     "parse_collection_page",
     "parse_collection_search_request",

{offering_protocol-0.1.0 → offering_protocol-0.1.1}/src/offering_protocol/core/models.py

@@ -379,7 +379,7 @@ class Action(OdpModel):
     http: HttpActionTarget | None = None
     id: str
     openapi: OpenApiActionTarget | None = None
-    rel: ActionRelation
+    rel: ActionRelation | str
 
 
 class Offering(OdpModel):

{offering_protocol-0.1.0 → offering_protocol-0.1.1}/src/offering_protocol/core/validation.py

@@ -82,6 +82,363 @@ def parse_service_document(data: bytes | str) -> ServiceDocument:
     return value
 
 
+def parse_agent_service_document(data: bytes | str) -> ServiceDocument:
+    try:
+        raw = json.loads(data)
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return parse_service_document(data)
+    if isinstance(raw, dict):
+        raw = _normalize_agent_response(raw, "service-document")
+    return parse_service_document(json.dumps(raw, separators=(",", ":")))
+
+
+def _normalize_agent_response(value: dict[str, Any], kind: str) -> dict[str, Any]:
+    normalized = dict(value)
+    if kind == "service-document":
+        _filter_agent_protocols(normalized)
+        protocols = normalized.get("protocols")
+        if isinstance(protocols, dict):
+            _filter_unknown_authentication(protocols, "payments")
+        _filter_named_list(
+            normalized,
+            "operations",
+            {
+                "get-collection",
+                "get-offering",
+                "list-collection-offerings",
+                "list-collections",
+                "list-offerings",
+                "search-collections",
+                "search-offerings",
+            },
+        )
+        _filter_unknown_authentication(normalized, "operations")
+        _filter_typed_list(normalized, "mcp", {"streamable-http"})
+        _filter_closed_object_list(normalized, "operations", {"authentication", "name"})
+        _filter_closed_object_list(normalized, "mcp", {"description", "name", "type", "url"})
+        _filter_payment_options(normalized)
+        _normalize_branding(normalized)
+        _normalize_search_capabilities(normalized)
+    elif kind in {"collection", "offering"}:
+        _filter_typed_list(
+            normalized,
+            "images",
+            {"image/avif", "image/jpeg", "image/png", "image/svg+xml", "image/webp"},
+        )
+        _strip_object_list(normalized, "images", {"alt", "height", "src", "type", "width"})
+        _normalize_search_capabilities(normalized)
+        if kind == "offering":
+            _normalize_offering(normalized)
+    elif kind in {"collection-page", "offering-page"} and isinstance(normalized.get("items"), list):
+        item_kind = "offering" if kind == "offering-page" else "collection"
+        normalized["items"] = [
+            _normalize_agent_response(item, item_kind) if isinstance(item, dict) else item
+            for item in normalized["items"]
+        ]
+    elif kind in {"filter-page", "sort-page"} and isinstance(normalized.get("items"), list):
+        predicate = _known_filter if kind == "filter-page" else _known_sort
+        normalized["items"] = [item for item in normalized["items"] if predicate(item)]
+    elif kind == "problem" and isinstance(normalized.get("invalid_params"), list):
+        normalized["invalid_params"] = [
+            item
+            for item in normalized["invalid_params"]
+            if not (
+                isinstance(item, dict)
+                and isinstance(item.get("in"), str)
+                and item["in"] not in {"body", "header", "path", "query"}
+            )
+        ]
+    return normalized
+
+
+def _filter_named_list(value: dict[str, Any], member: str, recognized: set[str]) -> None:
+    items = value.get(member)
+    if not isinstance(items, list):
+        return
+    filtered = [
+        item
+        for item in items
+        if not (
+            isinstance(item, dict)
+            and isinstance(item.get("name"), str)
+            and item["name"] not in recognized
+        )
+    ]
+    if filtered:
+        value[member] = filtered
+    else:
+        value.pop(member, None)
+
+
+def _filter_typed_list(value: dict[str, Any], member: str, recognized: set[str]) -> None:
+    items = value.get(member)
+    if not isinstance(items, list):
+        return
+    filtered = [
+        item
+        for item in items
+        if not (
+            isinstance(item, dict)
+            and isinstance(item.get("type"), str)
+            and item["type"] not in recognized
+        )
+    ]
+    if filtered:
+        value[member] = filtered
+    else:
+        value.pop(member, None)
+
+
+def _filter_closed_object_list(value: dict[str, Any], member: str, allowed: set[str]) -> None:
+    items = value.get(member)
+    if not isinstance(items, list):
+        return
+    filtered = [
+        item for item in items if not isinstance(item, dict) or not set(item).difference(allowed)
+    ]
+    if filtered:
+        value[member] = filtered
+    else:
+        value.pop(member, None)
+
+
+def _filter_unknown_authentication(value: dict[str, Any], member: str) -> None:
+    items = value.get(member)
+    if not isinstance(items, list):
+        return
+    filtered = [
+        item
+        for item in items
+        if not isinstance(item, dict) or not _has_unknown_authentication(item)
+    ]
+    if filtered:
+        value[member] = filtered
+    else:
+        value.pop(member, None)
+
+
+def _has_unknown_authentication(value: dict[str, Any]) -> bool:
+    authentication = value.get("authentication")
+    return isinstance(authentication, str) and authentication not in {
+        "not-required",
+        "optional",
+        "required",
+    }
+
+
+def _strip_object_list(value: dict[str, Any], member: str, allowed: set[str]) -> None:
+    items = value.get(member)
+    if not isinstance(items, list):
+        return
+    value[member] = [
+        {key: entry for key, entry in item.items() if key in allowed}
+        if isinstance(item, dict)
+        else item
+        for item in items
+    ]
+
+
+def _filter_payment_options(value: dict[str, Any]) -> None:
+    protocols = value.get("protocols")
+    if not isinstance(protocols, dict) or not isinstance(protocols.get("payments"), list):
+        return
+    recognized = {
+        "algorand",
+        "aptos",
+        "arbitrum",
+        "avalanche",
+        "base",
+        "card",
+        "ethereum",
+        "hedera",
+        "inflow",
+        "lightning",
+        "polygon",
+        "solana",
+        "stellar",
+        "stripe",
+        "tempo",
+        "ton",
+    }
+    for payment in protocols["payments"]:
+        if not isinstance(payment, dict) or not isinstance(payment.get("options"), list):
+            continue
+        options = [
+            option
+            for option in payment["options"]
+            if not isinstance(option, str) or option in recognized
+        ]
+        if options:
+            payment["options"] = options
+        else:
+            payment.pop("options", None)
+
+
+def _normalize_branding(value: dict[str, Any]) -> None:
+    branding = value.get("branding")
+    if not isinstance(branding, dict):
+        return
+    normalized = {key: entry for key, entry in branding.items() if key in {"icon", "logo"}}
+    for member in ("icon", "logo"):
+        image = normalized.get(member)
+        if (
+            isinstance(image, dict)
+            and isinstance(image.get("type"), str)
+            and image["type"] not in {"image/png", "image/svg+xml", "image/webp"}
+        ):
+            normalized.pop(member, None)
+        elif isinstance(image, dict):
+            normalized[member] = {
+                key: entry for key, entry in image.items() if key in {"src", "type"}
+            }
+    if normalized:
+        value["branding"] = normalized
+    else:
+        value.pop("branding", None)
+
+
+def _normalize_search_capabilities(value: dict[str, Any]) -> None:
+    capabilities = value.get("search_capabilities")
+    if not isinstance(capabilities, dict):
+        return
+    normalized = dict(capabilities)
+    for member, predicate in (("filters", _known_filter), ("sorts", _known_sort)):
+        source = normalized.get(member)
+        if not isinstance(source, dict) or not isinstance(source.get("inline"), list):
+            continue
+        items = [item for item in source["inline"] if predicate(item)]
+        if items:
+            normalized[member] = {**source, "inline": items}
+        else:
+            normalized.pop(member, None)
+    if normalized:
+        value["search_capabilities"] = normalized
+    else:
+        value.pop("search_capabilities", None)
+
+
+def _normalize_offering(value: dict[str, Any]) -> None:
+    schema = value.get("schema")
+    if isinstance(schema, dict) and set(schema).difference({"url"}):
+        value.pop("schema", None)
+    price = value.get("price")
+    if (
+        isinstance(price, dict)
+        and isinstance(price.get("type"), str)
+        and price["type"] not in {"fixed", "free", "metered", "quote", "range", "starting_at"}
+    ):
+        value.pop("price", None)
+    actions = value.get("actions")
+    if not isinstance(actions, list):
+        return
+    filtered = []
+    for action in actions:
+        if isinstance(action, dict) and _has_unknown_authentication(action):
+            continue
+        if isinstance(action, dict) and set(action).difference(
+            {"authentication", "description", "http", "id", "openapi", "rel"}
+        ):
+            continue
+        http = action.get("http") if isinstance(action, dict) else None
+        if isinstance(http, dict) and set(http).difference(
+            {"href", "method", "request", "response_content_types"}
+        ):
+            continue
+        request = http.get("request") if isinstance(http, dict) else None
+        if isinstance(request, dict) and set(request).difference({"content_type", "schema"}):
+            continue
+        schema = request.get("schema") if isinstance(request, dict) else None
+        if isinstance(schema, dict) and set(schema).difference({"url"}):
+            continue
+        openapi = action.get("openapi") if isinstance(action, dict) else None
+        if isinstance(openapi, dict) and set(openapi).difference({"operation_id", "url"}):
+            continue
+        method = http.get("method") if isinstance(http, dict) else None
+        if isinstance(method, str) and method not in {"GET", "POST"}:
+            continue
+        filtered.append(action)
+    if filtered:
+        value["actions"] = filtered
+    else:
+        value.pop("actions", None)
+
+
+def _known_filter(value: Any) -> bool:
+    if not isinstance(value, dict):
+        return True
+    if isinstance(value.get("type"), str) and value["type"] not in {
+        "boolean",
+        "date",
+        "date-time",
+        "decimal",
+        "integer",
+        "number",
+        "string",
+    }:
+        return False
+    operators = value.get("operators")
+    if isinstance(operators, list) and any(
+        isinstance(operator, str)
+        and operator not in {"eq", "exists", "gt", "gte", "in", "lt", "lte"}
+        for operator in operators
+    ):
+        return False
+    unit = value.get("unit")
+    return not (
+        isinstance(unit, dict)
+        and isinstance(unit.get("system"), str)
+        and unit["system"] not in {"service", "ucum"}
+    )
+
+
+def _known_sort(value: Any) -> bool:
+    if not isinstance(value, dict) or not isinstance(value.get("keys"), list):
+        return True
+    return not any(
+        isinstance(key, dict)
+        and (
+            (
+                isinstance(key.get("direction"), str)
+                and key["direction"] not in {"ascending", "descending"}
+            )
+            or (isinstance(key.get("missing"), str) and key["missing"] not in {"first", "last"})
+        )
+        for key in value["keys"]
+    )
+
+
+def _filter_agent_protocols(document: dict[str, Any]) -> None:
+    protocols = document.get("protocols")
+    if not isinstance(protocols, dict):
+        return
+    _filter_agent_protocol_category(protocols, "enrollment", {"aep"})
+    _filter_agent_protocol_category(protocols, "payments", {"mpp", "x402"})
+    _filter_agent_protocol_category(protocols, "trust", {"tap"})
+    if not protocols:
+        document.pop("protocols")
+
+
+def _filter_agent_protocol_category(
+    protocols: dict[str, Any], category: str, recognized: set[str]
+) -> None:
+    descriptors = protocols.get(category)
+    if not isinstance(descriptors, list):
+        return
+    filtered = [
+        descriptor
+        for descriptor in descriptors
+        if not (
+            isinstance(descriptor, dict)
+            and isinstance(descriptor.get("name"), str)
+            and descriptor["name"] not in recognized
+        )
+    ]
+    if descriptors and not filtered:
+        protocols.pop(category)
+    else:
+        protocols[category] = filtered
+
+
 def parse_collection(data: bytes | str) -> Collection:
     value = _parse(data, "collection.schema.json", "Collection", Collection)
     _validate_representation(
@@ -99,7 +456,14 @@ def parse_offering(data: bytes | str) -> Offering:
 
 
 def parse_problem_details(data: bytes | str) -> ProblemDetails:
-    return _parse(data, "problem-details.schema.json", "Problem Details", ProblemDetails)
+    value = _parse(data, "problem-details.schema.json", "Problem Details", ProblemDetails)
+    expected_type = "https://offeringprotocol.org/problems/" + value.code.lower().replace("_", "-")
+    if value.problem_type != expected_type:
+        raise OdpValidationError(
+            "Problem Details",
+            [_issue("/type", "problem-type", "must correspond to the problem code")],
+        )
+    return value
 
 
 def parse_problem_response(data: bytes | str, http_status: int) -> ProblemDetails:

{offering_protocol-0.1.0 → offering_protocol-0.1.1}/src/offering_protocol/directory/client.py

@@ -7,7 +7,11 @@ from urllib.parse import urlencode, urljoin
 
 from pydantic import ValidationError as ModelValidationError
 
-from offering_protocol.core import derive_service_origin
+from offering_protocol.core import (
+    OdpValidationError,
+    derive_service_origin,
+    parse_agent_service_document,
+)
 from offering_protocol.directory.models import (
     DirectoryService,
     Environment,
@@ -159,8 +163,18 @@ class DirectoryClient:
 
 def _parse_search_page(body: bytes) -> SearchPage:
     try:
-        page = SearchPage.model_validate_json(body)
-    except ModelValidationError as error:
+        raw = json.loads(body)
+        if isinstance(raw, dict) and isinstance(raw.get("items"), list):
+            for item in raw["items"]:
+                if isinstance(item, dict) and "protocols" in item:
+                    _normalize_service_protocols(item)
+        page = SearchPage.model_validate(raw)
+    except (
+        UnicodeDecodeError,
+        json.JSONDecodeError,
+        ModelValidationError,
+        OdpValidationError,
+    ) as error:
         raise DirectoryError(f"invalid Directory response: {error}") from error
     if len(page.items) > 100:
         raise DirectoryError("Directory search page exceeds 100 Services")
@@ -170,6 +184,27 @@ def _parse_search_page(body: bytes) -> SearchPage:
     return page
 
 
+def _normalize_service_protocols(item: dict[str, object]) -> None:
+    candidate = {
+        "description": "Directory protocol validation",
+        "http": {"endpoint_base": "/"},
+        "language": "en",
+        "localizations": ["en"],
+        "name": "Directory Service",
+        "odp_version": "1.0",
+        "operations": [
+            {"authentication": "not-required", "name": "get-offering"},
+            {"authentication": "not-required", "name": "list-offerings"},
+        ],
+        "protocols": item["protocols"],
+    }
+    document = parse_agent_service_document(json.dumps(candidate, separators=(",", ":")))
+    if document.protocols is None:
+        item.pop("protocols")
+    else:
+        item["protocols"] = document.protocols.model_dump(mode="json", exclude_defaults=True)
+
+
 def _validate_search_request(request: SearchRequest) -> None:
     if request.limit > 100:
         raise DirectoryError("limit must be from 1 through 100")