carrier-python 0.1.15__py3-none-any.whl

carrier/errors.py

@@ -0,0 +1,51 @@
+"""Errors raised by the Carrier client."""
+
+
+class CarrierError(Exception):
+    """Error returned by the Carrier API, or raised before a request is sent."""
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        error_type: str = "invalid_request_error",
+        *,
+        idempotency_key: str | None = None,
+        retryable: bool | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.type = error_type
+        self.idempotency_key = idempotency_key
+        self.retryable = retryable
+
+
+def outcome_unknown(key: str, status: int = 0) -> CarrierError:
+    """A dispatched issuance cannot safely be retried or given a new key."""
+    return CarrierError(
+        status, "outcome_unknown",
+        "Issuance outcome is unknown. Reconcile using the original idempotency key; do not automatically retry or create a new key.",
+        "api_error", idempotency_key=key, retryable=False,
+    )
+
+
+def error_from_body(status: int, body: object) -> CarrierError:
+    """Build a CarrierError from an API error envelope."""
+    if isinstance(body, dict):
+        error = body.get("error")
+        if isinstance(error, str):
+            code = body.get("code")
+            return CarrierError(status, code if isinstance(code, str) else "api_error", error, "api_error")
+        if isinstance(error, dict):
+            code = error.get("code")
+            message = error.get("message")
+            error_type = error.get("type")
+            return CarrierError(
+                status,
+                code if isinstance(code, str) else "api_error",
+                message if isinstance(message, str) else "Carrier request failed.",
+                error_type if isinstance(error_type, str) else "api_error",
+            )
+    return CarrierError(status, "api_error", "Carrier request failed.", "api_error")

carrier/http.py

@@ -0,0 +1,135 @@
+"""HTTP transport for the connectivity API."""
+
+import json
+import urllib.error
+import urllib.request
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from urllib.parse import urlencode
+
+from carrier.errors import CarrierError, error_from_body, outcome_unknown
+from carrier.idempotency import is_issuance, require_idempotency_key, require_issuance_key
+from carrier.version import __version__
+
+DEFAULT_BASE_URL = "https://api.carrier.llc"
+_USER_AGENT = f"carrier-python/{__version__}"
+
+
+@dataclass(frozen=True)
+class PreparedRequest:
+    """One outbound call. Tests capture this instead of opening a socket."""
+
+    method: str
+    url: str
+    headers: dict[str, str]
+    body: bytes | None
+
+
+Transport = Callable[[PreparedRequest], tuple[int, bytes]]
+
+
+class Http:
+    """Bearer-authenticated JSON client."""
+
+    def __init__(self, api_key: str, base_url: str, transport: Transport, timeout: float) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._transport = transport
+        self._timeout = timeout
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: object | None = None,
+        idempotency_key: str | None = None,
+        query: Mapping[str, str] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> object:
+        """Send one request and return the decoded JSON body."""
+        url = f"{self._base_url}{path}"
+        if query:
+            url = f"{url}?{urlencode(query)}"
+        outbound = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": _USER_AGENT,
+        }
+        for name, value in (headers or {}).items():
+            if name.lower() in {"authorization", "accept", "user-agent", "content-type", "host"}:
+                raise CarrierError(400, "invalid_header", f"{name} is set by the client.")
+            outbound[name] = value
+        payload: bytes | None = None
+        if body is not None:
+            try:
+                payload = json.dumps(body).encode("utf-8")
+            except (TypeError, ValueError) as error:
+                raise CarrierError(400, "invalid_body", "Request body could not be encoded.") from error
+            outbound["Content-Type"] = "application/json"
+        issuance = is_issuance(method, path)
+        key = ""
+        if issuance:
+            supplied_key = idempotency_key if idempotency_key is not None else outbound.get("X-Idempotency-Key", outbound.get("Idempotency-Key"))
+            key = require_issuance_key(supplied_key)
+        if idempotency_key is not None:
+            outbound["Idempotency-Key"] = require_idempotency_key(idempotency_key)
+        try:
+            status, raw = self._transport(
+                PreparedRequest(method=method, url=url, headers=outbound, body=payload),
+            )
+        except Exception as error:
+            if is_issuance(method, path):
+                raise outcome_unknown(key) from error
+            if isinstance(error, CarrierError):
+                raise
+            message = str(error) if str(error) else "Network request failed."
+            raise CarrierError(0, "network_error", message, "api_error") from error
+        try:
+            return _decode(status, raw)
+        except CarrierError as error:
+            if issuance and isinstance(error.__cause__, (UnicodeDecodeError, json.JSONDecodeError)):
+                raise outcome_unknown(key, status) from error
+            if issuance and error.code.lower() in ("outcome_unknown", "manual_reconciliation_required"):
+                error.idempotency_key = key
+                error.retryable = False
+            raise
+
+
+def urllib_transport(timeout: float) -> Transport:
+    """The default transport. Uses the stdlib so the package has no dependencies."""
+
+    def send(request: PreparedRequest) -> tuple[int, bytes]:
+        outbound = urllib.request.Request(
+            request.url,
+            data=request.body,
+            headers=request.headers,
+            method=request.method,
+        )
+        try:
+            with urllib.request.urlopen(outbound, timeout=timeout) as response:
+                return int(response.status), response.read()
+        except urllib.error.HTTPError as error:
+            return int(error.code), error.read()
+        except urllib.error.URLError as error:
+            reason = error.reason
+            message = str(reason) if reason else "Network request failed."
+            raise CarrierError(0, "network_error", message, "api_error") from error
+        except TimeoutError as error:
+            raise CarrierError(0, "network_error", str(error), "api_error") from error
+
+    return send
+
+
+def _decode(status: int, raw: bytes) -> object:
+    try:
+        parsed = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise CarrierError(
+            status,
+            "invalid_response",
+            "Carrier returned a body that is not JSON.",
+        ) from error
+    if 200 <= status <= 299:
+        return parsed
+    raise error_from_body(status, parsed)

