Python

Package name carrier-python on PyPI. Import name carrier. Python 3.11 or newer. The standard library is enough.

pip install carrier-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",
)

waiting = carrier.intents.create(
    metadata={"order": "124"},
    idempotency_key="order_124",
)
issued = carrier.intents.confirm(waiting.id, plan="test_global_1gb")
page = carrier.intents.list(limit=20)

Go

Module github.com/Lifecycle-Innovations-Limited/carrier-go. The package name is carrier. Go 1.22 or newer.

go get github.com/Lifecycle-Innovations-Limited/carrier-go@latest

client, err := carrier.New(os.Getenv("CARRIER_API_KEY"))
intent, err := client.Intents.Create(ctx, carrier.IntentCreateParams{
    Plan:     carrier.StringPtr("test_global_1gb"),
    Metadata: map[string]string{"order": "123"},
}, "order_123")

page, err := client.Intents.List(ctx, 20)
issued, err := client.Intents.Confirm(ctx, intent.ID, "test_global_1gb")

TypeScript

Package @carrierllc/sdk. Install @carrierllc/sdk@0.2.2. That release adds call, Mcp, and Cli. The 0.1.0 tarball only creates connectivity intents and products.

npm install @carrierllc/sdk@0.2.2

import { Carrier, Mcp, Cli, restTools } from "@carrierllc/sdk"

const carrier = new Carrier(process.env.CARRIER_API_KEY ?? "")
const accounts = await carrier.call("list_reseller_accounts")
const session = new Mcp(process.env.ESIMVAULT_API_TOKEN ?? "")
await session.callTool("list_subscribers", { limit: 5 })
const cli = new Cli()
await cli.run(["subscribers", "list", "--limit", "5"])
const tools = restTools(carrier)

Every API operation

call takes an OpenAPI operation id. Path, query, and header names come from the spec. Editors complete the id. A customer API key is bearer auth. Entries marked internal do not accept that key. Storefront and public routes are marked on the catalog entry.

carrier.call(
    "create_connectivity_intent",
    body={"plan": "test_global_1gb"},
    idempotency_key="order_123",
)

MCP

The default client posts JSON-RPC to https://mcp.carrier.llc/mcp?TOKEN=. That token is an eSIMVault reseller token. auth="bearer" sends an OAuth access token or a Clerk organization API key.request calls any MCP method after initialize.

session = Mcp(os.environ["ESIMVAULT_API_TOKEN"])
session.list_tools()
session.call_tool("get_subscriber", {"iccid": "8900"})

CLI

Cli runs the carrier binary from @carrierllc/mcp. Arguments are a list. The runner does not use a shell. Unknown commands fail before a process starts. describe reads the published catalog.

cli = Cli()
cli.run(["subscribers", "list", "--limit", "5"])

Tool definitions

rest_tools, mcp_tools, and cli_tools return plain objects with name, description, inputSchema, and execute. Python can hand them to LangGraph. TypeScript can pass inputSchema through the Vercel AI SDK jsonSchema() helper. Go returns the same shape from RESTTools. None of the clients import those frameworks.

Errors and retries

A failed call raises CarrierError in Python and returns *carrier.Error in Go. code is the API error code, such as unknown_plan. A blank API key or idempotency key fails before the request is sent. Sending the same idempotency key and body again returns the original object, so a caller can retry a create safely.

Webhooks

POST /v1/connectivity/webhook_endpoints returns the signing secret once. Deliveries send Carrier-Signature: t=<unix>,v1=<hex> over {timestamp}.{body}. The default replay window is 300 seconds.

from carrier import verify_webhook_signature

ok = verify_webhook_signature(raw_body, header, secret)

ok := carrier.VerifyWebhookSignature(
    rawBody, header, secret, carrier.DefaultWebhookToleranceSeconds, time.Now(),
)

The matrix, including the TypeScript client, is on /sdks. Source lives in sdks/python and sdks/go.

TypeScript, Python, and Go