carrier-python 0.1.15__py3-none-any.whl

carrier/operation_ids.py

@@ -0,0 +1,188 @@
+"""Operation ids from the public OpenAPI document.
+
+Generated by sdks/generate.py. Do not edit by hand.
+"""
+
+from typing import Literal
+
+OperationId = Literal[
+    "list_reseller_accounts",
+    "get_reseller_info",
+    "esim_status_per_account",
+    "list_sponsors",
+    "list_steering_lists",
+    "get_subscriber",
+    "list_subscribers",
+    "create_subscriber",
+    "get_sim_provider_status",
+    "change_sim_status",
+    "get_subscriber_location",
+    "hlr_get_bitrate",
+    "hlr_set_bitrate",
+    "list_subscriber_packages",
+    "assign_package",
+    "clean_all_packages",
+    "list_package_templates",
+    "create_package_template",
+    "list_location_zones",
+    "create_location_zone",
+    "list_detailed_location_zones",
+    "list_destination_prefixes",
+    "subscriber_usage",
+    "subscriber_network_events",
+    "subscriber_active_period",
+    "get_tariff",
+    "list_network_profiles",
+    "modify_subscriber_balance",
+    "modify_subscriber_status",
+    "modify_subscriber_contact_info",
+    "set_subscriber_traffic_restrictions",
+    "modify_subscriber_steering_list",
+    "move_subscriber_range_to_account",
+    "assign_recurring_package",
+    "modify_package_limits",
+    "modify_package_expiry",
+    "modify_package_status",
+    "stop_resume_recurring_package",
+    "modify_account_balance",
+    "delete_subscriber_package",
+    "modify_template_core",
+    "modify_template_recurring",
+    "modify_template_throttling",
+    "send_sms",
+    "fleet_health",
+    "churn_risk",
+    "audit_network_coverage",
+    "diagnose_subscriber",
+    "detect_usage_anomalies",
+    "optimize_package",
+    "marketing_intelligence",
+    "high_cost_subscribers",
+    "high_cost_subscribers_method_guard",
+    "detect_country_entry",
+    "list_intelligence_schedules",
+    "create_intelligence_schedule",
+    "delete_intelligence_schedule",
+    "run_intelligence_schedule",
+    "get_intelligence_schedule_report",
+    "get_intelligence_share",
+    "operator_billing_connect_begin",
+    "operator_billing_connect_oauth_begin",
+    "operator_billing_connect_oauth_complete",
+    "operator_billing_connect_status",
+    "operator_billing_connect_dashboard_link",
+    "operator_billing_list_payouts",
+    "operator_billing_create_manual_payout",
+    "operator_billing_get_payout_schedule",
+    "operator_billing_update_payout_schedule",
+    "operator_billing_list_fees",
+    "operator_billing_list_charges",
+    "operator_billing_get_balance",
+    "operator_billing_list_refunds",
+    "operator_billing_create_refund",
+    "operator_billing_list_disputes",
+    "operator_billing_submit_dispute_evidence",
+    "operator_billing_list_fraud_reviews",
+    "operator_billing_approve_fraud_review",
+    "operator_billing_decline_fraud_review",
+    "operator_billing_list_value_lists",
+    "operator_billing_add_value_list_item",
+    "affiliates_me_get",
+    "affiliates_me_create",
+    "affiliates_me_commissions_list",
+    "affiliates_link",
+    "operator_identity_status",
+    "operator_identity_create_session",
+    "operator_identity_update_session",
+    "operator_list_promotions",
+    "operator_create_promotion",
+    "signup_start",
+    "signup_verify",
+    "create_api_key",
+    "get_onboarding_state",
+    "onboarding_save_org",
+    "onboarding_connect_ocs_token",
+    "onboarding_start_managed_account",
+    "onboarding_save_plan",
+    "onboarding_skip_plan",
+    "onboarding_test_esim",
+    "onboarding_complete",
+    "operator_billing_stripe_webhook",
+    "receive_bridge4ip_webhook",
+    "affect_subscriber_phone_number",
+    "modify_subscriber_mobile_plan",
+    "modify_subscriber_voip_plan",
+    "push_steering_to_subscriber",
+    "modify_subscriber_package_active_period",
+    "get_subscriber_location_by_cell_id",
+    "reset_subscriber_gz_counter",
+    "list_destination_lists",
+    "list_subscriber_voip_tariff",
+    "list_voip_tariff_rule",
+    "change_network_profile_of_location_zone",
+    "get_network_default",
+    "set_network_default",
+    "plan_network_default",
+    "carrier_webhook_config",
+    "ai_chat",
+    "ai_insights",
+    "ai_quota",
+    "list_invoice_periods",
+    "get_billing_config",
+    "update_billing_config",
+    "stripe_connect_begin",
+    "stripe_connect_status",
+    "list_invoices",
+    "create_invoice",
+    "get_invoice",
+    "update_invoice",
+    "void_invoice",
+    "get_invoice_document",
+    "list_connectivity_plans",
+    "list_connectivity_products",
+    "create_connectivity_product",
+    "get_connectivity_product",
+    "list_connectivity_intents",
+    "create_connectivity_intent",
+    "get_connectivity_intent",
+    "confirm_connectivity_intent",
+    "create_connectivity_webhook_endpoint",
+    "list_connectivity_webhook_endpoints",
+    "delete_connectivity_webhook_endpoint",
+    "list_connectivity_events",
+    "get_connectivity_event",
+    "create_connectivity_usage_record",
+    "list_connectivity_usage_records",
+    "retry_connectivity_event",
+    "issue_esim_from_inventory",
+    "rollback_esim_issuance",
+    "subscriber_country_history",
+    "get_subscriber_notes",
+    "add_subscriber_note",
+    "put_subscriber_notes",
+    "observe_connectivity_event",
+    "ingest_connectivity_usage",
+    "ingest_cdr_events",
+    "aggregate_cdr",
+    "list_storefront_templates",
+    "list_storefront_buyer_orders",
+    "get_storefront_order_usage",
+    "get_storefront_order_top_up_options",
+    "cancel_storefront_top_up_checkout",
+    "cancel_storefront_order",
+    "get_storefront_order",
+    "rollback_storefront_order",
+    "get_hosted_storefront",
+    "get_hosted_storefront_plan_readiness",
+    "list_storefronts",
+    "create_storefront",
+    "list_storefront_orders",
+    "get_storefront",
+    "update_storefront",
+    "upsert_storefront_plan",
+    "update_storefront_plan",
+    "publish_storefront",
+    "plan_storefront_publish",
+    "unpublish_storefront",
+    "health_check",
+]