carrier/idempotency.py

@@ -0,0 +1,46 @@
+"""Idempotency-Key checks shared with the API."""
+
+import re
+
+from carrier.errors import CarrierError
+
+
+def is_issuance(method: str, path: str) -> bool:
+    return method == "POST" and path in {
+        "/v1/connectivity/intents", "/v1/subscribers/issue-from-inventory",
+    }
+
+
+def require_issuance_key(key: object) -> str:
+    """Preserve the API's stable business key verbatim; never coerce or trim."""
+    if not isinstance(key, str) or re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}", key) is None:
+        raise CarrierError(400, "invalid_idempotency_key", "Issuance requires a stable 1–200 character key: alphanumeric first, then letters, digits, _, ., :, or -.")
+    return key
+
+
+def require_idempotency_key(key: str | None) -> str:
+    """Return the key, or raise before a request is sent."""
+    if key is None or key.strip() == "":
+        raise CarrierError(400, "invalid_idempotency_key", "Idempotency-Key is required.")
+    if len(key) > 255:
+        raise CarrierError(
+            400,
+            "invalid_idempotency_key",
+            "Idempotency-Key must be 255 characters or fewer.",
+        )
+    for char in key:
+        code = ord(char)
+        if code <= 31 or code == 127:
+            raise CarrierError(
+                400,
+                "invalid_idempotency_key",
+                "Idempotency-Key must not contain control characters.",
+            )
+    return key
+
+
+def require_id(value: str, label: str) -> str:
+    """Reject a path segment that could escape the resource URL."""
+    if value.strip() == "" or any(char in value for char in "/\\?#") or ".." in value:
+        raise CarrierError(400, "invalid_id", f"{label} is not a valid id.")
+    return value

carrier/mcp.py

