carrier-python 0.1.15__tar.gz

carrier_python-0.1.15/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,72 @@
+# 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/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "carrier-python"
+version = "0.1.15"
+description = "Python client for the Carrier API, MCP server, and CLI."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Lifecycle Innovations Limited" }]
+keywords = ["carrier", "esim", "connectivity"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://carrier.llc/sdks/"
+Documentation = "https://carrier.llc/docs/sdks/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+carrier = ["py.typed", "data/*.json"]

carrier_python-0.1.15/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

carrier_python-0.1.15/src/carrier/__init__.py

@@ -0,0 +1,52 @@
+"""Python client for the Carrier API, MCP server, and CLI."""
+
+from carrier.adapters import cli_tools, mcp_tools, rest_tools
+from carrier.catalog import cli_commands, operations
+from carrier.cli import Cli, CliResult
+from carrier.client import Carrier
+from carrier.errors import CarrierError
+from carrier.mcp import DEFAULT_MCP_URL, Mcp
+from carrier.operation_ids import OperationId
+from carrier.models import (
+    ConnectivityEsim,
+    ConnectivityIntent,
+    ConnectivityPlan,
+    IntentError,
+    PlanPrice,
+)
+from carrier.records import (
+    ConnectivityEvent,
+    ConnectivityUsageRecord,
+    DeletedWebhookEndpoint,
+    WebhookEndpoint,
+    WebhookEndpointCreated,
+)
+from carrier.signature import verify_webhook_signature
+from carrier.version import __version__
+
+__all__ = [
+    "DEFAULT_MCP_URL",
+    "Carrier",
+    "CarrierError",
+    "Cli",
+    "CliResult",
+    "Mcp",
+    "OperationId",
+    "ConnectivityEsim",
+    "ConnectivityEvent",
+    "ConnectivityIntent",
+    "ConnectivityPlan",
+    "ConnectivityUsageRecord",
+    "DeletedWebhookEndpoint",
+    "IntentError",
+    "PlanPrice",
+    "WebhookEndpoint",
+    "WebhookEndpointCreated",
+    "__version__",
+    "cli_commands",
+    "cli_tools",
+    "mcp_tools",
+    "operations",
+    "rest_tools",
+    "verify_webhook_signature",
+]

carrier_python-0.1.15/src/carrier/adapters.py

@@ -0,0 +1,121 @@
+"""Dependency-free tool definitions for LangGraph, OpenAI, and the Vercel AI SDK.
+
+Each tool is a plain dict with `name`, `description`, `inputSchema`, and
+`execute`. Pass `inputSchema` to an AI SDK `jsonSchema()` helper, or use the
+dict as a LangGraph / OpenAI function tool. Nothing in this module imports
+those libraries.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TypedDict
+
+from carrier.catalog import Operation, cli_commands, operations
+from carrier.cli import Cli, CliResult
+from carrier.client import Carrier
+from carrier.errors import CarrierError
+from carrier.mcp import Mcp
+from carrier.operations import arguments_to_call, input_schema
+
+
+class Tool(TypedDict):
+    """One callable tool definition."""
+
+    name: str
+    description: str
+    inputSchema: dict[str, object]
+    execute: object
+
+
+def rest_tools(client: Carrier) -> list[Tool]:
+    """One tool per OpenAPI operation. `execute` calls `client.call`."""
+    tools: list[Tool] = []
+    for spec in operations():
+
+        def execute(arguments: Mapping[str, object], spec: Operation = spec) -> object:
+            prepared = arguments_to_call(spec, arguments)
+            return client.call(spec["id"], **_call_kwargs(prepared))
+
+        tools.append(
+            {
+                "name": spec["id"],
+                "description": f"{spec['summary']} ({spec['method']} {spec['path']}, {spec['security']})",
+                "inputSchema": input_schema(spec),
+                "execute": execute,
+            }
+        )
+    return tools
+
+
+def mcp_tools(session: Mcp) -> list[Tool]:
+    """One tool per MCP tool advertised by `session.list_tools()`."""
+    tools: list[Tool] = []
+    for advertised in session.list_tools():
+        if not isinstance(advertised, dict) or not isinstance(advertised.get("name"), str):
+            continue
+        name = advertised["name"]
+        description = advertised.get("description")
+        schema = advertised.get("inputSchema")
+        input_schema_value = schema if isinstance(schema, dict) else {"type": "object", "properties": {}}
+
+        def execute(arguments: Mapping[str, object], tool_name: str = name) -> dict[str, object]:
+            return session.call_tool(tool_name, arguments)
+
+        tools.append(
+            {
+                "name": name,
+                "description": description if isinstance(description, str) and description else name,
+                "inputSchema": input_schema_value,
+                "execute": execute,
+            }
+        )
+    return tools
+
+
+def cli_tools(cli: Cli) -> list[Tool]:
+    """One tool per catalogued CLI command. Extra flags go in `args`."""
+    tools: list[Tool] = []
+    for command in cli_commands():
+        tokens = command["invocation"].split()[1:]
+        option_text = ", ".join(option["flags"] for option in command["options"]) or "no flags"
+        description = f"{command['summary']} Flags: {option_text}."
+
+        def execute(arguments: Mapping[str, object], tokens: list[str] = tokens) -> CliResult:
+            extra = arguments.get("args", [])
+            if extra is None:
+                extra = []
+            if not isinstance(extra, list) or not all(isinstance(item, str) for item in extra):
+                raise CarrierError(400, "invalid_argument", "CLI tool args must be a list of strings.")
+            return cli.run([*tokens, *extra])
+
+        tools.append(
+            {
+                "name": "cli_" + "_".join(tokens),
+                "description": description,
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "args": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "Flags and values after the command name.",
+                        }
+                    },
+                    "additionalProperties": False,
+                },
+                "execute": execute,
+            }
+        )
+    return tools
+
+
+def _call_kwargs(prepared: Mapping[str, object]) -> dict[str, object]:
+    kwargs: dict[str, object] = {}
+    for key in ("path", "query", "headers", "body", "idempotency_key"):
+        if key in prepared:
+            kwargs[key] = prepared[key]
+    return kwargs
+
+
+__all__ = ["Tool", "cli_tools", "mcp_tools", "rest_tools"]

carrier_python-0.1.15/src/carrier/catalog.py

@@ -0,0 +1,108 @@
+"""Operation and CLI catalogs generated from the public contract."""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from importlib.resources import files
+from typing import TypedDict, cast
+
+from carrier.errors import CarrierError
+from carrier.operation_ids import OperationId
+
+HEADER_FIELDS = {
+    "Idempotency-Key": "idempotency_key",
+    "X-Idempotency-Key": "idempotency_key",
+    "X-Confirm-Token": "confirm_token",
+    "stripe-signature": "stripe_signature",
+}
+
+
+class Param(TypedDict):
+    """One path, query, or header parameter."""
+
+    name: str
+    required: bool
+
+
+class Operation(TypedDict):
+    """One OpenAPI operation the generic caller can invoke."""
+
+    id: OperationId
+    method: str
+    path: str
+    tag: str
+    summary: str
+    security: str
+    body: bool
+    bodyRequired: bool
+    pathParams: list[Param]
+    queryParams: list[Param]
+    headerParams: list[Param]
+
+
+class CliOption(TypedDict):
+    """One flag on a carrier CLI command."""
+
+    flags: str
+    description: str
+    required: bool
+
+
+class CliCommand(TypedDict):
+    """One command from the published CLI catalog."""
+
+    invocation: str
+    domain: str
+    summary: str
+    write: bool
+    transport: str
+    tool: str | None
+    restMethod: str | None
+    restPath: str | None
+    options: list[CliOption]
+
+
+@lru_cache(maxsize=1)
+def operations() -> tuple[Operation, ...]:
+    """Every operation in the public OpenAPI document, in spec order."""
+    return tuple(cast(list[Operation], _load("operations.json")))
+
+
+@lru_cache(maxsize=1)
+def cli_commands() -> tuple[CliCommand, ...]:
+    """Every command in the published CLI catalog."""
+    return tuple(cast(list[CliCommand], _load("cli.json")))
+
+
+def operation(operation_id: str) -> Operation:
+    """Return one operation, or raise when the id is not in the catalog."""
+    found = _operation_index().get(operation_id)
+    if found is None:
+        raise CarrierError(400, "unknown_operation", f"Unknown operation {operation_id}.")
+    return found
+
+
+def command_for_args(args: list[str]) -> CliCommand | None:
+    """Match the longest catalog command that is a prefix of args."""
+    best: CliCommand | None = None
+    best_len = -1
+    for command in cli_commands():
+        tokens = command["invocation"].split()[1:]
+        if args[: len(tokens)] == tokens and len(tokens) > best_len:
+            best = command
+            best_len = len(tokens)
+    return best
+
+
+@lru_cache(maxsize=1)
+def _operation_index() -> dict[str, Operation]:
+    return {item["id"]: item for item in operations()}
+
+
+def _load(name: str) -> list[object]:
+    raw = files("carrier").joinpath("data", name).read_text(encoding="utf-8")
+    parsed = json.loads(raw)
+    if not isinstance(parsed, list):
+        raise CarrierError(500, "invalid_catalog", f"{name} is not a list.")
+    return cast(list[object], parsed)

carrier_python-0.1.15/src/carrier/cli.py

@@ -0,0 +1,70 @@
+"""Runner for the carrier CLI. Arguments are passed as a list, never through a shell."""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+from carrier.catalog import CliCommand, cli_commands, command_for_args
+from carrier.errors import CarrierError
+
+
+@dataclass(frozen=True)
+class CliResult:
+    """Stdout and stderr from one carrier invocation."""
+
+    code: int
+    stdout: str
+    stderr: str
+
+
+Runner = Callable[[str, list[str]], CliResult]
+
+
+class Cli:
+    """Run catalogued `carrier` commands."""
+
+    def __init__(self, *, binary: str = "carrier", runner: Runner | None = None) -> None:
+        if binary.strip() == "" or "\x00" in binary:
+            raise CarrierError(400, "invalid_cli", "The carrier binary path is not valid.")
+        self.binary = binary
+        self._runner = runner if runner is not None else _subprocess_runner
+
+    def commands(self) -> tuple[CliCommand, ...]:
+        """Every command in the published catalog."""
+        return cli_commands()
+
+    def describe(self, invocation: str) -> CliCommand:
+        """Return one catalog entry, such as `carrier subscribers list`."""
+        for command in cli_commands():
+            if command["invocation"] == invocation:
+                return command
+        raise CarrierError(400, "unknown_command", f"Unknown command {invocation}.")
+
+    def run(self, args: Sequence[str], *, strict: bool = True) -> CliResult:
+        """Run `carrier` with args. Strict mode rejects commands missing from the catalog."""
+        argv = _validate_args(args)
+        if strict and command_for_args(argv) is None:
+            joined = " ".join(argv) if argv else "(empty)"
+            raise CarrierError(400, "unknown_command", f"Unknown command carrier {joined}.")
+        return self._runner(self.binary, argv)
+
+
+def _validate_args(args: Sequence[str]) -> list[str]:
+    argv: list[str] = []
+    for arg in args:
+        if not isinstance(arg, str) or "\x00" in arg:
+            raise CarrierError(400, "invalid_argument", "CLI arguments must be strings without NUL bytes.")
+        argv.append(arg)
+    return argv
+
+
+def _subprocess_runner(binary: str, args: list[str]) -> CliResult:
+    try:
+        completed = subprocess.run([binary, *args], capture_output=True, text=True, check=False)
+    except FileNotFoundError as error:
+        raise CarrierError(0, "cli_not_found", f"Could not run {binary}.") from error
+    except OSError as error:
+        raise CarrierError(0, "cli_not_found", str(error) or f"Could not run {binary}.") from error
+    return CliResult(completed.returncode, completed.stdout, completed.stderr)

carrier_python-0.1.15/src/carrier/client.py

@@ -0,0 +1,63 @@
+"""Typed client for the Carrier connectivity API."""
+
+from collections.abc import Mapping
+
+from carrier.errors import CarrierError
+from carrier.http import DEFAULT_BASE_URL, Http, Transport, urllib_transport
+from carrier.operation_ids import OperationId
+from carrier.operations import call_operation
+from carrier.resources import Events, Intents, Plans, Products, UsageRecords, WebhookEndpoints
+
+
+class Carrier:
+    """Client for one Carrier API key.
+
+    `intents.create` issues one eSIM. `call` reaches every public OpenAPI
+    operation id. The price on a product is catalogue data. Neither the intent
+    nor the product call debits a wallet.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        transport: Transport | None = None,
+        timeout: float = 30,
+    ) -> None:
+        if api_key.strip() == "":
+            raise CarrierError(400, "invalid_api_key", "A Carrier API key is required.")
+        http = Http(
+            api_key,
+            base_url or DEFAULT_BASE_URL,
+            transport if transport is not None else urllib_transport(timeout),
+            timeout,
+        )
+        self._http = http
+        self.intents = Intents(http)
+        self.products = Products(http)
+        self.plans = Plans(http)
+        self.webhook_endpoints = WebhookEndpoints(http)
+        self.events = Events(http)
+        self.usage_records = UsageRecords(http)
+
+    def call(
+        self,
+        operation_id: OperationId,
+        *,
+        path: Mapping[str, object] | None = None,
+        query: Mapping[str, object] | None = None,
+        headers: Mapping[str, object] | None = None,
+        body: object | None = None,
+        idempotency_key: str | None = None,
+    ) -> object:
+        """Call any operation id from the public OpenAPI document."""
+        return call_operation(
+            self._http,
+            operation_id,
+            path=path,
+            query=query,
+            headers=headers,
+            body=body,
+            idempotency_key=idempotency_key,
+        )