offering-protocol 0.1.0__py3-none-any.whl

offering_protocol/core/models.py

@@ -0,0 +1,475 @@
+"""Typed Offering Discovery Protocol models."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Generic, TypeVar, cast
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue
+
+VERSION = "1.0"
+
+__all__ = [
+    "VERSION",
+    "Action",
+    "ActionRelation",
+    "ActionRequest",
+    "AuthenticationRequirement",
+    "CapabilityLink",
+    "Collection",
+    "CollectionSearchRequest",
+    "EnrollmentProtocol",
+    "FilterCapabilitySource",
+    "FilterDefinition",
+    "FilterExpression",
+    "FilterOperator",
+    "FilterType",
+    "FilterUnit",
+    "HttpActionTarget",
+    "HttpConfiguration",
+    "InvalidParameter",
+    "McpEndpoint",
+    "McpEndpointType",
+    "MissingPlacement",
+    "OdpModel",
+    "Offering",
+    "OfferingPage",
+    "OfferingSearchRequest",
+    "OpenApiActionTarget",
+    "Operation",
+    "OperationDescriptor",
+    "Page",
+    "PaymentOption",
+    "PaymentProtocol",
+    "PricePreview",
+    "PriceType",
+    "ProblemDetails",
+    "Protocol",
+    "RefinementBucket",
+    "RefinementGroup",
+    "Representation",
+    "ResourceIdentity",
+    "ResourceImage",
+    "ResourceImageType",
+    "ResourceType",
+    "SchemaReference",
+    "SearchCapabilities",
+    "ServiceBranding",
+    "ServiceBrandingImage",
+    "ServiceBrandingImageType",
+    "ServiceDocument",
+    "ServiceOpenApi",
+    "ServiceProtocols",
+    "SortCapabilitySource",
+    "SortDefinition",
+    "SortDirection",
+    "SortKey",
+    "TrustProtocol",
+]
+
+
+class OdpModel(BaseModel):
+    """Base model that preserves additive protocol members."""
+
+    model_config = ConfigDict(extra="allow", frozen=True, populate_by_name=True)
+
+    @property
+    def additional(self) -> dict[str, JsonValue]:
+        return dict(self.model_extra or {})
+
+    def to_dict(self) -> dict[str, JsonValue]:
+        return cast(
+            dict[str, JsonValue],
+            self.model_dump(mode="json", by_alias=True, exclude_unset=True),
+        )
+
+
+class Representation(StrEnum):
+    TERSE = "terse"
+    FULL = "full"
+
+
+class PriceType(StrEnum):
+    FIXED = "fixed"
+    FREE = "free"
+    METERED = "metered"
+    QUOTE = "quote"
+    RANGE = "range"
+    STARTING_AT = "starting_at"
+
+
+class ActionRelation(StrEnum):
+    DOWNLOAD = "download"
+    INVOKE = "invoke"
+    PURCHASE = "purchase"
+    QUOTE = "quote"
+    RESERVE = "reserve"
+
+
+class ResourceType(StrEnum):
+    COLLECTION = "collection"
+    OFFERING = "offering"
+
+
+class Operation(StrEnum):
+    GET_COLLECTION = "get-collection"
+    GET_OFFERING = "get-offering"
+    LIST_COLLECTION_OFFERINGS = "list-collection-offerings"
+    LIST_COLLECTIONS = "list-collections"
+    LIST_OFFERINGS = "list-offerings"
+    SEARCH_COLLECTIONS = "search-collections"
+    SEARCH_OFFERINGS = "search-offerings"
+
+
+class AuthenticationRequirement(StrEnum):
+    NOT_REQUIRED = "not-required"
+    OPTIONAL = "optional"
+    REQUIRED = "required"
+
+
+class Protocol(StrEnum):
+    AEP = "aep"
+    MPP = "mpp"
+    TAP = "tap"
+    X402 = "x402"
+
+
+class PaymentOption(StrEnum):
+    ALGORAND = "algorand"
+    APTOS = "aptos"
+    ARBITRUM = "arbitrum"
+    AVALANCHE = "avalanche"
+    BASE = "base"
+    CARD = "card"
+    ETHEREUM = "ethereum"
+    HEDERA = "hedera"
+    INFLOW = "inflow"
+    LIGHTNING = "lightning"
+    POLYGON = "polygon"
+    SOLANA = "solana"
+    STELLAR = "stellar"
+    STRIPE = "stripe"
+    TEMPO = "tempo"
+    TON = "ton"
+
+
+class FilterType(StrEnum):
+    BOOLEAN = "boolean"
+    DATE = "date"
+    DATE_TIME = "date-time"
+    DECIMAL = "decimal"
+    INTEGER = "integer"
+    NUMBER = "number"
+    STRING = "string"
+
+
+class FilterOperator(StrEnum):
+    EQUAL = "eq"
+    EXISTS = "exists"
+    GREATER_THAN = "gt"
+    GREATER_THAN_OR_EQUAL = "gte"
+    IN = "in"
+    LESS_THAN = "lt"
+    LESS_THAN_OR_EQUAL = "lte"
+
+
+class SortDirection(StrEnum):
+    ASCENDING = "ascending"
+    DESCENDING = "descending"
+
+
+class MissingPlacement(StrEnum):
+    FIRST = "first"
+    LAST = "last"
+
+
+class ServiceBrandingImageType(StrEnum):
+    PNG = "image/png"
+    SVG = "image/svg+xml"
+    WEBP = "image/webp"
+
+
+class ResourceImageType(StrEnum):
+    AVIF = "image/avif"
+    JPEG = "image/jpeg"
+    PNG = "image/png"
+    SVG = "image/svg+xml"
+    WEBP = "image/webp"
+
+
+class McpEndpointType(StrEnum):
+    STREAMABLE_HTTP = "streamable-http"
+
+
+class OperationDescriptor(OdpModel):
+    authentication: AuthenticationRequirement
+    name: Operation
+
+
+class EnrollmentProtocol(OdpModel):
+    name: Protocol
+
+
+class PaymentProtocol(OdpModel):
+    authentication: AuthenticationRequirement
+    name: Protocol
+    options: list[PaymentOption] = Field(default_factory=list)
+
+
+class TrustProtocol(OdpModel):
+    name: Protocol
+
+
+class ServiceProtocols(OdpModel):
+    enrollment: list[EnrollmentProtocol] = Field(default_factory=list)
+    payments: list[PaymentProtocol] = Field(default_factory=list)
+    trust: list[TrustProtocol] = Field(default_factory=list)
+
+
+class ServiceOpenApi(OdpModel):
+    url: str
+
+
+class HttpConfiguration(OdpModel):
+    endpoint_base: str
+    openapi: ServiceOpenApi | None = None
+
+
+class CapabilityLink(OdpModel):
+    href: str
+
+
+class FilterUnit(OdpModel):
+    code: str
+    system: str
+    title: str = ""
+
+
+class FilterDefinition(OdpModel):
+    description: str
+    id: str
+    operators: list[FilterOperator]
+    refinable: bool = False
+    title: str
+    filter_type: FilterType = Field(alias="type")
+    unit: FilterUnit | None = None
+
+
+class SortKey(OdpModel):
+    direction: SortDirection
+    filter_id: str
+    missing: MissingPlacement
+
+
+class SortDefinition(OdpModel):
+    description: str
+    id: str
+    keys: list[SortKey]
+    title: str
+
+
+class FilterCapabilitySource(OdpModel):
+    inline: list[FilterDefinition] = Field(default_factory=list)
+    linked: CapabilityLink | None = None
+
+
+class SortCapabilitySource(OdpModel):
+    inline: list[SortDefinition] = Field(default_factory=list)
+    linked: CapabilityLink | None = None
+
+
+class SearchCapabilities(OdpModel):
+    filters: FilterCapabilitySource | None = None
+    sorts: SortCapabilitySource | None = None
+
+
+class ServiceBrandingImage(OdpModel):
+    src: str
+    media_type: ServiceBrandingImageType | None = Field(default=None, alias="type")
+
+
+class ServiceBranding(OdpModel):
+    icon: ServiceBrandingImage
+    logo: ServiceBrandingImage
+
+
+class McpEndpoint(OdpModel):
+    description: str = ""
+    name: str = ""
+    endpoint_type: McpEndpointType = Field(alias="type")
+    url: str
+
+
+class ServiceDocument(OdpModel):
+    branding: ServiceBranding | None = None
+    description: str
+    documentation_url: str = ""
+    http: HttpConfiguration
+    keywords: list[str] = Field(default_factory=list)
+    language: str
+    localizations: list[str]
+    mcp: list[McpEndpoint] = Field(default_factory=list)
+    name: str
+    odp_version: str
+    operations: list[OperationDescriptor]
+    payment_origins: list[str] = Field(default_factory=list)
+    protocols: ServiceProtocols | None = None
+    search_capabilities: SearchCapabilities | None = None
+    status_url: str = ""
+    support_url: str = ""
+    website_url: str = ""
+
+
+class ResourceImage(OdpModel):
+    alt: str = ""
+    height: int = 0
+    src: str
+    media_type: ResourceImageType | None = Field(default=None, alias="type")
+    width: int = 0
+
+
+class Collection(OdpModel):
+    auth_expands: bool = False
+    description: str = ""
+    detail_fields: list[str] = Field(default_factory=list)
+    id: str
+    images: list[ResourceImage] = Field(default_factory=list)
+    language: str = ""
+    localizations: list[str] = Field(default_factory=list)
+    name: str
+    odp_version: str = ""
+    parent_ids: list[str] = Field(default_factory=list)
+    search_capabilities: SearchCapabilities | None = None
+    web_url: str = ""
+
+
+class SchemaReference(OdpModel):
+    url: str
+
+
+class PricePreview(OdpModel):
+    amount: str = ""
+    currency: str = ""
+    maximum: str = ""
+    minimum: str = ""
+    price_type: PriceType = Field(alias="type")
+    unit: str = ""
+
+
+class ActionRequest(OdpModel):
+    content_type: str = ""
+    schema_: SchemaReference | None = Field(default=None, alias="schema")
+
+
+class HttpActionTarget(OdpModel):
+    href: str
+    method: str
+    request: ActionRequest | None = None
+    response_content_types: list[str] = Field(default_factory=list)
+
+
+class OpenApiActionTarget(OdpModel):
+    operation_id: str
+    url: str = ""
+
+
+class Action(OdpModel):
+    authentication: AuthenticationRequirement
+    description: str = ""
+    http: HttpActionTarget | None = None
+    id: str
+    openapi: OpenApiActionTarget | None = None
+    rel: ActionRelation
+
+
+class Offering(OdpModel):
+    actions: list[Action] = Field(default_factory=list)
+    auth_expands: bool = False
+    attributes: dict[str, JsonValue] = Field(default_factory=dict)
+    collection_ids: list[str] = Field(default_factory=list)
+    description: str = ""
+    detail_fields: list[str] = Field(default_factory=list)
+    id: str
+    images: list[ResourceImage] = Field(default_factory=list)
+    language: str = ""
+    localizations: list[str] = Field(default_factory=list)
+    name: str
+    odp_version: str = ""
+    price: PricePreview | None = None
+    schema_: SchemaReference | None = Field(default=None, alias="schema")
+    web_url: str = ""
+
+
+class InvalidParameter(OdpModel):
+    location: str = Field(alias="in")
+    name: str
+    reason: str
+
+
+class ProblemDetails(OdpModel):
+    code: str
+    detail: str = ""
+    instance: str = ""
+    invalid_params: list[InvalidParameter] = Field(default_factory=list)
+    status: int
+    title: str
+    problem_type: str = Field(alias="type")
+
+
+class ResourceIdentity(OdpModel):
+    id: str
+    service: str
+    resource_type: ResourceType = Field(alias="type")
+
+    @property
+    def key(self) -> str:
+        return f"{self.service}\0{self.resource_type.value}\0{self.id}"
+
+
+class CollectionSearchRequest(OdpModel):
+    limit: int = 0
+    odp_version: str = VERSION
+    parent_id: str | None = None
+    query: str = ""
+
+
+class FilterExpression(OdpModel):
+    id: str
+    operator: FilterOperator
+    value: JsonValue
+
+
+class OfferingSearchRequest(OdpModel):
+    collection_id: str = ""
+    filters: list[FilterExpression] = Field(default_factory=list)
+    include_descendants: bool = False
+    limit: int = 0
+    odp_version: str = VERSION
+    query: str = ""
+    refinements: list[str] = Field(default_factory=list)
+    sort: str = ""
+
+
+class RefinementBucket(OdpModel):
+    count: int
+    count_relation: str = ""
+    value: JsonValue
+
+
+class RefinementGroup(OdpModel):
+    filter_id: str
+    values: list[RefinementBucket]
+
+
+Item = TypeVar("Item")
+
+
+class Page(OdpModel, Generic[Item]):
+    auth_expands: bool = False
+    items: list[Item]
+    next: str = ""
+    odp_version: str
+
+
+class OfferingPage(Page[Item], Generic[Item]):
+    refinements: list[RefinementGroup] = Field(default_factory=list)

offering_protocol/core/references.py

@@ -0,0 +1,135 @@
+"""ODP URL, reference, operation-path, and identity helpers."""
+
+from __future__ import annotations
+
+from ipaddress import ip_address
+from typing import cast
+from urllib.parse import SplitResult, urljoin, urlsplit, urlunsplit
+
+from offering_protocol.core.models import Operation, ResourceIdentity, ResourceType
+
+
+class ReferenceError(ValueError):
+    """Raised when an ODP URL or reference violates protocol constraints."""
+
+
+_RESOURCE_OPERATIONS = {
+    Operation.GET_COLLECTION,
+    Operation.GET_OFFERING,
+    Operation.LIST_COLLECTION_OFFERINGS,
+}
+
+_OPERATION_PATHS = {
+    Operation.LIST_COLLECTIONS: "/collections",
+    Operation.SEARCH_COLLECTIONS: "/collections/search",
+    Operation.LIST_OFFERINGS: "/offerings",
+    Operation.SEARCH_OFFERINGS: "/offerings/search",
+}
+
+
+def is_local_resource_identifier(value: str) -> bool:
+    return (
+        bool(value)
+        and value not in {".", ".."}
+        and len(value) <= 128
+        and all(
+            character.isascii() and (character.isalnum() or character in "._~-")
+            for character in value
+        )
+    )
+
+
+def operation_method(operation: Operation) -> str:
+    if operation in {Operation.SEARCH_COLLECTIONS, Operation.SEARCH_OFFERINGS}:
+        return "POST"
+    return "GET"
+
+
+def derive_service_origin(service_url: str) -> str:
+    parsed = _parse_secure_url(service_url)
+    hostname = cast(str, parsed.hostname)
+    host = f"[{hostname}]" if ":" in hostname else hostname
+    port = parsed.port
+    if port is not None and not (parsed.scheme == "https" and port == 443):
+        host = f"{host}:{port}"
+    return urlunsplit((parsed.scheme, host, "", "", ""))
+
+
+def resolve_resource_reference(reference: str, service_origin: str) -> str:
+    if reference.startswith("//"):
+        raise ReferenceError("ODP resource reference cannot be scheme-relative")
+    if not reference.startswith(
+        ("/", "https://", "http://localhost", "http://127.0.0.1", "http://[::1]")
+    ):
+        raise ReferenceError(
+            "ODP resource reference must be an origin-relative absolute path or secure absolute URL"
+        )
+    resolved = _parse_secure_url(urljoin(f"{derive_service_origin(service_origin)}/", reference))
+    if resolved.fragment:
+        raise ReferenceError("ODP resource reference cannot contain a fragment")
+    return resolved.geturl()
+
+
+def resolve_continuation(reference: str, service_origin: str) -> str:
+    resolved = resolve_resource_reference(reference, service_origin)
+    if derive_service_origin(resolved) != derive_service_origin(service_origin):
+        raise ReferenceError("ODP continuation reference must remain on the Service origin")
+    return resolved
+
+
+def build_operation_url(
+    endpoint_base: str,
+    operation: Operation,
+    service_origin: str,
+    resource_id: str | None = None,
+) -> str:
+    if not endpoint_base.startswith("/") or endpoint_base.startswith("//"):
+        raise ReferenceError("ODP endpoint base must be an origin-relative absolute path")
+    path = operation_path(operation, resource_id)
+    return resolve_resource_reference(f"{endpoint_base.rstrip('/')}{path}", service_origin)
+
+
+def operation_path(operation: Operation, resource_id: str | None = None) -> str:
+    if operation in _RESOURCE_OPERATIONS:
+        if resource_id is None or not is_local_resource_identifier(resource_id):
+            raise ReferenceError(f"{operation.value} requires a valid local resource identifier")
+    elif resource_id is not None:
+        raise ReferenceError(f"{operation.value} does not accept a resource identifier")
+
+    if operation is Operation.GET_COLLECTION:
+        return f"/collections/{resource_id}"
+    if operation is Operation.LIST_COLLECTION_OFFERINGS:
+        return f"/collections/{resource_id}/offerings"
+    if operation is Operation.GET_OFFERING:
+        return f"/offerings/{resource_id}"
+    return _OPERATION_PATHS[operation]
+
+
+def create_resource_identity(
+    service_document_url: str, resource_type: ResourceType, resource_id: str
+) -> ResourceIdentity:
+    if not is_local_resource_identifier(resource_id):
+        raise ReferenceError(f"{resource_type.value} requires a valid local resource identifier")
+    return ResourceIdentity(
+        id=resource_id,
+        service=derive_service_origin(service_document_url),
+        type=resource_type,
+    )
+
+
+def _parse_secure_url(value: str) -> SplitResult:
+    parsed = urlsplit(value)
+    if parsed.username is not None or parsed.password is not None:
+        raise ReferenceError("ODP URL cannot contain user information")
+    hostname = parsed.hostname
+    if hostname is None:
+        raise ReferenceError("ODP URL must include a host")
+    loopback = hostname.lower() == "localhost"
+    if not loopback:
+        try:
+            loopback = ip_address(hostname).is_loopback
+        except ValueError:
+            loopback = False
+    if parsed.scheme != "https" and not (parsed.scheme == "http" and loopback):
+        raise ReferenceError("ODP URL must use HTTPS except on loopback hosts")
+    return parsed

offering_protocol/core/schemas/action-relation.schema.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://offeringprotocol.org/schemas/action-relation.schema.json",
+  "title": "ODP Action relation",
+  "type": "string",
+  "minLength": 1,
+  "maxLength": 64,
+  "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+}

offering_protocol/core/schemas/action-request.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://offeringprotocol.org/schemas/action-request.schema.json",
+  "title": "ODP compact Action request body",
+  "type": "object",
+  "additionalProperties": false,
+  "minProperties": 1,
+  "properties": {
+    "content_type": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "schema": {
+      "$ref": "schema-reference.schema.json"
+    }
+  }
+}

offering_protocol/core/schemas/action.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://offeringprotocol.org/schemas/action.schema.json",
+  "title": "ODP Offering Action",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "authentication",
+    "id",
+    "rel"
+  ],
+  "properties": {
+    "authentication": {
+      "$ref": "authentication-requirement.schema.json"
+    },
+    "id": {
+      "$ref": "local-resource-identifier.schema.json"
+    },
+    "rel": {
+      "$ref": "action-relation.schema.json"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512
+    },
+    "http": {
+      "$ref": "http-action-target.schema.json"
+    },
+    "openapi": {
+      "$ref": "openapi-action-target.schema.json"
+    }
+  },
+  "oneOf": [
+    {
+      "required": [
+        "http"
+      ],
+      "not": {
+        "required": [
+          "openapi"
+        ]
+      }
+    },
+    {
+      "required": [
+        "openapi"
+      ],
+      "not": {
+        "required": [
+          "http"
+        ]
+      }
+    }
+  ]
+}

offering_protocol/core/schemas/attribute-schema-reference.schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://offeringprotocol.org/schemas/attribute-schema-reference.schema.json",
+  "title": "ODP Attribute Schema reference",
+  "$ref": "schema-reference.schema.json"
+}