@@ -0,0 +1,237 @@
+"""Streamable HTTP client for the hosted Carrier MCP server."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+from carrier.errors import CarrierError
+from carrier.version import __version__
+
+DEFAULT_MCP_URL = "https://mcp.carrier.llc/mcp"
+PROTOCOL_VERSION = "2025-11-25"
+ACCEPTED_PROTOCOL_VERSIONS = frozenset({"2025-11-25", "2025-06-18", "2025-03-26"})
+_USER_AGENT = f"carrier-python/{__version__}"
+
+
+@dataclass(frozen=True)
+class McpRequest:
+    """One MCP HTTP call. Tests capture this instead of opening a socket."""
+
+    method: str
+    url: str
+    headers: dict[str, str]
+    body: bytes | None
+
+
+McpTransport = Callable[[McpRequest], tuple[int, Mapping[str, str], bytes]]
+
+
+class Mcp:
+    """Client for `https://mcp.carrier.llc/mcp`.
+
+    `auth="token"` sends the eSIMVault reseller token as `?TOKEN=`.
+    `auth="bearer"` sends an OAuth access token or a Clerk organization API key.
+    """
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        url: str = DEFAULT_MCP_URL,
+        auth: str = "token",
+        transport: McpTransport | None = None,
+        timeout: float = 30,
+    ) -> None:
+        if token.strip() == "":
+            raise CarrierError(400, "invalid_token", "An MCP token is required.")
+        if auth not in {"token", "bearer"}:
+            raise CarrierError(400, "invalid_auth", "MCP auth must be token or bearer.")
+        self._token = token
+        self._url = url
+        self._auth = auth
+        self._transport = transport if transport is not None else urllib_mcp_transport(timeout)
+        self._session_id: str | None = None
+        self._protocol: str | None = None
+        self._connected = False
+        self._next_id = 1
+
+    def connect(self) -> dict[str, object]:
+        """Initialize a session and send `notifications/initialized`."""
+        result = self._rpc(
+            "initialize",
+            {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {"tools": {}},
+                "clientInfo": {"name": "carrier-python", "version": __version__},
+            },
+            handshake=True,
+        )
+        if not isinstance(result, dict):
+            raise CarrierError(200, "invalid_response", "MCP initialize did not return an object.")
+        version = result.get("protocolVersion")
+        if version not in ACCEPTED_PROTOCOL_VERSIONS:
+            raise CarrierError(400, "unsupported_protocol", f"MCP server negotiated {version}.")
+        self._protocol = str(version)
+        self._notify("notifications/initialized")
+        self._connected = True
+        return result
+
+    def list_tools(self) -> list[object]:
+        """Return the tools advertised for this session."""
+        self._ensure_connected()
+        result = self._rpc("tools/list", {})
+        if not isinstance(result, dict) or not isinstance(result.get("tools"), list):
+            raise CarrierError(200, "invalid_response", "MCP tools/list did not return tools.")
+        return list(result["tools"])
+
+    def call_tool(self, name: str, arguments: Mapping[str, object] | None = None) -> dict[str, object]:
+        """Call one MCP tool and return the tool result object."""
+        self._ensure_connected()
+        if name.strip() == "":
+            raise CarrierError(400, "invalid_tool", "An MCP tool name is required.")
+        result = self._rpc("tools/call", {"name": name, "arguments": dict(arguments or {})})
+        if not isinstance(result, dict):
+            raise CarrierError(200, "invalid_response", "MCP tools/call did not return an object.")
+        return result
+
+    def request(self, method: str, params: Mapping[str, object] | None = None) -> object:
+        """Call any MCP method. The session is opened on the first call."""
+        if method != "initialize":
+            self._ensure_connected()
+        return self._rpc(method, dict(params or {}))
+
+    def _ensure_connected(self) -> None:
+        if not self._connected:
+            self.connect()
+
+    def _notify(self, method: str) -> None:
+        self._send({"jsonrpc": "2.0", "method": method}, notify=True)
+
+    def _rpc(self, method: str, params: Mapping[str, object], *, handshake: bool = False) -> object:
+        message = {"jsonrpc": "2.0", "id": self._next_id, "method": method, "params": dict(params)}
+        self._next_id += 1
+        return self._send(message, handshake=handshake)
+
+    def _send(self, message: Mapping[str, object], *, notify: bool = False, handshake: bool = False) -> object:
+        payload = json.dumps(dict(message)).encode("utf-8")
+        try:
+            status, headers, raw = self._transport(
+                McpRequest(method="POST", url=self._endpoint(), headers=self._headers(), body=payload),
+            )
+        except CarrierError:
+            raise
+        except Exception as error:
+            text = str(error) if str(error) else "Network request failed."
+            raise CarrierError(0, "network_error", text, "api_error") from error
+        if handshake:
+            self._session_id = _header(headers, "mcp-session-id") or self._session_id
+        if status < 200 or status > 299:
+            raise CarrierError(status, "mcp_error", _error_text(raw), "api_error")
+        if notify and raw.strip() == b"":
+            return None
+        return _decode_rpc(raw, headers)
+
+    def _endpoint(self) -> str:
+        if self._auth != "token":
+            return self._url
+        parts = urlsplit(self._url)
+        query = dict(parse_qsl(parts.query, keep_blank_values=True))
+        query["TOKEN"] = self._token
+        return urlunsplit((parts.scheme, parts.netloc, parts.path, urlencode(query), parts.fragment))
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+            "User-Agent": _USER_AGENT,
+        }
+        if self._auth == "bearer":
+            headers["Authorization"] = f"Bearer {self._token}"
+        if self._session_id:
+            headers["Mcp-Session-Id"] = self._session_id
+        if self._protocol:
+            headers["MCP-Protocol-Version"] = self._protocol
+        return headers
+
+
+def urllib_mcp_transport(timeout: float) -> McpTransport:
+    """Default MCP transport. Uses the stdlib so the package has no dependencies."""
+
+    def send(request: McpRequest) -> tuple[int, Mapping[str, str], bytes]:
+        outbound = urllib.request.Request(request.url, data=request.body, headers=request.headers, method=request.method)
+        try:
+            with urllib.request.urlopen(outbound, timeout=timeout) as response:
+                header_map = {key.lower(): value for key, value in response.headers.items()}
+                return int(response.status), header_map, response.read()
+        except urllib.error.HTTPError as error:
+            header_map = {key.lower(): value for key, value in error.headers.items()}
+            return int(error.code), header_map, error.read()
+        except urllib.error.URLError as error:
+            reason = error.reason
+            message = str(reason) if reason else "Network request failed."
+            raise CarrierError(0, "network_error", message, "api_error") from error
+        except TimeoutError as error:
+            raise CarrierError(0, "network_error", str(error), "api_error") from error
+
+    return send
+
+
+def _decode_rpc(raw: bytes, headers: Mapping[str, str]) -> object:
+    if raw.strip() == b"":
+        return None
+    content_type = _header(headers, "content-type") or ""
+    try:
+        if "text/event-stream" in content_type:
+            return _decode_sse(raw)
+        parsed = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise CarrierError(200, "invalid_response", "MCP returned a body that is not JSON.") from error
+    if not isinstance(parsed, dict):
+        raise CarrierError(200, "invalid_response", "MCP returned a body that is not an object.")
+    return _rpc_payload(parsed)
+
+
+def _decode_sse(raw: bytes) -> object:
+    for block in raw.decode("utf-8").split("\n\n"):
+        for line in block.split("\n"):
+            if not line.startswith("data:"):
+                continue
+            data = line[5:].strip()
+            if data == "" or data == "[DONE]":
+                continue
+            parsed = json.loads(data)
+            if isinstance(parsed, dict) and ("result" in parsed or "error" in parsed):
+                return _rpc_payload(parsed)
+    raise CarrierError(200, "invalid_response", "MCP event stream did not include a result.")
+
+
+def _rpc_payload(message: Mapping[str, object]) -> object:
+    error = message.get("error")
+    if isinstance(error, dict):
+        text = error.get("message")
+        raise CarrierError(
+            200,
+            "mcp_error",
+            text if isinstance(text, str) and text else "MCP request failed.",
+            "api_error",
+        )
+    return message.get("result")
+
+
+def _header(headers: Mapping[str, str], name: str) -> str | None:
+    for key, value in headers.items():
+        if key.lower() == name:
+            return value
+    return None
+
+
+def _error_text(raw: bytes) -> str:
+    text = raw.decode("utf-8", errors="replace").strip()
+    if text == "":
+        return "MCP request failed."
+    return text[:300]

carrier/models.py

@@ -0,0 +1,213 @@
+"""Public objects returned by the connectivity API."""
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from carrier.errors import CarrierError
+
+
+def _invalid(field: str) -> CarrierError:
+    return CarrierError(0, "invalid_response", f"Carrier response field {field} is missing or invalid.")
+
+
+def _mapping(value: object, label: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise CarrierError(0, "invalid_response", f"Carrier response {label} is not an object.")
+    return value
+
+
+def _str(data: dict[str, Any], key: str) -> str:
+    value = data.get(key)
+    if not isinstance(value, str):
+        raise _invalid(key)
+    return value
+
+
+def _int(data: dict[str, Any], key: str) -> int:
+    value = data.get(key)
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise _invalid(key)
+    return value
+
+
+def _bool(data: dict[str, Any], key: str) -> bool:
+    value = data.get(key)
+    if not isinstance(value, bool):
+        raise _invalid(key)
+    return value
+
+
+def _number(data: dict[str, Any], key: str) -> float:
+    value = data.get(key)
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        raise _invalid(key)
+    return float(value)
+
+
+def _string_map(value: object) -> dict[str, str]:
+    if not isinstance(value, dict):
+        raise _invalid("metadata")
+    metadata: dict[str, str] = {}
+    for key, entry in value.items():
+        if not isinstance(key, str) or not isinstance(entry, str):
+            raise _invalid("metadata")
+        metadata[key] = entry
+    return metadata
+
+
+T = TypeVar("T")
+
+
+def parse_list(payload: object, parse_item: Callable[[dict[str, Any]], T]) -> list[T]:
+    """Unwrap `{object: list, data: [...]}`."""
+    data = _mapping(payload, "list")
+    items = data.get("data")
+    if data.get("object") != "list" or not isinstance(items, list):
+        raise CarrierError(0, "invalid_response", "Carrier returned a list that is not an object.")
+    return [parse_item(_mapping(item, "item")) for item in items]
+
+
+class PlanPrice:
+    """Catalogue price in minor units. Present on operator products."""
+
+    def __init__(self, amount: int, currency: str) -> None:
+        self.amount = amount
+        self.currency = currency
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "PlanPrice":
+        return cls(amount=_int(data, "amount"), currency=_str(data, "currency"))
+
+
+class ConnectivityPlan:
+    """A test plan or an operator-defined product."""
+
+    def __init__(
+        self,
+        id: str,
+        object: str,
+        name: str,
+        data_mb: int,
+        validity_days: int,
+        countries: list[str],
+        livemode: bool,
+        price: PlanPrice | None,
+    ) -> None:
+        self.id = id
+        self.object = object
+        self.name = name
+        self.data_mb = data_mb
+        self.validity_days = validity_days
+        self.countries = countries
+        self.livemode = livemode
+        self.price = price
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ConnectivityPlan":
+        raw_countries = data.get("countries")
+        if not isinstance(raw_countries, list) or not all(isinstance(item, str) for item in raw_countries):
+            raise _invalid("countries")
+        raw_price = data.get("price")
+        price = None if raw_price is None else PlanPrice.from_dict(_mapping(raw_price, "price"))
+        return cls(
+            id=_str(data, "id"),
+            object=_str(data, "object"),
+            name=_str(data, "name"),
+            data_mb=_int(data, "data_mb"),
+            validity_days=_int(data, "validity_days"),
+            countries=list(raw_countries),
+            livemode=_bool(data, "livemode"),
+            price=price,
+        )
+
+
+class ConnectivityEsim:
+    """The profile attached to a succeeded intent."""
+
+    def __init__(
+        self,
+        iccid: str,
+        activation_code: str | None,
+        qr_code: str | None,
+        smdp_address: str | None,
+        matching_id: str | None,
+    ) -> None:
+        self.iccid = iccid
+        self.activation_code = activation_code
+        self.qr_code = qr_code
+        self.smdp_address = smdp_address
+        self.matching_id = matching_id
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ConnectivityEsim":
+        return cls(
+            iccid=_str(data, "iccid"),
+            activation_code=_optional_str(data, "activation_code"),
+            qr_code=_optional_str(data, "qr_code"),
+            smdp_address=_optional_str(data, "smdp_address"),
+            matching_id=_optional_str(data, "matching_id"),
+        )
+
+
+class IntentError:
+    """Failure stored on an intent. Distinct from CarrierError, which is raised."""
+
+    def __init__(self, code: str, message: str) -> None:
+        self.code = code
+        self.message = message
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "IntentError":
+        return cls(code=_str(data, "code"), message=_str(data, "message"))
+
+
+class ConnectivityIntent:
+    """One request to issue an eSIM."""
+
+    def __init__(
+        self,
+        id: str,
+        object: str,
+        status: str,
+        livemode: bool,
+        plan: ConnectivityPlan | None,
+        esim: ConnectivityEsim | None,
+        metadata: dict[str, str],
+        error: IntentError | None,
+        created: int,
+    ) -> None:
+        self.id = id
+        self.object = object
+        self.status = status
+        self.livemode = livemode
+        self.plan = plan
+        self.esim = esim
+        self.metadata = metadata
+        self.error = error
+        self.created = created
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ConnectivityIntent":
+        raw_plan = data.get("plan")
+        raw_esim = data.get("esim")
+        raw_error = data.get("error")
+        return cls(
+            id=_str(data, "id"),
+            object=_str(data, "object"),
+            status=_str(data, "status"),
+            livemode=_bool(data, "livemode"),
+            plan=None if raw_plan is None else ConnectivityPlan.from_dict(_mapping(raw_plan, "plan")),
+            esim=None if raw_esim is None else ConnectivityEsim.from_dict(_mapping(raw_esim, "esim")),
+            metadata=_string_map(data.get("metadata", {})),
+            error=None if raw_error is None else IntentError.from_dict(_mapping(raw_error, "error")),
+            created=_int(data, "created"),
+        )
+
+
+def _optional_str(data: dict[str, Any], key: str) -> str | None:
+    if key not in data or data[key] is None:
+        return None
+    value = data[key]
+    if not isinstance(value, str):
+        raise _invalid(key)
+    return value