carrier-python 0.1.15__py3-none-any.whl

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/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/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/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/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,
+        )