carrier-python 0.1.15__py3-none-any.whl

carrier/resources.py

@@ -0,0 +1,201 @@
+"""Resource clients. Each method maps to one connectivity route."""
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from carrier.errors import CarrierError, outcome_unknown
+from carrier.http import Http
+from carrier.idempotency import require_id
+from carrier.models import ConnectivityIntent, ConnectivityPlan, parse_list
+from carrier.records import (
+    ConnectivityEvent,
+    ConnectivityUsageRecord,
+    DeletedWebhookEndpoint,
+    WebhookEndpoint,
+    WebhookEndpointCreated,
+)
+
+
+class Intents:
+    """Issue, read, and confirm connectivity intents."""
+
+    def __init__(self, http: Http) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        plan: str | None = None,
+        metadata: Mapping[str, str] | None = None,
+        idempotency_key: str,
+    ) -> ConnectivityIntent:
+        """POST /v1/connectivity/intents. The same key and body return the original intent."""
+        body: dict[str, Any] = {}
+        if plan is not None:
+            body["plan"] = plan
+        if metadata is not None:
+            body["metadata"] = dict(metadata)
+        payload = self._http.request(
+            "POST",
+            "/v1/connectivity/intents",
+            body=body,
+            idempotency_key=idempotency_key,
+        )
+        try:
+            return ConnectivityIntent.from_dict(_as_object(payload))
+        except CarrierError as error:
+            raise outcome_unknown(idempotency_key) from error
+
+    def retrieve(self, intent_id: str) -> ConnectivityIntent:
+        """GET /v1/connectivity/intents/:id."""
+        path = f"/v1/connectivity/intents/{require_id(intent_id, 'intent')}"
+        return ConnectivityIntent.from_dict(_as_object(self._http.request("GET", path)))
+
+    def list(self, *, limit: int | None = None) -> list[ConnectivityIntent]:
+        """GET /v1/connectivity/intents. Newest first. Omit limit for the default page of 20."""
+        query: dict[str, str] = {}
+        if limit is not None:
+            if isinstance(limit, bool) or not isinstance(limit, int) or limit < 1 or limit > 100:
+                raise CarrierError(400, "invalid_limit", "limit must be an integer from 1 to 100.")
+            query["limit"] = str(limit)
+        payload = self._http.request("GET", "/v1/connectivity/intents", query=query or None)
+        return parse_list(payload, ConnectivityIntent.from_dict)
+
+    def confirm(self, intent_id: str, *, plan: str) -> ConnectivityIntent:
+        """POST /v1/connectivity/intents/:id/confirm."""
+        path = f"/v1/connectivity/intents/{require_id(intent_id, 'intent')}/confirm"
+        payload = self._http.request("POST", path, body={"plan": plan})
+        return ConnectivityIntent.from_dict(_as_object(payload))
+
+
+class Products:
+    """Operator-defined plans. Creating one does not debit a wallet."""
+
+    def __init__(self, http: Http) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        name: str,
+        data_mb: int,
+        validity_days: int,
+        countries: Sequence[str],
+        price_cents: int,
+        currency: str,
+        package_template_id: int,
+        account_id: int | None = None,
+        idempotency_key: str,
+    ) -> ConnectivityPlan:
+        """POST /v1/connectivity/products. price_cents is catalogue data."""
+        body: dict[str, Any] = {
+            "name": name,
+            "data_mb": data_mb,
+            "validity_days": validity_days,
+            "countries": list(countries),
+            "price_cents": price_cents,
+            "currency": currency,
+            "package_template_id": package_template_id,
+        }
+        if account_id is not None:
+            body["account_id"] = account_id
+        payload = self._http.request(
+            "POST",
+            "/v1/connectivity/products",
+            body=body,
+            idempotency_key=idempotency_key,
+        )
+        return ConnectivityPlan.from_dict(_as_object(payload))
+
+    def retrieve(self, product_id: str) -> ConnectivityPlan:
+        """GET /v1/connectivity/products/:id."""
+        path = f"/v1/connectivity/products/{require_id(product_id, 'product')}"
+        return ConnectivityPlan.from_dict(_as_object(self._http.request("GET", path)))
+
+    def list(self) -> list[ConnectivityPlan]:
+        """GET /v1/connectivity/products. Newest first, up to 100."""
+        return parse_list(self._http.request("GET", "/v1/connectivity/products"), ConnectivityPlan.from_dict)
+
+
+class Plans:
+    """Test plans and live plans this account can issue."""
+
+    def __init__(self, http: Http) -> None:
+        self._http = http
+
+    def list(self) -> list[ConnectivityPlan]:
+        """GET /v1/connectivity/plans."""
+        return parse_list(self._http.request("GET", "/v1/connectivity/plans"), ConnectivityPlan.from_dict)
+
+
+class WebhookEndpoints:
+    """HTTPS endpoints that receive Carrier-Signature deliveries."""
+
+    def __init__(self, http: Http) -> None:
+        self._http = http
+
+    def create(self, url: str) -> WebhookEndpointCreated:
+        """POST /v1/connectivity/webhook_endpoints. The secret is on this response only."""
+        payload = self._http.request("POST", "/v1/connectivity/webhook_endpoints", body={"url": url})
+        return WebhookEndpointCreated.from_dict(_as_object(payload))
+
+    def list(self) -> list[WebhookEndpoint]:
+        """GET /v1/connectivity/webhook_endpoints. Secrets are omitted."""
+        payload = self._http.request("GET", "/v1/connectivity/webhook_endpoints")
+        return parse_list(payload, WebhookEndpoint.from_dict)
+
+    def delete(self, endpoint_id: str) -> DeletedWebhookEndpoint:
+        """DELETE /v1/connectivity/webhook_endpoints/:id."""
+        path = f"/v1/connectivity/webhook_endpoints/{require_id(endpoint_id, 'webhook endpoint')}"
+        return DeletedWebhookEndpoint.from_dict(_as_object(self._http.request("DELETE", path)))
+
+
+class Events:
+    """Connectivity events for this account."""
+
+    def __init__(self, http: Http) -> None:
+        self._http = http
+
+    def list(self, *, intent: str | None = None) -> list[ConnectivityEvent]:
+        """GET /v1/connectivity/events. Newest first, at most 20."""
+        query = None if intent is None else {"intent": require_id(intent, "intent")}
+        return parse_list(self._http.request("GET", "/v1/connectivity/events", query=query), ConnectivityEvent.from_dict)
+
+    def retrieve(self, event_id: str) -> ConnectivityEvent:
+        """GET /v1/connectivity/events/:id."""
+        path = f"/v1/connectivity/events/{require_id(event_id, 'event')}"
+        return ConnectivityEvent.from_dict(_as_object(self._http.request("GET", path)))
+
+    def retry(self, event_id: str) -> ConnectivityEvent:
+        """POST /v1/connectivity/events/:id/retry."""
+        path = f"/v1/connectivity/events/{require_id(event_id, 'event')}/retry"
+        return ConnectivityEvent.from_dict(_as_object(self._http.request("POST", path)))
+
+
+class UsageRecords:
+    """Usage lines on a test intent. Live usage is metered by the network."""
+
+    def __init__(self, http: Http) -> None:
+        self._http = http
+
+    def create(self, *, intent: str, quantity_mb: float, idempotency_key: str) -> ConnectivityUsageRecord:
+        """POST /v1/connectivity/usage_records."""
+        payload = self._http.request(
+            "POST",
+            "/v1/connectivity/usage_records",
+            body={"intent": intent, "quantity_mb": quantity_mb},
+            idempotency_key=idempotency_key,
+        )
+        return ConnectivityUsageRecord.from_dict(_as_object(payload))
+
+    def list(self, intent: str) -> list[ConnectivityUsageRecord]:
+        """GET /v1/connectivity/usage_records?intent=."""
+        query = {"intent": require_id(intent, "intent")}
+        payload = self._http.request("GET", "/v1/connectivity/usage_records", query=query)
+        return parse_list(payload, ConnectivityUsageRecord.from_dict)
+
+
+def _as_object(payload: object) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        raise CarrierError(0, "invalid_response", "Carrier response is not an object.")
+    return payload

