bcp-sdk 0.1.0a2__py3-none-any.whl

bcp_sdk/canonical.py

@@ -0,0 +1,87 @@
+import json
+import math
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+def canonicalize(obj: Mapping[str, Any]) -> bytes:
+    """Serializes obj to JCS (RFC 8785) canonical JSON bytes, ready to sign/verify."""
+    return _encode(obj).encode("utf-8")
+
+
+def _encode(value: Any) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        return _encode_number(value)
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, Mapping):
+        return _encode_object(value)
+    if isinstance(value, Sequence):
+        return "[" + ",".join(_encode(item) for item in value) + "]"
+    msg = f"cannot canonicalize value of type {type(value).__name__}"
+    raise TypeError(msg)
+
+
+def _encode_object(value: Mapping[str, Any]) -> str:
+    for key in value:
+        if not isinstance(key, str):
+            msg = f"object keys must be str, got {type(key).__name__}"
+            raise TypeError(msg)
+    items = sorted(value.items(), key=lambda kv: _utf16_code_units(kv[0]))
+    body = ",".join(f"{json.dumps(key, ensure_ascii=False)}:{_encode(val)}" for key, val in items)
+    return "{" + body + "}"
+
+
+def _utf16_code_units(value: str) -> tuple[int, ...]:
+    """Sort key matching RFC 8785 key ordering: UTF-16 code unit order, not code point order."""
+    encoded = value.encode("utf-16-be")
+    return tuple(int.from_bytes(encoded[i : i + 2], "big") for i in range(0, len(encoded), 2))
+
+
+def _encode_number(value: float) -> str:
+    if math.isnan(value) or math.isinf(value):
+        msg = "NaN and Infinity are not representable in JSON"
+        raise ValueError(msg)
+    if value == 0:
+        return "0"
+    sign = "-" if value < 0 else ""
+    digits, point = _shortest_digits(abs(value))
+    k = len(digits)
+    if k <= point <= 21:
+        return sign + digits + "0" * (point - k)
+    if 0 < point <= 21:
+        return sign + digits[:point] + "." + digits[point:]
+    if -6 < point <= 0:
+        return sign + "0." + "0" * -point + digits
+    exponent = point - 1
+    mantissa = digits[0] + ("." + digits[1:] if k > 1 else "")
+    exp_sign = "+" if exponent >= 0 else "-"
+    return f"{sign}{mantissa}e{exp_sign}{abs(exponent)}"
+
+
+def _shortest_digits(value: float) -> tuple[str, int]:
+    """Extracts the shortest round-trip digit string and decimal point position from repr().
+
+    Returns (digits, n) such that value == 0.<digits> * 10**n, matching the (s, k, n)
+    triple of ECMA-262 Number::toString: digits has no leading/trailing zero and is the
+    shortest sequence that round-trips to the same float (guaranteed by Python's repr).
+    """
+    text = repr(value)
+    mantissa, _, exp_text = text.partition("e")
+    exponent = int(exp_text) if exp_text else 0
+    int_part, _, frac_part = mantissa.partition(".")
+    all_digits = int_part + frac_part
+    point = len(int_part) + exponent
+
+    stripped = all_digits.lstrip("0")
+    point -= len(all_digits) - len(stripped)
+    stripped = stripped.rstrip("0")
+    if not stripped:
+        return "0", 1
+    return stripped, point

bcp_sdk/models/__init__.py

@@ -0,0 +1,4 @@
+# Generated by datamodel-codegen. Do not edit.
+# Part of the Brazilian Commerce Protocol (BCP), derived in part from the
+# Universal Commerce Protocol (UCP), Apache License 2.0.
+# See LICENSE and NOTICE for copyright, attribution, and modifications.

bcp_sdk/models/discovery/__init__.py

@@ -0,0 +1,4 @@
+# Generated by datamodel-codegen. Do not edit.
+# Part of the Brazilian Commerce Protocol (BCP), derived in part from the
+# Universal Commerce Protocol (UCP), Apache License 2.0.
+# See LICENSE and NOTICE for copyright, attribution, and modifications.

bcp_sdk/models/discovery/profile_schema.py