carrier/operations.py

@@ -0,0 +1,192 @@
+"""Generic caller for every operation id in the public OpenAPI document."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from urllib.parse import quote
+
+from carrier.catalog import HEADER_FIELDS, Operation, operation
+from carrier.errors import CarrierError
+from carrier.http import Http
+from carrier.idempotency import is_issuance, require_id, require_idempotency_key, require_issuance_key
+
+_PATH_PARAM = re.compile(r"\{([^{}]+)\}")
+_IDEMPOTENCY_HEADERS = {"Idempotency-Key", "X-Idempotency-Key"}
+
+
+def call_operation(
+    http: Http,
+    operation_id: str,
+    *,
+    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 one operation by its OpenAPI operationId."""
+    spec = operation(operation_id)
+    path_values = _named(path, "path")
+    query_values = _named(query, "query")
+    header_values = _named(headers, "header")
+    _reject_unknown("path", path_values, spec["pathParams"])
+    _reject_unknown("query", query_values, spec["queryParams"])
+    _reject_unknown("header", header_values, spec["headerParams"])
+    _require_present("Path", path_values, spec["pathParams"])
+    _apply_idempotency(spec, header_values, idempotency_key)
+    _require_headers(header_values, spec)
+    for name in list(header_values):
+        if name in _IDEMPOTENCY_HEADERS:
+            if is_issuance(spec["method"], spec["path"]):
+                header_values[name] = require_issuance_key(header_values[name])
+            else:
+                header_values[name] = require_idempotency_key(str(header_values[name]))
+    if spec["bodyRequired"] and body is None:
+        raise CarrierError(400, "missing_body", "This operation requires a JSON body.")
+    if body is not None and not spec["body"]:
+        raise CarrierError(400, "invalid_body", "This operation does not take a JSON body.")
+    idempotency = header_values.pop("Idempotency-Key", None)
+    encoded_query = {key: _query_value(value) for key, value in query_values.items()}
+    return http.request(
+        spec["method"],
+        _fill_path(spec["path"], path_values),
+        body=body,
+        query=encoded_query or None,
+        headers={key: str(value) for key, value in header_values.items()} or None,
+        idempotency_key=str(idempotency) if idempotency is not None else None,
+    )
+
+
+def input_schema(spec: Operation) -> dict[str, object]:
+    """JSON schema for the arguments accepted by one operation."""
+    properties: dict[str, object] = {}
+    required: list[str] = []
+    for param in spec["pathParams"]:
+        properties[param["name"]] = {"type": "string", "description": f"Path {param['name']}"}
+        if param["required"]:
+            required.append(param["name"])
+    for param in spec["queryParams"]:
+        properties[param["name"]] = {"type": "string", "description": f"Query {param['name']}"}
+        if param["required"]:
+            required.append(param["name"])
+    for param in spec["headerParams"]:
+        field = HEADER_FIELDS.get(param["name"], param["name"])
+        schema: dict[str, object] = {"type": "string", "description": param["name"]}
+        if is_issuance(spec["method"], spec["path"]) and field == "idempotency_key":
+            schema.update({"minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$"})
+        properties[field] = schema
+        if param["required"]:
+            required.append(field)
+    if spec["body"]:
+        properties["body"] = {"type": "object", "additionalProperties": True, "description": "JSON request body"}
+        if spec["bodyRequired"]:
+            required.append("body")
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": required,
+        "additionalProperties": False,
+    }
+
+
+def arguments_to_call(spec: Operation, arguments: Mapping[str, object]) -> dict[str, object]:
+    """Split a flat tool argument object into call_operation keyword arguments."""
+    path: dict[str, object] = {}
+    query: dict[str, object] = {}
+    headers: dict[str, object] = {}
+    body = arguments.get("body") if "body" in arguments else None
+    known = {param["name"] for param in spec["pathParams"]}
+    known.update(param["name"] for param in spec["queryParams"])
+    header_names = {HEADER_FIELDS.get(param["name"], param["name"]): param["name"] for param in spec["headerParams"]}
+    known.update(header_names)
+    if spec["body"]:
+        known.add("body")
+    unknown = [key for key in arguments if key not in known]
+    if unknown:
+        raise CarrierError(400, "unknown_parameter", f"Unknown argument {unknown[0]}.")
+    for param in spec["pathParams"]:
+        if param["name"] in arguments:
+            path[param["name"]] = arguments[param["name"]]
+    for param in spec["queryParams"]:
+        if param["name"] in arguments:
+            query[param["name"]] = arguments[param["name"]]
+    for field, header in header_names.items():
+        if field in arguments and field != "idempotency_key":
+            headers[header] = arguments[field]
+    call: dict[str, object] = {"path": path, "query": query, "headers": headers}
+    if "body" in arguments:
+        call["body"] = body
+    if "idempotency_key" in arguments:
+        call["idempotency_key"] = arguments["idempotency_key"]
+    return call
+
+
+def _named(values: Mapping[str, object] | None, label: str) -> dict[str, object]:
+    if values is None:
+        return {}
+    named: dict[str, object] = {}
+    for key, value in values.items():
+        if not isinstance(key, str) or key.strip() == "":
+            raise CarrierError(400, "invalid_parameter", f"{label} parameter names must be strings.")
+        named[key] = value
+    return named
+
+
+def _reject_unknown(label: str, values: Mapping[str, object], params: list[dict[str, object]]) -> None:
+    allowed = {str(param["name"]) for param in params}
+    for name in values:
+        if name not in allowed:
+            raise CarrierError(400, "unknown_parameter", f"Unknown {label} parameter {name}.")
+
+
+def _require_present(label: str, values: Mapping[str, object], params: list[dict[str, object]]) -> None:
+    for param in params:
+        if param["required"] and param["name"] not in values:
+            raise CarrierError(400, "missing_parameter", f"{label} parameter {param['name']} is required.")
+
+
+def _apply_idempotency(spec: Operation, headers: dict[str, object], idempotency_key: str | None) -> None:
+    if idempotency_key is None:
+        return
+    names = {param["name"] for param in spec["headerParams"]}
+    if "Idempotency-Key" in names:
+        headers["Idempotency-Key"] = idempotency_key
+        return
+    if "X-Idempotency-Key" in names:
+        headers["X-Idempotency-Key"] = idempotency_key
+        return
+    raise CarrierError(400, "unknown_parameter", "This operation does not take an idempotency key.")
+
+
+def _require_headers(values: Mapping[str, object], spec: Operation) -> None:
+    for param in spec["headerParams"]:
+        if not param["required"] or param["name"] in values:
+            continue
+        if param["name"] == "X-Idempotency-Key" and "Idempotency-Key" in values:
+            continue
+        field = HEADER_FIELDS.get(param["name"], param["name"])
+        raise CarrierError(400, "missing_parameter", f"{field} is required.")
+
+
+def _fill_path(template: str, values: Mapping[str, object]) -> str:
+    def replace(match: re.Match[str]) -> str:
+        name = match.group(1)
+        if name not in values:
+            raise CarrierError(400, "missing_parameter", f"Path parameter {name} is required.")
+        return quote(require_id(str(values[name]), name), safe="")
+
+    filled = _PATH_PARAM.sub(replace, template)
+    if "{" in filled or "}" in filled:
+        raise CarrierError(400, "invalid_path", "Operation path could not be filled.")
+    return filled
+
+
+def _query_value(value: object) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, str):
+        return value
+    if isinstance(value, int):
+        return str(value)
+    raise CarrierError(400, "invalid_parameter", "Query values must be strings, integers, or booleans.")