carrier/signature.py

@@ -0,0 +1,57 @@
+"""Webhook signature check. Same header the API sends as Carrier-Signature."""
+
+import hashlib
+import hmac
+import time
+from typing import Final
+
+DEFAULT_TOLERANCE_SECONDS: Final = 300
+
+
+def verify_webhook_signature(
+    body: str,
+    signature: str,
+    secret: str,
+    *,
+    tolerance_seconds: int = DEFAULT_TOLERANCE_SECONDS,
+    now_seconds: int | None = None,
+) -> bool:
+    """Return whether `signature` signs `body` under `secret`.
+
+    The header is `t=<unix>,v1=<hex>` over `{timestamp}.{body}`. A rotation
+    can put more than one `v1` value in the header. Any match passes.
+    `tolerance_seconds` of 0 turns the replay window off.
+    """
+    timestamps: list[str] = []
+    candidates: list[str] = []
+    for part in signature.split(","):
+        if "=" not in part:
+            continue
+        key, value = part.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if value == "":
+            continue
+        if key == "t":
+            timestamps.append(value)
+        elif key == "v1":
+            candidates.append(value)
+    if not timestamps or not candidates:
+        return False
+    timestamp = timestamps[0]
+    if tolerance_seconds < 0:
+        return False
+    if tolerance_seconds > 0:
+        try:
+            signed_at = int(timestamp)
+        except ValueError:
+            return False
+        clock = int(time.time()) if now_seconds is None else now_seconds
+        if abs(clock - signed_at) > tolerance_seconds:
+            return False
+    digest = hmac.new(
+        secret.encode("utf-8"),
+        f"{timestamp}.{body}".encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+    return any(hmac.compare_digest(digest, candidate) for candidate in candidates)

carrier/version.py

@@ -0,0 +1,3 @@
+"""Package version. Kept beside the HTTP client so the user agent stays in sync."""
+
+__version__ = "0.1.15"

carrier_python-0.1.15.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: carrier-python
+Version: 0.1.15
+Summary: Python client for the Carrier API, MCP server, and CLI.
+Author: Lifecycle Innovations Limited
+License: MIT
+Project-URL: Homepage, https://carrier.llc/sdks/
+Project-URL: Documentation, https://carrier.llc/docs/sdks/
+Keywords: carrier,esim,connectivity
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# carrier-python
+
+Python client for the Carrier API, the hosted MCP server, and the `carrier` CLI. `intents.create` posts to `/v1/connectivity/intents`. `call` uses an OpenAPI operation id. `Mcp` speaks Streamable HTTP. `Cli` runs the binary with an argument list. `rest_tools`, `mcp_tools`, and `cli_tools` return plain dicts for LangGraph or an OpenAI-style tool loop. The price on a product is catalogue data. Neither an intent nor a product debits a wallet.
+
+```bash
+pip install carrier-python
+```
+
+```python
+import os
+from carrier import Carrier
+
+carrier = Carrier(os.environ["CARRIER_API_KEY"])
+intent = carrier.intents.create(
+    plan="test_global_1gb",
+    metadata={"order": "123"},
+    idempotency_key="order_123",
+)
+```
+
+`test_global_1gb` is a practice plan. The call succeeds, `livemode` is false, and the network is not used. The same idempotency key and body return the original intent.
+
+A waiting intent takes a plan later:
+
+```python
+carrier.intents.confirm(intent.id, plan="test_global_1gb")
+```
+
+Webhook deliveries use `Carrier-Signature: t=<unix>,v1=<hex>` over `{timestamp}.{body}`. The endpoint secret (`whsec_…`) is returned once, on create.
+
+```python
+from carrier import verify_webhook_signature
+
+ok = verify_webhook_signature(raw_body, header, secret)
+```
+
+`CarrierError.status`, `.code`, and `.type` match the API error envelope. A blank API key raises before a request is sent.
+
+## Issuance safety (0.1.11)
+
+For `intents.create` and `call("issue_esim_from_inventory", ...)`, supply a stable business key. Issuance keys must match `[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}`. They are never trimmed, coerced, or replaced. Invalid keys fail before transport; nonissuance operations retain their existing key rules.
+
+Transport loss, response-read failure, or response-decode failure after an issuance call raises `CarrierError` with `code == "outcome_unknown"`, the unchanged `.idempotency_key`, and `.retryable is False`. The SDK does not retry dispatch or mint a new key. Reconcile the original operation using that key; do not automatically reissue. A complete valid API error keeps its server status, code, message, and type. This is not a provider exactly-once guarantee. Custom transports must not retry issuance internally.
+
+Every public operation:
+
+```python
+accounts = carrier.call("list_reseller_accounts")
+issued = carrier.call(
+    "create_connectivity_intent",
+    body={"plan": "test_global_1gb"},
+    idempotency_key="order_123",
+)
+```
+
+`security` on each catalog entry is `bearer`, `public`, `internal`, or `storefront`. A customer API key is `bearer`. The two internal routes do not accept that key.
+
+```python
+from carrier import Mcp, Cli, rest_tools
+
+session = Mcp(os.environ["ESIMVAULT_API_TOKEN"])  # ?TOKEN= on https://mcp.carrier.llc/mcp
+tools = session.list_tools()
+session.call_tool("list_subscribers", {"limit": 5})
+
+cli = Cli()
+cli.run(["subscribers", "list", "--limit", "5"])
+agent_tools = rest_tools(carrier)
+```
+
+`Mcp(..., auth="bearer")` sends an OAuth access token or a Clerk organization API key. `Cli` never invokes a shell. Pass `strict=False` only when you intentionally run a command that is not in the catalog.
+
+Python 3.11 or newer. The package uses the standard library only. `pip install carrier-python` installs it from PyPI.

carrier_python-0.1.15.dist-info/RECORD

@@ -0,0 +1,23 @@
+carrier/__init__.py,sha256=W9FU9skCg7U4MxhH6UKO_Sxw0R-x_i9eng4Hgkq90js,1291
+carrier/adapters.py,sha256=Akxd630boQdyh4fUctI6xpxqiWze7wdrhHgWxTkD5AA,4374
+carrier/catalog.py,sha256=F_7tTFu8vXJ4NuxUgwfQErRGNQCC9AVWqWxi7drK158,2871
+carrier/cli.py,sha256=iFhB-j2ckurNuEK_e2khpjspYCmAjlb0RUNJJrddufs,2680
+carrier/client.py,sha256=tJEsBoyA7oailopi84tndEy7X7nr3tbrZZ3p46tG5Yw,2074
+carrier/errors.py,sha256=X61cqPBsgBF3-bq41DoNzLepabvhVDarpqF0Y7fyIDE,1923
+carrier/http.py,sha256=h8YAZkG5Ouh4893Sww7CmlcnnsYjNjZJmwE96-ZsCjA,5161
+carrier/idempotency.py,sha256=IzapZp2SmcIYJU9G_vfzsgu0n_h55O4Fcc3A45kaNwE,1698
+carrier/mcp.py,sha256=EtIJ71rXf9bfeOGz93hCVtODnkGq57eY0XdXyiffu2k,9475
+carrier/models.py,sha256=0_kKeAnewlpzwcn8K-KVCqxMQhs6oh70W9FlhNKmy1s,6638
+carrier/operation_ids.py,sha256=GSucnszcNxtbkpUIcRth1oHZNnEOed2RMp3eGl6ldUY,5835
+carrier/operations.py,sha256=4Zl3LIV7XtpP1Or-_IyUUjNs-mE59Aftnu4rrTz2OLw,8279
+carrier/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+carrier/records.py,sha256=4e4m0AiePdw5axgJiSfHBt2ftf4Szx5sOl5_rkN15Rw,3442
+carrier/resources.py,sha256=mj97lySHMJi12KQVhXlfZ-grAKmf7XkhgBNi_nGegZg,8057
+carrier/signature.py,sha256=MZRp9Vj9heode_plZvXTGhN6P1wos0DEyOvS29l2XtA,1724
+carrier/version.py,sha256=Mw8J1E9E8IbEMhFW_X8i2lF4PHFFzmUP-0N3u4L-1ZQ,108
+carrier/data/cli.json,sha256=omgHkZLsfMwxT8SQg29vJjl43lswtZE0sGUmpR9L_uM,87647
+carrier/data/operations.json,sha256=MXjZcvXUO8W35ir77R_BjidtmWGUex8QmkBfcrRShUk,73707
+carrier_python-0.1.15.dist-info/METADATA,sha256=PJvDHp0kMUeOvf8AR-Kvmtxslo7dqJUjhNg5FyvokR0,3817
+carrier_python-0.1.15.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+carrier_python-0.1.15.dist-info/top_level.txt,sha256=yXdhRVSdu7ru_mUxsikeswMIz0nQubrqn1MQa6EW2fQ,8
+carrier_python-0.1.15.dist-info/RECORD,,

carrier_python-0.1.15.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

carrier_python-0.1.15.dist-info/top_level.txt

@@ -0,0 +1 @@
+carrier