@@ -0,0 +1,104 @@
+# Generated by datamodel-codegen. Do not edit.
+# Part of the Brazilian Commerce Protocol (BCP), derived in part from the
+# Universal Commerce Protocol (UCP), Apache License 2.0.
+# See LICENSE and NOTICE for copyright, attribution, and modifications.
+
+from __future__ import annotations
+
+from pydantic import ConfigDict
+from typing import Literal
+from pydantic import BaseModel, ConfigDict, Field, RootModel
+from ..schemas import ucp as ucp_1
+
+
+class SigningKey(BaseModel):
+    """
+    Public key for signature verification in JWK format.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    kid: str
+    """
+    Key ID. Referenced in signature headers to identify which key to use for verification.
+    """
+    kty: str
+    """
+    Key type (e.g., 'EC', 'RSA').
+    """
+    crv: str | None = None
+    """
+    Curve name for EC keys (e.g., 'P-256').
+    """
+    x: str | None = None
+    """
+    X coordinate for EC public keys (base64url encoded).
+    """
+    y: str | None = None
+    """
+    Y coordinate for EC public keys (base64url encoded).
+    """
+    n: str | None = None
+    """
+    Modulus for RSA public keys (base64url encoded).
+    """
+    e: str | None = None
+    """
+    Exponent for RSA public keys (base64url encoded).
+    """
+    use: Literal["sig", "enc"] | None = None
+    """
+    Key usage. Should be 'sig' for signing keys.
+    """
+    alg: str | None = None
+    """
+    Algorithm (e.g., 'ES256', 'RS256').
+    """
+
+
+class Base(BaseModel):
+    """
+    Base discovery profile with shared properties for all profile types.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    ucp: ucp_1.Base
+    keys: list[SigningKey] | None = None
+    """
+    Public keys for signature verification (JWK format). Used to verify signed responses, webhooks, and other authenticated messages from this party.
+    """
+
+
+class PlatformProfile(Base):
+    """
+    Full discovery profile for platforms. Exposes complete service, capability, and payment handler registries.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    ucp: ucp_1.PlatformSchema | None = None
+
+
+class BusinessProfile(Base):
+    """
+    Discovery profile for businesses/merchants. Subset of platform profile with business-specific configuration.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    ucp: ucp_1.BusinessSchema | None = None
+
+
+class BcpDiscoveryProfile(RootModel[PlatformProfile | BusinessProfile]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: PlatformProfile | BusinessProfile = Field(..., title="BCP Discovery Profile")
+    """
+    Schema for BCP discovery profiles. Business profiles are hosted at /.well-known/bcp; platform profiles are hosted at URIs advertised in request headers.
+    """

bcp_sdk/models/schemas/__init__.py

@@ -0,0 +1,4 @@
+# Generated by datamodel-codegen. Do not edit.
+# Part of the Brazilian Commerce Protocol (BCP), derived in part from the
+# Universal Commerce Protocol (UCP), Apache License 2.0.
+# See LICENSE and NOTICE for copyright, attribution, and modifications.

bcp_sdk/models/schemas/capability.py

@@ -0,0 +1,267 @@
+# Generated by datamodel-codegen. Do not edit.
+# Part of the Brazilian Commerce Protocol (BCP), derived in part from the
+# Universal Commerce Protocol (UCP), Apache License 2.0.
+# See LICENSE and NOTICE for copyright, attribution, and modifications.
+
+from __future__ import annotations
+
+from pydantic import ConfigDict
+from typing import Any
+from pydantic import AnyUrl, BaseModel, ConfigDict, Field, RootModel
+
+
+class BcpCapability(RootModel[Any]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: Any = Field(..., title="BCP Capability")
+    """
+    Schema for BCP capabilities and extensions. Extensions are capabilities with an 'extends' field. Uses reverse-domain naming for governance.
+    """
+
+
+class Extends(RootModel[str]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: str = Field(..., pattern="^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$")
+    """
+    Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
+    """
+
+
+class Extends1Item(RootModel[str]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: str = Field(..., pattern="^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$")
+
+
+class Extends1(RootModel[list[Extends1Item]]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: list[Extends1Item] = Field(..., min_length=1)
+    """
+    Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
+    """
+
+
+class Extends2(RootModel[str]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: str = Field(..., pattern="^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$")
+    """
+    Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
+    """
+
+
+class Extends3Item(RootModel[str]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: str = Field(..., pattern="^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$")
+
+
+class Extends3(RootModel[list[Extends3Item]]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: list[Extends3Item] = Field(..., min_length=1)
+    """
+    Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
+    """
+
+
+class Extends4(RootModel[str]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: str = Field(..., pattern="^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$")
+    """
+    Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
+    """
+
+
+class Extends5Item(RootModel[str]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: str = Field(..., pattern="^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$")
+
+
+class Extends5(RootModel[list[Extends5Item]]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: list[Extends5Item] = Field(..., min_length=1)
+    """
+    Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
+    """
+
+
+class Extends6(RootModel[str]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: str = Field(..., pattern="^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$")
+    """
+    Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
+    """
+
+
+class Extends7Item(RootModel[str]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: str = Field(..., pattern="^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$")
+
+
+class Extends7(RootModel[list[Extends7Item]]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: list[Extends7Item] = Field(..., min_length=1)
+    """
+    Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
+    """
+
+
+class Version(RootModel[Any]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: Any
+
+
+class Base(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    version: Version
+    """
+    Entity version in YYYY-MM-DD format.
+    """
+    spec: AnyUrl | None = None
+    """
+    URL to human-readable specification document.
+    """
+    schema_: AnyUrl | None = Field(None, alias="schema")
+    """
+    URL to JSON Schema defining this entity's structure and payloads.
+    """
+    id: str | None = None
+    """
+    Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.
+    """
+    config: dict[str, Any] | None = None
+    """
+    Entity-specific configuration. Structure defined by each entity's schema.
+    """
+    extends: Extends | Extends1 | None = None
+    """
+    Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
+    """
+
+
+class PlatformSchema(BaseModel):
+    """
+    Full capability declaration for platform-level discovery. Includes spec/schema URLs for agent fetching.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    version: Version
+    """
+    Entity version in YYYY-MM-DD format.
+    """
+    spec: AnyUrl
+    """
+    URL to human-readable specification document.
+    """
+    schema_: AnyUrl = Field(..., alias="schema")
+    """
+    URL to JSON Schema defining this entity's structure and payloads.
+    """
+    id: str | None = None
+    """
+    Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.
+    """
+    config: dict[str, Any] | None = None
+    """
+    Entity-specific configuration. Structure defined by each entity's schema.
+    """
+    extends: Extends2 | Extends3 | None = None
+    """
+    Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
+    """
+
+
+class BusinessSchema(BaseModel):
+    """
+    Capability configuration for business/merchant level. May include business-specific config overrides.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    version: Version
+    """
+    Entity version in YYYY-MM-DD format.
+    """
+    spec: AnyUrl | None = None
+    """
+    URL to human-readable specification document.
+    """
+    schema_: AnyUrl | None = Field(None, alias="schema")
+    """
+    URL to JSON Schema defining this entity's structure and payloads.
+    """
+    id: str | None = None
+    """
+    Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.
+    """
+    config: dict[str, Any] | None = None
+    """
+    Entity-specific configuration. Structure defined by each entity's schema.
+    """
+    extends: Extends4 | Extends5 | None = None
+    """
+    Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
+    """
+
+
+class ResponseSchema(BaseModel):
+    """
+    Capability reference in responses. Only name/version required to confirm active capabilities.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    version: Version
+    """
+    Entity version in YYYY-MM-DD format.
+    """
+    spec: AnyUrl | None = None
+    """
+    URL to human-readable specification document.
+    """
+    schema_: AnyUrl | None = Field(None, alias="schema")
+    """
+    URL to JSON Schema defining this entity's structure and payloads.
+    """
+    id: str | None = None
+    """
+    Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.
+    """
+    config: dict[str, Any] | None = None
+    """
+    Entity-specific configuration. Structure defined by each entity's schema.
+    """
+    extends: Extends6 | Extends7 | None = None
+    """
+    Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
+    """

bcp_sdk/models/schemas/common/__init__.py

@@ -0,0 +1,4 @@
+# Generated by datamodel-codegen. Do not edit.
+# Part of the Brazilian Commerce Protocol (BCP), derived in part from the
+# Universal Commerce Protocol (UCP), Apache License 2.0.
+# See LICENSE and NOTICE for copyright, attribution, and modifications.

bcp_sdk/models/schemas/common/identity_linking/__init__.py

@@ -0,0 +1,45 @@
+# Generated by datamodel-codegen. Do not edit.
+# Part of the Brazilian Commerce Protocol (BCP), derived in part from the
+# Universal Commerce Protocol (UCP), Apache License 2.0.
+# See LICENSE and NOTICE for copyright, attribution, and modifications.
+
+from __future__ import annotations
+
+from pydantic import ConfigDict
+from typing import Any
+from pydantic import BaseModel, ConfigDict, Field, RootModel
+from ...shopping.types import description as description_1
+
+
+class IdentityLinking(RootModel[Any]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: Any = Field(..., title="Identity Linking")
+    """
+    Capability schema for identity linking. Businesses declare the user-authenticated scopes they offer in a flat 'scopes' map. Each key is the OAuth scope string as it appears on the wire ('{capability}:{scope}', e.g. 'br.dev.bcp.shopping.order:read'). Scope presence implies that the corresponding operations require user authentication. Operations not gated by any listed scope operate at whatever access level the business permits; BCP does not prescribe a default.
+    """
+
+
+class ScopePolicy(BaseModel):
+    """
+    Per-scope policy and metadata — auth constraints (e.g. min_acr, max_token_age), declarative metadata (e.g. claims produced, consent descriptions), or any other scope-specific configuration. An empty object means user authentication is required with no additional policy. Open for non-breaking extension.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    description: description_1.Description | None = None
+    """
+    Optional human-readable description of the scope that platforms can use to present and explain context (requirement and value) to the user.
+    """
+
+
+class ScopeToken(RootModel[str]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: str = Field(..., pattern="^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+:[a-z][a-z0-9_]*$")
+    """
+    OAuth scope string formed by joining a capability name and a scope name with a colon: '{capability}:{scope}', e.g. 'br.dev.bcp.shopping.order:read'. Capability names use reverse-DNS naming; scope names denote the permission granted, defined by each capability's spec (e.g. 'read', 'manage', 'create'). Platforms request these strings verbatim in OAuth 'scope' parameters; issued tokens carry them in the 'scope' claim.
+    """

bcp_sdk/models/schemas/common/identity_linking/br/__init__.py

@@ -0,0 +1,4 @@
+# Generated by datamodel-codegen. Do not edit.
+# Part of the Brazilian Commerce Protocol (BCP), derived in part from the
+# Universal Commerce Protocol (UCP), Apache License 2.0.
+# See LICENSE and NOTICE for copyright, attribution, and modifications.

bcp_sdk/models/schemas/common/identity_linking/br/dev/__init__.py

@@ -0,0 +1,4 @@
+# Generated by datamodel-codegen. Do not edit.
+# Part of the Brazilian Commerce Protocol (BCP), derived in part from the
+# Universal Commerce Protocol (UCP), Apache License 2.0.
+# See LICENSE and NOTICE for copyright, attribution, and modifications.

bcp_sdk/models/schemas/common/identity_linking/br/dev/bcp/__init__.py

@@ -0,0 +1,4 @@
+# Generated by datamodel-codegen. Do not edit.
+# Part of the Brazilian Commerce Protocol (BCP), derived in part from the
+# Universal Commerce Protocol (UCP), Apache License 2.0.
+# See LICENSE and NOTICE for copyright, attribution, and modifications.

bcp_sdk/models/schemas/common/identity_linking/br/dev/bcp/common.py

@@ -0,0 +1,17 @@
+# Generated by datamodel-codegen. Do not edit.
+# Part of the Brazilian Commerce Protocol (BCP), derived in part from the
+# Universal Commerce Protocol (UCP), Apache License 2.0.
+# See LICENSE and NOTICE for copyright, attribution, and modifications.
+
+from __future__ import annotations
+
+from pydantic import ConfigDict
+from typing import Any
+from pydantic import RootModel
+
+
+class IdentityLinking(RootModel[Any]):
+    model_config = ConfigDict(
+        frozen=True,
+    )
+    root: Any

bcp_sdk/models/schemas/handlers/__init__.py

@@ -0,0 +1,4 @@
+# Generated by datamodel-codegen. Do not edit.
+# Part of the Brazilian Commerce Protocol (BCP), derived in part from the
+# Universal Commerce Protocol (UCP), Apache License 2.0.
+# See LICENSE and NOTICE for copyright, attribution, and modifications.

bcp_sdk/models/schemas/handlers/pix/__init__.py

@@ -0,0 +1,4 @@
+# Generated by datamodel-codegen. Do not edit.
+# Part of the Brazilian Commerce Protocol (BCP), derived in part from the
+# Universal Commerce Protocol (UCP), Apache License 2.0.
+# See LICENSE and NOTICE for copyright, attribution, and modifications.