carrier/records.py

@@ -0,0 +1,117 @@
+"""Webhook, event, and usage objects."""
+
+from typing import Any
+
+from carrier.models import _bool, _int, _invalid, _number, _str
+
+
+class WebhookEndpoint:
+    """A registered HTTPS endpoint. The signing secret is not included."""
+
+    def __init__(self, id: str, object: str, url: str, status: str, created: int) -> None:
+        self.id = id
+        self.object = object
+        self.url = url
+        self.status = status
+        self.created = created
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "WebhookEndpoint":
+        return cls(
+            id=_str(data, "id"),
+            object=_str(data, "object"),
+            url=_str(data, "url"),
+            status=_str(data, "status"),
+            created=_int(data, "created"),
+        )
+
+
+class WebhookEndpointCreated(WebhookEndpoint):
+    """Create response. `secret` is returned once."""
+
+    def __init__(self, id: str, object: str, url: str, status: str, created: int, secret: str) -> None:
+        super().__init__(id, object, url, status, created)
+        self.secret = secret
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "WebhookEndpointCreated":
+        base = WebhookEndpoint.from_dict(data)
+        return cls(base.id, base.object, base.url, base.status, base.created, _str(data, "secret"))
+
+
+class DeletedWebhookEndpoint:
+    """Result of removing a webhook endpoint."""
+
+    def __init__(self, id: str, object: str, deleted: bool) -> None:
+        self.id = id
+        self.object = object
+        self.deleted = deleted
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "DeletedWebhookEndpoint":
+        return cls(id=_str(data, "id"), object=_str(data, "object"), deleted=_bool(data, "deleted"))
+
+
+class ConnectivityEvent:
+    """A connectivity event delivered to webhook endpoints."""
+
+    def __init__(
+        self,
+        id: str,
+        object: str,
+        type: str,
+        livemode: bool,
+        created: int,
+        data: dict[str, Any],
+    ) -> None:
+        self.id = id
+        self.object = object
+        self.type = type
+        self.livemode = livemode
+        self.created = created
+        self.data = data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ConnectivityEvent":
+        payload = data.get("data")
+        if not isinstance(payload, dict):
+            raise _invalid("data")
+        return cls(
+            id=_str(data, "id"),
+            object=_str(data, "object"),
+            type=_str(data, "type"),
+            livemode=_bool(data, "livemode"),
+            created=_int(data, "created"),
+            data=payload,
+        )
+
+
+class ConnectivityUsageRecord:
+    """A usage line recorded against one intent."""
+
+    def __init__(
+        self,
+        id: str,
+        object: str,
+        intent: str,
+        quantity_mb: float,
+        livemode: bool,
+        created: int,
+    ) -> None:
+        self.id = id
+        self.object = object
+        self.intent = intent
+        self.quantity_mb = quantity_mb
+        self.livemode = livemode
+        self.created = created
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ConnectivityUsageRecord":
+        return cls(
+            id=_str(data, "id"),
+            object=_str(data, "object"),
+            intent=_str(data, "intent"),
+            quantity_mb=_number(data, "quantity_mb"),
+            livemode=_bool(data, "livemode"),
+            created=_int(data, "created"),
+        )